@withone/connect 0.13.0 → 0.13.2

package/README.md

@@ -45,15 +45,14 @@ 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.
+Then, on the app's page, under **Credentials → Connect keys**, create a key with your dashboard on Production. It is shown once.
 
 ```env
 ONE_CLIENT_ID=…
 ONE_CLIENT_SECRET=one_secret_…                        # server only
-ONE_CONNECT_KEY=sk_live_…                             # server only: the app's connect key
+ONE_CONNECT_KEY=sk_live_…                             # 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
@@ -100,19 +99,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 · Choose a mode
+## 3 · The server client
 
-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.
+Your server holds one **connect key** for the app and saves one id per user who connects. Nothing expires and nothing is refreshed: One checks the user's consent on every call. This is **key mode**, the default.
 
 ```ts
 // lib/one.ts
@@ -123,8 +112,7 @@ 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,
-  connectKey: process.env.ONE_CONNECT_KEY!,                 // ← this makes it key mode
+  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,
@@ -133,31 +121,10 @@ export const oneConnect = createOneConnect({
 });
 ```
 
-`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),
-  },
-});
-```
-
-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.
+`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 unchanged. It is an identifier, not a secret, and it stays the same if the user disconnects and connects again.
 
 ## 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";
@@ -172,8 +139,6 @@ That file serves `/api/one/authorize` and `/api/one/callback`. For Express or pl
 
 ## 5 · Using the grant
 
-The same calls in both modes:
-
 ```ts
 const connections = await oneConnect.listConnections(userId);   // what the user granted
 const actions = await oneConnect.listActions(userId, "gmail");  // what a platform can do
@@ -187,34 +152,68 @@ const reply = await oneConnect.runAction(userId, {
 // { status, ok, blockedByGrant, data }
 ```
 
-A `403` means the call is outside what the user granted. Don't retry it. In key mode `blockedByGrant` is `true` for those.
+You never set a header: the client adds the connect key and the user's id to every call it makes.
+
+A `403` with `blockedByGrant: true` means the call is outside what the user granted. Don't retry it.
 
 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. |
+| `code` | What it means | What to do |
+|---|---|---|
+| `not_connected` | Nothing is stored for this user. | Show the Connect button. |
+| `reconnect_required` | One will not act for this user: they revoked access, or the app is deactivated. Your stored value is kept. | Ask the user to connect again. |
+| `request_failed` | 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.
+- Connect keys work in Production only. Create the key with your dashboard on Production.
 - `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**.
+- Lost or leaked a key? Create another on the app's page, move your servers to it, then revoke the old one there.
+
+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 · Token mode
 
-## 7 · Token mode notes
+The other way to hold a grant: your server stores an access token and a refresh token per user, as a standard OAuth client. The button, the routes and the calls stay the same. Use it when you need bearer tokens, or when the app already has them; an app that passes only a `tokenStore` keeps running in token mode with no change.
 
-- 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.
+```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,
+  tokenStore: {
+    saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
+    loadTokens: (userId) => db.oneTokens.find(userId),
+    clearTokens: (userId) => db.oneTokens.delete(userId),
+  },
+});
+```
+
+- 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.
-- 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.
+- When a user revokes access, the next refresh throws `refresh_failed` and the tokens are cleared. Ask them to connect again.
+- A `403` means the call is outside what the user granted; `blockedByGrant` stays `false` in token mode.
 
-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.
+**Keeping users connected.** Tokens expire, and two things keep them fresh. One is automatic. The other is yours to run.
+
+| | 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**); keep the job's window shorter than that, or every run refreshes.
+
+The mode is whichever credential you pass: `connectKey` and `userStore` for key mode, `tokenStore` for token mode. `oneConnect.mode` tells you which one is running.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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,6 +1,6 @@
 ---
 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, choosing key mode or token mode, 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, the connect key, and calling One with the grant.
 ---
 
 # One Connect
@@ -18,6 +18,11 @@ Browser                    Your backend                          One
 Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
 ```
 
