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/pricing_plans/legacy_plan_assignment_api.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, LegacyDefaultPlanAssignmentError, LegacyPlanAssignmentApi, LimitChecker, LimitableRegistry, OverageReporter, PeriodCalculator, Plan, PlanNotFoundError, PlanResolution, PlanResolver, PriceComponents, Registry, Result, StatusContext, StatusItem, Usage

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"0.5.0"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ Object 



68
69
70
 
# File 'lib/pricing_plans.rb', line 68

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



639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/pricing_plans.rb', line 639

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) 


601
602
603
604
605
606
607
608
609
610
611
612
613
 
# File 'lib/pricing_plans.rb', line 601

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) 


595
596
597
 
# File 'lib/pricing_plans.rb', line 595

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



504
505
506
507
508
509
510
511
512
513
 
# File 'lib/pricing_plans.rb', line 504

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 



79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/pricing_plans.rb', line 79

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.)



626
627
628
629
630
631
632
633
634
635
 
# File 'lib/pricing_plans.rb', line 626

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



617
618
619
620
621
622
623
 
# File 'lib/pricing_plans.rb', line 617

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)



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/pricing_plans.rb', line 158

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

.deprecator ⇒ Object

A gem-specific deprecator lets host applications configure pricing_plans warnings independently and lets Rails include them in its deprecator collection.



75
76
77
 
# File 'lib/pricing_plans.rb', line 75

def deprecator
  @deprecator ||= ActiveSupport::Deprecation.new("0.6.0", "pricing_plans")
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



124
125
126
 
# File 'lib/pricing_plans.rb', line 124

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



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/pricing_plans.rb', line 405

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)



664
665
666
 
# File 'lib/pricing_plans.rb', line 664

def highlighted_plan
  Registry.highlighted_plan
end

.highlighted_plan_key ⇒ Object 



668
669
670
 
# File 'lib/pricing_plans.rb', line 668

def highlighted_plan_key
  highlighted_plan&.key
end

.limit_status(limit_key, plan_owner:) ⇒ Object

UI-neutral status helpers for building settings/usage UIs



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/pricing_plans.rb', line 193

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 



218
219
220
221
 
# File 'lib/pricing_plans.rb', line 218

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



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
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
 
# File 'lib/pricing_plans.rb', line 522

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.



188
189
190
 
# File 'lib/pricing_plans.rb', line 188

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)



585
586
587
588
589
590
591
592
 
# File 'lib/pricing_plans.rb', line 585

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: }



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/pricing_plans.rb', line 435

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



178
179
180
181
182
183
184
 
# File 'lib/pricing_plans.rb', line 178

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)



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/pricing_plans.rb', line 105

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 



672
673
674
 
# File 'lib/pricing_plans.rb', line 672

def popular_plan
  highlighted_plan
end

.popular_plan_key ⇒ Object 



676
677
678
 
# File 'lib/pricing_plans.rb', line 676

def popular_plan_key
  highlighted_plan_key
end

.registry ⇒ Object 



98
99
100
 
# File 'lib/pricing_plans.rb', line 98

def registry
  Registry
end

.reset_configuration! ⇒ Object 



92
93
94
95
96
 
# File 'lib/pricing_plans.rb', line 92

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



517
518
519
 
# File 'lib/pricing_plans.rb', line 517

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

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



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
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/pricing_plans.rb', line 253

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)



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

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



468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
 
# File 'lib/pricing_plans.rb', line 468

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



456
457
458
459
460
461
462
463
464
 
# File 'lib/pricing_plans.rb', line 456

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).



130
131
132
 
# File 'lib/pricing_plans.rb', line 130

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