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

package/dist/server/index.js

@@ -3,6 +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, requireCurrentUser, requireEveryAppUser, } from "./everyApp.js";
+export { OrganizationMismatchError, RequestContextError, currentUser, withOrganization, } from "./context.js";
+export { AttributionError } from "./attribution.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 { authorizeUrl } from "./authorizeUrl.js";
+export { connectPath, connectUrl, } from "./connectUrl.js";
 export { createGatewayFetch, } from "./gatewayFetch.js";
-export { createMcpHandler, } from "./mcp.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 { ToolError, defineTools, toolResult, } from "./tools.js";
+export { fromMcpTools, } from "./fromMcpTools.js";

package/dist/server/integrationFetch.d.ts

@@ -0,0 +1,162 @@
+import { type ApiKeyCapabilityId, type CapabilityId, type ConnectionAccount, 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`).
+     */
+    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. Left out, the request `everyApp()` is serving
+     * (its user, 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?: 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;
+    /**
+     * `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.
+     */
+    optional?: boolean;
+}
+/**
+ * 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 (`google-workspace`, `slack`, ...) 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(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 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). */
+    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. */
+    clientId?: 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[];
+    /**
+     * 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;
+/**
+ * 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, 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; background work
+     * (`withOrganization()`) its organization, whose own connection is then
+     * reported. Explicitly the inbound request or `{ background: true,
+     * organizationId }`, as on every call.
+     */
+    for?: GatewayCallFor;
+}): Promise<IntegrationStatusOf<P>>;
+//# 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":"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"}