@civitai/sdk 0.19.1 → 0.20.1

package/README.md

@@ -559,7 +559,7 @@ A `kind: 'workflow'` body runs several steps as **one** workflow, and a later
 step can consume an earlier step's result through a `{ $ref, path }` reference:
 
 ```ts
-import { initialize, type WorkflowBody } from '@civitai/sdk';
+import { estimatedCost, initialize, type WorkflowBody } from '@civitai/sdk';
 
 const app = await initialize();
 
@@ -587,11 +587,13 @@ const body: WorkflowBody = {
 
 // 1. Price it. Nothing is charged or reserved.
 const estimate = await app.workflows.estimate(body);
-if (estimate.status === 'failed') {
+// A priced estimate is not 'succeeded' ('pending' in practice): read the price, not the status.
+const price = estimatedCost(estimate);
+if (price === null) {
   // A refusal RESOLVES — see below.
   throw new Error(estimate.error ?? 'This workflow could not be priced.');
 }
-if (!(await confirmSpend(estimate.cost?.total))) throw new Error('Not confirmed.');
+if (!(await confirmSpend(price))) throw new Error('Not confirmed.');
 
 // 2. Run it. One key per press of the button, reused on every retry.
 const idempotencyKey = crypto.randomUUID();
@@ -617,7 +619,7 @@ submitted. `app.workflows` has no call for that confirmation step.
 
 | Call | Does |
 |---|---|
-| `estimate(body)` | Prices the body. `snapshot.cost.total` is whole Buzz |
+| `estimate(body)` | Prices the body. `estimatedCost(snapshot)` is the price in whole Buzz, or `null` when there is none |
 | `submit(body, { idempotencyKey })` | Runs it, spending the viewer's Buzz |
 | `get(workflowId)` | The workflow as it stands now |
 | `watch(workflowId)` | An async iterator: the workflow now, then each time it changes, until a final status |
@@ -633,13 +635,19 @@ branch on the snapshot rather than wrapping the call in `try`:
 
 ```ts
 const estimate = await app.workflows.estimate(body);
