@withone/connect 0.12.2 → 0.13.1

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 the grant for the user, redirects home
 onSuccess()      ◄──────
 later:                     oneConnect.runAction(userId, …)  ──►  One, grant enforced
 ```
@@ -50,7 +50,6 @@ ONE_CLIENT_ID=…
 ONE_CLIENT_SECRET=one_secret_…                        # server only
 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
 ```
 
 ## 2 · The button
@@ -97,7 +96,9 @@ 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 · The server client
+
+Your server keeps an access token and a refresh token for each user who connects. This is **token mode**, and it is the one to use.
 
 ```ts
 // lib/one.ts
@@ -108,7 +109,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) => db.oneTokens.upsert(userId, tokens),
     loadTokens: (userId) => db.oneTokens.find(userId),
@@ -117,6 +117,12 @@ export const oneConnect = createOneConnect({
 });
 ```
 
+Store the tokens in your database, encrypted, keyed by your user id.
+
+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.
+
+## 4 · The two routes
+
 ```ts
 // app/api/one/[action]/route.ts   (Next.js; also Remix, SvelteKit, Hono, Bun)
 import { createOneConnectRoutes } from "@withone/connect/next";
@@ -129,7 +135,7 @@ 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
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // what the user granted
@@ -144,17 +150,71 @@ const reply = await oneConnect.runAction(userId, {
 // { status, ok, data }
 ```
 
+You never set a header: the client adds the user's credential to every call it makes.
+
 A `403` means the call is outside what the user granted. Don't retry it.
 
-## 5 · Tokens
+Errors are `OneConnectError` with a `code`:
+
+| `code` | What it means | What to do |
+|---|---|---|
+| `not_connected` | Nothing is stored for this user. | Show the Connect button. |
+| `refresh_failed` | The grant ended (revoked or expired). 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. |
+
+## 6 · Keeping users connected
+
+Tokens expire, and two things keep them fresh. One is automatic. The other is yours to run.
 
-- Store them in your database, encrypted, keyed by your user id. The SDK refreshes them for you.
-- 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.
+| | Who does it | When |
+|---|---|---|
+| Refresh before a call | the client, on its own | whenever you call One and the token is about to expire |
+| Refresh for users who have not called in a while | **you**, with a daily job | once a day, for every connected user |
+
+```ts
+// run once a day
+for (const userId of await db.oneTokens.allUserIds()) {
+  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
+}
+```
+
+The job renews both tokens when either is within 3 days of expiring. 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.
+
+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. Keep the job's window shorter than that, or every run refreshes.
 
 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.
 
+## 7 · Key mode
+
+A second way to hold a grant: one **connect key** for your app and one permanent id per user, with nothing to refresh. The button, the routes and the calls stay the same.
+
+Two limits today, so use token mode unless you have a reason not to:
+
+- `listActions` does not work in key mode yet. Your app has to know the actions it runs.
+- It works in Production only. Create the key with your dashboard on Production.
+
+Create the key on your app's page, under **Credentials → Connect key**. It is shown once. Keep it on the server as `ONE_CONNECT_KEY`.
+
+```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) => 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. Save it in one column and hand it back unchanged. It is an identifier, not a secret.
+- When a user revokes access, the next call throws `reconnect_required` instead of `refresh_failed`. Ask them to connect again; your stored value is kept.
+- A `403` reply carries `blockedByGrant: true` when the call is outside what the user granted.
+- The mode is whichever credential you pass: `tokenStore` for token mode, `connectKey` and `userStore` for key mode. `oneConnect.mode` tells you which one is running.
+
 ## License
 
 GPL-3.0. See [LICENSE](LICENSE).

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;
+}