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

package/dist/internal/capabilities.js

@@ -0,0 +1,1110 @@
+/**
+ * The built-in provider catalog: everything the gateway holds a credential
+ * for on apps' behalf (docs/capabilities.md,
+ * docs/design/2026-10-provider-registry.md), of four kinds, each an entry
+ * of data and nothing else, so a provider the catalog doesn't have can be
+ * registered on one gateway as a row of the same shape (./providerSpec.ts,
+ * ./providerRegistry.ts):
+ *
+ *  - `api_key`: a provider whose key the gateway holds. The operator sets
+ *    the key once on the gateway (`everyapp secret set <secret>`), an app lists the provider in its manifest's `capabilities`,
+ *    and the app calls the provider through the AppGateway binding
+ *    (`integrationFetch()`), so no app ever holds the key. `auth` says
+ *    where the key goes on the request ({@link ApiKeyAuth}).
+ *  - `ai`: an AI provider, reached under `providers` in the manifest and
+ *    `/api/ai/<id>` on the binding (`createGatewayFetch()`), with the AI
+ *    proxy's rules: inference routes only, the model allowlist, the usage
+ *    tap. Never a capability: its key would reach the account's credits
+ *    and keys on the same host.
+ *  - `oauth_client`: a provider's OAuth client (Google's, Microsoft's,
+ *    Slack's), held the same way. The gateway completes the token endpoint
+ *    calls only, putting the client on them; the app builds the authorize
+ *    URL from the public client id (`integrationStatus()`), sends people
+ *    back to a callback its manifest entry lists (`redirectPaths`), keeps
+ *    the user tokens and calls the provider's API with them itself. Other
+ *    providers' clients (GitHub, the social networks) are presets
+ *    (./oauthPresets.ts): rows only once an operator adds one. A client shared by apps
+ *    with different needs carries a `scopePolicy`: named scope sets an app
+ *    lists in its manifest entry's `scopes`, which ./oauthScopes.ts turns
+ *    into what the app may ask the provider for and what a token it is
+ *    handed may carry.
+ *  - `service`: something the gateway does itself, with no upstream host
+ *    an app names (sending email, listing the organization's members). An
+ *    app lists it the same way and calls its routes,
+ *    `/api/integrations/<id>/<route>`, through the SDK's own helper
+ *    (`sendEmail()`, `listMembers()`).
+ *
+ * The gateway enforces these definitions, the manifest validator checks
+ * `capabilities` against them, and the SDK reads them for its local-dev
+ * fallback, which calls the provider directly with a developer's own key.
+ * All three import them from here so they cannot drift.
+ */
+/** What `access: "write"` adds to a provider's read methods when its entry doesn't say. */
+export const DEFAULT_WRITE_METHODS = [
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+];
+import { CATALOG_ENTRIES } from "./catalog/index.js";
+export const CAPABILITIES = {
+    // The AI providers, in the order the AI proxy's table had them.
+    openai: {
+        mode: "ai",
+        label: "OpenAI",
+        description: "OpenAI's models: responses, chat, embeddings, audio, images.",
+        auth: { kind: "bearer", secret: "OPENAI_API_KEY" },
+        docs: "https://platform.openai.com/api-keys",
+        api: "https://platform.openai.com/docs/api-reference",
+        setup: "setup/openai.md",
+        origin: "https://api.openai.com",
+        inferenceRoutes: [
+            "/v1/responses",
+            "/v1/chat/completions",
+            "/v1/embeddings",
+            "/v1/audio/speech",
+            "/v1/audio/transcriptions",
+            "/v1/audio/translations",
+            "/v1/images/generations",
+            "/v1/images/edits",
+            "/v1/images/variations",
+        ],
+        unstoredRoutes: ["/v1/responses", "/v1/chat/completions"],
+        // More than inference needs both the operator (AI_PROXY_EXTRA_ROUTES)
+        // and the app's manifest (`ai.routes`): OpenAI paths only.
+        extraRoutes: true,
+        // Tool calling on chat completions needs `reasoning_effort: "none"`
+        // on the GPT-6 family (the responses route takes tools as it is).
+        chat: { path: "/v1/chat/completions", seedModel: "gpt-6-luna" },
+        embeddings: { path: "/v1/embeddings", seedModel: "text-embedding-3-small" },
+        // AI Gateway's OpenAI endpoint takes the path without `/v1`.
+        aig: { slug: "openai", trim: "/v1" },
+        hint: "A secret key from the API keys page; the Gateway puts it on every call as a bearer token.",
+        verified: { on: "2026-10-25", how: "live" },
+    },
+    // OpenAI-compatible, in front of many model providers. Usage (with cost)
+    // comes back in the response, so apps can meter their own spend.
+    openrouter: {
+        mode: "ai",
+        label: "OpenRouter",
+        description: "One key for many models, through OpenAI's API shape.",
+        auth: { kind: "bearer", secret: "OPENROUTER_API_KEY" },
+        docs: "https://openrouter.ai/settings/keys",
+        api: "https://openrouter.ai/docs",
+        setup: "setup/openrouter.md",
+        origin: "https://openrouter.ai",
+        inferenceRoutes: [
+            "/api/v1/chat/completions",
+            "/api/v1/completions",
+            "/api/v1/responses",
+            "/api/v1/embeddings",
+        ],
+        chat: {
+            path: "/api/v1/chat/completions",
+            seedModel: "anthropic/claude-haiku-5.5",
+        },
+        embeddings: {
+            path: "/api/v1/embeddings",
+            seedModel: "openai/text-embedding-3-small",
+        },
+        // AI Gateway's OpenRouter endpoint takes the path without `/api`.
+        aig: { slug: "openrouter", trim: "/api" },
+        hint: "An API key from OpenRouter's keys page; the Gateway puts it on every call as a bearer token.",
+        // Every answer's `usage.cost` is the call's price in USD, what
+        // OpenRouter charges the key: read off the tail with the tokens.
+        cost: {
+            unit: "token",
+            responseField: "usage.cost",
+            note: "The answer's usage.cost is the call's price in USD, per model.",
+        },
+        verified: { on: "2026-10-25", how: "live" },
+    },
+    // Workers AI's OpenAI-compatible REST API, in the gateway's own account
+    // (`/v1/run/...` and the native `/run/<model>` stay closed). Its chat
+    // streams send all-digit tokens as JSON numbers, which the gateway turns
+    // back into strings (normalizeWorkersAiResponse).
+    "workers-ai": {
+        mode: "ai",
+        label: "Workers AI",
+        description: "Cloudflare's models, in the Gateway's own account.",
+        auth: { kind: "bearer", secret: "WORKERS_AI_API_TOKEN" },
+        // A token from the "Workers AI" template (Read and Edit).
+        docs: "https://dash.cloudflare.com/profile/api-tokens",
+        api: "https://developers.cloudflare.com/workers-ai/",
+        setup: "setup/workers-ai.md",
+        origin: "https://api.cloudflare.com",
+        alsoNeeds: ["CLOUDFLARE_ACCOUNT_ID"],
+        basePath: "/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai",
+        inferenceRoutes: [
+            "/v1/chat/completions",
+            "/v1/embeddings",
+            "/v1/responses",
+        ],
+        normalize: "workers-ai",
+        chat: {
+            path: "/v1/chat/completions",
+            seedModel: "@cf/meta/llama-4-scout-17b-16e-instruct",
+        },
+        embeddings: { path: "/v1/embeddings", seedModel: "@cf/baai/bge-m3" },
+        // Workers AI's REST API is AI Gateway's own host: the URL stays and
+        // `cf-aig-gateway-id` names the gateway.
+        aig: { slug: "workers-ai", header: true },
+        hint: "A Cloudflare API token with Workers AI Read (the Workers AI page's prefilled token); the account is the Gateway's own.",
+        verified: { on: "2026-10-25", how: "live" },
+    },
+    // Cloudflare AI Gateway: a proxy in front of the other AI providers
+    // (logs, caching, rate limits, spend), with no models of its own. With
+    // AI_GATEWAY_ID set, every call to an `ai` entry that has an `aig` slug
+    // goes through it, the provider's own key still on the call; the
+    // gateway's own token is optional (an authenticated gateway requires
+    // it). Never listed under `providers`: it fronts the entries apps list.
+    "ai-gateway": {
+        mode: "ai",
+        kind: "proxy",
+        label: "Cloudflare AI Gateway",
+        description: "Cloudflare's proxy in front of the other AI providers: logs, caching, rate limits and spend, with each provider's own key.",
+        auth: {
+            kind: "header",
+            header: "cf-aig-authorization",
+            prefix: "Bearer ",
+            secret: "AI_GATEWAY_API_KEY",
+        },
+        authOptional: true,
+        docs: "https://dash.cloudflare.com/?to=/:account/ai/ai-gateway",
+        api: "https://developers.cloudflare.com/ai-gateway/",
+        setup: "setup/ai-gateway.md",
+        origin: "https://gateway.ai.cloudflare.com",
+        alsoNeeds: ["CLOUDFLARE_ACCOUNT_ID", "AI_GATEWAY_ID"],
+        basePath: "/v1/{CLOUDFLARE_ACCOUNT_ID}/{AI_GATEWAY_ID}",
+        inferenceRoutes: [],
+        hint: "The gateway's id from the AI Gateway page (everyapp ai gateway on makes one named everyapp); AI_GATEWAY_API_KEY only for an authenticated gateway, sent as cf-aig-authorization.",
+        secrets: [
+            {
+                name: "AI_GATEWAY_ID",
+                hint: "The AI Gateway's id (its name in the dashboard), in the Gateway's own Cloudflare account.",
+            },
+            {
+                name: "AI_GATEWAY_API_KEY",
+                hint: "An AI Gateway token with Run permission, only when the gateway is authenticated; leave unset for an open gateway.",
+            },
+        ],
+        verified: { on: "2026-10-25", how: "docs" },
+    },
+    dataforseo: {
+        mode: "api_key",
+        label: "DataForSEO",
+        description: "SEO data: keyword metrics, live search results, domain rankings, backlinks.",
+        // The key is `login:password` as the dashboard shows them, or that pair
+        // already base64-encoded (what OpenSEO's DATAFORSEO_API_KEY has always held).
+        auth: { kind: "basic", secret: "DATAFORSEO_API_KEY", as: "pair" },
+        docs: "https://app.dataforseo.com/api-access",
+        api: "https://docs.dataforseo.com/v3/",
+        setup: "setup/dataforseo.md",
+        // The sandbox answers like production, with made-up data and no charge.
+        hosts: ["api.dataforseo.com", "sandbox.dataforseo.com"],
+        access: ["read"],
+        // Every DataForSEO endpoint reads data, the paid live POSTs included;
+        // none changes anything the organization owns.
+        readMethods: ["GET", "POST"],
+        // Results are fetched by task id, which only the app that posted the
+        // task holds; these list every task (ready, or fixed within the last
+        // week), error and setting on the account.
+        accountWidePaths: [
+            ["tasks_ready"],
+            ["tasks_fixed"],
+            ["id_list"],
+            ["errors"],
+            ["appendix", "user_data"],
+            ["appendix", "webhook_resend"],
+        ],
+        hint: "The API login and password from API Access, as login:password (or that pair base64-encoded); the Gateway sends them as HTTP Basic.",
+        secrets: [
+            {
+                name: "DATAFORSEO_API_KEY",
+                hint: "login:password, or its base64; never the dashboard sign-in password.",
+            },
+        ],
+        // DataForSEO's envelope starts with the call's cost in USD.
+        cost: {
+            unit: "call",
+            responseField: "cost",
+            note: "A Google SERP $0.002 per 10 results; a Labs task $0.012 plus $0.00012 per item.",
+        },
+        smoke: {
+            method: "GET",
+            path: "/v3/appendix/user_data",
+            expect: [200],
+            free: true,
+            note: "Account-wide, so the Gateway refuses it for apps; run it from the person's terminal.",
+        },
+        example: "find keyword ideas for a page about running shoes",
+        verified: { on: "2026-10-25", how: "live" },
+    },
+    context: {
+        mode: "api_key",
+        label: "Context.dev",
+        description: "Scrapes and renders web pages, JavaScript included.",
+        auth: { kind: "bearer", secret: "CONTEXT_API_KEY" },
+        docs: "https://context.dev/",
+        setup: "setup/context.md",
+        hosts: ["api.context.dev"],
+        access: ["read"],
+        // Scraping and rendering pages reads the web; nothing it owns changes.
+        readMethods: ["GET", "POST"],
+        accountWidePaths: [],
+        hint: "An API key from the Context.dev dashboard; the Gateway puts it on every call as a bearer token.",
+        verified: { on: "2026-10-25", how: "live" },
+    },
+    // Outbound mail through the gateway's own sender and transport
+    // (apps/every-app-gateway/src/server/capabilities/email.ts): one sending
+    // domain onboarded per gateway, its daily budgets, attribution and logs.
+    email: {
+        mode: "service",
+        label: "Email",
+        access: ["write"],
+        routes: { send: ["POST"] },
+        // The sender is EMAIL_FROM with a display name: the gateway refuses to
+        // send without one. EMAIL_FROM_NAME is the plain way to give it, so the
+        // setup dialog and the CLI name both; EMAIL_FROM="Name <address>" stays
+        // accepted (parseEmailSender in internal/email.ts), and the gateway,
+        // which reads values, answers by its own rule (isEmailConfigured: a
+        // sender that parses and a provider that is selectable) rather than by
+        // these names. The CLI reads names alone, so it calls EMAIL_FROM_NAME
+        // unset until it is.
+        settings: ["EMAIL_FROM", "EMAIL_FROM_NAME"],
+        // The providers' settings (internal/email.ts chooseEmailProvider):
+        // Cloudflare's REST pair, sent instead of the gateway's EMAIL binding
+        // (a gateway outside Workers, local dev); Resend's key; and the choice
+        // between them when both are set.
+        optionalSettings: [
+            "EMAIL_REST_API_TOKEN",
+            "CLOUDFLARE_ACCOUNT_ID",
+            "RESEND_API_KEY",
+            "EMAIL_PROVIDER",
+        ],
+        setup: "setup/email.md",
+    },
+    // The organization's members who can open the app
+    // (apps/every-app-gateway/src/server/capabilities/members.ts): who an app
+    // may email or notify now, after people leave or lose access. It needs no
+    // setting; the gateway reads its own directory.
+    members: {
+        mode: "service",
+        label: "Members",
+        access: ["read"],
+        routes: { list: ["GET"] },
+        settings: [],
+        optionalSettings: [],
+    },
+    slack: {
+        mode: "oauth_client",
+        label: "Slack",
+        secrets: {
+            clientId: "SLACK_CLIENT_ID",
+            clientSecret: "SLACK_CLIENT_SECRET",
+        },
+        token: [
+            {
+                host: "slack.com",
+                path: "/api/oauth.v2.access",
+                methods: ["POST"],
+                inject: "form",
+            },
+        ],
+        access: ["write"],
+        console: "https://api.slack.com/apps",
+        setup: "setup/slack.md",
+        authorize: {
+            url: "https://slack.com/oauth/v2/authorize",
+            // The sets' union: the bot scopes in set order, then the one user
+            // scope no bot set carries. Postiz lists `channels.read`,
+            // `users.read`, `messages.write`, `channels.join` and `files.write`
+            // (it posts to channels it joins and uploads images); Open CRM adds
+            // `users.email`, `channels.manage` and `user-channels.manage` (its
+            // team agents match members to Slack users by email, create and
+            // manage the channels they post to, open DMs, and the installing
+            // person invites the bot to private channels).
+            scopes: [
+                "channels:read",
+                "groups:read",
+                "users:read",
+                "users:read.email",
+                "chat:write",
+                "chat:write.public",
+                "chat:write.customize",
+                "channels:join",
+                "channels:manage",
+                "groups:write",
+                "channels:write.invites",
+                "groups:write.invites",
+                "im:write",
+                "files:write",
+                "channels:write",
+            ],
+        },
+        scopePolicy: {
+            dialect: "slack",
+            // `oauth.v2.access` takes `code` with no `grant_type`; an app that
+            // opts into token rotation refreshes with `refresh_token`.
+            grantTypes: [null, "refresh_token"],
+            // Slack reads no `scope` on the token leg (the installation's scopes
+            // were fixed on the authorize URL), so the request goes as sent.
+            requestScope: "keep",
+            alwaysRequested: [],
+            tolerated: [],
+            deniedSegments: [],
+            // Slack authorizes by method name, not verb, and every method is one
+            // exact `/api/<method>` path on the host that also serves the token
+            // endpoint (which no set lists). A read set names its methods in
+            // `paths` (GET) and `posts` (POST) alike; a write set in `posts`
+            // only, with the one listing among them in `paths` too.
+            sets: {
+                "channels.read": {
+                    label: "Channels (read-only)",
+                    access: "read",
+                    scopes: ["channels:read", "groups:read"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [
+                                "/api/conversations.list",
+                                "/api/conversations.info",
+                                "/api/conversations.members",
+                                "/api/users.conversations",
+                            ],
+                            posts: [
+                                /^\/api\/conversations\.(list|info|members)$/,
+                                /^\/api\/users\.conversations$/,
+                            ],
+                        },
+                    ],
+                },
+                "users.read": {
+                    label: "Members (read-only)",
+                    access: "read",
+                    scopes: ["users:read"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [
+                                "/api/users.list",
+                                "/api/users.info",
+                                "/api/users.getPresence",
+                                "/api/bots.info",
+                            ],
+                            posts: [
+                                /^\/api\/users\.(list|info|getPresence)$/,
+                                /^\/api\/bots\.info$/,
+                            ],
+                        },
+                    ],
+                },
+                "users.email": {
+                    // Slack grants it only beside `users:read`: declare both sets.
+                    label: "Members' email addresses (read-only)",
+                    access: "read",
+                    scopes: ["users:read.email"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: ["/api/users.lookupByEmail"],
+                            posts: [/^\/api\/users\.lookupByEmail$/],
+                        },
+                    ],
+                },
+                "messages.write": {
+                    label: "Messages (post as the app)",
+                    access: "write",
+                    scopes: ["chat:write", "chat:write.public", "chat:write.customize"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            // The scheduled-messages listing is the one read among them.
+                            paths: ["/api/chat.scheduledMessages.list"],
+                            posts: [
+                                /^\/api\/chat\.(postMessage|postEphemeral|update|delete|scheduleMessage|deleteScheduledMessage|scheduledMessages\.list)$/,
+                            ],
+                        },
+                    ],
+                },
+                "channels.join": {
+                    label: "Channels (join public ones)",
+                    access: "write",
+                    scopes: ["channels:join"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [],
+                            posts: [/^\/api\/conversations\.join$/],
+                        },
+                    ],
+                },
+                "channels.manage": {
+                    label: "Channels (create, manage and invite to; open DMs)",
+                    access: "write",
+                    scopes: [
+                        "channels:manage",
+                        "groups:write",
+                        "channels:write.invites",
+                        "groups:write.invites",
+                        "im:write",
+                    ],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [],
+                            posts: [
+                                /^\/api\/conversations\.(create|rename|archive|unarchive|invite|open|kick|leave|setTopic|setPurpose|mark)$/,
+                            ],
+                        },
+                    ],
+                },
+                "files.write": {
+                    label: "Files (upload)",
+                    access: "write",
+                    scopes: ["files:write"],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [],
+                            // The external upload flow; the retired `files.upload` stays off.
+                            posts: [
+                                /^\/api\/files\.(getUploadURLExternal|completeUploadExternal)$/,
+                            ],
+                        },
+                    ],
+                },
+                "user-channels.manage": {
+                    label: "Channels (as the installing person: read, manage, invite to)",
+                    access: "write",
+                    scopes: [],
+                    // Slack's `user_scope`: issued to the person's own token, which
+                    // Open CRM uses to invite the bot to private channels.
+                    userScopes: [
+                        "channels:read",
+                        "channels:write",
+                        "groups:read",
+                        "groups:write",
+                    ],
+                    routes: [
+                        {
+                            host: "slack.com",
+                            paths: [
+                                "/api/conversations.list",
+                                "/api/conversations.info",
+                                "/api/conversations.members",
+                                "/api/users.conversations",
+                            ],
+                            posts: [
+                                /^\/api\/conversations\.(list|info|members|create|rename|archive|unarchive|invite|kick|leave|setTopic|setPurpose|mark)$/,
+                                /^\/api\/users\.conversations$/,
+                            ],
+                        },
+                    ],
+                },
+            },
+        },
+        api: ["slack.com"],
+        // Slack refuses `code_challenge`; `auth.test` names the workspace and
+        // the installing person.
+        flow: {
+            tokenUrl: "https://slack.com/api/oauth.v2.access",
+            revokeUrl: "https://slack.com/api/auth.revoke",
+            pkce: false,
+            scopeDialect: "slack",
+            identity: {
+                url: "https://slack.com/api/auth.test",
+                label: "team",
+                id: "user_id",
+            },
+        },
+    },
+    // Clients several apps share with different needs, so each app lists the
+    // scope sets it uses: Open CRM reads a member's own mailbox and calendar
+    // (`gmail.read`, `calendar.read`; `identity`, `mail.read`), OpenSEO reads
+    // a site's Search Console and Analytics (`identity`, `search-console.read`,
+    // `analytics.read`). Every set is read-only. Google's is one Cloud project
+    // apart from the YouTube preset's; Gmail's read scope is restricted and needs
+    // Google's verification, and whether Search Console and Analytics share
+    // that consent screen with it is the operator's choice when verifying.
+    "google-workspace": {
+        mode: "oauth_client",
+        label: "Google (Gmail, Calendar, Search Console and Analytics)",
+        secrets: {
+            clientId: "GOOGLE_WORKSPACE_CLIENT_ID",
+            clientSecret: "GOOGLE_WORKSPACE_CLIENT_SECRET",
+        },
+        token: [
+            {
+                host: "oauth2.googleapis.com",
+                path: "/token",
+                methods: ["POST"],
+                inject: "form",
+            },
+        ],
+        access: ["write"],
+        console: "https://console.cloud.google.com/apis/credentials",
+        setup: "setup/google.md",
+        authorize: {
+            url: "https://accounts.google.com/o/oauth2/v2/auth",
+            scopes: [
+                "openid",
+                "email",
+                "profile",
+                "https://www.googleapis.com/auth/gmail.readonly",
+                "https://www.googleapis.com/auth/calendar.readonly",
+                "https://www.googleapis.com/auth/webmasters.readonly",
+                "https://www.googleapis.com/auth/analytics.readonly",
+            ],
+        },
+        scopePolicy: {
+            dialect: "google",
+            // Google documents no scope on either token leg: the response's
+            // `scope` is where the gateway learns what a token holds.
+            grantTypes: ["authorization_code", "refresh_token"],
+            requestScope: "drop",
+            alwaysRequested: [],
+            // Both spellings: Google documents `email`/`profile` and the userinfo
+            // URLs as the same grants, and echoes the URLs.
+            tolerated: [
+                "openid",
+                "email",
+                "profile",
+                "https://www.googleapis.com/auth/userinfo.email",
+                "https://www.googleapis.com/auth/userinfo.profile",
+            ],
+            // Gmail's and Calendar's `/batch/<api>/<version>` carry whole requests
+            // inside; Analytics' measurement protocol secrets are readable under
+            // the read-only scope.
+            deniedSegments: ["batch", "measurementProtocolSecrets"],
+            sets: {
+                identity: {
+                    label: "Google account (who you are)",
+                    access: "read",
+                    scopes: ["openid", "email", "profile"],
+                    routes: [
+                        { host: "openidconnect.googleapis.com", paths: ["/v1/userinfo"] },
+                        {
+                            host: "www.googleapis.com",
+                            paths: [
+                                "/oauth2/v2/userinfo",
+                                "/oauth2/v3/userinfo",
+                                "/userinfo/v2/me",
+                            ],
+                        },
+                    ],
+                },
+                "gmail.read": {
+                    label: "Gmail (read-only)",
+                    access: "read",
+                    scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
+                    routes: [
+                        {
+                            host: "gmail.googleapis.com",
+                            paths: ["/gmail/v1/users/"],
+                            // Push notifications start and stop; `messages/send`, drafts
+                            // and `modify` are the other POSTs under the same prefix.
+                            posts: [/^\/gmail\/v1\/users\/[^/]+\/(watch|stop)$/],
+                        },
+                    ],
+                },
+                "calendar.read": {
+                    label: "Google Calendar (read-only)",
+                    access: "read",
+                    scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
+                    routes: [
+                        {
+                            host: "www.googleapis.com",
+                            paths: ["/calendar/v3/"],
+                            posts: [
+                                /^\/calendar\/v3\/freeBusy$/,
+                                /^\/calendar\/v3\/calendars\/[^/]+\/events\/watch$/,
+                                /^\/calendar\/v3\/users\/me\/calendarList\/watch$/,
+                                /^\/calendar\/v3\/channels\/stop$/,
+                            ],
+                        },
+                    ],
+                },
+                "search-console.read": {
+                    label: "Search Console (read-only)",
+                    access: "read",
+                    scopes: ["https://www.googleapis.com/auth/webmasters.readonly"],
+                    // The v3 paths answer on both hosts; URL inspection is v1 only.
+                    // A site is one segment, `https%3A%2F%2Fexample.com%2F` or
+                    // `sc-domain%3Aexample.com`, which is why routes match the raw path.
+                    routes: [
+                        {
+                            host: "www.googleapis.com",
+                            paths: ["/webmasters/v3/"],
+                            posts: [
+                                /^\/webmasters\/v3\/sites\/[^/]+\/searchAnalytics\/query$/,
+                            ],
+                        },
+                        {
+                            host: "searchconsole.googleapis.com",
+                            paths: ["/webmasters/v3/"],
+                            posts: [
+                                /^\/webmasters\/v3\/sites\/[^/]+\/searchAnalytics\/query$/,
+                                /^\/v1\/urlInspection\/index:inspect$/,
+                            ],
+                        },
+                    ],
+                },
+                "analytics.read": {
+                    label: "Google Analytics (read-only)",
+                    access: "read",
+                    scopes: ["https://www.googleapis.com/auth/analytics.readonly"],
+                    routes: [
+                        {
+                            // Reports are POSTed queries.
+                            host: "analyticsdata.googleapis.com",
+                            paths: ["/v1beta/properties/"],
+                            posts: [
+                                /^\/v1beta\/properties\/[^/]+:(runReport|batchRunReports|runPivotReport|batchRunPivotReports|runRealtimeReport|checkCompatibility)$/,
+                            ],
+                        },
+                        {
+                            // Reads only: accounts, properties and what hangs off them
+                            // (data streams, key events, enhanced measurement settings).
+                            host: "analyticsadmin.googleapis.com",
+                            paths: [
+                                "/v1beta/accountSummaries",
+                                "/v1beta/accounts",
+                                "/v1beta/accounts/",
+                                "/v1beta/properties",
+                                "/v1beta/properties/",
+                                "/v1alpha/properties/",
+                            ],
+                        },
+                    ],
+                },
+            },
+        },
+        api: [
+            "gmail.googleapis.com",
+            "www.googleapis.com",
+            "searchconsole.googleapis.com",
+            "analyticsdata.googleapis.com",
+            "analyticsadmin.googleapis.com",
+            "openidconnect.googleapis.com",
+        ],
+        // The Gateway-owned flow: a refresh token needs `access_type=offline`,
+        // and `prompt=consent` makes Google issue one on every connect. No
+        // revoke: Google's `/revoke` is per person per client and would also
+        // kill the tokens an app-driven OpenSEO holds under the same client.
+        flow: {
+            tokenUrl: "https://oauth2.googleapis.com/token",
+            pkce: true,
+            scopeDialect: "google",
+            authorizeParams: { access_type: "offline", prompt: "consent" },
+            identity: {
+                url: "https://openidconnect.googleapis.com/v1/userinfo",
+                label: "email",
+                id: "sub",
+            },
+        },
+    },
+    "microsoft-365": {
+        mode: "oauth_client",
+        label: "Microsoft 365 (Outlook mail and calendar)",
+        secrets: {
+            clientId: "MICROSOFT_365_CLIENT_ID",
+            clientSecret: "MICROSOFT_365_CLIENT_SECRET",
+        },
+        token: [
+            {
+                // The multi-tenant endpoint: register the client for accounts in
+                // any organization and personal accounts. A single-tenant client
+                // answers only on its tenant's path, which this does not complete.
+                host: "login.microsoftonline.com",
+                path: "/common/oauth2/v2.0/token",
+                methods: ["POST"],
+                inject: "form",
+            },
+        ],
+        access: ["write"],
+        console: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade",
+        setup: "setup/microsoft-365.md",
+        authorize: {
+            url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+            scopes: ["offline_access", "User.Read", "Mail.Read", "Calendars.Read"],
+        },
+        scopePolicy: {
+            dialect: "microsoft",
+            grantTypes: ["authorization_code", "refresh_token"],
+            // The token leg's `scope` is Microsoft's extension for naming the
+            // resource; the gateway sets it to the app's list so a token covers
+            // Graph alone.
+            requestScope: "replace",
+            // Refresh tokens; Entra never echoes it in a response's `scope`.
+            alwaysRequested: ["offline_access"],
+            // Compared case-insensitively, as Microsoft spells them both ways.
+            tolerated: ["openid", "profile", "email", "offline_access", "User.Read"],
+            // `$batch` carries whole requests inside; `beta` is another API.
+            deniedSegments: ["$batch", "beta"],
+            // `/v1.0/me/…` only: `/v1.0/users/<id>/…` reaches shared mailboxes
+            // and calendars under the same permissions.
+            sets: {
+                identity: {
+                    label: "Microsoft account (who you are)",
+                    access: "read",
+                    scopes: ["User.Read"],
+                    routes: [
+                        {
+                            host: "graph.microsoft.com",
+                            paths: ["/v1.0/me", "/oidc/userinfo"],
+                        },
+                    ],
+                },
+                "mail.read": {
+                    label: "Outlook mail (read-only)",
+                    access: "read",
+                    scopes: ["Mail.Read"],
+                    routes: [
+                        {
+                            host: "graph.microsoft.com",
+                            paths: [
+                                "/v1.0/me/messages",
+                                "/v1.0/me/messages/",
+                                "/v1.0/me/mailFolders",
+                                "/v1.0/me/mailFolders/",
+                            ],
+                        },
+                    ],
+                },
+                "calendar.read": {
+                    label: "Outlook calendar (read-only)",
+                    access: "read",
+                    scopes: ["Calendars.Read"],
+                    routes: [
+                        {
+                            host: "graph.microsoft.com",
+                            paths: [
+                                "/v1.0/me/calendar",
+                                "/v1.0/me/calendar/",
+                                "/v1.0/me/calendars",
+                                "/v1.0/me/calendars/",
+                                "/v1.0/me/events",
+                                "/v1.0/me/events/",
+                                "/v1.0/me/calendarView",
+                                "/v1.0/me/calendarView/",
+                            ],
+                            // Free/busy is a POSTed query.
+                            posts: [/^\/v1\.0\/me\/calendar\/getSchedule$/],
+                        },
+                    ],
+                },
+            },
+        },
+        api: ["graph.microsoft.com"],
+        flow: {
+            tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+            pkce: true,
+            scopeDialect: "microsoft",
+            identity: {
+                url: "https://graph.microsoft.com/v1.0/me",
+                label: "userPrincipalName",
+                id: "id",
+            },
+        },
+    },
+    // The first fifty beyond the entries above (catalog/*.ts, PR 3 of the
+    // provider registry), after them so the derived lists keep their order.
+    ...CATALOG_ENTRIES,
+};
+/** The Gateway settings an API-key or AI provider's `auth` names: the key first, then a Basic username held as a setting. */
+export function authSettingNames(auth) {
+    const names = [auth.secret];
+    if (auth.kind === "basic" &&
+        auth.as === "password" &&
+        typeof auth.user === "object") {
+        names.push(auth.user.secret);
+    }
+    return names;
+}
+/** Every gateway setting `capability` reads, the ones it needs first. */
+export function capabilitySettings(capability) {
+    switch (capability.mode) {
+        case "api_key":
+            return [
+                ...authSettingNames(capability.auth),
+                ...(capability.hostSetting ? [capability.hostSetting] : []),
+            ];
+        case "ai":
+            return [capability.auth.secret, ...(capability.alsoNeeds ?? [])];
+        case "service":
+            return [...capability.settings, ...capability.optionalSettings];
+        case "oauth_client":
+            return [
+                capability.secrets.clientId,
+                ...(capability.secrets.clientSecret
+                    ? [capability.secrets.clientSecret]
+                    : []),
+            ];
+    }
+}
+export const CAPABILITY_IDS = Object.keys(CAPABILITIES);
+export function isCapabilityId(value) {
+    return typeof value === "string" && Object.hasOwn(CAPABILITIES, value);
+}
+/** The built-in catalog as a lookup: what every surface reads without a gateway's rows. */
+export const CATALOG = {
+    get: (id) => (isCapabilityId(id) ? CAPABILITIES[id] : undefined),
+    ids: () => CAPABILITY_IDS,
+};
+/** The ids an app may list under `capabilities`: every provider but the AI ones, which go under `providers`. */
+export function capabilityIdsOf(lookup) {
+    return lookup.ids().filter((id) => lookup.get(id)?.mode !== "ai");
+}
+/**
+ * The settings `capability` needs on a request, read from the Gateway's
+ * settings (or `.dev.vars`): the headers to set and the query parameters
+ * to add, or null while any setting its `auth` names is unset or blank.
+ * Values are trimmed. A Basic key without a username is `login:password`
+ * to encode, or taken as already encoded when it holds no colon.
+ */
+export function authorizationFor(capability, settings) {
+    return authorizationOf(capability.auth, settings);
+}
+/** {@link authorizationFor} for an `auth` block alone (the SDK's AI fallback holds the block, not the entry). */
+export function authorizationOf(auth, settings) {
+    const key = settingValue(settings[auth.secret]);
+    if (!key)
+        return null;
+    switch (auth.kind) {
+        case "bearer":
+            return {
+                headers: { authorization: `${auth.scheme ?? "Bearer"} ${key}` },
+                query: {},
+            };
+        case "header":
+            return {
+                headers: { [auth.header.toLowerCase()]: `${auth.prefix ?? ""}${key}` },
+                query: {},
+            };
+        case "query":
+            return { headers: {}, query: { [auth.param]: key } };
+        case "basic": {
+            const basic = (credentials) => ({
+                headers: { authorization: `Basic ${credentials}` },
+                query: {},
+            });
+            if (auth.as === "pair")
+                return basic(basicCredentials(key));
+            if (auth.as === "username")
+                return basic(base64Utf8(`${key}:`));
+            const user = typeof auth.user === "string"
+                ? auth.user
+                : settingValue(settings[auth.user.secret]);
+            if (!user)
+                return null;
+            return basic(base64Utf8(`${user}:${key}`));
+        }
+    }
+}
+function settingValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * The host a provider's `hostSetting` names, from its value: a bare host
+ * or an https origin with nothing else (no path, port, query, userinfo),
+ * lowercased; null when unset or not of that shape. The host rules a row
+ * must pass apply to it when the registry reads the row.
+ */
+export function hostSettingValue(value) {
+    const text = settingValue(value);
+    if (!text)
+        return null;
+    let url;
+    try {
+        url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`);
+    }
+    catch {
+        return null;
+    }
+    const bare = url.protocol === "https:" &&
+        url.pathname === "/" &&
+        !url.search &&
+        !url.hash &&
+        !url.username &&
+        !url.password &&
+        !url.port &&
+        !text.endsWith("/");
+    return bare ? url.hostname.toLowerCase() : null;
+}
+/**
+ * The hosts an API-key provider's key may be sent to: the entry's own,
+ * and the one its `hostSetting` names when that is set and well-formed.
+ */
+export function apiKeyHosts(capability, settings) {
+    const named = capability.hostSetting
+        ? hostSettingValue(settings?.[capability.hostSetting])
+        : null;
+    return [...capability.hosts, ...(named ? [named] : [])];
+}
+/** Where AppGateway serves capability calls. */
+export const INTEGRATION_PROXY_PREFIX = "/api/integrations";
+/**
+ * The AppGateway path for a call to `upstream`:
+ * `/api/integrations/<id>/<host><path>?<query>`. The host is in the path so
+ * a provider with several API hosts needs no other channel.
+ */
+export function integrationProxyPath(id, upstream) {
+    return `${INTEGRATION_PROXY_PREFIX}/${id}/${upstream.host}${upstream.pathname}${upstream.search}`;
+}
+/** The AppGateway path of a service capability's route: `/api/integrations/<id>/<route>`. */
+export function serviceRoutePath(id, route) {
+    return `${INTEGRATION_PROXY_PREFIX}/${id}/${route}`;
+}
+/**
+ * The capability call an AppGateway path names, or null when the path names
+ * an unknown capability (or an AI provider, which has its own route), a
+ * host outside the provider's, a path that could leave that host, a path
+ * that isn't one of an OAuth client's token endpoints, or a route a service
+ * capability doesn't declare. `settings` resolves an API-key provider's
+ * `hostSetting` (a Shopify store's host); `lookup` is where the id is found,
+ * the catalog alone by default.
+ */
+export function parseIntegrationProxyPath(pathname, search, settings, lookup = CATALOG) {
+    const match = /^\/api\/integrations\/([a-z][a-z0-9-]*)\/([^/]+)(\/.*)?$/.exec(pathname);
+    if (!match)
+        return null;
+    const [, id = "", host = "", path] = match;
+    const capability = lookup.get(id);
+    if (!capability)
+        return null;
+    if (capability.mode === "service") {
+        // A route is one segment; nothing may follow it.
+        if (path !== undefined || !Object.hasOwn(capability.routes, host)) {
+            return null;
+        }
+        return {
+            kind: "service",
+            id: id,
+            capability,
+            route: host,
+        };
+    }
+    if (capability.mode === "oauth_client") {
+        const upstream = capability.token.some((rule) => rule.host === host)
+            ? httpsUpstream(host, path ?? "/", search)
+            : null;
+        const endpoint = upstream && tokenEndpointFor(capability, upstream);
+        if (!upstream || !endpoint)
+            return null;
+        return { kind: "oauth_client", id, capability, upstream, endpoint };
+    }
+    if (capability.mode !== "api_key")
+        return null;
+    const upstream = apiKeyHosts(capability, settings).includes(host)
+        ? httpsUpstream(host, path ?? "/", search)
+        : null;
+    if (!upstream)
+        return null;
+    return { kind: "api_key", id, capability, upstream };
+}
+/** `https://<host><path><search>`, or null for a path that could leave `host`. */
+function httpsUpstream(host, path, search) {
+    if (path.startsWith("//") || path.includes("\\"))
+        return null;
+    const upstream = new URL(`https://${host}${path}${search}`);
+    // A parser quirk must never move the key to another host.
+    if (upstream.host !== host || upstream.protocol !== "https:")
+        return null;
+    return upstream;
+}
+/**
+ * The token endpoint `upstream` is, by its exact host and path, or null.
+ * Its method is the caller's to check.
+ */
+export function tokenEndpointFor(capability, upstream) {
+    if (upstream.protocol !== "https:")
+        return null;
+    return (capability.token.find(({ host, path }) => host === upstream.host && path === upstream.pathname) ?? null);
+}
+/** An OAuth client's token endpoints, as `POST https://host/path` lines for messages. */
+export function describeTokenEndpoints(capability) {
+    return capability.token
+        .map(({ host, path, methods }) => `${methods.join("/")} https://${host}${path}`)
+        .join(", ");
+}
+/**
+ * The command that gives the gateway `capability`'s client:
+ * `pnpm everyapp secret set <ID> <SECRET>`.
+ */
+export function oauthClientSecretSetCommand(capability) {
+    return `pnpm everyapp secret set ${capabilitySettings(capability).join(" ")}`;
+}
+/** Times a path may decode to something new before it counts as hiding one. */
+const MAX_PATH_DECODES = 3;
+/** Control, zero-width and whitespace characters: in no endpoint's path. */
+const UNPRINTABLE = /[\p{Cc}\p{Cf}\p{Z}\s]/u;
+/**
+ * The part of a segment a provider can route on: an endpoint's name ends at
+ * the first character no name has, so `tasks_ready,`, `tasks_ready;x` and
+ * `tasks_ready.json` all name `tasks_ready`.
+ */
+const SEGMENT_NAME = /^[a-z0-9_-]*/;
+/**
+ * Whether `pathname` reaches one of the capability's account-wide paths,
+ * however it is spelled: percent-encoded (twice, even), in another case,
+ * with a suffix on a segment, with doubled or backslash separators, or with
+ * a trailing segment. A path that doesn't decode, or that holds control
+ * characters or whitespace once decoded, counts as one; so does anything
+ * outside ASCII for a provider that has account-wide paths, since how it
+ * folds case is its own business.
+ */
+export function isAccountWidePath(capability, pathname) {
+    const decoded = decodePath(pathname);
+    if (decoded === null || UNPRINTABLE.test(decoded))
+        return true;
+    const blocked = capability.accountWidePaths;
+    if (blocked.length === 0)
+        return false;
+    if (!/^[\x20-\x7e]*$/.test(decoded))
+        return true;
+    // Empty segments drop out, as on a server that merges slashes.
+    const segments = decoded.split(/[/\\]/).filter(Boolean);
+    // The URL parser already resolved every dot segment it could see; one
+    // that only decoding reveals is a disguise.
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        return true;
+    }
+    const names = segments.map((segment) => SEGMENT_NAME.exec(segment)?.[0] ?? "");
+    return blocked.some((path) => names.some((_, start) => path.every((name, offset) => names[start + offset] === name)));
+}
+/** `pathname` percent-decoded until it stops changing, lowercased; null if it won't. */
+function decodePath(pathname) {
+    let current = pathname;
+    for (let round = 0; round <= MAX_PATH_DECODES; round++) {
+        let next;
+        try {
+            next = decodeURIComponent(current);
+        }
+        catch {
+            return null;
+        }
+        if (next === current)
+            return current.toLowerCase();
+        current = next;
+    }
+    return null;
+}
+/**
+ * A Basic credential held as one setting: `login:password` as a dashboard
+ * shows them, or the pair already base64-encoded (DataForSEO's rule, and
+ * what OpenSEO's DATAFORSEO_API_KEY has always held). A base64 string never
+ * holds a colon, so the colon decides.
+ */
+function basicCredentials(key) {
+    const trimmed = key.trim();
+    return trimmed.includes(":") ? base64Utf8(trimmed) : trimmed;
+}
+/** The base64 of `text`'s UTF-8 bytes (`btoa` takes Latin-1 only). */
+export function base64Utf8(text) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(text)) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}