@pithy-sh/payments 0.6.0 → 0.7.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 (87) hide show
  1. package/README.md +6 -1
  2. package/dist/admin/coverage.d.ts.map +1 -1
  3. package/dist/admin/coverage.js +13 -7
  4. package/dist/admin/read.d.ts +60 -0
  5. package/dist/admin/read.d.ts.map +1 -1
  6. package/dist/admin/read.js +86 -2
  7. package/dist/audit/actions.d.ts +5 -0
  8. package/dist/audit/actions.d.ts.map +1 -1
  9. package/dist/audit/actions.js +6 -1
  10. package/dist/capability.d.ts +3 -3
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +14 -7
  13. package/dist/client/api.d.ts +25 -9
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +68 -12
  16. package/dist/client/hooks.d.ts +27 -39
  17. package/dist/client/hooks.d.ts.map +1 -1
  18. package/dist/client/hooks.js +166 -315
  19. package/dist/client/projection.d.ts +25 -18
  20. package/dist/client/projection.d.ts.map +1 -1
  21. package/dist/client/railChoice.d.ts +46 -0
  22. package/dist/client/railChoice.d.ts.map +1 -0
  23. package/dist/client/railChoice.js +48 -0
  24. package/dist/data/webhookEvent.d.ts +67 -0
  25. package/dist/data/webhookEvent.d.ts.map +1 -1
  26. package/dist/data/webhookEvent.js +76 -1
  27. package/dist/http/responses.d.ts +64 -0
  28. package/dist/http/responses.d.ts.map +1 -1
  29. package/dist/http/responses.js +34 -1
  30. package/dist/http/routes.d.ts +1 -0
  31. package/dist/http/routes.d.ts.map +1 -1
  32. package/dist/http/routes.js +64 -11
  33. package/dist/http/schemas.d.ts +19 -0
  34. package/dist/http/schemas.d.ts.map +1 -1
  35. package/dist/http/schemas.js +18 -1
  36. package/dist/http/scopes.d.ts +15 -6
  37. package/dist/http/scopes.d.ts.map +1 -1
  38. package/dist/http/scopes.js +55 -5
  39. package/dist/http/view.d.ts +9 -2
  40. package/dist/http/view.d.ts.map +1 -1
  41. package/dist/http/view.js +29 -1
  42. package/dist/http/webhookGuard.d.ts +7 -1
  43. package/dist/http/webhookGuard.d.ts.map +1 -1
  44. package/dist/http/webhookGuard.js +3 -2
  45. package/dist/migrations/0003_webhook_targets.d.ts +19 -0
  46. package/dist/migrations/0003_webhook_targets.d.ts.map +1 -0
  47. package/dist/migrations/0003_webhook_targets.js +29 -0
  48. package/dist/processing/activities.d.ts +9 -0
  49. package/dist/processing/activities.d.ts.map +1 -0
  50. package/dist/processing/activities.js +30 -0
  51. package/dist/projection/orphans.d.ts.map +1 -1
  52. package/dist/projection/orphans.js +15 -6
  53. package/dist/projection/targets.d.ts +50 -0
  54. package/dist/projection/targets.d.ts.map +1 -0
  55. package/dist/projection/targets.js +50 -0
  56. package/dist/purge/contribution.d.ts +32 -0
  57. package/dist/purge/contribution.d.ts.map +1 -0
  58. package/dist/purge/contribution.js +120 -0
  59. package/dist/version.generated.d.ts +1 -1
  60. package/dist/version.generated.js +1 -1
  61. package/dist/workflows/paddleSweep.d.ts.map +1 -1
  62. package/dist/workflows/paddleSweep.js +20 -9
  63. package/docs/lemon-squeezy.md +1 -1
  64. package/docs/paddle.md +2 -0
  65. package/package.json +6 -4
  66. package/src/admin/coverage.ts +13 -9
  67. package/src/admin/read.ts +135 -0
  68. package/src/audit/actions.ts +5 -0
  69. package/src/capability.ts +25 -15
  70. package/src/client/api.ts +74 -11
  71. package/src/client/hooks.ts +206 -301
  72. package/src/client/projection.ts +25 -18
  73. package/src/client/railChoice.ts +72 -0
  74. package/src/data/webhookEvent.ts +115 -0
  75. package/src/http/responses.ts +66 -0
  76. package/src/http/routes.ts +73 -11
  77. package/src/http/schemas.ts +26 -0
  78. package/src/http/scopes.ts +58 -6
  79. package/src/http/view.ts +31 -1
  80. package/src/http/webhookGuard.ts +23 -3
  81. package/src/migrations/0003_webhook_targets.ts +34 -0
  82. package/src/processing/activities.ts +34 -0
  83. package/src/projection/orphans.ts +28 -11
  84. package/src/projection/targets.ts +66 -0
  85. package/src/purge/contribution.ts +135 -0
  86. package/src/version.generated.ts +1 -1
  87. package/src/workflows/paddleSweep.ts +39 -14
@@ -4,7 +4,7 @@ import { PAYMENTS_HOSTED_RAILS } from "../data/rail.js";
4
4
  import { decodeSubjectReference, encodeSubjectReference, sameSubject } from "../data/subject.js";
5
5
  import { providerProductId, railEnabled, resolveProduct } from "../config/config.js";
6
6
  import { PaymentsPurchase } from "../data/purchase.js";
7
- import { WEBHOOK_EVENT_ORPHANED } from "../data/webhookEvent.js";
7
+ import { NO_WEBHOOK_EVENT_TARGETS, WEBHOOK_EVENT_ORPHANED } from "../data/webhookEvent.js";
8
8
  import { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } from "../data/tables.js";
9
9
  import { PaymentsEntitlementNotInCatalogError, PaymentsProductNotFoundError, PaymentsRailNotConfiguredError, PaymentsReceiptAlreadyOwnedError, PaymentsReconcileNotProvisionedError, PaymentsSubscriptionChangeRefusedError } from "../error/errors.js";
10
10
  import { resolveEntitlements } from "../projection/resolve.js";
