@01.software/cli 0.10.1 → 0.10.4

package/dist/index.js

@@ -8,7 +8,7 @@ import { Command } from "commander";
 import {
   CollectionClient,
   ServerCommerceClient
-} from "@01.software/sdk";
+} from "@01.software/sdk/server";
 
 // src/lib/credentials.ts
 import {
@@ -166,6 +166,9 @@ function classifyError(err) {
       if (isPermissionCode(code)) {
         return { type: "permission", code };
       }
+      if (code === "auth_error" || code === "permission_error") {
+        return { type: "permission", code: "credential_invalid" };
+      }
       if (isDegradedCode(code)) {
         const out = { type: "degraded", code };
         if (typeof obj.retryAfter === "number") {
@@ -187,7 +190,7 @@ function classifyError(err) {
     }
     const name = typeof obj.name === "string" ? obj.name : void 0;
     const status = typeof obj.status === "number" ? obj.status : void 0;
-    if (name === "ConfigError" || status === 401) {
+    if (name === "ConfigError" || name === "AuthError" || name === "PermissionError" || status === 401 || status === 403) {
       return { type: "permission", code: "credential_invalid" };
     }
     if (name === "NetworkError" || name === "TimeoutError" || status === 408 || status === 503) {
@@ -440,7 +443,14 @@ function exitWithError(error, options = {}) {
 function isValidBearerToken(secret) {
   return secret.startsWith("sk01_") || secret.startsWith("pat01_");
 }
-function resolveClient(apiKeyFlag) {
+function credentialError(detail) {
+  return {
+    type: "permission",
+    code: "credential_invalid",
+    detail
+  };
+}
+function resolveClientCredentials(apiKeyFlag) {
   let publishableKey = process.env.SOFTWARE_PUBLISHABLE_KEY;
   let secretKey = apiKeyFlag ?? process.env.SOFTWARE_SECRET_KEY;
   if (!publishableKey || !secretKey) {
@@ -458,29 +468,25 @@ function resolveClient(apiKeyFlag) {
     }
   }
   if (!publishableKey || !secretKey) {
-    exitWithError({
-      type: "permission",
-      code: "credential_invalid",
-      detail: {
-        message: t("AuthenticationRequired"),
-        steps: [
-          t("RunLoginToAuthenticate"),
-          t("PassApiKey"),
-          t("SetEnvVars")
-        ]
-      }
+    throw credentialError({
+      message: t("AuthenticationRequired"),
+      steps: [
+        t("RunLoginToAuthenticate"),
+        t("PassApiKey"),
+        t("SetEnvVars")
+      ]
     });
   }
   if (!isValidBearerToken(secretKey)) {
-    exitWithError({
-      type: "permission",
-      code: "credential_invalid",
-      detail: {
-        message: t("InvalidApiKeyFormat"),
-        suggestion: t("RetiredHexCredentialsRejected")
-      }
+    throw credentialError({
+      message: t("InvalidApiKeyFormat"),
+      suggestion: t("RetiredHexCredentialsRejected")
     });
   }
+  return { publishableKey, secretKey };
+}
+function resolveClientOrThrow(apiKeyFlag) {
+  const { publishableKey, secretKey } = resolveClientCredentials(apiKeyFlag);
   const serverOptions = { publishableKey, secretKey };
   return {
     collections: new CollectionClient(
@@ -495,11 +501,37 @@ function resolveClient(apiKeyFlag) {
     secretKey
   };
 }
+function resolveClient(apiKeyFlag) {
+  try {
+    return resolveClientOrThrow(apiKeyFlag);
+  } catch (error) {
+    exitWithError(error);
+  }
+}
 
 // src/commands/crud.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { basename } from "path";
+
+// src/lib/collections.ts
 import { COLLECTIONS } from "@01.software/sdk";
+function validateCollection(name) {
+  if (COLLECTIONS.includes(name)) {
+    return name;
+  }
+  const normalized = name.replace(/-/g, "").toLowerCase();
+  const suggestions = COLLECTIONS.filter((collection) => {
+    const candidate = collection.replace(/-/g, "").toLowerCase();
+    return candidate.startsWith(normalized) || normalized.startsWith(candidate) || normalized.length >= 3 && candidate.includes(normalized);
+  }).slice(0, 5);
+  const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 --help" for available collections.';
+  throw new Error(`Unknown collection "${name}". ${hint}`);
+}
+function parseSelect(input) {
+  return Object.fromEntries(
+    input.split(",").map((field) => field.trim()).map((field) => [field, true])
+  );
+}
 
 // src/lib/parse.ts
 function failArg(label, value, expectedKind) {
@@ -581,21 +613,6 @@ function readFileAsBlob(filePath) {
   const buffer = readFileSync2(filePath);
   return { blob: new Blob([buffer]), filename: basename(filePath) };
 }
-function validateCollection(name) {
-  if (!COLLECTIONS.includes(name)) {
-    const normalized = name.replace(/-/g, "").toLowerCase();
-    const suggestions = COLLECTIONS.filter((c) => {
-      const cn = c.replace(/-/g, "").toLowerCase();
-      return cn.startsWith(normalized) || normalized.startsWith(cn) || normalized.length >= 3 && cn.includes(normalized);
-    }).slice(0, 5);
-    const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 --help" for available collections.';
-    throw new Error(`Unknown collection "${name}". ${hint}`);
-  }
-  return name;
-}
-function parseSelect(input) {
-  return Object.fromEntries(input.split(",").map((f) => [f.trim(), true]));
-}
 function registerCrudCommands(program2, getClient2, getFormat2) {
   program2.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions (JSON)").option("--limit <n>", "Max results", (v) => parseInt(v, 10)).option("--page <n>", "Page number", (v) => parseInt(v, 10)).option("--sort <field>", "Sort field (prefix with - for descending)").option(
     "--depth <n>",
@@ -1552,8 +1569,9 @@ function registerSchemaCommands(program2, getClient2, getFormat2) {
   });
 }
 
-// ../contracts/src/tenant/index.ts
+// ../contracts/dist/index.js
 import { z as z3 } from "zod";
+import { z as z22 } from "zod";
 var tenantFieldConfigStateSchema = z3.object({
   hiddenFields: z3.array(z3.string()),
   isHidden: z3.boolean()
@@ -1697,6 +1715,233 @@ var collectionSchemaResponseSchema = z3.object({
     fields: z3.array(collectionFieldSchema)
   }).strict()
 }).strict();
+var transactionStatusSchema = z22.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled"
+]);
+var updateTransactionSchema = z22.object({
+  pgPaymentId: z22.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
+  status: transactionStatusSchema.describe(
+    "New transaction status (required)"
+  ),
+  paymentMethod: z22.string().optional().describe("Payment method (optional)"),
+  receiptUrl: z22.string().optional().describe("Receipt URL (optional)"),
+  paymentKey: z22.string().min(1).optional().describe("Provider payment key for verified paid confirmation"),
+  amount: z22.number().int().positive().optional().describe("Provider-confirmed amount for verified paid confirmation")
+}).strict();
+var providerSlugSchema = z22.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
+var confirmPaymentSchema = z22.object({
+  orderNumber: z22.string().min(1).optional(),
+  pgPaymentId: z22.string().min(1, "pgPaymentId is required").describe("Provider payment identifier stored on the transaction"),
+  pgProvider: providerSlugSchema.describe(
+    "Payment provider slug, e.g. toss, portone, stripe"
+  ),
+  pgOrderId: z22.string().min(1).optional(),
+  amount: z22.number().int().nonnegative("amount must be non-negative").describe("Provider-confirmed amount in minor units"),
+  currency: z22.string().min(1).optional(),
+  paymentMethod: z22.string().optional(),
+  receiptUrl: z22.string().url().optional(),
+  approvedAt: z22.string().optional(),
+  providerStatus: z22.string().optional(),
+  providerEventId: z22.string().min(1).optional(),
+  confirmationSource: z22.enum([
+    "provider_webhook",
+    "provider_lookup",
+    "provider_api_confirm",
+    "manual_server"
+  ]).optional(),
+  metadata: z22.record(z22.string(), z22.unknown()).optional()
+}).strict();
+var returnReasonSchema2 = z22.enum([
+  "change_of_mind",
+  "defective",
+  "wrong_delivery",
+  "damaged",
+  "other"
+]);
+var restockActionSchema = z22.enum(["return_to_stock", "discard"]);
+var returnWithRefundItemSchema = z22.object({
+  orderItem: z22.union([z22.string(), z22.number()]).transform(String),
+  quantity: z22.number().int().positive("quantity must be a positive integer"),
+  restockAction: restockActionSchema.default("return_to_stock"),
+  restockingFee: z22.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
+}).strict();
+var returnWithRefundSchema = z22.object({
+  orderNumber: z22.string().min(1, "orderNumber is required").describe("Order number (required)"),
+  reason: returnReasonSchema2.optional().describe("Return reason (optional)"),
+  reasonDetail: z22.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z22.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z22.number().min(0, "refundAmount must be non-negative").describe("Refund amount (required, min 0)"),
+  returnShippingFee: z22.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"),
+  pgPaymentId: z22.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
+  paymentKey: z22.string().min(1).optional().describe("Provider payment key for verified refund"),
+  refundReceiptUrl: z22.string().optional().describe("Refund receipt URL (optional)")
+}).strict();
+var MCP_TOOL_CONTRACT = {
+  "query-collection": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "get-collection-by-id": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "get-order": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "stock-check": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "product-detail": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "product-upsert": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "validate-discount": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "calculate-shipping": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "get-collection-schema": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "list-configurable-fields": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "get-tenant-context": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "check-feature-progress": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "add-cart-item": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-cart-item": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "remove-cart-item": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "clear-cart": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "apply-discount": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "remove-discount": {
+    consoleRole: "tenant-editor",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  checkout: {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "create-order": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-order": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "create-fulfillment": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-fulfillment": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "create-return": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-return": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "return-with-refund": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-transaction": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "update-field-config": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
+  "sdk-get-recipe": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "sdk-search-docs": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "sdk-get-auth-setup": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "sdk-get-collection-pattern": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  }
+};
+var MCP_TOOL_NAMES = Object.keys(MCP_TOOL_CONTRACT);
 
 // src/commands/feature.ts
 function getApiUrl2() {
@@ -1850,6 +2095,207 @@ Prerequisites:
   });
 }
 
+// src/commands/agent.ts
+import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
+
+// src/lib/agent-output.ts
+function stringifyAgentJson(data, options = {}) {
+  return options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function errorMessage(error) {
+  const raw = asRecord(error);
+  if (raw) {
+    if (typeof raw.message === "string" && raw.message.length > 0) {
+      return raw.message;
+    }
+    if (raw.detail && typeof raw.detail === "object" && typeof raw.detail.message === "string") {
+      return String(raw.detail.message);
+    }
+  }
+  if (error instanceof Error && error.message.length > 0) {
+    return error.message;
+  }
+  if (typeof error === "string" && error.length > 0) {
+    return error;
+  }
+  return "Internal error";
+}
+function isRawNotFound(error) {
+  const raw = asRecord(error);
+  return raw?.status === 404 || raw?.code === "not_found" || raw?.name === "GoneError";
+}
+function agentErrorExitCode(code) {
+  switch (code) {
+    case "INVALID_INPUT":
+      return 2;
+    case "AUTH_FAILED":
+      return 3;
+    case "NOT_FOUND":
+      return 4;
+    case "INTERNAL":
+      return 1;
+  }
+}
+function classifyAgentError(error) {
+  const adminError = classifyError(error);
+  const message = errorMessage(error);
+  if (isRawNotFound(error) || adminError.code === "not_found") {
+    return { error: { code: "NOT_FOUND", message } };
+  }
+  if (adminError.type === "permission") {
+    return { error: { code: "AUTH_FAILED", message } };
+  }
+  if (adminError.type === "validation" && adminError.code !== "unknown") {
+    return { error: { code: "INVALID_INPUT", message } };
+  }
+  return { error: { code: "INTERNAL", message } };
+}
+function printAgentSuccess(data, options = {}) {
+  console.log(stringifyAgentJson(data, options));
+}
+function printAgentError(error, options = {}) {
+  const envelope = classifyAgentError(error);
+  console.log(stringifyAgentJson(envelope, options));
+  return envelope;
+}
+function exitWithAgentError(error, options = {}) {
+  const envelope = printAgentError(error, options);
+  process.exit(agentErrorExitCode(envelope.error.code));
+}
+
+// src/commands/agent.ts
+var AGENT_PROTOCOL_VERSION = "1";
+function buildStableAgentFields() {
+  return {
+    id: { type: "string", queryable: true },
+    createdAt: { type: "string", queryable: true },
+    updatedAt: { type: "string", queryable: true }
+  };
+}
+function invalidInput(message, field, value) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: "invalid_argument",
+    field,
+    detail: { message, value, field }
+  });
+  return error;
+}
+function parsePositiveInteger(value, field) {
+  if (value == null) return void 0;
+  if (/^[1-9]\d*$/.test(value)) return Number(value);
+  throw invalidInput(`--${field} must be a positive integer`, field, value);
+}
+function handleCommanderError(error) {
+  if (error.code === "commander.helpDisplayed") {
+    process.exit(error.exitCode);
+  }
+  exitWithAgentError(invalidInput(error.message, "command"));
+}
+function configureAgentParser(command) {
+  command.configureOutput({
+    writeErr: () => {
+    },
+    writeOut: (str) => {
+      process.stdout.write(str);
+    }
+  });
+  command.exitOverride(handleCommanderError);
+  return command;
+}
+function parseWhere(value) {
+  if (value == null) return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    throw invalidInput("--where must be a JSON object", "where", value);
+  }
+  throw invalidInput("--where must be a JSON object", "where", value);
+}
+function buildAgentManifest() {
+  const collections = {};
+  for (const collection of COLLECTIONS3) {
+    collections[collection] = {
+      operations: ["query", "get"],
+      fields: buildStableAgentFields()
+    };
+  }
+  return {
+    version: AGENT_PROTOCOL_VERSION,
+    collections
+  };
+}
+function validateAgentCollection(collection) {
+  try {
+    return validateCollection(collection);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : `Unknown collection "${collection}".`;
+    throw invalidInput(message, "collection", collection);
+  }
+}
+function registerAgentCommands(program2, getClient2) {
+  const agent = configureAgentParser(
+    program2.command("agent").description("Machine-stable CLI namespace for coding agents").addHelpText(
+      "after",
+      "\nContract: docs/agent-cli-contract.md\nJSON only on stdout; no TTY effects."
+    )
+  );
+  configureAgentParser(
+    agent.command("manifest").description("Print the Agent CLI protocol manifest").option("--pretty", "Print 2-space indented JSON").action((opts) => {
+      printAgentSuccess(buildAgentManifest(), { pretty: Boolean(opts.pretty) });
+    })
+  );
+  configureAgentParser(
+    agent.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions as a JSON object").option("--limit <n>", "Max results").option("--page <n>", "Page number").option("--sort <field>", "Sort field; prefix with - for descending").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, opts) => {
+        try {
+          const col = validateAgentCollection(collection);
+          const options = {};
+          const where = parseWhere(opts.where);
+          const limit = parsePositiveInteger(opts.limit, "limit");
+          const page = parsePositiveInteger(opts.page, "page");
+          if (where) options.where = where;
+          if (limit != null) options.limit = limit;
+          if (page != null) options.page = page;
+          if (opts.sort) options.sort = opts.sort;
+          if (opts.select) options.select = parseSelect(opts.select);
+          const client = getClient2();
+          const result = await client.collections.from(col).find(options);
+          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+  configureAgentParser(
+    agent.command("get <collection> [id]").description("Get a document by ID").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, id, opts) => {
+        try {
+          const col = validateAgentCollection(collection);
+          if (!id) {
+            throw invalidInput("Missing required argument: id", "id");
+          }
+          const options = {};
+          if (opts.select) options.select = parseSelect(opts.select);
+          const client = getClient2();
+          const result = await client.collections.from(col).findById(id, options);
+          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1865,6 +2311,8 @@ process.on("unhandledRejection", (err) => {
   exitWithError(err, { format: getFormat() });
 });
 var getClient = () => resolveClient(program.opts().apiKey);
+var getAgentClient = () => resolveClientOrThrow(program.opts().apiKey);
+registerAgentCommands(program, getAgentClient);
 registerCrudCommands(program, getClient, getFormat);
 registerOrderCommands(program, getClient, getFormat);
 registerReturnCommands(program, getClient, getFormat);