@pithy-sh/payments 0.3.10 → 0.5.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 (215) hide show
  1. package/README.md +11 -3
  2. package/dist/admin/coverage.d.ts.map +1 -1
  3. package/dist/admin/coverage.js +26 -2
  4. package/dist/admin/read.d.ts +48 -1
  5. package/dist/admin/read.d.ts.map +1 -1
  6. package/dist/admin/read.js +89 -2
  7. package/dist/audit/actions.d.ts +13 -0
  8. package/dist/audit/actions.d.ts.map +1 -1
  9. package/dist/audit/actions.js +14 -1
  10. package/dist/capability.d.ts +33 -2
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +52 -9
  13. package/dist/client/api.d.ts +38 -0
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +59 -1
  16. package/dist/client/hooks.d.ts +63 -1
  17. package/dist/client/hooks.d.ts.map +1 -1
  18. package/dist/client/hooks.js +96 -2
  19. package/dist/client/paddleLink.d.ts +31 -0
  20. package/dist/client/paddleLink.d.ts.map +1 -0
  21. package/dist/client/paddleLink.js +37 -0
  22. package/dist/client/projection.d.ts +29 -0
  23. package/dist/client/projection.d.ts.map +1 -1
  24. package/dist/config/allowances.d.ts +71 -0
  25. package/dist/config/allowances.d.ts.map +1 -0
  26. package/dist/config/allowances.js +115 -0
  27. package/dist/config/config.d.ts +155 -9
  28. package/dist/config/config.d.ts.map +1 -1
  29. package/dist/config/config.js +164 -14
  30. package/dist/data/meterCounter.d.ts +34 -0
  31. package/dist/data/meterCounter.d.ts.map +1 -0
  32. package/dist/data/meterCounter.js +33 -0
  33. package/dist/data/override.d.ts +56 -0
  34. package/dist/data/override.d.ts.map +1 -0
  35. package/dist/data/override.js +58 -0
  36. package/dist/data/paddleIds.d.ts +28 -0
  37. package/dist/data/paddleIds.d.ts.map +1 -0
  38. package/dist/data/paddleIds.js +73 -0
  39. package/dist/data/period.d.ts +10 -0
  40. package/dist/data/period.d.ts.map +1 -0
  41. package/dist/data/period.js +37 -0
  42. package/dist/data/purchase.d.ts +1 -0
  43. package/dist/data/purchase.d.ts.map +1 -1
  44. package/dist/data/purchase.js +1 -0
  45. package/dist/data/tables.d.ts +17 -1
  46. package/dist/data/tables.d.ts.map +1 -1
  47. package/dist/data/tables.js +24 -4
  48. package/dist/data/usageReport.d.ts +68 -0
  49. package/dist/data/usageReport.d.ts.map +1 -0
  50. package/dist/data/usageReport.js +55 -0
  51. package/dist/data/usageRun.d.ts +93 -0
  52. package/dist/data/usageRun.d.ts.map +1 -0
  53. package/dist/data/usageRun.js +50 -0
  54. package/dist/entitlement/allowance.d.ts +100 -0
  55. package/dist/entitlement/allowance.d.ts.map +1 -0
  56. package/dist/entitlement/allowance.js +171 -0
  57. package/dist/entitlement/manual.d.ts +5 -5
  58. package/dist/entitlement/manual.js +3 -3
  59. package/dist/entitlement/meter.d.ts +98 -0
  60. package/dist/entitlement/meter.d.ts.map +1 -0
  61. package/dist/entitlement/meter.js +177 -0
  62. package/dist/entitlement/override.d.ts +119 -0
  63. package/dist/entitlement/override.d.ts.map +1 -0
  64. package/dist/entitlement/override.js +256 -0
  65. package/dist/entitlement/resolver.d.ts +2 -1
  66. package/dist/entitlement/resolver.d.ts.map +1 -1
  67. package/dist/entitlement/resolver.js +32 -1
  68. package/dist/entitlement/unimplementedSubject.d.ts.map +1 -1
  69. package/dist/entitlement/unimplementedSubject.js +3 -2
  70. package/dist/error/errors.d.ts +19 -0
  71. package/dist/error/errors.d.ts.map +1 -1
  72. package/dist/error/errors.js +35 -2
  73. package/dist/http/responses.d.ts +390 -5
  74. package/dist/http/responses.d.ts.map +1 -1
  75. package/dist/http/responses.js +169 -13
  76. package/dist/http/routes.d.ts +6 -2
  77. package/dist/http/routes.d.ts.map +1 -1
  78. package/dist/http/routes.js +478 -52
  79. package/dist/http/schemas.d.ts +75 -1
  80. package/dist/http/schemas.d.ts.map +1 -1
  81. package/dist/http/schemas.js +80 -3
  82. package/dist/http/scopes.d.ts +25 -0
  83. package/dist/http/scopes.d.ts.map +1 -1
  84. package/dist/http/scopes.js +60 -1
  85. package/dist/http/view.d.ts +22 -4
  86. package/dist/http/view.d.ts.map +1 -1
  87. package/dist/http/view.js +88 -7
  88. package/dist/http/webhookGuard.d.ts.map +1 -1
  89. package/dist/http/webhookGuard.js +1 -1
  90. package/dist/index.d.ts +2 -1
  91. package/dist/index.d.ts.map +1 -1
  92. package/dist/index.js +3 -2
  93. package/dist/migrations/0002_allowances.d.ts +26 -0
  94. package/dist/migrations/0002_allowances.d.ts.map +1 -0
  95. package/dist/migrations/0002_allowances.js +62 -0
  96. package/dist/peer.d.ts +1 -0
  97. package/dist/peer.d.ts.map +1 -1
  98. package/dist/projection/event.d.ts +1 -0
  99. package/dist/projection/event.d.ts.map +1 -1
  100. package/dist/projection/event.js +1 -0
  101. package/dist/projection/writer.d.ts.map +1 -1
  102. package/dist/projection/writer.js +3 -1
  103. package/dist/rails/contract.d.ts +6 -0
  104. package/dist/rails/contract.d.ts.map +1 -1
  105. package/dist/rails/google/playApi.d.ts.map +1 -1
  106. package/dist/rails/google/playApi.js +2 -0
  107. package/dist/rails/paddle/events.d.ts.map +1 -1
  108. package/dist/rails/paddle/events.js +2 -1
  109. package/dist/rails/paddle/objects.d.ts +2 -0
  110. package/dist/rails/paddle/objects.d.ts.map +1 -1
  111. package/dist/rails/paddle/objects.js +7 -2
  112. package/dist/rails/paddle/refresh.d.ts +10 -5
  113. package/dist/rails/paddle/refresh.d.ts.map +1 -1
  114. package/dist/rails/paddle/refresh.js +8 -5
  115. package/dist/rails/paddle/refund.d.ts.map +1 -1
  116. package/dist/rails/paddle/refund.js +10 -2
  117. package/dist/rails/paddle/subscription.d.ts.map +1 -1
  118. package/dist/rails/paddle/subscription.js +8 -3
  119. package/dist/rails/paddle/usage.d.ts +11 -0
  120. package/dist/rails/paddle/usage.d.ts.map +1 -0
  121. package/dist/rails/paddle/usage.js +49 -0
  122. package/dist/rails/paddle/verify.d.ts.map +1 -1
  123. package/dist/rails/paddle/verify.js +2 -3
  124. package/dist/rails/quantity.d.ts +12 -0
  125. package/dist/rails/quantity.d.ts.map +1 -0
  126. package/dist/rails/quantity.js +16 -0
  127. package/dist/rails/stripe/checkout.d.ts.map +1 -1
  128. package/dist/rails/stripe/checkout.js +1 -1
  129. package/dist/rails/stripe/objects.d.ts.map +1 -1
  130. package/dist/rails/stripe/objects.js +3 -0
  131. package/dist/rails/stripe/usage.d.ts +10 -0
  132. package/dist/rails/stripe/usage.d.ts.map +1 -0
  133. package/dist/rails/stripe/usage.js +49 -0
  134. package/dist/secret/registry.d.ts.map +1 -1
  135. package/dist/secret/registry.js +3 -2
  136. package/dist/usage/pass.d.ts +120 -0
  137. package/dist/usage/pass.d.ts.map +1 -0
  138. package/dist/usage/pass.js +363 -0
  139. package/dist/usage/reporter.d.ts +36 -0
  140. package/dist/usage/reporter.d.ts.map +1 -0
  141. package/dist/usage/reporter.js +2 -0
  142. package/dist/version.generated.d.ts +1 -1
  143. package/dist/version.generated.d.ts.map +1 -1
  144. package/dist/version.generated.js +1 -1
  145. package/dist/workflows/specs.d.ts +28 -0
  146. package/dist/workflows/specs.d.ts.map +1 -1
  147. package/dist/workflows/specs.js +26 -1
  148. package/dist/workflows/usage.d.ts +38 -0
  149. package/dist/workflows/usage.d.ts.map +1 -0
  150. package/dist/workflows/usage.js +77 -0
  151. package/dist/workflows/worker.js +2 -2
  152. package/dist/workflows/workerConfig.d.ts.map +1 -1
  153. package/dist/workflows/workerConfig.js +8 -2
  154. package/docs/entitlements.md +249 -0
  155. package/docs/lemon-squeezy.md +1 -0
  156. package/docs/paddle.md +18 -2
  157. package/package.json +7 -7
  158. package/pithy.manifest.json +3 -8
  159. package/src/admin/coverage.ts +28 -0
  160. package/src/admin/read.ts +173 -1
  161. package/src/audit/actions.ts +13 -0
  162. package/src/capability.ts +87 -9
  163. package/src/client/api.ts +79 -0
  164. package/src/client/hooks.ts +122 -0
  165. package/src/client/paddleLink.ts +41 -0
  166. package/src/client/projection.ts +31 -0
  167. package/src/config/allowances.ts +211 -0
  168. package/src/config/config.ts +283 -15
  169. package/src/data/meterCounter.ts +38 -0
  170. package/src/data/override.ts +74 -0
  171. package/src/data/paddleIds.ts +74 -0
  172. package/src/data/period.ts +53 -0
  173. package/src/data/purchase.ts +9 -0
  174. package/src/data/tables.ts +25 -1
  175. package/src/data/usageReport.ts +64 -0
  176. package/src/data/usageRun.ts +66 -0
  177. package/src/entitlement/allowance.ts +213 -0
  178. package/src/entitlement/manual.ts +6 -6
  179. package/src/entitlement/meter.ts +252 -0
  180. package/src/entitlement/override.ts +381 -0
  181. package/src/entitlement/resolver.ts +43 -2
  182. package/src/entitlement/unimplementedSubject.ts +3 -4
  183. package/src/error/errors.ts +44 -1
  184. package/src/http/responses.ts +338 -10
  185. package/src/http/routes.ts +1089 -460
  186. package/src/http/schemas.ts +171 -2
  187. package/src/http/scopes.ts +68 -0
  188. package/src/http/view.ts +112 -7
  189. package/src/http/webhookGuard.ts +3 -2
  190. package/src/index.ts +18 -0
  191. package/src/migrations/0002_allowances.ts +149 -0
  192. package/src/projection/event.ts +9 -0
  193. package/src/projection/writer.ts +4 -0
  194. package/src/rails/contract.ts +6 -0
  195. package/src/rails/google/playApi.ts +2 -0
  196. package/src/rails/paddle/events.ts +2 -1
  197. package/src/rails/paddle/fixtures/subscription-charge.json +19 -0
  198. package/src/rails/paddle/objects.ts +6 -0
  199. package/src/rails/paddle/refresh.ts +17 -10
  200. package/src/rails/paddle/refund.ts +10 -2
  201. package/src/rails/paddle/subscription.ts +8 -3
  202. package/src/rails/paddle/usage.ts +66 -0
  203. package/src/rails/paddle/verify.ts +6 -4
  204. package/src/rails/quantity.ts +14 -0
  205. package/src/rails/stripe/checkout.ts +3 -1
  206. package/src/rails/stripe/fixtures/meter-event-created.json +12 -0
  207. package/src/rails/stripe/objects.ts +4 -0
  208. package/src/rails/stripe/usage.ts +61 -0
  209. package/src/secret/registry.ts +3 -2
  210. package/src/usage/pass.ts +539 -0
  211. package/src/usage/reporter.ts +38 -0
  212. package/src/version.generated.ts +1 -1
  213. package/src/workflows/specs.ts +34 -0
  214. package/src/workflows/usage.ts +97 -0
  215. package/src/workflows/workerConfig.ts +9 -3
