@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
package/README.md CHANGED
@@ -21,6 +21,7 @@ _Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes
21
21
  | `POST /payments/restore` | Restore Purchases — rebind store history to the caller | bearer · session |
22
22
  | `GET /payments/pricing` | What the caller's own subscription pays, and when that changes | bearer · session |
23
23
  | `POST /payments/checkout` | Create a checkout, on Stripe, Lemon Squeezy or Paddle | bearer · session |
24
+ | `GET /payments/checkout/resume` | Paddle only — what a page needs to open the transaction a `_ptxn` payment link arrived for | **none** |
24
25
  | `POST /payments/portal` | Create a billing-portal session for the caller's own account | bearer · session |
25
26
  | `GET /payments/subscription` | Where the caller's own subscription stands, read live from the store | bearer · session |
26
27
  | `POST /payments/subscription/preview` | What moving to one catalog product would cost, before anything is committed | bearer · session |
@@ -352,6 +352,25 @@ export declare function createCheckout(input: {
352
352
  rail?: PaymentsHostedRail;
353
353
  discountCode?: string;
354
354
  }, options?: PaymentsClientOptions): Promise<PaymentsResult<PaymentsCheckoutHandoff>>;
355
+ /**
356
+ * What a page needs to open the transaction a Paddle payment link arrived for.
357
+ *
358
+ * **The transaction already exists, which is the whole difference from {@link createCheckout}.** Paddle
359
+ * created it before mailing the link — a past-due retry, a manually-collected invoice, a payment-method
360
+ * update — and appended `?_ptxn=<id>` to this project's Default payment link. So nothing is minted here;
361
+ * the id is read off the URL by `readPaddleLinkTransaction` in `./paddleLink` and this asks the server for
362
+ * the account and presentation that go with it.
363
+ *
364
+ * **Why a round trip at all, when the browser already holds the id.** Because `successUrl` is not the
365
+ * browser's to name. The handoff carries where a paying buyer is sent, and a page that could choose it
366
+ * could send a paying customer somewhere it controls — the same rule the minted path states on the field
367
+ * itself. The client token and the display mode travel with it for the same reason they do there: one
368
+ * source of truth for which Paddle account this project sells through.
369
+ *
370
+ * Sends no credentials of consequence and needs none: the route is unauthenticated, because the buyer
371
+ * following a dunning link days later is usually signed out.
372
+ */
373
+ export declare function resumeCheckout(transactionId: string, options?: PaymentsClientOptions): Promise<PaymentsResult<PaddleCheckoutHandoff>>;
355
374
  /**
356
375
  * Create a Billing Portal session for the caller's own store account.
357
376
  *
@@ -1 +1 @@
1
- {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}
@@ -318,6 +318,31 @@ function restorePurchases(input, options) {
318
318
  function createCheckout(input, options) {
319
319
  return callPayments("/checkout", jsonPost(input), options, isCheckoutHandoff);
320
320
  }
321
+ /** Whether a value is a Paddle handoff specifically — the only shape the resume read answers with. */
322
+ function isPaddleResumeHandoff(value) {
323
+ return isCheckoutHandoff(value) && value.kind === "paddle";
324
+ }
325
+ /**
326
+ * What a page needs to open the transaction a Paddle payment link arrived for.
327
+ *
328
+ * **The transaction already exists, which is the whole difference from {@link createCheckout}.** Paddle
329
+ * created it before mailing the link — a past-due retry, a manually-collected invoice, a payment-method
330
+ * update — and appended `?_ptxn=<id>` to this project's Default payment link. So nothing is minted here;
331
+ * the id is read off the URL by `readPaddleLinkTransaction` in `./paddleLink` and this asks the server for
332
+ * the account and presentation that go with it.
333
+ *
334
+ * **Why a round trip at all, when the browser already holds the id.** Because `successUrl` is not the
335
+ * browser's to name. The handoff carries where a paying buyer is sent, and a page that could choose it
336
+ * could send a paying customer somewhere it controls — the same rule the minted path states on the field
337
+ * itself. The client token and the display mode travel with it for the same reason they do there: one
338
+ * source of truth for which Paddle account this project sells through.
339
+ *
340
+ * Sends no credentials of consequence and needs none: the route is unauthenticated, because the buyer
341
+ * following a dunning link days later is usually signed out.
342
+ */
343
+ function resumeCheckout(transactionId, options) {
344
+ return callPayments(`/checkout/resume?transaction=${encodeURIComponent(transactionId)}`, {}, options, isPaddleResumeHandoff);
345
+ }
321
346
  /**
322
347
  * Create a Billing Portal session for the caller's own store account.
323
348
  *
@@ -414,4 +439,4 @@ function returnedCheckoutSession(options) {
414
439
  return value === null || value === "" ? null : value;
415
440
  }
416
441
  //#endregion
417
- export { CHECKOUT_SESSION_PARAM, PAYMENTS_BASE_PATH, PAYMENTS_HOSTED_RAILS, PAYMENTS_NO_BROWSER, PAYMENTS_UNREACHABLE, PAYMENTS_UNREADABLE, STORE_SUBSCRIPTION_URLS, callPayments, createCheckout, createPortal, getEntitlements, isEntitlementView, isPurchaseView, openBillingPortal, openStoreSubscriptions, restorePurchases, returnedCheckoutSession, startCheckout, submitPurchase };
442
+ export { CHECKOUT_SESSION_PARAM, PAYMENTS_BASE_PATH, PAYMENTS_HOSTED_RAILS, PAYMENTS_NO_BROWSER, PAYMENTS_UNREACHABLE, PAYMENTS_UNREADABLE, STORE_SUBSCRIPTION_URLS, callPayments, createCheckout, createPortal, getEntitlements, isEntitlementView, isPurchaseView, openBillingPortal, openStoreSubscriptions, restorePurchases, resumeCheckout, returnedCheckoutSession, startCheckout, submitPurchase };
@@ -141,6 +141,49 @@ export interface UsePaddleCheckout {
141
141
  * overlay and clicked Buy again arrives with a new transaction, and that one must open.
142
142
  */
