Module: PricingPlans

Defined in:
lib/pricing_plans.rb,
lib/pricing_plans/dsl.rb,
lib/pricing_plans/plan.rb,
lib/pricing_plans/engine.rb,
lib/pricing_plans/result.rb,
lib/pricing_plans/version.rb,
lib/pricing_plans/registry.rb,
lib/pricing_plans/callbacks.rb,
lib/pricing_plans/limitable.rb,
lib/pricing_plans/job_guards.rb,
lib/pricing_plans/plan_owner.rb,
lib/pricing_plans/pay_support.rb,
lib/pricing_plans/models/usage.rb,
lib/pricing_plans/view_helpers.rb,
lib/pricing_plans/configuration.rb,
lib/pricing_plans/grace_manager.rb,
lib/pricing_plans/limit_checker.rb,
lib/pricing_plans/plan_resolver.rb,
lib/pricing_plans/status_context.rb,
lib/pricing_plans/plan_resolution.rb,
lib/pricing_plans/overage_reporter.rb,
lib/pricing_plans/price_components.rb,
lib/pricing_plans/controller_guards.rb,
lib/pricing_plans/models/assignment.rb,
lib/pricing_plans/period_calculator.rb,
lib/pricing_plans/controller_rescues.rb,
lib/pricing_plans/integer_refinements.rb,
lib/pricing_plans/exceeded_state_utils.rb,
lib/pricing_plans/models/enforcement_state.rb,
lib/pricing_plans/association_limit_registry.rb,
lib/generators/pricing_plans/install/install_generator.rb,
sig/pricing_plans.rbs

Defined Under Namespace

Modules: Callbacks, ControllerGuards, ControllerRescues, DSL, ExceededStateUtils, Generators, IntegerRefinements, JobGuards, Limitable, PaySupport, PlanOwner, ViewHelpers Classes: Assignment, AssociationLimitRegistry, Configuration, ConfigurationError, EnforcementState, Engine, Error, FeatureDenied, GraceManager, InvalidOperation, LimitChecker, LimitableRegistry, OverageReporter, PeriodCalculator, Plan, PlanNotFoundError, PlanResolution, PlanResolver, PriceComponents, Registry, Result, StatusContext, StatusItem, Usage

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"0.4.1"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ Object 



55
56
57
 
# File 'lib/pricing_plans.rb', line 55

def configuration
  @configuration ||= Configuration.new
end

Class Method Details

.alert_for(plan_owner, limit_key) ⇒ Object

Pure-data alert view model for a single limit key. No HTML. Returns keys: :visible? (boolean), :severity, :title, :message, :overage, :cta_text, :cta_url



619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
 
# File 'lib/pricing_plans.rb', line 619

def alert_for(plan_owner, limit_key)
  sev = severity_for(plan_owner, limit_key)
  return { visible?: false, severity: :ok } if sev == :ok

  msg = message_for(plan_owner, limit_key)
  over = overage_for(plan_owner, limit_key)
  cta  = cta_for_upgrade(plan_owner)
  titles = {
    warning: "Approaching Limit",
    at_limit: "You've reached your #{limit_key.to_s.humanize.downcase} limit",
    grace:   "Limit for #{limit_key.to_s.humanize.downcase} exceeded (in grace period)",
    blocked: "Cannot create more #{limit_key.to_s.humanize.downcase}"
  }
  {
    visible?: true,
    severity: sev,
    title: titles[sev] || sev.to_s.humanize,
    message: msg,
    overage: over,
    cta_text: cta[:text],
    cta_url: cta[:url]
  }
end

.approaching_limit?(plan_owner, limit_key, at: nil) ⇒ Boolean

Boolean: approaching a limit. If at: given, uses that numeric threshold (0..1); otherwise uses the highest configured warn_at threshold for the limit.

Returns:

  • (Boolean) 


581
582
583
584
585
586
587
588
589
590
591
592
593
 