-if (estimate.status === 'failed') {
+if (estimatedCost(estimate) === null) {
   estimate.error; // a sentence for the viewer, e.g. which step is at fault
   estimate.errorCode; // a stable code to branch on, when the refusal defines one
-  estimate.cost; // absent: nothing was priced
 }
 ```
 
+`estimatedCost` is the check to use: the price when the estimate has one, else
+`null`. An estimate is priced when its `status` is not `'failed'` and it carries
+a numeric `cost.total`. 🔴 **Do not require `'succeeded'`**: nothing runs on an
+estimate, so a priced one comes back with a status that has not finished
+(`'pending'` in practice), and a check for `'succeeded'` treats every price as
+missing. `0` is a price.
+
 Three things follow from that shape:
 
 - **A refused estimate has no `cost`.** An estimate the host could not price
@@ -1038,9 +1046,15 @@ Where it differs from the server on purpose:
 
 `fake.calls` records every request and answer. Options also cover smaller `limits`,
 `consent` (revoked scopes, or `'unavailable'`), `appStatus`, `disabled` and a custom
-`moderate`; by default the scanner refuses the words in `FAKE_STORAGE_MODERATION`. It
-does not model moderator hides or the review-preview namespace, and at the `Http`
-seam there is no URL resolution — the client refuses the segments a URL would
+`moderate`; by default the scanner refuses the words in `FAKE_STORAGE_MODERATION`.
+That default is the server's enforced moderation. The host picks each app's
+moderation mode for shared data, and enforce is not the default there: expect
+shadow (scanned after the write) or off, where neither a hit nor a scanner outage
+refuses a write. So never rely on a refusal to keep content out of shared data:
+a write the fake refuses may land on the server, and other viewers read it. Pass
+`moderate: () => null` to test what such an app sees. The fake does not model
+moderator hides or the review-preview namespace, and at the `Http` seam there is no
+URL resolution — the client refuses the segments a URL would
 rewrite (`''`, `.`, `..`) before sending.
 
 ### The legacy key/value stores

package/dist/doc-store/fake.js

@@ -22,6 +22,13 @@ import { createDocumentStorage } from './index.js';
  * versions of its own, so which ones a viewer owns is `FakeStorageViewer.modelVersions`
  * (default none).
  *
+ * Moderation is the server's ENFORCE mode, which the contract's moderation cases
+ * describe: a hit refuses `content_rejected` and a scanner outage
+ * `moderation_unavailable`. The host picks each app's shared-data moderation mode,
+ * and enforce is not its default: in `shadow` (the scan runs after the write) or `off`
+ * (no scan) neither a hit nor an outage refuses the write. The fake has no mode of its
+ * own: `moderate: () => null` is what a shadow or off app sees.
+ *
  * NOT MODELLED: moderator hides (a hidden document reads as not found on the server;
  * nothing here hides one), moderator exemption from the scanner, the review-preview
  * namespace, the token middleware's other refusals (revoked instance, context

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { SubListingError } from './sub-listings/index.js';
 export type { MySubListing, SubListingCallOptions, SubListingContentRating, SubListingErrorCode, SubListingStatus, SubListingsClient, SubListingUpsertInput, SubListingUpsertResult, SubListingWithdrawResult, } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
 export type { DocumentAuthor, DocumentCallOptions, DocumentListQuery, DocumentPage, DocumentStorage, DocumentWhereValue, StorageCollection, StorageCollectionInfo, StorageDocument, StorageErrorCode, StorageIndexType, StorageInfo, StorageLimits, StorageUsage, WriteOptions, } from './doc-store/index.js';
-export { SubmissionUnconfirmedError } from './workflows/index.js';
+export { estimatedCost, SubmissionUnconfirmedError } from './workflows/index.js';
 export type { WorkflowCallOptions, WorkflowGetOptions, WorkflowListQuery, WorkflowListResult, WorkflowSubmitOptions, WorkflowWatchOptions, WorkflowsClient, } from './workflows/index.js';
 export type { AiToolkitLrScheduler, AiToolkitOptimizerType, AiToolkitPlainEcosystem, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AppWorkflow, AppWorkflowImage, BlockModel3dOutput, BlockModelSubstitution, BlockPublishedModel, BlockSourceImage, BlockStepQuote, BlockStepToolCall, BlockTextToImageParams, BlockTrainedEpoch, BlockTrainingDatasetItem, BlockTrainingQuote, BlockWorkflowSnapshot, BlockWorkflowStepSnapshot, BuzzAccountType, InlineComfyNode, KnownBlockWorkflowErrorCode, ModelSubstitutionReason, WithWorkflowStepRefs, WorkflowBody, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyInline, WorkflowBodyCustomComfyRecipe, WorkflowBodyPassThroughStep, WorkflowBodyStep, WorkflowBodyTextToImage, WorkflowBodyTraining, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, } from './workflows/types.generated.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export { createSignIn, SignInError } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
 export { SubListingError } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
-export { SubmissionUnconfirmedError } from './workflows/index.js';
+export { estimatedCost, SubmissionUnconfirmedError } from './workflows/index.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export { createHost } from './host/index.js';
 export { ApiError } from './http/index.js';

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.19.1";
+export declare const VERSION = "0.20.1";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.19.1";
+export const VERSION = "0.20.1";

package/dist/workflows/index.d.ts

@@ -28,6 +28,25 @@ export declare class SubmissionUnconfirmedError extends CivitaiError {
     readonly snapshot: BlockWorkflowSnapshot | undefined;
     constructor(snapshot: BlockWorkflowSnapshot | undefined);
 }
+/**
+ * The price an {@link WorkflowsClient.estimate} reply quotes, in whole Buzz, or
+ * `null` when it quotes none.
+ *
+ * An estimate is priced when its `status` is not `'failed'` AND it carries a
+ * numeric `cost.total`. That is the whole rule, and it is the one to branch on:
+ * - Do not require `'succeeded'`. Nothing runs on an estimate, so a priced one
+ *   comes back with a status that has not finished (`'pending'` in practice),
+ *   and a check for `'succeeded'` reads every price as missing.
+ * - `0` is a price.
+ * - A `'failed'` snapshot is never priced, even one carrying a `cost.total`: a
+ *   budget refusal carries the total it would not charge.
+ * - A snapshot with no numeric `cost.total` is not priced, whatever its status.
+ *
+ * `null` does not predict a refused {@link WorkflowsClient.submit}: a body the
+ * host cannot price can still be submitted. Read `error` / `errorCode` on the
+ * snapshot for why.
+ */
+export declare function estimatedCost(snapshot: Pick<BlockWorkflowSnapshot, 'status' | 'cost'>): number | null;
 export interface WorkflowCallOptions {
     signal?: AbortSignal;
 }
@@ -102,6 +121,16 @@ export interface WorkflowsClient {
      * The price is `snapshot.cost.total`. A refused estimate resolves with
      * `status: 'failed'` and no `cost`; a body the host cannot price fails this
      * way without that predicting a refused {@link WorkflowsClient.submit}.
+     *
+     * 🔴 DO NOT REQUIRE `'succeeded'`. Nothing runs on an estimate, so a priced
+     * one comes back with a status that has not finished (`'pending'` in
+     * practice). Read the price with {@link estimatedCost}, which is `null`
+     * exactly when there is none to show:
+     *
+     * ```ts
+     * const price = estimatedCost(await app.workflows.estimate(body));
+     * if (price === null) showMessage('This generation could not be priced.');
+     * ```
      */
     estimate(body: WorkflowBody, opts?: WorkflowCallOptions): Promise<BlockWorkflowSnapshot>;
     /**

package/dist/workflows/index.js

@@ -51,6 +51,28 @@ export class SubmissionUnconfirmedError extends CivitaiError {
         this.snapshot = snapshot;
     }
 }
+/**
+ * The price an {@link WorkflowsClient.estimate} reply quotes, in whole Buzz, or
+ * `null` when it quotes none.
+ *
+ * An estimate is priced when its `status` is not `'failed'` AND it carries a
+ * numeric `cost.total`. That is the whole rule, and it is the one to branch on:
+ * - Do not require `'succeeded'`. Nothing runs on an estimate, so a priced one
+ *   comes back with a status that has not finished (`'pending'` in practice),
+ *   and a check for `'succeeded'` reads every price as missing.
+ * - `0` is a price.
+ * - A `'failed'` snapshot is never priced, even one carrying a `cost.total`: a
+ *   budget refusal carries the total it would not charge.
+ * - A snapshot with no numeric `cost.total` is not priced, whatever its status.
+ *
+ * `null` does not predict a refused {@link WorkflowsClient.submit}: a body the
+ * host cannot price can still be submitted. Read `error` / `errorCode` on the
+ * snapshot for why.
+ */
+export function estimatedCost(snapshot) {
+    const total = snapshot.cost?.total;
+    return snapshot.status !== 'failed' && typeof total === 'number' ? total : null;
+}
 const isSnapshot = (value) => value != null && typeof value === 'object' && typeof value.status === 'string';
 /**
  * Asserted, not cast: every caller branches on `status`, and a reply without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",