@every-app/sdk 0.3.0-rc.2 → 0.3.0-rc.3

package/dist/server/connectUrl.js

@@ -0,0 +1,37 @@
+/**
+ * Where an app sends a person to connect an OAuth provider the Gateway
+ * runs the flow for (docs/design/2026-10-oauth-providers.md section 5):
+ * `<gateway>/connect/<id>?return=<back here>&account=<user|organization>`.
+ * The Gateway checks the session, asks the provider for the union of the
+ * sets every active app declares, finishes on its own callback and sends
+ * the browser back to `returnTo`, which must be a path on the Gateway or
+ * an https URL on one of its app hosts (in local dev also localhost).
+ */
+import { ConfigurationError } from "../internal/index.js";
+/** The path of the connect page for `provider` on the Gateway. */
+export function connectPath(provider) {
+    return `/connect/${encodeURIComponent(provider)}`;
+}
+/** The absolute URL that starts the Gateway-owned flow for `provider`. */
+export function connectUrl({ env, provider, returnTo, account, sets, }) {
+    const values = env;
+    const gateway = values["GATEWAY_URL"];
+    if (typeof gateway !== "string" || !gateway.trim()) {
+        throw new ConfigurationError("connectUrl() needs GATEWAY_URL in the Worker env: the deploy sets it, and everyapp dev sets it to the local gateway.");
+    }
+    let base;
+    try {
+        base = new URL(gateway.trim());
+    }
+    catch {
+        throw new ConfigurationError(`GATEWAY_URL isn't a URL: ${gateway}`);
+    }
+    const url = new URL(connectPath(provider), base.origin);
+    if (returnTo)
+        url.searchParams.set("return", returnTo);
+    if (account)
+        url.searchParams.set("account", account);
+    if (sets && sets.length > 0)
+        url.searchParams.set("sets", sets.join(","));
+    return url.toString();
+}

package/dist/server/gatewayFetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gatewayFetch.d.ts","sourceRoot":"","sources":["../../src/server/gatewayFetch.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAGlE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,eAAe,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,GAAG,EACH,GAAG,EAAE,MAAM,GACZ,EAAE,yBAAyB,GAAG,OAAO,KAAK,CA8D1C;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,OAAO,CAUT"}
+{"version":3,"file":"gatewayFetch.d.ts","sourceRoot":"","sources":["../../src/server/gatewayFetch.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAGlE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,eAAe,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,GAAG,EACH,GAAG,EAAE,MAAM,GACZ,EAAE,yBAAyB,GAAG,OAAO,KAAK,CAoE1C;AAwCD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,OAAO,CAUT"}

package/dist/server/gatewayFetch.js

@@ -1,4 +1,4 @@
-import { aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, devAiProvider, joinProviderUrl, } from "../internal/index.js";
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, AI_DEFAULT_ROUTES, aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, devAiProvider, joinProviderUrl, resolveAiDefault, } from "../internal/index.js";
 import { applyAttribution, checkAttribution, } from "./attribution.js";
 export const BINDING_ORIGIN = "http://every-app-gateway.internal";
 const AI_PROXY_PREFIX = "/api/ai/";
@@ -28,7 +28,8 @@ export function createGatewayFetch({ env, for: target, }) {
             const bindingRequest = streamingRequest(`${BINDING_ORIGIN}${url.pathname}${url.search}`, outbound, headers);
             return binding.fetch(bindingRequest);
         }
