@superglue/cli 1.1.21 → 1.1.23

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

@@ -0,0 +1,251 @@
+# HTTP
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_api",
+  url: "<<my_api_url>>/v1/users",
+  method: "GET",
+  headers: { "Authorization": "Bearer <<my_api_access_token>>" },
+  queryParams: { "limit": "<<limit>>", "status": "active" },
+  body: '{"name": "<<(sourceData) => sourceData.currentItem.name>>"}',
+  pagination: { ... }
+}
+```
+
+All fields support `<<variable>>` and `<<(sourceData) => ...>>` expressions.
+
+### Fields
+
+| Field         | Required | Notes                                                   |
+| ------------- | -------- | ------------------------------------------------------- |
+| `url`         | yes      | Prefer `<<systemId_url>>/path` over hardcoded base URLs |
+| `method`      | yes      | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`                 |
+| `headers`     | no       | Auth headers, content type, custom headers              |
+| `queryParams` | no       | Key-value pairs appended to URL                         |
+| `body`        | no       | Stripped for GET/HEAD/DELETE/OPTIONS                    |
+| `pagination`  | no       | See Pagination section                                  |
+| `systemId`    | no       | Links system credentials and URL. Omit for public APIs  |
+
+## Authentication
+
+Credentials are never injected automatically. You must place auth headers explicitly using `<<systemId_credentialKey>>` syntax.
+
+```javascript
+// Bearer token (including OAuth — token refresh is automatic, header is not)
+{ "Authorization": "Bearer <<systemId_access_token>>" }
+
+// API key
+{ "X-API-Key": "<<systemId_api_key>>" }
+
+// Basic Auth — auto-encoded to Base64, do NOT manually encode
+{ "Authorization": "Basic <<systemId_username>>:<<systemId_password>>" }
+
+// Runtime credentials from payload
+{ "Authorization": "Bearer <<(sourceData) => sourceData.user_access_token>>" }
+```
+
+### SOAP Authentication
+
+Some APIs (e.g. Salesforce) use SOAP XML login where credentials are embedded in the request body, not in headers. Multiple `<<>>` placeholders can appear adjacent — each is resolved independently and the results are concatenated.
+
+```typescript
+{
+  method: "POST",
+  url: "https://test.salesforce.com/services/Soap/u/59.0",
+  headers: {
+    "Content-Type": "text/xml; charset=UTF-8",
+    "SOAPAction": "login"
+  },
+  body: '<?xml version="1.0" encoding="utf-8"?><env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Body><n1:login xmlns:n1="urn:partner.soap.sforce.com"><n1:username><<systemId_username>></n1:username><n1:password><<systemId_password>><<systemId_security_token>></n1:password></n1:login></env:Body></env:Envelope>'
+}
+```
+
+`<<systemId_password>><<systemId_security_token>>` resolves to the password and token concatenated — no separator needed. This works in URL, headers, and body fields.
+
+Headers starting with `x-` are treated as custom headers.
+Modern APIs expect auth in headers, not query parameters, unless docs explicitly say otherwise.
+
+## HTTP Runtime Details
+
+### Request Behavior
+
+- **GET, HEAD, DELETE, OPTIONS**: body is always stripped
+- **POST, PUT, PATCH**: body with leading `{` is JSON-parsed; empty body becomes undefined
+- Default headers: `Accept: */*`, Chrome-like `User-Agent`
+- HTTPS: `rejectUnauthorized: false` (accepts self-signed certs)
+
+### Body Resolution
+
+The runtime processes the body in this order:
+
+1. `<<>>` template variables are resolved — object/array returns are `JSON.stringify`'d before splicing
+2. The resulting string is JSON-parsed when possible
+3. `file::` references are resolved on the parsed object
+4. Final send format is determined:
+   - raw bytes when the entire body is `file::<key>.raw`
+   - base64 string for `file::<key>.base64`
+   - `multipart/form-data` when the `Content-Type` header requests it and body resolves to an object
+   - `JSON.stringify(...)` for objects
+   - plain string for everything else
+
+File references resolve only in the body, not in headers, query params, or URLs.
+
+**Double-encoding risk:** the runtime stringifies at both step 1 (expression into template) and step 4 (object into fetch body). When the body contains nested JSON (e.g. LLM APIs), have `<<>>` expressions return a string via `JSON.stringify(...)`, or use a preceding transform step.
+
+### File Uploads
+
+**Raw body** — send a file as the entire HTTP body:
+
+```typescript
+{
+  method: "PUT",
+  headers: { "Content-Type": "application/pdf" },
+  body: "file::document.raw"
+}
+```
+
+**Base64-in-JSON** — embed a base64-encoded file inside a structured payload:
+
+```typescript
+{
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: '{"fileBase64":"file::document.base64"}'
+}
+```
+
+**Multipart form** — set the `Content-Type` header and provide a JSON object of form fields:
+
+```typescript
+{
+  method: "POST",
+  headers: { "Content-Type": "multipart/form-data" },
+  body: '{"file":"file::report.raw","description":"monthly export"}'
+}
+```
+
+The runtime builds a real `FormData` request: `file::...raw` values become file parts, scalars become text parts, non-file objects/arrays are JSON-stringified into text parts. The user-supplied `Content-Type` header is removed so `fetch` sets the boundary automatically.
+
+Multipart restrictions:
+
+- Body must resolve to a flat object of form fields
+- Nested file refs inside objects are not supported
+- Do not manually set a multipart boundary
+- Use `.raw` for file parts, `.base64` for base64 text fields, `.extracted` for parsed content fields
+
+### Response Handling
+
+All HTTP responses are read as raw bytes, then classified by byte-level detection (see `file-handling.md` for the full detection logic).
+
+- **Binary types** (PDF, Excel, DOCX, ZIP, GZIP): treated as files, parsed content also populates `data`. Later steps can reference via `file::<stepId>.raw/base64/extracted`.
+- **`application/octet-stream`**: always treated as a file.
+- **Responses over 25 MB**: treated as files as a safety fallback.
+- **RAW + `Content-Disposition: attachment`**: treated as a file.
+- **Structured/text responses** (JSON, XML, CSV, YAML, HTML, text under size limit): parsed inline to `data` only.
+
+### Error Detection
+
+Non-2xx responses throw with method, URL, response body preview (1000 chars), masked config, and retry count. Any response with status in the 2xx range is treated as success and returned to the step as-is — the runtime does not scan successful response bodies for error fields, so APIs that return HTTP 200 with `{ "error": "..." }` must be handled by your transform or by setting a `stopCondition`/assertion at the step level.
+
+Bypass: set `failureBehavior: "continue"` to skip the non-2xx throw and return the response anyway.
+
+### Retry Behavior
+
+**Connection/server errors:**
+
+- Default 5 retries, configurable via `retries` on the step
+- Retries on fetch-level errors (network/DNS/abort except timeout) and on 5xx responses
+- Fixed delay between retries (default 1000ms, configurable via `retryDelay`)
+
+**Rate limiting (429):**
+
+- Counts against the same retry budget as 5xx/network errors
+- Respects `Retry-After` header (seconds or HTTP-date)
+- Without header: exponential backoff `10^n * 1000ms + jitter` (capped at 1hr per wait)
+- Total wait across all 429 retries capped at `MAX_RATE_LIMIT_WAIT_MS` (1hr)
+
+**Timeouts:** Request timeout aborts the fetch and throws immediately — timeouts are not retried.
+
+### Pagination
+
+Makes multiple requests in a loop, merging results. Only configure after verifying the exact API pagination mechanism from docs.
+
+**Configuration:**
+
+```typescript
+pagination: {
+  type: "offsetBased" | "pageBased" | "cursorBased",
+  pageSize: "50",
+  cursorPath: "meta.next_cursor",   // cursorBased only — dot-path to cursor
+  stopCondition: "(response, pageInfo) => !response.data.meta.next_cursor"
+}
+```
+
+**Variables** — the matching variable MUST appear in the request (URL, queryParams, headers, or body). Throws if missing.
+
+| Type        | Variable                     | Starts at | Increments by            |
+| ----------- | ---------------------------- | --------- | ------------------------ |
+| pageBased   | `<<page>>`                   | 1         | 1                        |
+| offsetBased | `<<offset>>`                 | 0         | pageSize                 |
+| cursorBased | `<<cursor>>`                 | null      | extracted via cursorPath |
+| all         | `<<limit>>` / `<<pageSize>>` | pageSize  | —                        |
+
+**Stop conditions** — JS expression evaluated in sandbox. Receives `(response, pageInfo)`:
+
+- `response.data` = parsed API response body
+- `response.headers` = response headers
+- `pageInfo = { page, offset, cursor, totalFetched }`
+- Return `true` to STOP
+
+```javascript
+"!response.data.meta.next_cursor";
+"response.data.items.length === 0";
+"response.data.hasMore === false";
+"pageInfo.totalFetched >= 1000";
+```
+
+**Cursor extraction:** `cursorPath` is a simple dot-separated property path (e.g. `meta.next_cursor`, `data.0.id`) resolved against the parsed response body. It is not a JSONPath expression — wildcards, filters, and `$.` prefixes are not supported. For property names containing `@` (e.g. OData `@odata.nextLink`), use the name directly as the path. Null/undefined cursor stops pagination.
+
+**Safety checks (when stopCondition is set):**
+
+1. Identical pages 1 and 2 (both with data): throws — pagination params are not being applied
+2. Both pages empty + stop did not trigger: throws — broken stop condition
+3. Duplicate consecutive response after page 2: auto-stops
+
+**Without stopCondition (fallback):**
+
+- Array shorter than pageSize: stop
+- Duplicate response hash against any previously seen page: stop
+- Non-array response: stop after first request
+- Max 500 requests (vs 1000 max with a stopCondition)
+
+**Paginated step results:** all pages merge into a single result. Access via `sourceData.stepId.data` — it is NOT an array of per-page results. Do not call `.map()` on a paginated step result. Returns single object if one result, array if multiple (unwrapped from single-element array).
+
+### File Output
+
+When an HTTP step downloads a file (PDF, CSV, binary response), set `outputFile: true` on the step to make it downloadable by the user. Without the flag, downloaded files stay internal (only accessible to subsequent steps via `file::` references).
+
+## Common Pitfalls
+
+- Hardcoding base URLs that match the system's base URL instead of using `<<systemId_url>>`
+- Forgetting auth headers entirely — nothing is injected automatically, including for OAuth systems (only token refresh is automatic)
+- Forgetting `outputFile: true` on steps that download files the user wants
+- Putting pagination variables in the config but not setting a `pagination` block, or vice versa
+- Using `<<currentItem.id>>` — must use arrow function syntax: `<<(sourceData) => sourceData.currentItem.id>>`
+- Mixing multiple `<<>>` expressions in one body string when the API expects nested JSON — use a transform step instead
+- Setting `method: "POST"` for GraphQL queries without `modify: false` — POST that only reads should not be marked as modifying
+
+## Error Recovery
+
+When an HTTP step fails and the cause is not immediately clear:
+
+1. **Isolate endpoint vs system-level issues** — use `sg system call` to test a different endpoint on the same system. If multiple endpoints fail, the issue is likely global authentication or system configuration. If only one fails, the issue is endpoint-specific (wrong URL, missing params, incorrect method or authentication scopes).
+
+2. **Check credential scopes and system-side configuration** — a 403 or empty response often means the API key or OAuth token lacks required scopes, or the resource is restricted server-side. Use `sg system search-docs` or a web search to look up required scopes/permissions for the endpoint.
+
+3. **Verify request shape against API docs** — use `sg system search-docs` and web search to confirm the endpoint URL, required headers, query parameters, body format, and expected method. APIs change across versions. Search for the error message and the endpoint in docs and online.
+
+4. **Check for rate limiting** — 429 errors are retried automatically with backoff, but persistent 429s may mean the API key has hit a quota. Check API dashboard or docs for rate limit details.

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

