zinkee 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/commands/automations.test.ts

@@ -449,6 +449,136 @@ describe("automations commands", () => {
     });
   });
 
+  it("builds send_message actions with wrapped fieldMapping (recipients/subject/body)", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: "action-1" }));
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "actions",
+      "add",
+      "automation-1",
+      "--type",
+      "send_message",
+      "--name",
+      "Notify customer",
+      "--to",
+      "customer@example.com",
+      "--subject",
+      "Your order status has changed",
+      "--message",
+      "Hello, your order is now processed.",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      type: "send_message",
+      name: "Notify customer",
+      config: {
+        fieldMapping: {
+          recipients: {
+            rawValue: "customer@example.com",
+            source: null,
+          },
+          subject: {
+            rawValue: "Your order status has changed",
+            source: null,
+          },
+          body: {
+            rawValue: "Hello, your order is now processed.",
+            source: null,
+          },
+        },
+      },
+    });
+  });
+
+  it("wraps send_message --map values in {rawValue, source} like other field mappings", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: "action-1" }));
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "actions",
+      "add",
+      "automation-1",
+      "--type",
+      "send_message",
+      "--name",
+      "Notify customer",
+      "--to",
+      "customer@example.com",
+      "--map-json",
+      'metadata={"orderId":"ORD-1"}',
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      type: "send_message",
+      name: "Notify customer",
+      config: {
+        fieldMapping: {
+          recipients: {
+            rawValue: "customer@example.com",
+            source: null,
+          },
+          metadata: {
+            rawValue: { orderId: "ORD-1" },
+            source: null,
+          },
+        },
+      },
+    });
+  });
+
+  it("builds generate_document actions with template, schema, and file-field ids", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: "action-1" }));
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "actions",
+      "add",
+      "automation-1",
+      "--type",
+      "generate_document",
+      "--name",
+      "Generate invoice PDF",
+      "--document-template",
+      "6c08673e-f8a6-44d2-8c91-d09eca911f8f",
+      "--target-schema",
+      "68d2c7be-4392-42de-b5ae-625ad79cfc3c",
+      "--target-file-field",
+      "c8edbde8-a361-4e9f-a39a-2e88971f21a7",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      type: "generate_document",
+      name: "Generate invoice PDF",
+      config: {
+        documentTemplateId: "6c08673e-f8a6-44d2-8c91-d09eca911f8f",
+        targetSchemaId: "68d2c7be-4392-42de-b5ae-625ad79cfc3c",
+        targetFileFieldId: "c8edbde8-a361-4e9f-a39a-2e88971f21a7",
+      },
+    });
+  });
+
   it("rejects source-based trigger conditions", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/automations.ts

@@ -107,6 +107,11 @@ interface ActionMutationCommandOptions {
   plugin?: string;
   arg?: string[];
   argJson?: string[];
+  to?: string;
+  subject?: string;
+  message?: string;
+  documentTemplate?: string;
+  targetFileField?: string;
   raw?: string;
   rawFile?: string;
 }
@@ -1016,6 +1021,18 @@ function buildActionInput(
     config.targetSchemaId = options.targetSchema;
   }
 
+  if (options.to !== undefined) {
+    mappings.recipients = options.to;
+  }
+
+  if (options.subject !== undefined) {
+    mappings.subject = options.subject;
+  }
+
+  if (options.message !== undefined) {
+    mappings.body = options.message;
+  }
+
   if (!isEmptyObject(mappings)) {
     config.fieldMapping = mappings;
   }
@@ -1073,6 +1090,14 @@ function buildActionInput(
     config.pluginArgs = args;
   }
 
+  if (options.documentTemplate !== undefined) {
+    config.documentTemplateId = options.documentTemplate;
+  }
+
+  if (options.targetFileField !== undefined) {
+    config.targetFileFieldId = options.targetFileField;
+  }
+
   if (!isEmptyObject(config)) {
     if (isJsonObject(config.fieldMapping)) {
       config.fieldMapping = normalizeAutomationFieldMapping(
@@ -1319,9 +1344,26 @@ function addTriggerPayloadOptions(command: Command): Command {
     .option("--raw-file <path>", "path to raw trigger JSON payload");
 }
 
+const ACTION_TYPES_HELP = `
+Action types and their flags:
+  create_record      --target-schema, --map, --map-json
+  update_record      --target-schema, --use-trigger-record, --map,
+                     --condition, --condition-json
+  search_records     --target-schema, --condition, --condition-json
+  send_message       --to, --subject, --message
+                     (--map / --map-json also accepted for extra keys)
+  http_request       --method, --url, --header, --body, --content-type,
+                     --timeout-ms, --var, --auth-mode, --connection
+  execute_plugin     --plugin, --arg, --arg-json
+  generate_document  --document-template, --target-schema, --target-file-field
+`;
+
 function addActionPayloadOptions(command: Command): Command {
   return command
-    .option("--type <type>", "action type")
+    .option(
+      "--type <type>",
+      "action type (create_record|update_record|search_records|send_message|http_request|execute_plugin|generate_document)",
+    )
     .option("--name <name>", "action name")
     .option("--target-schema <uuid>", "target schema id")
     .option("--map <field=value>", "field mapping", collectValues, [])
@@ -1346,8 +1388,14 @@ function addActionPayloadOptions(command: Command): Command {
     .option("--plugin <id>", "plugin id for execute_plugin")
     .option("--arg <key=value>", "plugin argument", collectValues, [])
     .option("--arg-json <key=json>", "plugin argument as JSON", collectValues, [])
+    .option("--to <recipient>", "send_message recipient (maps to fieldMapping.recipients)")
+    .option("--subject <text>", "send_message subject")
+    .option("--message <text>", "send_message body text (maps to fieldMapping.body)")
+    .option("--document-template <uuid>", "generate_document template id")
+    .option("--target-file-field <uuid>", "generate_document target FileField id")
     .option("--raw <json>", "raw action JSON payload")
-    .option("--raw-file <path>", "path to raw action JSON payload");
+    .option("--raw-file <path>", "path to raw action JSON payload")
+    .addHelpText("after", ACTION_TYPES_HELP);
 }
 
 export function registerAutomationsCommands(

package/src/commands/displays.ts

@@ -17,6 +17,9 @@ import type { RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
 import { buildJsonSuccess, printTable } from "../utils/output.js";
 
+const DATE_DYNAMIC_OPTIONS =
+  "today, thisWeek, thisMonth, thisQuarter, thisSemester, thisYear, next7Days, next30Days, next6Months, next12Months, last12Months";
+
 interface CommandIo {
   write(chunk: string): unknown;
 }
@@ -674,7 +677,7 @@ export function registerDisplaysCommands(
     .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
     .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
     .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
     .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: VariableMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables create", readOnly, "write");
@@ -686,7 +689,7 @@ export function registerDisplaysCommands(
     .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
     .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
     .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
     .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string, commandOptions: VariableMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables update", readOnly, "write");

package/src/utils/examples.test.ts

@@ -102,6 +102,52 @@ describe("getCommandExamples", () => {
     expect(webhookExamples[0]?.raw).toContain("idempotencyKeyJsonPath");
   });
 
+  it("covers every action type documented by the backend", () => {
+    const actionExamples = getCommandExamples("automations actions add");
+    const backendActionTypes = [
+      "create_record",
+      "update_record",
+      "search_records",
+      "send_message",
+      "http_request",
+      "execute_plugin",
+      "generate_document",
+    ];
+
+    for (const type of backendActionTypes) {
+      expect(
+        actionExamples.some((example) => example.command.includes(`--type ${type}`)),
+      ).toBe(true);
+    }
+  });
+
+  it("documents send_message with wrapped {rawValue, source} values keyed by recipients/subject/body", () => {
+    const actionExamples = getCommandExamples("automations actions add");
+    const sendMessage = actionExamples.find((example) =>
+      example.command.includes("--type send_message"),
+    );
+
+    expect(sendMessage?.command).toContain("--to customer@example.com");
+    expect(sendMessage?.command).toContain("--subject");
+    expect(sendMessage?.command).toContain("--message");
+    expect(sendMessage?.raw).toContain(`"recipients"`);
+    expect(sendMessage?.raw).toContain(`"rawValue"`);
+    expect(sendMessage?.raw).not.toContain(`"channel"`);
+  });
+
+  it("documents generate_document with template, schema, and file-field ids", () => {
+    const actionExamples = getCommandExamples("automations actions add");
+    const generateDocument = actionExamples.find((example) =>
+      example.command.includes("--type generate_document"),
+    );
+
+    expect(generateDocument?.command).toContain("--document-template");
+    expect(generateDocument?.command).toContain("--target-schema");
+    expect(generateDocument?.command).toContain("--target-file-field");
+    expect(generateDocument?.raw).toContain("documentTemplateId");
+    expect(generateDocument?.raw).toContain("targetFileFieldId");
+  });
+
   it("covers every records query operator documented by the backend", () => {
     const examples = getCommandExamples("records query");
     const backendOperators = [

package/src/utils/examples.ts

@@ -1298,13 +1298,13 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Change a DATE variable to use lastWeek.",
+      description: "Change a DATE variable to use last12Months.",
       command:
-        'zinkee --json displays variables update 0f6f062f-1478-4df2-96a1-c495d037d260 bbbbbbbb-2222-4222-a222-222222222222 --date-mode dynamic --date-dynamic-option lastWeek',
+        'zinkee --json displays variables update 0f6f062f-1478-4df2-96a1-c495d037d260 bbbbbbbb-2222-4222-a222-222222222222 --date-mode dynamic --date-dynamic-option last12Months',
       raw: `{
   "date": {
     "mode": "dynamic",
-    "dynamicOption": "lastWeek"
+    "dynamicOption": "last12Months"
   }
 }`,
     },
@@ -3515,6 +3515,47 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "steps": ["one", "two"]
     }
   }
+}`,
+    },
+    {
+      description:
+        "Add a send-message action. --to maps to fieldMapping.recipients and --message maps to fieldMapping.body. Values are wrapped in {rawValue, source} like every other automation field mapping; use --map / --map-json for extra keys.",
+      command:
+        `zinkee --json automations actions add automation-1 --type send_message --name "Notify customer" --to customer@example.com --subject "Your order status has changed" --message "Hello, your order is now processed."`,
+      raw: `{
+  "type": "send_message",
+  "name": "Notify customer",
+  "config": {
+    "fieldMapping": {
+      "recipients": {
+        "rawValue": "customer@example.com",
+        "source": null
+      },
+      "subject": {
+        "rawValue": "Your order status has changed",
+        "source": null
+      },
+      "body": {
+        "rawValue": "Hello, your order is now processed.",
+        "source": null
+      }
+    }
+  }
+}`,
+    },
+    {
+      description:
+        "Add a generate-document action. The renderer reads the template, writes the file, and stores its id in the target FileField of the target schema.",
+      command:
+        'zinkee --json automations actions add automation-1 --type generate_document --name "Generate invoice PDF" --document-template 6c08673e-f8a6-44d2-8c91-d09eca911f8f --target-schema 68d2c7be-4392-42de-b5ae-625ad79cfc3c --target-file-field c8edbde8-a361-4e9f-a39a-2e88971f21a7',
+      raw: `{
+  "type": "generate_document",
+  "name": "Generate invoice PDF",
+  "config": {
+    "documentTemplateId": "6c08673e-f8a6-44d2-8c91-d09eca911f8f",
+    "targetSchemaId": "68d2c7be-4392-42de-b5ae-625ad79cfc3c",
+    "targetFileFieldId": "c8edbde8-a361-4e9f-a39a-2e88971f21a7"
+  }
 }`,
     },
   ]),
@@ -3569,6 +3610,32 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "authMode": "STORED",
     "connectionId": "connection-1"
   }
+}`,
+    },
+    {
+      description:
+        "Replace a send-message action. --to maps to fieldMapping.recipients and --message maps to fieldMapping.body; values are wrapped in {rawValue, source}.",
+      command:
+        `zinkee --json automations actions update automation-1 action-1 --type send_message --name "Notify customer" --to customer@example.com --subject "Your order status has changed" --message "Hello, your order is now processed."`,
+      raw: `{
+  "type": "send_message",
+  "name": "Notify customer",
+  "config": {
+    "fieldMapping": {
+      "recipients": {
+        "rawValue": "customer@example.com",
+        "source": null
+      },
+      "subject": {
+        "rawValue": "Your order status has changed",
+        "source": null
+      },
+      "body": {
+        "rawValue": "Hello, your order is now processed.",
+        "source": null
+      }
+    }
+  }
 }`,
     },
   ]),