@superglue/cli 1.1.6 → 1.1.8

package/dist/skills/superglue/references/redis.md

@@ -0,0 +1,190 @@
+# Redis Steps
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_redis",
+  url: "redis://<<my_redis_username>>:<<my_redis_password>>@<<my_redis_host>>:<<my_redis_port>>/<<my_redis_database>>",
+  method: "POST",            // ignored for Redis but required by schema
+  body: '{"command": "GET", "args": ["<<keyName>>"]}'
+}
+```
+
+Configure the connection URL depending on which credentials are saved in the stored Redis system - reference them accordingly.
+
+## URL Format
+
+```
+redis://user:password@host:port/database
+rediss://user:password@host:port/database   (TLS)
+```
+
+- `redis://` for standard connections
+- `rediss://` for TLS-encrypted connections (e.g. Redis Cloud, AWS ElastiCache with encryption)
+- `/database` is the database number (0-15), defaults to 0 if omitted
+
+All credential variables are resolved before connecting. Trailing slashes are cleaned.
+
+## Body Format
+
+JSON string with `command` (required) and optional `args` array. Body can be a single command object or an array of commands (pipelined in a single round-trip):
+
+```json
+{ "command": "GET", "args": ["mykey"] }
+```
+
+Multiple commands:
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] }
+]
+```
+
+### Common Commands
+
+**String operations:**
+
+```json
+{ "command": "GET", "args": ["user:123:name"] }
+{ "command": "SET", "args": ["user:123:name", "Alice"] }
+{ "command": "MGET", "args": ["key1", "key2", "key3"] }
+{ "command": "INCR", "args": ["counter"] }
+```
+
+**Hash operations:**
+
+```json
+{ "command": "HGETALL", "args": ["user:123"] }
+{ "command": "HGET", "args": ["user:123", "email"] }
+{ "command": "HSET", "args": ["user:123", "email", "alice@example.com"] }
+{ "command": "HMGET", "args": ["user:123", "name", "email"] }
+```
+
+**List operations:**
+
+```json
+{ "command": "LRANGE", "args": ["queue:tasks", "0", "-1"] }
+{ "command": "LPUSH", "args": ["queue:tasks", "task1"] }
+{ "command": "RPOP", "args": ["queue:tasks"] }
+{ "command": "LLEN", "args": ["queue:tasks"] }
+```
+
+**Set operations:**
+
+```json
+{ "command": "SMEMBERS", "args": ["tags:post:1"] }
+{ "command": "SADD", "args": ["tags:post:1", "redis", "database"] }
+{ "command": "SISMEMBER", "args": ["tags:post:1", "redis"] }
+```
+
+**Sorted set operations:**
+
+```json
+{ "command": "ZRANGE", "args": ["leaderboard", "0", "-1", "WITHSCORES"] }
+{ "command": "ZADD", "args": ["leaderboard", "100", "player1"] }
+{ "command": "ZRANK", "args": ["leaderboard", "player1"] }
+```
+
+**Key operations:**
+
+```json
+{ "command": "KEYS", "args": ["user:*"] }
+{ "command": "EXISTS", "args": ["mykey"] }
+{ "command": "TTL", "args": ["session:abc"] }
+{ "command": "EXPIRE", "args": ["session:abc", "3600"] }
+{ "command": "DEL", "args": ["mykey"] }
+{ "command": "TYPE", "args": ["mykey"] }
+```
+
+**Scan (safe iteration):**
+
+```json
+{ "command": "SCAN", "args": ["0", "MATCH", "user:*", "COUNT", "100"] }
+{ "command": "HSCAN", "args": ["myhash", "0", "MATCH", "field*"] }
+```
+
+### Dynamic Arguments with Variables
+
+```json
+{ "command": "GET", "args": ["<<(sourceData) => `user:${sourceData.userId}:profile`>>"] }
+```
+
+```json
+{ "command": "HSET", "args": ["<<userKey>>", "<<fieldName>>", "<<fieldValue>>"] }
+```
+
+## Connection Management
+
+- A fresh connection is created per execution and closed after completion
+- TLS auto-configured for `rediss://` URLs (with `rejectUnauthorized: false`)
+- 5-second connection timeout, 30-second command timeout
+- Array commands (pipeline) run on a single connection for efficiency
+
+## Retry Logic
+
+Default retries from server config. On final failure, error includes command and args.
+
+## Return Value
+
+Returns the raw Redis response:
+
+- `GET` / `HGET`: string or null
+- `HGETALL`: object with field-value pairs (flattened array from Redis, parsed by ioredis)
+- `LRANGE` / `SMEMBERS` / `KEYS`: array of strings
+- `SET` / `DEL` / `EXPIRE`: "OK" or integer
+- `INCR` / `LLEN` / `SADD`: integer
+- `MGET` / `HMGET`: array (nulls for missing keys)
+- `SCAN` / `HSCAN`: array of [cursor, results]
+
+## Multiple Commands (Pipeline)
+
+Pass an array of commands to execute them in a single round-trip (like FTP/SFTP batch operations):
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] },
+  { "command": "LRANGE", "args": ["tasks", "0", "-1"] }
+]
+```
+
+Returns an array of results, one per command:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "HGETALL", "result": ["name", "Alice", "email", "alice@example.com"] },
+  { "command": "LRANGE", "result": ["task3", "task2", "task1"] }
+]
+```
+
+If an individual command fails, that entry has `error` instead of `result`:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "WRONGCMD", "error": "ERR unknown command 'WRONGCMD'" }
+]
+```
+
+A single command returns a single result. Multiple commands return an array — same pattern as FTP/SFTP operations.
+
+## Batch Operations via Loop
+
+Use a data selector returning an array to execute a command per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.userIds
+// body: {"command": "HGETALL", "args": ["<<(sourceData) => `user:${sourceData.currentItem}`>>"]}
+```
+
+## Important Notes
+
+- All args must be strings (Redis protocol is text-based) - numbers are auto-coerced
+- Use `SCAN` instead of `KEYS` in production for large keyspaces
+- `HGETALL` returns an empty object `{}` for non-existent keys
+- Use array body for multi-command pipelines instead of separate steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "bin": {
     "sg": "./dist/cli.js"
   },
