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

package/dist/server/everyApp.js

@@ -0,0 +1,185 @@
+/**
+ * `everyApp()` — the app-side identity boundary.
+ *
+ *   export default everyApp(handler, { tools });
+ *
+ * The wrapper verifies the gateway-injected identity before app code runs,
+ * stores the result on the original Request, and then delegates to the
+ * worker-style handler. The expected audience is the Worker's own name in
+ * `env.EVERYAPP_AUDIENCE`, which `everyAppWorker()` sets at deploy (the
+ * gateway stamps every token it mints for the app with it); only in
+ * development, where `everyapp dev` mints for the app id, does the app id in
+ * `env.EVERYAPP_APP_ID` stand in. The Worker never imports
+ * `everyapp.config.ts` (the Cloudflare Vite plugin hides every file
+ * `cloudflare.config.ts` imports from the Worker in dev).
+ * It also answers the gateway's internal tools contract
+ * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog.
+ */
+import { APP_ID_ENV, AUDIENCE_ENV, ConfigurationError, DEV_ENV, IdentityError, ISSUER_ENV, PUBLIC_KEYS_ENV, getIdentityFromRequest, } from "../internal/index.js";
+import { handleToolsRequest } from "./toolsEndpoint.js";
+export { ConfigurationError, IdentityError };
+const requestIdentities = new WeakMap();
+function envValue(env, key) {
+    if (!env || typeof env !== "object")
+        return undefined;
+    const value = env[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function configFrom(manifest, options = {}) {
+    return {
+        manifestAppId: manifest?.id,
+        issuer: options.issuer,
+        keysEnvVar: options.keysEnvVar ?? PUBLIC_KEYS_ENV,
+        publicKeys: options.publicKeys,
+        allowDevIdentities: options.allowDevIdentities,
+        now: options.now,
+    };
+}
+/**
+ * The app id: EVERYAPP_APP_ID, or a manifest passed to everyApp() for
+ * Workers without it; the two must agree when both are present.
+ */
+function appIdFor(env, config) {
+    const fromEnv = envValue(env, APP_ID_ENV);
+    if (fromEnv && config.manifestAppId && fromEnv !== config.manifestAppId) {
+        throw new ConfigurationError(`${APP_ID_ENV} ("${fromEnv}") does not match the manifest id ("${config.manifestAppId}").`);
+    }
+    return fromEnv ?? config.manifestAppId;
+}
+function devIdentitiesAllowed(env, config) {
+    const devEnv = envValue(env, DEV_ENV);
+    return (config.allowDevIdentities ??
+        (devEnv !== undefined &&
+            (devEnv === "1" || devEnv.toLowerCase() === "true")));
+}
+/**
+ * The audience identity tokens must carry: this Worker's name, from
+ * EVERYAPP_AUDIENCE. The gateway mints for the Worker, not the app id, so a
+ * token for one organization's copy of an app never opens another's. Only
+ * under the dev opt-in, where `everyapp dev` mints for the app id, does the
+ * app id stand in when EVERYAPP_AUDIENCE is unset.
+ */
+function audienceFor(env, config) {
+    const appId = appIdFor(env, config);
+    const audience = envValue(env, AUDIENCE_ENV);
+    if (audience)
+        return audience;
+    if (appId && devIdentitiesAllowed(env, config))
+        return appId;
+    throw new ConfigurationError(`${AUDIENCE_ENV} is not set — the app's cloudflare.config.ts must declare it (everyAppWorker() does at deploy).`);
+}
+function unauthorized(message) {
+    return Response.json({ error: "unauthenticated", message }, { status: 401 });
+}
+function misconfigured(message) {
+    return Response.json({ error: "misconfigured", message }, { status: 500 });
+}
+function identityOptions(env, config, audience) {
+    return {
+        audience,
+        issuer: config.issuer ?? envValue(env, ISSUER_ENV),
+        publicKeys: config.publicKeys,
+        env: env,
+        keysEnvVar: config.keysEnvVar,
+        allowDevIdentities: devIdentitiesAllowed(env, config),
+        now: config.now,
+    };
+}
+async function resolveIdentity(request, env, config) {
+    return getIdentityFromRequest(request, identityOptions(env, config, audienceFor(env, config)));
+}
+function rememberIdentity(request, identity) {
+    requestIdentities.set(request, identity);
+}
+/**
+ * Return the verified Every App user for this request, or null for a declared
+ * public request. Uses the request cache first, then verifies the identity
+ * headers from the app id and public keys configured in env.
+ */
+export async function getEveryAppUser(request, env) {
+    const cached = requestIdentities.get(request);
+    if (cached)
+        return cached.user;
+    const identity = await resolveIdentity(request, env, {
+        keysEnvVar: PUBLIC_KEYS_ENV,
+    });
+    rememberIdentity(request, identity);
+    return identity.user;
+}
+/**
+ * Return the verified user, or throw the same 401 JSON Response shape as
+ * everyApp() when the request is public or unauthenticated.
+ */
+export async function requireEveryAppUser(request, env) {
+    try {
+        const user = await getEveryAppUser(request, env);
+        if (!user) {
+            throw new IdentityError("this request does not have an authenticated user");
+        }
+        return user;
+    }
+    catch (error) {
+        if (error instanceof IdentityError) {
+            throw unauthorized(error.message);
+        }
+        throw error;
+    }
+}
+export function hasScope(user, scope) {
+    return user.scopes.includes("*") || user.scopes.includes(scope);
+}
+function isManifest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.id === "string");
+}
+export function everyApp(handler, manifestOrOptions, legacyOptions = {}) {
+    const manifest = isManifest(manifestOrOptions)
+        ? manifestOrOptions
+        : undefined;
+    const options = manifest || manifestOrOptions === undefined
+        ? legacyOptions
+        : manifestOrOptions;
+    const config = configFrom(manifest, options);
+    return {
+        async fetch(request, env, ctx) {
+            let audience;
+            let appId;
+            try {
+                audience = audienceFor(env, config);
+                appId = appIdFor(env, config) ?? audience;
+            }
+            catch (err) {
+                if (err instanceof ConfigurationError) {
+                    console.error(err);
+                    return misconfigured(err.message);
+                }
+                throw err;
+            }
+            // The reserved tools contract carries its own gateway-minted tokens and
+            // never reaches the app's handler.
+            const toolsResponse = await handleToolsRequest(request, env, ctx, {
+                toolSet: options.tools,
+                appId,
+                identity: identityOptions(env, config, audience),
+            });
+            if (toolsResponse)
+                return toolsResponse;
+            let identity;
+            try {
+                identity = await getIdentityFromRequest(request, identityOptions(env, config, audience));
+                rememberIdentity(request, identity);
+            }
+            catch (err) {
+                if (err instanceof ConfigurationError) {
+                    console.error(err);
+                    return misconfigured(err.message);
+                }
+                if (err instanceof IdentityError)
+                    return unauthorized(err.message);
+                throw err;
+            }
+            return handler(request, env, ctx, identity.user);
+        },
+    };
+}

