dreamlayer 0.3.0 → 0.4.0-beta.1

package/README.md

@@ -107,3 +107,20 @@ Node.js 22.12 or later.
 ## License
 
 MIT. See LICENSE and NOTICE.
+
+## Sprite-sheet beta
+
+Sprite requests accept exactly one of `options.animation_prompt` (1–4000 characters) or an `options.action` preset (`walk`, `run`, `idle`). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. `animation_mode` is `loop` or `once`; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.
+
+Request integer `frame_count` 7–100 (default 12) and `frame_size` 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.
+
+Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check `sprite_pricing` in capabilities and approve the quote with `max_credits`. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.
+
+```sh
+dreamlayer sprite character.png --action walk --frames 12 --max-credits 9.9 --out walk.zip
+dreamlayer status EXECUTION_ID
+```
+
+Set `--max-credits` to the amount you approve after checking the current price. The CLI reconnects to existing work if an event stream closes.
+
+For affordability, compare the complete rounded quote in **credits** with `available`. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below `available`; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spriteCreditPrice } from "./client.js";
 /**
  * DreamLayer CLI.
  *
@@ -28,6 +29,7 @@ USAGE
   dreamlayer edit <image> <prompt> [--out <file>]
   dreamlayer cutout <image> [--out <file>]
   dreamlayer upscale <image> [--out <file>]
+  dreamlayer sprite <image> --action <walk|run|idle> [--frames <7–100>] --max-credits <n> [--out <zip>]
   dreamlayer answer <conversation-id> <text> [--image <file>] [--out <file>]
   dreamlayer status <execution-id>
   dreamlayer balance
@@ -37,6 +39,12 @@ OPTIONS
   --out <file>      Where to write the image. Default: dreamlayer-<n>.png
   --image <file>    Attach an image when answering a question that asks for one
   --aspect <ratio>  1:1, 16:9, 9:16, 4:3, 3:4. Default 1:1
+  --action <name>  Sprite preset: walk, run, idle (walk if no custom prompt)
+  --animation-prompt <text>  Custom animation; cannot combine with --action
+  --animation-mode <loop|once>  Default: loop for presets, once for custom
+  --frame-size <px> Square export: 32, 64, 128, 256, 512 (default), 720, 1080
+  --frames <n>      Frame count: integer 7–100, default 12
+  --max-credits <n> Maximum approved charge for the sprite job
   --json            Machine-readable output on stdout
   --quiet           No progress on stderr
   --idempotency-key <key>  Reuse to retry safely after an uncertain response
@@ -45,13 +53,15 @@ ENVIRONMENT
   DREAMLAYER_API_KEY   Required. Get one at https://platform.dreamlayer.io
   DREAMLAYER_API_URL   Override the endpoint. Default https://api.dreamlayer.io
 
-Every finished image costs one credit. A new account starts at zero.
+Image operations cost one credit. Sprite pricing is listed in capabilities. A new account starts at zero.
 `;
 class UsageError extends Error {
 }
 function parseOptions(argv) {
     const positional = [];
     const options = {
+        maxCredits: 1,
+        frameCount: 12,
         out: null,
         image: null,
         aspect: "1:1",
@@ -71,6 +81,42 @@ function parseOptions(argv) {
                 throw new UsageError("--out needs a file path");
             options.out = value;
         }
+        else if (token === "--action") {
+            const value = argv[++i];
+            if (value !== "walk" && value !== "run" && value !== "idle")
+                throw new UsageError("--action must be walk, run, or idle");
+            options.action = value;
+        }
+        else if (token === "--animation-prompt") {
+            const value = argv[++i];
+            if (!value?.trim() || [...value].length > 4000)
+                throw new UsageError("--animation-prompt needs 1–4000 characters");
+            options.animationPrompt = value;
+        }
+        else if (token === "--animation-mode") {
+            const value = argv[++i];
+            if (value !== "loop" && value !== "once")
+                throw new UsageError("--animation-mode must be loop or once");
+            options.animationMode = value;
+        }
+        else if (token === "--frame-size") {
+            const value = Number(argv[++i]);
+            if (![32, 64, 128, 256, 512, 720, 1080].includes(value))
+                throw new UsageError("--frame-size must be 32, 64, 128, 256, 512, 720 or 1080");
+            options.frameSize = value;
+        }
+        else if (token === "--frames") {
+            const value = Number(argv[++i]);
+            if (!Number.isInteger(value) || value < 7 || value > 100)
+                throw new UsageError("--frames must be an integer from 7 to 100");
+            options.frameCount = value;
+        }
+        else if (token === "--max-credits") {
+            const value = Number(argv[++i]);
+            if (!Number.isFinite(value) || value < 0.1 || value > 100)
+                throw new UsageError("--max-credits must be 0.1 to 100");
+            options.maxCredits = value;
+        }
         else if (token === "--image") {
             const value = argv[++i];
             if (!value)
@@ -130,7 +176,7 @@ function defaultOut() {
 async function run(api, input, options) {
     const progress = new Progress(!options.quiet && process.stderr.isTTY === true);
     const idempotencyKey = options.idempotencyKey ?? randomUUID();
-    const outcome = await consume(api.execute(input, { idempotencyKey }), progress);
+    const outcome = await consume(api.follow(input, { idempotencyKey }), progress);
     if (outcome.question) {
         progress.stop();
         if (options.json) {
@@ -161,7 +207,7 @@ async function run(api, input, options) {
     }
     progress.set("Downloading");
     const bytes = await api.download(outcome.asset.download_url);
-    const target = options.out ?? defaultOut();
+    const target = options.out ?? (input.operation === "sprite_sheet" ? `dreamlayer-${Date.now()}.zip` : defaultOut());
     await writeFile(target, bytes);
     progress.stop();
     if (options.json) {
@@ -218,7 +264,7 @@ function warnIfOperationsDrifted(capabilities) {
     const server = new Set(listed);
     const mine = new Set(KNOWN_OPERATIONS);
     const serverOnly = [...server].filter((o) => !mine.has(o));
-    const clientOnly = [...mine].filter((o) => !server.has(o));
+    const clientOnly = [...mine].filter((o) => !server.has(o) && o !== "sprite_sheet");
     if (serverOnly.length === 0 && clientOnly.length === 0)
         return;
     process.stderr.write("\nThis CLI and the server disagree about the operation list.\n");
@@ -250,6 +296,23 @@ async function main(argv) {
     }
     const { positional, options } = parseOptions(rest);
     switch (command) {
+        case "sprite": {
+            if (options.action && options.animationPrompt)
+                throw new UsageError("Use either --action or --animation-prompt, not both");
+            const file = positional[0];
+            if (!file)
+                throw new UsageError("sprite needs a reference image");
+            const api = client();
+            const caps = await api.getCapabilities();
+            if (!Array.isArray(caps.operations) || !caps.operations.includes("sprite_sheet"))
+                throw new UsageError("sprite beta access is not enabled for this account");
+            if (!caps.sprite_pricing)
+                throw new UsageError("The server does not support configurable sprite pricing yet");
+            const price = spriteCreditPrice(options.frameCount);
+            if (options.maxCredits < price)
+                throw new UsageError(`Sprite jobs require ${price} credits. Set --max-credits to approve that amount.`);
+            return run(api, { operation: "sprite_sheet", input_asset_id: await upload(api, file), options: { ...(options.animationPrompt ? { animation_prompt: options.animationPrompt } : { action: options.action ?? "walk" }), ...(options.animationMode ? { animation_mode: options.animationMode } : {}), ...(options.frameSize ? { frame_size: options.frameSize } : {}), frame_count: options.frameCount }, max_credits: options.maxCredits }, options);
+        }
         case "generate": {
             const prompt = positional[0];
             if (!prompt)
@@ -309,6 +372,9 @@ async function main(argv) {
                 process.stdout.write(`${balance.available} credits available ` +
                     `(${balance.promotional} promotional, ${balance.purchased} purchased)\n`);
             }
+            if (!options.json && Math.round(balance.available * 10) > Math.round(balance.promotional * 10) + Math.round(balance.purchased * 10)) {
+                process.stdout.write("Use the available total for affordability. Funding balances are rounded down separately; stored fractions are preserved.\n");
+            }
             return 0;
         }
         case "capabilities": {

package/dist/client.d.ts

@@ -34,7 +34,7 @@ export type ManagedEvent = {
  * anyway. Confirmed against the deployment, not the source: the live /openapi.json
  * advertises exactly these four in both ExecuteRequest and ImageJobCreate.
  */
