@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.
- package/README.md +1 -0
- package/dist/client/api.d.ts +19 -0
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +26 -1
- package/dist/client/hooks.d.ts +43 -0
- package/dist/client/hooks.d.ts.map +1 -1
- package/dist/client/hooks.js +58 -2
- package/dist/client/paddleLink.d.ts +31 -0
- package/dist/client/paddleLink.d.ts.map +1 -0
- package/dist/client/paddleLink.js +37 -0
- package/dist/data/paddleIds.d.ts +28 -0
- package/dist/data/paddleIds.d.ts.map +1 -0
- package/dist/data/paddleIds.js +73 -0
- package/dist/entitlement/unimplementedSubject.d.ts.map +1 -1
- package/dist/entitlement/unimplementedSubject.js +3 -2
- package/dist/http/responses.d.ts +23 -5
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +24 -7
- package/dist/http/routes.d.ts +6 -2
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +210 -38
- package/dist/http/schemas.d.ts +21 -1
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +20 -2
- package/dist/http/webhookGuard.d.ts.map +1 -1
- package/dist/http/webhookGuard.js +1 -1
- package/dist/rails/paddle/events.d.ts.map +1 -1
- package/dist/rails/paddle/events.js +2 -1
- package/dist/rails/paddle/refresh.d.ts +10 -5
- package/dist/rails/paddle/refresh.d.ts.map +1 -1
- package/dist/rails/paddle/refresh.js +8 -5
- package/dist/rails/paddle/refund.d.ts.map +1 -1
- package/dist/rails/paddle/refund.js +10 -2
- package/dist/rails/paddle/subscription.d.ts.map +1 -1
- package/dist/rails/paddle/subscription.js +8 -3
- package/dist/rails/paddle/verify.d.ts.map +1 -1
- package/dist/rails/paddle/verify.js +2 -3
- package/dist/secret/registry.d.ts.map +1 -1
- package/dist/secret/registry.js +3 -2
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/workerConfig.d.ts.map +1 -1
- package/dist/workflows/workerConfig.js +8 -2
- package/docs/paddle.md +17 -2
- package/package.json +6 -6
- package/src/client/api.ts +35 -0
- package/src/client/hooks.ts +78 -0
- package/src/client/paddleLink.ts +41 -0
- package/src/data/paddleIds.ts +74 -0
- package/src/entitlement/unimplementedSubject.ts +3 -4
- package/src/http/responses.ts +33 -6
- package/src/http/routes.ts +729 -454
- package/src/http/schemas.ts +32 -1
- package/src/http/webhookGuard.ts +3 -2
- package/src/rails/paddle/events.ts +2 -1
- package/src/rails/paddle/refresh.ts +17 -10
- package/src/rails/paddle/refund.ts +10 -2
- package/src/rails/paddle/subscription.ts +8 -3
- package/src/rails/paddle/verify.ts +6 -4
- package/src/secret/registry.ts +3 -2
- package/src/version.generated.ts +1 -1
- 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
|
}
|
package/src/http/responses.ts
CHANGED
|
@@ -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
|
|
28
|
-
*
|
|
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
|
|
1074
|
-
* second press while a run is in flight starts
|
|
1075
|
-
*
|
|
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(
|
|
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()
|