workato-dev-api 1.0.1 → 1.2.0

package/CLAUDE.md

@@ -4,7 +4,13 @@
 
 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`.
+Requires `WORKATO_API_TOKEN` in a `.env` file (cwd `.env` takes highest priority).
+
+Base URL is determined by `workato.sandbox` in the project's `package.json`:
+- `false` (default): `https://app.workato.com/api`
+- `true` (free sandbox): `https://app.trial.workato.com/api`
+
+**If the user says they are on a Workato free sandbox or trial account, set `"sandbox": true` in the `workato` block of their `package.json` immediately.**
 
 ### Commands
 
@@ -127,13 +133,12 @@ Always use `workato get-data-table <id>` or read the recipe code to look up the
 
 ---
 
-## Reference Recipe
-
-**Transcribe Audio** (ID: 167603) — `https://app.trial.workato.com/recipes/167603-transcribe-audio`
+## Reference Recipes
 
-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.
+If you are unsure how to wire a particular connector or step type, ask the user:
+> "Do you have an existing recipe that uses [connector/trigger type]? If so, share the recipe ID and I'll fetch it as a wiring reference."
 
-Trigger `as`: `8f52532b` | OpenAI step `as`: `5df21cfd` | Data Table step `as`: `1614a36d`
+Use `workato get <recipe_id>` to inspect the code and extract the correct `as` IDs, `provider` values, `input` structure, and `extended_output_schema` before building or patching a new recipe.
 
 ---
 

package/README.md

@@ -31,13 +31,16 @@ You can also export it directly in your shell environment.
 
 ## Claude Code setup
 
