@synap-core/workspace-templates 0.11.0 → 0.23.0

package/capabilities/stripe.capability.json

@@ -0,0 +1,420 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "stripe",
+    "name": "Stripe — Payments & Billing",
+    "description": "Read your Stripe account: list customers, invoices, subscriptions, charges, products and payouts, and read your current balance. Read-only by design — it cannot move money. Needs a Stripe RESTRICTED read-only key, never a full secret key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "stripe",
+    "name": "Stripe — Payments & Billing",
+    "description": "READ-ONLY Stripe access for the user's OWN account (not Connect/marketplace). Authenticates with a Stripe RESTRICTED API key (rk_live_… / rk_test_…) resolved server-side from the vault (vault://stripe) and injected as `Authorization: Bearer <key>` against https://api.stripe.com. List verbs default their limit (20, max 100). Covers customers, charges, invoices, subscriptions, products, payouts and the account balance. This capability deliberately contains NO create/update/refund/cancel verbs — it can read money state but can never move it; a restricted key scoped to read-only (or read + the specific list resources) is the correct credential and a full sk_live secret key should NOT be used. PRECONDITION: a Stripe account with a RESTRICTED API key created in the Dashboard (Developers -> API keys -> Create restricted key); pass it at connect time, it is stored server-encrypted in the vault and never persisted in the template. All endpoints are GET and return data inline, so reads auto-run. NOTE: paths are absolute against baseUrl https://api.stripe.com; response-field shaping (snake_case keys, `.data[]` list envelopes) is verified against Stripe's published API reference (customers/charges/invoices/subscriptions/products/payouts/balance list+retrieve) rather than the live account, and Stripe applies the account's default API version when no `Stripe-Version` header is pinned — so a shape check at first run is prudent. Stripe's top-level list envelope carries `has_more` (there is no `total_count` on the top-level list object), which is surfaced as `hasMore`.",
+    "params": [
+      {
+        "name": "stripeApiKey",
+        "label": "Stripe restricted API key",
+        "type": "text",
+        "required": true,
+        "description": "A Stripe RESTRICTED API key (Developers -> API keys -> Create restricted key; starts with rk_live_ or rk_test_). Grant only Read (or the specific list/read resources) — never use a full sk_live secret key. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "stripe",
+        "name": "{{name}} Stripe restricted API key",
+        "value": "{{stripeApiKey}}",
+        "type": "api_key",
+        "service": "stripe",
+        "description": "Stripe restricted API key for the stripe connector. Resolved as vault://<id> at apply time and injected as `Authorization: Bearer <key>` against https://api.stripe.com."
+      }
+    ],
+    "tools": [
+      {
+        "name": "stripe",
+        "kind": "provider",
+        "description": "Authenticated READ access to the user's own Stripe REST API (https://api.stripe.com). credentialRef vault://stripe resolves the user's restricted key from the vault, and the dispatcher injects it as `Authorization: Bearer <key>` (Stripe accepts Bearer auth as well as Basic) into a fixed host — a call-time path can never redirect the credentialed request elsewhere. Its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "stripe",
+        "executor": "is-agent",
+        "config": {
+          "serviceId": "stripe",
+          "baseUrl": "https://api.stripe.com",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "stripe_list_customers",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe customers, most recently created first. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/customers",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "customers",
+            "item": {
+              "id": "id",
+              "name": "name",
+              "email": "email",
+              "created": "created",
+              "currency": "currency",
+              "description": "description",
+              "delinquent": "delinquent"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_get_customer",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Gets one Stripe customer by id. Args: { customerId: string (a cus_… id) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "customerId": "string"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/customers/{{customerId}}",
+          "paramMapping": {
+            "customerId": {
+              "required": true,
+              "encode": "uri"
+            }
+          },
+          "responseShape": {
+            "scalar": {
+              "id": "id",
+              "name": "name",
+              "email": "email",
+              "created": "created",
+              "currency": "currency",
+              "description": "description",
+              "delinquent": "delinquent",
+              "balance": "balance"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_list_charges",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe charges (payments), most recent first. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/charges",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "charges",
+            "item": {
+              "id": "id",
+              "amount": "amount",
+              "currency": "currency",
+              "status": "status",
+              "paid": "paid",
+              "refunded": "refunded",
+              "created": "created",
+              "description": "description",
+              "customer": "customer",
+              "receiptUrl": "receipt_url"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_list_invoices",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe invoices, most recently created first. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/invoices",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "invoices",
+            "item": {
+              "id": "id",
+              "number": "number",
+              "customer": "customer",
+              "customerEmail": "customer_email",
+              "status": "status",
+              "currency": "currency",
+              "amountDue": "amount_due",
+              "amountPaid": "amount_paid",
+              "created": "created",
+              "dueDate": "due_date",
+              "hostedInvoiceUrl": "hosted_invoice_url",
+              "invoicePdf": "invoice_pdf"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_list_subscriptions",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe subscriptions. Stripe returns only non-canceled subscriptions by default; canceled ones are omitted unless a status filter is passed. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/subscriptions",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "subscriptions",
+            "item": {
+              "id": "id",
+              "customer": "customer",
+              "status": "status",
+              "currency": "currency",
+              "created": "created",
+              "latestInvoice": "latest_invoice",
+              "cancelAtPeriodEnd": "cancel_at_period_end"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_list_products",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe products, most recently created first. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/products",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "products",
+            "item": {
+              "id": "id",
+              "name": "name",
+              "active": "active",
+              "description": "description",
+              "created": "created",
+              "updated": "updated",
+              "defaultPrice": "default_price"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_list_payouts",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the user's Stripe payouts to bank accounts, most recently created first. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/payouts",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "payouts",
+            "item": {
+              "id": "id",
+              "amount": "amount",
+              "currency": "currency",
+              "status": "status",
+              "created": "created",
+              "arrivalDate": "arrival_date",
+              "description": "description",
+              "method": "method",
+              "type": "type"
+            },
+            "scalar": {
+              "count": "@count",
+              "hasMore": "has_more"
+            }
+          }
+        }
+      },
+      {
+        "name": "stripe_get_balance",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Gets the account's current Stripe balance: `available` and `pending` are per-currency lists of { amount, currency, source_types }, plus any connect_reserved. No args.",
+        "requires": [
+          "stripe"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {},
+        "providerSpec": {
+          "tool": "stripe",
+          "method": "GET",
+          "pathTemplate": "/v1/balance",
+          "responseShape": {
+            "scalar": {
+              "object": "object",
+              "livemode": "livemode",
+              "available": "available",
+              "pending": "pending",
+              "connectReserved": "connect_reserved"
+            }
+          }
+        }
+      }
+    ],
+    "provides": [
+      "list_records",
+      "fetch_record"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/telegram-bridge.capability.json

@@ -0,0 +1,56 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "telegram-bridge",
+    "name": "Telegram Bridge",
+    "description": "Two-way Telegram messaging with clients: group messages arrive in each client's channel in Synap, and replies go back through the bridge. Needs a Telegram bot token and the Synap messaging bridge set up with it.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "telegram-bridge",
+    "name": "Telegram Bridge",
+    "description": "Telegram two-way messaging via an EXTERNAL bridge gateway (the Telegram/Discord/WhatsApp bridge worker that lives OUTSIDE this repo). This template represents the bridge connection: it stores the bridge bot token in the vault and registers one external tool whose credentialRef is remapped to the runtime vault://<id> at apply time. Inbound Telegram messages are delivered by the bridge into the client's entity-bound channel (inbound-recorder substrate, shipped); outbound sends are dispatched by the bridge against this connection. PRECONDITION: a Telegram bot (BotFather) added to the target groups, and the external bridge gateway configured with this same token. Pass the bot token as telegramBotToken. Outbound send code skills are NOT seeded here — the bridge owns delivery; this template establishes the connection + auth.",
+    "metadata": {
+      "mode": "standing"
+    },
+    "params": [
+      {
+        "name": "telegramBotToken",
+        "label": "Telegram bridge bot token",
+        "type": "text",
+        "required": true,
+        "description": "The Telegram bot token (BotFather) used by the external bridge gateway. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "telegramBotTokenSecret",
+        "name": "{{name}} Telegram bridge bot token",
+        "value": "{{telegramBotToken}}",
+        "type": "api_key",
+        "description": "Telegram bot token for the external bridge gateway (telegram connector)."
+      }
+    ],
+    "tools": [
+      {
+        "name": "telegram",
+        "kind": "external",
+        "description": "Telegram messaging via the external bridge gateway. The bridge holds the connection; this tool's credentialRef is remapped to the runtime vault://<id> at apply time so the bridge token resolves server-side. Inbound is delivered by the bridge into the client's channel; outbound sends are dispatched by the bridge.",
+        "credentialRef": "telegramBotTokenSecret",
+        "executor": "external-agent",
+        "config": {
+          "transport": "bridge",
+          "externalSource": "telegram"
+        }
+      }
+    ],
+    "skills": [],
+    "provides": []
+  },
+  "dependencies": []
+}

package/capabilities/treg.capability.json

@@ -0,0 +1,102 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "treg",
+    "name": "treg — Tool catalog",
+    "description": "Find a provider endpoint on treg.to by the job you need, then run it with your treg token. Search is free and shows the price. Running an endpoint spends prepaid balance and waits for your approval. Sign up at treg.to yourself and paste one token.",
+    "tags": [
+      "capability",
+      "search_external",
+      "run_external_job"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "treg",
+    "name": "treg — Tool catalog",
+    "description": "Call provider endpoints through treg (https://treg.to) with one token the user pastes. The user signs up at https://treg.to themselves; Synap does not host signup and this is not a messaging bridge. Verified against https://treg.to/docs and https://treg.to/llms.txt (2026-09-29): base https://treg.to, auth header X-Treg-Token with an empty prefix. Do not send the token as Authorization: Bearer — REST ignores Bearer (401) and /call/ would relay that header to the provider. GET /catalog/search?q= finds endpoints and already includes price (cost.usd). GET /call/{endpoint_id} with a query string runs a catalog endpoint and spends prepaid balance, so that verb is not read-only. A catalog entry whose input is a JSON body (method POST) is a different shape; this pack's call verb sends the query object as the query string only.",
+    "params": [
+      {
+        "name": "tregToken",
+        "label": "treg token",
+        "type": "text",
+        "required": true,
+        "description": "Token from the user's own treg.to account (https://treg.to). Sent as the X-Treg-Token header, not as Authorization. Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "tregTokenSecret",
+        "name": "{{name}} treg token",
+        "value": "{{tregToken}}",
+        "type": "api_key",
+        "description": "treg token for the treg_api connector. The applier remaps this template-local ref to vault://<id>."
+      }
+    ],
+    "tools": [
+      {
+        "name": "treg_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to treg (https://treg.to). The applier injects the vaulted token into the X-Treg-Token header with an empty prefix — treg REST does not use Authorization: Bearer. credentialRef is remapped to vault://<id> at apply.",
+        "credentialRef": "tregTokenSecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://treg.to",
+          "auth": {
+            "in": "header",
+            "name": "X-Treg-Token",
+            "prefix": ""
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "treg_search",
+        "intent": "search_external",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Finds treg catalog endpoints for a job. Read-only: GET /catalog/search (the catalog does not spend balance). Returns at most 5 rows of { id, name, price }, where price is cost.usd (else cost.value) from the search payload. Args: { query: string }.",
+        "requires": [
+          "treg_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "query": "string"
+        },
+        "code": "// Catalog search. Executor wraps this body as (async (args, context) => { <code> }).\n// callProvider('treg_api','GET', path) injects X-Treg-Token. GET /catalog/search\n// is open and already includes price on each result (cost.usd) — no second get.\nconst query = String(args?.query ?? '').trim();\nif (!query) throw new Error('treg_search: query is required');\n\nconst res = await callProvider('treg_api', 'GET', '/catalog/search?q=' + encodeURIComponent(query) + '&limit=5');\nconst payload = res?.body ?? res;\nconst rows = Array.isArray(payload?.results) ? payload.results : [];\nconst results = rows.slice(0, 5).map((r) => {\n  const cost = r?.cost;\n  let price = null;\n  if (cost && typeof cost === 'object') {\n    if (typeof cost.usd === 'number') price = cost.usd;\n    else if (typeof cost.value === 'number') price = cost.value;\n  }\n  return { id: r?.id ?? null, name: r?.name ?? null, price };\n});\nreturn { query, count: results.length, results };",
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "treg_call",
+        "intent": "run_external_job",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Runs one treg catalog endpoint and spends prepaid balance. Not read-only: the run is proposal-gated. HTTP shape verified at https://treg.to/docs: GET /call/{endpoint_id} with the query object as the query string (example: /call/tikhub.tiktok.user.profile?uniqueId=tiktok). Does not send a JSON body and does not poll async generation tasks. Returns the upstream body, plus chargedMicro (X-Treg-Cost-Micro, else _treg.charged_micro) and callId (X-Treg-Call-Id) when the response has them. Args: { endpointId: string, query?: object }.",
+        "requires": [
+          "treg_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "endpointId": "string",
+          "query": "object?"
+        },
+        "code": "// Catalog call. Executor wraps this body as (async (args, context) => { <code> }).\n// callProvider('treg_api','GET', path) injects X-Treg-Token (empty prefix, not Bearer).\n// Docs: GET https://treg.to/call/{endpoint_id}?... — method and query string pass through.\n// This verb is not metadata.readOnly, so the skill gate proposes before the spend.\nconst endpointId = String(args?.endpointId ?? '').trim();\nif (!endpointId) throw new Error('treg_call: endpointId is required');\nif (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(endpointId)) {\n  throw new Error('treg_call: endpointId must be a catalog id, not a URL');\n}\n\nlet qs = '';\nif (args?.query !== undefined && args?.query !== null) {\n  if (typeof args.query !== 'object' || Array.isArray(args.query)) {\n    throw new Error('treg_call: query must be an object of parameters');\n  }\n  const parts = [];\n  for (const [key, value] of Object.entries(args.query)) {\n    if (value === undefined || value === null) continue;\n    const encoded = typeof value === 'object' ? JSON.stringify(value) : String(value);\n    parts.push(encodeURIComponent(key) + '=' + encodeURIComponent(encoded));\n  }\n  qs = parts.join('&');\n}\n\nconst path = '/call/' + encodeURIComponent(endpointId) + (qs ? '?' + qs : '');\nconst res = await callProvider('treg_api', 'GET', path);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, endpointId };\n}\nconst payload = res?.body !== undefined ? res.body : res;\nconst headers = res?.headers && typeof res.headers === 'object' ? res.headers : {};\nconst header = (name) => {\n  const want = name.toLowerCase();\n  for (const [k, v] of Object.entries(headers)) {\n    if (String(k).toLowerCase() === want && v != null) return String(v);\n  }\n  return null;\n};\nconst costHeader = header('x-treg-cost-micro');\nconst chargedFromHeader = costHeader != null && /^-?\\d+$/.test(costHeader) ? Number(costHeader) : null;\nconst tregMeta = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload._treg : null;\nconst chargedFromBody = tregMeta && typeof tregMeta.charged_micro === 'number' ? tregMeta.charged_micro : null;\nconst chargedMicro = chargedFromHeader != null ? chargedFromHeader : chargedFromBody;\nconst callId = header('x-treg-call-id');\nconst out = { endpointId, status: res?.status ?? null, body: payload };\nif (chargedMicro != null) out.chargedMicro = chargedMicro;\nif (callId) out.callId = callId;\nreturn out;",
+        "metadata": {
+          "verbType": "write"
+        }
+      }
+    ],
+    "provides": [
+      "search_external",
+      "run_external_job"
+    ]
+  },
+  "dependencies": []
+}