@clickraft/cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,8 +1,20 @@
-## [0.5.0](https://github.com/clickraft/cli/compare/v0.4.0...v0.5.0) (2026-05-24)
+## [0.6.0](https://github.com/clickraft/cli/compare/v0.5.0...v0.6.0) (2026-05-25)
 
 ### Features
 
-* **models:** add models list command consuming agents/v1/models ([83761d1](https://github.com/clickraft/cli/commit/83761d11d136758e23c40cf80cd87c8f08dbaad6))
+* **errors:** add PRODUCT_* server error codes ([b60a018](https://github.com/clickraft/cli/commit/b60a0184f57d52d8a423631adeea69d47e8f28fc))
+* **products:** add --product flag to generate create ([41a8948](https://github.com/clickraft/cli/commit/41a8948ee79c63abffe891411c0a36c67059d2d5))
+* **products:** add product list command with cursor pagination ([ca4c343](https://github.com/clickraft/cli/commit/ca4c3433e5e3aa7c53ccdd5ab26bac3775d37608))
+* **products:** show product and primary image IDs in list render ([2dc1d65](https://github.com/clickraft/cli/commit/2dc1d653ada365ceb0f1fa68697df71e24045633))
+* **products:** wire product commands into CLI dispatch ([c458355](https://github.com/clickraft/cli/commit/c45835599fe546f8a19ad6b08eb35ee772299d49))
+* **scopes:** request products:read in OAuth login ([ad67816](https://github.com/clickraft/cli/commit/ad67816e359de8198f2c5423de9f6ab9671f7418))
+
+### Bug Fixes
+
+* **products:** align scope-insufficient hint in error message and Try line ([6f6cb1e](https://github.com/clickraft/cli/commit/6f6cb1e935e9e65b7039f4423acdb0569772892d))
+* **products:** honor meta.hint in JSON error envelope ([f39b516](https://github.com/clickraft/cli/commit/f39b51668b29d5d78166933d56bd4f3954039ebe))
+* **products:** tolerate forward-compat additive fields in list response ([cfe7bf2](https://github.com/clickraft/cli/commit/cfe7bf25dc18710583408dea9dc1e975449ce13a))
+* **products:** validate --limit range and correct login help scope count ([d1341d9](https://github.com/clickraft/cli/commit/d1341d929f80f87407ec89c9abff5c214cd3b52a))
 
 # Changelog
 

package/dist/cli.js

@@ -334,6 +334,55 @@ var EXIT_CODE_MAP = {
     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,
@@ -877,7 +926,8 @@ function errorToEnvelopePayload(err) {
       retryable: err.meta.retryable,
       retryAfterMs: err.meta.retryAfterMs,
       requestId: err.meta.requestId,
-      details: err.meta.details
+      details: err.meta.details,
+      hint: err.meta.hint
     });
   }
   if (err instanceof AuthError || err instanceof CredentialsError) {
@@ -905,7 +955,8 @@ function buildPayload(args) {
   };
   if (typeof args.retryAfterMs === "number") payload.retry_after_ms = args.retryAfterMs;
   if (args.requestId) payload.request_id = args.requestId;
-  if (mapping?.hint) payload.hint = mapping.hint;
+  const resolvedHint = args.hint ?? mapping?.hint;
+  if (resolvedHint) payload.hint = resolvedHint;
   if (args.details != null) payload.details = args.details;
   return payload;
 }
@@ -1322,6 +1373,10 @@ async function listBrandModels(options) {
 
 // src/schemas/jobs.ts
 import { z as z6 } from "zod";
+var ProductReferenceSchema = z6.object({
+  id: z6.string().uuid(),
+  imageId: z6.string().uuid().optional()
+}).strict();
 var GenerateCreateRequestSchema = z6.object({
   modelSlug: z6.string().min(1).max(100),
   input: z6.object({
@@ -1336,7 +1391,8 @@ var GenerateCreateRequestSchema = z6.object({
   options: z6.object({
     workflowId: z6.string().uuid().optional(),
     nodeId: z6.string().optional()
-  }).strict().optional()
+  }).strict().optional(),
+  products: z6.array(ProductReferenceSchema).min(1).max(10).optional()
 }).strict();
 var GenerateCreateResponseSchema = z6.object({
   jobId: z6.string().uuid(),
@@ -1807,6 +1863,13 @@ function buildRequestBody(args) {
     if (args.nodeId !== void 0) options.nodeId = args.nodeId;
     body.options = options;
   }
+  if (args.products !== void 0 && args.products.length > 0) {
+    body.products = args.products.map((spec) => {
+      const entry = { id: spec.id };
+      if (spec.imageId) entry.imageId = spec.imageId;
+      return entry;
+    });
+  }
   const parsed = GenerateCreateRequestSchema.safeParse(body);
   if (!parsed.success) {
     throw new ApiError(
@@ -1979,6 +2042,44 @@ function validateBrandModelSpecs(specs) {
   }
 }
 
+// src/commands/generate/parse-product-spec.ts
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function parseProductSpec(raw) {
+  if (!raw) throw new ArgError("--product value cannot be empty.");
+  const colonIdx = raw.indexOf(":");
+  const productId = colonIdx >= 0 ? raw.slice(0, colonIdx) : raw;
+  const imageIdRaw = colonIdx >= 0 ? raw.slice(colonIdx + 1) : void 0;
+  if (!UUID_RE2.test(productId)) {
+    throw new ArgError(
+      `Invalid product ID: '${productId}'. Expected a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).`
+    );
+  }
+  if (imageIdRaw !== void 0) {
+    if (!imageIdRaw) {
+      throw new ArgError(
+        `Empty image ID for product ${productId.toLowerCase()}. Omit the colon or provide a valid UUID.`
+      );
+    }
+    if (!UUID_RE2.test(imageIdRaw)) {
+      throw new ArgError(
+        `Invalid image ID: '${imageIdRaw}' for product ${productId.toLowerCase()}. Expected a UUID.`
+      );
+    }
+    return { id: productId.toLowerCase(), imageId: imageIdRaw.toLowerCase() };
+  }
+  return { id: productId.toLowerCase() };
+}
+function validateProductSpecs(specs) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    const key = spec.imageId ? `${spec.id}:${spec.imageId}` : spec.id;
+    if (seen.has(key)) {
+      throw new ArgError(`Duplicate product reference: ${key}. Each --product must be unique.`);
+    }
+    seen.add(key);
+  }
+}
+
 // src/auth/device-flow.ts
 import { setTimeout as delay } from "timers/promises";
 import { request } from "undici";
@@ -2315,6 +2416,7 @@ var DEFAULT_SCOPES = [
   "workflows:write",
   "workflows:read",
   "brand-models:read",
+  "products:read",
   "assets:write",
   "balance:read"
 ];
@@ -2512,6 +2614,68 @@ async function listModels(opts) {
   return data;
 }
 
+// src/commands/product/list.ts
+import { z as z9 } from "zod";
+var ProductImageSummarySchema = z9.object({
+  id: z9.string().uuid(),
+  url: z9.string(),
+  altText: z9.string().nullable(),
+  isPrimary: z9.boolean(),
+  sortOrder: z9.number().int()
+});
+var ProductSummarySchema = z9.object({
+  id: z9.string().uuid(),
+  title: z9.string(),
+  sourceType: z9.string(),
+  syncStatus: z9.enum(["synced", "pending", "stale", "error", "deleted_upstream"]).nullable(),
+  vendor: z9.string().nullable(),
+  productType: z9.string().nullable(),
+  tags: z9.array(z9.string()),
+  images: z9.array(ProductImageSummarySchema)
+});
+var ProductsListResponseSchema = z9.object({
+  items: z9.array(ProductSummarySchema),
+  nextCursor: z9.string().nullable()
+});
+var DEFAULT_LIMIT = 50;
+async function listProducts(options) {
+  const config = await loadConfig({
+    flagProfile: options.profile,
+    flagApiBaseUrl: options.apiBaseUrl,
+    flagToken: options.token,
+    credentialsPath: options.credentialsPath
+  });
+  if (!config.accessToken) {
+    throw new AuthError("AUTH_TOKEN_MISSING", `Not authenticated. Run \`clickraft login\` first.`);
+  }
+  const factory = options.apiClientFactory ?? ((apiBaseUrl, accessToken) => new ApiClient({
+    apiBaseUrl,
+    accessToken,
+    signal: options.signal,
+    cloudflareAccess: config.cloudflareAccess
+  }));
+  const client = factory(config.apiBaseUrl, config.accessToken);
+  const query = {
+    limit: options.limit ?? DEFAULT_LIMIT
+  };
+  if (options.cursor) query.cursor = options.cursor;
+  if (options.syncStatus) query.syncStatus = options.syncStatus;
+  if (options.sourceType) query.sourceType = options.sourceType;
+  if (options.search) query.search = options.search;
+  const data = await client.request({
+    method: "GET",
+    path: "/products",
+    query,
+    responseSchema: ProductsListResponseSchema,
+    signal: options.signal
+  });
+  return {
+    products: data.items,
+    nextCursor: data.nextCursor,
+    hasMore: data.nextCursor !== null
+  };
+}
+
 // src/telemetry/detect.ts
 var AGENT_SIGNALS = [
   { envVar: "CLAUDE_CODE_SESSION_ID", agent: "claude-code" },
@@ -2602,33 +2766,33 @@ async function buildTemplateClient(opts) {
 }
 
 // src/schemas/templates.ts
-import { z as z9 } from "zod";
-var DeclaredParamSchema = z9.object({
-  name: z9.string(),
-  type: z9.string(),
-  required: z9.boolean(),
-  defaultValue: z9.string().nullable().optional(),
-  enumValues: z9.array(z9.string()).nullable().optional(),
-  description: z9.string().nullable().optional()
+import { z as z10 } from "zod";
+var DeclaredParamSchema = z10.object({
+  name: z10.string(),
+  type: z10.string(),
+  required: z10.boolean(),
+  defaultValue: z10.string().nullable().optional(),
+  enumValues: z10.array(z10.string()).nullable().optional(),
+  description: z10.string().nullable().optional()
 }).strict();
-var TemplateSummarySchema = z9.object({
-  id: z9.string().uuid(),
-  source: z9.enum(["own", "system"]),
-  name: z9.string(),
-  description: z9.string().nullable(),
-  category: z9.string().nullable(),
-  thumbnailUrl: z9.string().nullable(),
-  tags: z9.array(z9.string()),
-  createdAt: z9.string()
+var TemplateSummarySchema = z10.object({
+  id: z10.string().uuid(),
+  source: z10.enum(["own", "system"]),
+  name: z10.string(),
+  description: z10.string().nullable(),
+  category: z10.string().nullable(),
+  thumbnailUrl: z10.string().nullable(),
+  tags: z10.array(z10.string()),
+  createdAt: z10.string()
 }).strict();
 var TemplateDetailSchema = TemplateSummarySchema.extend({
-  declaredParams: z9.array(DeclaredParamSchema),
-  timesUsed: z9.number()
+  declaredParams: z10.array(DeclaredParamSchema),
+  timesUsed: z10.number()
 }).strict();
-var TemplatesListResponseSchema = z9.object({
-  templates: z9.array(TemplateSummarySchema),
-  cursor: z9.string().nullable(),
-  hasMore: z9.boolean()
+var TemplatesListResponseSchema = z10.object({
+  templates: z10.array(TemplateSummarySchema),
+  cursor: z10.string().nullable(),
+  hasMore: z10.boolean()
 }).strict();
 
 // src/commands/template/list.ts
@@ -2678,20 +2842,20 @@ async function getTemplate(opts) {
 }
 
 // src/commands/tokens/list.ts
-import { z as z10 } from "zod";
-var TokenRowSchema = z10.object({
-  id: z10.string().uuid(),
-  organizationId: z10.string().uuid(),
-  userId: z10.string().uuid(),
-  clientId: z10.string().nullable(),
-  tokenPrefix: z10.string(),
-  name: z10.string().nullable(),
-  scopes: z10.array(z10.string()),
-  lastUsedAt: z10.string().nullable(),
-  expiresAt: z10.string(),
-  createdAt: z10.string()
+import { z as z11 } from "zod";
+var TokenRowSchema = z11.object({
+  id: z11.string().uuid(),
+  organizationId: z11.string().uuid(),
+  userId: z11.string().uuid(),
+  clientId: z11.string().nullable(),
+  tokenPrefix: z11.string(),
+  name: z11.string().nullable(),
+  scopes: z11.array(z11.string()),
+  lastUsedAt: z11.string().nullable(),
+  expiresAt: z11.string(),
+  createdAt: z11.string()
 }).strict();
-var TokensListResponseSchema = z10.array(TokenRowSchema);
+var TokensListResponseSchema = z11.array(TokenRowSchema);
 async function listTokens(options) {
   const config = await loadConfig({
     flagProfile: options.profile,
@@ -2744,7 +2908,7 @@ function errorToView(err) {
     return {
       code: toEnvelopeCode(err.code),
       message: err.message,
-      hint: EXIT_CODE_MAP[err.code]?.hint ?? FALLBACK_HINT,
+      hint: err.meta.hint ?? EXIT_CODE_MAP[err.code]?.hint ?? FALLBACK_HINT,
       requestId: err.meta.requestId,
       details: formatDetails(err.meta.details)
     };
@@ -3004,6 +3168,39 @@ function renderBrandModelsList(models, out) {
   out.write(padRow(headers) + "\n");
   for (const cells of data) out.write(padRow(cells) + "\n");
 }
+function renderProductsList(result, out) {
+  const { products } = result;
+  if (products.length === 0) {
+    out.write("No products.\n");
+    return;
+  }
+  const MAX_TAGS = 3;
+  const headers = ["ID", "TITLE", "SOURCE", "SYNC", "IMAGES", "PRIMARY IMAGE", "VENDOR", "TAGS"];
+  const data = products.map((p) => {
+    const shown = p.tags.slice(0, MAX_TAGS).join(", ");
+    const extra = p.tags.length > MAX_TAGS ? ` +${p.tags.length - MAX_TAGS} more` : "";
+    const primary = p.images.find((img) => img.isPrimary) ?? p.images.find((img) => img.sortOrder === 0);
+    return [
+      p.id,
+      p.title,
+      p.sourceType,
+      p.syncStatus ?? "\u2014",
+      String(p.images.length),
+      primary?.id ?? "\u2014",
+      p.vendor ?? "\u2014",
+      p.tags.length > 0 ? shown + extra : "\u2014"
+    ];
+  });
+  const widths = headers.map(
+    (header, i) => Math.max(header.length, ...data.map((cells) => cells[i].length))
+  );
+  const padRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  out.write(padRow(headers) + "\n");
+  for (const cells of data) out.write(padRow(cells) + "\n");
+  if (result.hasMore) {
+    out.write("\nMore results available. Use --cursor to fetch the next page.\n");
+  }
+}
 function renderTemplatesList(result, out) {
   const { templates } = result;
   if (templates.length === 0) {
@@ -3351,6 +3548,7 @@ function renderRootHelp(version) {
     "  tokens list             List the caller's API tokens",
     "  balance                 Show credit balance and rate limits",
     "  brand-model list        List available brand models",
+    "  product list            List products in your organization",
     "  models list             List available AI models",
     "  telemetry inspect       Show current telemetry state and payload shape",
     "  template list            List available templates",
@@ -3379,7 +3577,7 @@ function renderCommandHelp(command) {
         "Options:",
         '  --profile <name>          Write to a specific profile (default: "default")',
         "  --api-base-url <url>      Override the API base URL",
-        "  --scope <s>               Space-separated scope list (default: all 8)",
+        `  --scope <s>               Space-separated scope list (default: all ${DEFAULT_SCOPES.length})`,
         "  --force-reauth            Re-authenticate even if a valid token exists",
         "  --no-open-browser         Do not auto-open the verification URL",
         "  --json                    Emit JSON envelope instead of human output",
@@ -3431,6 +3629,32 @@ function renderCommandHelp(command) {
         "  --json             Emit JSON envelope instead of human output",
         ""
       ].join("\n");
+    case "product":
+      return [
+        "Usage: clickraft product <subcommand> [options]",
+        "",
+        "Subcommands:",
+        "  list  List products in your organization",
+        ""
+      ].join("\n");
+    case "product list":
+      return [
+        "Usage: clickraft product list [options]",
+        "",
+        "List products in your organization. Supports cursor-based pagination.",
+        "",
+        "Options:",
+        "  --cursor <token>       Pagination cursor from a previous response",
+        "  --limit <n>            Max results per page (1-100, default: 50)",
+        "  --sync-status <s>      Filter by sync status (synced, pending, stale, error, deleted_upstream)",
+        "  --source-type <s>      Filter by source type (manual, csv, shopify, etsy, etc.)",
+        "  --search <q>           Free-text search query",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
     case "models":
       return [
         "Usage: clickraft models <subcommand> [options]",
@@ -3550,6 +3774,9 @@ function renderCommandHelp(command) {
         "  --brand-model <spec>      Brand Model reference (repeatable, max 3)",
         "                             Format: <uuid> or <uuid>:<pose>",
         "                             Poses: front, 3/4-right, right, left, 3/4-left, back, approved",
+        "  --product <spec>          Product reference (repeatable)",
+        "                             Format: <uuid> or <uuid>:<imageId>",
+        "                             Server enforces reference cap per model",
         "  --reference-image <v>     URL or local path (repeatable, max 8)",
         "  --aspect-ratio <a:b>      e.g. 16:9",
         "  --resolution <WxH>        e.g. 1024x768",
@@ -3658,6 +3885,12 @@ function matchNewCommand(argv) {
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "template" };
     return { kind: "unknown-sub", verb: "template", sub };
   }
+  if (verb === "product") {
+    const sub = argv[1];
+    if (sub === "list") return { kind: "cmd", path: "product.list", verbTokenCount: 2 };
+    if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "product" };
+    return { kind: "unknown-sub", verb: "product", sub };
+  }
   if (verb === "models") {
     const sub = argv[1];
     if (sub === "list") return { kind: "cmd", path: "models.list", verbTokenCount: 2 };
@@ -3720,6 +3953,8 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runTemplateGet(argvAfterVerb, ctx, rc);
       case "template.find":
         return await runTemplateFind(argvAfterVerb, ctx, rc);
+      case "product.list":
+        return await runProductList(argvAfterVerb, ctx, rc);
       case "models.list":
         return await runModelsList(argvAfterVerb, ctx, rc);
     }
@@ -3760,13 +3995,16 @@ async function runGenerateCreate(argv, ctx, rc) {
       "timeout"
     ],
     boolean: [...COMMON_RICH_BOOL_FLAGS, "wait", "async"],
-    array: ["reference-image", "brand-model"]
+    array: ["reference-image", "brand-model", "product"]
   });
   const modelSlug = parsed.string["model-slug"];
   if (!modelSlug) throw new ArgError("--model-slug is required.");
   const rawBrandModels = parsed.array["brand-model"] ?? [];
   const brandModels = rawBrandModels.length > 0 ? rawBrandModels.map(parseBrandModelSpec) : void 0;
   if (brandModels) validateBrandModelSpecs(brandModels);
+  const rawProducts = parsed.array["product"] ?? [];
+  const products = rawProducts.length > 0 ? rawProducts.map(parseProductSpec) : void 0;
+  if (products) validateProductSpecs(products);
   const result = await generateCreate({
     prompt: parsed.string.prompt ?? parsed.positional[0],
     modelSlug,
@@ -3775,6 +4013,7 @@ async function runGenerateCreate(argv, ctx, rc) {
     resolution: parsed.string.resolution,
     durationSeconds: optionalInt(parsed.string["duration-seconds"], "duration-seconds"),
     brandModels,
+    products,
     workflowId: parsed.string["workflow-id"],
     nodeId: parsed.string["node-id"],
     wait: computeWaitFlag(parsed),
@@ -3999,6 +4238,60 @@ function emitTemplateDetail(detail, ctx, rc) {
   }
   renderTemplateDetail(detail, rc.stdout);
 }
+var PRODUCTS_SCOPE_HINT = "Your CLI token doesn't include products:read. Run `clickraft login` to re-authenticate with the new scope.";
+async function runProductList(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [
+      ...COMMON_RICH_STRING_FLAGS,
+      "cursor",
+      "limit",
+      "sync-status",
+      "source-type",
+      "search"
+    ],
+    boolean: [...COMMON_RICH_BOOL_FLAGS]
+  });
+  const limit = optionalInt(parsed.string.limit, "limit");
+  if (limit !== void 0 && (limit < 1 || limit > 100)) {
+    throw new ArgError("--limit must be between 1 and 100.");
+  }
+  try {
+    const result = await listProducts({
+      cursor: parsed.string.cursor,
+      limit,
+      syncStatus: parsed.string["sync-status"],
+      sourceType: parsed.string["source-type"],
+      search: parsed.string.search,
+      profile: parsed.string.profile,
+      apiBaseUrl: parsed.string["api-base-url"],
+      token: parsed.string.token,
+      signal: rc.signal
+    });
+    ctx.nextCursor = result.nextCursor ?? void 0;
+    emitProductList(result, ctx, rc);
+    return 0;
+  } catch (err) {
+    if (err instanceof ApiError && err.code === "AUTH_TOKEN_SCOPE_INSUFFICIENT") {
+      throw new ApiError(
+        err.code,
+        PRODUCTS_SCOPE_HINT,
+        { ...err.meta, hint: PRODUCTS_SCOPE_HINT },
+        err.cause
+      );
+    }
+    throw err;
+  }
+}
+function emitProductList(result, ctx, rc) {
+  if (rc.signal?.aborted) {
+    throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  }
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderProductsList(result, rc.stdout);
+}
 async function runModelsList(argv, ctx, rc) {
   const parsed = parseArgs(argv, {
     string: [...COMMON_RICH_STRING_FLAGS, "category", "tier", "type"],