@civitai/blocks-react 0.64.0 → 0.65.0

package/README.md

@@ -735,6 +735,126 @@ options drive both arms (including `declined`). **`dev:live` refuses this bridge
 it has no civitai chrome to render the server-resolved confirm in, and driving
 the write without it would let dev prove out a flow production does not have.
 
+### `usePrepareTrainingDataset()` and `useRunTraining()` — LoRA training
+
+Train a LoRA with the ai-toolkit engine on the **viewer's own images**, from
+inside a page app — the App Blocks `kind: 'training'` flow. Four steps, three
+hooks:
+
+1. **Dataset** — `usePrepareTrainingDataset().prepareDataset([{ imageId, caption }])`
+   (`PREPARE_TRAINING_DATASET`). Only the viewer's own scanned, unflagged images
+   within the page's maturity ceiling are admitted; the rest come back in
+   `rejected` with a reason (`unavailable`, `unsupported-media`, `not-eligible`,
+   `pending-scan`, `import-failed`, `import-unavailable`; `pending-scan` and
+   `import-unavailable` are retryable). You get an opaque `datasetId` and the
+   admitted `count`, always at least 1 — if **nothing** is admitted the call
+   rejects with the server's message instead. 1–50 images, captions up to 1,000 characters; captions are
+   moderated. No dialog, no charge.
+2. **Quote** — `useBuzzWorkflow().estimate(body)` with a `WorkflowBodyTraining`
+   (`kind: 'training'`, no `quoteId`). The reply carries `trainingQuote:
+   { quoteId, total, imageCount, expiresAt }` — the orchestrator's own price for
+   exactly this run, stored server-side for 15 minutes.
+3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })` (`RUN_TRAINING`).
+   **Civitai shows the viewer a consent dialog in its own chrome** — price, base
+   model, length and dataset size, all read back from the server, never from
+   your body — and submits only on their click. Change nothing in the body
+   between the estimate and the run; the server checks it against the quoted one.
+4. **Follow** — `useBuzzWorkflow().watch(workflowId)`. Once the run's moderation
+   status is approved, `trainedEpochs` lists the epochs whose checkpoint is
+   ready; send the viewer to the publish wizard with one of them (see
+   `trainedEpochs` on `BlockWorkflowSnapshot`).
+
+🔴 **Availability.** Behind the host flag **`app-blocks-training-kind`**, which
+ships **off** and is evaluated per viewer. **Page apps only** — the model slot
+answers both messages with an error. The manifest must declare
+**`ai:write:budgeted`** and the viewer must be signed in and have granted it.
+**Refused from `dev:live` and from review sessions** (the server refuses
+development and review tokens); build the flow against the mock host. Requires a
+civitai.com host carrying civitai/civitai#5434 (`kind: 'training'`,
+`RUN_TRAINING`) and civitai/civitai#5438 (`PREPARE_TRAINING_DATASET`).
+
+🔴 **Money.** There is no `maxBuzz` and no timeout knob — the price is the quote.
+A confirmed run may cost more than the token's per-call `buzzBudget` (the viewer
+confirms the exact price), up to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz);
+an estimate above that is refused. `useBuzzWorkflow().submit()` **refuses** a
+training body before sending anything: only `RUN_TRAINING`'s dialog can confirm a
+quote, so a training run starts nowhere else.
+
+`runTraining` **rejects** with a `RunTrainingError`; read the flags before
+saying anything about money:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the dialog — **no run was submitted** | revert, say nothing |
+| `err.unconfirmed` | `submission-unconfirmed`, or no reply within the 10-min bound (`err.timedOut`) — the run **may be running and charged** | 🔴 **never retry automatically**: check the viewer's trainings first (`useAppWorkflows()` lists this app's runs). Re-running the same body after the server did start it is a **second, separately charged run** |
+| `err.refused` (`code: 'refused'`) | the server refused the submit after the viewer confirmed — a **spend cap** (their daily or private-run Buzz cap, the per-app consent budget, the app's daily spend or rate limit, a dev-session cap) or a **temporary-availability** deny. Refunded: **no run, nothing charged**; the quote is used up | show `err.message` (the server's reason, e.g. `daily Buzz cap reached: …`); estimate again before any retry — buying Buzz does not lift these caps |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `invalid training request` / `no block token`) | show or ignore per case |
+| `err.code === undefined`, no flag | a server refusal before any submit (expired or used quote, changed body, ineligible image) | estimate again, then retry |
+
+`prepareDataset` rejects with a `PrepareTrainingDatasetError` (`.code` for the
+host's refusals — `review-mode`, `block is not ready`, `sign in to train`,
+`invalid training dataset`, `no block token` — plus `.signInRequired` and
+`.timedOut`). Preparing charges nothing, so none of them cost Buzz. It prompts
+for `ai:write:budgeted` and retries once on a grant (see the table below);
+`runTraining` deliberately does not — it carries no idempotency key and has an
+outcome where a run may exist, so it never re-sends.
+
+```tsx
+const { prepareDataset } = usePrepareTrainingDataset();
+const { estimate, watch } = useBuzzWorkflow();
+const { runTraining } = useRunTraining();
+
+async function train(images: Array<{ id: number; caption: string }>) {
+  // Rejects (no `.code`) when NOTHING is admitted, e.g. "none of the requested
+  // images can be used for training"; a resolved dataset always has count >= 1.
+  const dataset = await prepareDataset(images.map((i) => ({ imageId: i.id, caption: i.caption })));
+  if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+
+  const body: WorkflowBodyTraining = {
+    kind: 'training',
+    datasetId: dataset.datasetId,
+    engine: 'ai-toolkit',
+    model: baseModelKey, // a key from Civitai's training catalog
+    params: aiToolkitParams, // AiToolkitTrainingParams
+    triggerWord: 'mystyle',
+    samplePrompts: ['mystyle, a lighthouse at dusk'],
+  };
+  const quote = (await estimate(body)).trainingQuote;
+  if (!quote) return showError('No training price came back.');
+  // Show quote.total; the host's dialog will show the same number.
+
+  try {
+    const started = await runTraining({ ...body, quoteId: quote.quoteId });
+    const done = await watch(started.workflowId, { onUpdate: render });
+    setEpochs(done.trainedEpochs ?? []);
+  } catch (err) {
+    if (!(err instanceof RunTrainingError)) throw err;
+    if (err.declined) return; // no run
+    if (err.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+    if (err.refused) return showError(err.message); // a cap / availability refusal; no run, nothing charged
+    if (err.signInRequired) return requestSignIn();
+    showError('Could not start training. Get a new price and try again.');
+  }
+}
+```
+
+With the mock host — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — the training path is **kind-faithful**: it
+holds the datasets it prepared and the quotes it stored, refuses an unknown
+dataset, a dataset with nothing admitted, a quote above 5,000 and a quote run
+twice, and needs
+`ai:write:budgeted` on the token and a signed-in viewer. Its knobs are
+`trainingDatasetRejected`, `trainingDatasetError`, `trainingQuoteTotal`,
+`runTrainingError` (`'declined'`, `'submission-unconfirmed'`, or any server
+message), `runTrainingCapRefusal` (the server's resolved cap / availability refusal, which consumes the quote →
+`err.refused`) and `generation.trainedEpochs` for the finished run. It has no
+consent dialog, so `runTraining` settles at once where the real host waits on a
+click, and it checks a run's body against its quote by `datasetId` only — the
+server compares the whole body.
+**`dev:live` refuses both bridges**, because the server refuses every training
+request from a dev token.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -1227,6 +1347,7 @@ had just worked.
 |---|---|---|
 | `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
 | `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
+| `usePrepareTrainingDataset()` | `prepareDataset()` | `ai:write:budgeted` |
 | `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
 | `useTip()` | `tip()` | `social:tip:self` |
 

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,5 +1,18 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
 import type { ConsentRetryOptions } from './consentRetryOptions.js';
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export declare const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body \u2014 estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -465,6 +478,10 @@ export interface UseBuzzWorkflow {
      * consent dialog with no user gesture behind it, once per edit. A missing
      * scope surfaces as an ordinary rejection; show no price and let `submit()`
      * do the asking.
+     *
+     * A `kind: 'training'` body's reply also carries
+     * {@link BlockWorkflowSnapshot.trainingQuote} — the `quoteId` to run it with
+     * through `useRunTraining()`.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -512,6 +529,9 @@ export interface UseBuzzWorkflow {
      * `CONSENT_UNAVAILABLE` environment is never retried, and a second consent
      * failure reaches you unchanged. Opt out with
      * {@link ConsentRetryOptions.autoRequestConsent}`: false`.
+     *
+     * 🔴 A `kind: 'training'` BODY IS REFUSED before anything is sent — it runs
+     * only through `useRunTraining()`. See {@link TRAINING_BODY_SUBMIT_REFUSAL}.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
 import { withConsentRetry } from '../internal/withConsentRetry.js';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
 /**
@@ -16,6 +17,19 @@ import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.
  * automatic prompt silently do nothing.
  */
 const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body — estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -27,18 +41,16 @@ const TERMINAL_STATUSES = new Set([
     'canceled',
     'expired',
 ]);
-/**
- * The workflow requests (estimate / submit / poll) are orchestrator-bound:
- * the host forwards them to the generation orchestrator and only replies
- * once it answers. `submit` is the slowest — server-side it does a whatif
- * cost-preflight AND the real submit (two orchestrator round-trips) plus a
- * prompt audit before responding, which legitimately exceeds the
- * transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
- * messages) when the orchestrator queue is busy. Give these calls a
- * generous ceiling so a busy-but-healthy orchestrator doesn't surface as
- * a spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
- */
-const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
+// The workflow requests (estimate / submit / poll) are orchestrator-bound:
+// the host forwards them to the generation orchestrator and only replies
+// once it answers. `submit` is the slowest — server-side it does a whatif
+// cost-preflight AND the real submit (two orchestrator round-trips) plus a
+// prompt audit before responding, which legitimately exceeds the
+// transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
+// messages) when the orchestrator queue is busy. `WORKFLOW_REQUEST_TIMEOUT_MS`
+// (imported above, from `transport/requestTimeouts.ts`) gives these calls a
+// generous ceiling so a busy-but-healthy orchestrator doesn't surface as a
+// spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -720,6 +732,14 @@ export function useBuzzWorkflow() {
         return snapshot;
     }, []);
     const submit = useCallback(async (body, options) => {
+        // See `TRAINING_BODY_SUBMIT_REFUSAL`. Before the status flip, the key
+        // mint and the consent retry: nothing about this call may reach the wire.
+        if (body.kind === 'training') {
+            const refused = new Error(TRAINING_BODY_SUBMIT_REFUSAL);
+            setError(refused);
+            setStatus('error');
+            throw refused;
+        }
         setError(null);
         setStatus('submitting');
         // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz

package/dist/hooks/usePrepareTrainingDataset.d.ts

@@ -0,0 +1,99 @@
+import type { BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason } from '@civitai/app-sdk/blocks';
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
+export type { BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, };
+/**
+ * The host's CLOSED refusal codes for `PREPARE_TRAINING_DATASET`, as a runtime
+ * list. Mirrors civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: it also carries free-text server
+ * messages, so "is this a code?" is a membership question at runtime — see
+ * {@link isPrepareTrainingDatasetErrorCode}.
+ */
+export declare const PREPARE_TRAINING_DATASET_ERROR_CODES: readonly ["review-mode", "block is not ready", "sign in to train", "invalid training dataset", "no block token"];
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export declare function isPrepareTrainingDatasetErrorCode(error: string): error is BlockPrepareTrainingDatasetHostError;
+/**
+ * A dataset-preparation failure.
+ *
+ * `.code` is the host's refusal code when the HOST refused, `undefined` for a
+ * server message or a transport timeout. Check `.timedOut` before rendering
+ * `.message` — a timeout's message is an SDK-internal string.
+ *
+ * Preparing charges nothing, so no failure here costs the viewer Buzz.
+ */
+export declare class PrepareTrainingDatasetError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    readonly code?: BlockPrepareTrainingDatasetHostError;
+    /**
+     * No reply arrived within the bound. The server may still have prepared a
+     * dataset; nothing was charged either way, and preparing again simply makes a
+     * new handle.
+     */
+    readonly timedOut: boolean;
+    /**
+     * There is no session — the viewer is signed out (`sign in to train`), or their
+     * session ended (a bare `UNAUTHORIZED`). Route into `useRequestSignIn()`.
+     */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+    });
+}
+/** What {@link usePrepareTrainingDataset} returns. */
+export interface UsePrepareTrainingDataset {
+    /**
+     * Ask the host to prepare a training dataset from the viewer's OWN images.
+     * Resolves with the opaque `datasetId`, the admitted `count` and the
+     * `rejected` images. REJECTS with a {@link PrepareTrainingDatasetError}.
+     *
+     * A resolved result admitted AT LEAST ONE image (`count >= 1`) — when nothing
+     * is admitted the server refuses instead, and this rejects with its message
+     * (`none of the requested images can be used for training` / `… could be
+     * prepared for training`, no `.code`). Read `rejected` for what was left out:
+     * `pending-scan` and `import-unavailable` are retryable; the rest are not.
+     * The per-image reasons are not available when everything was rejected.
+     */
+    prepareDataset: (items: BlockTrainingDatasetItem[], options?: ConsentRetryOptions) => Promise<BlockTrainingDatasetResult>;
+    /** `true` while a request is in flight. */
+    pending: boolean;
+    /** The last request's failure, or `null`. Cleared at the start of the next call. */
+    error: PrepareTrainingDatasetError | null;
+}
+/**
+ * Step 1 of the App Blocks `kind: 'training'` flow: turn the viewer's own images
+ * and your captions into a dataset handle for `WorkflowBodyTraining.datasetId`,
+ * through the host-mediated `PREPARE_TRAINING_DATASET` → `TRAINING_DATASET_RESULT`
+ * bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared in the manifest and granted by a
+ * signed-in viewer. Refused from `dev:live` and from review sessions — build the
+ * flow against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * Only the viewer's OWN scanned, unflagged images within the page's maturity
+ * ceiling are admitted; captions are moderated. Bounds: 1–50 items, captions up
+ * to 1,000 characters (`BLOCK_TRAINING_DATASET_MAX_ITEMS`,
+ * `BLOCK_TRAINING_CAPTION_MAX_CHARS`); the host refuses anything else with
+ * `invalid training dataset` before calling the server.
+ *
+ * No dialog and no charge. When the token lacks `ai:write:budgeted`, the call
+ * opens the host's consent prompt and retries once on a grant (opt out with
+ * `{ autoRequestConsent: false }`).
+ *
+ * Sent under the 120s server-work bound, not the 30s protocol default: the server
+ * imports up to 50 images into the orchestrator within its own 60s budget.
+ *
+ * @example
+ * const { prepareDataset } = usePrepareTrainingDataset();
+ * try {
+ *   const dataset = await prepareDataset(
+ *     picked.map((img) => ({ imageId: img.id, caption: img.caption })),
+ *   );
+ *   if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+ * } catch (e) {
+ *   // Includes "none of the requested images can be used for training".
+ *   if (e instanceof PrepareTrainingDatasetError) showError(e.message);
+ * }
+ */
+export declare function usePrepareTrainingDataset(): UsePrepareTrainingDataset;
+//# sourceMappingURL=usePrepareTrainingDataset.d.ts.map

