@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.
Files changed (46) hide show
  1. package/dist/capability.d.ts +11 -3
  2. package/dist/capability.d.ts.map +1 -1
  3. package/dist/capability.js +33 -8
  4. package/dist/grants/apply.d.ts +11 -5
  5. package/dist/grants/apply.d.ts.map +1 -1
  6. package/dist/grants/apply.js +9 -6
  7. package/dist/grants/ledgerSeam.d.ts +34 -14
  8. package/dist/grants/ledgerSeam.d.ts.map +1 -1
  9. package/dist/grants/ledgerSeam.js +8 -16
  10. package/dist/http/routes.d.ts +8 -0
  11. package/dist/http/routes.d.ts.map +1 -1
  12. package/dist/http/routes.js +9 -8
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/peer.d.ts +78 -0
  16. package/dist/peer.d.ts.map +1 -0
  17. package/dist/peer.js +27 -0
  18. package/dist/provision/resolvePaymentsConfig.d.ts +6 -0
  19. package/dist/provision/resolvePaymentsConfig.d.ts.map +1 -1
  20. package/dist/provision/resolvePaymentsConfig.js +5 -2
  21. package/dist/version.generated.d.ts +1 -1
  22. package/dist/version.generated.js +1 -1
  23. package/dist/workflows/hostPeers.d.ts +37 -0
  24. package/dist/workflows/hostPeers.d.ts.map +1 -0
  25. package/dist/workflows/hostPeers.js +17 -0
  26. package/dist/workflows/paddleSweep.d.ts +3 -0
  27. package/dist/workflows/paddleSweep.d.ts.map +1 -1
  28. package/dist/workflows/paddleSweep.js +2 -0
  29. package/dist/workflows/reconcile.d.ts +6 -0
  30. package/dist/workflows/reconcile.d.ts.map +1 -1
  31. package/dist/workflows/reconcile.js +1 -0
  32. package/dist/workflows/worker.d.ts.map +1 -1
  33. package/dist/workflows/worker.js +3 -0
  34. package/package.json +4 -4
  35. package/src/capability.ts +60 -16
  36. package/src/grants/apply.ts +14 -8
  37. package/src/grants/ledgerSeam.ts +43 -33
  38. package/src/http/routes.ts +17 -8
  39. package/src/index.ts +2 -1
  40. package/src/peer.ts +29 -0
  41. package/src/provision/resolvePaymentsConfig.ts +15 -2
  42. package/src/version.generated.ts +1 -1
  43. package/src/workflows/hostPeers.ts +41 -0
  44. package/src/workflows/paddleSweep.ts +9 -2
  45. package/src/workflows/reconcile.ts +12 -1
  46. 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 PaymentsLedgerLoader,
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, { project, capability: PAYMENTS_CAPABILITY, env });
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 —
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/payments";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.3.5";
16
+ export const PACKAGE_VERSION = "0.3.7";
@@ -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 ?? ((d1, value) => fulfillPurchase(d1, value, { config: deps.config, now: () => at.getTime() }));
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 ?? ((d1, value) => fulfillPurchase(d1, value, { config: deps.config, now: () => at.getTime() }));
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, { config: deps.config, emit: deps.emit, now: () => now.getTime() }));
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) {
@@ -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
  }