workato-dev-api 1.0.0 → 1.1.0

package/CLAUDE.md

@@ -0,0 +1,153 @@
+# Workato Dev Environment — Claude Notes
+
+## CLI: `workato-dev-api`
+
+Use `npx workato-dev-api <command>` (or `workato <command>` if installed globally) for all Workato operations — reads and writes alike.
+
+Requires `WORKATO_API_TOKEN` in a `.env` file (cwd `.env` takes highest priority). Base URL: `https://app.trial.workato.com/api`.
+
+### Commands
+
+| 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 |
+| `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 entire recipe code |
+| `workato start <recipe_id>` | Start a recipe |
+| `workato stop <recipe_id>` | Stop a recipe |
+| `workato delete <recipe_id>` | Delete a recipe |
+
+### How `update-step` works
+- Fetches current recipe code
+- Finds the step whose `as` field matches `<step_as_id>` (searches recursively into nested `block` arrays; trigger is the top-level code object)
+- Deep-merges the patch JSON into that step (objects merged, arrays/primitives replaced)
+- PUTs the full updated code back
+
+---
+
+## Recipe Code Structure
+
+A recipe's `code` field is a JSON-stringified object. The top-level object is the **trigger** step; action steps live in `code.block[]`.
+
+```json
+{
+  "number": 0,
+  "provider": "<provider>",
+  "name": "<action_name>",
+  "as": "<8-char-hex>",           // unique step ID used for wiring
+  "keyword": "trigger",            // "trigger" | "action" | "if" | "foreach" etc.
+  "dynamicPickListSelection": {},
+  "toggleCfg": {},
+  "input": { ... },               // field values and wiring go here
+  "extended_output_schema": [...], // THIS is the output schema — must be specified manually
+  "extended_input_schema": [...],  // describes available input fields (e.g. data table columns) — must be specified manually
+  "block": [...],                  // nested steps
+  "uuid": "<uuid>",
+  "title": null,
+  "description": null
+}
+```
+
+There is no non-extended `output_schema` / `input_schema` — `extended_output_schema` and `extended_input_schema` are the only schema fields. For some built-in connector actions (e.g. OpenAI `transcription`), the output schema is known server-side and the step can omit `extended_output_schema` entirely — downstream steps can still wire from it using the datapill syntax. For custom/dynamic steps (e.g. API Platform trigger, Data Table), you must provide these schemas explicitly.
+
+The recipe also has a separate `config` array (JSON-stringified) listing which connections are used:
+```json
+[
+  { "keyword": "application", "name": "<provider>", "provider": "<provider>", "skip_validation": false, "account_id": <connection_id_or_null> }
+]
+```
+
+---
+
+## Field Wiring Syntax
+
+All field values in a step's `input` object use one of three forms:
+
+### 1. Datapill — reference another step's output
+
+```
+"#{_dp('{\"pill_type\":\"output\",\"provider\":\"<provider>\",\"line\":\"<step_as_id>\",\"path\":[\"<field1>\",\"<field2>\"]}')}
+```
+
+- `provider`: the provider of the source step (e.g. `workato_api_platform`, `open_ai`, `workato_db_table`, `google_drive`)
+- `line`: the `as` value (8-char hex) of the source step
+- `path`: JSON array of strings navigating the output schema
+
+**Example — wire trigger's `request.file_content` into an OpenAI step:**
+```json
+"file_content": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"workato_api_platform\",\"line\":\"8f52532b\",\"path\":[\"request\",\"file_content\"]}')}
+```
+
+**Example — wire OpenAI step's `text` output into a data table column:**
+```json
+"03886fe9_176d_4bdd_9296_d48219b345c8": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"open_ai\",\"line\":\"5df21cfd\",\"path\":[\"text\"]}')}
+```
+
+### 2. Formula mode — Workato functions/expressions
+
+Prefix the value with `=` inside the string:
+
+```
+"=\"#{now}\""       // current timestamp
+"=\"#{uuid}\""      // generate a UUID
+```
+
+### 3. Static literal
+
+Plain string value — no special syntax:
+```json
+"language": "en",
+"table_id": "3512"
+```
+
+---
+
+## Data Table Column Names
+
+Data table column field names in `input.parameters` are **UUID-style strings with underscores**, not human-readable names. You must fetch the recipe's existing code (or the data table schema) to get the correct column key for each field.
+
+Example from Audio Transcripts table:
+- `transcript_text` → `03886fe9_176d_4bdd_9296_d48219b345c8`
+- `transcribed_at`  → `aa4e76dd_0de1_4f0a_946b_fb0a4e1ecff5`
+- `file_name`       → `33ee499b_51cc_4ddf_ba03_6a5b8eca79f5`
+- `file_id`         → `0f05f324_040d_4d11_b201_05afaa850729`
+- `recorded_at`     → `aefc6da4_93a5_40e9_b933_13c2cac095ac`
+
+Always use `workato get-data-table <id>` or read the recipe code to look up the actual column UUIDs before wiring.
+
+---
+
+## Reference Recipe
+
+**Transcribe Audio** (ID: 167603) — `https://app.trial.workato.com/recipes/167603-transcribe-audio`
+
+This recipe demonstrates complete working wiring across all three step types (API Platform trigger → OpenAI action → Data Table action). Use it as the canonical wiring reference.
+
+Trigger `as`: `8f52532b` | OpenAI step `as`: `5df21cfd` | Data Table step `as`: `1614a36d`
+
+---
+
+## Current Project
+
+**"Get Audio Transcript"** — Project ID: `14318`, Folder ID: `20245`
+
+Key recipe IDs:
+- `167582` — Get Audio Transcript (callable, RecipeOps trigger)
+- `167583` — Audio File Orchestrator (Google Drive trigger)
+- `167603` — Transcribe Audio (API Platform trigger, reference recipe)
+
+Key connection IDs:
+- OpenAI: `14358`
+- RecipeOps: `14233`
+
+Data Table: **Audio Transcripts** (ID: `3512`) in project `14318`.

