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

package/dist/server/gatewayFetch.js

@@ -1,24 +1,66 @@
-import { aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, devAiProvider, joinProviderUrl, } from "../internal/index.js";
-import { applyAttribution, checkAttribution, } from "./attribution.js";
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, AI_DEFAULT_ROUTES, aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, DEV_ENV, devAiProvider, joinProviderUrl, LINKED_DEV_HEADER, LINKED_DEV_NONCE_ENV, LINKED_DEV_URL_ENV, resolveAiDefault, } from "../internal/index.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
 export const BINDING_ORIGIN = "http://every-app-gateway.internal";
 const AI_PROXY_PREFIX = "/api/ai/";
 /**
- * Create a fetch for the gateway's AI providers (`/api/ai/<provider>/…`),
- * backed by the private gateway service binding. In local dev only, the
- * developer's own provider key from `.dev.vars` is a direct-provider
- * fallback when no binding exists.
+ * The Gateway the SDK's services call: the `EVERY_APP_GATEWAY` service
+ * binding when deployed; under `everyapp dev --gateway` (linked dev,
+ * docs/design/linked-dev.md) a `{ fetch }` that sends the same requests to
+ * the gateway-lite's loopback forwarder, which adds the person's token and
+ * forwards them to the real Gateway's `/linked-dev/<app>` route. Undefined
+ * with neither (stub and mirror modes: the `.dev.vars` fallbacks). A value
+ * under the binding's name that isn't one is answered as before by each
+ * caller (`ConfigurationError`).
  */
-export function createGatewayFetch({ env, for: target, }) {
-    checkAttribution(env, target, "createGatewayFetch");
-    const binding = env.EVERY_APP_GATEWAY;
+export function gatewayBinding(env) {
+    const values = env;
+    const binding = values["EVERY_APP_GATEWAY"];
+    if (binding)
+        return binding;
+    if (!values[DEV_ENV])
+        return undefined;
+    const url = values[LINKED_DEV_URL_ENV];
+    const nonce = values[LINKED_DEV_NONCE_ENV];
+    if (typeof url !== "string" || !url.trim() || typeof nonce !== "string") {
+        return undefined;
+    }
+    return linkedDevBinding(url.trim(), nonce);
+}
+/**
+ * The linked dev shim: a request to the binding's origin goes to the
+ * forwarder's URL with the same path and query, the run's nonce on it. The
+ * forwarder answers as the Gateway did, refusals included; nothing here
+ * falls back to a local key.
+ */
+export function linkedDevBinding(forwarderUrl, nonce) {
+    const base = forwarderUrl.replace(/\/+$/, "");
+    return {
+        fetch(input, init) {
+            const outbound = new Request(input, init);
+            const url = new URL(outbound.url);
+            const headers = new Headers(outbound.headers);
+            headers.set(LINKED_DEV_HEADER, nonce);
+            return fetch(streamingRequest(`${base}${url.pathname}${url.search}`, outbound, headers));
+        },
+    };
+}
+export function createGatewayFetch({ env: workerEnv, for: explicitTarget, optional = false, }) {
+    const env = workerEnv;
+    // Checked now, so a call nobody's fails where the fetch is made; and
+    // again per call, where an identity may since have neared its expiry.
+    attributionFor(env, explicitTarget, "createGatewayFetch");
+    const binding = gatewayBinding(env);
     const devProviders = env.EVERYAPP_DEV ? localProviders(env) : {};
     if (binding && typeof binding.fetch !== "function") {
         throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
     }
     if (!binding && Object.keys(devProviders).length === 0) {
-        throw new ConfigurationError(`AI gateway unavailable: deploy with the EVERY_APP_GATEWAY binding, or set the provider's key (${listOf(Object.values(DEV_AI_PROVIDERS).map((spec) => settingsNames(spec, "with")), "or")}) in .dev.vars for direct local development.`);
+        if (optional)
+            return null;
+        throw new ConfigurationError(`AI gateway unavailable: deploy with the EVERY_APP_GATEWAY binding, or set the provider's key (${listOf(Object.values(DEV_AI_PROVIDERS).map((spec) => settingsNames(spec, "with")), "or")}) in .dev.vars for direct local development.`, { code: "ai_provider_not_configured" });
     }
     return async (input, init) => {
+        const target = attributionFor(env, explicitTarget, "createGatewayFetch");
         const outbound = new Request(input, init);
         const headers = new Headers(outbound.headers);
         headers.delete("authorization");
@@ -28,15 +70,24 @@ 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.`);
+            throw new ConfigurationError(`Set ${settingsNames(spec)} in .dev.vars to call ${provider} in local development.`, {
+                code: "ai_provider_not_configured",
+                settings: aiProviderSettings(spec),
+            });
         }
         const url = joinProviderUrl(`${spec.origin}${dev.basePath}`, path, search);
         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 +97,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 +166,54 @@ 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];
-    const spec = provider ? devAiProvider(provider) : undefined;
+    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,
+        // with its seed models (dev has no operator settings; a request that
+        // names a model sends it as it is).
+        const values = env;
+        const resolution = resolveAiDefault({
+            provider: 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.`, {
+                code: "ai_default_not_configured",
+                settings: resolution.settings,
+            });
+        }
+        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 =
+            route === resolution.chat
+                ? resolution.model
+                : (resolution.embeddingsModel ?? null);
+    }
+    const spec = provider
+        ? devAiProvider(provider, env)
+        : 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/gatewayUrl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Gateway's URL, with `path` on it: `gatewayUrl(env)` for the launcher,
+ * `gatewayUrl(env, "/admin/users")` for the page where owners and admins
+ * invite people.
+ *
+ * Read from `env.GATEWAY_URL`, which the deploy sets on every Worker of the
+ * app and `everyapp dev` sets to its local launcher, so the same link works
+ * in both. `env` is the Worker's env (any object; only `GATEWAY_URL` is
+ * read). Throws {@link ConfigurationError} when it is unset or not an http(s)
+ * URL: a Worker no deploy or `everyapp dev` built.
+ */
+export declare function gatewayUrl(env: object, path?: string): string;
+//# sourceMappingURL=gatewayUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayUrl.d.ts","sourceRoot":"","sources":["../../src/server/gatewayUrl.ts"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,MAAM,CAgB1D"}

