@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.
- package/README.md +11 -3
- package/dist/admin/coverage.d.ts.map +1 -1
- package/dist/admin/coverage.js +26 -2
- package/dist/admin/read.d.ts +48 -1
- package/dist/admin/read.d.ts.map +1 -1
- package/dist/admin/read.js +89 -2
- package/dist/audit/actions.d.ts +13 -0
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +14 -1
- package/dist/capability.d.ts +33 -2
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +52 -9
- package/dist/client/api.d.ts +38 -0
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +59 -1
- package/dist/client/hooks.d.ts +63 -1
- package/dist/client/hooks.d.ts.map +1 -1
- package/dist/client/hooks.js +96 -2
- package/dist/client/paddleLink.d.ts +31 -0
- package/dist/client/paddleLink.d.ts.map +1 -0
- package/dist/client/paddleLink.js +37 -0
- package/dist/client/projection.d.ts +29 -0
- package/dist/client/projection.d.ts.map +1 -1
- package/dist/config/allowances.d.ts +71 -0
- package/dist/config/allowances.d.ts.map +1 -0
- package/dist/config/allowances.js +115 -0
- package/dist/config/config.d.ts +155 -9
- package/dist/config/config.d.ts.map +1 -1
- package/dist/config/config.js +164 -14
- package/dist/data/meterCounter.d.ts +34 -0
- package/dist/data/meterCounter.d.ts.map +1 -0
- package/dist/data/meterCounter.js +33 -0
- package/dist/data/override.d.ts +56 -0
- package/dist/data/override.d.ts.map +1 -0
- package/dist/data/override.js +58 -0
- package/dist/data/paddleIds.d.ts +28 -0
- package/dist/data/paddleIds.d.ts.map +1 -0
- package/dist/data/paddleIds.js +73 -0
- package/dist/data/period.d.ts +10 -0
- package/dist/data/period.d.ts.map +1 -0
- package/dist/data/period.js +37 -0
- package/dist/data/purchase.d.ts +1 -0
- package/dist/data/purchase.d.ts.map +1 -1
- package/dist/data/purchase.js +1 -0
- package/dist/data/tables.d.ts +17 -1
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +24 -4
- package/dist/data/usageReport.d.ts +68 -0
- package/dist/data/usageReport.d.ts.map +1 -0
- package/dist/data/usageReport.js +55 -0
- package/dist/data/usageRun.d.ts +93 -0
- package/dist/data/usageRun.d.ts.map +1 -0
- package/dist/data/usageRun.js +50 -0
- package/dist/entitlement/allowance.d.ts +100 -0
- package/dist/entitlement/allowance.d.ts.map +1 -0
- package/dist/entitlement/allowance.js +171 -0
- package/dist/entitlement/manual.d.ts +5 -5
- package/dist/entitlement/manual.js +3 -3
- package/dist/entitlement/meter.d.ts +98 -0
- package/dist/entitlement/meter.d.ts.map +1 -0
- package/dist/entitlement/meter.js +177 -0
- package/dist/entitlement/override.d.ts +119 -0
- package/dist/entitlement/override.d.ts.map +1 -0
- package/dist/entitlement/override.js +256 -0
- package/dist/entitlement/resolver.d.ts +2 -1
- package/dist/entitlement/resolver.d.ts.map +1 -1
- package/dist/entitlement/resolver.js +32 -1
- package/dist/entitlement/unimplementedSubject.d.ts.map +1 -1
- package/dist/entitlement/unimplementedSubject.js +3 -2
- package/dist/error/errors.d.ts +19 -0
- package/dist/error/errors.d.ts.map +1 -1
- package/dist/error/errors.js +35 -2
- package/dist/http/responses.d.ts +390 -5
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +169 -13
- package/dist/http/routes.d.ts +6 -2
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +478 -52
- package/dist/http/schemas.d.ts +75 -1
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +80 -3
- package/dist/http/scopes.d.ts +25 -0
- package/dist/http/scopes.d.ts.map +1 -1
- package/dist/http/scopes.js +60 -1
- package/dist/http/view.d.ts +22 -4
- package/dist/http/view.d.ts.map +1 -1
- package/dist/http/view.js +88 -7
- package/dist/http/webhookGuard.d.ts.map +1 -1
- package/dist/http/webhookGuard.js +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/migrations/0002_allowances.d.ts +26 -0
- package/dist/migrations/0002_allowances.d.ts.map +1 -0
- package/dist/migrations/0002_allowances.js +62 -0
- package/dist/peer.d.ts +1 -0
- package/dist/peer.d.ts.map +1 -1
- package/dist/projection/event.d.ts +1 -0
- package/dist/projection/event.d.ts.map +1 -1
- package/dist/projection/event.js +1 -0
- package/dist/projection/writer.d.ts.map +1 -1
- package/dist/projection/writer.js +3 -1
- package/dist/rails/contract.d.ts +6 -0
- package/dist/rails/contract.d.ts.map +1 -1
- package/dist/rails/google/playApi.d.ts.map +1 -1
- package/dist/rails/google/playApi.js +2 -0
- package/dist/rails/paddle/events.d.ts.map +1 -1
- package/dist/rails/paddle/events.js +2 -1
- package/dist/rails/paddle/objects.d.ts +2 -0
- package/dist/rails/paddle/objects.d.ts.map +1 -1
- package/dist/rails/paddle/objects.js +7 -2
- package/dist/rails/paddle/refresh.d.ts +10 -5
- package/dist/rails/paddle/refresh.d.ts.map +1 -1
- package/dist/rails/paddle/refresh.js +8 -5
- package/dist/rails/paddle/refund.d.ts.map +1 -1
- package/dist/rails/paddle/refund.js +10 -2
- package/dist/rails/paddle/subscription.d.ts.map +1 -1
- package/dist/rails/paddle/subscription.js +8 -3
- package/dist/rails/paddle/usage.d.ts +11 -0
- package/dist/rails/paddle/usage.d.ts.map +1 -0
- package/dist/rails/paddle/usage.js +49 -0
- package/dist/rails/paddle/verify.d.ts.map +1 -1
- package/dist/rails/paddle/verify.js +2 -3
- package/dist/rails/quantity.d.ts +12 -0
- package/dist/rails/quantity.d.ts.map +1 -0
- package/dist/rails/quantity.js +16 -0
- package/dist/rails/stripe/checkout.d.ts.map +1 -1
- package/dist/rails/stripe/checkout.js +1 -1
- package/dist/rails/stripe/objects.d.ts.map +1 -1
- package/dist/rails/stripe/objects.js +3 -0
- package/dist/rails/stripe/usage.d.ts +10 -0
- package/dist/rails/stripe/usage.d.ts.map +1 -0
- package/dist/rails/stripe/usage.js +49 -0
- package/dist/secret/registry.d.ts.map +1 -1
- package/dist/secret/registry.js +3 -2
- package/dist/usage/pass.d.ts +120 -0
- package/dist/usage/pass.d.ts.map +1 -0
- package/dist/usage/pass.js +363 -0
- package/dist/usage/reporter.d.ts +36 -0
- package/dist/usage/reporter.d.ts.map +1 -0
- package/dist/usage/reporter.js +2 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.d.ts.map +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/specs.d.ts +28 -0
- package/dist/workflows/specs.d.ts.map +1 -1
- package/dist/workflows/specs.js +26 -1
- package/dist/workflows/usage.d.ts +38 -0
- package/dist/workflows/usage.d.ts.map +1 -0
- package/dist/workflows/usage.js +77 -0
- package/dist/workflows/worker.js +2 -2
- package/dist/workflows/workerConfig.d.ts.map +1 -1
- package/dist/workflows/workerConfig.js +8 -2
- package/docs/entitlements.md +249 -0
- package/docs/lemon-squeezy.md +1 -0
- package/docs/paddle.md +18 -2
- package/package.json +7 -7
- package/pithy.manifest.json +3 -8
- package/src/admin/coverage.ts +28 -0
- package/src/admin/read.ts +173 -1
- package/src/audit/actions.ts +13 -0
- package/src/capability.ts +87 -9
- package/src/client/api.ts +79 -0
- package/src/client/hooks.ts +122 -0
- package/src/client/paddleLink.ts +41 -0
- package/src/client/projection.ts +31 -0
- package/src/config/allowances.ts +211 -0
- package/src/config/config.ts +283 -15
- package/src/data/meterCounter.ts +38 -0
- package/src/data/override.ts +74 -0
- package/src/data/paddleIds.ts +74 -0
- package/src/data/period.ts +53 -0
- package/src/data/purchase.ts +9 -0
- package/src/data/tables.ts +25 -1
- package/src/data/usageReport.ts +64 -0
- package/src/data/usageRun.ts +66 -0
- package/src/entitlement/allowance.ts +213 -0
- package/src/entitlement/manual.ts +6 -6
- package/src/entitlement/meter.ts +252 -0
- package/src/entitlement/override.ts +381 -0
- package/src/entitlement/resolver.ts +43 -2
- package/src/entitlement/unimplementedSubject.ts +3 -4
- package/src/error/errors.ts +44 -1
- package/src/http/responses.ts +338 -10
- package/src/http/routes.ts +1089 -460
- package/src/http/schemas.ts +171 -2
- package/src/http/scopes.ts +68 -0
- package/src/http/view.ts +112 -7
- package/src/http/webhookGuard.ts +3 -2
- package/src/index.ts +18 -0
- package/src/migrations/0002_allowances.ts +149 -0
- package/src/projection/event.ts +9 -0
- package/src/projection/writer.ts +4 -0
- package/src/rails/contract.ts +6 -0
- package/src/rails/google/playApi.ts +2 -0
- package/src/rails/paddle/events.ts +2 -1
- package/src/rails/paddle/fixtures/subscription-charge.json +19 -0
- package/src/rails/paddle/objects.ts +6 -0
- package/src/rails/paddle/refresh.ts +17 -10
- package/src/rails/paddle/refund.ts +10 -2
- package/src/rails/paddle/subscription.ts +8 -3
- package/src/rails/paddle/usage.ts +66 -0
- package/src/rails/paddle/verify.ts +6 -4
- package/src/rails/quantity.ts +14 -0
- package/src/rails/stripe/checkout.ts +3 -1
- package/src/rails/stripe/fixtures/meter-event-created.json +12 -0
- package/src/rails/stripe/objects.ts +4 -0
- package/src/rails/stripe/usage.ts +61 -0
- package/src/secret/registry.ts +3 -2
- package/src/usage/pass.ts +539 -0
- package/src/usage/reporter.ts +38 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/specs.ts +34 -0
- package/src/workflows/usage.ts +97 -0
- package/src/workflows/workerConfig.ts +9 -3
package/src/workflows/specs.ts
CHANGED
|
@@ -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:
|
|
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;
|