snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-server/test/integration/billing/suites/billing-controller.integration-spec.ts

@@ -0,0 +1,112 @@
+import request from 'supertest';
+import { createMockStripeEntitlementUpdatedData } from 'test/integration/billing/utils/create-mock-stripe-entitlement-updated-data.util';
+import { createMockStripePriceCreatedData } from 'test/integration/billing/utils/create-mock-stripe-price-created-data.util';
+import { createMockStripeProductUpdatedData } from 'test/integration/billing/utils/create-mock-stripe-product-updated-data.util';
+import { createMockStripeSubscriptionCreatedData } from 'test/integration/billing/utils/create-mock-stripe-subscription-created-data.util';
+
+const client = request(`http://localhost:${APP_PORT}`);
+
+describe('BillingController (integration)', () => {
+  it('should handle product.updated and price.created webhook events', async () => {
+    const productUpdatedPayload = {
+      type: 'product.updated',
+      data: createMockStripeProductUpdatedData(),
+    };
+    const priceCreatedPayload = {
+      type: 'price.created',
+      data: createMockStripePriceCreatedData(),
+    };
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'correct-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(productUpdatedPayload))
+      .expect(200)
+      .then((res) => {
+        expect(res.body.stripeProductId).toBeDefined();
+      });
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'correct-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(priceCreatedPayload))
+      .expect(200)
+      .then((res) => {
+        expect(res.body.stripePriceId).toBeDefined();
+        expect(res.body.stripeMeterId).toBeDefined();
+      });
+  });
+  it('should handle subscription.created webhook event', async () => {
+    const subscriptionCreatedPayload = {
+      type: 'customer.subscription.created',
+      data: createMockStripeSubscriptionCreatedData(),
+    };
+    const entitlementUpdatedPayload = {
+      type: 'entitlements.active_entitlement_summary.updated',
+      data: createMockStripeEntitlementUpdatedData(),
+    };
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'correct-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(subscriptionCreatedPayload))
+      .expect(200)
+      .then((res) => {
+        expect(res.body.stripeSubscriptionId).toBeDefined();
+        expect(res.body.stripeCustomerId).toBeDefined();
+      });
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'correct-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(entitlementUpdatedPayload))
+      .expect(200)
+      .then((res) => {
+        expect(res.body.stripeEntitlementCustomerId).toBeDefined();
+      });
+  });
+
+  it('should handle entitlements.active_entitlement_summary.updated when the subscription is not found', async () => {
+    const entitlementUpdatedPayload = {
+      type: 'entitlements.active_entitlement_summary.updated',
+      data: createMockStripeEntitlementUpdatedData({
+        customer: 'new_customer',
+      }),
+    };
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'correct-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(entitlementUpdatedPayload))
+      .expect(404);
+  });
+
+  it('should reject webhook with invalid signature', async () => {
+    const entitlementUpdatedPayload = {
+      type: 'customer.entitlement.created',
+      data: {
+        object: {
+          id: 'ent_test123',
+        },
+      },
+    };
+
+    await client
+      .post('/webhooks/stripe')
+      .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+      .set('stripe-signature', 'invalid-signature')
+      .set('Content-Type', 'application/json')
+      .send(JSON.stringify(entitlementUpdatedPayload))
+      .expect(500);
+  });
+});

packages/twenty-server/test/integration/billing/suites/billing-credit-grant-admin.integration-spec.ts

