@withone/connect 0.10.0 → 0.12.0

package/dist/vue.d.ts

@@ -1,35 +1,52 @@
 import type { PropType } from "vue";
-import { type ConnectButtonPlatformInput, type ConnectButtonVariant, type OneConnectTheme } from "@withone/connect";
+import { type ConnectButtonPlatformInput, type ConnectButtonSize, type ConnectButtonTheme, type ConnectButtonVariant, type ConnectFailureCode, type OneConnectTheme } from "@withone/connect";
 export declare const ConnectButton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     authorizeUrl: {
         type: StringConstructor;
         required: true;
     };
-    appTheme: {
-        type: PropType<OneConnectTheme>;
+    platforms: {
+        type: PropType<ConnectButtonPlatformInput[]>;
         default: undefined;
     };
-    label: {
-        type: StringConstructor;
+    connected: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    disabled: {
+        type: BooleanConstructor;
         default: undefined;
     };
     variant: {
         type: PropType<ConnectButtonVariant>;
         default: undefined;
     };
+    size: {
+        type: PropType<ConnectButtonSize>;
+        default: undefined;
+    };
+    fullWidth: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     theme: {
+        type: PropType<ConnectButtonTheme>;
+        default: undefined;
+    };
+    connectTheme: {
         type: PropType<OneConnectTheme>;
         default: undefined;
     };
-    platforms: {
-        type: PropType<ConnectButtonPlatformInput[]>;
+    /** @deprecated use connectTheme */
+    appTheme: {
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
-    description: {
+    accentColor: {
         type: StringConstructor;
         default: undefined;
     };
-    accentColor: {
+    label: {
         type: StringConstructor;
         default: undefined;
     };
@@ -37,41 +54,63 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         type: StringConstructor;
         default: undefined;
     };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     success: () => true;
-    error: (message: string) => boolean;
+    error: (message: string, code: ConnectFailureCode) => boolean;
+    cancel: () => true;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     authorizeUrl: {
         type: StringConstructor;
         required: true;
     };
-    appTheme: {
-        type: PropType<OneConnectTheme>;
+    platforms: {
+        type: PropType<ConnectButtonPlatformInput[]>;
         default: undefined;
     };
-    label: {
-        type: StringConstructor;
+    connected: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    disabled: {
+        type: BooleanConstructor;
         default: undefined;
     };
     variant: {
         type: PropType<ConnectButtonVariant>;
         default: undefined;
     };
+    size: {
+        type: PropType<ConnectButtonSize>;
+        default: undefined;
+    };
+    fullWidth: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     theme: {
+        type: PropType<ConnectButtonTheme>;
+        default: undefined;
+    };
+    connectTheme: {
         type: PropType<OneConnectTheme>;
         default: undefined;
     };
-    platforms: {
-        type: PropType<ConnectButtonPlatformInput[]>;
+    /** @deprecated use connectTheme */
+    appTheme: {
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
-    description: {
+    accentColor: {
         type: StringConstructor;
         default: undefined;
     };
-    accentColor: {
+    label: {
         type: StringConstructor;
         default: undefined;
     };
@@ -79,16 +118,26 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         type: StringConstructor;
         default: undefined;
     };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
 }>> & Readonly<{
     onSuccess?: (() => any) | undefined;
-    onError?: ((message: string) => any) | undefined;
+    onError?: ((message: string, code: ConnectFailureCode) => any) | undefined;
+    onCancel?: (() => any) | undefined;
 }>, {
+    connected: boolean;
     label: string;
-    variant: ConnectButtonVariant;
-    theme: OneConnectTheme;
+    disabled: boolean;
+    connectTheme: OneConnectTheme;
+    appTheme: OneConnectTheme;
     platforms: ConnectButtonPlatformInput[];
+    variant: ConnectButtonVariant;
+    size: ConnectButtonSize;
+    theme: ConnectButtonTheme;
     description: string;
-    appTheme: OneConnectTheme;
+    fullWidth: boolean;
     accentColor: string;
     connectedLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.esm.js

@@ -1 +1 @@
-import{defineComponent as e,ref as t,onMounted as r,watch as o,onBeforeUnmount as n,h as i}from"vue";import{propsIdentity as l,mountConnectButton as u,optionsFromProps as d}from"@withone/connect";const a=e({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},appTheme:{type:String,default:void 0},label:{type:String,default:void 0},variant:{type:String,default:void 0},theme:{type:String,default:void 0},platforms:{type:Array,default:void 0},description:{type:String,default:void 0},accentColor:{type:String,default:void 0},connectedLabel:{type:String,default:void 0}},emits:{success:()=>!0,error:e=>"string"==typeof e},setup(e,{emit:a}){const p=t(null);let s=null;const c=()=>{var t;null===(t=s)||void 0===t||t.destroy(),s=null,p.value&&(s=u(p.value,d({...e},{onSuccess:()=>a("success"),onError:e=>a("error",e)})))};return r(c),o(()=>l({...e}),c),n(()=>{var e;null===(e=s)||void 0===e||e.destroy(),s=null}),()=>i("div",{ref:p})}});export{a as ConnectButton};
+import{defineComponent as e,ref as t,onMounted as n,watch as o,onBeforeUnmount as r,h as i}from"vue";import{mountConnectButton as l}from"@withone/connect";const d={type:Boolean,default:void 0},a=e({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},platforms:{type:Array,default:void 0},connected:d,disabled:d,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:d,theme:{type:String,default:void 0},connectTheme:{type:String,default:void 0},appTheme:{type:String,default:void 0},accentColor:{type:String,default:void 0},label:{type:String,default:void 0},connectedLabel:{type:String,default:void 0},description:{type:String,default:void 0}},emits:{success:()=>!0,error:(e,t)=>"string"==typeof e&&"string"==typeof t,cancel:()=>!0},setup(e,{emit:d}){const a=t(null);let u=null;const c=()=>({...e,onSuccess:()=>d("success"),onError:(e,t)=>d("error",e,t),onCancel:()=>d("cancel")});return n(()=>{a.value&&(u=l(a.value,c()))}),o(()=>({...e}),()=>{var e;return null===(e=u)||void 0===e?void 0:e.update(c())},{deep:!0}),r(()=>{var e;null===(e=u)||void 0===e||e.destroy(),u=null}),()=>i("div",{ref:a})}});export{a as ConnectButton};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "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",
@@ -27,8 +27,11 @@
     "@tsconfig/recommended": "^1.0.3",
     "@types/node": "^22.15.0",
     "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^20.14.5",
     "prettier": "^3.2.5",
     "react": "^19.2.8",
+    "react-dom": "^19.3.0",
     "rollup": "^4.12.0",
     "rollup-plugin-typescript2": "^0.36.0",
     "tslib": "^2.6.2",

package/skills/one-connect/SKILL.md

@@ -72,7 +72,9 @@ export const oneConnect = createOneConnect({
   tokenStore: {
     saveTokens: (userId, tokens) => /* write to this app's database, encrypted, keyed by its user */,
     loadTokens: (userId) => /* read; null when the user never connected */,
-    clearTokens: (userId) => /* delete */,
+    clearTokens: (userId, failed) => /* delete; when `failed` is set, only if the stored refreshToken is still failed.refreshToken */,
+    // Required when the app runs more than one process (serverless, several instances, a worker):
+    withLock: (userId, run) => /* run() while holding a per-user lock all processes share, e.g. pg_advisory_xact_lock */,
   },
 });
 ```
@@ -81,6 +83,14 @@ export const oneConnect = createOneConnect({
 id as the key. Implement the store on whatever the app already uses; do not
 add a database for it.
 
+One rotates the refresh token on every refresh and revokes the whole grant if
+an old one is used again. So when two processes could refresh the same user,
+`withLock` is not optional: without it, a web request and a worker refreshing
+together disconnect the user. The README's "Tokens" section has a Postgres
+version. For background work, call `refreshIfExpiring(userId, { withinMs })`:
+every few minutes with a window of minutes to keep access tokens warm, and
+once a day with a window of days so idle users' 30-day refresh tokens renew.
+
 ## 4 - The two routes
 
 Next.js App Router (also Remix, SvelteKit, Hono, Bun: anything with the web `Request`):
@@ -116,32 +126,50 @@ The routes mint `state` and PKCE, keep them in a per-flow httpOnly cookie
 (`one_tx_<state>`, SameSite=Lax, 30 minutes), verify the state on return,
 exchange the code with the secret over HTTP Basic, store both tokens, and
 redirect to `/` with `?one_connect=success` or
-`?one_connect=error&one_connect_message=...`. Pass `returnTo` to
+`?one_connect=error&one_connect_error=declined|expired|failed` (a code, never
+free text: the SDK shows fixed text for it). Pass `returnTo` to
 `createOneConnect` to land somewhere else.
 
 ## 5 - The button
 
 ```tsx
-import { ConnectButton } from "@withone/connect/react";
+import { ConnectButton } from "@withone/connect/react";   // "use client" bundle: fine in a Server Component
 
 <ConnectButton
   authorizeUrl="/api/one/authorize"
-  platforms={["stripe", "google-calendar"]}   // connector slugs; logos and names come from One
-  onSuccess={() => { /* refresh app state; the tokens are already stored */ }}
-  onError={(message) => { /* show it; the user may simply have declined */ }}
+  platforms={["stripe", "google-calendar"]}   // connector slugs; logos from One's CDN, names from the slug
+  connected={hasGrant}                         // from the server (e.g. await oneConnect.isConnected(userId))
+  onSuccess={() => { /* refetch app state; the tokens are already stored */ }}
+  onError={(message, code) => { /* show message; code: declined | expired | failed */ }}
 />
 ```
 
-Vue: `import { ConnectButton } from "@withone/connect/vue"` with `authorize-url`,
-`:platforms`, `@success`, `@error`. Svelte: `import { connectButton } from
-"@withone/connect/svelte"` as `use:connectButton={{ authorizeUrl, platforms,
-onSuccess }}`. Anything else: `import "@withone/connect"` registers
-`<one-connect-button authorize-url="/api/one/authorize" platforms="stripe, notion">`,
-which dispatches `success` and `error` events. A custom element:
-`useOneConnect({ authorizeUrl, onSuccess, onError }).open` on a click.
-
-The flow is a same-tab redirect. `onSuccess` and `onError` fire once when the
-tab comes back, and the SDK removes the `one_connect` params from the URL.
+Other props: `disabled`, `variant` ("default" | "accent" | "block"), `size`
+("sm" | "md" | "lg"), `fullWidth`, `theme` ("light" | "dark" | "auto"),
+`connectTheme` (One's page), `accentColor`, `label`, `connectedLabel`,
+`description` (block), `onCancel` (user pressed Back on One's page).
+
+Always pass `connected` from the server. Without it the button forgets after
+a reload and asks the user to connect again.
+
+Vue: `import { ConnectButton } from "@withone/connect/vue"` with the same props
+in kebab case (`authorize-url`, `:connected`), and `@success`, `@error`,
+`@cancel`. Svelte: `import { connectButton } from "@withone/connect/svelte"`
+as `use:connectButton={{ authorizeUrl, platforms, connected, onSuccess }}`.
+Anything else: `import "@withone/connect"` registers
+`<one-connect-button authorize-url="/api/one/authorize" platforms="stripe, notion" connected>`,
+which dispatches `success`, `error` (detail `{ message, code }`) and `cancel`.
+A custom button in React: `const { open, status, error } = useOneConnect({ authorizeUrl })`
+from `@withone/connect/react`. Elsewhere: `createConnectFlow({ authorizeUrl, onSuccess, onError }).open`.
+
+The button renders in a shadow root with a constructed stylesheet, so it
+works under a strict CSP. Allow `https://assets.withone.ai` in `img-src` for
+the logos. Style it with `--one-connect-font`, `--one-connect-radius` and
+`::part(button)`; do not wrap it in extra styling divs.
+
+The flow is a same-tab redirect. The outcome is read once per page load:
+every button shows it, and the callbacks fire once, on the first button
+still mounted.
 
 ## 6 - Calling One with the grant
 
@@ -170,14 +198,22 @@ grant; the provider was never called. Do not retry. Any other `/v1` call:
 `oneConnect.fetch(userId, "/connections", init)`.
 
 `OneConnectError` codes: `not_connected` (no tokens stored), `refresh_failed`
-(One refused the refresh; the tokens were cleared; ask the user to connect
-again), `request_failed` (One answered with an error; `status` carries it).
+(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; `status` carries it; during a refresh the
+tokens are KEPT, so retry later rather than asking the user to reconnect).
+
+To ask users for more tools later, edit the app's permission set in the
+dashboard. The next Connect shows only the new tools as "needs one more
+connection" and the callback stores the new pair; no code change.
 
 ## 7 - Rules
 
 - Never put the secret in a client bundle, a log line or an error report.
 - Store tokens encrypted, keyed by the app's user. Delete them when the user
-  is deleted. The client deletes them itself when a refresh fails.
+  is deleted. The client deletes them itself only when One declares the
+  grant dead, and never deletes a newer pair saved in the meantime.
+- Give the store `withLock` whenever more than one process can refresh.
 - The registered redirect URI and `ONE_REDIRECT_URI` must be the same string.
 - Do not build a completion page. The callback redirect is the completion.
 - Do not write the OAuth steps by hand when the package exposes them.