@fantastic.dev/better-stripe 0.54.0 → 0.55.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 (122) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +112 -34
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +40 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +112 -34
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +40 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +5 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/usage/client.d.ts +2 -2
  14. package/dist/client/usage/client.d.ts.map +1 -1
  15. package/dist/client/usage/client.js +2 -2
  16. package/dist/client/usage/client.js.map +1 -1
  17. package/dist/client/usage/index.d.ts +5 -0
  18. package/dist/client/usage/index.d.ts.map +1 -1
  19. package/dist/client/usage/invoiceObservation.d.ts +38 -0
  20. package/dist/client/usage/invoiceObservation.d.ts.map +1 -0
  21. package/dist/client/usage/invoiceObservation.js +157 -0
  22. package/dist/client/usage/invoiceObservation.js.map +1 -0
  23. package/dist/client/usage/observationClient.d.ts +83 -0
  24. package/dist/client/usage/observationClient.d.ts.map +1 -0
  25. package/dist/client/usage/observationClient.js +157 -0
  26. package/dist/client/usage/observationClient.js.map +1 -0
  27. package/dist/client/usage/observationTypes.d.ts +63 -0
  28. package/dist/client/usage/observationTypes.d.ts.map +1 -0
  29. package/dist/client/usage/observationTypes.js +59 -0
  30. package/dist/client/usage/observationTypes.js.map +1 -0
  31. package/dist/client/usage/providerObservation.d.ts +4 -0
  32. package/dist/client/usage/providerObservation.d.ts.map +1 -0
  33. package/dist/client/usage/providerObservation.js +96 -0
  34. package/dist/client/usage/providerObservation.js.map +1 -0
  35. package/dist/client/usage/reconciliation.d.ts +12 -0
  36. package/dist/client/usage/reconciliation.d.ts.map +1 -0
  37. package/dist/client/usage/reconciliation.js +48 -0
  38. package/dist/client/usage/reconciliation.js.map +1 -0
  39. package/dist/client/usage/summary.d.ts +50 -0
  40. package/dist/client/usage/summary.d.ts.map +1 -0
  41. package/dist/client/usage/summary.js +110 -0
  42. package/dist/client/usage/summary.js.map +1 -0
  43. package/dist/component/_generated/api.d.ts +8 -0
  44. package/dist/component/_generated/api.d.ts.map +1 -1
  45. package/dist/component/_generated/api.js.map +1 -1
  46. package/dist/component/_generated/component.d.ts +95 -0
  47. package/dist/component/_generated/component.d.ts.map +1 -1
  48. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  49. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  50. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  51. package/dist/component/earnings/triggers.d.ts +104 -18
  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 +40 -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 +7 -2
  58. package/dist/component/usage/schema.d.ts.map +1 -1
  59. package/dist/component/usageDelivery/fields.d.ts +1 -0
  60. package/dist/component/usageDelivery/fields.d.ts.map +1 -1
  61. package/dist/component/usageDelivery/fields.js +1 -0
  62. package/dist/component/usageDelivery/fields.js.map +1 -1
  63. package/dist/component/usageDelivery/helpers.d.ts +1 -0
  64. package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
  65. package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
  66. package/dist/component/usageDelivery/mutations.js +8 -1
  67. package/dist/component/usageDelivery/mutations.js.map +1 -1
  68. package/dist/component/usageDelivery/queries.d.ts +2 -0
  69. package/dist/component/usageDelivery/queries.d.ts.map +1 -1
  70. package/dist/component/usageDelivery/steps.d.ts.map +1 -1
  71. package/dist/component/usageDelivery/steps.js +8 -1
  72. package/dist/component/usageDelivery/steps.js.map +1 -1
  73. package/dist/component/usageObservations/helpers.d.ts +38 -0
  74. package/dist/component/usageObservations/helpers.d.ts.map +1 -0
  75. package/dist/component/usageObservations/helpers.js +80 -0
  76. package/dist/component/usageObservations/helpers.js.map +1 -0
  77. package/dist/component/usageObservations/history.d.ts +6 -0
  78. package/dist/component/usageObservations/history.d.ts.map +1 -0
  79. package/dist/component/usageObservations/history.js +29 -0
  80. package/dist/component/usageObservations/history.js.map +1 -0
  81. package/dist/component/usageObservations/mutations.d.ts +6 -0
  82. package/dist/component/usageObservations/mutations.d.ts.map +1 -0
  83. package/dist/component/usageObservations/mutations.js +39 -0
  84. package/dist/component/usageObservations/mutations.js.map +1 -0
  85. package/dist/component/usageObservations/queries.d.ts +78 -0
  86. package/dist/component/usageObservations/queries.d.ts.map +1 -0
  87. package/dist/component/usageObservations/queries.js +131 -0
  88. package/dist/component/usageObservations/queries.js.map +1 -0
  89. package/dist/component/usageObservations/schema.d.ts +72 -0
  90. package/dist/component/usageObservations/schema.d.ts.map +1 -0
  91. package/dist/component/usageObservations/schema.js +29 -0
  92. package/dist/component/usageObservations/schema.js.map +1 -0
  93. package/docs/README.md +2 -0
  94. package/docs/metering-setup.md +2 -0
  95. package/docs/usage-observations.md +152 -0
  96. package/package.json +3 -2
  97. package/src/client/index.ts +18 -0
  98. package/src/client/usage/client.ts +2 -2
  99. package/src/client/usage/index.ts +18 -0
  100. package/src/client/usage/invoiceObservation.test.ts +195 -0
  101. package/src/client/usage/invoiceObservation.ts +203 -0
  102. package/src/client/usage/observationClient.ts +233 -0
  103. package/src/client/usage/observationTypes.ts +101 -0
  104. package/src/client/usage/providerObservation.test.ts +207 -0
  105. package/src/client/usage/providerObservation.ts +124 -0
  106. package/src/client/usage/reconciliation.test.ts +117 -0
  107. package/src/client/usage/reconciliation.ts +86 -0
  108. package/src/client/usage/summary.test.ts +222 -0
  109. package/src/client/usage/summary.ts +188 -0
  110. package/src/component/_generated/api.ts +8 -0
  111. package/src/component/_generated/component.ts +135 -0
  112. package/src/component/schema.ts +6 -0
  113. package/src/component/usageDelivery/fields.ts +1 -0
  114. package/src/component/usageDelivery/mutations.ts +26 -1
  115. package/src/component/usageDelivery/steps.ts +39 -1
  116. package/src/component/usageObservations/helpers.ts +95 -0
  117. package/src/component/usageObservations/history.test.ts +87 -0
  118. package/src/component/usageObservations/history.ts +39 -0
  119. package/src/component/usageObservations/mutations.ts +39 -0
  120. package/src/component/usageObservations/queries.test.ts +162 -0
  121. package/src/component/usageObservations/queries.ts +145 -0
  122. package/src/component/usageObservations/schema.ts +40 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queries.js","sourceRoot":"","sources":["../../../src/component/usageObservations/queries.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,72 @@
