workato-dev-api 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CLAUDE.md +153 -0
  2. package/README.md +16 -0
  3. package/cli.js +13 -0
  4. package/package.json +1 -1
package/CLAUDE.md ADDED
@@ -0,0 +1,153 @@
1
+ # Workato Dev Environment — Claude Notes
2
+
3
+ ## CLI: `workato-dev-api`
4
+
5
+ Use `npx workato-dev-api <command>` (or `workato <command>` if installed globally) for all Workato operations — reads and writes alike.
6
+
7
+ Requires `WORKATO_API_TOKEN` in a `.env` file (cwd `.env` takes highest priority). Base URL: `https://app.trial.workato.com/api`.
8
+
9
+ ### Commands
10
+
11
+ | Command | Description |
12
+ |---|---|
13
+ | `workato get <recipe_id>` | Fetch recipe code JSON → saved to `recipe_<id>_code.json` |
14
+ | `workato list-recipes` | List recipes. Filters: `--folder <id>`, `--project <id>`, `--page <n>` |
15
+ | `workato list-projects` | List all projects |
16
+ | `workato list-folders` | List folders. Filter: `--parent <id>` |
17
+ | `workato list-connections` | List connections. Filter: `--folder <id>` |
18
+ | `workato list-data-tables` | List data tables. Filter: `--project <id>` |
19
+ | `workato get-data-table <id>` | Fetch data table schema and details |
20
+ | `workato get-jobs <recipe_id>` | List recent jobs. Filters: `--limit <n>`, `--status <status>` |
21
+ | `workato get-job <recipe_id> <job_id>` | Fetch a single job |
22
+ | `workato create "<name>" <code.json>` | Create a recipe from a full code JSON file |
23
+ | `workato create-api-trigger "<name>"` | Create a recipe with a bare API Platform trigger |
24
+ | `workato update-step <recipe_id> <step_as_id> <patch.json>` | Deep-merge a patch into one step (by `as` ID) |
25
+ | `workato put-code <recipe_id> <code.json>` | Replace entire recipe code |
26
+ | `workato start <recipe_id>` | Start a recipe |
27
+ | `workato stop <recipe_id>` | Stop a recipe |
28
+ | `workato delete <recipe_id>` | Delete a recipe |
29
+
30
+ ### How `update-step` works
31
+ - Fetches current recipe code
32
+ - Finds the step whose `as` field matches `<step_as_id>` (searches recursively into nested `block` arrays; trigger is the top-level code object)
33
+ - Deep-merges the patch JSON into that step (objects merged, arrays/primitives replaced)
34
+ - PUTs the full updated code back
35
+
36
+ ---
37
+
38
+ ## Recipe Code Structure
39
+
40
+ A recipe's `code` field is a JSON-stringified object. The top-level object is the **trigger** step; action steps live in `code.block[]`.
41
+
42
+ ```json
43
+ {
44
+ "number": 0,
45
+ "provider": "<provider>",
46
+ "name": "<action_name>",
47
+ "as": "<8-char-hex>", // unique step ID used for wiring
48
+ "keyword": "trigger", // "trigger" | "action" | "if" | "foreach" etc.
49
+ "dynamicPickListSelection": {},
50
+ "toggleCfg": {},
51
+ "input": { ... }, // field values and wiring go here
52
+ "extended_output_schema": [...], // THIS is the output schema — must be specified manually
53
+ "extended_input_schema": [...], // describes available input fields (e.g. data table columns) — must be specified manually
54
+ "block": [...], // nested steps
55
+ "uuid": "<uuid>",
56
+ "title": null,
57
+ "description": null
58
+ }
59
+ ```
60
+
61
+ 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.
62
+
63
+ The recipe also has a separate `config` array (JSON-stringified) listing which connections are used:
64
+ ```json
65
+ [
66
+ { "keyword": "application", "name": "<provider>", "provider": "<provider>", "skip_validation": false, "account_id": <connection_id_or_null> }
67
+ ]
68
+ ```
69
+
70
+ ---
71
+
72
+ ## Field Wiring Syntax
73
+
74
+ All field values in a step's `input` object use one of three forms:
75
+
76
+ ### 1. Datapill — reference another step's output
77
+
78
+ ```
79
+ "#{_dp('{\"pill_type\":\"output\",\"provider\":\"<provider>\",\"line\":\"<step_as_id>\",\"path\":[\"<field1>\",\"<field2>\"]}')}
80
+ ```
81
+
82
+ - `provider`: the provider of the source step (e.g. `workato_api_platform`, `open_ai`, `workato_db_table`, `google_drive`)
83
+ - `line`: the `as` value (8-char hex) of the source step
84
+ - `path`: JSON array of strings navigating the output schema
85
+
86
+ **Example — wire trigger's `request.file_content` into an OpenAI step:**
87
+ ```json
88
+ "file_content": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"workato_api_platform\",\"line\":\"8f52532b\",\"path\":[\"request\",\"file_content\"]}')}
89
+ ```
90
+
91
+ **Example — wire OpenAI step's `text` output into a data table column:**
92
+ ```json
93
+ "03886fe9_176d_4bdd_9296_d48219b345c8": "#{_dp('{\"pill_type\":\"output\",\"provider\":\"open_ai\",\"line\":\"5df21cfd\",\"path\":[\"text\"]}')}
94
+ ```
95
+
96
+ ### 2. Formula mode — Workato functions/expressions
97
+
98
+ Prefix the value with `=` inside the string:
99
+
100
+ ```
101
+ "=\"#{now}\"" // current timestamp
102
+ "=\"#{uuid}\"" // generate a UUID
103
+ ```
104
+
105
+ ### 3. Static literal
106
+
107
+ Plain string value — no special syntax:
108
+ ```json
109
+ "language": "en",
110
+ "table_id": "3512"
111
+ ```
112
+
113
+ ---
114
+
115
+ ## Data Table Column Names
116
+
117
+ 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.
118
+
119
+ Example from Audio Transcripts table:
120
+ - `transcript_text` → `03886fe9_176d_4bdd_9296_d48219b345c8`
121
+ - `transcribed_at` → `aa4e76dd_0de1_4f0a_946b_fb0a4e1ecff5`
122
+ - `file_name` → `33ee499b_51cc_4ddf_ba03_6a5b8eca79f5`
123
+ - `file_id` → `0f05f324_040d_4d11_b201_05afaa850729`
124
+ - `recorded_at` → `aefc6da4_93a5_40e9_b933_13c2cac095ac`
125
+
126
+ Always use `workato get-data-table <id>` or read the recipe code to look up the actual column UUIDs before wiring.
127
+
128
+ ---
129
+
130
+ ## Reference Recipe
131
+
132
+ **Transcribe Audio** (ID: 167603) — `https://app.trial.workato.com/recipes/167603-transcribe-audio`
133
+
134
+ 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.
135
+
136
+ Trigger `as`: `8f52532b` | OpenAI step `as`: `5df21cfd` | Data Table step `as`: `1614a36d`
137
+
138
+ ---
139
+
140
+ ## Current Project
141
+
142
+ **"Get Audio Transcript"** — Project ID: `14318`, Folder ID: `20245`
143
+
144
+ Key recipe IDs:
145
+ - `167582` — Get Audio Transcript (callable, RecipeOps trigger)
146
+ - `167583` — Audio File Orchestrator (Google Drive trigger)
147
+ - `167603` — Transcribe Audio (API Platform trigger, reference recipe)
148
+
149
+ Key connection IDs:
150
+ - OpenAI: `14358`
151
+ - RecipeOps: `14233`
152
+
153
+ Data Table: **Audio Transcripts** (ID: `3512`) in project `14318`.
package/README.md CHANGED
@@ -29,8 +29,24 @@ WORKATO_API_TOKEN=your_token_here
29
29
 
