@pithy-sh/payments 0.3.9 → 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 (62) 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.js +1 -1
  42. package/dist/workflows/workerConfig.d.ts.map +1 -1
  43. package/dist/workflows/workerConfig.js +8 -2
  44. package/docs/paddle.md +17 -2
  45. package/package.json +6 -6
  46. package/src/client/api.ts +35 -0
  47. package/src/client/hooks.ts +78 -0
  48. package/src/client/paddleLink.ts +41 -0
  49. package/src/data/paddleIds.ts +74 -0
  50. package/src/entitlement/unimplementedSubject.ts +3 -4
  51. package/src/http/responses.ts +33 -6
  52. package/src/http/routes.ts +729 -454
  53. package/src/http/schemas.ts +32 -1
  54. package/src/http/webhookGuard.ts +3 -2
  55. package/src/rails/paddle/events.ts +2 -1
  56. package/src/rails/paddle/refresh.ts +17 -10
  57. package/src/rails/paddle/refund.ts +10 -2
  58. package/src/rails/paddle/subscription.ts +8 -3
  59. package/src/rails/paddle/verify.ts +6 -4
  60. package/src/secret/registry.ts +3 -2
  61. package/src/version.generated.ts +1 -1
  62. package/src/workflows/workerConfig.ts +9 -3
@@ -0,0 +1,74 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ /**
5
+ * What a Paddle id looks like, in one place per kind of id.
6
+ *
7
+ * **Extracted because the rule had five producers and no two of them agreed.** `rails/paddle/verify.ts`
8
+ * held the transaction pattern as a module-private const, checking a receipt before spending a round trip
9
+ * on it; the `_ptxn` reader in `../client/paddleLink.ts` needs the same question answered about a value out
10
+ * of a query string (#680). Then `refund.ts`, `refresh.ts` and `subscription.ts` each answered it again
11
+ * with `startsWith`, which accepts the bare prefix and an alphabet Paddle does not issue — so one string
12
+ * was a transaction in `refund.ts` and not one in `verify.ts` (#681). A second regex is a second producer,
13
+ * and the ones that drift are always the copies nobody knew were copies.
14
+ *
15
+ * **Two kinds, two patterns, one rule.** Paddle's ids are globally prefixed and distinct, so the prefix is
16
+ * what says whether a row names a payment or the subscription it belongs to. Both predicates live here
17
+ * because that is one rule read two ways, not two rules: a caller asking "is this a transaction" is asking
18
+ * the question whose other half is "is this a subscription", and splitting them across modules is how the
19
+ * next build ends up with a tight transaction check beside a loose subscription one.
20
+ *
21
+ * **Deliberately `+` rather than `{26}`.** Paddle's API reference documents the ids as `^txn_[a-z\d]{26}$`
22
+ * and `^sub_[a-z\d]{26}$`, and every id seen from the live and sandbox accounts has been 26 characters
23
+ * after the prefix. These stay looser than the documentation on purpose: the length is Paddle's to change,
24
+ * a length that grew would make this kit reject transactions that are perfectly real, and nothing here
25
+ * depends on the count. The prefix and the alphabet are what distinguish a transaction from a
26
+ * subscription, a price or a URL, and they are what the callers actually need to know.
27
+ *
28
+ * **It lives in `data/` rather than in `rails/paddle/`, and the gate is why.** `client/sameOrigin.test.ts`
29
+ * freezes every specifier a browser module may import, and the one existing crossing out of `src/client/`
30
+ * is `wholeUnits.ts` reaching `../data/money` — permitted because that module imports nothing, so "a set of
31
+ * currency codes reaches the bundle, no graph behind it". This is the same shape and earns its place the
32
+ * same way: it imports nothing, so the browser half reaches a predicate and not a rail. Under
33
+ * `rails/paddle/` it made a browser module read the server rail, which the gate refused and was right to.
34
+ * **Nothing in this module may grow an import** — not a shared prefix constant, not a helper. The empty
35
+ * list at `sameOrigin.test.ts`'s `"src/data/paddleIds.ts"` is the whole reason the crossing is allowed.
36
+ *
37
+ * `paddleIds.test.ts` beside this file is also the sweep that keeps these two patterns the only ones:
38
+ * it fails when any other module in the package interrogates a Paddle id prefix.
39
+ */
40
+ const TRANSACTION_ID = /^txn_[a-z0-9]+$/;
41
+
42
+ /** A subscription, the other half of the same rule. See the module doc for why both live here. */
43
+ const SUBSCRIPTION_ID = /^sub_[a-z0-9]+$/;
44
+
45
+ /**
46
+ * Whether a value is shaped like a Paddle transaction id.
47
+ *
48
+ * Shape only. It says nothing about whether the transaction exists, who it belongs to, or what it is for —
49
+ * a caller acting on any of that has to ask Paddle, and `verify.ts` is what does. This is the cheap check
50
+ * that comes first.
51
+ *
52
+ * **`boolean`, deliberately, not `value is string`.** The predicate is the tempting signature and it makes
53
+ * the *false* branch `never` for a caller whose value is already a string — which is every caller that
54
+ * matters. `verify.ts` refuses a malformed receipt with a message naming `id.length`, and under a predicate
55
+ * that line stopped compiling. Nothing here needs the narrowing: the one caller holding `string | null` has
56
+ * already narrowed on `!== null` before asking, and Zod's `.refine` wants a boolean.
57
+ */
58
+ export function isPaddleTransactionId(value: unknown): boolean {
59
+ return typeof value === "string" && TRANSACTION_ID.test(value);
60
+ }
61
+
62
+ /**
63
+ * Whether a value is shaped like a Paddle subscription id.
64
+ *
65
+ * Shape only, and `boolean` rather than a type predicate, for the reasons {@link isPaddleTransactionId}
66
+ * gives — the three rail callers all hold a `string` already and want the false branch to stay reachable.
67
+ *
68
+ * The three callers read a purchase row's `providerTransactionId` and ask whether it names a subscription
69
+ * rather than one of its payments: `refresh.ts` to decide which endpoint to re-read, twice, and
70
+ * `subscription.ts` to decide whether there is a subscription to quote, change, cancel or keep at all.
71
+ */
72
+ export function isPaddleSubscriptionId(value: unknown): boolean {
73
+ return typeof value === "string" && SUBSCRIPTION_ID.test(value);
74
+ }
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import { commandName } from "@pithy-sh/core/src/cli/command";
4
5
  import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