@@ -141,3 +141,37 @@ export const paymentsWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
141
141
  return [key, { key, capability: PAYMENTS_CAPABILITY, job, spec }];
142
142
  }),
143
143
  );
144
+
145
+ /**
146
+ * What one usage-reporting run should cover. Nothing: a cron passes no input, and the pass covers every
147
+ * quantity-billed product. The object exists so a dispatch is validated like every other.
148
+ */
149
+ export const PaymentsUsageParams = z
150
+ .object({})
151
+ .describe("One usage-reporting run. No parameters: a cron passes none, and the pass covers every reported product.");
152
+ export type PaymentsUsageParams = z.infer<typeof PaymentsUsageParams>;
153
+
154
+ /**
155
+ * The usage-reporting pass — a Workflow **the adopter's own Worker hosts**, unlike reconciliation.
156
+ *
157
+ * **Why not the payments host.** The pass calls `resolveQuantity`, which is the adopter's function and lives
158
+ * only in the Worker whose `pithy.config.ts` passed it. The prebuilt host parses a config from a var and has
159
+ * no adopter code at all. So the class is exported from the app Worker's own entry — the same five lines as
160
+ * any app-declared Workflow, calling `reportPaymentsUsage` in `workflows/usage.ts` — and the body finds the
161
+ * composed capability, and the resolver on it, the way a Workflow that sends mail finds the composed email
162
+ * capability.
163
+ *
164
+ * Hourly, so a `daily-peak` day is sampled through the day and every period's report — under either
165
+ * cadence — lands in its last day whatever hour the period ends at. Contributed by `payments()` only when the catalog sells a
166
+ * reported product; a project that bills nothing by quantity binds nothing for it.
167
+ */
168
+ export const paymentsUsageWorkflows = {
169
+ usage: {
170
+ binding: "PAYMENTS_USAGE",
171
+ // No `className`, deliberately: the class is the adopter's — five lines in their own entry, calling
172
+ // `reportPaymentsUsage` — so its `workflows` entry is one they write, and no host derives it.
173
+ params: PaymentsUsageParams,
174
+ schedule: "15 * * * *",
175
+ optional: true,
176
+ },
177
+ } as const satisfies WorkflowSpecMap;
@@ -0,0 +1,97 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import type { D1Database } from "@cloudflare/workers-types";
5
+ import { composedCapability } from "@pithy-sh/core/src/capability/composition";
6
+ import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
7
+ import {
8
+ classifiedSteps,
9
+ type TerminalErrorConstructor,
10
+ type WorkflowStepLike,
11
+ } from "@pithy-sh/core/src/workflow/faults";
12
+ import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
13
+ import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
14
+ import { isPaymentsCapability, type PaymentsCapability } from "../capability";
15
+ import { paddleUsageReporter } from "../rails/paddle/usage";
16
+ import { stripeUsageReporter } from "../rails/stripe/usage";
17
+ import { PAYMENTS_PROVIDER_SECRET, paymentsSecretsRegistry } from "../secret/registry";
18
+ import { runUsageReport, type UsagePassTally } from "../usage/pass";
19
+ import type { UsageReporter } from "../usage/reporter";
20
+ import { paymentsWorkflowRetry } from "./retryPolicy";
21
+ import { PaymentsUsageParams } from "./specs";
22
+
23
+ /**
24
+ * The usage-reporting Workflow's body — run by a class **the adopter's own Worker** exports, because it calls
25
+ * their `resolveQuantity` and that function exists nowhere else.
26
+ *
27
+ * // apps/api/src/index.ts, beside the `createEntrypoint` it already exports
28
+ * import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
29
+ * import { NonRetryableError } from "cloudflare:workflows";
30
+ * import { reportPaymentsUsage } from "@pithy-sh/payments/src/workflows/usage";
31
+ *
32
+ * export class PaymentsUsageWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
33
+ * override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
34
+ * return reportPaymentsUsage(this.env, event, step, NonRetryableError);
35
+ * }
36
+ * }
37
+ *
38
+ * plus a `workflows` entry binding `PAYMENTS_USAGE` to that class and the spec's cron —
39
+ * `packages/payments/docs/entitlements.md` has the stanza. **The class is the adopter's, the body is the
40
+ * kit's**, which is the split every app-declared Workflow already has: Cloudflare resolves a `class_name` in
41
+ * the script that binds it, so the class must be exported from the app's own entry, and a class shipped here
42
+ * would be one more module the build reads as a Workflow host it is not.
43
+ *
44
+ * The body finds the composed payments capability the way a Workflow that sends mail finds the composed email
45
+ * one: the class is exported from the same entry that calls `createBackend`, so the composition has happened
46
+ * in this isolate, and `resolveQuantity` is on the capability, never in a config that crossed a var.
47
+ *
48
+ * One journalled step. The pass is idempotent end to end — every period has one row, claimed before the store
49
+ * is called, and the row id is the store's idempotency key — so a retried step reports nothing twice.
50
+ */
51
+ export async function reportPaymentsUsage(
52
+ env: Record<string, unknown>,
53
+ event: { payload?: unknown; workflowName?: string; instanceId?: string },
54
+ step: WorkflowStepLike,
55
+ terminalError: TerminalErrorConstructor,
56
+ ): Promise<UsagePassTally | null> {
57
+ PaymentsUsageParams.parse(event.payload ?? {});
58
+ const log = bindWorkflowContext(createWorkerLogger({ name: "payments:usage" }), {
59
+ workflow: event.workflowName ?? "payments-usage",
60
+ instance: event.instanceId ?? "unknown",
61
+ env: typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : "unknown",
62
+ });
63
+ const payments = composedCapability<PaymentsCapability>("payments", isPaymentsCapability);
64
+ const usage = payments.paymentsUsage;
65
+ if (usage === undefined) {
66
+ log.warn("usage reporting has no resolver; nothing reported");
67
+ return null;
68
+ }
69
+ const config = payments.paymentsConfig;
70
+
71
+ // Classified like every payments step: a store that could not be reached re-drives it, and anything else
72
+ // fails it at once rather than spending a retry budget on an answer that will not change.
73
+ const steps = classifiedSteps(step, paymentsWorkflowRetry, terminalError);
74
+ return steps.do("report usage", async () => {
75
+ const secrets = await sharedSecretsStore(env as unknown as SecretsStoreEnv, paymentsSecretsRegistry);
76
+ const credentials = secrets.get(PAYMENTS_PROVIDER_SECRET);
77
+ const reporters: Partial<Record<"stripe" | "paddle", UsageReporter>> = {};
78
+ if (credentials.stripe !== undefined) {
79
+ reporters.stripe = stripeUsageReporter({ secretKey: credentials.stripe.secretKey });
80
+ }
81
+ if (credentials.paddle !== undefined && config.paddle !== undefined) {
82
+ reporters.paddle = paddleUsageReporter({
83
+ apiKey: credentials.paddle.apiKey,
84
+ environment: config.paddle.environment,
85
+ });
86
+ }
87
+ return runUsageReport({
88
+ d1: env.DB as D1Database,
89
+ config,
90
+ resolveQuantity: usage.resolveQuantity,
91
+ reporters,
92
+ env,
93
+ now: () => new Date(),
94
+ log,
95
+ });
96
+ });
97
+ }
@@ -2,10 +2,17 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import type { D1Database } from "@cloudflare/workers-types";
5
+ import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
5
6
  import { fromZodError, InternalError, messageOf } from "@pithy-sh/core/src/error/pithyError";