package/dist/hooks/usePrepareTrainingDataset.js

@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope the training flow requires — `ai:write:budgeted`. The
+ * server refuses a dataset request from a token without it (it is the spend
+ * scope, and preparing is gated exactly like the run it prepares for). From
+ * {@link BLOCK_SCOPES}, never a literal: a typo would make the automatic consent
+ * prompt silently do nothing.
+ */
+const TRAINING_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
+/**
+ * The host's CLOSED refusal codes for `PREPARE_TRAINING_DATASET`, as a runtime
+ * list. Mirrors civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: it also carries free-text server
+ * messages, so "is this a code?" is a membership question at runtime — see
+ * {@link isPrepareTrainingDatasetErrorCode}.
+ */
+export const PREPARE_TRAINING_DATASET_ERROR_CODES = [
+    'review-mode',
+    'block is not ready',
+    'sign in to train',
+    'invalid training dataset',
+    'no block token',
+];
+const CODE_SET = new Set(PREPARE_TRAINING_DATASET_ERROR_CODES);
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export function isPrepareTrainingDatasetErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A dataset-preparation failure.
+ *
+ * `.code` is the host's refusal code when the HOST refused, `undefined` for a
+ * server message or a transport timeout. Check `.timedOut` before rendering
+ * `.message` — a timeout's message is an SDK-internal string.
+ *
+ * Preparing charges nothing, so no failure here costs the viewer Buzz.
+ */
+export class PrepareTrainingDatasetError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    code;
+    /**
+     * No reply arrived within the bound. The server may still have prepared a
+     * dataset; nothing was charged either way, and preparing again simply makes a
+     * new handle.
+     */
+    timedOut;
+    /**
+     * There is no session — the viewer is signed out (`sign in to train`), or their
+     * session ended (a bare `UNAUTHORIZED`). Route into `useRequestSignIn()`.
+     */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'PrepareTrainingDatasetError';
+        this.timedOut = opts?.timedOut === true;
+        if (isPrepareTrainingDatasetErrorCode(error))
+            this.code = error;
+        this.signInRequired = error === 'sign in to train' || error === 'UNAUTHORIZED';
+    }
+}
+/**
+ * Step 1 of the App Blocks `kind: 'training'` flow: turn the viewer's own images
+ * and your captions into a dataset handle for `WorkflowBodyTraining.datasetId`,
+ * through the host-mediated `PREPARE_TRAINING_DATASET` → `TRAINING_DATASET_RESULT`
+ * bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared in the manifest and granted by a
+ * signed-in viewer. Refused from `dev:live` and from review sessions — build the
+ * flow against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * Only the viewer's OWN scanned, unflagged images within the page's maturity
+ * ceiling are admitted; captions are moderated. Bounds: 1–50 items, captions up
+ * to 1,000 characters (`BLOCK_TRAINING_DATASET_MAX_ITEMS`,
+ * `BLOCK_TRAINING_CAPTION_MAX_CHARS`); the host refuses anything else with
+ * `invalid training dataset` before calling the server.
+ *
+ * No dialog and no charge. When the token lacks `ai:write:budgeted`, the call
+ * opens the host's consent prompt and retries once on a grant (opt out with
+ * `{ autoRequestConsent: false }`).
+ *
+ * Sent under the 120s server-work bound, not the 30s protocol default: the server
+ * imports up to 50 images into the orchestrator within its own 60s budget.
+ *
+ * @example
+ * const { prepareDataset } = usePrepareTrainingDataset();
+ * try {
+ *   const dataset = await prepareDataset(
+ *     picked.map((img) => ({ imageId: img.id, caption: img.caption })),
+ *   );
+ *   if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+ * } catch (e) {
+ *   // Includes "none of the requested images can be used for training".
+ *   if (e instanceof PrepareTrainingDatasetError) showError(e.message);
+ * }
+ */
+export function usePrepareTrainingDataset() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // The consent wait can outlive the component; see `useCreatePostFromApp`.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    /** ONE round-trip + its result contract. Re-invoked verbatim on a consent retry. */
+    const prepareOnce = useCallback(async (items) => {
+        const reply = await sendTypedRequest(getTransport(), { type: 'PREPARE_TRAINING_DATASET', payload: { items } }, 'TRAINING_DATASET_RESULT', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS }).catch((err) => {
+            // Stamped INSIDE the closure `withConsentRetry` re-invokes, so its rule 4
+            // sees it: a 120s wait is not repeated behind a consent prompt.
+            if (err instanceof RequestTimeoutError) {
+                throw new PrepareTrainingDatasetError(err.message, { timedOut: true });
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        });
+        if (reply.error || !reply.result) {
+            // `||`, not `??`: the validator shape-checks `error`, so `''` is a valid
+            // reply that must not become an Error with an empty message. The
+            // fallback is deliberately NOT a host code — `invalid training dataset`
+            // would claim "nothing reached the server", which an empty error does
+            // not tell us.
+            throw new PrepareTrainingDatasetError(reply.error || 'training dataset could not be prepared');
+        }
+        return reply.result;
+    }, []);
+    const prepareDataset = useCallback(async (items, options) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            return await withConsentRetry(getTransport(), TRAINING_SCOPES, () => prepareOnce(items), options, () => mountedRef.current);
+        }
+        catch (err) {
+            const wrapped = err instanceof PrepareTrainingDatasetError
+                ? err
+                : new PrepareTrainingDatasetError(err instanceof Error ? err.message : String(err));
+            if (mountedRef.current)
+                setError(wrapped);
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, [prepareOnce]);
+    return { prepareDataset, pending, error };
+}
+//# sourceMappingURL=usePrepareTrainingDataset.js.map

