seams 0.1.0

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_finalized.json.tt

@@ -0,0 +1,18 @@
+{
+  "id": "evt_test_invoice_finalized",
+  "object": "event",
+  "type": "invoice.finalized",
+  "livemode": false,
+  "created": 1730700000,
+  "data": {
+    "object": {
+      "id": "in_test_123",
+      "object": "invoice",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "status": "open",
+      "amount_due": 1299,
+      "currency": "gbp"
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_paid.json.tt

@@ -0,0 +1,19 @@
+{
+  "id": "evt_test_invoice_paid",
+  "object": "event",
+  "type": "invoice.paid",
+  "livemode": false,
+  "created": 1730500000,
+  "data": {
+    "object": {
+      "id": "in_test_123",
+      "object": "invoice",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "status": "paid",
+      "amount_paid": 1299,
+      "currency": "gbp",
+      "paid_at": 1730500000
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_payment_failed.json.tt

@@ -0,0 +1,20 @@
+{
+  "id": "evt_test_invoice_payment_failed",
+  "object": "event",
+  "type": "invoice.payment_failed",
+  "livemode": false,
+  "created": 1730600000,
+  "data": {
+    "object": {
+      "id": "in_test_123",
+      "object": "invoice",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "status": "open",
+      "amount_due": 1299,
+      "currency": "gbp",
+      "attempt_count": 1,
+      "next_payment_attempt": 1730700000
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/invoice_voided.json.tt

@@ -0,0 +1,18 @@
+{
+  "id": "evt_test_invoice_voided",
+  "object": "event",
+  "type": "invoice.voided",
+  "livemode": false,
+  "created": 1730800000,
+  "data": {
+    "object": {
+      "id": "in_test_123",
+      "object": "invoice",
+      "customer": "cus_test_123",
+      "subscription": "sub_test_123",
+      "status": "void",
+      "amount_due": 1299,
+      "currency": "gbp"
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/payment_intent_payment_failed.json.tt

@@ -0,0 +1,21 @@
+{
+  "id": "evt_test_payment_intent_payment_failed",
+  "object": "event",
+  "type": "payment_intent.payment_failed",
+  "livemode": false,
+  "created": 1731000000,
+  "data": {
+    "object": {
+      "id": "pi_test_123",
+      "object": "payment_intent",
+      "customer": "cus_test_123",
+      "amount": 1299,
+      "currency": "gbp",
+      "status": "requires_payment_method",
+      "last_payment_error": {
+        "code": "card_declined",
+        "message": "Your card was declined."
+      }
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/fixtures/stripe/payment_intent_succeeded.json.tt

@@ -0,0 +1,17 @@
+{
+  "id": "evt_test_payment_intent_succeeded",
+  "object": "event",
+  "type": "payment_intent.succeeded",
+  "livemode": false,
+  "created": 1730900000,
+  "data": {
+    "object": {
+      "id": "pi_test_123",
+      "object": "payment_intent",
+      "customer": "cus_test_123",
+      "amount": 1299,
+      "currency": "gbp",
+      "status": "succeeded"
+    }
+  }
+}

data/lib/generators/seams/billing/templates/spec/gateways/contract_spec.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require_relative "../../support/shared_examples/a_billing_gateway"
+
+# Stripe is the reference implementation — it MUST satisfy the
+# contract. Hosts adding a new gateway add a sibling spec file and
+# the same `it_behaves_like` line.
+RSpec.describe Billing::Gateways::Stripe do
+  it_behaves_like "a billing gateway"
+end

data/lib/generators/seams/billing/templates/spec/gateways/stripe_spec.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Billing::Gateways::Stripe do
+  let(:fake_client) { instance_double(Billing::Stripe::Client) }
+  let(:gateway)     { described_class.new(client: fake_client) }
+
+  describe "#create_subscription" do
+    let(:response) do
+      {
+        "id"     => "sub_x",
+        "status" => "active",
+        "items"  => { "data" => [{ "price" => { "id" => "price_x" }, "current_period_end" => 1_700_000_000 }] }
+      }
+    end
+
+    it "delegates to the Faraday client with the documented param shape" do
+      expect(fake_client).to receive(:create_subscription).with(
+        customer: "cus_x", items: [{ price: "price_x" }]
+      ).and_return(response)
+
+      result = gateway.create_subscription(customer_ref: "cus_x", plan_ref: "price_x")
+      expect(result).to include(id: "sub_x", status: "active", plan_ref: "price_x", current_period_end: 1_700_000_000)
+    end
+
+    it "lets Billing::GatewayError raised by the client propagate" do
+      allow(fake_client).to receive(:create_subscription).and_raise(Billing::GatewayError, "bad")
+      expect { gateway.create_subscription(customer_ref: "x", plan_ref: "y") }
+        .to raise_error(Billing::GatewayError, "bad")
+    end
+  end
+
+  describe "#verify_webhook" do
+    let(:secret)    { "whsec_test" }
+    let(:timestamp) { Time.now.to_i }
+    let(:payload)   { %({"id":"evt_1","type":"customer.subscription.created","livemode":false,"data":{"object":{"id":"sub_x"}}}) }
+    let(:signed)    { OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, "#{timestamp}.#{payload}") }
+    let(:header)    { "t=#{timestamp},v1=#{signed}" }
+
+    it "verifies a valid signed payload + returns the normalised event" do
+      event = gateway.verify_webhook(payload: payload, signature: header, secret: secret)
+      expect(event).to include(id: "evt_1", type: "customer.subscription.created", livemode: false)
+      expect(event[:object]).to eq("id" => "sub_x")
+    end
+
+    it "raises Billing::WebhookError on a bad signature" do
+      bad_header = "t=#{timestamp},v1=deadbeef"
+      expect { gateway.verify_webhook(payload: payload, signature: bad_header, secret: secret) }
+        .to raise_error(Billing::WebhookError, /No signatures found matching/)
+    end
+  end
+end

data/lib/generators/seams/billing/templates/spec/models/plan_spec.rb.tt

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Billing::Plan do
+  describe "validations" do
+    it "requires gateway_ref" do
+      plan = build(:billing_plan, gateway_ref: nil)
+      expect(plan).not_to be_valid
+    end
+
+    it "rejects unknown intervals" do
+      plan = build(:billing_plan, interval: "decade")
+      expect(plan).not_to be_valid
+    end
+  end
+
+  describe "#lifetime_inventory_remaining" do
+    it "is nil for plans with no cap" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: nil)
+      expect(plan.lifetime_inventory_remaining).to be_nil
+    end
+
+    it "is the cap minus issued passes" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: 3)
+      create(:billing_lifetime_pass, plan_ref: plan.gateway_ref)
+      expect(plan.lifetime_inventory_remaining).to eq(2)
+    end
+
+    it "floors at zero (no negative remaining)" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: 1)
+      2.times { create(:billing_lifetime_pass, plan_ref: plan.gateway_ref) }
+      expect(plan.lifetime_inventory_remaining).to eq(0)
+    end
+  end
+
+  describe "#enforce_lifetime_inventory_or_raise!" do
+    it "no-ops on non-lifetime plans even if max_lifetime_units is set" do
+      plan = create(:billing_plan, interval: "month", max_lifetime_units: 1)
+      Billing::Plan.transaction do
+        expect { plan.enforce_lifetime_inventory_or_raise! }.not_to raise_error
+      end
+    end
+
+    it "no-ops on lifetime plans with nil max_lifetime_units (unlimited)" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: nil)
+      # Even if some passes exist, nil cap means no enforcement.
+      create(:billing_lifetime_pass, plan_ref: plan.gateway_ref)
+      Billing::Plan.transaction do
+        expect { plan.enforce_lifetime_inventory_or_raise! }.not_to raise_error
+      end
+    end
+
+    it "passes when remaining inventory > 0" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: 5)
+      create(:billing_lifetime_pass, plan_ref: plan.gateway_ref)
+      Billing::Plan.transaction do
+        expect { plan.enforce_lifetime_inventory_or_raise! }.not_to raise_error
+      end
+    end
+
+    it "raises Billing::Plan::SoldOut when the cap is exhausted" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: 1)
+      create(:billing_lifetime_pass, plan_ref: plan.gateway_ref)
+      Billing::Plan.transaction do
+        expect { plan.enforce_lifetime_inventory_or_raise! }
+          .to raise_error(Billing::Plan::SoldOut, /sold out/)
+      end
+    end
+
+    it "issues a SELECT ... FOR UPDATE row-lock under the hood" do
+      plan = create(:billing_lifetime_plan, max_lifetime_units: 5)
+      # We can't directly inspect the lock, but we can confirm
+      # `lock!` is invoked (which is what produces the FOR UPDATE).
+      expect(plan).to receive(:lock!).and_call_original
+      Billing::Plan.transaction do
+        plan.enforce_lifetime_inventory_or_raise!
+      end
+    end
+  end
+end

data/lib/generators/seams/billing/templates/spec/models/subscription_spec.rb.tt

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Billing::Subscription do
+  let(:valid_attrs) do
+    {
+      account_id:   SecureRandom.uuid,
+      customer_ref: "cus_x",
+      plan_ref:     "price_x",
+      gateway_ref:  "sub_x",
+      status:       "active"
+    }
+  end
+
+  describe "validations" do
+    it "requires gateway_ref" do
+      sub = described_class.new(valid_attrs.merge(gateway_ref: nil))
+      expect(sub).not_to be_valid
+    end
+
+    it "requires account_id" do
+      sub = described_class.new(valid_attrs.merge(account_id: nil))
+      expect(sub).not_to be_valid
+    end
+
+    it "rejects unknown statuses" do
+      sub = described_class.new(valid_attrs.merge(status: "made_up"))
+      expect(sub).not_to be_valid
+    end
+  end
+
+  describe "#active?" do
+    it "is true for active and trialing" do
+      expect(described_class.new(valid_attrs.merge(status: "active"))).to be_active
+      expect(described_class.new(valid_attrs.merge(status: "trialing"))).to be_active
+    end
+
+    it "is false for canceled" do
+      expect(described_class.new(valid_attrs.merge(status: "canceled"))).not_to be_active
+    end
+  end
+end

data/lib/generators/seams/billing/templates/spec/runtime/boot_spec.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Billing engine boot", type: :integration do
+  it "loads the engine" do
+    expect(defined?(Billing::Engine)).to eq("constant")
+  end
+
+  it "registers the five canonical billing events" do
+    %w[
+      subscription.created.billing
+      subscription.updated.billing
+      subscription.canceled.billing
+      invoice.paid.billing
+      invoice.failed.billing
+    ].each do |event|
+      expect(Seams::EventRegistry.registered?(event)).to be(true)
+    end
+  end
+
+  it "creates the billing tables from the dummy schema" do
+    %i[billing_subscriptions billing_invoices billing_webhook_events billing_plans
+       billing_lifetime_passes accounts].each do |t|
+      expect(ActiveRecord::Base.connection.table_exists?(t)).to be(true), "missing #{t}"
+    end
+  end
+
+  it "exposes the Billable concern + the Stripe gateway class" do
+    expect(defined?(Billing::Billable)).to          eq("constant")
+    expect(defined?(Billing::Gateways::Stripe)).to  eq("constant")
+    expect(defined?(Billing::Configuration)).to     eq("constant")
+  end
+
+  it "Billing::Configuration ships an Account-default billable_class" do
+    expect(Billing.configuration.billable_class).to eq("Accounts::Account")
+  end
+end