@optima-chat/tiktok-cli 0.10.0 → 0.10.2

package/README.md

@@ -44,12 +44,28 @@ tiktok <domain> <verb> --shop <shopId> [--flags]
 | `delivery-options --warehouse <id>` | 仓库交付方式 |
 | `images upload --file <path> --use-case MAIN_IMAGE [--out <f>]` | 上传本地图 → 返回 TikTok CDN `uri`（multipart，供拼 `main_images` 用） |
 
+## 传参写法
+
+`--key value` 与 `--key=value` 等价，随便用哪种：
+
+```bash
+tiktok promotions create-flashsale --shop <id> --price 11.9    # 空格式
+tiktok promotions create-flashsale --shop=<id> --price=11.9    # 等号式
+```
+
+（0.10.2 之前只认空格式，等号式会让那一格参数**静默消失**而命令照报成功，见 #11。）
+
+**开关型 flag**（`--apply` / `--enable` / `--default` / `--unprocessed`）除了裸传，也能带值：
+`true`/`1`/`yes`/`on` 为真，`false`/`0`/`no`/`off`/空串为假（大小写不敏感），
+给它别的值**当场报错**而不是猜。同一个 flag 写两次以后者为准（`--apply=false --apply` 会真发）。
+
 ## 写操作（Phase 2，安全护栏）
 
 写命令三道阀，把 A 轨「填完回读」纪律做进 CLI：
 
 1. **默认 dry-run** —— 不加 `--apply` 只打印将提交的 payload，不碰真实店铺
