@civitai/blocks-react 0.43.0 → 0.44.0

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -111,46 +111,57 @@ export interface WatchWorkflowOptions {
  * reproduces the bug one layer down: a caller who logs `message` expecting the
  * server's words gets a constant and is exactly as stuck as before.
  *
- *   - {@link WorkflowEstimateError.snapshot}`.error` — the server's own words,
- *     verbatim. **Server-authored and UNSANITISED**: civitai's `errorHandling.ts`
- *     documents that raw upstream text — Prisma/`pg` column and constraint names
- *     among it — can reach this field. Log it, or show it in a developer-facing
- *     error surface; do NOT render it as trusted copy.
- *   - {@link WorkflowEstimateError.message} — a CONSTANT template with only
- *     `code` interpolated. It contains no server text and nothing to sanitise, so
- *     it is safe to print. That is deliberate: `message` is what an uncaught
+ * 🔴 THREE FIELDS, THREE AUDIENCES — AND **NONE OF THEM IS VIEWER-FACING COPY**.
+ * The viewer-facing string is one the APP owns; this error carries nothing you
+ * may render as-is. Two apps migrating to `0.43.0` each had a `catch` that piped
+ * `err.message` straight into rendered UI, and each would have shipped
+ * `estimate did not return a usable price (failed) — reason on .snapshot.error`
+ * to end users; both were caught only by a test asserting that exact string.
+ *
+ *   - {@link WorkflowEstimateError.snapshot}`.error` — **the DIAGNOSTIC read.**
+ *     The server's own words, verbatim. **Server-authored and UNSANITISED**:
+ *     civitai's `errorHandling.ts` documents that raw upstream text —
+ *     Prisma/`pg` column and constraint names among it — can reach this field.
+ *     Log it, or show it in a developer-facing error surface. **NEVER render it
+ *     verbatim into markup**, and think before shipping it to a third-party
+ *     error tracker.
+ *   - {@link WorkflowEstimateError.message} — **DEVELOPER-FACING.** A CONSTANT
+ *     template with only `code` interpolated. It contains no server text and
+ *     nothing to sanitise, so it is safe to LOG and safe to let a stack trace
+ *     print — that is deliberate, because `message` is what an uncaught
  *     rejection prints and what a third-party block's error reporter ships
  *     upstream by default, and this is a package consumed by third-party code.
- *     Its exact wording is NOT a contract.
- *   - {@link WorkflowEstimateError.code} — the only stable branch target.
+ *     **It is NOT intended for display to viewers**: it names an internal field
+ *     path, it is not localised, and **its exact wording is NOT a contract** —
+ *     it can change in any release, so a UI built on it silently rots.
+ *   - {@link WorkflowEstimateError.code} — **the BRANCH TARGET**, and the only
+ *     stable one. Switch on it to pick a viewer-facing string YOUR APP owns
+ *     (see the mapper in the `@example` on {@link useBuzzWorkflow}).
  *
  * 🔴 DO NOT "SIMPLIFY" THIS BY PUTTING `snapshot.error` BACK ON `message`. The
  * two fields are split on purpose and the split is what keeps database internals
  * off a third party's default-printed surface. `test/useBuzzWorkflow.test.tsx`
  * pins it with a realistic `Unique constraint failed: Key (email)=(…)` fixture.
  *
- * 🔴 NOT APPLIED TO `submit`, and the reason is narrower than it looks. On
- * `WORKFLOW_SUBMITTED` there are likewise TWO producers, indistinguishable by
- * `status`: budget/cap REJECTIONS, which are a documented outcome the block
- * recovers from (open a top-up flow) and which carry a `cost`; and caught server
- * exceptions posted via the SAME `failureSnapshot(err)` used above, which do not.
- * The `#4159` defect is therefore live on `submit` too, discriminated by `cost`
- * presence rather than by `status`. Fixing it there is a separate change with its
- * own blast radius on the recovery path (a fix MUST keep the budget-rejection arm
- * RESOLVING, or the top-up flow breaks) and is deliberately NOT attempted here —
- * so `submit` is left resolving BOTH, and the accompanying test pins only the
- * budget-rejection producer, not a claim that submit is correct.
- *
- * 🔴 TRACKED, NOT FORGOTTEN: civitai/civitai-app-starters#251. Read it before
- * touching `submit`'s failure handling.
+ * 🔴 `submit` HAS ITS OWN CLASS — {@link WorkflowSubmitError} — BECAUSE ITS
+ * DISCRIMINATOR IS DIFFERENT. On `WORKFLOW_SUBMITTED` both producers report
+ * `status:'failed'`, so `status` separates nothing there and `cost` presence is
+ * what does. Do not merge the two classes or reuse this one for submit: the
+ * question each answers is different ("was a usable price returned?" vs "was a
+ * workflow actually queued?") and so is the arm that must keep resolving.
+ * (civitai/civitai-app-starters#251, the `submit` half of civitai/civitai#4159.)
  */
 export declare class WorkflowEstimateError extends Error {
     /**
      * WHICH PRODUCER this was, structurally — so a caller branches on an enum
      * rather than on prose. It is the ONLY stable branch target here:
      * `snapshot.error` is server-authored and can change without notice, and
-     * {@link WorkflowEstimateError.message} is a generic summary whose exact
-     * wording is not a contract either.
+     * {@link WorkflowEstimateError.message} is a generic developer-facing summary
+     * whose exact wording is not a contract either.
+     *
+     * 🔴 THIS IS WHAT A VIEWER-FACING MESSAGE MUST BE DERIVED FROM. Branch on
+     * `code` and return a string your app owns and localises; never render
+     * `message` or `snapshot.error` to a viewer.
      *
      * - `'failed'`  — the reply's `status` is `'failed'`. USUALLY that means
      *   `blocks.estimateWorkflow` threw server-side and the host posted its
@@ -175,12 +186,176 @@ export declare class WorkflowEstimateError extends Error {
      * will not price — the whole point of civitai/civitai#4159), but civitai's
      * `errorHandling.ts` documents that raw upstream text — Prisma/`pg` column and
      * constraint names among it — can reach that field. Log it, show it in a
-     * developer-facing error surface, do NOT render it as trusted copy and do not
-     * ship it to a third-party error tracker without thinking about it.
+     * developer-facing error surface, **NEVER render it verbatim into markup**,
+     * and do not ship it to a third-party error tracker without thinking about it.
      */
     readonly snapshot: BlockWorkflowSnapshot;
     constructor(snapshot: BlockWorkflowSnapshot, code: 'failed' | 'no-cost');
 }
+/**
+ * Why {@link UseBuzzWorkflowReturn.submit} rejected. **The two differ on whether
+ * money may already have moved** — see {@link WorkflowSubmitError.code}.
+ */
+export type WorkflowSubmitErrorCode = 'exception' | 'workflow-failed';
+/**
+ * Thrown by {@link UseBuzzWorkflowReturn.submit} when the host's reply carries no
+ * usable workflow outcome — either the submit ERRORED before anything was queued,
+ * or a workflow-shaped reply came back already failed with no price.
+ *
+ * 🔴 READ {@link WorkflowSubmitError.code} BEFORE SAYING ANYTHING ABOUT MONEY.
+ * The two codes differ on exactly that, and getting it wrong is expensive in both
+ * directions — see the per-code notes below.
+ *
+ * 🔴 WHY THIS EXISTS — civitai/civitai-app-starters#251, the `submit` half of
+ * civitai/civitai#4159. A server-side `blocks.submitWorkflow` throw cannot reach
+ * the block as a rejection; the reply crosses `postMessage`. The host instead
+ * posts a well-formed `WORKFLOW_SUBMITTED` carrying its `failureSnapshot(err)` —
+ * `{ workflowId: 'failed', status: 'failed', error: '<server message>' }`, with
+ * **no `cost`**. That snapshot is perfectly legal, so `submit()` resolved it and
+ * moved the hook to `'done'`, handing the caller a "workflow" that does not
+ * exist.
+ *
+ * 🔴 TWO PRODUCERS, ONE `status` — AND HERE `status` DISCRIMINATES NOTHING. This
+ * is what makes submit's version of the defect different from estimate's, and
+ * why {@link WorkflowEstimateError}'s guard could not simply be copied:
+ *
+ *   - **budget / spend-cap REJECTION** — a legitimate OUTCOME. The server quotes
+ *     the price it refused to charge, so the snapshot carries a numeric
+ *     `cost.total`. Blocks recover from it (open a top-up flow), so it MUST keep
+ *     RESOLVING. Every such exit on the server attaches a cost: the per-call
+ *     `buzzBudget` gate, the per-user daily Buzz cap, the per-app aggregate and
+ *     velocity caps, and the dev-tunnel session cap — on all three body kinds.
+ *   - **caught server EXCEPTION** — `failureSnapshot(err)`, no `cost`, and the
+ *     `'failed'` sentinel id. The host had no workflow to report — usually
+ *     nothing was queued, but a lost response or an in-progress idempotency
+ *     conflict lands here too. Rejects as `'exception'`.
+ *   - **a reply that came back failed and unpriced with a NON-sentinel id** —
+ *     normally a genuine orchestrator id, no `cost` (the server's
+ *     `snapshotFromWorkflow` omits the key whenever `workflow.cost?.total` is not
+ *     numeric). Rejects as `'workflow-failed'`, and **money may already be
+ *     committed** — see that code's note.
+ *
+ * So the rule is `cost` presence, and ONLY among failure-shaped replies: an
+ * ordinary in-flight submit (`{ workflowId:'wf_…', status:'pending' }`) is
+ * cost-less too and must keep resolving, which is why the guard is not keyed on
+ * `cost` alone either. Both clauses are load-bearing; each has its own control
+ * in `test/useBuzzWorkflow.test.tsx`.
+ *
+ * 🔴 THE GUARD IS DELIBERATELY NOT WIDENED TO ALL TERMINAL STATUSES. A cost-less
+ * `succeeded` / `canceled` / `expired` reply is a legitimate outcome and must
+ * RESOLVE; only `'failed'` is unusable. Swapping the clause for
+ * `TERMINAL_STATUSES.has(...)` is a silent WIDENING that a delete-only mutation
+ * sweep cannot see — `test/useBuzzWorkflow.test.tsx` pins each of those three
+ * statuses explicitly for exactly that reason.
+ *
+ * 🔴 THREE FIELDS, THREE AUDIENCES — AND **NONE OF THEM IS VIEWER-FACING COPY**,
+ * exactly as on {@link WorkflowEstimateError}. Two apps migrating to `0.43.0`
+ * piped that class's `err.message` straight into rendered UI
+ * (civitai/civitai-app-starters#253); the same split applies here so the same
+ * mistake is not re-enabled on the submit path.
+ *
+ *   - {@link WorkflowSubmitError.snapshot}`.error` — **the DIAGNOSTIC read.** The
+ *     server's own words, verbatim. **Server-authored and UNSANITISED**:
+ *     civitai's `errorHandling.ts` documents that raw upstream text —
+ *     Prisma/`pg` column and constraint names among it — can reach this field.
+ *     Log it, or show it in a developer-facing error surface. **NEVER render it
+ *     verbatim into markup**, and think before shipping it to a third-party
+ *     error tracker.
+ *   - {@link WorkflowSubmitError.message} — **DEVELOPER-FACING.** A CONSTANT
+ *     template with only `code` interpolated. It contains no server text, so it
+ *     is safe to LOG and safe to let a stack trace print — deliberate, because
+ *     `message` is what an uncaught rejection prints and what a third-party
+ *     block's error reporter ships upstream by default. **It is NOT intended for
+ *     display to viewers** and **its exact wording is NOT a contract.**
+ *   - {@link WorkflowSubmitError.code} — **the BRANCH TARGET**, and the only
+ *     stable one.
+ *
+ * 🔴 DO NOT "SIMPLIFY" THIS BY PUTTING `snapshot.error` BACK ON `message`, and do
+ * not widen the guard to reject a budget rejection. The first re-opens #253; the
+ * second breaks the top-up recovery flow, which is the one thing #251 says must
+ * not break.
+ */
+export declare class WorkflowSubmitError extends Error {
+    /**
+     * WHICH PRODUCER this was, structurally — so a caller branches on an enum
+     * rather than on prose. It is the ONLY stable branch target here:
+     * `snapshot.error` is server-authored and can change without notice, and
+     * {@link WorkflowSubmitError.message} is a generic developer-facing summary
+     * whose exact wording is not a contract either.
+     *
+     * 🔴 THE TWO CODES DIFFER ON WHETHER MONEY MOVED. Do not collapse them, and do
+     * not write recovery copy that ignores the distinction.
+     *
+     * - `'exception'` — the host built this reply itself
+     *   (`failureSnapshot(err)`, id {@link HOST_SYNTHESISED_WORKFLOW_ID}), from a
+     *   `catch` OR from a non-catch short-circuit such as the moderator-review
+     *   nack. **It means the host had no workflow to report — NOT that nothing
+     *   happened.**
+     *
+     *   🔴 USUALLY nothing was queued and nothing was charged, and a retry is the
+     *   sensible recovery. But the same shape is reachable when a workflow MAY have
+     *   been created and charged, because the failure happened after the request
+     *   left the block:
+     *     - a **lost response** — the server's own catch concedes that "the
+     *       orchestrator externalId dedupe still protects a retry that DID create a
+     *       workflow server-side despite a lost response". What that path refunds
+     *       is its own reservation and cap counters; the Buzz debit happens inside
+     *       the orchestrator's submit.
+     *     - an **in-progress idempotency CONFLICT** — a concurrent first attempt is
+     *       still in flight and may be committing right now. Retrying blind is the
+     *       worst option there.
+     *     - a **transient transport failure** (5xx / 408 / 429 / 401), which the
+     *       `dev:live` host collapses into this same shape.
+     *
+     *   So prefer **reusing the same {@link SubmitWorkflowOptions.idempotencyKey}**
+     *   on retry rather than letting a fresh one be minted, and do not render
+     *   "nothing was charged" to a viewer as a certainty. There is no workflow id
+     *   on this arm to poll.
+     *
+     * - `'workflow-failed'` — the id was NOT the host's sentinel, so the reply came
+     *   from the server's `snapshotFromWorkflow`: normally a real orchestrator id,
+     *   already `'failed'` and with no price.
+     *
+     *   🔴 **DO NOT TELL THE VIEWER NOTHING WAS CHARGED, AND DO NOT BLIND-RETRY.**
+     *   Server-side, `blocks.submitWorkflow` treats *any resolved* submit as
+     *   money-COMMITTED: its own comment is "A resolved submit is money-COMMITTED
+     *   (the reservation is kept regardless of snapshot status)… we do NOT refund
+     *   on a non-throwing failed snapshot", and `finalizeGenIdempotency` runs on
+     *   that path. So Buzz may already be spent for this call.
+     *
+     *   A retry is a SECOND reservation unless you reuse the same
+     *   {@link SubmitWorkflowOptions.idempotencyKey} — `submit()` mints a fresh key
+     *   per call by default, so an automatic retry double-reserves.
+     *
+     *   🔴 `err.snapshot.workflowId` IS USUALLY POLLABLE, BUT CHECK IT FIRST — this
+     *   arm is defined by what the id is NOT. The server emits `workflow.id ??
+     *   'whatif'`, and it treats **both** `'failed'` and `'whatif'` as non-workflow
+     *   sentinels (it skips its own persistence and settle steps on either). So
+     *   `'whatif'` lands here — correctly, because the cautious money reading still
+     *   applies — but there is nothing to poll. Guard with
+     *   `err.snapshot.workflowId !== 'whatif'` before calling
+     *   {@link UseBuzzWorkflowReturn.watch} / {@link UseBuzzWorkflowReturn.poll} to
+     *   learn the workflow's actual fate before spending again.
+     *
+     * A union rather than a boolean so a future producer gets its own code without
+     * breaking a caller's `switch`.
+     *
+     * 🔴 A BUDGET REJECTION NEVER ARRIVES HERE. It resolves, and is read off the
+     * returned snapshot as `status === 'failed'` with a numeric `cost.total`.
+     */
+    readonly code: WorkflowSubmitErrorCode;
+    /**
+     * The snapshot the host replied with, VERBATIM — including `snapshot.error`,
+     * the server's own words, when there are any.
+     *
+     * 🔴 `snapshot.error` IS SERVER-AUTHORED AND UNSANITISED. It is where the
+     * reason lives, but raw upstream text — Prisma/`pg` column and constraint
+     * names among it — can reach that field. Log it, show it in a developer-facing
+     * error surface, **NEVER render it verbatim into markup**.
+     */
+    readonly snapshot: BlockWorkflowSnapshot;
+    constructor(snapshot: BlockWorkflowSnapshot, code: WorkflowSubmitErrorCode);
+}
 /** Optional per-submit controls. */
 export interface SubmitWorkflowOptions {
     /**
@@ -189,6 +364,11 @@ export interface SubmitWorkflowOptions {
      * host+orchestrator collapse it to ONE Buzz charge instead of double-charging.
      * Omit → the hook generates a fresh key per `submit()` call (each call is a new
      * logical submit); pass a stable id (e.g. a grid-cell id) to make a retry safe.
+     *
+     * 🔴 THIS IS THE FIELD THAT MAKES A RETRY AFTER A `'workflow-failed'` REJECTION
+     * SAFE. That code means a workflow probably exists and its spend may already
+     * be committed server-side; retrying WITHOUT reusing the key mints a fresh one
+     * and therefore a SECOND reservation. See {@link WorkflowSubmitError.code}.
      */
     idempotencyKey?: string;
 }
@@ -216,6 +396,43 @@ interface UseBuzzWorkflowReturn {
      * estimate's price sitting in `result` for a Confirm gate to read.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
+    /**
+     * Queue a workflow. Resolves ONLY with a reply that represents a real workflow
+     * OUTCOME — one that was queued, or one the server priced and then refused.
+     *
+     * 🔴 REJECTS with {@link WorkflowSubmitError} when the reply is failure-shaped
+     * and carries no price. Wrap every call in `try/catch`; see that class for why
+     * resolving such a reply was the `submit` half of civitai/civitai#4159.
+     * **Check `err.code` before saying anything about money** — and note that
+     * NEITHER code guarantees nothing was spent. `'exception'` usually means
+     * nothing was queued or charged, but a lost response or an in-progress
+     * idempotency conflict reaches it too; `'workflow-failed'` means a workflow
+     * PROBABLY exists (the `'whatif'` sentinel lands here too and has nothing to
+     * poll — guard before polling) and its spend may already be committed. Do not
+     * tell the viewer it was free, and on either code prefer reusing the same
+     * {@link SubmitWorkflowOptions.idempotencyKey}.
+     *
+     * 🔴 A BUDGET / SPEND-CAP REJECTION STILL RESOLVES, and that is deliberate. It
+     * is a documented outcome, not an error: the server quotes what it refused to
+     * charge, so the resolved snapshot has `status === 'failed'` AND a numeric
+     * `cost.total`. THAT is the shape to branch on when offering a top-up —
+     * `useBuzzPurchase().openPurchaseModal()` — not a `catch`.
+     *
+     * 🔴 BUT A RESOLVED `'failed'` IS NOT ALWAYS AN AFFORDABILITY PROBLEM, so do not
+     * wire every one of them to a purchase modal. The per-app **velocity** limit,
+     * the per-app **aggregate daily** cap, a fail-closed "temporarily unavailable"
+     * deny and a **missing price quote** are all priced, resolving outcomes that
+     * buying Buzz cannot fix.
+     *
+     * 🔴 THIS ALSO INCLUDES MODERATOR REVIEW PREVIEW. While an app is under review
+     * the host short-circuits every workflow request with
+     * `failureSnapshot('not available in review preview')`, so `submit()` rejects
+     * there where it used to resolve — the correct reading (no workflow was
+     * queued), and why the catch is not optional.
+     *
+     * `result` is updated to the returned snapshot BEFORE any rejection, so a
+     * failed submit can never leave a previous submit's workflow in `result`.
+     */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**
      * ONE host round-trip. The low-level pull primitive — you almost certainly
@@ -264,10 +481,20 @@ interface UseBuzzWorkflowReturn {
  * Orchestrates the estimate → confirm → submit → poll dance through the
  * host-mediated `postMessage` path.
  *
- * The host enforces budget rules (`cost_estimate <= token.buzzBudget`)
- * before forwarding to the orchestrator; submit() will reject if the host
- * refuses. Block apps should call `useBuzzPurchase().openPurchaseModal()`
- * when that happens.
+ * The host enforces budget rules (`cost_estimate <= token.buzzBudget`) before
+ * forwarding to the orchestrator.
+ *
+ * 🔴 A BUDGET REFUSAL DOES **NOT** REJECT — IT RESOLVES. It comes back as a
+ * snapshot with `status: 'failed'`, an `error` string and the `cost` the server
+ * declined to charge, and THAT resolved shape is the cue to call
+ * `useBuzzPurchase().openPurchaseModal()`. What DOES reject is a submit with no
+ * usable outcome — see {@link WorkflowSubmitError}. Routing a rejection into a
+ * top-up sells Buzz for a failure Buzz cannot fix.
+ *
+ * 🔴 NOR IS EVERY RESOLVED `'failed'` AN AFFORDABILITY PROBLEM. The per-app
+ * velocity limit, the per-app aggregate daily cap, a fail-closed "temporarily
+ * unavailable" deny and a missing price quote are all priced, resolving outcomes
+ * too. Branch on the message/your own policy before offering to sell anything.
  *
  * AFTER `submit` FLIPS `status` TO `'polling'`, USE `watch(workflowId)`. It owns
  * the loop, resolves on the terminal snapshot, and pushes every intermediate
@@ -310,21 +537,58 @@ interface UseBuzzWorkflowReturn {
  *   modelVersionId,
  *   params: { prompt: 'a cat' },
  * };
+ * // A viewer-facing string YOUR APP owns, chosen by `code`. Neither
+ * // `err.message` (developer-facing, wording not a contract) nor
+ * // `err.snapshot.error` (server-authored, unsanitised) may be rendered.
+ * const estimateFailureMessage = (err: WorkflowEstimateError) =>
+ *   err.code === 'no-cost'
+ *     ? 'We could not get a price for this configuration. Try adjusting it.'
+ *     : 'Pricing is unavailable right now. Please try again shortly.';
+ *
  * // 🔴 estimate() REJECTS when the reply carries no usable price — an errored
  * // estimate, or one that came back with no numeric cost. ALWAYS catch it.
  * try {
  *   await estimate(body);          // status 'estimating' → 'confirming' (cost in result.cost.total)
  * } catch (err) {
  *   // status is now 'error'; `result` holds the unusable snapshot, never a
- *   // STALE priced one. Branch on err.code ('failed' | 'no-cost'); the server's
- *   // reason is on err.snapshot.error (unsanitised — log it, don't render it as
- *   // trusted copy). See WorkflowEstimateError.
+ *   // STALE priced one. See WorkflowEstimateError for the three-audience split.
  *   if (!(err instanceof WorkflowEstimateError)) throw err;
- *   logForDebugging(err.snapshot.error);
- *   showError('This configuration cannot be priced right now.');
+ *   logForDebugging(err.message, err.snapshot.error); // developer-facing: LOG only
+ *   showError(estimateFailureMessage(err));           // viewer-facing: app-owned
+ * }
+ * // 🔴 submit() REJECTS when the reply carries no usable workflow outcome, so it
+ * // needs a catch too — and the two codes differ on whether MONEY MOVED.
+ * try {
+ *   const snap = await submit(body); // status 'submitting' → 'polling'
+ *   if (snap.status === 'failed') {
+ *     // RESOLVED + priced = a server outcome (affordability, a cap, a velocity
+ *     // limit, a transient deny). Only some of those are fixable by buying Buzz.
+ *     showError(submitOutcomeMessage(snap));
+ *   } else {
+ *     const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal
+ *     if (done.status === 'succeeded') setImages(done.imageUrls ?? []);
+ *   }
+ * } catch (err) {
+ *   if (!(err instanceof WorkflowSubmitError)) throw err;
+ *   logForDebugging(err.message, err.snapshot.error); // developer-facing: LOG only
+ *   // 🔴 TWO SEPARATE QUESTIONS: `code` decides what you may say about MONEY,
+ *   // the id decides only whether there is anything to POLL. Conjoining them
+ *   // sends a 'whatif' id into the reassuring arm.
+ *   if (err.code === 'workflow-failed') {
+ *     // Spend may already be committed. Do NOT retry blindly (that mints a new
+ *     // idempotency key = a second reservation) and do NOT claim nothing was
+ *     // charged.
+ *     showError('The generation may have started but did not complete.');
+ *     // 'whatif' is a non-workflow sentinel — nothing behind it to poll.
+ *     if (err.snapshot.workflowId !== 'whatif') {
+ *       await watch(err.snapshot.workflowId, { onUpdate: render });
+ *     }
+ *   } else {
+ *     // 'exception' — usually nothing was queued. Retry, but reuse the SAME
+ *     // idempotencyKey: a lost response can also land here.
+ *     showError('Could not start the generation. Please try again.');
+ *   }
  * }
- * const snap = await submit(body); // status 'submitting' → 'polling'; returns a workflowId
- * const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal
  */
 export declare function useBuzzWorkflow(): UseBuzzWorkflowReturn;
 export {};

package/dist/hooks/useBuzzWorkflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BnG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAW7C,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACrD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;gBAE7B,QAAQ,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS;CAexE;AAED,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,EAAE,CACN,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;;OAGG;IACH,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,EAAE,CACL,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CAkPvD"}
+{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"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"}