5
6
  import type { PaymentsSubjectResolver } from "./subjectSeam";
6
7
 
@@ -57,8 +58,7 @@ export const unimplementedSubject: PaymentsSubjectResolver = Object.defineProper
57
58
  throw new InternalError({
58
59
  message: "The subject resolver for this project has not been written.",
59
60
  action: "Implement resolveSubject in this Worker's src/billing/subject.ts.",
60
- detail:
61
- 'pithy add scaffolded an unimplemented resolveSubject and it is still the one composed. Under billingSubject: "organization" only the application can say which organization a caller is acting for.',
61
+ detail: `The resolveSubject that ${commandName("add")} scaffolded is unimplemented, and it is still the one composed. Under billingSubject: "organization" only the application can say which organization a caller is acting for.`,
62
62
  });
63
63
  },
64
64
  UNIMPLEMENTED_SUBJECT,
@@ -83,7 +83,6 @@ export function requireImplementedSubject(resolver: PaymentsSubjectResolver | un
83
83
  message: "This project bills organizations, and its subject resolver is still the scaffolded placeholder.",
84
84
  action:
85
85
  'Implement resolveSubject in this Worker\'s src/billing/subject.ts, or set `billingSubject: "user"` in pithy.config.ts.',
86
- detail:
87
- "pithy add wrote src/billing/subject.ts exporting an unimplemented resolveSubject, and it is unchanged. Payments has no members table and never guesses a holder, so booting on it would deny every entitlement gate and raise payments/subject_unresolved on every write, for every caller, forever.",
86
+ detail: `src/billing/subject.ts, as ${commandName("add")} wrote it, exports an unimplemented resolveSubject, and it is unchanged. Payments has no members table and never guesses a holder, so booting on it would deny every entitlement gate and raise payments/subject_unresolved on every write, for every caller, forever.`,
88
87
  });
