@howells/motif-sdk 7.2.0 → 7.3.0

package/README.md

@@ -32,6 +32,8 @@ console.log(result.value.model, result.value.files[0]?.url, result.value.cost);
 
 Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` and does not throw for fal request failures; check `isErr()` / `isOk()`.
 
+Failures stay in the Result, including a fal response that is not the JSON it should be (`INVALID_RESPONSE`). A request that can bill, the synchronous run and the queue submission, is attempted once and never retried: if fal gives no clear answer (a connection error, a timeout or a 5xx), the error is `SUBMISSION_UNCERTAIN` and says fal may have accepted and may bill for it, so check fal's dashboard before submitting again. Status polls, result fetches and storage calls cannot bill and are retried. Once fal has accepted a queued run, every failure after that carries `requestId` and `details.endpoint`; pass the id to `resume` to wait for the same job.
+
 ## Curated Models and Tiers
 
 The Task client curates 23 generation Models, with separate rankings for generation and editing. Both follow Arena, read 29 October 2026. `TASKS.generate` and `TASKS.vary` expose the current choices, Tiers and evidence in `basis` and `rankedAt`. Sunburst and Flare run GPT Image 2.6; Arena has not scored 2.6 yet, so their benchmarks are the GPT Image 2.5 scores, and each carries a `note` saying so. A generation with `references` uses the editing ranking.
@@ -44,11 +46,11 @@ The Task client curates 23 generation Models, with separate rankings for generat
 
 These are the first choices when the request's capabilities and available keys permit them. Explicit Models, Looks and pins take precedence. Selected specialists remain for typography, transparency, control and inexpensive drafts.
 
-Nano Banana 2.1 (`banana21`) supports up to 14 References and 1K/2K/4K output, with no 0.5K output. Its balanced placement uses preliminary Arena evidence. Sunburst and Flare run GPT Image 2.6 on fal and default to `quality: "max"`; `params: { quality: "high" }` with an explicit `model` overrides it. Both also return an animated GIF (`outputFormat: "gif"`, with `params.frame_count` and `params.frame_duration_ms`) or, from text, an SVG (`outputFormat: "svg"`), and take `markup`: a transparent PNG of arrows, circles and notes the size of the image being edited, which guides a vary or an edit with References. Asking for a format or markup limits the choice to Models that support it. The direct provider image layer described below has its own adapter capabilities and chooses no Model.
+Nano Banana 2.1 (`banana21`) supports up to 14 References and 1K/2K/4K output, with no 0.5K output. Its balanced placement uses preliminary Arena evidence. Sunburst and Flare run GPT Image 2.6 on fal and default to `quality: "max"`; `params: { quality: "high" }` with an explicit `model` overrides it. Both also return an animated GIF (`outputFormat: "gif"`, with `params.frame_count` and `params.frame_duration_ms`) or, from text, an SVG (`outputFormat: "svg"`), and take `markup`: a transparent PNG of arrows, circles and notes the size of the image being edited, which guides a vary or an edit with References. A plan carries `size`, the exact `{ width, height }` requested (null when the Model decides the pixels), and `modelProfile(id).sizing` says what each resolution tier means for that Model: tiers are not pixel counts. With no `outputFormat`, every Model that takes a format returns PNG (in the spelling its endpoint uses); a Model with no format setting is left alone, and `params.output_format` replaces the default. Asking for a format or markup limits the choice to Models that support it. The direct provider image layer described below has its own adapter capabilities and chooses no Model.
 
 Token-billed Task plans, including Sunburst, Flare, Nano Banana 2.1, Banana Lite and MAI 2.5, report `cost: { usd: null, basis: "unknown" }`; a published representative price is not an exact total.
 
-Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"processing"`, then `"completed"` (or `"failed"`). Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
+Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"processing"`, then `"completed"` (or `"failed"`). Passing it sends a generation through fal's queue, since only the queue reports state; a tool that runs synchronously reports nothing. Models without streaming report state, not a percentage.
 
 Pass `onSubmitted(requestId)` to hear the request id the moment fal's queue accepts the run, before any wait. Keep it: after a restart, `motif.resume(task, input, requestId)` waits for that same job and returns its output, submitting nothing and so paying nothing twice. Passing `onSubmitted` also queues the run.
 
@@ -98,7 +100,7 @@ for await (const result of opened.value.events) {
 
 Events use `images`, `progress` or `provider` types. Images carry the same `TaskFile` URL shape as ordinary Task outputs, including data URIs. Progress fractions are normalised only when explicitly between zero and one. The raw provider payload remains available as `raw` or `data`, and SSE event/id metadata is preserved. Preview images depend on the model; an images event is not labelled preview or final, and transport EOF does not prove generation success.
 
-The handle exposes `plan`, optional `requestId` and `abort()`. Consume its events once. Abort, iterator exit and the overall deadline close local consumption; this does not guarantee cancellation of provider work or a refund. There is no queue submission, reconnection or retry. `plan()` remains a normal execution plan, so its `queued` flag describes `run()`, not `stream()`.
+The handle exposes `plan`, optional `requestId` and `abort()`. Consume its events once. Abort, iterator exit and the overall deadline close local consumption; this does not guarantee cancellation of provider work or a refund. There is no queue submission, reconnection or retry. `plan()` remains a normal execution plan, so its `queued` flag, which says whether the Model always uses fal's queue, describes `run()`, not `stream()`.
 
 For a local checkout, `node packages/motif-sdk/examples/stream.mjs` prints the resolved request without a provider call. Adding `--run` spends provider credits; it requires `FAL_KEY` and a built SDK. The runner is a repository example, not a packaged public API.
 

package/dist/image.d.ts

@@ -20,14 +20,7 @@ import { Result } from "neverthrow";
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
-/**
- * `MotifError` and its coercion helper.
- *
- * Extracted from `server.ts` so `server-tools.ts` can construct errors without
- * importing back into `server.ts` — that import was a dependency cycle. Both
- * `server.ts` and `server-tools.ts` import from here, and `server.ts`
- * re-exports `MotifError` so the package's public surface is unchanged.
- */
+/** `MotifError` and the fal HTTP error mapping. */
 declare class MotifError extends Error {
   readonly status: number;
   readonly code?: string;
@@ -118,7 +111,7 @@ interface GenerateImageOptions {
   signal?: AbortSignal;
   /**
    * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
-   * (paired with FalClient.deletePayloads) is
+   * (paired with `MotifClient.deletePayloads`) is
    * `headers: { "X-Fal-Store-IO": "0" }`.
    */
   headers?: Record<string, string>;
@@ -163,7 +156,7 @@ interface EditImageOptions {
   signal?: AbortSignal;
   /**
    * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
-   * (paired with FalClient.deletePayloads) is
+   * (paired with `MotifClient.deletePayloads`) is
    * `headers: { "X-Fal-Store-IO": "0" }`.
    */
   headers?: Record<string, string>;