@cosmicdrift/kumiko-samples 0.414.0 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +1 -1
  3. package/packages/bundled-features/src/auth-email-password/signup-token-store.ts +2 -3
  4. package/packages/bundled-features/src/auth-email-password/web/session.tsx +2 -1
  5. package/packages/bundled-features/src/auth-mfa/changes.json +6 -0
  6. package/packages/bundled-features/src/billing-foundation/changes.json +24 -0
  7. package/packages/bundled-features/src/billing-foundation/checkout-core.ts +11 -0
  8. package/packages/bundled-features/src/billing-foundation/checkout-ledger.ts +8 -0
  9. package/packages/bundled-features/src/billing-foundation/events.ts +7 -5
  10. package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts +2 -0
  11. package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts +76 -24
  12. package/packages/bundled-features/src/billing-foundation/handlers/process-payment-event.write.ts +5 -4
  13. package/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts +2 -0
  14. package/packages/bundled-features/src/billing-foundation/webhook-handler.ts +2 -2
  15. package/packages/bundled-features/src/channel-whatsapp/changes.json +24 -0
  16. package/packages/bundled-features/src/channel-whatsapp/events.ts +4 -3
  17. package/packages/bundled-features/src/channel-whatsapp/inbound-handlers.ts +23 -2
  18. package/packages/bundled-features/src/channel-whatsapp/webhook-normalize.ts +27 -6
  19. package/packages/bundled-features/src/compliance-profiles/changes.json +5 -0
  20. package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts +2 -0
  21. package/packages/bundled-features/src/data-retention/feature.ts +1 -0
  22. package/packages/bundled-features/src/delivery/changes.json +6 -0
  23. package/packages/bundled-features/src/delivery/handlers/opted-in-user-ids.query.ts +12 -3
  24. package/packages/bundled-features/src/document-ingest-foundation/changes.json +6 -0
  25. package/packages/bundled-features/src/document-ingest-foundation/feature.ts +1 -0
  26. package/packages/bundled-features/src/document-ingest-foundation/report-ingest-progress.ts +3 -1
  27. package/packages/bundled-features/src/documents/changes.json +6 -0
  28. package/packages/bundled-features/src/documents/feature.ts +10 -5
  29. package/packages/bundled-features/src/form-draft/feature.ts +1 -0
  30. package/packages/bundled-features/src/helpdesk/changes.json +6 -0
  31. package/packages/bundled-features/src/helpdesk/feature.ts +1 -0
  32. package/packages/bundled-features/src/helpdesk/handlers/reply.write.ts +3 -3
  33. package/packages/bundled-features/src/helpdesk/handlers/report.write.ts +3 -2
  34. package/packages/bundled-features/src/helpdesk/handlers/submit.write.ts +3 -2
  35. package/packages/bundled-features/src/helpdesk/legacy-contact-streams.ts +3 -1
  36. package/packages/bundled-features/src/helpdesk/lib.ts +9 -4
  37. package/packages/bundled-features/src/inbound-mail-foundation/account-poll.ts +4 -1
  38. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  39. package/packages/bundled-features/src/inbound-mail-foundation/content-refetch.ts +11 -4
  40. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +18 -9
  41. package/packages/bundled-features/src/inbound-mail-foundation/events.ts +18 -9
  42. package/packages/bundled-features/src/inbound-mail-foundation/handlers/connect-account.write.ts +2 -1
  43. package/packages/bundled-features/src/inbound-mail-foundation/handlers/forget-message.write.ts +6 -0
  44. package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message-schema.ts +18 -5
  45. package/packages/bundled-features/src/inbound-mail-foundation/normalize-inbound-message.ts +22 -8
  46. package/packages/bundled-features/src/inbound-mail-foundation/sanitize-inbound-html.ts +2 -5
  47. package/packages/bundled-features/src/managed-pages/web/page-edit-screen.tsx +11 -5
  48. package/packages/bundled-features/src/shared/changes.json +6 -0
  49. package/packages/bundled-features/src/shared/hmac-signature.ts +4 -2
  50. package/packages/bundled-features/src/shared/index.ts +2 -1
  51. package/packages/bundled-features/src/shared/normalize-email.ts +3 -0
  52. package/packages/bundled-features/src/shared/send-best-effort.ts +16 -6
  53. package/packages/bundled-features/src/step-dispatcher/changes.json +6 -0
  54. package/packages/bundled-features/src/step-dispatcher/deliver-dispatch-request.ts +5 -2
  55. package/packages/bundled-features/src/step-dispatcher/feature.ts +14 -0
  56. package/packages/bundled-features/src/step-dispatcher/sweep-abandoned.ts +4 -0
  57. package/packages/bundled-features/src/subscription-paddle/backfill-checkout-ledger.ts +2 -0
  58. package/packages/bundled-features/src/subscription-paddle/changes.json +6 -0
  59. package/packages/bundled-features/src/subscription-paddle/redeliver-legacy-checkout.ts +23 -2
  60. package/packages/bundled-features/src/subscription-stripe/changes.json +6 -0
  61. package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts +19 -5
  62. package/packages/bundled-features/src/template-resolver/changes.json +12 -0
  63. package/packages/bundled-features/src/template-resolver/seeding.ts +37 -7
  64. package/packages/bundled-features/src/template-resolver/web/web-preview-renderer.tsx +7 -1
  65. package/packages/bundled-features/src/tenant-inactivity/changes.json +6 -0
  66. package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +34 -16
  67. package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +6 -0
  68. package/packages/bundled-features/src/tenant-inactivity/state-store.ts +12 -1
  69. package/packages/bundled-features/src/tenant-lifecycle/changes.json +6 -0
  70. package/packages/bundled-features/src/tenant-lifecycle/feature.ts +1 -0
  71. package/packages/bundled-features/src/user/resolve-verified-user-email.ts +3 -3
  72. package/packages/bundled-features/src/user-data-rights/feature.ts +1 -0
  73. package/packages/bundled-features/src/waitlist/handlers/reject.write.ts +1 -1
  74. package/packages/bundled-features/src/waitlist/handlers/submit.write.ts +2 -2
  75. package/packages/bundled-features/src/waitlist/import.ts +2 -1
  76. package/packages/bundled-features/src/waitlist/lib.ts +1 -5
  77. package/packages/bundled-features/src/waitlist/link-on-signup.ts +2 -2
  78. package/packages/bundled-features/src/workflow-runner/changes.json +6 -0
  79. package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts +4 -2
  80. package/samples/apps/admin-console/src/app/shell.tsx +1 -0
  81. package/samples/recipes/crypto-shredding-hr/README.md +11 -0
  82. package/samples/recipes/crypto-shredding-hr/src/feature.ts +27 -0
  83. package/samples/recipes/record-detail-layout/src/feature.ts +36 -5
  84. package/samples/recipes/record-detail-layout/src/order-board.ts +10 -2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-samples",