package/README.md

@@ -29,8 +29,28 @@ WORKATO_API_TOKEN=your_token_here
 
 You can also export it directly in your shell environment.
 
+## Claude Code setup
+
+In a clean working directory, run these two commands once before starting Claude Code:
+
+```sh
+npx workato-dev-api auth YOUR_API_TOKEN
+npx workato-dev-api bootstrap-claude
+```
+
+That's it. The first command saves your token to `.env`. The second drops a `CLAUDE.md` into the directory so Claude Code automatically has full context — recipe structure, wiring syntax, data table column names, and project reference IDs.
+
+Then just open Claude Code in that directory and start working.
+
 ## Commands
 
+### Setup
+
+| Command | Description |
+|---|---|
+| `workato bootstrap-claude` | Copy `CLAUDE.md` into the current directory |
+| `workato auth <token>` | Save your API token to `.env` in the current directory |
+
 ### Read
 
 | Command | Description |

package/cli.js

@@ -5,6 +5,7 @@ const os = require('os');
 const path = require('path');
 const {
   loadEnv,
+  cmdBootstrapClaude, cmdAuth,
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,
   cmdGetJobs, cmdGetJob,
@@ -12,6 +13,22 @@ const {
   cmdStart, cmdStop, cmdDelete,
 } = require('./lib');
 
+// Setup commands run before env/token setup
+const _setupCmd = process.argv[2];
+if (_setupCmd === 'bootstrap-claude') {
+  cmdBootstrapClaude(process.cwd());
+  process.exit(0);
+}
+if (_setupCmd === 'auth') {
+  const token = process.argv[3];
+  if (!token) {
+    console.error('Usage: workato auth <token>');
+    process.exit(1);
+  }
+  cmdAuth(token, process.cwd());
+  process.exit(0);
+}
+
 // Load order — last one wins, so highest-priority sources go last:
 //   package dir  →  home dir  →  cwd  (cwd always wins)
 loadEnv(path.join(__dirname, '.env'));
@@ -19,7 +36,7 @@ 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');
+  console.error('Error: WORKATO_API_TOKEN not set.\nRun: workato auth <your_token>\nOr create a .env file with: WORKATO_API_TOKEN=your_token_here');
   process.exit(1);
 }
 
