@every-app/sdk 0.3.0-rc.9 → 0.3.1

package/dist/server/integrationFetch.d.ts

@@ -1,45 +1,48 @@
-import { type ApiKeyCapabilityId, type CapabilityId, type ConnectionAccount, type EmailCapabilityStatus, type OAuthClientCapabilityId } from "../internal/index.js";
+import { type ApiKeyCapabilityId, type CapabilityId, type EmailCapabilityStatus, type OAuthPresetId } 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,
+     * key the gateway holds, or an OAuth provider whose connections it
+     * holds. The catalog's ids and the OAuth presets' complete; a provider
+     * registered on the gateway (an OAuth preset's row among them) is
      * reached through the binding, which checks it. The `email` capability
      * is sent with `sendEmail()` instead.
      */
-    provider: ApiKeyCapabilityId | OAuthClientCapabilityId | (string & {});
+    provider: ApiKeyCapabilityId | OAuthPresetId | (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`.
+     * (its person, while the identity is good) or the organization
+     * an event delivery runs under; 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 of the person
+     * behind it, which they allowed this app to use. `{ background: true,
+     * userId }` names another member's connection instead (one who allowed
+     * this app), 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;
-    /**
-     * 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.
+     * attribution mistake still throw. An OAuth provider is never
+     * unavailable this way: without a connection its calls answer
+     * `integration_not_connected`.
      */
     optional?: boolean;
 }
@@ -51,19 +54,20 @@ 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 (`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.
+ * For an OAuth provider (`google-workspace`, `github`, ...) the gateway
+ * puts the token of the person's connection on the call, to the
+ * provider's API hosts only, once the person allowed this app to use it.
+ * Without a connection, or before they allowed this app, 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;
@@ -92,70 +96,60 @@ export interface IntegrationStatus extends SetupInfo {
  */
 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 or allows
+ * this app, and their connection once they allowed this app to use it.
+ * `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. */
-    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[];
+export type OAuthClientIntegrationStatus = IntegrationStatus & {
+    /** The provider's scopes as the app's `everyapp.config.ts` lists them. */
+    scopes: 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.
+     * Where the person connects the provider, or allows this app to use
+     * their connection to it: `/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).
      */
-    scopes?: readonly string[];
-    /** Slack's `user_scope` strings, when the sets name any. */
-    userScopes?: readonly string[];
+    connectPath: string | null;
     /**
-     * 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).
+     * The connection the call would use (the person's, or the member's
+     * `for: { background: true, userId }` names), or null when there is
+     * none or they haven't allowed this app to use it. `ready` false with
+     * `missingScopes` when it lacks a scope the app now lists, or the app
+     * lists one the person hasn't allowed it, and `reconnect` when the
+     * person has to go through `connectPath` again (missing scopes, or it
+     * expired).
      */
-    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;
+    connection: {
+        /** The account's name at the provider (an email address, a login). */
         label: string | null;
-        scopeSets: readonly string[];
+        /** The scopes it holds, canonical. */
+        scopes: readonly string[];
         ready: boolean;
-        reconnect?: boolean;
+        missingScopes?: readonly string[];
+        reconnect?: true;
     } | 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;
+};
+/** 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 OAuthPresetId ? 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, once they
+ * allowed this app to use it, and where to connect or allow.
  */
 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.
+     * OAuth provider's `connection` is that person's, once they allowed
+     * 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>>;

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

@@ -1 +1 @@
-{"version":3,"file":"integrationFetch.d.ts","sourceRoot":"","sources":["../../src/server/integrationFetch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"integrationFetch.d.ts","sourceRoot":"","sources":["../../src/server/integrationFetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAeL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAE1B,KAAK,aAAa,EAKnB,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,aAAa,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC7D;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;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;AAuLD,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;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,iBAAiB,GAAG;IAC7D,0EAA0E;IAC1E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;;;;OAQG;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,aAAa,GACrB,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"}