-        const { provider, spec, path, search } = directProviderPath(outbound.url);
+        const direct = directProviderPath(outbound.url, env);
+        const { provider, spec, path, search } = direct;
         const dev = devProviders[provider];
         if (!dev) {
             throw new ConfigurationError(`Set ${settingsNames(spec)} in .dev.vars to call ${provider} in local development.`);
@@ -37,6 +38,11 @@ export function createGatewayFetch({ env, for: target, }) {
         if (!url)
             throw new ConfigurationError("Invalid provider proxy path.");
         applyAttribution(headers, undefined);
+        // The default route in dev: the model filled in as the gateway would.
+        let body = outbound;
+        if (direct.fillModel !== null) {
+            body = await withModel(outbound, direct.fillModel, headers);
+        }
         // The developer's key, put where the provider's entry says (a bearer
         // token for the three today), as the gateway would put its own.
         const auth = authorizationOf(spec.auth, { [spec.keyEnv]: dev.key });
@@ -46,11 +52,44 @@ export function createGatewayFetch({ env, for: target, }) {
         for (const [name, value] of Object.entries(auth?.query ?? {})) {
             url.searchParams.set(name, value);
         }
-        const response = await fetch(streamingRequest(url.toString(), outbound, headers));
+        const response = await fetch(streamingRequest(url.toString(), body, headers));
         // What the gateway does to the provider's answer, so dev behaves alike.
         return spec.normalizeResponse?.(path, response) ?? response;
     };
 }
+/**
+ * `source` with `model` put into its JSON body where the app named none
+ * or named `default`, as the gateway's default route does. A body that
+ * isn't a JSON object goes through as it is.
+ */
+async function withModel(source, model, headers) {
+    if (!canIncludeBody(source.method) || !source.body)
+        return source;
+    const text = await source.clone().text();
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return source;
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return source;
+    }
+    const record = payload;
+    if (record["model"] === undefined ||
+        record["model"] === null ||
+        record["model"] === AI_DEFAULT_MODEL) {
+        record["model"] = model;
+    }
+    headers.delete("content-length");
+    return new Request(source.url, {
+        method: source.method,
+        headers,
+        body: JSON.stringify(record),
+        signal: source.signal,
+    });
+}
 /** A copy of `source` aimed at `url`, streaming its body rather than buffering it. */
 export function streamingRequest(url, source, headers) {
     const body = canIncludeBody(source.method) ? source.body : undefined;
@@ -82,19 +121,44 @@ function localProviders(env) {
     }
     return providers;
 }