1
+ export declare const observationsTable: import("convex/server").TableDefinition<import("convex/values").VObject<{
2
+ key: string;
3
+ observationJson: string;
4
+ scopeKey: string;
5
+ sourceJson: string;
6
+ startedAt: number;
7
+ }, {
8
+ key: import("convex/values").VString<string, "required">;
9
+ scopeKey: import("convex/values").VString<string, "required">;
10
+ sourceJson: import("convex/values").VString<string, "required">;
11
+ observationJson: import("convex/values").VString<string, "required">;
12
+ startedAt: import("convex/values").VFloat64<number, "required">;
13
+ }, "required", "key" | "observationJson" | "scopeKey" | "sourceJson" | "startedAt">, {
14
+ by_key: ["key", "_creationTime"];
15
+ }, {}, {}>;
16
+ export declare const historyPhase: import("convex/values").VUnion<"accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired", [import("convex/values").VLiteral<"started", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"rate_limited", "required">, import("convex/values").VLiteral<"unavailable", "required">, import("convex/values").VLiteral<"unknown", "required">, import("convex/values").VLiteral<"rejected", "required">, import("convex/values").VLiteral<"held", "required">, import("convex/values").VLiteral<"resumed", "required">, import("convex/values").VLiteral<"window_expired", "required">, import("convex/values").VLiteral<"retry_exhausted", "required">], "required", never>;
17
+ export declare const historyFields: {
18
+ scopeKey: import("convex/values").VString<string, "required">;
19
+ eventId: import("convex/values").VId<import("convex/values").GenericId<"usageEvents">, "required">;
20
+ sequence: import("convex/values").VFloat64<number, "required">;
21
+ attempt: import("convex/values").VFloat64<number, "required">;
22
+ phase: import("convex/values").VUnion<"accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired", [import("convex/values").VLiteral<"started", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"rate_limited", "required">, import("convex/values").VLiteral<"unavailable", "required">, import("convex/values").VLiteral<"unknown", "required">, import("convex/values").VLiteral<"rejected", "required">, import("convex/values").VLiteral<"held", "required">, import("convex/values").VLiteral<"resumed", "required">, import("convex/values").VLiteral<"window_expired", "required">, import("convex/values").VLiteral<"retry_exhausted", "required">], "required", never>;
23
+ identity: import("convex/values").VString<string, "required">;
24
+ recordedAt: import("convex/values").VFloat64<number, "required">;
25
+ created: import("convex/values").VFloat64<number | undefined, "optional">;
26
+ };
27
+ export declare const historyDoc: import("convex/values").VObject<{
28
+ _creationTime: number;
29
+ _id: import("convex/values").GenericId<"usageDeliveryHistory">;
30
+ attempt: number;
31
+ created?: number | undefined;
32
+ eventId: import("convex/values").GenericId<"usageEvents">;
33
+ identity: string;
34
+ phase: "accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired";
35
+ recordedAt: number;
36
+ scopeKey: string;
37
+ sequence: number;
38
+ }, {
39
+ scopeKey: import("convex/values").VString<string, "required">;
40
+ eventId: import("convex/values").VId<import("convex/values").GenericId<"usageEvents">, "required">;
41
+ sequence: import("convex/values").VFloat64<number, "required">;
42
+ attempt: import("convex/values").VFloat64<number, "required">;
43
+ phase: import("convex/values").VUnion<"accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired", [import("convex/values").VLiteral<"started", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"rate_limited", "required">, import("convex/values").VLiteral<"unavailable", "required">, import("convex/values").VLiteral<"unknown", "required">, import("convex/values").VLiteral<"rejected", "required">, import("convex/values").VLiteral<"held", "required">, import("convex/values").VLiteral<"resumed", "required">, import("convex/values").VLiteral<"window_expired", "required">, import("convex/values").VLiteral<"retry_exhausted", "required">], "required", never>;
44
+ identity: import("convex/values").VString<string, "required">;
45
+ recordedAt: import("convex/values").VFloat64<number, "required">;
46
+ created: import("convex/values").VFloat64<number | undefined, "optional">;
47
+ _id: import("convex/values").VId<import("convex/values").GenericId<"usageDeliveryHistory">, "required">;
48
+ _creationTime: import("convex/values").VFloat64<number, "required">;
49
+ }, "required", "_creationTime" | "_id" | "attempt" | "created" | "eventId" | "identity" | "phase" | "recordedAt" | "scopeKey" | "sequence">;
50
+ export declare const historyTable: import("convex/server").TableDefinition<import("convex/values").VObject<{
51
+ attempt: number;
52
+ created?: number | undefined;
53
+ eventId: import("convex/values").GenericId<"usageEvents">;
54
+ identity: string;
55
+ phase: "accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired";
56
+ recordedAt: number;
57
+ scopeKey: string;
58
+ sequence: number;
59
+ }, {
60
+ scopeKey: import("convex/values").VString<string, "required">;
61
+ eventId: import("convex/values").VId<import("convex/values").GenericId<"usageEvents">, "required">;
62
+ sequence: import("convex/values").VFloat64<number, "required">;
63
+ attempt: import("convex/values").VFloat64<number, "required">;
64
+ phase: import("convex/values").VUnion<"accepted" | "held" | "rate_limited" | "rejected" | "resumed" | "retry_exhausted" | "started" | "unavailable" | "unknown" | "window_expired", [import("convex/values").VLiteral<"started", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"rate_limited", "required">, import("convex/values").VLiteral<"unavailable", "required">, import("convex/values").VLiteral<"unknown", "required">, import("convex/values").VLiteral<"rejected", "required">, import("convex/values").VLiteral<"held", "required">, import("convex/values").VLiteral<"resumed", "required">, import("convex/values").VLiteral<"window_expired", "required">, import("convex/values").VLiteral<"retry_exhausted", "required">], "required", never>;
65
+ identity: import("convex/values").VString<string, "required">;
66
+ recordedAt: import("convex/values").VFloat64<number, "required">;
67
+ created: import("convex/values").VFloat64<number | undefined, "optional">;
68
+ }, "required", "attempt" | "created" | "eventId" | "identity" | "phase" | "recordedAt" | "scopeKey" | "sequence">, {
69
+ by_event_identity: ["eventId", "identity", "_creationTime"];
70
+ by_event_sequence: ["eventId", "sequence", "_creationTime"];
71
+ }, {}, {}>;
72
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/component/usageObservations/schema.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;UAMH,CAAC;AAE5B,eAAO,MAAM,YAAY,oxBAWxB,CAAC;AACF,eAAO,MAAM,aAAa;IACxB,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,OAAO;IACP,KAAK;IACL,QAAQ;IACR,UAAU;IACV,OAAO;CACR,CAAC;AACF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;2IAIrB,CAAC;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;UAE6B,CAAC"}
@@ -0,0 +1,29 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ export const observationsTable = defineTable({
4
+ key: v.string(),
5
+ scopeKey: v.string(),
6
+ sourceJson: v.string(),
7
+ observationJson: v.string(),
8
+ startedAt: v.number(),
9
+ }).index("by_key", ["key"]);
10
+ export const historyPhase = v.union(v.literal("started"), v.literal("accepted"), v.literal("rate_limited"), v.literal("unavailable"), v.literal("unknown"), v.literal("rejected"), v.literal("held"), v.literal("resumed"), v.literal("window_expired"), v.literal("retry_exhausted"));
11
+ export const historyFields = {
12
+ scopeKey: v.string(),
13
+ eventId: v.id("usageEvents"),
14
+ sequence: v.number(),
15
+ attempt: v.number(),
16
+ phase: historyPhase,
17
+ identity: v.string(),
18
+ recordedAt: v.number(),
19
+ created: v.optional(v.number()),
20
+ };
21
+ export const historyDoc = v.object({
22
+ _id: v.id("usageDeliveryHistory"),
23
+ _creationTime: v.number(),
24
+ ...historyFields,
25
+ });
26
+ export const historyTable = defineTable(historyFields)
27
+ .index("by_event_sequence", ["eventId", "sequence"])
28
+ .index("by_event_identity", ["eventId", "identity"]);
29
+ //# sourceMappingURL=schema.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/component/usageObservations/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;IAC3C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAE5B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CACjC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EACrB,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,EACzB,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EACxB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EACrB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAC3B,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAC7B,CAAC;AACF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAChC,CAAC;AACF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,sBAAsB,CAAC;IACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,GAAG,aAAa;CACjB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC,aAAa,CAAC;KACnD,KAAK,CAAC,mBAAmB,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;KACnD,KAAK,CAAC,mBAAmB,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC"}
package/docs/README.md CHANGED
@@ -62,3 +62,5 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
62
62
  [Native usage catalog](usage-catalog.md) covers provisioning, immutable versions and typed price observations.
