@fantastic.dev/better-stripe 0.57.0 → 0.58.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 +6 -0
- package/README.md +3 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +122 -36
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +45 -2
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +122 -36
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +45 -2
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/usage/allowanceClient.d.ts +51 -0
- package/dist/client/usage/allowanceClient.d.ts.map +1 -0
- package/dist/client/usage/allowanceClient.js +64 -0
- package/dist/client/usage/allowanceClient.js.map +1 -0
- package/dist/client/usage/allowanceTerms.d.ts +64 -0
- package/dist/client/usage/allowanceTerms.d.ts.map +1 -0
- package/dist/client/usage/allowanceTerms.js +101 -0
- package/dist/client/usage/allowanceTerms.js.map +1 -0
- package/dist/client/usage/client.d.ts +2 -2
- package/dist/client/usage/client.d.ts.map +1 -1
- package/dist/client/usage/client.js +2 -2
- package/dist/client/usage/client.js.map +1 -1
- package/dist/client/usage/index.d.ts +2 -0
- package/dist/client/usage/index.d.ts.map +1 -1
- package/dist/client/usageExports.d.ts +2 -0
- package/dist/client/usageExports.d.ts.map +1 -1
- package/dist/component/_generated/api.d.ts +8 -0
- package/dist/component/_generated/api.d.ts.map +1 -1
- package/dist/component/_generated/api.js.map +1 -1
- package/dist/component/_generated/component.d.ts +70 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/mutations.d.ts +16 -16
- package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
- package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
- package/dist/component/earnings/triggers.d.ts +110 -18
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/schema.d.ts +45 -2
- package/dist/component/schema.js +3 -0
- package/dist/component/schema.js.map +1 -1
- package/dist/component/usage/mutations.d.ts.map +1 -1
- package/dist/component/usage/mutations.js +4 -0
- package/dist/component/usage/mutations.js.map +1 -1
- package/dist/component/usage/schema.d.ts +3 -2
- package/dist/component/usage/schema.d.ts.map +1 -1
- package/dist/component/usage/schema.js +2 -1
- package/dist/component/usage/schema.js.map +1 -1
- package/dist/component/usageAllowance/helpers.d.ts +78 -0
- package/dist/component/usageAllowance/helpers.d.ts.map +1 -0
- package/dist/component/usageAllowance/helpers.js +99 -0
- package/dist/component/usageAllowance/helpers.js.map +1 -0
- package/dist/component/usageAllowance/mutations.d.ts +37 -0
- package/dist/component/usageAllowance/mutations.d.ts.map +1 -0
- package/dist/component/usageAllowance/mutations.js +99 -0
- package/dist/component/usageAllowance/mutations.js.map +1 -0
- package/dist/component/usageAllowance/queries.d.ts +36 -0
- package/dist/component/usageAllowance/queries.d.ts.map +1 -0
- package/dist/component/usageAllowance/queries.js +113 -0
- package/dist/component/usageAllowance/queries.js.map +1 -0
- package/dist/component/usageAllowance/reservations.d.ts +25 -0
- package/dist/component/usageAllowance/reservations.d.ts.map +1 -0
- package/dist/component/usageAllowance/reservations.js +150 -0
- package/dist/component/usageAllowance/reservations.js.map +1 -0
- package/dist/component/usageAllowance/schema.d.ts +77 -0
- package/dist/component/usageAllowance/schema.d.ts.map +1 -0
- package/dist/component/usageAllowance/schema.js +32 -0
- package/dist/component/usageAllowance/schema.js.map +1 -0
- package/docs/README.md +2 -0
- package/docs/usage-limits.md +217 -0
- package/package.json +2 -1
- package/src/client/usage/allowanceClient.test.ts +93 -0
- package/src/client/usage/allowanceClient.ts +134 -0
- package/src/client/usage/allowanceTerms.test.ts +131 -0
- package/src/client/usage/allowanceTerms.ts +172 -0
- package/src/client/usage/client.ts +2 -2
- package/src/client/usage/index.ts +8 -0
- package/src/client/usageExports.ts +8 -0
- package/src/component/_generated/api.ts +8 -0
- package/src/component/_generated/component.ts +94 -0
- package/src/component/schema.ts +6 -0
- package/src/component/usage/allowance.test.ts +435 -0
- package/src/component/usage/mutations.ts +13 -0
- package/src/component/usage/schema.ts +4 -1
- package/src/component/usageAllowance/helpers.ts +137 -0
- package/src/component/usageAllowance/mutations.ts +139 -0
- package/src/component/usageAllowance/queries.ts +133 -0
- package/src/component/usageAllowance/reservations.ts +220 -0
- package/src/component/usageAllowance/schema.ts +36 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { RunCtx } from "../helpers.js";
|
|
3
|
+
import { runMutationOrThrow } from "../helpers.js";
|
|
4
|
+
import { componentRef } from "../webhooks/helpers.js";
|
|
5
|
+
import { UsageCreditClient } from "./creditClient.js";
|
|
6
|
+
import { prepareUsageRecord, scopeSchema, type UsageScope } from "./records.js";
|
|
7
|
+
import {
|
|
8
|
+
allowanceBinding,
|
|
9
|
+
limitPolicy,
|
|
10
|
+
type UsageAllowanceBinding,
|
|
11
|
+
type UsageAllowanceStatus,
|
|
12
|
+
type UsageAllowanceReconciliation,
|
|
13
|
+
type UsageLimitPolicy,
|
|
14
|
+
} from "./allowanceTerms.js";
|
|
15
|
+
import type { UsageSubscriptionBinding } from "./boundaries.js";
|
|
16
|
+
import type { Doc, Id } from "../../component/_generated/dataModel.js";
|
|
17
|
+
export type UsageAllowanceReservation =
|
|
18
|
+
| { state: "denied"; reason: "not_entitled" | "hard_limit"; revision: number }
|
|
19
|
+
| {
|
|
20
|
+
state: "reserved" | "committed" | "released";
|
|
21
|
+
reservationId: Id<"usageReservations">;
|
|
22
|
+
revision: number;
|
|
23
|
+
};
|
|
24
|
+
const bindingJson = (input: UsageAllowanceBinding) =>
|
|
25
|
+
JSON.stringify(
|
|
26
|
+
allowanceBinding({
|
|
27
|
+
scope: input.scope,
|
|
28
|
+
binding: input.binding,
|
|
29
|
+
subscription: input.subscription,
|
|
30
|
+
}),
|
|
31
|
+
);
|
|
32
|
+
/** Trusted host authorizes policy management and the exact billable activity. */
|
|
33
|
+
export class UsageAllowanceClient extends UsageCreditClient {
|
|
34
|
+
configureAllowance(
|
|
35
|
+
ctx: RunCtx,
|
|
36
|
+
input: UsageAllowanceBinding & {
|
|
37
|
+
policy: UsageLimitPolicy;
|
|
38
|
+
expectedRevision: number;
|
|
39
|
+
},
|
|
40
|
+
): Promise<{ revision: number }> {
|
|
41
|
+
const binding = allowanceBinding({
|
|
42
|
+
scope: input.scope,
|
|
43
|
+
binding: input.binding,
|
|
44
|
+
subscription: input.subscription,
|
|
45
|
+
});
|
|
46
|
+
return runMutationOrThrow(
|
|
47
|
+
ctx,
|
|
48
|
+
componentRef(this.component, "usageAllowance/mutations/configure"),
|
|
49
|
+
{
|
|
50
|
+
bindingJson: JSON.stringify(binding),
|
|
51
|
+
policyJson: JSON.stringify(limitPolicy(input.policy, binding)),
|
|
52
|
+
expectedRevision: input.expectedRevision,
|
|
53
|
+
},
|
|
54
|
+
);
|
|
55
|
+
}
|
|
56
|
+
async getAllowanceStatus(
|
|
57
|
+
ctx: RunCtx,
|
|
58
|
+
input: UsageAllowanceBinding,
|
|
59
|
+
): Promise<UsageAllowanceStatus | null> {
|
|
60
|
+
const result = (await ctx.runQuery(
|
|
61
|
+
componentRef(this.component, "usageAllowance/queries/status"),
|
|
62
|
+
{ bindingJson: bindingJson(input) },
|
|
63
|
+
)) as string | null;
|
|
64
|
+
return result === null
|
|
65
|
+
? null
|
|
66
|
+
: (JSON.parse(result) as UsageAllowanceStatus);
|
|
67
|
+
}
|
|
68
|
+
reconcileAllowance(
|
|
69
|
+
ctx: RunCtx,
|
|
70
|
+
input: UsageAllowanceBinding,
|
|
71
|
+
): Promise<UsageAllowanceReconciliation> {
|
|
72
|
+
return ctx.runQuery(
|
|
73
|
+
componentRef(this.component, "usageAllowance/queries/reconciliation"),
|
|
74
|
+
{ bindingJson: bindingJson(input) },
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
reserveAllowance(
|
|
78
|
+
ctx: RunCtx,
|
|
79
|
+
input: { event: unknown; subscription: UsageSubscriptionBinding },
|
|
80
|
+
): Promise<UsageAllowanceReservation> {
|
|
81
|
+
const event = prepareUsageRecord(input.event);
|
|
82
|
+
return runMutationOrThrow(
|
|
83
|
+
ctx,
|
|
84
|
+
componentRef(this.component, "usageAllowance/mutations/reserve"),
|
|
85
|
+
{
|
|
86
|
+
inputJson: JSON.stringify({
|
|
87
|
+
scope: event.scope,
|
|
88
|
+
binding: event.binding,
|
|
89
|
+
sourceEventId: event.sourceEventId,
|
|
90
|
+
occurredAt: event.occurredAt,
|
|
91
|
+
quantity: event.quantity,
|
|
92
|
+
}),
|
|
93
|
+
subscriptionJson: JSON.stringify(input.subscription),
|
|
94
|
+
},
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
releaseAllowance(
|
|
98
|
+
ctx: RunCtx,
|
|
99
|
+
input: {
|
|
100
|
+
scope: UsageScope;
|
|
101
|
+
reservationId: Id<"usageReservations">;
|
|
102
|
+
reason: "work_failed" | "abandoned_before_work";
|
|
103
|
+
},
|
|
104
|
+
) {
|
|
105
|
+
return runMutationOrThrow(
|
|
106
|
+
ctx,
|
|
107
|
+
componentRef(this.component, "usageAllowance/mutations/release"),
|
|
108
|
+
{ ...input, scope: scopeSchema.parse(input.scope) },
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
async readAllowanceHistory(
|
|
112
|
+
ctx: RunCtx,
|
|
113
|
+
input: UsageAllowanceBinding & { limit: number; cursor: string | null },
|
|
114
|
+
) {
|
|
115
|
+
const limit = z.number().int().min(1).max(100).parse(input.limit),
|
|
116
|
+
cursor = z.string().min(1).max(2048).nullable().parse(input.cursor);
|
|
117
|
+
const result = (await ctx.runQuery(
|
|
118
|
+
componentRef(this.component, "usageAllowance/queries/readHistory"),
|
|
119
|
+
{
|
|
120
|
+
bindingJson: bindingJson(input),
|
|
121
|
+
paginationOpts: { numItems: limit, cursor },
|
|
122
|
+
},
|
|
123
|
+
)) as {
|
|
124
|
+
page: Doc<"usageAllowanceHistory">[];
|
|
125
|
+
continueCursor: string;
|
|
126
|
+
isDone: boolean;
|
|
127
|
+
};
|
|
128
|
+
return {
|
|
129
|
+
records: result.page,
|
|
130
|
+
cursor: result.isDone ? null : result.continueCursor,
|
|
131
|
+
isDone: result.isDone,
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { expect, it } from "vitest";
|
|
2
|
+
import {
|
|
3
|
+
allowanceBinding,
|
|
4
|
+
allowanceStatus,
|
|
5
|
+
limitPolicy,
|
|
6
|
+
} from "./allowanceTerms.js";
|
|
7
|
+
import { request } from "./subscription.fixtures.js";
|
|
8
|
+
const original = {
|
|
9
|
+
...request.meters[0],
|
|
10
|
+
subscription: {
|
|
11
|
+
subscriptionId: "sub_calls",
|
|
12
|
+
subscriptionItemId: "si_calls",
|
|
13
|
+
stripePriceId: "price_calls",
|
|
14
|
+
period: { start: 600, end: 1200 },
|
|
15
|
+
interval: "month",
|
|
16
|
+
},
|
|
17
|
+
};
|
|
18
|
+
it("calculates fractional units and decimal minor-currency estimates without rounding", () => {
|
|
19
|
+
const binding = allowanceBinding({
|
|
20
|
+
...original,
|
|
21
|
+
binding: {
|
|
22
|
+
...original.binding,
|
|
23
|
+
plan: {
|
|
24
|
+
...original.binding.plan,
|
|
25
|
+
unit: { name: "call", precision: 2 },
|
|
26
|
+
includedQuantity: "1.25",
|
|
27
|
+
rate: { currency: "usd", unitAmountDecimal: "0.025" },
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
const policy = limitPolicy(
|
|
32
|
+
{
|
|
33
|
+
reset: "billing_period",
|
|
34
|
+
rollover: "none",
|
|
35
|
+
entitled: true,
|
|
36
|
+
overage: "allow",
|
|
37
|
+
limit: { mode: "soft", quantity: "1.30" },
|
|
38
|
+
},
|
|
39
|
+
binding,
|
|
40
|
+
);
|
|
41
|
+
expect(
|
|
42
|
+
allowanceStatus(
|
|
43
|
+
binding,
|
|
44
|
+
policy,
|
|
45
|
+
{ consumed: "130", reserved: "1", revision: 1 },
|
|
46
|
+
700,
|
|
47
|
+
),
|
|
48
|
+
).toMatchObject({
|
|
49
|
+
consumedQuantity: "1.3",
|
|
50
|
+
reservedQuantity: "0.01",
|
|
51
|
+
billableOverageQuantity: "0.05",
|
|
52
|
+
softLimitReached: true,
|
|
53
|
+
committedEstimate: { amountDecimal: "0.00125", currency: "usd" },
|
|
54
|
+
projectedEstimate: { amountDecimal: "0.0015", currency: "usd" },
|
|
55
|
+
});
|
|
56
|
+
});
|
|
57
|
+
it("rejects unsupported rollover/reset, invalid precision and prepaid instead of minting allowance credit", () => {
|
|
58
|
+
const binding = allowanceBinding(original),
|
|
59
|
+
policy = {
|
|
60
|
+
reset: "billing_period",
|
|
61
|
+
rollover: "none",
|
|
62
|
+
entitled: true,
|
|
63
|
+
overage: "allow",
|
|
64
|
+
limit: { mode: "none" },
|
|
65
|
+
};
|
|
66
|
+
for (const changed of [
|
|
67
|
+
{ ...policy, reset: "calendar_month" },
|
|
68
|
+
{ ...policy, rollover: "carry" },
|
|
69
|
+
{ ...policy, limit: { mode: "hard", quantity: "0.1" } },
|
|
70
|
+
{ ...policy, limit: { mode: "hard", quantity: "1000000000000000000" } },
|
|
71
|
+
])
|
|
72
|
+
expect(() => limitPolicy(changed, binding)).toThrow();
|
|
73
|
+
expect(() =>
|
|
74
|
+
allowanceBinding({
|
|
75
|
+
...original,
|
|
76
|
+
binding: {
|
|
77
|
+
...original.binding,
|
|
78
|
+
plan: {
|
|
79
|
+
key: "calls",
|
|
80
|
+
version: "v1",
|
|
81
|
+
model: "prepaid",
|
|
82
|
+
unit: { name: "call", precision: 0 },
|
|
83
|
+
rate: { currency: "usd", unitAmountDecimal: "2" },
|
|
84
|
+
insufficientBalance: "reject",
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
}),
|
|
88
|
+
).toThrow(/payment-backed/i);
|
|
89
|
+
});
|
|
90
|
+
it("supports optional pay-as-you-go hard caps without inventing included units", () => {
|
|
91
|
+
const binding = allowanceBinding({
|
|
92
|
+
...original,
|
|
93
|
+
binding: {
|
|
94
|
+
...original.binding,
|
|
95
|
+
plan: {
|
|
96
|
+
key: "calls",
|
|
97
|
+
version: "v1",
|
|
98
|
+
model: "pay_as_you_go",
|
|
99
|
+
unit: { name: "call", precision: 0 },
|
|
100
|
+
rate: { currency: "usd", unitAmountDecimal: "2" },
|
|
101
|
+
},
|
|
102
|
+
},
|
|
103
|
+
});
|
|
104
|
+
const policy = limitPolicy(
|
|
105
|
+
{
|
|
106
|
+
reset: "billing_period",
|
|
107
|
+
rollover: "none",
|
|
108
|
+
entitled: true,
|
|
109
|
+
overage: "allow",
|
|
110
|
+
limit: { mode: "hard", quantity: "12" },
|
|
111
|
+
},
|
|
112
|
+
binding,
|
|
113
|
+
);
|
|
114
|
+
expect(
|
|
115
|
+
allowanceStatus(
|
|
116
|
+
binding,
|
|
117
|
+
policy,
|
|
118
|
+
{ consumed: "6", reserved: "6", revision: 1 },
|
|
119
|
+
700,
|
|
120
|
+
),
|
|
121
|
+
).toMatchObject({
|
|
122
|
+
includedQuantity: "0",
|
|
123
|
+
hardLimitRemainingQuantity: "0",
|
|
124
|
+
accepting: false,
|
|
125
|
+
committedEstimate: { amountDecimal: "12", currency: "usd" },
|
|
126
|
+
projectedEstimate: { amountDecimal: "24", currency: "usd" },
|
|
127
|
+
});
|
|
128
|
+
expect(() => limitPolicy({ ...policy, overage: "reject" }, binding)).toThrow(
|
|
129
|
+
/explicit usage cap/i,
|
|
130
|
+
);
|
|
131
|
+
});
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { prepareUsageRecord, type PreparedUsageRecord } from "./records.js";
|
|
3
|
+
import { parseUsageQuantity } from "./contracts.js";
|
|
4
|
+
import { decimalFromScaled } from "./summary.js";
|
|
5
|
+
import type { UsageSubscriptionBinding } from "./boundaries.js";
|
|
6
|
+
export type UsageAllowanceBinding = Pick<
|
|
7
|
+
PreparedUsageRecord,
|
|
8
|
+
"scope" | "binding"
|
|
9
|
+
> & {
|
|
10
|
+
subscription: UsageSubscriptionBinding;
|
|
11
|
+
};
|
|
12
|
+
const seconds = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
|
|
13
|
+
const subscriptionSchema = z.strictObject({
|
|
14
|
+
subscriptionId: z.string().regex(/^sub_[a-zA-Z0-9]+$/),
|
|
15
|
+
subscriptionItemId: z.string().regex(/^si_[a-zA-Z0-9]+$/),
|
|
16
|
+
stripePriceId: z.string().regex(/^price_[a-zA-Z0-9]+$/),
|
|
17
|
+
period: z.strictObject({ start: seconds, end: seconds }),
|
|
18
|
+
interval: z.literal("month"),
|
|
19
|
+
});
|
|
20
|
+
export const usageLimitPolicySchema = z.strictObject({
|
|
21
|
+
reset: z.literal("billing_period"),
|
|
22
|
+
rollover: z.literal("none"),
|
|
23
|
+
entitled: z.boolean(),
|
|
24
|
+
overage: z.enum(["allow", "reject"]),
|
|
25
|
+
limit: z.discriminatedUnion("mode", [
|
|
26
|
+
z.strictObject({ mode: z.literal("none") }),
|
|
27
|
+
z.strictObject({ mode: z.enum(["soft", "hard"]), quantity: z.string() }),
|
|
28
|
+
]),
|
|
29
|
+
});
|
|
30
|
+
export type UsageLimitPolicy = z.infer<typeof usageLimitPolicySchema>;
|
|
31
|
+
export type UsageAllowanceStatus = {
|
|
32
|
+
revision: number;
|
|
33
|
+
observedAt: number;
|
|
34
|
+
period: UsageSubscriptionBinding["period"];
|
|
35
|
+
accepting: boolean;
|
|
36
|
+
policy: UsageLimitPolicy;
|
|
37
|
+
consumedQuantity: string;
|
|
38
|
+
reservedQuantity: string;
|
|
39
|
+
includedQuantity: string;
|
|
40
|
+
remainingIncludedQuantity: string;
|
|
41
|
+
billableOverageQuantity: string;
|
|
42
|
+
softLimitReached: boolean;
|
|
43
|
+
hardLimitRemainingQuantity: string | null;
|
|
44
|
+
committedEstimate: { amountDecimal: string; currency: string };
|
|
45
|
+
projectedEstimate: { amountDecimal: string; currency: string };
|
|
46
|
+
cashCollection: "none";
|
|
47
|
+
};
|
|
48
|
+
export function allowanceBinding(input: unknown): UsageAllowanceBinding {
|
|
49
|
+
const raw = z
|
|
50
|
+
.strictObject({
|
|
51
|
+
scope: z.unknown(),
|
|
52
|
+
binding: z.unknown(),
|
|
53
|
+
subscription: subscriptionSchema,
|
|
54
|
+
})
|
|
55
|
+
.parse(input);
|
|
56
|
+
const event = prepareUsageRecord({
|
|
57
|
+
scope: raw.scope,
|
|
58
|
+
binding: raw.binding,
|
|
59
|
+
sourceEventId: "validation",
|
|
60
|
+
quantity: "0",
|
|
61
|
+
occurredAt: 0,
|
|
62
|
+
});
|
|
63
|
+
if (event.binding.plan.model === "prepaid")
|
|
64
|
+
throw new Error("Use payment-backed prepaid credit accounting");
|
|
65
|
+
if (
|
|
66
|
+
raw.subscription.period.end <= raw.subscription.period.start ||
|
|
67
|
+
raw.subscription.stripePriceId !== event.binding.stripePriceId
|
|
68
|
+
)
|
|
69
|
+
throw new Error("Allowance subscription period/price mismatch");
|
|
70
|
+
return {
|
|
71
|
+
scope: event.scope,
|
|
72
|
+
binding: event.binding,
|
|
73
|
+
subscription: raw.subscription,
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
export function limitPolicy(
|
|
77
|
+
input: unknown,
|
|
78
|
+
binding: UsageAllowanceBinding,
|
|
79
|
+
): UsageLimitPolicy {
|
|
80
|
+
const policy = usageLimitPolicySchema.parse(input),
|
|
81
|
+
precision = binding.binding.plan.unit.precision;
|
|
82
|
+
if (policy.limit.mode !== "none")
|
|
83
|
+
policy.limit.quantity = parseUsageQuantity(
|
|
84
|
+
policy.limit.quantity,
|
|
85
|
+
precision,
|
|
86
|
+
).quantity;
|
|
87
|
+
if (
|
|
88
|
+
binding.binding.plan.model === "pay_as_you_go" &&
|
|
89
|
+
policy.overage === "reject"
|
|
90
|
+
)
|
|
91
|
+
throw new Error(
|
|
92
|
+
"Pay-as-you-go requires an explicit usage cap instead of an included allowance",
|
|
93
|
+
);
|
|
94
|
+
return policy;
|
|
95
|
+
}
|
|
96
|
+
export function allowanceStatus(
|
|
97
|
+
binding: UsageAllowanceBinding,
|
|
98
|
+
policy: UsageLimitPolicy,
|
|
99
|
+
row: { consumed: string; reserved: string; revision: number },
|
|
100
|
+
observedAt: number,
|
|
101
|
+
): UsageAllowanceStatus {
|
|
102
|
+
const plan = binding.binding.plan,
|
|
103
|
+
precision = plan.unit.precision;
|
|
104
|
+
const consumed = BigInt(row.consumed),
|
|
105
|
+
reserved = BigInt(row.reserved),
|
|
106
|
+
total = consumed + reserved;
|
|
107
|
+
const included =
|
|
108
|
+
plan.model === "included_overage"
|
|
109
|
+
? BigInt(
|
|
110
|
+
parseUsageQuantity(plan.includedQuantity, precision).scaledQuantity,
|
|
111
|
+
)
|
|
112
|
+
: 0n;
|
|
113
|
+
const overage = (quantity: bigint) =>
|
|
114
|
+
quantity > included ? quantity - included : 0n;
|
|
115
|
+
const quantity = (value: bigint) => decimalFromScaled(value, precision);
|
|
116
|
+
const cost = (value: bigint) => {
|
|
117
|
+
const [whole, fraction = ""] = plan.rate.unitAmountDecimal.split(".");
|
|
118
|
+
return {
|
|
119
|
+
amountDecimal: decimalFromScaled(
|
|
120
|
+
overage(value) * BigInt(whole + fraction),
|
|
121
|
+
precision + fraction.length,
|
|
122
|
+
),
|
|
123
|
+
currency: plan.rate.currency,
|
|
124
|
+
};
|
|
125
|
+
};
|
|
126
|
+
let hard: bigint | null =
|
|
127
|
+
policy.limit.mode === "hard"
|
|
128
|
+
? BigInt(
|
|
129
|
+
parseUsageQuantity(policy.limit.quantity, precision).scaledQuantity,
|
|
130
|
+
)
|
|
131
|
+
: null;
|
|
132
|
+
if (policy.overage === "reject")
|
|
133
|
+
hard = hard === null || included < hard ? included : hard;
|
|
134
|
+
return {
|
|
135
|
+
revision: row.revision,
|
|
136
|
+
observedAt,
|
|
137
|
+
period: binding.subscription.period,
|
|
138
|
+
accepting:
|
|
139
|
+
policy.entitled &&
|
|
140
|
+
observedAt >= binding.subscription.period.start &&
|
|
141
|
+
observedAt < binding.subscription.period.end - 60 &&
|
|
142
|
+
(hard === null || total < hard),
|
|
143
|
+
policy,
|
|
144
|
+
consumedQuantity: quantity(consumed),
|
|
145
|
+
reservedQuantity: quantity(reserved),
|
|
146
|
+
includedQuantity: quantity(included),
|
|
147
|
+
remainingIncludedQuantity: quantity(
|
|
148
|
+
included > total ? included - total : 0n,
|
|
149
|
+
),
|
|
150
|
+
billableOverageQuantity: quantity(overage(consumed)),
|
|
151
|
+
softLimitReached:
|
|
152
|
+
policy.limit.mode === "soft" &&
|
|
153
|
+
total >=
|
|
154
|
+
BigInt(
|
|
155
|
+
parseUsageQuantity(policy.limit.quantity, precision).scaledQuantity,
|
|
156
|
+
),
|
|
157
|
+
hardLimitRemainingQuantity:
|
|
158
|
+
hard === null ? null : quantity(hard > total ? hard - total : 0n),
|
|
159
|
+
committedEstimate: cost(consumed),
|
|
160
|
+
projectedEstimate: cost(total),
|
|
161
|
+
cashCollection: "none",
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export type UsageAllowanceReconciliation = {
|
|
166
|
+
status: "matched" | "held";
|
|
167
|
+
reason: string;
|
|
168
|
+
consumedScaledQuantity: string;
|
|
169
|
+
reservedScaledQuantity: string;
|
|
170
|
+
acceptedScaledQuantity: string;
|
|
171
|
+
repaired: false;
|
|
172
|
+
};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { UsageAllowanceClient } from "./allowanceClient.js";
|
|
2
2
|
import type { Component, RunCtx } from "../helpers.js";
|
|
3
3
|
import { runMutationOrThrow } from "../helpers.js";
|
|
4
4
|
import { componentRef } from "../webhooks/helpers.js";
|
|
@@ -46,7 +46,7 @@ function decode({ event, delivery }: StoredView): UsageEventView {
|
|
|
46
46
|
};
|
|
47
47
|
}
|
|
48
48
|
/** Trusted host facade. Authenticate and authorize each exact scope first. */
|
|
49
|
-
export class UsageLedgerClient extends
|
|
49
|
+
export class UsageLedgerClient extends UsageAllowanceClient {
|
|
50
50
|
constructor(component: Component) {
|
|
51
51
|
super(component);
|
|
52
52
|
}
|
|
@@ -80,3 +80,11 @@ export type {
|
|
|
80
80
|
UsageCreditPurchase,
|
|
81
81
|
UsageCreditBalance,
|
|
82
82
|
} from "./creditTerms.js";
|
|
83
|
+
|
|
84
|
+
export type {
|
|
85
|
+
UsageAllowanceBinding,
|
|
86
|
+
UsageAllowanceStatus,
|
|
87
|
+
UsageAllowanceReconciliation,
|
|
88
|
+
UsageLimitPolicy,
|
|
89
|
+
} from "./allowanceTerms.js";
|
|
90
|
+
export type { UsageAllowanceReservation } from "./allowanceClient.js";
|
|
@@ -46,3 +46,11 @@ export type {
|
|
|
46
46
|
UsageCreditPurchase,
|
|
47
47
|
UsageCreditBalance,
|
|
48
48
|
} from "./usage/creditTerms.js";
|
|
49
|
+
|
|
50
|
+
export type {
|
|
51
|
+
UsageAllowanceBinding,
|
|
52
|
+
UsageAllowanceStatus,
|
|
53
|
+
UsageAllowanceReconciliation,
|
|
54
|
+
UsageLimitPolicy,
|
|
55
|
+
} from "./usage/allowanceTerms.js";
|
|
56
|
+
export type { UsageAllowanceReservation } from "./usage/allowanceClient.js";
|
|
@@ -165,6 +165,10 @@ import type * as settlement_queries from "../settlement/queries.js";
|
|
|
165
165
|
import type * as usage_helpers from "../usage/helpers.js";
|
|
166
166
|
import type * as usage_mutations from "../usage/mutations.js";
|
|
167
167
|
import type * as usage_queries from "../usage/queries.js";
|
|
168
|
+
import type * as usageAllowance_helpers from "../usageAllowance/helpers.js";
|
|
169
|
+
import type * as usageAllowance_mutations from "../usageAllowance/mutations.js";
|
|
170
|
+
import type * as usageAllowance_queries from "../usageAllowance/queries.js";
|
|
171
|
+
import type * as usageAllowance_reservations from "../usageAllowance/reservations.js";
|
|
168
172
|
import type * as usageCatalog_mutations from "../usageCatalog/mutations.js";
|
|
169
173
|
import type * as usageCatalog_queries from "../usageCatalog/queries.js";
|
|
170
174
|
import type * as usageCredits_helpers from "../usageCredits/helpers.js";
|
|
@@ -359,6 +363,10 @@ const fullApi: ApiFromModules<{
|
|
|
359
363
|
"usage/helpers": typeof usage_helpers;
|
|
360
364
|
"usage/mutations": typeof usage_mutations;
|
|
361
365
|
"usage/queries": typeof usage_queries;
|
|
366
|
+
"usageAllowance/helpers": typeof usageAllowance_helpers;
|
|
367
|
+
"usageAllowance/mutations": typeof usageAllowance_mutations;
|
|
368
|
+
"usageAllowance/queries": typeof usageAllowance_queries;
|
|
369
|
+
"usageAllowance/reservations": typeof usageAllowance_reservations;
|
|
362
370
|
"usageCatalog/mutations": typeof usageCatalog_mutations;
|
|
363
371
|
"usageCatalog/queries": typeof usageCatalog_queries;
|
|
364
372
|
"usageCredits/helpers": typeof usageCredits_helpers;
|
|
@@ -8378,6 +8378,100 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
|
|
|
8378
8378
|
>;
|
|
8379
8379
|
};
|
|
8380
8380
|
};
|
|
8381
|
+
usageAllowance: {
|
|
8382
|
+
mutations: {
|
|
8383
|
+
configure: FunctionReference<
|
|
8384
|
+
"mutation",
|
|
8385
|
+
"internal",
|
|
8386
|
+
{ bindingJson: string; expectedRevision: number; policyJson: string },
|
|
8387
|
+
{ revision: number },
|
|
8388
|
+
Name
|
|
8389
|
+
>;
|
|
8390
|
+
release: FunctionReference<
|
|
8391
|
+
"mutation",
|
|
8392
|
+
"internal",
|
|
8393
|
+
{
|
|
8394
|
+
reason: "work_failed" | "abandoned_before_work";
|
|
8395
|
+
reservationId: string;
|
|
8396
|
+
scope: {
|
|
8397
|
+
customerAccount: string;
|
|
8398
|
+
livemode: boolean;
|
|
8399
|
+
meterId: string;
|
|
8400
|
+
stripeAccountId: string;
|
|
8401
|
+
};
|
|
8402
|
+
},
|
|
8403
|
+
null,
|
|
8404
|
+
Name
|
|
8405
|
+
>;
|
|
8406
|
+
reserve: FunctionReference<
|
|
8407
|
+
"mutation",
|
|
8408
|
+
"internal",
|
|
8409
|
+
{ inputJson: string; subscriptionJson: string },
|
|
8410
|
+
| {
|
|
8411
|
+
reason: "not_entitled" | "hard_limit";
|
|
8412
|
+
revision: number;
|
|
8413
|
+
state: "denied";
|
|
8414
|
+
}
|
|
8415
|
+
| {
|
|
8416
|
+
reservationId: string;
|
|
8417
|
+
revision: number;
|
|
8418
|
+
state: "reserved" | "committed" | "released";
|
|
8419
|
+
},
|
|
8420
|
+
Name
|
|
8421
|
+
>;
|
|
8422
|
+
};
|
|
8423
|
+
queries: {
|
|
8424
|
+
readHistory: FunctionReference<
|
|
8425
|
+
"query",
|
|
8426
|
+
"internal",
|
|
8427
|
+
{
|
|
8428
|
+
bindingJson: string;
|
|
8429
|
+
paginationOpts: {
|
|
8430
|
+
cursor: string | null;
|
|
8431
|
+
endCursor?: string | null;
|
|
8432
|
+
id?: number;
|
|
8433
|
+
maximumBytesRead?: number;
|
|
8434
|
+
maximumRowsRead?: number;
|
|
8435
|
+
numItems: number;
|
|
8436
|
+
};
|
|
8437
|
+
},
|
|
8438
|
+
{
|
|
8439
|
+
continueCursor: string;
|
|
8440
|
+
isDone: boolean;
|
|
8441
|
+
page: Array<{
|
|
8442
|
+
_creationTime: number;
|
|
8443
|
+
_id: string;
|
|
8444
|
+
at: number;
|
|
8445
|
+
evidenceJson: string;
|
|
8446
|
+
key: string;
|
|
8447
|
+
kind: "policy" | "reservation" | "commit" | "release";
|
|
8448
|
+
}>;
|
|
8449
|
+
},
|
|
8450
|
+
Name
|
|
8451
|
+
>;
|
|
8452
|
+
reconciliation: FunctionReference<
|
|
8453
|
+
"query",
|
|
8454
|
+
"internal",
|
|
8455
|
+
{ bindingJson: string },
|
|
8456
|
+
{
|
|
8457
|
+
acceptedScaledQuantity: string;
|
|
8458
|
+
consumedScaledQuantity: string;
|
|
8459
|
+
reason: string;
|
|
8460
|
+
repaired: false;
|
|
8461
|
+
reservedScaledQuantity: string;
|
|
8462
|
+
status: "matched" | "held";
|
|
8463
|
+
},
|
|
8464
|
+
Name
|
|
8465
|
+
>;
|
|
8466
|
+
status: FunctionReference<
|
|
8467
|
+
"query",
|
|
8468
|
+
"internal",
|
|
8469
|
+
{ bindingJson: string },
|
|
8470
|
+
string | null,
|
|
8471
|
+
Name
|
|
8472
|
+
>;
|
|
8473
|
+
};
|
|
8474
|
+
};
|
|
8381
8475
|
usageCatalog: {
|
|
8382
8476
|
mutations: {
|
|
8383
8477
|
complete: FunctionReference<
|
package/src/component/schema.ts
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
import {
|
|
2
|
+
policiesTable as usageAllowancePolicies,
|
|
3
|
+
historyTable as usageAllowanceHistory,
|
|
4
|
+
} from "./usageAllowance/schema.js";
|
|
1
5
|
import {
|
|
2
6
|
accountsTable as usageCreditAccounts,
|
|
3
7
|
purchasesTable as usageCreditPurchases,
|
|
@@ -116,6 +120,8 @@ import { pricesTable, productsTable } from "./products/schema";
|
|
|
116
120
|
import { webhookEventsTable } from "./webhooks/schema";
|
|
117
121
|
|
|
118
122
|
export default defineSchema({
|
|
123
|
+
usageAllowancePolicies,
|
|
124
|
+
usageAllowanceHistory,
|
|
119
125
|
usageSubscriptionControls,
|
|
120
126
|
usageSubscriptionIntents,
|
|
121
127
|
usageSubscriptionLocks,
|