@@ -15,6 +15,7 @@
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
+    "@superglue/shared": "file:../shared",
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"

package/skills/superglue/SKILL.md

@@ -235,21 +235,26 @@ sg system call --url "postgres://<<my_db_host>>:5432/mydb" \
   --system-id my_db \
   --body '{"query":"SELECT * FROM users LIMIT 5"}'
 
+# Redis command
+sg system call --url "redis://<<my_redis_host>>:6379/0" \
+  --system-id my_redis \
+  --body '{"command":"HGETALL","args":["user:123"]}'
+
 # File server (SFTP)
 sg system call --url "sftp://<<my_sftp_host>>:22/data" \
   --system-id my_sftp \
   --body '{"operation":"list","path":"/"}'
 ```
 
-| Flag                | Description                                               |
-| ------------------- | --------------------------------------------------------- |
-| `--url <url>`       | Full URL with protocol (http/https/postgres/sftp/ftp/smb) |
-| `--system-id <id>`  | System ID for credential injection                        |
-| `--method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH)               |
-| `--headers <json>`  | HTTP headers JSON with credential placeholders            |
-| `--body <string>`   | Request body (JSON string)                                |
-| `--env <env>`       | Environment: `dev` or `prod`                              |
-| `--file <key=path>` | File references (repeatable)                              |
+| Flag                | Description                                                            |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--url <url>`       | Full URL with protocol (http/https/postgres/redis/rediss/sftp/ftp/smb) |
+| `--system-id <id>`  | System ID for credential injection                                     |
+| `--method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH)                            |
+| `--headers <json>`  | HTTP headers JSON with credential placeholders                         |
+| `--body <string>`   | Request body (JSON string)                                             |
+| `--env <env>`       | Environment: `dev` or `prod`                                           |
+| `--file <key=path>` | File references (repeatable)                                           |
 
 **`sg system search-docs`** — Search system documentation.
 
@@ -366,15 +371,26 @@ All step config fields support `<<variable>>` placeholders:
 | -------------------------- | --------------------------- |
 | `<<fieldName>>`            | Payload field or credential |
 | `<<systemId_credKey>>`     | System credential           |
+| `<<sg_auth_email>>`        | Email of authenticated user |
 | `<<(sourceData) => expr>>` | JavaScript expression       |
 
 **CRITICAL**: Simple `<<varName>>` only works for **top-level keys**. No dots, no nesting.
 
-- VALID: `<<userId>>`, `<<currentItem>>`, `<<stripe_api_key>>`
+- VALID: `<<userId>>`, `<<currentItem>>`, `<<stripe_api_key>>`, `<<sg_auth_email>>`
 - INVALID: `<<currentItem.id>>`, `<<sourceData.userId>>` — these FAIL at runtime
 
 For nested access, use arrow functions: `<<(sourceData) => sourceData.currentItem.id>>`
 
