@fantastic.dev/better-stripe 0.53.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +116 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +58 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +116 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +58 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +3 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/index.js +1 -0
  14. package/dist/client/index.js.map +1 -1
  15. package/dist/client/usage/client.d.ts +2 -2
  16. package/dist/client/usage/client.d.ts.map +1 -1
  17. package/dist/client/usage/client.js +3 -3
  18. package/dist/client/usage/client.js.map +1 -1
  19. package/dist/client/usage/deliveryClient.d.ts +64 -0
  20. package/dist/client/usage/deliveryClient.d.ts.map +1 -0
  21. package/dist/client/usage/deliveryClient.js +60 -0
  22. package/dist/client/usage/deliveryClient.js.map +1 -0
  23. package/dist/client/usage/deliveryProtocol.d.ts +130 -0
  24. package/dist/client/usage/deliveryProtocol.d.ts.map +1 -0
  25. package/dist/client/usage/deliveryProtocol.js +21 -0
  26. package/dist/client/usage/deliveryProtocol.js.map +1 -0
  27. package/dist/client/usage/deliveryProvider.d.ts +32 -0
  28. package/dist/client/usage/deliveryProvider.d.ts.map +1 -0
  29. package/dist/client/usage/deliveryProvider.js +127 -0
  30. package/dist/client/usage/deliveryProvider.js.map +1 -0
  31. package/dist/client/usage/index.d.ts +3 -0
  32. package/dist/client/usage/index.d.ts.map +1 -1
  33. package/dist/client/usage/index.js +1 -0
  34. package/dist/client/usage/index.js.map +1 -1
  35. package/dist/client/webhooks/handler.d.ts.map +1 -1
  36. package/dist/client/webhooks/handler.js +2 -1
  37. package/dist/client/webhooks/handler.js.map +1 -1
  38. package/dist/client/webhooks/meterErrors.d.ts +5 -0
  39. package/dist/client/webhooks/meterErrors.d.ts.map +1 -0
  40. package/dist/client/webhooks/meterErrors.js +98 -0
  41. package/dist/client/webhooks/meterErrors.js.map +1 -0
  42. package/dist/client/webhooks/v2.d.ts.map +1 -1
  43. package/dist/client/webhooks/v2.js +5 -0
  44. package/dist/client/webhooks/v2.js.map +1 -1
  45. package/dist/component/_generated/api.d.ts +14 -0
  46. package/dist/component/_generated/api.d.ts.map +1 -1
  47. package/dist/component/_generated/api.js.map +1 -1
  48. package/dist/component/_generated/component.d.ts +170 -0
  49. package/dist/component/_generated/component.d.ts.map +1 -1
  50. package/dist/component/balanceFunding/mutations.d.ts +43 -43
  51. package/dist/component/earnings/triggers.d.ts +104 -2
  52. package/dist/component/earnings/triggers.d.ts.map +1 -1
  53. package/dist/component/refundHistory/queries.d.ts +1 -1
  54. package/dist/component/schema.d.ts +58 -1
  55. package/dist/component/schema.js +3 -0
  56. package/dist/component/schema.js.map +1 -1
  57. package/dist/component/usage/schema.d.ts +96 -1
  58. package/dist/component/usage/schema.d.ts.map +1 -1
  59. package/dist/component/usage/schema.js +11 -2
  60. package/dist/component/usage/schema.js.map +1 -1
  61. package/dist/component/usageDelivery/bridge.d.ts +25 -0
  62. package/dist/component/usageDelivery/bridge.d.ts.map +1 -0
  63. package/dist/component/usageDelivery/bridge.js +45 -0
  64. package/dist/component/usageDelivery/bridge.js.map +1 -0
  65. package/dist/component/usageDelivery/fields.d.ts +78 -0
  66. package/dist/component/usageDelivery/fields.d.ts.map +1 -0
  67. package/dist/component/usageDelivery/fields.js +38 -0
  68. package/dist/component/usageDelivery/fields.js.map +1 -0
  69. package/dist/component/usageDelivery/helpers.d.ts +83 -0
  70. package/dist/component/usageDelivery/helpers.d.ts.map +1 -0
  71. package/dist/component/usageDelivery/helpers.js +63 -0
  72. package/dist/component/usageDelivery/helpers.js.map +1 -0
  73. package/dist/component/usageDelivery/mutations.d.ts +97 -0
  74. package/dist/component/usageDelivery/mutations.d.ts.map +1 -0
  75. package/dist/component/usageDelivery/mutations.js +153 -0
  76. package/dist/component/usageDelivery/mutations.js.map +1 -0
  77. package/dist/component/usageDelivery/queries.d.ts +113 -0
  78. package/dist/component/usageDelivery/queries.d.ts.map +1 -0
  79. package/dist/component/usageDelivery/queries.js +22 -0
  80. package/dist/component/usageDelivery/queries.js.map +1 -0
  81. package/dist/component/usageDelivery/schema.d.ts +79 -0
  82. package/dist/component/usageDelivery/schema.d.ts.map +1 -0
  83. package/dist/component/usageDelivery/schema.js +30 -0
  84. package/dist/component/usageDelivery/schema.js.map +1 -0
  85. package/dist/component/usageDelivery/steps.d.ts +85 -0
  86. package/dist/component/usageDelivery/steps.d.ts.map +1 -0
  87. package/dist/component/usageDelivery/steps.js +154 -0
  88. package/dist/component/usageDelivery/steps.js.map +1 -0
  89. package/dist/component/usageDelivery/workflow.d.ts +15 -0
  90. package/dist/component/usageDelivery/workflow.d.ts.map +1 -0
  91. package/dist/component/usageDelivery/workflow.js +28 -0
  92. package/dist/component/usageDelivery/workflow.js.map +1 -0
  93. package/docs/README.md +3 -1
  94. package/docs/metering-setup.md +1 -1
  95. package/docs/usage-delivery.md +143 -0
  96. package/package.json +3 -2
  97. package/src/client/index.ts +16 -0
  98. package/src/client/usage/client.ts +5 -2
  99. package/src/client/usage/deliveryClient.ts +130 -0
  100. package/src/client/usage/deliveryProtocol.ts +26 -0
  101. package/src/client/usage/deliveryProvider.test.ts +207 -0
  102. package/src/client/usage/deliveryProvider.ts +155 -0
  103. package/src/client/usage/index.ts +13 -0
  104. package/src/client/webhooks/handler.ts +2 -1
  105. package/src/client/webhooks/meterErrors.test.ts +164 -0
  106. package/src/client/webhooks/meterErrors.ts +118 -0
  107. package/src/client/webhooks/v2.ts +5 -0
  108. package/src/component/_generated/api.ts +14 -0
  109. package/src/component/_generated/component.ts +302 -0
  110. package/src/component/schema.ts +6 -0
  111. package/src/component/usage/schema.ts +11 -2
  112. package/src/component/usageDelivery/bridge.ts +56 -0
  113. package/src/component/usageDelivery/concurrency.test.ts +62 -0
  114. package/src/component/usageDelivery/fields.ts +59 -0
  115. package/src/component/usageDelivery/helpers.ts +77 -0
  116. package/src/component/usageDelivery/mutations.ts +185 -0
  117. package/src/component/usageDelivery/queries.ts +25 -0
  118. package/src/component/usageDelivery/schema.ts +33 -0
  119. package/src/component/usageDelivery/steps.ts +171 -0
  120. package/src/component/usageDelivery/workflow.test.ts +402 -0
  121. package/src/component/usageDelivery/workflow.ts +36 -0