# File 'lib/pricing_plans.rb', line 581

def approaching_limit?(plan_owner, limit_key, at: nil)
  st = limit_status(limit_key, plan_owner: plan_owner)
  return false unless st[:configured]
  percent = st[:percent_used].to_f
  threshold = if at
    (at.to_f * 100.0)
  else
    thresholds = LimitChecker.warning_thresholds(plan_owner, limit_key)
    thresholds.max.to_f * 100.0
  end
  return false if threshold <= 0.0
  percent >= threshold
end

.attention_required?(plan_owner, *limit_keys) ⇒ Boolean

Boolean: any attention required (warning/grace/blocked) for provided keys

Returns:

  • (Boolean) 


575
576
577
 
# File 'lib/pricing_plans.rb', line 575

def attention_required?(plan_owner, *limit_keys)
  highest_severity_for(plan_owner, *limit_keys) != :ok
end

.combine_messages_for(plan_owner, *limit_keys) ⇒ Object

Combine human messages for a set of limits into one string



484
485
486
487
488
489
490
491
492
493
 
# File 'lib/pricing_plans.rb', line 484

def combine_messages_for(plan_owner, *limit_keys)
  keys = limit_keys.flatten
  parts = keys.map do |key|
    result = ControllerGuards.require_plan_limit!(key, plan_owner: plan_owner, by: 0)
    next nil if result.ok?
    "#{key.to_s.humanize}: #{result.message}"
  end.compact
  return nil if parts.empty?
  parts.join(" · ")
end

.configure(&block) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/pricing_plans.rb', line 59

def configure(&block)
  # Support both styles simultaneously inside the block:
  # - Bare DSL:   plan :free { ... }
  # - Explicit:   config.plan :free { ... }
  # We evaluate the block with self = configuration, while also
  # passing the configuration object as the first block parameter.
  # Evaluate with self = configuration and also pass the configuration
  # object as a block parameter for explicit calls (config.plan ...).
  configuration.instance_exec(configuration, &block) if block
  configuration.validate!
  Registry.build_from_configuration(configuration)
end

.cta_for(plan_owner) ⇒ Object

Recommend CTA data used by other contexts (pricing plan cards etc.)



606
607
608
609
610
611
612
613
614
615
 
# File 'lib/pricing_plans.rb', line 606

def cta_for(plan_owner)
  plan = PlanResolver.effective_plan_for(plan_owner)
  cfg = configuration
  url = plan&.cta_url(plan_owner: plan_owner) || cfg.default_cta_url
  if url.nil? && cfg.redirect_on_blocked_limit.is_a?(String)
    url = cfg.redirect_on_blocked_limit
  end
  text = plan&.cta_text || cfg.default_cta_text
  { text: text, url: url }
end

.cta_for_upgrade(plan_owner) ⇒ Object

Recommend CTA data (pure data, no UI): { text:, url: } For limit banners, prefer global upgrade defaults to avoid confusing “Current Plan” CTAs



597
598
599
600
601
602
603
 
# File 'lib/pricing_plans.rb', line 597

def cta_for_upgrade(plan_owner)
  cfg = configuration
  url = cfg.default_cta_url
  url ||= (cfg.redirect_on_blocked_limit.is_a?(String) ? cfg.redirect_on_blocked_limit : nil)
  text = cfg.default_cta_text.presence || "View Plans"
  { text: text, url: url }
end

.decorate_for_view(plan, plan_owner: nil, view: nil) ⇒ Object

Optional view-model decorator for UIs (pure data, no HTML)



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/pricing_plans.rb', line 138

