@withone/connect 0.12.2 → 0.13.0

package/README.md

@@ -28,7 +28,7 @@ You add three things: a button, two backend routes, and the calls you make with
 Browser                    Your server                          One
 <ConnectButton>  ──────►   GET /api/one/authorize  ──302──►  hosted page: sign in, pick tools, set access
                            GET /api/one/callback   ◄──302──  ?code&state
-                             stores the tokens, redirects home
+                             saves one id for the user, redirects home
 onSuccess()      ◄──────
 later:                     oneConnect.runAction(userId, …)  ──►  One, grant enforced
 ```
@@ -45,9 +45,12 @@ Using a coding agent? `npx skills add withoneai/connect` teaches it the whole se
 
 Dashboard → **Developers → Connect → New app**. Register your callback URL exactly, for example `https://yourapp.com/api/one/callback`. Optionally choose the tools and access levels to ask for; the consent page lists them in the order you add them.
 
+Then, on the app's page, under **Credentials → Connect key**, create a key. It is shown once, and it is made for the environment your dashboard is on: switch the dashboard to Sandbox to create a Sandbox key.
+
 ```env
 ONE_CLIENT_ID=…
 ONE_CLIENT_SECRET=one_secret_…                        # server only
+ONE_CONNECT_KEY=sk_live_…                             # server only: the app's connect key
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback  # exactly the registered URL
 ONE_PERMISSION_SET=…                                  # optional: the tools you ask for
 ONE_API_URL=https://api.withone.ai                    # optional: production when unset
@@ -97,7 +100,19 @@ Your own button in React: `const { open, status } = useOneConnect({ authorizeUrl
 
 To match your design, set `--one-connect-font` and `--one-connect-radius`, or style `::part(button)`.
 
-## 3 · The two routes
+## 3 · Choose a mode
+
+Your server holds a user's grant in one of two ways. The button, the two routes and every call are the same in both. **The mode is whichever credential you configure.**
+
+| | Key mode (default) | Token mode |
+|---|---|---|
+| Your server holds | one connect key for the app | nothing app-wide |
+| You store per user | one id, saved once | an access token and a refresh token |
+| Expires | nothing expires; One checks the consent on every call | the tokens expire, on the lifetime set on your app |
+| Refreshing | none | the SDK does it; several servers need a shared lock |
+| Pick it when | you call One from your own server. Start here. | you need a standard OAuth bearer token |
+
+**Key mode**: pass the connect key and a place to save one value per user.
 
 ```ts
 // lib/one.ts
@@ -109,7 +124,27 @@ export const oneConnect = createOneConnect({
   redirectUri: process.env.ONE_REDIRECT_URI!,
   permissionSet: process.env.ONE_PERMISSION_SET,
   oneApiUrl: process.env.ONE_API_URL,
-  tokenStore: {
+  connectKey: process.env.ONE_CONNECT_KEY!,                 // ← this makes it key mode
+  userStore: {
+    saveUser: (userId, reference) => db.users.update(userId, { oneConnect: reference }),
+    loadUser: async (userId) => (await db.users.find(userId))?.oneConnect ?? null,
+    clearUser: (userId) => db.users.update(userId, { oneConnect: null }),
+  },
+});
+```
+
+`reference` is one short string: the user's permanent One id, plus the space they granted from. Save it in one column and hand it back. It is an identifier, not a secret, and it stays the same if the user disconnects and connects again.
+
+**Token mode**: pass a token store instead.
+
+```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,
+  oneApiUrl: process.env.ONE_API_URL,
+  tokenStore: {                                             // ← this makes it token mode
     saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
     loadTokens: (userId) => db.oneTokens.find(userId),
     clearTokens: (userId) => db.oneTokens.delete(userId),
@@ -117,6 +152,12 @@ export const oneConnect = createOneConnect({
 });
 ```
 
+To be explicit, add `mode: "key"` or `mode: "token"`. `oneConnect.mode` tells you which one is running. An app written before key mode existed passes only a `tokenStore`, so it keeps running in token mode with no change.
+
+## 4 · The two routes
+
+The same file in both modes:
+
 ```ts
 // app/api/one/[action]/route.ts   (Next.js; also Remix, SvelteKit, Hono, Bun)
 import { createOneConnectRoutes } from "@withone/connect/next";
@@ -129,7 +170,9 @@ export const { GET } = createOneConnectRoutes(oneConnect, {
 
 That file serves `/api/one/authorize` and `/api/one/callback`. For Express or plain Node, use `createOneConnectHandlers` from `@withone/connect/node`.
 
-## 4 · Using the grant
+## 5 · Using the grant
+
+The same calls in both modes:
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // what the user granted
@@ -141,17 +184,35 @@ const reply = await oneConnect.runAction(userId, {
   method: actions[0].method,
   path: actions[0].path,
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
 ```
 
-A `403` means the call is outside what the user granted. Don't retry it.
+A `403` means the call is outside what the user granted. Don't retry it. In key mode `blockedByGrant` is `true` for those.
+
+Errors are `OneConnectError` with a `code`:
+
+| `code` | Mode | What it means | What to do |
+|---|---|---|---|
+| `not_connected` | both | Nothing is stored for this user. | Show the Connect button. |
+| `reconnect_required` | key | One will not act for this user: they revoked access, or the app is deactivated. | Ask the user to connect again. Your stored value is kept. |
+| `refresh_failed` | token | The grant ended (revoked or expired). The tokens were cleared. | Ask the user to connect again. |
+| `request_failed` | both | One answered with an error or could not be reached. Nothing stored changed. | Retry later. |
+
+## 6 · Key mode notes
+
+- Keep the connect key on the server, in an environment variable. It is bound to your app and does nothing without a user's id.
+- A key works in one environment. Use the Production key in production and the Sandbox key in sandbox; the wrong one refuses every user.
+- `isConnected(userId)` says whether the user has connected before. One confirms the consent on each call, so a user who revoked is found by the next call throwing `reconnect_required`.
+- `oneConnect.getConnectUserId(userId)` returns the user's One id (`cu_…`) if you want it for your own records.
+- Lost or leaked a key? Create another on the app's page and delete the old one under **Developers → API keys**.
 
-## 5 · Tokens
+## 7 · Token mode notes
 
-- Store them in your database, encrypted, keyed by your user id. The SDK refreshes them for you.
+- Store the tokens in your database, encrypted, keyed by your user id. The SDK refreshes them for you.
+- The access token lives as long as your app's **Token lifetime** says: 30 days unless you changed it under **Advanced** when creating or editing the app. The refresh token lives 30 days, and only a live refresh token can renew the pair.
 - Running more than one server or a background worker? Add `withLock(userId, run)` to your token store, for example a Postgres advisory lock. Two servers refreshing at once would otherwise disconnect the user.
-- Keep idle users connected: once a day, call `oneConnect.refreshIfExpiring(userId, { withinMs: 7 * 24 * 3_600_000 })`.
-- A `refresh_failed` error means the grant ended (revoked or expired). Ask the user to connect again.
+- Required: once a day, for each connected user, call `oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 })`. It renews both tokens when either is within 3 days of expiring. Without it, users have to connect again when the tokens run out. Keep the window shorter than your Token lifetime, or every run refreshes.
+- `getAccessToken`, `getTokens`, `refreshTokens` and `refreshIfExpiring` exist in token mode only.
 
 To ask for more tools later, edit your app's tools in the dashboard. Users see only the new ones the next time they connect.
 

package/dist/next.d.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
      *  signed in. The grant is stored under this id. */
@@ -33,4 +33,4 @@ export declare const CALLBACK_ROUTE = "callback";
 export declare function readCookie(request: Request, name: string): string | undefined;
 /** The last path segment names the leg: ".../authorize" or ".../callback". */
 export declare function routeFor(url: string): string;
-export declare function createOneConnectRoutes(oneConnect: OneConnect, options: OneConnectRoutesOptions): OneConnectRoutes;
+export declare function createOneConnectRoutes(oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">, options: OneConnectRoutesOptions): OneConnectRoutes;

package/dist/node.d.ts

@@ -15,7 +15,7 @@
  *   app.get("/api/one/callback", callback);
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-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
      *  signed in. */
@@ -30,4 +30,4 @@ export interface OneConnectHandlers {
     authorize: NodeHandler;
     callback: NodeHandler;
 }
-export declare function createOneConnectHandlers(oneConnect: OneConnect, options: OneConnectNodeOptions): OneConnectHandlers;
+export declare function createOneConnectHandlers(oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">, options: OneConnectNodeOptions): OneConnectHandlers;

package/dist/server/credential.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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;
+}