@withone/connect 0.12.2 → 0.13.1

package/dist/server/key.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Key mode: the app holds one connect key, and one permanent id per
+ * user. Both go on every call; One reads the user's consent live each
+ * time. Nothing expires, so there is nothing to refresh, rotate or lock.
+ *
+ *   X-One-Secret:           the app's connect key
+ *   X-One-Connect-User-Id:  cu_… for the user being acted for
+ *
+ * The id comes from the one code exchange the callback makes. It is the
+ * same for a user for the life of the app, through revocation and
+ * re-consent, so it is saved once and never deleted by the SDK.
+ */
+import type { Credential } from "./credential";
+import { type OneConnectUserReference, type OneConnectUserStore } from "./types";
+/**
+ * The one value an app stores per user, as a string for one column:
+ * `cu_…`, then the space the user granted from when it is not their
+ * personal one (`cu_…;org=<id>;project=<id>`).
+ *
+ * The space travels with the id because One resolves a call's tenant
+ * from headers: a grant made from an organization lives there, and a
+ * call that names none runs in the user's personal space and reaches
+ * nothing. In token mode the access token names the space on every
+ * call; here there is no token after the exchange, so it is kept.
+ */
+export declare function encodeUserReference(reference: OneConnectUserReference): string;
+/** Reads a stored value back. Null when it is not one this SDK wrote. */
+export declare function parseUserReference(value: string): OneConnectUserReference | null;
+export interface KeyCredential extends Credential {
+    getConnectUserId: (userId: string) => Promise<string | null>;
+}
+export declare function createKeyCredential(connectKey: string, userStore: OneConnectUserStore): KeyCredential;

package/dist/server/token.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Token mode: the app holds an access token and a refresh token per
+ * user, and the SDK refreshes them with One.
+ *
+ * Lifetimes. The access token lives as long as the app's Token lifetime
+ * setting says (dashboard, Advanced, when creating or editing the app: 7
+ * days, 30 days, 90 days or 1 year; 30 days unless changed). An app that
+ * never had the setting gets an hour. The refresh token always lives 30
+ * days, whatever the access token's lifetime, and only a live refresh
+ * token can buy a new pair.
+ *
+ * Who refreshes. Before each call the client refreshes a pair that is
+ * within a minute of expiring. Refreshing earlier than that is the app's
+ * job: it runs `refreshIfExpiring` on a schedule, so the refresh token
+ * never runs out. When it has run out, the access token is used until it
+ * expires too, and only then is the user asked to connect again.
+ *
+ * Rotation. Every refresh rotates both tokens, 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 the grant is
+ * dead, and never lets a failing old pair delete a newer one.
+ */
+import type { Credential, PostToken } from "./credential";
+import { type OneConnectTokenStore, type OneConnectTokens, type RefreshIfExpiringOptions } from "./types";
+export interface TokenCredential extends Credential {
+    getAccessToken: (userId: string) => Promise<string>;
+    getTokens: (userId: string) => Promise<OneConnectTokens | null>;
+    refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+    refreshIfExpiring: (userId: string, options?: RefreshIfExpiringOptions) => Promise<OneConnectTokens>;
+}
+export declare function createTokenCredential(tokenStore: OneConnectTokenStore, postToken: PostToken): TokenCredential;

package/dist/server/types.d.ts

@@ -2,6 +2,39 @@
  * Types for `@withone/connect/server`: the half of the SDK that runs on
  * the app's server and holds the client secret.
  */