def decorate_for_view(plan, plan_owner: nil, view: nil)
  is_current = plan_owner ? (PlanResolver.effective_plan_for(plan_owner)&.key == plan.key) : false
  is_popular = Registry.highlighted_plan&.key == plan.key
  price_label = plan_price_label_for(plan)
  # Duplicate metadata to avoid mutating plan internals from view-layer code.
  {
    key: plan.key,
    name: plan.name,
    description: plan.description,
    bullets: plan.bullets,
    metadata: plan.metadata.dup,
    price_label: price_label,
    is_current: is_current,
    is_popular: is_popular,
    button_text: plan.cta_text,
    button_url: plan.cta_url(plan_owner: plan_owner)
  }
end

.for_pricing(plan_owner: nil, view: nil) ⇒ Object

Single, UI-neutral helper for pricing pages. Returns an array of Hashes containing plain data for building pricing UIs. Each item includes: :key, :name, :description, :bullets, :price_label, :is_current, :is_popular, :button_text, :button_url



104
105
106
 
# File 'lib/pricing_plans.rb', line 104

def for_pricing(plan_owner: nil, view: nil)
  plans.map { |plan| decorate_for_view(plan, plan_owner: plan_owner, view: view) }
end

.highest_severity_for(plan_owner, *limit_keys) ⇒ Object

Aggregates across multiple limits for global banners/messages Returns one of :ok, :warning, :at_limit, :grace, :blocked



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/pricing_plans.rb', line 385

def highest_severity_for(plan_owner, *limit_keys)
  keys = limit_keys.flatten
  per_key = keys.map do |key|
    st = limit_status(key, plan_owner: plan_owner)
    next :ok unless st[:configured]

    lim = st[:limit_amount]
    cur = st[:current_usage]

    # Grace has priority over other non-blocked statuses
    return :grace if st[:grace_active]

    # Numeric limit semantics
    if lim != :unlimited && lim.to_i > 0
      return :blocked if cur.to_i > lim.to_i
      return :at_limit if cur.to_i == lim.to_i
    end

    # Otherwise, warning based on thresholds
    percent = st[:percent_used].to_f
    warn_thresholds = LimitChecker.warning_thresholds(plan_owner, key)
    highest_warn = warn_thresholds.max.to_f * 100.0
    (percent >= highest_warn && highest_warn.positive?) ? :warning : :ok
  end
  return :at_limit if per_key.include?(:at_limit)
  per_key.include?(:warning) ? :warning : :ok
end

.highlighted_plan ⇒ Object

Global highlighted/popular plan sugar (UI ergonomics)



644
645
646
 
# File 'lib/pricing_plans.rb', line 644

def highlighted_plan
  Registry.highlighted_plan
end

.highlighted_plan_key ⇒ Object 



648
649
650
 
# File 'lib/pricing_plans.rb', line 648

def highlighted_plan_key
  highlighted_plan&.key
end

.limit_status(limit_key, plan_owner:) ⇒ Object

UI-neutral status helpers for building settings/usage UIs



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/pricing_plans.rb', line 173

def limit_status(limit_key, plan_owner:)
  plan = PlanResolver.effective_plan_for(plan_owner)
  limit_config = plan&.limit_for(limit_key)
  return { configured: false } unless limit_config

  usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
  limit_amount = limit_config[:to]
  percent = LimitChecker.plan_limit_percent_used(plan_owner, limit_key)
  grace = GraceManager.grace_active?(plan_owner, limit_key)
  blocked = GraceManager.should_block?(plan_owner, limit_key)

  {
    configured: true,
    limit_key: limit_key.to_sym,
    limit_amount: limit_amount,
    current_usage: usage,
    percent_used: percent,
    grace_active: grace,
    grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key),
    blocked: blocked,
    after_limit: limit_config[:after_limit],
    per: !!limit_config[:per]
  }
end

.limit_statuses(*limit_keys, plan_owner:) ⇒ Object 



198
199
200
201
 
# File 'lib/pricing_plans.rb', line 198

def limit_statuses(*limit_keys, plan_owner:)
  keys = limit_keys.flatten
  keys.index_with { |k| limit_status(k, plan_owner: plan_owner) }
end