-function directProviderPath(input) {
+function directProviderPath(input, env) {
     const incoming = new URL(input);
     const match = incoming.pathname.match(/^\/api\/ai\/([a-z][a-z0-9-]*)(\/.*)?$/);
-    const provider = match?.[1];
+    let provider = match?.[1];
+    let path = match?.[2] || "/";
+    let fillModel = null;
+    if (provider === AI_DEFAULT_PROVIDER) {
+        // The default in dev, by the gateway's rule on the developer's own
+        // `.dev.vars`: the first provider of the order with every setting set.
+        const values = env;
+        const resolution = resolveAiDefault({
+            choice: null,
+            isSet: (name) => typeof values[name] === "string" &&
+                values[name].trim().length > 0,
+        });
+        if (!resolution.configured) {
+            throw new ConfigurationError(`Set ${resolution.settings.join(" and ")} (or another model provider's key) in .dev.vars to call the default model in local development.`);
+        }
+        const route = path === AI_DEFAULT_ROUTES.chat
+            ? resolution.chat
+            : path === AI_DEFAULT_ROUTES.embeddings
+                ? resolution.embeddings
+                : undefined;
+        if (!route) {
+            throw new ConfigurationError(`The default model serves ${AI_DEFAULT_ROUTES.chat} and ${AI_DEFAULT_ROUTES.embeddings} only; call /api/ai/<provider>/… for anything else.`);
+        }
+        provider = resolution.provider;
+        path = route.path;
+        fillModel = path === resolution.chat.path ? resolution.model : route.model;
+    }
     const spec = provider ? devAiProvider(provider) : undefined;
     if (!provider || !spec) {
-        throw new ConfigurationError(`Direct local provider fallback only supports ${listOf(Object.keys(DEV_AI_PROVIDERS).map((name) => `${AI_PROXY_PREFIX}${name}`), "and")} paths.`);
+        throw new ConfigurationError(`Direct local provider fallback only supports ${listOf([AI_DEFAULT_PROVIDER, ...Object.keys(DEV_AI_PROVIDERS)].map((name) => `${AI_PROXY_PREFIX}${name}`), "and")} paths.`);
     }
-    const path = match?.[2] || "/";
     if (path.startsWith("//") || path.includes("\\")) {
         throw new ConfigurationError("Invalid provider proxy path.");
     }
-    return { provider, spec, path, search: incoming.search };
+    return { provider, spec, path, search: incoming.search, fillModel };
 }
 /** A provider's settings as a person reads them: `KEY`, or `KEY and SETTING`. */
 function settingsNames(spec, conjunction = "and") {

package/dist/server/index.d.ts

@@ -6,13 +6,15 @@
 export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, type EveryAppOptions, type EveryAppManifestLike, type EveryAppHandler, type EveryAppUser, type IdentityResult, } from "./everyApp.js";
 export { AttributionError, type GatewayCallFor } from "./attribution.js";
 export { authorizeUrl, type AuthorizeUrlOptions } from "./authorizeUrl.js";
+export { connectPath, connectUrl, type ConnectUrlOptions, } from "./connectUrl.js";
 export { createGatewayFetch, type CreateGatewayFetchOptions, type GatewayFetchEnv, } from "./gatewayFetch.js";
-export { GatewayRefusalError, gatewayRefusal, integrationFetch, integrationStatus, type EmailIntegrationStatus, type GatewayRefusal, type IntegrationFetchOptions, type IntegrationStatus, type IntegrationStatusOf, type OAuthClientIntegrationStatus, } from "./integrationFetch.js";
+export { ai, AI_DEFAULT_BASE_URL, type AiClient } from "./ai.js";
+export { GatewayRefusalError, gatewayRefusal, devAccessTokenName, integrationFetch, integrationStatus, type EmailIntegrationStatus, type GatewayRefusal, type IntegrationFetchOptions, type IntegrationStatus, type IntegrationStatusOf, type OAuthClientIntegrationStatus, } from "./integrationFetch.js";
 export { nodeServerHandler, type NodeServer, type NodeServerHandlerOptions, } from "./nodeServer.js";
 export { sendEmail, type SendEmailOptions } from "./sendEmail.js";
 export { listMembers, type ListMembersOptions } from "./listMembers.js";
 export { emit, type EmitOptions } from "./emit.js";
-export type { ApiKeyCapabilityId, CapabilityId, OAuthClientCapabilityId, EmailAddressInput, EmailAttachmentInput, SendEmailMessage, SendEmailResult, ListMembersResult, OrganizationMember, OrganizationMemberRole, EmitEventResult, } from "../internal/index.js";
+export type { ApiKeyCapabilityId, CapabilityId, OAuthClientCapabilityId, ConnectionAccount, EmailAddressInput, EmailAttachmentInput, SendEmailMessage, SendEmailResult, ListMembersResult, OrganizationMember, OrganizationMemberRole, EmitEventResult, } from "../internal/index.js";
 export { ToolError, defineTools, toolResult, type DefineToolsOptions, type PlainToolSchema, type StandardSchemaWithJSON, type ToolContext, type ToolDefinition, type ToolResult, type ToolSchema, type ToolSet, } from "./tools.js";
 export type { ToolRisk } from "../internal/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,GAClC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,SAAS,EACT,WAAW,EACX,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,WAAW,EACX,UAAU,EACV,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,EAAE,EAAE,mBAAmB,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,GAClC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,SAAS,EACT,WAAW,EACX,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/server/index.js

@@ -6,8 +6,10 @@
 export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, } from "./everyApp.js";
 export { AttributionError } from "./attribution.js";
 export { authorizeUrl } from "./authorizeUrl.js";
+export { connectPath, connectUrl, } from "./connectUrl.js";
 export { createGatewayFetch, } from "./gatewayFetch.js";
-export { GatewayRefusalError, gatewayRefusal, integrationFetch, integrationStatus, } from "./integrationFetch.js";
+export { ai, AI_DEFAULT_BASE_URL } from "./ai.js";
+export { GatewayRefusalError, gatewayRefusal, devAccessTokenName, integrationFetch, integrationStatus, } from "./integrationFetch.js";
 export { nodeServerHandler, } from "./nodeServer.js";
 export { sendEmail } from "./sendEmail.js";
 export { listMembers } from "./listMembers.js";

package/dist/server/integrationFetch.d.ts