@@ -0,0 +1,413 @@
+import { INTERNAL_CREDITS_PER_DISPLAY_CREDIT } from 'twenty-shared/constants';
+import { randomUUID } from 'node:crypto';
+
+import { addDays, addMonths, startOfMonth } from 'date-fns';
+import request from 'supertest';
+import {
+  getBillingUsageCacheService,
+  getSeededBillingWorkspaceId,
+  listCreditGrants,
+  quitBillingFixtureRedis,
+  readAllowanceCounter,
+  resetBillingCreditState,
+  setupResourceCreditSubscription,
+  warmAllowanceCounter,
+  setSubscriptionStatus,
+} from 'test/integration/billing/utils/billing-credit-fixtures.util';
+
+import { BillingCreditGrantType } from 'src/engine/core-modules/billing/enums/billing-credit-grant-type.enum';
+import { SubscriptionInterval } from 'src/engine/core-modules/billing/enums/billing-subscription-interval.enum';
+import { SubscriptionStatus } from 'src/engine/core-modules/billing/enums/billing-subscription-status.enum';
+import { alignGrantExpiryToPeriodEnd } from 'src/engine/core-modules/billing/utils/align-grant-expiry-to-period-end.util';
+
+const client = request(`http://localhost:${APP_PORT}`);
+
+const PERIOD_START = startOfMonth(new Date());
+const PERIOD_END = addMonths(PERIOD_START, 1);
+const ALLOWANCE_MICRO = 1_000_000;
+
+const GRANT_MUTATION = `
+  mutation GrantWorkspaceCredits(
+    $workspaceId: UUID!
+    $amount: Float!
+    $type: BillingCreditGrantType!
+    $reason: String
+    $expiresInDays: Int
+    $clientOperationId: UUID!
+  ) {
+    grantWorkspaceCredits(
+      workspaceId: $workspaceId
+      amount: $amount
+      type: $type
+      reason: $reason
+      expiresInDays: $expiresInDays
+      clientOperationId: $clientOperationId
+    ) {
+      id
+      amount
+      type
+      reason
+      expiresAt
+      isActive
+    }
+  }
+`;
+
+const REVOKE_MUTATION = `
+  mutation RevokeWorkspaceCreditGrant($workspaceId: UUID!, $creditGrantId: UUID!) {
+    revokeWorkspaceCreditGrant(
+      workspaceId: $workspaceId
+      creditGrantId: $creditGrantId
+    ) {
+      id
+      revokedAt
+    }
+  }
+`;
+
+const grantCredits = (variables: Record<string, unknown>) =>
+  callAdminGraphql(GRANT_MUTATION, {
+    clientOperationId: randomUUID(),
+    ...variables,
+  });
+
+const callAdminGraphql = (query: string, variables: Record<string, unknown>) =>
+  client
+    .post('/admin-panel')
+    .set('Authorization', `Bearer ${APPLE_JANE_ADMIN_ACCESS_TOKEN}`)
+    .set('Content-Type', 'application/json')
+    .send({ query, variables });
+
+describe('Admin credit grant and revoke (integration)', () => {
+  let workspaceId: string;
+
+  beforeAll(async () => {
+    workspaceId = await getSeededBillingWorkspaceId();
+  });
+
+  beforeEach(async () => {
+    await resetBillingCreditState(workspaceId);
+    await setupResourceCreditSubscription({
+      workspaceId,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+      creditAmountMicro: ALLOWANCE_MICRO,
+    });
+  });
+
+  afterEach(async () => {
+    await resetBillingCreditState(workspaceId);
+  });
+
+  afterAll(async () => {
+    await quitBillingFixtureRedis();
+  });
+
+  it('records a granted amount on the ledger and mirrors it', async () => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: 'Outage on the 3rd',
+    });
+
+    expect(response.body.errors).toBeUndefined();
+
+    const grants = await listCreditGrants(workspaceId);
+
+    expect(grants).toHaveLength(1);
+    expect(grants[0]).toMatchObject({
+      amountMicro: 2 * INTERNAL_CREDITS_PER_DISPLAY_CREDIT,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: 'Outage on the 3rd',
+      revokedAt: null,
+    });
+  });
+
+  it('leaves a granted amount without an expiry so no missed transition can drop it', async () => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+
+    expect(response.body.errors).toBeUndefined();
+    expect(response.body.data.grantWorkspaceCredits.expiresAt).toBeNull();
+
+    const grants = await listCreditGrants(workspaceId);
+
+    expect(grants[0].expiresAt).toBeNull();
+  });
+
+  // Rounded up to a period end rather than the exact day: credits are spent and
+  // settled a period at a time, so a deadline inside one would be invisible to
+  // both the cached counter and the carry-forward.
+  it('expires a time-boxed grant at the end of the period the requested day falls in', async () => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.SALES,
+      reason: 'Pilot credits',
+      expiresInDays: 30,
+    });
+
+    expect(response.body.errors).toBeUndefined();
+    expect(response.body.data.grantWorkspaceCredits.isActive).toBe(true);
+
+    const [storedGrant] = await listCreditGrants(workspaceId);
+
+    // Which period the thirtieth day lands in depends on when the suite runs,
+    // so the boundary is derived the same way the server derives it rather
+    // than listed.
+    const expectedExpiresAt = alignGrantExpiryToPeriodEnd({
+      requestedExpiresAt: addDays(new Date(), 30),
+      currentPeriodStart: PERIOD_START,
+      currentPeriodEnd: PERIOD_END,
+      interval: SubscriptionInterval.Month,
+    });
+
+    expect(storedGrant.expiresAt).toEqual(expectedExpiresAt);
+    expect(expectedExpiresAt.getTime()).toBeGreaterThanOrEqual(
+      addDays(new Date(), 30).getTime(),
+    );
+  });
+
+  it('refuses an expiry beyond the accepted range', async () => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+      expiresInDays: 100_000,
+    });
+
+    expect(response.body.errors).toBeDefined();
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  it('adds the granted amount to a warm available-credits counter', async () => {
+    const cache = getBillingUsageCacheService();
+
+    await cache.warmAvailableCredits(
+      workspaceId,
+      PERIOD_START,
+      PERIOD_END,
+      500_000,
+    );
+
+    await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+
+    expect(await cache.getAvailableCredits(workspaceId, PERIOD_START)).toBe(
+      500_000 + 2 * INTERNAL_CREDITS_PER_DISPLAY_CREDIT,
+    );
+  });
+
+  // The aligned deadline lands on the period end the counter already expires
+  // with, so the cached balance stays valid and can simply be incremented.
+  it('keeps a warm available-credits counter usable for a time-boxed grant', async () => {
+    const cache = getBillingUsageCacheService();
+
+    await cache.warmAvailableCredits(
+      workspaceId,
+      PERIOD_START,
+      PERIOD_END,
+      500_000,
+    );
+
+    await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.SALES,
+      reason: null,
+      expiresInDays: 1,
+    });
+
+    expect(await cache.getAvailableCredits(workspaceId, PERIOD_START)).toBe(
+      500_000 + 2 * INTERNAL_CREDITS_PER_DISPLAY_CREDIT,
+    );
+  });
+
+  it('takes a revoked grant back off the ledger and the available-credits counter', async () => {
+    const cache = getBillingUsageCacheService();
+
+    await cache.warmAvailableCredits(
+      workspaceId,
+      PERIOD_START,
+      PERIOD_END,
+      500_000,
+    );
+
+    const granted = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+    const creditGrantId = granted.body.data.grantWorkspaceCredits.id;
+
+    const revoked = await callAdminGraphql(REVOKE_MUTATION, {
+      workspaceId,
+      creditGrantId,
+    });
+
+    expect(revoked.body.errors).toBeUndefined();
+    expect(
+      revoked.body.data.revokeWorkspaceCreditGrant.revokedAt,
+    ).not.toBeNull();
+
+    const grants = await listCreditGrants(workspaceId);
+
+    expect(grants[0].revokedAt).not.toBeNull();
+    expect(await cache.getAvailableCredits(workspaceId, PERIOD_START)).toBe(
+      500_000,
+    );
+  });
+
+  it.each([
+    BillingCreditGrantType.ROLLOVER,
+    BillingCreditGrantType.ONBOARDING_REWARD,
+  ])('refuses to grant a %s by hand', async (type) => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 1,
+      type,
+      reason: null,
+    });
+
+    expect(response.body.errors?.[0]?.extensions?.subCode).toBe(
+      'BILLING_CREDIT_GRANT_TYPE_NOT_GRANTABLE',
+    );
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  it('drops the warm allowance counter when a grant lands', async () => {
+    await warmAllowanceCounter(workspaceId, PERIOD_START, 500_000);
+
+    await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+
+    expect(await readAllowanceCounter(workspaceId, PERIOD_START)).toBeNull();
+  });
+
+  it('takes a revoked grant off the ledger and drops the counter', async () => {
+    const granted = await grantCredits({
+      workspaceId,
+      amount: 2,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+    const creditGrantId = granted.body.data.grantWorkspaceCredits.id;
+
+    await warmAllowanceCounter(workspaceId, PERIOD_START, 500_000);
+
+    const revoked = await callAdminGraphql(REVOKE_MUTATION, {
+      workspaceId,
+      creditGrantId,
+    });
+
+    expect(revoked.body.errors).toBeUndefined();
+    expect(
+      revoked.body.data.revokeWorkspaceCreditGrant.revokedAt,
+    ).not.toBeNull();
+
+    const grants = await listCreditGrants(workspaceId);
+
+    expect(grants[0].revokedAt).not.toBeNull();
+    expect(await readAllowanceCounter(workspaceId, PERIOD_START)).toBeNull();
+  });
+
+  // The panel only offers the three operator types, but the mutation is
+  // reachable directly and these two are written by the period transition and
+  // the onboarding jobs.
+  it.each([
+    BillingCreditGrantType.ROLLOVER,
+    BillingCreditGrantType.ONBOARDING_REWARD,
+  ])('refuses to grant a %s by hand', async (type) => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 1,
+      type,
+      reason: null,
+    });
+
+    expect(response.body.errors?.[0]?.extensions?.subCode).toBe(
+      'BILLING_CREDIT_GRANT_TYPE_NOT_GRANTABLE',
+    );
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  it('refuses an amount above the configured ceiling', async () => {
+    const response = await grantCredits({
+      workspaceId,
+      amount: 1_000_000_000,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: null,
+    });
+
+    expect(response.body.errors?.[0]?.extensions?.subCode).toBe(
+      'BILLING_CREDIT_AMOUNT_INVALID',
+    );
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  // The admin panel keeps one operation id per open modal, so an Apollo retry
+  // or a resubmit after a lost response must answer with the grant the first
+  // attempt wrote rather than crediting the workspace a second time.
+  it('answers a retried grant with the original instead of granting twice', async () => {
+    const clientOperationId = randomUUID();
+    const variables = {
+      workspaceId,
+      amount: 25,
+      type: BillingCreditGrantType.COMPENSATION,
+      reason: 'Retried by the client',
+      clientOperationId,
+    };
+
+    const first = await callAdminGraphql(GRANT_MUTATION, variables);
+    const second = await callAdminGraphql(GRANT_MUTATION, variables);
+
+    expect(second.body.data.grantWorkspaceCredits.id).toBe(
+      first.body.data.grantWorkspaceCredits.id,
+    );
+    expect(await listCreditGrants(workspaceId)).toHaveLength(1);
+  });
+
+  // The refusal to time-box a grant with no billing period must not reach a
+  // replay: the subscription that anchored the original deadline can be gone by
+  // the time the client retries, and the operation already succeeded.
+  it('answers a retried time-boxed grant after the subscription is canceled', async () => {
+    const clientOperationId = randomUUID();
+    const variables = {
+      workspaceId,
+      amount: 25,
+      type: BillingCreditGrantType.SALES,
+      reason: 'Retried after cancellation',
+      clientOperationId,
+      expiresInDays: 30,
+    };
+
+    const first = await callAdminGraphql(GRANT_MUTATION, variables);
+
+    expect(first.body.errors).toBeUndefined();
+
+    await setSubscriptionStatus(workspaceId, SubscriptionStatus.Canceled);
+
+    const second = await callAdminGraphql(GRANT_MUTATION, variables);
+
+    expect(second.body.errors).toBeUndefined();
+    expect(second.body.data.grantWorkspaceCredits.id).toBe(
+      first.body.data.grantWorkspaceCredits.id,
+    );
+    expect(await listCreditGrants(workspaceId)).toHaveLength(1);
+  });
+});

packages/twenty-server/test/integration/billing/suites/billing-credit-rollover.integration-spec.ts

@@ -0,0 +1,343 @@
+import { addMonths, startOfMonth, subMonths } from 'date-fns';
+import request from 'supertest';
+import { createMockStripeInvoiceFinalizedData } from 'test/integration/billing/utils/create-mock-stripe-invoice-finalized-data.util';
+import {
+  getBillingUsageCacheService,
+  getSeededBillingWorkspaceId,
+  insertCreditGrant,
+  listCreditGrants,
+  quitBillingFixtureRedis,
+  readAllowanceCounter,
+  resetBillingCreditState,
+  setupResourceCreditSubscription,
+  TEST_STRIPE_CUSTOMER_ID,
+  warmAllowanceCounter,
+} from 'test/integration/billing/utils/billing-credit-fixtures.util';
+import { getAppProviderByClassName } from 'test/integration/utils/get-app-provider-by-class-name.util';
+
+import { BillingCreditGrantType } from 'src/engine/core-modules/billing/enums/billing-credit-grant-type.enum';
+import { type BillingUsageService } from 'src/engine/core-modules/billing/services/billing-usage.service';
+
+const client = request(`http://localhost:${APP_PORT}`);
+
+// Whole calendar months, anchored so the period the transition opens is the
+// one running right now. The ledger filters on now(), so periods fixed in the
+// past would read as expired and assert nothing.
+const PERIOD_BOUNDARY = startOfMonth(new Date());
+const CLOSING_PERIOD_START = subMonths(PERIOD_BOUNDARY, 1);
+const CLOSING_PERIOD_END = PERIOD_BOUNDARY;
+const NEXT_PERIOD_END = addMonths(PERIOD_BOUNDARY, 1);
+
+const ALLOWANCE_MICRO = 1_000_000;
+
+const postInvoiceFinalized = (
+  invoiceId = 'in_test_default',
+  { periodStart = CLOSING_PERIOD_END, periodEnd = NEXT_PERIOD_END } = {},
+) =>
+  client
+    .post('/webhooks/stripe')
+    .set('stripe-signature', 'correct-signature')
+    .set('Content-Type', 'application/json')
+    .send(
+      JSON.stringify({
+        type: 'invoice.finalized',
+        data: createMockStripeInvoiceFinalizedData({
+          periodStart,
+          periodEnd,
+          stripeCustomerId: TEST_STRIPE_CUSTOMER_ID,
+          invoiceId,
+        }),
+      }),
+    );
+
+describe('Billing credit rollover (integration)', () => {
+  let workspaceId: string;
+  let billingUsageService: BillingUsageService;
+  let usageSpy: jest.SpyInstance;
+
+  beforeAll(async () => {
+    workspaceId = await getSeededBillingWorkspaceId();
+    billingUsageService = getAppProviderByClassName<BillingUsageService>(
+      'BillingUsageService',
+    );
+  });
+
+  beforeEach(async () => {
+    await resetBillingCreditState(workspaceId);
+    await setupResourceCreditSubscription({
+      workspaceId,
+      periodStart: CLOSING_PERIOD_START,
+      periodEnd: CLOSING_PERIOD_END,
+      creditAmountMicro: ALLOWANCE_MICRO,
+    });
+
+    // Usage is read from ClickHouse, whose inserts are asynchronous. Stubbing
+    // the read keeps every expectation exact instead of racing ingestion; the
+    // query itself has its own unit coverage.
+    usageSpy = jest.spyOn(billingUsageService, 'getCreditsUsedBetweenOrNull');
+  });
+
+  afterEach(async () => {
+    usageSpy?.mockRestore();
+    await resetBillingCreditState(workspaceId);
+  });
+
+  afterAll(async () => {
+    await quitBillingFixtureRedis();
+  });
+
+  it('carries the unspent allowance into the next period', async () => {
+    usageSpy.mockResolvedValue(300_000);
+
+    await postInvoiceFinalized().expect(200);
+
+    const grants = await listCreditGrants(workspaceId);
+
+    expect(grants).toHaveLength(1);
+    expect(grants[0]).toMatchObject({
+      amountMicro: 700_000,
+      type: BillingCreditGrantType.ROLLOVER,
+      revokedAt: null,
+    });
+    expect(new Date(grants[0].effectiveAt)).toEqual(CLOSING_PERIOD_END);
+    // Successors carry no deadline: stamping the next period end would put the
+    // balance back at the mercy of the transition after this one running.
+    expect(grants[0].expiresAt).toBeNull();
+  });
+
+  it('reads usage over the closing period, not the one just opened', async () => {
+    usageSpy.mockResolvedValue(0);
+
+    await postInvoiceFinalized().expect(200);
+
+    expect(usageSpy).toHaveBeenCalledWith({
+      workspaceId,
+      from: CLOSING_PERIOD_START,
+      to: CLOSING_PERIOD_END,
+    });
+  });
+
+  it('carries nothing when the whole allowance was spent', async () => {
+    usageSpy.mockResolvedValue(ALLOWANCE_MICRO);
+
+    await postInvoiceFinalized().expect(200);
+
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  it('closes the grants it carried forward so they cannot be counted twice', async () => {
+    usageSpy.mockResolvedValue(0);
+    await insertCreditGrant({
+      workspaceId,
+      amountMicro: 500_000,
+      type: BillingCreditGrantType.COMPENSATION,
+      effectiveAt: CLOSING_PERIOD_START,
+      expiresAt: NEXT_PERIOD_END,
+    });
+
+    await postInvoiceFinalized().expect(200);
+
+    const grants = await listCreditGrants(workspaceId);
+    const compensation = grants.find(
+      (grant) =>
+        grant.type === BillingCreditGrantType.COMPENSATION &&
+        grant.sourceGrantId === null,
+    );
+
+    expect(compensation).toBeDefined();
+
+    // Its expiry was pulled back to the boundary, so the balance counts it
+    // once through its carried-forward copy rather than twice.
+    expect(compensation?.expiresAt).toEqual(CLOSING_PERIOD_END);
+    expect(
+      grants.some(
+        (grant) =>
+          grant.type === BillingCreditGrantType.COMPENSATION &&
+          grant.sourceGrantId === compensation!.id,
+      ),
+    ).toBe(true);
+  });
+
+  it('caps the carried rollover at the configured multiple of the allowance', async () => {
+    usageSpy.mockResolvedValue(0);
+    await insertCreditGrant({
+      workspaceId,
+      amountMicro: ALLOWANCE_MICRO,
+      type: BillingCreditGrantType.ROLLOVER,
+      effectiveAt: CLOSING_PERIOD_START,
+      expiresAt: CLOSING_PERIOD_END,
+    });
+
+    await postInvoiceFinalized().expect(200);
+
+    const carried = (await listCreditGrants(workspaceId)).filter(
+      (grant) => grant.sourceGrantId !== null || grant.idempotencyKey !== null,
+    );
+    const carriedRollover = carried.filter(
+      (grant) => grant.type === BillingCreditGrantType.ROLLOVER,
+    );
+
+    // allowance + expiring rollover = 2M unspent, clamped to (2 - 1) x 1M.
+    expect(
+      carriedRollover.reduce((total, grant) => total + grant.amountMicro, 0),
+    ).toBe(ALLOWANCE_MICRO);
+  });
+
+  // A redelivery must not hand out the credits a second time.
+  it('is idempotent when Stripe redelivers the same invoice', async () => {
+    usageSpy.mockResolvedValue(300_000);
+
+    await postInvoiceFinalized().expect(200);
+    const afterFirst = await listCreditGrants(workspaceId);
+
+    await postInvoiceFinalized().expect(200);
+    const afterSecond = await listCreditGrants(workspaceId);
+
+    expect(afterSecond).toHaveLength(afterFirst.length);
+    expect(
+      afterSecond.reduce((total, grant) => total + grant.amountMicro, 0),
+    ).toBe(afterFirst.reduce((total, grant) => total + grant.amountMicro, 0));
+  });
+
+  // Returning normally would answer 200 and Stripe would never redeliver, so
+  // the transition would be lost and the balance would expire unrolled.
+  it('fails the webhook when usage cannot be read so Stripe redelivers', async () => {
+    usageSpy.mockResolvedValue(null);
+
+    await postInvoiceFinalized().expect(500);
+
+    expect(await listCreditGrants(workspaceId)).toHaveLength(0);
+  });
+
+  it('adds the carried balance to a warm available-credits counter', async () => {
+    usageSpy.mockResolvedValue(300_000);
+    const cache = getBillingUsageCacheService();
+
+    await cache.warmAvailableCredits(
+      workspaceId,
+      CLOSING_PERIOD_START,
+      NEXT_PERIOD_END,
+      120_000,
+    );
+
+    await postInvoiceFinalized().expect(200);
+
+    expect(
+      await cache.getAvailableCredits(workspaceId, CLOSING_PERIOD_START),
+    ).toBe(120_000 + 700_000);
+  });
+
+  it('leaves a warm available-credits counter alone when a successful delivery is repeated', async () => {
+    usageSpy.mockResolvedValue(300_000);
+    const cache = getBillingUsageCacheService();
+
+    await cache.warmAvailableCredits(
+      workspaceId,
+      CLOSING_PERIOD_START,
+      NEXT_PERIOD_END,
+      120_000,
+    );
+
+    await postInvoiceFinalized().expect(200);
+    const afterFirst = await cache.getAvailableCredits(
+      workspaceId,
+      CLOSING_PERIOD_START,
+    );
+
+    await postInvoiceFinalized().expect(200);
+
+    expect(afterFirst).toBe(120_000 + 700_000);
+    expect(
+      await cache.getAvailableCredits(workspaceId, CLOSING_PERIOD_START),
+    ).toBe(afterFirst);
+  });
+
+  it('drops the allowance counter on the period transition', async () => {
+    usageSpy.mockResolvedValue(300_000);
+
+    // The counter is keyed by the period the subscription is currently in,
+    // which is the one the invoice is closing: Stripe moves the subscription
+    // forward in a separate event.
+    await warmAllowanceCounter(workspaceId, CLOSING_PERIOD_START, 120_000);
+
+    await postInvoiceFinalized().expect(200);
+
+    expect(
+      await readAllowanceCounter(workspaceId, CLOSING_PERIOD_START),
+    ).toBeNull();
+  });
+
+  // A subscription anchored on the 31st runs January 31 to February 28. Once
+  // the subscription.updated webhook has moved the subscription on, calendar
+  // arithmetic clamps February 28 back to January 28 and the closing period
+  // swallows three days of the period before it.
+  describe('a month-end anchor whose subscription already advanced', () => {
+    const MONTH_END_BOUNDARY = new Date('2026-02-28T00:00:00.000Z');
+    const TRUE_CLOSING_PERIOD_START = new Date('2026-01-31T00:00:00.000Z');
+    const MONTH_END_NEXT_PERIOD_END = new Date('2026-03-31T00:00:00.000Z');
+
+    it('reads the closing period start off the ledger rather than the calendar', async () => {
+      usageSpy.mockResolvedValue(0);
+      await setupResourceCreditSubscription({
+        workspaceId,
+        periodStart: MONTH_END_BOUNDARY,
+        periodEnd: MONTH_END_NEXT_PERIOD_END,
+        creditAmountMicro: ALLOWANCE_MICRO,
+      });
+      // What the previous transition left behind: a grant closed at the instant
+      // the period it belonged to ended.
+      await insertCreditGrant({
+        workspaceId,
+        amountMicro: 100_000,
+        type: BillingCreditGrantType.ROLLOVER,
+        effectiveAt: new Date('2025-12-31T00:00:00.000Z'),
+        expiresAt: TRUE_CLOSING_PERIOD_START,
+      });
+
+      await postInvoiceFinalized('in_test_month_end', {
+        periodStart: MONTH_END_BOUNDARY,
+        periodEnd: MONTH_END_NEXT_PERIOD_END,
+      }).expect(200);
+
+      expect(usageSpy).toHaveBeenCalledWith({
+        workspaceId,
+        from: TRUE_CLOSING_PERIOD_START,
+        to: MONTH_END_BOUNDARY,
+      });
+    });
+  });
+
+  describe('closing a trial', () => {
+    it('carries credits earned during the trial into the first paid period', async () => {
+      usageSpy.mockResolvedValue(0);
+      await setupResourceCreditSubscription({
+        workspaceId,
+        periodStart: CLOSING_PERIOD_START,
+        periodEnd: CLOSING_PERIOD_END,
+        creditAmountMicro: ALLOWANCE_MICRO,
+        status: 'trialing',
+        trialStart: CLOSING_PERIOD_START,
+        trialEnd: CLOSING_PERIOD_END,
+      });
+      await insertCreditGrant({
+        workspaceId,
+        amountMicro: 250_000,
+        type: BillingCreditGrantType.ONBOARDING_REWARD,
+        effectiveAt: CLOSING_PERIOD_START,
+        expiresAt: null,
+      });
+
+      await postInvoiceFinalized('in_test_trial').expect(200);
+
+      const reward = (await listCreditGrants(workspaceId)).find(
+        (grant) =>
+          grant.type === BillingCreditGrantType.ONBOARDING_REWARD &&
+          grant.sourceGrantId !== null,
+      );
+
+      expect(reward).toBeDefined();
+      expect(reward?.amountMicro).toBe(250_000);
+      expect(reward?.expiresAt).toBeNull();
+    });
+  });
+});