-In a clean working directory, run this once before starting Claude Code:
+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
 ```
 
-This writes a `CLAUDE.md` with full context — recipe code structure, wiring syntax, data table column naming, and project reference IDs — directly into your working directory where Claude Code will pick it up automatically.
+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 open Claude Code in that directory and start working. If you're on a **Workato free sandbox**, just tell Claude — it will update your `package.json` automatically so the CLI points at the right URL.
 
 ## Commands
 
@@ -46,6 +49,7 @@ This writes a `CLAUDE.md` with full context — recipe code structure, wiring sy
 | 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
 

package/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
-const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const {
-  loadEnv,
+  loadEnv, setConfig, resolveBaseUrl, readProjectConfig,
+  cmdBootstrapClaude, cmdAuth,
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,
   cmdGetJobs, cmdGetJob,
@@ -13,12 +13,19 @@ const {
   cmdStart, cmdStop, cmdDelete,
 } = require('./lib');
 
-// bootstrap-claude runs before env/token setup — handle it immediately
-if (process.argv[2] === 'bootstrap-claude') {
-  const src = path.join(__dirname, 'CLAUDE.md');
-  const dest = path.join(process.cwd(), 'CLAUDE.md');
-  fs.copyFileSync(src, dest);
-  console.log(`CLAUDE.md written to ${dest}`);
+// 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);
 }
 
@@ -29,10 +36,14 @@ 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);
 }
 
+// Apply base URL from workato.sandbox in cwd package.json
+const { workato: _wCfg = {} } = readProjectConfig();
+setConfig({ baseUrl: resolveBaseUrl(_wCfg.sandbox) });
+
 // Parse argv: separate --flag value pairs from positional args
 function parseArgs(argv) {
   const positional = [];
@@ -61,6 +72,7 @@ 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

package/lib.js

@@ -7,10 +7,25 @@ const crypto = require('crypto');
 // ── Config ────────────────────────────────────────────────────────────────────
 
 const _config = {
-  baseUrl: 'https://app.trial.workato.com/api',
+  baseUrl: 'https://app.workato.com/api',
   token: null,
 };
 
+function resolveBaseUrl(sandbox) {
+  return sandbox === true
+    ? 'https://app.trial.workato.com/api'
+    : 'https://app.workato.com/api';
+}
+
+function readProjectConfig(cwd) {
+  const pkgPath = path.join(cwd ?? process.cwd(), 'package.json');
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
 function loadEnv(envPath) {
   const p = envPath ?? path.join(process.cwd(), '.env');
   if (!fs.existsSync(p)) return;
@@ -143,6 +158,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) {
@@ -307,12 +346,14 @@ async function cmdDelete(recipeId) {
 
 module.exports = {
   // config
-  loadEnv, setConfig, getToken,
+  loadEnv, setConfig, getToken, resolveBaseUrl, readProjectConfig,
   // http
   apiGet, apiPost, apiPut, apiDelete,
   // 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.1",
+  "version": "1.2.0",
   "description": "CLI for the Workato Developer API — recipes, connections, data tables, and more",
   "bin": {
     "workato": "cli.js"
@@ -18,5 +18,8 @@
     "recipes",
     "automation"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "workato": {
+    "sandbox": false
+  }
 }

package/test/cli.test.js

@@ -982,6 +982,245 @@ describe('cmdUpdateStep — deeply nested step', () => {
   });
 });
 
+// ── resolveBaseUrl ────────────────────────────────────────────────────────────
+
+describe('resolveBaseUrl', () => {
+  test('returns production URL when sandbox is false', () => {
+    assert.equal(lib.resolveBaseUrl(false), 'https://app.workato.com/api');
+  });
+
+  test('returns production URL when sandbox is undefined', () => {
+    assert.equal(lib.resolveBaseUrl(undefined), 'https://app.workato.com/api');
+  });
+
+  test('returns production URL when sandbox is a string "false"', () => {
+    assert.equal(lib.resolveBaseUrl('false'), 'https://app.workato.com/api');
+  });
+
+  test('returns sandbox URL when sandbox is true', () => {
+    assert.equal(lib.resolveBaseUrl(true), 'https://app.trial.workato.com/api');
+  });
+
+  test('sandbox URL contains "trial"', () => {
+    assert.ok(lib.resolveBaseUrl(true).includes('trial'));
+  });
+
+  test('production URL does not contain "trial"', () => {
+    assert.ok(!lib.resolveBaseUrl(false).includes('trial'));
+  });
+});
+
+// ── readProjectConfig ─────────────────────────────────────────────────────────
+
+describe('readProjectConfig', () => {
+  function tmpDir() {
+    const d = path.join(os.tmpdir(), `workato-cfg-test-${Date.now()}-${Math.random()}`);
+    fs.mkdirSync(d, { recursive: true });
+    return d;
+  }
+
+  test('returns empty object when no package.json exists', () => {
+    const dir = tmpDir();
+    try {
+      assert.deepEqual(lib.readProjectConfig(dir), {});
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('returns parsed package.json contents', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ workato: { sandbox: true } }));
+      const cfg = lib.readProjectConfig(dir);
+      assert.equal(cfg.workato.sandbox, true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('returns empty object when package.json is malformed JSON', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), 'not valid json {{{');
+      assert.deepEqual(lib.readProjectConfig(dir), {});
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('sandbox false in package.json resolves to production URL', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ workato: { sandbox: false } }));
+      const { workato: wCfg = {} } = lib.readProjectConfig(dir);
+      assert.equal(lib.resolveBaseUrl(wCfg.sandbox), 'https://app.workato.com/api');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('sandbox true in package.json resolves to trial URL', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ workato: { sandbox: true } }));
+      const { workato: wCfg = {} } = lib.readProjectConfig(dir);
+      assert.equal(lib.resolveBaseUrl(wCfg.sandbox), 'https://app.trial.workato.com/api');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('missing workato key resolves to production URL', () => {
+    const dir = tmpDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'my-project' }));
+      const { workato: wCfg = {} } = lib.readProjectConfig(dir);
+      assert.equal(lib.resolveBaseUrl(wCfg.sandbox), 'https://app.workato.com/api');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── 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;