.message_for(plan_owner, limit_key) ⇒ Object

Convenience: message for a single limit key, or nil if OK



502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/pricing_plans.rb', line 502

def message_for(plan_owner, limit_key)
  st = limit_status(limit_key, plan_owner: plan_owner)
  return nil unless st[:configured]

  severity = severity_for(plan_owner, limit_key)
  return nil if severity == :ok

  cfg = configuration
  current_usage = st[:current_usage]
  limit_amount = st[:limit_amount]
  grace_ends_at = st[:grace_ends_at]

  if cfg.message_builder
    context = case severity
              when :blocked then :over_limit
              when :grace then :grace
              when :at_limit then :at_limit
              else :warning
              end
    begin
      custom = cfg.message_builder.call(context: context, limit_key: limit_key, current_usage: current_usage, limit_amount: limit_amount, grace_ends_at: grace_ends_at)
      return custom if custom
    rescue StandardError
      # fall through to defaults
    end
  end

  noun = begin
    PricingPlans.noun_for(limit_key)
  rescue StandardError
    "limit"
  end

  case severity
  when :blocked
    if limit_amount.is_a?(Numeric)
      "You've gone over your #{noun} for #{limit_key.to_s.humanize.downcase} (#{current_usage}/#{limit_amount}). Please upgrade your plan."
    else
      "You've gone over your #{noun} for #{limit_key.to_s.humanize.downcase}. Please upgrade your plan."
    end
  when :grace
    deadline = grace_ends_at ? ", and your grace period ends #{grace_ends_at.strftime('%B %d at %I:%M%p')}" : ""
    if limit_amount.is_a?(Numeric)
      "Heads up! You’re currently over your #{noun} for #{limit_key.to_s.humanize.downcase} (#{current_usage}/#{limit_amount})#{deadline}. Please upgrade soon to avoid any interruptions."
    else
      "Heads up! You’re currently over your #{noun} for #{limit_key.to_s.humanize.downcase}#{deadline}. Please upgrade soon to avoid any interruptions."
    end
  when :at_limit
    if limit_amount.is_a?(Numeric)
      "You’ve reached your #{noun} for #{limit_key.to_s.humanize.downcase} (#{current_usage}/#{limit_amount}). Upgrade your plan to unlock more."
    else
      "You’re at the maximum allowed for #{limit_key.to_s.humanize.downcase}. Want more? Consider upgrading your plan."
    end
  else # :warning
    if limit_amount.is_a?(Numeric)
      "You’re getting close to your #{noun} for #{limit_key.to_s.humanize.downcase} (#{current_usage}/#{limit_amount}). Keep an eye on your usage, or upgrade your plan now to stay ahead."
    else
      "You’re getting close to your #{noun} for #{limit_key.to_s.humanize.downcase}. Keep an eye on your usage, or upgrade your plan now to stay ahead."
    end
  end
end

.noun_for(limit_key) ⇒ Object

Minimal noun resolver for human messages. Defaults to "limit" to match expected copy in tests and docs. Host apps may override this method.



168
169
170
 
# File 'lib/pricing_plans.rb', line 168

def noun_for(limit_key)
  "limit"
end

.overage_for(plan_owner, limit_key) ⇒ Object

Compute how much over the limit the plan_owner is for a key (0 if within)



565
566
567
568
569
570
571
572
 
# File 'lib/pricing_plans.rb', line 565

def overage_for(plan_owner, limit_key)
  st = limit_status(limit_key, plan_owner: plan_owner)
  return 0 unless st[:configured]
  allowed = st[:limit_amount]
  current = st[:current_usage].to_i
  return 0 unless allowed.is_a?(Numeric)
  [current - allowed.to_i, 0].max
end

.overview_for(plan_owner, *limit_keys) ⇒ Object

Global overview for multiple keys for easy banner building. Returns: { severity:, severity_level:, title:, message:, attention?:, keys:, highest_keys:, highest_limits:, keys_sentence:, noun:, has_have:, cta_text:, cta_url: }



