@superglue/cli 1.1.31 → 1.1.32

package/skills/superglue/references/mongodb.md

@@ -0,0 +1,136 @@
+# MongoDB
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_mongo",
+  url: "mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin",
+  body: '{"collection": "users", "operation": "find", "filter": {"status": "active"}, "options": {"limit": 50, "sort": {"createdAt": -1}}}'
+}
+```
+
+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 MongoDB steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON: single operation object or array of operations           |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+mongodb://user:password@host:port/database?authSource=admin
+mongodb+srv://user:password@cluster.example.mongodb.net/database   (SRV seedlist, e.g. Atlas)
+```
+
+- `mongodb://` for a standard host:port connection.
+- `mongodb+srv://` for DNS SRV seedlists (MongoDB Atlas). The driver resolves the seedlist and enables TLS automatically; do not add a port.
+- The default database comes from the URL path; override per operation with a `database` field in the body.
+- Common query params: `authSource` (auth database, usually `admin` for root users), `replicaSet`, `tls`, `retryWrites`.
+- Special characters in the username or password are URL-encoded automatically before the driver parses the string.
+
+### Body Format
+
+JSON string with `operation` (required) and `collection` (required for all operations except `listCollections`). Bodies are parsed as MongoDB Extended JSON, so `{ "$oid": "..." }` becomes an `ObjectId` and `{ "$date": "..." }` becomes a `Date`:
+
+```json
+{
+  "collection": "orders",
+  "operation": "find",
+  "filter": { "_id": { "$oid": "652c1f77bcf86cd799439011" } }
+}
+```
+
+For several operations in one step, pass an array (executed in order, results returned as an array):
+
+```json
+[
+  { "collection": "orders", "operation": "countDocuments", "filter": { "status": "paid" } },
+  {
+    "collection": "orders",
+    "operation": "find",
+    "filter": { "status": "paid" },
+    "options": { "limit": 10 }
+  }
+]
+```
+
+### Supported Operations
+
+| Operation                                                     | Required fields                                   | Returns                                        |
+| ------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
+| `find`                                                        | `collection`                                      | array of documents                             |
+| `findOne`                                                     | `collection`                                      | a document or `null`                           |
+| `aggregate`                                                   | `collection`, `pipeline`                          | array of documents                             |
+| `countDocuments`                                              | `collection`                                      | number                                         |
+| `estimatedDocumentCount`                                      | `collection`                                      | number                                         |
+| `distinct`                                                    | `collection`, `field`                             | array of values                                |
+| `listCollections`                                             | —                                                 | array of collection info                       |
+| `insertOne`                                                   | `collection`, `document`                          | `{ acknowledged, insertedId }`                 |
+| `insertMany`                                                  | `collection`, `documents`                         | `{ acknowledged, insertedCount, insertedIds }` |
+| `updateOne` / `updateMany`                                    | `collection`, `filter`, `update`                  | `{ matchedCount, modifiedCount, upsertedId }`  |
+| `replaceOne`                                                  | `collection`, `filter`, `replacement`             | update result                                  |
+| `deleteOne` / `deleteMany`                                    | `collection`, `filter`                            | `{ acknowledged, deletedCount }`               |
+| `findOneAndUpdate` / `findOneAndReplace` / `findOneAndDelete` | `collection`, `filter` (+ `update`/`replacement`) | the affected document                          |
+| `bulkWrite`                                                   | `collection`, `operations`                        | bulk write result                              |
+
+`filter`, `pipeline`, `document`, `update`, `replacement`, and driver `options` (e.g. `limit`, `skip`, `sort`, `projection`, `upsert`) are passed straight through to the driver.
+
+Dynamic values with variables:
+
+```json
+{
+  "collection": "users",
+  "operation": "find",
+  "filter": { "orgId": "<<(sourceData) => sourceData.orgId>>" }
+}
+```
+
+## Authentication
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically. Root/admin users almost always need `?authSource=admin`.
+
+```
+mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin
+```
+
+## MongoDB Runtime Details
+
+### Return Values
+
+Documents are returned as Extended JSON (relaxed): an `ObjectId` becomes `{ "$oid": "..." }` and a `Date` becomes `{ "$date": "..." }`. Query those values back with the same form. A single operation returns its result directly; an array of operations returns an array of results in order.
+
+### Connection Management
+
+- Clients are reused per connection string within a run and closed after completion.
+- TLS is automatic for `mongodb+srv://` and when the connection string sets `tls=true`.
+- Connection timeout defaults to 30 seconds; operation/socket timeout follows the system/protocol timeout.
+
+### Retry Behavior
+
+Default retries come from server config. On final failure, the error includes the failing operation name.
+
+## Common Pitfalls
+
+- Omitting `?authSource=admin` when authenticating as a root user — auth fails with "Authentication failed".
+- Adding a port to a `mongodb+srv://` URL — SRV connection strings must not include a port.
+- Passing an `_id` as a plain string when the document stores an `ObjectId` — wrap it as `{ "$oid": "..." }` so it matches.
+- Putting `limit`/`sort`/`projection` at the top level — they belong inside `options`.
+- Accessing the step result directly instead of via `.data` — MongoDB results follow the same envelope as all steps: `sourceData.stepId.data`.
+
+## Error Recovery
+
+When a MongoDB step fails:
+
+1. **Read the error message** — superglue includes the operation name in the error. Check for unknown operations, missing required fields (`filter`, `update`, `pipeline`), or malformed Extended JSON.
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test with a `listCollections` operation via `sg system call`.
+3. **Check auth source** — "Authentication failed" usually means a missing or wrong `authSource`. Root users authenticate against `admin`.
+4. **Check connectivity** — connection refused or server-selection timeouts mean the host is unreachable, the SRV record can't resolve, or an IP allowlist (Atlas) is blocking you. `mongodb+srv://` requires outbound DNS.
+5. **Check the operation shape** — read operations (`find`, `countDocuments`, `distinct`) never mutate; write operations require their specific fields. `aggregate` is read-only unless its pipeline contains a `$out` or `$merge` stage, which writes results back to a collection. Confirm `filter`/`update`/`pipeline` are objects/arrays, not strings.

