@clickraft/cli 0.8.4 → 0.8.5

package/dist/index.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,10 +457,15 @@ 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 createClient(options) {
+  return new ApiClient(options);
+}
 function parseSuccessBody(args) {
   let parsed;
   try {
@@ -960,7 +534,9 @@ function parseErrorBody(args) {
     statusCode: args.statusCode,
     requestId: args.requestId,
     retryAfterHeader: args.retryAfterHeader,
-    redactedBody
+    redactedBody,
+    onWarning: args.onWarning,
+    isRetryableServerCode: args.isRetryableServerCode
   });
 }
 function apiErrorFromServerBody(args) {
@@ -972,12 +548,11 @@ function apiErrorFromServerBody(args) {
     safeMessage = redactTokenLikeFields(error.message);
   } else {
     const redactedRawCode = redactTokenLikeFields(error.code);
-    console.warn(`Unknown server error code: ${redactedRawCode}. Treating as INTERNAL_ERROR.`);
+    args.onWarning?.(`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 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,
@@ -1062,6 +637,435 @@ function errorMessage(err) {
   return String(err);
 }
 
+// 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/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
 var AuthError = class extends Error {
   code;
@@ -1488,7 +1492,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 +1518,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 +1683,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 +1850,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 +2622,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 +2707,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 +2760,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 +2804,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 +2913,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 +3007,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 +3079,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,