zinkee 0.1.12 → 0.1.15

package/package.json

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

package/src/api/records.ts

@@ -133,6 +133,13 @@ export class RecordsApi {
     );
   }
 
+  clearRecords(schema: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/schemas/${selectorValue(schema)}/records:clear`,
+      { method: "DELETE" },
+    );
+  }
+
   private normalizeQueryInput(query: RecordQueryInput): Record<string, unknown> {
     const where = query.where?.map((expression) => ({
       field: expression.field,

package/src/command-registry.ts

@@ -665,6 +665,13 @@ export const commandRegistry = {
     supportsRaw: false,
     output: writeOutput,
   },
+  "records clear": {
+    command: "records clear",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "comments list": {
     command: "comments list",
     accessLevel: "read",

package/src/commands/automations.test.ts

@@ -335,7 +335,7 @@ describe("automations commands", () => {
       "--target-schema",
       "schema-1",
       "--map-json",
-      'owner={"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}',
+      'owner={"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}',
     ]);
 
     expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
@@ -348,7 +348,7 @@ describe("automations commands", () => {
             rawValue: null,
             source: {
               type: "TRIGGER",
-              id: "payload_value",
+              id: "f1e1d000-0000-0000-0000-000000000005",
             },
           },
         },
@@ -378,7 +378,7 @@ describe("automations commands", () => {
       "--target-schema",
       "schema-1",
       "--condition-json",
-      '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}',
+      '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}',
     ]);
 
     expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
@@ -395,7 +395,7 @@ describe("automations commands", () => {
                 rawValue: null,
                 source: {
                   type: "TRIGGER",
-                  id: "payload_value",
+                  id: "f1e1d000-0000-0000-0000-000000000005",
                 },
               },
             ],
@@ -471,7 +471,7 @@ describe("automations commands", () => {
         "--trigger-field",
         "field-1",
         "--condition-json",
-        '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}',
+        '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}',
       ]),
     ).rejects.toThrowError('Expected trigger condition 1 value 1 to use only literal "rawValue" values.');
 

package/src/commands/displays.test.ts

@@ -151,7 +151,7 @@ describe("displays commands", () => {
       "--name",
       "Revenue",
       "--chart-type",
-      "bar",
+      "bars",
     ]);
 
     const init = fetchMock.mock.calls[0]?.[1];
@@ -159,7 +159,7 @@ describe("displays commands", () => {
     expect(JSON.parse(String(init?.body))).toMatchObject({
       type: "CHART",
       presentation: { name: "Revenue" },
-      chart: { chartType: "bar" },
+      chart: { chartType: "bars" },
     });
     expect(JSON.parse(output.read())).toEqual({
       data: { displayId: "display-1", widgetId: "widget-1" },

package/src/commands/records.test.ts

@@ -364,4 +364,62 @@ describe("records commands", () => {
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("clears all records in a schema", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        schemaId: "schema-1",
+        cleared: true,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "clear",
+      "contacts",
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records:clear",
+    );
+    expect(init?.method).toBe("DELETE");
+    expect(init?.body).toBeUndefined();
+
+    const payload = JSON.parse(output.read());
+
+    expect(payload.data).toEqual({
+      schemaId: "schema-1",
+      cleared: true,
+    });
+  });
+
+  it("blocks records clear in read-only mode", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "records",
+        "clear",
+        "contacts",
+      ]),
+    ).rejects.toThrowError('Command "records clear" is not allowed in read-only mode.');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/records.ts

@@ -723,4 +723,23 @@ export function registerRecordsCommands(
 
       writeLine(stdout, `Deleted record "${record.value}" from schema "${schema.value}".`);
     });
+
+  records
+    .command("clear")
+    .description("Delete all records from a schema's table")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, schema: NormalizedUuidOrSlug) {
+      const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+      ensureWritable("records clear", readOnly, "destructive");
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+
+      const data = await api.clearRecords(resolvedSchema);
+
+      if (json) {
+        emitJson(stdout, "records clear", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
+    });
 }

package/src/utils/examples.ts

@@ -411,11 +411,11 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     {
       description: "Patch formula field (formula text).",
       command:
-        `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"amount * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
+        `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
       raw: `{
   "type": "FormulaField",
   "config": {
-    "formulaText": "amount * 1.10",
+    "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10",
     "uiFormatKind": "number",
     "status": "ACTIVE",
     "numberFormatOptions": {
@@ -1398,9 +1398,9 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Create a bar CHART widget with a time-serie x-axis and two y-axis series.",
+      description: "Create a bars CHART widget with a time-serie x-axis and two y-axis series.",
       command:
-        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bar --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"BAR"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"LINE"}' --legend '{"position":"bottom"}'`,
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -1412,7 +1412,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   },
   "presentation": { "name": "Revenue by month" },
   "chart": {
-    "chartType": "bar",
+    "chartType": "bars",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "MONTH",
     "xAxisAsTimeSerie": true,
@@ -1421,13 +1421,13 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#4B9CD3",
-        "axisType": "BAR"
+        "axisType": "PRIMARY"
       },
       {
         "typeCalc": "COUNT",
         "fieldCalc": "id",
         "color": "#E57373",
-        "axisType": "LINE"
+        "axisType": "SECONDARY"
       }
     ],
     "legend": { "position": "bottom" }
@@ -1582,12 +1582,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Replace the chart series with a weekly line.",
+      description: "Replace the chart series with weekly lines.",
       command:
-        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type line --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"LINE"}'`,
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type lines --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"PRIMARY"}'`,
       raw: `{
   "chart": {
-    "chartType": "line",
+    "chartType": "lines",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "WEEK",
     "xAxisAsTimeSerie": true,
@@ -1596,7 +1596,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#2E7D32",
-        "axisType": "LINE"
+        "axisType": "PRIMARY"
       }
     ]
   }
@@ -1932,7 +1932,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "amount * 1.21",
+        "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
         "uiFormatKind": "number",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -1947,12 +1947,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     {
       "id": "6d7e8f90-1234-5678-9abc-def012345678",
       "type": "FormulaField",
-      "slug": "formula-deadline",
-      "label": "Computed Deadline",
+      "slug": "formula-period",
+      "label": "Formula Period",
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "addDays(startDate, 7)",
+        "formulaText": "date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, \"AAAA-MM\")",
         "uiFormatKind": "date",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -2234,6 +2234,17 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       response: `{
   "recordId": "550e8400-e29b-41d4-a716-446655440000",
   "deleted": true
+}`,
+    },
+  ]),
+  "records clear": buildCommandExamples([
+    {
+      description:
+        "Delete every record from a schema's table. Heritage rules (CASCADE / SET NULL) propagate to child schemas asynchronously via the CDC pipeline.",
+      command: "zinkee --json records clear contacts",
+      response: `{
+  "schemaId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+  "cleared": true
 }`,
     },
   ]),
@@ -3353,7 +3364,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       description:
         "Add a search-records action whose condition pulls its value from the trigger payload using --condition-json.",
       command:
-        `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+        `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}'`,
       raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -3368,7 +3379,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "f1e1d000-0000-0000-0000-000000000005"
             }
           }
         ]