-export declare const KNOWN_OPERATIONS: readonly ["text_to_image", "image_to_image", "background_remove", "upscale"];
+export declare const KNOWN_OPERATIONS: readonly ["text_to_image", "image_to_image", "background_remove", "upscale", "sprite_sheet"];
 /**
  * Derived from the array above, not written twice.
  *
@@ -53,7 +53,17 @@ export type ManagedExecuteInput = {
     aspect_ratio?: string;
     /** Requires the gateway build that added it. See ManagedOperation. */
     operation?: ManagedOperation;
+    options?: {
+        action?: "walk" | "run" | "idle";
+        animation_prompt?: string;
+        animation_mode?: "loop" | "once";
+        frame_count?: number;
+        frame_size?: 32 | 64 | 128 | 256 | 512 | 720 | 1080;
+    };
+    max_credits?: number;
 };
+export declare function spriteCreditPrice(frameCount: number): number;
+export declare function validateSpriteInput(input: ManagedExecuteInput): void;
 export type ManagedInputAsset = {
     input_asset_id: string;
     width: number;
@@ -66,7 +76,7 @@ export type ManagedExecution = {
     status: string;
     image_job: Record<string, unknown> | null;
 };
-export declare const PUBLIC_ERROR_REASONS: readonly ["invalid_request", "authentication_failed", "access_denied", "resource_not_found", "insufficient_credits", "conflict", "too_many_active_jobs", "rate_limited", "quota_exceeded", "content_refused", "temporarily_unavailable", "generation_failed"];
+export declare const PUBLIC_ERROR_REASONS: readonly ["invalid_request", "authentication_failed", "access_denied", "resource_not_found", "insufficient_credits", "conflict", "too_many_active_jobs", "rate_limited", "quota_exceeded", "content_refused", "temporarily_unavailable", "generation_failed", "insufficient_frames"];
 export type PublicErrorReason = (typeof PUBLIC_ERROR_REASONS)[number];
 export declare class ApiError extends Error {
     readonly status: number;
@@ -130,6 +140,10 @@ export declare class ManagedClient {
     execute(input: ManagedExecuteInput, options: {
         idempotencyKey: string;
     }): AsyncGenerator<ManagedEvent>;
+    /** Follow a durable job across finite streams without submitting it twice. */
+    follow(input: ManagedExecuteInput, options: {
+        idempotencyKey: string;
+    }): AsyncGenerator<ManagedEvent>;
     /** Resume a stream after a drop. Pass the last event id you actually processed. */
     events(executionId: string, lastEventId?: string): AsyncGenerator<ManagedEvent>;
     getCapabilities(): Promise<Record<string, unknown>>;

package/dist/client.js

@@ -33,7 +33,32 @@ export const KNOWN_OPERATIONS = [
     "image_to_image",
     "background_remove",
     "upscale",
+    "sprite_sheet",
 ];
+export function spriteCreditPrice(frameCount) {
+    if (!Number.isInteger(frameCount) || frameCount < 7 || frameCount > 100)
+        throw new Error("frame_count must be an integer from 7 to 100");
+    const cents = 14 * Math.min(frameCount, 14) + 7 * Math.max(frameCount - 14, 0);
+    return Math.ceil(cents * 10 / 17) / 10;
+}
+export function validateSpriteInput(input) {
+    if (input.operation !== "sprite_sheet")
+        return;
+    const options = input.options;
+    if (!options || (options.action === undefined) === (options.animation_prompt === undefined))
+        throw new Error("Sprite requests require exactly one of options.action or options.animation_prompt");
+    if (options.action !== undefined && !["walk", "run", "idle"].includes(options.action))
+        throw new Error("Invalid sprite preset");
+    if (options.animation_prompt !== undefined && (typeof options.animation_prompt !== "string" || !options.animation_prompt.trim() || [...options.animation_prompt].length > 4000))
+        throw new Error("animation_prompt must contain 1–4000 characters");
+    if (options.animation_mode !== undefined && !["loop", "once"].includes(options.animation_mode))
+        throw new Error("animation_mode must be loop or once");
+    const price = spriteCreditPrice(options.frame_count ?? 12);
+    if (options.frame_size !== undefined && ![32, 64, 128, 256, 512, 720, 1080].includes(options.frame_size))
+        throw new Error("frame_size must be 32, 64, 128, 256, 512, 720 or 1080");
+    if (typeof input.max_credits !== "number" || !Number.isFinite(input.max_credits) || input.max_credits < price || input.max_credits > 100)
+        throw new Error(`This sprite request requires ${price} credits. Supply a sufficient max_credits limit.`);
+}
 const DIRECT_INPUT_BYTES = 20 * 1024 * 1024;
 const RASTER_INPUT_SUFFIXES = new Set([".png", ".jpg", ".jpeg", ".webp"]);
 const LEGACY_INPUT_SUFFIXES = new Set([
@@ -54,6 +79,7 @@ export const PUBLIC_ERROR_REASONS = [
     "content_refused",
     "temporarily_unavailable",
     "generation_failed",
+    "insufficient_frames",
 ];
 const PUBLIC_ERROR_SPECS = {
     invalid_request: { message: "The request could not be validated.", retryable: false },
@@ -82,6 +108,7 @@ const PUBLIC_ERROR_SPECS = {
         message: "The service is temporarily unavailable. Please try again.",
         retryable: true,
     },
+    insufficient_frames: { message: "Not enough distinct animation frames. Try a lower frame count.", retryable: false },
     generation_failed: { message: "Image generation failed.", retryable: false },
 };
 const PUBLIC_ERROR_REASON_SET = new Set(PUBLIC_ERROR_REASONS);
@@ -123,6 +150,7 @@ function defaultCode(reason) {
         content_refused: "CONTENT_REFUSED",
         temporarily_unavailable: "SERVICE_UNAVAILABLE",
         generation_failed: "INTERNAL_ERROR",
+        insufficient_frames: "INSUFFICIENT_FRAMES",
     };
     return codes[reason];
 }
@@ -140,6 +168,7 @@ function statusForReason(reason) {
         content_refused: 422,
         temporarily_unavailable: 503,
         generation_failed: 500,
+        insufficient_frames: 422,
     };
     return statuses[reason];
 }
@@ -318,14 +347,17 @@ export function managedBalance(value) {
         throw new Error("Invalid DreamLayer balance response");
     }
     for (const field of ["promotional", "purchased", "available"]) {
-        if (!Number.isSafeInteger(value[field]) || Number(value[field]) < 0) {
+        if (typeof value[field] !== "number" || !Number.isFinite(value[field]) || Number(value[field]) < 0 || Number(value[field]) > Number.MAX_SAFE_INTEGER / 10) {
             throw new Error("Invalid DreamLayer balance response");
         }
     }
     if (value.credit_usd !== "0.17" ||
-        Number(value.available) !== Number(value.promotional) + Number(value.purchased)) {
+        Math.round(Number(value.available) * 10) < Math.round(Number(value.promotional) * 10) + Math.round(Number(value.purchased) * 10) ||
+        Math.round(Number(value.available) * 10) > Math.round(Number(value.promotional) * 10) + Math.round(Number(value.purchased) * 10) + 1) {
         throw new Error("Invalid DreamLayer balance response");
     }
+    if ([value.promotional, value.purchased, value.available].some(v => Math.abs(Number(v) * 10 - Math.round(Number(v) * 10)) > 1e-7))
+        throw new Error("Invalid DreamLayer balance response");
     return {
         promotional: Number(value.promotional),
         purchased: Number(value.purchased),
@@ -518,6 +550,7 @@ export class ManagedClient {
      * so a caller could not even resume what it had already paid for.
      */
     async *execute(input, options) {
+        validateSpriteInput(input);
         const stream = await this.fetchStream("/v1/execute", {
             method: "POST",
             headers: {
@@ -529,6 +562,50 @@ export class ManagedClient {
         });
         yield* this.parse(stream);
     }
+    /** Follow a durable job across finite streams without submitting it twice. */
+    async *follow(input, options) {
+        let executionId;
+        let cursor;
+        let stream = this.execute(input, options);
+        const deadline = Date.now() + 16 * 60_000;
+        let failures = 0;
+        while (Date.now() < deadline) {
+            try {
+                for await (const event of stream) {
+                    if (event.event === "started")
+                        executionId = String(event.data.execution_id);
+                    if (event.id)
+                        cursor = event.id;
+                    yield event;
+                    if (event.event === "done")
+                        return;
+                }
+                failures = 0;
+            }
+            catch (error) {
+                if (error instanceof StreamIdleError)
+                    throw error;
+                if (!executionId || (error instanceof ApiError && ![429, 500, 502, 503, 504].includes(error.status)) || ++failures > 5)
+                    throw error;
+            }
+            if (!executionId)
+                throw new Error("Execution stream ended before an identifier was received; reuse your idempotency key.");
+            const state = await this.getExecution(executionId);
+            if (["completed", "failed", "cancelled"].includes(state.status)) {
+                if (state.status === "completed") {
+                    const assets = state.image_job?.finished_assets;
+                    if (!Array.isArray(assets) || assets.length !== 1 || typeof assets[0]?.download_url !== "string")
+                        throw new Error(`Execution ${executionId} has no downloadable asset yet.`);
+                    yield managedEvent("asset", null, { asset_id: assets[0].asset_id, download_url: assets[0].download_url });
+                }
+                yield managedEvent("done", null, { status: state.status });
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, Math.min(5000, 500 * 2 ** failures)));
+            stream = this.events(executionId, cursor);
+        }
+        throw new Error(`Execution ${executionId ?? "unknown"} is still active. Use status to resume; the job has not been cancelled.`);
+    }
     /** Resume a stream after a drop. Pass the last event id you actually processed. */
     async *events(executionId, lastEventId) {
         const headers = { Accept: "text/event-stream" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamlayer",
-  "version": "0.3.0",
+  "version": "0.4.0-beta.1",
   "description": "Generate and edit images from your terminal, over local files, with one API key.",
   "license": "MIT",
   "type": "module",