@clickraft/cli 0.8.4 → 0.8.6

package/dist/cli.js

@@ -10,6 +10,10 @@ import { z } from "zod";
 import { z as z2 } from "zod";
 import { z as z3 } from "zod";
 import { z as z4 } from "zod";
+import { request as undiciRequest } from "undici";
+import { z as z6 } from "zod";
+import { createHash, randomUUID } from "crypto";
+import { z as z5 } from "zod";
 var TOKEN_FIELD_PATTERN = /"(access_token|refresh_token|device_code|user_code|code_verifier|client_secret)"\s*:\s*"[^"]*"/gi;
 var BARE_TOKEN_PATTERN = /\bck_(?:live|dev|test)_[A-Za-z0-9_-]+/gi;
 function redactTokenLikeFields(input) {
@@ -202,432 +206,6 @@ function composeIterationSignal(userSignal, remainingMs) {
   const deadlineSignal = AbortSignal.timeout(Math.max(remainingMs, 0));
   return userSignal ? AbortSignal.any([userSignal, deadlineSignal]) : deadlineSignal;
 }
-
-// src/api/client.ts
-import { request as undiciRequest } from "undici";
-import { z as z6 } from "zod";
-
-// src/errors/codes.ts
-var LOGIN_HINT = "Run `clickraft login` to authenticate.";
-var RELOGIN_HINT = "Run `clickraft login` to refresh.";
-var EXIT_CODE_MAP = {
-  // --- 37 Phase 8 Q7 codes ----------------------------------------------------
-  AUTH_TOKEN_MISSING: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "Set `CLICKRAFT_TOKEN` or run `clickraft login`."
-  },
-  AUTH_TOKEN_INVALID: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "The token is malformed or unknown. Run `clickraft login`."
-  },
-  AUTH_TOKEN_EXPIRED: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: RELOGIN_HINT
-  },
-  AUTH_TOKEN_REVOKED: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "Token was revoked. Run `clickraft login` to mint a new one."
-  },
-  AUTH_TOKEN_SCOPE_INSUFFICIENT: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "This token does not have the required scope. Re-run `clickraft login` selecting the needed scopes."
-  },
-  AUTH_ORG_MISMATCH: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "This token's org no longer exists or you have been removed."
-  },
-  AUTH_DEVICE_CODE_PENDING: {
-    exitCode: 0,
-    category: "success",
-    retryable: false,
-    hint: "Continue polling."
-  },
-  AUTH_DEVICE_CODE_EXPIRED: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "Device code expired. Re-run `clickraft login`."
-  },
-  AUTH_DEVICE_CODE_SLOW_DOWN: {
-    exitCode: 0,
-    category: "success",
-    retryable: false,
-    hint: "Increase polling interval (Retry-After)."
-  },
-  IDEMPOTENCY_KEY_MISSING: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Add `X-Idempotency-Key` header (or `--idempotency-key`)."
-  },
-  IDEMPOTENCY_KEY_CONFLICT: {
-    exitCode: 7,
-    category: "conflict",
-    retryable: false,
-    hint: "Same key was used with a different request body. Use a new key."
-  },
-  PLAN_FEATURE_LOCKED: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "API access is not enabled on your plan. Visit billing settings."
-  },
-  PLAN_QUOTA_EXCEEDED: {
-    exitCode: 5,
-    category: "quota",
-    retryable: false,
-    hint: "Daily API quota exhausted. Wait, or upgrade your plan."
-  },
-  INSUFFICIENT_CREDITS: {
-    exitCode: 5,
-    category: "quota",
-    retryable: false,
-    hint: "Top up credits to retry."
-  },
-  CREDIT_DEDUCTION_FAILED: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Could not charge credits. Retry; no charge was made."
-  },
-  RATE_LIMITED: {
-    exitCode: 5,
-    category: "quota",
-    retryable: true,
-    hint: "Slow down. Honor Retry-After."
-  },
-  INPUT_INVALID_FORMAT: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Check input format and try again."
-  },
-  INPUT_TOO_LONG: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Field exceeded max length."
-  },
-  WORKFLOW_VALIDATION_FAILED: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Run `workflow validate` for the full list of errors."
-  },
-  WORKFLOW_NODE_TYPE_UNKNOWN: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Run `clickraft nodes list` for the current set of node types."
-  },
-  CANVAS_REV_MISMATCH: {
-    exitCode: 7,
-    category: "conflict",
-    retryable: false,
-    hint: "The workflow was updated elsewhere. Re-fetch and retry with the current canvas_rev."
-  },
-  CANVAS_REV_REQUIRED: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Include --canvas-rev or use --auto-rev."
-  },
-  WORKER_UNREACHABLE: {
-    exitCode: 6,
-    category: "network",
-    retryable: true,
-    hint: "Collaboration service temporarily unavailable. Retry."
-  },
-  IDEMPOTENCY_IN_PROGRESS: {
-    exitCode: 7,
-    category: "conflict",
-    retryable: false,
-    hint: "A request with this idempotency key is currently in-flight. Retry in a moment."
-  },
-  TOKEN_NAME_INVALID: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Agent token name is malformed."
-  },
-  WORKFLOW_NOT_FOUND: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "No workflow with that ID in your org."
-  },
-  NOT_FOUND: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Resource not found."
-  },
-  NODE_TYPE_NOT_FOUND: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Run `clickraft nodes list` for the current set of node types."
-  },
-  FEATURE_DISABLED: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "This endpoint is not enabled. Contact support if you believe this is in error."
-  },
-  FORBIDDEN: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "Your role does not permit this action."
-  },
-  MODEL_NOT_FOUND: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Unknown `modelSlug`. Run `brand-model list` for the current set."
-  },
-  PROVIDER_UNAVAILABLE: {
-    exitCode: 6,
-    category: "network",
-    retryable: true,
-    hint: "Provider is temporarily unavailable. Retry shortly."
-  },
-  STORAGE_UPLOAD_FAILED: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Upload failed mid-stream. Retry."
-  },
-  STORAGE_QUOTA_EXCEEDED: {
-    exitCode: 5,
-    category: "quota",
-    retryable: false,
-    hint: "Org storage quota exceeded. Free space or upgrade."
-  },
-  GEN_CONTENT_REFUSAL: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "The model declined the request via safety policy."
-  },
-  GEN_OUTPUT_SCHEMA_MISMATCH: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Provider returned malformed output. Full refund issued. Retry."
-  },
-  GEN_EMPTY_OUTPUT: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Provider returned no usable output. Full refund issued. Retry."
-  },
-  GEN_ITEM_COUNT_MISMATCH: {
-    exitCode: 0,
-    category: "success",
-    retryable: false,
-    hint: "Partial output kept; no refund."
-  },
-  AGENT_FINGERPRINT_REJECTED: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "This client identification is not permitted. Contact support."
-  },
-  INTERNAL_ERROR: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Server error. Retry; if it persists, contact support with the request ID."
-  },
-  CREDENTIALS_LOCKED: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: true,
-    hint: "Another CLI invocation holds the credentials lock. Retry shortly."
-  },
-  CREDENTIALS_PERMISSIONS_LOOSE: {
-    exitCode: 0,
-    category: "success",
-    retryable: false,
-    hint: "Credentials file mode is wider than 0600; continuing."
-  },
-  // --- 5 additional codes introduced by 1A.1 ---------------------------------
-  AUTH_ACCESS_DENIED: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "You denied the OAuth grant. Re-run `clickraft login` to retry."
-  },
-  AUTH_FLOW_CANCELLED: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: "Authentication was cancelled. Re-run `clickraft login`."
-  },
-  CREDENTIALS_CORRUPT: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Credentials file is unreadable. Remove it and run `clickraft login`."
-  },
-  CREDENTIALS_NOT_FOUND: {
-    exitCode: 3,
-    category: "auth",
-    retryable: false,
-    hint: LOGIN_HINT
-  },
-  CREDENTIALS_PROFILE_NOT_FOUND: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "No such profile. Use `clickraft auth profiles` to list available profiles."
-  },
-  // --- 8 brand model resolution codes -----------------------------------------
-  BRAND_MODEL_NOT_FOUND: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "No brand model with that ID. Run `clickraft brand-model list`."
-  },
-  BRAND_MODEL_NOT_A_MODEL: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "The specified asset is not a brand model."
-  },
-  BRAND_MODEL_NOT_ACTIVE: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Brand model is not active. Check its status in the dashboard."
-  },
-  BRAND_MODEL_NO_REFERENCES: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Brand model has no reference images. Upload references first."
-  },
-  BRAND_MODEL_POSE_NOT_FOUND: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Requested pose not found. Valid: front, 3/4-right, right, left, 3/4-left, back, approved."
-  },
-  BRAND_MODEL_DUPLICATE_ID: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Same brand model ID appears more than once."
-  },
-  MODEL_DOES_NOT_SUPPORT_REFERENCES: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "This model does not support brand model references."
-  },
-  REFERENCE_LIMIT_EXCEEDED: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Too many reference images. Check model limits."
-  },
-  // --- 8 product reference resolver codes -------------------------------------
-  PRODUCT_NOT_FOUND: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "No product with that ID in your org. Run `clickraft product list`."
-  },
-  PRODUCT_DUPLICATE_REFERENCE: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "Same (productId, imageId) tuple appears twice in the request."
-  },
-  PRODUCT_IMAGE_NOT_FOUND: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "imageId does not exist in the product images."
-  },
-  PRODUCT_IMAGE_MISMATCH: {
-    exitCode: 2,
-    category: "usage",
-    retryable: false,
-    hint: "imageId belongs to a different product."
-  },
-  PRODUCT_SYNC_ERROR: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Product sync status is 'error'. Re-sync or use a different product."
-  },
-  PRODUCT_DELETED_UPSTREAM: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Product was deleted upstream. Remove it or re-sync."
-  },
-  PRODUCT_NO_PRIMARY_IMAGE: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Product has no primary image. Specify --product <id>:<imageId> explicitly."
-  },
-  PRODUCT_SOURCE_MANAGED: {
-    exitCode: 4,
-    category: "permission",
-    retryable: false,
-    hint: "Product is managed by an external integration."
-  },
-  // --- 4 CLI-synthetic codes --------------------------------------------------
-  NETWORK_ERROR: {
-    exitCode: 6,
-    category: "network",
-    retryable: true,
-    hint: "Network connection failed. Check connectivity and retry."
-  },
-  TIMEOUT: {
-    exitCode: 6,
-    category: "network",
-    retryable: true,
-    hint: "Request timed out. Retry; consider increasing the timeout."
-  },
-  PARSE_ERROR: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Server returned an unexpected response. Contact support with the request ID."
-  },
-  SCHEMA_MISMATCH: {
-    exitCode: 1,
-    category: "runtime",
-    retryable: false,
-    hint: "Server response did not match the expected schema. Update the CLI."
-  }
-};
-function getExitCode(code) {
-  return EXIT_CODE_MAP[code]?.exitCode ?? 1;
-}
-function toEnvelopeCode(code) {
-  return code.startsWith("E_") ? code : `E_${code}`;
-}
-var SIGINT_EXIT_CODE = 130;
-
-// src/errors/schema-mismatch.ts
 var MAX_ISSUES = 5;
 function formatSchemaIssues(error) {
   const issues = error.issues;
@@ -651,9 +229,6 @@ function formatPath(path) {
   if (path.length === 0) return "(root)";
   return path.map(String).join(".");
 }
-
-// src/api/idempotency.ts
-import { createHash, randomUUID } from "crypto";
 function generateIdempotencyKey() {
   return randomUUID();
 }
@@ -661,8 +236,6 @@ function generateUploadIdempotencyKey(content, scope) {
   const hash = createHash("sha256").update(content).digest("hex");
   return `upload-${scope}-${hash}`;
 }
-
-// src/api/retry.ts
 var DEFAULT_RETRY_OPTIONS = {
   maxAttempts: 3,
   baseDelayMs: 200,
@@ -676,7 +249,7 @@ function computeBackoffMs(attempt, baseDelayMs, maxDelayMs, jitterFraction) {
   return Math.max(0, Math.round(exp + jitter));
 }
 function decideRetry(params) {
-  const { attempt, options, serverRetryAfterMs, isNetworkError, isRetryable } = params;
+  const { attempt, options, serverRetryAfterMs, isNetworkError, isRetryable, onWarning: onWarning2 } = params;
   if (options.signal?.aborted) {
     return { shouldRetry: false, delayMs: 0, reason: "aborted" };
   }
@@ -689,7 +262,7 @@ function decideRetry(params) {
   if (typeof serverRetryAfterMs === "number" && serverRetryAfterMs >= 0) {
     let delayMs2 = serverRetryAfterMs;
     if (delayMs2 > ABSOLUTE_MAX_RETRY_AFTER_MS) {
-      console.warn(`Server Retry-After exceeded ${ABSOLUTE_MAX_RETRY_AFTER_MS}ms; clipping.`);
+      onWarning2?.(`Server Retry-After exceeded ${ABSOLUTE_MAX_RETRY_AFTER_MS}ms; clipping.`);
       delayMs2 = ABSOLUTE_MAX_RETRY_AFTER_MS;
     }
     return { shouldRetry: true, delayMs: delayMs2, reason: "rate_limited" };
@@ -729,9 +302,6 @@ function signalToAbortError(signal) {
   err.name = "AbortError";
   return err;
 }
-
-// src/api/types.ts
-import { z as z5 } from "zod";
 var ServerSuccessSchema = (payload) => z5.object({ data: payload }).strict();
 var ServerErrorBodySchema = z5.object({
   error: z5.object({
@@ -742,8 +312,6 @@ var ServerErrorBodySchema = z5.object({
     details: z5.unknown().optional()
   }).strict()
 }).strict();
-
-// src/api/client.ts
 var REDACT_BODY_LIMIT = 1024;
 var REDACT_INPUT_CAP = 100 * 1024;
 var DEFAULT_USER_AGENT = "clickraft-cli";
@@ -800,7 +368,8 @@ var ApiClient = class {
           options: { ...retry, signal },
           serverRetryAfterMs: err.meta.retryAfterMs,
           isNetworkError,
-          isRetryable
+          isRetryable,
+          onWarning: this.options.onWarning
         });
         if (!decision.shouldRetry) throw err;
         try {
@@ -888,178 +457,654 @@ var ApiClient = class {
       bodyText,
       statusCode,
       requestId,
-      retryAfterHeader: pickHeader(responseHeaders, "retry-after")
+      retryAfterHeader: pickHeader(responseHeaders, "retry-after"),
+      onWarning: this.options.onWarning,
+      isRetryableServerCode: this.options.isRetryableServerCode
     });
   }
 };
-function parseSuccessBody(args) {
-  let parsed;
-  try {
-    parsed = JSON.parse(args.bodyText);
-  } catch (err) {
-    throw new ApiError(
-      "PARSE_ERROR",
-      "Server returned a non-JSON response.",
-      {
-        status: args.statusCode,
-        requestId: args.requestId,
-        retryable: false,
-        redactedBody: redactAndTruncate(args.bodyText)
-      },
-      err
-    );
-  }
-  const envelope = ServerSuccessSchema(args.responseSchema ?? z6.unknown()).safeParse(parsed);
-  if (!envelope.success) {
-    const issues = formatSchemaIssues(envelope.error);
-    throw new ApiError(
-      "SCHEMA_MISMATCH",
-      `Server response did not match the expected schema. Issues: ${issues}`,
-      {
-        status: args.statusCode,
-        requestId: args.requestId,
-        retryable: false,
-        redactedBody: redactAndTruncate(args.bodyText)
-      }
-    );
-  }
-  return envelope.data.data;
-}
-function parseErrorBody(args) {
-  const redactedBody = redactAndTruncate(args.bodyText);
-  let parsed;
-  try {
-    parsed = JSON.parse(args.bodyText);
-  } catch {
-    return new ApiError(
-      "PARSE_ERROR",
-      `Server returned a ${args.statusCode} response with a non-JSON body.`,
-      {
-        status: args.statusCode,
-        requestId: args.requestId,
-        retryable: args.statusCode >= 500,
-        redactedBody
-      }
-    );
-  }
-  const envelope = ServerErrorBodySchema.safeParse(parsed);
-  if (!envelope.success) {
-    return new ApiError(
-      "PARSE_ERROR",
-      `Server returned ${args.statusCode} but body did not match the error envelope.`,
-      {
-        status: args.statusCode,
-        requestId: args.requestId,
-        retryable: args.statusCode >= 500,
-        redactedBody
-      }
-    );
-  }
-  return apiErrorFromServerBody({
-    body: envelope.data,
-    statusCode: args.statusCode,
-    requestId: args.requestId,
-    retryAfterHeader: args.retryAfterHeader,
-    redactedBody
-  });
-}
-function apiErrorFromServerBody(args) {
-  const { error } = args.body;
-  let code;
-  let safeMessage;
-  if (KNOWN_SERVER_CODES.has(error.code)) {
-    code = error.code;
-    safeMessage = redactTokenLikeFields(error.message);
-  } else {
-    const redactedRawCode = redactTokenLikeFields(error.code);
-    console.warn(`Unknown server error code: ${redactedRawCode}. Treating as INTERNAL_ERROR.`);
-    code = "INTERNAL_ERROR";
-    safeMessage = `Unknown server error code: ${redactedRawCode}.`;
-  }
-  const mapping = EXIT_CODE_MAP[code];
-  const retryable = mapping?.retryable ?? (args.statusCode >= 500 || args.statusCode === 429);
-  const retryAfterMs = typeof error.retryAfter === "number" ? error.retryAfter * 1e3 : parseRetryAfterHeader(args.retryAfterHeader);
-  return new ApiError(code, safeMessage, {
-    status: args.statusCode,
-    requestId: error.correlationId ?? args.requestId,
-    retryable,
-    retryAfterMs,
-    redactedBody: args.redactedBody,
-    details: error.details
-  });
-}
-function parseRetryAfterHeader(headerValue) {
-  if (!headerValue) return void 0;
-  const trimmed = headerValue.trim();
-  if (/^\d+$/.test(trimmed)) {
-    return Number.parseInt(trimmed, 10) * 1e3;
-  }
-  if (/[A-Za-z]/.test(trimmed)) {
-    const parsed = Date.parse(trimmed);
-    if (!Number.isNaN(parsed)) {
-      return Math.max(0, parsed - Date.now());
-    }
-  }
-  return void 0;
-}
-function buildUrl(baseUrl, path, query) {
-  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
-  const relative = path.startsWith("/") ? path.slice(1) : path;
-  const url = new URL(relative, base);
-  if (query) {
-    for (const [key, value] of Object.entries(query)) {
-      if (value === void 0) continue;
-      if (Array.isArray(value)) {
-        for (const item of value) url.searchParams.append(key, item);
-        continue;
-      }
-      url.searchParams.append(key, String(value));
-    }
-  }
-  return url.toString();
-}
-function serializeBody(opts) {
-  if (opts.body === void 0) return void 0;
-  if (opts.method === "GET") return void 0;
-  return JSON.stringify(opts.body);
-}
-function composeSignals(signals) {
-  const present = signals.filter((s) => s !== void 0);
-  if (present.length === 0) return new AbortController().signal;
-  if (present.length === 1) return present[0];
-  const any = AbortSignal.any;
-  if (typeof any === "function") return any(present);
-  const ctrl = new AbortController();
-  for (const s of present) {
-    if (s.aborted) {
-      ctrl.abort(s.reason);
-      break;
-    }
-    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
-  }
-  return ctrl.signal;
-}
-function pickHeader(headers, name) {
-  const value = headers[name] ?? headers[name.toLowerCase()];
-  if (Array.isArray(value)) return value[0];
-  return value;
-}
-function redactAndTruncate(body) {
-  const input = body.length > REDACT_INPUT_CAP ? body.slice(0, REDACT_INPUT_CAP) : body;
-  const redacted = redactTokenLikeFields(input);
-  return redacted.length > REDACT_BODY_LIMIT ? `${redacted.slice(0, REDACT_BODY_LIMIT)}\u2026` : redacted;
-}
-function isAbortError(err) {
-  if (!(err instanceof Error)) return false;
-  return err.name === "AbortError" || /aborted/i.test(err.message);
+function createClient(options) {
+  return new ApiClient(options);
+}
+function parseSuccessBody(args) {
+  let parsed;
+  try {
+    parsed = JSON.parse(args.bodyText);
+  } catch (err) {
+    throw new ApiError(
+      "PARSE_ERROR",
+      "Server returned a non-JSON response.",
+      {
+        status: args.statusCode,
+        requestId: args.requestId,
+        retryable: false,
+        redactedBody: redactAndTruncate(args.bodyText)
+      },
+      err
+    );
+  }
+  const envelope = ServerSuccessSchema(args.responseSchema ?? z6.unknown()).safeParse(parsed);
+  if (!envelope.success) {
+    const issues = formatSchemaIssues(envelope.error);
+    throw new ApiError(
+      "SCHEMA_MISMATCH",
+      `Server response did not match the expected schema. Issues: ${issues}`,
+      {
+        status: args.statusCode,
+        requestId: args.requestId,
+        retryable: false,
+        redactedBody: redactAndTruncate(args.bodyText)
+      }
+    );
+  }
+  return envelope.data.data;
+}
+function parseErrorBody(args) {
+  const redactedBody = redactAndTruncate(args.bodyText);
+  let parsed;
+  try {
+    parsed = JSON.parse(args.bodyText);
+  } catch {
+    return new ApiError(
+      "PARSE_ERROR",
+      `Server returned a ${args.statusCode} response with a non-JSON body.`,
+      {
+        status: args.statusCode,
+        requestId: args.requestId,
+        retryable: args.statusCode >= 500,
+        redactedBody
+      }
+    );
+  }
+  const envelope = ServerErrorBodySchema.safeParse(parsed);
+  if (!envelope.success) {
+    return new ApiError(
+      "PARSE_ERROR",
+      `Server returned ${args.statusCode} but body did not match the error envelope.`,
+      {
+        status: args.statusCode,
+        requestId: args.requestId,
+        retryable: args.statusCode >= 500,
+        redactedBody
+      }
+    );
+  }
+  return apiErrorFromServerBody({
+    body: envelope.data,
+    statusCode: args.statusCode,
+    requestId: args.requestId,
+    retryAfterHeader: args.retryAfterHeader,
+    redactedBody,
+    onWarning: args.onWarning,
+    isRetryableServerCode: args.isRetryableServerCode
+  });
+}
+function apiErrorFromServerBody(args) {
+  const { error } = args.body;
+  let code;
+  let safeMessage;
+  if (KNOWN_SERVER_CODES.has(error.code)) {
+    code = error.code;
+    safeMessage = redactTokenLikeFields(error.message);
+  } else {
+    const redactedRawCode = redactTokenLikeFields(error.code);
+    args.onWarning?.(`Unknown server error code: ${redactedRawCode}. Treating as INTERNAL_ERROR.`);
+    code = "INTERNAL_ERROR";
+    safeMessage = `Unknown server error code: ${redactedRawCode}.`;
+  }
+  const retryable = args.isRetryableServerCode?.(code) ?? (args.statusCode >= 500 || args.statusCode === 429);
+  const retryAfterMs = typeof error.retryAfter === "number" ? error.retryAfter * 1e3 : parseRetryAfterHeader(args.retryAfterHeader);
+  return new ApiError(code, safeMessage, {
+    status: args.statusCode,
+    requestId: error.correlationId ?? args.requestId,
+    retryable,
+    retryAfterMs,
+    redactedBody: args.redactedBody,
+    details: error.details
+  });
+}
+function parseRetryAfterHeader(headerValue) {
+  if (!headerValue) return void 0;
+  const trimmed = headerValue.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Number.parseInt(trimmed, 10) * 1e3;
+  }
+  if (/[A-Za-z]/.test(trimmed)) {
+    const parsed = Date.parse(trimmed);
+    if (!Number.isNaN(parsed)) {
+      return Math.max(0, parsed - Date.now());
+    }
+  }
+  return void 0;
+}
+function buildUrl(baseUrl, path, query) {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const relative = path.startsWith("/") ? path.slice(1) : path;
+  const url = new URL(relative, base);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) url.searchParams.append(key, item);
+        continue;
+      }
+      url.searchParams.append(key, String(value));
+    }
+  }
+  return url.toString();
+}
+function serializeBody(opts) {
+  if (opts.body === void 0) return void 0;
+  if (opts.method === "GET") return void 0;
+  return JSON.stringify(opts.body);
+}
+function composeSignals(signals) {
+  const present = signals.filter((s) => s !== void 0);
+  if (present.length === 0) return new AbortController().signal;
+  if (present.length === 1) return present[0];
+  const any = AbortSignal.any;
+  if (typeof any === "function") return any(present);
+  const ctrl = new AbortController();
+  for (const s of present) {
+    if (s.aborted) {
+      ctrl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+  }
+  return ctrl.signal;
+}
+function pickHeader(headers, name) {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function redactAndTruncate(body) {
+  const input = body.length > REDACT_INPUT_CAP ? body.slice(0, REDACT_INPUT_CAP) : body;
+  const redacted = redactTokenLikeFields(input);
+  return redacted.length > REDACT_BODY_LIMIT ? `${redacted.slice(0, REDACT_BODY_LIMIT)}\u2026` : redacted;
+}
+function isAbortError(err) {
+  if (!(err instanceof Error)) return false;
+  return err.name === "AbortError" || /aborted/i.test(err.message);
+}
+function toAbortApiError(signal, cause) {
+  const reasonMessage = signal.reason instanceof Error ? signal.reason.message : "Request was aborted.";
+  return new ApiError("TIMEOUT", reasonMessage, { retryable: true }, cause);
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+async function applyWorkflowWithRetry(params) {
+  try {
+    return await patch(params);
+  } catch (err) {
+    if (!(err instanceof ApiError)) throw err;
+    const isRevConflict = err.code === "CANVAS_REV_MISMATCH" || err.meta.status === 409 && err.meta.details != null;
+    if (!isRevConflict || !params.autoRev) throw err;
+    const snapshot = await params.client.request({
+      method: "GET",
+      path: `/workflows/${encodeURIComponent(params.id)}`,
+      responseSchema: params.schemas.detail,
+      signal: params.signal
+    });
+    const retryResult = await patch({
+      ...params,
+      canvasRev: snapshot.canvas_rev,
+      // Fresh key — the body changed (different canvas_rev), so reusing the
+      // caller's key would trigger IDEMPOTENCY_KEY_CONFLICT.
+      idempotencyKey: void 0
+    });
+    return { ...retryResult, retriedWithRev: snapshot.canvas_rev };
+  }
+}
+async function patch(params) {
+  const data = await params.client.request({
+    method: "PATCH",
+    path: `/workflows/${encodeURIComponent(params.id)}`,
+    body: {
+      canvas_rev: params.canvasRev,
+      operations: params.operations
+    },
+    idempotencyKey: params.idempotencyKey,
+    responseSchema: params.schemas.mutate,
+    signal: params.signal
+  });
+  return {
+    canvasRev: data.canvas_rev,
+    applied: data.applied,
+    workflow: data.workflow
+  };
+}
+
+// src/errors/codes.ts
+var LOGIN_HINT = "Run `clickraft login` to authenticate.";
+var RELOGIN_HINT = "Run `clickraft login` to refresh.";
+var EXIT_CODE_MAP = {
+  // --- 37 Phase 8 Q7 codes ----------------------------------------------------
+  AUTH_TOKEN_MISSING: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "Set `CLICKRAFT_TOKEN` or run `clickraft login`."
+  },
+  AUTH_TOKEN_INVALID: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "The token is malformed or unknown. Run `clickraft login`."
+  },
+  AUTH_TOKEN_EXPIRED: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: RELOGIN_HINT
+  },
+  AUTH_TOKEN_REVOKED: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "Token was revoked. Run `clickraft login` to mint a new one."
+  },
+  AUTH_TOKEN_SCOPE_INSUFFICIENT: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "This token does not have the required scope. Re-run `clickraft login` selecting the needed scopes."
+  },
+  AUTH_ORG_MISMATCH: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "This token's org no longer exists or you have been removed."
+  },
+  AUTH_DEVICE_CODE_PENDING: {
+    exitCode: 0,
+    category: "success",
+    retryable: false,
+    hint: "Continue polling."
+  },
+  AUTH_DEVICE_CODE_EXPIRED: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "Device code expired. Re-run `clickraft login`."
+  },
+  AUTH_DEVICE_CODE_SLOW_DOWN: {
+    exitCode: 0,
+    category: "success",
+    retryable: false,
+    hint: "Increase polling interval (Retry-After)."
+  },
+  IDEMPOTENCY_KEY_MISSING: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Add `X-Idempotency-Key` header (or `--idempotency-key`)."
+  },
+  IDEMPOTENCY_KEY_CONFLICT: {
+    exitCode: 7,
+    category: "conflict",
+    retryable: false,
+    hint: "Same key was used with a different request body. Use a new key."
+  },
+  PLAN_FEATURE_LOCKED: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "API access is not enabled on your plan. Visit billing settings."
+  },
+  PLAN_QUOTA_EXCEEDED: {
+    exitCode: 5,
+    category: "quota",
+    retryable: false,
+    hint: "Daily API quota exhausted. Wait, or upgrade your plan."
+  },
+  INSUFFICIENT_CREDITS: {
+    exitCode: 5,
+    category: "quota",
+    retryable: false,
+    hint: "Top up credits to retry."
+  },
+  CREDIT_DEDUCTION_FAILED: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Could not charge credits. Retry; no charge was made."
+  },
+  RATE_LIMITED: {
+    exitCode: 5,
+    category: "quota",
+    retryable: true,
+    hint: "Slow down. Honor Retry-After."
+  },
+  INPUT_INVALID_FORMAT: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Check input format and try again."
+  },
+  INPUT_TOO_LONG: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Field exceeded max length."
+  },
+  WORKFLOW_VALIDATION_FAILED: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Run `workflow validate` for the full list of errors."
+  },
+  WORKFLOW_NODE_TYPE_UNKNOWN: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Run `clickraft nodes list` for the current set of node types."
+  },
+  CANVAS_REV_MISMATCH: {
+    exitCode: 7,
+    category: "conflict",
+    retryable: false,
+    hint: "The workflow was updated elsewhere. Re-fetch and retry with the current canvas_rev."
+  },
+  CANVAS_REV_REQUIRED: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Include --canvas-rev or use --auto-rev."
+  },
+  WORKER_UNREACHABLE: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Collaboration service temporarily unavailable. Retry."
+  },
+  IDEMPOTENCY_IN_PROGRESS: {
+    exitCode: 7,
+    category: "conflict",
+    retryable: false,
+    hint: "A request with this idempotency key is currently in-flight. Retry in a moment."
+  },
+  TOKEN_NAME_INVALID: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Agent token name is malformed."
+  },
+  WORKFLOW_NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "No workflow with that ID in your org."
+  },
+  NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Resource not found."
+  },
+  NODE_TYPE_NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Run `clickraft nodes list` for the current set of node types."
+  },
+  FEATURE_DISABLED: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "This endpoint is not enabled. Contact support if you believe this is in error."
+  },
+  FORBIDDEN: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "Your role does not permit this action."
+  },
+  MODEL_NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Unknown `modelSlug`. Run `brand-model list` for the current set."
+  },
+  PROVIDER_UNAVAILABLE: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Provider is temporarily unavailable. Retry shortly."
+  },
+  STORAGE_UPLOAD_FAILED: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Upload failed mid-stream. Retry."
+  },
+  STORAGE_QUOTA_EXCEEDED: {
+    exitCode: 5,
+    category: "quota",
+    retryable: false,
+    hint: "Org storage quota exceeded. Free space or upgrade."
+  },
+  GEN_CONTENT_REFUSAL: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "The model declined the request via safety policy."
+  },
+  GEN_OUTPUT_SCHEMA_MISMATCH: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Provider returned malformed output. Full refund issued. Retry."
+  },
+  GEN_EMPTY_OUTPUT: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Provider returned no usable output. Full refund issued. Retry."
+  },
+  GEN_ITEM_COUNT_MISMATCH: {
+    exitCode: 0,
+    category: "success",
+    retryable: false,
+    hint: "Partial output kept; no refund."
+  },
+  AGENT_FINGERPRINT_REJECTED: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "This client identification is not permitted. Contact support."
+  },
+  INTERNAL_ERROR: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Server error. Retry; if it persists, contact support with the request ID."
+  },
+  CREDENTIALS_LOCKED: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: true,
+    hint: "Another CLI invocation holds the credentials lock. Retry shortly."
+  },
+  CREDENTIALS_PERMISSIONS_LOOSE: {
+    exitCode: 0,
+    category: "success",
+    retryable: false,
+    hint: "Credentials file mode is wider than 0600; continuing."
+  },
+  // --- 5 additional codes introduced by 1A.1 ---------------------------------
+  AUTH_ACCESS_DENIED: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "You denied the OAuth grant. Re-run `clickraft login` to retry."
+  },
+  AUTH_FLOW_CANCELLED: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: "Authentication was cancelled. Re-run `clickraft login`."
+  },
+  CREDENTIALS_CORRUPT: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Credentials file is unreadable. Remove it and run `clickraft login`."
+  },
+  CREDENTIALS_NOT_FOUND: {
+    exitCode: 3,
+    category: "auth",
+    retryable: false,
+    hint: LOGIN_HINT
+  },
+  CREDENTIALS_PROFILE_NOT_FOUND: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "No such profile. Use `clickraft auth profiles` to list available profiles."
+  },
+  // --- 8 brand model resolution codes -----------------------------------------
+  BRAND_MODEL_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "No brand model with that ID. Run `clickraft brand-model list`."
+  },
+  BRAND_MODEL_NOT_A_MODEL: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "The specified asset is not a brand model."
+  },
+  BRAND_MODEL_NOT_ACTIVE: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Brand model is not active. Check its status in the dashboard."
+  },
+  BRAND_MODEL_NO_REFERENCES: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Brand model has no reference images. Upload references first."
+  },
+  BRAND_MODEL_POSE_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Requested pose not found. Valid: front, 3/4-right, right, left, 3/4-left, back, approved."
+  },
+  BRAND_MODEL_DUPLICATE_ID: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Same brand model ID appears more than once."
+  },
+  MODEL_DOES_NOT_SUPPORT_REFERENCES: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "This model does not support brand model references."
+  },
+  REFERENCE_LIMIT_EXCEEDED: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Too many reference images. Check model limits."
+  },
+  // --- 8 product reference resolver codes -------------------------------------
+  PRODUCT_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "No product with that ID in your org. Run `clickraft product list`."
+  },
+  PRODUCT_DUPLICATE_REFERENCE: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Same (productId, imageId) tuple appears twice in the request."
+  },
+  PRODUCT_IMAGE_NOT_FOUND: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "imageId does not exist in the product images."
+  },
+  PRODUCT_IMAGE_MISMATCH: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "imageId belongs to a different product."
+  },
+  PRODUCT_SYNC_ERROR: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Product sync status is 'error'. Re-sync or use a different product."
+  },
+  PRODUCT_DELETED_UPSTREAM: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Product was deleted upstream. Remove it or re-sync."
+  },
+  PRODUCT_NO_PRIMARY_IMAGE: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Product has no primary image. Specify --product <id>:<imageId> explicitly."
+  },
+  PRODUCT_SOURCE_MANAGED: {
+    exitCode: 4,
+    category: "permission",
+    retryable: false,
+    hint: "Product is managed by an external integration."
+  },
+  // --- 4 CLI-synthetic codes --------------------------------------------------
+  NETWORK_ERROR: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Network connection failed. Check connectivity and retry."
+  },
+  TIMEOUT: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Request timed out. Retry; consider increasing the timeout."
+  },
+  PARSE_ERROR: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Server returned an unexpected response. Contact support with the request ID."
+  },
+  SCHEMA_MISMATCH: {
+    exitCode: 1,
+    category: "runtime",
+    retryable: false,
+    hint: "Server response did not match the expected schema. Update the CLI."
+  }
+};
+function getExitCode(code) {
+  return EXIT_CODE_MAP[code]?.exitCode ?? 1;
 }