+Use **key mode**, described in sections 1 to 7: the app holds one connect
+key and saves one id per user, and nothing is refreshed. Token mode
+(section 9) is the other way to hold the grant; use it only when the human
+asks for it, or when the app already passes a `tokenStore`.
+
 The client secret and the connect key stay on the server.
 
 ## 1 - Ask the human for these
@@ -28,10 +33,9 @@ They create the app in the One dashboard: Developers -> Connect -> New app.
 |---|---|
 | `ONE_CLIENT_ID` | From the app. |
 | `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
-| `ONE_CONNECT_KEY` | Key mode only. On the app's page: Credentials -> Connect key -> Create key. Shown once. It is made for the environment the dashboard is on (Production or Sandbox). |
+| `ONE_CONNECT_KEY` | On the app's page: Credentials -> Connect keys -> Create key, with the dashboard on Production. 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 or the connect key into the chat.
 Tell them which environment variable to set and read it from there.
@@ -41,51 +45,17 @@ Tell them which environment variable to set and read it from there.
 ```bash
 ONE_CLIENT_ID=...
 ONE_CLIENT_SECRET=one_secret_...
-ONE_CONNECT_KEY=sk_live_...   # key mode
+ONE_CONNECT_KEY=sk_live_...
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
 ONE_PERMISSION_SET=...        # optional
-ONE_API_URL=...               # optional
 ```
 
-## 3 - Choose a mode
-
-The server holds a user's grant in one of two ways. The button, the two
-routes and every call are identical in both. The mode is whichever
-credential you pass to `createOneConnect`.
-
-| | Key mode (default) | Token mode |
-|---|---|---|
-| The server holds | one connect key for the app | nothing app-wide |
-| Stored per user | one string, saved once | an access token and a refresh token |
-| Expires | nothing; One checks the consent on every call | the tokens, on the lifetime set on the app |
-| Refreshing | none | the SDK does it; several servers need a shared lock |
-
-How to decide:
-
-- New integration: **key mode**.
-- The app already passes a `tokenStore`: it is in token mode. Leave it as it
-  is unless the human asks to move.
-- The human asks for OAuth bearer tokens: token mode.
-
-```ts
-// key mode
-createOneConnect({ ...app, connectKey: process.env.ONE_CONNECT_KEY!, userStore });
-
-// token mode
-createOneConnect({ ...app, tokenStore });
-```
-
-`mode: "key"` or `mode: "token"` may be added to be explicit.
-`oneConnect.mode` reports which one is running.
-
-## 4 - Install and create the client
+## 3 - Install and create the client
 
 ```bash
 npm install @withone/connect
 ```
 
-Key mode:
-
 ```ts
 // lib/one.ts  (server only)
 import { createOneConnect } from "@withone/connect/server";
@@ -95,7 +65,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,
   connectKey: process.env.ONE_CONNECT_KEY!,
   userStore: {
     saveUser: (userId, reference) => /* save the string on the app's user row */,
@@ -105,43 +74,16 @@ export const oneConnect = createOneConnect({
 });
 ```
 
+Use the app's own user id as the key and the database it already has.
+
 `reference` is one short string: the user's permanent One id and the space
 they granted from. One text column on the user row is enough. Store it as
 given and hand it back unchanged; do not parse or rebuild it. It is an
-identifier, not a secret, so it needs no encryption and no lock.
-
-Token mode:
-
-```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: {
-    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
-    loadTokens: (userId) => /* read; null when never connected */,
-    clearTokens: (userId) => /* delete */,
-  },
-});
-```
-
-In token mode, if the app runs more than one server process or a background
-worker, also add `withLock: (userId, run) => ...`, which runs `run()` while
-holding a per-user lock all processes share (for example a Postgres advisory
-lock). The access token lives as long as the app's Token lifetime says (30
-days unless changed under Advanced when creating the app); the refresh token
-lives 30 days. 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 the Token lifetime, or every run refreshes.
+identifier, not a secret, so it needs no encryption and no lock. The
+package writes it in the callback and reads it on every call; the app
+never passes it anywhere.
 
-In both modes use the app's own user id as the key and the database it
-already has.
-
-## 5 - The two routes
+## 4 - The two routes
 
 Next.js App Router (also Remix, SvelteKit, Hono, Bun):
 
@@ -161,7 +103,7 @@ Express or plain Node: `createOneConnectHandlers(oneConnect, { identifyUser })`
 from `@withone/connect/node`, mounted at `/api/one/authorize` and
 `/api/one/callback`.
 
-## 6 - The button
+## 5 - The button
 
 ```tsx
 import { ConnectButton } from "@withone/connect/react";