package/skills/superglue/references/superglue-info.md

@@ -16,9 +16,17 @@ If the user is asking general questions (not building):
 - Product/features → https://docs.superglue.cloud/getting-started/introduction
 - Open-source/code → https://github.com/superglue-ai/superglue
 
+## Cloud Usage Tiers
+
+- Cloud tiers are **Trial**, **Pro**, **Team**, and **Enterprise**; billing-enabled apps expose upgrades through the in-app **Upgrade Plan** button, not a separate Billing page.
+- **Trial** includes 1M input tokens and 100 runs lifetime; **Pro** is €59/$69 per month with 3M input tokens/user/month and 3,000 runs/user/month.
+- **Team** is €99/$119 per seat/month with 5M input tokens/user/month and 5,000 runs/user/month; Team includes organization management, activity tracking, and custom MCP servers.
+- **Enterprise** is custom-priced with unlimited usage limits by default, enterprise access controls, and self-hosting/on-prem options.
+- These cloud tier details do not apply to self-hosted or enterprise deployment setups.
+
 ## Authentication
 
-API, SDK, CLI, and webhook usage require an **API key**. MCP clients can use OAuth when supported, or API keys for non-interactive setup. Self-hosted deployments also need the API/MCP endpoint URL. There are no workspace IDs, project IDs, or other identifiers.
+API, SDK, and webhook usage require an **API key**. The CLI should use browser OAuth via `sg login`; headless/API-key CLI auth is available through environment variables, flags, or `config.json` for CI and legacy automation. MCP clients can use OAuth when supported, or API keys for non-interactive setup. Self-hosted deployments also need the API/MCP endpoint URL. There are no workspace IDs, project IDs, or other identifiers.
 
 MCP authentication is separate from API/SDK/CLI setup. For MCP OAuth, dynamic client registration, Langdock setup, and named server permissions, use the MCP documentation.
 
