dreamlayer 0.2.0 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ dreamlayer cutout <image> [--out file.png]      # background removal
 dreamlayer upscale <image> [--out file.png]     # 2x
 dreamlayer answer <conversation-id> <text> [--image file.png]
 dreamlayer status <execution-id>
+dreamlayer balance                              # spends nothing
 dreamlayer capabilities                         # spends nothing
 ```
 
@@ -52,7 +53,7 @@ open "$(dreamlayer generate 'a fox logo')"
 | 1 | Usage error |
 | 2 | Auth or account problem |
 | 3 | Out of credits |
-| 4 | Request rejected, will fail identically until you change it |
+| 4 | Non-retryable request or execution failure |
 | 5 | Temporary, worth retrying |
 | 6 | It asked a question instead of producing an image |
 
@@ -60,9 +61,19 @@ open "$(dreamlayer generate 'a fox logo')"
 for f in shots/*.png; do dreamlayer cutout "$f" --out "cut/$(basename "$f")" || break; done
 ```
 
-**`--json`** gives machine-readable output on stdout, carrying job state, execution ids,
-and the written path. It deliberately excludes your prompt, your images, and your key,
-so it is safe to paste into a bug report.
+**`--json`** gives machine-readable success output on stdout, carrying job state,
+execution ids, and the written path. Errors use the same stable `code`, `reason`,
+`message`, `retryable`, and `request_id` fields as REST and are written to stderr, so
+stdout stays result-only. Error envelopes deliberately exclude your prompt, images,
+local filenames, and key. Successful image JSON includes the destination path you chose;
+remove it before sharing if the local name is private.
+
+Check the authenticated key's own balance without starting image work:
+
+```bash
+dreamlayer balance
+dreamlayer balance --json
+```
 
 ## Retries are safe if you reuse the key
 

package/dist/cli.js

@@ -18,7 +18,7 @@ import { randomUUID } from "node:crypto";
 import { openAsBlob, readFileSync } from "node:fs";
 import { stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { ApiError, KNOWN_OPERATIONS, ManagedClient, StreamIdleError, UploadTimeoutError, } from "./client.js";
+import { ApiError, KNOWN_OPERATIONS, ManagedClient, StreamIdleError, UploadTimeoutError, terminalExecutionError, } from "./client.js";
 import { Progress, consume } from "./render.js";
 const PACKAGE_VERSION = String(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
 const USAGE = `dreamlayer - generate and edit images from your terminal
@@ -30,6 +30,7 @@ USAGE
   dreamlayer upscale <image> [--out <file>]
   dreamlayer answer <conversation-id> <text> [--image <file>] [--out <file>]
   dreamlayer status <execution-id>
+  dreamlayer balance
   dreamlayer capabilities
 
 OPTIONS
@@ -146,7 +147,12 @@ async function run(api, input, options) {
         return 6;
     }
     if (outcome.status !== "completed" || !outcome.asset) {
-        progress.stop("Failed");
+        progress.stop(options.json ? undefined : "Failed");
+        if (outcome.status === "failed" && outcome.execution_id) {
+            const terminal = terminalExecutionError(await api.getExecution(outcome.execution_id));
+            if (terminal)
+                throw terminal;
+        }
         if (options.json)
             process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
         else
@@ -226,13 +232,11 @@ function warnIfOperationsDrifted(capabilities) {
     }
 }
 function exitCodeFor(error) {
-    if (error.status === 401 || error.status === 403)
+    if (error.reason === "authentication_failed" || error.reason === "access_denied")
         return 2;
-    if (error.status === 402)
+    if (error.reason === "insufficient_credits" || error.reason === "quota_exceeded")
         return 3;
-    if (error.status === 409 || error.status === 422)
-        return 4;
-    return 5;
+    return error.retryable ? 5 : 4;
 }
 async function main(argv) {
     const [command, ...rest] = argv;
@@ -294,6 +298,19 @@ async function main(argv) {
             process.stdout.write(`${JSON.stringify(execution, null, 2)}\n`);
             return 0;
         }
+        case "balance": {
+            if (positional.length > 0)
+                throw new UsageError("balance takes no arguments");
+            const balance = await client().getBalance();
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(balance, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${balance.available} credits available ` +
+                    `(${balance.promotional} promotional, ${balance.purchased} purchased)\n`);
+            }
+            return 0;
+        }
         case "capabilities": {
             const capabilities = await client().getCapabilities();
             process.stdout.write(`${JSON.stringify(capabilities, null, 2)}\n`);
@@ -315,12 +332,17 @@ main(process.argv.slice(2))
         return;
     }
     if (error instanceof ApiError) {
-        const hint = error.status === 402
+        const hint = error.reason === "insufficient_credits"
             ? "Buy credits at https://platform.dreamlayer.io/console/billing"
             : error.retryable
                 ? "Temporary. Retry with --idempotency-key to avoid paying twice."
                 : "";
-        process.stderr.write(`${error.message}${hint ? `\n${hint}` : ""}\n`);
+        if (process.argv.slice(2).includes("--json")) {
+            process.stderr.write(`${JSON.stringify(error.toPublicEnvelope())}\n`);
+        }
+        else {
+            process.stderr.write(`${error.message}\nReason: ${error.reason}${hint ? `\n${hint}` : ""}\n`);
+        }
         process.exitCode = exitCodeFor(error);
         return;
     }

