@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/internal/catalog/comms.js

@@ -0,0 +1,520 @@
+export const COMMS = {
+    postmark: {
+        mode: "api_key",
+        label: "Postmark",
+        description: "Transactional email: single, batch and templated messages from one Postmark server.",
+        auth: {
+            kind: "header",
+            secret: "POSTMARK_API_TOKEN",
+            header: "X-Postmark-Server-Token",
+        },
+        docs: "https://postmarkapp.com/support/article/1008-what-are-the-account-and-server-api-tokens",
+        api: "https://postmarkapp.com/developer/api/overview",
+        hosts: ["api.postmarkapp.com"],
+        data: "account",
+        access: ["write"],
+        readMethods: [],
+        writeMethods: ["POST"],
+        accountWidePaths: [
+            ["server"],
+            ["servers"],
+            ["domains"],
+            ["senders"],
+            ["webhooks"],
+            ["message-streams"],
+            ["triggers"],
+            ["data-removals"],
+        ],
+        hint: "A Server API token from the API Tokens tab of the Postmark server the app sends from; the Gateway sends it in the X-Postmark-Server-Token header.",
+        secrets: [
+            {
+                name: "POSTMARK_API_TOKEN",
+                hint: "A Server API token from the server's API Tokens tab, never the Account API token.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/server",
+            expect: [200],
+            free: true,
+            note: "Returns the server's settings; account-wide, so run it from a terminal.",
+        },
+        example: "send a password reset email",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["email", "transactional"],
+    },
+    sendgrid: {
+        mode: "api_key",
+        label: "SendGrid",
+        description: "Twilio SendGrid email: send transactional and marketing mail through the v3 Mail Send API.",
+        auth: {
+            kind: "bearer",
+            secret: "SENDGRID_API_KEY",
+        },
+        docs: "https://app.sendgrid.com/settings/api_keys",
+        api: "https://www.twilio.com/docs/sendgrid/api-reference",
+        hosts: ["api.sendgrid.com", "api.eu.sendgrid.com"],
+        data: "account",
+        access: ["write"],
+        readMethods: [],
+        writeMethods: ["POST"],
+        accountWidePaths: [
+            ["api_keys"],
+            ["scopes"],
+            ["user"],
+            ["subusers"],
+            ["teammates"],
+            ["sso"],
+            ["access_settings"],
+            ["whitelabel"],
+            ["ips"],
+            ["send_ips"],
+            ["partners"],
+            ["partner_settings"],
+            ["alerts"],
+            ["mail_settings"],
+            ["tracking_settings"],
+            ["verified_senders"],
+            ["senders"],
+            ["marketing", "integrations"],
+            ["recipients", "erasejob"],
+        ],
+        hint: "An API key from Settings > API Keys in SendGrid, sent as a bearer token; Custom Access with Mail Send alone is enough to send. EU regional subusers call api.eu.sendgrid.com.",
+        secrets: [
+            {
+                name: "SENDGRID_API_KEY",
+                hint: "A Custom Access key with Mail Send only, never a Full Access key.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/v3/scopes",
+            expect: [200],
+            free: true,
+            note: "Lists the key's own scopes (the docs don't say whether a Mail-Send-only key may call it); account-wide, so run it from a terminal.",
+        },
+        rate: {
+            note: "Each endpoint has its own limit; answers carry X-RateLimit-Limit, -Remaining and -Reset.",
+        },
+        example: "send an order confirmation email",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["email", "transactional", "marketing"],
+    },
+    // A Standard or Restricted API key (SID as the Basic username, its secret as the password), never the Auth Token: with it a write grant could close the account.
+    twilio: {
+        mode: "api_key",
+        label: "Twilio",
+        description: "SMS, MMS and voice: send text messages and place calls from your Twilio numbers.",
+        auth: {
+            kind: "basic",
+            secret: "TWILIO_API_SECRET",
+            as: "password",
+            user: {
+                secret: "TWILIO_API_KEY",
+            },
+        },
+        docs: "https://www.twilio.com/docs/iam/api-keys/keys-in-console",
+        api: "https://www.twilio.com/docs/usage/requests-to-twilio",
+        hosts: ["api.twilio.com"],
+        data: "account",
+        access: ["write"],
+        readMethods: [],
+        writeMethods: ["POST"],
+        accountWidePaths: [
+            ["keys"],
+            ["signingkeys"],
+            ["incomingphonenumbers"],
+            ["outgoingcallerids"],
+            ["applications"],
+            ["connectapps"],
+            ["authorizedconnectapps"],
+            ["addresses"],
+            ["sip"],
+            ["usage"],
+            ["balance"],
+        ],
+        hint: "A Standard or Restricted API key from Account settings > API keys & auth tokens in the Twilio Console, sent as HTTP Basic (the key's SID and secret); a Standard key can't reach the Accounts or Keys resources. Every path names the account, so the app puts its Account SID in it: /2010-04-01/Accounts/<Account SID>/Messages.json, with a form-encoded body.",
+        secrets: [
+            {
+                name: "TWILIO_API_SECRET",
+                hint: "The API key's secret, shown once when the key is created.",
+            },
+            {
+                name: "TWILIO_API_KEY",
+                hint: "The SID of a Standard or Restricted API key, never a Main key or the Auth Token.",
+            },
+        ],
+        example: "text a reminder to a customer's phone number",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["sms", "voice", "messaging"],
+    },
+    intercom: {
+        mode: "api_key",
+        label: "Intercom",
+        description: "Customer messaging: contacts, companies, conversations, tickets and help center articles.",
+        auth: {
+            kind: "bearer",
+            secret: "INTERCOM_API_TOKEN",
+        },
+        docs: "https://app.intercom.com/a/apps/_/developer-hub",
+        api: "https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis",
+        hosts: ["api.intercom.io", "api.eu.intercom.io", "api.au.intercom.io"],
+        data: "account",
+        access: ["read", "write"],
+        readMethods: ["GET", "HEAD"],
+        writeMethods: ["POST", "PUT", "PATCH", "DELETE"],
+        accountWidePaths: [
+            ["me"],
+            ["admins"],
+            ["teams"],
+            ["export"],
+            ["download"],
+            ["ip_allowlist"],
+        ],
+        hint: "The Access Token of a private app in your workspace's Developer Hub, sent as a bearer token. Searching contacts, conversations or tickets is a POST, so an app that searches asks for write.",
+        secrets: [
+            {
+                name: "INTERCOM_API_TOKEN",
+                hint: "The Access Token on your private app's Configure > Authentication page in the Developer Hub.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/me",
+            expect: [200],
+            free: true,
+            note: "Returns the admin behind the token; account-wide, so run it from a terminal.",
+        },
+        rate: {
+            perMinute: 10000,
+            note: "Per workspace, shared by its private apps; 25,000 a minute across all apps; counted in 10-second windows.",
+        },
+        example: "list the latest open conversations",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["support", "crm", "messaging"],
+    },
+    crisp: {
+        mode: "api_key",
+        label: "Crisp",
+        description: "Customer chat: conversations, messages, people and visitors of one Crisp workspace.",
+        auth: {
+            kind: "basic",
+            secret: "CRISP_API_KEY",
+            as: "password",
+            user: {
+                secret: "CRISP_API_IDENTIFIER",
+            },
+        },
+        docs: "https://docs.crisp.chat/guides/rest-api/authentication/website-token/",
+        api: "https://docs.crisp.chat/references/rest-api/v1/",
+        hosts: ["api.crisp.chat"],
+        data: "account",
+        access: ["read", "write"],
+        readMethods: ["GET", "HEAD"],
+        writeMethods: ["POST", "PUT", "PATCH", "DELETE"],
+        accountWidePaths: [
+            ["operators"],
+            ["operator"],
+            ["teams"],
+            ["team"],
+            ["settings"],
+            ["verify"],
+            ["audit"],
+            ["plans"],
+            ["plugins"],
+            ["plugin"],
+            ["connect"],
+        ],
+        hint: "A website token, which the workspace owner generates under Settings > Workspace Settings > Advanced configuration > API Token. The Gateway sends the identifier and key as HTTP Basic; the app sends X-Crisp-Tier: website on every call.",
+        secrets: [
+            {
+                name: "CRISP_API_KEY",
+                hint: "The token's key, shown once when the workspace owner generates it.",
+            },
+            {
+                name: "CRISP_API_IDENTIFIER",
+                hint: "The token's identifier, shown beside the key.",
+            },
+        ],
+        rate: {
+            perDay: 10000,
+            note: "The website token's daily quota.",
+        },
+        example: "list the latest chat conversations on my website",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["support", "chat", "messaging"],
+    },
+    // Added 2026-10-30 from docs.granola.ai and its OpenAPI spec. Granola's
+    // hosted MCP server (mcp.granola.ai/mcp) is OAuth only, which the Gateway
+    // can't sign in to yet; this is its API-key REST API.
+    granola: {
+        mode: "api_key",
+        label: "Granola",
+        description: "Meeting notes: list, search and read notes with their AI summaries, transcripts, folders and spaces.",
+        auth: { kind: "bearer", secret: "GRANOLA_API_KEY" },
+        docs: "https://docs.granola.ai/help-center/sharing/integrations/granola-api",
+        api: "https://docs.granola.ai/introduction",
+        hosts: ["public-api.granola.ai"],
+        data: "account",
+        access: ["read"],
+        // Searching notes is a POST that reads; with the paths below refused,
+        // it is the only POST an app can reach.
+        readMethods: ["GET", "POST"],
+        // Workspace administration: the audit log, webhook endpoints (which
+        // would send every note to a URL of the app's choosing) and legal holds.
+        accountWidePaths: [["audit"], ["webhook-endpoints"], ["legal-holds"]],
+        hint: "An API key (grn_...) from the Granola desktop app's Settings > Connectors > API keys, on a Business or Enterprise plan; the Gateway sends it as a bearer token. It reads only the notes its scopes allow.",
+        secrets: [
+            {
+                name: "GRANOLA_API_KEY",
+                hint: "A personal or workspace API key (grn_...), with only the note scopes the apps need.",
+            },
+        ],
+        rate: {
+            perSecond: 5,
+            note: "Bursts of 25 requests in 5 seconds; per user or per workspace, by the key's scope.",
+        },
+        smoke: {
+            method: "GET",
+            path: "/v1/notes?page_size=1",
+            expect: [200],
+            free: true,
+        },
+        example: "summarize what we decided in this week's customer calls",
+        verified: {
+            on: "2026-10-30",
+            how: "docs",
+        },
+        tags: ["meetings", "notes", "transcripts"],
+    },
+    linear: {
+        mode: "api_key",
+        label: "Linear",
+        description: "Issue tracking over GraphQL: issues, projects, cycles, comments and teams.",
+        auth: {
+            kind: "header",
+            secret: "LINEAR_API_KEY",
+            header: "Authorization",
+        },
+        docs: "https://linear.app/settings/account/security",
+        api: "https://linear.app/developers/graphql",
+        hosts: ["api.linear.app"],
+        data: "account",
+        access: ["write"],
+        readMethods: [],
+        writeMethods: ["POST"],
+        accountWidePaths: [],
+        hint: "A personal API key from Settings > Account > Security & access; the Gateway sends it as the Authorization header with no Bearer word. Every call is a POST to /graphql, queries included, so the app asks for write.",
+        secrets: [
+            {
+                name: "LINEAR_API_KEY",
+                hint: "A personal API key, restricted to the permissions and teams the app needs.",
+            },
+        ],
+        rate: {
+            note: "2,500 requests and 3,000,000 complexity points an hour per API key.",
+        },
+        example: "create an issue for this bug in the Engineering team",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["issues", "project-management", "graphql"],
+    },
+    github: {
+        mode: "api_key",
+        label: "GitHub",
+        description: "Code hosting: repositories, issues, pull requests, Actions and releases through the REST API.",
+        auth: {
+            kind: "bearer",
+            secret: "GITHUB_API_TOKEN",
+        },
+        docs: "https://github.com/settings/personal-access-tokens/new",
+        api: "https://docs.github.com/en/rest",
+        hosts: ["api.github.com"],
+        data: "account",
+        access: ["read", "write"],
+        readMethods: ["GET", "HEAD"],
+        writeMethods: ["POST", "PUT", "PATCH", "DELETE"],
+        accountWidePaths: [
+            ["user", "email"],
+            ["user", "emails"],
+            ["user", "public_emails"],
+            ["user", "gpg_keys"],
+            ["user", "ssh_signing_keys"],
+            ["user", "social_accounts"],
+            ["keys"],
+            ["hooks"],
+            ["secrets"],
+            ["members"],
+            ["memberships"],
+            ["invitations"],
+            ["failed_invitations"],
+            ["collaborators"],
+            ["outside_collaborators"],
+            ["blocks"],
+            ["installations"],
+            ["personal-access-tokens"],
+            ["personal-access-token-requests"],
+            ["credential-authorizations"],
+            ["audit-log"],
+            ["billing"],
+        ],
+        hint: "A fine-grained personal access token from Settings > Developer settings, limited to one owner, the repositories the app needs and the least permissions; sent as a bearer token. GraphQL is a POST to /graphql, so it needs write.",
+        secrets: [
+            {
+                name: "GITHUB_API_TOKEN",
+                hint: "A fine-grained personal access token limited to the repositories and permissions the app needs.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/user",
+            expect: [200],
+            free: true,
+            note: "Returns the token's owner; 401 means the token is wrong.",
+        },
+        rate: {
+            note: "5,000 requests an hour per token; at most 100 concurrent requests and 900 points a minute across REST endpoints.",
+        },
+        example: "list the open pull requests in my repository",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["code", "git", "issues"],
+    },
+    gitlab: {
+        mode: "api_key",
+        label: "GitLab",
+        description: "Code hosting on GitLab.com: projects, issues, merge requests, pipelines and releases.",
+        auth: {
+            kind: "header",
+            secret: "GITLAB_API_TOKEN",
+            header: "PRIVATE-TOKEN",
+        },
+        docs: "https://gitlab.com/-/user_settings/personal_access_tokens",
+        api: "https://docs.gitlab.com/api/rest/",
+        hosts: ["gitlab.com"],
+        data: "account",
+        access: ["read", "write"],
+        readMethods: ["GET", "HEAD"],
+        writeMethods: ["POST", "PUT", "PATCH", "DELETE"],
+        accountWidePaths: [
+            ["user"],
+            ["personal_access_tokens"],
+            ["access_tokens"],
+            ["deploy_tokens"],
+            ["deploy_keys"],
+            ["project_deploy_keys"],
+            ["hooks"],
+            ["members"],
+            ["pending_members"],
+            ["billable_members"],
+            ["invitations"],
+            ["variables"],
+            ["audit_events"],
+        ],
+        hint: "A personal, project or group access token from GitLab.com, sent in the PRIVATE-TOKEN header; read_api is enough to read. Paths start with /api/v4. A self-managed GitLab needs its own registered provider.",
+        secrets: [
+            {
+                name: "GITLAB_API_TOKEN",
+                hint: "A personal, project or group access token with read_api, or api when the app writes.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/api/v4/personal_access_tokens/self",
+            expect: [200],
+            free: true,
+            note: "Describes a personal access token itself (401 when it is wrong or revoked); account-wide, so run it from a terminal.",
+        },
+        rate: {
+            perMinute: 2000,
+            note: "Authenticated API traffic per user on GitLab.com.",
+        },
+        example: "list the open merge requests in my project",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["code", "git", "ci"],
+    },
+    vercel: {
+        mode: "api_key",
+        label: "Vercel",
+        description: "Frontend hosting: projects, deployments, domains and logs through the Vercel REST API.",
+        auth: {
+            kind: "bearer",
+            secret: "VERCEL_API_TOKEN",
+        },
+        docs: "https://vercel.com/account/tokens",
+        api: "https://vercel.com/docs/rest-api",
+        hosts: ["api.vercel.com"],
+        data: "account",
+        access: ["read", "write"],
+        readMethods: ["GET", "HEAD"],
+        writeMethods: ["POST", "PUT", "PATCH", "DELETE"],
+        accountWidePaths: [
+            ["user"],
+            ["teams"],
+            ["members"],
+            ["organizations"],
+            ["access-groups"],
+            ["billing"],
+            ["webhooks"],
+            ["drains"],
+            ["env"],
+            ["v3", "events"],
+            ["v1", "events"],
+            ["v1", "integrations"],
+            ["installations"],
+            ["connect"],
+            ["kms"],
+            ["api-keys"],
+            ["ai-gateway"],
+            ["token"],
+            ["tokens"],
+            ["registrar"],
+            ["transfer-request"],
+        ],
+        hint: "An access token from your account's Tokens page, sent as a bearer token; scope it to one team or one project. A team- or project-scoped token needs no teamId parameter.",
+        secrets: [
+            {
+                name: "VERCEL_API_TOKEN",
+                hint: "An access token scoped to one team or one project, never Full Account.",
+            },
+        ],
+        smoke: {
+            method: "GET",
+            path: "/v10/projects",
+            expect: [200],
+            free: true,
+            note: "Lists the projects the token can reach.",
+        },
+        rate: {
+            note: "Limits are per action (deployments, domains, teams), listed on Vercel's limits page.",
+        },
+        example: "list the latest deployments of my project",
+        verified: {
+            on: "2026-10-25",
+            how: "docs",
+        },
+        tags: ["hosting", "deploy", "frontend"],
+    },
+};