package/dist/server/gatewayUrl.js

@@ -0,0 +1,34 @@
+/**
+ * `gatewayUrl()`: the one rule for a link from an app back to its Gateway
+ * ("‹ Every App", "Invite people", "Sign out").
+ */
+import { ConfigurationError } from "../internal/index.js";
+/** Where the Gateway is: the deploy sets it, and so does `everyapp dev`. */
+const GATEWAY_URL_ENV = "GATEWAY_URL";
+/**
+ * The Gateway's URL, with `path` on it: `gatewayUrl(env)` for the launcher,
+ * `gatewayUrl(env, "/admin/users")` for the page where owners and admins
+ * invite people.
+ *
+ * Read from `env.GATEWAY_URL`, which the deploy sets on every Worker of the
+ * app and `everyapp dev` sets to its local launcher, so the same link works
+ * in both. `env` is the Worker's env (any object; only `GATEWAY_URL` is
+ * read). Throws {@link ConfigurationError} when it is unset or not an http(s)
+ * URL: a Worker no deploy or `everyapp dev` built.
+ */
+export function gatewayUrl(env, path = "/") {
+    const value = env[GATEWAY_URL_ENV];
+    let base;
+    if (typeof value === "string" && value) {
+        try {
+            base = new URL(value);
+        }
+        catch {
+            base = undefined;
+        }
+    }
+    if (!base || (base.protocol !== "https:" && base.protocol !== "http:")) {
+        throw new ConfigurationError(`${GATEWAY_URL_ENV} is ${value ? "not an http(s) URL" : "unset"}: everyapp deploy and everyapp dev set it on the app's Worker.`);
+    }
+    return new URL(path, base.origin).toString();
+}

package/dist/server/index.d.ts

@@ -3,16 +3,28 @@
  *
  * There is intentionally no client-side export.
  */