package/dist/client.d.ts

@@ -66,17 +66,28 @@ 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 type PublicErrorReason = (typeof PUBLIC_ERROR_REASONS)[number];
 export declare class ApiError extends Error {
     readonly status: number;
-    readonly detail: string | null;
-    /** Server-assigned id for this failure. The only handle support can search on. */
+    readonly detail: string;
     readonly requestId: string | null;
+    readonly code: string;
+    readonly reason: PublicErrorReason;
     constructor(status: number, surface?: string, detail?: string | null, 
     /** Server-assigned id for this failure. The only handle support can search on. */
-    requestId?: string | null);
+    requestId?: string | null, code?: string | null, reason?: PublicErrorReason);
     /** Whether retrying with the same idempotency key is worth doing. */
     get retryable(): boolean;
+    /** The same stable fields exposed by REST and MCP, with no private response text. */
+    toPublicEnvelope(): Record<string, unknown>;
 }
+export type ManagedBalance = {
+    promotional: number;
+    purchased: number;
+    available: number;
+    credit_usd: "0.17";
+};
 /**
  * A stream that went silent, as distinct from a slow one.
  *
@@ -93,6 +104,9 @@ export declare class UploadTimeoutError extends Error {
     constructor();
 }
 export declare function uploadTimeoutMs(bytes: number): number;
+export declare function managedBalance(value: unknown): ManagedBalance;
+/** Convert a terminal job failure into the same safe contract used by HTTP errors. */
+export declare function terminalExecutionError(execution: ManagedExecution): ApiError | null;
 /**
  * Validate one sanitized event against the published contract.
  *
@@ -120,6 +134,7 @@ export declare class ManagedClient {
     events(executionId: string, lastEventId?: string): AsyncGenerator<ManagedEvent>;
     getCapabilities(): Promise<Record<string, unknown>>;
     getExecution(executionId: string): Promise<ManagedExecution>;
+    getBalance(): Promise<ManagedBalance>;
     cancel(executionId: string): Promise<ManagedExecution>;
     listConversations(): Promise<Array<Record<string, unknown>>>;
     deleteConversation(conversationId: string): Promise<void>;

package/dist/client.js

@@ -41,24 +41,145 @@ const LEGACY_INPUT_SUFFIXES = new Set([
     ".arw", ".cr2", ".cr3", ".crw", ".dng", ".nef", ".nrw", ".orf", ".pef",
     ".raf", ".rw2", ".sr2", ".srw",
 ]);
+export const PUBLIC_ERROR_REASONS = [
+    "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",
+];
+const PUBLIC_ERROR_SPECS = {
+    invalid_request: { message: "The request could not be validated.", retryable: false },
+    authentication_failed: { message: "Authentication failed.", retryable: false },
+    access_denied: {
+        message: "This request is not available for this account.",
+        retryable: false,
+    },
+    resource_not_found: { message: "The requested item was not found.", retryable: false },
+    insufficient_credits: {
+        message: "The account has insufficient credits.",
+        retryable: false,
+    },
+    conflict: { message: "The request conflicts with the current state.", retryable: false },
+    too_many_active_jobs: {
+        message: "Too many image jobs are already in progress.",
+        retryable: true,
+    },
+    rate_limited: { message: "Too many requests. Please try again shortly.", retryable: true },
+    quota_exceeded: { message: "The account quota has been reached.", retryable: false },
+    content_refused: {
+        message: "The request could not be completed under the service policy.",
+        retryable: false,
+    },
+    temporarily_unavailable: {
+        message: "The service is temporarily unavailable. Please try again.",
+        retryable: true,
+    },
+    generation_failed: { message: "Image generation failed.", retryable: false },
+};
+const PUBLIC_ERROR_REASON_SET = new Set(PUBLIC_ERROR_REASONS);
+function publicReason(value) {
+    return typeof value === "string" && PUBLIC_ERROR_REASON_SET.has(value)
+        ? value
+        : null;
+}
+function reasonForStatus(status) {
+    if (status === 400 || status === 405 || status === 422)
+        return "invalid_request";
+    if (status === 401)
+        return "authentication_failed";
+    if (status === 403)
+        return "access_denied";
+    if (status === 404)
+        return "resource_not_found";
+    if (status === 402)
+        return "insufficient_credits";
+    if (status === 409)
+        return "conflict";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 502 || status === 503 || status === 504)
+        return "temporarily_unavailable";
+    return "generation_failed";
+}
+function defaultCode(reason) {
+    const codes = {
+        invalid_request: "VALIDATION_FAILED",
+        authentication_failed: "AUTHENTICATION_FAILED",
+        access_denied: "FORBIDDEN",
+        resource_not_found: "NOT_FOUND",
+        insufficient_credits: "BUDGET_EXCEEDED",
+        conflict: "CONFLICT",
+        too_many_active_jobs: "RATE_LIMITED",
+        rate_limited: "RATE_LIMITED",
+        quota_exceeded: "BUDGET_EXCEEDED",
+        content_refused: "CONTENT_REFUSED",
+        temporarily_unavailable: "SERVICE_UNAVAILABLE",
+        generation_failed: "INTERNAL_ERROR",
+    };
+    return codes[reason];
+}
+function statusForReason(reason) {
+    const statuses = {
+        invalid_request: 422,
+        authentication_failed: 401,
+        access_denied: 403,
+        resource_not_found: 404,
+        insufficient_credits: 402,
+        conflict: 409,
+        too_many_active_jobs: 429,
+        rate_limited: 429,
+        quota_exceeded: 402,
+        content_refused: 422,
+        temporarily_unavailable: 503,
+        generation_failed: 500,
+    };
+    return statuses[reason];
+}
+const ERROR_IDENTIFIER_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+function publicIdentifier(value) {
+    return typeof value === "string" && ERROR_IDENTIFIER_PATTERN.test(value) ? value : null;
+}
 export class ApiError extends Error {
     status;
     detail;
     requestId;
+    code;
+    reason;
     constructor(status, surface = "DreamLayer Agent API", detail = null, 
     /** Server-assigned id for this failure. The only handle support can search on. */
