@fantastic.dev/better-stripe 0.67.1 → 0.68.1

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 (49) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/MIGRATION.md +1 -1
  3. package/README.md +12 -12
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
  6. package/dist/client/index.d.ts +1 -0
  7. package/dist/client/index.d.ts.map +1 -1
  8. package/dist/client/index.js.map +1 -1
  9. package/dist/client/products/catalogClient.d.ts +7 -0
  10. package/dist/client/products/catalogClient.d.ts.map +1 -1
  11. package/dist/client/products/catalogClient.js +7 -0
  12. package/dist/client/products/catalogClient.js.map +1 -1
  13. package/dist/client/products/identity.d.ts +26 -0
  14. package/dist/client/products/identity.d.ts.map +1 -0
  15. package/dist/client/products/identity.js +8 -0
  16. package/dist/client/products/identity.js.map +1 -0
  17. package/dist/client/usage/observationClient.d.ts +2 -2
  18. package/dist/client/usage/observationClient.d.ts.map +1 -1
  19. package/dist/component/_generated/component.d.ts +43 -0
  20. package/dist/component/_generated/component.d.ts.map +1 -1
  21. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  22. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  23. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  24. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  25. package/dist/component/products/queries.d.ts +49 -0
  26. package/dist/component/products/queries.d.ts.map +1 -1
  27. package/dist/component/products/queries.js +32 -0
  28. package/dist/component/products/queries.js.map +1 -1
  29. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  30. package/docs/README.md +18 -32
  31. package/docs/architecture.md +40 -21
  32. package/docs/client-api.md +25 -3
  33. package/docs/configuration.md +36 -8
  34. package/docs/development.md +25 -5
  35. package/docs/marketplace.md +34 -10
  36. package/docs/overview.md +14 -3
  37. package/docs/react-api.md +18 -9
  38. package/docs/read-contracts.md +34 -0
  39. package/docs/testing.md +29 -4
  40. package/docs/usage-observations.md +5 -2
  41. package/docs/webhooks.md +45 -7
  42. package/package.json +15 -60
  43. package/src/client/index.ts +4 -0
  44. package/src/client/products/catalogClient.ts +15 -0
  45. package/src/client/products/identity.test.ts +91 -0
  46. package/src/client/products/identity.ts +36 -0
  47. package/src/component/_generated/component.ts +47 -0
  48. package/src/component/products/identity.test.ts +217 -0
  49. package/src/component/products/queries.ts +42 -0
@@ -9,6 +9,7 @@ import type { StripeComponentProduct, StripeComponentPrice } from "../types.js";
9
9
  import * as productsImpl from "./products.js";
10
10
  import * as pricesImpl from "./prices.js";
11
11
  import * as catalog from "./catalog.js";
12
+ import * as identity from "./identity.js";
12
13
 
13
14
  /** Catalog APIs inherited by BetterStripe. Host authorization remains required. */
