@fantastic.dev/better-stripe 0.50.0 → 0.50.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.
package/CHANGELOG.md CHANGED
@@ -26,6 +26,14 @@
26
26
  - Remove internal tracker references from public documentation and add a
27
27
  regression check that prevents their reintroduction.
28
28
 
29
+ ## [0.50.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.0...v0.50.1) (2026-10-17)
30
+
31
+ ### Bug Fixes
32
+
33
+ - **react:** initialize workflow refs before descendant layout effects ([b6a9da8](https://github.com/FantasticDevHQ/better-stripe/commit/b6a9da8ad0cd3043a575420bd876b1878d9ed9f4))
34
+ - **react:** settle commit-started workflow actions ([f1befb4](https://github.com/FantasticDevHQ/better-stripe/commit/f1befb4194dee87b0b1c54528ae4305b5b749147))
35
+ - **react:** settle workflow actions started during commit ([5d4d2e1](https://github.com/FantasticDevHQ/better-stripe/commit/5d4d2e1fa3623205b3f971f1e5e1c9d24919a091))
36
+
29
37
  ## [0.50.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.49.0...v0.50.0) (2026-10-17)
30
38
 
31
39
  ### Features
package/README.md CHANGED
@@ -72,7 +72,7 @@ claim execution are completed.
72
72
 
73
73
  ## Status
74
74
 
75
- **Version**: `0.50.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
75
+ **Version**: `0.50.1` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
76
76
 
77
77
  Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
78
78
 
@@ -1 +1 @@
1
- {"version":3,"file":"useWorkflowAction.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,IAAI;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AACF,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EACzD,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,KAAK,GAAE,MAAkB,EACzB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAC9B,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,CAgE9B"}
1
+ {"version":3,"file":"useWorkflowAction.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,IAAI;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AACF,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EACzD,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,KAAK,GAAE,MAAkB,EACzB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAC9B,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,CAgE9B"}
@@ -1,5 +1,7 @@
1
1
  "use client";
2
- import { useCallback, useEffect, useRef, useState } from "react";
2
+ import { useCallback, useEffect, useInsertionEffect, useRef, useState, } from "react";
3
+ // Ref-only synchronization must precede layout effects in descendants as well.
4
+ const useCommitEffect = typeof window === "undefined" ? useEffect : useInsertionEffect;
3
5
  /** Shared async action lifecycle. Scope identifies the authenticated account/resource, not authorization. */
4
6
  export function useWorkflowAction(action, scope = "default", onSuccess) {
5
7
  const initial = {
@@ -15,11 +17,11 @@ export function useWorkflowAction(action, scope = "default", onSuccess) {
15
17
  const success = useRef(onSuccess);
16
18
  const lifecycle = useRef({ version: 0, mounted: false });
17
19
  const lock = useRef(null);
18
- useEffect(() => {
20
+ useCommitEffect(() => {
19
21
  callback.current = action;
20
22
  success.current = onSuccess;
21
23
  }, [action, onSuccess]);
22
- useEffect(() => {
24
+ useCommitEffect(() => {
23
25
  const version = ++lifecycle.current.version;
24
26
  lifecycle.current.mounted = true;
25
27
  lock.current = null;
@@ -1 +1 @@
1
- {"version":3,"file":"useWorkflowAction.js","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"useWorkflowAction.js","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"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"}
@@ -577,6 +577,12 @@ checking that the response still belongs to the mounted scope. `useOnboarding`
577
577
  uses this lifecycle for both create and continue navigation, including its
578
578
  `window.location.assign` fallback. An old response cannot navigate after unmount
579
579
  or scope replacement. Current requests preserve shared pending locks and errors.
580
+ The lifecycle and current action callbacks initialize during the browser commit
581
+ phase, using ref-only insertion effects before parent or child layout effects
582
+ can start work. These effects neither update state nor inspect DOM attachment.
583
+ A layout-started action
584
+ therefore settles normally; later unmount or scope replacement still suppresses
585
+ its stale result. Server rendering remains idle and invokes no action.
580
586
  `uploadDisputeEvidence`, `EvidenceUpload` and the onboarding navigation fix shipped
581
587
  in [0.14.0](https://github.com/FantasticDevHQ/better-stripe/releases/tag/v0.14.0).
582
588
  Version 0.13.0 does not contain them. Consumers must upgrade to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.50.0",
3
+ "version": "0.50.1",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -0,0 +1,194 @@
1
+ // @vitest-environment jsdom
2
+ import { StrictMode, useLayoutEffect } from "react";
3
+ import {
4
+ act,
5
+ cleanup,
6
+ fireEvent,
7
+ render,
8
+ renderHook,
9
+ screen,
10
+ } from "@testing-library/react";
11
+ import { afterEach, expect, it, vi } from "vitest";
12
+ import { useWorkflowAction } from "./useWorkflowAction.js";
13
+
14
+ afterEach(cleanup);
15
+
16
+ function ActionConsumer({
17
+ startsDuringCommit,
18
+ }: {
19
+ startsDuringCommit: boolean;
20
+ }) {
21
+ const observation = useWorkflowAction(async () => "observed", "original");
22
+ useLayoutEffect(() => {
23
+ if (startsDuringCommit) void observation.run();
24
+ }, [startsDuringCommit, observation.run]);
25
+ return (
26
+ <div>
27
+ <button
28
+ onClick={() => {
29
+ void observation.run();
30
+ }}
31
+ >
32
+ Observe
33
+ </button>
34
+ <p>
35
+ {observation.isPending ? "pending" : (observation.result ?? "idle")}
36
+ </p>
37
+ </div>
38
+ );
39
+ }
40
+
41
+ it("completes an ordinary event-started workflow action", async () => {
42
+ render(<ActionConsumer startsDuringCommit={false} />);
43
+ fireEvent.click(screen.getByRole("button", { name: "Observe" }));
44
+ expect((await screen.findByText("observed")).textContent).toBe("observed");
45
+ expect(screen.queryByText("pending")).toBeNull();
46
+ });
47
+
48
+ it("completes an action started by a consumer layout effect", async () => {
49
+ render(<ActionConsumer startsDuringCommit />);
50
+ expect((await screen.findByText("observed")).textContent).toBe("observed");
51
+ expect(screen.queryByText("pending")).toBeNull();
52
+ });
53
+
54
+ it("completes the current commit-started action through StrictMode replay", async () => {
55
+ render(
56
+ <StrictMode>
57
+ <ActionConsumer startsDuringCommit />
58
+ </StrictMode>,
59
+ );
60
+ expect((await screen.findByText("observed")).textContent).toBe("observed");
61
+ expect(screen.queryByText("pending")).toBeNull();
62
+ });
63
+
64
+ it("uses the current callback when a layout effect starts work after rerender", async () => {
65
+ const first = vi.fn(async () => "first");
66
+ const second = vi.fn(async () => "second");
67
+ const { result, rerender } = renderHook(
68
+ ({ action }) => {
69
+ const observation = useWorkflowAction(action);
70
+ useLayoutEffect(() => {
71
+ void observation.run();
72
+ }, [action, observation.run]);
73
+ return observation;
74
+ },
75
+ { initialProps: { action: first } },
76
+ );
77
+ await act(async () => {});
78
+ expect(result.current.result).toBe("first");
79
+ rerender({ action: second });
80
+ await act(async () => {});
81
+ expect(result.current.result).toBe("second");
82
+ expect(first).toHaveBeenCalledOnce();
83
+ expect(second).toHaveBeenCalledOnce();
84
+ });
85
+
86
+ it("does not call success after a pending consumer unmounts", async () => {
87
+ let complete!: (value: string) => void;
88
+ const onSuccess = vi.fn();
89
+ const { result, unmount } = renderHook(() =>
90
+ useWorkflowAction(
91
+ () =>
92
+ new Promise<string>((resolve) => {
93
+ complete = resolve;
94
+ }),
95
+ "original",
96
+ onSuccess,
97
+ ),
98
+ );
99
+ let pending!: Promise<string | undefined>;
100
+ act(() => {
101
+ pending = result.current.run();
102
+ });
103
+ unmount();
104
+ await act(async () => {
105
+ complete("discarded");
106
+ expect(await pending).toBeUndefined();
107
+ });
108
+ expect(onSuccess).not.toHaveBeenCalled();
109
+ });
110
+
111
+ function Child({
112
+ run,
113
+ starts,
114
+ }: {
115
+ run: () => Promise<string | undefined>;
116
+ starts: boolean;
117
+ }) {
118
+ useLayoutEffect(() => {
119
+ if (starts) void run();
120
+ }, [run, starts]);
121
+ return null;
122
+ }
123
+ function Parent({ starts, label }: { starts: boolean; label: string }) {
124
+ const action = useWorkflowAction(async () => label, "original");
125
+ return (
126
+ <>
127
+ <Child run={action.run} starts={starts} />
128
+ <p>{action.isPending ? "pending" : (action.result ?? "idle")}</p>
129
+ </>
130
+ );
131
+ }
132
+
133
+ it("settles a parent-owned public workflow action started by its child layout effect", async () => {
134
+ render(<Parent starts label="observed" />);
135
+ expect(await screen.findByText("observed")).toBeTruthy();
136
+ expect(screen.queryByText("pending")).toBeNull();
137
+ });
138
+
139
+ it("uses the current parent callback when child layout starts work after an update", async () => {
140
+ const view = render(<Parent starts={false} label="first" />);
141
+ expect(screen.getByText("idle")).toBeTruthy();
142
+ view.rerender(<Parent starts label="second" />);
143
+ expect(await screen.findByText("second")).toBeTruthy();
144
+ });
145
+
146
+ it("dispatches and publishes once when a child starts its parent's action under StrictMode", async () => {
147
+ const action = vi.fn(async () => "current");
148
+ const onSuccess = vi.fn();
149
+ function StrictParent() {
150
+ const observation = useWorkflowAction(action, "original", onSuccess);
151
+ return (
152
+ <>
153
+ <Child run={observation.run} starts />
154
+ <p>
155
+ {observation.isPending ? "pending" : (observation.result ?? "idle")}
156
+ </p>
157
+ </>
158
+ );
159
+ }
160
+ render(
161
+ <StrictMode>
162
+ <StrictParent />
163
+ </StrictMode>,
164
+ );
165
+ expect((await screen.findByText("current")).textContent).toBe("current");
166
+ expect(action).toHaveBeenCalledOnce();
167
+ expect(onSuccess).toHaveBeenCalledExactlyOnceWith("current");
168
+ expect(screen.queryByText("pending")).toBeNull();
169
+ });
170
+
171
+ it("suppresses pending success and result after the scope changes", async () => {
172
+ let complete!: (value: string) => void;
173
+ const onSuccess = vi.fn();
174
+ const action = () =>
175
+ new Promise<string>((resolve) => {
176
+ complete = resolve;
177
+ });
178
+ const { result, rerender } = renderHook(
179
+ ({ scope }) => useWorkflowAction(action, scope, onSuccess),
180
+ { initialProps: { scope: "original" } },
181
+ );
182
+ let pending!: Promise<string | undefined>;
183
+ act(() => {
184
+ pending = result.current.run();
185
+ });
186
+ rerender({ scope: "replacement" });
187
+ await act(async () => {
188
+ complete("old");
189
+ expect(await pending).toBeUndefined();
190
+ });
191
+ expect(onSuccess).not.toHaveBeenCalled();
192
+ expect(result.current.result).toBeUndefined();
193
+ expect(result.current.isPending).toBe(false);
194
+ });
@@ -0,0 +1,20 @@
1
+ // @vitest-environment node
2
+ import { renderToString } from "react-dom/server";
3
+ import { expect, it, vi } from "vitest";
4
+ import { useWorkflowAction } from "./useWorkflowAction.js";
5
+
6
+ it("renders idle on the server without invoking actions or layout effects", () => {
7
+ const action = vi.fn(async () => "observed");
8
+ const warning = vi.spyOn(console, "error").mockImplementation(() => {});
9
+ function Consumer() {
10
+ const observation = useWorkflowAction(action);
11
+ return <p>{observation.isPending ? "pending" : "idle"}</p>;
12
+ }
13
+ try {
14
+ expect(renderToString(<Consumer />)).toBe("<p>idle</p>");
15
+ expect(action).not.toHaveBeenCalled();
16
+ expect(warning).not.toHaveBeenCalled();
17
+ } finally {
18
+ warning.mockRestore();
19
+ }
20
+ });
@@ -1,5 +1,15 @@
1
1
  "use client";
2
- import { useCallback, useEffect, useRef, useState } from "react";
2
+ import {
3
+ useCallback,
4
+ useEffect,
5
+ useInsertionEffect,
6
+ useRef,
7
+ useState,
8
+ } from "react";
9
+ // Ref-only synchronization must precede layout effects in descendants as well.
10
+ const useCommitEffect =
11
+ typeof window === "undefined" ? useEffect : useInsertionEffect;
12
+
3
13
  export type WorkflowActionState<T, Args extends unknown[]> = {
4
14
  isPending: boolean;
5
15
  error: string | null;
@@ -26,11 +36,11 @@ export function useWorkflowAction<T, Args extends unknown[]>(
26
36
  const success = useRef(onSuccess);
27
37
  const lifecycle = useRef({ version: 0, mounted: false });
28
38
  const lock = useRef<number | null>(null);
29
- useEffect(() => {
39
+ useCommitEffect(() => {
30
40
  callback.current = action;
31
41
  success.current = onSuccess;
32
42
  }, [action, onSuccess]);
33
- useEffect(() => {
43
+ useCommitEffect(() => {
34
44
  const version = ++lifecycle.current.version;
35
45
  lifecycle.current.mounted = true;
36
46
  lock.current = null;