143
143
  export declare function usePaddleCheckout(handoff: PaddleCheckoutHandoff | null, options?: PaddleCheckoutOptions): UsePaddleCheckout;
144
+ /** What {@link usePaddleLink} gives the screen a Paddle payment link lands on. */
145
+ export interface UsePaddleLink {
146
+ /**
147
+ * The handoff to open, or null.
148
+ *
149
+ * Null covers three different facts and deliberately reads as one: there was no `_ptxn` in the URL, there
150
+ * was one and it was not a transaction id, or the server has not answered yet. A screen renders its
151
+ * ordinary state for all three, which is what it was already rendering before this hook existed.
152
+ */
153
+ handoff: PaddleCheckoutHandoff | null;
154
+ /** Whether the resume read is in flight. A screen with nothing to show need not read it. */
155
+ loading: boolean;
156
+ /** The refusal, or null. A rail that is off, or a mode that cannot resume. */
157
+ failure: PaymentsFailure | null;
158
+ }
159
+ /**
160
+ * Resume the checkout a Paddle payment link arrived for.
161
+ *
162
+ * **The inbound half of Paddle's *Default payment link*.** Paddle appends `?_ptxn=<transaction_id>` to it
163
+ * and expects this page to open a checkout for that transaction. Those are the links Paddle sends rather
164
+ * than ones this kit opened: a past-due dunning mail, a manually-collected invoice, the payment-method
165
+ * update link minted for a subscription. `useCheckout` cannot serve them — it mints a transaction, and here
166
+ * one already exists.
167
+ *
168
+ * **Pass the result to {@link usePaddleCheckout}, which opens it.** Nothing about opening is reimplemented
169
+ * here, and that is the point: the one-open-per-transaction guard, the `StrictMode` second pass, and the
170
+ * `PADDLE_NO_CONTAINER` refusal when an inline container is missing are all inherited by going through the
171
+ * same hook the minted path goes through.
172
+ *
173
+ * **In inline mode the page must already render the container.** Paddle finds it by class name when `open`
174
+ * is called, so a Default payment link pointing at a page that does not render one produces a refusal
175
+ * rather than a checkout — which makes the choice of landing page part of configuring this, not a detail.
176
+ * `docs/paddle.md` says so where an adopter sets the link.
177
+ *
178
+ * Reads `location.search` once, on mount. A link is a navigation, so there is no later arrival to watch for.
179
+ *
180
+ * **One read per transaction, remembered rather than assumed.** The same rule {@link usePaddleCheckout}
181
+ * states and for the same reason: `StrictMode` runs every effect, cleans it up and runs it again, and that
182
+ * is the mode `pithy ui add` scaffolds. Without the ref this asked the server twice on every mount — not
183
+ * harmful, since the route only echoes config, and still two requests where the file beside it had already
184
+ * solved the problem.
185
+ */
186
+ export declare function usePaddleLink(options?: PaymentsClientOptions): UsePaddleLink;
144
187
  /** What {@link usePurchase} gives the screen that submits receipts. */
