Class: Seams::Generators::BillingGenerator

Inherits:
Rails::Generators::Base
  • Object
show all
Includes:
EjectAware, HostInjector
Defined in:
lib/generators/seams/billing/billing_generator.rb

Overview

Generates a canonical Billing engine on top of the generic engine scaffold. Wires Stripe by default through a swappable Gateway adapter, ships subscription + invoice models, a webhook controller with signature verification, and a Billable concern the host’s user model can include.

Run with: bin/rails generate seams:billing rubocop:disable Metrics/ClassLength

Constant Summary collapse

ENGINE_NAME = 
"billing"
DEFAULT_GATEWAY = 
"stripe"
KNOWN_GATEWAYS = 
%w[stripe paddle adyen].freeze

Constants included from EjectAware

EjectAware::EJECT_HEADER_PREFIX

Instance Method Summary collapse

Methods included from EjectAware

#ejected?, #template_unless_ejected

Methods included from HostInjector

#host_inject_gem, #host_inject_include_in_application_controller, #host_inject_include_in_user, #host_inject_mount, #host_uninject_gem, #host_uninject_include, #host_uninject_mount, #routes_draw_anchor

Instance Method Details

#create_base_engine ⇒ Object 



34
35
36
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 34

def create_base_engine
  EngineGenerator.start([ENGINE_NAME], destination_root: destination_root)
end

#create_concern ⇒ Object 



87
88
89
90
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 87

def create_concern
  template_unless_ejected "lib/concerns/billable.rb.tt",
                          engine_path("lib/billing/concerns/billable.rb")
end

#create_controllers_and_views ⇒ Object 



171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 171

def create_controllers_and_views
  template_unless_ejected "app/controllers/webhooks_controller.rb.tt",
                          engine_path("app/controllers/billing/webhooks_controller.rb")
  template_unless_ejected "app/controllers/checkout_controller.rb.tt",
                          engine_path("app/controllers/billing/checkout_controller.rb")
  template_unless_ejected "app/controllers/portal_controller.rb.tt",
                          engine_path("app/controllers/billing/portal_controller.rb")
  template_unless_ejected "app/controllers/plans_controller.rb.tt",
                          engine_path("app/controllers/billing/plans_controller.rb")
  template_unless_ejected "app/views/checkout/success.html.erb.tt",
                          engine_path("app/views/billing/checkout/success.html.erb")
  template_unless_ejected "app/views/plans/index.html.erb.tt",
                          engine_path("app/views/billing/plans/index.html.erb")
end

#create_customer_and_subscription_services ⇒ Object 



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 127

def create_customer_and_subscription_services
  # Phase 3 (2/4) — Customers + Subscriptions service objects.
  template_unless_ejected "app/services/customers/find_or_create_service.rb.tt",
                          engine_path("app/services/billing/customers/find_or_create_service.rb")
  template_unless_ejected "app/services/subscriptions/cancel_service.rb.tt",
                          engine_path("app/services/billing/subscriptions/cancel_service.rb")
  template_unless_ejected "app/services/subscriptions/change_plan_service.rb.tt",
                          engine_path("app/services/billing/subscriptions/change_plan_service.rb")
  template_unless_ejected "app/services/subscriptions/reactivate_service.rb.tt",
                          engine_path("app/services/billing/subscriptions/reactivate_service.rb")
end

#create_domain_services ⇒ Object 



122
123
124
125
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 122

def create_domain_services
  create_customer_and_subscription_services
  create_invoice_and_lifetime_services
end

#create_dummy_app ⇒ Object 



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 290

def create_dummy_app
  # Post Wave 9: the dummy app does NOT ship a host User model.
  # Billing addresses an Accounts::Account (the tenant), not a
  # human; the engine specs use the dummy `accounts` table that
  # ships in dummy_schema below. Hosts that keep a User model
  # are unaffected — Billable is included into the configured
  # tenant class (default Accounts::Account), not into User.
  Seams::Generators::DummyAppWriter.write!(
    engine_path: File.join(destination_root, "engines", ENGINE_NAME),
    engine_module: "Billing",
    mount_at: "/billing",
    schema: dummy_schema
  )
  template "spec/runtime/boot_spec.rb.tt",
           engine_path("spec/runtime/billing_boot_spec.rb")
  # Phase 3 (3/4) coverage gap: a runtime spec that instantiates
  # each of the 13 webhook handlers with the matching Stripe
  # fixture and asserts the local DB row + canonical seams event.
  template "spec/runtime/webhook_handlers_spec.rb.tt",
           engine_path("spec/runtime/webhook_handlers_spec.rb")