89
88
  }
@@ -24,8 +24,9 @@ import { RefundRequestStatus, ScheduledSubscriptionChangeAction } from "../data/
24
24
  *
25
25
  * **Nothing here is a receipt.** `PaymentsPurchase.payload` is the whole verified provider response,
26
26
  * and a bearer artifact; the purchase view is the normalized projection of it, and there is no field
27
- * that carries the original. The webhook responses are deliberately absent from this file too — they
28
- * are acknowledgements addressed to Apple, Google and Stripe, not a contract offered to any client.
27
+ * that carries the original. The webhook acknowledgement is here only so the OpenAPI contract can say
28
+ * what a store receives — it is addressed to Apple, Google and the hosted stores, not a contract offered
29
+ * to any client.
29
30
  *
30
31
  * **A client's own views name no subject; the management views name both halves of one.** A player reads
31
32
  * its own rows, and who holds them is the answer the request already carried — echoing it back teaches a
@@ -807,6 +808,30 @@ export const PaymentsDiscountResponse = z
807
808
  .describe("One discount code, as the store minted it.");
808
809
  export type PaymentsDiscountResponse = z.output<typeof PaymentsDiscountResponse>;
809
810
 
811
+ /**
812
+ * What every webhook route answers a store once authenticity is established: always a 200, so the store
813
+ * stops redelivering. Three shapes share it — a redelivery of a finished event (`duplicate`), a delivery
814
+ * that projected nothing (`projected: false`), and one that projected a purchase (`projected: true` with
815
+ * the projection's `outcome`).
816
+ */
817
+ export const PaymentsWebhookAck = z
818
+ .object({
819
+ received: z.literal(true).describe("Always true. The delivery was authentic and is recorded."),
820
+ duplicate: z
821
+ .literal(true)
822
+ .optional()
823
+ .describe("Present when this event was already finished, so the delivery changed nothing."),
824
+ projected: z.boolean().optional().describe("Whether the delivery projected a purchase. Absent on a duplicate."),
825
+ outcome: z
826
+ .enum(["created", "updated", "ignored"])
827
+ .optional()
828
+ .describe(
829
+ "What the projection did, when one ran: a new purchase, a newer event applied, or an event no newer than the stored row.",
830
+ ),
831
+ })
832
+ .describe("The acknowledgement a store receives for an authentic webhook delivery.");
833
+ export type PaymentsWebhookAck = z.output<typeof PaymentsWebhookAck>;
834
+
810
835
  /**
811
836
  * ## The management read surface
812
837
  *
@@ -1070,9 +1095,9 @@ export type PaymentsAdminReconcileRunsResponse = z.output<typeof PaymentsAdminRe
1070
1095
  * job designed not to be blocked on, or invent the answer — and the answer is the one thing an operator pressed
1071
1096
  * the button to find out. So this says *started, here is its id*, and the run log is where the tally lands.
1072
1097
  *
1073
- * **`started: false` is a real answer rather than an error.** The pass is idempotent and the trigger is too: a
1074
- * second press while a run is in flight starts nothing and says so, which is a true sentence about somebody's
1075
- * catalog. Turning that into a 409 would make a nervous operator's second click look like a fault.
1098
+ * **`started` is `true` on every answer today.** A press either starts a pass or is refused with an error;
1099
+ * a second press while a run is in flight starts a second, and the pass is idempotent, so the two converge.
1100
+ * The field stays so a later trigger that declines a duplicate can say so without changing the shape.
1076
1101
  *
1077
1102
  * No count, no duration, no "queued position". Every one of those is a number a screen would print and nobody
1078
1103
  * could stand behind.
@@ -1081,7 +1106,9 @@ export const PaymentsAdminReconcileRunStarted = z
1081
1106
  .object({
1082
1107
  started: z
1083
1108
  .boolean()
1084
- .describe("Whether this request began a pass. False when one was already running, which is not a failure."),
1109
+ .describe(
1110
+ "Whether this request began a pass. Always true today: a press that starts nothing is refused with an error instead.",
1111
+ ),
1085
1112
  runId: z
1086
1113
  .string()
1087
1114
  .nullable()