@withone/connect 0.13.1 → 0.13.2

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
-                             saves the grant for the user, 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 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
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback  # exactly the registered URL
 ONE_PERMISSION_SET=…                                  # optional: the tools you ask for
 ```
@@ -98,7 +101,7 @@ To match your design, set `--one-connect-font` and `--one-connect-radius`, or st
 
 ## 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.
+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
@@ -109,17 +112,16 @@ export const oneConnect = createOneConnect({
   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),
+  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 }),
   },
 });
 ```
 
-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.
+`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
 
@@ -147,53 +149,34 @@ const reply = await oneConnect.runAction(userId, {
   method: actions[0].method,
   path: actions[0].path,
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
 ```
 
-You never set a header: the client adds the user's credential to every call it makes.
+You never set a header: the client adds the connect key and the user's id to every call it makes.
 
-A `403` means the call is outside what the user granted. Don't retry it.
+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` | 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. |
+| `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 · 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 |
+## 6 · Key mode notes
 
-```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.
+- 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.
+- 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, 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 · 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.
+## 7 · Token mode
 
-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`.
+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.
 
 ```ts
 export const oneConnect = createOneConnect({
@@ -201,19 +184,36 @@ export const oneConnect = createOneConnect({
   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 }),
+  tokenStore: {
+    saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
+    loadTokens: (userId) => db.oneTokens.find(userId),
+    clearTokens: (userId) => db.oneTokens.delete(userId),
   },
 });
 ```
 
-- `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.
+- 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.
+- 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.
+
+**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.1",
+  "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,29 +1,29 @@
 ---
 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, storing and refreshing the grant, and calling One with it.
+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
 
 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 four things: a button, two routes, a daily refresh job, and the calls
-made with the grant.
+you wire three things: a button, two routes, and the calls made with the grant.
 
 ```
 Browser                    Your backend                          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 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.
+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`.
 
-Secrets and tokens stay on the server.
+The client secret and the connect key stay on the server.
 
 ## 1 - Ask the human for these
 
@@ -33,17 +33,19 @@ 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` | 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. |
 
-Never ask the human to paste the secret into the chat. Tell them which
-environment variable to set and read it from there.
+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.
 
 ## 2 - Environment (server only)
 
 ```bash
 ONE_CLIENT_ID=...
 ONE_CLIENT_SECRET=one_secret_...
+ONE_CONNECT_KEY=sk_live_...
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
 ONE_PERMISSION_SET=...        # optional
 ```
@@ -63,19 +65,23 @@ export const oneConnect = createOneConnect({
   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 */,
+  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 */,
   },
 });
 ```
 
 Use the app's own user id as the key and the database it already has.
 
-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).
+`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. The
+package writes it in the callback and reads it on every call; the app
+never passes it anywhere.
 
 ## 4 - The two routes
 
@@ -120,33 +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 }`.
 
-## 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
+## 6 - Calling One with the grant
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
@@ -159,20 +139,21 @@ const reply = await oneConnect.runAction(userId, {
   path: action.path,
   body: payload,
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
 ```
 
-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.
+Do not set any header. The package adds the connect key and the user's id
+to every call it makes.
 
-A `403` reply means the call is outside what the user granted. Do not retry it.
+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` | 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. |
+| `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
@@ -183,7 +164,7 @@ try {
 } catch (error) {
   if (
     error instanceof OneConnectError &&
-    ["not_connected", "refresh_failed"].includes(error.code)
+    ["not_connected", "reconnect_required"].includes(error.code)
   ) {
     // show the Connect button again
   } else {
@@ -192,31 +173,38 @@ try {
 }
 ```
 
-## 8 - Rules
+`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`.
 
-- 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.
+## 7 - Rules
+
+- Never put the client secret or the connect key in browser code, logs,
+  error reports, source files or prompts. Environment variables only.
+- 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 - Key mode (only when asked)
+## 8 - Done when
 
-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:
+1. The button leads to One's page; after signing in and authorizing, the user
+   lands back in the app and `onSuccess` fires.
+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` 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` and the app asks them to connect again.
 
-- `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.
+## 9 - Token mode (only when asked)
 
-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.
+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({
@@ -224,33 +212,44 @@ export const oneConnect = createOneConnect({
   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 */,
+  tokenStore: {
+    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
+    loadTokens: (userId) => /* read; null when never connected */,
+    clearTokens: (userId) => /* delete */,
   },
 });
 ```
 
-- `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.
+- 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.
 
-## 10 - Done when
+Tokens expire, and two things keep them fresh. Only the first is automatic:
 
-1. The button leads to One's page; after signing in and authorizing, the user
-   lands back in the app and `onSuccess` fires.
-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.
-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.
+| | 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.