@civitai/blocks-react 0.57.4 → 0.58.0

package/README.md

@@ -211,13 +211,25 @@ const bp = useBlockBreakpoint();
 ### `useBlockToken()`
 
 Current block-scoped JWT, auto-refreshing ~2 min before expiry. Returns the token
-fields plus a `refresh()` for the 401-retry path.
+fields plus a `refresh()` for the 401-retry path, which **resolves with the new
+token**.
 
 ```tsx
 const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
-// after a 401: await refresh(); then retry the request once with the new `raw`.
+
+let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+if (res.status === 401) {
+  const fresh = await refresh();   // resolves WITH the new token
+  res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+}
 ```
 
+> **Retry with the resolved token, not the `raw` you destructured.** That `raw` is
+> a `const` from the render closure that ran *before* the refresh — awaiting
+> `refresh()` re-renders the component but cannot reassign the binding your
+> in-flight callback is already holding. A retry that re-reads the outer `raw`
+> re-sends the stale JWT and 401s for exactly the reason the first call did.
+
 ### `useHostOrigin()`
 
 The validated host origin to direct-fetch the App Blocks HTTP API against —

package/dist/hooks/useBlockToken.d.ts

@@ -1,10 +1,11 @@
 import type { BlockToken } from '@civitai/app-sdk/blocks';
 /**
  * What {@link useBlockToken} returns: the live block token plus a manual
- * `refresh`. See `./returnTypeLedger.js`.
+ * `refresh` that resolves WITH the newly-minted token. See
+ * `./returnTypeLedger.js`.
  */
 export type UseBlockToken = BlockToken & {
-    refresh: () => Promise<void>;
+    refresh: () => Promise<BlockToken>;
 };
 /**
  * Returns the current block-scoped JWT and keeps it fresh.
@@ -14,21 +15,48 @@ export type UseBlockToken = BlockToken & {
  * snapshot, and the hook re-renders with the new token.
  *
  * Consumers also get a `refresh()` callable for the 401-retry path. Call it
- * after any API request returns 401 — it forces an immediate token mint and
- * resolves once the new token is applied to the snapshot.
+ * after any API request returns 401 — it forces an immediate token mint,
+ * applies the new token to the snapshot, and RESOLVES WITH that new
+ * {@link BlockToken}.
+ *
+ * 🔴 RETRY WITH THE RESOLVED TOKEN, NOT THE `raw` YOU DESTRUCTURED. The `raw`
+ * in scope was captured from the render closure that ran BEFORE the refresh;
+ * awaiting `refresh()` re-renders the component but cannot reassign a `const`
+ * binding inside an async callback that is already executing. So a retry that
+ * re-reads the outer `raw` re-sends the STALE token and 401s for exactly the
+ * reason the first call did. This is why `refresh()` resolves with the token:
+ * the resolved value is the only in-scope handle on the fresh JWT.
  *
  * @returns The {@link BlockToken} fields (`raw`, `scopes`, `expiresAt`,
- * `buzzBudget`, …) plus a `refresh()` for the 401-retry path.
+ * `buzzBudget`, …) plus a `refresh()` for the 401-retry path, which resolves
+ * with the new {@link BlockToken}.
  *
  * @example
  * const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
- * // after a 401: await refresh(); then retry the request once with the new `raw`.
+ * let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+ * if (res.status === 401) {
+ *   const fresh = await refresh();        // resolves WITH the new token
+ *   res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+ * }
  */
 export declare function useBlockToken(): UseBlockToken;
 /**
  * Mint/await a token refresh for one block instance, coalescing concurrent calls
  * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
  * dedup test — hooks call it via `useBlockToken().refresh`.
+ *
+ * Resolves with the REFRESHED {@link BlockToken} so a 401-retry has an in-scope
+ * handle on the new JWT — the caller's destructured `raw` belongs to a closure
+ * that ran before the refresh and cannot be reassigned by it.
+ *
+ * The value is read back off the transport SNAPSHOT rather than re-parsed from
+ * the reply payload, and that is the ordering this depends on:
+ * `IframeTransport.handleMessage` calls `applyTokenRefresh` BEFORE
+ * `pending.resolve`, deliberately (see the comment there), so by the time this
+ * `.then` runs the snapshot already holds the new token. Reading the snapshot
+ * keeps ONE parse of the wire token — the resolved value is the very object the
+ * next render observes, not a second `tokenFromWrapped` of the same bytes that
+ * could drift from it.
  */