package/dist/server/gatewayFetch.d.ts

@@ -0,0 +1,37 @@
+import { type GatewayCallFor } from "./attribution.js";
+export declare const BINDING_ORIGIN = "http://every-app-gateway.internal";
+export interface GatewayServiceBinding {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface GatewayFetchEnv {
+    EVERY_APP_GATEWAY?: GatewayServiceBinding;
+    EVERYAPP_DEV?: string | boolean;
+    /** `1` on a shared app's Workers (`everyAppWorker()` sets it). */
+    EVERYAPP_SHARED?: string;
+    OPENAI_API_KEY?: string;
+    OPENROUTER_API_KEY?: string;
+    /** Workers AI: an API token (Workers AI Read and Edit) and the account it bills. */
+    WORKERS_AI_API_TOKEN?: string;
+    CLOUDFLARE_ACCOUNT_ID?: string;
+}
+export interface CreateGatewayFetchOptions {
+    env: GatewayFetchEnv;
+    /**
+     * 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}).
+     */
+    for?: GatewayCallFor;
+}
+/**
+ * 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.
+ */
+export declare function createGatewayFetch({ env, for: target, }: CreateGatewayFetchOptions): typeof fetch;
+/** A copy of `source` aimed at `url`, streaming its body rather than buffering it. */
+export declare function streamingRequest(url: string, source: Request, headers: Headers): Request;
+//# sourceMappingURL=gatewayFetch.d.ts.map

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

@@ -0,0 +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"}

package/dist/server/gatewayFetch.js

@@ -0,0 +1,115 @@
+import { aiProviderSettings, authorizationOf, ConfigurationError, DEV_AI_PROVIDERS, devAiProvider, joinProviderUrl, } 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/";
+/**
+ * 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.
+ */
+export function createGatewayFetch({ env, for: target, }) {
+    checkAttribution(env, target, "createGatewayFetch");
+    const binding = env.EVERY_APP_GATEWAY;
+    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.`);
+    }
+    return async (input, init) => {
+        const outbound = new Request(input, init);
+        const headers = new Headers(outbound.headers);
+        headers.delete("authorization");
+        if (binding) {
+            applyAttribution(headers, target);
+            const url = new URL(outbound.url);
+            const bindingRequest = streamingRequest(`${BINDING_ORIGIN}${url.pathname}${url.search}`, outbound, headers);
+            return binding.fetch(bindingRequest);
+        }
+        const { provider, spec, path, search } = directProviderPath(outbound.url);
+        const dev = devProviders[provider];
+        if (!dev) {
+            throw new ConfigurationError(`Set ${settingsNames(spec)} in .dev.vars to call ${provider} in local development.`);
+        }
+        const url = joinProviderUrl(`${spec.origin}${dev.basePath}`, path, search);
+        if (!url)
+            throw new ConfigurationError("Invalid provider proxy path.");
+        applyAttribution(headers, undefined);
+        // 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 });
+        for (const [name, value] of Object.entries(auth?.headers ?? {})) {
+            headers.set(name, value);
+        }
+        for (const [name, value] of Object.entries(auth?.query ?? {})) {
+            url.searchParams.set(name, value);
+        }
+        const response = await fetch(streamingRequest(url.toString(), outbound, headers));
+        // What the gateway does to the provider's answer, so dev behaves alike.
+        return spec.normalizeResponse?.(path, response) ?? response;
+    };
+}
+/** 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;
+    const init = {
+        method: source.method,
+        headers,
+        body,
+        signal: source.signal,
+        ...(body ? { duplex: "half" } : {}),
+    };
+    return new Request(url, init);
+}
+/** The providers `.dev.vars` sets every setting of, with their key and base path. */
+function localProviders(env) {
+    const providers = {};
+    for (const [provider, spec] of Object.entries(DEV_AI_PROVIDERS)) {
+        const settings = {};
+        for (const name of aiProviderSettings(spec)) {
+            const value = env[name];
+            if (typeof value === "string" && value.trim()) {
+                settings[name] = value.trim();
+            }
+        }
+        const key = settings[spec.keyEnv];
+        // A provider is reachable only with every setting it needs.
+        if (!key || Object.keys(settings).length < aiProviderSettings(spec).length)
+            continue;
+        providers[provider] = { key, basePath: spec.basePath?.(settings) ?? "" };
+    }
+    return providers;
+}
+function directProviderPath(input) {
+    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;
+    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.`);
+    }
+    const path = match?.[2] || "/";
+    if (path.startsWith("//") || path.includes("\\")) {
+        throw new ConfigurationError("Invalid provider proxy path.");
+    }
+    return { provider, spec, path, search: incoming.search };
+}
+/** A provider's settings as a person reads them: `KEY`, or `KEY and SETTING`. */
+function settingsNames(spec, conjunction = "and") {
+    const [key, ...others] = aiProviderSettings(spec);
+    return others.length
+        ? `${key} ${conjunction} ${listOf(others, "and")}`
+        : key;
+}
+/** `a`, `a and b`, `a, b and c`. */
+function listOf(items, conjunction) {
+    return items.length < 2
+        ? (items[0] ?? "")
+        : `${items.slice(0, -1).join(", ")} ${conjunction} ${items.at(-1)}`;
+}
+function canIncludeBody(method) {
+    const normalized = method.toUpperCase();
+    return normalized !== "GET" && normalized !== "HEAD";
+}