@@ -3965,7 +3976,7 @@ async function buildDynamicAutomationExamples(
         {
           description:
             `Add a create-record action with literal and trigger-based mappings targeting ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}'`,
+          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}'`,
           raw: `{
   "type": "create_record",
   "name": "Create follow-up order",
@@ -3980,7 +3991,7 @@ async function buildDynamicAutomationExamples(
         "rawValue": null,
         "source": {
           "type": "TRIGGER",
-          "id": "payload_value"
+          "id": "${schemaField.fieldId}"
         }
       }
     }
@@ -4008,7 +4019,7 @@ async function buildDynamicAutomationExamples(
         },
         {
           description: `Add a search-records action with a trigger-based condition on ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}]}'`,
           raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -4023,7 +4034,7 @@ async function buildDynamicAutomationExamples(
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "${schemaField.fieldId}"
             }
           }
         ]

package/src/utils/schema-fields.ts

@@ -450,17 +450,18 @@ const fieldTypeDefinitions = [
     aliases: ["formula", "FormulaField"],
     description: "Calculated field from a formula.",
     rawShape:
-      '{"type":"FormulaField","slug":"formula-summary","label":"Formula Summary","config":{"formulaText":"concat(firstName, \' \', lastName)","uiFormatKind":"none"}}',
+      '{"type":"FormulaField","slug":"formula-code","label":"Formula Code","config":{"formulaText":"concat(\\"CUST-\\", f1e1d000-0000-0000-0000-000000000005)","uiFormatKind":"none"}}',
     examplePayloads: [
       {
         name: "Formula field (none)",
         payload: {
           type: "FormulaField",
-          slug: "formula-summary",
-          label: "Formula Summary",
+          slug: "formula-code",
+          label: "Formula Code",
           required: false,
           config: {
-            formulaText: "concat(firstName, ' ', lastName)",
+            formulaText:
+              'concat("CUST-", f1e1d000-0000-0000-0000-000000000005)',
             uiFormatKind: "none",
             status: "ACTIVE",
             conditionalFormatting: [],
@@ -475,7 +476,7 @@ const fieldTypeDefinitions = [
           label: "Formula Total",
           required: false,
           config: {
-            formulaText: "amount * 1.21",
+            formulaText: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
             uiFormatKind: "number",
             status: "ACTIVE",
             numberFormatOptions: {
@@ -491,11 +492,12 @@ const fieldTypeDefinitions = [
         name: "Formula field (date)",
         payload: {
           type: "FormulaField",
-          slug: "formula-deadline",
-          label: "Computed Deadline",
+          slug: "formula-period",
+          label: "Formula Period",
           required: false,
           config: {
-            formulaText: "addDays(startDate, 7)",
+            formulaText:
+              'date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, "AAAA-MM")',
             uiFormatKind: "date",
             status: "ACTIVE",
             dateFormatOptions: {
@@ -515,7 +517,7 @@ const fieldTypeDefinitions = [
           label: "Computed Assignee",
           required: false,
           config: {
-            formulaText: "manager",
+            formulaText: "a7b8c9d0-e1f2-3a4b-5c6d-7e8f90123456",
             uiFormatKind: "member",
             status: "ACTIVE",
             conditionalFormatting: [],