-export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, type EveryAppOptions, type EveryAppManifestLike, type EveryAppHandler, type EveryAppUser, type IdentityResult, } from "./everyApp.js";
+export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, isAdmin, isAgentCall, requireCurrentUser, requireEveryAppUser, type EveryAppOptions, type EveryAppManifestLike, type EveryAppHandler, type EveryAppUser, type IdentityResult, type OrgRole, } from "./everyApp.js";
+export { OrganizationMismatchError, RequestContextError, currentUser, withOrganization, } from "./context.js";
 export { AttributionError, type GatewayCallFor } from "./attribution.js";
-export { authorizeUrl, type AuthorizeUrlOptions } from "./authorizeUrl.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 { gatewayUrl } from "./gatewayUrl.js";
+export type { EveryAppEnv } from "./env.js";
+/** The header a Gateway refusal carries its code in; `gatewayRefusal()` reads the rest. */
+export { GATEWAY_ERROR_HEADER } from "../internal/protocol.js";
+export { connectPath, connectUrl, type ConnectUrlOptions, } from "./connectUrl.js";
+export { createGatewayFetch, type CreateGatewayFetchOptions, } from "./gatewayFetch.js";
+export { ai, aiBaseUrl, aiStatus, providerBaseUrl, AI_DEFAULT_BASE_URL, type AiClient, type AiStatus, } from "./ai.js";
+export { AI_NOT_CONFIGURED_CODES, GatewayRefusalError, gatewayRefusal, isAiNotConfigured, refusalFromError, type GatewayRefusal, type SetupInfo, } from "./refusal.js";
+export { devAccessTokenName, integrationFetch, integrationStatus, type EmailIntegrationStatus, 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 { gatewayAiBinding, type GatewayAiBindingOptions } from "./aiBinding.js";
+export { gatewayEmailBinding, type GatewayEmailBindingMessage, type GatewayEmailBindingOptions, } from "./emailBinding.js";
 export { listMembers, type ListMembersOptions } from "./listMembers.js";
 export { emit, type EmitOptions } from "./emit.js";
+export { WEBHOOK_MAX_BYTES_DEFAULT, verifyWebhook, type VerifyWebhookOptions, type WebhookProvider, type WebhookRefusalReason, type WebhookVerification, } from "./webhooks.js";
+export type { AppEvent, AppEventHandler, AppEventsOptions, } from "./eventsEndpoint.js";
 export type { ApiKeyCapabilityId, CapabilityId, OAuthClientCapabilityId, 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";
+export { fromMcpTools, type FromMcpToolsOptions, type McpToolAnnotationsLike, type McpToolLike, type McpToolResultLike, type McpToolSchemaLike, } from "./fromMcpTools.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":"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"}

package/dist/server/index.js

@@ -3,13 +3,23 @@
  *
  * There is intentionally no client-side export.
  */
-export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, } from "./everyApp.js";
+export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, isAdmin, isAgentCall, requireCurrentUser, requireEveryAppUser, } from "./everyApp.js";
+export { OrganizationMismatchError, RequestContextError, currentUser, withOrganization, } from "./context.js";
 export { AttributionError } from "./attribution.js";
-export { authorizeUrl } from "./authorizeUrl.js";
+export { gatewayUrl } from "./gatewayUrl.js";
+/** The header a Gateway refusal carries its code in; `gatewayRefusal()` reads the rest. */
+export { GATEWAY_ERROR_HEADER } from "../internal/protocol.js";
+export { connectPath, connectUrl, } from "./connectUrl.js";
 export { createGatewayFetch, } from "./gatewayFetch.js";
-export { GatewayRefusalError, gatewayRefusal, integrationFetch, integrationStatus, } from "./integrationFetch.js";
+export { ai, aiBaseUrl, aiStatus, providerBaseUrl, AI_DEFAULT_BASE_URL, } from "./ai.js";
+export { AI_NOT_CONFIGURED_CODES, GatewayRefusalError, gatewayRefusal, isAiNotConfigured, refusalFromError, } from "./refusal.js";
+export { devAccessTokenName, integrationFetch, integrationStatus, } from "./integrationFetch.js";
 export { nodeServerHandler, } from "./nodeServer.js";
 export { sendEmail } from "./sendEmail.js";