-export declare function requestRefresh(blockInstanceId: string): Promise<void>;
+export declare function requestRefresh(blockInstanceId: string): Promise<BlockToken>;
 //# sourceMappingURL=useBlockToken.d.ts.map

package/dist/hooks/useBlockToken.js

@@ -12,15 +12,29 @@ const REFRESH_LEAD_MS = 2 * 60 * 1000;
  * snapshot, and the hook re-renders with the new token.
  *
  * Consumers also get a `refresh()` callable for the 401-retry path. Call it
- * after any API request returns 401 — it forces an immediate token mint and
- * resolves once the new token is applied to the snapshot.
+ * after any API request returns 401 — it forces an immediate token mint,
+ * applies the new token to the snapshot, and RESOLVES WITH that new
+ * {@link BlockToken}.
+ *
+ * 🔴 RETRY WITH THE RESOLVED TOKEN, NOT THE `raw` YOU DESTRUCTURED. The `raw`
+ * in scope was captured from the render closure that ran BEFORE the refresh;
+ * awaiting `refresh()` re-renders the component but cannot reassign a `const`
+ * binding inside an async callback that is already executing. So a retry that
+ * re-reads the outer `raw` re-sends the STALE token and 401s for exactly the
+ * reason the first call did. This is why `refresh()` resolves with the token:
+ * the resolved value is the only in-scope handle on the fresh JWT.
  *
  * @returns The {@link BlockToken} fields (`raw`, `scopes`, `expiresAt`,
- * `buzzBudget`, …) plus a `refresh()` for the 401-retry path.
+ * `buzzBudget`, …) plus a `refresh()` for the 401-retry path, which resolves
+ * with the new {@link BlockToken}.
  *
  * @example
  * const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
- * // after a 401: await refresh(); then retry the request once with the new `raw`.
+ * let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+ * if (res.status === 401) {
+ *   const fresh = await refresh();        // resolves WITH the new token
+ *   res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+ * }
  */
 export function useBlockToken() {
     const snap = useTransportSnapshot();
@@ -64,6 +78,19 @@ const inFlightRefreshByInstance = new Map();
  * Mint/await a token refresh for one block instance, coalescing concurrent calls
  * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
  * dedup test — hooks call it via `useBlockToken().refresh`.
+ *
+ * Resolves with the REFRESHED {@link BlockToken} so a 401-retry has an in-scope
+ * handle on the new JWT — the caller's destructured `raw` belongs to a closure
+ * that ran before the refresh and cannot be reassigned by it.
+ *
+ * The value is read back off the transport SNAPSHOT rather than re-parsed from
+ * the reply payload, and that is the ordering this depends on:
+ * `IframeTransport.handleMessage` calls `applyTokenRefresh` BEFORE
+ * `pending.resolve`, deliberately (see the comment there), so by the time this
+ * `.then` runs the snapshot already holds the new token. Reading the snapshot
+ * keeps ONE parse of the wire token — the resolved value is the very object the
+ * next render observes, not a second `tokenFromWrapped` of the same bytes that
+ * could drift from it.
  */
 export async function requestRefresh(blockInstanceId) {
     const existing = inFlightRefreshByInstance.get(blockInstanceId);
@@ -71,7 +98,7 @@ export async function requestRefresh(blockInstanceId) {
         return existing;
     const transport = getTransport();
     const refresh = sendTypedRequest(transport, { type: 'REQUEST_TOKEN', payload: { blockInstanceId } }, 'TOKEN_REFRESH_RESPONSE')
-        .then(() => undefined)
+        .then(() => transport.getSnapshot().token)
         .finally(() => {
         inFlightRefreshByInstance.delete(blockInstanceId);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.57.4",
+  "version": "0.58.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",