@pithy-sh/payments 0.3.10 → 0.4.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 (63) hide show
  1. package/README.md +1 -0
  2. package/dist/client/api.d.ts +19 -0
  3. package/dist/client/api.d.ts.map +1 -1
  4. package/dist/client/api.js +26 -1
  5. package/dist/client/hooks.d.ts +43 -0
  6. package/dist/client/hooks.d.ts.map +1 -1
  7. package/dist/client/hooks.js +58 -2
  8. package/dist/client/paddleLink.d.ts +31 -0
  9. package/dist/client/paddleLink.d.ts.map +1 -0
  10. package/dist/client/paddleLink.js +37 -0
  11. package/dist/data/paddleIds.d.ts +28 -0
  12. package/dist/data/paddleIds.d.ts.map +1 -0
  13. package/dist/data/paddleIds.js +73 -0
  14. package/dist/entitlement/unimplementedSubject.d.ts.map +1 -1
  15. package/dist/entitlement/unimplementedSubject.js +3 -2
  16. package/dist/http/responses.d.ts +23 -5
  17. package/dist/http/responses.d.ts.map +1 -1
  18. package/dist/http/responses.js +24 -7
  19. package/dist/http/routes.d.ts +6 -2
  20. package/dist/http/routes.d.ts.map +1 -1
  21. package/dist/http/routes.js +210 -38
  22. package/dist/http/schemas.d.ts +21 -1
  23. package/dist/http/schemas.d.ts.map +1 -1
  24. package/dist/http/schemas.js +20 -2
  25. package/dist/http/webhookGuard.d.ts.map +1 -1
  26. package/dist/http/webhookGuard.js +1 -1
  27. package/dist/rails/paddle/events.d.ts.map +1 -1
  28. package/dist/rails/paddle/events.js +2 -1
  29. package/dist/rails/paddle/refresh.d.ts +10 -5
  30. package/dist/rails/paddle/refresh.d.ts.map +1 -1
  31. package/dist/rails/paddle/refresh.js +8 -5
  32. package/dist/rails/paddle/refund.d.ts.map +1 -1
  33. package/dist/rails/paddle/refund.js +10 -2
  34. package/dist/rails/paddle/subscription.d.ts.map +1 -1
  35. package/dist/rails/paddle/subscription.js +8 -3
  36. package/dist/rails/paddle/verify.d.ts.map +1 -1
  37. package/dist/rails/paddle/verify.js +2 -3
  38. package/dist/secret/registry.d.ts.map +1 -1
  39. package/dist/secret/registry.js +3 -2
  40. package/dist/version.generated.d.ts +1 -1
  41. package/dist/version.generated.d.ts.map +1 -1
  42. package/dist/version.generated.js +1 -1
  43. package/dist/workflows/workerConfig.d.ts.map +1 -1
  44. package/dist/workflows/workerConfig.js +8 -2
  45. package/docs/paddle.md +17 -2
  46. package/package.json +6 -6
  47. package/src/client/api.ts +35 -0
  48. package/src/client/hooks.ts +78 -0
  49. package/src/client/paddleLink.ts +41 -0
  50. package/src/data/paddleIds.ts +74 -0
  51. package/src/entitlement/unimplementedSubject.ts +3 -4
  52. package/src/http/responses.ts +33 -6
  53. package/src/http/routes.ts +729 -454
  54. package/src/http/schemas.ts +32 -1
  55. package/src/http/webhookGuard.ts +3 -2
  56. package/src/rails/paddle/events.ts +2 -1
  57. package/src/rails/paddle/refresh.ts +17 -10
  58. package/src/rails/paddle/refund.ts +10 -2
  59. package/src/rails/paddle/subscription.ts +8 -3
  60. package/src/rails/paddle/verify.ts +6 -4
  61. package/src/secret/registry.ts +3 -2
  62. package/src/version.generated.ts +1 -1
  63. package/src/workflows/workerConfig.ts +9 -3
@@ -27,6 +27,8 @@ import { type RailTrustOptions } from "../rails/providers";
27
27
  * (bearer | session) —
28
28
  * POST /payments/checkout → a hosted checkout, on whichever rail sells the product
29
29
  * (bearer | session) json: CheckoutRequest
30
+ * GET /payments/checkout/resume → open the transaction a `_ptxn` link arrived for
31
+ * (none) query: PaddleResumeQuery
30
32
  * POST /payments/portal → a billing-portal session (bearer | session) —
31
33
  * GET /payments/subscription → where the caller's subscription stands, read live
32
34
  * (bearer | session) —
@@ -93,8 +95,10 @@ import { type RailTrustOptions } from "../rails/providers";
93
95
  * selects a verifier through `resolveRailProvider`, and everything past that point is the normalized event. A
94
96
  * rail arriving is one entry in `rails/providers.ts`, not a case in a handler.
95
97
  *
96
- * **No `public` routes, ever.** Every caller is either an authenticated user acting on their own purchases or a
97
- * machine proving authenticity. Turnstile has nothing to gate here.
98
+ * **One `public` route, and only one.** `GET /checkout/resume` opens the transaction a Paddle payment link
99
+ * arrived for, and the person following that link may not be signed in. Every other caller is either an
100
+ * authenticated user acting on their own purchases or a machine proving authenticity. Turnstile has nothing
101
+ * to gate here.
98
102
  *
99
103
  * **`signed-webhook` is one strategy over three unrelated mechanisms** — Apple signs a JWS against its
100
104
  * certificate chain, Google's Pub/Sub push carries an OIDC token verified with an audience check, Stripe sends