-    requestId = null) {
-        super(detail
-            ? `${detail}${requestId ? ` (request ${requestId})` : ""}`
-            : `${surface} request failed (${status})`);
+    requestId = null, code = null, reason = reasonForStatus(status)) {
+        const safeDetail = detail ?? PUBLIC_ERROR_SPECS[reason].message;
+        super(`${safeDetail || `${surface} request failed (${status})`}${requestId ? ` (request ${requestId})` : ""}`);
         this.status = status;
-        this.detail = detail;
-        this.requestId = requestId;
         this.name = "ApiError";
+        this.detail = safeDetail;
+        this.requestId = requestId;
+        this.code = code ?? defaultCode(reason);
+        this.reason = reason;
     }
     /** Whether retrying with the same idempotency key is worth doing. */
     get retryable() {
-        return this.status === 429 || this.status >= 500;
+        return PUBLIC_ERROR_SPECS[this.reason].retryable;
+    }
+    /** The same stable fields exposed by REST and MCP, with no private response text. */
+    toPublicEnvelope() {
+        return {
+            error: {
+                code: this.code,
+                reason: this.reason,
+                message: this.detail,
+                retryable: this.retryable,
+                request_id: this.requestId,
+            },
+        };
     }
 }
 /**
@@ -84,7 +205,6 @@ export class UploadTimeoutError extends Error {
     }
 }
 const ERROR_BODY_LIMIT = 16 * 1024;
-const ERROR_DETAIL_LIMIT = 300;
 /**
  * A plain request: send, get a body back. Bounded work, so a total cap is right.
  */
