workato-dev-api 1.1.0 → 1.2.1

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

@@ -1,8 +1,29 @@
 # 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.
+Zero-dependency CLI and SDK for the [Workato Developer API](https://docs.workato.com/workato-api.html). Built for use with AI coding assistants and programmatic tooling — read and write recipes, connections, data tables, projects, folders, and jobs.
 
-## Install
+---
+
+## Claude Code / Cursor / Windsurf / ...
+
+In a clean working directory, run these two commands once before opening your AI assistant:
+
+```sh
+npx workato-dev-api auth YOUR_API_TOKEN
+npx workato-dev-api bootstrap
+```
+
+The first saves your token to `.env`. The second drops a `CLAUDE.md` into the directory — picked up automatically by Claude Code, Cursor, Windsurf, and other assistants that support project context files — giving it full Workato context: recipe structure, wiring syntax, data table column naming, and how to use this CLI.
+
+Then open your assistant in that directory and start working.
+
+> **Workato free sandbox?** Just tell your assistant — it will update your `package.json` automatically so the CLI points at the right URL.
+
+---
+
+## SDK / CLI Reference
+
+### Install
 
 ```sh
 npm install -g workato-dev-api
@@ -14,44 +35,42 @@ Or use without installing:
 npx workato-dev-api <command>
 ```
 
-## Authentication
+### 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
+Set `WORKATO_API_TOKEN` in a `.env` file, or run:
 
 ```sh
-# .env
-WORKATO_API_TOKEN=your_token_here
+workato auth YOUR_API_TOKEN
 ```
 
-You can also export it directly in your shell environment.
+The CLI checks `.env` files in this order, with later files winning:
 
-## Claude Code setup
+1. `<package-dir>/.env`
+2. `~/.env`
+3. `./.env` (cwd) — highest priority
 
-In a clean working directory, run these two commands once before starting Claude Code:
+### Sandbox configuration
 
-```sh
-npx workato-dev-api auth YOUR_API_TOKEN
-npx workato-dev-api bootstrap-claude
-```
+By default the CLI targets `app.workato.com`. For a Workato free sandbox (trial account), set in your `package.json`:
 
-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.
+```json
+{
+  "workato": { "sandbox": true }
+}
+```
 
-Then just open Claude Code in that directory and start working.
+This switches the base URL to `app.trial.workato.com`.
 
-## Commands
+### Commands
 
-### Setup
+#### 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 |
+| `workato auth <token>` | Save API token to `.env` in the current directory |
+| `workato bootstrap` | Copy `CLAUDE.md` into the current directory |
 
-### Read
+#### Read
 
 | Command | Description |
 |---|---|
@@ -65,7 +84,7 @@ Then just open Claude Code in that directory and start working.
 | `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
+#### Write
 
 | Command | Description |
 |---|---|
@@ -77,48 +96,19 @@ Then just open Claude Code in that directory and start working.
 | `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
+### 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`.
+`workato get <id>` saves the code to `recipe_<id>_code.json` for inspection and editing before pushing back with `put-code`.
 
-## Development
+### Development
 
 ```sh
-git clone ...
+git clone https://github.com/bill-bishop/workato-dev-api
 cd workato-dev-api
 cp .env.example .env   # add your token
-npm test               # runs 88 unit tests, no network required
+npm test               # 110 unit tests, no network required
 ```
 
 Tests use Node's built-in `node:test` runner — no extra dependencies.

package/cli.js

@@ -4,8 +4,8 @@
 const os = require('os');
 const path = require('path');
 const {
-  loadEnv,
-  cmdBootstrapClaude, cmdAuth,
+  loadEnv, setConfig, resolveBaseUrl, readProjectConfig,
+  cmdBootstrap, cmdAuth,
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,
   cmdGetJobs, cmdGetJob,
@@ -15,8 +15,8 @@ const {
 
 // Setup commands run before env/token setup
 const _setupCmd = process.argv[2];
-if (_setupCmd === 'bootstrap-claude') {
-  cmdBootstrapClaude(process.cwd());
+if (_setupCmd === 'bootstrap') {
+  cmdBootstrap(process.cwd());
   process.exit(0);
 }
 if (_setupCmd === 'auth') {
@@ -40,6 +40,10 @@ if (!process.env.WORKATO_API_TOKEN) {
   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 = [];
@@ -67,7 +71,7 @@ function usage() {
 workato <command> [options]
 
 Setup:
-  bootstrap-claude                           Copy CLAUDE.md into the current directory
+  bootstrap                                  Copy CLAUDE.md into the current directory
   auth <token>                               Save API token to .env in the current directory
 
 Read commands:

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;
@@ -145,7 +160,7 @@ function apiTriggerConfig() {
 
 // ── Setup commands ────────────────────────────────────────────────────────────
 
-function cmdBootstrapClaude(destDir) {
+function cmdBootstrap(destDir) {
   const src = path.join(__dirname, 'CLAUDE.md');
   const dest = path.join(destDir ?? process.cwd(), 'CLAUDE.md');
   fs.copyFileSync(src, dest);
@@ -331,14 +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,
+  cmdBootstrap, cmdAuth,
   // read commands
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workato-dev-api",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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,9 +982,110 @@ describe('cmdUpdateStep — deeply nested step', () => {
   });
 });
 
-// ── cmdBootstrapClaude ────────────────────────────────────────────────────────
+// ── resolveBaseUrl ────────────────────────────────────────────────────────────
 
-describe('cmdBootstrapClaude', () => {
+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 });
+    }
+  });
+});
+
+// ── cmdBootstrap ────────────────────────────────────────────────────────
+
+describe('cmdBootstrap', () => {
   function tmpDir() {
     const d = path.join(os.tmpdir(), `workato-test-${Date.now()}-${Math.random()}`);
     fs.mkdirSync(d, { recursive: true });
@@ -994,7 +1095,7 @@ describe('cmdBootstrapClaude', () => {
   test('copies CLAUDE.md into the destination directory', () => {
     const dir = tmpDir();
     try {
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(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 });
@@ -1004,7 +1105,7 @@ describe('cmdBootstrapClaude', () => {
   test('written file content matches the source CLAUDE.md', () => {
     const dir = tmpDir();
     try {
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(dir);
       const srcPath = path.join(__dirname, '..', 'CLAUDE.md');
       const src = fs.readFileSync(srcPath, 'utf8');
       const dest = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
@@ -1017,7 +1118,7 @@ describe('cmdBootstrapClaude', () => {
   test('returns the destination file path', () => {
     const dir = tmpDir();
     try {
-      const result = lib.cmdBootstrapClaude(dir);
+      const result = lib.cmdBootstrap(dir);
       assert.equal(result, path.join(dir, 'CLAUDE.md'));
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
@@ -1028,7 +1129,7 @@ describe('cmdBootstrapClaude', () => {
     const dir = tmpDir();
     try {
       fs.writeFileSync(path.join(dir, 'CLAUDE.md'), 'old content');
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(dir);
       const content = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
       assert.notEqual(content, 'old content');
     } finally {