@withone/connect 0.11.0 → 0.12.0

package/dist/server/index.esm.js

@@ -4,7 +4,8 @@ import { randomBytes, createHash } from 'node:crypto';
  *  The SDK reads them off the page URL when the tab comes home, so
  *  there is no completion page to build. */
 const RETURN_STATUS_PARAM = "one_connect";
-const RETURN_MESSAGE_PARAM = "one_connect_message";
+/** Why the flow failed, as a code (see ConnectFailureCode). */
+const RETURN_ERROR_PARAM = "one_connect_error";
 
 /** One's production API. Point `oneApiUrl` elsewhere for development. */
 const DEFAULT_ONE_API_URL = "https://api.withone.ai";
@@ -180,10 +181,10 @@ function createOneConnect(config) {
   /** One refresh in flight per user: two concurrent refreshes with the
    *  same refresh token trip One's reuse detection. */
   const refreshing = new Map();
-  const returnUrl = (status, message) => {
+  const returnUrl = (status, code) => {
     const url = new URL(returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
-    if (message) url.searchParams.set(RETURN_MESSAGE_PARAM, message);
+    if (code) url.searchParams.set(RETURN_ERROR_PARAM, code);
     return url.toString();
   };
   const postToken = async body => {
@@ -260,17 +261,18 @@ function createOneConnect(config) {
     const oauthError = params.get("error");
     const cookieName = state ? txCookieName(state) : undefined;
     const verifier = cookieName ? input.getCookie(cookieName) : undefined;
-    const fail = (outcome, message) => ({
-      outcome,
+    const fail = (failure, message) => ({
+      outcome: failure === "declined" ? "declined" : "failed",
+      code: failure,
       message,
-      redirectUrl: returnUrl("error", message),
+      redirectUrl: returnUrl("error", failure),
       clearCookieName: cookieName
     });
-    if (oauthError === "access_denied") return fail("declined", "You cancelled the request.");
+    if (oauthError === "access_denied") return fail("declined", "The user cancelled on One's page.");
     if (oauthError) return fail("failed", `One reported an error: ${oauthError}.`);
-    // The returned state names its own cookie. No cookie means a forged
-    // or stale state; the code is never exchanged in that case.
-    if (!code || !state || !verifier) return fail("failed", "The sign-in attempt expired or was tampered with.");
+    // The returned state names its own cookie. No cookie means a stale,
+    // foreign or forged state; the code is never exchanged in that case.
+    if (!code || !state || !verifier) return fail("expired", "The attempt expired, or its state cookie was missing.");
     try {
       const tokens = toTokens(await exchange(new URLSearchParams({
         grant_type: "authorization_code",

package/dist/server/types.d.ts

@@ -101,10 +101,15 @@ export interface CompleteAuthorizationInput {
     /** Reads a cookie by name from the incoming request. */
     getCookie: (name: string) => string | undefined;
 }
+import type { ConnectFailureCode } from "../types";
+export type { ConnectFailureCode };
 export type AuthorizationOutcome = "connected" | "declined" | "failed";
 export interface CompleteAuthorizationResult {
     outcome: AuthorizationOutcome;
-    /** Safe to show to the user when the outcome is not "connected". */
+    /** Why it failed, as the code the browser receives. Only the code goes
+     *  on the return URL; the browser shows fixed text for it. */
+    code?: ConnectFailureCode;
+    /** What happened, for your logs. Never put it in front of the user. */
     message?: string;
     /** Send the browser here with a 302; it carries `?one_connect=…`. */
     redirectUrl: string;

package/dist/svelte.cjs.js

@@ -1 +1 @@
-"use strict";var t=require("@withone/connect");exports.connectButton=function(o,n){let e=t.mountConnectButton(o,t.optionsFromProps(n));return{update(n){e.destroy(),e=t.mountConnectButton(o,t.optionsFromProps(n))},destroy(){e.destroy()}}};
+"use strict";var t=require("@withone/connect");exports.connectButton=function(n,e){const o=t.mountConnectButton(n,e);return{update:t=>o.update(t),destroy:()=>o.destroy()}};

package/dist/svelte.d.ts

@@ -5,7 +5,7 @@
  * Svelte compiler or dependency is involved:
  *
  *   <div use:connectButton={{ authorizeUrl: "/api/one/authorize",
- *     platforms: ["stripe", "notion"],
+ *     platforms: ["stripe", "notion"], connected: data.hasOneGrant,
  *     onSuccess: () => { ... } }} />
  */
 import { type ConnectButtonProps } from "@withone/connect";

package/dist/svelte.esm.js

@@ -1 +1 @@
-import{mountConnectButton as t,optionsFromProps as e}from"@withone/connect";function o(o,r){let n=t(o,e(r));return{update(r){n.destroy(),n=t(o,e(r))},destroy(){n.destroy()}}}export{o as connectButton};
+import{mountConnectButton as t}from"@withone/connect";function o(o,e){const n=t(o,e);return{update:t=>n.update(t),destroy:()=>n.destroy()}}export{o as connectButton};

package/dist/types.d.ts

@@ -8,32 +8,55 @@
  */
 /** Theme of One's hosted connect page. */
 export type OneConnectTheme = "light" | "dark";
-export interface OneConnectOptions {
+/** Theme of the button: fixed, or following the visitor's setting. */
+export type ConnectButtonTheme = "light" | "dark" | "auto";
+/**
+ * Why a flow ended without a grant. The callback route puts only this
+ * code on the return URL; the text shown for it is fixed in the SDK, so
+ * a crafted link can never put its own words in front of the user.
+ *
+ * - `declined`: the user cancelled on One's page.
+ * - `expired`: the attempt took too long or was started elsewhere.
+ * - `failed`: One could not complete the connection.
+ */
+export type ConnectFailureCode = "declined" | "expired" | "failed";
+export interface OneConnectFlowOptions {
     /** The app's own backend authorize route. Relative paths such as
      *  "/api/one/authorize" resolve against the page's origin. */
     authorizeUrl: string;
     /** Theme for One's hosted page. Carried on the URL fragment, which
      *  survives the redirect chain, so the backend forwards nothing. */
+    connectTheme?: OneConnectTheme;
+    /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
     appTheme?: OneConnectTheme;
-    /** The grant completed and the backend stored the tokens. */
+    /** The grant completed and the backend stored the tokens. Fires once
+     *  per page load, on the first flow still mounted when the tab
+     *  returns. Treat it as a hint to refetch: your server is the truth. */
     onSuccess?: () => void;
-    /** The flow ended without a grant: the user declined, the attempt
-     *  expired, or the exchange failed. `message` is safe to show. */
-    onError?: (message: string) => void;
+    /** The flow ended without a grant. `message` is fixed text for
+     *  `code`, safe to show. */
+    onError?: (message: string, code: ConnectFailureCode) => void;
+    /** The user came back with the browser's Back button before finishing
+     *  (the page was restored from the back-forward cache). */
+    onCancel?: () => void;
 }
-export interface OneConnectHandle {
+export interface OneConnectFlow {
     /** Navigates the tab to One's hosted connect flow. */
     open: () => void;
+    /** Swaps the options (callbacks, theme) without losing the flow. */
+    update: (options: OneConnectFlowOptions) => void;
+    /** Stops listening: callbacks no longer fire for this flow. */
+    destroy: () => void;
 }
-/** How the app's callback route reports the outcome on its final
- *  redirect, read off the page URL when the tab returns. */
+/** How the flow ended, read off the page URL when the tab returns. */
 export interface OneConnectReturn {
     status: "success" | "error";
+    code?: ConnectFailureCode;
     message?: string;
 }
 /**
  * A connector chip on the button. Pass One's connector slug ("stripe",
- * "google-calendar") and the SDK shows the logo and the name; pass an
+ * "google-calendar") and the SDK shows its logo and name; pass an
  * object to override either.
  */
 export type ConnectButtonPlatformInput = string | {
@@ -48,31 +71,50 @@ export interface ConnectButtonPlatform {
     imageUrl: string;
 }
 export type ConnectButtonVariant = "default" | "accent" | "block";
+export type ConnectButtonSize = "sm" | "md" | "lg";
 export type ConnectButtonState = "idle" | "connecting" | "connected";
-export interface ConnectButtonOptions {
-    /** Everything the flow needs; the button wires open() and the
-     *  Connecting and Connected states around your callbacks. */
-    connect: OneConnectOptions;
-    /** "Connect your apps" unless overridden. */
-    label?: string;
-    /** default = neutral pill; accent = brand-colored pill; block =
-     *  full-width card with a description and a "Secured by One" foot. */
-    variant?: ConnectButtonVariant;
-    /** Matches the host page, not One's page (that is connect.appTheme). */
-    theme?: OneConnectTheme;
-    /** Connector chips. The first three render; the rest fold into a "+N"
-     *  chip, so that count only ever describes this list. */
+/** One prop shape for every surface: React, Vue, Svelte, the custom
+ *  element and `mountConnectButton`. */
+export interface ConnectButtonProps {
+    /** The app's own backend authorize route; relative is fine. */
+    authorizeUrl: string;
+    /** Connector slugs, or objects that override the name or the logo.
+     *  The first three draw as logos; the rest fold into a "+N" chip. */
     platforms?: ConnectButtonPlatformInput[];
-    /** Sub-line on the block variant, shown while idle. */
-    description?: string;
-    /** Fill of the accent variant; One's lime when omitted. */
+    /** Whether this user has a live grant, from your server. When set, it
+     *  decides the Connected state. When omitted, the button shows
+     *  Connected only right after a successful return. */
+    connected?: boolean;
+    /** Not clickable, for example until terms are accepted. */
+    disabled?: boolean;
+    /** default = neutral, accent = your brand colour, block = a card with
+     *  a description and a "Secured by One" foot. */
+    variant?: ConnectButtonVariant;
+    size?: ConnectButtonSize;
+    /** Stretches to the width of its container. */
+    fullWidth?: boolean;
+    /** Matches the host page. "auto" follows the visitor's setting. */
+    theme?: ConnectButtonTheme;
+    /** Theme of One's hosted page. */
+    connectTheme?: OneConnectTheme;
+    /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
+    appTheme?: OneConnectTheme;
+    /** Fill of the accent variant; One's lime when omitted. The label is
+     *  black or white, whichever reads better on it. */
     accentColor?: string;
-    /** Label for the connected state. */
+    /** "Connect your apps" unless set. */
+    label?: string;
+    /** "Connected" unless set. */
     connectedLabel?: string;
+    /** Sub-line on the block variant. */
+    description?: string;
+    onSuccess?: () => void;
+    onError?: (message: string, code: ConnectFailureCode) => void;
+    onCancel?: () => void;
 }
 export interface ConnectButtonHandle {
-    /** Override the visual state by hand. */
-    setState: (state: ConnectButtonState) => void;
-    /** Remove the button. */
+    /** Applies new props in place, keeping the button's state. */
+    update: (props: ConnectButtonProps) => void;
+    /** Removes the button and stops its callbacks. */
     destroy: () => void;
 }

package/dist/vue.cjs.js

@@ -1 +1 @@
-"use strict";var e=require("vue"),t=require("@withone/connect");const n=e.defineComponent({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(n,{emit:o}){const r=e.ref(null);let i=null;const u=()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null,r.value&&(i=t.mountConnectButton(r.value,t.optionsFromProps({...n},{onSuccess:()=>o("success"),onError:e=>o("error",e)})))};return e.onMounted(u),e.watch(()=>t.propsIdentity({...n}),u),e.onBeforeUnmount(()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null}),()=>e.h("div",{ref:r})}});exports.ConnectButton=n;
+"use strict";var e=require("vue"),t=require("@withone/connect");const n={type:Boolean,default:void 0},o=e.defineComponent({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},platforms:{type:Array,default:void 0},connected:n,disabled:n,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:n,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(n,{emit:o}){const r=e.ref(null);let i=null;const d=()=>({...n,onSuccess:()=>o("success"),onError:(e,t)=>o("error",e,t),onCancel:()=>o("cancel")});return e.onMounted(()=>{r.value&&(i=t.mountConnectButton(r.value,d()))}),e.watch(()=>({...n}),()=>{var e;return null===(e=i)||void 0===e?void 0:e.update(d())},{deep:!0}),e.onBeforeUnmount(()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null}),()=>e.h("div",{ref:r})}});exports.ConnectButton=o;

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.11.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

@@ -126,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