415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'lib/pricing_plans.rb', line 415

def overview_for(plan_owner, *limit_keys)
  keys = limit_keys.flatten
  items = status(plan_owner, limits: keys)
  {
    severity: items.overall_severity,
    severity_level: items.overall_severity_level,
    title: items.overall_title,
    message: items.overall_message,
    attention?: items.overall_attention?,
    keys: items.overall_keys,
    highest_keys: items.overall_highest_keys,
    highest_limits: items.overall_highest_limits,
    keys_sentence: items.overall_keys_sentence,
    noun: items.overall_noun,
    has_have: items.overall_has_have,
    cta_text: items.overall_cta_text,
    cta_url: items.overall_cta_url
  }
end

.plan_price_label_for(plan) ⇒ Object

Derive a human price label for a plan



158
159
160
161
162
163
164
 
# File 'lib/pricing_plans.rb', line 158

def plan_price_label_for(plan)
  return "Free" if plan.price && plan.price.to_i.zero?
  return plan.price_string if plan.price_string
  return "$#{plan.price}/mo" if plan.price
  return "Contact" if plan.stripe_price || plan.price.nil?
  nil
end

.plans ⇒ Object

Zero-shim Plans API for host apps Returns an array of Plan objects in a sensible order (free → paid → enterprise/contact) Excludes hidden plans (use Registry.plans to access all plans including hidden)



85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/pricing_plans.rb', line 85

def plans
  array = Registry.plans.values
    .reject(&:hidden?)  # Filter out hidden plans from public API
  array.sort_by do |p|
    # Free first, then numeric price ascending, then price_string/stripe-price at the end
    if p.price && p.price.to_f.zero?
      0
    elsif p.price
      1 + p.price.to_f
    else
      10_000 # price_string or stripe_price (enterprise/contact) last
    end
  end
end

.popular_plan ⇒ Object 



652
653
654
 
# File 'lib/pricing_plans.rb', line 652

def popular_plan
  highlighted_plan
end

.popular_plan_key ⇒ Object 



656
657
658
 
# File 'lib/pricing_plans.rb', line 656

def popular_plan_key
  highlighted_plan_key
end

.registry ⇒ Object 



78
79
80
 
# File 'lib/pricing_plans.rb', line 78

def registry
  Registry
end

.reset_configuration! ⇒ Object 



72
73
74
75
76
 
# File 'lib/pricing_plans.rb', line 72

def reset_configuration!
  @configuration = nil
  Registry.clear!
  LimitableRegistry.clear!
end

.severity_for(plan_owner, limit_key) ⇒ Object

Convenience: severity for a single limit key Returns :ok | :warning | :grace | :blocked



497
498
499
 
# File 'lib/pricing_plans.rb', line 497

def severity_for(plan_owner, limit_key)
  highest_severity_for(plan_owner, limit_key)
end

.status(plan_owner, limits: []) ⇒ Object 



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/pricing_plans.rb', line 233