@@ -0,0 +1,154 @@
1
+ import { internalMutation } from "../_generated/server.js";
2
+ import { v } from "convex/values";
3
+ import { refFields, request, status } from "./schema.js";
4
+ import { outcome } from "./fields.js";
5
+ import { read, statusOf, lockKeys } from "./helpers.js";
6
+ export const claim = internalMutation({
7
+ args: refFields,
8
+ returns: v.union(v.object({ kind: v.literal("ready"), request: v.object(request) }), v.object({ kind: v.literal("wait"), delayMs: v.number() }), v.object({ kind: v.literal("done") })),
9
+ handler: async (ctx, args) => {
10
+ const { outbox, record } = await read(ctx, args), now = Math.floor(Date.now() / 1000);
11
+ if (outbox.held ||
12
+ ["provider_accepted", "rejected", "unknown", "held"].includes(outbox.state))
13
+ return { kind: "done" };
14
+ if (record.occurredAt < now - 35 * 86400 ||
15
+ record.occurredAt > now + 300 ||
16
+ (outbox.firstSendAt !== undefined &&
17
+ now - outbox.firstSendAt >= 23 * 3600)) {
18
+ await ctx.db.patch("usageOutbox", outbox._id, {
19
+ state: outbox.firstSendAt === undefined ? "held" : "unknown",
20
+ reason: "delivery_window_expired",
21
+ });
22
+ return { kind: "done" };
23
+ }
24
+ if (outbox.state === "sending") {
25
+ if ((outbox.leaseUntil ?? 0) > now)
26
+ return {
27
+ kind: "wait",
28
+ delayMs: Math.min(60000, Math.max(1000, ((outbox.leaseUntil ?? now) - now) * 1000)),
29
+ };
30
+ await ctx.db.patch("usageOutbox", outbox._id, {
31
+ state: "unknown",
32
+ reason: "provider_outcome_unknown",
33
+ });
34
+ return { kind: "done" };
35
+ }
36
+ const keys = lockKeys(record);
37
+ const realm = await ctx.db
38
+ .query("usageDeliveryLocks")
39
+ .withIndex("by_key", (q) => q.eq("key", keys.realm))
40
+ .unique();
41
+ const customer = await ctx.db
42
+ .query("usageDeliveryLocks")
43
+ .withIndex("by_key", (q) => q.eq("key", keys.customer))
44
+ .unique();
45
+ const waitUntil = Math.max(outbox.nextAttemptAt, realm?.nextAttemptAt ?? 0, customer?.leaseUntil ?? 0);
46
+ if (waitUntil > now)
47
+ return {
48
+ kind: "wait",
49
+ delayMs: Math.min(60000, (waitUntil - now) * 1000),
50
+ };
51
+ const slot = { key: keys.realm, leaseUntil: 0, nextAttemptAt: now + 1 };
52
+ if (realm)
53
+ await ctx.db.patch("usageDeliveryLocks", realm._id, slot);
54
+ else
55
+ await ctx.db.insert("usageDeliveryLocks", slot);
56
+ const lock = {
57
+ key: keys.customer,
58
+ eventId: args.eventId,
59
+ leaseUntil: now + 900,
60
+ nextAttemptAt: 0,
61
+ };
62
+ if (customer)
63
+ await ctx.db.patch("usageDeliveryLocks", customer._id, lock);
64
+ else
65
+ await ctx.db.insert("usageDeliveryLocks", lock);
66
+ const attempt = outbox.attempts + 1;
67
+ await ctx.db.patch("usageOutbox", outbox._id, {
68
+ state: "sending",
69
+ attempts: attempt,
70
+ firstSendAt: outbox.firstSendAt ?? now,
71
+ leaseUntil: now + 900,
72
+ reason: undefined,
73
+ });
74
+ return {
75
+ kind: "ready",
76
+ request: {
77
+ ...args,
78
+ attempt,
79
+ definitionVersion: 1,
80
+ apiVersion: record.binding.apiVersion,
81
+ identifier: outbox.providerIdentifier,
82
+ },
83
+ };
84
+ },
85
+ });
86
+ export const save = internalMutation({
87
+ args: { ...request, outcome },
88
+ returns: status,
89
+ handler: async (ctx, args) => {
90
+ const { outbox, record } = await read(ctx, args);
91
+ if (outbox.attempts !== args.attempt ||
92
+ outbox.providerIdentifier !== args.identifier ||
93
+ record.binding.apiVersion !== args.apiVersion ||
94
+ outbox.definitionVersion !== args.definitionVersion)
95
+ throw new Error("Stale usage delivery receipt");
96
+ if (outbox.receipt || outbox.state === "rejected")
97
+ return statusOf(outbox);
98
+ const result = args.outcome, now = Math.floor(Date.now() / 1000);
99
+ const update = result.status === "accepted"
100
+ ? {
101
+ state: "provider_accepted",
102
+ receipt: { identifier: args.identifier, created: result.created },
103
+ reason: undefined,
104
+ }
105
+ : result.status === "unknown"
106
+ ? {
107
+ state: "unknown",
108
+ reason: "provider_outcome_unknown",
109
+ }
110
+ : result.status === "rejected"
111
+ ? {
112
+ state: "rejected",
113
+ reason: "provider_rejected",
114
+ }
115
+ : result.status === "unavailable"
116
+ ? {
117
+ state: "held",
118
+ reason: "provider_unavailable",
119
+ }
120
+ : {
121
+ state: outbox.held ? "held" : "queued",
122
+ reason: "rate_limited",
123
+ nextAttemptAt: now + Math.min(60, 2 ** Math.min(outbox.attempts, 6)),
124
+ };
125
+ await ctx.db.patch("usageOutbox", outbox._id, update);
126
+ if (result.status !== "unknown") {
127
+ const key = lockKeys(record).customer;
128
+ const lock = await ctx.db
129
+ .query("usageDeliveryLocks")
130
+ .withIndex("by_key", (q) => q.eq("key", key))
131
+ .unique();
132
+ if (lock?.eventId === args.eventId)
133
+ await ctx.db.patch("usageDeliveryLocks", lock._id, {
134
+ leaseUntil: 0,
135
+ eventId: undefined,
136
+ });
137
+ }
138
+ return statusOf((await read(ctx, args)).outbox);
139
+ },
140
+ });
141
+ export const exhaust = internalMutation({
142
+ args: refFields,
143
+ returns: v.null(),
144
+ handler: async (ctx, args) => {
145
+ const { outbox } = await read(ctx, args);
146
+ if (outbox.state === "queued")
147
+ await ctx.db.patch("usageOutbox", outbox._id, {
148
+ state: "held",
149
+ reason: "retry_exhausted",
150
+ });
151
+ return null;
152
+ },
153
+ });
154
+ //# sourceMappingURL=steps.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../src/component/usageDelivery/steps.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ export declare const run: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
2
+ scope: import("convex/values").VObject<{
3
+ customerAccount: string;
4
+ livemode: boolean;
5
+ meterId: string;
6
+ stripeAccountId: string;
7
+ }, {
8
+ stripeAccountId: import("convex/values").VString<string, "required">;
9
+ customerAccount: import("convex/values").VString<string, "required">;
10
+ meterId: import("convex/values").VString<string, "required">;
11
+ livemode: import("convex/values").VBoolean<boolean, "required">;
12
+ }, "required", "customerAccount" | "livemode" | "meterId" | "stripeAccountId">;
13
+ eventId: import("convex/values").VId<import("convex/values").GenericId<"usageEvents">, "required">;
14
+ }>, import("@convex-dev/workflow").WorkflowMutationResult<null>>;
15
+ //# sourceMappingURL=workflow.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/component/usageDelivery/workflow.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,GAAG;;;;;;;;;;;;;gEA+BZ,CAAC"}
@@ -0,0 +1,28 @@
1
+ import { anyApi } from "convex/server";
2
+ import { executionWorkflow } from "../durableExecution/runtime.js";
3
+ import { refFields } from "./schema.js";
4
+ import { v } from "convex/values";
5
+ export const run = executionWorkflow
6
+ .define({ args: refFields, returns: v.null() })
7
+ .handler(async (step, args) => {
8
+ let sends = 0;
9
+ for (let turn = 0; turn < 40; turn++) {
10
+ const claimed = await step.runMutation(anyApi.usageDelivery.steps.claim, args, { name: `claim-${turn}` });
11
+ if (claimed.kind === "done")
12
+ return null;
13
+ if (claimed.kind === "wait") {
14
+ await step.sleep(claimed.delayMs);
15
+ continue;
16
+ }
17
+ const outcome = await step.runAction(anyApi.usageDelivery.bridge.invoke, claimed.request, { name: `provider-${turn}`, retry: false });
18
+ const saved = await step.runMutation(anyApi.usageDelivery.steps.save, { ...claimed.request, outcome }, { name: "save-receipt" });
19
+ sends++;
20
+ if (saved.state !== "queued")
21
+ return null;
22
+ if (sends >= 3)
23
+ break;
24
+ }
25
+ await step.runMutation(anyApi.usageDelivery.steps.exhaust, args);
26
+ return null;
27
+ });
28
+ //# sourceMappingURL=workflow.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../../src/component/usageDelivery/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,MAAM,CAAC,MAAM,GAAG,GAAG,iBAAiB;KACjC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;KAC9C,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAiB,EAAE;IAC3C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CACpC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,EAChC,IAAI,EACJ,EAAE,IAAI,EAAE,SAAS,IAAI,EAAE,EAAE,CAC1B,CAAC;QACF,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACzC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAClC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAClC,OAAO,CAAC,OAAO,EACf,EAAE,IAAI,EAAE,YAAY,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAC3C,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAClC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,EAC/B,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAC/B,EAAE,IAAI,EAAE,cAAc,EAAE,CACzB,CAAC;QACF,KAAK,EAAE,CAAC;QACR,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,IAAI,KAAK,IAAI,CAAC;YAAE,MAAM;IACxB,CAAC;IACD,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC,CAAC,CAAC"}
package/docs/README.md CHANGED
@@ -24,7 +24,7 @@ guide for your integration.
24
24
  - [SetupIntent recovery](setup-intent-recovery.md).