+export { gatewayAiBinding } from "./aiBinding.js";
+export { gatewayEmailBinding, } from "./emailBinding.js";
 export { listMembers } from "./listMembers.js";
 export { emit } from "./emit.js";
+export { WEBHOOK_MAX_BYTES_DEFAULT, verifyWebhook, } from "./webhooks.js";
 export { ToolError, defineTools, toolResult, } from "./tools.js";
+export { fromMcpTools, } from "./fromMcpTools.js";

package/dist/server/integrationFetch.d.ts

@@ -1,29 +1,49 @@
 import { type ApiKeyCapabilityId, type CapabilityId, type EmailCapabilityStatus, type OAuthClientCapabilityId } from "../internal/index.js";
 import { type GatewayCallFor } from "./attribution.js";
+import type { SetupInfo } from "./refusal.js";
 export interface IntegrationFetchOptions {
     /**
      * The Worker env: the EVERY_APP_GATEWAY binding when deployed, or in local
      * dev EVERYAPP_DEV and the provider's key (e.g. DATAFORSEO_API_KEY in
-     * `.dev.vars`).
+     * `.dev.vars`), or for an OAuth provider a token you obtained yourself
+     * (`GOOGLE_WORKSPACE_ACCESS_TOKEN`, {@link devAccessTokenName}).
      */
     env: object;
     /**
      * A provider the app lists in its manifest's `capabilities`: one whose
-     * key the gateway holds, or one whose OAuth client it holds (its token
-     * endpoints only). The built-in catalog's ids complete; a provider
-     * registered on the gateway (`everyapp provider add`) is any other id,
-     * reached through the binding, which checks it. The `email` capability
-     * is sent with `sendEmail()` instead.
+     * key the gateway holds, or an OAuth provider whose connections it
+     * holds. The built-in catalog's ids complete; a provider registered on
+     * the gateway (`everyapp provider add`) is any other id, reached
+     * through the binding, which checks it. The `email` capability is sent
+     * with `sendEmail()` instead.
      */
     provider: ApiKeyCapabilityId | OAuthClientCapabilityId | (string & {});
     /**
-     * Whom the call is for: the inbound request (its user), or
-     * `{ background: true, organizationId }` for work no person started
-     * (crons, Workflows, queues). An organization's own app may omit it for
-     * background work, which is then the app's; a shared app's Worker must
-     * pass one or the other ({@link AttributionError}).
+     * Whom the call is for. Left out, the request `everyApp()` is serving
+     * (its person, while the identity is good) or the organization
+     * `withOrganization()` named; outside both, `RequestContextError`.
+     * Explicitly: the inbound request, or `{ background: true,
+     * organizationId }` for work no person started (crons, Workflows,
+     * queues). A shared app's Worker must end up with one or the other
+     * ({@link AttributionError}).
+     *
+     * For an OAuth provider the call uses the connection the person behind
+     * it made in this app. `{ background: true, userId }` names another
+     * member's connection to this app instead, at any time, even while
+     * serving a different person: the call then carries that member and
+     * not the person being served. Only an organization's own app may.
      */
     for?: GatewayCallFor;
+    /**
+     * `true`: answer null instead of throwing `ConfigurationError` when the
+     * provider is unavailable (no binding, and in local dev not its
+     * settings in `.dev.vars`), so a feature that can do without it checks
+     * for null. A wrong provider id, a binding that isn't one, and an
+     * attribution mistake still throw. An OAuth provider is never
+     * unavailable this way: without a connection its calls answer
+     * `integration_not_connected`.
+     */
+    optional?: boolean;
 }
 /**
  * A `fetch` for one of the gateway's capabilities. Call the provider's real
@@ -33,22 +53,32 @@ export interface IntegrationFetchOptions {
  * sees the key. A refusal the gateway makes itself comes back as a response
  * {@link gatewayRefusal} recognizes; anything else is the provider's answer.
  *
- * For an OAuth client (`linkedin`, `mastodon`, ...) it reaches the
- * provider's token endpoints only, and the gateway puts its client on the
- * request: send the code (or refresh token) without `client_id` or
- * `client_secret`. Build the authorize URL with {@link authorizeUrl} from
- * {@link integrationStatus}, and call the provider's API with the user's
- * token directly.
+ * For an OAuth provider (`google-workspace`, `github`, ...) the gateway
+ * puts the token of the person's connection in this app on the call, to
+ * the provider's API hosts only. Without one the answer is a 409
+ * `integration_not_connected` refusal with the `connectPath` to send the
+ * person to ({@link connectUrl}).
  *
- * In local dev only, with no binding, the developer's own key or client
- * from `.dev.vars` reaches the provider directly, under the gateway's names:
+ * In local dev only, with no binding, the developer's own key from
+ * `.dev.vars` reaches the provider directly, under the gateway's names:
  * a catalog provider's from the catalog, a provider registered on the
  * gateway from its spec in `.everyapp/providers/<id>.json` (`everyapp
  * provider show <id> --save` writes it), put on the call as the gateway's
- * spec says.
+ * spec says. An OAuth provider's calls carry a token you obtained
+ * yourself ({@link devAccessTokenName}), to its API hosts only.
+ */
+export declare function integrationFetch(options: IntegrationFetchOptions & {
+    optional: true;
+}): typeof fetch | null;
+export declare function integrationFetch(options: 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 integrationFetch({ env, provider, for: target, }: IntegrationFetchOptions): typeof fetch;
-export interface IntegrationStatus {
+export declare function devAccessTokenName(provider: string): string;
+export interface IntegrationStatus extends SetupInfo {
     /** The app's manifest lists the capability. */
     requested: boolean;
     /** The gateway holds a key for it (in local dev: `.dev.vars` sets one). */
@@ -64,68 +94,57 @@ export interface IntegrationStatus {
  */
 export type EmailIntegrationStatus = IntegrationStatus & Pick<EmailCapabilityStatus, "sender" | "senders" | "provider">;
 /**
- * An OAuth client's status: as {@link IntegrationStatus}, plus what the app
- * needs to send people to the provider's authorize page, present only when
- * the app lists the capability and the gateway holds the client.
+ * An OAuth provider's status: as {@link IntegrationStatus}, plus the
+ * scopes the app's manifest lists, where the person connects in this app,
+ * and their connection to this app. `configured` means the gateway holds
+ * the client; `ready` that a call for this person would go through.
  */
-export interface OAuthClientIntegrationStatus extends IntegrationStatus {
-    /** The client's public id, for the authorize URL (and Twitch's `Client-Id`). */
-    clientId?: string;
+export type OAuthClientIntegrationStatus = IntegrationStatus & {
+    /** The provider's scopes as the app's `everyapp.config.ts` lists them. */
+    scopes: readonly string[];
     /**
-     * The provider's origin when the operator chose it (Mastodon's instance,
-     * `MASTODON_URL`): the authorize page, token endpoint and API are on it.
+     * Where the person connects the provider in this app:
+     * `/connect/<id>?app=<app>` on the Gateway ({@link connectUrl} builds
+     * the absolute URL); null when the app can't connect (the manifest
+     * doesn't list it, or the gateway holds no client).
      */
-    origin?: string;
+    connectPath: string | null;
     /**
-     * For a client with scope sets (`google-workspace`, `microsoft-365`): the
-     * set names the app's manifest entry declares, `[]` when the entry voids
-     * its grant (no `scopes`, or a set this gateway doesn't offer), in which
-     * case `ready` is false and no token call can complete.
+     * The connection the call would use (the person's in this app, or the
+     * member's `for: { background: true, userId }` names), or null when there
+     * is none. `ready` false with `missingScopes` when it lacks a scope the
+     * app now lists, and `reconnect` when the person has to connect again
+     * (missing scopes, or it expired).
      */
-    scopeSets?: readonly string[];
-    /**
-     * The provider's scope strings those sets ask for, in the provider's
-     * spelling and the registry's order, for the authorize URL
-     * ({@link authorizeUrl} puts them on). The gateway refuses a token that
-     * carries more.
-     */
-    scopes?: readonly string[];
-    /** Slack's `user_scope` strings, when the sets name any. */
-    userScopes?: readonly string[];
-}
-/** The status of a capability: email's carries its senders, an OAuth client's its id. */
+    connection: {
+        /** The account's name at the provider (an email address, a login). */
+        label: string | null;
+        /** The scopes it holds, canonical. */
+        scopes: readonly string[];
+        ready: boolean;
+        missingScopes?: readonly string[];
+        reconnect?: true;
+    } | null;
+};
+/** The status of a capability: email's carries its senders, an OAuth provider's the connection. */
 export type IntegrationStatusOf<P extends string> = P extends "email" ? EmailIntegrationStatus : P extends OAuthClientCapabilityId ? OAuthClientIntegrationStatus : IntegrationStatus;
 /**
  * Whether the app can use an integration right now, without calling the
  * provider: show "an admin needs to set up DataForSEO" (or "sending isn't
- * set up") up front instead of failing mid-task. An OAuth client's status
- * carries its public `clientId` for the authorize URL.
+ * set up", or "connect Google") up front instead of failing mid-task. An
+ * OAuth provider's status carries the person's connection in this app and
+ * where to connect.
  */
-export declare function integrationStatus<P extends CapabilityId | (string & {})>({ env, provider, }: {
+export declare function integrationStatus<P extends CapabilityId | (string & {})>({ env, provider, for: explicitTarget, }: {
     env: object;
     provider: P;
+    /**
+     * Whom the status is for: the request being served (its person), so an
+     * OAuth provider's `connection` is that person's in this app; `{
+     * background: true, userId }` that member's. Explicitly the inbound
+     * request or `{ background: true, organizationId, userId? }`, as on
+     * every call.
+     */
+    for?: GatewayCallFor;
 }): Promise<IntegrationStatusOf<P>>;
-/** A refusal the AppGateway binding made itself, not the provider. */
-export interface GatewayRefusal {
-    status: number;
-    /** e.g. `capability_not_requested`, `integration_not_configured`. */
-    code: string;
-    message: string;
-}
-/**
- * A refusal the AppGateway binding made, thrown: what `sendEmail()` throws
- * when the gateway won't send (`email_sender_not_allowed`,
- * `email_budget_exhausted`, ...). The thrown twin of {@link gatewayRefusal}.
- */
-export declare class GatewayRefusalError extends Error implements GatewayRefusal {
-    readonly status: number;
-    readonly code: string;
-    constructor({ status, code, message }: GatewayRefusal);
-}
-/**
- * The gateway's own refusal in `response`, or null when the response is the
- * provider's answer (which may be an error of its own). Reads the body only
- * for a refusal, so call it before reading the body yourself.
- */
-export declare function gatewayRefusal(response: Response): Promise<GatewayRefusal | null>;
 //# sourceMappingURL=integrationFetch.d.ts.map

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":"AAAA,OAAO,EAcL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAE1B,KAAK,uBAAuB,EAK7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAO9C,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,QAAQ,EAAE,kBAAkB,GAAG,uBAAuB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACvE;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GACpD,OAAO,KAAK,GAAG,IAAI,CAAC;AACvB,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,KAAK,CAAC;AAgHhB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAsLD,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,+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;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GAAG,iBAAiB,GAAG;IAC7D,0EAA0E;IAC1E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;;OAMG;IACH,UAAU,EAAE;QACV,sEAAsE;QACtE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,sCAAsC;QACtC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1B,KAAK,EAAE,OAAO,CAAC;QACf,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,IAAI,CAAC;KAClB,GAAG,IAAI,CAAC;CACV,CAAC;AAEF,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,OAAO,GACjE,sBAAsB,GACtB,CAAC,SAAS,uBAAuB,GAC/B,4BAA4B,GAC5B,iBAAiB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,CAAC,SAAS,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EACtC,EACA,GAAG,EACH,QAAQ,EACR,GAAG,EAAE,cAAc,GACpB,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,CAAC,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAWlC"}