def status(plan_owner, limits: [])
  # Use StatusContext to cache all computed values and eliminate N+1 queries.
  # Each call to status() gets its own context - thread-safe by design.
  ctx = StatusContext.new(plan_owner)

  items = Array(limits).map do |limit_key|
    st = ctx.limit_status(limit_key)
    if !st[:configured]
      StatusItem.new(
        key: limit_key,
        human_key: limit_key.to_s.humanize.downcase,
        current: 0,
        allowed: nil,
        percent_used: 0.0,
        grace_active: false,
        grace_ends_at: nil,
        blocked: false,
        per: false,
        severity: :ok,
        severity_level: 0,
        message: nil,
        overage: 0,
        configured: false,
        unlimited: false,
        remaining: nil,
        after_limit: nil,
        attention?: false,
        next_creation_blocked?: false,
        warn_thresholds: [],
        next_warn_percent: nil,
        period_start: nil,
        period_end: nil,
        period_seconds_remaining: nil
      )
    else
      sev = ctx.severity_for(limit_key)
      allowed = st[:limit_amount]
      current = st[:current_usage].to_i
      unlimited = (allowed == :unlimited)
      remaining = if allowed.is_a?(Numeric)
        [allowed.to_i - current, 0].max
      else
        nil
      end
      warn_thresholds = ctx.warning_thresholds(limit_key)
      percent = st[:percent_used].to_f
      next_warn = begin
        thresholds = warn_thresholds.map { |t| t.to_f * 100.0 }.uniq.sort
        thresholds.find { |t| t > percent }
      end
      period_start = nil
      period_end = nil
      period_seconds_remaining = nil
      if st[:per]
        begin
          period_start, period_end = ctx.period_window_for(limit_key)
          if period_end
            period_seconds_remaining = [0, (period_end - Time.current).to_i].max
          end
        rescue StandardError
          # ignore period window resolution errors in status
        end
      end
      next_creation_blocked = case sev
      when :blocked
        true
      when :at_limit
        st[:after_limit] == :block_usage
      else
        false
      end
      StatusItem.new(
        key: limit_key,
        human_key: limit_key.to_s.humanize.downcase,
        current: current,
        allowed: allowed,
        percent_used: st[:percent_used],
        grace_active: st[:grace_active],
        grace_ends_at: st[:grace_ends_at],
        blocked: st[:blocked],
        per: st[:per],
        severity: sev,
        severity_level: case sev
                         when :ok then 0
                         when :warning then 1
                         when :at_limit then 2
                         when :grace then 3
                         when :blocked then 4
                         else 0
                         end,
        message: (sev == :ok ? nil : ctx.message_for(limit_key)),
        overage: ctx.overage_for(limit_key),
        configured: true,
        unlimited: unlimited,
        remaining: remaining,
        after_limit: st[:after_limit],
        attention?: sev != :ok,
        next_creation_blocked?: next_creation_blocked,
        warn_thresholds: warn_thresholds,
        next_warn_percent: next_warn,
        period_start: period_start,
        period_end: period_end,
        period_seconds_remaining: period_seconds_remaining
      )
    end
  end

  # Compute overall helpers using context (all values already cached)
  keys = items.map(&:key)
  sev = ctx.highest_severity_for(*keys)
  title = summary_title_for(sev)
  msg = compute_summary_message_from_context(ctx, keys, sev)
  highest_keys = keys.select { |k| ctx.severity_for(k) == sev }
  highest_limits = items.select { |it| highest_keys.include?(it.key) }
  human_keys = highest_keys.map { |k| k.to_s.humanize.downcase }
  keys_sentence = if human_keys.respond_to?(:to_sentence)
    human_keys.to_sentence
  else
    human_keys.length <= 2 ? human_keys.join(" and ") : (human_keys[0..-2].join(", ") + " and " + human_keys[-1])
  end
  noun = highest_keys.size == 1 ? "plan limit" : "plan limits"
  has_have = highest_keys.size == 1 ? "has" : "have"
  cta = cta_for_upgrade(plan_owner)

  sev_level = case sev
              when :ok then 0
              when :warning then 1
              when :at_limit then 2
              when :grace then 3
              when :blocked then 4
              else 0
              end

  items.define_singleton_method(:overall_severity) { sev }
  items.define_singleton_method(:overall_severity_level) { sev_level }
  items.define_singleton_method(:overall_title) { title }
  items.define_singleton_method(:overall_message) { msg }
  items.define_singleton_method(:overall_attention?) { sev != :ok }
  items.define_singleton_method(:overall_keys) { keys }
  items.define_singleton_method(:overall_highest_keys) { highest_keys }
  items.define_singleton_method(:overall_highest_limits) { highest_limits }
  items.define_singleton_method(:overall_keys_sentence) { keys_sentence }
  items.define_singleton_method(:overall_noun) { noun }
  items.define_singleton_method(:overall_has_have) { has_have }
  items.define_singleton_method(:overall_cta_text) { cta[:text] }
  items.define_singleton_method(:overall_cta_url) { cta[:url] }

  items