14
15
  export abstract class CatalogClient extends BillingPortalClient {
@@ -137,6 +138,13 @@ export abstract class CatalogClient extends BillingPortalClient {
137
138
  return productsImpl.getProduct(this.component, ctx, opts);
138
139
  }
139
140
 
141
+ async getProductIdentity(
142
+ ctx: RunCtx,
143
+ opts: { stripeProductId: string },
144
+ ): Promise<identity.ProductIdentityResult> {
145
+ return identity.getProductIdentity(this.component, ctx, opts);
146
+ }
147
+
140
148
  async getProductByStripeId(
141
149
  ctx: RunCtx,
142
150
  opts: { stripeProductId: string },
@@ -208,6 +216,13 @@ export abstract class CatalogClient extends BillingPortalClient {
208
216
  return pricesImpl.getPrice(this.component, ctx, opts);
209
217
  }
210
218
 
219
+ async getPriceIdentity(
220
+ ctx: RunCtx,
221
+ opts: { stripePriceId: string },
222
+ ): Promise<identity.PriceIdentityResult> {
223
+ return identity.getPriceIdentity(this.component, ctx, opts);
224
+ }
225
+
211
226
  async getPriceByStripeId(
212
227
  ctx: RunCtx,
213
228
  opts: { stripePriceId: string },
@@ -0,0 +1,91 @@
1
+ import { describe, expect, it, vi } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import { components, initConvexTest } from "../setup.test.js";
4
+ import schema from "../../component/schema.js";
5
+ import type { RunCtx } from "../helpers.js";
6
+ class ReadOnlyCatalog extends BetterStripe {
7
+ providerAccesses = 0;
8
+ protected override stripe(): never {
9
+ this.providerAccesses += 1;
10
+ throw new Error("Provider access forbidden for identity reads");
11
+ }
12
+ }
13
+ const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
14
+
15
+ describe("public strict catalog identity facade", () => {
16
+ it("exposes a public strict product reader", () => {
17
+ const client = new ReadOnlyCatalog(components.betterStripe, {
18
+ STRIPE_SECRET_KEY: "sk_test_identity",
19
+ });
20
+ expect(Reflect.get(client, "getProductIdentity")).toBeTypeOf("function");
21
+ });
22
+ it("exposes a public strict price reader", () => {
23
+ const client = new ReadOnlyCatalog(components.betterStripe, {
24
+ STRIPE_SECRET_KEY: "sk_test_identity",
25
+ });
26
+ expect(Reflect.get(client, "getPriceIdentity")).toBeTypeOf("function");
27
+ });
28
+ it("forwards exact selectors through the actual component and preserves every result", async () => {
29
+ const t = initConvexTest();
30
+ t.registerComponent("betterStripe", schema, modules);
31
+ const client = new ReadOnlyCatalog(components.betterStripe, {
32
+ STRIPE_SECRET_KEY: "sk_test_identity",
33
+ });
34
+ await t.action(async (realCtx) => {
35
+ const ctx: RunCtx = realCtx;
36
+ const query = vi.spyOn(ctx, "runQuery");
37
+ const productOpts = { stripeProductId: "prod_facade" };
38
+ const priceOpts = { stripePriceId: "price_facade" };
39
+ expect(await client.getProductIdentity(ctx, productOpts)).toEqual({
40
+ status: "missing",
41
+ });
42
+ expect(await client.getPriceIdentity(ctx, priceOpts)).toEqual({
43
+ status: "missing",
44
+ });
45
+ expect(query.mock.calls[0]?.[1]).toEqual(productOpts);
46
+ expect(query.mock.calls[1]?.[1]).toEqual(priceOpts);
47
+ await client.upsertProduct(ctx, {
48
+ ...productOpts,
49
+ name: "Facade",
50
+ active: true,
51
+ });
52
+ const original = await client.getProductIdentity(ctx, productOpts);
53
+ expect(original.status).toBe("unique");
54
+ if (original.status !== "unique")
55
+ throw new Error("Expected original product fixture");
56
+ const productId = original.product._id;
57
+ await client.upsertPrice(ctx, {
58
+ ...priceOpts,
59
+ productId,
60
+ stripeProductId: productOpts.stripeProductId,
61
+ unitAmount: 1200,
62
+ currency: "usd",
63
+ active: true,
64
+ type: "one_time",
65
+ });
66
+ const product = await client.getProductIdentity(ctx, productOpts);
67
+ const price = await client.getPriceIdentity(ctx, priceOpts);
68
+ expect(product).toMatchObject({
69
+ status: "unique",
70
+ product: {
71
+ _id: productId,
72
+ stripeProductId: productOpts.stripeProductId,
73
+ },
74
+ });
75
+ expect(price).toMatchObject({
76
+ status: "unique",
77
+ price: { stripePriceId: priceOpts.stripePriceId, productId },
78
+ });
79
+ // Cardinality itself is exercised against actual duplicate rows in component tests.
80
+ // The facade must preserve an ambiguous result rather than reinterpret it as missing.
81
+ query.mockResolvedValue({ status: "ambiguous" });
82
+ expect(await client.getProductIdentity(ctx, productOpts)).toEqual({
83
+ status: "ambiguous",
84
+ });
85
+ expect(await client.getPriceIdentity(ctx, priceOpts)).toEqual({
86
+ status: "ambiguous",
87
+ });
88
+ expect(client.providerAccesses).toBe(0);
89
+ });
90
+ });
91
+ });
@@ -0,0 +1,36 @@
1
+ import type { Component, RunCtx } from "../helpers.js";
2
+ import type { StripeComponentProduct, StripeComponentPrice } from "../types.js";
3
+ import { componentRef } from "../webhooks/helpers.js";
4
+
5
+ /** Cache cardinality is data, not permission or provider reconciliation. */
6
+ export type ProductIdentityResult =
7
+ | { status: "missing" }
8
+ | { status: "unique"; product: StripeComponentProduct }
9
+ | { status: "ambiguous" };
10
+
11
+ export type PriceIdentityResult =
12
+ | { status: "missing" }
13
+ | { status: "unique"; price: StripeComponentPrice }
14
+ | { status: "ambiguous" };
15
+
16
+ export async function getProductIdentity(
17
+ component: Component,
18
+ ctx: RunCtx,
19
+ opts: { stripeProductId: string },
20
+ ): Promise<ProductIdentityResult> {
21
+ return ctx.runQuery(
22
+ componentRef(component, "products/queries/getProductIdentity"),
23
+ opts,
24
+ );
25
+ }
26
+
27
+ export async function getPriceIdentity(
28
+ component: Component,
29
+ ctx: RunCtx,
30
+ opts: { stripePriceId: string },
31
+ ): Promise<PriceIdentityResult> {
32
+ return ctx.runQuery(
33
+ componentRef(component, "products/queries/getPriceIdentity"),
34
+ opts,
35
+ );
36
+ }
@@ -7601,6 +7601,32 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7601
7601
  } | null,
7602
7602
  Name
7603
7603
  >;
7604
+ getPriceIdentity: FunctionReference<
7605
+ "query",
7606
+ "internal",
7607
+ { stripePriceId: string },
7608
+ | { status: "missing" }
7609
+ | {
7610
+ price: {
7611
+ _creationTime: number;
7612
+ _id: string;
7613
+ active: boolean;
7614
+ currency: string;
7615
+ interval?: "day" | "week" | "month" | "year";
7616
+ intervalCount?: number;
7617
+ metadata?: any;
7618
+ nickname?: string;
7619
+ productId: string;
7620
+ stripePriceId: string;
7621
+ stripeProductId: string;
7622
+ type: "one_time" | "recurring";
7623
+ unitAmount: number;
7624
+ };
7625
+ status: "unique";
7626
+ }
7627
+ | { status: "ambiguous" },
7628
+ Name
7629
+ >;
7604
7630
  getProduct: FunctionReference<
7605
7631
  "query",
7606
7632
  "internal",
@@ -7633,6 +7659,27 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7633
7659
  } | null,
7634
7660
  Name
7635
7661
  >;
7662
+ getProductIdentity: FunctionReference<
7663
+ "query",
7664
+ "internal",
7665
+ { stripeProductId: string },
7666
+ | { status: "missing" }
7667
+ | {
7668
+ product: {
7669
+ _creationTime: number;
7670
+ _id: string;
7671
+ accountId?: string;
7672
+ active: boolean;
7673
+ description?: string;
7674
+ metadata?: any;
7675
+ name: string;
7676
+ stripeProductId: string;
7677
+ };
7678
+ status: "unique";
7679
+ }
7680
+ | { status: "ambiguous" },
7681
+ Name
7682
+ >;
7636
7683
  listPrices: FunctionReference<
7637
7684
  "query",
7638
7685
  "internal",
@@ -0,0 +1,217 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { describe, expect, it } from "vitest";
4
+ import { api } from "../_generated/api.js";
5
+ import { schema, modules } from "../../test.js";
6
+ import * as queries from "./queries.js";
7
+
8
+ const product = {
9
+ stripeProductId: "prod_identity",
10
+ name: "Original",
11
+ active: true,
12
+ };
13
+
14
+ const price = {
15
+ stripePriceId: "price_identity",
16
+ productId: "component_product",
17
+ stripeProductId: product.stripeProductId,
18
+ unitAmount: 1200,
19
+ currency: "usd",
20
+ active: true,
21
+ type: "recurring" as const,
22
+ interval: "month" as const,
23
+ };
24
+
25
+ describe("bounded catalog identity", () => {
26
+ it("exports an actual registered strict product reader", () => {
27
+ expect(Reflect.get(queries, "getProductIdentity")).toBeTypeOf("function");
28
+ });
29
+
30
+ it("exports an actual registered strict price reader", () => {
31
+ expect(Reflect.get(queries, "getPriceIdentity")).toBeTypeOf("function");
32
+ });
33
+
34
+ it("retains the legacy product getter's first-row behavior on actual duplicates", async () => {
35
+ const t = convexTest(schema, modules);
36
+ const first = await t.run((ctx) => ctx.db.insert("products", product));
37
+ await t.run((ctx) =>
38
+ ctx.db.insert("products", {
39
+ ...product,
40
+ active: false,
41
+ accountId: "acct_foreign",
42
+ metadata: { conflicting: true },
43
+ }),
44
+ );
45
+ expect(
46
+ (
47
+ await t.query(api.products.queries.getProductByStripeId, {
48
+ stripeProductId: product.stripeProductId,
49
+ })
50
+ )?._id,
51
+ ).toBe(first);
52
+ });
53
+ it("distinguishes missing product and price identities", async () => {
54
+ const t = convexTest(schema, modules);
55
+ expect(
56
+ await t.query(api.products.queries.getProductIdentity, {
57
+ stripeProductId: "absent",
58
+ }),
59
+ ).toEqual({ status: "missing" });
60
+ expect(
61
+ await t.query(api.products.queries.getPriceIdentity, {
62
+ stripePriceId: "absent",
63
+ }),
64
+ ).toEqual({ status: "missing" });
65
+ });
66
+
67
+ it("returns the complete unique product including its actual component identity", async () => {
68
+ const t = convexTest(schema, modules);
69
+ const id = await t.run((ctx) => ctx.db.insert("products", product));
70
+ const row = await t.run((ctx) => ctx.db.get("products", id));
71
+ expect(
72
+ await t.query(api.products.queries.getProductIdentity, {
73
+ stripeProductId: product.stripeProductId,
74
+ }),
75
+ ).toEqual({ status: "unique", product: row });
76
+ });
77
+
78
+ it("returns the complete unique price including its actual product association", async () => {
79
+ const t = convexTest(schema, modules);
80
+ const id = await t.run((ctx) => ctx.db.insert("prices", price));
81
+ const row = await t.run((ctx) => ctx.db.get("prices", id));
82
+ expect(
83
+ await t.query(api.products.queries.getPriceIdentity, {
84
+ stripePriceId: price.stripePriceId,
85
+ }),
86
+ ).toEqual({ status: "unique", price: row });
87
+ });
88
+
89
+ it.each([
90
+ { active: false },
91
+ { accountId: "acct_foreign" },
92
+ { metadata: { original: "contradiction" } },
93
+ ])(
94
+ "rejects product uniqueness across conflicting duplicate %j",
95
+ async (changed) => {
96
+ const t = convexTest(schema, modules);
97
+ await t.run(async (ctx) => {
98
+ await ctx.db.insert("products", product);
99
+ await ctx.db.insert("products", { ...product, ...changed });
100
+ });
101
+ expect(
102
+ await t.query(api.products.queries.getProductIdentity, {
103
+ stripeProductId: product.stripeProductId,
104
+ }),
105
+ ).toEqual({ status: "ambiguous" });
106
+ },
107
+ );
108
+
109
+ it.each([
110
+ { active: false },
111
+ { productId: "foreign_component_product", stripeProductId: "prod_foreign" },
112
+ { metadata: { original: "contradiction" } },
113
+ ])(
114
+ "rejects price uniqueness across conflicting duplicate %j",
115
+ async (changed) => {
116
+ const t = convexTest(schema, modules);
117
+ await t.run(async (ctx) => {
118
+ await ctx.db.insert("prices", price);
119
+ await ctx.db.insert("prices", { ...price, ...changed });
120
+ });
121
+ expect(
122
+ await t.query(api.products.queries.getPriceIdentity, {
123
+ stripePriceId: price.stripePriceId,
124
+ }),
125
+ ).toEqual({ status: "ambiguous" });
126
+ },
127
+ );
128
+
129
+ it("becomes ambiguous when another product arrives after a unique read", async () => {
130
+ const t = convexTest(schema, modules);
131
+ await t.run((ctx) => ctx.db.insert("products", product));
132
+ expect(
133
+ (
134
+ await t.query(api.products.queries.getProductIdentity, {
135
+ stripeProductId: product.stripeProductId,
136
+ })
137
+ ).status,
138
+ ).toBe("unique");
139
+ await t.run((ctx) => ctx.db.insert("products", product));
140
+ expect(
141
+ await t.query(api.products.queries.getProductIdentity, {
142
+ stripeProductId: product.stripeProductId,
143
+ }),
144
+ ).toEqual({ status: "ambiguous" });
145
+ });
146
+
147
+ it("becomes ambiguous when another price arrives after a unique read", async () => {
148
+ const t = convexTest(schema, modules);
149
+ await t.run((ctx) => ctx.db.insert("prices", price));
150
+ expect(
151
+ (
152
+ await t.query(api.products.queries.getPriceIdentity, {
153
+ stripePriceId: price.stripePriceId,
154
+ })
155
+ ).status,
156
+ ).toBe("unique");
157
+ await t.run((ctx) => ctx.db.insert("prices", price));
158
+ expect(
159
+ await t.query(api.products.queries.getPriceIdentity, {
160
+ stripePriceId: price.stripePriceId,
161
+ }),
162
+ ).toEqual({ status: "ambiguous" });
163
+ });
164
+
165
+ it("does not let unrelated duplicate products poison a queried unique identity", async () => {
166
+ const t = convexTest(schema, modules);
167
+ const id = await t.run(async (ctx) => {
168
+ await ctx.db.insert("products", {
169
+ ...product,
170
+ stripeProductId: "unrelated",
171
+ });
172
+ await ctx.db.insert("products", {
173
+ ...product,
174
+ stripeProductId: "unrelated",
175
+ });
176
+ return ctx.db.insert("products", product);
177
+ });
178
+ expect(
179
+ await t.query(api.products.queries.getProductIdentity, {
180
+ stripeProductId: product.stripeProductId,
181
+ }),
182
+ ).toMatchObject({ status: "unique", product: { _id: id } });
183
+ });
184
+
185
+ it("does not let unrelated duplicate prices poison a queried unique identity", async () => {
186
+ const t = convexTest(schema, modules);
187
+ const id = await t.run(async (ctx) => {
188
+ await ctx.db.insert("prices", { ...price, stripePriceId: "unrelated" });
189
+ await ctx.db.insert("prices", { ...price, stripePriceId: "unrelated" });
190
+ return ctx.db.insert("prices", price);
191
+ });
192
+ expect(
193
+ await t.query(api.products.queries.getPriceIdentity, {
194
+ stripePriceId: price.stripePriceId,
195
+ }),
196
+ ).toMatchObject({ status: "unique", price: { _id: id } });
197
+ });
198
+
199
+ it("retains the legacy price getter's first-row behavior on actual duplicates", async () => {
200
+ const t = convexTest(schema, modules);
201
+ const first = await t.run((ctx) => ctx.db.insert("prices", price));
202
+ await t.run((ctx) =>
203
+ ctx.db.insert("prices", {
204
+ ...price,
205
+ active: false,
206
+ productId: "foreign",
207
+ }),
208
+ );
209
+ expect(
210
+ (
211
+ await t.query(api.products.queries.getPriceByStripeId, {
212
+ stripePriceId: price.stripePriceId,
213
+ })
214
+ )?._id,
215
+ ).toBe(first);
216
+ });
217
+ });
@@ -221,3 +221,45 @@ export const paginatePrices = query({
221
221
  });
222
222
  },
