@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.
Files changed (42) 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/version.generated.d.ts +1 -1
  19. package/dist/version.generated.js +1 -1
  20. package/dist/workflows/hostPeers.d.ts +37 -0
  21. package/dist/workflows/hostPeers.d.ts.map +1 -0
  22. package/dist/workflows/hostPeers.js +17 -0
  23. package/dist/workflows/paddleSweep.d.ts +3 -0
  24. package/dist/workflows/paddleSweep.d.ts.map +1 -1
  25. package/dist/workflows/paddleSweep.js +2 -0
  26. package/dist/workflows/reconcile.d.ts +6 -0
  27. package/dist/workflows/reconcile.d.ts.map +1 -1
  28. package/dist/workflows/reconcile.js +1 -0
  29. package/dist/workflows/worker.d.ts.map +1 -1
  30. package/dist/workflows/worker.js +3 -0
  31. package/package.json +3 -3
  32. package/src/capability.ts +60 -16
  33. package/src/grants/apply.ts +14 -8
  34. package/src/grants/ledgerSeam.ts +43 -33
  35. package/src/http/routes.ts +17 -8
  36. package/src/index.ts +2 -1
  37. package/src/peer.ts +29 -0
  38. package/src/version.generated.ts +1 -1
  39. package/src/workflows/hostPeers.ts +41 -0
  40. package/src/workflows/paddleSweep.ts +9 -2
  41. package/src/workflows/reconcile.ts +12 -1
  42. package/src/workflows/worker.ts +5 -0
@@ -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
  }