@@ -184,7 +126,7 @@ 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 }`.
 
-## 7 - Calling One with the grant
+## 6 - Calling One with the grant
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
@@ -200,17 +142,19 @@ const reply = await oneConnect.runAction(userId, {
 // { status, ok, blockedByGrant, data }
 ```
 
-A `403` reply means the call is outside what the user granted. Do not retry
-it. In key mode `blockedByGrant` is `true` for those.
+Do not set any header. The package adds the connect key and the user's id
+to every call it makes.
+
+A `403` reply with `blockedByGrant: true` 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` | Mode | Meaning | 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. The stored value is kept. | Ask the user to connect again. |
-| `refresh_failed` | token | The grant ended. 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. |
+| `code` | Meaning | Do |
+|---|---|---|
+| `not_connected` | Nothing is stored for this user. | Show the Connect button. |
+| `reconnect_required` | One will not act for this user: they revoked access, or the app is deactivated. The stored value is kept. | 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";
@@ -220,7 +164,7 @@ try {
 } catch (error) {
   if (
     error instanceof OneConnectError &&
-    ["not_connected", "reconnect_required", "refresh_failed"].includes(error.code)
+    ["not_connected", "reconnect_required"].includes(error.code)
   ) {
     // show the Connect button again
   } else {
@@ -229,31 +173,83 @@ try {
 }
 ```
 
-In key mode `isConnected(userId)` says 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`.
+`isConnected(userId)` says 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`.
 
-## 8 - Rules
+## 7 - Rules
 
 - Never put the client secret or the connect key in browser code, logs,
   error reports, source files or prompts. Environment variables only.
-- A connect key works in one environment. Use the Production key against
-  production and the Sandbox key against sandbox.
-- Key mode: store the per-user string as given. Token mode: store tokens
-  encrypted, keyed by the app's user.
+- Connect keys work in Production only; the human creates the key with
+  the dashboard on Production.
+- Store the per-user string as given.
 - 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 or One request headers by hand; use the package.
 - Do not switch an existing app from one mode to the other unless asked.
 
-## 9 - Done when
+## 8 - 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. Key mode: one string is saved for the user. Token mode: the tokens are saved.
+2. One string is 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. `runAction` works for an action inside the grant and returns `403` with
+   `blockedByGrant: true` for one outside it.
 5. After the user revokes the app in their One dashboard, the next call
-   fails with `reconnect_required` (key mode) or `refresh_failed` (token
-   mode) and the app asks them to connect again.
+   fails with `reconnect_required` and the app asks them to connect again.
+
+## 9 - Token mode (only when asked)
+
+The other way to hold the grant: the app stores an access token and a
+refresh token per user, as a standard OAuth client. The routes, the button
+and the calls are the same. No `ONE_CONNECT_KEY` is needed.
+
+```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,
+  tokenStore: {
+    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
+    loadTokens: (userId) => /* read; null when never connected */,
+    clearTokens: (userId) => /* delete */,
+  },
+});
+```
+
+- Store tokens encrypted, keyed by the app's user.
+- If the app runs more than one server process or a background worker, also
+  add `withLock: (userId, run) => ...`, which runs `run()` while holding a
+  per-user lock all processes share (for example a Postgres advisory lock).
+- When the user revokes access, the next refresh throws `refresh_failed`
+  (not `reconnect_required`) and the tokens are cleared. Ask them to connect
+  again.
+- `blockedByGrant` stays `false` in token mode; treat any `403` as outside
+  the grant.
+
+Tokens expire, and two things keep them fresh. 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 |
+
+```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 });
+}
+```
+
+Without the job, 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 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. In token mode, "done"
+also means the daily job exists and runs for every connected user.
+
+The mode is whichever credential `createOneConnect` is given: `connectKey`
+and `userStore` for key mode, `tokenStore` for token mode.