@@ -49,6 +66,10 @@ function usage() {
   console.error(`
 workato <command> [options]
 
+Setup:
+  bootstrap-claude                           Copy CLAUDE.md into the current directory
+  auth <token>                               Save API token to .env in the current directory
+
 Read commands:
   get <recipe_id>                            Fetch recipe code → recipe_<id>_code.json
   list-recipes [--folder <id>] [--project <id>] [--page <n>]

package/lib.js

@@ -143,6 +143,30 @@ function apiTriggerConfig() {
   ];
 }
 
+// ── Setup commands ────────────────────────────────────────────────────────────
+
+function cmdBootstrapClaude(destDir) {
+  const src = path.join(__dirname, 'CLAUDE.md');
+  const dest = path.join(destDir ?? process.cwd(), 'CLAUDE.md');
+  fs.copyFileSync(src, dest);
+  console.log(`CLAUDE.md written to ${dest}`);
+  return dest;
+}
+
+function cmdAuth(token, destDir) {
+  const envPath = path.join(destDir ?? process.cwd(), '.env');
+  let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+  const line = `WORKATO_API_TOKEN=${token}`;
+  if (/^WORKATO_API_TOKEN=/m.test(content)) {
+    content = content.replace(/^WORKATO_API_TOKEN=.*/m, line);
+  } else {
+    content = content ? content.trimEnd() + '\n' + line + '\n' : line + '\n';
+  }
+  fs.writeFileSync(envPath, content);
+  console.log(`Token saved to ${envPath}`);
+  return envPath;
+}
+
 // ── Read commands ─────────────────────────────────────────────────────────────
 
 async function cmdGet(recipeId) {
@@ -313,6 +337,8 @@ module.exports = {
   // helpers
   findStep, deepMerge, extractCode,
   apiTriggerCode, apiTriggerConfig,
+  // setup commands
+  cmdBootstrapClaude, cmdAuth,
   // read commands
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workato-dev-api",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI for the Workato Developer API — recipes, connections, data tables, and more",
   "bin": {
     "workato": "cli.js"

package/test/cli.test.js

@@ -982,6 +982,144 @@ describe('cmdUpdateStep — deeply nested step', () => {
   });
 });
 
+// ── cmdBootstrapClaude ────────────────────────────────────────────────────────
+
+describe('cmdBootstrapClaude', () => {
+  function tmpDir() {
+    const d = path.join(os.tmpdir(), `workato-test-${Date.now()}-${Math.random()}`);
+    fs.mkdirSync(d, { recursive: true });
+    return d;
+  }
+
+  test('copies CLAUDE.md into the destination directory', () => {
+    const dir = tmpDir();
+    try {
+      lib.cmdBootstrapClaude(dir);
+      assert.ok(fs.existsSync(path.join(dir, 'CLAUDE.md')), 'CLAUDE.md should exist in dest dir');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('written file content matches the source CLAUDE.md', () => {
+    const dir = tmpDir();
+    try {
+      lib.cmdBootstrapClaude(dir);
+      const srcPath = path.join(__dirname, '..', 'CLAUDE.md');
+      const src = fs.readFileSync(srcPath, 'utf8');
+      const dest = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
+      assert.equal(dest, src);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('returns the destination file path', () => {
+    const dir = tmpDir();
+    try {
+      const result = lib.cmdBootstrapClaude(dir);
+      assert.equal(result, path.join(dir, 'CLAUDE.md'));
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('overwrites an existing CLAUDE.md', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'CLAUDE.md'), 'old content');
+      lib.cmdBootstrapClaude(dir);
+      const content = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
+      assert.notEqual(content, 'old content');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── cmdAuth ───────────────────────────────────────────────────────────────────
+
+describe('cmdAuth', () => {
+  function tmpDir() {
+    const d = path.join(os.tmpdir(), `workato-auth-test-${Date.now()}-${Math.random()}`);
+    fs.mkdirSync(d, { recursive: true });
+    return d;
+  }
+
+  test('creates .env with token when file does not exist', () => {
+    const dir = tmpDir();
+    try {
+      lib.cmdAuth('mytoken123', dir);
+      const content = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+      assert.ok(content.includes('WORKATO_API_TOKEN=mytoken123'));
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('returns the .env file path', () => {
+    const dir = tmpDir();
+    try {
+      const result = lib.cmdAuth('tok', dir);
+      assert.equal(result, path.join(dir, '.env'));
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('updates existing WORKATO_API_TOKEN line in .env', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, '.env'), 'WORKATO_API_TOKEN=oldtoken\n');
+      lib.cmdAuth('newtoken', dir);
+      const content = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+      assert.ok(content.includes('WORKATO_API_TOKEN=newtoken'), 'should have new token');
+      assert.ok(!content.includes('oldtoken'), 'should not have old token');
+      assert.equal((content.match(/WORKATO_API_TOKEN=/g) || []).length, 1, 'only one token line');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('appends token to .env that has other keys but no WORKATO_API_TOKEN', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, '.env'), 'OTHER_KEY=value\n');
+      lib.cmdAuth('mytoken', dir);
+      const content = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+      assert.ok(content.includes('OTHER_KEY=value'), 'existing key preserved');
+      assert.ok(content.includes('WORKATO_API_TOKEN=mytoken'), 'token appended');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('token value containing = is preserved verbatim', () => {
+    const dir = tmpDir();
+    try {
+      lib.cmdAuth('tok==extra==', dir);
+      const content = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+      assert.ok(content.includes('WORKATO_API_TOKEN=tok==extra=='));
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('preserves other keys in .env when updating token', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, '.env'), 'FOO=bar\nWORKATO_API_TOKEN=old\nBAZ=qux\n');
+      lib.cmdAuth('updated', dir);
+      const content = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+      assert.ok(content.includes('FOO=bar'), 'FOO preserved');
+      assert.ok(content.includes('BAZ=qux'), 'BAZ preserved');
+      assert.ok(content.includes('WORKATO_API_TOKEN=updated'), 'token updated');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 // Restore console at end
 process.on('exit', () => {
   console.log = origLog;