@@ -1 +1 @@
1
- {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAU7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,KAAK,mBAAmB,EAAkD,MAAM,4BAA4B,CAAC;AAUtH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAiB/D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AA2EhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsJG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAC;CAC/C;AA2JD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,qCAAqC;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,4GAA4G;IAC5G,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,GACD;IACE,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAmBtC;AAkPD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAk/DxG"}
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAW7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,KAAK,mBAAmB,EAAkD,MAAM,4BAA4B,CAAC;AAUtH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAiB/D,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,oBAAoB,CAAC;AA6EhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0JG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAC;CAC/C;AA2JD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,qCAAqC;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,4GAA4G;IAC5G,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,GACD;IACE,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAmBtC;AAkPD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA+vExG"}
@@ -22,16 +22,17 @@ import { PAYMENTS_PROVIDER_SECRET, paymentsSecretsRegistry } from "../secret/reg
22
22
  import { resolveRailProvider } from "../rails/providers.js";
23
23
  import { PAYMENTS_CAPABILITY, paymentsWorkflows } from "../workflows/specs.js";
24
24
  import { requireAuth } from "./guards.js";
25
- import { AdminDiscountsQuery, AdminEntitlementsQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest } from "./schemas.js";
25
+ import { PaymentsAdminCatalogResponse, PaymentsAdminDiscountsResponse, PaymentsAdminEntitlementsResponse, PaymentsAdminPurchasesResponse, PaymentsAdminReconcileRunStarted, PaymentsAdminReconcileRunsResponse, PaymentsAdminSubjectEntitlementsResponse, PaymentsAdminSubscriptionsResponse, PaymentsCheckoutHandoffResponse, PaymentsDiscountResponse, PaymentsEntitlementResponse, PaymentsEntitlementsResponse, PaymentsPortalHandoffResponse, PaymentsPricingEnvelope, PaymentsPurchaseResponse, PaymentsRefundResponse, PaymentsRestoreResponse, PaymentsSubscriptionQuoteResponse, PaymentsSubscriptionResponse, PaymentsSubscriptionStandingResponse, PaymentsWebhookAck } from "./responses.js";
26
+ import { AdminDiscountsQuery, AdminEntitlementsQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest } from "./schemas.js";
26
27
  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_PURCHASES_READ_SCOPE, PAYMENTS_RECONCILE_READ_SCOPE, PAYMENTS_RECONCILE_RUN_SCOPE, PAYMENTS_SUBSCRIPTIONS_READ_SCOPE } from "./scopes.js";
27
28
  import { adminCatalogView, adminEntitlementView, adminPurchaseView, adminReconcileRunView, entitlementView, purchaseView } from "./view.js";
28
29
  import { completeWebhook, requireSignedWebhook, verifiedWebhook } from "./webhookGuard.js";