end

.suggest_next_plan_for(plan_owner, keys: nil) ⇒ Object

Opinionated next-plan suggestion: pick the smallest plan that satisfies current usage Always suggests visible plans only (never suggests hidden plans)



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/pricing_plans.rb', line 116

def suggest_next_plan_for(plan_owner, keys: nil)
  current_plan = PlanResolver.effective_plan_for(plan_owner)
  sorted = plans  # Only visible plans (hidden plans filtered out)
  keys ||= (current_plan&.limits&.keys || [])
  keys = keys.map(&:to_sym)

  candidate = sorted.find do |plan|
    if current_plan && current_plan.price && plan.price && plan.price.to_f < current_plan.price.to_f
      next false
    end
    keys.all? do |key|
      limit = plan.limit_for(key)
      next true unless limit
      limit[:to] == :unlimited || LimitChecker.current_usage_for(plan_owner, key, limit) <= limit[:to].to_i
    end
  end
  # Fallback logic: never suggest hidden plans
  # If current_plan is hidden (e.g., :unsubscribed), suggest first visible plan instead
  candidate || (current_plan unless current_plan&.hidden?) || sorted.first
end

.summary_message_for(plan_owner, *limit_keys, severity: nil) ⇒ Object

Short, humanized summary for multiple keys Builds copy using only the keys at the highest severity



448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/pricing_plans.rb', line 448

def summary_message_for(plan_owner, *limit_keys, severity: nil)
  keys = limit_keys.flatten
  return nil if keys.empty?
  sev = severity || highest_severity_for(plan_owner, *keys)
  return nil if sev == :ok

  affected = keys.select { |k| severity_for(plan_owner, k) == sev }
  human_keys = affected.map { |k| k.to_s.humanize.downcase }
  keys_list = if human_keys.respond_to?(:to_sentence)
    human_keys.to_sentence
  else
    # Simple fallback: "a, b and c"
    if human_keys.length <= 2
      human_keys.join(" and ")
    else
      human_keys[0..-2].join(", ") + " and " + human_keys[-1]
    end
  end
  noun = affected.size == 1 ? "plan limit" : "plan limits"

  case sev
  when :blocked
    "Your #{noun} for #{keys_list} #{affected.size == 1 ? "has" : "have"} been exceeded. Please upgrade to continue."
  when :grace
    # If any grace ends_at is present, show the earliest
    grace_end = keys.map { |k| GraceManager.grace_ends_at(plan_owner, k) }.compact.min
    suffix = grace_end ? ", grace active until #{grace_end}" : ""
    "You are over your #{noun} for #{keys_list}#{suffix}. Please upgrade to avoid service disruption."
  when :at_limit
    "You have reached your #{noun} for #{keys_list}."
  else # :warning
    "You are approaching your #{noun} for #{keys_list}."
  end
end

.summary_title_for(severity) ⇒ Object

Human title for overall banner based on severity



436
437
438
439
440
441
442
443
444
 
# File 'lib/pricing_plans.rb', line 436

def summary_title_for(severity)
  case severity
  when :blocked then "Plan limit reached"
  when :grace   then "Over limit — grace active"
  when :at_limit then "At your plan limit"
  when :warning then "Approaching plan limit"
  else "All good"
  end
end

.view_models ⇒ Object

View model for modern UIs (Stimulus/Hotwire/JSON). Pure data. Uses the new semantic pricing API on Plan (price_components and Stripe accessors).



110
111
112
 
# File 'lib/pricing_plans.rb', line 110

def view_models
  plans.map { |p| p.to_view_model }
end