workato-dev-api 1.0.0

package/.env.example

@@ -0,0 +1 @@
+WORKATO_API_TOKEN=your_token_here

package/README.md

@@ -0,0 +1,104 @@
+# workato-dev-api
+
+A zero-dependency CLI for the [Workato Developer API](https://docs.workato.com/workato-api.html). Read and edit recipes, connections, data tables, projects, folders, and jobs from your terminal.
+
+## Install
+
+```sh
+npm install -g workato-dev-api
+```
+
+Or use without installing:
+
+```sh
+npx workato-dev-api <command>
+```
+
+## Authentication
+
+Set `WORKATO_API_TOKEN` in a `.env` file. The CLI checks these locations in order, with **later files winning**:
+
+1. `<package-dir>/.env` — lowest priority (rarely used)
+2. `~/.env` — your home directory default
+3. `./.env` (cwd) — **highest priority**, project-specific override
+
+```sh
+# .env
+WORKATO_API_TOKEN=your_token_here
+```
+
+You can also export it directly in your shell environment.
+
+## Commands
+
+### Read
+
+| Command | Description |
+|---|---|
+| `workato get <recipe_id>` | Fetch recipe code JSON → saved to `recipe_<id>_code.json` |
+| `workato list-recipes` | List recipes. Filters: `--folder <id>`, `--project <id>`, `--page <n>` |
+| `workato list-projects` | List all projects |
+| `workato list-folders` | List folders. Filter: `--parent <id>` |
+| `workato list-connections` | List connections. Filter: `--folder <id>` |
+| `workato list-data-tables` | List data tables. Filter: `--project <id>` |
+| `workato get-data-table <id>` | Fetch data table schema and details |
+| `workato get-jobs <recipe_id>` | List recent jobs. Filters: `--limit <n>`, `--status <status>` |
+| `workato get-job <recipe_id> <job_id>` | Fetch a single job |
+
+### Write
+
+| Command | Description |
+|---|---|
+| `workato create "<name>" <code.json>` | Create a recipe from a full code JSON file |
+| `workato create-api-trigger "<name>"` | Create a recipe with a bare API Platform trigger |
+| `workato update-step <recipe_id> <step_as_id> <patch.json>` | Deep-merge a patch into one step (by `as` ID) |
+| `workato put-code <recipe_id> <code.json>` | Replace an entire recipe's code |
+| `workato start <recipe_id>` | Start a recipe |
+| `workato stop <recipe_id>` | Stop a recipe |
+| `workato delete <recipe_id>` | Delete a recipe |
+
+## Examples
+
+```sh
+# Fetch recipe code and save to file
+workato get 167603
+
+# List all recipes in a project
+workato list-recipes --project 14318
+
+# List jobs that failed
+workato get-jobs 167603 --limit 20 --status failed
+
+# Start a recipe
+workato start 167603
+
+# Patch a single step's input fields
+cat > patch.json <<'EOF'
+{
+  "input": {
+    "language": "fr"
+  }
+}
+EOF
+workato update-step 167603 5df21cfd patch.json
+
+# Replace entire recipe code
+workato put-code 167603 recipe_167603_code.json
+```
+
+## Recipe code structure
+
+A recipe's code is a JSON object. The top-level object is the **trigger** step; action steps live in `code.block[]`. Each step has a unique `as` field (8-char hex) used for cross-step wiring (datapills).
+
+`workato get <id>` saves the code to `recipe_<id>_code.json` so you can inspect and edit it before pushing back with `put-code`.
+
+## Development
+
+```sh
+git clone ...
+cd workato-dev-api
+cp .env.example .env   # add your token
+npm test               # runs 88 unit tests, no network required
+```
+
+Tests use Node's built-in `node:test` runner — no extra dependencies.

package/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const {
+  loadEnv,
+  cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
+  cmdListConnections, cmdListDataTables, cmdGetDataTable,
+  cmdGetJobs, cmdGetJob,
+  cmdCreate, cmdCreateApiTrigger, cmdUpdateStep, cmdPutCode,
+  cmdStart, cmdStop, cmdDelete,
+} = require('./lib');
+
+// Load order — last one wins, so highest-priority sources go last:
+//   package dir  →  home dir  →  cwd  (cwd always wins)
+loadEnv(path.join(__dirname, '.env'));
+loadEnv(path.join(os.homedir(), '.env'));
+loadEnv(path.join(process.cwd(), '.env'));
+
+if (!process.env.WORKATO_API_TOKEN) {
+  console.error('Error: WORKATO_API_TOKEN not set.\nCreate a .env file in your current directory with:\n  WORKATO_API_TOKEN=your_token_here');
+  process.exit(1);
+}
+
+// Parse argv: separate --flag value pairs from positional args
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      // treat next token as value unless it's also a flag or missing
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  return { positional, flags };
+}
+
+function usage() {
+  console.error(`
+workato <command> [options]
+
+Read commands:
+  get <recipe_id>                            Fetch recipe code → recipe_<id>_code.json
+  list-recipes [--folder <id>] [--project <id>] [--page <n>]
+  list-projects
+  list-folders [--parent <id>]
+  list-connections [--folder <id>]
+  list-data-tables [--project <id>]
+  get-data-table <id>                        Fetch data table schema/details
+  get-jobs <recipe_id> [--limit <n>] [--status <status>]
+  get-job <recipe_id> <job_id>
+
+Write commands:
+  create "<name>" <code.json>                Create recipe from full code JSON
+  create-api-trigger "<name>"               Create recipe with a bare API Platform trigger
+  update-step <recipe_id> <step_as_id> <patch.json>  Deep-merge patch into a step
+  put-code <recipe_id> <code.json>           Replace entire recipe code
+  start <recipe_id>                          Start a recipe
+  stop <recipe_id>                           Stop a recipe
+  delete <recipe_id>                         Delete a recipe
+
+Environment:
+  WORKATO_API_TOKEN   Required. Set in a .env file in your current directory.
+`.trim());
+  process.exit(1);
+}
+
+const [,, cmd, ...rawArgs] = process.argv;
+const { positional: args, flags } = parseArgs(rawArgs);
+
+(async () => {
+  try {
+    switch (cmd) {
+      // ── Read ──────────────────────────────────────────────────────────────
+      case 'get':
+        if (!args[0]) usage();
+        await cmdGet(args[0]);
+        break;
+
+      case 'list-recipes':
+        await cmdListRecipes({
+          folder_id: flags.folder,
+          project_id: flags.project,
+          page: flags.page,
+        });
+        break;
+
+      case 'list-projects':
+        await cmdListProjects();
+        break;
+
+      case 'list-folders':
+        await cmdListFolders({ parent_id: flags.parent });
+        break;
+
+      case 'list-connections':
+        await cmdListConnections({ folder_id: flags.folder });
+        break;
+
+      case 'list-data-tables':
+        await cmdListDataTables({ project_id: flags.project });
+        break;
+
+      case 'get-data-table':
+        if (!args[0]) usage();
+        await cmdGetDataTable(args[0]);
+        break;
+
+      case 'get-jobs':
+        if (!args[0]) usage();
+        await cmdGetJobs(args[0], { limit: flags.limit, status: flags.status });
+        break;
+
+      case 'get-job':
+        if (!args[0] || !args[1]) usage();
+        await cmdGetJob(args[0], args[1]);
+        break;
+
+      // ── Write ─────────────────────────────────────────────────────────────
+      case 'create':
+        if (!args[0] || !args[1]) usage();
+        await cmdCreate(args[0], args[1]);
+        break;
+
+      case 'create-api-trigger':
+        await cmdCreateApiTrigger(args[0] || 'New API Recipe');
+        break;
+
+      case 'update-step':
+        if (!args[0] || !args[1] || !args[2]) usage();
+        await cmdUpdateStep(args[0], args[1], args[2]);
+        break;
+
+      case 'put-code':
+        if (!args[0] || !args[1]) usage();
+        await cmdPutCode(args[0], args[1]);
+        break;
+
+      case 'start':
+        if (!args[0]) usage();
+        await cmdStart(args[0]);
+        break;
+
+      case 'stop':
+        if (!args[0]) usage();
+        await cmdStop(args[0]);
+        break;
+
+      case 'delete':
+        if (!args[0]) usage();
+        await cmdDelete(args[0]);
+        break;
+
+      default:
+        usage();
+    }
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+})();

package/lib.js

@@ -0,0 +1,323 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const _config = {
+  baseUrl: 'https://app.trial.workato.com/api',
+  token: null,
+};
+
+function loadEnv(envPath) {
+  const p = envPath ?? path.join(process.cwd(), '.env');
+  if (!fs.existsSync(p)) return;
+  for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+    const match = line.match(/^([^#=]+)=(.*)$/);
+    if (match) process.env[match[1].trim()] = match[2].trim();
+  }
+}
+
+function setConfig(cfg) {
+  Object.assign(_config, cfg);
+}
+
+function getToken() {
+  return _config.token || process.env.WORKATO_API_TOKEN;
+}
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+async function apiGet(urlPath) {
+  const res = await fetch(`${_config.baseUrl}${urlPath}`, {
+    headers: { 'Authorization': `Bearer ${getToken()}` },
+  });
+  if (!res.ok) throw new Error(`GET ${urlPath} failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+async function apiPost(urlPath, body) {
+  const res = await fetch(`${_config.baseUrl}${urlPath}`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${getToken()}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`POST ${urlPath} failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+async function apiPut(urlPath, body) {
+  const res = await fetch(`${_config.baseUrl}${urlPath}`, {
+    method: 'PUT',
+    headers: {
+      'Authorization': `Bearer ${getToken()}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`PUT ${urlPath} failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+async function apiDelete(urlPath) {
+  const res = await fetch(`${_config.baseUrl}${urlPath}`, {
+    method: 'DELETE',
+    headers: { 'Authorization': `Bearer ${getToken()}` },
+  });
+  if (!res.ok) throw new Error(`DELETE ${urlPath} failed: ${res.status} ${await res.text()}`);
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+// ── Recipe code helpers ───────────────────────────────────────────────────────
+
+// Recursively find a step by its `as` value within block arrays
+function findStep(block, asId) {
+  for (const step of block) {
+    if (step.as === asId) return step;
+    if (step.block) {
+      const found = findStep(step.block, asId);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// Deep merge source into target (mutates target). Arrays/primitives are replaced, objects are merged.
+function deepMerge(target, source) {
+  for (const [key, val] of Object.entries(source)) {
+    if (
+      val && typeof val === 'object' && !Array.isArray(val) &&
+      target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
+    ) {
+      deepMerge(target[key], val);
+    } else {
+      target[key] = val;
+    }
+  }
+}
+
+function extractCode(data) {
+  const recipe = data.recipe ?? data;
+  return JSON.parse(recipe.code);
+}
+
+function randomHex(n) {
+  return crypto.randomBytes(n).toString('hex').slice(0, n);
+}
+
+function randomUUID() {
+  return crypto.randomUUID();
+}
+
+function apiTriggerCode() {
+  return {
+    number: 0,
+    provider: 'workato_api_platform',
+    name: 'receive_request',
+    as: randomHex(8),
+    title: null,
+    description: null,
+    keyword: 'trigger',
+    dynamicPickListSelection: {},
+    toggleCfg: {},
+    input: {
+      request: { content_type: 'json', schema: '[]' },
+      response: { content_type: 'json', responses: [] },
+    },
+    extended_output_schema: [],
+    extended_input_schema: [],
+    block: [],
+    uuid: randomUUID(),
+  };
+}
+
+function apiTriggerConfig() {
+  return [
+    { keyword: 'application', name: 'workato_api_platform', provider: 'workato_api_platform', skip_validation: false, account_id: null },
+  ];
+}
+
+// ── Read commands ─────────────────────────────────────────────────────────────
+
+async function cmdGet(recipeId) {
+  const data = await apiGet(`/recipes/${recipeId}`);
+  const code = extractCode(data);
+  const outFile = `recipe_${recipeId}_code.json`;
+  fs.writeFileSync(outFile, JSON.stringify(code, null, 2));
+  console.log(JSON.stringify(code, null, 2));
+  console.error(`\nSaved to ${outFile}`);
+  return code;
+}
+
+async function cmdListRecipes(opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.folder_id) params.set('folder_id', opts.folder_id);
+  if (opts.project_id) params.set('project_id', opts.project_id);
+  if (opts.page) params.set('page', opts.page);
+  if (opts.per_page) params.set('per_page', opts.per_page);
+  const qs = params.toString();
+  const data = await apiGet(`/recipes${qs ? '?' + qs : ''}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdListProjects() {
+  const data = await apiGet('/projects');
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdListFolders(opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.parent_id) params.set('parent_id', opts.parent_id);
+  const qs = params.toString();
+  const data = await apiGet(`/folders${qs ? '?' + qs : ''}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdListConnections(opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.folder_id) params.set('folder_id', opts.folder_id);
+  const qs = params.toString();
+  const data = await apiGet(`/connections${qs ? '?' + qs : ''}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdListDataTables(opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.project_id) params.set('project_id', opts.project_id);
+  const qs = params.toString();
+  const data = await apiGet(`/data_tables${qs ? '?' + qs : ''}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdGetDataTable(id) {
+  const data = await apiGet(`/data_tables/${id}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdGetJobs(recipeId, opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.limit) params.set('per_page', opts.limit);
+  if (opts.status) params.set('status', opts.status);
+  const qs = params.toString();
+  const data = await apiGet(`/recipes/${recipeId}/jobs${qs ? '?' + qs : ''}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+async function cmdGetJob(recipeId, jobId) {
+  const data = await apiGet(`/recipes/${recipeId}/jobs/${jobId}`);
+  console.log(JSON.stringify(data, null, 2));
+  return data;
+}
+
+// ── Write commands ────────────────────────────────────────────────────────────
+
+async function cmdCreate(name, codeFile) {
+  const code = JSON.parse(fs.readFileSync(codeFile, 'utf8'));
+  const result = await apiPost('/recipes', {
+    recipe: { name, code: JSON.stringify(code) },
+  });
+  console.log(JSON.stringify(result, null, 2));
+  const id = (result.recipe ?? result).id;
+  console.error(`\nCreated recipe id: ${id}`);
+  return result;
+}
+
+async function cmdCreateApiTrigger(name) {
+  const code = apiTriggerCode();
+  const config = apiTriggerConfig();
+  const result = await apiPost('/recipes', {
+    recipe: { name, code: JSON.stringify(code), config: JSON.stringify(config) },
+  });
+  console.log(JSON.stringify(result, null, 2));
+  const id = (result.recipe ?? result).id;
+  console.error(`\nCreated recipe id: ${id}`);
+  return result;
+}
+
+async function cmdUpdateStep(recipeId, asId, patchFile) {
+  const patch = JSON.parse(fs.readFileSync(patchFile, 'utf8'));
+
+  const data = await apiGet(`/recipes/${recipeId}`);
+  const code = extractCode(data);
+
+  let step;
+  if (code.as === asId) {
+    step = code;
+  } else {
+    step = findStep(code.block ?? [], asId);
+  }
+  if (!step) throw new Error(`Step with as="${asId}" not found`);
+
+  console.error(`Found step: ${step.keyword} (as: ${asId})`);
+  deepMerge(step, patch);
+
+  const result = await apiPut(`/recipes/${recipeId}`, {
+    recipe: { code: JSON.stringify(code) },
+  });
+  console.log(JSON.stringify(result, null, 2));
+  console.error(`\nStep ${asId} updated successfully.`);
+  return result;
+}
+
+async function cmdPutCode(recipeId, codeFile) {
+  const code = JSON.parse(fs.readFileSync(codeFile, 'utf8'));
+  const result = await apiPut(`/recipes/${recipeId}`, {
+    recipe: { code: JSON.stringify(code) },
+  });
+  console.log(JSON.stringify(result, null, 2));
+  console.error('\nRecipe code replaced successfully.');
+  return result;
+}
+
+async function cmdStart(recipeId) {
+  const result = await apiPut(`/recipes/${recipeId}/start`, {});
+  console.log(JSON.stringify(result, null, 2));
+  console.error(`\nRecipe ${recipeId} started.`);
+  return result;
+}
+
+async function cmdStop(recipeId) {
+  const result = await apiPut(`/recipes/${recipeId}/stop`, {});
+  console.log(JSON.stringify(result, null, 2));
+  console.error(`\nRecipe ${recipeId} stopped.`);
+  return result;
+}
+
+async function cmdDelete(recipeId) {
+  const result = await apiDelete(`/recipes/${recipeId}`);
+  console.log(JSON.stringify(result, null, 2));
+  console.error(`\nRecipe ${recipeId} deleted.`);
+  return result;
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // config
+  loadEnv, setConfig, getToken,
+  // http
+  apiGet, apiPost, apiPut, apiDelete,
+  // helpers
+  findStep, deepMerge, extractCode,
+  apiTriggerCode, apiTriggerConfig,
+  // read commands
+  cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
+  cmdListConnections, cmdListDataTables, cmdGetDataTable,
+  cmdGetJobs, cmdGetJob,
+  // write commands
+  cmdCreate, cmdCreateApiTrigger, cmdUpdateStep, cmdPutCode,
+  cmdStart, cmdStop, cmdDelete,
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "workato-dev-api",
+  "version": "1.0.0",
+  "description": "CLI for the Workato Developer API — recipes, connections, data tables, and more",
+  "bin": {
+    "workato": "cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/cli.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "workato",
+    "cli",
+    "api",
+    "recipes",
+    "automation"
+  ],
+  "license": "MIT"
+}