145
188
  export interface UsePurchase {
146
189
  /** Submit one receipt for verification. */
@@ -1 +1 @@
1
- {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/client/hooks.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/client/hooks.ts"],"names":[],"mappings":"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"}
@@ -1,8 +1,9 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { getEntitlements, openBillingPortal, openStoreSubscriptions, restorePurchases, startCheckout, submitPurchase } from "./api.js";
3
+ import { getEntitlements, openBillingPortal, openStoreSubscriptions, restorePurchases, resumeCheckout, startCheckout, submitPurchase } from "./api.js";
4
4
  import { loadPaddle, previewPrices, priceQueryKey } from "./paddle.js";
5
5
  import { openPaddleCheckout } from "./checkout.js";
6
+ import { readPaddleLinkTransaction } from "./paddleLink.js";
6
7
  import { useCallback, useEffect, useRef, useState } from "react";
7
8
  //#region src/client/hooks.ts
8
9
  /**
@@ -247,6 +248,61 @@ function usePaddleCheckout(handoff, options) {
247
248
  };
248
249
  }
249
250
  /**
251
+ * Resume the checkout a Paddle payment link arrived for.
252
+ *
253
+ * **The inbound half of Paddle's *Default payment link*.** Paddle appends `?_ptxn=<transaction_id>` to it
254
+ * and expects this page to open a checkout for that transaction. Those are the links Paddle sends rather
255
+ * than ones this kit opened: a past-due dunning mail, a manually-collected invoice, the payment-method
256
+ * update link minted for a subscription. `useCheckout` cannot serve them — it mints a transaction, and here
257
+ * one already exists.
258
+ *
259
+ * **Pass the result to {@link usePaddleCheckout}, which opens it.** Nothing about opening is reimplemented
260
+ * here, and that is the point: the one-open-per-transaction guard, the `StrictMode` second pass, and the
261
+ * `PADDLE_NO_CONTAINER` refusal when an inline container is missing are all inherited by going through the
262
+ * same hook the minted path goes through.
263
+ *
264
+ * **In inline mode the page must already render the container.** Paddle finds it by class name when `open`
265
+ * is called, so a Default payment link pointing at a page that does not render one produces a refusal
266
+ * rather than a checkout — which makes the choice of landing page part of configuring this, not a detail.
267
+ * `docs/paddle.md` says so where an adopter sets the link.
268
+ *
269
+ * Reads `location.search` once, on mount. A link is a navigation, so there is no later arrival to watch for.
270
+ *
271
+ * **One read per transaction, remembered rather than assumed.** The same rule {@link usePaddleCheckout}
272
+ * states and for the same reason: `StrictMode` runs every effect, cleans it up and runs it again, and that
273
+ * is the mode `pithy ui add` scaffolds. Without the ref this asked the server twice on every mount — not
274
+ * harmful, since the route only echoes config, and still two requests where the file beside it had already
275
+ * solved the problem.
276
+ */
277
+ function usePaddleLink(options) {
278
+ const [handoff, setHandoff] = useState(null);
279
+ const [loading, setLoading] = useState(false);
280
+ const [failure, setFailure] = useState(null);
281
+ const latest = useLatest(options);
282
+ const live = useLive();
283
+ /** The transaction this hook has already asked about, so a second effect pass asks nothing. */
284
+ const asked = useRef(null);
285
+ useEffect(() => {
286
+ const search = globalThis.location?.search;
287
+ const transactionId = search === void 0 ? null : readPaddleLinkTransaction(search);
288
+ if (transactionId === null) return;
289
+ if (asked.current === transactionId) return;
290
+ asked.current = transactionId;
291
+ setLoading(true);
292
+ resumeCheckout(transactionId, latest.current).then((outcome) => {
293
+ if (!live.current) return;
294
+ setLoading(false);
295
+ if (outcome.ok) setHandoff(outcome.value);
296
+ else setFailure(outcome.failure);
297
+ });
298
+ }, [latest, live]);
299
+ return {
300
+ handoff,
301
+ loading,
302
+ failure
303
+ };
304
+ }
305
+ /**
250
306
  * Submitting receipts — the path that exists so a buyer sees their entitlement now rather than when the
251
307
  * webhook lands.
252
308
  *
@@ -427,4 +483,4 @@ function usePricePreview(setup, query, options) {
427
483
  };
428
484
  }
429
485
  //#endregion
430
- export { useCheckout, useEntitlement, usePaddle, usePaddleCheckout, usePricePreview, usePurchase, useSubscription };
486
+ export { useCheckout, useEntitlement, usePaddle, usePaddleCheckout, usePaddleLink, usePricePreview, usePurchase, useSubscription };
@@ -0,0 +1,31 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ /**
4
+ * The query parameter Paddle appends to a seller's **Default payment link**.
5
+ *
6
+ * Named once, because Paddle does not document it as stable and a literal at two call sites is how one of
7
+ * them survives a rename. This is the thing to grep for if it ever moves.
8
+ */
9
+ export declare const PADDLE_LINK_PARAM = "_ptxn";
10
+ /**
11
+ * The transaction Paddle put in this page's URL, or null.
12
+ *
13
+ * **Paddle's own links are the ones that arrive here**, not any this kit opened: a past-due dunning mail,
14
+ * a manually-collected invoice's pay link, the payment-method-update link Paddle mints for a subscription.
15
+ * Each is the seller's *Default payment link* with `?_ptxn=<transaction_id>` on the end, and the contract
16
+ * is that the page it lands on opens a checkout for that transaction.
17
+ *
18
+ * **Null is the ordinary answer and is not a failure.** Every page this is called on is loaded without a
19
+ * `_ptxn` almost every time, so an absent parameter reads as "nothing to resume" and a screen renders
20
+ * exactly as it did before this existed. A malformed one reads the same way, which is the second half of
21
+ * the point: the value comes from outside, from a URL, from somebody who may not be signed in, and it is
22
+ * about to be sent to a route and then handed to `Paddle.Checkout.open`. The only thing that makes it safe
23
+ * to pass on is that it is shaped like a transaction id — so anything else is null rather than an error
24
+ * worth telling a buyer about, because a buyer cannot act on it and an attacker already knows.
25
+ *
26
+ * The shape check is {@link isPaddleTransactionId}, which is the rail's own and is shared rather than
27
+ * copied. Takes a search string rather than reading `location` itself, so this is a pure function and the
28
+ * hook that owns the browser is the only thing that needs one.
29
+ */
30
+ export declare function readPaddleLinkTransaction(search: string): string | null;
31
+ //# sourceMappingURL=paddleLink.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paddleLink.d.ts","sourceRoot":"","sources":["../../src/client/paddleLink.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE"}
@@ -0,0 +1,37 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { isPaddleTransactionId } from "../data/paddleIds.js";
4
+ //#region src/client/paddleLink.ts
5
+ /**
6
+ * The query parameter Paddle appends to a seller's **Default payment link**.
7
+ *
8
+ * Named once, because Paddle does not document it as stable and a literal at two call sites is how one of
9
+ * them survives a rename. This is the thing to grep for if it ever moves.
10
+ */
11
+ const PADDLE_LINK_PARAM = "_ptxn";
12
+ /**
13
+ * The transaction Paddle put in this page's URL, or null.
14
+ *
15
+ * **Paddle's own links are the ones that arrive here**, not any this kit opened: a past-due dunning mail,
16
+ * a manually-collected invoice's pay link, the payment-method-update link Paddle mints for a subscription.
17
+ * Each is the seller's *Default payment link* with `?_ptxn=<transaction_id>` on the end, and the contract
18
+ * is that the page it lands on opens a checkout for that transaction.
19
+ *
20
+ * **Null is the ordinary answer and is not a failure.** Every page this is called on is loaded without a
21
+ * `_ptxn` almost every time, so an absent parameter reads as "nothing to resume" and a screen renders
22
+ * exactly as it did before this existed. A malformed one reads the same way, which is the second half of
23
+ * the point: the value comes from outside, from a URL, from somebody who may not be signed in, and it is
24
+ * about to be sent to a route and then handed to `Paddle.Checkout.open`. The only thing that makes it safe
25
+ * to pass on is that it is shaped like a transaction id — so anything else is null rather than an error
26
+ * worth telling a buyer about, because a buyer cannot act on it and an attacker already knows.
27
+ *
28
+ * The shape check is {@link isPaddleTransactionId}, which is the rail's own and is shared rather than
29
+ * copied. Takes a search string rather than reading `location` itself, so this is a pure function and the
30
+ * hook that owns the browser is the only thing that needs one.
31
+ */
32
+ function readPaddleLinkTransaction(search) {
33
+ const value = new URLSearchParams(search).get(PADDLE_LINK_PARAM);
34
+ return value !== null && isPaddleTransactionId(value) ? value : null;
35
+ }
36
+ //#endregion
37
+ export { PADDLE_LINK_PARAM, readPaddleLinkTransaction };
@@ -0,0 +1,28 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ /**
4
+ * Whether a value is shaped like a Paddle transaction id.
5
+ *
6
+ * Shape only. It says nothing about whether the transaction exists, who it belongs to, or what it is for —
7
+ * a caller acting on any of that has to ask Paddle, and `verify.ts` is what does. This is the cheap check
8
+ * that comes first.
9
+ *
10
+ * **`boolean`, deliberately, not `value is string`.** The predicate is the tempting signature and it makes
11
+ * the *false* branch `never` for a caller whose value is already a string — which is every caller that
12
+ * matters. `verify.ts` refuses a malformed receipt with a message naming `id.length`, and under a predicate
13
+ * that line stopped compiling. Nothing here needs the narrowing: the one caller holding `string | null` has
14
+ * already narrowed on `!== null` before asking, and Zod's `.refine` wants a boolean.
15
+ */
16
+ export declare function isPaddleTransactionId(value: unknown): boolean;
17
+ /**
18
+ * Whether a value is shaped like a Paddle subscription id.
19
+ *
20
+ * Shape only, and `boolean` rather than a type predicate, for the reasons {@link isPaddleTransactionId}
21
+ * gives — the three rail callers all hold a `string` already and want the false branch to stay reachable.
22
+ *
23
+ * The three callers read a purchase row's `providerTransactionId` and ask whether it names a subscription
24
+ * rather than one of its payments: `refresh.ts` to decide which endpoint to re-read, twice, and
25
+ * `subscription.ts` to decide whether there is a subscription to quote, change, cancel or keep at all.
26
+ */
27
+ export declare function isPaddleSubscriptionId(value: unknown): boolean;
28
+ //# sourceMappingURL=paddleIds.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paddleIds.d.ts","sourceRoot":"","sources":["../../src/data/paddleIds.ts"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D"}
@@ -0,0 +1,73 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ //#region src/data/paddleIds.ts
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
+ /** A subscription, the other half of the same rule. See the module doc for why both live here. */
42
+ const SUBSCRIPTION_ID = /^sub_[a-z0-9]+$/;
43
+ /**
44
+ * Whether a value is shaped like a Paddle transaction id.
45
+ *
46
+ * Shape only. It says nothing about whether the transaction exists, who it belongs to, or what it is for —
47
+ * a caller acting on any of that has to ask Paddle, and `verify.ts` is what does. This is the cheap check
48
+ * that comes first.
49
+ *
50
+ * **`boolean`, deliberately, not `value is string`.** The predicate is the tempting signature and it makes
51
+ * the *false* branch `never` for a caller whose value is already a string — which is every caller that
52
+ * matters. `verify.ts` refuses a malformed receipt with a message naming `id.length`, and under a predicate
53
+ * that line stopped compiling. Nothing here needs the narrowing: the one caller holding `string | null` has
54
+ * already narrowed on `!== null` before asking, and Zod's `.refine` wants a boolean.
55
+ */
56
+ function isPaddleTransactionId(value) {
57
+ return typeof value === "string" && TRANSACTION_ID.test(value);
58
+ }
59
+ /**
60
+ * Whether a value is shaped like a Paddle subscription id.
61
+ *
62
+ * Shape only, and `boolean` rather than a type predicate, for the reasons {@link isPaddleTransactionId}
63
+ * gives — the three rail callers all hold a `string` already and want the false branch to stay reachable.
64
+ *
65
+ * The three callers read a purchase row's `providerTransactionId` and ask whether it names a subscription
66
+ * rather than one of its payments: `refresh.ts` to decide which endpoint to re-read, twice, and
67
+ * `subscription.ts` to decide whether there is a subscription to quote, change, cancel or keep at all.
68
+ */
69
+ function isPaddleSubscriptionId(value) {
70
+ return typeof value === "string" && SUBSCRIPTION_ID.test(value);
71
+ }
72
+ //#endregion
73
+ export { isPaddleSubscriptionId, isPaddleTransactionId };
@@ -1 +1 @@
1
- {"version":3,"file":"unimplementedSubject.d.ts","sourceRoot":"","sources":["../../src/entitlement/unimplementedSubject.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAwC7D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,uBAWP,CAAC;AAE7B,mGAAmG;AACnG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,OAAO,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI,CAS7F"}
1
+ {"version":3,"file":"unimplementedSubject.d.ts","sourceRoot":"","sources":["../../src/entitlement/unimplementedSubject.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAwC7D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,uBAUP,CAAC;AAE7B,mGAAmG;AACnG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,OAAO,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI,CAQ7F"}
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
4
+ import { commandName } from "@pithy-sh/core/src/cli/command";
4
5
  //#region src/entitlement/unimplementedSubject.ts
5
6
  /**
6
7
  * The placeholder `pithy add payments --set billingSubject=organization` scaffolds, and the brand that
@@ -52,7 +53,7 @@ const unimplementedSubject = Object.defineProperty(async () => {
52
53
  throw new InternalError({
53
54
  message: "The subject resolver for this project has not been written.",
54
55
  action: "Implement resolveSubject in this Worker's src/billing/subject.ts.",
55
- detail: "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."
56
+ 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.`
56
57
  });
57
58
  }, UNIMPLEMENTED_SUBJECT, { value: true });
58
59
  /** Whether this resolver is the scaffolded placeholder rather than something the adopter wrote. */
@@ -71,7 +72,7 @@ function requireImplementedSubject(resolver) {
71
72
  throw new ValidationError({
72
73
  message: "This project bills organizations, and its subject resolver is still the scaffolded placeholder.",
73
74
  action: "Implement resolveSubject in this Worker's src/billing/subject.ts, or set `billingSubject: \"user\"` in pithy.config.ts.",
74
- detail: "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."
75
+ 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.`
75
76
  });
76
77
  }
77
78
  //#endregion
@@ -16,8 +16,9 @@ import { z } from "zod";
16
16
  *
17
17
  * **Nothing here is a receipt.** `PaymentsPurchase.payload` is the whole verified provider response,
18
18
  * and a bearer artifact; the purchase view is the normalized projection of it, and there is no field
19
- * that carries the original. The webhook responses are deliberately absent from this file too — they
20
- * are acknowledgements addressed to Apple, Google and Stripe, not a contract offered to any client.
19
+ * that carries the original. The webhook acknowledgement is here only so the OpenAPI contract can say
20
+ * what a store receives — it is addressed to Apple, Google and the hosted stores, not a contract offered
21
+ * to any client.
21
22
  *
22
23
  * **A client's own views name no subject; the management views name both halves of one.** A player reads
23
24
  * its own rows, and who holds them is the answer the request already carried — echoing it back teaches a
@@ -1057,6 +1058,23 @@ export declare const PaymentsDiscountResponse: z.ZodObject<{
1057
1058
  }>;
1058
1059
  }, z.core.$strip>;
1059
1060
  export type PaymentsDiscountResponse = z.output<typeof PaymentsDiscountResponse>;
1061
+ /**
1062
+ * What every webhook route answers a store once authenticity is established: always a 200, so the store
1063
+ * stops redelivering. Three shapes share it — a redelivery of a finished event (`duplicate`), a delivery
1064
+ * that projected nothing (`projected: false`), and one that projected a purchase (`projected: true` with
1065
+ * the projection's `outcome`).
1066
+ */
1067
+ export declare const PaymentsWebhookAck: z.ZodObject<{
1068
+ received: z.ZodLiteral<true>;
1069
+ duplicate: z.ZodOptional<z.ZodLiteral<true>>;
1070
+ projected: z.ZodOptional<z.ZodBoolean>;
1071
+ outcome: z.ZodOptional<z.ZodEnum<{
1072
+ created: "created";
1073
+ ignored: "ignored";
1074
+ updated: "updated";
1075
+ }>>;
1076
+ }, z.core.$strip>;
1077
+ export type PaymentsWebhookAck = z.output<typeof PaymentsWebhookAck>;
1060
1078
  /**
1061
1079
  * ## The management read surface
1062
1080
  *
@@ -1293,9 +1311,9 @@ export type PaymentsAdminReconcileRunsResponse = z.output<typeof PaymentsAdminRe
1293
1311
  * job designed not to be blocked on, or invent the answer — and the answer is the one thing an operator pressed
1294
1312
  * the button to find out. So this says *started, here is its id*, and the run log is where the tally lands.
1295
1313
  *
1296
- * **`started: false` is a real answer rather than an error.** The pass is idempotent and the trigger is too: a
1297
- * second press while a run is in flight starts nothing and says so, which is a true sentence about somebody's
1298
- * catalog. Turning that into a 409 would make a nervous operator's second click look like a fault.
1314
+ * **`started` is `true` on every answer today.** A press either starts a pass or is refused with an error;
1315
+ * a second press while a run is in flight starts a second, and the pass is idempotent, so the two converge.
1316
+ * The field stays so a later trigger that declines a duplicate can say so without changing the shape.
1299
1317
  *
1300
1318
  * No count, no duration, no "queued position". Every one of those is a number a screen would print and nobody
1301
1319
  * could stand behind.
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB;;;;iBAMqD,CAAC;AAC1F,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E,0GAA0G;AAC1G,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwBoE,CAAC;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK+B,CAAC;AACrE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,2DAA2D;AAC3D,eAAO,MAAM,4BAA4B;;;;;;iBAES,CAAC;AACnD,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEzF,6BAA6B;AAC7B,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKiD,CAAC;AACtF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;2BA6BsD,CAAC;AACnG,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE/F;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;;;;;;;iBAgBmE,CAAC;AAC9G,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAEuD,CAAC;AAChG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAagD,CAAC;AACrF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;iBAQyE,CAAC;AACzG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAKmC,CAAC;AACxE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,mBAAmB;;;;iBAgB2E,CAAC;AAC5G,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA4DvE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAEwE,CAAC;AACpH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAEwD,CAAC;AAC5G,MAAM,MAAM,sCAAsC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAgC7G,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BnC,CAAC;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;iBAekE,CAAC;AACnH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEvG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;2BAqB6D,CAAC;AACxG,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmC+E,CAAC;AACrH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM2C,CAAC;AACrF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEzF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI4D,CAAC;AAC9G,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAEzG;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE8D,CAAC;AAC7G,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAEnG;;;;;;;;;;;;;;;;;GAiBG;AAEH,6IAA6I;AAC7I,eAAO,MAAM,2BAA2B;;;;;;EAEvC,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAuCvF,oHAAoH;AACpH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;8BAEgF,CAAC;AACnH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;iBAQ8E,CAAC;AACjH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,mEAAmE;AACnE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;iBAEqD,CAAC;AACzF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B;;;;;;;iBAmByB,CAAC;AACrE,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE7F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;iBAMoB,CAAC;AAC1D,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;iBAW0D,CAAC;AACnG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEvF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;8BAyBsE,CAAC;AAChH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAQzF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoDwD,CAAC;AAC/F,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;iBAyB8D,CAAC;AACxG,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEzF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;iBA0ByE,CAAC;AACpH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKK,CAAC;AACrD,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAErG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gCAAgC;;;iBAY2D,CAAC;AACzG,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAEjG,oCAAoC;AACpC,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKD,CAAC;AAC3C,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE7F,yFAAyF;AACzF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOG,CAAC;AACnD,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAErG,uCAAuC;AACvC,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;iBAKuB,CAAC;AACtE,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAEnG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;iBAUG,CAAC;AACzD,MAAM,MAAM,wCAAwC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wCAAwC,CAAC,CAAC"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
@@ -23,8 +23,9 @@ import { z } from "zod";
23
23
  *
24
24
  * **Nothing here is a receipt.** `PaymentsPurchase.payload` is the whole verified provider response,
25
25
  * and a bearer artifact; the purchase view is the normalized projection of it, and there is no field
26
- * that carries the original. The webhook responses are deliberately absent from this file too — they
27
- * are acknowledgements addressed to Apple, Google and Stripe, not a contract offered to any client.
26
+ * that carries the original. The webhook acknowledgement is here only so the OpenAPI contract can say
27
+ * what a store receives — it is addressed to Apple, Google and the hosted stores, not a contract offered
28
+ * to any client.
28
29
  *
29
30
  * **A client's own views name no subject; the management views name both halves of one.** A player reads
30
31
  * its own rows, and who holds them is the answer the request already carried — echoing it back teaches a
@@ -529,6 +530,22 @@ const PaymentsDiscountResponse = z.object({
529
530
  rail: PaymentsHostedRail.describe("Which store now holds it.")
530
531
  }).describe("One discount code, as the store minted it.");
531
532
  /**
533
+ * What every webhook route answers a store once authenticity is established: always a 200, so the store
534
+ * stops redelivering. Three shapes share it — a redelivery of a finished event (`duplicate`), a delivery
535
+ * that projected nothing (`projected: false`), and one that projected a purchase (`projected: true` with
536
+ * the projection's `outcome`).
537
+ */
538
+ const PaymentsWebhookAck = z.object({
539
+ received: z.literal(true).describe("Always true. The delivery was authentic and is recorded."),
540
+ duplicate: z.literal(true).optional().describe("Present when this event was already finished, so the delivery changed nothing."),
541
+ projected: z.boolean().optional().describe("Whether the delivery projected a purchase. Absent on a duplicate."),
542
+ outcome: z.enum([
543
+ "created",
544
+ "updated",
545
+ "ignored"
546
+ ]).optional().describe("What the projection did, when one ran: a new purchase, a newer event applied, or an event no newer than the stored row.")
547
+ }).describe("The acknowledgement a store receives for an authentic webhook delivery.");
548
+ /**
532
549
  * ## The management read surface
533
550
  *
534
551
  * Everything below answers a **control-plane** route, so it is read by a dashboard across a trust
@@ -683,15 +700,15 @@ const PaymentsAdminReconcileRunsResponse = z.object({
683
700
  * job designed not to be blocked on, or invent the answer — and the answer is the one thing an operator pressed
684
701
  * the button to find out. So this says *started, here is its id*, and the run log is where the tally lands.
685
702
  *
686
- * **`started: false` is a real answer rather than an error.** The pass is idempotent and the trigger is too: a
687
- * second press while a run is in flight starts nothing and says so, which is a true sentence about somebody's
688
- * catalog. Turning that into a 409 would make a nervous operator's second click look like a fault.
703
+ * **`started` is `true` on every answer today.** A press either starts a pass or is refused with an error;
704
+ * a second press while a run is in flight starts a second, and the pass is idempotent, so the two converge.
705
+ * The field stays so a later trigger that declines a duplicate can say so without changing the shape.
689
706
  *
690
707
  * No count, no duration, no "queued position". Every one of those is a number a screen would print and nobody
691
708
  * could stand behind.
692
709
  */
693
710
  const PaymentsAdminReconcileRunStarted = z.object({
694
- started: z.boolean().describe("Whether this request began a pass. False when one was already running, which is not a failure."),
711
+ started: z.boolean().describe("Whether this request began a pass. Always true today: a press that starts nothing is refused with an error instead."),
695
712
  runId: z.string().nullable().describe("The Workflow instance that was started, so a caller can find this pass in the run log once it finishes. Null when `started` is false — there is no instance of *this* request to name, and naming the one already running would attribute somebody else's pass to this press.")
696
713
  }).describe("What a press on the reconciliation trigger produced: whether a pass began, and which one.");
697
714
  /** `GET {base}/admin/purchases`. */
@@ -727,4 +744,4 @@ const PaymentsAdminSubjectEntitlementsResponse = z.object({
727
744
  entitlements: z.array(PaymentsAdminEntitlementView).describe("Every entitlement this subject holds, by key. Empty when it holds none.")
728
745
  }).describe("One subject's entitlements, resolved now.");
729
746
  //#endregion
730
- export { PaymentsAdminCatalogProduct, PaymentsAdminCatalogResponse, PaymentsAdminDiscountsResponse, PaymentsAdminEntitlementView, PaymentsAdminEntitlementsResponse, PaymentsAdminPurchaseView, PaymentsAdminPurchasesResponse, PaymentsAdminReconcileRunStarted, PaymentsAdminReconcileRunView, PaymentsAdminReconcileRunsResponse, PaymentsAdminSubjectEntitlementsResponse, PaymentsAdminSubscriptionsResponse, PaymentsCheckoutHandoffResponse, PaymentsDeferredSubscriptionSettlement, PaymentsDiscountResponse, PaymentsEntitlementResponse, PaymentsEntitlementView, PaymentsEntitlementsResponse, PaymentsPortalHandoffResponse, PaymentsPricingEnvelope, PaymentsPricingResponse, PaymentsPurchaseResponse, PaymentsPurchaseView, PaymentsQuotedFrom, PaymentsQuotedMoney, PaymentsRefundOutcome, PaymentsRefundRequest, PaymentsRefundRequestStatus, PaymentsRefundResponse, PaymentsRestoreResponse, PaymentsSubscriptionNextEvent, PaymentsSubscriptionQuote, PaymentsSubscriptionQuoteResponse, PaymentsSubscriptionResponse, PaymentsSubscriptionScheduledChange, PaymentsSubscriptionSettlement, PaymentsSubscriptionStandingResponse, PaymentsSubscriptionView };
747
+ export { PaymentsAdminCatalogProduct, PaymentsAdminCatalogResponse, PaymentsAdminDiscountsResponse, PaymentsAdminEntitlementView, PaymentsAdminEntitlementsResponse, PaymentsAdminPurchaseView, PaymentsAdminPurchasesResponse, PaymentsAdminReconcileRunStarted, PaymentsAdminReconcileRunView, PaymentsAdminReconcileRunsResponse, PaymentsAdminSubjectEntitlementsResponse, PaymentsAdminSubscriptionsResponse, PaymentsCheckoutHandoffResponse, PaymentsDeferredSubscriptionSettlement, PaymentsDiscountResponse, PaymentsEntitlementResponse, PaymentsEntitlementView, PaymentsEntitlementsResponse, PaymentsPortalHandoffResponse, PaymentsPricingEnvelope, PaymentsPricingResponse, PaymentsPurchaseResponse, PaymentsPurchaseView, PaymentsQuotedFrom, PaymentsQuotedMoney, PaymentsRefundOutcome, PaymentsRefundRequest, PaymentsRefundRequestStatus, PaymentsRefundResponse, PaymentsRestoreResponse, PaymentsSubscriptionNextEvent, PaymentsSubscriptionQuote, PaymentsSubscriptionQuoteResponse, PaymentsSubscriptionResponse, PaymentsSubscriptionScheduledChange, PaymentsSubscriptionSettlement, PaymentsSubscriptionStandingResponse, PaymentsSubscriptionView, PaymentsWebhookAck };