30
30
  You can also export it directly in your shell environment.
31
31
 
32
+ ## Claude Code setup
33
+
34
+ In a clean working directory, run this once before starting Claude Code:
35
+
36
+ ```sh
37
+ npx workato-dev-api bootstrap-claude
38
+ ```
39
+
40
+ 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.
41
+
32
42
  ## Commands
33
43
 
44
+ ### Setup
45
+
46
+ | Command | Description |
47
+ |---|---|
48
+ | `workato bootstrap-claude` | Copy `CLAUDE.md` into the current directory |
49
+
34
50
  ### Read
35
51
 
36
52
  | Command | Description |
package/cli.js CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
+ const fs = require('fs');
4
5
  const os = require('os');
5
6
  const path = require('path');
6
7
  const {
@@ -12,6 +13,15 @@ const {
12
13
  cmdStart, cmdStop, cmdDelete,
13
14
  } = require('./lib');
14
15
 
16
+ // bootstrap-claude runs before env/token setup — handle it immediately
17
+ if (process.argv[2] === 'bootstrap-claude') {
18
+ const src = path.join(__dirname, 'CLAUDE.md');
19
+ const dest = path.join(process.cwd(), 'CLAUDE.md');
20
+ fs.copyFileSync(src, dest);
21
+ console.log(`CLAUDE.md written to ${dest}`);
22
+ process.exit(0);
23
+ }
24
+
15
25
  // Load order — last one wins, so highest-priority sources go last:
16
26
  // package dir → home dir → cwd (cwd always wins)
17
27
  loadEnv(path.join(__dirname, '.env'));
@@ -49,6 +59,9 @@ function usage() {
49
59
  console.error(`
50
60
  workato <command> [options]
51
61
 
62
+ Setup:
63
+ bootstrap-claude Copy CLAUDE.md into the current directory
64
+
52
65
  Read commands:
53
66
  get <recipe_id> Fetch recipe code → recipe_<id>_code.json
54
67
  list-recipes [--folder <id>] [--project <id>] [--page <n>]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "workato-dev-api",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "CLI for the Workato Developer API — recipes, connections, data tables, and more",
5
5
  "bin": {
6
6
  "workato": "cli.js"