@@ -44,6 +52,10 @@ OAuth flows require a callback URL: `{appEndpoint}/api/auth/callback`
 
 On superglue Cloud, the app endpoint is `https://app.superglue.cloud`. Self-hosted and enterprise deployments use their own app URL. If a user doesn't know their endpoints, they can check the browser URL bar for the app endpoint and deployment configuration for the API endpoint.
 
+### Cloud Networking
+
+If a customer's system requires IP allowlisting for firewall rules, security groups, or vendor access controls, superglue Cloud outbound requests come from `34.234.12.178` and `18.198.191.215`. These IPs apply to superglue Cloud only; self-hosted and enterprise deployments use deployment-specific networking.
+
 ## Web App UI Layout
 
 Use this section as the source of truth for high-level web app navigation. Do not invent UI locations that are not listed here.
@@ -53,7 +65,7 @@ The persistent left sidebar contains these top-level items:
 - **Agent** (`/`) — primary AI chat assistant for building and debugging tools and systems.
 - **Tools** (`/tools`, detail at `/tools/{toolId}`) — saved tools; opens the tool playground for editing, testing, and running.
 - **Systems** (`/systems`, detail at `/systems/{systemId}`) — connected external systems with credentials and documentation.
-- **My Credentials** (`/credentials`) — personal credential management for systems configured to use user-owned credentials. Admins and members open it inside the normal app shell from the sidebar. API keys are not managed here.
+- **Credentials** (`/credentials`) — manage the credentials you own for each system, and the credentials shared with you. Admins and members open it inside the normal app shell from the sidebar. API keys are not managed here.
 - **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
 - **Control Panel** (`/admin`) — expandable group for organization and account administration:
   - **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
@@ -63,9 +75,9 @@ The persistent left sidebar contains these top-level items:
   - **Organization** (`/organization`) — visible on paid tiers as a standalone page without tabs. It shows members, invitations, role assignment, and member-management actions; management actions are admin-gated.
   - **MCP Servers** (`/admin?view=mcp-servers`) — manage and export named MCP server endpoints. Use the MCP documentation for behavior, permissions, and client setup.
 
-Below the navigation, the sidebar shows the current organization menu. Opening it shows the signed-in user email and menu items for **API Keys** (`/api-keys`), **Settings** (`/settings`, admin-only), **Switch organization**, and **Sign Out**. Depending on the plan, the sidebar also shows **Upgrade Plan** or **Subscription**; Subscription opens the external Stripe billing portal. There is no separate in-app Billing page.
+Below the navigation, the sidebar shows the current organization menu. Opening it shows the signed-in user email and menu items for **API Keys** (`/api-keys`), **Settings** (`/settings`, admin-only), **Switch organization**, and **Sign Out**. When billing is enabled, the sidebar also shows **Upgrade Plan** for non-enterprise organizations; it opens the in-app upgrade flow. There is no separate in-app Billing page.
 
-**API Keys** (`/api-keys`) is a standalone page with a simple own-key editor for superglue API keys used by API, SDK, CLI, webhook, and non-OAuth MCP clients. Org users can create, copy, and delete their own keys.
+**API Keys** (`/api-keys`) is a standalone page with a simple own-key editor for superglue API keys used by API, SDK, CLI headless/API-key auth, webhook, and non-OAuth MCP clients. Org users can create, copy, and delete their own keys.
 
 **Settings** (`/settings`) is an admin-only standalone page with distinct sections:
 
@@ -98,7 +110,8 @@ Steps are routed to execution strategies by protocol (first match wins):
 3. PostgreSQL → URL starts with `postgres://` or `postgresql://`
 4. MSSQL/Azure SQL → URL starts with `mssql://` or `sqlserver://`
 5. Redis → URL starts with `redis://` or `rediss://`
-6. FTP/SFTP → URL starts with `ftp://`, `ftps://`, or `sftp://`
-7. SMB → URL starts with `smb://`
+6. MongoDB → URL starts with `mongodb://` or `mongodb+srv://`
+7. FTP/SFTP → URL starts with `ftp://`, `ftps://`, or `sftp://`
+8. SMB → URL starts with `smb://`
 
 All user-provided JS (data selectors, transforms, stop conditions) runs in an isolated Deno sandbox.