@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
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/events.ts"],"names":[],"mappings":"
|
|
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
|
|
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:
|
|
18
|
-
*
|
|
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
|
|
53
|
-
* answers `undefined` — the same "nothing to say about
|
|
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;
|
|
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
|
|
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
|
|
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
|
|
42
|
-
* answers `undefined` — the same "nothing to say about
|
|
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
|
|
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":"
|
|
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
|
-
/**
|
|
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
|
|
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":"
|
|
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
|
|
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
|
|
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":"
|
|
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 (!
|
|
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":"
|
|
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"}
|
package/dist/secret/registry.js
CHANGED
|
@@ -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
|
|
151
|
-
action: `Take the ${rail} credentials from ${PAYMENTS_RAIL_CONSOLES[rail]} and set them with
|
|
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.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.4.0";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -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.
|
|
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;
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
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
|
+
"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.
|
|
46
|
-
"@pithy-sh/ledger": "^0.
|
|
47
|
-
"@pithy-sh/secrets": "^0.
|
|
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.
|
|
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.
|
|
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
|
*
|
package/src/client/hooks.ts
CHANGED
|
@@ -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
|
+
}
|