@fantastic.dev/better-stripe 0.50.3 → 0.51.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/CHANGELOG.md +19 -0
- package/README.md +5 -1
- package/dist/client/usage/boundaries.d.ts +132 -0
- package/dist/client/usage/boundaries.d.ts.map +1 -0
- package/dist/client/usage/boundaries.js +43 -0
- package/dist/client/usage/boundaries.js.map +1 -0
- package/dist/client/usage/contracts.d.ts +59 -0
- package/dist/client/usage/contracts.d.ts.map +1 -0
- package/dist/client/usage/contracts.js +63 -0
- package/dist/client/usage/contracts.js.map +1 -0
- package/dist/client/usage/index.d.ts +7 -0
- package/dist/client/usage/index.d.ts.map +1 -0
- package/dist/client/usage/index.js +4 -0
- package/dist/client/usage/index.js.map +1 -0
- package/dist/client/usage/records.d.ts +50 -0
- package/dist/client/usage/records.d.ts.map +1 -0
- package/dist/client/usage/records.js +54 -0
- package/dist/client/usage/records.js.map +1 -0
- package/docs/README.md +5 -0
- package/docs/development.md +26 -8
- package/docs/metered-usage.md +289 -37
- package/docs/metering-setup.md +183 -0
- package/package.json +6 -1
- package/src/client/transferContinuation.test.ts +2 -6
- package/src/client/usage/boundaries.test.ts +136 -0
- package/src/client/usage/boundaries.ts +182 -0
- package/src/client/usage/contracts.test.ts +145 -0
- package/src/client/usage/contracts.ts +79 -0
- package/src/client/usage/index.ts +34 -0
- package/src/client/usage/records.ts +76 -0
package/CHANGELOG.md
CHANGED
|
@@ -26,6 +26,25 @@
|
|
|
26
26
|
- Remove internal tracker references from public documentation and add a
|
|
27
27
|
regression check that prevents their reintroduction.
|
|
28
28
|
|
|
29
|
+
## [0.51.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.3...v0.51.0) (2026-10-18)
|
|
30
|
+
|
|
31
|
+
### Features
|
|
32
|
+
|
|
33
|
+
- complete scoped usage API and host authorization contracts ([41d58ac](https://github.com/FantasticDevHQ/better-stripe/commit/41d58ac99ff63c89c17143dde5e59de04ee2c80d))
|
|
34
|
+
|
|
35
|
+
### Documentation
|
|
36
|
+
|
|
37
|
+
- align metering status and index with native sandbox evidence ([d1c1bf5](https://github.com/FantasticDevHQ/better-stripe/commit/d1c1bf57893c6045c91a8c9103ea02103c871ed9))
|
|
38
|
+
|
|
39
|
+
### Continuous Integration
|
|
40
|
+
|
|
41
|
+
- batch coverage floor increases in weekly PRs ([d648b82](https://github.com/FantasticDevHQ/better-stripe/commit/d648b82f6c910b16c6349096a2022c798777f608))
|
|
42
|
+
- batch coverage floor increases in weekly PRs ([8217f1f](https://github.com/FantasticDevHQ/better-stripe/commit/8217f1fe9e1bdac5c730d98cc1022ea7cd1c385c))
|
|
43
|
+
|
|
44
|
+
### Tests
|
|
45
|
+
|
|
46
|
+
- ratchet native usage contract coverage floors ([5c8ff1b](https://github.com/FantasticDevHQ/better-stripe/commit/5c8ff1b31913a08db9493cc5a0219601ad540608))
|
|
47
|
+
|
|
29
48
|
## [0.50.3](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.2...v0.50.3) (2026-10-18)
|
|
30
49
|
|
|
31
50
|
### Documentation
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ billing, and Connect marketplaces. It provides checkout, subscriptions, webhook
|
|
|
5
5
|
syncing, marketplace fees and splits, payouts, refunds, and disputes, with React
|
|
6
6
|
hooks and headless UI components.
|
|
7
7
|
|
|
8
|
-
**Version**: `0.
|
|
8
|
+
**Version**: `0.51.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
|
|
9
9
|
|
|
10
10
|
Connect platforms use the default GA API version. Non-Connect merchants using
|
|
11
11
|
customer-only Accounts v2 need preview access and an explicit preview version.
|
|
@@ -126,3 +126,7 @@ for publishing. Run `pnpm run check:all` before submitting changes.
|
|
|
126
126
|
## License
|
|
127
127
|
|
|
128
128
|
MIT
|
|
129
|
+
|
|
130
|
+
## Metered usage
|
|
131
|
+
|
|
132
|
+
Native Stripe integration supports shared configuration and exact quantity helpers at `@fantastic.dev/better-stripe/usage`. See the [setup guide for developers and AI agents](docs/metering-setup.md) and [contracts and sandbox evidence](docs/metered-usage.md). Operational billing APIs are still under development.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import type { PreparedUsageRecord, UsageScope } from "./records.js";
|
|
2
|
+
export type UsagePeriod = {
|
|
3
|
+
start: number;
|
|
4
|
+
end: number;
|
|
5
|
+
};
|
|
6
|
+
export type UsagePageRequest = {
|
|
7
|
+
period: UsagePeriod;
|
|
8
|
+
limit: number;
|
|
9
|
+
cursor: string | null;
|
|
10
|
+
};
|
|
11
|
+
export type UsageAvailability<T> = {
|
|
12
|
+
status: "available";
|
|
13
|
+
value: T;
|
|
14
|
+
observedAt: number;
|
|
15
|
+
} | {
|
|
16
|
+
status: "unavailable" | "unsupported";
|
|
17
|
+
reason: string;
|
|
18
|
+
retryable: boolean;
|
|
19
|
+
};
|
|
20
|
+
export type UsageAuthorization<Context> = {
|
|
21
|
+
/** Throw on denial. Resolve identity and tenant ownership in the host. */
|
|
22
|
+
authorize(ctx: Context, request: {
|
|
23
|
+
scope: UsageScope;
|
|
24
|
+
operation: "record" | "read" | "reconcile" | "correct" | "configure";
|
|
25
|
+
}): Promise<void>;
|
|
26
|
+
/** Throw when the server-verified activity is not billable. */
|
|
27
|
+
authorizeActivity(ctx: Context, record: PreparedUsageRecord): Promise<void>;
|
|
28
|
+
};
|
|
29
|
+
/** Independent observations; none is inferred from another field. */
|
|
30
|
+
export type UsageObservations = {
|
|
31
|
+
localAcceptedQuantity: string;
|
|
32
|
+
providerAcceptedQuantity: string;
|
|
33
|
+
aggregate: UsageAvailability<{
|
|
34
|
+
quantity: string;
|
|
35
|
+
complete: boolean;
|
|
36
|
+
}>;
|
|
37
|
+
estimate: UsageAvailability<{
|
|
38
|
+
amountDecimal: string;
|
|
39
|
+
currency: string;
|
|
40
|
+
}>;
|
|
41
|
+
invoice: UsageAvailability<{
|
|
42
|
+
invoiceId: string;
|
|
43
|
+
status: "draft" | "open" | "paid" | "void" | "uncollectible";
|
|
44
|
+
amount: string;
|
|
45
|
+
currency: string;
|
|
46
|
+
}>;
|
|
47
|
+
};
|
|
48
|
+
export type UsageCorrectionRequest = {
|
|
49
|
+
scope: UsageScope;
|
|
50
|
+
sourceEventId: string;
|
|
51
|
+
correctionId: string;
|
|
52
|
+
reason: string;
|
|
53
|
+
/** Cancellation preserves the original event. Replacement is a new event. */
|
|
54
|
+
operation: "cancel";
|
|
55
|
+
};
|
|
56
|
+
export type UsageRetentionPolicy = {
|
|
57
|
+
/** Financial evidence has no automatic deletion path. */
|
|
58
|
+
financialEvidence: "retain";
|
|
59
|
+
/** Execution payload cleanup must never erase event/payment/correction history. */
|
|
60
|
+
executionJournalDays: number;
|
|
61
|
+
};
|
|
62
|
+
export type UsageTransitionRequest = {
|
|
63
|
+
scope: UsageScope;
|
|
64
|
+
fromVersion: string;
|
|
65
|
+
toVersion: string;
|
|
66
|
+
effectiveAt: number;
|
|
67
|
+
pendingUsage: "drain_before_transition";
|
|
68
|
+
reservations: "resolve_before_transition";
|
|
69
|
+
existingCredits: "retain_original_terms";
|
|
70
|
+
};
|
|
71
|
+
export type UsageSubscriptionBinding = {
|
|
72
|
+
subscriptionId: string;
|
|
73
|
+
subscriptionItemId: string;
|
|
74
|
+
stripePriceId: string;
|
|
75
|
+
period: UsagePeriod;
|
|
76
|
+
interval: "month";
|
|
77
|
+
};
|
|
78
|
+
export type UsageCreditProvenance = {
|
|
79
|
+
grantId: string;
|
|
80
|
+
purchasePaymentIntentId: string;
|
|
81
|
+
currency: string;
|
|
82
|
+
originalAmount: string;
|
|
83
|
+
/** Quantity projections retain their original plan version and unit. */
|
|
84
|
+
planVersion: string;
|
|
85
|
+
reservationId: string;
|
|
86
|
+
scaledQuantity: string;
|
|
87
|
+
};
|
|
88
|
+
export type UsageCorrectionOutcome = {
|
|
89
|
+
correctionId: string;
|
|
90
|
+
sourceEventId: string;
|
|
91
|
+
state: "requested" | "provider_accepted" | "confirmed" | "held" | "unsupported" | "invoice_adjustment_required";
|
|
92
|
+
providerAdjustmentId: string | null;
|
|
93
|
+
reason: string;
|
|
94
|
+
};
|
|
95
|
+
export type UsageReceipt = {
|
|
96
|
+
eventId: string;
|
|
97
|
+
identity: string;
|
|
98
|
+
acceptedAt: number;
|
|
99
|
+
delivery: import("./records.js").UsageDeliveryState;
|
|
100
|
+
};
|
|
101
|
+
export type UsageHistoryPage = {
|
|
102
|
+
events: Array<{
|
|
103
|
+
receipt: UsageReceipt;
|
|
104
|
+
record: PreparedUsageRecord;
|
|
105
|
+
}>;
|
|
106
|
+
cursor: string | null;
|
|
107
|
+
isDone: boolean;
|
|
108
|
+
};
|
|
109
|
+
export type UsageProviderCapabilities = {
|
|
110
|
+
aggregation: "sum";
|
|
111
|
+
scaledIntegerQuantities: true;
|
|
112
|
+
realTimeBalance: false;
|
|
113
|
+
eventCancellation: "provider_window";
|
|
114
|
+
invoiceFinalization: "asynchronous";
|
|
115
|
+
};
|
|
116
|
+
/** Contract for host adapters; this interface does not supply a billing engine. */
|
|
117
|
+
export interface UsageContractPort {
|
|
118
|
+
record(record: PreparedUsageRecord): Promise<UsageReceipt>;
|
|
119
|
+
read(request: {
|
|
120
|
+
scope: UsageScope;
|
|
121
|
+
page: UsagePageRequest;
|
|
122
|
+
}): Promise<UsageHistoryPage>;
|
|
123
|
+
reconcile(request: {
|
|
124
|
+
scope: UsageScope;
|
|
125
|
+
period: UsagePeriod;
|
|
126
|
+
}): Promise<UsageAvailability<UsageObservations>>;
|
|
127
|
+
capabilities(scope: UsageScope): Promise<UsageAvailability<UsageProviderCapabilities>>;
|
|
128
|
+
}
|
|
129
|
+
export declare function validateUsagePageRequest(input: unknown): UsagePageRequest;
|
|
130
|
+
export declare function assertUsageReplay(original: PreparedUsageRecord, candidate: PreparedUsageRecord): void;
|
|
131
|
+
export declare function authorizeUsageRecord<Context, Result>(ctx: Context, policy: UsageAuthorization<Context>, input: unknown, accept: (record: PreparedUsageRecord) => Promise<Result>): Promise<Result>;
|
|
132
|
+
//# sourceMappingURL=boundaries.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"boundaries.d.ts","sourceRoot":"","sources":["../../../src/client/usage/boundaries.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { prepareUsageRecord } from "./records.js";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { defineUsagePlan } from "./contracts.js";
|
|
4
|
+
const seconds = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
|
|
5
|
+
const pageSchema = z.strictObject({
|
|
6
|
+
period: z.strictObject({ start: seconds, end: seconds }),
|
|
7
|
+
limit: z.number().int().min(1).max(100),
|
|
8
|
+
cursor: z.string().min(1).max(2048).nullable(),
|
|
9
|
+
});
|
|
10
|
+
export function validateUsagePageRequest(input) {
|
|
11
|
+
const request = pageSchema.parse(input);
|
|
12
|
+
if (request.period.end <= request.period.start)
|
|
13
|
+
throw new Error("Usage period must have a positive duration");
|
|
14
|
+
return request;
|
|
15
|
+
}
|
|
16
|
+
export function assertUsageReplay(original, candidate) {
|
|
17
|
+
const signature = (record) => JSON.stringify([
|
|
18
|
+
record.schemaVersion,
|
|
19
|
+
record.identity,
|
|
20
|
+
record.sourceEventId,
|
|
21
|
+
record.scope.livemode,
|
|
22
|
+
record.scope.stripeAccountId,
|
|
23
|
+
record.scope.customerAccount,
|
|
24
|
+
record.scope.meterId,
|
|
25
|
+
record.quantity,
|
|
26
|
+
record.scaledQuantity,
|
|
27
|
+
record.occurredAt,
|
|
28
|
+
record.binding.stripeCustomerId,
|
|
29
|
+
record.binding.stripePriceId,
|
|
30
|
+
record.binding.eventName,
|
|
31
|
+
record.binding.apiVersion,
|
|
32
|
+
defineUsagePlan(record.binding.plan),
|
|
33
|
+
]);
|
|
34
|
+
if (signature(original) !== signature(candidate))
|
|
35
|
+
throw new Error("Conflicting usage replay");
|
|
36
|
+
}
|
|
37
|
+
export async function authorizeUsageRecord(ctx, policy, input, accept) {
|
|
38
|
+
const record = prepareUsageRecord(input);
|
|
39
|
+
await policy.authorize(ctx, { scope: record.scope, operation: "record" });
|
|
40
|
+
await policy.authorizeActivity(ctx, record);
|
|
41
|
+
return accept(record);
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=boundaries.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"boundaries.js","sourceRoot":"","sources":["../../../src/client/usage/boundaries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAgIjD,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAC5E,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAEH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK;QAC5C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,QAA6B,EAC7B,SAA8B;IAE9B,MAAM,SAAS,GAAG,CAAC,MAA2B,EAAE,EAAE,CAChD,IAAI,CAAC,SAAS,CAAC;QACb,MAAM,CAAC,aAAa;QACpB,MAAM,CAAC,QAAQ;QACf,MAAM,CAAC,aAAa;QACpB,MAAM,CAAC,KAAK,CAAC,QAAQ;QACrB,MAAM,CAAC,KAAK,CAAC,eAAe;QAC5B,MAAM,CAAC,KAAK,CAAC,eAAe;QAC5B,MAAM,CAAC,KAAK,CAAC,OAAO;QACpB,MAAM,CAAC,QAAQ;QACf,MAAM,CAAC,cAAc;QACrB,MAAM,CAAC,UAAU;QACjB,MAAM,CAAC,OAAO,CAAC,gBAAgB;QAC/B,MAAM,CAAC,OAAO,CAAC,aAAa;QAC5B,MAAM,CAAC,OAAO,CAAC,SAAS;QACxB,MAAM,CAAC,OAAO,CAAC,UAAU;QACzB,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;KACrC,CAAC,CAAC;IACL,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC,SAAS,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAY,EACZ,MAAmC,EACnC,KAAc,EACd,MAAwD;IAExD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1E,MAAM,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
declare const planSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
|
|
3
|
+
key: z.ZodString;
|
|
4
|
+
version: z.ZodString;
|
|
5
|
+
unit: z.ZodObject<{
|
|
6
|
+
name: z.ZodString;
|
|
7
|
+
precision: z.ZodNumber;
|
|
8
|
+
}, z.core.$strict>;
|
|
9
|
+
rate: z.ZodObject<{
|
|
10
|
+
currency: z.ZodString;
|
|
11
|
+
unitAmountDecimal: z.ZodString;
|
|
12
|
+
}, z.core.$strict>;
|
|
13
|
+
model: z.ZodLiteral<"pay_as_you_go">;
|
|
14
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
15
|
+
key: z.ZodString;
|
|
16
|
+
version: z.ZodString;
|
|
17
|
+
unit: z.ZodObject<{
|
|
18
|
+
name: z.ZodString;
|
|
19
|
+
precision: z.ZodNumber;
|
|
20
|
+
}, z.core.$strict>;
|
|
21
|
+
rate: z.ZodObject<{
|
|
22
|
+
currency: z.ZodString;
|
|
23
|
+
unitAmountDecimal: z.ZodString;
|
|
24
|
+
}, z.core.$strict>;
|
|
25
|
+
model: z.ZodLiteral<"included_overage">;
|
|
26
|
+
includedQuantity: z.ZodString;
|
|
27
|
+
reset: z.ZodLiteral<"billing_period">;
|
|
28
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
29
|
+
key: z.ZodString;
|
|
30
|
+
version: z.ZodString;
|
|
31
|
+
unit: z.ZodObject<{
|
|
32
|
+
name: z.ZodString;
|
|
33
|
+
precision: z.ZodNumber;
|
|
34
|
+
}, z.core.$strict>;
|
|
35
|
+
rate: z.ZodObject<{
|
|
36
|
+
currency: z.ZodString;
|
|
37
|
+
unitAmountDecimal: z.ZodString;
|
|
38
|
+
}, z.core.$strict>;
|
|
39
|
+
model: z.ZodLiteral<"prepaid">;
|
|
40
|
+
insufficientBalance: z.ZodLiteral<"reject">;
|
|
41
|
+
}, z.core.$strict>], "model">;
|
|
42
|
+
/** Configuration contracts only. Validating a plan does not enable billing. */
|
|
43
|
+
export type UsagePlan = z.infer<typeof planSchema>;
|
|
44
|
+
export type UsageBillingModel = UsagePlan["model"];
|
|
45
|
+
export type ExactUsageQuantity = {
|
|
46
|
+
quantity: string;
|
|
47
|
+
scaledQuantity: string;
|
|
48
|
+
precision: number;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Parse a nonnegative decimal quantity without rounding. The shared contract
|
|
52
|
+
* supports 0–6 decimal places and at most 18 scaled digits. A provider adapter
|
|
53
|
+
* must additionally enforce its own supported bounds before accepting usage.
|
|
54
|
+
*/
|
|
55
|
+
export declare function parseUsageQuantity(value: unknown, precision: number): ExactUsageQuantity;
|
|
56
|
+
/** Validate and copy terms; provider provisioning and host authorization are separate. */
|
|
57
|
+
export declare function defineUsagePlan(input: unknown): UsagePlan;
|
|
58
|
+
export {};
|
|
59
|
+
//# sourceMappingURL=contracts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/client/usage/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAad,CAAC;AAEH,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AACnD,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAqBpB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAKzD"}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
const unit = z.strictObject({
|
|
3
|
+
name: z.string().min(1).max(100),
|
|
4
|
+
precision: z.number().int().min(0).max(6),
|
|
5
|
+
});
|
|
6
|
+
const rate = z.strictObject({
|
|
7
|
+
currency: z.string().regex(/^[a-z]{3}$/),
|
|
8
|
+
// Decimal minor currency units per whole billable unit, never a JS float.
|
|
9
|
+
unitAmountDecimal: z.string().regex(/^(0|[1-9]\d{0,11})(\.\d{1,12})?$/),
|
|
10
|
+
});
|
|
11
|
+
const common = {
|
|
12
|
+
key: z.string().min(1).max(100),
|
|
13
|
+
version: z.string().min(1).max(100),
|
|
14
|
+
unit,
|
|
15
|
+
rate,
|
|
16
|
+
};
|
|
17
|
+
const planSchema = z.discriminatedUnion("model", [
|
|
18
|
+
z.strictObject({ ...common, model: z.literal("pay_as_you_go") }),
|
|
19
|
+
z.strictObject({
|
|
20
|
+
...common,
|
|
21
|
+
model: z.literal("included_overage"),
|
|
22
|
+
includedQuantity: z.string(),
|
|
23
|
+
reset: z.literal("billing_period"),
|
|
24
|
+
}),
|
|
25
|
+
z.strictObject({
|
|
26
|
+
...common,
|
|
27
|
+
model: z.literal("prepaid"),
|
|
28
|
+
insufficientBalance: z.literal("reject"),
|
|
29
|
+
}),
|
|
30
|
+
]);
|
|
31
|
+
/**
|
|
32
|
+
* Parse a nonnegative decimal quantity without rounding. The shared contract
|
|
33
|
+
* supports 0–6 decimal places and at most 18 scaled digits. A provider adapter
|
|
34
|
+
* must additionally enforce its own supported bounds before accepting usage.
|
|
35
|
+
*/
|
|
36
|
+
export function parseUsageQuantity(value, precision) {
|
|
37
|
+
if (!Number.isInteger(precision) || precision < 0 || precision > 6)
|
|
38
|
+
throw new Error("Usage precision must be an integer between 0 and 6");
|
|
39
|
+
if (typeof value !== "string" ||
|
|
40
|
+
value.length > 25 ||
|
|
41
|
+
!/^(0|[1-9]\d*)(\.\d+)?$/.test(value))
|
|
42
|
+
throw new Error("Usage quantity must be a nonnegative decimal string");
|
|
43
|
+
const [whole, fraction = ""] = value.split(".");
|
|
44
|
+
if (fraction.length > precision)
|
|
45
|
+
throw new Error("Usage quantity exceeds configured precision");
|
|
46
|
+
const scaled = BigInt(whole + fraction.padEnd(precision, "0"));
|
|
47
|
+
if (scaled > 999999999999999999n)
|
|
48
|
+
throw new Error("Usage quantity exceeds the shared scaled bound");
|
|
49
|
+
const normalizedFraction = fraction.replace(/0+$/, "");
|
|
50
|
+
return {
|
|
51
|
+
quantity: normalizedFraction ? `${whole}.${normalizedFraction}` : whole,
|
|
52
|
+
scaledQuantity: scaled.toString(),
|
|
53
|
+
precision,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
/** Validate and copy terms; provider provisioning and host authorization are separate. */
|
|
57
|
+
export function defineUsagePlan(input) {
|
|
58
|
+
const plan = planSchema.parse(input);
|
|
59
|
+
if (plan.model === "included_overage")
|
|
60
|
+
parseUsageQuantity(plan.includedQuantity, plan.unit.precision);
|
|
61
|
+
return plan;
|
|
62
|
+
}
|
|
63
|
+
//# sourceMappingURL=contracts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/client/usage/contracts.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { defineUsagePlan, parseUsageQuantity } from "./contracts.js";
|
|
2
|
+
export type { UsagePlan, UsageBillingModel, ExactUsageQuantity, } from "./contracts.js";
|
|
3
|
+
export { prepareUsageRecord } from "./records.js";
|
|
4
|
+
export type { UsageScope, PreparedUsageRecord, UsageDeliveryState, } from "./records.js";
|
|
5
|
+
export { assertUsageReplay, validateUsagePageRequest, authorizeUsageRecord, } from "./boundaries.js";
|
|
6
|
+
export type { UsagePeriod, UsagePageRequest, UsageAvailability, UsageAuthorization, UsageObservations, UsageCorrectionRequest, UsageRetentionPolicy, UsageTransitionRequest, UsageSubscriptionBinding, UsageCreditProvenance, UsageCorrectionOutcome, UsageReceipt, UsageHistoryPage, UsageProviderCapabilities, UsageContractPort, } from "./boundaries.js";
|
|
7
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/usage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/usage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAMrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMlD,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type UsagePlan } from "./contracts.js";
|
|
3
|
+
declare const scopeSchema: z.ZodObject<{
|
|
4
|
+
stripeAccountId: z.ZodString;
|
|
5
|
+
customerAccount: z.ZodString;
|
|
6
|
+
meterId: z.ZodString;
|
|
7
|
+
livemode: z.ZodBoolean;
|
|
8
|
+
}, z.core.$strict>;
|
|
9
|
+
declare const recordSchema: z.ZodObject<{
|
|
10
|
+
scope: z.ZodObject<{
|
|
11
|
+
stripeAccountId: z.ZodString;
|
|
12
|
+
customerAccount: z.ZodString;
|
|
13
|
+
meterId: z.ZodString;
|
|
14
|
+
livemode: z.ZodBoolean;
|
|
15
|
+
}, z.core.$strict>;
|
|
16
|
+
binding: z.ZodObject<{
|
|
17
|
+
stripeCustomerId: z.ZodString;
|
|
18
|
+
stripePriceId: z.ZodString;
|
|
19
|
+
eventName: z.ZodString;
|
|
20
|
+
apiVersion: z.ZodDefault<z.ZodEnum<{
|
|
21
|
+
"2026-09-30.endive": "2026-09-30.endive";
|
|
22
|
+
"2026-09-30.preview": "2026-09-30.preview";
|
|
23
|
+
}>>;
|
|
24
|
+
plan: z.ZodUnknown;
|
|
25
|
+
}, z.core.$strict>;
|
|
26
|
+
sourceEventId: z.ZodString;
|
|
27
|
+
quantity: z.ZodUnknown;
|
|
28
|
+
occurredAt: z.ZodNumber;
|
|
29
|
+
}, z.core.$strict>;
|
|
30
|
+
/** The exact Stripe realm, Accounts v2 payer, meter and test/live scope. */
|
|
31
|
+
export type UsageScope = z.infer<typeof scopeSchema>;
|
|
32
|
+
export type PreparedUsageRecord = Omit<z.infer<typeof recordSchema>, "quantity" | "binding"> & {
|
|
33
|
+
schemaVersion: 1;
|
|
34
|
+
identity: string;
|
|
35
|
+
quantity: string;
|
|
36
|
+
scaledQuantity: string;
|
|
37
|
+
binding: Omit<z.infer<typeof recordSchema>["binding"], "plan"> & {
|
|
38
|
+
plan: UsagePlan;
|
|
39
|
+
};
|
|
40
|
+
};
|
|
41
|
+
export type UsageDeliveryState = "queued" | "sending" | "provider_accepted" | "rejected" | "unknown" | "held";
|
|
42
|
+
/**
|
|
43
|
+
* Validate and snapshot a record before acceptance. This pure helper does not
|
|
44
|
+
* authorize an actor, verify provider ownership, persist or deliver anything.
|
|
45
|
+
* Occurrence time is Unix seconds; native provider windows are enforced by the
|
|
46
|
+
* acceptance/delivery implementation, not by changing historical event time.
|
|
47
|
+
*/
|
|
48
|
+
export declare function prepareUsageRecord(input: unknown): PreparedUsageRecord;
|
|
49
|
+
export {};
|
|
50
|
+
//# sourceMappingURL=records.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../../src/client/usage/records.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,QAAA,MAAM,WAAW;;;;;kBAKf,CAAC;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;kBAchB,CAAC;AAEH,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AACrD,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,EAC5B,UAAU,GAAG,SAAS,CACvB,GAAG;IACF,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,GAAG;QAC/D,IAAI,EAAE,SAAS,CAAC;KACjB,CAAC;CACH,CAAC;AACF,MAAM,MAAM,kBAAkB,GAC5B,QAAQ,GAAG,SAAS,GAAG,mBAAmB,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAqBtE"}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { STRIPE_API_VERSION } from "../constants.js";
|
|
3
|
+
import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
|
|
4
|
+
import { defineUsagePlan, parseUsageQuantity, } from "./contracts.js";
|
|
5
|
+
const scopeSchema = z.strictObject({
|
|
6
|
+
stripeAccountId: z.string().regex(/^acct_[a-zA-Z0-9]+$/),
|
|
7
|
+
customerAccount: z.string().regex(/^acct_[a-zA-Z0-9]+$/),
|
|
8
|
+
meterId: z.string().regex(/^mtr_[a-zA-Z0-9_]+$/),
|
|
9
|
+
livemode: z.boolean(),
|
|
10
|
+
});
|
|
11
|
+
const recordSchema = z.strictObject({
|
|
12
|
+
scope: scopeSchema,
|
|
13
|
+
binding: z.strictObject({
|
|
14
|
+
stripeCustomerId: z.string().regex(/^cus_[a-zA-Z0-9]+$/),
|
|
15
|
+
stripePriceId: z.string().regex(/^price_[a-zA-Z0-9]+$/),
|
|
16
|
+
eventName: z.string().min(1).max(100),
|
|
17
|
+
apiVersion: z
|
|
18
|
+
.enum([STRIPE_API_VERSION, STRIPE_CUSTOMER_PREVIEW_API_VERSION])
|
|
19
|
+
.default(STRIPE_API_VERSION),
|
|
20
|
+
plan: z.unknown(),
|
|
21
|
+
}),
|
|
22
|
+
sourceEventId: z.string().min(1).max(200),
|
|
23
|
+
quantity: z.unknown(),
|
|
24
|
+
occurredAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
|
|
25
|
+
});
|
|
26
|
+
/**
|
|
27
|
+
* Validate and snapshot a record before acceptance. This pure helper does not
|
|
28
|
+
* authorize an actor, verify provider ownership, persist or deliver anything.
|
|
29
|
+
* Occurrence time is Unix seconds; native provider windows are enforced by the
|
|
30
|
+
* acceptance/delivery implementation, not by changing historical event time.
|
|
31
|
+
*/
|
|
32
|
+
export function prepareUsageRecord(input) {
|
|
33
|
+
const record = recordSchema.parse(input);
|
|
34
|
+
const plan = defineUsagePlan(record.binding.plan);
|
|
35
|
+
const quantity = parseUsageQuantity(record.quantity, plan.unit.precision);
|
|
36
|
+
const scope = record.scope;
|
|
37
|
+
return {
|
|
38
|
+
...record,
|
|
39
|
+
schemaVersion: 1,
|
|
40
|
+
quantity: quantity.quantity,
|
|
41
|
+
scaledQuantity: quantity.scaledQuantity,
|
|
42
|
+
binding: { ...record.binding, plan },
|
|
43
|
+
// A plan/version/quantity change must conflict with the original source
|
|
44
|
+
// event, so these are deliberately outside the deduplication identity.
|
|
45
|
+
identity: JSON.stringify([
|
|
46
|
+
scope.livemode,
|
|
47
|
+
scope.stripeAccountId,
|
|
48
|
+
scope.customerAccount,
|
|
49
|
+
scope.meterId,
|
|
50
|
+
record.sourceEventId,
|
|
51
|
+
]),
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
//# sourceMappingURL=records.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"records.js","sourceRoot":"","sources":["../../../src/client/usage/records.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EACL,eAAe,EACf,kBAAkB,GAEnB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IAChD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IAClC,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC;QACtB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC;QACxD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC;QACvD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACrC,UAAU,EAAE,CAAC;aACV,IAAI,CAAC,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,CAAC;aAC/D,OAAO,CAAC,kBAAkB,CAAC;QAC9B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;KAClB,CAAC;IACF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACzC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC;CACxE,CAAC,CAAC;AAmBH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,OAAO;QACL,GAAG,MAAM;QACT,aAAa,EAAE,CAAC;QAChB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE;QACpC,wEAAwE;QACxE,uEAAuE;QACvE,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC;YACvB,KAAK,CAAC,QAAQ;YACd,KAAK,CAAC,eAAe;YACrB,KAAK,CAAC,eAAe;YACrB,KAAK,CAAC,OAAO;YACb,MAAM,CAAC,aAAa;SACrB,CAAC;KACH,CAAC;AACJ,CAAC"}
|
package/docs/README.md
CHANGED
|
@@ -51,3 +51,8 @@ guide for your integration.
|
|
|
51
51
|
|
|
52
52
|
The [example app setup guide](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md)
|
|
53
53
|
covers sandbox configuration, checkout comparisons, and test flows.
|
|
54
|
+
|
|
55
|
+
## Metered usage
|
|
56
|
+
|
|
57
|
+
Start with the [native Stripe setup guide](metering-setup.md), then read the
|
|
58
|
+
[shared contracts and sandbox evidence](metered-usage.md).
|
package/docs/development.md
CHANGED
|
@@ -46,14 +46,32 @@ formatting, typechecks, codegen drift check, tests, and repository quality gates
|
|
|
46
46
|
used by CI. Policy lives in `repo-gates.config.json`; measured baselines live in
|
|
47
47
|
`gates/`. Fix failures without weakening the gates or raising existing budgets.
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
`
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
the
|
|
49
|
+
Coverage checks enforce the committed floors in `gates/coverage-budgets.json`.
|
|
50
|
+
`pnpm run check:coverage` and `pnpm run check:all` never edit that file or fail
|
|
51
|
+
because coverage improved. Ordinary feature PRs should leave the budget file alone.
|
|
52
|
+
|
|
53
|
+
The [weekly coverage workflow](https://github.com/FantasticDevHQ/better-stripe/actions/workflows/coverage-ratchet.yml)
|
|
54
|
+
runs Mondays at 09:17 Asia/Bangkok, 02:17 UTC. It runs every repository gate on
|
|
55
|
+
`main`, then captures earned floor increases of at least **0.05 percentage points**
|
|
56
|
+
per metric. It keeps the existing 0.5-point margin below measured coverage and
|
|
57
|
+
never lowers a floor. Eligible metrics capture their full earned increase; this
|
|
58
|
+
is a minimum useful change, not a forced weekly increase. Smaller gains accumulate
|
|
59
|
+
until a later run. Failed checks and old reports cannot authorize any update.
|
|
60
|
+
|
|
61
|
+
The workflow maintains one ready-for-review PR on `codex/coverage-ratchet`, changing
|
|
62
|
+
only the coverage budget file. Its description records measured coverage, old and
|
|
63
|
+
proposed floors, and a link to the full gate run. It reuses the existing release
|
|
64
|
+
GitHub App configuration so the generated PR runs normal CI. Auto-merge matches
|
|
65
|
+
the exact generated head and waits for all required checks under the existing
|
|
66
|
+
branch protections, without bypass actors. The helper checks the app author,
|
|
67
|
+
branch, repository, changed files, policy metadata, and measured proposal before
|
|
68
|
+
enabling auto-merge. Do not add unrelated commits to this managed branch.
|
|
69
|
+
|
|
70
|
+
Use **Run workflow** on `main` for an additional full measurement between weekly
|
|
71
|
+
runs. Once merged, this workflow becomes available to the scheduler and manual
|
|
72
|
+
dispatch. Locally, `node scripts/check-coverage.mjs --ratchet` runs the same complete
|
|
73
|
+
gates before proposing a budget update. It accepts no test filters, partial mode,
|
|
74
|
+
or skipped execution. `pnpm test:coverage` generates a report only.
|
|
57
75
|
|
|
58
76
|
Builds and typechecks use TypeScript 7 (`@typescript/native` aliases
|
|
59
77
|
`typescript`). ESLint and Convex code generation still need the TypeScript 6
|