6
7
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
7
8
  import { PaymentsConfig } from "../config/config";
8
9
 
10
+ /**
11
+ * The provision that rewrites this host's config, as the host can name it: it cannot know the `apps/` directory
12
+ * of the app Worker that provisioned it, so it names no `--worker`, and the run asks (#711).
13
+ */
14
+ const PROVISION = pithyCommandOf("payments provision", {}, { runtime: true });
15
+
9
16
  /**
10
17
  * The reconcile worker's env, and the one function that reads its config out of a var.
11
18
  *
@@ -54,7 +61,7 @@ export function reconcileWorkerConfig(env: PaymentsWorkerEnv): PaymentsConfig {
54
61
  } catch (cause) {
55
62
  throw new InternalError({
56
63
  message: "The reconcile worker's PAYMENTS_CONFIG var is not valid JSON.",
57
- action: "Re-run `pithy payments provision` for this environment to rewrite it.",
64
+ action: `Re-run \`${PROVISION}\` for this environment to rewrite it.`,
58
65
  detail: messageOf(cause),
59
66
  });
60
67
  }
@@ -65,8 +72,7 @@ export function reconcileWorkerConfig(env: PaymentsWorkerEnv): PaymentsConfig {
65
72
  message: "The reconcile worker's PAYMENTS_CONFIG var is not a payments config this build can run.",
66
73
  // The two halves of the repair, in the order they have to happen: the value is the adopter's, and the
67
74
  // var is a copy of it. Fixing only the second is a provision that writes the same refusal back.
68
- action:
69
- "Set the missing keys in this Worker's pithy.config.ts — `billingSubject` is required — then re-run `pithy payments provision` for this environment.",
75
+ action: `Set the missing keys in this Worker's pithy.config.ts — \`billingSubject\` is required — then re-run \`${PROVISION}\` for this environment.`,
70
76
  });
71
77
  }
72
78
  return parsed.data;