+### Context Variables
+
+Context variables provide information about the execution environment:
+
+- `<<sg_auth_email>>` — Email of the authenticated user who triggered the tool
+
+**Use case**: Personalize tool outputs based on who runs the tool (e.g., user-specific permissions, account lookups, audit logging).
+
+**Important**: `sg_auth_email` is NOT available in scheduled executions. Tools using `<<sg_auth_email>>` will fail if run via scheduler.
+
 ### sourceData Object
 
 `sourceData` is the cumulative state available to all JS expressions (data selectors, transforms, variable expressions):
@@ -442,7 +458,7 @@ Empty arrays are valid — the step simply skips execution.
 
 ### Two Step Types
 
-**Request step** (HTTP, Postgres, FTP/SFTP/SMB) — makes an API call:
+**Request step** (HTTP, Postgres, Redis, FTP/SFTP/SMB) — makes an API call:
 
 ```json
 {
@@ -534,9 +550,31 @@ Templates auto-populate endpoints and OAuth config. Use `sg system find` to disc
 
 ### OAuth Flow
 
-1. `sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
-2. `sg system oauth --system-id gmail --scopes "..."`
-3. User authenticates in browser → tokens saved automatically
+**IMPORTANT:** For OAuth systems, always use `--template` when creating the system. Templates auto-configure OAuth URLs, token exchange settings, and scopes. Without a template, OAuth will likely fail or require manual credential setup.
+
+If you don't know the template ID, the CLI auto-detects it from the URL — but using `--template` explicitly is more reliable.
+
+**Step 1: Create the system with template and credentials**
+
+```bash
+# Best: explicit template (auto-fills URL and OAuth config)
+sg system create --name "Gmail" --template gmail \
+  --credentials '{"client_id":"...","client_secret":"..."}'
+
+# Also works: URL-based auto-detection (template inferred from googleapis.com)
+sg system create --name "Gmail" --url https://gmail.googleapis.com \
+  --credentials '{"client_id":"...","client_secret":"..."}'
+```
+
+**Step 2: Authenticate via OAuth**
+
+```bash
+sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.readonly"
+```
+
+**Step 3:** User authenticates in browser → tokens saved automatically
+
+**Common OAuth templates:** gmail, google_drive, google_calendar, google_sheets, slack, salesforce, github, jira, confluence, notion, airtable, hubspot, shopify, dropbox, zoom, microsoft_365
 
 ### System IDs
 