-2. `--apply` 才真发
+2. `--apply` 才真发。它是开关，写成 `--apply=false` / `=0` / `=no` / `=off` 一样停在 dry-run；
+   `--apply=true` / `=1` / `=yes` / `=on` 才真发；给它一个看不懂的值（`--apply=maybe`）当场报错、不猜
 3. **成功后自动回读** —— 写完 GET 回资源，输出 `readback` 供 agent/人核对是否生效
 
 ```bash

package/dist/index.js

@@ -202,6 +202,18 @@ function mergeSkus(existing, add) {
   });
   return [...existing, ...filledAdd];
 }
+function fillEmptyList(data, listKey) {
+  if (!listKey) return;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return;
+  const d = data;
+  if (!(listKey in d)) d[listKey] = [];
+}
+function commandUsage(cmd) {
+  return `tiktok ${cmd.name} --shop <shopId> [--flags]
+
+${cmd.summary}
+`;
+}
 var today = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
 var toEpoch = (v) => /^\d+$/.test(v) ? Number(v) : Math.floor(Date.parse(v) / 1e3);
@@ -209,6 +221,7 @@ var COMMANDS = [
   {
     name: "orders list",
     summary: "\u8BA2\u5355\u5217\u8868\uFF08\u9ED8\u8BA4\u8FD130\u5929\u3001\u6309\u521B\u5EFA\u65F6\u95F4\u5012\u5E8F\uFF1B--from/--to\uFF08unix\u79D2\u6216YYYY-MM-DD\uFF09--status --page-size --sort-order ASC/DESC --sort-field create_time/update_time\uFF09",
+    listKey: "orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/order/202309/orders/search", {
       query: {
         page_size: args2["page-size"] ?? "20",
@@ -235,6 +248,7 @@ var COMMANDS = [
   {
     name: "orders cancellations",
     summary: "\u53D6\u6D88\u5355\u5217\u8868\uFF08--status \u53EF\u9009\uFF0C--page-size\uFF09",
+    listKey: "cancellations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/return_refund/202309/cancellations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: args2.status ? { cancel_status: args2.status } : {}
@@ -243,6 +257,7 @@ var COMMANDS = [
   {
     name: "orders returns",
     summary: "\u9000\u8D27\u5355\u5217\u8868\uFF08--status \u53EF\u9009\uFF0C--page-size\uFF09",
+    listKey: "return_orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/return_refund/202309/returns/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: args2.status ? { return_status: args2.status } : {}
@@ -261,6 +276,7 @@ var COMMANDS = [
   {
     name: "orders reject-reasons",
     summary: "\u9A73\u56DE\u53D6\u6D88/\u9000\u8D27\u7684\u5408\u6CD5\u7406\u7531\uFF08--id return_or_cancel_id\uFF09",
+    listKey: "reasons",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/return_refund/202309/reject_reasons", {
       query: { return_or_cancel_id: args2.id }
     })
@@ -288,6 +304,7 @@ var COMMANDS = [
   {
     name: "packages search",
     summary: "\u5305\u88F9\u5217\u8868\uFF08--page-size\uFF09",
+    listKey: "packages",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/fulfillment/202309/packages/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: {}
@@ -560,6 +577,7 @@ var COMMANDS = [
   {
     name: "products list",
     summary: "\u5546\u54C1\u5217\u8868\uFF08--status ACTIVATE \u53EA\u53D6\u5728\u552E\uFF1B\u4E0D\u4F20\u8FD4\u6240\u6709\u542B DELETED\uFF0C\u5199\u64CD\u4F5C\u524D\u52A1\u5FC5\u7B5B ACTIVATE\uFF09",
+    listKey: "products",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/products/search", {
       query: { page_size: args2["page-size"] ?? "20" },
       body: args2.status ? { status: args2.status } : {}
@@ -573,6 +591,7 @@ var COMMANDS = [
   {
     name: "products diagnose",
     summary: "\u5546\u54C1\u5B98\u65B9\u95EE\u9898\u8BCA\u65AD\uFF08--product \u9017\u53F7\u5206\u9694\u672C\u5E97\u81EA\u6709\u5546\u54C1 id\uFF09",
+    listKey: "products",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202405/products/diagnoses", {
       query: { product_ids: String(args2.product ?? "") }
     })
@@ -580,6 +599,7 @@ var COMMANDS = [
   {
     name: "promotions list",
     summary: "\u4FC3\u9500\u6D3B\u52A8\u5217\u8868\uFF08--status ONGOING/NOT_START/EXPIRED\uFF09",
+    listKey: "activities",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/promotion/202309/activities/search", {
       body: { status: args2.status ?? "ONGOING", page_size: Number(args2["page-size"] ?? 20) }
     })
@@ -587,6 +607,7 @@ var COMMANDS = [
   {
     name: "finance statements",
     summary: "\u7ED3\u7B97\u5355\u5217\u8868",
+    listKey: "statements",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/finance/202309/statements", {
       query: {
         page_size: args2["page-size"] ?? "20",
@@ -615,6 +636,7 @@ var COMMANDS = [
   {
     name: "categories recommend",
     summary: "\u7C7B\u76EE\u63A8\u8350\uFF08--title [--desc]\uFF09",
+    listKey: "categories",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/product/202309/categories/recommend", {
       body: {
         product_title: args2.title,
@@ -625,6 +647,7 @@ var COMMANDS = [
   {
     name: "categories tree",
     summary: "\u7C7B\u76EE\u6811\uFF08--version v2\uFF09",
+    listKey: "categories",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/categories", {
       query: { category_version: args2.version ?? "v2" }
     })
@@ -646,6 +669,7 @@ var COMMANDS = [
   {
     name: "brands list",
     summary: "\u54C1\u724C\u5217\u8868\uFF08[--category] [--name]\uFF09",
+    listKey: "brands",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/product/202309/brands", {
       query: {
         page_size: args2["page-size"] ?? "50",
@@ -664,11 +688,13 @@ var COMMANDS = [
   {
     name: "warehouses list",
     summary: "\u4ED3\u5E93\u5217\u8868\uFF08\u8DE8\u5883\u8BA4 sub_type CB_*\uFF09",
+    listKey: "warehouses",
     run: ({ shop }) => proxy("GET", shop, "/logistics/202309/warehouses", {})
   },
   {
     name: "shipping-templates list",
     summary: "\u8FD0\u8D39\u6A21\u677F\u5217\u8868",
+    listKey: "templates",
     run: ({ shop }) => proxy("GET", shop, "/logistics/202510/seller_templates", {})
   },
   {
@@ -783,6 +809,7 @@ var COMMANDS = [
   {
     name: "affiliate creators search",
     summary: "\u8054\u76DF\u5E7F\u573A\u627E\u8FBE\u4EBA\uFF08--keyword\uFF0C--page-size 12|20\uFF0C\u9ED8\u8BA4 12\uFF09",
+    listKey: "creators",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/marketplace_creators/search", {
       query: { page_size: String(args2["page-size"] ?? 12) },
       body: args2.keyword ? { keyword: args2.keyword } : {}
@@ -796,6 +823,7 @@ var COMMANDS = [
   {
     name: "affiliate target-collab search",
     summary: "\u5B9A\u5411\u9080\u7EA6\u5217\u8868\uFF08--status collaboration_status\uFF0C\u5982 ONGOING/EXPIRING/VALID/CANCELING/COMPLETED\uFF1B--page-size\uFF09",
+    listKey: "target_collaborations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/target_collaborations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: args2.status ? { collaboration_status: args2.status } : {}
@@ -809,6 +837,7 @@ var COMMANDS = [
   {
     name: "affiliate samples search",
     summary: "\u6837\u54C1\u7533\u8BF7\u5217\u8868\uFF08--page-size\uFF09",
+    listKey: "sample_applications",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202508/sample_applications/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: {}
@@ -817,6 +846,7 @@ var COMMANDS = [
   {
     name: "affiliate dm list",
     summary: "\u79C1\u4FE1\u4F1A\u8BDD\u5217\u8868\uFF08--page-size\uFF0C--status conversation_status \u53EF\u9009\uFF09\u3002\u26A0\uFE0F\u7248\u672C\u56FA\u5B9A 202412",
+    listKey: "conversations",
     run: ({ shop, args: args2 }) => proxy("GET", shop, "/affiliate_seller/202412/conversations", {
       query: {
         page_size: String(args2["page-size"] ?? 20),
@@ -832,6 +862,7 @@ var COMMANDS = [
   {
     name: "affiliate orders search",
     summary: "\u8054\u76DF\u8BA2\u5355\u5217\u8868\uFF08\u4F63\u91D1\u660E\u7EC6\uFF0C--page-size\uFF09",
+    listKey: "orders",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202410/orders/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: {}
@@ -840,6 +871,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab products-search",
     summary: "\u516C\u5F00\u5408\u4F5C\u53EF\u8BBE\u4F63\u54C1\u5217\u8868\uFF08--page-size\uFF09",
+    listKey: "products",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202405/open_collaborations/products/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: {}
@@ -848,6 +880,7 @@ var COMMANDS = [
   {
     name: "affiliate open-collab search",
     summary: "\u516C\u5F00\u5408\u4F5C\u751F\u6548\u5217\u8868\uFF08\u542B current_commission\uFF0C--page-size\uFF09",
+    listKey: "open_collaborations",
     run: ({ shop, args: args2 }) => proxy("POST", shop, "/affiliate_seller/202412/open_collaborations/search", {
       query: { page_size: String(args2["page-size"] ?? 20) },
       body: {}
@@ -947,6 +980,7 @@ var COMMANDS = [
   {
     name: "affiliate samples review",
     summary: "\u5BA1\u6279\u6837\u54C1\u7533\u8BF7\uFF08--id application_id --result review_result [--reject-reason]\uFF09\u3002\u9ED8\u8BA4 dry-run\uFF0C--apply \u624D\u53D1",
+    listKey: "sample_applications",
     write: true,
     preview: ({ args: args2 }) => [{
       step: "\u5BA1\u6279\u6837\u54C1\u7533\u8BF7",
@@ -1011,7 +1045,7 @@ var COMMANDS = [
   // ── 多 App 管理（admin 配置操作，鉴权走 x-admin-token，不走商家 --shop，也不走三道阀 dry-run/--apply）──
   {
     name: "apps add",
-    summary: "\u767B\u8BB0\u4E00\u4E2A TikTok App\uFF08--service-id --app-key --app-secret --type --label\uFF0C[--markets a,b] [--redirect] [--owner-entity]\uFF09",
+    summary: "\u767B\u8BB0\u4E00\u4E2A TikTok App\uFF08--service-id --app-key --app-secret --type --label\uFF0C[--markets a,b] [--redirect] [--owner-entity] [--default]\uFF09",
     run: ({ args: args2 }) => adminApps("POST", {
       body: {
         serviceId: args2["service-id"],
@@ -1131,7 +1165,13 @@ function parseFlags(tokens) {
   const positional2 = [];
   for (let i = 0; i < tokens.length; i++) {
     const t = tokens[i];
+    if (t === "--") continue;
     if (t.startsWith("--")) {
+      const eq = t.indexOf("=");
+      if (eq !== -1) {
+        args2[t.slice(2, eq)] = t.slice(eq + 1);
+        continue;
+      }
       const key = t.slice(2);
       const next = tokens[i + 1];
       if (next && !next.startsWith("--")) {
@@ -1142,6 +1182,33 @@ function parseFlags(tokens) {
   }
   return { args: args2, positional: positional2 };
 }
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["apply", "default", "unprocessed", "enable"]);
+var FLAG_TRUE = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
+var FLAG_FALSE = /* @__PURE__ */ new Set(["false", "0", "no", "off", ""]);
+function normalizeBooleanFlags(args2) {
+  for (const key of BOOLEAN_FLAGS) {
+    if (!(key in args2)) continue;
+    const raw = args2[key];
+    const v = raw.toLowerCase();
+    if (FLAG_TRUE.has(v)) {
+      args2[key] = "true";
+      continue;
+    }
+    if (FLAG_FALSE.has(v)) {
+      delete args2[key];
+      continue;
+    }
+    out({
+      ok: false,
+      error: {
+        code: "VALIDATION",
+        message: `--${key} \u662F\u5F00\u5173\uFF0C\u53EA\u63A5\u53D7 true/1/yes/on \u6216 false/0/no/off\uFF0C\u6536\u5230\u300C${raw}\u300D`,
+        retryable: false
+      }
+    });
+    process.exit(1);
+  }
+}
 function out(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
 }
@@ -1180,7 +1247,14 @@ if (positional[0] === "images" && positional[1] === "upload") {
   out(r);
   process.exit(0);
 }
+var wantsHelp = argv.includes("--help") || argv.includes("-h");
 var match = findCommand(positional);
+if (wantsHelp) {
+  if (match) process.stderr.write(commandUsage(match.cmd));
+  else usage();
+  process.exit(0);
+}
+normalizeBooleanFlags(args);
 if (!match) {
   out({ ok: false, error: { code: "VALIDATION", message: `\u672A\u77E5\u547D\u4EE4: ${positional.join(" ")}`, retryable: false } });
   usage();
@@ -1212,6 +1286,7 @@ if (match.cmd.write && !("apply" in args)) {
   process.exit(0);
 }
 var env = await match.cmd.run(ctx);
+fillEmptyList(env.data, match.cmd.listKey);
 if (match.cmd.write && env.ok) {
   const result = { ...env, applied: true };
   if (env.data?.warnings?.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/tiktok-cli",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "TikTok Shop CLI for Optima agents — 经 tiktok-backend 操作店铺",
   "type": "module",
   "bin": {