@withone/connect 0.10.0 → 0.12.0

package/src/server/index.ts

@@ -16,14 +16,23 @@
  *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
+ *
+ * Refresh. One's access token lives an hour by default, its refresh token 30
+ * days; every refresh rotates both, and One treats a second use of a
+ * rotated refresh token as theft and revokes the whole grant. So the
+ * client refreshes one user at a time (in this process always, across
+ * processes through `tokenStore.withLock`), re-reads the store before
+ * spending a refresh token, clears tokens only when One declares the
+ * grant dead, and never lets a failing old pair delete a newer one.
  */
-import { DEFAULT_ONE_API_URL, RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "../constants";
+import { DEFAULT_ONE_API_URL, RETURN_ERROR_PARAM, RETURN_STATUS_PARAM } from "../constants";
 import {
   DEFAULT_SCOPES,
   basicAuthorization,
   createPkceVerifier,
   createState,
   pkceChallenge,
+  refreshTokenExpiresAt,
   tenancyHeaders,
   txCookie,
   txCookieName,
@@ -32,10 +41,12 @@ import {
   OneConnectError,
   type CompleteAuthorizationInput,
   type CompleteAuthorizationResult,
+  type ConnectFailureCode,
   type OneConnectServerConfig,
   type OneConnectTokens,
   type PlatformAction,
   type ReachableConnection,
+  type RefreshIfExpiringOptions,
   type RunActionInput,
   type RunActionResult,
   type StartAuthorizationInput,
@@ -43,7 +54,7 @@ import {
 } from "./types";
 
 export * from "./types";
-export { tenancyHeaders, tokenScopes } from "./oauth";
+export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 
 /** Refresh this long before expiry, so a call never races the clock. */
 const REFRESH_MARGIN_MS = 60_000;
@@ -56,6 +67,16 @@ interface TokenResponse {
   expires_in: number;
 }
 
+/** What One's token endpoint answered. A network failure throws instead. */
+type TokenAnswer =
+  | { ok: true; body: TokenResponse }
+  | { ok: false; status: number; error?: string };
+
+/** The one refusal that means the grant is gone for good: revoked by the
+ *  user, expired, or burned by a reused refresh token (RFC 6749 §5.2). */
+const isDeadGrant = (answer: TokenAnswer): boolean =>
+  !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
+
 export interface OneConnect {
   /** The authorize leg: where to send the browser and the cookie to set. */
   startAuthorization: (
@@ -73,8 +94,19 @@ export interface OneConnect {
   getAccessToken: (userId: string) => Promise<string>;
   /** The stored tokens, for display. Null when not connected. */
   getTokens: (userId: string) => Promise<OneConnectTokens | null>;
-  /** Forces a refresh now. */
+  /** 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
    *  itself from their One dashboard. */
   disconnect: (userId: string) => Promise<void>;
@@ -106,14 +138,14 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
    *  same refresh token trip One's reuse detection. */
   const refreshing = new Map<string, Promise<OneConnectTokens>>();
 
-  const returnUrl = (status: "success" | "error", message?: string): string => {
+  const returnUrl = (status: "success" | "error", code?: ConnectFailureCode): string => {
     const url = new URL(returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
-    if (message) url.searchParams.set(RETURN_MESSAGE_PARAM, message);
+    if (code) url.searchParams.set(RETURN_ERROR_PARAM, code);
     return url.toString();
   };
 
-  const exchange = async (body: URLSearchParams): Promise<TokenResponse> => {
+  const postToken = async (body: URLSearchParams): Promise<TokenAnswer> => {
     const response = await fetch(tokenUrl, {
       method: "POST",
       headers: {
@@ -122,14 +154,43 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
       },
       body,
     });
-    if (!response.ok) {
+    if (response.ok)
+      return { ok: true, body: (await response.json()) as TokenResponse };
+    let error: string | undefined;
+    try {
+      const refusal = (await response.json()) as { error?: unknown };
+      if (typeof refusal.error === "string") error = refusal.error;
+    } catch {
+      /* not an OAuth error body: a proxy page or a server error */
+    }
+    return { ok: false, status: response.status, error };
+  };
+
+  const exchange = async (body: URLSearchParams): Promise<TokenResponse> => {
+    const answer = await postToken(body);
+    if (!answer.ok) {
       throw new OneConnectError(
         "request_failed",
-        `One refused the token request (HTTP ${response.status}).`,
-        response.status,
+        `One refused the token request (HTTP ${answer.status}).`,
+        answer.status,
       );
     }
-    return (await response.json()) as TokenResponse;
+    return answer.body;
+  };
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = <T>(userId: string, run: () => Promise<T>): Promise<T> =>
+    tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens: OneConnectTokens, withinMs: number): boolean => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return (
+      tokens.expiresAt <= horizon ||
+      (refreshExpiresAt !== null && refreshExpiresAt <= horizon)
+    );
   };
 
   const toTokens = (response: TokenResponse): OneConnectTokens => ({
@@ -171,23 +232,24 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     const verifier = cookieName ? input.getCookie(cookieName) : undefined;
 
     const fail = (
-      outcome: "declined" | "failed",
+      failure: ConnectFailureCode,
       message: string,
     ): CompleteAuthorizationResult => ({
-      outcome,
+      outcome: failure === "declined" ? "declined" : "failed",
+      code: failure,
       message,
-      redirectUrl: returnUrl("error", message),
+      redirectUrl: returnUrl("error", failure),
       clearCookieName: cookieName,
     });
 
     if (oauthError === "access_denied")
-      return fail("declined", "You cancelled the request.");
+      return fail("declined", "The user cancelled on One's page.");
     if (oauthError)
       return fail("failed", `One reported an error: ${oauthError}.`);
-    // The returned state names its own cookie. No cookie means a forged
-    // or stale state; the code is never exchanged in that case.
+    // The returned state names its own cookie. No cookie means a stale,
+    // foreign or forged state; the code is never exchanged in that case.
     if (!code || !state || !verifier)
-      return fail("failed", "The sign-in attempt expired or was tampered with.");
+      return fail("expired", "The attempt expired, or its state cookie was missing.");
 
     try {
       const tokens = toTokens(
@@ -200,7 +262,9 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
           }),
         ),
       );
-      await tokenStore.saveTokens(input.userId, tokens);
+      // Under the lock, so a refresh in flight on another server cannot
+      // interleave with this save.
+      await locked(input.userId, () => tokenStore.saveTokens(input.userId, tokens));
     } catch (error) {
       const status = error instanceof OneConnectError ? error.status : undefined;
       return fail(
@@ -218,51 +282,123 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     };
   };
 
-  const refreshTokens = (userId: string): Promise<OneConnectTokens> => {
-    const inFlight = refreshing.get(userId);
-    if (inFlight) return inFlight;
-    const job = (async () => {
+  const notConnected = () =>
+    new OneConnectError("not_connected", "This user is not connected.");
+
+  /**
+   * The grant behind `failed` is dead. Clears it, unless a newer pair
+   * landed while it was failing (a reconnect's callback, another
+   * server's refresh): that pair is returned instead, because the user
+   * did nothing wrong and deleting it would disconnect them.
+   */
+  const retire = async (
+    userId: string,
+    failed: OneConnectTokens,
+    status?: number,
+  ): Promise<OneConnectTokens> => {
+    const latest = await tokenStore.loadTokens(userId);
+    if (latest && latest.refreshToken !== failed.refreshToken) return latest;
+    await tokenStore.clearTokens(userId, failed);
+    throw new OneConnectError(
+      "refresh_failed",
+      "The connection to One has expired or was revoked. Ask the user to connect again.",
+      status,
+    );
+  };
+
+  /**
+   * The one place a refresh token is spent. Under the app's lock it
+   * re-reads the store, and refreshes only when `stillNeeded` says the
+   * stored pair still needs it: another process may have refreshed while
+   * this one waited, and spending the same refresh token twice makes One
+   * revoke the grant.
+   */
+  const refreshUnderLock = (
+    userId: string,
+    stillNeeded: (current: OneConnectTokens) => boolean,
+  ): Promise<OneConnectTokens> =>
+    locked(userId, async () => {
       const current = await tokenStore.loadTokens(userId);
-      if (!current)
-        throw new OneConnectError("not_connected", "This user is not connected.");
+      if (!current) throw notConnected();
+      if (!stillNeeded(current)) return current;
+
+      // An expired refresh token cannot work, and One answers one with a
+      // server error rather than invalid_grant, so settle it here.
+      const refreshExpiresAt = refreshTokenExpiresAt(current.refreshToken);
+      if (refreshExpiresAt !== null && refreshExpiresAt <= Date.now())
+        return retire(userId, current);
+
+      let answer: TokenAnswer;
       try {
-        const next = toTokens(
-          await exchange(
-            new URLSearchParams({
-              grant_type: "refresh_token",
-              refresh_token: current.refreshToken,
-            }),
-          ),
+        answer = await postToken(
+          new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: current.refreshToken,
+          }),
+        );
+      } catch {
+        throw new OneConnectError(
+          "request_failed",
+          "One could not be reached to refresh the connection. The tokens were kept; try again.",
         );
+      }
+
+      if (answer.ok) {
         // Both tokens: One rotates the pair on every refresh.
+        const next = toTokens(answer.body);
         await tokenStore.saveTokens(userId, next);
         return next;
-      } catch (error) {
-        // The family is dead: revoked, expired or reused. Keeping the
-        // pair would only fail again; the user has to reconnect.
-        await tokenStore.clearTokens(userId);
-        const status = error instanceof OneConnectError ? error.status : undefined;
-        throw new OneConnectError(
-          "refresh_failed",
-          "The connection to One has expired or was revoked. Ask the user to connect again.",
-          status,
-        );
-      } finally {
-        refreshing.delete(userId);
       }
-    })();
-    refreshing.set(userId, job);
-    return job;
+      if (isDeadGrant(answer)) return retire(userId, current, answer.status);
+      // A server error, a rate limit, a misconfigured secret: nothing says
+      // the grant is gone, so keep the tokens and let the caller retry.
+      throw new OneConnectError(
+        "request_failed",
+        `One could not refresh the connection (HTTP ${answer.status}). The tokens were kept; try again.`,
+        answer.status,
+      );
+    });
+
+  /** One refresh per user in this process; concurrent callers share it. */
+  const singleFlight = (
+    userId: string,
+    job: () => Promise<OneConnectTokens>,
+  ): Promise<OneConnectTokens> => {
+    const inFlight = refreshing.get(userId);
+    if (inFlight) return inFlight;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
   };
 
-  const getAccessToken = async (userId: string): Promise<string> => {
+  const refreshTokens = (userId: string): Promise<OneConnectTokens> =>
+    singleFlight(userId, async () => {
+      const before = await tokenStore.loadTokens(userId);
+      if (!before) throw notConnected();
+      // Rotate the pair seen now; a pair someone else rotated since is
+      // already fresh.
+      return refreshUnderLock(
+        userId,
+        (current) => current.refreshToken === before.refreshToken,
+      );
+    });
+
+  const refreshIfExpiring = async (
+    userId: string,
+    options: RefreshIfExpiringOptions = {},
+  ): Promise<OneConnectTokens> => {
+    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
     const tokens = await tokenStore.loadTokens(userId);
-    if (!tokens)
-      throw new OneConnectError("not_connected", "This user is not connected.");
-    if (Date.now() < tokens.expiresAt - REFRESH_MARGIN_MS) return tokens.accessToken;
-    return (await refreshTokens(userId)).accessToken;
+    if (!tokens) throw notConnected();
+    if (!expiresWithin(tokens, withinMs)) return tokens;
+    return singleFlight(userId, () =>
+      refreshUnderLock(userId, (current) => expiresWithin(current, withinMs)),
+    );
   };
 
+  const getAccessToken = async (userId: string): Promise<string> =>
+    (await refreshIfExpiring(userId)).accessToken;
+
   const oneFetch = async (
     userId: string,
     path: string,
@@ -373,6 +509,7 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     getAccessToken,
     getTokens: (userId) => tokenStore.loadTokens(userId),
     refreshTokens,
+    refreshIfExpiring,
     disconnect: (userId) => tokenStore.clearTokens(userId),
     listConnections,
     listActions,

package/src/server/oauth.ts

@@ -85,6 +85,22 @@ export function tenancyHeaders(accessToken: string): Record<string, string> {
   }
 }
 
+/** When a refresh token stops working, in epoch milliseconds, from its
+ *  `exp` claim. Null when the token carries no readable expiry, in which
+ *  case only One can say whether it still works. */
+export function refreshTokenExpiresAt(refreshToken: string): number | null {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(refreshToken.split(".")[1], "base64url").toString(),
+    ) as { exp?: unknown };
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp)
+      ? payload.exp * 1000
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The scopes the token was granted, from its claims. Display only. */
 export function tokenScopes(accessToken: string): string[] {
   try {

package/src/server/types.ts

@@ -13,13 +13,45 @@ export interface OneConnectTokens {
 
 /**
  * Where the app keeps each user's tokens: its database, a cache, an
- * encrypted cookie. The SDK never sees a token outside these three
- * calls. `userId` is the app's own id for its user.
+ * encrypted cookie. The SDK never sees a token outside these calls.
+ * `userId` is the app's own id for its user.
  */
 export interface OneConnectTokenStore {
   saveTokens: (userId: string, tokens: OneConnectTokens) => Promise<void>;
   loadTokens: (userId: string) => Promise<OneConnectTokens | null>;
-  clearTokens: (userId: string) => Promise<void>;
+  /**
+   * Deletes the user's tokens.
+   *
+   * `failed` is set when the SDK clears because One declared that pair
+   * dead. Delete only when the stored refresh token is still
+   * `failed.refreshToken`: a newer pair saved in the meantime (a
+   * reconnect, another server's refresh) must survive. `failed` is
+   * undefined for `disconnect`, which always deletes.
+   */
+  clearTokens: (userId: string, failed?: OneConnectTokens) => Promise<void>;
+  /**
+   * Runs `run` while holding a lock on this user that every server and
+   * worker of the app shares: a Postgres advisory lock, a Redis lock, a
+   * row lock. The SDK loads, refreshes and saves the user's tokens
+   * inside it.
+   *
+   * Required when the app runs more than one process (serverless,
+   * several instances, a background worker). One rotates the refresh
+   * token on every use and treats a second use of the old one as theft,
+   * revoking the whole grant, so two processes refreshing the same user
+   * at once disconnect that user. Without a lock the SDK can only stop
+   * that inside a single process.
+   *
+   * Hold it for at least 60 seconds before any timeout: it spans one
+   * call to One's token endpoint.
+   */
+  withLock?: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+}
+
+export interface RefreshIfExpiringOptions {
+  /** Refresh when the access token or the refresh token expires within
+   *  this many milliseconds. One minute when omitted. */
+  withinMs?: number;
 }
 
 export interface OneConnectServerConfig {
@@ -78,11 +110,17 @@ export interface CompleteAuthorizationInput {
   getCookie: (name: string) => string | undefined;
 }
 
+import type { ConnectFailureCode } from "../types";
+export type { ConnectFailureCode };
+
 export type AuthorizationOutcome = "connected" | "declined" | "failed";
 
 export interface CompleteAuthorizationResult {
   outcome: AuthorizationOutcome;
-  /** Safe to show to the user when the outcome is not "connected". */
+  /** Why it failed, as the code the browser receives. Only the code goes
+   *  on the return URL; the browser shows fixed text for it. */
+  code?: ConnectFailureCode;
+  /** What happened, for your logs. Never put it in front of the user. */
   message?: string;
   /** Send the browser here with a 302; it carries `?one_connect=…`. */
   redirectUrl: string;
@@ -137,6 +175,13 @@ export interface RunActionResult {
   data: unknown;
 }
 
+/**
+ * - `not_connected`: no tokens are stored for this user.
+ * - `refresh_failed`: One declared the grant dead (revoked, expired or
+ *   reused). The tokens were cleared; ask the user to connect again.
+ * - `request_failed`: One answered with an error or could not be
+ *   reached. During a refresh the tokens are kept, so retry later.
+ */
 export type OneConnectErrorCode =
   | "not_connected"
   | "refresh_failed"

package/src/svelte.ts

@@ -5,12 +5,11 @@
  * Svelte compiler or dependency is involved:
  *
  *   <div use:connectButton={{ authorizeUrl: "/api/one/authorize",
- *     platforms: ["stripe", "notion"],
+ *     platforms: ["stripe", "notion"], connected: data.hasOneGrant,
  *     onSuccess: () => { ... } }} />
  */
 import {
   mountConnectButton,
-  optionsFromProps,
   type ConnectButtonHandle,
   type ConnectButtonProps,
 } from "@withone/connect";
@@ -24,17 +23,10 @@ export function connectButton(
   update: (next: ConnectButtonProps) => void;
   destroy: () => void;
 } {
-  let handle: ConnectButtonHandle = mountConnectButton(
-    node,
-    optionsFromProps(props),
-  );
+  const handle: ConnectButtonHandle = mountConnectButton(node, props);
   return {
-    update(next: ConnectButtonProps) {
-      handle.destroy();
-      handle = mountConnectButton(node, optionsFromProps(next));
-    },
-    destroy() {
-      handle.destroy();
-    },
+    // In place: the button keeps its state and focus across updates.
+    update: (next) => handle.update(next),
+    destroy: () => handle.destroy(),
   };
 }

package/src/types.ts

@@ -10,35 +10,60 @@
 /** Theme of One's hosted connect page. */
 export type OneConnectTheme = "light" | "dark";
 
-export interface OneConnectOptions {
+/** Theme of the button: fixed, or following the visitor's setting. */
+export type ConnectButtonTheme = "light" | "dark" | "auto";
+
+/**
+ * Why a flow ended without a grant. The callback route puts only this
+ * code on the return URL; the text shown for it is fixed in the SDK, so
+ * a crafted link can never put its own words in front of the user.
+ *
+ * - `declined`: the user cancelled on One's page.
+ * - `expired`: the attempt took too long or was started elsewhere.
+ * - `failed`: One could not complete the connection.
+ */
+export type ConnectFailureCode = "declined" | "expired" | "failed";
+
+export interface OneConnectFlowOptions {
   /** The app's own backend authorize route. Relative paths such as
    *  "/api/one/authorize" resolve against the page's origin. */
   authorizeUrl: string;
   /** Theme for One's hosted page. Carried on the URL fragment, which
    *  survives the redirect chain, so the backend forwards nothing. */
+  connectTheme?: OneConnectTheme;
+  /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
   appTheme?: OneConnectTheme;
-  /** The grant completed and the backend stored the tokens. */
+  /** The grant completed and the backend stored the tokens. Fires once
+   *  per page load, on the first flow still mounted when the tab
+   *  returns. Treat it as a hint to refetch: your server is the truth. */
   onSuccess?: () => void;
-  /** The flow ended without a grant: the user declined, the attempt
-   *  expired, or the exchange failed. `message` is safe to show. */
-  onError?: (message: string) => void;
+  /** The flow ended without a grant. `message` is fixed text for
+   *  `code`, safe to show. */
+  onError?: (message: string, code: ConnectFailureCode) => void;
+  /** The user came back with the browser's Back button before finishing
+   *  (the page was restored from the back-forward cache). */
+  onCancel?: () => void;
 }
 
-export interface OneConnectHandle {
+export interface OneConnectFlow {
   /** Navigates the tab to One's hosted connect flow. */
   open: () => void;
+  /** Swaps the options (callbacks, theme) without losing the flow. */
+  update: (options: OneConnectFlowOptions) => void;
+  /** Stops listening: callbacks no longer fire for this flow. */
+  destroy: () => void;
 }
 
-/** How the app's callback route reports the outcome on its final
- *  redirect, read off the page URL when the tab returns. */
+/** How the flow ended, read off the page URL when the tab returns. */
 export interface OneConnectReturn {
   status: "success" | "error";
+  code?: ConnectFailureCode;
   message?: string;
 }
 
 /**
  * A connector chip on the button. Pass One's connector slug ("stripe",
- * "google-calendar") and the SDK shows the logo and the name; pass an
+ * "google-calendar") and the SDK shows its logo and name; pass an
  * object to override either.
  */
 export type ConnectButtonPlatformInput =
@@ -52,33 +77,52 @@ export interface ConnectButtonPlatform {
 }
 
 export type ConnectButtonVariant = "default" | "accent" | "block";
+export type ConnectButtonSize = "sm" | "md" | "lg";
 export type ConnectButtonState = "idle" | "connecting" | "connected";
 
-export interface ConnectButtonOptions {
-  /** Everything the flow needs; the button wires open() and the
-   *  Connecting and Connected states around your callbacks. */
-  connect: OneConnectOptions;
-  /** "Connect your apps" unless overridden. */
-  label?: string;
-  /** default = neutral pill; accent = brand-colored pill; block =
-   *  full-width card with a description and a "Secured by One" foot. */
-  variant?: ConnectButtonVariant;
-  /** Matches the host page, not One's page (that is connect.appTheme). */
-  theme?: OneConnectTheme;
-  /** Connector chips. The first three render; the rest fold into a "+N"
-   *  chip, so that count only ever describes this list. */
+/** One prop shape for every surface: React, Vue, Svelte, the custom
+ *  element and `mountConnectButton`. */
+export interface ConnectButtonProps {
+  /** The app's own backend authorize route; relative is fine. */
+  authorizeUrl: string;
+  /** Connector slugs, or objects that override the name or the logo.
+   *  The first three draw as logos; the rest fold into a "+N" chip. */
   platforms?: ConnectButtonPlatformInput[];
-  /** Sub-line on the block variant, shown while idle. */
-  description?: string;
-  /** Fill of the accent variant; One's lime when omitted. */
+  /** Whether this user has a live grant, from your server. When set, it
+   *  decides the Connected state. When omitted, the button shows
+   *  Connected only right after a successful return. */
+  connected?: boolean;
+  /** Not clickable, for example until terms are accepted. */
+  disabled?: boolean;
+  /** default = neutral, accent = your brand colour, block = a card with
+   *  a description and a "Secured by One" foot. */
+  variant?: ConnectButtonVariant;
+  size?: ConnectButtonSize;
+  /** Stretches to the width of its container. */
+  fullWidth?: boolean;
+  /** Matches the host page. "auto" follows the visitor's setting. */
+  theme?: ConnectButtonTheme;
+  /** Theme of One's hosted page. */
+  connectTheme?: OneConnectTheme;
+  /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
+  appTheme?: OneConnectTheme;
+  /** Fill of the accent variant; One's lime when omitted. The label is
+   *  black or white, whichever reads better on it. */
   accentColor?: string;
-  /** Label for the connected state. */
+  /** "Connect your apps" unless set. */
+  label?: string;
+  /** "Connected" unless set. */
   connectedLabel?: string;
+  /** Sub-line on the block variant. */
+  description?: string;
+  onSuccess?: () => void;
+  onError?: (message: string, code: ConnectFailureCode) => void;
+  onCancel?: () => void;
 }
 
 export interface ConnectButtonHandle {
-  /** Override the visual state by hand. */
-  setState: (state: ConnectButtonState) => void;
-  /** Remove the button. */
+  /** Applies new props in place, keeping the button's state. */
+  update: (props: ConnectButtonProps) => void;
+  /** Removes the button and stops its callbacks. */
   destroy: () => void;
 }