@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
@@ -1 +1 @@
1
- {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/events.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAIlG,OAAO,EAAE,KAAK,8BAA8B,EAAmB,MAAM,WAAW,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,4GAA4G;AAC5G,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAoBrD,CAAC;AAKF,iCAAiC;AACjC,MAAM,WAAW,kBAAmB,SAAQ,8BAA8B;IACxE,8BAA8B;IAC9B,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1C;;;;;;;;;;;;;OAaG;IACH,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACtE;AAED,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,0GAA0G;AAC1G,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqG7F"}
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/events.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAIlG,OAAO,EAAE,KAAK,8BAA8B,EAAmB,MAAM,WAAW,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,4GAA4G;AAC5G,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAoBrD,CAAC;AAKF,iCAAiC;AACjC,MAAM,WAAW,kBAAmB,SAAQ,8BAA8B;IACxE,8BAA8B;IAC9B,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1C;;;;;;;;;;;;;OAaG;IACH,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACtE;AAED,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,0GAA0G;AAC1G,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqG7F"}
@@ -6,6 +6,7 @@ import { PADDLE_ADJUSTMENTS_INCLUDE, readTransaction } from "./read.js";
6
6
  import { recordedPayload } from "./recorded.js";
7
7
  import { readPaddleEvent } from "./webhook.js";
8
8
  import { z } from "zod";
9
+ import { commandName } from "@pithy-sh/core/src/cli/command";
9
10
  //#region src/rails/paddle/events.ts
10
11
  /**
11
12
  * The events sweep — the repair `refresh` cannot make.
@@ -118,7 +119,7 @@ async function sweepPaddleEvents(options) {
118
119
  events: [],
119
120
  cursor: options.cursor,
120
121
  hasMore: false,
121
- gap: `Paddle no longer knows event ${options.cursor}, so the sweep cannot resume from it. Paddle retains 90 days of events, and anything between that cursor and the retention window is gone. Reconcile the affected purchases with \`pithy payments reconcile --rail paddle\`, then clear the cursor to restart from the oldest retained event.`
122
+ gap: `Paddle no longer knows event ${options.cursor}, so the sweep cannot resume from it. Paddle retains 90 days of events, and anything between that cursor and the retention window is gone. Reconcile the affected purchases with \`${commandName("payments reconcile")}\`, passing --rail paddle and this environment's --env, then clear the cursor to restart from the oldest retained event.`
122
123
  };
123
124
  throw cause;
124
125
  }
@@ -14,9 +14,12 @@ import { type PaddleEnvironment, type PaddleHttpFetch } from "./api";
14
14
  *
15
15
  * ## Which rows it can answer for
16
16
  *
17
- * Paddle's ids are globally prefixed, so the row's own key says what to ask: `sub_…` is a subscription,
18
- * `txn_…` is a transaction. Both are addressable, so both are re-read — unlike Lemon Squeezy, where a
19
- * money row records a closed period and has nothing to re-read.
17
+ * Paddle's ids are globally prefixed, so the row's own key says what to ask: a subscription id is a
18
+ * subscription, a transaction id is a transaction. Both are addressable, so both are re-read — unlike
19
+ * Lemon Squeezy, where a money row records a closed period and has nothing to re-read. **What counts as
20
+ * one of those keys is `data/paddleIds.ts`'s to say**, not this module's: a prefix test here accepted the
21
+ * bare prefix and an uppercase id, and spent a round trip finding out the store had never issued it
22
+ * (#681).
20
23
  *
21
24
  * A **subscription** transaction's money row is born `expired`, which is in the Workflow's terminal set,
22
25
  * so the pass never selects one. Should one reach here it is answered honestly rather than skipped: a
@@ -49,8 +52,10 @@ export declare function refreshPaddlePurchase(purchase: PaymentsPurchase, option
49
52
  * list price. Nothing here multiplies a price by a percentage — a second calculation would be a second
50
53
  * answer to the one question a customer checks against their statement.
51
54
  *
52
- * Only a `sub_…` row can be asked. A transaction records one closed period and has no "next", so it
53
- * answers `undefined` — the same "nothing to say about this purchase" the refresh path uses.
55
+ * Only a subscription row can be asked, and `data/paddleIds.ts` says which rows those are. A transaction
56
+ * records one closed period and has no "next", so it answers `undefined` — the same "nothing to say about
57
+ * this purchase" the refresh path uses, and the same answer a column holding something Paddle never
58
+ * issued now gets without a round trip (#681).
54
59
  */
55
60
  export declare function readPaddlePricing(purchase: PaymentsPurchase, options: RefreshPaddleOptions): Promise<SubscriptionPricing | undefined>;
56
61
  //# sourceMappingURL=refresh.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/refresh.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAIlG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,WAAW,EAAE,yBAAyB,CAAC;IACvC,yCAAyC;IACzC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,oEAAoE;IACpE,GAAG,EAAE,IAAI,CAAC;IACV,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,oFAAoF;AACpF,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CA2B3C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAoC1C"}
1
+ {"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/refresh.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAIlG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,WAAW,EAAE,yBAAyB,CAAC;IACvC,yCAAyC;IACzC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,oEAAoE;IACpE,GAAG,EAAE,IAAI,CAAC;IACV,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,oFAAoF;AACpF,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CA4B3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAoC1C"}
@@ -3,6 +3,7 @@
3
3
  import { paddleHttpFetch, paddleJson } from "./api.js";
4
4
  import { currencyOf, minorAmount, subscriptionEvent, transactionEvent } from "./objects.js";
5
5
  import { readSubscription, readTransaction } from "./read.js";
6
+ import { isPaddleSubscriptionId, isPaddleTransactionId } from "../../data/paddleIds.js";
6
7
  //#region src/rails/paddle/refresh.ts
7
8
  /** Re-read one purchase, or `undefined` when Paddle has nothing to say about it. */
8
9
  async function refreshPaddlePurchase(purchase, options) {
@@ -13,7 +14,7 @@ async function refreshPaddlePurchase(purchase, options) {
13
14
  };
14
15
  const id = purchase.providerTransactionId;
15
16
  const environment = options.environment === "production" ? "production" : "sandbox";
16
- if (id.startsWith("sub_")) {
17
+ if (isPaddleSubscriptionId(id)) {
17
18
  const subscription = await readSubscription(id, read);
18
19
  if (subscription === void 0) return void 0;
19
20
  return {
@@ -21,7 +22,7 @@ async function refreshPaddlePurchase(purchase, options) {
21
22
  providerEventAt: options.now
22
23
  };
23
24
  }
24
- if (id.startsWith("txn_")) {
25
+ if (isPaddleTransactionId(id)) {
25
26
  const transaction = await readTransaction(id, read);
26
27
  if (transaction === void 0) return void 0;
27
28
  return {
@@ -38,12 +39,14 @@ async function refreshPaddlePurchase(purchase, options) {
38
39
  * list price. Nothing here multiplies a price by a percentage — a second calculation would be a second
39
40
  * answer to the one question a customer checks against their statement.
40
41
  *
41
- * Only a `sub_…` row can be asked. A transaction records one closed period and has no "next", so it
42
- * answers `undefined` — the same "nothing to say about this purchase" the refresh path uses.
42
+ * Only a subscription row can be asked, and `data/paddleIds.ts` says which rows those are. A transaction
43
+ * records one closed period and has no "next", so it answers `undefined` — the same "nothing to say about
44
+ * this purchase" the refresh path uses, and the same answer a column holding something Paddle never
45
+ * issued now gets without a round trip (#681).
43
46
  */
44
47
  async function readPaddlePricing(purchase, options) {
45
48
  const id = purchase.providerTransactionId;
46
- if (!id.startsWith("sub_")) return void 0;
49
+ if (!isPaddleSubscriptionId(id)) return void 0;
47
50
  const answer = await paddleJson(options.transport ?? paddleHttpFetch, `/subscriptions/${encodeURIComponent(id)}`, {
48
51
  what: `subscription ${id}'s pricing`,
49
52
  apiKey: options.credentials.apiKey,
@@ -1 +1 @@
1
- {"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/refund.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAuD,MAAM,yBAAyB,CAAC;AAE7G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAoD,MAAM,OAAO,CAAC;AAIvH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAoGjD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAyFxB"}
1
+ {"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/refund.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAuD,MAAM,yBAAyB,CAAC;AAE7G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAoD,MAAM,OAAO,CAAC;AAIvH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AA2GjD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAyFxB"}
@@ -5,6 +5,7 @@ import { RefundRequest } from "../../data/subscription.js";
5
5
  import { paddleHttpFetch, paddleJson, redactPaddleSecrets } from "./api.js";
6
6
  import { PaddleAdjustment } from "./objects.js";
7
7
  import { PADDLE_ADJUSTMENTS_INCLUDE, readTransaction } from "./read.js";
8
+ import { isPaddleTransactionId } from "../../data/paddleIds.js";
8
9
  import { REVOKING_ACTIONS } from "./adjustments.js";
9
10
  //#region src/rails/paddle/refund.ts
10
11
  /**
@@ -37,10 +38,17 @@ function refuse(detail) {
37
38
  detail
38
39
  });
39
40
  }
40
- /** The transaction this purchase row names, or null when it names none. */
41
+ /**
42
+ * The transaction this purchase row names, or null when it names none.
43
+ *
44
+ * **The primitive decides, not a prefix test here.** `startsWith` accepted the bare prefix and Paddle's
45
+ * alphabet in uppercase, neither of which is an id the store can hold — so a malformed row cost a
46
+ * `GET /transactions/{id}` and then refused on the 404, naming the store rather than the row (#681).
47
+ * `data/paddleIds.ts` is the one place that says what a transaction id is.
48
+ */
41
49
  function transactionIdOf(purchase) {
42
50
  const id = purchase.providerTransactionId;
43
- return id.startsWith("txn_") ? id : null;
51
+ return isPaddleTransactionId(id) ? id : null;
44
52
  }
45
53
  /**
46
54
  * The adjustment already standing against this transaction, or undefined.
@@ -1 +1 @@
1
- {"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/subscription.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAIL,uBAAuB,EAGvB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAYlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,yBAAyB;IACxC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AA2fD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAK3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,EAClC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA0B/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B"}
1
+ {"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/subscription.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAIL,uBAAuB,EAGvB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAYlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,yBAAyB;IACxC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AA+fD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAK3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,EAClC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA0B/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B"}
@@ -4,6 +4,7 @@ import { PaymentsProviderUnavailableError, PaymentsSubscriptionChangeRefusedErro
4
4
  import { SubscriptionChangeQuote, SubscriptionStanding } from "../../data/subscription.js";
5
5
  import { paddleHttpFetch, paddleJson } from "./api.js";
6
6
  import { PaddleSubscription, PaddleSubscriptionPreview, currencyOf, minorAmount, subscriptionPendingChange, subscriptionStatus } from "./objects.js";
7
+ import { isPaddleSubscriptionId } from "../../data/paddleIds.js";
7
8
  import { renderMoney } from "../../data/renderMoney.js";
8
9
  import { z } from "zod";
9
10
  //#region src/rails/paddle/subscription.ts
@@ -89,12 +90,16 @@ function orNull(value) {
89
90
  * The subscription this purchase names, or null when it names none.
90
91
  *
91
92
  * Paddle's ids are globally prefixed, so the row's own key says what it is — `refreshPaddlePurchase`'s rule,
92
- * and for the same reason: a money row's family key is `sub_…`, and falling back to it would act on a
93
- * subscription from a row that is not one.
93
+ * and for the same reason: a money row's family key is the subscription's, and falling back to it would act
94
+ * on a subscription from a row that is not one.
95
+ *
96
+ * **`isPaddleSubscriptionId` rather than a prefix test, and all five callers feel it.** The prefix alone,
97
+ * and an id in an alphabet Paddle does not issue, used to read as subscriptions here: the read answered
98
+ * after a wasted round trip, and the other four refused on the store's answer instead of on the row (#681).
94
99
  */
95
100
  function subscriptionIdOf(purchase) {
96
101
  const id = purchase.providerTransactionId;
97
- return id.startsWith("sub_") ? id : null;
102
+ return isPaddleSubscriptionId(id) ? id : null;
98
103
  }
99
104
  /** The subscription, or a refusal. Used by the write verbs, which have nothing to do without it. */
100
105
  async function loadSubscription(id, options) {
@@ -1 +1 @@
1
- {"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/verify.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,oDAAoD;AACpD,MAAM,WAAW,8BAA8B;IAC7C,wGAAwG;IACxG,WAAW,EAAE,yBAAyB,CAAC;IACvC,yCAAyC;IACzC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,GAAG,EAAE,IAAI,CAAC;IACV,qBAAqB;IACrB,SAAS,EAAE,eAAe,CAAC;CAC5B;AAKD,wFAAwF;AACxF,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,gBAAgB,CAAC,CA2D3B"}
1
+ {"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/verify.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,oDAAoD;AACpD,MAAM,WAAW,8BAA8B;IAC7C,wGAAwG;IACxG,WAAW,EAAE,yBAAyB,CAAC;IACvC,yCAAyC;IACzC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,GAAG,EAAE,IAAI,CAAC;IACV,qBAAqB;IACrB,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,wFAAwF;AACxF,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,gBAAgB,CAAC,CA+D3B"}
@@ -3,13 +3,12 @@
3
3
  import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors.js";
4
4
  import { PADDLE_CUSTOM_ACCOUNT, accountReferenceOf, transactionEvent } from "./objects.js";
5
5
  import { readTransaction } from "./read.js";
6
+ import { isPaddleTransactionId } from "../../data/paddleIds.js";
6
7
  //#region src/rails/paddle/verify.ts
7
- /** Paddle's transaction ids. Checked before a round trip, so a malformed one costs nothing. */
8
- const TRANSACTION_ID = /^txn_[a-z0-9]+$/;
9
8
  /** Verify one submitted Paddle transaction id, and report who it says it belongs to. */
10
9
  async function verifyPaddleTransaction(receipt, options) {
11
10
  const id = receipt.trim();
12
- if (!TRANSACTION_ID.test(id)) throw new PaymentsInvalidReceiptError({
11
+ if (!isPaddleTransactionId(id)) throw new PaymentsInvalidReceiptError({
13
12
  message: "That isn't a Paddle transaction.",
14
13
  action: "Submit the `txn_…` the checkout's completion callback handed back.",
15
14
  detail: `A Paddle receipt is a transaction id of the form txn_…; this one is ${id.length} characters and does not match.`
@@ -1 +1 @@
1
- {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAUzE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,iHAC0E,CAAC;AAEjH,eAAO,MAAM,wBAAwB;;;;;kBAiC6E,CAAC;AACnH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;;;;kBAgCiF,CAAC;AACxH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,yBAAyB;;;kBAiB2E,CAAC;AAClH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,+BAA+B;;;;kBAwBkE,CAAC;AAC/G,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE9F,eAAO,MAAM,yBAAyB;;;kBAmBnC,CAAC;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYrC,CAAC;AACJ,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,WAAW,EAAE,2BAA2B,EACxC,IAAI,EAAE,CAAC,GACN,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAS7C"}
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAUzE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,iHAC0E,CAAC;AAEjH,eAAO,MAAM,wBAAwB;;;;;kBAiC6E,CAAC;AACnH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;;;;kBAgCiF,CAAC;AACxH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,yBAAyB;;;kBAiB2E,CAAC;AAClH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,+BAA+B;;;;kBAwBkE,CAAC;AAC/G,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE9F,eAAO,MAAM,yBAAyB;;;kBAmBnC,CAAC;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYrC,CAAC;AACJ,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,WAAW,EAAE,2BAA2B,EACxC,IAAI,EAAE,CAAC,GACN,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAS7C"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { PaymentsRailNotConfiguredError } from "../error/errors.js";
4
4
  import { z } from "zod";
5
+ import { pithyCommand } from "@pithy-sh/core/src/cli/command";
5
6
  import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
6
7
  //#region src/secret/registry.ts
7
8
  /**
@@ -147,8 +148,8 @@ const paymentsSecretsRegistry = defineSecretRegistry({ [PAYMENTS_PROVIDER_SECRET
147
148
  function railCredentials(credentials, rail) {
148
149
  const block = credentials[rail];
149
150
  if (!block) throw new PaymentsRailNotConfiguredError({
150
- detail: `The ${rail} rail has no credentials in "${PAYMENTS_PROVIDER_SECRET}" for this environment. Run \`pithy secrets set\` for it.`,
151
- action: `Take the ${rail} credentials from ${PAYMENTS_RAIL_CONSOLES[rail]} and set them with \`pithy secrets set ${PAYMENTS_PROVIDER_SECRET}\`.`
151
+ detail: `The ${rail} rail has no credentials in "${PAYMENTS_PROVIDER_SECRET}" for this environment. Run \`${pithyCommand("secrets update", { args: [PAYMENTS_PROVIDER_SECRET] })}\` for it.`,
152
+ action: `Take the ${rail} credentials from ${PAYMENTS_RAIL_CONSOLES[rail]} and set them with \`${pithyCommand("secrets update", { args: [PAYMENTS_PROVIDER_SECRET] })}\`.`
152
153
  });
153
154
  return block;
154
155
  }
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/payments";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.3.10";
6
+ export declare const PACKAGE_VERSION = "0.4.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,uBAAuB,CAAC;AAEjD,oFAAoF;AACpF,eAAO,MAAM,eAAe,WAAW,CAAC"}
1
+ {"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,uBAAuB,CAAC;AAEjD,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/payments";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.3.10";
7
+ const PACKAGE_VERSION = "0.4.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -1 +1 @@
1
- {"version":3,"file":"workerConfig.d.ts","sourceRoot":"","sources":["../../src/workflows/workerConfig.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;GAWG;AAEH,0GAA0G;AAC1G,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,6GAA6G;IAC7G,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE;QAAE,MAAM,CAAC,OAAO,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CAChG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,CA0B5E"}
1
+ {"version":3,"file":"workerConfig.d.ts","sourceRoot":"","sources":["../../src/workflows/workerConfig.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQlD;;;;;;;;;;;GAWG;AAEH,0GAA0G;AAC1G,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,6GAA6G;IAC7G,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE;QAAE,MAAM,CAAC,OAAO,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CAChG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,CAyB5E"}
@@ -2,8 +2,14 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { PaymentsConfig } from "../config/config.js";
4
4
  import { InternalError, fromZodError, messageOf } from "@pithy-sh/core/src/error/pithyError";
5
+ import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
5
6
  //#region src/workflows/workerConfig.ts
6
7
  /**
8
+ * The provision that rewrites this host's config, as the host can name it: it cannot know the `apps/` directory
9
+ * of the app Worker that provisioned it, so it names no `--worker`, and the run asks (#711).
10
+ */
11
+ const PROVISION = pithyCommandOf("payments provision", {}, { runtime: true });
12
+ /**
7
13
  * The catalog this worker reconciles against, read back out of the `PAYMENTS_CONFIG` var.
8
14
  *
9
15
  * **A config this does not accept stops the run, and since `billingSubject` became required that includes
@@ -25,14 +31,14 @@ function reconcileWorkerConfig(env) {
25
31
  } catch (cause) {
26
32
  throw new InternalError({
27
33
  message: "The reconcile worker's PAYMENTS_CONFIG var is not valid JSON.",
28
- action: "Re-run `pithy payments provision` for this environment to rewrite it.",
34
+ action: `Re-run \`${PROVISION}\` for this environment to rewrite it.`,
29
35
  detail: messageOf(cause)
30
36
  });
31
37
  }
32
38
  const parsed = PaymentsConfig.safeParse(value ?? {});
33
39
  if (!parsed.success) throw fromZodError(parsed.error, {
34
40
  message: "The reconcile worker's PAYMENTS_CONFIG var is not a payments config this build can run.",
35
- action: "Set the missing keys in this Worker's pithy.config.ts — `billingSubject` is required — then re-run `pithy payments provision` for this environment."
41
+ action: `Set the missing keys in this Worker's pithy.config.ts — \`billingSubject\` is required — then re-run \`${PROVISION}\` for this environment.`
36
42
  });
37
43
  return parsed.data;
38
44
  }
package/docs/paddle.md CHANGED
@@ -54,10 +54,25 @@ This is not a nicety and it is not hosted-mode-only. Without it Paddle refuses t
54
54
 
55
55
  > Cannot create a transaction or open a checkout as no default payment link has been set for this account. Set in the Paddle dashboard, then try again.
56
56
 
57
- Verified live. Every checkout mode creates the transaction server-side, so overlay and inline are blocked by exactly the same refusal. Point it at your own domain — Paddle only uses it to construct the hosted URL, which `checkout: "hosted"` returns and the other two modes ignore.
57
+ Verified live. Every checkout mode creates the transaction server-side, so overlay and inline are blocked by exactly the same refusal. Point it at your own domain.
58
58
 
59
59
  `pithy doctor` asks the same question, so this is caught before a buyer finds it.
60
60
 
61
+ ### It is also the address Paddle sends buyers back to
62
+
63
+ The link has a second job, and it is the one that decides **which page** to point it at. Paddle appends `?_ptxn=<transaction_id>` to it for links it sends rather than ones you open — a past-due dunning mail, a manually-collected invoice's pay link, the payment-method-update link it mints for a subscription — and expects that page to open a checkout for that transaction.
64
+
65
+ ```tsx
66
+ const { handoff } = usePaddleLink(); // reads `_ptxn`, asks the server for the account
67
+ usePaddleCheckout(handoff, { frameTarget: "pithy-checkout" });
68
+ ```
69
+
70
+ `usePaddleLink` returns `null` when there is no `_ptxn`, so a page that is usually reached normally renders exactly as it did before. The transaction is Paddle's; nothing is minted, and the id never names a price.
71
+
72
+ **In `inline` mode the page you name must already render the frame container.** Paddle finds it by class name at the moment `open` is called, so a link pointing at a page without one produces `client/paddle_no_container` rather than a checkout. Point it at the screen that holds your checkout container — usually your billing page — not at your site root. In `overlay` mode any page works. In `hosted` mode there is nothing to resume: the buyer is on Paddle's own checkout, and `GET /payments/checkout/resume` refuses with `payments/rail_not_configured`.
73
+
74
+ `GET /payments/checkout/resume` is **unauthenticated**, and that is deliberate: the buyer following a dunning mail days later is usually signed out. It discloses nothing — the client token is publishable, the environment, display mode and success URL are config constants, and the id is the caller's own. It never reads the transaction from Paddle, so it cannot be used to discover whether an id exists.
75
+
61
76
  ## 4. Choose a checkout mode
62
77
 
63
78
  ```
@@ -415,7 +430,7 @@ The frame is styled `width: 100%; min-width: 312px; background-color: transparen
415
430
 
416
431
  ## 13. Testing checkout against a payment link in dev
417
432
 
418
- The sandbox account's default payment link is normalized by Paddle to `https://`. `wrangler dev` serves plain HTTP on 8787, so a Paddle-generated **hosted** payment link will not connect in dev unless you run `pithy dev` with `--local-protocol=https`. Overlay and inline never route through that link and are unaffected.
433
+ The sandbox account's default payment link is normalized by Paddle to `https://`. `wrangler dev` serves plain HTTP on 8787, so a Paddle-generated **hosted** payment link will not connect in dev unless you run `pithy dev` with `--local-protocol=https`. Overlay and inline do not route *outbound* through that link, so starting a checkout in either is unaffected — but a `_ptxn` arrival is inbound on the same URL, so testing one locally hits the same normalization and wants the same flag.
419
434
 
420
435
  ## 14. Discounts
421
436
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/payments",
3
- "version": "0.3.10",
3
+ "version": "0.4.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,9 +42,9 @@
42
42
  "@paddle/paddle-js": "^1.6.4"
43
43
  },
44
44
  "peerDependencies": {
45
- "@pithy-sh/core": "^0.9.0",
46
- "@pithy-sh/ledger": "^0.2.8",
47
- "@pithy-sh/secrets": "^0.3.2",
45
+ "@pithy-sh/core": "^0.10.0",
46
+ "@pithy-sh/ledger": "^0.3.0",
47
+ "@pithy-sh/secrets": "^0.4.0",
48
48
  "hono": "^4.13.2",
49
49
  "kysely": "^0.29.0",
50
50
  "react": "^19.0.0",
@@ -59,7 +59,7 @@
59
59
  }
60
60
  },
61
61
  "devDependencies": {
62
- "@cloudflare/vitest-plugin": "^1.0.0",
62
+ "@cloudflare/vitest-plugin": "^1.4.2",
63
63
  "@pithy-sh/core": "workspace:*",
64
64
  "@pithy-sh/ledger": "workspace:*",
65
65
  "@pithy-sh/secrets": "workspace:*",
@@ -78,7 +78,7 @@
78
78
  "tsdown": "^0.23.0",
79
79
  "typescript": "^7.0.2",
80
80
  "vitest": "^4.1.0",
81
- "wrangler": "^4.115.0",
81
+ "wrangler": "^4.151.0",
82
82
  "zod": "^4.4.0"
83
83
  }
84
84
  }
package/src/client/api.ts CHANGED
@@ -610,6 +610,41 @@ export function createCheckout(
610
610
  return callPayments("/checkout", jsonPost(input), options, isCheckoutHandoff);
611
611
  }
612
612
 
613
+ /** Whether a value is a Paddle handoff specifically — the only shape the resume read answers with. */
614
+ function isPaddleResumeHandoff(value: unknown): value is PaddleCheckoutHandoff {
615
+ return isCheckoutHandoff(value) && value.kind === "paddle";
616
+ }
617
+
618
+ /**
619
+ * What a page needs to open the transaction a Paddle payment link arrived for.
620
+ *
621
+ * **The transaction already exists, which is the whole difference from {@link createCheckout}.** Paddle
622
+ * created it before mailing the link — a past-due retry, a manually-collected invoice, a payment-method
623
+ * update — and appended `?_ptxn=<id>` to this project's Default payment link. So nothing is minted here;
624
+ * the id is read off the URL by `readPaddleLinkTransaction` in `./paddleLink` and this asks the server for
625
+ * the account and presentation that go with it.
626
+ *
627
+ * **Why a round trip at all, when the browser already holds the id.** Because `successUrl` is not the
628
+ * browser's to name. The handoff carries where a paying buyer is sent, and a page that could choose it
629
+ * could send a paying customer somewhere it controls — the same rule the minted path states on the field
630
+ * itself. The client token and the display mode travel with it for the same reason they do there: one
631
+ * source of truth for which Paddle account this project sells through.
632
+ *
633
+ * Sends no credentials of consequence and needs none: the route is unauthenticated, because the buyer
634
+ * following a dunning link days later is usually signed out.
635
+ */
636
+ export function resumeCheckout(
637
+ transactionId: string,
638
+ options?: PaymentsClientOptions,
639
+ ): Promise<PaymentsResult<PaddleCheckoutHandoff>> {
640
+ return callPayments(
641
+ `/checkout/resume?transaction=${encodeURIComponent(transactionId)}`,
642
+ {},
643
+ options,
644
+ isPaddleResumeHandoff,
645
+ );
646
+ }
647
+
613
648
  /**
614
649
  * Create a Billing Portal session for the caller's own store account.
615
650
  *
@@ -14,6 +14,7 @@ import {
14
14
  type PaymentsHostedRail,
15
15
  type PurchaseView,
16
16
  restorePurchases,
17
+ resumeCheckout,
17
18
  startCheckout,
18
19
  submitPurchase,
19
20
  } from "./api";
@@ -28,6 +29,7 @@ import {
28
29
  previewPrices,
29
30
  priceQueryKey,
30
31
  } from "./paddle";
32
+ import { readPaddleLinkTransaction } from "./paddleLink";
31
33
 
32
34
  /**
33
35
  * The headless client surface: six hooks a paywall, a pricing page, a subscription screen, and a route
@@ -370,6 +372,82 @@ export function usePaddleCheckout(
370
372
  return { inline: handoff?.displayMode === "inline", opening, failure };
371
373
  }
372
374
 
375
+ /** What {@link usePaddleLink} gives the screen a Paddle payment link lands on. */
376
+ export interface UsePaddleLink {
377
+ /**
378
+ * The handoff to open, or null.
379
+ *
380
+ * Null covers three different facts and deliberately reads as one: there was no `_ptxn` in the URL, there
381
+ * was one and it was not a transaction id, or the server has not answered yet. A screen renders its
382
+ * ordinary state for all three, which is what it was already rendering before this hook existed.
383
+ */
384
+ handoff: PaddleCheckoutHandoff | null;
385
+ /** Whether the resume read is in flight. A screen with nothing to show need not read it. */
386
+ loading: boolean;
387
+ /** The refusal, or null. A rail that is off, or a mode that cannot resume. */
388
+ failure: PaymentsFailure | null;
389
+ }
390
+
391
+ /**
392
+ * Resume the checkout a Paddle payment link arrived for.
393
+ *
394
+ * **The inbound half of Paddle's *Default payment link*.** Paddle appends `?_ptxn=<transaction_id>` to it
395
+ * and expects this page to open a checkout for that transaction. Those are the links Paddle sends rather
396
+ * than ones this kit opened: a past-due dunning mail, a manually-collected invoice, the payment-method
397
+ * update link minted for a subscription. `useCheckout` cannot serve them — it mints a transaction, and here
398
+ * one already exists.
399
+ *
400
+ * **Pass the result to {@link usePaddleCheckout}, which opens it.** Nothing about opening is reimplemented
401
+ * here, and that is the point: the one-open-per-transaction guard, the `StrictMode` second pass, and the
402
+ * `PADDLE_NO_CONTAINER` refusal when an inline container is missing are all inherited by going through the
403
+ * same hook the minted path goes through.
404
+ *
405
+ * **In inline mode the page must already render the container.** Paddle finds it by class name when `open`
406
+ * is called, so a Default payment link pointing at a page that does not render one produces a refusal
407
+ * rather than a checkout — which makes the choice of landing page part of configuring this, not a detail.
408
+ * `docs/paddle.md` says so where an adopter sets the link.
409
+ *
410
+ * Reads `location.search` once, on mount. A link is a navigation, so there is no later arrival to watch for.
411
+ *
412
+ * **One read per transaction, remembered rather than assumed.** The same rule {@link usePaddleCheckout}
413
+ * states and for the same reason: `StrictMode` runs every effect, cleans it up and runs it again, and that
414
+ * is the mode `pithy ui add` scaffolds. Without the ref this asked the server twice on every mount — not
415
+ * harmful, since the route only echoes config, and still two requests where the file beside it had already
416
+ * solved the problem.
417
+ */
418
+ export function usePaddleLink(options?: PaymentsClientOptions): UsePaddleLink {
419
+ const [handoff, setHandoff] = useState<PaddleCheckoutHandoff | null>(null);
420
+ const [loading, setLoading] = useState(false);
421
+ const [failure, setFailure] = useState<PaymentsFailure | null>(null);
422
+ const latest = useLatest(options);
423
+ const live = useLive();
424
+ /** The transaction this hook has already asked about, so a second effect pass asks nothing. */
425
+ const asked = useRef<string | null>(null);
426
+
427
+ useEffect(() => {
428
+ // Narrowly cast rather than read off a typed global, which is `checkout.ts`'s `documentOf` pattern and
429
+ // is forced by the same thing: the build's tsconfig gives `globalThis` no DOM index signature, so
430
+ // `globalThis.location` compiles under `typecheck` and fails the published build with TS7017.
431
+ const search = (globalThis as { location?: { search?: string } }).location?.search;
432
+ // No browser, or nothing in the URL. Both are "this page was not reached from a payment link", and a
433
+ // server render is the first of those rather than a failure worth reporting.
434
+ const transactionId = search === undefined ? null : readPaddleLinkTransaction(search);
435
+ if (transactionId === null) return;
436
+ // StrictMode's second pass, or any remount holding the same URL. One arrival is one read.
437
+ if (asked.current === transactionId) return;
438
+ asked.current = transactionId;
439
+ setLoading(true);
440
+ void resumeCheckout(transactionId, latest.current).then((outcome) => {
441
+ if (!live.current) return;
442
+ setLoading(false);
443
+ if (outcome.ok) setHandoff(outcome.value);
444
+ else setFailure(outcome.failure);
445
+ });
446
+ }, [latest, live]);
447
+
448
+ return { handoff, loading, failure };
449
+ }
450
+
373
451
  /** What {@link usePurchase} gives the screen that submits receipts. */
374
452
  export interface UsePurchase {
375
453
  /** Submit one receipt for verification. */
@@ -0,0 +1,41 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import { isPaddleTransactionId } from "../data/paddleIds";
5
+
6
+ /**
7
+ * The query parameter Paddle appends to a seller's **Default payment link**.
8
+ *
9
+ * Named once, because Paddle does not document it as stable and a literal at two call sites is how one of
10
+ * them survives a rename. This is the thing to grep for if it ever moves.
11
+ */
12
+ export const PADDLE_LINK_PARAM = "_ptxn";
13
+
14
+ /**
15
+ * The transaction Paddle put in this page's URL, or null.
16
+ *
17
+ * **Paddle's own links are the ones that arrive here**, not any this kit opened: a past-due dunning mail,
18
+ * a manually-collected invoice's pay link, the payment-method-update link Paddle mints for a subscription.
19
+ * Each is the seller's *Default payment link* with `?_ptxn=<transaction_id>` on the end, and the contract
20
+ * is that the page it lands on opens a checkout for that transaction.
21
+ *
22
+ * **Null is the ordinary answer and is not a failure.** Every page this is called on is loaded without a
23
+ * `_ptxn` almost every time, so an absent parameter reads as "nothing to resume" and a screen renders
24
+ * exactly as it did before this existed. A malformed one reads the same way, which is the second half of
25
+ * the point: the value comes from outside, from a URL, from somebody who may not be signed in, and it is
26
+ * about to be sent to a route and then handed to `Paddle.Checkout.open`. The only thing that makes it safe
27
+ * to pass on is that it is shaped like a transaction id — so anything else is null rather than an error
28
+ * worth telling a buyer about, because a buyer cannot act on it and an attacker already knows.
29
+ *
30
+ * The shape check is {@link isPaddleTransactionId}, which is the rail's own and is shared rather than
31
+ * copied. Takes a search string rather than reading `location` itself, so this is a pure function and the
32
+ * hook that owns the browser is the only thing that needs one.
33
+ */
34
+ export function readPaddleLinkTransaction(search: string): string | null {
35
+ // `URLSearchParams` takes either spelling, so a caller may pass `location.search` — which carries the
36
+ // `?` — or a string it assembled without one, and neither has to be normalized first.
37
+ const value = new URLSearchParams(search).get(PADDLE_LINK_PARAM);
38
+ // Not trimmed, deliberately. A padded id is somebody's broken link or somebody's probe, and silently
39
+ // repairing it would mean this function and the route disagreed about what the id was.
40
+ return value !== null && isPaddleTransactionId(value) ? value : null;
41
+ }