29
30
  import { InternalError, NotFoundError, PithyError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
30
- import { zValidator } from "@hono/zod-validator";
31
31
  import { safeEmit } from "@pithy-sh/core/src/controlPlane/audit/actions";
32
32
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
33
33
  import { memoryJwksCache } from "@pithy-sh/core/src/http/oidcWebhook";
34
- import { validationHook } from "@pithy-sh/core/src/http/validation";
34
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
35
+ import { validate } from "@pithy-sh/core/src/http/validation";
35
36
  import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
36
37
  import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
37
38
  //#region src/http/routes.ts
@@ -784,7 +785,12 @@ function registerPaymentsRoutes(options) {
784
785
  * No query at all, and none to add: the catalog is small, fixed at deploy, and has no page. What
785
786
  * crosses is decided by `adminCatalogView` and asserted as an invariant rather than as a field list.
786
787
  */
787
- app.get(`${base}/admin/catalog`, requireControlPlane(PAYMENTS_CATALOG_READ_SCOPE), async (c) => {
788
+ app.get(`${base}/admin/catalog`, describeRoute({
789
+ summary: "Read what this project sells, and the keys it comps by hand.",
790
+ verification: "control-plane",
791
+ scopes: [PAYMENTS_CATALOG_READ_SCOPE],
792
+ responses: { 200: PaymentsAdminCatalogResponse }
793
+ }), requireControlPlane(PAYMENTS_CATALOG_READ_SCOPE), async (c) => {
788
794
  const view = adminCatalogView(config);
789
795
  await recordRead(c, PaymentsAuditActions.catalogRead, null, { products: view.enabled ? view.products.length : 0 });
790
796
  return c.json(view, 200);
@@ -797,7 +803,12 @@ function registerPaymentsRoutes(options) {
797
803
  * would have been needed for. `environment` is unfiltered by default on purpose — hiding sandbox
798
804
  * transactions would hide the single thing an operator most needs to notice on a production board.
799
805
  */
800
- app.get(`${base}/admin/purchases`, requireControlPlane(PAYMENTS_PURCHASES_READ_SCOPE), zValidator("query", AdminPurchasesQuery, validationHook), async (c) => {
806
+ app.get(`${base}/admin/purchases`, describeRoute({
807
+ summary: "Read the purchase log, newest first.",
808
+ verification: "control-plane",
809
+ scopes: [PAYMENTS_PURCHASES_READ_SCOPE],
810
+ responses: { 200: PaymentsAdminPurchasesResponse }
811
+ }), requireControlPlane(PAYMENTS_PURCHASES_READ_SCOPE), validate("query", AdminPurchasesQuery), async (c) => {
801
812
  const query = c.req.valid("query");
802
813
  const subject = subjectFilter(query);
803
814
  const page = await listPurchases(database(c), {
@@ -829,7 +840,12 @@ function registerPaymentsRoutes(options) {
829
840
  * is applied by `listSubscriptions` rather than by a `type` filter the request could name, so the
830
841
  * wider read is not reachable through this scope by construction.
831
842
  */
832
- app.get(`${base}/admin/subscriptions`, requireControlPlane(PAYMENTS_SUBSCRIPTIONS_READ_SCOPE), zValidator("query", AdminSubscriptionsQuery, validationHook), async (c) => {
843
+ app.get(`${base}/admin/subscriptions`, describeRoute({
844
+ summary: "Read the purchases that renew, newest first.",
845
+ verification: "control-plane",
846
+ scopes: [PAYMENTS_SUBSCRIPTIONS_READ_SCOPE],
847
+ responses: { 200: PaymentsAdminSubscriptionsResponse }
848
+ }), requireControlPlane(PAYMENTS_SUBSCRIPTIONS_READ_SCOPE), validate("query", AdminSubscriptionsQuery), async (c) => {
833
849
  const query = c.req.valid("query");
834
850
  const subject = subjectFilter(query);
835
851
  const page = await listSubscriptions(database(c), {
@@ -857,7 +873,12 @@ function registerPaymentsRoutes(options) {
857
873
  * resolves it. A dashboard that recomputed it from the stored flag would eventually disagree with that
858
874
  * gate, and the customer would believe the dashboard.
859
875
  */
860
- app.get(`${base}/admin/entitlements`, requireControlPlane(PAYMENTS_ENTITLEMENTS_READ_SCOPE), zValidator("query", AdminEntitlementsQuery, validationHook), async (c) => {
876
+ app.get(`${base}/admin/entitlements`, describeRoute({
877
+ summary: "Read the entitlement model, page by page.",
878
+ verification: "control-plane",
879
+ scopes: [PAYMENTS_ENTITLEMENTS_READ_SCOPE],
880
+ responses: { 200: PaymentsAdminEntitlementsResponse }
881
+ }), requireControlPlane(PAYMENTS_ENTITLEMENTS_READ_SCOPE), validate("query", AdminEntitlementsQuery), async (c) => {
861
882
  const query = c.req.valid("query");
862
883
  const now = clock();
863
884
  const subject = subjectFilter(query);
@@ -894,7 +915,12 @@ function registerPaymentsRoutes(options) {
894
915
  * its absence is not a missing holder — and a 404 would make this surface an existence oracle for user and
895
916
  * organization ids alike.
896
917
  */
897
- app.get(`${base}/admin/entitlements/:subjectType/:subjectId`, requireControlPlane(PAYMENTS_ENTITLEMENTS_READ_SCOPE), zValidator("param", AdminSubjectParam, validationHook), async (c) => {
918
+ app.get(`${base}/admin/entitlements/:subjectType/:subjectId`, describeRoute({
919
+ summary: "Read one subject's entitlements, resolved now.",
920
+ verification: "control-plane",
921
+ scopes: [PAYMENTS_ENTITLEMENTS_READ_SCOPE],
922
+ responses: { 200: PaymentsAdminSubjectEntitlementsResponse }
923
+ }), requireControlPlane(PAYMENTS_ENTITLEMENTS_READ_SCOPE), validate("param", AdminSubjectParam), async (c) => {
898
924
  const subject = c.req.valid("param");
899
925
  const now = clock();
900
926
  const rows = await readEntitlements(database(c), subject);
@@ -918,7 +944,12 @@ function registerPaymentsRoutes(options) {
918
944
  * Its own scope: a run names no account, no transaction and no amount, so a health monitor can be granted
919
945
  * exactly this without acquiring the purchase log.
920
946
  */
921
- app.get(`${base}/admin/reconcile-runs`, requireControlPlane(PAYMENTS_RECONCILE_READ_SCOPE), zValidator("query", AdminReconcileRunsQuery, validationHook), async (c) => {
947
+ app.get(`${base}/admin/reconcile-runs`, describeRoute({
948
+ summary: "Read the reconciliation passes this deployment has run.",
949
+ verification: "control-plane",
950
+ scopes: [PAYMENTS_RECONCILE_READ_SCOPE],
951
+ responses: { 200: PaymentsAdminReconcileRunsResponse }
952
+ }), requireControlPlane(PAYMENTS_RECONCILE_READ_SCOPE), validate("query", AdminReconcileRunsQuery), async (c) => {
922
953
  const query = c.req.valid("query");
923
954
  const page = await listReconcileRuns(database(c), query);
924
955
  await recordRead(c, PaymentsAuditActions.reconcileRunsRead, null, {
@@ -952,10 +983,15 @@ function registerPaymentsRoutes(options) {
952
983
  * pass happen, and answering 202 while nothing started is the failure this codebase spends its comments
953
984
  * avoiding — so the binding is resolved directly and its absence is a refusal naming what to deploy.
954
985
  *
955
- * Idempotent, like the pass itself. A second press while one is in flight starts nothing and says
956
- * `started: false`, which is a true sentence rather than a 409 that reads as a fault.
986
+ * Every press that is not refused starts a pass and answers `started: true`. A second press while one is
987
+ * in flight starts a second: the pass is idempotent, so two converge on the same repairs.
957
988
  */
958
- app.post(`${base}/admin/reconcile-runs`, requireControlPlane(PAYMENTS_RECONCILE_RUN_SCOPE), async (c) => {
989
+ app.post(`${base}/admin/reconcile-runs`, describeRoute({
990
+ summary: "Start a reconciliation pass now.",
991
+ verification: "control-plane",
992
+ scopes: [PAYMENTS_RECONCILE_RUN_SCOPE],
993
+ responses: { 202: PaymentsAdminReconcileRunStarted }
994
+ }), requireControlPlane(PAYMENTS_RECONCILE_RUN_SCOPE), async (c) => {
959
995
  const spec = paymentsWorkflows.reconcile;
960
996
  const binding = resolveWorkflowBinding(c.env, {
961
997
  binding: spec.binding,
@@ -986,7 +1022,11 @@ function registerPaymentsRoutes(options) {
986
1022
  * existing purchase — the write path is idempotent, so a repeat is not an error. A receipt belonging to
987
1023
  * somebody else is a 409, audited as denied.
988
1024
  */
989
- app.post(`${base}/purchases`, requireAuth(), zValidator("json", PurchaseSubmission, validationHook), async (c) => {
1025
+ app.post(`${base}/purchases`, describeRoute({
1026
+ summary: "Verify a receipt and project the purchase.",
1027
+ verification: ["bearer", "session"],
1028
+ responses: { 200: PaymentsPurchaseResponse }
1029
+ }), requireAuth(), validate("json", PurchaseSubmission), async (c) => {
990
1030
  const input = c.req.valid("json");
991
1031
  const subject = await requirePaymentsSubject(c, seam);
992
1032
  try {
@@ -1044,7 +1084,11 @@ function registerPaymentsRoutes(options) {
1044
1084
  * already answers for somebody who has bought nothing — and a 403 here would make a paywall render an
1045
1085
  * error where it should render the paywall.
1046
1086
  */
1047
- app.get(`${base}/entitlements`, requireAuth(), async (c) => {
1087
+ app.get(`${base}/entitlements`, describeRoute({
1088
+ summary: "Read the caller's own entitlements.",
1089
+ verification: ["bearer", "session"],
1090
+ responses: { 200: PaymentsEntitlementsResponse }
1091
+ }), requireAuth(), async (c) => {
1048
1092
  const subject = await resolvePaymentsSubject(c, seam);
1049
1093
  if (subject === void 0) return c.json({ entitlements: [] }, 200);
1050
1094
  const entitlements = await resolveEntitlements(paymentsDatabase(database(c)), subject, clock());
@@ -1059,7 +1103,11 @@ function registerPaymentsRoutes(options) {
1059
1103
  * success would hide it. Every receipt that did project stays projected — the writer is idempotent, so the
1060
1104
  * client simply retries.
1061
1105
  */
1062
- app.post(`${base}/restore`, requireAuth(), zValidator("json", RestoreRequest, validationHook), async (c) => {
1106
+ app.post(`${base}/restore`, describeRoute({
1107
+ summary: "Restore purchases onto the caller's own holder.",
1108
+ verification: ["bearer", "session"],
1109
+ responses: { 200: PaymentsRestoreResponse }
1110
+ }), requireAuth(), validate("json", RestoreRequest), async (c) => {
1063
1111
  const input = c.req.valid("json");
1064
1112
  const subject = await requirePaymentsSubject(c, seam);
1065
1113
  const purchases = [];
@@ -1086,11 +1134,15 @@ function registerPaymentsRoutes(options) {
1086
1134
  /**
1087
1135
  * SIGNED WEBHOOK — Apple. App Store Server Notifications V2, signed as a JWS against Apple's pinned chain.
1088
1136
  */
1089
- app.post(`${base}/webhooks/apple`, requireSignedWebhook("apple", {
1137
+ app.post(`${base}/webhooks/apple`, describeRoute({
1138
+ summary: "Receive an App Store Server Notification.",
1139
+ verification: "signed-webhook",
1140
+ responses: { 200: PaymentsWebhookAck }
1141
+ }), requireSignedWebhook("apple", {
1090
1142
  config,
1091
1143
  now: clock,
1092
1144
  trust
1093
- }), zValidator("json", AppleWebhookNotification, validationHook), webhookHandler("apple"));
1145
+ }), validate("json", AppleWebhookNotification), webhookHandler("apple"));
1094
1146
  /**
1095
1147
  * SIGNED WEBHOOK — Google. A Pub/Sub push whose OIDC token the guard verified, audience and all.
1096
1148
  *
@@ -1098,11 +1150,15 @@ function registerPaymentsRoutes(options) {
1098
1150
  * already turned Play's pointer into a normalized event through the Play Developer API, so there is nothing
1099
1151
  * Google-shaped left to branch on.
1100
1152
  */
1101
- app.post(`${base}/webhooks/google`, requireSignedWebhook("google", {
1153
+ app.post(`${base}/webhooks/google`, describeRoute({
1154
+ summary: "Receive a Play notification, pushed through Pub/Sub.",
1155
+ verification: "signed-webhook",
1156
+ responses: { 200: PaymentsWebhookAck }
1157
+ }), requireSignedWebhook("google", {
1102
1158
  config,
1103
1159
  now: clock,
1104
1160
  trust
1105
- }), zValidator("json", GoogleWebhookNotification, validationHook), webhookHandler("google"));
1161
+ }), validate("json", GoogleWebhookNotification), webhookHandler("google"));
1106
1162
  /**
1107
1163
  * SIGNED WEBHOOK — Stripe. An HMAC in `Stripe-Signature`, over the exact received bytes and dated, which the
1108
1164
  * guard has checked inside the replay window before this validator ever parses the body.
@@ -1111,11 +1167,15 @@ function registerPaymentsRoutes(options) {
1111
1167
  * this is where most Stripe purchases enter the system — and it is still nothing but a verified notification
1112
1168
  * by the time the handler runs.
1113
1169
  */
1114
- app.post(`${base}/webhooks/stripe`, requireSignedWebhook("stripe", {
1170
+ app.post(`${base}/webhooks/stripe`, describeRoute({
1171
+ summary: "Receive a Stripe event.",
1172
+ verification: "signed-webhook",
1173
+ responses: { 200: PaymentsWebhookAck }
1174
+ }), requireSignedWebhook("stripe", {
1115
1175
  config,
1116
1176
  now: clock,
1117
1177
  trust
1118
- }), zValidator("json", StripeWebhookNotification, validationHook), webhookHandler("stripe"));
1178
+ }), validate("json", StripeWebhookNotification), webhookHandler("stripe"));
1119
1179
  /**
1120
1180
  * SIGNED WEBHOOK — Lemon Squeezy. A bare HMAC in `X-Signature`, over the exact received bytes, which the
1121
1181
  * guard has checked before this validator ever parses the body.
@@ -1129,11 +1189,15 @@ function registerPaymentsRoutes(options) {
1129
1189
  * has no client-submission path at all: its order ids are sequential integers, so no submitted receipt
1130
1190
  * could be trusted.
1131
1191
  */
1132
- app.post(`${base}/webhooks/lemon-squeezy`, requireSignedWebhook("lemonSqueezy", {
1192
+ app.post(`${base}/webhooks/lemon-squeezy`, describeRoute({
1193
+ summary: "Receive a Lemon Squeezy event.",
1194
+ verification: "signed-webhook",
1195
+ responses: { 200: PaymentsWebhookAck }
1196
+ }), requireSignedWebhook("lemonSqueezy", {
1133
1197
  config,
1134
1198
  now: clock,
1135
1199
  trust
1136
- }), zValidator("json", LemonSqueezyWebhookNotification, validationHook), webhookHandler("lemonSqueezy"));
1200
+ }), validate("json", LemonSqueezyWebhookNotification), webhookHandler("lemonSqueezy"));
1137
1201
  /**
1138
1202
  * SIGNED WEBHOOK — Paddle. `Paddle-Signature: ts=…;h1=…`, an HMAC-SHA256 over `${ts}:${exact received
1139
1203
  * bytes}`, which the guard has checked inside the freshness window before this validator ever parses the
@@ -1149,11 +1213,15 @@ function registerPaymentsRoutes(options) {
1149
1213
  * Squeezy this rail has a submittable receipt, because a `txn_…` checked against a *proven* ownership
1150
1214
  * stamp is safe where an unguessable order id is not.
1151
1215
  */
1152
- app.post(`${base}/webhooks/paddle`, requireSignedWebhook("paddle", {
1216
+ app.post(`${base}/webhooks/paddle`, describeRoute({
1217
+ summary: "Receive a Paddle event.",
1218
+ verification: "signed-webhook",
1219
+ responses: { 200: PaymentsWebhookAck }
1220
+ }), requireSignedWebhook("paddle", {
1153
1221
  config,
1154
1222
  now: clock,
1155
1223
  trust
1156
- }), zValidator("json", PaddleWebhookNotification, validationHook), webhookHandler("paddle"));
1224
+ }), validate("json", PaddleWebhookNotification), webhookHandler("paddle"));
1157
1225
  /**
1158
1226
  * AUTHED WRITE — Stripe only. Create a hosted Checkout Session and hand back where to send the browser.
1159
1227
  *
@@ -1167,7 +1235,11 @@ function registerPaymentsRoutes(options) {
1167
1235
  * be charged as, and refusing before the 404 keeps this from answering what a project sells to somebody it
1168
1236
  * cannot bill.
1169
1237
  */
1170
- app.post(`${base}/checkout`, requireAuth(), zValidator("json", CheckoutRequest, validationHook), async (c) => {
1238
+ app.post(`${base}/checkout`, describeRoute({
1239
+ summary: "Start a hosted checkout for one catalog product.",
1240
+ verification: ["bearer", "session"],
1241
+ responses: { 200: PaymentsCheckoutHandoffResponse }
1242
+ }), requireAuth(), validate("json", CheckoutRequest), async (c) => {
1171
1243
  const input = c.req.valid("json");
1172
1244
  const subject = await requirePaymentsSubject(c, seam);
1173
1245
  const entry = product(config, input.productId);
@@ -1207,13 +1279,65 @@ function registerPaymentsRoutes(options) {
1207
1279
  return c.json(handoff, 200);
1208
1280
  });
1209
1281
  /**
1282
+ * PUBLIC READ — Paddle only. What a page needs to resume a transaction Paddle itself created.
1283
+ *
1284
+ * **`#680`.** Paddle appends `?_ptxn=<transaction_id>` to a seller's *Default payment link* and expects
1285
+ * the page it lands on to open a checkout for that transaction. Those links are the ones Paddle sends
1286
+ * rather than the ones this kit opens — a past-due dunning mail, a manually-collected invoice, the
1287
+ * payment-method-update link minted for a subscription — and until this route existed the kit could not
1288
+ * use one: `POST {base}/checkout` mints a transaction, and here the transaction already exists.
1289
+ *
1290
+ * **Unauthenticated, and that is the point rather than an oversight.** The buyer following a dunning
1291
+ * link is frequently signed out — that is the population this serves, so `requireAuth()` would break it
1292
+ * for exactly them. It is safe because it discloses nothing: `clientToken` is publishable by design,
1293
+ * `environment`, `displayMode` and `successUrl` are config constants identical for every transaction,
1294
+ * and the id is the caller's own, echoed. The sum of what a stranger learns is this project's Paddle
1295
+ * account, which every pricing page already ships.
1296
+ *
1297
+ * **It must never read the transaction from Paddle**, and that is the one line to defend in review. A
1298
+ * lookup would turn an unauthenticated route into an oracle for whether a transaction id exists, and
1299
+ * then for what it costs. Shape is checked; existence is Paddle's to tell the buyer, inside the
1300
+ * checkout, where it is already their own transaction.
1301
+ *
1302
+ * **Nothing about a session is read, structurally.** No `requireAuth`, no `requirePaymentsSubject`, and
1303
+ * `PaddleResumeQuery` has no holder field for one — so a resume cannot stamp the current user onto a
1304
+ * transaction that arrived in a URL, which is the way this route could have been used to claim somebody
1305
+ * else's payment.
1306
+ *
1307
+ * **`hosted` refuses.** In that mode this kit never opens a checkout in the page: it redirects to
1308
+ * Paddle's own, at a URL only a transaction read would yield — the read this route may not do. A buyer
1309
+ * on a hosted-mode project is already on Paddle's page, so there is nothing here to resume.
1310
+ */
1311
+ app.get(`${base}/checkout/resume`, describeRoute({
1312
+ summary: "Resume a Paddle transaction a payment link arrived for.",
1313
+ verification: "public",
1314
+ responses: { 200: PaymentsCheckoutHandoffResponse }
1315
+ }), validate("query", PaddleResumeQuery), (c) => {
1316
+ const { transaction } = c.req.valid("query");
1317
+ if (config.paddle === void 0) throw new PaymentsRailNotConfiguredError({ detail: "The paddle rail is off in this project's config, so there is no payment link to resume." });
1318
+ if (config.paddle.checkout === "hosted") throw new PaymentsRailNotConfiguredError({ detail: "This project runs `paddle.checkout: \"hosted\"`, which redirects to Paddle's own checkout rather than opening one in the page, so a `_ptxn` arrival has nothing to resume here." });
1319
+ const handoff = {
1320
+ kind: "paddle",
1321
+ transactionId: transaction,
1322
+ clientToken: config.paddle.clientToken,
1323
+ environment: config.paddle.environment,
1324
+ displayMode: config.paddle.checkout,
1325
+ successUrl: config.paddle.successUrl
1326
+ };
1327
+ return c.json(handoff, 200);
1328
+ });
1329
+ /**
1210
1330
  * AUTHED WRITE — Stripe only. Open the Billing Portal for the caller's own store account.
1211
1331
  *
1212
1332
  * No body at all, and that is the request contract: there is exactly one customer this caller may manage,
1213
1333
  * and it comes from the provider-account map. A `customer` field here would be the whole vulnerability —
1214
1334
  * any signed-in caller could open a session against somebody else's billing history and cancel it.
1215
1335
  */
1216
- app.post(`${base}/portal`, requireAuth(), async (c) => {
1336
+ app.post(`${base}/portal`, describeRoute({
1337
+ summary: "Open the billing portal for the caller's own store account.",
1338
+ verification: ["bearer", "session"],
1339
+ responses: { 200: PaymentsPortalHandoffResponse }
1340
+ }), requireAuth(), async (c) => {
1217
1341
  const subject = await requirePaymentsSubject(c, seam);
1218
1342
  const enabled = PAYMENTS_HOSTED_RAILS.filter((rail) => railEnabled(config, rail));
1219
1343
  if (enabled.length === 0) throw new PaymentsRailNotConfiguredError({ detail: "No hosted-checkout rail is on in this project's config, so there is no billing portal to open. Enable `rails.stripe`, `rails.lemonSqueezy`, or `rails.paddle`." });
@@ -1298,7 +1422,11 @@ function registerPaymentsRoutes(options) {
1298
1422
  * bought anything has no pricing and may still have no customer, and somebody mid-subscription has
1299
1423
  * both. Nesting one in the other would make the common case unreachable.
1300
1424
  */
1301
- app.get(`${base}/pricing`, requireAuth(), async (c) => {
1425
+ app.get(`${base}/pricing`, describeRoute({
1426
+ summary: "Read what the caller's own subscription pays, and when that changes.",
1427
+ verification: ["bearer", "session"],
1428
+ responses: { 200: PaymentsPricingEnvelope }
1429
+ }), requireAuth(), async (c) => {
1302
1430
  const subject = await resolvePaymentsSubject(c, seam);
1303
1431
  if (subject === void 0) return c.json({
1304
1432
  pricing: null,
@@ -1357,7 +1485,11 @@ function registerPaymentsRoutes(options) {
1357
1485
  * shape of this request that reads somebody else's. Nobody resolved is the empty answer rather than a
1358
1486
  * refusal, which is the read half of the seam's rule and what `GET {base}/entitlements` already does.
1359
1487
  */
1360
- app.get(`${base}/subscription`, requireAuth(), async (c) => {
1488
+ app.get(`${base}/subscription`, describeRoute({
1489
+ summary: "Read where the caller's own subscription stands, live from the store.",
1490
+ verification: ["bearer", "session"],
1491
+ responses: { 200: PaymentsSubscriptionResponse }
1492
+ }), requireAuth(), async (c) => {
1361
1493
  const subject = await resolvePaymentsSubject(c, seam);
1362
1494
  if (subject === void 0) return c.json({ subscription: null }, 200);
1363
1495
  const target = await changeableSubscription(database(c), subject, clock());
@@ -1392,7 +1524,11 @@ function registerPaymentsRoutes(options) {
1392
1524
  * `payments/subject_unresolved` says exactly that, where a 404 would claim the caller has no
1393
1525
  * subscription anywhere.
1394
1526
  */
1395
- app.post(`${base}/subscription/preview`, requireAuth(), zValidator("json", SubscriptionPreviewRequest, validationHook), async (c) => {
1527
+ app.post(`${base}/subscription/preview`, describeRoute({
1528
+ summary: "Preview what moving to one catalog product would cost.",
1529
+ verification: ["bearer", "session"],
1530
+ responses: { 200: PaymentsSubscriptionQuoteResponse }
1531
+ }), requireAuth(), validate("json", SubscriptionPreviewRequest), async (c) => {
1396
1532
  const input = c.req.valid("json");
1397
1533
  const subject = await requirePaymentsSubject(c, seam);
1398
1534
  const purchase = requireOneSubscription(await changeableSubscription(database(c), subject, clock()));
@@ -1434,7 +1570,11 @@ function registerPaymentsRoutes(options) {
1434
1570
  * its own row rather than from the rail, which reports no such flag, and the residual gap is stated at
1435
1571
  * {@link changedPlan}.
1436
1572
  */
1437
- app.post(`${base}/subscription/change`, requireAuth(), zValidator("json", SubscriptionChangeRequest, validationHook), async (c) => {
1573
+ app.post(`${base}/subscription/change`, describeRoute({
1574
+ summary: "Move the caller's own subscription onto one catalog product.",
1575
+ verification: ["bearer", "session"],
1576
+ responses: { 200: PaymentsSubscriptionStandingResponse }
1577
+ }), requireAuth(), validate("json", SubscriptionChangeRequest), async (c) => {
1438
1578
  const input = c.req.valid("json");
1439
1579
  const subject = await requirePaymentsSubject(c, seam);
1440
1580
  const purchase = requireOneSubscription(await changeableSubscription(database(c), subject, clock()));
@@ -1489,7 +1629,11 @@ function registerPaymentsRoutes(options) {
1489
1629
  *
1490
1630
  * Writes no purchase row, as every route here does not: the webhook owns it.
1491
1631
  */
1492
- app.post(`${base}/subscription/cancel`, requireAuth(), zValidator("json", SubscriptionCancelRequest, validationHook), async (c) => {
1632
+ app.post(`${base}/subscription/cancel`, describeRoute({
1633
+ summary: "Stop the caller's own subscription renewing.",
1634
+ verification: ["bearer", "session"],
1635
+ responses: { 200: PaymentsSubscriptionStandingResponse }
1636
+ }), requireAuth(), validate("json", SubscriptionCancelRequest), async (c) => {
1493
1637
  const input = c.req.valid("json");
1494
1638
  const subject = await requirePaymentsSubject(c, seam);
1495
1639
  const purchase = requireOneSubscription(await changeableSubscription(database(c), subject, clock()));
@@ -1544,7 +1688,11 @@ function registerPaymentsRoutes(options) {
1544
1688
  * A subscription with nothing scheduled is the no-op rather than a refusal — it already renews, which
1545
1689
  * is what the caller asked for — and it writes no audit row, for {@link standingMoved}'s reason.
1546
1690
  */
1547
- app.post(`${base}/subscription/keep`, requireAuth(), async (c) => {
1691
+ app.post(`${base}/subscription/keep`, describeRoute({
1692
+ summary: "Withdraw a scheduled cancellation.",
1693
+ verification: ["bearer", "session"],
1694
+ responses: { 200: PaymentsSubscriptionStandingResponse }
1695
+ }), requireAuth(), async (c) => {
1548
1696
  const subject = await requirePaymentsSubject(c, seam);
1549
1697
  const purchase = requireOneSubscription(await changeableSubscription(database(c), subject, clock()));
1550
1698
  const provider = await subscriptionRail(c, purchase.rail);
@@ -1603,7 +1751,11 @@ function registerPaymentsRoutes(options) {
1603
1751
  * already standing is the state the caller wanted, and a trail claiming two of them is worse than one
1604
1752
  * claiming none.
1605
1753
  */
1606
- app.post(`${base}/subscription/refund`, requireAuth(), async (c) => {
1754
+ app.post(`${base}/subscription/refund`, describeRoute({
1755
+ summary: "Ask the store to refund the payments on the caller's own subscription.",
1756
+ verification: ["bearer", "session"],
1757
+ responses: { 200: PaymentsRefundResponse }
1758
+ }), requireAuth(), async (c) => {
1607
1759
  const subject = await requirePaymentsSubject(c, seam);
1608
1760
  const purchase = requireOneSubscription(await changeableSubscription(database(c), subject, clock()));
1609
1761
  const provider = await refundRail(c, purchase.rail);
@@ -1653,7 +1805,12 @@ function registerPaymentsRoutes(options) {
1653
1805
  * issue. Never reaches a browser — the set of codes an adopter has issued is a commercial fact, and the
1654
1806
  * client projection draws the same line here it draws for SKUs.
1655
1807
  */
1656
- app.get(`${base}/admin/discounts`, requireControlPlane(PAYMENTS_DISCOUNT_READ_SCOPE), zValidator("query", AdminDiscountsQuery, validationHook), async (c) => {
1808
+ app.get(`${base}/admin/discounts`, describeRoute({
1809
+ summary: "Read the discount codes this project has issued at one store.",
1810
+ verification: "control-plane",
1811
+ scopes: [PAYMENTS_DISCOUNT_READ_SCOPE],
1812
+ responses: { 200: PaymentsAdminDiscountsResponse }
1813
+ }), requireControlPlane(PAYMENTS_DISCOUNT_READ_SCOPE), validate("query", AdminDiscountsQuery), async (c) => {
1657
1814
  const { rail } = c.req.valid("query");
1658
1815
  const provider = resolveRailProvider(rail, config, await credentials(c), trust);
1659
1816
  if (!isDiscountRail(provider)) throw new PaymentsRailNotConfiguredError({ detail: `The ${provider.rail} rail does not mint discounts.` });
@@ -1682,7 +1839,12 @@ function registerPaymentsRoutes(options) {
1682
1839
  * Applying a code does **not** go through here and does not require this scope. An adopter whose codes
1683
1840
  * are minted by hand in a provider dashboard is fully served by `/checkout`'s `discountCode`.
1684
1841
  */
1685
- app.post(`${base}/admin/discounts`, requireControlPlane(PAYMENTS_DISCOUNT_CREATE_SCOPE), zValidator("json", DiscountCreateRequest, validationHook), async (c) => {
1842
+ app.post(`${base}/admin/discounts`, describeRoute({
1843
+ summary: "Mint a discount code at one store.",
1844
+ verification: "control-plane",
1845
+ scopes: [PAYMENTS_DISCOUNT_CREATE_SCOPE],
1846
+ responses: { 200: PaymentsDiscountResponse }
1847
+ }), requireControlPlane(PAYMENTS_DISCOUNT_CREATE_SCOPE), validate("json", DiscountCreateRequest), async (c) => {
1686
1848
  const input = c.req.valid("json");
1687
1849
  const provider = resolveRailProvider(input.rail, config, await credentials(c), trust);
1688
1850
  if (!isDiscountRail(provider)) throw new PaymentsRailNotConfiguredError({ detail: `The ${provider.rail} rail does not mint discounts.` });
@@ -1708,7 +1870,12 @@ function registerPaymentsRoutes(options) {
1708
1870
  rail: input.rail
1709
1871
  }, 200);
1710
1872
  });
1711
- app.post(`${base}/entitlements/grant`, requireControlPlane(PAYMENTS_ENTITLEMENT_GRANT_SCOPE), zValidator("json", EntitlementGrantRequest, validationHook), async (c) => {
1873
+ app.post(`${base}/entitlements/grant`, describeRoute({
1874
+ summary: "Grant an entitlement by hand.",
1875
+ verification: "control-plane",
1876
+ scopes: [PAYMENTS_ENTITLEMENT_GRANT_SCOPE],
1877
+ responses: { 200: PaymentsEntitlementResponse }
1878
+ }), requireControlPlane(PAYMENTS_ENTITLEMENT_GRANT_SCOPE), validate("json", EntitlementGrantRequest), async (c) => {
1712
1879
  const input = c.req.valid("json");
1713
1880
  const caller = controlPlaneCaller(c);
1714
1881
  if (input.subjectType !== config.billingSubject) throw new ValidationError({
@@ -1773,7 +1940,12 @@ function registerPaymentsRoutes(options) {
1773
1940
  * from a live customer and handing product out for free are different mistakes with different victims, and
1774
1941
  * an adopter's refund tooling has no business being able to make the second one.
1775
1942
  */
1776
- app.post(`${base}/entitlements/revoke`, requireControlPlane(PAYMENTS_ENTITLEMENT_REVOKE_SCOPE), zValidator("json", EntitlementRevokeRequest, validationHook), async (c) => {
1943
+ app.post(`${base}/entitlements/revoke`, describeRoute({
1944
+ summary: "Revoke an entitlement by hand.",
1945
+ verification: "control-plane",
1946
+ scopes: [PAYMENTS_ENTITLEMENT_REVOKE_SCOPE],
1947
+ responses: { 200: PaymentsEntitlementResponse }
1948
+ }), requireControlPlane(PAYMENTS_ENTITLEMENT_REVOKE_SCOPE), validate("json", EntitlementRevokeRequest), async (c) => {
1777
1949
  const input = c.req.valid("json");
1778
1950
  const caller = controlPlaneCaller(c);
1779
1951
  const revoked = await revokeEntitlement(database(c), {
@@ -80,7 +80,7 @@ export type CheckoutRequest = z.infer<typeof CheckoutRequest>;
80
80
  *
81
81
  * **No body at all on `keep`.** Withdrawing a scheduled cancellation takes no parameters: which
82
82
  * subscription is the server's answer, and there is nothing to say about it but *do not*. So that route
83
- * declares no schema and no `zValidator("json", …)`, exactly as `POST {base}/portal` does. A
83
+ * declares no schema and no `validate("json", …)`, exactly as `POST {base}/portal` does. A
84
84
  * `z.object({})` would read as a refusal of everything and be neither — Zod strips rather than refuses —
85
85
  * while making a POST with no body at all a 400 on a route that wants nothing.
86
86
  */
@@ -403,4 +403,24 @@ export declare const AdminSubjectParam: z.ZodObject<{
403
403
  subjectId: z.ZodString;
404
404
  }, z.core.$strip>;
405
405
  export type AdminSubjectParam = z.output<typeof AdminSubjectParam>;
406
+ /**
407
+ * The transaction a Paddle payment link put in the URL — the `?transaction=` query on the resume read.
408
+ *
409
+ * **The id is the whole request, and it came from outside.** Paddle appends `?_ptxn=<transaction_id>` to a
410
+ * seller's Default payment link; the browser reads it and sends it here. So this is attacker-supplied text
411
+ * on an unauthenticated route, and the shape check is what makes it safe to echo back into a handoff a page
412
+ * will hand to `Paddle.Checkout.open`.
413
+ *
414
+ * **Checked against the rail's own primitive**, `isPaddleTransactionId`, rather than a regex written here:
415
+ * `rails/paddle/verify.ts` asks the same question of a submitted receipt, and two copies of one rule is the
416
+ * defect class this repository has paid for four times.
417
+ *
418
+ * **It names no holder, and that is structural rather than remembered.** The resume route takes no session
419
+ * and resolves no subject, so there is no field here for one — which `routeContract.test.ts`'s subject sweep
420
+ * asserts from the other side, by finding none.
421
+ */
422
+ export declare const PaddleResumeQuery: z.ZodObject<{
423
+ transaction: z.ZodString;
424
+ }, z.core.$strip>;
425
+ export type PaddleResumeQuery = z.output<typeof PaddleResumeQuery>;
406
426
  //# sourceMappingURL=schemas.d.ts.map
@@ -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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"}
@@ -5,6 +5,7 @@ import { PaymentsSubject } from "../data/subject.js";
5
5
  import { PurchaseStatus } from "../data/status.js";
6
6
  import { PurchaseEnvironment } from "../data/purchase.js";
7
7
  import { SubscriptionCancelTiming } from "../data/subscription.js";
8
+ import { isPaddleTransactionId } from "../data/paddleIds.js";
8
9
  import { DiscountCode, DiscountTerms } from "../data/discount.js";
9
10
  import { EntitlementKey } from "@pithy-sh/core/src/entitlement/entitlement";
10
11
  import { z } from "zod";
@@ -115,7 +116,7 @@ const CheckoutRequest = z.object({
115
116
  *
116
117
  * **No body at all on `keep`.** Withdrawing a scheduled cancellation takes no parameters: which
117
118
  * subscription is the server's answer, and there is nothing to say about it but *do not*. So that route
118
- * declares no schema and no `zValidator("json", …)`, exactly as `POST {base}/portal` does. A
119
+ * declares no schema and no `validate("json", …)`, exactly as `POST {base}/portal` does. A
119
120
  * `z.object({})` would read as a refusal of everything and be neither — Zod strips rather than refuses —
120
121
  * while making a POST with no body at all a 400 on a route that wants nothing.
121
122
  */
@@ -357,5 +358,22 @@ const AdminSubjectParam = z.object({
357
358
  subjectType: PaymentsSubject.shape.subjectType.describe("Which kind of holder to resolve — the `:subjectType` path segment. A closed enum, so an unknown kind is a 400 naming the two that exist."),
358
359
  subjectId: PaymentsSubject.shape.subjectId.describe("Whose entitlements to resolve — the `:subjectId` path segment. Opaque to payments: whatever id the adopter's auth capability or its own membership model issued.")
359
360
  }).describe("The `:subjectType/:subjectId` path segments on the per-subject management read.");
361
+ /**
362
+ * The transaction a Paddle payment link put in the URL — the `?transaction=` query on the resume read.
363
+ *
364
+ * **The id is the whole request, and it came from outside.** Paddle appends `?_ptxn=<transaction_id>` to a
365
+ * seller's Default payment link; the browser reads it and sends it here. So this is attacker-supplied text
366
+ * on an unauthenticated route, and the shape check is what makes it safe to echo back into a handoff a page
367
+ * will hand to `Paddle.Checkout.open`.
368
+ *
369
+ * **Checked against the rail's own primitive**, `isPaddleTransactionId`, rather than a regex written here:
370
+ * `rails/paddle/verify.ts` asks the same question of a submitted receipt, and two copies of one rule is the
371
+ * defect class this repository has paid for four times.
372
+ *
373
+ * **It names no holder, and that is structural rather than remembered.** The resume route takes no session
374
+ * and resolves no subject, so there is no field here for one — which `routeContract.test.ts`'s subject sweep
375
+ * asserts from the other side, by finding none.
376
+ */
377
+ 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.");
360
378
  //#endregion
361
- export { AdminDiscountsQuery, AdminEntitlementsQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest };
379
+ export { AdminDiscountsQuery, AdminEntitlementsQuery, AdminPurchasesQuery, AdminReconcileRunsQuery, AdminSubjectParam, AdminSubscriptionsQuery, AppleWebhookNotification, CheckoutRequest, DiscountCreateRequest, EntitlementGrantRequest, EntitlementRevokeRequest, GoogleWebhookNotification, LemonSqueezyWebhookNotification, PaddleResumeQuery, PaddleWebhookNotification, PurchaseSubmission, RestoreRequest, StripeWebhookNotification, SubscriptionCancelRequest, SubscriptionChangeRequest, SubscriptionPreviewRequest };
@@ -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;AAkGhF,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;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"}
@@ -24,7 +24,7 @@ import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
24
24
  * it.
25
25
  *
26
26
  * `c.req.text()` rather than `c.req.raw.text()`, and that distinction matters. Hono caches its own body reads,
27
- * so the route's `zValidator("json", …)` afterwards is served from the same cache and sees identical bytes.
27
+ * so the route's `validate("json", …)` afterwards is served from the same cache and sees identical bytes.
28
28
  * Reading `c.req.raw` directly would consume the stream and leave the validator with nothing.
29
29
  *
30
30
  * ## Why it persists before it hands off