@odla-ai/chapter 0.50.0 → 0.52.0

package/dist/worker/index.d.cts

@@ -25,7 +25,7 @@ type TextFields$1<Key extends string> = {
     [Field in Key]: string;
 };
 /** User-visible language for sharing, delivery state, and leader rollups. */
-type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
+type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "edgeUnpaired" | "edgeUnpairedHint" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
 
 /** Copy for the person record panels: lifecycle actions, comms, scheduling, billing and meetings. */
 type AdminRecordsCopy = {
@@ -78,7 +78,7 @@ interface ChapterCopy {
         availability: TextFields<"loading" | "loadFailed" | "saved" | "title" | "days" | "startHour" | "endHour" | "slotMinutes" | "minNoticeHours" | "windowDays" | "timezone" | "summaryTemplate" | "save"> & {
             dayLabels: readonly string[];
         };
-        email: TextFields<"loading" | "loadFailed" | "saved" | "sent" | "testFailed" | "delivery" | "notificationAddress" | "replyTo" | "debugInbox" | "debugInboxHint" | "sendTest" | "enabled" | "subject" | "body" | "save" | "sendLog" | "sentColumn" | "templateColumn" | "statusColumn" | "toColumn" | "failed" | "redirected" | "delivered">;
+        email: TextFields<"loading" | "loadFailed" | "saved" | "sent" | "testFailed" | "delivery" | "notificationAddress" | "replyTo" | "fromName" | "fromNameHint" | "debugInbox" | "debugInboxHint" | "sendTest" | "enabled" | "subject" | "body" | "save" | "sendLog" | "sentColumn" | "templateColumn" | "statusColumn" | "toColumn" | "failed" | "redirected" | "delivered">;
         meetings: TextFields<"loading" | "loadFailed" | "cancelConfirm" | "newStartPrompt" | "parseFailed" | "agenda" | "empty" | "unknown" | "drift" | "meet" | "reschedule" | "cancel">;
         admission: TextFields<"title" | "description" | "email" | "decision" | "expires" | "note" | "waive" | "require" | "add" | "ledger" | "loading" | "consumed" | "revoked" | "expired" | "active" | "local" | "parent" | "revoke">;
         network: AdminNetworkCopy;
@@ -214,7 +214,10 @@ type DbRules = Record<string, Rule>;
 
 /** One follower site a leader can push CRM records to. The secret VALUE never
  * lives in config: `secretName` names the leader tenant's vaulted copy of the
- * follower's `network_share_secret`. */
+ * follower's `network_share_secret`. Both slots are declared by
+ * `createChapterIntegration` and filled together by
+ * `odla-ai chapter edge pair --leader <leader> --follower <id>`; until then
+ * every leader-side surface reports the edge as `edge_unpaired`. */
 interface ChapterNetworkTarget {
     /** Stable lowercase slug used by the UI, audit tags, and default secret name. */
     id: string;
@@ -516,9 +519,12 @@ interface EmailTemplate {
 interface ChapterEmails {
     notificationEmail: string;
     replyTo?: string;
+    /** Display name on outbound lifecycle mail (`Tori Horton <from@…>`); the
+     * address itself stays the Worker's `EMAIL_FROM`. Absent ⇒ bare address. */
+    fromName?: string;
     debugEmail?: string;
-    /** Operational lifecycle templates: adminNotification / paymentConfirmation /
-     * prepEmail / onboardingInvite, each `{ subject, text, enabled? }`. */
+    /** Operational lifecycle templates: adminNotification / submitConfirmation /
+     * paymentConfirmation / prepEmail / onboardingInvite, each `{ subject, text, enabled? }`. */
     templates?: Record<string, EmailTemplate>;
 }
 /** Booking rules for the intro-call scheduler (stored as schedulingJson). */
@@ -842,7 +848,9 @@ interface MembershipOfferingVersion {
     autoRenew: true;
     paymentGraceDays: number;
     seatPriceCents: number;
-    seatPurchaseWindowCalendarMonths: number;
+    /** Calendar months after the initial payment during which a seat may be bought. Absent: no window; a seat
+     * may be bought whenever the primary membership is paid and active, renewals included. */
+    seatPurchaseWindowCalendarMonths?: number;
     requiredDisclosures: string[];
 }
 /** Cohort qualification survives the expiration of its monetary benefit. */
@@ -1010,6 +1018,8 @@ interface NamedSeatOffer {
     autoRenew: boolean;
     eligible: boolean;
     digest: string;
+    /** False when the frozen offering sets no purchase window: seats may be bought for as long as the membership is paid. */
+    purchaseWindowed?: boolean;
     seat?: {
         seatId: string;
         status: string;
@@ -1130,9 +1140,31 @@ type NamedSeatEvidenceRequest = MembershipQuoteTarget & {
     eventId: string;
 };
 
+/** Content-free operator alert attached to an error report. Its shape is a subset of
+ * the `ErrorReport` that `recordError` from `@odla-ai/o11y` accepts, so a host passes
+ * that function straight through as `ChapterWorkerOptions.recordError`. */
+interface ChapterErrorReport {
+    /** Stable, low-cardinality alert code, for example `stripe_webhook_quarantined`. */
+    code: string;
+    /** Route or step the alert belongs to. */
+    route?: string;
+    /** Low-cardinality index attributes: counts and dispositions, never ids. */
+    attributes?: Record<string, string | number | boolean>;
+    /** Bounded triage context kept out of the index: provider event ids, never PII. */
+    artifacts?: Record<string, unknown>;
+    /** Optional dedup key; the collector falls back to type + code + route. */
+    fingerprint?: string;
+}
+/** Records one structured error. `recordError` from `@odla-ai/o11y` satisfies it. */
+type ChapterErrorRecorder = (error: Error, report: ChapterErrorReport) => unknown;
+
 /** The Cloudflare SEND_EMAIL binding payload. */
 interface EmailPayload {
-    from: string;
+    /** A bare address, or `{ name, email }` when the group sets a From display name. */
+    from: string | {
+        name: string;
+        email: string;
+    };
     to: string[];
     subject: string;
     text?: string;
@@ -1228,6 +1260,12 @@ interface ChapterWorkerOptions {
     };
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
+    /** Structured error recorder for operator alerts: a quarantined Stripe webhook, a
+     *  network commercial exception becoming active. Pass `recordError` from
+     *  `@odla-ai/o11y` when the Worker is wrapped in `withObservability`; the default
+     *  writes one JSON line to `console.error`, which Workers Logs retains. Reports carry
+     *  counts and provider event ids only, never payloads or PII. */
+    recordError?: ChapterErrorRecorder;
     /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
      *  routes (or override/alias a built-in path) and reuse chapter's auth via the
      *  shared {@link WorkerContext}, instead of re-verifying JWTs itself. */
@@ -1304,6 +1342,7 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         makeDb: (env: ChapterEnv) => ChapterDb;
         stripeSecretName?: string;
     } | undefined;
+    recordError: ChapterErrorRecorder;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1989,11 +2028,14 @@ declare function withActiveSignupControlTheme(response: Response, options: Activ
  *
  * Observability is a host concern, not a chapter dependency. To trace, wrap the
  * result in your worker entry — `export default withObservability(chapterWorker(
- * { chapter }))` — with `withObservability` from `@odla-ai/o11y`. Sites that
- * don't run o11y bundle `@odla-ai/chapter/worker` without installing it.
+ * { chapter, recordError }))` — with `withObservability` and `recordError` from
+ * `@odla-ai/o11y`; `recordError` turns the Worker's operator alerts (quarantined
+ * webhooks, commercial exceptions) into error-level o11y reports. Sites that
+ * don't run o11y bundle `@odla-ai/chapter/worker` without installing it and
+ * keep those alerts as structured `console.error` lines.
  */
 declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };

package/dist/worker/index.d.ts

@@ -25,7 +25,7 @@ type TextFields$1<Key extends string> = {
     [Field in Key]: string;
 };
 /** User-visible language for sharing, delivery state, and leader rollups. */
-type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
+type AdminNetworkCopy = TextFields$1<"title" | "allowlistDescription" | "sharing" | "shareWith" | "shared" | "shareFailed" | "deliveryFailed" | "loadingRollup" | "loadRollupFailed" | "overview" | "configuredFollowers" | "reachableFollowers" | "recordsAcrossFollowers" | "noFollowers" | "followers" | "available" | "unavailable" | "transportReachable" | "transportUnavailable" | "transportNotChecked" | "edgeUnpaired" | "edgeUnpairedHint" | "bindingTransport" | "urlTransport" | "activeConfiguration" | "noActiveConfiguration" | "publicSiteAvailable" | "publicSiteUnavailable" | "publicSiteNotChecked" | "recordTotals" | "noRecordTotals">;
 
 /** Copy for the person record panels: lifecycle actions, comms, scheduling, billing and meetings. */
 type AdminRecordsCopy = {
@@ -78,7 +78,7 @@ interface ChapterCopy {
         availability: TextFields<"loading" | "loadFailed" | "saved" | "title" | "days" | "startHour" | "endHour" | "slotMinutes" | "minNoticeHours" | "windowDays" | "timezone" | "summaryTemplate" | "save"> & {
             dayLabels: readonly string[];
         };
-        email: TextFields<"loading" | "loadFailed" | "saved" | "sent" | "testFailed" | "delivery" | "notificationAddress" | "replyTo" | "debugInbox" | "debugInboxHint" | "sendTest" | "enabled" | "subject" | "body" | "save" | "sendLog" | "sentColumn" | "templateColumn" | "statusColumn" | "toColumn" | "failed" | "redirected" | "delivered">;
+        email: TextFields<"loading" | "loadFailed" | "saved" | "sent" | "testFailed" | "delivery" | "notificationAddress" | "replyTo" | "fromName" | "fromNameHint" | "debugInbox" | "debugInboxHint" | "sendTest" | "enabled" | "subject" | "body" | "save" | "sendLog" | "sentColumn" | "templateColumn" | "statusColumn" | "toColumn" | "failed" | "redirected" | "delivered">;
         meetings: TextFields<"loading" | "loadFailed" | "cancelConfirm" | "newStartPrompt" | "parseFailed" | "agenda" | "empty" | "unknown" | "drift" | "meet" | "reschedule" | "cancel">;
         admission: TextFields<"title" | "description" | "email" | "decision" | "expires" | "note" | "waive" | "require" | "add" | "ledger" | "loading" | "consumed" | "revoked" | "expired" | "active" | "local" | "parent" | "revoke">;
         network: AdminNetworkCopy;
@@ -214,7 +214,10 @@ type DbRules = Record<string, Rule>;
 
 /** One follower site a leader can push CRM records to. The secret VALUE never
  * lives in config: `secretName` names the leader tenant's vaulted copy of the
- * follower's `network_share_secret`. */
+ * follower's `network_share_secret`. Both slots are declared by
+ * `createChapterIntegration` and filled together by
+ * `odla-ai chapter edge pair --leader <leader> --follower <id>`; until then
+ * every leader-side surface reports the edge as `edge_unpaired`. */
 interface ChapterNetworkTarget {
     /** Stable lowercase slug used by the UI, audit tags, and default secret name. */
     id: string;
@@ -516,9 +519,12 @@ interface EmailTemplate {
 interface ChapterEmails {
     notificationEmail: string;
     replyTo?: string;
+    /** Display name on outbound lifecycle mail (`Tori Horton <from@…>`); the
+     * address itself stays the Worker's `EMAIL_FROM`. Absent ⇒ bare address. */
+    fromName?: string;
     debugEmail?: string;
-    /** Operational lifecycle templates: adminNotification / paymentConfirmation /
-     * prepEmail / onboardingInvite, each `{ subject, text, enabled? }`. */
+    /** Operational lifecycle templates: adminNotification / submitConfirmation /
+     * paymentConfirmation / prepEmail / onboardingInvite, each `{ subject, text, enabled? }`. */
     templates?: Record<string, EmailTemplate>;
 }
 /** Booking rules for the intro-call scheduler (stored as schedulingJson). */
@@ -842,7 +848,9 @@ interface MembershipOfferingVersion {
     autoRenew: true;
     paymentGraceDays: number;
     seatPriceCents: number;
-    seatPurchaseWindowCalendarMonths: number;
+    /** Calendar months after the initial payment during which a seat may be bought. Absent: no window; a seat
+     * may be bought whenever the primary membership is paid and active, renewals included. */
+    seatPurchaseWindowCalendarMonths?: number;
     requiredDisclosures: string[];
 }
 /** Cohort qualification survives the expiration of its monetary benefit. */
@@ -1010,6 +1018,8 @@ interface NamedSeatOffer {
     autoRenew: boolean;
     eligible: boolean;
     digest: string;
+    /** False when the frozen offering sets no purchase window: seats may be bought for as long as the membership is paid. */
+    purchaseWindowed?: boolean;
     seat?: {
         seatId: string;
         status: string;
@@ -1130,9 +1140,31 @@ type NamedSeatEvidenceRequest = MembershipQuoteTarget & {
     eventId: string;
 };
 
+/** Content-free operator alert attached to an error report. Its shape is a subset of
+ * the `ErrorReport` that `recordError` from `@odla-ai/o11y` accepts, so a host passes
+ * that function straight through as `ChapterWorkerOptions.recordError`. */
+interface ChapterErrorReport {
+    /** Stable, low-cardinality alert code, for example `stripe_webhook_quarantined`. */
+    code: string;
+    /** Route or step the alert belongs to. */
+    route?: string;
+    /** Low-cardinality index attributes: counts and dispositions, never ids. */
+    attributes?: Record<string, string | number | boolean>;
+    /** Bounded triage context kept out of the index: provider event ids, never PII. */
+    artifacts?: Record<string, unknown>;
+    /** Optional dedup key; the collector falls back to type + code + route. */
+    fingerprint?: string;
+}
+/** Records one structured error. `recordError` from `@odla-ai/o11y` satisfies it. */
+type ChapterErrorRecorder = (error: Error, report: ChapterErrorReport) => unknown;
+
 /** The Cloudflare SEND_EMAIL binding payload. */
 interface EmailPayload {
-    from: string;
+    /** A bare address, or `{ name, email }` when the group sets a From display name. */
+    from: string | {
+        name: string;
+        email: string;
+    };
     to: string[];
     subject: string;
     text?: string;
@@ -1228,6 +1260,12 @@ interface ChapterWorkerOptions {
     };
     /** CRM mount point. Default "/api/crm". */
     crmBasePath?: string;
+    /** Structured error recorder for operator alerts: a quarantined Stripe webhook, a
+     *  network commercial exception becoming active. Pass `recordError` from
+     *  `@odla-ai/o11y` when the Worker is wrapped in `withObservability`; the default
+     *  writes one JSON line to `console.error`, which Workers Logs retains. Reports carry
+     *  counts and provider event ids only, never payloads or PII. */
+    recordError?: ChapterErrorRecorder;
     /** Host routes, tried BEFORE the built-ins — so a wrapping site can add its own
      *  routes (or override/alias a built-in path) and reuse chapter's auth via the
      *  shared {@link WorkerContext}, instead of re-verifying JWTs itself. */
@@ -1304,6 +1342,7 @@ declare function createWorkerContext(options: ChapterWorkerOptions): {
         makeDb: (env: ChapterEnv) => ChapterDb;
         stripeSecretName?: string;
     } | undefined;
+    recordError: ChapterErrorRecorder;
     getPublicConfig: (env: ChapterEnv) => Promise<PublicConfig>;
     verifyUser: (req: Request, env: ChapterEnv) => Promise<Verified | null>;
     makeDb: (env: ChapterEnv) => Db;
@@ -1989,11 +2028,14 @@ declare function withActiveSignupControlTheme(response: Response, options: Activ
  *
  * Observability is a host concern, not a chapter dependency. To trace, wrap the
  * result in your worker entry — `export default withObservability(chapterWorker(
- * { chapter }))` — with `withObservability` from `@odla-ai/o11y`. Sites that
- * don't run o11y bundle `@odla-ai/chapter/worker` without installing it.
+ * { chapter, recordError }))` — with `withObservability` and `recordError` from
+ * `@odla-ai/o11y`; `recordError` turns the Worker's operator alerts (quarantined
+ * webhooks, commercial exceptions) into error-level o11y reports. Sites that
+ * don't run o11y bundle `@odla-ai/chapter/worker` without installing it and
+ * keep those alerts as structured `console.error` lines.
  */
 declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, AdmissionGrantDeliveryError, type AdmissionGrantDeliveryOptions, type BuilderLibraryDeliveryOptions, type ChapterEnv, type ChapterErrorRecorder, type ChapterErrorReport, type ChapterWorkerOptions, type LeaderAdmissionAssignment, type LeaderAdmissionDelivery, type LeaderAdmissionDeliveryStatus, MEMBERSHIP_AUTHORITY_PATH, type MemberContentDeliveryOptions, type MembershipAuthorityHandlerOptions, type MembershipAuthorityPeer, type MembershipChapterEffect, type MembershipEffectScope, type MembershipWorkerAdapter, type MembershipWorkerAdapterOptions, type NamedSeatOperatorRefundInput, type NamedSeatRefundReason, type NetworkTargetTransport, NetworkTargetTransportError, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterMembershipAccess, chapterWorker, createMembershipAuthorityHandler, createMembershipAuthorityStorage, createMembershipChapterEffectRoute, createMembershipWorkerAdapter, createWorkerContext, deliverAdmissionGrants, deliverBuilderLibrary, deliverMemberContent, deliverMembershipChapterEffect, deliverSignupControl, drainMembershipEffects, refundNamedSeatByOperator, renderActiveSignupControlHtml, resolveNetworkTargetTransport, retryChapterApprovalEffects, retryLeaderAdmissionDeliveries, withActiveSignupControlTheme };