@cosmicdrift/kumiko-samples 0.370.0 → 0.371.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.370.0",
+  "version": "0.371.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.370.0",
+  "version": "0.371.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>",

package/packages/bundled-features/src/auth-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.371.0",
+    "type": "improvement",
+    "title": "Boot warning when anonymous routes run without anonymousAccess",
+    "detail": "A boot warning names anonymousAccess when host-routing, managed-pages or legal-pages is mounted without it; anonymous requests get no tenant until the option is set."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-foundation/resolve-anonymous-access.ts

@@ -11,9 +11,15 @@ import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { resolveTenantExistence, resolveTenantResolver } from "./feature.ts";
 import type { AuthProviderBuildDeps } from "./types.ts";
 
+// Features whose routes are anonymous and need an `anonymousAccess` entry to resolve a tenant.
+const ANONYMOUS_ROUTE_FEATURES = ["host-routing", "managed-pages", "legal-pages"] as const;
+
 export async function resolveAnonymousAccessFromRegistry(
   base: AnonymousAccessResolved | AnonymousAccessConfig | undefined,
-  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+  deps: AuthProviderBuildDeps & {
+    readonly registry: Registry;
+    readonly warn?: (message: string) => void;
+  },
 ): Promise<AnonymousAccessResolved | undefined> {
   const [tenantResolver, tenantExists] = await Promise.all([
     resolveTenantResolver(deps),
@@ -25,7 +31,16 @@ export async function resolveAnonymousAccessFromRegistry(
   // anonymousAccess become defined for an app that never set it — that
   // would upgrade every roles:["anonymous"] handler to reachable without
   // a JWT the moment such a routing feature is mounted (#1452).
-  if (!base) return undefined;
+  if (!base) {
+    const needing = ANONYMOUS_ROUTE_FEATURES.filter((name) => deps.registry.getFeature(name));
+    if (needing.length > 0) {
+      deps.warn?.(
+        `[auth-foundation] ${needing.join(", ")} mount${needing.length === 1 ? "s" : ""} anonymous routes but anonymousAccess is not set, ` +
+          "so anonymous requests get no tenant. Add `anonymousAccess: {}` to opt in.",
+      );
+    }
+    return undefined;
+  }
 
   // Fail-closed (#1374 security): inline tenantResolver without trust is the
   // old ambiguous config — providers always carry trust; test stacks must too.

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.371.0",
+    "type": "improvement",
+    "title": "Billing webhook sync exposes afterSync",
+    "detail": "The billing webhook sync calls afterSync({ tenantId, tier, changed, event }) after every webhook, with changed false when the tier stayed the same."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/billing-foundation/index.ts

@@ -79,6 +79,7 @@ export {
   effectiveTierFromSubscription,
   SUBSCRIPTION_WEBHOOK_PATH,
   type SubscriptionTierSyncDeps,
+  type TierSyncResult,
 } from "./subscription-tier-sync.ts";
 export {
   type BillingFoundationOptions,

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -19,6 +19,7 @@ import type { TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { subscriptionAggregateId } from "./aggregate-id.ts";
 import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.ts";
+import type { PaymentEvent, SubscriptionEvent } from "./types.ts";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.ts";
 
 // Outside /api — signature routes carry their own auth (verify()) and are
@@ -38,8 +39,30 @@ export type SubscriptionTierSyncDeps<TTier extends string> = {
   // 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";
+  /** Runs after every webhook whose sync succeeded, also when the tier stayed the same
+   *  (`changed: false`). Not called when the tenant has no subscription yet, when a
+   *  manual grant was kept, or when the sync failed. A throw counts as a sync failure
+   *  and follows `onSyncError`. */
+  readonly afterSync?: (result: TierSyncResult<TTier>) => Promise<void>;
 };
 
+export type TierSyncResult<TTier extends string> = {
+  readonly tenantId: TenantId;
+  /** The tier the subscription yields. */
+  readonly tier: TTier;
+  /** True when this sync created or updated the tenant's tier assignment. */
+  readonly changed: boolean;
+  readonly event: SubscriptionEvent | PaymentEvent;
+};
+
+type SyncError = { code: string; message: string };
+type SyncOutcome<TTier extends string> =
+  | { readonly error: SyncError }
+  | {
+      readonly error: null;
+      readonly applied?: { readonly tier: TTier; readonly changed: boolean };
+    };
+
 // A manual grant that differs from what billing would assign is reported with this
 // code but never fails the webhook: a provider retry cannot resolve it.
 export const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
@@ -92,10 +115,10 @@ function findTierAssignment(
 export function createSubscriptionTierSync<TTier extends string>(
   deps: SubscriptionTierSyncDeps<TTier>,
 ) {
-  async function syncTierFromSubscription(
+  async function runTierSync(
     tenantId: TenantId,
     routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">,
-  ): Promise<{ code: string; message: string } | null> {
+  ): Promise<SyncOutcome<TTier>> {
     try {
       const subscriptionId = subscriptionAggregateId(tenantId);
       const subscriptionRows = asRows(
@@ -106,7 +129,7 @@ export function createSubscriptionTierSync<TTier extends string>(
         }),
       );
       const sub = subscriptionRows.find((row) => row["id"] === subscriptionId);
-      if (!sub) return null;
+      if (!sub) return { error: null };
 
       const effective = effectiveTierFromSubscription(
         typeof sub["status"] === "string" ? sub["status"] : undefined,
@@ -135,17 +158,23 @@ export function createSubscriptionTierSync<TTier extends string>(
         });
         if (!created.isSuccess) {
           return {
-            code: "tier_sync_failed",
-            message: `tier-engine create with "${effective}" failed: ${created.error?.code ?? "unknown"}`,
+            error: {
+              code: "tier_sync_failed",
+              message: `tier-engine create with "${effective}" failed: ${created.error?.code ?? "unknown"}`,
+            },
           };
         }
-        return null;
+        return { error: null, applied: { tier: effective, changed: true } };
+      }
+      if (assignment.tier === effective) {
+        return { error: null, applied: { tier: effective, changed: false } };
       }
-      if (assignment.tier === effective) return null;
       if (assignment.source === TierAssignmentSources.manual) {
         return {
-          code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
-          message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+          error: {
+            code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
+            message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+          },
         };
       }
 
@@ -160,11 +189,13 @@ export function createSubscriptionTierSync<TTier extends string>(
       });
       if (!result.isSuccess) {
         return {
-          code: "tier_sync_failed",
-          message: `tier-engine update to "${effective}" failed: ${result.error?.code ?? "unknown"}`,
+          error: {
+            code: "tier_sync_failed",
+            message: `tier-engine update to "${effective}" failed: ${result.error?.code ?? "unknown"}`,
+          },
         };
       }
-      return null;
+      return { error: null, applied: { tier: effective, changed: true } };
     } catch (error) {
       // dispatchSystemQuery throws (AccessDenied/NotFound/Validation) rather
       // than returning an error envelope — e.g. a consumer that mounts
@@ -172,8 +203,37 @@ export function createSubscriptionTierSync<TTier extends string>(
       // a failed dispatchSystemWrite instead of letting it bubble into the
       // webhook response as an unhandled 500.
       return {
-        code: "tier_sync_failed",
-        message: error instanceof Error ? error.message : "tier sync threw a non-Error value",
+        error: {
+          code: "tier_sync_failed",
+          message: error instanceof Error ? error.message : "tier sync threw a non-Error value",
+        },
+      };
+    }
+  }
+
+  async function syncTierFromSubscription(
+    tenantId: TenantId,
+    routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">,
+  ): Promise<SyncError | null> {
+    return (await runTierSync(tenantId, routeDeps)).error;
+  }
+
+  async function syncAndNotify(
+    tenantId: TenantId,
+    event: SubscriptionEvent | PaymentEvent,
+    routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">,
+  ): Promise<SyncError | null> {
+    const outcome = await runTierSync(tenantId, routeDeps);
+    if (outcome.error !== null || outcome.applied === undefined || !deps.afterSync) {
+      return outcome.error;
+    }
+    try {
+      await deps.afterSync({ tenantId, event, ...outcome.applied });
+      return null;
+    } catch (error) {
+      return {
+        code: "tier_sync_after_hook_failed",
+        message: error instanceof Error ? error.message : "afterSync threw a non-Error value",
       };
     }
   }
@@ -182,8 +242,13 @@ export function createSubscriptionTierSync<TTier extends string>(
   function createWebhookRoute(options: { readonly path?: string } = {}): ExtraRouteDefinition {
     return createSubscriptionWebhookRoute({
       path: options.path ?? SUBSCRIPTION_WEBHOOK_PATH,
-      afterDispatch: async (dispatched: WriteResult, tenantId, routeDeps): Promise<WriteResult> => {
-        const syncError = await syncTierFromSubscription(tenantId, routeDeps);
+      afterDispatch: async (
+        dispatched: WriteResult,
+        tenantId,
+        routeDeps,
+        event,
+      ): Promise<WriteResult> => {
+        const syncError = await syncAndNotify(tenantId, event, routeDeps);
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
@@ -209,5 +274,5 @@ export function createSubscriptionTierSync<TTier extends string>(
     });
   }
 
-  return { createWebhookRoute, syncTierFromSubscription };
+  return { createWebhookRoute, syncTierFromSubscription, syncAndNotify };
 }

package/packages/bundled-features/src/billing-foundation/webhook-handler.ts

@@ -27,6 +27,7 @@ export type SubscriptionWebhookRouteOptions = {
     dispatched: import("@cosmicdrift/kumiko-framework/engine").WriteResult,
     tenantId: import("@cosmicdrift/kumiko-framework/engine").TenantId,
     deps: import("@cosmicdrift/kumiko-framework/api").SignatureExtraRouteDeps,
+    event: SubscriptionEvent | PaymentEvent,
   ) => Promise<import("@cosmicdrift/kumiko-framework/engine").WriteResult>;
 };
 
@@ -113,7 +114,7 @@ export function createSubscriptionWebhookRoute(options: SubscriptionWebhookRoute
         return respondFromDispatch(
           c,
           dispatched.isSuccess && options.afterDispatch
-            ? await options.afterDispatch(dispatched, tenantId, deps)
+            ? await options.afterDispatch(dispatched, tenantId, deps, parsed)
             : dispatched,
           "subscription_payment_webhook_processing_failed",
           "Internal error processing payment event",
@@ -138,7 +139,7 @@ export function createSubscriptionWebhookRoute(options: SubscriptionWebhookRoute
       return respondFromDispatch(
         c,
         dispatched.isSuccess && options.afterDispatch
-          ? await options.afterDispatch(dispatched, tenantId, deps)
+          ? await options.afterDispatch(dispatched, tenantId, deps, parsed)
           : dispatched,
         "subscription_webhook_processing_failed",
         "Internal error processing subscription event",

package/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.371.0",
+    "type": "improvement",
+    "title": "Unsubscribe endpoint answers form posts with an HTML page",
+    "detail": "POST on the delivery unsubscribe route returns an HTML confirmation page for a form post and JSON for a bare POST. The behavior is unchanged; this only documents it.",
+    "migration": "Clients that post the unsubscribe form expect HTML, API clients that post without a form content type expect JSON. No code change is needed."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

package/packages/bundled-features/src/file-provider-s3/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.371.0",
+    "type": "improvement",
+    "title": "S3 endpoint over http outside production",
+    "detail": "s3EndpointSchema rejects http on non-loopback hosts only when NODE_ENV=production, so compose hostnames such as minio work in smoke setups."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

package/packages/bundled-features/src/file-provider-s3/env-schema.ts

@@ -2,18 +2,20 @@ import * as z from "zod";
 
 const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
-// The bucket holds tenant files, so a remote endpoint must be https; plain
-// http stays allowed for a loopback MinIO in dev and CI.
-function isHttpsOrLoopbackHttp(value: string): boolean {
+// The bucket holds tenant files, so in production a remote endpoint must be
+// https. Outside production plain http stays allowed, also for compose-network
+// hostnames (minio, rustfs) that are not loopback.
+function isAcceptableEndpoint(value: string): boolean {
   if (!URL.canParse(value)) return false;
   const url = new URL(value);
-  return url.protocol === "https:" || LOOPBACK_HOSTNAMES.has(url.hostname);
+  if (url.protocol === "https:") return true;
+  return process.env["NODE_ENV"] !== "production" || LOOPBACK_HOSTNAMES.has(url.hostname);
 }
 
-/** S3-compatible endpoint URL: https, or http on a loopback host. */
+/** S3-compatible endpoint URL: https, or http on a loopback host; any http host outside `NODE_ENV=production`. */
 export const s3EndpointSchema = z
   .url({ protocol: /^https?$/ })
-  .refine(isHttpsOrLoopbackHttp, "must use https unless the host is loopback");
+  .refine(isAcceptableEndpoint, "must use https unless the host is loopback");
 
 /** Builds the env block `createS3ProviderFromEnv(prefix)` reads, e.g.
  *  `createS3EnvSchema({ prefix: "RELEASES_S3_" })` for a second bucket.