@@ -12,12 +12,13 @@ import { resolveAllowances } from "../entitlement/allowance.js";
12
12
  import { allowanceOverride, clearOverride, overrideCeiling, overrideVersion, readOverride, setOverride, setUnrestricted } from "../entitlement/override.js";
13
13
  import { allowanceInputFor } from "../entitlement/meter.js";
14
14
  import { requirePaymentsSubject, resolvePaymentsSubject } from "../entitlement/subjectSeam.js";
15
- import { lastReports, listEntitlements, listOverrides, listPurchases, listReconcileRuns, listSubscriptions, listUsageRuns, readEntitlements, unrestrictedSubjects } from "../admin/read.js";
15
+ import { lastReports, listEntitlements, listOverrides, listPurchases, listReconcileRuns, listSubscriptions, listUsageRuns, listWebhookEvents, readEntitlements, unrestrictedSubjects } from "../admin/read.js";
16
16
  import { PaymentsAuditActions } from "../audit/actions.js";
17
17
  import { nextSubscriptionEvent } from "../data/subscription.js";
18
18
  import { grantEntitlement, revokeEntitlement } from "../entitlement/manual.js";
19
19
  import { fulfillPurchase } from "../grants/apply.js";
20
20
  import { linkProviderAccount, providerAccountForSubject, resolveNotificationOwner } from "../projection/owner.js";
21
+ import { notificationTargets, projectionTargets } from "../projection/targets.js";
21
22
  import { projectPurchase } from "../projection/writer.js";
22
23
  import { repairOrphanedEvents } from "../projection/orphans.js";
23
24
  import { isCheckoutRail, isDiscountRail, isPricingRail, isRefundRail, isSubscriptionRail, noteText } from "../rails/contract.js";
@@ -25,10 +26,10 @@ import { PAYMENTS_PROVIDER_SECRET, paymentsSecretsRegistry } from "../secret/reg
25
26
  import { resolveRailProvider } from "../rails/providers.js";
26
27
  import { PAYMENTS_CAPABILITY, paymentsWorkflows } from "../workflows/specs.js";
27
28
  import { requireAuth } from "./guards.js";
28
- import { PaymentsAdminCatalogResponse, PaymentsAdminDiscountsResponse, PaymentsAdminEntitlementsResponse, PaymentsAdminOverridesResponse, PaymentsAdminPurchasesResponse, PaymentsAdminReconcileRunStarted, PaymentsAdminReconcileRunsResponse, PaymentsAdminSubjectEntitlementsResponse, PaymentsAdminSubscriptionsResponse, PaymentsAdminUsageRunsResponse, PaymentsCheckoutHandoffResponse, PaymentsDiscountResponse, PaymentsEntitlementResponse, PaymentsEntitlementsResponse, PaymentsOverrideResponse, PaymentsPortalHandoffResponse, PaymentsPricingEnvelope, PaymentsPurchaseResponse, PaymentsRefundResponse, PaymentsRestoreResponse, PaymentsSubscriptionQuoteResponse, PaymentsSubscriptionResponse, PaymentsSubscriptionStandingResponse, PaymentsWebhookAck } from "./responses.js";
29
- import { AdminDiscountsQuery, AdminEntitlementsQuery, AdminOverridesQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AdminUsageRunsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, OverrideClearRequest, OverrideSetRequest, OverrideUnrestrictedRequest, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest } from "./schemas.js";
30
- import { PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_DISCOUNT_CREATE_SCOPE, PAYMENTS_DISCOUNT_READ_SCOPE, PAYMENTS_ENTITLEMENTS_READ_SCOPE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_OVERRIDE_CLEAR_SCOPE, PAYMENTS_OVERRIDE_SET_SCOPE, PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE, PAYMENTS_PURCHASES_READ_SCOPE, PAYMENTS_RECONCILE_READ_SCOPE, PAYMENTS_RECONCILE_RUN_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE, PAYMENTS_USAGE_READ_SCOPE } from "./scopes.js";
31
- import { adminAllowancesView, adminCatalogView, adminEntitlementView, adminOverrideView, adminPurchaseView, adminReconcileRunView, adminUsageRunView, entitlementView, overrideView, purchaseView } from "./view.js";
29
+ import { PaymentsAdminCatalogResponse, PaymentsAdminDiscountsResponse, PaymentsAdminEntitlementsResponse, PaymentsAdminOverridesResponse, PaymentsAdminPurchasesResponse, PaymentsAdminReconcileRunStarted, PaymentsAdminReconcileRunsResponse, PaymentsAdminSubjectEntitlementsResponse, PaymentsAdminSubscriptionsResponse, PaymentsAdminUsageRunsResponse, PaymentsAdminWebhookEventsResponse, PaymentsCheckoutHandoffResponse, PaymentsDiscountResponse, PaymentsEntitlementResponse, PaymentsEntitlementsResponse, PaymentsOverrideResponse, PaymentsPortalHandoffResponse, PaymentsPricingEnvelope, PaymentsPurchaseResponse, PaymentsRefundResponse, PaymentsRestoreResponse, PaymentsSubscriptionQuoteResponse, PaymentsSubscriptionResponse, PaymentsSubscriptionStandingResponse, PaymentsWebhookAck } from "./responses.js";
30
+ import { AdminDiscountsQuery, AdminEntitlementsQuery, AdminOverridesQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AdminUsageRunsQuery, AdminWebhookEventsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, OverrideClearRequest, OverrideSetRequest, OverrideUnrestrictedRequest, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest } from "./schemas.js";
31
+ import { PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_DISCOUNT_CREATE_SCOPE, PAYMENTS_DISCOUNT_READ_SCOPE, PAYMENTS_ENTITLEMENTS_READ_SCOPE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_OVERRIDE_CLEAR_SCOPE, PAYMENTS_OVERRIDE_SET_SCOPE, PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE, PAYMENTS_PURCHASES_READ_SCOPE, PAYMENTS_RECONCILE_READ_SCOPE, PAYMENTS_RECONCILE_RUN_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE, PAYMENTS_USAGE_READ_SCOPE, PAYMENTS_WEBHOOKS_READ_SCOPE } from "./scopes.js";
32
+ import { adminAllowancesView, adminCatalogView, adminEntitlementView, adminOverrideView, adminPurchaseView, adminReconcileRunView, adminUsageRunView, adminWebhookEventView, entitlementView, overrideView, purchaseView } from "./view.js";
32
33
  import { completeWebhook, requireSignedWebhook, verifiedWebhook } from "./webhookGuard.js";
