@cosmicdrift/kumiko-bundled-features 0.287.0 → 0.288.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.287.0",
+  "version": "0.288.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -132,12 +132,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.287.0",
-    "@cosmicdrift/kumiko-framework": "0.287.0",
-    "@cosmicdrift/kumiko-headless": "0.287.0",
-    "@cosmicdrift/kumiko-renderer": "0.287.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.287.0",
-    "@cosmicdrift/kumiko-types": "0.287.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.288.0",
+    "@cosmicdrift/kumiko-framework": "0.288.0",
+    "@cosmicdrift/kumiko-headless": "0.288.0",
+    "@cosmicdrift/kumiko-renderer": "0.288.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.288.0",
+    "@cosmicdrift/kumiko-types": "0.288.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -166,8 +166,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.287.0",
-    "@cosmicdrift/kumiko-locale-es": "0.287.0",
+    "@cosmicdrift/kumiko-locale-de": "0.288.0",
+    "@cosmicdrift/kumiko-locale-es": "0.288.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/billing-foundation/__tests__/subscription-tier-sync.integration.test.ts

@@ -0,0 +1,186 @@
+// Integration test for createSubscriptionTierSync()'s onSyncError option
+// (#3027). Forces a sync failure via a dispatchSystemWrite stub that fails
+// only the tier-engine handlers (the primary billing-foundation writes run
+// for real against the test DB) — proving that "log" (default) still
+// answers the webhook successfully, while "fail-webhook" surfaces the sync
+// error all the way into the HTTP response.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { buildEntityTable, type EntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  type EntityDefinition,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { Hono } from "hono";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import type { TierMap } from "../../tier-engine/compose-app";
+import { TierEngineHandlers } from "../../tier-engine/constants";
+import { tierAssignmentEntity } from "../../tier-engine/entity";
+import { createTierEngineFeature } from "../../tier-engine/feature";
+import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
+import { billingFoundationFeature } from "../feature";
+import {
+  createSubscriptionTierSync,
+  SUBSCRIPTION_WEBHOOK_PATH,
+  type SystemWriteResult,
+} from "../subscription-tier-sync";
+import type { SubscriptionEvent, SubscriptionProviderPlugin } from "../types";
+
+type TestTier = "free" | "pro";
+const isTierName = (v: string): v is TestTier => v === "free" || v === "pro";
+const TEST_TIER_MAP: TierMap<{ readonly maxItems: number }> = {
+  free: { features: [], caps: { maxItems: 1 } },
+  pro: { features: [], caps: { maxItems: 100 } },
+};
+
+const mockProviderFeature = defineFeature("test-mock-tier-sync-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = {
+    verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent,
+  };
+  r.useExtension("subscriptionProvider", "mock", plugin);
+});
+
+// Boundary-cast: SubscriptionTierSyncDeps deliberately erases the entity's
+// concrete field types to EntityDefinition (generic factory), which TS
+// can't structurally widen to on its own.
+const tierAssignmentTable = buildEntityTable(
+  "tier-assignment",
+  tierAssignmentEntity,
+) as unknown as EntityTable<EntityDefinition>;
+
+let stack: TestStack;
+let forceTierSyncFailure = false;
+
+async function dispatchSystemWrite(args: {
+  readonly handlerQn: string;
+  readonly payload: unknown;
+  readonly tenantId: TenantId;
+}): Promise<SystemWriteResult> {
+  if (
+    forceTierSyncFailure &&
+    (args.handlerQn === TierEngineHandlers.create || args.handlerQn === TierEngineHandlers.update)
+  ) {
+    return {
+      isSuccess: false,
+      error: { code: "test_forced_failure", message: "forced tier-sync failure" },
+    };
+  }
+  const systemUser = createTestUser({ id: 1, tenantId: args.tenantId, roles: ["SystemAdmin"] });
+  const res = await stack.http.write(args.handlerQn, args.payload, systemUser);
+  const body = (await res.json()) as {
+    isSuccess: boolean;
+    data?: unknown;
+    error?: { readonly code?: string; readonly message?: string };
+  };
+  return body.isSuccess
+    ? { isSuccess: true, data: body.data }
+    : { isSuccess: false, error: body.error };
+}
+
+let logApp: Hono;
+let failApp: Hono;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP }),
+      mockProviderFeature,
+    ],
+  });
+  await createEventsTable(stack.db);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await unsafePushTables(stack.db, { tier_assignments: tierAssignmentTable });
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+  const sharedDeps = {
+    db: stack.db,
+    registry: stack.registry,
+    dispatchSystemWrite,
+    tierAssignmentTable,
+    isTierName,
+    defaultTier: "free" as const,
+  };
+
+  logApp = new Hono();
+  createSubscriptionTierSync<TestTier>(sharedDeps).wireSubscriptionWebhookRoute(logApp);
+
+  failApp = new Hono();
+  createSubscriptionTierSync<TestTier>({
+    ...sharedDeps,
+    onSyncError: "fail-webhook",
+  }).wireSubscriptionWebhookRoute(failApp);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+});
+
+const webhookPath = SUBSCRIPTION_WEBHOOK_PATH.replace(":providerName", "mock");
+
+function buildEvent(tenantId: string, providerEventId: string): SubscriptionEvent {
+  return {
+    providerEventId,
+    providerName: "mock",
+    type: SubscriptionEventTypes.created,
+    tenantId,
+    providerCustomerId: `cus_${providerEventId}`,
+    providerSubscriptionId: `sub_${providerEventId}`,
+    status: SubscriptionStatuses.active,
+    tier: "pro",
+    currentPeriodEnd: "2026-06-01T00:00:00Z",
+    rawPayload: "{}",
+  };
+}
+
+describe("createSubscriptionTierSync onSyncError", () => {
+  test("default ('log'): a tier-sync failure still returns a successful webhook response", async () => {
+    forceTierSyncFailure = true;
+    const tenantId = testTenantId(9001);
+    const res = await logApp.request(webhookPath, {
+      method: "POST",
+      body: JSON.stringify(buildEvent(tenantId, "evt_log_1")),
+    });
+    forceTierSyncFailure = false;
+
+    expect(res.status).toBe(200);
+  });
+
+  test("'fail-webhook': a tier-sync failure also fails the webhook response", async () => {
+    forceTierSyncFailure = true;
+    const tenantId = testTenantId(9002);
+    const res = await failApp.request(webhookPath, {
+      method: "POST",
+      body: JSON.stringify(buildEvent(tenantId, "evt_fail_1")),
+    });
+    forceTierSyncFailure = false;
+
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("subscription_webhook_processing_failed");
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.288.0",
+    "type": "improvement",
+    "title": "add onSyncError option to createSubscriptionTierSync",
+    "detail": "`SubscriptionTierSyncDeps<TTier>` gets an optional `onSyncError?: \"log\" | \"fail-webhook\"`\n(default `\"log\"`, matching prior behavior exactly). `\"fail-webhook\"` makes a tier-sync\nfailure also fail the webhook response, so an idempotent-retry caller (whose retry\nno-ops the already-committed primary write) gets another attempt at the sync step."
+  },
   {
     "version": "0.286.0",
     "type": "improvement",

package/src/billing-foundation/subscription-tier-sync.ts

@@ -35,6 +35,12 @@ export type SubscriptionTierSyncDeps<TTier extends string> = {
   readonly tierAssignmentTable: EntityTable<EntityDefinition>;
   readonly isTierName: (value: string) => value is TTier;
   readonly defaultTier: TTier;
+  // "log" (default): sync failure only warns, the webhook still reports
+  // success — right when the caller has no idempotent retry to lean on.
+  // "fail-webhook": sync failure fails the webhook response too, so an
+  // idempotent caller (e.g. Stripe, whose retry re-runs the already-committed
+  // primary write as a no-op) gets a second attempt at the sync step itself.
+  readonly onSyncError?: "log" | "fail-webhook";
 };
 
 export function effectiveTierFromSubscription<TTier extends string>(
@@ -116,16 +122,15 @@ export function createSubscriptionTierSync<TTier extends string>(
           tenantId: targetTenantId,
         });
         if (!result.isSuccess) return result;
-        // The primary write already committed — a webhook caller (Stripe/
-        // PayPal) that sees isSuccess:false here retries the whole event,
-        // re-running an already-succeeded side effect. Log the tier-sync
-        // failure instead of masking the primary write's success.
         const syncError = await syncTierFromSubscription(targetTenantId);
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
             `[subscription-tier-sync] tier sync failed for tenant ${targetTenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
           );
+          if (deps.onSyncError === "fail-webhook") {
+            return { isSuccess: false, error: syncError };
+          }
         }
         return result;
       },