223
223
  });
224
+
225
+ /** Resolve a provider ID without selecting an arbitrary duplicate. */
226
+ export const getProductIdentity = query({
227
+ args: { stripeProductId: v.string() },
228
+ returns: v.union(
229
+ v.object({ status: v.literal("missing") }),
230
+ v.object({ status: v.literal("unique"), product: productDocValidator }),
231
+ v.object({ status: v.literal("ambiguous") }),
232
+ ),
233
+ handler: async (ctx, args) => {
234
+ const rows = await ctx.db
235
+ .query("products")
236
+ .withIndex("by_stripe_product_id", (q) =>
237
+ q.eq("stripeProductId", args.stripeProductId),
238
+ )
239
+ .take(2);
240
+ if (rows.length === 0) return { status: "missing" as const };
241
+ if (rows.length > 1) return { status: "ambiguous" as const };
242
+ return { status: "unique" as const, product: rows[0]! };
243
+ },
244
+ });
245
+
246
+ /** Resolve a provider ID without selecting an arbitrary duplicate. */
247
+ export const getPriceIdentity = query({
248
+ args: { stripePriceId: v.string() },
249
+ returns: v.union(
250
+ v.object({ status: v.literal("missing") }),
251
+ v.object({ status: v.literal("unique"), price: priceDocValidator }),
252
+ v.object({ status: v.literal("ambiguous") }),
253
+ ),
254
+ handler: async (ctx, args) => {
255
+ const rows = await ctx.db
256
+ .query("prices")
257
+ .withIndex("by_stripe_price_id", (q) =>
258
+ q.eq("stripePriceId", args.stripePriceId),
259
+ )
260
+ .take(2);
261
+ if (rows.length === 0) return { status: "missing" as const };
262
+ if (rows.length > 1) return { status: "ambiguous" as const };
263
+ return { status: "unique" as const, price: rows[0]! };
264
+ },
265
+ });