@withone/connect 0.10.0 → 0.12.0

package/dist/react.d.ts

@@ -1,7 +1,26 @@
 import type { CSSProperties, ReactElement } from "react";
-import { type ConnectButtonProps as ConnectButtonCoreProps } from "@withone/connect";
+import { type ConnectButtonProps as ConnectButtonCoreProps, type ConnectFailureCode, type OneConnectFlowOptions } from "@withone/connect";
 export interface ConnectButtonProps extends ConnectButtonCoreProps {
+    /** On the wrapper element around the button. */
     className?: string;
     style?: CSSProperties;
 }
 export declare function ConnectButton(props: ConnectButtonProps): ReactElement;
+export type OneConnectStatus = "idle" | "connecting" | "connected" | "error";
+export interface UseOneConnectResult {
+    /** Sends the tab to One's hosted connect flow. */
+    open: () => void;
+    /** "connected" and "error" reflect how this page load ended a flow. */
+    status: OneConnectStatus;
+    error: {
+        message: string;
+        code: ConnectFailureCode;
+    } | null;
+}
+/**
+ * The flow for your own button:
+ *
+ *   const { open, status, error } = useOneConnect({ authorizeUrl: "/api/one/authorize" });
+ *   <button onClick={open} disabled={status === "connecting"}>Connect</button>
+ */
+export declare function useOneConnect(options: OneConnectFlowOptions): UseOneConnectResult;

package/dist/react.esm.js

@@ -1 +1,2 @@
-import{useRef as r,useEffect as n,createElement as o}from"react";import{propsIdentity as c,mountConnectButton as e,optionsFromProps as u}from"@withone/connect";function t(t){const s=r(null),l=r(null),i=r({onSuccess:t.onSuccess,onError:t.onError});i.current={onSuccess:t.onSuccess,onError:t.onError};const a=c(t);return n(()=>{if(s.current)return l.current=e(s.current,u(t,{onSuccess:()=>{var r,n;return null===(r=(n=i.current).onSuccess)||void 0===r?void 0:r.call(n)},onError:r=>{var n,o;return null===(n=(o=i.current).onError)||void 0===n?void 0:n.call(o,r)}})),()=>{var r;null===(r=l.current)||void 0===r||r.destroy(),l.current=null}},[a]),o("div",{ref:s,className:t.className,style:t.style})}export{t as ConnectButton};
+"use client";
+import{useRef as r,useEffect as n,createElement as e,useState as t,useCallback as c}from"react";import{mountConnectButton as l,createConnectFlow as o,readConnectReturn as u}from"@withone/connect";const s=r=>{var n,e;return JSON.stringify([r.authorizeUrl,null!==(n=r.platforms)&&void 0!==n?n:[],r.connected,r.disabled,r.variant,r.size,r.fullWidth,r.theme,null!==(e=r.connectTheme)&&void 0!==e?e:r.appTheme,r.accentColor,r.label,r.connectedLabel,r.description])};function a(t){const c=r(null),o=r(null),u=r(""),a=r(t);a.current=t;const i=()=>({...a.current,onSuccess:()=>{var r,n;return null===(r=(n=a.current).onSuccess)||void 0===r?void 0:r.call(n)},onError:(r,n)=>{var e,t;return null===(e=(t=a.current).onError)||void 0===e?void 0:e.call(t,r,n)},onCancel:()=>{var r,n;return null===(r=(n=a.current).onCancel)||void 0===r?void 0:r.call(n)}});n(()=>{if(c.current)return o.current=l(c.current,i()),u.current=s(a.current),()=>{var r;null===(r=o.current)||void 0===r||r.destroy(),o.current=null}},[]);const d=s(t);return n(()=>{o.current&&d!==u.current&&(u.current=d,o.current.update(i()))},[d]),e("div",{ref:c,className:t.className,style:t.style})}function i(e){const[l,s]=t("idle"),[a,i]=t(null),d=r(e);d.current=e;const v=r(null),f=()=>({...d.current,onSuccess:()=>{var r,n;return null===(r=(n=d.current).onSuccess)||void 0===r?void 0:r.call(n)},onError:(r,n)=>{var e,t;return null===(e=(t=d.current).onError)||void 0===e?void 0:e.call(t,r,n)},onCancel:()=>{var r,n;s("idle"),null===(r=(n=d.current).onCancel)||void 0===r||r.call(n)}});n(()=>{const r=o(f());v.current=r;const n=u();if("success"===(null==n?void 0:n.status))s("connected");else if("error"===(null==n?void 0:n.status)){var e,t;s("error"),i({message:null!==(e=n.message)&&void 0!==e?e:"",code:null!==(t=n.code)&&void 0!==t?t:"failed"})}return()=>{r.destroy(),v.current=null}},[]),n(()=>{var r;null===(r=v.current)||void 0===r||r.update(f())});return{open:c(()=>{v.current&&(i(null),s("connecting"),v.current.open())},[]),status:l,error:a}}export{a as ConnectButton,i as useOneConnect};