3
- "version": "0.414.0",
3
+ "version": "0.415.0",
4
4
  "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-bundled-features",
3
- "version": "0.414.0",
3
+ "version": "0.415.0",
4
4
  "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,6 +15,7 @@ import * as z from "zod";
15
15
  import {
16
16
  createSingleUseTokenStore,
17
17
  hashSingleUseToken,
18
+ normalizeEmail,
18
19
  type SignupHandoverBinding,
19
20
  } from "../shared/index.ts";
20
21
 
@@ -22,9 +23,7 @@ import {
22
23
  * internally by the store AND by callers that need a consistent form
23
24
  * in the return body / mail send). Previously two places called
24
25
  * `.toLowerCase()` — one source means no drift. */
25
- export function normalizeEmail(email: string): string {
26
- return email.toLowerCase();
27
- }
26
+ export { normalizeEmail };
28
27
 
29
28
  export const SIGNUP_TOKEN_KEY_PREFIXES = {
30
29
  token: "signup:by-token:",
@@ -14,7 +14,7 @@ import {
14
14
  useSessionEndedSignal,
15
15
  } from "@cosmicdrift/kumiko-renderer";
16
16
  import { readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
17
- import { clearRememberedListState } from "@cosmicdrift/kumiko-renderer/web";
17
+ import { clearNavCollapseState, clearRememberedListState } from "@cosmicdrift/kumiko-renderer/web";
18
18
  import {
19
19
  createContext,
20
20
  type ReactNode,
@@ -219,6 +219,7 @@ export function SessionProvider({
219
219
  await logoutApi();
220
220
  // The reload below would hide the identity change from the list-state boot.
221
221
  clearRememberedListState();
222
+ clearNavCollapseState();
222
223
  if (typeof window === "undefined") {
223
224
  setState(UNAUTHENTICATED);
224
225
  return;
@@ -1,4 +1,10 @@
1
1
  [
2
+ {
3
+ "version": "0.415.0",
4
+ "type": "fix",
5
+ "title": "Signed tokens accept only the exact signature text",
6
+ "detail": "`hmacSignatureMatches` compared the decoded bytes, so a signature whose last character differed only in its unused trailing bits also verified. It now compares the text. No consumer action needed."
7
+ },
2
8
  {
3
9
  "version": "0.405.0",
4
10
  "type": "improvement",
@@ -1,4 +1,28 @@
1
1
  [
2
+ {
3
+ "version": "0.415.0",
4
+ "type": "fix",
5
+ "title": "Webhook events without a subscription stop answering 503 after an hour",
6
+ "detail": "An `updated`, `canceled` or invoice event that arrives before its subscription exists is redelivered (503) only while its provider event time is at most 60 minutes old. Older ones are ignored with 200 (`subscription_not_yet_created`), so a `created` that never comes (subscription from before the checkout ledger, foreign custom_data, deleted subscription) no longer drives the provider's endpoint into disabling. A provider that sends no event time (mollie) keeps retrying as before."
7
+ },
8
+ {
9
+ "version": "0.415.0",
10
+ "type": "fix",
11
+ "title": "create-checkout-session and start-plan-checkout allow 30 starts per tenant and hour",
12
+ "detail": "Every started checkout appends a `checkout-opened` event to the tenant's stream, which each webhook reads in full. Both checkout-starting handlers now declare `{ per: \"tenant+handler\", limit: 30, windowSeconds: 3600 }`, so a tenant member can no longer grow the stream without bound. An app that mounts billing-foundation now needs a rate limit resolver (Redis on `context.redis` or `context.rateLimit`); without one the handler fails at dispatch."
13
+ },
14
+ {
15
+ "version": "0.415.0",
16
+ "type": "fix",
17
+ "title": "Review fixes for Paddle redelivery, plan-switch consent age and WhatsApp ids",
18
+ "detail": "shouldRedeliverLegacyCheckout answers false only for configuration or permission failures of the backfill marker (access_denied, not_found, feature_disabled) and true for transient or internal ones, since Paddle retries only a bounded number of times. billing-foundation attaches a recorded switch consent to a provider tier change only within 24 hours before the provider event time. channel-whatsapp sets mediaId and contextWamid to null when they exceed the id length instead of truncating them into a different reference. The waitlist and helpdesk lib modules no longer re-export normalizeEmail; it comes from the shared index."
19
+ },
20
+ {
21
+ "version": "0.415.0",
22
+ "type": "fix",
23
+ "title": "plan-switch consent survives interleaved state events, one stream load per webhook",
24
+ "detail": "pendingSwitchConsentId no longer limits the consent search to events after the last state event, so a same-tier update between switch-plan and the tier change keeps the consent. process-event loads the subscription stream once under the lock for admission and append. Ignored-event reasons share one IgnoredEventReasons object and the provider id limit one constant."
25
+ },
2
26
  {
3
27
  "version": "0.414.0",
4
28
  "type": "breaking",
@@ -11,6 +11,7 @@ import {
11
11
  UnconfiguredError,
12
12
  UnprocessableError,
13
13
  } from "@cosmicdrift/kumiko-framework/errors";
14
+ import type { RateLimitOption } from "@cosmicdrift/kumiko-types/handlers";
14
15
  import { appendCheckoutOpened } from "./checkout-ledger.ts";
15
16
  import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
16
17
  import { assertOneOffAuthorized, assertOneOffPriceAllowed } from "./one-off-checkout-gate.ts";
@@ -384,6 +385,16 @@ export async function assertCheckoutAllowed(
384
385
  return plugin;
385
386
  }
386
387
 
388
+ // Every started checkout appends a `checkout-opened` to the tenant's event stream, and the
389
+ // webhook reads that whole stream, so unbounded starts would grow every later webhook. A real
390
+ // customer never opens this many checkouts per hour. Per handler, so each checkout-starting
391
+ // handler gets its own bucket.
392
+ export const CHECKOUT_START_RATE_LIMIT: RateLimitOption = {
393
+ per: "tenant+handler",
394
+ limit: 30,
395
+ windowSeconds: 60 * 60,
396
+ };
397
+
387
398
  export async function startProviderCheckout(
388
399
  ctx: HandlerContext,
389
400
  plugin: CheckoutCapableProvider,
@@ -12,6 +12,14 @@ import {
12
12
  SUBSCRIPTION_AGGREGATE_TYPE,
13
13
  } from "./events.ts";
14
14
 
15
+ export const IgnoredEventReasons = {
16
+ checkoutNotInLedger: "checkout_not_in_ledger",
17
+ priceMismatch: "price_mismatch",
18
+ foreignSubscription: "foreign_subscription",
19
+ subscriptionNotYetCreated: "subscription_not_yet_created",
20
+ } as const;
21
+ export type IgnoredEventReason = (typeof IgnoredEventReasons)[keyof typeof IgnoredEventReasons];
22
+
15
23
  type CheckoutMode = CheckoutOpenedPayload["mode"];
16
24
 
17
25
  export type CheckoutLookup = {
@@ -15,6 +15,8 @@ import * as z from "zod";
15
15
  import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./web/constants.ts";
16
16
  import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.ts";
17
17
 
18
+ export const PROVIDER_ID_MAX_CHARS = 200;
19
+
18
20
  // Aggregate type for the event store. One subscription per tenant is
19
21
  // one stream; the subscriptionAggregateId helper provides the stream ID.
20
22
  export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
@@ -54,9 +56,9 @@ const statusEnum = z.enum([
54
56
  // PII, and event headers cannot be crypto-shredded.
55
57
  export const subscriptionEventPayloadSchema = z.object({
56
58
  providerName: z.string().min(1).max(50),
57
- // Ciphertext, not the raw id: process-event limits the plaintext id to 200.
58
- providerCustomerId: z.string().min(1).max(piiCiphertextMaxLengthFor(200)),
59
- providerSubscriptionId: z.string().min(1).max(piiCiphertextMaxLengthFor(200)),
59
+ // Ciphertext, not the raw id: the plaintext id is limited to PROVIDER_ID_MAX_CHARS.
60
+ providerCustomerId: z.string().min(1).max(piiCiphertextMaxLengthFor(PROVIDER_ID_MAX_CHARS)),
61
+ providerSubscriptionId: z.string().min(1).max(piiCiphertextMaxLengthFor(PROVIDER_ID_MAX_CHARS)),
60
62
  status: statusEnum,
61
63
  tier: z.string().min(1).max(50),
62
64
  currentPeriodEndIso: z.string().min(1),
@@ -98,8 +100,8 @@ export const PAYMENT_RECEIVED_EVENT_QN =
98
100
 
99
101
  export const paymentEventPayloadSchema = z.object({
100
102
  providerName: z.string().min(1).max(50),
101
- // Ciphertext, not the raw id (plaintext limit 200).
102
- providerCustomerId: z.string().min(1).max(piiCiphertextMaxLengthFor(200)),
103
+ // Ciphertext, not the raw id (plaintext limit PROVIDER_ID_MAX_CHARS).
104
+ providerCustomerId: z.string().min(1).max(piiCiphertextMaxLengthFor(PROVIDER_ID_MAX_CHARS)),
103
105
  priceId: z.string().min(1).max(200),
104
106
  // Optional so payloads stored before quantity existed still parse; absent = 1.
105
107
  quantity: z.number().int().positive().optional(),
@@ -27,6 +27,7 @@ import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework
27
27
  import * as z from "zod";
28
28
  import {
29
29
  assertCheckoutAllowed,
30
+ CHECKOUT_START_RATE_LIMIT,
30
31
  type OpenCheckoutInput,
31
32
  openCheckout,
32
33
  startProviderCheckout,
@@ -83,6 +84,7 @@ export function createCheckoutSessionHandler(
83
84
  // Tenant-Admin-only — the tenant must deliberately configure its own
84
85
  // subscription. SystemAdmin as a fallback for operator-initiated flows.
85
86
  access: { roles: ["TenantAdmin", "SystemAdmin"] },
87
+ rateLimit: CHECKOUT_START_RATE_LIMIT,
86
88
  handler: async (event, ctx) => {
87
89
  // @cast-boundary engine-payload — dispatcher-zod-validated payload
88
90
  const payload = event.payload as CreateCheckoutSessionPayload;
@@ -25,7 +25,11 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
25
25
  import * as z from "zod";
26
26
  import { subscriptionAggregateId } from "../aggregate-id.ts";
27
27
  import { findProviderPlugin } from "../checkout-core.ts";
28
- import { findCheckoutOpened } from "../checkout-ledger.ts";
28
+ import {
29
+ findCheckoutOpened,
30
+ type IgnoredEventReason,
31
+ IgnoredEventReasons,
32
+ } from "../checkout-ledger.ts";
29
33
  import { SUBSCRIPTION_PII_FIELDS, subscriptionEntity } from "../entities.ts";
30
34
  import {
31
35
  CHECKOUT_CONSENT_RECORDED_EVENT_QN,
@@ -33,6 +37,7 @@ import {
33
37
  checkoutConsentRecordedPayloadSchema,
34
38
  INVOICE_PAID_EVENT_QN,
35
39
  INVOICE_PAYMENT_FAILED_EVENT_QN,
40
+ PROVIDER_ID_MAX_CHARS,
36
41
  SUBSCRIPTION_AGGREGATE_TYPE,
37
42
  SUBSCRIPTION_CANCELED_EVENT_QN,
38
43
  SUBSCRIPTION_CREATED_EVENT_QN,
@@ -76,8 +81,8 @@ export const processEventSchema = z.object({
76
81
  providerEventId: z.string().min(1).max(200),
77
82
  providerName: z.string().min(1).max(50),
78
83
  type: eventTypeSchema,
79
- providerCustomerId: z.string().min(1).max(200),
80
- providerSubscriptionId: z.string().min(1).max(200),
84
+ providerCustomerId: z.string().min(1).max(PROVIDER_ID_MAX_CHARS),
85
+ providerSubscriptionId: z.string().min(1).max(PROVIDER_ID_MAX_CHARS),
81
86
  status: statusSchema,
82
87
  tier: z.string().min(1).max(50),
83
88
  currentPeriodEndIso: z.string().min(1),
@@ -147,6 +152,16 @@ export function isLateStateEvent(
147
152
  // who constructs `payload` and what `providerEventId` they use.
148
153
  // =============================================================================
149
154
 
155
+ type SubscriptionStreamEvent = Awaited<ReturnType<HandlerContext["events"]["load"]>>[number];
156
+
157
+ async function lockAndLoadSubscriptionStream(
158
+ ctx: HandlerContext,
159
+ aggId: string,
160
+ ): Promise<readonly SubscriptionStreamEvent[]> {
161
+ await ctx.db.advisoryXactLock(BILLING_SUBSCRIPTION_LOCK_NAMESPACE, aggId);
162
+ return ctx.events.load(aggId);
163
+ }
164
+
150
165
  // A provider timestamp far in the future would make every later, genuine event look late.
151
166
  const PROVIDER_EVENT_CLOCK_SKEW_SECONDS = 300;
152
167
 
@@ -167,6 +182,7 @@ export async function appendSubscriptionEvent(
167
182
  rawPayload: ProcessEventPayload,
168
183
  now: Temporal.Instant = Temporal.Now.instant(),
169
184
  consentId?: string,
185
+ lockedStream?: readonly SubscriptionStreamEvent[],
170
186
  ): Promise<{
171
187
  readonly duplicate: boolean;
172
188
  readonly stale?: true;
@@ -175,10 +191,9 @@ export async function appendSubscriptionEvent(
175
191
  const aggId = subscriptionAggregateId(tenantId);
176
192
  const payload = clampProviderEventAt(rawPayload, now);
177
193
 
178
- // Serialises the read (idempotency + late check) with the append: the append re-reads the
179
- // stream version itself, so without the lock a concurrent delivery could slip in between and
180
- // the late check would have judged an outdated stream.
181
- await ctx.db.advisoryXactLock(BILLING_SUBSCRIPTION_LOCK_NAMESPACE, aggId);
194
+ // The lock serialises the read (idempotency + late check) with the append: the append re-reads the
195
+ // stream version itself, so without it a concurrent delivery could slip in between and the late
196
+ // check would have judged an outdated stream. A caller that already holds it passes its stream.
182
197
 
183
198
  // ---------------------------------------------------------------
184
199
  // 1. Idempotency: load the subscription stream and check whether this
@@ -191,7 +206,7 @@ export async function appendSubscriptionEvent(
191
206
  // streams, optimize via snapshot or a per-tenant dedup table as the
192
207
  // idempotency anchor (like cap-counter).
193
208
  // ---------------------------------------------------------------
194
- const existingEvents = await ctx.events.load(aggId);
209
+ const existingEvents = lockedStream ?? (await lockAndLoadSubscriptionStream(ctx, aggId));
195
210
  if (hasSeenProviderEvent(existingEvents, payload)) {
196
211
  return { duplicate: true, subscriptionAggregateId: aggId };
197
212
  }
@@ -311,7 +326,7 @@ function isStaleSubscriptionEvent(
311
326
 
312
327
  type Admission =
313
328
  | { readonly admitted: true; readonly consentId?: string }
314
- | { readonly admitted: false; readonly reason: string; readonly retry?: true };
329
+ | { readonly admitted: false; readonly reason: IgnoredEventReason; readonly retry?: true };
315
330
 
316
331
  function isBoundToLedgerEntry(
317
332
  ctx: HandlerContext,
@@ -323,23 +338,34 @@ function isBoundToLedgerEntry(
323
338
  }
324
339
 
325
340
  // A plan switch has no checkout of its own: its consent is the newest one recorded for the target
326
- // tier since the last stored state event, as long as no stored subscription event carries it yet.
341
+ // tier, as long as no stored subscription event carries it yet. No window by state events: another
342
+ // state event (renewal, status change) may arrive between the consent and the tier change. The age
343
+ // limit keeps an abandoned consent from being attached to a portal switch months later.
344
+ const SWITCH_CONSENT_MAX_AGE_HOURS = 24;
345
+
346
+ function providerEventInstant(payload: ProcessEventPayload, now: Temporal.Instant) {
347
+ const iso = clampProviderEventAt(payload, now).providerEventAtIso;
348
+ return iso === undefined ? now : Temporal.Instant.from(iso);
349
+ }
350
+
327
351
  function pendingSwitchConsentId(
328
- storedEvents: readonly { readonly type: string; readonly payload: unknown }[],
352
+ storedEvents: readonly SubscriptionStreamEvent[],
329
353
  payload: ProcessEventPayload,
354
+ now: Temporal.Instant,
330
355
  ): string | undefined {
331
- let lastStateIndex = -1;
356
+ const referenceAt = providerEventInstant(payload, now);
357
+ const oldestAcceptedAt = referenceAt.subtract({ hours: SWITCH_CONSENT_MAX_AGE_HOURS });
332
358
  const carried = new Set<string>();
333
- storedEvents.forEach((stored, index) => {
359
+ for (const stored of storedEvents) {
334
360
  // skip: only subscription state events can carry a consent
335
- if (!STATE_EVENT_QNS.has(stored.type)) return;
336
- lastStateIndex = index;
361
+ if (!STATE_EVENT_QNS.has(stored.type)) continue;
337
362
  const consentId = propertyOf(stored.payload, "consentId");
338
363
  if (typeof consentId === "string") carried.add(consentId);
339
- });
340
- for (let index = storedEvents.length - 1; index > lastStateIndex; index--) {
364
+ }
365
+ for (let index = storedEvents.length - 1; index >= 0; index--) {
341
366
  const stored = storedEvents[index];
342
367
  if (stored?.type !== CHECKOUT_CONSENT_RECORDED_EVENT_QN) continue;
368
+ if (Temporal.Instant.compare(stored.createdAt, oldestAcceptedAt) < 0) continue;
343
369
  const parsed = checkoutConsentRecordedPayloadSchema.safeParse(stored.payload);
344
370
  if (!parsed.success) continue;
345
371
  const consent = parsed.data;
@@ -355,11 +381,27 @@ function pendingSwitchConsentId(
355
381
  return undefined;
356
382
  }
357
383
 
384
+ // A `created` that never comes (subscription from before the ledger, foreign custom_data, deleted
385
+ // subscription) would otherwise answer 503 until the provider gives up, and Stripe disables an
386
+ // endpoint that keeps failing. Only a young event may still be overtaken by its `created`.
387
+ // A provider that sends no event time (mollie) cannot be aged and keeps retrying.
388
+ const MISSING_SUBSCRIPTION_RETRY_WINDOW_MINUTES = 60;
389
+
390
+ function isWithinMissingSubscriptionRetryWindow(
391
+ payload: ProcessEventPayload,
392
+ now: Temporal.Instant,
393
+ ): boolean {
394
+ if (payload.providerEventAtIso === undefined) return true;
395
+ const oldestRetriedAt = now.subtract({ minutes: MISSING_SUBSCRIPTION_RETRY_WINDOW_MINUTES });
396
+ return Temporal.Instant.compare(providerEventInstant(payload, now), oldestRetriedAt) >= 0;
397
+ }
398
+
358
399
  function admitProviderEvent(
359
400
  ctx: HandlerContext,
360
- storedEvents: readonly { readonly type: string; readonly payload: unknown }[],
401
+ storedEvents: readonly SubscriptionStreamEvent[],
361
402
  current: SubscriptionView | null,
362
403
  payload: ProcessEventPayload,
404
+ now: Temporal.Instant,
363
405
  ): Admission {
364
406
  const entry =
365
407
  payload.providerCheckoutId === undefined
@@ -373,19 +415,25 @@ function admitProviderEvent(
373
415
  return { admitted: true, ...(entry.consentId !== undefined && { consentId: entry.consentId }) };
374
416
  }
375
417
  if (payload.type === SubscriptionEventTypes.created) {
376
- return { admitted: false, reason: "checkout_not_in_ledger" };
418
+ return { admitted: false, reason: IgnoredEventReasons.checkoutNotInLedger };
377
419
  }
378
420
  // The provider does not guarantee order: an update that beats the `created` of its
379
421
  // subscription must be redelivered, not dropped.
380
- if (current === null)
381
- return { admitted: false, reason: "subscription_not_yet_created", retry: true };
422
+ if (current === null) {
423
+ return {
424
+ admitted: false,
425
+ reason: IgnoredEventReasons.subscriptionNotYetCreated,
426
+ ...(isWithinMissingSubscriptionRetryWindow(payload, now) && { retry: true }),
427
+ };
428
+ }
382
429
  const isCurrentSubscription =
383
430
  current.providerName === payload.providerName &&
384
431
  current.providerSubscriptionId === payload.providerSubscriptionId;
385
- if (!isCurrentSubscription) return { admitted: false, reason: "foreign_subscription" };
432
+ if (!isCurrentSubscription)
433
+ return { admitted: false, reason: IgnoredEventReasons.foreignSubscription };
386
434
  const switchConsentId =
387
435
  payload.type === SubscriptionEventTypes.updated && current.tier !== payload.tier
388
- ? pendingSwitchConsentId(storedEvents, payload)
436
+ ? pendingSwitchConsentId(storedEvents, payload, now)
389
437
  : undefined;
390
438
  return { admitted: true, ...(switchConsentId !== undefined && { consentId: switchConsentId }) };
391
439
  }
@@ -400,8 +448,11 @@ export function createProcessEventHandler(now: () => Temporal.Instant): WriteHan
400
448
  // @cast-boundary engine-payload — dispatcher-zod-validated payload
401
449
  const payload = event.payload as ProcessEventPayload;
402
450
  const aggId = subscriptionAggregateId(event.user.tenantId);
451
+ // One locked load serves admission and the append; the stream grows with every opened checkout.
452
+ // The lock comes first so the stream and `current` are both read under it.
453
+ const stream = await lockAndLoadSubscriptionStream(ctx, aggId);
403
454
  const current = await getSubscriptionForTenant(ctx, event.user.tenantId);
404
- const admission = admitProviderEvent(ctx, await ctx.events.load(aggId), current, payload);
455
+ const admission = admitProviderEvent(ctx, stream, current, payload, now());
405
456
  if (!admission.admitted) {
406
457
  ctx.obs.log?.warn(
407
458
  `[billing-foundation:process-event] ignored ${payload.type} ${payload.providerEventId} (${admission.reason}): provider ${payload.providerName}`,
@@ -431,6 +482,7 @@ export function createProcessEventHandler(now: () => Temporal.Instant): WriteHan
431
482
  payload,
432
483
  now(),
433
484
  admission.consentId,
485
+ stream,
434
486
  );
435
487
  return { isSuccess: true as const, data: result };
436
488
  },
@@ -19,13 +19,14 @@ import {
19
19
  import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
20
20
  import * as z from "zod";
21
21
  import { paymentAggregateId } from "../aggregate-id.ts";
22
- import { findCheckoutOpened } from "../checkout-ledger.ts";
22
+ import { findCheckoutOpened, IgnoredEventReasons } from "../checkout-ledger.ts";
23
23
  import { PAYMENT_PII_FIELDS, paymentEntity } from "../entities.ts";
24
24
  import {
25
25
  PAYMENT_AGGREGATE_TYPE,
26
26
  PAYMENT_RECEIVED_EVENT_QN,
27
27
  type PaymentEventHeaders,
28
28
  type PaymentEventPayload,
29
+ PROVIDER_ID_MAX_CHARS,
29
30
  } from "../events.ts";
30
31
  import { hasSeenProviderEvent } from "../provider-event-seen.ts";
31
32
 
@@ -33,7 +34,7 @@ export const processPaymentEventSchema = z.object({
33
34
  providerEventId: z.string().min(1).max(200),
34
35
  providerName: z.string().min(1).max(50),
35
36
  providerCheckoutId: z.string().min(1).max(200),
36
- providerCustomerId: z.string().min(1).max(200),
37
+ providerCustomerId: z.string().min(1).max(PROVIDER_ID_MAX_CHARS),
37
38
  priceId: z.string().min(1).max(200),
38
39
  quantity: z.number().int().positive().optional(),
39
40
  });
@@ -77,9 +78,9 @@ export const processPaymentEventHandler: WriteHandlerDef = {
77
78
  });
78
79
  const rejection =
79
80
  entry === undefined
80
- ? "checkout_not_in_ledger"
81
+ ? IgnoredEventReasons.checkoutNotInLedger
81
82
  : entry.priceId !== payload.priceId
82
- ? "price_mismatch"
83
+ ? IgnoredEventReasons.priceMismatch
83
84
  : undefined;
84
85
  if (rejection !== undefined) {
85
86
  ctx.obs.log?.warn(
@@ -9,6 +9,7 @@ import * as z from "zod";
9
9
  import {
10
10
  assertBillingEnabled,
11
11
  assertNoActiveSubscription,
12
+ CHECKOUT_START_RATE_LIMIT,
12
13
  isNonEmptyStringArray,
13
14
  joinBaseUrl,
14
15
  listOfferedCatalogProviders,
@@ -77,6 +78,7 @@ export function createStartPlanCheckoutHandler(
77
78
  "Starts a hosted checkout for a plan tier when the tenant has no active subscription; the server picks price and redirect URLs. Name the provider with providerName when the catalog offers several.",
78
79
  schema,
79
80
  access: { roles: purchaseRolesOf(catalog) },
81
+ rateLimit: CHECKOUT_START_RATE_LIMIT,
80
82
  handler: async (event, ctx) => {
81
83
  // @cast-boundary engine-payload — dispatcher-zod-validated payload
82
84
  const payload = event.payload as {
@@ -7,6 +7,7 @@
7
7
  import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
8
8
  import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
9
9
  import type { Context } from "hono";
10
+ import { IgnoredEventReasons } from "./checkout-ledger.ts";
10
11
  import type { PaymentEvent, SubscriptionEvent, SubscriptionProviderPlugin } from "./types.ts";
11
12
  import {
12
13
  BILLING_FOUNDATION_FEATURE,
@@ -32,7 +33,6 @@ export type SubscriptionWebhookRouteOptions = {
32
33
  ) => Promise<import("@cosmicdrift/kumiko-framework/engine").WriteResult>;
33
34
  };
34
35
 
35
- const IGNORED_CHECKOUT_NOT_IN_LEDGER = "checkout_not_in_ledger";
36
36
  const DEFAULT_WEBHOOK_PATH = "/api/subscription/webhook/:providerName";
37
37
 
38
38
  function resolveProvider(
@@ -180,7 +180,7 @@ async function redeliveryReason(
180
180
  const reason = propertyOf(dispatched.data, "reason");
181
181
  if (typeof reason !== "string") return undefined;
182
182
  if (propertyOf(dispatched.data, "retry") === true) return reason;
183
- if (reason !== IGNORED_CHECKOUT_NOT_IN_LEDGER) return undefined;
183
+ if (reason !== IgnoredEventReasons.checkoutNotInLedger) return undefined;
184
184
  const plugin = resolveProvider(deps.registry, event.providerName);
185
185
  const redeliver = await plugin?.shouldRedeliverIgnoredEvent?.({ event, reason, deps });
186
186
  return redeliver === true ? reason : undefined;
@@ -1,4 +1,28 @@
1
1
  [
2
+ {
3
+ "version": "0.415.0",
4
+ "type": "fix",
5
+ "title": "Inbound messages are charged to the sender budget once per wamid",
6
+ "detail": "A one-token marker bucket per tenant and wamid is taken before the sender windows are charged. A delivery that fails after the charge, its redelivery, and concurrent deliveries of the same wamid no longer use up the sender's budget again, so a real message is not stored as throttled by retries."
7
+ },
8
+ {
9
+ "version": "0.415.0",
10
+ "type": "fix",
11
+ "title": "WhatsApp webhook skips oversized ids and survives absurd timestamps",
12
+ "detail": "An entry with a wamid or phone number id above its limit is counted as skipped instead of failing the whole delivery with a 5xx. Overlong context ids, media ids and mime types are clipped, and a timestamp beyond the Temporal range falls back to the receive time."
13
+ },
14
+ {
15
+ "version": "0.415.0",
16
+ "type": "fix",
17
+ "title": "Non-integer status error codes are dropped instead of answering 500",
18
+ "detail": "The webhook normalizer accepted any number as a status error code while the handler schema requires an integer, so a fractional code made the whole delivery answer 500 and Meta redeliver it. The code is now dropped to null like other invalid optional fields."
19
+ },
20
+ {
21
+ "version": "0.415.0",
22
+ "type": "fix",
23
+ "title": "Concurrent webhook deliveries no longer store a message or status twice",
24
+ "detail": "The receive-message and record-status handlers now take a per-stream advisory lock before their duplicate check. Before, a delivery that committed after the other one's load landed as a second event on the same stream."
25
+ },
2
26
  {
3
27
  "version": "0.414.0",
4
28
  "type": "improvement",
@@ -23,8 +23,9 @@ export const WHATSAPP_THROTTLED_EVENT_QN =
23
23
  `${CHANNEL_WHATSAPP_FEATURE}:event:${WHATSAPP_THROTTLED_EVENT_SHORT}` as const;
24
24
 
25
25
  const E164_MAX_CHARS = 32;
26
- const WAMID_MAX_CHARS = 256;
27
- const PHONE_NUMBER_ID_MAX_CHARS = 64;
26
+ export const WAMID_MAX_CHARS = 256;
27
+ export const PHONE_NUMBER_ID_MAX_CHARS = 64;
28
+ export const MIME_TYPE_MAX_CHARS = 255;
28
29
  export const RAW_STATUS_MAX_CHARS = 64;
29
30
 
30
31
  // What the webhook route hands to the write handlers: normalized, still plaintext.
@@ -38,7 +39,7 @@ export const receiveMessageInputSchema = z.object({
38
39
  buttonPayload: z.string().max(WHATSAPP_BUTTON_PAYLOAD_MAX_CHARS).nullable(),
39
40
  contextWamid: z.string().max(WAMID_MAX_CHARS).nullable(),
40
41
  mediaId: z.string().max(WAMID_MAX_CHARS).nullable(),
41
- mimeType: z.string().max(255).nullable(),
42
+ mimeType: z.string().max(MIME_TYPE_MAX_CHARS).nullable(),
42
43
  });
43
44
  export type ReceiveMessageInput = z.infer<typeof receiveMessageInputSchema>;
44
45
 
@@ -17,6 +17,8 @@ import {
17
17
  import type { ResolvedWhatsappOptions } from "./options.ts";
18
18
  import { encryptWhatsappPii, WhatsappPiiFields } from "./pii.ts";
19
19
 
20
+ const WHATSAPP_STREAM_LOCK_NAMESPACE = 0x77616d73;
21
+
20
22
  export type InboundOutcome = "stored" | "duplicate" | "throttled";
21
23
 
22
24
  type InboundResult = {
@@ -32,11 +34,17 @@ type LimitContext = Pick<HandlerContext, "services" | "rateLimitDigest">;
32
34
 
33
35
  // Counts one message against every per-sender window. Only a RateLimitError means "throttled";
34
36
  // anything else (Redis down, bad config) propagates so the webhook answers 5xx and Meta redelivers.
37
+ // A one-token marker bucket per wamid makes the charge once-only across failed rounds and
38
+ // concurrent deliveries. The marker is taken before the charge: a crash in between loses one
39
+ // charge, never doubles one. A redelivery after a throttled-then-failed attempt skips the charge.
40
+ // ponytail: that redelivery also skips the throttle decision (RateLimitResolver cannot read without
41
+ // consuming), so at most one message per failed round gets past the limit; upgrade: add a peek.
35
42
  async function chargeSender(
36
43
  ctx: LimitContext,
37
44
  options: ResolvedWhatsappOptions,
38
45
  tenantId: TenantId,
39
46
  from: string,
47
+ wamid: string,
40
48
  ): Promise<RateLimitError | null> {
41
49
  if (options.senderRateLimits.length === 0) return null;
42
50
  const { rateLimit } = ctx.services;
@@ -46,6 +54,16 @@ async function chargeSender(
46
54
  message: "channel-whatsapp: the per-sender limit needs a rate limiter and a digest key",
47
55
  });
48
56
  }
57
+ const markerWindowSeconds = Math.max(...options.senderRateLimits.map((l) => l.windowSeconds));
58
+ try {
59
+ await rateLimit.enforce(`whatsapp-inbound-charged:${tenantId}:${wamid}`, {
60
+ limit: 1,
61
+ windowSeconds: markerWindowSeconds,
62
+ });
63
+ } catch (error) {
64
+ if (error instanceof RateLimitError) return null;
65
+ throw error;
66
+ }
49
67
  const senderKey = `whatsapp-inbound:${tenantId}:${digest(from)}`;
50
68
  try {
51
69
  await rateLimit.enforceAll(
@@ -74,11 +92,13 @@ export function createReceiveMessageHandler(options: ResolvedWhatsappOptions) {
74
92
  const input = event.payload;
75
93
  const tenantId = event.user.tenantId;
76
94
  const aggregateId = whatsappMessageAggregateId(tenantId, input.wamid);
95
+ // tryAppend re-reads the stream version, so a delivery that committed after our load would land as a second event.
96
+ await ctx.db.advisoryXactLock(WHATSAPP_STREAM_LOCK_NAMESPACE, aggregateId);
77
97
 
78
98
  // Dedupe before the limit: Meta's redeliveries must not use up the sender's budget.
79
99
  if ((await ctx.events.load(aggregateId)).length > 0) return OUTCOME_DUPLICATE;
80
100
 
81
- const throttle = await chargeSender(ctx, options, tenantId, input.from);
101
+ const throttle = await chargeSender(ctx, options, tenantId, input.from, input.wamid);
82
102
  const requestId = `channel-whatsapp:receive-message:${aggregateId}`;
83
103
  const from = await encryptWhatsappPii(
84
104
  tenantId,
@@ -132,7 +152,6 @@ export function createReceiveMessageHandler(options: ResolvedWhatsappOptions) {
132
152
  mediaId: input.mediaId,
133
153
  mimeType: input.mimeType,
134
154
  };
135
- // A concurrent delivery of the same wamid that won the race counts as a duplicate.
136
155
  const appended = await ctx.events.tryAppend({
137
156
  aggregateId,
138
157
  aggregateType: WHATSAPP_MESSAGE_AGGREGATE_TYPE,
@@ -162,6 +181,8 @@ export function createRecordStatusHandler(options: ResolvedWhatsappOptions) {
162
181
  input.status,
163
182
  input.rawStatus,
164
183
  );
184
+ // tryAppend re-reads the stream version, so a delivery that committed after our load would land as a second event.
185
+ await ctx.db.advisoryXactLock(WHATSAPP_STREAM_LOCK_NAMESPACE, aggregateId);
165
186
  if ((await ctx.events.load(aggregateId)).length > 0) return OUTCOME_DUPLICATE;
166
187
 
167
188
  const payload: StatusUpdatedPayload = {