25
25
  - [Balance funding state](balance-funding-state.md) and [workflow](balance-funding-workflow.md).
26
26
  - [Example balance funding cutover](example-balance-funding-cutover.md).
27
- - [Metered usage investigation](metered-usage.md), provider comparison and acceptance requirements. Shared contracts, catalog provisioning and local usage acceptance are available; delivery and credit accounting are in progress.
27
+ - [Metered usage investigation](metered-usage.md), provider comparison and acceptance requirements. Shared contracts, catalog provisioning and local usage acceptance are available; credit accounting is in progress.
28
28
 
29
29
  ## Marketplace, settlement, and recovery
30
30
 
@@ -60,3 +60,5 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
60
60
  [Atomic usage ledger and scoped history](usage-ledger.md) describes acceptance and retention.
61
61
 
62
62
  [Native usage catalog](usage-catalog.md) covers provisioning, immutable versions and typed price observations.
63
+
64
+ [Durable native delivery](usage-delivery.md) explains host actions, bounded retries, operational holds and asynchronous errors.
@@ -7,7 +7,7 @@ native Stripe integration into the existing BetterStripe Convex component.
7
7
 
8
8
  Current status: shared configuration/quantity helpers and repository sandbox probes
9
9
  are implemented. Atomic recording and bounded local history are available through the