@@ -73,12 +73,14 @@ curl -X POST "$SUPERGLUE_API_ENDPOINT/v1/runs/{runId}/cancel" \
 
 ## SDK Installation
 
+**Always install the latest version** — older SDK versions may have known bugs (e.g. case-sensitivity issues on Linux in versions before 3.3.0).
+
 ```bash
 # TypeScript/JavaScript
-npm install @superglue/client
+npm install @superglue/client@latest
 
 # Python
-pip install superglue-client
+pip install --upgrade superglue-client
 ```
 
 Both SDKs are auto-generated from the OpenAPI spec (JS via orval, Python via openapi-python-client).

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

@@ -0,0 +1,207 @@
+# MSSQL
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_azure_sql",
+  url: "mssql://<<my_azure_sql_user>>:<<my_azure_sql_password>>@<<my_azure_sql_host>>:<<my_azure_sql_port>>/<<my_azure_sql_database>>",
+  body: '{"query": "SELECT * FROM users WHERE id = @param1", "params": [<<userId>>]}'
+}
+```
+
+Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON string with `query` and optional `params`                 |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+mssql://user:password@host:port/database
+sqlserver://user:password@host:port/database
+```
+
+Both `mssql://` and `sqlserver://` are supported.
+
+**Azure SQL Database** — use the fully qualified server name:
+
+```
+mssql://myuser:mypassword@myserver.database.windows.net:1433/mydatabase
+```
+
+Azure SQL usernames often include `@servername` suffix (e.g., `myuser@myserver`). Encode the `@` as `%40` in the URL:
+
+```
+mssql://myuser%40myserver:mypassword@myserver.database.windows.net:1433/mydatabase
+```
+
+**Connection parameters** can be appended as query strings:
+
+```
+mssql://user:password@host:port/database?encrypt=true&trustServerCertificate=false
+```
+
+| Parameter                | Default | Notes                                   |
+| ------------------------ | ------- | --------------------------------------- |
+| `encrypt`                | `true`  | Required for Azure SQL                  |
+| `trustServerCertificate` | `false` | Whether to trust the server certificate |
+| `database`               | —       | Can be in URL path or query parameter   |
+
+### Body Format
+
+JSON string with `query` and optional `params` (or `values`):
+
+```json
+{
+  "query": "SELECT * FROM users WHERE age > @param1 AND status = @param2",
+  "params": [25, "active"]
+}
+```
+
+## Authentication
+
+### SQL Server Authentication (default)
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically.
+
+```
+mssql://<<my_db_user>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_database>>
+```
+
+### Azure Active Directory Authentication
+
+For Azure AD auth, store the following credential keys on the system alongside the standard connection fields:
+
+**Entra ID User + Password** — authenticates as an Azure AD user. Requires an Azure app registration.
+
+| Credential Key | Required | Notes                                                  |
+| -------------- | -------- | ------------------------------------------------------ |
+| `authType`     | yes      | `azure-active-directory-password`                      |
+| `clientId`     | yes      | Application (client) ID from Azure app registration    |
+| `tenantId`     | no       | Directory (tenant) ID                                  |
+| `user`         | yes      | Azure AD username (also accepts `username`, or in URL) |
+| `password`     | yes      | Azure AD password (or in URL)                          |
+
+`user` and `password` can be stored as credentials or embedded in the URL — credentials take precedence.
+
+```
+URL:  mssql://<<sys_user>>:<<sys_password>>@myserver.database.windows.net:1433/mydb
+Credentials: { authType, clientId, tenantId, user, password, host, port, database }
+```
+
+**Service Principal** — authenticates as an Azure AD application. No user/password needed in the URL.
+
+| Credential Key | Required | Notes                                             |
+| -------------- | -------- | ------------------------------------------------- |
+| `authType`     | yes      | `azure-active-directory-service-principal-secret` |
+| `clientId`     | yes      | Application (client) ID                           |
+| `clientSecret` | yes      | Client secret                                     |
+| `tenantId`     | yes      | Directory (tenant) ID                             |
+
+```
+URL:  mssql://myserver.database.windows.net:1433/mydb
+Credentials: { authType, clientId, clientSecret, tenantId, host, port, database }
+```
+
+The runtime authenticates entirely via the service principal credentials — no user or password is needed in the URL.
+
+## MSSQL Runtime Details
+
+### Schema Discovery
+
+superglue does not auto-introspect MSSQL schemas. Before building tools, always query the schema manually with `sg system call` to discover tables and columns:
+
+```json
+{
+  "query": "SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, IS_NULLABLE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'dbo' ORDER BY TABLE_NAME, ORDINAL_POSITION"
+}
+```
+
+For Azure SQL or databases with non-default schemas, adjust the `TABLE_SCHEMA` filter or remove it to see all schemas.
+Always verify table and column names against the actual schema before building tools.
+
+### Parameterized Queries
+
+Always use parameterized queries with `@param1`, `@param2`, etc. This prevents SQL injection. The params array maps positionally: `params[0]` maps to `@param1`, `params[1]` maps to `@param2`, etc.
+
+```json
+{ "query": "SELECT * FROM orders WHERE customer_id = @param1", "params": ["<<customerId>>"] }
+```
+
+With expressions:
+
+```json
+{
+  "query": "INSERT INTO logs (message, level) VALUES (@param1, @param2)",
+  "params": ["<<(sourceData) => sourceData.message>>", "error"]
+}
+```
+
+With OUTPUT (MSSQL equivalent of RETURNING):
+
+```json
+{
+  "query": "INSERT INTO users (name, email) OUTPUT INSERTED.* VALUES (@param1, @param2)",
+  "params": [
+    "<<(sourceData) => sourceData.currentItem.name>>",
+    "<<(sourceData) => sourceData.currentItem.email>>"
+  ]
+}
+```
+
+### Return Value
+
+Returns the recordset — array of row objects with column names as keys.
+
+- `SELECT`: array of matching rows
+- `INSERT/UPDATE/DELETE` with `OUTPUT`: array of returned rows
+- Mutations without `OUTPUT`: empty array
+
+### Batch Operations
+
+Use a data selector returning an array to execute a query per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.newUsers
+// body: {"query": "INSERT INTO users (name) VALUES (@param1)", "params": ["<<(sourceData) => sourceData.currentItem.name>>"]}
+```
+
+### Connection Pooling
+
+- Pools cached by connection string, max 10 clients per pool
+- 30s connection timeout, configurable request timeout
+- Idle pools cleaned up automatically
+- SSL/TLS encryption enabled by default for Azure SQL
+
+### Retry Behavior
+
+Default retries from server config. On final failure, error includes query text and params.
+
+## Common Pitfalls
+
+- Using `$1`, `$2` (PostgreSQL syntax) instead of `@param1`, `@param2` — MSSQL uses named `@param` parameters
+- Forgetting `OUTPUT INSERTED.*` on INSERT/UPDATE/DELETE when you need the result — without it the step returns an empty array
+- Accessing step result directly instead of via `.data` — database results follow the same envelope as all steps: `sourceData.stepId.data`
+- Not URL-encoding `@` in Azure SQL usernames — `myuser@myserver` must be `myuser%40myserver` in the connection URL
+
+## Error Recovery
+
+When an MSSQL step fails and the cause is not obvious:
+
+1. **Read the error message** — superglue includes the query text and params in the error. Check for syntax errors, missing columns, or type mismatches.
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access. Verify with the user that the credentials have the required grants.
+4. **Check Azure-specific issues** — if connecting to Azure SQL:
+   - Confirm the client IP is allowed in the Azure SQL firewall rules
+   - Verify the username includes the `@servername` suffix if required, properly encoded as `%40`
+   - Confirm `encrypt=true` is set (required for Azure SQL)
+5. **Verify parameter types** — MSSQL infers types from the values passed. Passing a string where a number is expected may cause implicit conversion errors. Ensure `params` values match expected column types.

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

@@ -0,0 +1,162 @@
+# ODBC
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_sybase_db",
+  url: "odbc://<<my_sybase_db_username>>:<<my_sybase_db_password>>@<<my_sybase_db_host>>:<<my_sybase_db_port>>/<<my_sybase_db_database>>?DRIVER=<<my_sybase_db_driver>>",
+  body: '{"query": "SELECT * FROM users WHERE id = ?", "params": [<<userId>>]}'
+}
+```
+
+Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON string with `query` and optional `params`                 |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+odbc://user:password@host:port/database?DRIVER=DriverName
+odbc://user:password@host:port/database?DRIVER=FreeTDS&TDS_Version=5.0
+```
+
+The path contains the **database name**. The ODBC driver is specified via the `DRIVER` query parameter (defaults to `FreeTDS` if omitted). This format is consistent with other superglue database strategies (postgres, mssql) where the path is always the database.
+
+**Supported drivers:**
+
+| Driver    | Database                     | Default Port |
+| --------- | ---------------------------- | ------------ |
+| `FreeTDS` | SAP ASE (Sybase), SQL Server | 5000         |
+
+Additional query parameters (beyond `DRIVER`) are passed through to the ODBC connection string as key=value pairs.
+
+### Body Format
+
+JSON string with `query` and optional `params` (or `values`):
+
+```json
+{
+  "query": "SELECT * FROM users WHERE age > ? AND status = ?",
+  "params": [25, "active"]
+}
+```
+
+## Authentication
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically.
+
+```
+odbc://<<my_db_username>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_database>>?DRIVER=<<my_db_driver>>
+```
+
+Credential variables are resolved at runtime before connecting.
+
+## ODBC Runtime Details
+
+### Schema Discovery
+
+superglue does not auto-introspect ODBC database schemas. Before building tools, always query the schema manually with `sg system call` to discover tables and columns.
+
+**SAP ASE (Sybase):**
+
+```json
+{
+  "query": "SELECT o.name AS table_name, c.name AS column_name, t.name AS data_type, CASE WHEN c.status & 8 = 8 THEN 'YES' ELSE 'NO' END AS is_nullable FROM sysobjects o JOIN syscolumns c ON o.id = c.id JOIN systypes t ON c.usertype = t.usertype WHERE o.type = 'U' ORDER BY o.name, c.colid"
+}
+```
+
+Always verify table and column names against the actual schema before building tools.
+
+### Parameterized Queries
+
+Always use parameterized queries with positional `?` placeholders — prevents SQL injection. Parameters are bound positionally from the `params` array.
+
+For numeric or boolean parameters in query params arrays, use unquoted placeholders: `[<<numericParam>>]` not `["<<numericParam>>"]`. The quotes force string resolution.
+
+```json
+{ "query": "SELECT * FROM orders WHERE name = ? AND customer_id = ?", "params": ["<<customerName>>", <<customerId>>] }
+```
+
+With expressions:
+
+```json
+{
+  "query": "INSERT INTO logs (message, level) VALUES (?, ?)",
+  "params": ["<<(sourceData) => sourceData.message>>", "error"]
+}
+```
+
+### Return Value
+
+Returns an array of row objects with column names as keys.
+
+- `SELECT`: array of matching rows
+- `INSERT/UPDATE/DELETE`: empty array (SAP ASE does not support `RETURNING` — query the data separately if needed)
+
+### Batch Operations
+
+Use a data selector returning an array to execute a query per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.newUsers
+// body: {"query": "INSERT INTO users (name) VALUES (?)", "params": ["<<(sourceData) => sourceData.currentItem.name>>"]}
+```
+
+### Retry Behavior
+
+Default retries from server config. On final failure, error includes a truncated query preview.
+
+## SAP ASE (Sybase) Specifics
+
+### Differences from SQL Server
+
+SAP ASE uses Transact-SQL like SQL Server, but with key differences:
+
+- **No `OUTPUT` clause** — use `SELECT @@identity` after INSERT to get the last inserted identity value
+- **No `TOP` with `ORDER BY` guarantee** — use `SET ROWCOUNT n` before the query instead
+- **`CONVERT` syntax differs** — `CONVERT(target_type, expression)` not `CONVERT(expression, style)`
+- **String concatenation** — use `+` operator, not `CONCAT()` (unless ASE 16.0+)
+- **Date functions** — use `GETDATE()` not `CURRENT_TIMESTAMP`, `DATEADD`/`DATEDIFF` syntax matches SQL Server
+
+### TDS Protocol Version
+
+FreeTDS defaults to TDS 5.0 for Sybase connections. If you encounter protocol errors, you can specify the version via query parameter:
+
+```
+odbc://user:pass@host:5000/mydb?DRIVER=FreeTDS&TDS_Version=5.0
+```
+
+| TDS Version | Use Case                   |
+| ----------- | -------------------------- |
+| `5.0`       | SAP ASE / Sybase (default) |
+| `7.0`       | SQL Server 7.0+            |
+| `7.4`       | SQL Server 2012+           |
+
+## Common Pitfalls
+
+- Using `@param1`, `@param2` (MSSQL syntax) or `$1`, `$2` (PostgreSQL syntax) instead of positional `?` placeholders — ODBC uses `?` for all parameter binding
+- Forgetting that SAP ASE has no `OUTPUT`/`RETURNING` clause — mutations return empty arrays; query the data separately
+- Using `CONCAT()` on older ASE versions — use `+` for string concatenation instead
+- Driver name mismatch — the `DRIVER` query parameter must exactly match the section name in `odbcinst.ini` (case-sensitive). Use `DRIVER=FreeTDS`, not `DRIVER=freetds` or `DRIVER=FREETDS`
+- Accessing step result directly instead of via `.data` — database results follow the same envelope as all steps: `sourceData.stepId.data`
+
+## Error Recovery
+
+When an ODBC step fails and the cause is not obvious:
+
+1. **Read the error message** — superglue includes the a truncated query preview in the error. Check for syntax errors, missing columns, or type mismatches.
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access. Verify with the user that the credentials have the required grants.
+4. **Check driver availability** — if the error mentions "driver not found", the `DRIVER` query parameter does not match any registered driver in `/etc/odbcinst.ini`. Verify the driver name is correct and the driver is installed in the Docker image.
+5. **Test the query directly** — use `sg system call` with a simplified version of the query to isolate whether the issue is the query itself, the parameters, or the connection.
+6. **Check TDS version** — protocol errors may indicate a TDS version mismatch. Try adding `?TDS_Version=5.0` to the query parameters for SAP ASE connections.