@pithy-sh/payments 0.3.6 → 0.3.8
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/dist/capability.d.ts +11 -3
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +33 -8
- package/dist/grants/apply.d.ts +11 -5
- package/dist/grants/apply.d.ts.map +1 -1
- package/dist/grants/apply.js +9 -6
- package/dist/grants/ledgerSeam.d.ts +34 -14
- package/dist/grants/ledgerSeam.d.ts.map +1 -1
- package/dist/grants/ledgerSeam.js +8 -16
- package/dist/http/routes.d.ts +8 -0
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +9 -8
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/peer.d.ts +78 -0
- package/dist/peer.d.ts.map +1 -0
- package/dist/peer.js +27 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/hostPeers.d.ts +37 -0
- package/dist/workflows/hostPeers.d.ts.map +1 -0
- package/dist/workflows/hostPeers.js +17 -0
- package/dist/workflows/paddleSweep.d.ts +3 -0
- package/dist/workflows/paddleSweep.d.ts.map +1 -1
- package/dist/workflows/paddleSweep.js +2 -0
- package/dist/workflows/reconcile.d.ts +6 -0
- package/dist/workflows/reconcile.d.ts.map +1 -1
- package/dist/workflows/reconcile.js +1 -0
- package/dist/workflows/worker.d.ts.map +1 -1
- package/dist/workflows/worker.js +3 -0
- package/package.json +3 -3
- package/src/capability.ts +60 -16
- package/src/grants/apply.ts +14 -8
- package/src/grants/ledgerSeam.ts +43 -33
- package/src/http/routes.ts +17 -8
- package/src/index.ts +2 -1
- package/src/peer.ts +29 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/hostPeers.ts +41 -0
- package/src/workflows/paddleSweep.ts +9 -2
- package/src/workflows/reconcile.ts +12 -1
- package/src/workflows/worker.ts +5 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
4
|
+
/**
|
|
5
|
+
* **The reconcile host's composition: the optional peers it was handed** (#645).
|
|
6
|
+
*
|
|
7
|
+
* An app Worker composes capabilities and `payments()`'s `compose` hook finds the ledger among them. This host
|
|
8
|
+
* composes nothing — it is a prebuilt Worker the adopter never authors — so it has no hook and nothing to find
|
|
9
|
+
* a ledger in. It still owes a credit when a pass repairs a purchase whose product has a `grants.ledger`
|
|
10
|
+
* clause, and it may not import `@pithy-sh/ledger` to make one, for the reason `grants/ledgerSeam.ts` gives.
|
|
11
|
+
*
|
|
12
|
+
* So `pithy` hands it over. When the project's catalog credits a balance, the CLI deploys this host from an
|
|
13
|
+
* entry it generates beside the resolved config, which imports the ledger's `ledgerPeer` from the project's
|
|
14
|
+
* own install and calls {@link providePeers} before re-exporting `worker.ts` unchanged. A catalog that credits
|
|
15
|
+
* nothing gets no entry: `main` stays `worker.ts`, and the bundle never meets the specifier.
|
|
16
|
+
*
|
|
17
|
+
* Its own module rather than an export of `worker.ts`, because every export of a Worker's main module is read
|
|
18
|
+
* as an entrypoint, and a function is not one.
|
|
19
|
+
*/
|
|
20
|
+
/** What this host may be handed, keyed by the capability that supplies it. */
|
|
21
|
+
export interface PaymentsHostPeers {
|
|
22
|
+
/** `ledger()`'s peer surface, when the catalog credits a balance. */
|
|
23
|
+
readonly ledger?: PaymentsLedgerPeer;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The peers this host was handed — empty when its entry handed none.
|
|
27
|
+
*
|
|
28
|
+
* A value rather than a getter, and read as a property inside a Workflow's `run`: it is set once, by the entry,
|
|
29
|
+
* before the isolate serves anything, so every replay of a run reads the same thing — which is what
|
|
30
|
+
* `workflowDeterminism.test.ts` holds every driver body to.
|
|
31
|
+
*/
|
|
32
|
+
export declare const hostPeers: {
|
|
33
|
+
-readonly [Key in keyof PaymentsHostPeers]: PaymentsHostPeers[Key];
|
|
34
|
+
};
|
|
35
|
+
/** Hand this host its peers. Called once, by the generated entry, before any request or cron fire. */
|
|
36
|
+
export declare function providePeers(peers: PaymentsHostPeers): void;
|
|
37
|
+
//# sourceMappingURL=hostPeers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"hostPeers.d.ts","sourceRoot":"","sources":["../../src/workflows/hostPeers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE;IAAE,CAAC,UAAU,GAAG,IAAI,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,GAAG,CAAC;CAAO,CAAC;AAEpG,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAE3D"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
//#region src/workflows/hostPeers.ts
|
|
4
|
+
/**
|
|
5
|
+
* The peers this host was handed — empty when its entry handed none.
|
|
6
|
+
*
|
|
7
|
+
* A value rather than a getter, and read as a property inside a Workflow's `run`: it is set once, by the entry,
|
|
8
|
+
* before the isolate serves anything, so every replay of a run reads the same thing — which is what
|
|
9
|
+
* `workflowDeterminism.test.ts` holds every driver body to.
|
|
10
|
+
*/
|
|
11
|
+
const hostPeers = {};
|
|
12
|
+
/** Hand this host its peers. Called once, by the generated entry, before any request or cron fire. */
|
|
13
|
+
function providePeers(peers) {
|
|
14
|
+
Object.assign(hostPeers, peers);
|
|
15
|
+
}
|
|
16
|
+
//#endregion
|
|
17
|
+
export { hostPeers, providePeers };
|
|
@@ -4,6 +4,7 @@ import type { D1Database } from "@cloudflare/workers-types";
|
|
|
4
4
|
import type { PaymentsConfig } from "../config/config";
|
|
5
5
|
import type { PurchaseEnvironment } from "../data/purchase";
|
|
6
6
|
import { fulfillPurchase } from "../grants/apply";
|
|
7
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
7
8
|
import { type PaddleEnvironment, type PaddleHttpFetch } from "../rails/paddle/api";
|
|
8
9
|
import { PADDLE_EVENT_RETENTION_DAYS } from "../rails/paddle/events";
|
|
9
10
|
import type { PaymentsPaddleCredentials } from "../secret/registry";
|
|
@@ -106,6 +107,8 @@ export interface PaddleSweepDeps {
|
|
|
106
107
|
transport?: PaddleHttpFetch;
|
|
107
108
|
/** Fulfillment for a swept purchase. Defaults to {@link fulfillPurchase}, and is safe to repeat. */
|
|
108
109
|
fulfill?: (d1: D1Database, projection: Parameters<typeof fulfillPurchase>[1]) => Promise<unknown>;
|
|
110
|
+
/** The ledger the default {@link fulfill} credits through, when the host was handed one. See `grants/ledgerSeam.ts`. */
|
|
111
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
109
112
|
/** How many pages one sweep may walk. A bound on the work, so a first pass finishes. */
|
|
110
113
|
maxPages?: number;
|
|
111
114
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"paddleSweep.d.ts","sourceRoot":"","sources":["../../src/workflows/paddleSweep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAU5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"paddleSweep.d.ts","sourceRoot":"","sources":["../../src/workflows/paddleSweep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAU5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,2BAA2B,EAAqB,MAAM,wBAAwB,CAAC;AAIxF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,uGAAuG;IACvG,WAAW,EAAE,mBAAmB,CAAC;IACjC,8EAA8E;IAC9E,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,oGAAoG;IACpG,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,wHAAwH;IACxH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAmT3C;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmNnF;AAED,2GAA2G;AAC3G,OAAO,EAAE,2BAA2B,EAAE,CAAC"}
|
|
@@ -255,6 +255,7 @@ async function repairOrphans(deps, at) {
|
|
|
255
255
|
fulfill: async (projection) => {
|
|
256
256
|
await (deps.fulfill ?? ((d1, value) => fulfillPurchase(d1, value, {
|
|
257
257
|
config: deps.config,
|
|
258
|
+
ledgerPeer: deps.ledgerPeer,
|
|
258
259
|
now: () => at.getTime()
|
|
259
260
|
})))(deps.d1, projection);
|
|
260
261
|
}
|
|
@@ -408,6 +409,7 @@ async function sweepPaddle(deps) {
|
|
|
408
409
|
});
|
|
409
410
|
await (deps.fulfill ?? ((d1, value) => fulfillPurchase(d1, value, {
|
|
410
411
|
config: deps.config,
|
|
412
|
+
ledgerPeer: deps.ledgerPeer,
|
|
411
413
|
now: () => at.getTime()
|
|
412
414
|
})))(deps.d1, projection);
|
|
413
415
|
await complete(deps.d1, id, at);
|
|
@@ -4,6 +4,7 @@ import type { D1Database } from "@cloudflare/workers-types";
|
|
|
4
4
|
import { type AuditEmit } from "@pithy-sh/core/src/audit/recorder";
|
|
5
5
|
import type { PaymentsConfig } from "../config/config";
|
|
6
6
|
import { type PurchaseEnvironment } from "../data/purchase";
|
|
7
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
7
8
|
import type { PurchaseProjection } from "../projection/writer";
|
|
8
9
|
import type { PaddleSweepReport } from "./paddleSweep";
|
|
9
10
|
import type { ReconcileRailAccess } from "./railAccess";
|
|
@@ -104,6 +105,11 @@ export interface ReconcileDeps {
|
|
|
104
105
|
* the webhook already applied is a no-op rather than a double.
|
|
105
106
|
*/
|
|
106
107
|
fulfill?: (projection: PurchaseProjection) => Promise<unknown>;
|
|
108
|
+
/**
|
|
109
|
+
* The ledger the default {@link fulfill} credits through — handed to the host by the entry `pithy` generates
|
|
110
|
+
* when the catalog credits a balance, and undefined otherwise. Never imported here: see `grants/ledgerSeam.ts`.
|
|
111
|
+
*/
|
|
112
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
107
113
|
/**
|
|
108
114
|
* The Paddle events sweep, or undefined to skip it.
|
|
109
115
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/workflows/reconcile.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,mCAAmC,CAAC;AAI7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAgE,KAAK,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,8GAA8G;AAC9G,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAcD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,iGAAiG;IACjG,MAAM,EAAE,cAAc,CAAC;IACvB,2GAA2G;IAC3G,WAAW,EAAE,mBAAmB,CAAC;IACjC,4FAA4F;IAC5F,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,mBAAmB,CAAC;IAC3C,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChD;AAyBD,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,6GAA6G;IAC7G,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;
|
|
1
|
+
{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/workflows/reconcile.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,mCAAmC,CAAC;AAI7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAgE,KAAK,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,8GAA8G;AAC9G,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAcD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,iGAAiG;IACjG,MAAM,EAAE,cAAc,CAAC;IACvB,2GAA2G;IAC3G,WAAW,EAAE,mBAAmB,CAAC;IACjC,4FAA4F;IAC5F,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,mBAAmB,CAAC;IAC3C,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChD;AAyBD,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,6GAA6G;IAC7G,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AA+PD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,uBAA4B,GACnC,OAAO,CAAC,eAAe,CAAC,CAyL1B"}
|
|
@@ -148,6 +148,7 @@ async function reconcileOne(deps, runId, access, purchase, now, dryRun) {
|
|
|
148
148
|
const fulfill = deps.fulfill ?? ((repaired) => fulfillPurchase(deps.d1, repaired, {
|
|
149
149
|
config: deps.config,
|
|
150
150
|
emit: deps.emit,
|
|
151
|
+
ledgerPeer: deps.ledgerPeer,
|
|
151
152
|
now: () => now.getTime()
|
|
152
153
|
}));
|
|
153
154
|
try {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAW/F,OAAO,EAAE,KAAK,eAAe,EAAqB,MAAM,aAAa,CAAC;AAGtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,KAAK,iBAAiB,EAAyB,MAAM,gBAAgB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB,CAAC,iBAAiB,EAAE,uBAAuB,CAAC;IAC5F,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAuE9G;CACF;;IAGC;;;;;;OAMG;IACG,SAAS,cAAc,OAAO,OAAO,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC"}
|
package/dist/workflows/worker.js
CHANGED
|
@@ -5,6 +5,7 @@ import { PaymentsReconcileParams } from "./specs.js";
|
|
|
5
5
|
import { triggerPaymentsReconcile } from "../http/dispatch.js";
|
|
6
6
|
import { batchedRailAccess } from "./railAccess.js";
|
|
7
7
|
import { reconcilePayments } from "./reconcile.js";
|
|
8
|
+
import { hostPeers } from "./hostPeers.js";
|
|
8
9
|
import { sweepPaddle } from "./paddleSweep.js";
|
|
9
10
|
import { auditLogEmit, logReconcileReport } from "./report.js";
|
|
10
11
|
import { paymentsWorkflowRetry } from "./retryPolicy.js";
|
|
@@ -54,6 +55,7 @@ var PaymentsReconcileWorkflow = class extends WorkflowEntrypoint {
|
|
|
54
55
|
}),
|
|
55
56
|
now: () => /* @__PURE__ */ new Date(),
|
|
56
57
|
emit: auditLogEmit(log),
|
|
58
|
+
ledgerPeer: hostPeers.ledger,
|
|
57
59
|
/**
|
|
58
60
|
* The Paddle events sweep, supplied only when that rail is on.
|
|
59
61
|
*
|
|
@@ -72,6 +74,7 @@ var PaymentsReconcileWorkflow = class extends WorkflowEntrypoint {
|
|
|
72
74
|
credentials: railCredentials(credentials, "paddle"),
|
|
73
75
|
paddleEnvironment: config.paddle?.environment ?? "sandbox",
|
|
74
76
|
deployment: this.env.ENVIRONMENT,
|
|
77
|
+
ledgerPeer: hostPeers.ledger,
|
|
75
78
|
now: () => /* @__PURE__ */ new Date()
|
|
76
79
|
}) } : {}
|
|
77
80
|
}, classifiedSteps(step, paymentsWorkflowRetry, NonRetryableError), params);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/payments",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.8",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -43,8 +43,8 @@
|
|
|
43
43
|
},
|
|
44
44
|
"peerDependencies": {
|
|
45
45
|
"@pithy-sh/core": "^0.7.4",
|
|
46
|
-
"@pithy-sh/ledger": "^0.2.
|
|
47
|
-
"@pithy-sh/secrets": "^0.
|
|
46
|
+
"@pithy-sh/ledger": "^0.2.6",
|
|
47
|
+
"@pithy-sh/secrets": "^0.3.0",
|
|
48
48
|
"hono": "^4.13.2",
|
|
49
49
|
"kysely": "^0.29.0",
|
|
50
50
|
"react": "^19.0.0",
|
package/src/capability.ts
CHANGED
|
@@ -18,10 +18,12 @@ import { paymentsTables } from "./data/tables";
|
|
|
18
18
|
import { installEntitlementResolver } from "./entitlement/resolver";
|
|
19
19
|
import type { PaymentsSubjectResolver, PaymentsSubjectSeam } from "./entitlement/subjectSeam";
|
|
20
20
|
import { requireImplementedSubject } from "./entitlement/unimplementedSubject";
|
|
21
|
+
import type { PaymentsLedgerPeer } from "./grants/ledgerSeam";
|
|
21
22
|
import { paymentsManifestConfig } from "./http/manifestConfig";
|
|
22
23
|
import { registerPaymentsRoutes } from "./http/routes";
|
|
23
24
|
import { paymentsAdminRoutes } from "./http/scopes";
|
|
24
25
|
import { payments_0001_purchases } from "./migrations/0001_purchases";
|
|
26
|
+
import { type PaymentsPeer, paymentsPeer } from "./peer";
|
|
25
27
|
import { paymentsInapplicableSecrets, paymentsSecretBranches } from "./secret/branches";
|
|
26
28
|
import { paymentsSecretsRegistry } from "./secret/registry";
|
|
27
29
|
import { paymentsExampleSeed } from "./seeds/example";
|
|
@@ -67,23 +69,41 @@ export type PaymentsOptions = PaymentsConfigInput & {
|
|
|
67
69
|
};
|
|
68
70
|
|
|
69
71
|
/**
|
|
70
|
-
* The slice of `@pithy-sh/ledger`'s capability
|
|
72
|
+
* The slice of `@pithy-sh/ledger`'s capability payments reads — its declared currency codes, and the peer
|
|
73
|
+
* surface a credit goes through.
|
|
71
74
|
*
|
|
72
75
|
* Structural, and recognized by a copied three-line predicate rather than by importing the ledger's own
|
|
73
|
-
* `isLedgerCapability`.
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
76
|
+
* `isLedgerCapability`. The ledger is an **optional** peer, and a specifier naming it — static, or a dynamic
|
|
77
|
+
* `import()` behind a `try` — is one a bundler resolves whether or not the branch holding it ever runs, so a
|
|
78
|
+
* project that never installed it could not bundle payments at all (#645). So payments names the package
|
|
79
|
+
* nowhere, not even for a type, and the ledger reaches it through the composition: this hook finds it, and
|
|
80
|
+
* {@link payments} keeps its `ledgerPeer` for the routes.
|
|
81
|
+
*
|
|
82
|
+
* `ledgerPeer` is optional here because a ledger released before #645 does not carry one, and that is a
|
|
83
|
+
* composition {@link checkLedgerGrants} refuses by name rather than a purchase that fails later.
|
|
77
84
|
*/
|
|
78
|
-
interface
|
|
85
|
+
interface LedgerPeerCapability extends Capability {
|
|
79
86
|
ledgerConfig: { currencies: readonly { code: string }[] };
|
|
87
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
80
88
|
}
|
|
81
89
|
|
|
82
90
|
/** Whether a composed capability is the ledger, carrying its parsed currency set. */
|
|
83
|
-
function isLedgerPeer(capability: Capability): capability is
|
|
91
|
+
function isLedgerPeer(capability: Capability): capability is LedgerPeerCapability {
|
|
84
92
|
return capability.name === "ledger" && "ledgerConfig" in capability;
|
|
85
93
|
}
|
|
86
94
|
|
|
95
|
+
/** The ledger's peer surface among the composed capabilities, or undefined when no ledger is composed. */
|
|
96
|
+
function composedLedger(capabilities: readonly Capability[]): PaymentsLedgerPeer | undefined {
|
|
97
|
+
return capabilities.find(isLedgerPeer)?.ledgerPeer;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Products named for a sentence: `product "coins_100"`, or `products "a" and "b"`. */
|
|
101
|
+
function products(list: readonly { id: string }[]): string {
|
|
102
|
+
const ids = list.map((entry) => `"${entry.id}"`);
|
|
103
|
+
if (ids.length === 1) return `product ${ids[0]}`;
|
|
104
|
+
return `products ${ids.slice(0, -1).join(", ")} and ${ids[ids.length - 1]}`;
|
|
105
|
+
}
|
|
106
|
+
|
|
87
107
|
/**
|
|
88
108
|
* Validate every `grants.currency` against the composed ledger, at assembly.
|
|
89
109
|
*
|
|
@@ -122,11 +142,20 @@ function checkLedgerGrants({ capabilities }: CapabilityComposeContext, config: P
|
|
|
122
142
|
const peer = capabilities.find(isLedgerPeer);
|
|
123
143
|
if (!peer) {
|
|
124
144
|
throw new ValidationError({
|
|
125
|
-
message:
|
|
126
|
-
action:
|
|
145
|
+
message: `No ledger is composed in this Worker, and ${products(granting)} ${granting.length === 1 ? "credits" : "credit"} a balance through one.`,
|
|
146
|
+
action: `Compose \`ledger(...)\` in this Worker, or turn crediting off by removing the \`grants.ledger\` clause from ${products(granting)}.`,
|
|
127
147
|
detail: `Products with a \`grants.ledger\` clause: ${granting.map((entry) => entry.id).join(", ")}. Crediting needs @pithy-sh/ledger composed in the same Worker.`,
|
|
128
148
|
});
|
|
129
149
|
}
|
|
150
|
+
// A ledger from before #645 is composed and cannot be called: it carries no peer surface, and payments no
|
|
151
|
+
// longer imports the package to reach around it. Refused here, by name, rather than as the first purchase.
|
|
152
|
+
if (typeof peer.ledgerPeer?.openLedger !== "function") {
|
|
153
|
+
throw new ValidationError({
|
|
154
|
+
message: "The composed ledger is too old for payments to credit a balance.",
|
|
155
|
+
action: "Upgrade @pithy-sh/ledger to the version this @pithy-sh/payments peers.",
|
|
156
|
+
detail: `The composed ledger capability carries no \`ledgerPeer\`. Products with a \`grants.ledger\` clause: ${granting.map((entry) => entry.id).join(", ")}.`,
|
|
157
|
+
});
|
|
158
|
+
}
|
|
130
159
|
|
|
131
160
|
const declared = new Set(peer.ledgerConfig.currencies.map((currency) => currency.code));
|
|
132
161
|
const unknown = granting.filter((entry) => !declared.has(entry.currency));
|
|
@@ -267,6 +296,12 @@ export interface PaymentsCapability
|
|
|
267
296
|
extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "payments", typeof paymentsWorkflows> {
|
|
268
297
|
/** The resolved catalog. */
|
|
269
298
|
paymentsConfig: PaymentsConfig;
|
|
299
|
+
/**
|
|
300
|
+
* What a capability composed beside this one reads purchases through — `support`, showing an operator what a
|
|
301
|
+
* sender bought. Found in its `compose` hook, so it never imports this package and a project without
|
|
302
|
+
* payments bundles it (#645). See `peer.ts`.
|
|
303
|
+
*/
|
|
304
|
+
paymentsPeer: PaymentsPeer;
|
|
270
305
|
}
|
|
271
306
|
|
|
272
307
|
/**
|
|
@@ -285,9 +320,10 @@ export interface PaymentsCapability
|
|
|
285
320
|
* registry, so a project composing payments without `@pithy-sh/secrets` must fail at assembly rather
|
|
286
321
|
* than at the first receipt. Auth is *not* listed — it is a seam: under `billingSubject: "user"` a purchase
|
|
287
322
|
* scopes to the authenticated caller, so with no auth capability composed every route denies, which is the
|
|
288
|
-
* right failure and needs no dependency edge. `@pithy-sh/ledger` is likewise a seam
|
|
289
|
-
*
|
|
290
|
-
* manifest's
|
|
323
|
+
* right failure and needs no dependency edge. `@pithy-sh/ledger` is likewise a seam: `compose` finds it among
|
|
324
|
+
* the composed capabilities and hands its `ledgerPeer` to the routes, and nothing in this package imports it
|
|
325
|
+
* (#645). Only a product whose catalog entry declares `grants` ever calls it. Both belong in the manifest's
|
|
326
|
+
* `optionalCapabilities`.
|
|
291
327
|
*
|
|
292
328
|
* Under `billingSubject: "organization"` the holder is not the caller and cannot be derived from them, so
|
|
293
329
|
* the adopter supplies `resolveSubject` and a composition without one is refused outright — see
|
|
@@ -321,6 +357,10 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
|
|
|
321
357
|
...(resolveSubject ? { resolveSubject } : {}),
|
|
322
358
|
};
|
|
323
359
|
|
|
360
|
+
// The optional peers, filled once by `compose` — which runs after this factory, so the routes are handed
|
|
361
|
+
// the slot and read it per request rather than being handed a value that does not exist yet.
|
|
362
|
+
const peers: { ledger: PaymentsLedgerPeer | undefined } = { ledger: undefined };
|
|
363
|
+
|
|
324
364
|
const migrations: Record<string, Migration> = {
|
|
325
365
|
"0001_purchases": payments_0001_purchases,
|
|
326
366
|
};
|
|
@@ -357,8 +397,12 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
|
|
|
357
397
|
// binding and types `c.var.workflows.trigger("payments/reconcile", …)` precisely.
|
|
358
398
|
workflows: paymentsWorkflows,
|
|
359
399
|
// The one thing this capability cannot check on its own: whether the ledger it credits agrees the
|
|
360
|
-
// currency exists. See `checkLedgerGrants` for why the failure is otherwise invisible.
|
|
361
|
-
|
|
400
|
+
// currency exists. See `checkLedgerGrants` for why the failure is otherwise invisible. And the one place
|
|
401
|
+
// the ledger reaches payments at all: found among the composed capabilities, never imported (#645).
|
|
402
|
+
compose: (context) => {
|
|
403
|
+
checkLedgerGrants(context, resolved);
|
|
404
|
+
peers.ledger = composedLedger(context.capabilities);
|
|
405
|
+
},
|
|
362
406
|
// The other half of {@link requireResolvableSubject}, and it is at the entrypoint rather than at
|
|
363
407
|
// composition on purpose: `pithy add` scaffolds an unimplemented `resolveSubject`, and every `pithy`
|
|
364
408
|
// command evaluates this config to learn what the Worker composes. Refusing here refuses the Worker
|
|
@@ -390,11 +434,11 @@ export function payments(options: PaymentsOptions): PaymentsCapability {
|
|
|
390
434
|
manifestConfig: paymentsManifestConfig(resolved.billingSubject),
|
|
391
435
|
// The routes ask the same question the gate does — a checkout, a restore and a portal all need a holder
|
|
392
436
|
// to key a row to — so they are handed the same seam rather than building one from the config alone.
|
|
393
|
-
routes: registerPaymentsRoutes({ config: resolved, subject }),
|
|
437
|
+
routes: registerPaymentsRoutes({ config: resolved, subject, ledger: () => peers.ledger }),
|
|
394
438
|
seeds: [paymentsExampleSeed],
|
|
395
439
|
});
|
|
396
440
|
|
|
397
|
-
return Object.assign(capability, { paymentsConfig: resolved });
|
|
441
|
+
return Object.assign(capability, { paymentsConfig: resolved, paymentsPeer });
|
|
398
442
|
}
|
|
399
443
|
|
|
400
444
|
/** Whether a capability is the payments capability — carries its resolved catalog. */
|
package/src/grants/apply.ts
CHANGED
|
@@ -9,13 +9,13 @@ import type { PaymentsPurchase } from "../data/purchase";
|
|
|
9
9
|
import type { PurchaseStatus } from "../data/status";
|
|
10
10
|
import type { PurchaseProjection } from "../projection/writer";
|
|
11
11
|
import { type ClawbackOutcome, clawbackGrants } from "./clawback";
|
|
12
|
-
import { ledgerAccountId, openPaymentsLedger, type PaymentsLedger } from "./ledgerSeam";
|
|
12
|
+
import { ledgerAccountId, openPaymentsLedger, type PaymentsLedger, type PaymentsLedgerPeer } from "./ledgerSeam";
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
15
|
* Fulfillment: turning a projected purchase into the balance a `grants` clause promised.
|
|
16
16
|
*
|
|
17
|
-
* This is deliberately **not** in the projection writer. The writer stays pure D1 so its tests
|
|
18
|
-
*
|
|
17
|
+
* This is deliberately **not** in the projection writer. The writer stays pure D1 so its tests need no ledger,
|
|
18
|
+
* and the credit is a separate step its caller runs on what it returned — a route, or any
|
|
19
19
|
* other caller holding a projection. Nothing is lost by the separation, because the credit's idempotency has
|
|
20
20
|
* never rested on call ordering: it rests on the ledger's `UNIQUE (ref)`.
|
|
21
21
|
*
|
|
@@ -93,8 +93,14 @@ export interface GrantOptions {
|
|
|
93
93
|
export interface FulfillPurchaseOptions extends GrantOptions {
|
|
94
94
|
/** The audit seam. Defaults to core's no-op, so a caller with no recorder composed needs no branch. */
|
|
95
95
|
emit?: AuditEmit;
|
|
96
|
-
/** An already-open ledger. Absent in production
|
|
96
|
+
/** An already-open ledger. Absent in production, where {@link ledgerPeer} opens one only when it is needed. */
|
|
97
97
|
ledger?: PaymentsLedger;
|
|
98
|
+
/**
|
|
99
|
+
* The ledger the composition handed over — `ledger()`'s `ledgerPeer`, found by `payments()`'s `compose` hook,
|
|
100
|
+
* or handed to the reconcile host by its generated entry. Undefined when no ledger is composed, which is
|
|
101
|
+
* only a fault for a product that credits one.
|
|
102
|
+
*/
|
|
103
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
98
104
|
/** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
|
|
99
105
|
now?: () => number;
|
|
100
106
|
}
|
|
@@ -156,9 +162,9 @@ export async function applyGrants(
|
|
|
156
162
|
* Fulfill one projected purchase in both directions: credit what it bought, and reverse what a refund took
|
|
157
163
|
* back where the catalog asks for it.
|
|
158
164
|
*
|
|
159
|
-
* The ledger is opened **
|
|
160
|
-
*
|
|
161
|
-
*
|
|
165
|
+
* The ledger is opened **only when the catalog names a currency**, and only from what the composition handed
|
|
166
|
+
* over. A project selling nothing but features never composes one, never installs `@pithy-sh/ledger`, and —
|
|
167
|
+
* because nothing here names the package — never carries a specifier a bundler would have to resolve (#645).
|
|
162
168
|
*
|
|
163
169
|
* A refused clawback is recorded here rather than thrown. It is the one fulfillment fact no other table
|
|
164
170
|
* holds — a successful credit or debit is already a ledger row, keyed by a ref that names the purchase — so
|
|
@@ -172,7 +178,7 @@ export async function fulfillPurchase(
|
|
|
172
178
|
const { purchase } = projection;
|
|
173
179
|
if (ledgerGrantFor(options.config, purchase.productId) === undefined) return { granted: [], clawedBack: [] };
|
|
174
180
|
|
|
175
|
-
const ledger = options.ledger ??
|
|
181
|
+
const ledger = options.ledger ?? openPaymentsLedger(d1, { peer: options.ledgerPeer, now: options.now });
|
|
176
182
|
const granted = await applyGrants(ledger, projection, options);
|
|
177
183
|
const clawedBack = await clawbackGrants(ledger, projection, options);
|
|
178
184
|
|
package/src/grants/ledgerSeam.ts
CHANGED
|
@@ -6,19 +6,30 @@ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
|
6
6
|
import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
|
|
7
7
|
|
|
8
8
|
/**
|
|
9
|
-
* The single point of contact between `@pithy-sh/payments` and `@pithy-sh/ledger
|
|
9
|
+
* The single point of contact between `@pithy-sh/payments` and `@pithy-sh/ledger` — and it imports nothing
|
|
10
|
+
* from it.
|
|
10
11
|
*
|
|
11
12
|
* The ledger is an **optional peer**: most catalogs sell features, not currency, and a project that never
|
|
12
|
-
* declares a `grants` clause must neither install the package nor
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
13
|
+
* declares a `grants` clause must neither install the package nor carry it in a Worker bundle. This file used
|
|
14
|
+
* to reach it with `import("@pithy-sh/ledger/src/ledger")` behind a `try`, which is optional at runtime and
|
|
15
|
+
* required at bundle time — wrangler's esbuild resolves a literal specifier whether or not the branch holding
|
|
16
|
+
* it ever runs, so every project composing payments without the ledger could not deploy its payments host at
|
|
17
|
+
* all (#645). The unit test here injected a loader, so it proved the runtime half and never met the bundler.
|
|
18
|
+
*
|
|
19
|
+
* **So the ledger is handed to payments, never fetched by it.** `ledger()` carries its peer surface as
|
|
20
|
+
* `ledgerPeer`; `payments()`'s `compose` hook finds it among the composed capabilities and keeps it for the
|
|
21
|
+
* routes, and the reconcile host — which composes nothing — is handed it by the entry `pithy` generates when
|
|
22
|
+
* the catalog credits a balance. Everything downstream depends on {@link PaymentsLedgerPeer} and
|
|
23
|
+
* {@link PaymentsLedger}, structural views, so no module in this package names `@pithy-sh/ledger` at all —
|
|
24
|
+
* not even for a type, which would put an optional package on the typecheck path of every module that touches
|
|
25
|
+
* fulfillment. `optionalPeerImports.test.ts` holds the whole kit to that.
|
|
16
26
|
*
|
|
17
27
|
* **An absent ledger is an error, never a skip.** A catalog with a `grants` clause has told us a purchase
|
|
18
28
|
* credits a balance; quietly not crediting it is a support ticket that arrives weeks later as "I paid and got
|
|
19
29
|
* no coins". The normal place this is caught is far earlier — `payments()`'s `compose` hook refuses at
|
|
20
30
|
* assembly when a `grants` product is composed without the ledger, so a deploy fails rather than a purchase.
|
|
21
|
-
*
|
|
31
|
+
* The throw in {@link openPaymentsLedger} is the backstop for a caller that reached fulfillment some other way,
|
|
32
|
+
* and it names the fix.
|
|
22
33
|
*/
|
|
23
34
|
|
|
24
35
|
/**
|
|
@@ -95,47 +106,46 @@ export function ledgerAccountId(subject: PaymentsSubject): string {
|
|
|
95
106
|
return subject.subjectId;
|
|
96
107
|
}
|
|
97
108
|
|
|
98
|
-
/** How
|
|
99
|
-
export type
|
|
100
|
-
openLedger: (d1: D1Database, now?: () => number) => PaymentsLedger;
|
|
101
|
-
}>;
|
|
109
|
+
/** How a ledger is opened over a D1: `@pithy-sh/ledger`'s own `openLedger`, as payments sees it. */
|
|
110
|
+
export type PaymentsLedgerOpener = (d1: D1Database, now?: () => number) => PaymentsLedger;
|
|
102
111
|
|
|
103
|
-
/**
|
|
104
|
-
|
|
112
|
+
/**
|
|
113
|
+
* The slice of `@pithy-sh/ledger`'s peer surface payments calls — its `ledgerPeer`, structurally.
|
|
114
|
+
*
|
|
115
|
+
* Structural for {@link PaymentsLedger}'s reason: a type imported from the optional package would put it on
|
|
116
|
+
* the typecheck path of every module that touches fulfillment. The ledger's own `ledgerPeer` satisfies it, and
|
|
117
|
+
* `capability.test.ts` composes the real one to prove that stays true.
|
|
118
|
+
*/
|
|
119
|
+
export interface PaymentsLedgerPeer {
|
|
120
|
+
/** Open the ledger against a D1 binding, stamping rows with `now`. */
|
|
121
|
+
openLedger: PaymentsLedgerOpener;
|
|
122
|
+
}
|
|
105
123
|
|
|
106
124
|
/** What {@link openPaymentsLedger} accepts beyond the binding. */
|
|
107
125
|
export interface OpenPaymentsLedgerOptions {
|
|
108
|
-
/**
|
|
109
|
-
|
|
126
|
+
/** The ledger the composition handed over, or undefined when none is composed. */
|
|
127
|
+
peer?: PaymentsLedgerPeer;
|
|
110
128
|
/** The clock the ledger stamps its rows with. Injected so a fulfillment is deterministic under test. */
|
|
111
129
|
now?: () => number;
|
|
112
130
|
}
|
|
113
131
|
|
|
114
132
|
/**
|
|
115
|
-
* Open the ledger against the app database, or explain what is missing.
|
|
133
|
+
* Open the ledger the composition handed over against the app database, or explain what is missing.
|
|
116
134
|
*
|
|
117
135
|
* The ledger's tables live in the same D1 as payments' own — both capabilities bind `DB` — so there is no
|
|
118
136
|
* second database to reach and no configuration to resolve. That is also why the two write independently and
|
|
119
137
|
* a credit is idempotent on its `ref` rather than on being in the purchase's transaction: D1 has no
|
|
120
138
|
* cross-statement transaction a caller can hold open across two packages.
|
|
121
139
|
*/
|
|
122
|
-
export
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
throw new InternalError(
|
|
132
|
-
{
|
|
133
|
-
message: "This purchase credits a balance, and the ledger is not installed.",
|
|
134
|
-
action: "Install @pithy-sh/ledger and compose ledger(...), or drop the `grants` clause from the product.",
|
|
135
|
-
detail: `Loading @pithy-sh/ledger failed: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
136
|
-
},
|
|
137
|
-
{ cause },
|
|
138
|
-
);
|
|
140
|
+
export function openPaymentsLedger(d1: D1Database, options: OpenPaymentsLedgerOptions = {}): PaymentsLedger {
|
|
141
|
+
if (options.peer === undefined) {
|
|
142
|
+
throw new InternalError({
|
|
143
|
+
message: "This purchase credits a balance, and no ledger is composed.",
|
|
144
|
+
action:
|
|
145
|
+
"Add `ledger(...)` to this Worker's capabilities in pithy.config.ts, or drop the `grants` clause from the product.",
|
|
146
|
+
detail:
|
|
147
|
+
"fulfillPurchase reached a product with a grants.ledger clause and was handed no ledger peer. payments() refuses that composition at assembly, so this caller reached fulfillment some other way, or a host was deployed without the entry that hands it the ledger.",
|
|
148
|
+
});
|
|
139
149
|
}
|
|
140
|
-
return
|
|
150
|
+
return options.peer.openLedger(d1, options.now);
|
|
141
151
|
}
|
package/src/http/routes.ts
CHANGED
|
@@ -55,6 +55,7 @@ import {
|
|
|
55
55
|
PaymentsSubscriptionChangeRefusedError,
|
|
56
56
|
} from "../error/errors";
|
|
57
57
|
import { fulfillPurchase } from "../grants/apply";
|
|
58
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
58
59
|
import { repairOrphanedEvents } from "../projection/orphans";
|
|
59
60
|
import { linkProviderAccount, providerAccountForSubject, resolveNotificationOwner } from "../projection/owner";
|
|
60
61
|
import { resolveEntitlements } from "../projection/resolve";
|
|
@@ -333,6 +334,13 @@ export interface PaymentsRoutesOptions {
|
|
|
333
334
|
* compose organization billing without a resolver rather than reaching this state.
|
|
334
335
|
*/
|
|
335
336
|
subject?: PaymentsSubjectSeam;
|
|
337
|
+
/**
|
|
338
|
+
* The ledger a `grants` product credits through, read per request — `payments()` hands the slot its
|
|
339
|
+
* `compose` hook fills, because `compose` runs after this factory. Undefined when no ledger is composed,
|
|
340
|
+
* which `payments()` refuses at assembly for any catalog that credits one. Never imported: see
|
|
341
|
+
* `grants/ledgerSeam.ts`.
|
|
342
|
+
*/
|
|
343
|
+
ledger?: () => PaymentsLedgerPeer | undefined;
|
|
336
344
|
}
|
|
337
345
|
|
|
338
346
|
/** The app `DB` binding, or a wiring failure. Payments cannot resolve anything without it. */
|
|
@@ -1254,14 +1262,6 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
|
|
|
1254
1262
|
return projection;
|
|
1255
1263
|
}
|
|
1256
1264
|
|
|
1257
|
-
/**
|
|
1258
|
-
* Credit what the purchase bought, and reverse it where a refund and the catalog both ask.
|
|
1259
|
-
*
|
|
1260
|
-
* A no-op for every product with no `grants` clause, and it resolves the optional `@pithy-sh/ledger` import
|
|
1261
|
-
* only when one is present — so a project selling nothing but features never reaches the package. A failure
|
|
1262
|
-
* here is deliberately left to propagate: the credit's ref is stable, so a retry settles it, and swallowing
|
|
1263
|
-
* it would lose a purchase's currency with nothing anywhere to read.
|
|
1264
|
-
*/
|
|
1265
1265
|
/**
|
|
1266
1266
|
* Project the orphans a link just made resolvable. Never throws: see {@link repairOrphanedEvents}.
|
|
1267
1267
|
*
|
|
@@ -1291,10 +1291,19 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
|
|
|
1291
1291
|
}
|
|
1292
1292
|
}
|
|
1293
1293
|
|
|
1294
|
+
/**
|
|
1295
|
+
* Credit what the purchase bought, and reverse it where a refund and the catalog both ask.
|
|
1296
|
+
*
|
|
1297
|
+
* A no-op for every product with no `grants` clause, and it calls the ledger the composition handed over
|
|
1298
|
+
* only when one is present — so a project selling nothing but features never needs one. A failure here is
|
|
1299
|
+
* deliberately left to propagate: the credit's ref is stable, so a retry settles it, and swallowing it would
|
|
1300
|
+
* lose a purchase's currency with nothing anywhere to read.
|
|
1301
|
+
*/
|
|
1294
1302
|
async function fulfill(c: Context<PithyHonoEnv>, projection: PurchaseProjection): Promise<void> {
|
|
1295
1303
|
await fulfillPurchase(database(c), projection, {
|
|
1296
1304
|
config,
|
|
1297
1305
|
emit: c.var.emit,
|
|
1306
|
+
ledgerPeer: options.ledger?.(),
|
|
1298
1307
|
now: () => clock().getTime(),
|
|
1299
1308
|
});
|
|
1300
1309
|
}
|
package/src/index.ts
CHANGED
|
@@ -129,7 +129,8 @@ export {
|
|
|
129
129
|
type OpenPaymentsLedgerOptions,
|
|
130
130
|
openPaymentsLedger,
|
|
131
131
|
type PaymentsLedger,
|
|
132
|
-
type
|
|
132
|
+
type PaymentsLedgerOpener,
|
|
133
|
+
type PaymentsLedgerPeer,
|
|
133
134
|
} from "./grants/ledgerSeam";
|
|
134
135
|
export { PAYMENTS_RECONCILE_KEY, triggerPaymentsReconcile } from "./http/dispatch";
|
|
135
136
|
export { requireAuth } from "./http/guards";
|
package/src/peer.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { PaymentsPurchase } from "./data/purchase";
|
|
5
|
+
import { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } from "./data/tables";
|
|
6
|
+
import { resolveEntitlements } from "./projection/resolve";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* **What a capability composed beside payments may read — handed to it, never imported by it** (#645).
|
|
10
|
+
*
|
|
11
|
+
* `@pithy-sh/payments` is an optional peer of `support`, which shows an operator what a sender bought and is
|
|
12
|
+
* entitled to. It used to reach these modules by `import()` behind a `try`, and a literal specifier is one a
|
|
13
|
+
* bundler resolves whether or not the branch holding it ever runs — so a project without payments could not
|
|
14
|
+
* bundle support at all.
|
|
15
|
+
*
|
|
16
|
+
* So `payments()` carries this object as `paymentsPeer`, and a dependent finds it among the composed
|
|
17
|
+
* capabilities in its `compose` hook. The dependent names this package only in a type, which a bundler never
|
|
18
|
+
* sees. Reads only: the purchases table and the schema that decodes it, and the resolver every entitlement
|
|
19
|
+
* gate in the kit already trusts.
|
|
20
|
+
*/
|
|
21
|
+
export const paymentsPeer = {
|
|
22
|
+
PAYMENTS_PURCHASES_TABLE,
|
|
23
|
+
paymentsDatabase,
|
|
24
|
+
PaymentsPurchase,
|
|
25
|
+
resolveEntitlements,
|
|
26
|
+
} as const;
|
|
27
|
+
|
|
28
|
+
/** Payments' peer surface, by type — what `paymentsPeer` holds. */
|
|
29
|
+
export type PaymentsPeer = typeof paymentsPeer;
|
package/src/version.generated.ts
CHANGED