package/dist/return.d.ts

@@ -1,5 +1,8 @@
-import type { OneConnectReturn } from "./types";
-/** Reads the outcome the callback route put on the return URL. */
+import type { ConnectFailureCode, OneConnectReturn } from "./types";
+/** The only text the SDK ever shows for a failed flow. */
+export declare const ERROR_MESSAGES: Record<ConnectFailureCode, string>;
+/** Reads the outcome the callback route put on the return URL. The
+ *  message always comes from ERROR_MESSAGES, never from the URL. */
 export declare function parseReturn(search: string): OneConnectReturn | null;
 /** The same URL without the return params, so a refresh does not
  *  re-fire the callbacks. */

package/dist/server/index.cjs.js

@@ -6,7 +6,8 @@ var node_crypto = require('node:crypto');
  *  The SDK reads them off the page URL when the tab comes home, so
  *  there is no completion page to build. */
 const RETURN_STATUS_PARAM = "one_connect";
-const RETURN_MESSAGE_PARAM = "one_connect_message";
+/** Why the flow failed, as a code (see ConnectFailureCode). */
+const RETURN_ERROR_PARAM = "one_connect_error";
 
 /** One's production API. Point `oneApiUrl` elsewhere for development. */
 const DEFAULT_ONE_API_URL = "https://api.withone.ai";
@@ -72,6 +73,18 @@ function tenancyHeaders(accessToken) {
   }
 }
 