package/dist/server/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @every-app/sdk/server — the server-side surface.
+ *
+ * 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 { 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 { 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 { 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

@@ -0,0 +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"}

package/dist/server/index.js

@@ -0,0 +1,15 @@
+/**
+ * @every-app/sdk/server — the server-side surface.
+ *
+ * There is intentionally no client-side export.
+ */
+export { ConfigurationError, IdentityError, everyApp, getEveryAppUser, hasScope, requireEveryAppUser, } from "./everyApp.js";
+export { AttributionError } from "./attribution.js";
+export { authorizeUrl } from "./authorizeUrl.js";
+export { createGatewayFetch, } from "./gatewayFetch.js";
+export { GatewayRefusalError, gatewayRefusal, integrationFetch, integrationStatus, } from "./integrationFetch.js";
+export { nodeServerHandler, } from "./nodeServer.js";
+export { sendEmail } from "./sendEmail.js";
+export { listMembers } from "./listMembers.js";
+export { emit } from "./emit.js";
+export { ToolError, defineTools, toolResult, } from "./tools.js";

package/dist/server/integrationFetch.d.ts

@@ -0,0 +1,131 @@
+import { type ApiKeyCapabilityId, type CapabilityId, type EmailCapabilityStatus, type OAuthClientCapabilityId } from "../internal/index.js";
+import { type GatewayCallFor } from "./attribution.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`).
+     */
+    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.
+     */
+    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}).
+     */
+    for?: GatewayCallFor;
+}
+/**
+ * A `fetch` for one of the gateway's capabilities. Call the provider's real
+ * URLs (`https://api.dataforseo.com/v3/…`); this sends them over the
+ * AppGateway binding, which checks the app's manifest lists the capability,
+ * injects the key the gateway holds and forwards the call. The app never
+ * 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.
+ *
+ * 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:
+ * 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.
+ */
+export declare function integrationFetch({ env, provider, for: target, }: IntegrationFetchOptions): typeof fetch;
+export interface IntegrationStatus {
+    /** The app's manifest lists the capability. */
+    requested: boolean;
+    /** The gateway holds a key for it (in local dev: `.dev.vars` sets one). */
+    configured: boolean;
+    /** Calls would go through. */
+    ready: boolean;
+}
+/**
+ * The email capability's status: as {@link IntegrationStatus}, plus the
+ * From a message without `from` gets, the `from` patterns the gateway
+ * accepts from this app (its installation's senders, `everyapp email set
+ * --sender`) and the provider mail goes out with (`cloudflare` or `resend`).
+ */
+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.
+ */
+export interface OAuthClientIntegrationStatus extends IntegrationStatus {
+    /** The client's public id, for the authorize URL (and Twitch's `Client-Id`). */
+    clientId?: 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.
+     */
+    origin?: string;
+    /**
+     * 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.
+     */
+    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. */
+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.
+ */
+export declare function integrationStatus<P extends CapabilityId | (string & {})>({ env, provider, }: {
+    env: object;
+    provider: P;
+}): 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

@@ -0,0 +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"}