63
63
 
64
64
  [Durable native delivery](usage-delivery.md) explains host actions, bounded retries, operational holds and asynchronous errors.
65
+
66
+ [Usage observations and reconciliation](usage-observations.md) covers exact summaries, paginated audit history, native freshness and invoice observations.
@@ -184,3 +184,5 @@ Primary references:
184
184
  - [Metronome quickstart](https://docs.metronome.com/guides/get-started/api-quickstart)
185
185
 
186
186
  Use the [native catalog guide](usage-catalog.md) to provision versioned meters and prices through BetterStripe.
187
+
188
+ Use the [usage observation guide](usage-observations.md) for bounded local reads, native aggregate refreshes and honest invoice/credit availability.
@@ -0,0 +1,152 @@
1
+ # Read and reconcile usage
2
+
3
+ BetterStripe keeps local acceptance, transport acceptance, native aggregates,
4
+ estimates and invoices separate. Start with [setup](metering-setup.md), the
5
+ [catalog](usage-catalog.md), [ledger](usage-ledger.md) and
6
+ [delivery](usage-delivery.md). Authenticate and authorize the exact Stripe realm,
7
+ payer and meter before every read, page or reconciliation call. Resolve the
8
+ original binding and subscription snapshot on the server.
9
+
10
+ ## Local summaries and history
11
+
12
+ ```ts
13
+ const local = await stripe.usage.getSummary(ctx, {
14
+ scope: verifiedScope,
15
+ period: { start, end }, // Unix seconds, half-open.
16
+ maxRecords: 100,
17
+ });
18
+ ```
19
+
20
+ The indexed summary reads at most `maxRecords + 1` immutable records, with a
21
+ budget of 1–500 and a default of 100. `complete: false` means the result is only a
22
+ bounded prefix. It never presents that prefix as a complete bill or silently
23
+ assumes missing history is zero. Use the ledger's paginated `read` to export a
24
+ larger period. An empty complete local result means no local events were found;
25
+ it says nothing about native Stripe usage.
26
+
27
+ Groups retain the original plan, version, unit, currency, customer, price and
28
+ subscription item/period. Quantities and decimal minor currency amounts are
29
+ strings. There is no combined money total across currencies or plan versions.
30
+ Each group distinguishes locally accepted quantities, transport-accepted
31
+ quantities and quantities by current delivery state. Validation-error counts
32
+ count events with observed errors, not a complete inventory of provider errors.
33
+
34
+ Pay-as-you-go estimates apply the original exact rate. Included-unit projections
35
+ require a complete original billing period and apply that period's allowance
36
+ before the overage rate. Partial periods, overlapping native subscription
37
+ items and multiple original bindings within an overlapping period return
38
+ unavailable estimates. A plan or price change on the same item does not reset
39
+ the local allowance. Estimates exclude taxes, discounts, fixed
40
+ fees, rounding and other invoice lines. They are not finalized amounts or limits
41
+ that authorize work. Strict allowance reservations are implemented separately.
42
+ Prepaid balance/estimate fields remain explicitly unavailable until the prepaid
43
+ accounting APIs are configured. They never infer available credits from usage.
44
+
45
+ `read(ctx, {scope, page: {period, limit, cursor}})` returns immutable event history
46
+ with current delivery state. For an event's delivery audit:
47
+
48
+ ```ts
49
+ const attempts = await stripe.usage.readDeliveryHistory(ctx, {
50
+ scope: verifiedScope,
51
+ eventId,
52
+ limit: 20,
53
+ cursor: null,
54
+ });
55
+ const errors = await stripe.usage.readValidationHistory(ctx, {
56
+ scope: verifiedScope,
57
+ eventId,
58
+ limit: 20,
59
+ cursor: null,
60
+ });
61
+ ```
62
+
63
+ Both return `records`, `cursor` and `isDone`. Page sizes are 1–100; continue until
64
+ `isDone`, including an empty final page when required. Delivery history appends
65
+ started attempts, outcomes and operational holds/resumes independently of the
66
+ Workflow journal. Idempotent receipt projection does not duplicate audit entries.
67
+ `legacyHistoryMissing` identifies events whose earlier attempts predate this
68
+ history implementation. History is not reconstructed from guesses. Validation
69
+ history contains only provider samples that were actually observed. Correction
70
+ history is a typed unsupported state until the correction workflow is installed.
71
+
72
+ ## Native aggregates and cached freshness
73
+
74
+ Construct one server-owned observation request using the original binding and
75
+ subscription snapshot:
76
+
77
+ ```ts
78
+ const request = {
79
+ scope: verifiedScope,
80
+ binding: originalBinding,
81
+ subscription: originalSubscription,
82
+ period: { start, end },
83
+ limit: 100,
84
+ cursor: null,
85
+ };
86
+
87
+ // In an authorized action, with the secret resolved at execution time.
88
+ const result = await stripe.usage.reconcile(ctx, request, {
89
+ stripeSecretKey: process.env.STRIPE_SECRET_KEY,
90
+ });
91
+
92
+ // In an authorized reactive query, without a Stripe key or network call.
93
+ const cached = await stripe.usage.getReconciliation(ctx, {
94
+ ...request,
95
+ maxAgeSeconds: 60,
96
+ maxRecords: 100,
97
+ });
98
+ ```
99
+
100
+ `observeProviderUsage` refreshes only the native observation.
101
+ `getProviderUsage` reads only its scoped cache. One refresh makes a bounded native
102
+ page request, with a maximum page size of 100 and zero SDK retries. There is no
103
+ automatic polling loop. Use explicit, bounded refreshes, normally at least a
104
+ minute apart, and keep transient failures visible. Cache identity includes the
105
+ original scope, binding, subscription, exact period and page request. Older
106
+ in-flight refreshes cannot replace a newer projection.
107
+
108
+ Stripe requires minute-aligned aggregate start/end times. The adapter returns
109
+ `unsupported` for unaligned periods and never rounds a billing period to hide
110
+ that difference. An empty native response is `aggregation_pending`, not zero.
111
+ An explicit native zero remains a zero observation with aggregation lag possible.
112
+ Missing pages, overlapping buckets or incomplete period coverage cannot establish
113
+ a complete total. Unsafe integer or fractional provider values are reported as
114
+ unsupported precision because this adapter submits scaled integer units. It never
115
+ rounds a provider number to fit the local quantity contract.
116
+
117
+ Cached available data carries `observedAt` and `stale`. The default freshness
118
+ limit is 60 seconds; hosts may choose 1–86,400 seconds. Fresh transport responses
119
+ can still contain lagging Stripe aggregates. `aggregationLagPossible` stays true.
120
+ Native customer/meter reads require the key's own verified account and mode and
121
+ the original Accounts v2 payer/subscription mapping. Foreign key/context modes
122
+ return typed unsupported or unavailable results.
123
+
124
+ Reconciliation returns independent `local`, `aggregate`, `comparison` and invoice/
125
+ correction availability. `observed_match` means only that complete, fresh observed
126
+ transport quantities equal the observed aggregate for that exact period. It does
127
+ not prove invoice inclusion or payment. Incomplete local history, stale/incomplete
128
+ provider data, unresolved sends and ambiguous terms prevent comparison. A
129
+ mismatch can reflect aggregation lag, external usage or validation errors.
130
+ Reconciliation never resends, cancels, reroutes or reprices billable usage.
131
+
132
+ ## Invoice observations
133
+
134
+ From an authorized action, use `readInvoiceUsage(ctx, request, providerOptions)`
135
+ for a native preview. Add `invoiceId` to request a specific existing invoice.
136
+ This verifies its realm/mode, Accounts v2 payer, native customer and subscription.
137
+ The result distinguishes whole-invoice amounts from matching metered lines,
138
+ preserves full decimal quantities and nullable tiered unit amounts, and reports
139
+ whether the native line page is complete. Missing or ambiguous lines do not become
140
+ a zero meter amount. Native line periods are preserved with Stripe's semantics.
141
+
142
+ Previews remain previews. Only an existing invoice with native finalization
143
+ evidence is marked finalized. `paymentEvidence: "not_resolved"` applies even to a
144
+ paid invoice: credits or out-of-band marking can pay an invoice without new cash.
145
+ Use the separate payment-provenance and settlement APIs before distributing money.
146
+ These readers never finalize, charge, refund or settle an invoice. The generic
147
+ reconciliation result leaves invoices unavailable until explicitly observed.
148
+
149
+ Authoritative references: [native aggregate period and pagination rules](https://docs.stripe.com/api/billing/meter-event-summary/list),
150
+ [asynchronous aggregation and invoice cutoffs](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api),
151
+ [invoice previews](https://docs.stripe.com/api/invoices/create_preview), and
152
+ [full-precision invoice line quantities](https://docs.stripe.com/api/invoice-line-item/object).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.54.0",
3
+ "version": "0.55.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -103,7 +103,8 @@
103
103
  "docs/development.md",
104
104
  "docs/usage-ledger.md",
105
105
  "docs/usage-catalog.md",
106
- "docs/usage-delivery.md"
106
+ "docs/usage-delivery.md",
107
+ "docs/usage-observations.md"
107
108
  ],
108
109
  "scripts": {
109
110
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
@@ -1843,3 +1843,21 @@ export {
1843
1843
  usageDeliveryArgs,
1844
1844
  usageDeliveryResult,
1845
1845
  } from "./usage/deliveryProtocol.js";
1846
+
1847
+ export type {
1848
+ UsageObservationOptions,
1849
+ UsageAggregateValue,
1850
+ UsageAggregateObservation,
1851
+ } from "./usage/observationTypes.js";
1852
+ export type {
1853
+ UsageLocalSummary,
1854
+ UsageLocalGroup,
1855
+ UsageCreditSummary,
1856
+ } from "./usage/summary.js";
1857
+ export type { UsageComparison } from "./usage/reconciliation.js";
1858
+ export type { UsageReconciliationOptions } from "./usage/observationClient.js";
1859
+
1860
+ export type {
1861
+ UsageInvoiceObservation,
1862
+ UsageInvoiceLine,
1863
+ } from "./usage/invoiceObservation.js";
@@ -1,4 +1,4 @@
1
- import { UsageDeliveryClient } from "./deliveryClient.js";
1
+ import { UsageObservationClient } from "./observationClient.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 UsageDeliveryClient {
49
+ export class UsageLedgerClient extends UsageObservationClient {
50
50
  constructor(component: Component) {
51
51
  super(component);
52
52
  }
@@ -45,3 +45,21 @@ export type {
45
45
  } from "./deliveryClient.js";
46
46
 
47
47
  export { usageDeliveryArgs, usageDeliveryResult } from "./deliveryProtocol.js";
48
+
49
+ export type {
50
+ UsageObservationOptions,
51
+ UsageAggregateValue,
52
+ UsageAggregateObservation,
53
+ } from "./observationTypes.js";
54
+ export type {
55
+ UsageLocalSummary,
56
+ UsageLocalGroup,
57
+ UsageCreditSummary,
58
+ } from "./summary.js";
59
+ export type { UsageComparison } from "./reconciliation.js";
60
+ export type { UsageReconciliationOptions } from "./observationClient.js";
61
+
62
+ export type {
63
+ UsageInvoiceObservation,
64
+ UsageInvoiceLine,
65
+ } from "./invoiceObservation.js";
@@ -0,0 +1,195 @@
1
+ import Stripe from "stripe";
2
+ import { convexToJson } from "convex/values";
3
+ import { expect, it } from "vitest";
4
+ import { STRIPE_API_VERSION } from "../constants.js";
5
+ import { prepareUsageRecord } from "./records.js";
6
+ import { observeUsageInvoice } from "./invoiceObservation.js";
7
+ const scope = {
8
+ stripeAccountId: "acct_platform",
9
+ customerAccount: "acct_buyer",
10
+ meterId: "mtr_calls",
11
+ livemode: false,
12
+ },
13
+ period = { start: 600, end: 1200 };
14
+ const binding = prepareUsageRecord({
15
+ scope,
16
+ binding: {
17
+ stripeCustomerId: "cus_buyer",
18
+ stripePriceId: "price_calls",
19
+ eventName: "calls",
20
+ plan: {
21
+ key: "calls",
22
+ version: "v1",
23
+ model: "pay_as_you_go",
24
+ unit: { name: "call", precision: 0 },
25
+ rate: { currency: "usd", unitAmountDecimal: "2" },
26
+ },
27
+ },
28
+ sourceEventId: "read",
29
+ quantity: "0",
30
+ occurredAt: 600,
31
+ }).binding;
32
+ const options = {
33
+ scope,
34
+ binding,
35
+ subscription: {
36
+ subscriptionId: "sub_calls",
37
+ subscriptionItemId: "si_calls",
38
+ stripePriceId: "price_calls",
39
+ period,
40
+ interval: "month" as const,
41
+ },
42
+ period,
43
+ };
44
+ function setup(hasMore = false, wrongPayer = false, missingQuantity = false) {
45
+ const requests: Array<{ method: string; path: string }> = [];
46
+ const stripe = new Stripe("sk_test_invoice_read", {
47
+ apiVersion: STRIPE_API_VERSION,
48
+ maxNetworkRetries: 0,
49
+ httpClient: Stripe.createFetchHttpClient(async (input, init) => {
50
+ const url = new URL(String(input)),
51
+ path = url.pathname;
52
+ requests.push({ method: init?.method ?? "GET", path });
53
+ const result =
54
+ path === "/v1/account"
55
+ ? { id: "acct_platform" }
56
+ : path === "/v1/balance"
57
+ ? { livemode: false }
58
+ : path === "/v1/billing/meters/mtr_calls"
59
+ ? {
60
+ id: "mtr_calls",
61
+ livemode: false,
62
+ status: "active",
63
+ event_name: "calls",
64
+ default_aggregation: { formula: "sum" },
65
+ customer_mapping: {
66
+ type: "by_id",
67
+ event_payload_key: "stripe_customer_id",
68
+ },
69
+ value_settings: { event_payload_key: "value" },
70
+ event_time_window: null,
71
+ }
72
+ : path === "/v1/subscriptions/sub_calls"
73
+ ? {
74
+ id: "sub_calls",
75
+ livemode: false,
76
+ customer: "cus_buyer",
77
+ customer_account: "acct_buyer",
78
+ }
79
+ : {
80
+ id: "in_one",
81
+ object: "invoice",
82
+ livemode: false,
83
+ customer_account: wrongPayer ? "acct_other" : "acct_buyer",
84
+ customer: "cus_buyer",
85
+ currency: "usd",
86
+ status: path.endsWith("create_preview") ? "draft" : "paid",
87
+ status_transitions: {
88
+ finalized_at: path.endsWith("create_preview")
89
+ ? null
90
+ : 1200,
91
+ },
92
+ amount_due: 20,
93
+ amount_paid: 20,
94
+ total: 20,
95
+ parent: {
96
+ subscription_details: { subscription: "sub_calls" },
97
+ },
98
+ lines: {
99
+ data: [
100
+ {
101
+ id: "il_one",
102
+ object: "line_item",
103
+ currency: "usd",
104
+ amount: 10,
105
+ quantity: 2,
106
+ quantity_decimal: missingQuantity ? null : "2.5",
107
+ pricing: {
108
+ type: "price_details",
109
+ price_details: { price: "price_calls" },
110
+ unit_amount_decimal: null,
111
+ },
112
+ parent: {
113
+ subscription_item_details: {
114
+ subscription: "sub_calls",
115
+ subscription_item: "si_calls",
116
+ proration: false,
117
+ },
118
+ },
119
+ period,
120
+ pretax_credit_amounts: [],
121
+ },
122
+ ],
123
+ has_more: hasMore,
124
+ },
125
+ };
126
+ return new Response(JSON.stringify(result), {
127
+ status: 200,
128
+ headers: { "content-type": "application/json" },
129
+ });
130
+ }),
131
+ });
132
+ return { stripe, requests };
133
+ }
134
+ it("distinguishes full invoice amounts and matching metered lines with decimal quantities", async () => {
135
+ const f = setup(),
136
+ result = await observeUsageInvoice(f.stripe, options, "in_one");
137
+ expect(result).toMatchObject({
138
+ status: "available",
139
+ value: {
140
+ kind: "invoice",
141
+ invoiceId: "in_one",
142
+ finalized: true,
143
+ amountDue: "20",
144
+ amountPaid: "20",
145
+ total: "20",
146
+ meterAmount: {
147
+ status: "available",
148
+ value: { amount: "10", currency: "usd" },
149
+ },
150
+ lines: [{ quantity: "2.5", unitAmountDecimal: null }],
151
+ },
152
+ });
153
+ expect(() => convexToJson(result)).not.toThrow();
154
+ expect(f.requests.every((r) => r.method === "GET")).toBe(true);
155
+ });
156
+ it("does not call a preview finalized or an incomplete line page a complete meter amount", async () => {
157
+ const f = setup(true),
158
+ result = await observeUsageInvoice(f.stripe, options);
159
+ expect(result).toMatchObject({
160
+ status: "available",
161
+ value: {
162
+ kind: "preview",
163
+ finalized: false,
164
+ linesComplete: false,
165
+ meterAmount: {
166
+ status: "unavailable",
167
+ reason: "invoice_history_incomplete",
168
+ },
169
+ },
170
+ });
171
+ expect(f.requests.filter((r) => r.method === "POST")).toEqual([
172
+ { method: "POST", path: "/v1/invoices/create_preview" },
173
+ ]);
174
+ });
175
+ it("rejects another payer's invoice", async () => {
176
+ expect(
177
+ await observeUsageInvoice(setup(false, true).stripe, options, "in_one"),
178
+ ).toMatchObject({
179
+ status: "unsupported",
180
+ reason: "invoice_binding_mismatch",
181
+ });
182
+ });
183
+
184
+ it("does not treat the legacy truncated invoice quantity as full precision", async () => {
185
+ expect(
186
+ await observeUsageInvoice(
187
+ setup(false, false, true).stripe,
188
+ options,
189
+ "in_one",
190
+ ),
191
+ ).toMatchObject({
192
+ status: "available",
193
+ value: { lines: [{ quantity: null, providerQuantityDecimal: null }] },
194
+ });
195
+ });