end

#create_gateways ⇒ Object 



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 67

def create_gateways
  template_unless_ejected "lib/gateways/abstract.rb.tt",
                          engine_path("lib/billing/gateways/abstract.rb")

  # Stripe ships unconditionally (it's the default + reference
  # implementation that sibling specs reference). Paddle / Adyen
  # are stubs — copied only when --gateway=paddle/adyen.
  template_unless_ejected "lib/gateways/stripe.rb.tt",
                          engine_path("lib/billing/gateways/stripe.rb")
  template_unless_ejected "lib/stripe/client.rb.tt",
                          engine_path("lib/billing/stripe/client.rb")
  template_unless_ejected "lib/stripe/webhook_signature.rb.tt",
                          engine_path("lib/billing/stripe/webhook_signature.rb")

  return if gateway == "stripe"

  template_unless_ejected "lib/gateways/#{gateway}.rb.tt",
                          engine_path("lib/billing/gateways/#{gateway}.rb")
end

#create_helpers ⇒ Object 



269
270
271
272
273
274
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 269

def create_helpers
  # Phase 3 (1/4) — currency formatter for the pricing page +
  # invoice views.
  template_unless_ejected "app/helpers/currency_helper.rb.tt",
                          engine_path("app/helpers/billing/currency_helper.rb")
end

#create_invoice_and_lifetime_services ⇒ Object 



139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 139

def create_invoice_and_lifetime_services
  template_unless_ejected "app/services/invoices/sync_service.rb.tt",
                          engine_path("app/services/billing/invoices/sync_service.rb")
  # Lifetime Deal services — see issue #2 section 3A.LTD.
  template_unless_ejected "app/services/lifetime/grant_pass_service.rb.tt",
                          engine_path("app/services/billing/lifetime/grant_pass_service.rb")
  template_unless_ejected "app/services/lifetime/revoke_pass_service.rb.tt",
                          engine_path("app/services/billing/lifetime/revoke_pass_service.rb")
  template_unless_ejected "app/services/lifetime/create_pass_from_checkout_service.rb.tt",
                          engine_path("app/services/billing/lifetime/create_pass_from_checkout_service.rb")
  template_unless_ejected "app/services/lifetime/create_lifetime_session_service.rb.tt",
                          engine_path("app/services/billing/lifetime/create_lifetime_session_service.rb")
end

#create_jobs ⇒ Object 



92
93
94
95
96
97
98
99
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 92

def create_jobs
  template_unless_ejected "app/jobs/application_job.rb.tt",
                          engine_path("app/jobs/billing/application_job.rb")
  template_unless_ejected "app/jobs/start_subscription_job.rb.tt",
                          engine_path("app/jobs/billing/start_subscription_job.rb")
  template_unless_ejected "app/jobs/cancel_subscription_job.rb.tt",
                          engine_path("app/jobs/billing/cancel_subscription_job.rb")
end

#create_lifetime_admin_controller_and_views ⇒ Object