10
- [usage ledger](usage-ledger.md). Durable provider delivery, allowance/credit
10
+ [usage ledger](usage-ledger.md). [Durable provider delivery](usage-delivery.md) is available. Allowance/credit
11
11
  accounting and the three example UI flows are still under development. The probes
12
12
  below verify provider behavior directly; they are not public BetterStripe billing
13
13
  workflows. See [metered usage contracts and evidence](metered-usage.md).
@@ -0,0 +1,143 @@
1
+ # Deliver accepted usage to native Stripe
2
+
3
+ Start with the [catalog](usage-catalog.md) and [atomic ledger](usage-ledger.md).
4
+ This layer sends the same immutable usage records for all three billing models.
5
+ It does not purchase prepaid credits, collect payment, finalize invoices or settle
6
+ seller proceeds. Native Stripe Billing Meters need no Metronome token.
7
+
8
+ ## Register a host internal provider action
9
+
10
+ The component owns the outbox, Workflow journal, rate limits and receipts. The
11
+ host owns credentials and authorization. Register this action in your Convex app:
12
+
13
+ ```ts
14
+ import { internalAction } from "./_generated/server";
15
+ import {
16
+ usageDeliveryArgs,
17
+ usageDeliveryResult,
18
+ } from "@fantastic.dev/better-stripe/usage";
19
+ import { stripe } from "./stripe"; // Your configured BetterStripe instance.
20
+
21
+ export const sendUsage = internalAction({
22
+ args: usageDeliveryArgs,
23
+ returns: usageDeliveryResult,
24
+ handler: (ctx, request) =>
25
+ stripe.usage.deliver(ctx, request, {
26
+ stripeSecretKey: process.env.STRIPE_SECRET_KEY,
27
+ }),
28
+ });
29
+ ```
30
+
31
+ Then record and dispatch from an authorized host mutation. Authenticate the actor,
32
+ authorize the exact realm/payer/meter, apply your billable-activity policy and
33
+ resolve the subscription binding from verified server state before this code:
34
+
35
+ ```ts
36
+ const receipt = await stripe.usage.record(ctx, {
37
+ event: serverEvent,
38
+ subscription: verifiedSubscription,
39
+ });
40
+ await stripe.usage.startDelivery(ctx, {
41
+ scope: serverEvent.scope,
42
+ eventId: receipt.eventId,
43
+ provider: internal.billing.sendUsage,
44
+ });
45
+ return receipt;
46
+ ```
47
+
48
+ Both calls participate in the host mutation transaction. A failed dispatch rolls
49
+ back acceptance too. Alternatively, accept without dispatch and start delivery
50
+ later from an internal worker. Never accept a provider function reference,
51
+ credential, price or unverified scope from a browser. Reauthorize every status,
52
+ hold and resume request. The internal provider action must use the package's
53
+ `deliver` helper and must not implement its own retry loop.
54
+
55
+ `startDeliveryBatch` accepts one scope, the same internal provider reference and
56
+ 1–10 event IDs. Each event has its own durable progress. If a host action fails
57
+ partway through dispatching a batch, replay its original IDs; completed dispatches
58
+ are idempotent. Delivery is individually submitted, with no unbounded native
59
+ batch or account-wide scan.
60
+
61
+ ## Execution and retries
62
+
63
+ The existing nested Workflow runtime runs at most two steps concurrently and
64
+ never retries provider actions automatically. Delivery additionally reserves a
65
+ single slot per native customer/meter across Accounts v2 payer aliases, and a
66
+ conservative account/mode rate of one send per second. Claims use Convex
67
+ transactions. A send lease lasts 15 minutes, beyond the host action execution
68
+ limit. The native helper rechecks its attempt and lease immediately before the
69
+ write. Native requests use a 15-second timeout and zero SDK network retries.
70
+
71
+ The immutable event pins its Stripe API version and routing/pricing snapshot.
72
+ Delivery definition version 1 and the internal provider handle are retained.
73
+ The outbox's `bs_usage_…` identifier is also the native idempotency key. Neither
74
+ identity changes on resume. Credentials are supplied at execution time and never
75
+ stored in outbox rows or Workflow arguments/results.
76
+
77
+ Known HTTP 429 responses back off exponentially, with at most three sends per
78
+ Workflow run and a 60-second delay ceiling. Other queued events retain their
79
+ progress. Missing credentials and preflight failures stop as `provider_unavailable`
80
+ until an administrator fixes the configuration and resumes. Explicit validation
81
+ rejections stop as `rejected`. Ambiguous responses, duplicate-identifier errors,
82
+ network loss and provider 5xx responses become `unknown` and retain the possible
83
+ effect. Raw SDK errors and response payloads do not enter the journal.
84
+
85
+ A failed receipt mutation can resume from that failed step using the already
86
+ journaled provider result. Do not restart from step zero, delete the outbox or
87
+ change the source identifier. A worker crash before the provider result is
88
+ journaled becomes unknown when its send lease expires.
89
+
90
+ New delivery must still fall within Stripe's 35-day past/5-minute future event
91
+ window. Automatic sends also stop 23 hours after the first send attempt. Stripe
92
+ retains deduplication for at least 24 hours, not forever. A historical acceptance
93
+ receipt remains valid after these windows expire, but does not authorize replay.
94
+ The adapter never changes the original occurrence time to make an event eligible.
95
+
96
+ ## Status and operational controls
97
+
98
+ Use `getDelivery(ctx, {scope, eventId})` for current delivery state, attempt count,
99
+ provider identifier, optional acceptance receipt and observed validation errors.
100
+ `provider_accepted` means transport acceptance. It does not prove successful
101
+ aggregation, invoice inclusion, finalization or payment. Keep the original ledger
102
+ receipt and later observations separate.
103
+
104
+ `holdDelivery` prevents future sends. It cannot abort an in-flight native request;
105
+ a later accepted receipt remains visible even while the administrative hold flag
106
+ is set. `resumeDelivery` clears a hold and starts or resumes compatible work after
107
+ known retryable failures. It never blindly replays unknown effects or expired
108
+ windows. Native Stripe has no per-event retrieve API that proves the fate of an
109
+ unknown submission. An aggregate total cannot prove an individual event's fate.
110
+ Investigate provider logs and reconciliation before any financial correction.
111
+
112
+ `cancelDelivery` returns a typed unsupported result. Holding work is not native
113
+ cancellation, an adjustment or a refund. Use the separately implemented correction
114
+ workflow when available and preserve the original event and payment provenance.
115
+ No deletion or financial-history cleanup API is provided here.
116
+
117
+ ## Receive asynchronous native validation errors
118
+
119
+ Configure a Stripe **thin** event destination for:
120
+
121
+ - `v1.billing.meter.error_report_triggered`
122
+ - `v1.billing.meter.no_meter_found`
123
+
124
+ Use the BetterStripe webhook route and configure its thin destination secret as
125
+ `webhookSecretV2`. The `v1.` names still carry thin payloads. The package selects
126
+ the thin signature verifier, retrieves the full event from Stripe, verifies its
127
+ account/mode and maps allowlisted sample identifiers to their original outbox
128
+ records. Destination/account context must match the configured key's own realm.
129
+ Organization or foreign account contexts are not silently substituted.
130
+
131
+ Observed errors are append-only and deduplicated by native report/event/code.
132
+ They do not overwrite transport acceptance or invoice history. Reads include at
133
+ most 20 errors plus `validationHistoryComplete` for this bounded local history.
134
+ This flag does not claim complete provider validation. Stripe reports samples;
135
+ unmatched identifiers, unsupported codes and truncated reports cannot prove that
136
+ all affected events were observed. The adapter bounds a report to 100 matched
137
+ samples, reports truncation and discards raw error messages and metadata.
138
+
139
+ Test locally with Stripe's thin-event forwarding and meter-error triggers before
140
+ production. Use the sandbox and verify webhook signatures. See Stripe's
141
+ [recording and error guide](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api),
142
+ [event creation contract](https://docs.stripe.com/api/billing/meter-event/create)
143
+ and [finite idempotency retention](https://docs.stripe.com/api/idempotent_requests).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.53.0",
3
+ "version": "0.54.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -102,7 +102,8 @@
102
102
  "docs/architecture.md",
103
103
  "docs/development.md",
104
104
  "docs/usage-ledger.md",
105
- "docs/usage-catalog.md"
105
+ "docs/usage-catalog.md",
106
+ "docs/usage-delivery.md"
106
107
  ],
107
108
  "scripts": {
108
109
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
@@ -1827,3 +1827,19 @@ export type {
1827
1827
  SubscriptionPaymentMethodOptions,
1828
1828
  SubscriptionPaymentMethodResult,
1829
1829
  } from "./billing/subscription-payment-method.js";
1830
+
1831
+ export type {
1832
+ UsageDeliveryRequest,
1833
+ UsageDeliveryOutcome,
1834
+ UsageDeliveryProviderOptions,
1835
+ } from "./usage/deliveryProvider.js";
1836
+ export type {
1837
+ UsageDeliveryRef,
1838
+ UsageDeliveryStatus,
1839
+ UsageDeliveryStartOptions,
1840
+ } from "./usage/deliveryClient.js";
1841
+
1842
+ export {
1843
+ usageDeliveryArgs,
1844
+ usageDeliveryResult,
1845
+ } from "./usage/deliveryProtocol.js";
@@ -1,3 +1,4 @@
1
+ import { UsageDeliveryClient } from "./deliveryClient.js";
1
2
  import type { Component, RunCtx } from "../helpers.js";
2
3
  import { runMutationOrThrow } from "../helpers.js";
3
4
  import { componentRef } from "../webhooks/helpers.js";
@@ -45,8 +46,10 @@ function decode({ event, delivery }: StoredView): UsageEventView {
45
46
  };
46
47
  }
47
48
  /** Trusted host facade. Authenticate and authorize each exact scope first. */
48
- export class UsageLedgerClient {
49
- constructor(private readonly component: Component) {}
49
+ export class UsageLedgerClient extends UsageDeliveryClient {
50
+ constructor(component: Component) {
51
+ super(component);
52
+ }
50
53
  async record(ctx: RunCtx, opts: RecordUsageOptions): Promise<UsageReceipt> {
51
54
  const event = prepareUsageRecord(opts.event);
52
55
  const input = {
@@ -0,0 +1,130 @@
1
+ import { createFunctionHandle, type FunctionReference } from "convex/server";
2
+ import { z } from "zod";
3
+ import type { Component, RunCtx } from "../helpers.js";
4
+ import { runMutationOrThrow } from "../helpers.js";
5
+ import { componentRef } from "../webhooks/helpers.js";
6
+ import {
7
+ scopeSchema,
8
+ type UsageScope,
9
+ type UsageDeliveryState,
10
+ } from "./records.js";
11
+ import {
12
+ deliverUsageProvider,
13
+ type UsageDeliveryRequest,
14
+ type UsageDeliveryOutcome,
15
+ type UsageDeliveryProviderOptions,
16
+ } from "./deliveryProvider.js";
17
+ export type UsageDeliveryRef = { scope: UsageScope; eventId: string };
18
+ export type UsageDeliveryStatus = {
19
+ validationErrors: Array<{
20
+ providerEventId: string;
21
+ code: string;
22
+ observedAt: number;
23
+ }>;
24
+ validationHistoryComplete: boolean;
25
+ eventId: string;
26
+ state: UsageDeliveryState;
27
+ attempts: number;
28
+ held: boolean;
29
+ reason?: string;
30
+ providerIdentifier: string;
31
+ receipt?: { identifier: string; created: number };
32
+ };
33
+ export type UsageDeliveryStartOptions = UsageDeliveryRef & {
34
+ provider: FunctionReference<
35
+ "action",
36
+ "internal",
37
+ UsageDeliveryRequest,
38
+ UsageDeliveryRequest & { outcome: UsageDeliveryOutcome }
39
+ >;
40
+ };
41
+ function ref(input: UsageDeliveryRef) {
42
+ return {
43
+ scope: scopeSchema.parse(input.scope),
44
+ eventId: z.string().min(1).max(100).parse(input.eventId),
45
+ };
46
+ }
47
+ export class UsageDeliveryClient {
48
+ constructor(protected readonly component: Component) {}
49
+ async startDelivery(
50
+ ctx: RunCtx,
51
+ opts: UsageDeliveryStartOptions,
52
+ ): Promise<UsageDeliveryStatus> {
53
+ return runMutationOrThrow(
54
+ ctx,
55
+ componentRef(this.component, "usageDelivery/mutations/start"),
56
+ {
57
+ ...ref(opts),
58
+ provider: await createFunctionHandle(opts.provider),
59
+ definitionVersion: 1,
60
+ },
61
+ );
62
+ }
63
+ async startDeliveryBatch(
64
+ ctx: RunCtx,
65
+ opts: {
66
+ scope: UsageScope;
67
+ eventIds: string[];
68
+ provider: UsageDeliveryStartOptions["provider"];
69
+ },
70
+ ) {
71
+ const ids = z
72
+ .array(z.string().min(1).max(100))
73
+ .min(1)
74
+ .max(10)
75
+ .parse(opts.eventIds);
76
+ const results: UsageDeliveryStatus[] = [];
77
+ for (const eventId of ids)
78
+ results.push(
79
+ await this.startDelivery(ctx, {
80
+ scope: opts.scope,
81
+ eventId,
82
+ provider: opts.provider,
83
+ }),
84
+ );
85
+ return results;
86
+ }
87
+ getDelivery(
88
+ ctx: RunCtx,
89
+ input: UsageDeliveryRef,
90
+ ): Promise<UsageDeliveryStatus> {
91
+ return ctx.runQuery(
92
+ componentRef(this.component, "usageDelivery/queries/get"),
93
+ ref(input),
94
+ );
95
+ }
96
+ holdDelivery(
97
+ ctx: RunCtx,
98
+ input: UsageDeliveryRef,
99
+ ): Promise<UsageDeliveryStatus> {
100
+ return runMutationOrThrow(
101
+ ctx,
102
+ componentRef(this.component, "usageDelivery/mutations/hold"),
103
+ ref(input),
104
+ );
105
+ }
106
+ resumeDelivery(
107
+ ctx: RunCtx,
108
+ input: UsageDeliveryRef,
109
+ ): Promise<UsageDeliveryStatus> {
110
+ return runMutationOrThrow(
111
+ ctx,
112
+ componentRef(this.component, "usageDelivery/mutations/resume"),
113
+ ref(input),
114
+ );
115
+ }
116
+ async cancelDelivery(ctx: RunCtx, input: UsageDeliveryRef) {
117
+ await this.getDelivery(ctx, input);
118
+ return {
119
+ status: "unsupported" as const,
120
+ reason: "native_event_cancellation_requires_adjustment" as const,
121
+ };
122
+ }
123
+ deliver(
124
+ ctx: RunCtx,
125
+ input: UsageDeliveryRequest,
126
+ options: UsageDeliveryProviderOptions,
127
+ ) {
128
+ return deliverUsageProvider(this.component, ctx, input, options);
129
+ }
130
+ }
@@ -0,0 +1,26 @@
1
+ import { v } from "convex/values";
2
+ /** Register only as a host internal action. Never accept provider options from a browser. */
3
+ export const usageDeliveryArgs = {
4
+ scope: v.object({
5
+ stripeAccountId: v.string(),
6
+ customerAccount: v.string(),
7
+ meterId: v.string(),
8
+ livemode: v.boolean(),
9
+ }),
10
+ eventId: v.string(),
11
+ attempt: v.number(),
12
+ definitionVersion: v.literal(1),
13
+ apiVersion: v.string(),
14
+ identifier: v.string(),
15
+ };
16
+ export const usageDeliveryOutcomeValidator = v.union(
17
+ v.object({ status: v.literal("accepted"), created: v.number() }),
18
+ v.object({ status: v.literal("rate_limited") }),
19
+ v.object({ status: v.literal("unavailable") }),
20
+ v.object({ status: v.literal("unknown") }),
21
+ v.object({ status: v.literal("rejected") }),
22
+ );
23
+ export const usageDeliveryResult = v.object({
24
+ ...usageDeliveryArgs,
25
+ outcome: usageDeliveryOutcomeValidator,
26
+ });