package/dist/hooks/useRunTraining.d.ts

@@ -0,0 +1,151 @@
+import type { BlockRunTrainingHostError, BlockTrainingQuote, BlockWorkflowSnapshot, WorkflowBodyTraining } from '@civitai/app-sdk/blocks';
+export type { BlockRunTrainingHostError, BlockTrainingQuote, WorkflowBodyTraining };
+/**
+ * A training body ready to RUN: {@link WorkflowBodyTraining} with the `quoteId`
+ * its estimate returned. Required here so a body without one is a compile error
+ * rather than a host refusal.
+ */
+export type QuotedTrainingBody = WorkflowBodyTraining & {
+    quoteId: string;
+};
+/**
+ * The host's CLOSED refusal codes for `RUN_TRAINING`, as a runtime list. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: server messages (an expired or used quote,
+ * a body that differs from the quoted one) arrive in the same field — see
+ * {@link isRunTrainingErrorCode}.
+ */
+export declare const RUN_TRAINING_ERROR_CODES: readonly ["review-mode", "block is not ready", "sign in to train", "invalid training request", "no block token", "declined", "submission-unconfirmed"];
+/**
+ * The `code` a {@link RunTrainingError} can carry: one of the host's closed
+ * refusal codes, or `'refused'` — assigned by THIS SDK, never sent by the host,
+ * for a submit the server refused at a spend cap or as temporarily unavailable
+ * (see {@link RunTrainingError.refused}).
+ */
+export type RunTrainingErrorCode = BlockRunTrainingHostError | 'refused';
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export declare function isRunTrainingErrorCode(error: string): error is BlockRunTrainingHostError;
+/**
+ * A training run that did not come back with a snapshot.
+ *
+ * 🔴 READ THE FLAGS BEFORE SAYING ANYTHING ABOUT MONEY — they are the only part of
+ * this error with a money meaning, and they point in opposite directions:
+ *
+ *  - `.declined` — the viewer dismissed the consent dialog. NO RUN WAS
+ *    SUBMITTED, guaranteed by the host's consent latch. Render nothing.
+ *  - `.unconfirmed` — the run MAY BE RUNNING AND CHARGED: the host sent the
+ *    submit and could not learn its outcome (`submission-unconfirmed`), or no
+ *    reply arrived at all (`.timedOut` — the viewer may have clicked Train on a
+ *    dialog this block had stopped waiting for). Do NOT retry automatically and
+ *    do NOT tell the viewer it failed: check their trainings first
+ *    (`useAppWorkflows()` lists this app's runs), because re-running the same
+ *    body after the server did start it is a SECOND, separately charged run.
+ *  - `.refused` (`code: 'refused'`) — the server REFUSED the submit at a spend
+ *    cap after the viewer confirmed (the viewer's daily or private-run Buzz cap,
+ *    the per-app consent budget, the app's daily spend or rate limit, a dev
+ *    session cap). Its reservation was refunded: NO RUN, nothing charged.
+ *    `.message` is the server's reason (e.g. `daily Buzz cap reached: …`) and
+ *    `.snapshot` the refusal it arrived in. Retrying needs a new estimate and
+ *    usually a later time; buying Buzz does not lift these caps.
+ *  - `.signInRequired` — no session. Route into `useRequestSignIn()`.
+ *  - anything else — a refusal before any submit (an expired or used quote, a
+ *    body that no longer matches its quote, an ineligible image). Estimate again
+ *    before retrying; `.message` is the host's or server's text.
+ */
+export declare class RunTrainingError extends Error {
+    /**
+     * The closed host refusal code, `'refused'` for a cap refusal, or `undefined`
+     * for a server/transport error.
+     */
+    readonly code?: RunTrainingErrorCode;
+    /**
+     * The server refused the submit (a spend cap, or a temporary-availability deny)
+     * and refunded it — no run exists. The quote is used up: estimate again.
+     * See the class docs; `.message` is the server's reason.
+     */
+    readonly refused: boolean;
+    /** The refusal snapshot the host replied with, when {@link refused}. */
+    readonly snapshot?: BlockWorkflowSnapshot;
+    /** The viewer dismissed the consent dialog — no run was submitted. */
+    readonly declined: boolean;
+    /**
+     * The run may exist and may have been charged — `submission-unconfirmed`, or a
+     * transport timeout. Check the viewer's trainings before retrying.
+     */
+    readonly unconfirmed: boolean;
+    /** No reply arrived within the 10-minute consent bound. Implies {@link unconfirmed}. */
+    readonly timedOut: boolean;
+    /** There is no session (`sign in to train`, or a bare `UNAUTHORIZED`). */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+        refusedSnapshot?: BlockWorkflowSnapshot;
+    });
+}
+/** What {@link useRunTraining} returns. */
+export interface UseRunTraining {
+    /**
+     * Ask the host to run a quoted training body. Civitai shows the viewer a
+     * consent dialog with the server's price and details; on their click it
+     * submits, and this resolves with the submitted workflow's snapshot — poll it
+     * with `useBuzzWorkflow().watch(snapshot.workflowId)`.
+     *
+     * REJECTS with a {@link RunTrainingError} — including `declined` (no run),
+     * `refused` (a spend-cap or temporary-availability refusal; no run) and
+     * `unconfirmed` (a run may
+     * exist). Read the flags before rendering anything. A resolved snapshot is
+     * always a submitted run with a pollable `workflowId`.
+     */
+    runTraining: (body: QuotedTrainingBody) => Promise<BlockWorkflowSnapshot>;
+    /** `true` while a request is in flight (including the viewer's dialog). */
+    pending: boolean;
+    /** The last request's failure, or `null`. Cleared at the start of the next call. */
+    error: RunTrainingError | null;
+}
+/**
+ * Run an App Blocks `kind: 'training'` LoRA training — the only way one starts —
+ * through the host-mediated `RUN_TRAINING` → `TRAINING_RESULT` bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared and granted by a signed-in
+ * viewer. Refused from `dev:live` and from review sessions — build the flow
+ * against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * The flow: `usePrepareTrainingDataset()` → `useBuzzWorkflow().estimate(body)`
+ * (its `trainingQuote.quoteId`) → `runTraining({ ...body, quoteId })` →
+ * `useBuzzWorkflow().watch(workflowId)`. Change nothing in the body between the
+ * estimate and the run: the server checks it against the quoted one.
+ *
+ * 🔴 THE CONSENT DIALOG IS CIVITAI'S, AND IT IS THE CHARGE. Every number on it is
+ * read back from the server's stored quote — never from your body. A run may cost
+ * more than the token's per-call budget (the viewer confirms the exact price), up
+ * to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz). Images are the viewer's own.
+ *
+ * 🔴 NO AUTOMATIC CONSENT RETRY, unlike the other consent-gated hooks — on
+ * purpose. `RUN_TRAINING` carries no idempotency key and has an outcome
+ * (`submission-unconfirmed`) where a run may exist, so this hook never re-sends.
+ * It is also unreachable in practice: a block holding a `quoteId` got it from an
+ * estimate that already required `ai:write:budgeted`.
+ *
+ * Sent under the 10-minute human-interaction bound: the host replies only when
+ * the viewer clicks or dismisses its dialog.
+ *
+ * @example
+ * const { estimate, watch } = useBuzzWorkflow();
+ * const { runTraining } = useRunTraining();
+ * const quote = (await estimate(body)).trainingQuote!;
+ * try {
+ *   const started = await runTraining({ ...body, quoteId: quote.quoteId });
+ *   await watch(started.workflowId, { onUpdate: render });
+ * } catch (e) {
+ *   if (!(e instanceof RunTrainingError)) throw e;
+ *   if (e.declined) return;                          // no run — say nothing
+ *   if (e.signInRequired) return requestSignIn();
+ *   if (e.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+ *   if (e.refused) return showError(e.message); // a cap / availability refusal; no run, nothing charged
+ *   showError('Could not start training. Get a new price and try again.');
+ * }
+ */
+export declare function useRunTraining(): UseRunTraining;
+//# sourceMappingURL=useRunTraining.d.ts.map