@pithy-sh/payments 0.3.5 → 0.3.7
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/provision/resolvePaymentsConfig.d.ts +6 -0
- package/dist/provision/resolvePaymentsConfig.d.ts.map +1 -1
- package/dist/provision/resolvePaymentsConfig.js +5 -2
- 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 +4 -4
- 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/provision/resolvePaymentsConfig.ts +15 -2
- 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
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;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import type { FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
|
|
4
5
|
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
5
6
|
import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
|
|
6
7
|
import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
|
|
@@ -34,6 +35,11 @@ export interface PaymentsConfigParams {
|
|
|
34
35
|
project: string;
|
|
35
36
|
/** The target environment. */
|
|
36
37
|
env: ManagedEnvironment;
|
|
38
|
+
/**
|
|
39
|
+
* **The feature this host serves, when it serves one (#643).** Its Worker, its Workflows and every store
|
|
40
|
+
* entry it binds then take the feature's names, as every feature host's do; `env` is `feature`.
|
|
41
|
+
*/
|
|
42
|
+
feature?: FeatureIdentity;
|
|
37
43
|
/** The app database id for this environment — where the `pithy_payments_*` tables live. */
|
|
38
44
|
appDatabaseId: string;
|
|
39
45
|
/** This environment's secrets database id (`<project>-<env>-secrets`) — holds the rails' credentials. */
|
|
@@ -60,21 +66,28 @@ export function resolvePaymentsConfig(
|
|
|
60
66
|
template: WorkflowHostTemplate,
|
|
61
67
|
params: PaymentsConfigParams,
|
|
62
68
|
): WorkflowHostTemplate {
|
|
69
|
+
const feature = params.feature;
|
|
63
70
|
const { project, env, appDatabaseId, secretsDatabaseId, storeId, paymentsConfig } = params;
|
|
64
71
|
|
|
65
72
|
// Derived before the resolve rather than assigned after it: `resolveWorkflowHost` refuses to fill a
|
|
66
73
|
// template that declares `workflows` without them, because the only name it could invent unaided is an
|
|
67
74
|
// unscoped one a second project in the same account would overwrite.
|
|
68
|
-
const derived = hostWorkflowsFor(paymentsWorkflowRegistry, {
|
|
75
|
+
const derived = hostWorkflowsFor(paymentsWorkflowRegistry, {
|
|
76
|
+
project,
|
|
77
|
+
capability: PAYMENTS_CAPABILITY,
|
|
78
|
+
env,
|
|
79
|
+
...(feature ? { feature } : {}),
|
|
80
|
+
});
|
|
69
81
|
|
|
70
82
|
const resolved = resolveWorkflowHost(template, {
|
|
71
83
|
project,
|
|
72
84
|
capability: PAYMENTS_CAPABILITY,
|
|
73
85
|
env,
|
|
86
|
+
...(feature ? { feature } : {}),
|
|
74
87
|
databaseIds: { DB: appDatabaseId, SECRETS: secretsDatabaseId },
|
|
75
88
|
secretsStoreId: storeId,
|
|
76
89
|
// The master key entry is project- and env-scoped, matching what the secrets manager wrote.
|
|
77
|
-
masterKeySecretName: masterKeySecretName(project, env),
|
|
90
|
+
masterKeySecretName: masterKeySecretName(project, env, feature),
|
|
78
91
|
workflows: derived.workflows,
|
|
79
92
|
// The catalog travels whole: the pass has to map a refreshed store SKU back to a product before it can
|
|
80
93
|
// project it, and the rails' toggles decide which stores it may ask at all. Nothing sensitive is in it —
|
package/src/version.generated.ts
CHANGED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* **The reconcile host's composition: the optional peers it was handed** (#645).
|
|
8
|
+
*
|
|
9
|
+
* An app Worker composes capabilities and `payments()`'s `compose` hook finds the ledger among them. This host
|
|
10
|
+
* composes nothing — it is a prebuilt Worker the adopter never authors — so it has no hook and nothing to find
|
|
11
|
+
* a ledger in. It still owes a credit when a pass repairs a purchase whose product has a `grants.ledger`
|
|
12
|
+
* clause, and it may not import `@pithy-sh/ledger` to make one, for the reason `grants/ledgerSeam.ts` gives.
|
|
13
|
+
*
|
|
14
|
+
* So `pithy` hands it over. When the project's catalog credits a balance, the CLI deploys this host from an
|
|
15
|
+
* entry it generates beside the resolved config, which imports the ledger's `ledgerPeer` from the project's
|
|
16
|
+
* own install and calls {@link providePeers} before re-exporting `worker.ts` unchanged. A catalog that credits
|
|
17
|
+
* nothing gets no entry: `main` stays `worker.ts`, and the bundle never meets the specifier.
|
|
18
|
+
*
|
|
19
|
+
* Its own module rather than an export of `worker.ts`, because every export of a Worker's main module is read
|
|
20
|
+
* as an entrypoint, and a function is not one.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** What this host may be handed, keyed by the capability that supplies it. */
|
|
24
|
+
export interface PaymentsHostPeers {
|
|
25
|
+
/** `ledger()`'s peer surface, when the catalog credits a balance. */
|
|
26
|
+
readonly ledger?: PaymentsLedgerPeer;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The peers this host was handed — empty when its entry handed none.
|
|
31
|
+
*
|
|
32
|
+
* A value rather than a getter, and read as a property inside a Workflow's `run`: it is set once, by the entry,
|
|
33
|
+
* before the isolate serves anything, so every replay of a run reads the same thing — which is what
|
|
34
|
+
* `workflowDeterminism.test.ts` holds every driver body to.
|
|
35
|
+
*/
|
|
36
|
+
export const hostPeers: { -readonly [Key in keyof PaymentsHostPeers]: PaymentsHostPeers[Key] } = {};
|
|
37
|
+
|
|
38
|
+
/** Hand this host its peers. Called once, by the generated entry, before any request or cron fire. */
|
|
39
|
+
export function providePeers(peers: PaymentsHostPeers): void {
|
|
40
|
+
Object.assign(hostPeers, peers);
|
|
41
|
+
}
|
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
webhookEventState,
|
|
18
18
|
} from "../data/webhookEvent";
|
|
19
19
|
import { fulfillPurchase } from "../grants/apply";
|
|
20
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
20
21
|
import { repairOrphanedEvents } from "../projection/orphans";
|
|
21
22
|
import { linkProviderAccount, resolveNotificationOwner } from "../projection/owner";
|
|
22
23
|
import { projectPurchase } from "../projection/writer";
|
|
@@ -128,6 +129,8 @@ export interface PaddleSweepDeps {
|
|
|
128
129
|
transport?: PaddleHttpFetch;
|
|
129
130
|
/** Fulfillment for a swept purchase. Defaults to {@link fulfillPurchase}, and is safe to repeat. */
|
|
130
131
|
fulfill?: (d1: D1Database, projection: Parameters<typeof fulfillPurchase>[1]) => Promise<unknown>;
|
|
132
|
+
/** The ledger the default {@link fulfill} credits through, when the host was handed one. See `grants/ledgerSeam.ts`. */
|
|
133
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
131
134
|
/** How many pages one sweep may walk. A bound on the work, so a first pass finishes. */
|
|
132
135
|
maxPages?: number;
|
|
133
136
|
}
|
|
@@ -482,7 +485,9 @@ async function repairOrphans(deps: PaddleSweepDeps, at: Date): Promise<void> {
|
|
|
482
485
|
},
|
|
483
486
|
fulfill: async (projection) => {
|
|
484
487
|
const fulfill =
|
|
485
|
-
deps.fulfill ??
|
|
488
|
+
deps.fulfill ??
|
|
489
|
+
((d1, value) =>
|
|
490
|
+
fulfillPurchase(d1, value, { config: deps.config, ledgerPeer: deps.ledgerPeer, now: () => at.getTime() }));
|
|
486
491
|
await fulfill(deps.d1, projection);
|
|
487
492
|
},
|
|
488
493
|
});
|
|
@@ -679,7 +684,9 @@ export async function sweepPaddle(deps: PaddleSweepDeps): Promise<PaddleSweepRep
|
|
|
679
684
|
// credit its coins would leave the entitlement right and the balance wrong, and nothing else would
|
|
680
685
|
// ever fix it — the renewal this sweep discovered is the one the webhook lost.
|
|
681
686
|
const fulfill =
|
|
682
|
-
deps.fulfill ??
|
|
687
|
+
deps.fulfill ??
|
|
688
|
+
((d1, value) =>
|
|
689
|
+
fulfillPurchase(d1, value, { config: deps.config, ledgerPeer: deps.ledgerPeer, now: () => at.getTime() }));
|
|
683
690
|
await fulfill(deps.d1, projection);
|
|
684
691
|
await complete(deps.d1, id, at);
|
|
685
692
|
report.projected += 1;
|
|
@@ -12,6 +12,7 @@ import { recordReconcileRun } from "../data/reconcileRun";
|
|
|
12
12
|
import type { PurchaseStatus } from "../data/status";
|
|
13
13
|
import { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } from "../data/tables";
|
|
14
14
|
import { fulfillPurchase } from "../grants/apply";
|
|
15
|
+
import type { PaymentsLedgerPeer } from "../grants/ledgerSeam";
|
|
15
16
|
import type { PurchaseProjection } from "../projection/writer";
|
|
16
17
|
import { projectPurchase } from "../projection/writer";
|
|
17
18
|
import type { PaddleSweepReport } from "./paddleSweep";
|
|
@@ -128,6 +129,11 @@ export interface ReconcileDeps {
|
|
|
128
129
|
* the webhook already applied is a no-op rather than a double.
|
|
129
130
|
*/
|
|
130
131
|
fulfill?: (projection: PurchaseProjection) => Promise<unknown>;
|
|
132
|
+
/**
|
|
133
|
+
* The ledger the default {@link fulfill} credits through — handed to the host by the entry `pithy` generates
|
|
134
|
+
* when the catalog credits a balance, and undefined otherwise. Never imported here: see `grants/ledgerSeam.ts`.
|
|
135
|
+
*/
|
|
136
|
+
ledgerPeer?: PaymentsLedgerPeer;
|
|
131
137
|
/**
|
|
132
138
|
* The Paddle events sweep, or undefined to skip it.
|
|
133
139
|
*
|
|
@@ -392,7 +398,12 @@ async function reconcileOne(
|
|
|
392
398
|
const fulfill =
|
|
393
399
|
deps.fulfill ??
|
|
394
400
|
((repaired: PurchaseProjection) =>
|
|
395
|
-
fulfillPurchase(deps.d1, repaired, {
|
|
401
|
+
fulfillPurchase(deps.d1, repaired, {
|
|
402
|
+
config: deps.config,
|
|
403
|
+
emit: deps.emit,
|
|
404
|
+
ledgerPeer: deps.ledgerPeer,
|
|
405
|
+
now: () => now.getTime(),
|
|
406
|
+
}));
|
|
396
407
|
try {
|
|
397
408
|
await fulfill(projection);
|
|
398
409
|
} catch (cause) {
|
package/src/workflows/worker.ts
CHANGED
|
@@ -9,6 +9,7 @@ import { configureSharedSecrets, sharedSecretsStore } from "@pithy-sh/secrets/sr
|
|
|
9
9
|
import type { PurchaseEnvironment } from "../data/purchase";
|
|
10
10
|
import { triggerPaymentsReconcile } from "../http/dispatch";
|
|
11
11
|
import { PAYMENTS_PROVIDER_SECRET, paymentsSecretsRegistry, railCredentials } from "../secret/registry";
|
|
12
|
+
import { hostPeers } from "./hostPeers";
|
|
12
13
|
import { sweepPaddle } from "./paddleSweep";
|
|
13
14
|
import { batchedRailAccess } from "./railAccess";
|
|
14
15
|
import { type ReconcileReport, reconcilePayments } from "./reconcile";
|
|
@@ -111,6 +112,9 @@ export class PaymentsReconcileWorkflow extends WorkflowEntrypoint<PaymentsWorker
|
|
|
111
112
|
railAccess: (now) => batchedRailAccess({ config, credentials, now }),
|
|
112
113
|
now: () => new Date(),
|
|
113
114
|
emit: auditLogEmit(log),
|
|
115
|
+
// Handed over by the generated entry when the catalog credits a balance, undefined otherwise — this
|
|
116
|
+
// host composes nothing, so it cannot find a ledger for itself. See `hostPeers.ts`.
|
|
117
|
+
ledgerPeer: hostPeers.ledger,
|
|
114
118
|
/**
|
|
115
119
|
* The Paddle events sweep, supplied only when that rail is on.
|
|
116
120
|
*
|
|
@@ -134,6 +138,7 @@ export class PaymentsReconcileWorkflow extends WorkflowEntrypoint<PaymentsWorker
|
|
|
134
138
|
// The raw `ENVIRONMENT`, not the two-valued store environment: the shared-sandbox fence
|
|
135
139
|
// separates `dev` from `staging`, and both are `sandbox` on the other axis.
|
|
136
140
|
deployment: this.env.ENVIRONMENT,
|
|
141
|
+
ledgerPeer: hostPeers.ledger,
|
|
137
142
|
now: () => new Date(),
|
|
138
143
|
}),
|
|
139
144
|
}
|