@@ -1,4 +1,4 @@
-import { type ApiKeyCapabilityId, type CapabilityId, type EmailCapabilityStatus, type OAuthClientCapabilityId } from "../internal/index.js";
+import { type ApiKeyCapabilityId, type CapabilityId, type ConnectionAccount, type EmailCapabilityStatus, type OAuthClientCapabilityId } from "../internal/index.js";
 import { type GatewayCallFor } from "./attribution.js";
 export interface IntegrationFetchOptions {
     /**
@@ -24,6 +24,13 @@ export interface IntegrationFetchOptions {
      * pass one or the other ({@link AttributionError}).
      */
     for?: GatewayCallFor;
+    /**
+     * For an OAuth provider the gateway holds connections for: whose
+     * connection the call uses, the person's (`user`, the default when a
+     * person is behind the call) or the organization's (`organization`,
+     * the default for background work). Sent as `x-everyapp-account`.
+     */
+    account?: ConnectionAccount;
 }
 /**
  * A `fetch` for one of the gateway's capabilities. Call the provider's real
@@ -47,7 +54,14 @@ export interface IntegrationFetchOptions {
  * provider show <id> --save` writes it), put on the call as the gateway's
  * spec says.
  */
-export declare function integrationFetch({ env, provider, for: target, }: IntegrationFetchOptions): typeof fetch;
+export declare function integrationFetch({ env, provider, for: target, account, }: IntegrationFetchOptions): typeof fetch;
+/**
+ * The `.dev.vars` name of a held token for `provider` in local dev
+ * (`GOOGLE_WORKSPACE_ACCESS_TOKEN`, `GITHUB_ACCESS_TOKEN`): a token the
+ * developer obtained themselves, standing in for the connection the
+ * gateway would hold. Dev-only: the gateway never reads it.
+ */
+export declare function devAccessTokenName(provider: string): string;
 export interface IntegrationStatus {
     /** The app's manifest lists the capability. */
     requested: boolean;
@@ -92,6 +106,29 @@ export interface OAuthClientIntegrationStatus extends IntegrationStatus {
     scopes?: readonly string[];
     /** Slack's `user_scope` strings, when the sets name any. */
     userScopes?: readonly string[];
+    /**
+     * Which flows the client supports: `app` (the app runs authorize and
+     * callback itself and keeps the tokens, the social networks), `gateway`
+     * (the Gateway holds the connection; API calls go through
+     * `integrationFetch` with the token injected) or `both` (Google,
+     * Microsoft, Slack, Discord and every registered OAuth provider).
+     */
+    flow?: "app" | "gateway" | "both";
+    /** Where a person connects on the Gateway: `/connect/<id>`; see `connectUrl()`. */
+    connectPath?: string;
+    /**
+     * The connection the caller's account would use (the person's, or the
+     * organization's for background work), or null when there is none yet;
+     * `reconnect` when it exists but lacks a set the app declares or has
+     * expired, so the person has to connect again.
+     */
+    connection?: {
+        account: ConnectionAccount;
+        label: string | null;
+        scopeSets: readonly string[];
+        ready: boolean;
+        reconnect?: boolean;
+    } | null;
 }
 /** The status of a capability: email's carries its senders, an OAuth client's its id. */
 export type IntegrationStatusOf<P extends string> = P extends "email" ? EmailIntegrationStatus : P extends OAuthClientCapabilityId ? OAuthClientIntegrationStatus : IntegrationStatus;

package/dist/server/integrationFetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrationFetch.d.ts","sourceRoot":"","sources":["../../src/server/integrationFetch.ts"],"names":[],"mappings":"AAAA,OAAO,EA2BL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAE1B,KAAK,uBAAuB,EAO7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAO1B,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,QAAQ,EAAE,kBAAkB,GAAG,uBAAuB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACvE;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,QAAQ,EACR,GAAG,EAAE,MAAM,GACZ,EAAE,uBAAuB,GAAG,OAAO,KAAK,CAkGxC;AA+XD,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GACpD,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,4BAA6B,SAAQ,iBAAiB;IACrE,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,yFAAyF;AACzF,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,OAAO,GACjE,sBAAsB,GACtB,CAAC,SAAS,uBAAuB,GAC/B,4BAA4B,GAC5B,iBAAiB,CAAC;AAExB;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,CAAC,SAAS,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACtC,EACA,GAAG,EACH,QAAQ,GACT,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,CAAC,CAAC;CACb,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAoElC;AA2FD,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAM,YAAW,cAAc;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,cAAc;CAMtD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAWhC"}
+{"version":3,"file":"integrationFetch.d.ts","sourceRoot":"","sources":["../../src/server/integrationFetch.ts"],"names":[],"mappings":"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"}

package/dist/server/integrationFetch.js

@@ -1,4 +1,4 @@
-import { CATALOG, ConfigurationError, GATEWAY_ERROR_HEADER, INTEGRATION_PROXY_PREFIX, OAUTH_TOKEN_BODY_LIMIT, allowedScopes, apiKeyHosts, authorizationFor, capabilitySettings, carriesToken, declaredScopeSets, describeTokenEndpoints, devProviderFile, grantedScopes, injectClientCredentials, integrationProxyPath, oauthClientCredentials, oauthClientOrigin, requestedScopes, requestedTokenScopes, resolveDevProvider, rewriteTokenRequestScope, scopeExcess, tokenEndpointFor, tokenGrantType, EMAIL_SENDERS_ENV, chooseEmailProvider, parseEmailList, parseEmailSender, } from "../internal/index.js";
+import { ACCOUNT_HEADER, CATALOG, ConfigurationError, GATEWAY_ERROR_HEADER, INTEGRATION_PROXY_PREFIX, OAUTH_TOKEN_BODY_LIMIT, allowedScopes, apiKeyHosts, authorizationFor, capabilitySettings, carriesToken, declaredScopeSets, describeTokenEndpoints, devProviderFile, grantedScopes, heldTokenCallAllowed, injectClientCredentials, integrationProxyPath, oauthClientCredentials, oauthClientOrigin, oauthReadMethods, oauthWriteMethods, providerSettingPrefix, requestedScopes, requestedTokenScopes, resolveDevProvider, rewriteTokenRequestScope, scopeExcess, tokenEndpointFor, tokenGrantType, EMAIL_SENDERS_ENV, chooseEmailProvider, parseEmailList, parseEmailSender, } from "../internal/index.js";
 import { applyAttribution, checkAttribution, } from "./attribution.js";
 import { BINDING_ORIGIN, streamingRequest, } from "./gatewayFetch.js";
 /**
@@ -23,7 +23,7 @@ import { BINDING_ORIGIN, streamingRequest, } from "./gatewayFetch.js";
  * provider show <id> --save` writes it), put on the call as the gateway's
  * spec says.
  */
-export function integrationFetch({ env, provider, for: target, }) {
+export function integrationFetch({ env, provider, for: target, account, }) {
     const catalogEntry = fetchableCapability(provider);
     checkAttribution(env, target, `integrationFetch("${provider}")`);
     const values = env;
@@ -36,8 +36,23 @@ export function integrationFetch({ env, provider, for: target, }) {
     const integration = catalogEntry ??
         (binding ? undefined : devRegisteredProvider(provider, values));
     const local = binding || !integration ? null : localCredentials(integration, values);
-    if (!binding && !local && integration) {
-        throw new ConfigurationError(`${integration.label} is unavailable: deploy with the EVERY_APP_GATEWAY binding, or set ${capabilitySettings(integration).join(", ")} in .dev.vars for local development.`);
+    // In dev an OAuth provider with a held token in `.dev.vars` serves API
+    // calls without the client (the token stands in for a connection).
+    const devToken = !binding && integration?.mode === "oauth_client" && integration.flow
+        ? stringValue(values[devAccessTokenName(provider)])
+        : undefined;
+    // An OAuth provider with a Gateway-owned flow answers an API call
+    // without the client (`integration_not_connected`, below); a token
+    // endpoint call without the client throws when it is made.
+    const decidesLater = integration?.mode === "oauth_client" && integration.flow !== undefined;
+    if (!binding && !local && !devToken && integration && !decidesLater) {
+        const names = [
+            ...capabilitySettings(integration),
+            ...(integration.mode === "oauth_client" && integration.flow
+                ? [devAccessTokenName(provider)]
+                : []),
+        ];
+        throw new ConfigurationError(`${integration.label} is unavailable: deploy with the EVERY_APP_GATEWAY binding, or set ${names.join(", ")} in .dev.vars for local development.`);
     }
     return async (input, init) => {
         const outbound = new Request(input, init);
@@ -55,6 +70,30 @@ export function integrationFetch({ env, provider, for: target, }) {
             return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
         }
         if (integration.mode === "oauth_client") {
+            // A call to the provider's API with the token the gateway holds
+            // (docs/design/2026-10-oauth-providers.md section 7), for an entry
+            // that supports the Gateway-owned flow; a token endpoint stays the
+            // app-driven call it always was.
+            const toApi = integration.flow !== undefined &&
+                upstream.protocol === "https:" &&
+                integration.api.includes(upstream.host) &&
+                !tokenEndpointFor(integration, upstream, binding && integration.hostSetting ? undefined : values);
+            if (toApi) {
+                if (binding) {
+                    if (account)
+                        headers.set(ACCOUNT_HEADER, account);
+                    applyAttribution(headers, target);
+                    return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
+                }
+                return devHeldTokenCall({
+                    provider,
+                    capability: integration,
+                    outbound,
+                    upstream,
+                    headers,
+                    values,
+                });
+            }
             return oauthClientCall({
                 provider: provider,
                 capability: integration,
@@ -92,6 +131,93 @@ export function integrationFetch({ env, provider, for: target, }) {
         return fetch(streamingRequest(upstream.toString(), outbound, headers));
     };
 }
+/**
+ * The `.dev.vars` name of a held token for `provider` in local dev
+ * (`GOOGLE_WORKSPACE_ACCESS_TOKEN`, `GITHUB_ACCESS_TOKEN`): a token the
+ * developer obtained themselves, standing in for the connection the
+ * gateway would hold. Dev-only: the gateway never reads it.
+ */
+export function devAccessTokenName(provider) {
+    return `${providerSettingPrefix(provider)}ACCESS_TOKEN`;
+}
+/**
+ * An app's call to an OAuth provider's API in local dev, with no
+ * gateway: the gateway's held-token checks in its order (the app's
+ * declared sets, the method, the route), then the developer's own token
+ * from `.dev.vars` as the bearer, straight to the provider.
+ */
+async function devHeldTokenCall({ provider, capability, outbound, upstream, headers, values, }) {
+    const token = stringValue(values[devAccessTokenName(provider)]);
+    if (!token) {
+        return devRefusal(409, "integration_not_connected", `${capability.label} isn't connected here. In local dev, set ${devAccessTokenName(provider)} in .dev.vars to a token you obtained yourself; deployed, the person connects at /connect/${provider}.`, { connectPath: `/connect/${provider}`, reconnect: false });
+    }
+    const policy = capability.scopePolicy;
+    const grant = policy
+        ? devScopeSets(policy, provider, capability.label, values, "any")
+        : null;
+    if (grant && "problem" in grant) {
+        return devRefusal(403, grant.code, grant.problem);
+    }
+    const method = outbound.method.toUpperCase();
+    const reads = oauthReadMethods(capability).includes(method);
+    const writes = !reads &&
+        capability.access.includes("write") &&
+        oauthWriteMethods(capability).includes(method) &&
+        devDeclaredAccess(provider, values) === "write";
+    if (policy && grant) {
+        const allowed = heldTokenCallAllowed({
+            policy,
+            declaredSets: grant.sets,
+            // The developer's token stands for a connection granted every set.
+            connectionSets: grant.sets,
+            hosts: capability.api,
+            method,
+            upstream,
+            readMethods: oauthReadMethods(capability),
+            writes,
+        });
+        if (!allowed.ok) {
+            const status = {
+                integration_not_connected: 409,
+                integration_method_not_allowed: 405,
+                integration_scope_not_allowed: 403,
+            }[allowed.code];
+            return devRefusal(status, allowed.code, allowed.code === "integration_not_connected"
+                ? `${capability.label} is connected without ${allowed.missingSets.join(", ")}.`
+                : allowed.message);
+        }
+    }
+    else if (!reads && !writes) {
+        return devRefusal(405, "integration_method_not_allowed", `${capability.label} calls may use ${oauthReadMethods(capability).join(" or ")} with access: "read"; ${method} needs access: "write" in the app's capabilities entry, on a provider that offers it.`);
+    }
+    applyAttribution(headers, undefined);
+    headers.set("authorization", `Bearer ${token}`);
+    for (const name of ["access_token", "token"]) {
+        upstream.searchParams.delete(name);
+    }
+    headers.delete("x-http-method-override");
+    return fetch(new Request(upstream.toString(), {
+        method,
+        headers,
+        body: method === "GET" || method === "HEAD" ? null : outbound.body,
+        signal: outbound.signal,
+        // As the gateway: the token never follows a redirect.
+        redirect: "manual",
+        ...(method === "GET" || method === "HEAD" ? {} : { duplex: "half" }),
+    }));
+}
+/** The `access` the manifest entry for `provider` declares in dev (EVERYAPP_DEV_CAPABILITIES), or null. */
+function devDeclaredAccess(provider, values) {
+    const raw = values["EVERYAPP_DEV_CAPABILITIES"];
+    try {
+        const capabilities = typeof raw === "string" ? jsonRecord(JSON.parse(raw)) : undefined;
+        const entry = jsonRecord(capabilities?.[provider]);
+        return typeof entry?.["access"] === "string" ? entry["access"] : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The developer's own key or client from `.dev.vars` (with EVERYAPP_DEV
  * set), under the gateway's names; null until every setting it needs is.
@@ -125,6 +251,9 @@ async function oauthClientCall({ provider, capability, outbound, upstream, heade
         return binding.fetch(streamingRequest(`${BINDING_ORIGIN}${integrationProxyPath(provider, upstream)}`, outbound, headers));
     }
     applyAttribution(headers, undefined);
+    if (!client) {
+        throw new ConfigurationError(`${capability.label}'s token endpoints need the client in .dev.vars for local development: set ${capabilitySettings(capability).join(", ")}.`);
+    }
     // The gateway's scope checks, in its order, answering its refusals: an
     // app sees in `everyapp dev` what the gateway will say.
     const policy = capability.scopePolicy;
@@ -173,13 +302,15 @@ async function oauthClientCall({ provider, capability, outbound, upstream, heade
  * `x-everyapp-error`) from the local-dev twin, so {@link gatewayRefusal}
  * reads it the same way.
  */
-function devRefusal(status, code, message) {
+function devRefusal(status, code, message, extra = {}) {
     const labels = {
         400: "Bad Request",
         403: "Forbidden",
+        405: "Method Not Allowed",
+        409: "Conflict",
         502: "Bad Gateway",
     };
-    return Response.json({ error: labels[status] ?? "Error", code, message }, { status, headers: { [GATEWAY_ERROR_HEADER]: code } });
+    return Response.json({ error: labels[status] ?? "Error", code, message, ...extra }, { status, headers: { [GATEWAY_ERROR_HEADER]: code } });
 }
 /**
  * The scope sets the manifest declares for `id`, read from
@@ -191,7 +322,9 @@ function devRefusal(status, code, message) {
  * doesn't offer). Fails closed like the gateway: a hand-rolled dev harness
  * that passes no capabilities gets nothing.
  */
-function devScopeSets(policy, id, label, values) {
+function devScopeSets(policy, id, label, values, 
+/** The grant the entry needs: `write` for a token-endpoint call (the app-driven flow), `any` for a held-token call. */
+grant = "write") {
     const offered = Object.keys(policy.sets).join(", ");
     const raw = values["EVERYAPP_DEV_CAPABILITIES"];
     let capabilities;
@@ -211,11 +344,16 @@ function devScopeSets(policy, id, label, values) {
     const entry = Object.hasOwn(capabilities, id)
         ? jsonRecord(capabilities[id])
         : undefined;
-    // The gateway's check 2: listing the client for writing is the grant.
-    if (entry?.["access"] !== "write") {
+    // The gateway's check 2: listing the client for writing is the grant
+    // of the app-driven flow; a held-token call takes any listing.
+    const access = entry?.["access"];
+    if (!entry ||
+        (grant === "write"
+            ? access !== "write"
+            : access !== "read" && access !== "write")) {
         return {
             code: "capability_not_requested",
-            problem: `This app doesn't list ${label} in its capabilities. Add capabilities: { ${JSON.stringify(id)}: { access: "write" } } to everyapp.config.ts and start everyapp dev again.`,
+            problem: `This app doesn't list ${label} in its capabilities. Add capabilities: { ${JSON.stringify(id)}: { access: "${grant === "write" ? "write" : "read"}" } } to everyapp.config.ts and start everyapp dev again.`,
         };
     }
     const sets = declaredScopeSets(policy, entry);
@@ -315,6 +453,8 @@ async function checkTokenResponse(policy, capability, sets, response) {
             google: "Ask for only the scopes integrationStatus() returns, without include_granted_scopes, and connect again; if the app needs more, add the scope set to everyapp.config.ts and deploy.",
             microsoft: "On a shared Microsoft client a token carries everything the person consented to this client: have them remove this app's consent at https://myapplications.microsoft.com and connect again, or add the scope set to everyapp.config.ts and deploy.",
             slack: "Slack scopes add up per workspace installation: reinstall the app in the workspace with only the status's scopes, or add the scope set to everyapp.config.ts and deploy.",
+            space: "Ask for only the scopes integrationStatus() returns and connect again, or add the scope set to everyapp.config.ts and deploy.",
+            comma: "Ask for only the scopes integrationStatus() returns and connect again, or add the scope set to everyapp.config.ts and deploy.",
         }[policy.dialect];
         return devRefusal(403, "integration_scope_exceeded", `${capability.label} granted scopes this app doesn't declare: ${excess.join(", ")}. It declares ${sets.join(", ")} (${requestedScopes(policy, sets).scopes.join(", ")}). Nothing was passed on. ${remedy}`);
     }
@@ -431,9 +571,31 @@ function devOAuthClientStatus(id, capability, values) {
         : null;
     const origin = oauthClientOrigin(capability, values);
     const policy = capability.scopePolicy;
+    // An entry with a Gateway-owned flow is listed for reading or writing;
+    // the app-driven flow alone needs the write grant.
     const grant = policy
-        ? devScopeSets(policy, id, capability.label, values)
+        ? devScopeSets(policy, id, capability.label, values, capability.flow ? "any" : "write")
         : null;
+    // The Gateway-owned flow's fields, in dev: a token in `.dev.vars`
+    // stands for a connection granted every declared set.
+    const flow = capability.flow ? "both" : "app";
+    const devToken = capability.flow
+        ? stringValue(values[devAccessTokenName(id)])
+        : undefined;
+    const gateway = (sets) => capability.flow
+        ? {
+            flow,
+            connectPath: `/connect/${id}`,
+            connection: devToken
+                ? {
+                    account: "user",
+                    label: devAccessTokenName(id),
+                    scopeSets: sets,
+                    ready: true,
+                }
+                : null,
+        }
+        : { flow };
     if (grant && "problem" in grant) {
         if (grant.code === "capability_not_requested") {
             return { requested: false, configured: false, ready: false };
@@ -443,16 +605,17 @@ function devOAuthClientStatus(id, capability, values) {
             configured: Boolean(client),
             ready: false,
             scopeSets: [],
+            ...gateway([]),
         };
     }
     const asked = policy && grant ? requestedScopes(policy, grant.sets) : null;
     return {
         requested: true,
         configured: Boolean(client),
-        ready: Boolean(client),
+        ready: Boolean(client) || Boolean(devToken),
         ...(client ? { clientId: client.clientId } : {}),
         ...(client && origin ? { origin } : {}),
-        ...(client && grant && asked
+        ...((client || devToken) && grant && asked
             ? {
                 scopeSets: grant.sets,
                 scopes: asked.scopes,
@@ -461,6 +624,7 @@ function devOAuthClientStatus(id, capability, values) {
                     : {}),
             }
             : {}),
+        ...gateway(grant?.sets ?? []),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-app/sdk",
-  "version": "0.3.0-rc.2",
+  "version": "0.3.0-rc.3",
   "license": "MIT",
   "type": "module",
   "exports": {