@@ -608,6 +646,7 @@ For detailed documentation on specific topics, read these files in the `referenc
 | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `references/integration.md`           | **READ THIS** when deploying tools to production - SDK usage, REST API, webhooks, error handling |
 | `references/databases.md`             | Building tools that query PostgreSQL/MySQL databases                                             |
+| `references/redis.md`                 | Building tools that interact with Redis (commands, pipelines, data types)                        |
 | `references/file-servers.md`          | Building tools that interact with FTP/SFTP/SMB file servers                                      |
 | `references/transforms-and-output.md` | Complex data transformations, output shaping, JS sandbox constraints                             |
 

package/skills/superglue/references/redis.md

@@ -0,0 +1,190 @@
+# Redis Steps
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_redis",
+  url: "redis://<<my_redis_username>>:<<my_redis_password>>@<<my_redis_host>>:<<my_redis_port>>/<<my_redis_database>>",
+  method: "POST",            // ignored for Redis but required by schema
+  body: '{"command": "GET", "args": ["<<keyName>>"]}'
+}
+```
+
+Configure the connection URL depending on which credentials are saved in the stored Redis system - reference them accordingly.
+
+## URL Format
+
+```
+redis://user:password@host:port/database
+rediss://user:password@host:port/database   (TLS)
+```
+
+- `redis://` for standard connections
+- `rediss://` for TLS-encrypted connections (e.g. Redis Cloud, AWS ElastiCache with encryption)
+- `/database` is the database number (0-15), defaults to 0 if omitted
+
+All credential variables are resolved before connecting. Trailing slashes are cleaned.
+
+## Body Format
+
+JSON string with `command` (required) and optional `args` array. Body can be a single command object or an array of commands (pipelined in a single round-trip):
+
+```json
+{ "command": "GET", "args": ["mykey"] }
+```
+
+Multiple commands:
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] }
+]
+```
+
+### Common Commands
+
+**String operations:**
+
+```json
+{ "command": "GET", "args": ["user:123:name"] }
+{ "command": "SET", "args": ["user:123:name", "Alice"] }
+{ "command": "MGET", "args": ["key1", "key2", "key3"] }
+{ "command": "INCR", "args": ["counter"] }
+```
+
+**Hash operations:**
+
+```json
+{ "command": "HGETALL", "args": ["user:123"] }
+{ "command": "HGET", "args": ["user:123", "email"] }
+{ "command": "HSET", "args": ["user:123", "email", "alice@example.com"] }
+{ "command": "HMGET", "args": ["user:123", "name", "email"] }
+```
+
+**List operations:**
+
+```json
+{ "command": "LRANGE", "args": ["queue:tasks", "0", "-1"] }
+{ "command": "LPUSH", "args": ["queue:tasks", "task1"] }
+{ "command": "RPOP", "args": ["queue:tasks"] }
+{ "command": "LLEN", "args": ["queue:tasks"] }
+```
+
+**Set operations:**
+
+```json
+{ "command": "SMEMBERS", "args": ["tags:post:1"] }
+{ "command": "SADD", "args": ["tags:post:1", "redis", "database"] }
+{ "command": "SISMEMBER", "args": ["tags:post:1", "redis"] }
+```
+
+**Sorted set operations:**
+
+```json
+{ "command": "ZRANGE", "args": ["leaderboard", "0", "-1", "WITHSCORES"] }
+{ "command": "ZADD", "args": ["leaderboard", "100", "player1"] }
+{ "command": "ZRANK", "args": ["leaderboard", "player1"] }
+```
+
+**Key operations:**
+
+```json
+{ "command": "KEYS", "args": ["user:*"] }
+{ "command": "EXISTS", "args": ["mykey"] }
+{ "command": "TTL", "args": ["session:abc"] }
+{ "command": "EXPIRE", "args": ["session:abc", "3600"] }
+{ "command": "DEL", "args": ["mykey"] }
+{ "command": "TYPE", "args": ["mykey"] }
+```
+
+**Scan (safe iteration):**
+
+```json
+{ "command": "SCAN", "args": ["0", "MATCH", "user:*", "COUNT", "100"] }
+{ "command": "HSCAN", "args": ["myhash", "0", "MATCH", "field*"] }
+```
+
+### Dynamic Arguments with Variables
+
+```json
+{ "command": "GET", "args": ["<<(sourceData) => `user:${sourceData.userId}:profile`>>"] }
+```
+
+```json
+{ "command": "HSET", "args": ["<<userKey>>", "<<fieldName>>", "<<fieldValue>>"] }
+```
+
+## Connection Management
+
+- A fresh connection is created per execution and closed after completion
+- TLS auto-configured for `rediss://` URLs (with `rejectUnauthorized: false`)
+- 5-second connection timeout, 30-second command timeout
+- Array commands (pipeline) run on a single connection for efficiency
+
+## Retry Logic
+
+Default retries from server config. On final failure, error includes command and args.
+
+## Return Value
+
+Returns the raw Redis response:
+
+- `GET` / `HGET`: string or null
+- `HGETALL`: object with field-value pairs (flattened array from Redis, parsed by ioredis)
+- `LRANGE` / `SMEMBERS` / `KEYS`: array of strings
+- `SET` / `DEL` / `EXPIRE`: "OK" or integer
+- `INCR` / `LLEN` / `SADD`: integer
+- `MGET` / `HMGET`: array (nulls for missing keys)
+- `SCAN` / `HSCAN`: array of [cursor, results]
+
+## Multiple Commands (Pipeline)
+
+Pass an array of commands to execute them in a single round-trip (like FTP/SFTP batch operations):
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] },
+  { "command": "LRANGE", "args": ["tasks", "0", "-1"] }
+]
+```
+
+Returns an array of results, one per command:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "HGETALL", "result": ["name", "Alice", "email", "alice@example.com"] },
+  { "command": "LRANGE", "result": ["task3", "task2", "task1"] }
+]
+```
+
+If an individual command fails, that entry has `error` instead of `result`:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "WRONGCMD", "error": "ERR unknown command 'WRONGCMD'" }
+]
+```
+
+A single command returns a single result. Multiple commands return an array — same pattern as FTP/SFTP operations.
+
+## Batch Operations via Loop
+
+Use a data selector returning an array to execute a command per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.userIds
+// body: {"command": "HGETALL", "args": ["<<(sourceData) => `user:${sourceData.currentItem}`>>"]}
+```
+
+## Important Notes
+
+- All args must be strings (Redis protocol is text-based) - numbers are auto-coerced
+- Use `SCAN` instead of `KEYS` in production for large keyspaces
+- `HGETALL` returns an empty object `{}` for non-existent keys
+- Use array body for multi-command pipelines instead of separate steps