LTD admin controller + views (issue #2 section 3A.LTD). Kept in its own generator method so create_controllers_and_views stays under the AbcSize lint threshold.



206
207
208
209
210
211
212
213
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 206

def create_lifetime_admin_controller_and_views
  template_unless_ejected "app/controllers/admin/lifetime_passes_controller.rb.tt",
                          engine_path("app/controllers/billing/admin/lifetime_passes_controller.rb")
  template_unless_ejected "app/views/admin/lifetime_passes/index.html.erb.tt",
                          engine_path("app/views/billing/admin/lifetime_passes/index.html.erb")
  template_unless_ejected "app/views/admin/lifetime_passes/new.html.erb.tt",
                          engine_path("app/views/billing/admin/lifetime_passes/new.html.erb")
end

#create_migrations ⇒ Object 



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 215

def create_migrations
  template "db/migrate/create_billing_subscriptions.rb.tt",
           engine_path("db/migrate/#{timestamp(0)}_create_billing_subscriptions.rb")
  template "db/migrate/create_billing_invoices.rb.tt",
           engine_path("db/migrate/#{timestamp(1)}_create_billing_invoices.rb")
  template "db/migrate/create_billing_webhook_events.rb.tt",
           engine_path("db/migrate/#{timestamp(2)}_create_billing_webhook_events.rb")
  template "db/migrate/create_billing_plans.rb.tt",
           engine_path("db/migrate/#{timestamp(3)}_create_billing_plans.rb")
  template "db/migrate/create_billing_lifetime_passes.rb.tt",
           engine_path("db/migrate/#{timestamp(4)}_create_billing_lifetime_passes.rb")
end

#create_models ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 52

def create_models
  template_unless_ejected "app/models/application_record.rb.tt",
                          engine_path("app/models/billing/application_record.rb")
  template_unless_ejected "app/models/subscription.rb.tt",
                          engine_path("app/models/billing/subscription.rb")
  template_unless_ejected "app/models/invoice.rb.tt",
                          engine_path("app/models/billing/invoice.rb")
  template_unless_ejected "app/models/webhook_event.rb.tt",
                          engine_path("app/models/billing/webhook_event.rb")
  template_unless_ejected "app/models/plan.rb.tt",
                          engine_path("app/models/billing/plan.rb")
  template_unless_ejected "app/models/lifetime_pass.rb.tt",
                          engine_path("app/models/billing/lifetime_pass.rb")
end

#create_service_foundation ⇒ Object 



107
108
109
110
111
112
113
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 107

def create_service_foundation
  # Phase 3 (1/4) — uniform service object foundation.
  template_unless_ejected "app/services/service_result.rb.tt",
                          engine_path("app/services/billing/service_result.rb")
  template_unless_ejected "app/services/stripe_service.rb.tt",
                          engine_path("app/services/billing/stripe_service.rb")
end

#create_services ⇒ Object 



101
102
103
104
105
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 101

def create_services
  create_service_foundation
  create_session_services
  create_domain_services
end

#create_session_services ⇒ Object 



115
116
117
118
119
120
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 115

def create_session_services
  template_unless_ejected "app/services/checkout_session_service.rb.tt",
                          engine_path("app/services/billing/checkout/create_session_service.rb")
  template_unless_ejected "app/services/portal_session_service.rb.tt",
                          engine_path("app/services/billing/portal/create_session_service.rb")
end

#create_specs ⇒ Object 



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 228

def create_specs
  template_unless_ejected "spec/models/subscription_spec.rb.tt",
                          engine_path("spec/models/billing/subscription_spec.rb")
  template_unless_ejected "spec/models/plan_spec.rb.tt",
                          engine_path("spec/models/billing/plan_spec.rb")
  template_unless_ejected "spec/gateways/stripe_spec.rb.tt",
                          engine_path("spec/gateways/billing/stripe_spec.rb")
  # Phase 3 (1/4) — factories + Stripe webmock helpers + event fixtures.
  template_unless_ejected "spec/factories/billing.rb.tt",
                          engine_path("spec/factories/billing.rb")
  template_unless_ejected "spec/support/stripe_helpers.rb.tt",
                          engine_path("spec/support/stripe_helpers.rb")
  # Phase 3 (4/4) — gateway contract shared_examples.
  template_unless_ejected "spec/support/shared_examples/a_billing_gateway.rb.tt",
                          engine_path("spec/support/shared_examples/a_billing_gateway.rb")
  template_unless_ejected "spec/gateways/contract_spec.rb.tt",
                          engine_path("spec/gateways/billing/contract_spec.rb")
  create_stripe_event_fixtures
end

#create_stripe_event_fixtures ⇒ Object 



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 248

def create_stripe_event_fixtures
  %w[
    customer_subscription_created
    customer_subscription_updated
    customer_subscription_deleted
    customer_subscription_trial_will_end
    invoice_created
    invoice_paid
    invoice_payment_failed
    invoice_finalized
    invoice_voided
    payment_intent_succeeded
    payment_intent_payment_failed
    charge_refunded
    checkout_session_completed
  ].each do |name|
    template_unless_ejected "spec/fixtures/stripe/#{name}.json.tt",
                            engine_path("spec/fixtures/stripe/#{name}.json")
  end
end

#create_subscriptions_and_invoices_ui ⇒ Object

Phase 3 (4/4) — self-service subscription management + read-only billing history. Routes live in config/routes.rb.tt.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 188

def create_subscriptions_and_invoices_ui
  template_unless_ejected "app/controllers/subscriptions_controller.rb.tt",
                          engine_path("app/controllers/billing/subscriptions_controller.rb")
  template_unless_ejected "app/controllers/invoices_controller.rb.tt",
                          engine_path("app/controllers/billing/invoices_controller.rb")
  template_unless_ejected "app/views/subscriptions/index.html.erb.tt",
                          engine_path("app/views/billing/subscriptions/index.html.erb")
  template_unless_ejected "app/views/subscriptions/show.html.erb.tt",
                          engine_path("app/views/billing/subscriptions/show.html.erb")
  template_unless_ejected "app/views/invoices/index.html.erb.tt",
                          engine_path("app/views/billing/invoices/index.html.erb")
  template_unless_ejected "app/views/invoices/show.html.erb.tt",
                          engine_path("app/views/billing/invoices/show.html.erb")
end

#create_webhook_process_event_job ⇒ Object 



166
167
168
169
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 166

def create_webhook_process_event_job
  template_unless_ejected "app/jobs/webhooks/process_event_job.rb.tt",
                          engine_path("app/jobs/billing/webhooks/process_event_job.rb")
end

#create_webhook_router_and_handlers ⇒ Object

Phase 3 (3/4) — webhook router + 13 handler classes.



154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 154

def create_webhook_router_and_handlers
  template_unless_ejected "app/services/webhooks/handler.rb.tt",
                          engine_path("app/services/billing/webhooks/handler.rb")
  template_unless_ejected "app/services/webhooks/event_router.rb.tt",
                          engine_path("app/services/billing/webhooks/event_router.rb")

  webhook_handler_templates.each do |basename|
    template_unless_ejected "app/services/webhooks/handlers/#{basename}.rb.tt",
                            engine_path("app/services/billing/webhooks/handlers/#{basename}.rb")
  end
end

#overwrite_engine_entry_point ⇒ Object 



38
39
40
41
42
43
44
45
46
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 38

def overwrite_engine_entry_point
  # engine.rb / lib/billing.rb stay framework-managed.
  template "lib/engine.rb.tt",                 engine_path("lib/billing/engine.rb"),        force: true
  template "lib/billing.rb.tt",                engine_path("lib/billing.rb"),               force: true
  template_unless_ejected "lib/configuration.rb.tt",
                          engine_path("lib/billing/configuration.rb")
  template_unless_ejected "lib/tasks/billing_check.rake.tt",
                          engine_path("lib/tasks/billing_check.rake")
end

#overwrite_readme ⇒ Object 



276
277
278
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 276

def overwrite_readme
  template "README.md.tt", engine_path("README.md"), force: true
end

#overwrite_routes ⇒ Object 



48
49
50
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 48

def overwrite_routes
  template_unless_ejected "config/routes.rb.tt", engine_path("config/routes.rb"), force: true
end

#report_summary ⇒ Object 



331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 331

def report_summary
  say ""
  say "  Billing engine generated at engines/billing/", :green
  say ""
  say "  Next steps:", :yellow
  say "    1. bundle install   (picks up stripe + Billing::Engine)"
  say "    2. Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in your env"
  say "    3. Configure your Stripe webhook to POST to /billing/webhooks/stripe"
  say "    4. bin/rails db:migrate"
  say ""
end

#update_exposed_concerns ⇒ Object 



280
281
282
283
284
285
286
287
288
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 280

def update_exposed_concerns
  rubocop_path = engine_path(".rubocop.yml")
  return unless File.exist?(rubocop_path)

  contents = File.read(rubocop_path)
  replacement = "  ExposedConcerns:\n    - Billing::Billable"
  contents.sub!(/^  ExposedConcerns: \[\]$/, replacement)
  File.write(rubocop_path, contents)
end

#wire_into_host ⇒ Object 



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
 
# File 'lib/generators/seams/billing/billing_generator.rb', line 312

def wire_into_host
  # The Billing engine speaks Stripe via the official `stripe`
  # gem (https://github.com/stripe/stripe-ruby). Wave 8's earlier
  # decision to roll a Faraday client was reversed — Stripe
  # maintains the gem as a first-class deliverable; tracking
  # their API ourselves wasn't worth the centralisation
  # benefit. See feedback_external_apis.md.
  host_inject_gem("stripe", "~> 13.0")
  host_inject_gem("factory_bot_rails", "~> 6.4",  group: :test)
  host_inject_gem("webmock",           "~> 3.23", group: :test)
  host_inject_mount(engine_class: "Billing::Engine", at: "/billing")
  # Post Wave 9: Billing::Billable is included into the
  # configured tenant class (default Accounts::Account) at
  # engine boot via Billing::Configuration#billable_class —
  # not injected into a host User model. Hosts that customise
  # the tenant class set Billing.configuration.billable_class
  # in config/initializers/billing.rb.
end