-function toAbortApiError(signal, cause) {
-  const reasonMessage = signal.reason instanceof Error ? signal.reason.message : "Request was aborted.";
-  return new ApiError("TIMEOUT", reasonMessage, { retryable: true }, cause);
+function toEnvelopeCode(code) {
+  return code.startsWith("E_") ? code : `E_${code}`;
 }
-function errorMessage(err) {
-  if (err instanceof Error) return err.message;
-  return String(err);
+var SIGINT_EXIT_CODE = 130;
+
+// src/api/client.ts
+var isRetryableServerCode = (code) => EXIT_CODE_MAP[code].retryable;
+var onWarning = (msg) => {
+  console.warn(msg);
+};
+function createApiClient(opts) {
+  return createClient({ ...opts, onWarning, isRetryableServerCode });
 }
 
 // src/auth/errors.ts
@@ -1488,7 +1533,7 @@ async function getBalance(options) {
   if (!config.accessToken) {
     throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
   }
-  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
     apiBaseUrl,
     accessToken,
     signal: options.signal,
@@ -1514,7 +1559,7 @@ async function listBrandModels(options) {
   if (!config.accessToken) {
     throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
   }
-  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
     apiBaseUrl,
     accessToken,
     signal: options.signal,
@@ -1679,7 +1724,7 @@ async function buildClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -1846,7 +1891,7 @@ async function buildGenerateClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -2618,7 +2663,7 @@ async function logout(options) {
   let serverRevoked = false;
   let revokeFailureMessage;
   if (options.revoke) {
-    const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+    const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
       apiBaseUrl,
       accessToken,
       signal: options.signal,
@@ -2703,7 +2748,7 @@ async function buildModelClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -2756,7 +2801,7 @@ async function buildNodesClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -2800,7 +2845,7 @@ async function listProducts(options) {
   if (!config.accessToken) {
     throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
   }
-  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
     apiBaseUrl,
     accessToken,
     signal: options.signal,
@@ -2909,7 +2954,7 @@ async function buildTemplateClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -3003,7 +3048,7 @@ async function listTokens(options) {
   if (!config.accessToken) {
     throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
   }
-  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => createApiClient({
     apiBaseUrl,
     accessToken,
     signal: options.signal,
@@ -3075,7 +3120,7 @@ async function buildWorkflowClient(opts) {
     flagApiBaseUrl: opts.apiBaseUrl,
     flagToken: opts.token
   });
-  return new ApiClient({
+  return createApiClient({
     apiBaseUrl: cfg.apiBaseUrl,
     accessToken: cfg.accessToken,
     signal: opts.signal,
@@ -3083,54 +3128,19 @@ async function buildWorkflowClient(opts) {
   });
 }
 
-// src/commands/workflow/get.ts
-async function getWorkflow(opts) {
-  const client = opts.client ?? await buildWorkflowClient(opts);
-  return client.request({
-    method: "GET",
-    path: `/workflows/${encodeURIComponent(opts.id)}`,
-    responseSchema: WorkflowDetailSchema,
-    signal: opts.signal
-  });
-}
-
 // src/commands/workflow/apply.ts
 async function applyWorkflow(opts) {
   const client = opts.client ?? await buildWorkflowClient(opts);
-  try {
-    return await patchWorkflow(client, opts);
-  } catch (err) {
-    if (!(err instanceof ApiError)) throw err;
-    const isRevConflict = err.code === "CANVAS_REV_MISMATCH" || err.meta.status === 409 && err.meta.details != null;
-    if (!isRevConflict || !opts.autoRev) throw err;
-    const snapshot = await getWorkflow({ id: opts.id, client, signal: opts.signal });
-    const retryResult = await patchWorkflow(client, {
-      ...opts,
-      canvasRev: snapshot.canvas_rev,
-      // Fresh key — the body changed (different canvas_rev), so reusing
-      // the caller's key would trigger IDEMPOTENCY_KEY_CONFLICT.
-      idempotencyKey: void 0
-    });
-    return { ...retryResult, retriedWithRev: snapshot.canvas_rev };
-  }
-}
-async function patchWorkflow(client, opts) {
-  const data = await client.request({
-    method: "PATCH",
-    path: `/workflows/${encodeURIComponent(opts.id)}`,
-    body: {
-      canvas_rev: opts.canvasRev,
-      operations: opts.operations
-    },
+  return applyWorkflowWithRetry({
+    client,
+    id: opts.id,
+    canvasRev: opts.canvasRev,
+    operations: opts.operations,
     idempotencyKey: opts.idempotencyKey,
-    responseSchema: WorkflowMutateResponseSchema,
-    signal: opts.signal
+    autoRev: opts.autoRev,
+    signal: opts.signal,
+    schemas: { mutate: WorkflowMutateResponseSchema, detail: WorkflowDetailSchema }
   });
-  return {
-    canvasRev: data.canvas_rev,
-    applied: data.applied,
-    workflow: data.workflow
-  };
 }
 
 // src/commands/workflow/create.ts
@@ -3161,6 +3171,17 @@ async function createWorkflow(opts) {
   });
 }
 
+// src/commands/workflow/get.ts
+async function getWorkflow(opts) {
+  const client = opts.client ?? await buildWorkflowClient(opts);
+  return client.request({
+    method: "GET",
+    path: `/workflows/${encodeURIComponent(opts.id)}`,
+    responseSchema: WorkflowDetailSchema,
+    signal: opts.signal
+  });
+}
+
 // src/commands/workflow/list.ts
 async function listWorkflows(opts) {
   const client = opts.client ?? await buildWorkflowClient(opts);