@@ -130,40 +250,52 @@ const STREAM_IDLE_TIMEOUT_MS = (() => {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function sanitizedErrorDetail(value) {
-    if (typeof value !== "string")
-        return null;
-    const normalized = value
-        .replace(/[\u0000-\u001f\u007f]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-    return normalized ? normalized.slice(0, ERROR_DETAIL_LIMIT) : null;
+async function boundedErrorBody(response) {
+    const length = Number(response.headers.get("content-length") ?? "0");
+    if (!Number.isFinite(length) || length < 0 || length > ERROR_BODY_LIMIT || !response.body) {
+        return "";
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let total = 0;
+    let body = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return body + decoder.decode();
+            total += value.byteLength;
+            if (total > ERROR_BODY_LIMIT) {
+                await reader.cancel();
+                return "";
+            }
+            body += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
 }
 async function apiError(response, surface = "DreamLayer Agent API") {
-    let detail = null;
-    let requestId = null;
+    let reason = reasonForStatus(response.status);
+    let code = null;
+    let requestId = publicRequestId(response.headers.get("x-request-id"));
     try {
-        const length = Number(response.headers.get("content-length") ?? "0");
-        if (!Number.isFinite(length) || length < 0 || length > ERROR_BODY_LIMIT) {
-            return new ApiError(response.status, surface);
-        }
-        const parsed = JSON.parse(await response.text());
-        if (isRecord(parsed)) {
-            // Two shapes in the wild. The gateway returns
-            // {"error":{"code","message","category","request_id"}}; older surfaces and
-            // FastAPI's own handlers return {"detail": "..."}. Reading only the latter is
-            // why every failure used to print a bare status code and nothing else.
-            detail = sanitizedErrorDetail(parsed.detail);
-            if (isRecord(parsed.error)) {
-                detail = detail ?? sanitizedErrorDetail(parsed.error.message);
-                requestId = sanitizedErrorDetail(parsed.error.request_id);
-            }
+        const raw = await boundedErrorBody(response);
+        const parsed = raw ? JSON.parse(raw) : null;
+        if (isRecord(parsed) && isRecord(parsed.error)) {
+            // Treat only the closed reason/code/id fields as data. The local message table
+            // deliberately ignores arbitrary remote detail so a private upstream response
+            // cannot leak through a client even if a server regression serializes it.
+            reason = publicReason(parsed.error.reason) ?? reason;
+            code = publicIdentifier(parsed.error.code);
+            requestId = publicRequestId(parsed.error.request_id) ?? requestId;
         }
     }
     catch {
-        detail = null;
+        // A malformed or oversized response still becomes a closed, status-derived error.
     }
-    return new ApiError(response.status, surface, detail, requestId);
+    return new ApiError(response.status, surface, null, requestId, code, reason);
 }
 const MANAGED_EVENT_NAMES = new Set([
     "started",
@@ -175,6 +307,41 @@ const MANAGED_EVENT_NAMES = new Set([
     "done",
 ]);
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function publicRequestId(value) {
+    return typeof value === "string" && UUID_PATTERN.test(value) ? value : null;
+}
+export function managedBalance(value) {
+    if (!isRecord(value))
+        throw new Error("Invalid DreamLayer balance response");
+    const exact = ["available", "credit_usd", "promotional", "purchased"];
+    if (Object.keys(value).sort().join("\0") !== exact.join("\0")) {
+        throw new Error("Invalid DreamLayer balance response");
+    }
+    for (const field of ["promotional", "purchased", "available"]) {
+        if (!Number.isSafeInteger(value[field]) || Number(value[field]) < 0) {
+            throw new Error("Invalid DreamLayer balance response");
+        }
+    }
+    if (value.credit_usd !== "0.17" ||
+        Number(value.available) !== Number(value.promotional) + Number(value.purchased)) {
+        throw new Error("Invalid DreamLayer balance response");
+    }
+    return {
+        promotional: Number(value.promotional),
+        purchased: Number(value.purchased),
+        available: Number(value.available),
+        credit_usd: "0.17",
+    };
+}
+/** Convert a terminal job failure into the same safe contract used by HTTP errors. */
+export function terminalExecutionError(execution) {
+    if (!isRecord(execution.image_job) || !isRecord(execution.image_job.sanitized_error)) {
+        return execution.status === "failed" ? new ApiError(500) : null;
+    }
+    const error = execution.image_job.sanitized_error;
+    const reason = publicReason(error.reason) ?? "generation_failed";
+    return new ApiError(statusForReason(reason), "DreamLayer execution", null, publicRequestId(error.request_id), publicIdentifier(error.code), reason);
+}
 /**
  * Validate one sanitized event against the published contract.
  *
@@ -386,6 +553,9 @@ export class ManagedClient {
     getExecution(executionId) {
         return this.request(`/v1/executions/${encodeURIComponent(executionId)}`);
     }
+    async getBalance() {
+        return managedBalance(await this.request("/v1/balance"));
+    }
     cancel(executionId) {
         return this.request(`/v1/executions/${encodeURIComponent(executionId)}/cancel`, {
             method: "POST",

package/package.json

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