33
34
  import { InternalError, NotFoundError, PithyError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
34
35
  import { grantedEntitlementKeys } from "@pithy-sh/core/src/entitlement/entitlement";
@@ -1059,6 +1060,40 @@ function registerPaymentsRoutes(options) {
1059
1060
  }, 200);
1060
1061
  });
1061
1062
  /**
1063
+ * CONTROL PLANE. Every notification a store sent, newest received first (#830).
1064
+ *
1065
+ * **The read that explains the other two revenue-integrity findings.** A purchase paid and not entitled, or
1066
+ * entitled and not paid, is usually a notification that arrived and never projected — and that row was
1067
+ * invisible to every management client. Here it reads as `pending` with its attempts or `abandoned`, never
1068
+ * as missing, and a projected one names the purchase and subscription rows it changed.
1069
+ *
1070
+ * Its own scope. The rows name no subject, but they are every customer's commerce as the stores reported it.
1071
+ * The payload is never selected, and the stored error crosses as its code alone — see `adminWebhookEventView`.
1072
+ */
1073
+ app.get(`${base}/admin/webhook-events`, describeRoute({
1074
+ summary: "Read every notification a store sent, and what became of it.",
1075
+ verification: "control-plane",
1076
+ scopes: [PAYMENTS_WEBHOOKS_READ_SCOPE],
1077
+ responses: { 200: PaymentsAdminWebhookEventsResponse }
1078
+ }), requireControlPlane(PAYMENTS_WEBHOOKS_READ_SCOPE), validate("query", AdminWebhookEventsQuery), async (c) => {
1079
+ const query = c.req.valid("query");
1080
+ const page = await listWebhookEvents(database(c), query);
1081
+ await recordRead(c, PaymentsAuditActions.webhookEventsRead, null, {
1082
+ returned: page.items.length,
1083
+ resumed: query.cursor !== void 0,
1084
+ filters: {
1085
+ rail: query.rail ?? null,
1086
+ state: query.state ?? null,
1087
+ since: query.since?.toISOString() ?? null,
1088
+ until: query.until?.toISOString() ?? null
1089
+ }
1090
+ });
1091
+ return c.json({
1092
+ events: page.items.map(adminWebhookEventView),
1093
+ nextCursor: page.nextCursor
1094
+ }, 200);
1095
+ });
1096
+ /**
1062
1097
  * CONTROL PLANE WRITE. Start a reconciliation pass now.
1063
1098
  *
1064
1099
  * **The counterpart to the read above, and a different power.** Reading the log says whether the nightly
@@ -2265,7 +2300,10 @@ function registerPaymentsRoutes(options) {
2265
2300
  } : outcome.note !== void 0 ? {
2266
2301
  at: now,
2267
2302
  note: outcome.note
2268
- } : { at: now });
2303
+ } : {
2304
+ at: now,
2305
+ targets: NO_WEBHOOK_EVENT_TARGETS
2306
+ });
2269
2307
  await c.var.emit({
2270
2308
  action: PaymentsAuditActions.webhookReceived,
2271
2309
  outcome: outcome.reason === void 0 ? "success" : "failure",
@@ -2318,7 +2356,13 @@ function registerPaymentsRoutes(options) {
2318
2356
  now
2319
2357
  });
2320
2358
  await fulfill(c, projection);
2321
- await completeWebhook(d1, eventRowId, { at: now });
2359
+ await completeWebhook(d1, eventRowId, {
2360
+ at: now,
2361
+ targets: projectionTargets([{
2362
+ projection,
2363
+ eventAt: now
2364
+ }])
2365
+ });
2322
2366
  await c.var.emit({
2323
2367
  action: PaymentsAuditActions.webhookReceived,
2324
2368
  outcome: "success",
@@ -2388,16 +2432,25 @@ function registerPaymentsRoutes(options) {
2388
2432
  severity: "warning"
2389
2433
  });
2390
2434
  }
2391
- if (notification.stateEvent) await projectPurchase(d1, {
2435
+ const standing = notification.stateEvent ? await projectPurchase(d1, {
2392
2436
  ...notification.stateEvent,
2393
2437
  ...subject
2394
2438
  }, {
2395
2439
  config,
2396
2440
  environment: deploymentEnvironment(c),
2397
2441
  now
2398
- });
2442
+ }) : void 0;
2399
2443
  await fulfill(c, projection);
2400
- await completeWebhook(d1, eventRowId, { at: now });
2444
+ await completeWebhook(d1, eventRowId, {
2445
+ at: now,
2446
+ targets: notificationTargets({
2447
+ event: notification.event,
2448
+ projection
2449
+ }, {
2450
+ event: notification.stateEvent,
2451
+ projection: standing
2452
+ })
2453
+ });
2401
2454
  await c.var.emit({
2402
2455
  action: PaymentsAuditActions.webhookReceived,
2403
2456
  outcome: "success",
@@ -432,6 +432,25 @@ export declare const AdminReconcileRunsQuery: z.ZodObject<{
432
432
  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
433
433
  }, z.core.$strip>;
434
434
  export type AdminReconcileRunsQuery = z.output<typeof AdminReconcileRunsQuery>;
435
+ export declare const AdminWebhookEventsQuery: z.ZodObject<{
436
+ rail: z.ZodOptional<z.ZodEnum<{
437
+ apple: "apple";
438
+ google: "google";
439
+ lemonSqueezy: "lemonSqueezy";
440
+ paddle: "paddle";
441
+ stripe: "stripe";
442
+ }>>;
443
+ state: z.ZodOptional<z.ZodEnum<{
444
+ abandoned: "abandoned";
445
+ pending: "pending";
446
+ projected: "projected";
447
+ }>>;
448
+ since: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
449
+ until: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
450
+ cursor: z.ZodOptional<z.ZodString>;
451
+ limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
452
+ }, z.core.$strip>;
453
+ export type AdminWebhookEventsQuery = z.output<typeof AdminWebhookEventsQuery>;
435
454
  export declare const AdminUsageRunsQuery: z.ZodObject<{
436
455
  cursor: z.ZodOptional<z.ZodString>;
437
456
  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"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"}
@@ -397,6 +397,23 @@ const AdminReconcileRunsQuery = z.object({
397
397
  cursor: Cursor,
398
398
  limit: Limit
399
399
  }).describe("The reconciliation-run query: what to narrow it to, and where to resume.");
400
+ /**
401
+ * A window bound, as ISO-8601, decoded to a `Date` by the schema rather than by the handler — the handler takes
402
+ * typed values, so no handler parses a caller's string.
403
+ */
404
+ const WindowBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
405
+ const AdminWebhookEventsQuery = z.object({
406
+ rail: PaymentsRail.optional().describe("Restrict to the notifications one store sent."),
407
+ state: z.enum([
408
+ "projected",
409
+ "pending",
410
+ "abandoned"
411
+ ]).optional().describe("Restrict to one state: `projected` — finished; `pending` — arrived and not finished, tried or not; `abandoned` — a repair pass gave up on it."),
412
+ since: WindowBound.optional().describe("Received at or after this instant, ISO-8601. Inclusive."),
413
+ until: WindowBound.optional().describe("Received before this instant, ISO-8601. Exclusive."),
414
+ cursor: Cursor,
415
+ limit: Limit
416
+ }).refine((query) => query.since === void 0 || query.until === void 0 || query.since < query.until, { message: "`since` must be before `until`. A window that ends before it starts holds nothing." }).describe("The webhook-event query: which store, which state, which window of receipt, and where to resume.");
400
417
  const AdminUsageRunsQuery = z.object({
401
418
  cursor: Cursor,
402
419
  limit: Limit
@@ -435,4 +452,4 @@ const AdminSubjectParam = z.object({
435
452
  */
436
453
  const PaddleResumeQuery = z.object({ transaction: z.string().refine(isPaddleTransactionId, { message: "Not a Paddle transaction id. Expected the `txn_…` Paddle put in `_ptxn`." }).describe("The Paddle transaction to resume — the `_ptxn` value, `txn_…`. Publishable: Paddle itself put it in a URL it mailed to the buyer.") }).describe("The resume read's query: which transaction a Paddle payment link arrived for.");
437
454
  //#endregion
438
- export { AdminDiscountsQuery, AdminEntitlementsQuery, AdminOverridesQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AdminUsageRunsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, OverrideClearRequest, OverrideSetRequest, OverrideUnrestrictedRequest, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest };
455
+ export { AdminDiscountsQuery, AdminEntitlementsQuery, AdminOverridesQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AdminUsageRunsQuery, AdminWebhookEventsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, OverrideClearRequest, OverrideSetRequest, OverrideUnrestrictedRequest, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest };
@@ -1,11 +1,11 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
3
+ import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
4
4
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
5
5
  /**
6
6
  * Payments' control-plane scopes, and the admin surface a manifest advertises.
7
7
  *
8
- * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
8
+ * **Separate from `guards.ts` because a scope name is a client's business**. A management
9
9
  * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
10
10
  * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
11
11
  * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
@@ -47,7 +47,7 @@ export declare const PAYMENTS_DISCOUNT_CREATE_SCOPE: ControlPlaneScope;
47
47
  *
48
48
  * Separate from creating one, and strictly narrower: a pane that lists what was minted does not need the
49
49
  * power to mint. The read exists because the write does — a management client that can create a code and
50
- * never see it leaves a pane computing *absent* rather than blocked, which no grant repairs (#247).
50
+ * never see it leaves a pane computing *absent* rather than blocked, which no grant repairs.
51
51
  */
52
52
  export declare const PAYMENTS_DISCOUNT_READ_SCOPE: ControlPlaneScope;
53
53
  /**
@@ -123,8 +123,7 @@ export declare const PAYMENTS_RECONCILE_READ_SCOPE: ControlPlaneScope;
123
123
  *
124
124
  * **A trigger exists because the cron is not enough.** `pithy payments reconcile` runs the same pass, and it
125
125
  * needs a laptop, a checkout, and a Cloudflare API token for the project — so the answer to "my subscription
126
- * isn't showing up" at 4pm on a Saturday is either this route or nothing until 04:00 UTC. Adopted from
127
- * `pithy-sh/dashboard#96`, where the operator with the run log open had no way to act on it.
126
+ * isn't showing up" at 4pm on a Saturday is either this route or nothing until 04:00 UTC.
128
127
  *
129
128
  * Idempotent by construction, so the scope carries no warning about pressing twice: `reconcilePayments` finds
130
129
  * a reconciled catalog already matching and writes nothing.
@@ -155,6 +154,16 @@ export declare const PAYMENTS_OVERRIDE_CLEAR_SCOPE: ControlPlaneScope;
155
154
  * why. Its own scope, separate from the reconciliation log's: its findings name subjects.
156
155
  */
157
156
  export declare const PAYMENTS_USAGE_READ_SCOPE: ControlPlaneScope;
157
+ /**
158
+ * Read the webhook-event log — every notification a store sent, whether it became a purchase, is still
159
+ * pending with its attempts, or was given up on, and which purchase and subscription rows it changed.
160
+ *
161
+ * Its own scope, and a read in kind. The rows name no subject, but they are a record of every customer's
162
+ * commerce as the stores reported it, so a tool reading them should hold exactly this — not the purchase log,
163
+ * which `scopeCovers` keeps separate. Neither the provider's payload nor the store's sentence about a failure
164
+ * crosses on it: the event's type, its state and the error's code do.
165
+ */
166
+ export declare const PAYMENTS_WEBHOOKS_READ_SCOPE: ControlPlaneScope;
158
167
  /**
159
168
  * Every control-plane scope payments defines — what `pithy dashboard connect` offers for this capability, and
160
169
  * the list a manifest or a doc quotes rather than re-typing. Core's `SEAM_SCOPES` is the same idea for the
@@ -183,5 +192,5 @@ export declare const PAYMENTS_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[]
183
192
  * construction rather than by luck. It also keeps the reads at the shape a management client looks for: a
184
193
  * `GET`, with a declared scope, no `:` segment, ending in the resource's own noun.
185
194
  */
186
- export declare function paymentsAdminRoutes(basePath: string): AdminRoute[];
195
+ export declare function paymentsAdminRoutes(basePath: string): AdminRouteDeclaration[];
187
196
  //# sourceMappingURL=scopes.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/http/scopes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,EAAE,iBAA+C,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAA6C,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,iBAAiD,CAAC;AAEjG;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAAE,iBAAkD,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,iBAAiD,CAAC;AAElG;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,iBAAgD,CAAC;AAEhG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAA2C,CAAC;AAEtF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAA4C,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAA4C,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,EAAE,iBAAqD,CAAC;AAEzG;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,iBAAiB,EAerE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CA6GlE"}
1
+ {"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/http/scopes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,EAAE,iBAA+C,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAA6C,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,iBAAiD,CAAC;AAEjG;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAAE,iBAAkD,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,iBAAiD,CAAC;AAElG;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,iBAAgD,CAAC;AAEhG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAA2C,CAAC;AAEtF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAA4C,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAA4C,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,EAAE,iBAAqD,CAAC;AAEzG;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAA4C,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,iBAAiB,EAgBrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAsJ7E"}
@@ -4,7 +4,7 @@
4
4
  /**
5
5
  * Payments' control-plane scopes, and the admin surface a manifest advertises.
6
6
  *
7
- * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
7
+ * **Separate from `guards.ts` because a scope name is a client's business**. A management
8
8
  * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
9
9
  * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
10
10
  * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
@@ -46,7 +46,7 @@ const PAYMENTS_DISCOUNT_CREATE_SCOPE = "payments:discounts:create";
46
46
  *
47
47
  * Separate from creating one, and strictly narrower: a pane that lists what was minted does not need the
48
48
  * power to mint. The read exists because the write does — a management client that can create a code and
49
- * never see it leaves a pane computing *absent* rather than blocked, which no grant repairs (#247).
49
+ * never see it leaves a pane computing *absent* rather than blocked, which no grant repairs.
50
50
  */
51
51
  const PAYMENTS_DISCOUNT_READ_SCOPE = "payments:discounts:read";
52
52
  /**
@@ -122,8 +122,7 @@ const PAYMENTS_RECONCILE_READ_SCOPE = "payments:reconcile:read";
122
122
  *
123
123
  * **A trigger exists because the cron is not enough.** `pithy payments reconcile` runs the same pass, and it
124
124
  * needs a laptop, a checkout, and a Cloudflare API token for the project — so the answer to "my subscription
125
- * isn't showing up" at 4pm on a Saturday is either this route or nothing until 04:00 UTC. Adopted from
126
- * `pithy-sh/dashboard#96`, where the operator with the run log open had no way to act on it.
125
+ * isn't showing up" at 4pm on a Saturday is either this route or nothing until 04:00 UTC.
127
126
  *
128
127
  * Idempotent by construction, so the scope carries no warning about pressing twice: `reconcilePayments` finds
129
128
  * a reconciled catalog already matching and writes nothing.
@@ -155,6 +154,16 @@ const PAYMENTS_OVERRIDE_CLEAR_SCOPE = "payments:overrides:clear";
155
154
  */
156
155
  const PAYMENTS_USAGE_READ_SCOPE = "payments:usage:read";
157
156
  /**
157
+ * Read the webhook-event log — every notification a store sent, whether it became a purchase, is still
158
+ * pending with its attempts, or was given up on, and which purchase and subscription rows it changed.
159
+ *
160
+ * Its own scope, and a read in kind. The rows name no subject, but they are a record of every customer's
161
+ * commerce as the stores reported it, so a tool reading them should hold exactly this — not the purchase log,
162
+ * which `scopeCovers` keeps separate. Neither the provider's payload nor the store's sentence about a failure
163
+ * crosses on it: the event's type, its state and the error's code do.
164
+ */
165
+ const PAYMENTS_WEBHOOKS_READ_SCOPE = "payments:webhooks:read";
166
+ /**
158
167
  * Every control-plane scope payments defines — what `pithy dashboard connect` offers for this capability, and
159
168
  * the list a manifest or a doc quotes rather than re-typing. Core's `SEAM_SCOPES` is the same idea for the
160
169
  * seam's own routes.
@@ -170,6 +179,7 @@ const PAYMENTS_CONTROL_PLANE_SCOPES = [
170
179
  PAYMENTS_DISCOUNT_READ_SCOPE,
171
180
  PAYMENTS_RECONCILE_READ_SCOPE,
172
181
  PAYMENTS_USAGE_READ_SCOPE,
182
+ PAYMENTS_WEBHOOKS_READ_SCOPE,
173
183
  PAYMENTS_ENTITLEMENT_GRANT_SCOPE,
174
184
  PAYMENTS_ENTITLEMENT_REVOKE_SCOPE,
175
185
  PAYMENTS_OVERRIDE_SET_SCOPE,
@@ -201,101 +211,141 @@ function paymentsAdminRoutes(basePath) {
201
211
  return [
202
212
  {
203
213
  method: "GET",
214
+ operation: "catalog.read",
204
215
  path: `${basePath}/admin/catalog`,
205
216
  scope: PAYMENTS_CATALOG_READ_SCOPE,
217
+ kind: "reads",
206
218
  summary: "What this project sells — each product's id, kind, display name, and the entitlement keys it grants. The list a comp control fills its dropdown from."
207
219
  },
208
220
  {
209
221
  method: "GET",
222
+ operation: "purchases.list",
210
223
  path: `${basePath}/admin/purchases`,
211
224
  scope: PAYMENTS_PURCHASES_READ_SCOPE,
225
+ kind: "reads",
212
226
  summary: "Page the purchase log — every verified transaction, newest first, filtered by holder (both halves of the subject), store, status or store environment."
213
227
  },
214
228
  {
215
229
  method: "GET",
230
+ operation: "subscriptions.list",
216
231
  path: `${basePath}/admin/subscriptions`,
217
232
  scope: PAYMENTS_SUBSCRIPTIONS_READ_SCOPE,
233
+ kind: "reads",
218
234
  summary: "Page the purchases that renew — who is still paying, and when the period they paid for ends."
219
235
  },
220
236
  {
221
237
  method: "GET",
238
+ operation: "entitlements.list",
222
239
  path: `${basePath}/admin/entitlements`,
223
240
  scope: PAYMENTS_ENTITLEMENTS_READ_SCOPE,
241
+ kind: "reads",
224
242
  summary: "Page what accounts hold — whether each entitlement grants right now, and which purchase is the reason."
225
243
  },
226
244
  {
227
245
  method: "GET",
246
+ operation: "entitlements.read",
228
247
  path: `${basePath}/admin/entitlements/:subjectType/:subjectId`,
229
248
  scope: PAYMENTS_ENTITLEMENTS_READ_SCOPE,
249
+ kind: "reads",
230
250
  summary: "Everything one subject is entitled to, resolved now — addressed by both halves, `user`/`organization` and the id. The answer to “why can this person not use what they paid for”."
231
251
  },
232
252
  {
233
253
  method: "GET",
254
+ operation: "discounts.list",
234
255
  path: `${basePath}/admin/discounts`,
235
256
  scope: PAYMENTS_DISCOUNT_READ_SCOPE,
257
+ kind: "reads",
236
258
  summary: "The discount codes this project has issued, read from the store that holds them."
237
259
  },
238
260
  {
239
261
  method: "POST",
262
+ operation: "discounts.create",
240
263
  path: `${basePath}/admin/discounts`,
241
264
  scope: PAYMENTS_DISCOUNT_CREATE_SCOPE,
265
+ kind: "charges",
242
266
  summary: "Mint a discount code at one store, from terms stated in the units a customer experiences."
243
267
  },
244
268
  {
245
269
  method: "GET",
270
+ operation: "reconcile_runs.list",
246
271
  path: `${basePath}/admin/reconcile-runs`,
247
272
  scope: PAYMENTS_RECONCILE_READ_SCOPE,
273
+ kind: "reads",
248
274
  summary: "The reconciliation passes this deployment has run — when each ran, what it compared, and what it had to repair. The answer to whether the nightly repair is still firing."
249
275
  },
250
276
  {
251
277
  method: "POST",
278
+ operation: "reconcile_runs.start",
252
279
  path: `${basePath}/admin/reconcile-runs`,
253
280
  scope: PAYMENTS_RECONCILE_RUN_SCOPE,
281
+ kind: "writes",
254
282
  summary: "Start a reconciliation pass now, rather than waiting for the nightly one. The repair path for a purchase a dropped webhook never projected."
255
283
  },
256
284
  {
257
285
  method: "POST",
286
+ operation: "entitlements.grant",
258
287
  path: `${basePath}/entitlements/grant`,
259
288
  scope: PAYMENTS_ENTITLEMENT_GRANT_SCOPE,
289
+ kind: "charges",
260
290
  summary: "Comp an entitlement, or repair a purchase that verified but never projected."
261
291
  },
262
292
  {
263
293
  method: "POST",
294
+ operation: "entitlements.revoke",
264
295
  path: `${basePath}/entitlements/revoke`,
265
296
  scope: PAYMENTS_ENTITLEMENT_REVOKE_SCOPE,
297
+ kind: "charges",
266
298
  summary: "Take an entitlement back, effective immediately."
267
299
  },
268
300
  {
269
301
  method: "GET",
302
+ operation: "usage_runs.list",
270
303
  path: `${basePath}/admin/usage-runs`,
271
304
  scope: PAYMENTS_USAGE_READ_SCOPE,
305
+ kind: "reads",
272
306
  summary: "The usage-reporting passes this deployment has run — what each reported, and which subjects it skipped and why. The answer to why a quantity-billed customer was not billed."
273
307
  },
274
308
  {
275
309
  method: "GET",
310
+ operation: "webhook_events.list",
311
+ path: `${basePath}/admin/webhook-events`,
312
+ scope: PAYMENTS_WEBHOOKS_READ_SCOPE,
313
+ kind: "reads",
314
+ summary: "Page every notification a store sent — whether it became a purchase, is still pending, or was given up on, and what it changed. The answer to why a purchase is paid and not entitled, or entitled and not paid."
315
+ },
316
+ {
317
+ method: "GET",
318
+ operation: "overrides.list",
276
319
  path: `${basePath}/admin/overrides`,
277
320
  scope: PAYMENTS_ENTITLEMENTS_READ_SCOPE,
321
+ kind: "reads",
278
322
  summary: "Page every subject's override — the numbers negotiated per customer, and which subjects are unrestricted."
279
323
  },
280
324
  {
281
325
  method: "POST",
326
+ operation: "overrides.set",
282
327
  path: `${basePath}/entitlements/overrides`,
283
328
  scope: PAYMENTS_OVERRIDE_SET_SCOPE,
329
+ kind: "charges",
284
330
  summary: "Pin a negotiated number or switch for one subject, with a reason on the record. Merges by name; every other allowance keeps tracking the plan."
285
331
  },
286
332
  {
287
333
  method: "POST",
334
+ operation: "overrides.unrestricted",
288
335
  path: `${basePath}/entitlements/overrides/unrestricted`,
289
336
  scope: PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE,
337
+ kind: "charges",
290
338
  summary: "Grant one subject the whole product — every quota unlimited and every feature on, including names declared later — or take it back."
291
339
  },
292
340
  {
293
341
  method: "POST",
342
+ operation: "overrides.clear",
294
343
  path: `${basePath}/entitlements/overrides/clear`,
295
344
  scope: PAYMENTS_OVERRIDE_CLEAR_SCOPE,
345
+ kind: "charges",
296
346
  summary: "Unpin allowances for one subject, or clear its override entirely. Unpinned names follow the plan again."
297
347
  }
298
348
  ];
299
349
  }
300
350
  //#endregion
301
- export { PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_CONTROL_PLANE_SCOPES, PAYMENTS_DISCOUNT_CREATE_SCOPE, PAYMENTS_DISCOUNT_READ_SCOPE, PAYMENTS_ENTITLEMENTS_READ_SCOPE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_OVERRIDE_CLEAR_SCOPE, PAYMENTS_OVERRIDE_SET_SCOPE, PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE, PAYMENTS_PURCHASES_READ_SCOPE, PAYMENTS_RECONCILE_READ_SCOPE, PAYMENTS_RECONCILE_RUN_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE, PAYMENTS_USAGE_READ_SCOPE, paymentsAdminRoutes };
351
+ export { PAYMENTS_CATALOG_READ_SCOPE, PAYMENTS_CONTROL_PLANE_SCOPES, PAYMENTS_DISCOUNT_CREATE_SCOPE, PAYMENTS_DISCOUNT_READ_SCOPE, PAYMENTS_ENTITLEMENTS_READ_SCOPE, PAYMENTS_ENTITLEMENT_GRANT_SCOPE, PAYMENTS_ENTITLEMENT_REVOKE_SCOPE, PAYMENTS_OVERRIDE_CLEAR_SCOPE, PAYMENTS_OVERRIDE_SET_SCOPE, PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE, PAYMENTS_PURCHASES_READ_SCOPE, PAYMENTS_RECONCILE_READ_SCOPE, PAYMENTS_RECONCILE_RUN_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE, PAYMENTS_USAGE_READ_SCOPE, PAYMENTS_WEBHOOKS_READ_SCOPE, paymentsAdminRoutes };
@@ -1,6 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import type { PaymentsPurchaseRecord } from "../admin/read";
3
+ import type { PaymentsPurchaseRecord, PaymentsWebhookEventListing } from "../admin/read";
4
4
  import { type PaymentsConfig } from "../config/config";
5
5
  import type { PaymentsEntitlement } from "../data/entitlement";
6
6
  import { type PaymentsOverride } from "../data/override";
@@ -8,7 +8,7 @@ import type { PaymentsReconcileRun } from "../data/reconcileRun";
8
8
  import type { PaymentsUsageRun } from "../data/usageRun";
9
9
  import type { ResolvedAllowances } from "../entitlement/allowance";
10
10
  import type { PurchaseProjection } from "../projection/writer";
11
- import type { PaymentsAdminAllowancesView, PaymentsAdminCatalogResponse, PaymentsAdminEntitlementView, PaymentsAdminOverrideView, PaymentsAdminPurchaseView, PaymentsAdminReconcileRunView, PaymentsAdminUsageRunView, PaymentsEntitlementView, PaymentsPurchaseView } from "./responses";
11
+ import type { PaymentsAdminAllowancesView, PaymentsAdminCatalogResponse, PaymentsAdminEntitlementView, PaymentsAdminOverrideView, PaymentsAdminPurchaseView, PaymentsAdminReconcileRunView, PaymentsAdminUsageRunView, PaymentsAdminWebhookEventView, PaymentsEntitlementView, PaymentsPurchaseView } from "./responses";
12
12
  /**
13
13
  * What a client is shown. Nothing in this package ever returns a raw row.
14
14
  *
@@ -94,6 +94,13 @@ export declare function adminPurchaseView(purchase: PaymentsPurchaseRecord, repo
94
94
  export declare function adminEntitlementView(row: PaymentsEntitlement, now: Date, unrestricted?: boolean): PaymentsAdminEntitlementView;
95
95
  /** Project one usage run for a management client. The row's columns, dates as ISO strings. */
96
96
  export declare function adminUsageRunView(run: PaymentsUsageRun): PaymentsAdminUsageRunView;
97
+ /**
98
+ * Project one recorded notification for a management client (#830).
99
+ *
100
+ * The state is derived, the error is reduced to its code, and the targets are copied — so the stored sentence
101
+ * and the payload (which the read never selected) have no field to land in.
102
+ */
103
+ export declare function adminWebhookEventView(event: PaymentsWebhookEventListing): PaymentsAdminWebhookEventView;
97
104
  /** Project one subject's override for a management client, or null when it has none. */
98
105
  export declare function adminOverrideView(row: PaymentsOverride | undefined): PaymentsAdminOverrideView | null;
99
106
  /** Project one override row for a management client. */
@@ -1 +1 @@
1
- {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/http/view.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,oBAAoB,CAcjF;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,WAAW,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB,GAAG,uBAAuB,CAE1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,4BAA4B,CA+BrF;AAED,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,GACvD,yBAAyB,CAyB3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,IAAI,EACT,YAAY,UAAQ,GACnB,4BAA4B,CAY9B;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,yBAAyB,CAclF;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,GAAG,yBAAyB,GAAG,IAAI,CAGrG;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,yBAAyB,CAS7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC5C,2BAA2B,CAsB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,6BAA6B,CAiB9F"}
1
+ {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/http/view.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,oBAAoB,CAcjF;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,WAAW,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB,GAAG,uBAAuB,CAE1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,4BAA4B,CA+BrF;AAED,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,GACvD,yBAAyB,CAyB3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,mBAAmB,EACxB,GAAG,EAAE,IAAI,EACT,YAAY,UAAQ,GACnB,4BAA4B,CAY9B;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,yBAAyB,CAclF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,2BAA2B,GAAG,6BAA6B,CAoBvG;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,GAAG,yBAAyB,GAAG,IAAI,CAGrG;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,yBAAyB,CAS7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC5C,2BAA2B,CAsB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,6BAA6B,CAiB9F"}
package/dist/http/view.js CHANGED
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { compOnlyEntitlements } from "../config/config.js";
4
4
  import { isEmptyOverride } from "../data/override.js";
5
+ import { webhookEventErrorCode, webhookEventReadState } from "../data/webhookEvent.js";
5
6
  //#region src/http/view.ts
6
7
  /**
7
8
  * What a client is shown. Nothing in this package ever returns a raw row.
@@ -180,6 +181,33 @@ function adminUsageRunView(run) {
180
181
  findings: run.findings.map((finding) => ({ ...finding }))
181
182
  };
182
183
  }
184
+ /**
185
+ * Project one recorded notification for a management client (#830).
186
+ *
187
+ * The state is derived, the error is reduced to its code, and the targets are copied — so the stored sentence
188
+ * and the payload (which the read never selected) have no field to land in.
189
+ */
190
+ function adminWebhookEventView(event) {
191
+ const targets = event.projectedTargets ?? null;
192
+ return {
193
+ id: event.id,
194
+ rail: event.rail,
195
+ providerEventId: event.providerEventId,
196
+ eventType: event.eventType,
197
+ receivedAt: event.receivedAt.toISOString(),
198
+ state: webhookEventReadState({
199
+ processedAt: event.processedAt?.getTime() ?? null,
200
+ abandonedAt: event.abandonedAt?.getTime() ?? null,
201
+ error: event.error
202
+ }),
203
+ attempts: event.attempts ?? 0,
204
+ errorCode: webhookEventErrorCode(event.error),
205
+ targets: targets === null ? null : {
206
+ purchaseIds: [...targets.purchaseIds],
207
+ subscriptionIds: [...targets.subscriptionIds]
208
+ }
209
+ };
210
+ }
183
211
  /** Project one subject's override for a management client, or null when it has none. */
184
212
  function adminOverrideView(row) {
185
213
  return row === void 0 || isEmptyOverride(row) ? null : overrideView(row);
@@ -250,4 +278,4 @@ function adminReconcileRunView(run) {
250
278
  };
251
279
  }
252
280
  //#endregion
253
- export { adminAllowancesView, adminCatalogView, adminEntitlementView, adminOverrideView, adminPurchaseView, adminReconcileRunView, adminUsageRunView, entitlementView, overrideView, purchaseView };
281
+ export { adminAllowancesView, adminCatalogView, adminEntitlementView, adminOverrideView, adminPurchaseView, adminReconcileRunView, adminUsageRunView, adminWebhookEventView, entitlementView, overrideView, purchaseView };
@@ -5,6 +5,7 @@ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
5
5
  import type { Context, MiddlewareHandler } from "hono";
6
6
  import type { PaymentsConfig } from "../config/config";
7
7
  import type { PaymentsRail } from "../data/rail";
8
+ import { type PaymentsWebhookEventTargets } from "../data/webhookEvent";
8
9
  import type { VerifiedNotification } from "../rails/contract";
9
10
  import { type RailTrustOptions } from "../rails/providers";
10
11
  /** A verified delivery, as the handler receives it: the notification, and the row recording it. */
@@ -52,7 +53,11 @@ export declare function requireSignedWebhook(rail: PaymentsRail, options: Webhoo
52
53
  /**
53
54
  * What became of a verified delivery, as the handler reports it. **Three cases, because there are three.**
54
55
  *
55
- * `{ at }` — it projected. Finished.
56
+ * `{ at, targets }` — it projected, and these are the purchase and subscription rows it changed (#830).
57
+ * Finished. `targets` is required rather than defaulted: a projecting path that forgot it would record
58
+ * "changed nothing" about an event that changed something, which is the one wrong answer worse than none.
59
+ * A delivery about no transaction at all passes {@link NO_WEBHOOK_EVENT_TARGETS} — it is finished, and it
60
+ * genuinely changed nothing.
56
61
  *
57
62
  * `{ at, note }` — it was never going to project, and here is why. The rail read the notification and said
58
63
  * it carries no transaction state: a partial refund that takes nothing away, a token Play will not show us
@@ -81,6 +86,7 @@ export declare function requireSignedWebhook(rail: PaymentsRail, options: Webhoo
81
86
  */
82
87
  export type WebhookCompletion = {
83
88
  readonly at: Date;
89
+ readonly targets: PaymentsWebhookEventTargets;
84
90
  } | {
85
91
  readonly at: Date;
86
92
  readonly note: string;
@@ -1 +1 @@
1
- {"version":3,"file":"webhookGuard.d.ts","sourceRoot":"","sources":["../../src/http/webhookGuard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAM7E,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AAmGhF,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,+FAA+F;IAC/F,YAAY,EAAE,oBAAoB,CAAC;IACnC,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,eAAe,CAQzE;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,mBAAmB,GAC3B,iBAAiB,CAAC,YAAY,CAAC,CA6GjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAenH"}
1
+ {"version":3,"file":"webhookGuard.d.ts","sourceRoot":"","sources":["../../src/http/webhookGuard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAM7E,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAKL,KAAK,2BAA2B,EAEjC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AAmGhF,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,+FAA+F;IAC/F,YAAY,EAAE,oBAAoB,CAAC;IACnC,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,eAAe,CAQzE;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,mBAAmB,GAC3B,iBAAiB,CAAC,YAAY,CAAC,CA6GjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBnH"}
@@ -1,6 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { PaymentsWebhookEvent, isWebhookEventFinished, webhookEventState } from "../data/webhookEvent.js";
3
+ import { NO_WEBHOOK_EVENT_TARGETS, PaymentsWebhookEvent, encodeWebhookEventTargets, isWebhookEventFinished, webhookEventState } from "../data/webhookEvent.js";
4
4
  import { PAYMENTS_WEBHOOK_EVENTS_TABLE, paymentsDatabase } from "../data/tables.js";
5
5
  import { PaymentsWebhookUnverifiedError } from "../error/errors.js";
6
6
  import { PaymentsAuditActions } from "../audit/actions.js";
@@ -237,7 +237,8 @@ async function completeWebhook(d1, eventRowId, outcome) {
237
237
  const db = paymentsDatabase(d1);
238
238
  await withD1Retry(() => db.updateTable(PAYMENTS_WEBHOOK_EVENTS_TABLE).set({
239
239
  processedAt: repairable ? null : outcome.at.getTime(),
240
- error: "error" in outcome ? outcome.error : "note" in outcome ? outcome.note : null
240
+ error: "error" in outcome ? outcome.error : "note" in outcome ? outcome.note : null,
241
+ ...repairable ? {} : { projectedTargets: encodeWebhookEventTargets("targets" in outcome ? outcome.targets : NO_WEBHOOK_EVENT_TARGETS) }
241
242
  }).where("id", "=", eventRowId).execute());
242
243
  }
243
244
  //#endregion