@pithy-sh/payments 0.4.0 → 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 +10 -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 +19 -0
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +34 -1
- package/dist/client/hooks.d.ts +20 -1
- package/dist/client/hooks.d.ts.map +1 -1
- package/dist/client/hooks.js +40 -2
- 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/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/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 +367 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +146 -7
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +270 -16
- package/dist/http/schemas.d.ts +54 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +61 -2
- 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/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/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/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/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/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.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/docs/entitlements.md +249 -0
- package/docs/lemon-squeezy.md +1 -0
- package/docs/paddle.md +1 -0
- package/package.json +5 -5
- 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 +44 -0
- package/src/client/hooks.ts +44 -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/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/error/errors.ts +44 -1
- package/src/http/responses.ts +305 -4
- package/src/http/routes.ts +365 -11
- package/src/http/schemas.ts +139 -1
- package/src/http/scopes.ts +68 -0
- package/src/http/view.ts +112 -7
- 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/fixtures/subscription-charge.json +19 -0
- package/src/rails/paddle/objects.ts +6 -0
- package/src/rails/paddle/usage.ts +66 -0
- 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/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
|
@@ -2,11 +2,18 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
4
|
import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
|
|
5
|
-
import type {
|
|
5
|
+
import type {
|
|
6
|
+
Entitlement,
|
|
7
|
+
EntitlementHolder,
|
|
8
|
+
EntitlementResolver,
|
|
9
|
+
MeterLimit,
|
|
10
|
+
} from "@pithy-sh/core/src/entitlement/entitlement";
|
|
6
11
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
12
|
import { encodeSubjectReference, type PaymentsSubject } from "../data/subject";
|
|
8
13
|
import type { PaymentsDatabase } from "../data/tables";
|
|
9
14
|
import { resolveEntitlements } from "../projection/resolve";
|
|
15
|
+
import { requireDeclaredFeature, requireDeclaredQuota, resolveFeature, resolveQuota } from "./allowance";
|
|
16
|
+
import { allowanceInputFor, meterLimitFor, type PaymentsAllowances } from "./meter";
|
|
10
17
|
import { type PaymentsSubjectSeam, resolvePaymentsSubject } from "./subjectSeam";
|
|
11
18
|
|
|
12
19
|
/**
|
|
@@ -81,7 +88,11 @@ export function createPaymentsEntitlementResolver(
|
|
|
81
88
|
* neither is a composition problem, and reporting `null` here would send an operator looking for a missing
|
|
82
89
|
* capability.
|
|
83
90
|
*/
|
|
84
|
-
export function installEntitlementResolver(
|
|
91
|
+
export function installEntitlementResolver(
|
|
92
|
+
database: string,
|
|
93
|
+
seam: PaymentsSubjectSeam,
|
|
94
|
+
allowances: PaymentsAllowances = { declarations: { entitlements: {} }, meters: {} },
|
|
95
|
+
): PithyMiddleware {
|
|
85
96
|
return (app) => {
|
|
86
97
|
app.use("*", async (c, next) => {
|
|
87
98
|
// **One resolution per request, shared by `list()` and `holder()`.** The seam is the adopter's and
|
|
@@ -93,8 +104,38 @@ export function installEntitlementResolver(database: string, seam: PaymentsSubje
|
|
|
93
104
|
resolving ??= resolvePaymentsSubject(c, seam);
|
|
94
105
|
return resolving;
|
|
95
106
|
};
|
|
107
|
+
/** The database, or the wiring fault — checked only once a read actually needs one. */
|
|
108
|
+
const appDatabase = (): PaymentsDatabase => {
|
|
109
|
+
const db = (c.var.db as Record<string, PaymentsDatabase>)[database];
|
|
110
|
+
if (!db) {
|
|
111
|
+
throw new InternalError({
|
|
112
|
+
message: "Payments is not configured.",
|
|
113
|
+
action: "Bind a D1 database named DB in wrangler.jsonc.",
|
|
114
|
+
detail: `No \`${database}\` database on c.var.db; payments cannot resolve allowances.`,
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
return db;
|
|
118
|
+
};
|
|
96
119
|
c.set("entitlements", {
|
|
97
120
|
provider: PAYMENTS_ENTITLEMENT_PROVIDER,
|
|
121
|
+
// **The name is checked before anything is read**, so a typo is a hard failure on every request
|
|
122
|
+
// rather than only on the ones that reach D1 — and never a 0 or an unlimited.
|
|
123
|
+
quota: async (name: string): Promise<number | null> => {
|
|
124
|
+
requireDeclaredQuota(allowances.declarations, name);
|
|
125
|
+
const subject = await subjectOnce();
|
|
126
|
+
const input = await allowanceInputFor(subject && appDatabase(), allowances.declarations, subject, new Date());
|
|
127
|
+
return resolveQuota(input, name).effective.value;
|
|
128
|
+
},
|
|
129
|
+
feature: async (name: string): Promise<boolean> => {
|
|
130
|
+
requireDeclaredFeature(allowances.declarations, name);
|
|
131
|
+
const subject = await subjectOnce();
|
|
132
|
+
const input = await allowanceInputFor(subject && appDatabase(), allowances.declarations, subject, new Date());
|
|
133
|
+
return resolveFeature(input, name).effective.value;
|
|
134
|
+
},
|
|
135
|
+
meterLimit: async (meter: string): Promise<MeterLimit> => {
|
|
136
|
+
const subject = await subjectOnce();
|
|
137
|
+
return meterLimitFor(appDatabase(), allowances, subject, meter, new Date());
|
|
138
|
+
},
|
|
98
139
|
// Who the read answered for, for the log and the trail alone. `undefined` is a real answer and a
|
|
99
140
|
// different one from "holds nothing": it is a caller acting for no organization, which is what
|
|
100
141
|
// lets core's denial say so instead of reporting an empty list twice over.
|
package/src/error/errors.ts
CHANGED
|
@@ -256,7 +256,7 @@ export class PaymentsEntitlementNotInCatalogError extends PithyError {
|
|
|
256
256
|
message: args.message ?? "That entitlement is not one this project defines.",
|
|
257
257
|
action:
|
|
258
258
|
args.action ??
|
|
259
|
-
"Grant a key
|
|
259
|
+
"Grant a key the `entitlements` map in pithy.config.ts declares, or declare it there — a declared key no product sells is grantable by hand.",
|
|
260
260
|
detail: args.detail,
|
|
261
261
|
params: args.params,
|
|
262
262
|
},
|
|
@@ -419,3 +419,46 @@ export class PaymentsSubscriptionChangeRefusedError extends PithyError {
|
|
|
419
419
|
);
|
|
420
420
|
}
|
|
421
421
|
}
|
|
422
|
+
|
|
423
|
+
/**
|
|
424
|
+
* An override set named a version behind the row it would change. Two operators share one customer: both
|
|
425
|
+
* opened `emails`, and the second would silently win while the first believes they succeeded. So the set is
|
|
426
|
+
* refused and nothing is written, and the caller re-reads before it tries again.
|
|
427
|
+
*/
|
|
428
|
+
export class PaymentsOverrideStaleError extends PithyError {
|
|
429
|
+
constructor(args: PaymentsErrorArgs = {}, options?: { cause?: unknown }) {
|
|
430
|
+
super(
|
|
431
|
+
{
|
|
432
|
+
code: "payments/override_stale",
|
|
433
|
+
status: 409,
|
|
434
|
+
message: args.message ?? "That override changed since it was read.",
|
|
435
|
+
action: args.action ?? "Read the subject's entitlements again, then set the override against the new version.",
|
|
436
|
+
detail: args.detail,
|
|
437
|
+
params: args.params,
|
|
438
|
+
},
|
|
439
|
+
options,
|
|
440
|
+
);
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* An enforced meter refused: the subject's effective quota for this period does not allow more. 402, because
|
|
446
|
+
* the caller's plan does not allow it and the remedy is a purchase — a bigger tier, or a pinned number.
|
|
447
|
+
*/
|
|
448
|
+
export class PaymentsQuotaExceededError extends PithyError {
|
|
449
|
+
constructor(args: PaymentsErrorArgs = {}, options?: { cause?: unknown }) {
|
|
450
|
+
super(
|
|
451
|
+
{
|
|
452
|
+
code: "payments/quota_exceeded",
|
|
453
|
+
status: 402,
|
|
454
|
+
message: args.message ?? "This plan's allowance is used up for this period.",
|
|
455
|
+
action:
|
|
456
|
+
args.action ??
|
|
457
|
+
"Upgrade the plan, or pin a larger allowance for this subject from the control plane. The meter resets when the period does.",
|
|
458
|
+
detail: args.detail,
|
|
459
|
+
params: args.params,
|
|
460
|
+
},
|
|
461
|
+
options,
|
|
462
|
+
);
|
|
463
|
+
}
|
|
464
|
+
}
|
package/src/http/responses.ts
CHANGED
|
@@ -91,8 +91,22 @@ export type PaymentsPurchaseResponse = z.output<typeof PaymentsPurchaseResponse>
|
|
|
91
91
|
|
|
92
92
|
/** `GET {base}/entitlements` — always the caller's own. */
|
|
93
93
|
export const PaymentsEntitlementsResponse = z
|
|
94
|
-
.object({
|
|
95
|
-
|
|
94
|
+
.object({
|
|
95
|
+
entitlements: z.array(PaymentsEntitlementView).describe("The caller's entitlements, resolved now."),
|
|
96
|
+
quotas: z
|
|
97
|
+
.record(z.string(), z.number().int().nonnegative().nullable().describe("A whole number, or null for unlimited."))
|
|
98
|
+
.optional()
|
|
99
|
+
.describe(
|
|
100
|
+
"Every declared quota, resolved for the caller's holder now — what `quota(c, name)` answers on the server, for a paywall screen to show. A UX affordance, never a security boundary: the server enforces. Absent from a Worker that predates declarations.",
|
|
101
|
+
),
|
|
102
|
+
features: z
|
|
103
|
+
.record(z.string(), z.boolean().describe("Whether it is on."))
|
|
104
|
+
.optional()
|
|
105
|
+
.describe(
|
|
106
|
+
"Every declared feature, resolved for the caller's holder now. A UX affordance, never a security boundary. Absent from a Worker that predates declarations.",
|
|
107
|
+
),
|
|
108
|
+
})
|
|
109
|
+
.describe("Every entitlement the caller holds, and the allowances they resolve to.");
|
|
96
110
|
export type PaymentsEntitlementsResponse = z.output<typeof PaymentsEntitlementsResponse>;
|
|
97
111
|
|
|
98
112
|
/** `POST {base}/restore`. */
|
|
@@ -602,6 +616,22 @@ export const PaymentsSubscriptionView = z
|
|
|
602
616
|
nextEvent: PaymentsSubscriptionNextEvent.describe(
|
|
603
617
|
"What happens next and when, already resolved — the scheduled change ahead of the billing date. The sentence a screen prints.",
|
|
604
618
|
),
|
|
619
|
+
reportedQuantity: z
|
|
620
|
+
.number()
|
|
621
|
+
.int()
|
|
622
|
+
.nonnegative()
|
|
623
|
+
.nullable()
|
|
624
|
+
.optional()
|
|
625
|
+
.describe(
|
|
626
|
+
"For a quantity-billed product, the last count reported to the store — null when nothing has been reported yet. Absent from a Worker that predates reported billing.",
|
|
627
|
+
),
|
|
628
|
+
reportedAt: z.iso
|
|
629
|
+
.datetime()
|
|
630
|
+
.nullable()
|
|
631
|
+
.optional()
|
|
632
|
+
.describe(
|
|
633
|
+
"When that count was reported, ISO-8601, or null when nothing has been. Absent from a Worker that predates reported billing.",
|
|
634
|
+
),
|
|
605
635
|
})
|
|
606
636
|
.describe("One subscription as the person paying for it reads it: which plan, where it stands, and what is next.");
|
|
607
637
|
export type PaymentsSubscriptionView = z.output<typeof PaymentsSubscriptionView>;
|
|
@@ -878,6 +908,52 @@ export const PaymentsAdminCatalogProduct = z
|
|
|
878
908
|
.describe("One catalog product as a management client sees it: what it is, and what it grants.");
|
|
879
909
|
export type PaymentsAdminCatalogProduct = z.output<typeof PaymentsAdminCatalogProduct>;
|
|
880
910
|
|
|
911
|
+
/** A quota's value on the wire: a whole number from 0, or null for unlimited. */
|
|
912
|
+
const WireQuota = z.number().int().nonnegative().nullable().describe("A whole number from 0, or null for unlimited.");
|
|
913
|
+
|
|
914
|
+
/**
|
|
915
|
+
* One declared entitlement key, as a management client sees it: what it is called, and what it buys.
|
|
916
|
+
*
|
|
917
|
+
* **What an override editor is built from.** An override names a quota or a feature, and without this a pane
|
|
918
|
+
* could not say which names exist, which are numbers and which are switches, what the plan's value is, or
|
|
919
|
+
* what ceiling an operator may type up to. `quotas` holds numbers and `features` holds booleans, so the map a
|
|
920
|
+
* name sits in *is* its kind.
|
|
921
|
+
*/
|
|
922
|
+
export const PaymentsAdminCatalogEntitlement = z
|
|
923
|
+
.object({
|
|
924
|
+
key: z.string().describe("The entitlement key — what gating code names, and what a comp grants."),
|
|
925
|
+
name: z.string().describe("The tier's display name, as the adopter wrote it — `Growth`."),
|
|
926
|
+
quotas: z
|
|
927
|
+
.record(z.string(), WireQuota)
|
|
928
|
+
.describe("What this key allows, by quota name. A whole number, or null for unlimited."),
|
|
929
|
+
features: z
|
|
930
|
+
.record(z.string(), z.boolean().describe("Whether the switch is on."))
|
|
931
|
+
.describe("Its switches, by name."),
|
|
932
|
+
overrideMax: z
|
|
933
|
+
.record(z.string(), z.number().int().nonnegative().describe("The ceiling."))
|
|
934
|
+
.describe(
|
|
935
|
+
"Per quota, the largest number an override may set. A quota absent here accepts any whole number. `unrestricted` is never bounded by it.",
|
|
936
|
+
),
|
|
937
|
+
sold: z
|
|
938
|
+
.boolean()
|
|
939
|
+
.describe(
|
|
940
|
+
"Whether a product in this catalog grants the key. False is comp-only: grantable by hand, sold by nothing.",
|
|
941
|
+
),
|
|
942
|
+
})
|
|
943
|
+
.describe("One declared entitlement key: its name, its quotas, its features, and the ceilings on overriding them.");
|
|
944
|
+
export type PaymentsAdminCatalogEntitlement = z.output<typeof PaymentsAdminCatalogEntitlement>;
|
|
945
|
+
|
|
946
|
+
/** The free floor, as a management client sees it. */
|
|
947
|
+
export const PaymentsAdminCatalogDefaults = z
|
|
948
|
+
.object({
|
|
949
|
+
quotas: z.record(z.string(), WireQuota).describe("What a subject holding no key gets, by quota name."),
|
|
950
|
+
features: z
|
|
951
|
+
.record(z.string(), z.boolean().describe("Whether the switch is on."))
|
|
952
|
+
.describe("The switches a subject holding no key gets."),
|
|
953
|
+
})
|
|
954
|
+
.describe("What a caller holding no key gets — the free floor.");
|
|
955
|
+
export type PaymentsAdminCatalogDefaults = z.output<typeof PaymentsAdminCatalogDefaults>;
|
|
956
|
+
|
|
881
957
|
/**
|
|
882
958
|
* `GET {base}/admin/catalog` — what this project sells.
|
|
883
959
|
*
|
|
@@ -898,7 +974,7 @@ export const PaymentsAdminCatalogResponse = z
|
|
|
898
974
|
enabled: z
|
|
899
975
|
.literal(false)
|
|
900
976
|
.describe(
|
|
901
|
-
"This project defines nothing — no product is configured and no key
|
|
977
|
+
"This project defines nothing — no product is configured and no key is declared, so there is no entitlement a comp control could offer and no grant that would succeed.",
|
|
902
978
|
),
|
|
903
979
|
})
|
|
904
980
|
.describe("A project composing payments with an empty catalog. The same answer as not composing it at all."),
|
|
@@ -911,8 +987,17 @@ export const PaymentsAdminCatalogResponse = z
|
|
|
911
987
|
manualEntitlements: z
|
|
912
988
|
.array(z.string())
|
|
913
989
|
.describe(
|
|
914
|
-
"
|
|
990
|
+
"The comp-only keys — declared, and sold by no product. Offered beside the products because a comp control that omitted them would refuse the grants it then submitted. Kept under its first name so a client reading an older Worker and a newer one reads one field.",
|
|
991
|
+
),
|
|
992
|
+
entitlements: z
|
|
993
|
+
.array(PaymentsAdminCatalogEntitlement)
|
|
994
|
+
.optional()
|
|
995
|
+
.describe(
|
|
996
|
+
"Every declared key and what it buys, in the order the adopter wrote them. Absent from a Worker that predates declarations. What an override editor is built from: every editable name, and whether it is a number or a switch.",
|
|
915
997
|
),
|
|
998
|
+
defaults: PaymentsAdminCatalogDefaults.nullable()
|
|
999
|
+
.optional()
|
|
1000
|
+
.describe("The free floor, or null when none is declared. Absent from a Worker that predates declarations."),
|
|
916
1001
|
})
|
|
917
1002
|
.describe("The catalog, as a management client reads it."),
|
|
918
1003
|
])
|
|
@@ -940,6 +1025,31 @@ const NextCursor = z
|
|
|
940
1025
|
*/
|
|
941
1026
|
export const PaymentsAdminPurchaseView = z
|
|
942
1027
|
.object({
|
|
1028
|
+
quantity: z
|
|
1029
|
+
.number()
|
|
1030
|
+
.int()
|
|
1031
|
+
.positive()
|
|
1032
|
+
.nullable()
|
|
1033
|
+
.optional()
|
|
1034
|
+
.describe(
|
|
1035
|
+
"How many were bought, as the store stated it, or null where it did not. Absent from a Worker that predates the column.",
|
|
1036
|
+
),
|
|
1037
|
+
reportedQuantity: z
|
|
1038
|
+
.number()
|
|
1039
|
+
.int()
|
|
1040
|
+
.nonnegative()
|
|
1041
|
+
.nullable()
|
|
1042
|
+
.optional()
|
|
1043
|
+
.describe(
|
|
1044
|
+
"For a quantity-billed subscription, the last count reported to the store, or null when none has been. Absent from a Worker that predates reported billing.",
|
|
1045
|
+
),
|
|
1046
|
+
reportedAt: z.iso
|
|
1047
|
+
.datetime()
|
|
1048
|
+
.nullable()
|
|
1049
|
+
.optional()
|
|
1050
|
+
.describe(
|
|
1051
|
+
"When that count was reported, ISO-8601, or null. Absent from a Worker that predates reported billing.",
|
|
1052
|
+
),
|
|
943
1053
|
id: z.string().describe("The purchase's UUID — its stable identifier on this Worker."),
|
|
944
1054
|
subjectType: PaymentsSubject.shape.subjectType.describe(
|
|
945
1055
|
"Whether `subjectId` names a user or an organization. Half the owner: read the two together or a row is attributed to whoever else holds that id.",
|
|
@@ -1029,10 +1139,136 @@ export const PaymentsAdminEntitlementView = z
|
|
|
1029
1139
|
.describe(
|
|
1030
1140
|
"The purchase currently granting this entitlement, or null when nothing does — a comp, or a grant whose purchase has lapsed.",
|
|
1031
1141
|
),
|
|
1142
|
+
unrestricted: z
|
|
1143
|
+
.boolean()
|
|
1144
|
+
.optional()
|
|
1145
|
+
.describe(
|
|
1146
|
+
"Whether this row's subject is `unrestricted` — every quota unlimited and every feature on, whatever it holds. On every row, because a privilege this large must not be inferable only from a row nobody opens. Absent from a Worker that predates overrides.",
|
|
1147
|
+
),
|
|
1032
1148
|
})
|
|
1033
1149
|
.describe("One entitlement as a management client sees it: whose it is, whether it grants, and why.");
|
|
1034
1150
|
export type PaymentsAdminEntitlementView = z.output<typeof PaymentsAdminEntitlementView>;
|
|
1035
1151
|
|
|
1152
|
+
/** Where an allowance's value came from. */
|
|
1153
|
+
export const PaymentsAllowanceSource = z
|
|
1154
|
+
.enum(["unrestricted", "override", "plan", "default", "none"])
|
|
1155
|
+
.describe(
|
|
1156
|
+
"Where the value came from: the subject's `unrestricted` override, a pin on its override, a key it holds (`key` names it), the free floor, or `none` — nothing declared spoke to it, so it is 0 or false.",
|
|
1157
|
+
);
|
|
1158
|
+
export type PaymentsAllowanceSource = z.output<typeof PaymentsAllowanceSource>;
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* One quota for one subject: what applies now, where it came from, and what it would be with the override
|
|
1162
|
+
* removed. **Three facts, because a pane that lets an operator pin one field needs all three** — projecting only
|
|
1163
|
+
* the effective value loses the plan's number the instant an override exists, and the pane can no longer draw
|
|
1164
|
+
* the row it is editing or offer to revert it.
|
|
1165
|
+
*/
|
|
1166
|
+
export const PaymentsAdminQuotaView = z
|
|
1167
|
+
.object({
|
|
1168
|
+
name: z.string().describe("The quota name."),
|
|
1169
|
+
effective: WireQuota.describe("What applies now. A whole number, or null for unlimited."),
|
|
1170
|
+
source: PaymentsAllowanceSource,
|
|
1171
|
+
key: z.string().nullable().describe("The entitlement key that supplied `effective`, when `source` is `plan`."),
|
|
1172
|
+
inherited: WireQuota.describe(
|
|
1173
|
+
"What it would be with the override removed — the plan's own number, to show beside a pin and to revert to.",
|
|
1174
|
+
),
|
|
1175
|
+
inheritedSource: PaymentsAllowanceSource.describe("Where `inherited` came from."),
|
|
1176
|
+
inheritedKey: z.string().nullable().describe("The key that supplied `inherited`, when it is a plan's."),
|
|
1177
|
+
overrideMax: z
|
|
1178
|
+
.number()
|
|
1179
|
+
.int()
|
|
1180
|
+
.nonnegative()
|
|
1181
|
+
.nullable()
|
|
1182
|
+
.describe("The largest number an override may set here for this subject, or null for no ceiling."),
|
|
1183
|
+
})
|
|
1184
|
+
.describe("One quota for one subject: effective, provenance, and inherited.");
|
|
1185
|
+
export type PaymentsAdminQuotaView = z.output<typeof PaymentsAdminQuotaView>;
|
|
1186
|
+
|
|
1187
|
+
/** One feature for one subject, the same three facts. */
|
|
1188
|
+
export const PaymentsAdminFeatureView = z
|
|
1189
|
+
.object({
|
|
1190
|
+
name: z.string().describe("The feature name."),
|
|
1191
|
+
effective: z.boolean().describe("Whether it is on now."),
|
|
1192
|
+
source: PaymentsAllowanceSource,
|
|
1193
|
+
key: z.string().nullable().describe("The entitlement key that supplied `effective`, when `source` is `plan`."),
|
|
1194
|
+
inherited: z.boolean().describe("Whether it would be on with the override removed."),
|
|
1195
|
+
inheritedSource: PaymentsAllowanceSource.describe("Where `inherited` came from."),
|
|
1196
|
+
inheritedKey: z.string().nullable().describe("The key that supplied `inherited`, when it is a plan's."),
|
|
1197
|
+
})
|
|
1198
|
+
.describe("One feature for one subject: effective, provenance, and inherited.");
|
|
1199
|
+
export type PaymentsAdminFeatureView = z.output<typeof PaymentsAdminFeatureView>;
|
|
1200
|
+
|
|
1201
|
+
/** Every declared allowance for one subject. */
|
|
1202
|
+
export const PaymentsAdminAllowancesView = z
|
|
1203
|
+
.object({
|
|
1204
|
+
quotas: z.array(PaymentsAdminQuotaView).describe("Every declared quota, by name."),
|
|
1205
|
+
features: z.array(PaymentsAdminFeatureView).describe("Every declared feature, by name."),
|
|
1206
|
+
})
|
|
1207
|
+
.describe("Every declared allowance for one subject, resolved now.");
|
|
1208
|
+
export type PaymentsAdminAllowancesView = z.output<typeof PaymentsAdminAllowancesView>;
|
|
1209
|
+
|
|
1210
|
+
/** One subject's override row, as a management client sees it. */
|
|
1211
|
+
export const PaymentsAdminOverrideView = z
|
|
1212
|
+
.object({
|
|
1213
|
+
version: z
|
|
1214
|
+
.number()
|
|
1215
|
+
.int()
|
|
1216
|
+
.positive()
|
|
1217
|
+
.describe("The version a set must send back. A set naming an older one is refused as stale."),
|
|
1218
|
+
unrestricted: z
|
|
1219
|
+
.boolean()
|
|
1220
|
+
.describe(
|
|
1221
|
+
"Whether every quota is unlimited and every feature on, except the pins, for every name present and future.",
|
|
1222
|
+
),
|
|
1223
|
+
quotas: z.record(z.string(), WireQuota).describe("The pinned quotas."),
|
|
1224
|
+
features: z.record(z.string(), z.boolean().describe("Whether the switch is on.")).describe("The pinned features."),
|
|
1225
|
+
reason: z.string().describe("The reason the last write gave."),
|
|
1226
|
+
updatedAt: z.iso.datetime().describe("When it last changed, ISO-8601."),
|
|
1227
|
+
})
|
|
1228
|
+
.describe("One subject's override: its version, its mode, its pins, and why.");
|
|
1229
|
+
export type PaymentsAdminOverrideView = z.output<typeof PaymentsAdminOverrideView>;
|
|
1230
|
+
|
|
1231
|
+
/** One subject's override in the listing: whose it is, and the override. */
|
|
1232
|
+
export const PaymentsAdminOverrideListItem = z
|
|
1233
|
+
.object({
|
|
1234
|
+
subjectType: PaymentsSubject.shape.subjectType.describe("Whether `subjectId` names a user or an organization."),
|
|
1235
|
+
subjectId: PaymentsSubject.shape.subjectId.describe("The subject the override shades."),
|
|
1236
|
+
override: PaymentsAdminOverrideView,
|
|
1237
|
+
})
|
|
1238
|
+
.describe("One subject's override, as the listing pages it.");
|
|
1239
|
+
export type PaymentsAdminOverrideListItem = z.output<typeof PaymentsAdminOverrideListItem>;
|
|
1240
|
+
|
|
1241
|
+
/** `GET {base}/admin/overrides`. */
|
|
1242
|
+
export const PaymentsAdminOverridesResponse = z
|
|
1243
|
+
.object({
|
|
1244
|
+
overrides: z.array(PaymentsAdminOverrideListItem).describe("The page, most recently changed first."),
|
|
1245
|
+
nextCursor: z
|
|
1246
|
+
.string()
|
|
1247
|
+
.nullable()
|
|
1248
|
+
.describe("Where the next page resumes. Null at the end of the list. Opaque — pass it back verbatim."),
|
|
1249
|
+
})
|
|
1250
|
+
.describe("A page of every subject's override — the negotiated numbers, and who is unrestricted.");
|
|
1251
|
+
export type PaymentsAdminOverridesResponse = z.output<typeof PaymentsAdminOverridesResponse>;
|
|
1252
|
+
|
|
1253
|
+
/** What every override write answers: the subject, and its override as it now stands. */
|
|
1254
|
+
export const PaymentsOverrideResponse = z
|
|
1255
|
+
.object({
|
|
1256
|
+
subjectType: PaymentsSubject.shape.subjectType.describe("Which kind of holder, echoed."),
|
|
1257
|
+
subjectId: PaymentsSubject.shape.subjectId.describe("The subject, echoed."),
|
|
1258
|
+
override: PaymentsAdminOverrideView.nullable().describe(
|
|
1259
|
+
"The override after the write, or null when the subject now has none — a whole clear, or a clear of nothing.",
|
|
1260
|
+
),
|
|
1261
|
+
version: z
|
|
1262
|
+
.number()
|
|
1263
|
+
.int()
|
|
1264
|
+
.nonnegative()
|
|
1265
|
+
.describe(
|
|
1266
|
+
"The version the next write must name. 0 when the subject has never had an override; a cleared one keeps its version, so a stale writer stays stale.",
|
|
1267
|
+
),
|
|
1268
|
+
})
|
|
1269
|
+
.describe("An override write's result: the subject, its override now, and the version to write against next.");
|
|
1270
|
+
export type PaymentsOverrideResponse = z.output<typeof PaymentsOverrideResponse>;
|
|
1271
|
+
|
|
1036
1272
|
/**
|
|
1037
1273
|
* One reconciliation pass, as a management client sees it.
|
|
1038
1274
|
*
|
|
@@ -1119,6 +1355,53 @@ export const PaymentsAdminReconcileRunStarted = z
|
|
|
1119
1355
|
.describe("What a press on the reconciliation trigger produced: whether a pass began, and which one.");
|
|
1120
1356
|
export type PaymentsAdminReconcileRunStarted = z.output<typeof PaymentsAdminReconcileRunStarted>;
|
|
1121
1357
|
|
|
1358
|
+
/** One subject a usage run did not report, and why. */
|
|
1359
|
+
export const PaymentsAdminUsageFindingView = z
|
|
1360
|
+
.object({
|
|
1361
|
+
subjectType: PaymentsSubject.shape.subjectType.describe("Whether `subjectId` names a user or an organization."),
|
|
1362
|
+
subjectId: PaymentsSubject.shape.subjectId.describe("The subject."),
|
|
1363
|
+
productId: z.string().describe("The product whose count was not reported."),
|
|
1364
|
+
reason: z
|
|
1365
|
+
.enum(["unanswered", "not_integer", "negative", "below_min", "above_max", "resolver_failed", "report_failed"])
|
|
1366
|
+
.describe(
|
|
1367
|
+
"Why: the resolver answered nothing, a non-integer, a negative, a count outside min or max, or threw — or the store refused the report.",
|
|
1368
|
+
),
|
|
1369
|
+
})
|
|
1370
|
+
.describe("One subject a usage run did not report.");
|
|
1371
|
+
export type PaymentsAdminUsageFindingView = z.output<typeof PaymentsAdminUsageFindingView>;
|
|
1372
|
+
|
|
1373
|
+
/** One usage-reporting pass, as a management client sees it. */
|
|
1374
|
+
export const PaymentsAdminUsageRunView = z
|
|
1375
|
+
.object({
|
|
1376
|
+
id: z.string().describe("The run's id."),
|
|
1377
|
+
startedAt: z.iso.datetime().describe("When the pass began, ISO-8601."),
|
|
1378
|
+
finishedAt: z.iso.datetime().describe("When it finished, ISO-8601."),
|
|
1379
|
+
scanned: z.number().int().describe("Subscriptions examined."),
|
|
1380
|
+
reported: z.number().int().describe("Periods a store accepted."),
|
|
1381
|
+
sampled: z.number().int().describe("Daily-peak samples taken for a day still open."),
|
|
1382
|
+
alreadyReported: z.number().int().describe("Periods already reported, so nothing was sent."),
|
|
1383
|
+
skipped: z.number().int().describe("Subjects whose resolver answered nothing. Never reported as zero."),
|
|
1384
|
+
invalid: z
|
|
1385
|
+
.number()
|
|
1386
|
+
.int()
|
|
1387
|
+
.describe("Subjects whose resolver answered a number that may not be billed. Never clamped."),
|
|
1388
|
+
failed: z.number().int().describe("Subjects whose resolver threw, or whose report a store refused."),
|
|
1389
|
+
findings: z
|
|
1390
|
+
.array(PaymentsAdminUsageFindingView)
|
|
1391
|
+
.describe("The subjects not reported and why, up to a hundred. The counts are whole either way."),
|
|
1392
|
+
})
|
|
1393
|
+
.describe("One usage-reporting pass: when it ran, its tally, and who it did not report.");
|
|
1394
|
+
export type PaymentsAdminUsageRunView = z.output<typeof PaymentsAdminUsageRunView>;
|
|
1395
|
+
|
|
1396
|
+
/** `GET {base}/admin/usage-runs`. */
|
|
1397
|
+
export const PaymentsAdminUsageRunsResponse = z
|
|
1398
|
+
.object({
|
|
1399
|
+
runs: z.array(PaymentsAdminUsageRunView).describe("The page, most recently started first."),
|
|
1400
|
+
nextCursor: NextCursor,
|
|
1401
|
+
})
|
|
1402
|
+
.describe("A page of the usage-reporting run log.");
|
|
1403
|
+
export type PaymentsAdminUsageRunsResponse = z.output<typeof PaymentsAdminUsageRunsResponse>;
|
|
1404
|
+
|
|
1122
1405
|
/** `GET {base}/admin/purchases`. */
|
|
1123
1406
|
export const PaymentsAdminPurchasesResponse = z
|
|
1124
1407
|
.object({
|
|
@@ -1169,6 +1452,24 @@ export const PaymentsAdminSubjectEntitlementsResponse = z
|
|
|
1169
1452
|
entitlements: z
|
|
1170
1453
|
.array(PaymentsAdminEntitlementView)
|
|
1171
1454
|
.describe("Every entitlement this subject holds, by key. Empty when it holds none."),
|
|
1455
|
+
unrestricted: z
|
|
1456
|
+
.boolean()
|
|
1457
|
+
.optional()
|
|
1458
|
+
.describe("Whether the subject is `unrestricted`. Absent from a Worker that predates overrides."),
|
|
1459
|
+
overrideVersion: z
|
|
1460
|
+
.number()
|
|
1461
|
+
.int()
|
|
1462
|
+
.nonnegative()
|
|
1463
|
+
.optional()
|
|
1464
|
+
.describe(
|
|
1465
|
+
"The version an override write for this subject must name — 0 when it has none. Absent from a Worker that predates overrides.",
|
|
1466
|
+
),
|
|
1467
|
+
override: PaymentsAdminOverrideView.nullable()
|
|
1468
|
+
.optional()
|
|
1469
|
+
.describe("The subject's override, or null when it has none. Absent from a Worker that predates overrides."),
|
|
1470
|
+
allowances: PaymentsAdminAllowancesView.optional().describe(
|
|
1471
|
+
"Every declared quota and feature, resolved for this subject now — effective, provenance, inherited. Absent from a Worker that predates declarations.",
|
|
1472
|
+
),
|
|
1172
1473
|
})
|
|
1173
1474
|
.describe("One subject's entitlements, resolved now.");
|
|
1174
1475
|
export type PaymentsAdminSubjectEntitlementsResponse = z.output<typeof PaymentsAdminSubjectEntitlementsResponse>;
|