@withone/connect 0.12.2 → 0.13.0

package/dist/server/index.d.ts

@@ -1,30 +1,22 @@
-import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectServerConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RefreshIfExpiringOptions, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
+import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectKeyConfig, type OneConnectMode, type OneConnectServerConfig, type OneConnectTokenConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RefreshIfExpiringOptions, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
 export * from "./types";
+export { encodeUserReference, parseUserReference } from "./key";
 export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
-export interface OneConnect {
+/** What an app does with One in either mode. */
+export interface OneConnectClient {
+    /** How this client holds each user's grant. */
+    readonly mode: OneConnectMode;
     /** The authorize leg: where to send the browser and the cookie to set. */
     startAuthorization: (input?: StartAuthorizationInput) => StartAuthorizationResult;
-    /** The callback leg: verifies state, exchanges the code, stores the
-     *  tokens, and says where to send the browser next. Never throws for
-     *  a failed flow; read `outcome`. */
+    /** The callback leg: verifies state, exchanges the code, stores what
+     *  the mode keeps, and says where to send the browser next. Never
+     *  throws for a failed flow; read `outcome`. */
     completeAuthorization: (input: CompleteAuthorizationInput) => Promise<CompleteAuthorizationResult>;
-    /** Whether the user has tokens stored. */
+    /** Whether the app has something stored for the user. In key mode One
+     *  confirms the consent on each call, so a user who revoked still
+     *  reads as connected here until a call throws `reconnect_required`. */
     isConnected: (userId: string) => Promise<boolean>;
-    /** A live access token, refreshed first when it is about to expire. */
-    getAccessToken: (userId: string) => Promise<string>;
-    /** The stored tokens, for display. Null when not connected. */
-    getTokens: (userId: string) => Promise<OneConnectTokens | null>;
-    /** Refreshes now and returns the new pair. When another caller rotated
-     *  the pair a moment earlier, returns that pair instead of rotating it
-     *  a second time. */
-    refreshTokens: (userId: string) => Promise<OneConnectTokens>;
-    /** Refreshes only when the access token or the refresh token expires
-     *  within `withinMs`, and returns the pair that is current afterwards.
-     *  For background jobs: a frequent run keeps access tokens warm, and a
-     *  daily run with a window of days keeps idle users' 30-day refresh
-     *  tokens from running out. */
-    refreshIfExpiring: (userId: string, options?: RefreshIfExpiringOptions) => Promise<OneConnectTokens>;
-    /** Drops the app's copy of the tokens. The user revokes the grant
+    /** Drops the app's copy of what it stored. The user revokes the grant
      *  itself from their One dashboard. */
     disconnect: (userId: string) => Promise<void>;
     /** The connections the grant reaches, each with its access. */
@@ -37,4 +29,32 @@ export interface OneConnect {
     /** Any authenticated request to One's /v1 API, headers handled. */
     fetch: (userId: string, path: string, init?: RequestInit) => Promise<Response>;
 }
-export declare function createOneConnect(config: OneConnectServerConfig): OneConnect;
+/** The client key mode returns. */
+export interface OneConnectKeyClient extends OneConnectClient {
+    readonly mode: "key";
+    /** One's permanent id for this user (`cu_…`), or null when they have
+     *  never connected. */
+    getConnectUserId: (userId: string) => Promise<string | null>;
+}
+/** The client token mode returns. */
+export interface OneConnect extends OneConnectClient {
+    readonly mode: "token";
+    /** A live access token, refreshed first when it is about to expire. */
+    getAccessToken: (userId: string) => Promise<string>;
+    /** The stored tokens, for display. Null when not connected. */
+    getTokens: (userId: string) => Promise<OneConnectTokens | null>;
+    /** Refreshes now and returns the new pair. When another caller rotated
+     *  the pair a moment earlier, returns that pair instead of rotating it
+     *  a second time. */
+    refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+    /** Refreshes only when the access token or the refresh token expires
+     *  within `withinMs`, and returns the pair that is current afterwards.
+     *  For the app's scheduled job: a daily run with a window of days
+     *  renews each user's pair before the 30-day refresh token runs out. */
+    refreshIfExpiring: (userId: string, options?: RefreshIfExpiringOptions) => Promise<OneConnectTokens>;
+}
+/** Key mode: a connect key for the app and one permanent id per user. */
+export declare function createOneConnect(config: OneConnectKeyConfig): OneConnectKeyClient;
+/** Token mode: an access and a refresh token per user, kept fresh. */
+export declare function createOneConnect(config: OneConnectTokenConfig): OneConnect;
+export declare function createOneConnect(config: OneConnectServerConfig): OneConnectKeyClient | OneConnect;