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

package/dist/internal/signInProviders.js

@@ -0,0 +1,245 @@
+/**
+ * The sign-in providers a Gateway can offer beside passwords ("Continue
+ * with Google"), as data: what each one is called, the Worker secrets it
+ * reads, where the OAuth app is made, the scopes asked for and which claim
+ * becomes the email. One catalog serves the Gateway (which providers are
+ * on, the sign-in page's buttons, Manage workspace → Sign-in), the CLI
+ * (`everyapp signin add|list|show|remove`, `secret set`), the manifest
+ * validator (an app's own secret can never take one of these names) and
+ * the docs' drift tests.
+ *
+ * Naming rule, agreed with the provider registry's conventions
+ * (docs/design/2026-10-provider-registry.md, section 6): a sign-in
+ * provider's settings are `<ID>_SIGNIN_<FIELD>`, with FIELD one of
+ * CLIENT_ID, CLIENT_SECRET, ISSUER, LABEL or TENANT. The `_SIGNIN_` infix is
+ * what keeps the family apart from the API providers' `<ID>_API_KEY`,
+ * `<ID>_CLIENT_ID` (the OAuth clients the Gateway holds for apps) and the
+ * MCP apps' `<ID>_MCP_TOKEN`: `GOOGLE_SIGNIN_CLIENT_ID` is the sign-in
+ * provider's, `GOOGLE_WORKSPACE_CLIENT_ID` the OAuth client apps use, and
+ * a registered provider row or an app manifest can never claim a name in
+ * the family (isSignInSettingName).
+ *
+ * The settings are Worker secrets, set under the Cloudflare login (`everyapp
+ * signin add`, or `secret set`), never from the admin UI or an agent
+ * connection: a stolen session can't add a way in.
+ */
+export const SIGN_IN_PROVIDER_IDS = [
+    "google",
+    "microsoft",
+    "github",
+    "apple",
+    "cloudflare",
+    "oidc",
+];
+/** The path Better Auth serves the provider's callback on, under the Gateway's URL. */
+export function signInCallbackPath(id) {
+    return `/api/auth/callback/${id}`;
+}
+/** The redirect URL to register with the provider, for a Gateway at `gatewayUrl`. */
+export function signInCallbackUrl(gatewayUrl, id) {
+    return `${gatewayUrl.replace(/\/+$/, "")}${signInCallbackPath(id)}`;
+}
+function settingName(id, field) {
+    return `${id.toUpperCase()}_SIGNIN_${field}`;
+}
+function clientPair(id, what) {
+    return [
+        {
+            name: settingName(id, "CLIENT_ID"),
+            role: "clientId",
+            required: true,
+            plain: true,
+            what: what.clientId,
+        },
+        {
+            name: settingName(id, "CLIENT_SECRET"),
+            role: "clientSecret",
+            required: true,
+            plain: false,
+            what: what.clientSecret,
+        },
+    ];
+}
+const IDENTITY_SCOPES = ["openid", "email", "profile"];
+export const SIGN_IN_PROVIDERS = {
+    google: {
+        id: "google",
+        label: "Google",
+        console: "https://console.cloud.google.com/apis/credentials",
+        appNoun: "OAuth client ID (Web application)",
+        settings: clientPair("google", {
+            clientId: "The OAuth client's Client ID (ends in .apps.googleusercontent.com)",
+            clientSecret: "The OAuth client's Client secret",
+        }),
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email`, counted as verified only when its `email_verified` is true (every Google account's own address is)",
+        setup: "setup/signin-google.md",
+        notes: [
+            "An OAuth consent screen still in Testing only signs in the test users listed on it; publish it for everyone else.",
+        ],
+    },
+    microsoft: {
+        id: "microsoft",
+        label: "Microsoft",
+        console: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade",
+        appNoun: "App registration",
+        settings: [
+            ...clientPair("microsoft", {
+                clientId: "The app registration's Application (client) ID",
+                clientSecret: "A client secret from Certificates & secrets (it expires; 24 months at most)",
+            }),
+            {
+                name: settingName("microsoft", "TENANT"),
+                role: "tenant",
+                required: false,
+                plain: true,
+                what: "The Directory (tenant) ID to pin sign-in to your own directory; unset means any Microsoft account (common), which then needs the xms_edov claim",
+            },
+        ],
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email`, counted as verified when MICROSOFT_SIGNIN_TENANT pins your own directory, or the token carries `xms_edov: true` (the optional claim that says the domain's owner verified it), `email_verified: true`, a matching `verified_primary_email`, or comes from a personal Microsoft account",
+        setup: "setup/signin-microsoft.md",
+        notes: [
+            "Without MICROSOFT_SIGNIN_TENANT, add the optional claims `email` and `xms_edov` under Token configuration, or every sign-in is refused as unverified: any tenant's admin can put any address on their users.",
+        ],
+    },
+    github: {
+        id: "github",
+        label: "GitHub",
+        console: "https://github.com/settings/developers",
+        appNoun: "OAuth App",
+        settings: clientPair("github", {
+            clientId: "The OAuth App's Client ID",
+            clientSecret: "A client secret generated on the OAuth App",
+        }),
+        scopes: ["read:user", "user:email"],
+        emailClaim: "the primary address from GitHub's emails API, counted as verified only when GitHub marks it verified",
+        setup: "setup/signin-github.md",
+        notes: [
+            "GitHub Apps are something else: make an OAuth App (Settings → Developer settings → OAuth Apps).",
+        ],
+    },
+    apple: {
+        id: "apple",
+        label: "Apple",
+        console: "https://developer.apple.com/account/resources/identifiers/list/serviceId",
+        appNoun: "Services ID",
+        settings: clientPair("apple", {
+            clientId: "The Services ID's identifier (com.example.gateway)",
+            clientSecret: "The client secret JWT you generate from your Sign in with Apple key (ES256; valid six months at most, then generate it again)",
+        }),
+        scopes: ["email", "name"],
+        emailClaim: "the ID token's `email`, counted as verified only when its `email_verified` is true; someone who chose Hide My Email arrives as a @privaterelay.appleid.com address, which no invitation names",
+        setup: "setup/signin-apple.md",
+        notes: [
+            "Apple returns to the Gateway with a POST; behind the outer ring, `everyapp access on` leaves /api/auth/callback/apple public (it only redirects to the same URL as a GET, which Access then checks).",
+            "The client secret is a JWT that expires within six months: generate a new one before then or sign-in stops.",
+        ],
+    },
+    cloudflare: {
+        id: "cloudflare",
+        label: "Cloudflare",
+        console: "https://dash.cloudflare.com/?to=/:account/oauth-clients",
+        appNoun: "OAuth client (Manage Account → OAuth clients)",
+        settings: clientPair("cloudflare", {
+            clientId: "The OAuth client's Client ID",
+            clientSecret: "The OAuth client's Client secret",
+        }),
+        scopes: ["user-details.read"],
+        emailClaim: "the Cloudflare API's /user `email` (the account's sign-in address). Cloudflare reports no verified flag, so the email counts as verified on the strength of the client being private: only members of your Cloudflare account can authorize it, and they got in by accepting an invitation sent to that address",
+        setup: "setup/signin-cloudflare.md",
+        notes: [
+            "Keep the client private (the default): a public client lets any Cloudflare user sign in, and Cloudflare says nothing about whether their address is verified. Making a client public is permanent.",
+            "The Cloudflare account's members sign in; for everyone else use Cloudflare Access's one-time PIN (`everyapp access on`) or another provider.",
+        ],
+    },
+    oidc: {
+        id: "oidc",
+        label: "SSO",
+        console: "your identity provider's admin console",
+        appNoun: "OpenID Connect client (web application, authorization code)",
+        settings: [
+            {
+                name: settingName("oidc", "ISSUER"),
+                role: "issuer",
+                required: true,
+                plain: true,
+                what: "The issuer URL (https://…), which serves /.well-known/openid-configuration",
+            },
+            ...clientPair("oidc", {
+                clientId: "The client ID",
+                clientSecret: "The client secret",
+            }),
+            {
+                name: settingName("oidc", "LABEL"),
+                role: "label",
+                required: false,
+                plain: true,
+                what: 'The button text after "Continue with" (default "SSO")',
+            },
+        ],
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email` (else the userinfo endpoint's), counted as verified only when `email_verified` is true",
+        setup: "setup/signin-oidc.md",
+        notes: [
+            "Cloudflare Access has its own settings (CLOUDFLARE_ACCESS_OIDC_*, `everyapp access`): use those for Access, this for Okta, Keycloak, Auth0, Authentik, Google Workspace as an OIDC issuer and the like. For Microsoft Entra ID use the `microsoft` provider: Entra's ID tokens carry no `email_verified`, so through this entry every sign-in would be refused as unverified.",
+            "ID tokens must be signed with RS256 (every major provider's default).",
+        ],
+    },
+};
+/** The catalog in listing order. */
+export const SIGN_IN_PROVIDER_LIST = SIGN_IN_PROVIDER_IDS.map((id) => SIGN_IN_PROVIDERS[id]);
+export function isSignInProviderId(value) {
+    return SIGN_IN_PROVIDER_IDS.includes(value);
+}
+/**
+ * Every setting a sign-in provider reads, in catalog order: what `everyapp
+ * secret set` accepts for the Gateway, and what the Gateway's dev config
+ * declares.
+ */
+export const SIGN_IN_GATEWAY_SETTINGS = SIGN_IN_PROVIDER_LIST.flatMap((provider) => provider.settings.map((setting) => setting.name));
+/** The plain (non-credential) ones among them: ids, the issuer, the label, the tenant. */
+export const PLAIN_SIGN_IN_SETTINGS = SIGN_IN_PROVIDER_LIST.flatMap((provider) => provider.settings
+    .filter((setting) => setting.plain)
+    .map((setting) => setting.name));
+/**
+ * The family: any name of the shape `<ID>_SIGNIN_<FIELD>`. Reserved for the
+ * catalog above, whether or not an entry reads the name today, so no
+ * registered provider row and no app manifest can ever take one.
+ */
+export const SIGN_IN_SETTING_PATTERN = /^[A-Z][A-Z0-9_]*_SIGNIN_(CLIENT_ID|CLIENT_SECRET|ISSUER|LABEL|TENANT)$/;
+export function isSignInSettingName(name) {
+    return SIGN_IN_SETTING_PATTERN.test(name);
+}
+/** The provider a setting belongs to, if one reads it. */
+export function signInProviderOfSetting(name) {
+    for (const provider of SIGN_IN_PROVIDER_LIST) {
+        if (provider.settings.some((setting) => setting.name === name)) {
+            return provider;
+        }
+    }
+    return null;
+}
+/**
+ * A provider's state from which of its settings exist: on when every
+ * required one is set, off when none at all is, incomplete in between (the
+ * Gateway refuses to half-configure a sign-in: the provider is off and the
+ * problem is reported).
+ */
+export function signInProviderState(provider, isSet) {
+    const set = provider.settings
+        .filter((setting) => isSet(setting.name))
+        .map((setting) => setting.name);
+    const unset = provider.settings
+        .filter((setting) => setting.required && !isSet(setting.name))
+        .map((setting) => setting.name);
+    const status = unset.length === 0 ? "on" : set.length === 0 ? "off" : "incomplete";
+    // `missing` names what a half-set provider still needs; a provider nobody
+    // started setting up isn't missing anything, it is off.
+    return {
+        id: provider.id,
+        status,
+        missing: status === "incomplete" ? unset : [],
+        set,
+    };
+}

package/dist/server/ai.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `ai()`: the Gateway's default chat model for an app that needs "a model"
+ * rather than one provider (docs/design/2026-10-model-providers.md). The
+ * manifest says `ai: { chat: true }` (or `{ chat: { why } }`); the Gateway's
+ * operator decides which provider and model that is (`everyapp ai
+ * default`, else OpenRouter → Workers AI → OpenAI → …, the first with its
+ * key set), and the app never names either: it sends OpenAI-shaped chat
+ * completions (and embeddings) to `/api/ai/default/v1/…` with `model:
+ * "default"` or no model at all, and the Gateway fills the model in.
+ *
+ * An OpenAI client takes `baseURL` and `fetch` as they are:
+ *
+ *   const { baseURL, fetch, model } = ai({ env, for: request });
+ *   const client = new OpenAI({ baseURL, fetch, apiKey: "gateway-managed" });
+ *   await client.chat.completions.create({ model, messages });
+ *
+ * In local development with no Gateway, the developer's own key in
+ * `.dev.vars` decides the provider by the same order (createGatewayFetch's
+ * fallback). An app that needs one provider in particular keeps listing it
+ * under `providers` and calling `/api/ai/<provider>/…`.
+ */
+import { AI_DEFAULT_MODEL } from "../internal/index.js";
+import { type CreateGatewayFetchOptions } from "./gatewayFetch.js";
+export interface AiClient {
+    /** `http://every-app-gateway.internal/api/ai/default/v1`: an OpenAI client's base URL. */
+    baseURL: string;
+    /** The fetch that reaches the Gateway (or, in dev, the provider directly). */
+    fetch: typeof fetch;
+    /** The model name that means "whatever the Gateway's default is": `default`. */
+    model: typeof AI_DEFAULT_MODEL;
+    /** The default route's chat completions URL, for a plain `fetch`. */
+    chatCompletionsUrl: string;
+    /** The default route's embeddings URL, for a plain `fetch`. */
+    embeddingsUrl: string;
+}
+/** The base URL of the default route, as the SDK and the docs name it. */
+export declare const AI_DEFAULT_BASE_URL = "http://every-app-gateway.internal/api/ai/default/v1";
+/**
+ * The Gateway's default chat model as a client: a base URL, a fetch and
+ * the model name to send. Throws `ConfigurationError` where
+ * `createGatewayFetch` does (no binding and no dev key) and
+ * `AttributionError` where a shared app's call says nobody's.
+ */
+export declare function ai(options: CreateGatewayFetchOptions): AiClient;
+//# sourceMappingURL=ai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/server/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,OAAO,gBAAgB,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,wDAAuD,CAAC;AAExF;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,OAAO,EAAE,yBAAyB,GAAG,QAAQ,CAQ/D"}

package/dist/server/ai.js

@@ -0,0 +1,40 @@
+/**
+ * `ai()`: the Gateway's default chat model for an app that needs "a model"
+ * rather than one provider (docs/design/2026-10-model-providers.md). The
+ * manifest says `ai: { chat: true }` (or `{ chat: { why } }`); the Gateway's
+ * operator decides which provider and model that is (`everyapp ai
+ * default`, else OpenRouter → Workers AI → OpenAI → …, the first with its
+ * key set), and the app never names either: it sends OpenAI-shaped chat
+ * completions (and embeddings) to `/api/ai/default/v1/…` with `model:
+ * "default"` or no model at all, and the Gateway fills the model in.
+ *
+ * An OpenAI client takes `baseURL` and `fetch` as they are:
+ *
+ *   const { baseURL, fetch, model } = ai({ env, for: request });
+ *   const client = new OpenAI({ baseURL, fetch, apiKey: "gateway-managed" });
+ *   await client.chat.completions.create({ model, messages });
+ *
+ * In local development with no Gateway, the developer's own key in
+ * `.dev.vars` decides the provider by the same order (createGatewayFetch's
+ * fallback). An app that needs one provider in particular keeps listing it
+ * under `providers` and calling `/api/ai/<provider>/…`.
+ */
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER } from "../internal/index.js";
+import { BINDING_ORIGIN, createGatewayFetch, } from "./gatewayFetch.js";
+/** The base URL of the default route, as the SDK and the docs name it. */
+export const AI_DEFAULT_BASE_URL = `${BINDING_ORIGIN}/api/ai/${AI_DEFAULT_PROVIDER}/v1`;
+/**
+ * The Gateway's default chat model as a client: a base URL, a fetch and
+ * the model name to send. Throws `ConfigurationError` where
+ * `createGatewayFetch` does (no binding and no dev key) and
+ * `AttributionError` where a shared app's call says nobody's.
+ */
+export function ai(options) {
+    return {
+        baseURL: AI_DEFAULT_BASE_URL,
+        fetch: createGatewayFetch(options),
+        model: AI_DEFAULT_MODEL,
+        chatCompletionsUrl: `${AI_DEFAULT_BASE_URL}/chat/completions`,
+        embeddingsUrl: `${AI_DEFAULT_BASE_URL}/embeddings`,
+    };
+}

package/dist/server/connectUrl.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectionAccount } from "../internal/index.js";
+export interface ConnectUrlOptions {
+    /** The Worker env: `GATEWAY_URL`, which every deployed Worker and `everyapp dev` set. */
+    env: object;
+    /** The OAuth provider's id (`google-workspace`, `github`). */
+    provider: string;
+    /**
+     * Where to send the person afterwards: the app's own URL (absolute) or
+     * a path on the Gateway. Absent: Settings → Connected accounts.
+     */
+    returnTo?: string;
+    /** Whose connection to make: the person's (default) or the organization's (owner or admin). */
+    account?: ConnectionAccount;
+    /** Scope sets to ask for; absent: the union every active app that lists the provider declares. */
+    sets?: readonly string[];
+}
+/** The path of the connect page for `provider` on the Gateway. */
+export declare function connectPath(provider: string): string;
+/** The absolute URL that starts the Gateway-owned flow for `provider`. */
+export declare function connectUrl({ env, provider, returnTo, account, sets, }: ConnectUrlOptions): string;
+//# sourceMappingURL=connectUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectUrl.d.ts","sourceRoot":"","sources":["../../src/server/connectUrl.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,kGAAkG;IAClG,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,EACzB,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,IAAI,GACL,EAAE,iBAAiB,GAAG,MAAM,CAmB5B"}

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;