+/**
+ * How the app holds a user's grant.
+ *
+ * - `"key"`: the app's connect key plus a permanent id per user. Nothing
+ *   expires, so there is nothing to refresh. The default.
+ * - `"token"`: an access token and a refresh token per user, which the
+ *   SDK keeps fresh.
+ */
+export type OneConnectMode = "key" | "token";
+/** Key mode: who a stored user is to One, and where their grant lives. */
+export interface OneConnectUserReference {
+    /** One's permanent id for this user, for this app: `cu_…`. */
+    connectUserId: string;
+    /** The organization the user granted from; absent for their personal
+     *  space. */
+    organizationId?: string;
+    /** The project the user granted from, when it was one. */
+    projectId?: string;
+}
+/**
+ * Key mode: where the app keeps the one value the SDK gives it per user.
+ * A single string, written when the user connects and the same until
+ * they connect again, so one column on the app's user row is enough.
+ * `userId` is the app's own id for its user.
+ *
+ * It is an identifier, not a credential: it does nothing without the
+ * app's connect key. No lock is needed, because nothing rotates.
+ */
+export interface OneConnectUserStore {
+    saveUser: (userId: string, reference: string) => Promise<void>;
+    loadUser: (userId: string) => Promise<string | null>;
+    clearUser: (userId: string) => Promise<void>;
+}
 /** What the app stores per user after the exchange. */
 export interface OneConnectTokens {
     accessToken: string;
@@ -47,10 +80,13 @@ export interface OneConnectTokenStore {
 }
 export interface RefreshIfExpiringOptions {
     /** Refresh when the access token or the refresh token expires within
-     *  this many milliseconds. One minute when omitted. */
+     *  this many milliseconds. One minute when omitted. A refresh token
+     *  that has already run out cannot be refreshed: the pair is returned
+     *  as it is while its access token still works. */
     withinMs?: number;
 }
-export interface OneConnectServerConfig {
+/** What every app configures, whichever mode it uses. */
+export interface OneConnectBaseConfig {
     /** The app's client id from the dashboard. */
     clientId: string;
     /** The app's client secret. Server only. */
@@ -69,8 +105,35 @@ export interface OneConnectServerConfig {
     /** OAuth scopes. All three tenancy tiers when omitted, so the user may
      *  grant from any space. */
     scopes?: string[];
+}
+/**
+ * Key mode, the default: pass the app's connect key and a place to keep
+ * one value per user.
+ */
+export interface OneConnectKeyConfig extends OneConnectBaseConfig {
+    mode?: "key";
+    /** The app's connect key, minted on the app's page in the dashboard.
+     *  Server only. One key per environment. */
+    connectKey: string;
+    userStore: OneConnectUserStore;
+    tokenStore?: never;
+}
+/**
+ * Token mode: pass a token store and the SDK keeps each user's tokens
+ * fresh.
+ */
+export interface OneConnectTokenConfig extends OneConnectBaseConfig {
+    mode?: "token";
     tokenStore: OneConnectTokenStore;
+    connectKey?: never;
+    userStore?: never;
 }
+/**
+ * The mode is whichever credential is configured: a `connectKey` is key
+ * mode, a `tokenStore` alone is token mode. Set `mode` to say so
+ * explicitly.
+ */
+export type OneConnectServerConfig = OneConnectKeyConfig | OneConnectTokenConfig;
 /** The transaction cookie the authorize leg sets and the callback reads. */
 export interface OneConnectCookie {
     name: string;
@@ -160,18 +223,23 @@ export interface RunActionResult {
     status: number;
     ok: boolean;
     /** True when One refused the call because it is outside the grant.
-     *  The provider was never called. Do not retry. */
+     *  The provider was never called. Do not retry. Key mode sets it; in
+     *  token mode it stays false today, so treat any 403 there as refused. */
     blockedByGrant: boolean;
     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.
+ * - `not_connected`: nothing is stored for this user.
+ * - `reconnect_required` (key mode): One will not act for this user.
+ *   Their consent was revoked, or the app is deactivated. What the app
+ *   stored is kept; ask the user to connect again.
+ * - `refresh_failed` (token mode): 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.
+ *   reached. Nothing stored was changed, so retry later.
  */
-export type OneConnectErrorCode = "not_connected" | "refresh_failed" | "request_failed";
+export type OneConnectErrorCode = "not_connected" | "reconnect_required" | "refresh_failed" | "request_failed";
 export declare class OneConnectError extends Error {
     readonly code: OneConnectErrorCode;
     readonly status?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "One Connect for your app: the button your users press, the two backend routes as one import, and a server client that calls One with the grant. Users keep their connections in One; your app holds only what they granted.",
   "files": [
     "dist",

package/skills/one-connect/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: one-connect
-description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, and calling One with the grant.
+description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, storing and refreshing the grant, and calling One with it.
 ---
 
 # One Connect
 
 You are adding One Connect to this application. Its users will grant the app
 scoped, revocable access to their own tools. The package does the OAuth work;
-you wire three things: a button, two routes, and the calls made with the grant.
+you wire four things: a button, two routes, a daily refresh job, and the calls
+made with the grant.
 
 ```
 Browser                    Your backend                          One
@@ -16,8 +17,12 @@ Browser                    Your backend                          One
                              stores the tokens, redirects home
                  <------   onSuccess fires
 Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
+Daily:                     oneConnect.refreshIfExpiring(userId, ...) for every connected user
 ```
 
+Use **token mode**, described in sections 1 to 8. Key mode (section 9) is a
+second way to hold the grant; use it only when the human asks for it.
+
 Secrets and tokens stay on the server.
 
 ## 1 - Ask the human for these
@@ -30,7 +35,9 @@ They create the app in the One dashboard: Developers -> Connect -> New app.
 | `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
 | Redirect URI | Registered on the app. Must match the callback route exactly, e.g. `http://localhost:3000/api/one/callback`. |
 | `ONE_PERMISSION_SET` | Optional. The tools and access levels to ask for. |
-| `ONE_API_URL` | Optional. Production when unset; `https://development-api.withone.ai` for the development dashboard. |
+
+Never ask the human to paste the secret into the chat. Tell them which
+environment variable to set and read it from there.
 
 ## 2 - Environment (server only)
 
@@ -39,7 +46,6 @@ ONE_CLIENT_ID=...
 ONE_CLIENT_SECRET=one_secret_...
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
 ONE_PERMISSION_SET=...        # optional
-ONE_API_URL=...               # optional
 ```
 
 ## 3 - Install and create the client
@@ -57,7 +63,6 @@ export const oneConnect = createOneConnect({
   clientSecret: process.env.ONE_CLIENT_SECRET!,
   redirectUri: process.env.ONE_REDIRECT_URI!,
   permissionSet: process.env.ONE_PERMISSION_SET,
-  oneApiUrl: process.env.ONE_API_URL,
   tokenStore: {
     saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
     loadTokens: (userId) => /* read; null when never connected */,
@@ -115,7 +120,33 @@ Vue: `@withone/connect/vue`, same props. Svelte: `use:connectButton` from
 `<one-connect-button authorize-url="/api/one/authorize" platforms="gmail, stripe">`.
 A custom button in React: `useOneConnect({ authorizeUrl })` returns `{ open, status }`.
 
-## 6 - Calling One with the grant
+## 6 - Keeping users connected
+
+Tokens expire. Two things keep them fresh, and only the first is automatic.
+
+| | Who does it | When |
+|---|---|---|
+| Refresh before a call | the package, on its own | whenever the app calls One and the token is about to expire |
+| Refresh for users who have not called in a while | **the app**, with a daily job | once a day, for every connected user |
+
+You must add the daily job. Without it, a user who stays away for 30 days
+has to connect again: the refresh token lives 30 days, and only a live
+refresh token can renew the pair.
+
+```ts
+// a scheduled job, once a day
+for (const userId of /* every user with stored tokens */) {
+  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
+}
+```
+
+It renews both tokens when either is within 3 days of expiring, and does
+nothing otherwise. The access token lives as long as the app's Token lifetime
+says (30 days unless changed under Advanced when creating the app); keep the
+window shorter than that, or every run refreshes. Use the scheduler the app
+already has (a cron route, a queue, a worker).
+
+## 7 - Calling One with the grant
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
@@ -131,23 +162,95 @@ const reply = await oneConnect.runAction(userId, {
 // { status, ok, data }
 ```
 
-A `403` means the call is outside what the user granted. Do not retry it.
-A `refresh_failed` error means the grant ended; ask the user to connect again.
+Do not set any header. The package adds the user's credential to every call
+it makes, and refreshes it first when it is about to expire.
+
+A `403` reply means the call is outside what the user granted. Do not retry it.
+
+Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
+
+| `code` | Meaning | Do |
+|---|---|---|
+| `not_connected` | Nothing is stored for this user. | Show the Connect button. |
+| `refresh_failed` | The grant ended. The tokens were cleared. | Ask the user to connect again. |
+| `request_failed` | One answered with an error or could not be reached. Nothing stored changed. | Retry later. |
+
+```ts
+import { OneConnectError } from "@withone/connect/server";
+
+try {
+  await oneConnect.runAction(userId, action);
+} catch (error) {
+  if (
+    error instanceof OneConnectError &&
+    ["not_connected", "refresh_failed"].includes(error.code)
+  ) {
+    // show the Connect button again
+  } else {
+    throw error;
+  }
+}
+```
 
-## 7 - Rules
+## 8 - Rules
 
-- Never put the client secret in browser code, logs or error reports.
+- Never put the client secret in browser code, logs, error reports, source
+  files or prompts. Environment variables only.
 - Store tokens encrypted, keyed by the app's user.
+- Add the daily refresh job. It is part of the integration, not an extra.
 - The registered redirect URI and `ONE_REDIRECT_URI` must be identical.
 - Do not build a completion page; the callback redirect is the completion.
-- Do not write OAuth steps by hand; use the package.
+- Do not write OAuth steps or One request headers by hand; use the package.
+- Do not switch an existing app from one mode to the other unless asked.
+
+## 9 - Key mode (only when asked)
+
+A second way to hold the grant: one connect key for the app and one permanent
+id per user, with nothing to refresh. The routes, the button and the calls are
+the same. Two limits today:
+
+- `listActions` does not work in key mode yet. The app has to know the
+  actions it runs.
+- It works in Production only. The human creates the key with the dashboard
+  on Production.
+
+The human creates the key on the app's page: Credentials -> Connect key ->
+Create key. It is shown once. They set it as `ONE_CONNECT_KEY`; never ask
+them to paste it into the chat.
+
+```ts
+export const oneConnect = createOneConnect({
+  clientId: process.env.ONE_CLIENT_ID!,
+  clientSecret: process.env.ONE_CLIENT_SECRET!,
+  redirectUri: process.env.ONE_REDIRECT_URI!,
+  permissionSet: process.env.ONE_PERMISSION_SET,
+  connectKey: process.env.ONE_CONNECT_KEY!,
+  userStore: {
+    saveUser: (userId, reference) => /* save the string on the app's user row */,
+    loadUser: (userId) => /* read it; null when never connected */,
+    clearUser: (userId) => /* set it to null */,
+  },
+});
+```
+
+- `reference` is one short string. Store it as given and hand it back
+  unchanged; do not parse or rebuild it. It is an identifier, not a secret.
+- There is no daily refresh job in key mode.
+- When the user revokes access, the next call throws `reconnect_required`
+  (not `refresh_failed`). Ask them to connect again. The stored value is kept.
+- A `403` reply carries `blockedByGrant: true` when the call is outside what
+  the user granted.
+- The mode is whichever credential `createOneConnect` is given: `tokenStore`
+  for token mode, `connectKey` and `userStore` for key mode.
 
-## 8 - Done when
+## 10 - Done when
 
 1. The button leads to One's page; after signing in and authorizing, the user
    lands back in the app and `onSuccess` fires.
-2. `listConnections` returns only the granted connections.
-3. `runAction` works for an action inside the grant and returns `403` for
+2. The tokens are saved for the user.
+3. `listConnections` returns only the granted connections.
+4. `runAction` works for an action inside the grant and returns `403` for
    one outside it.
-4. After the user revokes the app in their One dashboard, the app asks them
+5. The daily refresh job exists and runs for every connected user.
+6. After the user revokes the app in their One dashboard, the app asks them
    to connect again.

package/src/next.ts

@@ -14,7 +14,7 @@
  * That serves /api/one/authorize and /api/one/callback. Register
  * `https://yourapp.com/api/one/callback` as the app's redirect URI.
  */
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectRoutesOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -80,7 +80,7 @@ export function routeFor(url: string): string {
 }
 
 export function createOneConnectRoutes(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectRoutesOptions,
 ): OneConnectRoutes {
   const cookiePath = (): string =>

package/src/node.ts

@@ -17,7 +17,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import { createOneConnectRoutes, type OneConnectRoutesOptions } from "@withone/connect/next";
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectNodeOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -76,7 +76,7 @@ async function send(response: ServerResponse, web: Response): Promise<void> {
 }
 
 export function createOneConnectHandlers(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectNodeOptions,
 ): OneConnectHandlers {
   // The web adapter receives a Request; the Node callbacks want the

package/src/server/credential.ts

@@ -0,0 +1,44 @@
+/**
+ * The seam between the two ways an app can hold a user's grant.
+ *
+ * Everything around it is shared: the authorize leg, the callback, and
+ * the calls made with the grant. A credential answers only what differs:
+ * what to keep when a user connects, what to send on a call, and how to
+ * read One refusing it.
+ *
+ * - key mode (`./key`): the app's connect key plus a permanent id for
+ *   the user. Nothing expires, so nothing is refreshed.
+ * - token mode (`./token`): an access token and a refresh token per
+ *   user, rotated before they expire.
+ */
+import type { OneConnectError } from "./types";
+
+/** What One's token endpoint answers on success. `connect_user_id` is
+ *  present whenever a durable grant backs the token. */
+export interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  connect_user_id?: string;
+}
+
+/** What One's token endpoint answered. A network failure throws instead. */
+export type TokenAnswer =
+  | { ok: true; body: TokenResponse }
+  | { ok: false; status: number; error?: string };
+
+export type PostToken = (body: URLSearchParams) => Promise<TokenAnswer>;
+
+export interface Credential {
+  /** The callback exchanged the code: keep what this mode needs. */
+  connected: (userId: string, response: TokenResponse) => Promise<void>;
+  /** The headers that make a /v1 call act for this user. Throws
+   *  `not_connected` when the user has nothing stored. */
+  headers: (userId: string) => Promise<Record<string, string>>;
+  isConnected: (userId: string) => Promise<boolean>;
+  /** Drops the app's copy. The user revokes the grant itself in One. */
+  disconnect: (userId: string) => Promise<void>;
+  /** One refused the credential itself, rather than the call it carried:
+   *  the error to throw, or null when this answer is not that. */
+  refusal: (status: number, body: string) => OneConnectError | null;
+}