@odla-ai/chapter 0.44.0 → 0.45.0

package/README.md

@@ -859,6 +859,47 @@ and relations by composing its own config before passing it to Chapter.
 Formation is off unless configured. Chapter intentionally does not ship a
 public form design: the site renders the fields in its own voice and brand.
 
+### Shared-Stripe commercial shadow
+
+A hub may opt into a read-only network commercial projection when multiple
+chapters intentionally bill through one Stripe account. Every accepted source
+is an exact partition, including Stripe test/live mode:
+
+```ts
+networkCommercialReadModel: {
+  mode: "shadow",
+  sources: [{
+    stripeMode: "test",
+    appId: "example-chapter",
+    chapterId: "example-chapter",
+    environment: "dev",
+    dataEnvironment: "dev",
+    runtime: "cory",
+  }],
+},
+```
+
+The dedicated `/api/network-commercial/stripe-webhook` verifies Stripe's
+signature with `network_commercial_stripe_webhook_secret` before writing an
+append-only, PII-free event fact. The projector is rebuildable and deterministic:
+late metadata-less events may inherit a partition only through an unambiguous
+provider customer/subscription/invoice/charge reference. Wrong, missing,
+ambiguous, unsupported, and colliding events remain explained exceptions.
+
+`GET /api/admin/network-commercial-read-model` is super-admin-only and exposes
+current customer, subscription, invoice, refund, and currency-total facts for a
+BNF operator surface. `POST` with `{ command: "rebuild", mutationId }` rebuilds
+from the local event log without calling or mutating Stripe. `POST` with
+`{ command: "reconcile-stripe" }` performs bounded, GET-only current-object
+reads through the hub's vaulted `stripe_secret_key` and reports missing,
+unexpected, mismatched, truncated, and totals exceptions without changing the
+event log or projection. Objects outside the configured exact partitions are
+counted as ignored rather than adopted. This shadow never
+authorizes charges, refunds, subscription changes, or Chapter lifecycle writes;
+removing it changes no customer-facing behavior. The BNF frontend may be down
+while the webhook continues to ingest. Registering a Stripe endpoint and
+enabling production remain separate reviewed operations.
+
 For a hub with network targets, the standard admin catalog is Dashboard,
 Network, People, Portfolio, and Settings. Dashboard Overview renders aggregate network
 health; People contains CRM types whose `workspace` is absent or `"people"`;

package/dist/{copy-context-B4SCy6vx.d.ts → copy-context-CIxmneHI.d.ts}

@@ -147,6 +147,26 @@ interface ResolvedNetworkPersonRegistry {
     chapterIds: readonly string[];
 }
 
+/** One exact Stripe event partition accepted by the network commercial shadow. */
+interface NetworkCommercialSource {
+    appId: string;
+    chapterId: string;
+    environment: string;
+    dataEnvironment: string;
+    runtime: string;
+    stripeMode: "test" | "live";
+}
+/** Opt-in, read-only projection of a shared Stripe account. */
+interface ChapterNetworkCommercialReadModel {
+    mode: "shadow";
+    sources: readonly NetworkCommercialSource[];
+}
+/** Validated settings carried by a resolved hub. */
+interface ResolvedNetworkCommercialReadModel {
+    mode: "shadow";
+    sources: readonly NetworkCommercialSource[];
+}
+
 /** Scalar kinds accepted by the Chapter schema adapter. */
 type AttrType = "string" | "number" | "boolean" | "json";
 /** One odla-db attribute: its type and index/uniqueness/optionality flags. */
@@ -554,6 +574,8 @@ interface ChapterConfig {
     /** Network-scoped canonical Person registry. Shadow mode is additive only:
      * Chapter workflows and access continue to read their existing authority. */
     networkPersonRegistry?: ChapterNetworkPersonRegistry;
+    /** Read-only, rebuildable commercial projection from a shared Stripe account. */
+    networkCommercialReadModel?: ChapterNetworkCommercialReadModel;
     /** Enable a public, host-rendered formation application workflow. */
     formation?: LeaderFormationConfig;
     thesis?: unknown;
@@ -656,6 +678,8 @@ interface Chapter {
     builderLibrary: ResolvedBuilderLibrary | null;
     /** Null unless this hub explicitly enables the shadow Person registry. */
     networkPersonRegistry: ResolvedNetworkPersonRegistry | null;
+    /** Null unless this hub explicitly enables the commercial shadow. */
+    networkCommercialReadModel: ResolvedNetworkCommercialReadModel | null;
     /** Resolved public formation intake contract (disabled when omitted). */
     formation: ResolvedLeaderFormation;
     /** Resolved CRM engine (from `defineCrm`). */