+/** 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. */
+function refreshTokenExpiresAt(refreshToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(refreshToken.split(".")[1], "base64url").toString());
+    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. */
 function tokenScopes(accessToken) {
   try {
@@ -91,8 +104,8 @@ function tokenScopes(accessToken) {
 
 /**
  * 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.
  */
 
 /** The transaction cookie the authorize leg sets and the callback reads. */
@@ -101,6 +114,14 @@ function tokenScopes(accessToken) {
 
 /** One catalog action for a platform. */
 
+/**
+ * - `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.
+ */
+
 class OneConnectError extends Error {
   constructor(code, message, status) {
     super(message);
@@ -128,12 +149,26 @@ class OneConnectError extends Error {
  *   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.
  */
 
 /** Refresh this long before expiry, so a call never races the clock. */
 const REFRESH_MARGIN_MS = 60_000;
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
+
+/** What One's token endpoint answered. A network failure throws instead. */
+
+/** 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 => !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
 function createOneConnect(config) {
   const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(/\/+$/, "");
   const authorizeUrl = `${oneApiUrl}/oauth/authorize`;
@@ -148,13 +183,13 @@ function createOneConnect(config) {
   /** One refresh in flight per user: two concurrent refreshes with the
    *  same refresh token trip One's reuse detection. */
   const refreshing = new Map();
-  const returnUrl = (status, message) => {
+  const returnUrl = (status, code) => {
     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 => {
+  const postToken = async body => {
     const response = await fetch(tokenUrl, {
       method: "POST",
       headers: {
@@ -163,10 +198,40 @@ function createOneConnect(config) {
       },
       body
     });
-    if (!response.ok) {
-      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${response.status}).`, response.status);
+    if (response.ok) return {
+      ok: true,
+      body: await response.json()
+    };
+    let error;
+    try {
+      const refusal = await response.json();
+      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 => {
+    const answer = await postToken(body);
+    if (!answer.ok) {
+      throw new OneConnectError("request_failed", `One refused the token request (HTTP ${answer.status}).`, answer.status);
     }
-    return await response.json();
+    return answer.body;
+  };
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = (userId, run) => tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens, withinMs) => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return tokens.expiresAt <= horizon || refreshExpiresAt !== null && refreshExpiresAt <= horizon;
   };
   const toTokens = response => ({
     accessToken: response.access_token,
@@ -198,17 +263,18 @@ function createOneConnect(config) {
     const oauthError = params.get("error");
     const cookieName = state ? txCookieName(state) : undefined;
     const verifier = cookieName ? input.getCookie(cookieName) : undefined;
-    const fail = (outcome, message) => ({
-      outcome,
+    const fail = (failure, message) => ({
+      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.");
+    if (oauthError === "access_denied") 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.
-    if (!code || !state || !verifier) return fail("failed", "The sign-in attempt expired or was tampered with.");
+    // 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("expired", "The attempt expired, or its state cookie was missing.");
     try {
       const tokens = toTokens(await exchange(new URLSearchParams({
         grant_type: "authorization_code",
@@ -216,7 +282,9 @@ function createOneConnect(config) {
         redirect_uri: config.redirectUri,
         code_verifier: verifier
       })));
-      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("failed", status ? `One rejected the code exchange (HTTP ${status}).` : "One could not be reached to complete the connection.");
@@ -227,39 +295,81 @@ function createOneConnect(config) {
       clearCookieName: cookieName
     };
   };
-  const refreshTokens = userId => {
+  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, failed, status) => {
+    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, stillNeeded) => locked(userId, async () => {
+    const current = await tokenStore.loadTokens(userId);
+    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;
+    try {
+      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;
+    }
+    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, job) => {
     const inFlight = refreshing.get(userId);
     if (inFlight) return inFlight;
-    const job = (async () => {
-      const current = await tokenStore.loadTokens(userId);
-      if (!current) throw new OneConnectError("not_connected", "This user is not connected.");
-      try {
-        const next = toTokens(await exchange(new URLSearchParams({
-          grant_type: "refresh_token",
-          refresh_token: current.refreshToken
-        })));
-        // Both tokens: One rotates the pair on every refresh.
-        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;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
   };
-  const getAccessToken = async userId => {
+  const refreshTokens = userId => 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, options = {}) => {
+    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 => (await refreshIfExpiring(userId)).accessToken;
   const oneFetch = async (userId, path, init = {}) => {
     const accessToken = await getAccessToken(userId);
     const headers = new Headers(init.headers);
@@ -335,6 +445,7 @@ function createOneConnect(config) {
     getAccessToken,
     getTokens: userId => tokenStore.loadTokens(userId),
     refreshTokens,
+    refreshIfExpiring,
     disconnect: userId => tokenStore.clearTokens(userId),
     listConnections,
     listActions,
@@ -345,5 +456,6 @@ function createOneConnect(config) {
 
 exports.OneConnectError = OneConnectError;
 exports.createOneConnect = createOneConnect;
+exports.refreshTokenExpiresAt = refreshTokenExpiresAt;
 exports.tenancyHeaders = tenancyHeaders;
 exports.tokenScopes = tokenScopes;

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
-import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectServerConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
+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";
 export * from "./types";
-export { tenancyHeaders, tokenScopes } from "./oauth";
+export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 export interface OneConnect {
     /** The authorize leg: where to send the browser and the cookie to set. */
     startAuthorization: (input?: StartAuthorizationInput) => StartAuthorizationResult;
@@ -14,8 +14,16 @@ 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>;