@withone/connect 0.8.3 → 0.9.0

package/dist/useOneConnect.d.ts

@@ -1,2 +1,13 @@
-import type { OneConnectHandle, OneConnectProps } from "./types";
-export declare const useOneConnect: (props: OneConnectProps) => OneConnectHandle;
+import type { OneConnectHandle, OneConnectOptions } from "./types";
+/**
+ * Wires the connect flow to any element. A plain function rather than a
+ * React hook, so it works from every framework: call it once where the
+ * button lives and pass `open` to a click.
+ *
+ * The flow is a full-page redirect: the tab goes to the app's authorize
+ * route, on to One's hosted page, back to the app's callback route, and
+ * home. On the way home the callback route appends `?one_connect=…` to
+ * the URL it redirects to; this function reads that on load, fires
+ * onSuccess or onError once, and removes the params from the address bar.
+ */
+export declare const useOneConnect: (options: OneConnectOptions) => OneConnectHandle;

package/dist/vue.cjs.js

@@ -1 +1 @@
-"use strict";var e=require("vue");function t(e,t,n){return(t=function(e){var t=function(e,t){if("object"!=typeof e||!e)return e;var n=e[Symbol.toPrimitive];if(void 0!==n){var o=n.call(e,t);if("object"!=typeof o)return o;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===t?String:Number)(e)}(e,"string");return"symbol"==typeof t?t:t+""}(t))in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}const n="one_connect",o="one_connect_message";let i=!1;const r=e=>{let t=!1;if("undefined"!=typeof window&&!i){const l=new URLSearchParams(window.location.search),c=l.get(n);if("success"===c||"error"===c){var r;i=!0;const a=null!==(r=l.get(o))&&void 0!==r?r:void 0,s=()=>{const e=new URLSearchParams(window.location.search);(e.has(n)||e.has(o))&&(e.delete(n),e.delete(o),window.history.replaceState(null,"",window.location.pathname+(e.toString()?`?${e.toString()}`:"")+window.location.hash))};s();for(const e of[50,500,2e3])window.setTimeout(s,e);window.setTimeout(()=>{if(!t){t=!0;try{var n,o;"success"===c?null===(n=e.onSuccess)||void 0===n||n.call(e):null===(o=e.onError)||void 0===o||o.call(e,null!=a?a:"The connection was not completed.")}catch{}}},0)}}return{open:()=>{"undefined"!=typeof window&&window.location.assign((()=>{try{const t=new URL(e.authorize.url,"undefined"==typeof window?void 0:window.location.origin);return e.appTheme&&(t.hash=`one_theme=${e.appTheme}`),t.toString()}catch{return e.authorize.url}})())},close:e=>{}}},l="one-connect-button-styles",c="cubic-bezier(.2,.9,.25,1)",a={btnBg:"#0A0C0B",btnFg:"#ffffff",surface:"#ffffff",fg:"#0A0C0B",muted:"#6B7280",line:"#D1D5DB",shadow:"0 1px 2px rgba(10,12,11,.08), 0 4px 14px rgba(10,12,11,.06)"},s={btnBg:"#F2F5F3",btnFg:"#0A0C0B",surface:"#101312",fg:"#F2F5F3",muted:"#8A938E",line:"#2A302D",shadow:"0 1px 2px rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.35)"},d="#CCFF00",p="#3FE3A5",u="#0A0C0B";function h(e){const t=e.trim().toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"");return t?`https://assets.withone.ai/connectors/${t}.svg`:""}const m=(e,t)=>{var n,o;!function(){if("undefined"==typeof document||document.getElementById(l))return;const e=document.createElement("style");e.id=l,e.textContent=[`.owcb{font:500 14.5px/1.2 inherit;font-family:inherit;letter-spacing:-.01em;cursor:pointer;border:0;display:inline-flex;align-items:center;gap:12px;padding:12px 16px 12px 14px;border-radius:12px;transition:transform .2s ${c},box-shadow .2s ${c},opacity .2s ${c}}`,".owcb:hover{transform:translateY(-1px)}",".owcb:active{transform:translateY(0)}",`.owcb:focus-visible{outline:2px solid ${p};outline-offset:3px}`,".owcb[disabled]{cursor:default;opacity:.75;transform:none}",".owcb-stack{display:inline-flex;align-items:center;flex-shrink:0}",`.owcb-chip{width:22px;height:22px;border-radius:6px;display:grid;place-items:center;overflow:hidden;margin-left:-7px;transition:margin-left .28s ${c};position:relative}`,".owcb-chip:first-child{margin-left:0}",".owcb-chip img{width:14px;height:14px;display:block;object-fit:contain}",".owcb-chip.owcb-more{font-family:ui-monospace,monospace;font-size:9px;font-weight:500;letter-spacing:-.02em}",".owcb:hover .owcb-chip{margin-left:-2px}",".owcb:hover .owcb-chip:first-child{margin-left:0}",".owcb-label{white-space:nowrap}",`.owcb-arrow{opacity:.5;transition:transform .2s ${c},opacity .2s ${c}}`,".owcb:hover .owcb-arrow{transform:translateX(2px);opacity:.8}",".owcb-spinner{width:16px;height:16px;border-radius:50%;border:2px solid currentColor;border-top-color:transparent;opacity:.7;animation:owcb-spin .7s linear infinite}","@keyframes owcb-spin{to{transform:rotate(360deg)}}",".owcb.owcb-block{display:flex;flex-direction:column;align-items:stretch;width:100%;max-width:420px;text-align:left;padding:16px;border-radius:14px;gap:0}",".owcb-block-top{display:flex;align-items:center;justify-content:space-between;gap:12px}",".owcb-block-title{font-size:15px;font-weight:600;letter-spacing:-.01em}",".owcb-block-sub{font-size:13px;line-height:1.5;margin-top:6px;font-weight:400}",".owcb-block-foot{margin-top:14px;padding-top:12px;display:flex;align-items:center;gap:6px;font-size:11.5px;font-weight:400}","@media (prefers-reduced-motion:reduce){.owcb,.owcb-chip,.owcb-arrow{transition:none}.owcb-spinner{animation-duration:1.4s}}"].join("\n"),document.head.appendChild(e)}();const i="dark"===t.theme?s:a,m=null!==(n=t.variant)&&void 0!==n?n:"default",f=null!==(o=t.label)&&void 0!==o?o:"Connect your apps";let b="idle",v=!1;const w=r({...t.connect,onSuccess:()=>{var e,n;y("connected"),null===(e=(n=t.connect).onSuccess)||void 0===e||e.call(n)},onError:e=>{var n,o;y("idle"),null===(n=(o=t.connect).onError)||void 0===n||n.call(o,e)},onClose:()=>{var e,n;y("idle"),null===(e=(n=t.connect).onClose)||void 0===e||e.call(n)}}),g=document.createElement("button");g.type="button",g.className="block"===m?"owcb owcb-block":"owcb",g.addEventListener("click",()=>{"idle"!==b&&"connected"!==b||(y("connecting"),w.open())});const x=()=>{var e,n,o;const r="accent"===m,l="block"===m,c=l?i.surface:r?null!==(e=t.accentColor)&&void 0!==e?e:d:i.btnBg,a=l?i.fg:r?u:i.btnFg,s=l?i.surface:c,v=u;g.style.background="connected"!==b||l?c:p,g.style.color="connected"!==b||l?a:u,g.style.boxShadow=l?`inset 0 0 0 1px ${i.line}`:"connected"===b?"none":r?`0 1px 2px rgba(10,12,11,.1), 0 6px 20px ${null!==(n=t.accentColor)&&void 0!==n?n:d}38`:i.shadow,g.disabled="connecting"===b,g.innerHTML="";const w=function(e,t,n){var o,i;const r=null!==(o=e.platforms)&&void 0!==o?o:[];if(0===r.length&&!e.moreCount)return null;const l=document.createElement("span");l.className="owcb-stack",l.setAttribute("aria-hidden","true");for(const e of r.slice(0,3)){var c;const n=document.createElement("span");n.className="owcb-chip",n.style.background="#ffffff",n.style.boxShadow=`0 0 0 1.5px ${t}`;const o=()=>{n.textContent=e.name.charAt(0).toUpperCase(),n.style.font="600 10px ui-monospace,monospace",n.style.color=u},i=null!==(c=e.imageUrl)&&void 0!==c?c:h(e.name);if(i){const e=document.createElement("img");e.alt="",e.src=i,e.addEventListener("error",()=>{e.remove(),o()}),n.appendChild(e)}else o();l.appendChild(n)}const a=(null!==(i=e.moreCount)&&void 0!==i?i:0)+Math.max(0,r.length-3);if(a>0){const e=document.createElement("span");e.className="owcb-chip owcb-more",e.style.background="#ffffff",e.style.boxShadow=`0 0 0 1.5px ${t}`,e.style.color=n,e.textContent=`+${a}`,l.appendChild(e)}return l}(t,s,v);if(l){var x;const e=document.createElement("span");e.className="owcb-block-top";const n=document.createElement("span");if(n.className="owcb-block-title",n.textContent="connecting"===b?"Connecting…":"connected"===b?null!==(x=t.connectedLabel)&&void 0!==x?x:"Connected":f,e.appendChild(n),"connecting"===b){const t=document.createElement("span");t.className="owcb-spinner",e.appendChild(t)}else w&&e.appendChild(w);if(g.appendChild(e),t.description&&"idle"===b){const e=document.createElement("span");e.className="owcb-block-sub",e.style.color=i.muted,e.textContent=t.description,g.appendChild(e)}const o=document.createElement("span");return o.className="owcb-block-foot",o.style.color=i.muted,o.style.borderTop=`1px solid ${i.line}`,o.innerHTML=`<span style="font-size:11px;color:${i.muted}">Secured by</span><span style="display:inline-flex;color:${i.fg}"><svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2.4" style="flex-shrink:0"><circle cx="12" cy="12" r="8.5"/></svg></span><span style="font-size:12px;font-weight:600;letter-spacing:-0.02em;color:${i.fg}">one</span>`,void g.appendChild(o)}if("connecting"===b){const e=document.createElement("span");e.className="owcb-spinner",g.appendChild(e)}else if("connected"===b){const e=document.createElement("span");e.innerHTML='<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:16px;height:16px"><path d="M3 8.5l3.5 3.5L13 5"/></svg>',e.style.display="inline-flex",g.appendChild(e)}else w&&g.appendChild(w);const y=document.createElement("span");if(y.className="owcb-label",y.textContent="connecting"===b?"Connecting…":"connected"===b?null!==(o=t.connectedLabel)&&void 0!==o?o:"Connected":f,g.appendChild(y),"idle"===b){const e=document.createElement("span");e.innerHTML='<svg class="owcb-arrow" width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3l5 5-5 5"/></svg>',e.style.display="inline-flex",g.appendChild(e)}},y=e=>{v||(b=e,x())};return x(),e.appendChild(g),{setState:y,destroy:()=>{v=!0,w.close({keepResult:!0}),g.remove()}}};!function(){if("undefined"!=typeof window&&"undefined"!=typeof customElements&&!customElements.get("one-connect-button")){class e extends HTMLElement{constructor(...e){super(...e),t(this,"onSuccess",null),t(this,"onError",null),t(this,"onClose",null),t(this,"handle",null)}connectedCallback(){this.mount()}disconnectedCallback(){var e;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null}attributeChangedCallback(){this.isConnected&&this.handle&&this.mount()}mount(){var e,t,n,o,i,r,l,c;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null;const a=this.getAttribute("authorize-url");if(!a)return;let s;const d=this.getAttribute("platforms");if(d)try{const e=JSON.parse(d);Array.isArray(e)&&(s=e)}catch{}const p=this.getAttribute("more-count"),u=p?parseInt(p,10):void 0;this.handle=m(this,{connect:{authorize:{url:a},appTheme:null!==(t=this.getAttribute("app-theme"))&&void 0!==t?t:void 0,onSuccess:()=>{var e;null===(e=this.onSuccess)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("success"))},onError:e=>{var t;null===(t=this.onError)||void 0===t||t.call(this,e),this.dispatchEvent(new CustomEvent("error",{detail:e}))},onClose:()=>{var e;null===(e=this.onClose)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("close"))}},label:null!==(n=this.getAttribute("label"))&&void 0!==n?n:void 0,variant:null!==(o=this.getAttribute("variant"))&&void 0!==o?o:void 0,theme:null!==(i=this.getAttribute("theme"))&&void 0!==i?i:void 0,platforms:s,moreCount:Number.isFinite(u)?u:void 0,description:null!==(r=this.getAttribute("description"))&&void 0!==r?r:void 0,accentColor:null!==(l=this.getAttribute("accent-color"))&&void 0!==l?l:void 0,connectedLabel:null!==(c=this.getAttribute("connected-label"))&&void 0!==c?c:void 0})}}t(e,"observedAttributes",["authorize-url","app-theme","label","variant","theme","platforms","more-count","description","accent-color","connected-label"]),customElements.define("one-connect-button",e)}}();const f=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},moreCount:{type:Number,default:void 0},description:{type:String,default:void 0},accentColor:{type:String,default:void 0},connectedLabel:{type:String,default:void 0}},emits:["success","error","close"],setup(t,{emit:n}){const o=e.ref(null);let i=null;const r=()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null,o.value&&(i=m(o.value,function(e,t){const n=null!=t?t:e;return{connect:{authorize:{url:e.authorizeUrl},appTheme:e.appTheme,onSuccess:()=>{var e;return null===(e=n.onSuccess)||void 0===e?void 0:e.call(n)},onError:e=>{var t;return null===(t=n.onError)||void 0===t?void 0:t.call(n,e)},onClose:()=>{var e;return null===(e=n.onClose)||void 0===e?void 0:e.call(n)}},label:e.label,variant:e.variant,theme:e.theme,platforms:e.platforms,moreCount:e.moreCount,description:e.description,accentColor:e.accentColor,connectedLabel:e.connectedLabel}}({...t},{onSuccess:()=>n("success"),onError:e=>n("error",e),onClose:()=>n("close")})))};return e.onMounted(r),e.watch(()=>{var e;return[t.authorizeUrl,t.appTheme,t.label,t.variant,t.theme,JSON.stringify(null!==(e=t.platforms)&&void 0!==e?e:[]),t.moreCount,t.description,t.accentColor,t.connectedLabel]},r),e.onBeforeUnmount(()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null}),()=>e.h("div",{ref:o})}});exports.ConnectButton=f;
+"use strict";var e=require("vue"),t=require("@withone/connect");const o=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},moreCount:{type:Number,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(o,{emit:n}){const r=e.ref(null);let u=null;const i=()=>{var e;null===(e=u)||void 0===e||e.destroy(),u=null,r.value&&(u=t.mountConnectButton(r.value,t.optionsFromProps({...o},{onSuccess:()=>n("success"),onError:e=>n("error",e)})))};return e.onMounted(i),e.watch(()=>t.propsIdentity({...o}),i),e.onBeforeUnmount(()=>{var e;null===(e=u)||void 0===e||e.destroy(),u=null}),()=>e.h("div",{ref:r})}});exports.ConnectButton=o;

package/dist/vue.d.ts

@@ -1,12 +1,12 @@
 import type { PropType } from "vue";
-import type { ConnectButtonPlatform } from "./types";
+import { type ConnectButtonPlatformInput, type ConnectButtonVariant, type OneConnectTheme } from "@withone/connect";
 export declare const ConnectButton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     authorizeUrl: {
         type: StringConstructor;
         required: true;
     };
     appTheme: {
-        type: PropType<"light" | "dark">;
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
     label: {
@@ -14,15 +14,15 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         default: undefined;
     };
     variant: {
-        type: PropType<"default" | "accent" | "block">;
+        type: PropType<ConnectButtonVariant>;
         default: undefined;
     };
     theme: {
-        type: PropType<"light" | "dark">;
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
     platforms: {
-        type: PropType<ConnectButtonPlatform[]>;
+        type: PropType<ConnectButtonPlatformInput[]>;
         default: undefined;
     };
     moreCount: {
@@ -43,13 +43,16 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
     };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
-}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("success" | "error" | "close")[], "success" | "error" | "close", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    success: () => true;
+    error: (message: string) => boolean;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     authorizeUrl: {
         type: StringConstructor;
         required: true;
     };
     appTheme: {
-        type: PropType<"light" | "dark">;
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
     label: {
@@ -57,15 +60,15 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         default: undefined;
     };
     variant: {
-        type: PropType<"default" | "accent" | "block">;
+        type: PropType<ConnectButtonVariant>;
         default: undefined;
     };
     theme: {
-        type: PropType<"light" | "dark">;
+        type: PropType<OneConnectTheme>;
         default: undefined;
     };
     platforms: {
-        type: PropType<ConnectButtonPlatform[]>;
+        type: PropType<ConnectButtonPlatformInput[]>;
         default: undefined;
     };
     moreCount: {
@@ -85,17 +88,16 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         default: undefined;
     };
 }>> & Readonly<{
-    onSuccess?: ((...args: any[]) => any) | undefined;
-    onError?: ((...args: any[]) => any) | undefined;
-    onClose?: ((...args: any[]) => any) | undefined;
+    onSuccess?: (() => any) | undefined;
+    onError?: ((message: string) => any) | undefined;
 }>, {
-    appTheme: "light" | "dark";
     label: string;
-    variant: "default" | "accent" | "block";
-    theme: "light" | "dark";
-    platforms: ConnectButtonPlatform[];
-    moreCount: number;
+    variant: ConnectButtonVariant;
+    theme: OneConnectTheme;
+    platforms: ConnectButtonPlatformInput[];
     description: string;
+    appTheme: OneConnectTheme;
+    moreCount: number;
     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 n,watch as o,onBeforeUnmount as i,h as r}from"vue";function l(e,t,n){return(t=function(e){var t=function(e,t){if("object"!=typeof e||!e)return e;var n=e[Symbol.toPrimitive];if(void 0!==n){var o=n.call(e,t);if("object"!=typeof o)return o;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===t?String:Number)(e)}(e,"string");return"symbol"==typeof t?t:t+""}(t))in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}const c="one_connect",a="one_connect_message";let s=!1;const d=e=>{let t=!1;if("undefined"!=typeof window&&!s){const o=new URLSearchParams(window.location.search),i=o.get(c);if("success"===i||"error"===i){var n;s=!0;const r=null!==(n=o.get(a))&&void 0!==n?n:void 0,l=()=>{const e=new URLSearchParams(window.location.search);(e.has(c)||e.has(a))&&(e.delete(c),e.delete(a),window.history.replaceState(null,"",window.location.pathname+(e.toString()?`?${e.toString()}`:"")+window.location.hash))};l();for(const e of[50,500,2e3])window.setTimeout(l,e);window.setTimeout(()=>{if(!t){t=!0;try{var n,o;"success"===i?null===(n=e.onSuccess)||void 0===n||n.call(e):null===(o=e.onError)||void 0===o||o.call(e,null!=r?r:"The connection was not completed.")}catch{}}},0)}}return{open:()=>{"undefined"!=typeof window&&window.location.assign((()=>{try{const t=new URL(e.authorize.url,"undefined"==typeof window?void 0:window.location.origin);return e.appTheme&&(t.hash=`one_theme=${e.appTheme}`),t.toString()}catch{return e.authorize.url}})())},close:e=>{}}},p="one-connect-button-styles",u="cubic-bezier(.2,.9,.25,1)",h={btnBg:"#0A0C0B",btnFg:"#ffffff",surface:"#ffffff",fg:"#0A0C0B",muted:"#6B7280",line:"#D1D5DB",shadow:"0 1px 2px rgba(10,12,11,.08), 0 4px 14px rgba(10,12,11,.06)"},m={btnBg:"#F2F5F3",btnFg:"#0A0C0B",surface:"#101312",fg:"#F2F5F3",muted:"#8A938E",line:"#2A302D",shadow:"0 1px 2px rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.35)"},f="#CCFF00",b="#3FE3A5",v="#0A0C0B";function w(e){const t=e.trim().toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"");return t?`https://assets.withone.ai/connectors/${t}.svg`:""}const g=(e,t)=>{var n,o;!function(){if("undefined"==typeof document||document.getElementById(p))return;const e=document.createElement("style");e.id=p,e.textContent=[`.owcb{font:500 14.5px/1.2 inherit;font-family:inherit;letter-spacing:-.01em;cursor:pointer;border:0;display:inline-flex;align-items:center;gap:12px;padding:12px 16px 12px 14px;border-radius:12px;transition:transform .2s ${u},box-shadow .2s ${u},opacity .2s ${u}}`,".owcb:hover{transform:translateY(-1px)}",".owcb:active{transform:translateY(0)}",`.owcb:focus-visible{outline:2px solid ${b};outline-offset:3px}`,".owcb[disabled]{cursor:default;opacity:.75;transform:none}",".owcb-stack{display:inline-flex;align-items:center;flex-shrink:0}",`.owcb-chip{width:22px;height:22px;border-radius:6px;display:grid;place-items:center;overflow:hidden;margin-left:-7px;transition:margin-left .28s ${u};position:relative}`,".owcb-chip:first-child{margin-left:0}",".owcb-chip img{width:14px;height:14px;display:block;object-fit:contain}",".owcb-chip.owcb-more{font-family:ui-monospace,monospace;font-size:9px;font-weight:500;letter-spacing:-.02em}",".owcb:hover .owcb-chip{margin-left:-2px}",".owcb:hover .owcb-chip:first-child{margin-left:0}",".owcb-label{white-space:nowrap}",`.owcb-arrow{opacity:.5;transition:transform .2s ${u},opacity .2s ${u}}`,".owcb:hover .owcb-arrow{transform:translateX(2px);opacity:.8}",".owcb-spinner{width:16px;height:16px;border-radius:50%;border:2px solid currentColor;border-top-color:transparent;opacity:.7;animation:owcb-spin .7s linear infinite}","@keyframes owcb-spin{to{transform:rotate(360deg)}}",".owcb.owcb-block{display:flex;flex-direction:column;align-items:stretch;width:100%;max-width:420px;text-align:left;padding:16px;border-radius:14px;gap:0}",".owcb-block-top{display:flex;align-items:center;justify-content:space-between;gap:12px}",".owcb-block-title{font-size:15px;font-weight:600;letter-spacing:-.01em}",".owcb-block-sub{font-size:13px;line-height:1.5;margin-top:6px;font-weight:400}",".owcb-block-foot{margin-top:14px;padding-top:12px;display:flex;align-items:center;gap:6px;font-size:11.5px;font-weight:400}","@media (prefers-reduced-motion:reduce){.owcb,.owcb-chip,.owcb-arrow{transition:none}.owcb-spinner{animation-duration:1.4s}}"].join("\n"),document.head.appendChild(e)}();const i="dark"===t.theme?m:h,r=null!==(n=t.variant)&&void 0!==n?n:"default",l=null!==(o=t.label)&&void 0!==o?o:"Connect your apps";let c="idle",a=!1;const s=d({...t.connect,onSuccess:()=>{var e,n;y("connected"),null===(e=(n=t.connect).onSuccess)||void 0===e||e.call(n)},onError:e=>{var n,o;y("idle"),null===(n=(o=t.connect).onError)||void 0===n||n.call(o,e)},onClose:()=>{var e,n;y("idle"),null===(e=(n=t.connect).onClose)||void 0===e||e.call(n)}}),g=document.createElement("button");g.type="button",g.className="block"===r?"owcb owcb-block":"owcb",g.addEventListener("click",()=>{"idle"!==c&&"connected"!==c||(y("connecting"),s.open())});const x=()=>{var e,n,o;const a="accent"===r,s="block"===r,d=s?i.surface:a?null!==(e=t.accentColor)&&void 0!==e?e:f:i.btnBg,p=s?i.fg:a?v:i.btnFg,u=s?i.surface:d,h=v;g.style.background="connected"!==c||s?d:b,g.style.color="connected"!==c||s?p:v,g.style.boxShadow=s?`inset 0 0 0 1px ${i.line}`:"connected"===c?"none":a?`0 1px 2px rgba(10,12,11,.1), 0 6px 20px ${null!==(n=t.accentColor)&&void 0!==n?n:f}38`:i.shadow,g.disabled="connecting"===c,g.innerHTML="";const m=function(e,t,n){var o,i;const r=null!==(o=e.platforms)&&void 0!==o?o:[];if(0===r.length&&!e.moreCount)return null;const l=document.createElement("span");l.className="owcb-stack",l.setAttribute("aria-hidden","true");for(const e of r.slice(0,3)){var c;const n=document.createElement("span");n.className="owcb-chip",n.style.background="#ffffff",n.style.boxShadow=`0 0 0 1.5px ${t}`;const o=()=>{n.textContent=e.name.charAt(0).toUpperCase(),n.style.font="600 10px ui-monospace,monospace",n.style.color=v},i=null!==(c=e.imageUrl)&&void 0!==c?c:w(e.name);if(i){const e=document.createElement("img");e.alt="",e.src=i,e.addEventListener("error",()=>{e.remove(),o()}),n.appendChild(e)}else o();l.appendChild(n)}const a=(null!==(i=e.moreCount)&&void 0!==i?i:0)+Math.max(0,r.length-3);if(a>0){const e=document.createElement("span");e.className="owcb-chip owcb-more",e.style.background="#ffffff",e.style.boxShadow=`0 0 0 1.5px ${t}`,e.style.color=n,e.textContent=`+${a}`,l.appendChild(e)}return l}(t,u,h);if(s){var x;const e=document.createElement("span");e.className="owcb-block-top";const n=document.createElement("span");if(n.className="owcb-block-title",n.textContent="connecting"===c?"Connecting…":"connected"===c?null!==(x=t.connectedLabel)&&void 0!==x?x:"Connected":l,e.appendChild(n),"connecting"===c){const t=document.createElement("span");t.className="owcb-spinner",e.appendChild(t)}else m&&e.appendChild(m);if(g.appendChild(e),t.description&&"idle"===c){const e=document.createElement("span");e.className="owcb-block-sub",e.style.color=i.muted,e.textContent=t.description,g.appendChild(e)}const o=document.createElement("span");return o.className="owcb-block-foot",o.style.color=i.muted,o.style.borderTop=`1px solid ${i.line}`,o.innerHTML=`<span style="font-size:11px;color:${i.muted}">Secured by</span><span style="display:inline-flex;color:${i.fg}"><svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2.4" style="flex-shrink:0"><circle cx="12" cy="12" r="8.5"/></svg></span><span style="font-size:12px;font-weight:600;letter-spacing:-0.02em;color:${i.fg}">one</span>`,void g.appendChild(o)}if("connecting"===c){const e=document.createElement("span");e.className="owcb-spinner",g.appendChild(e)}else if("connected"===c){const e=document.createElement("span");e.innerHTML='<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:16px;height:16px"><path d="M3 8.5l3.5 3.5L13 5"/></svg>',e.style.display="inline-flex",g.appendChild(e)}else m&&g.appendChild(m);const y=document.createElement("span");if(y.className="owcb-label",y.textContent="connecting"===c?"Connecting…":"connected"===c?null!==(o=t.connectedLabel)&&void 0!==o?o:"Connected":l,g.appendChild(y),"idle"===c){const e=document.createElement("span");e.innerHTML='<svg class="owcb-arrow" width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3l5 5-5 5"/></svg>',e.style.display="inline-flex",g.appendChild(e)}},y=e=>{a||(c=e,x())};return x(),e.appendChild(g),{setState:y,destroy:()=>{a=!0,s.close({keepResult:!0}),g.remove()}}};!function(){if("undefined"!=typeof window&&"undefined"!=typeof customElements&&!customElements.get("one-connect-button")){class e extends HTMLElement{constructor(...e){super(...e),l(this,"onSuccess",null),l(this,"onError",null),l(this,"onClose",null),l(this,"handle",null)}connectedCallback(){this.mount()}disconnectedCallback(){var e;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null}attributeChangedCallback(){this.isConnected&&this.handle&&this.mount()}mount(){var e,t,n,o,i,r,l,c;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null;const a=this.getAttribute("authorize-url");if(!a)return;let s;const d=this.getAttribute("platforms");if(d)try{const e=JSON.parse(d);Array.isArray(e)&&(s=e)}catch{}const p=this.getAttribute("more-count"),u=p?parseInt(p,10):void 0;this.handle=g(this,{connect:{authorize:{url:a},appTheme:null!==(t=this.getAttribute("app-theme"))&&void 0!==t?t:void 0,onSuccess:()=>{var e;null===(e=this.onSuccess)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("success"))},onError:e=>{var t;null===(t=this.onError)||void 0===t||t.call(this,e),this.dispatchEvent(new CustomEvent("error",{detail:e}))},onClose:()=>{var e;null===(e=this.onClose)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("close"))}},label:null!==(n=this.getAttribute("label"))&&void 0!==n?n:void 0,variant:null!==(o=this.getAttribute("variant"))&&void 0!==o?o:void 0,theme:null!==(i=this.getAttribute("theme"))&&void 0!==i?i:void 0,platforms:s,moreCount:Number.isFinite(u)?u:void 0,description:null!==(r=this.getAttribute("description"))&&void 0!==r?r:void 0,accentColor:null!==(l=this.getAttribute("accent-color"))&&void 0!==l?l:void 0,connectedLabel:null!==(c=this.getAttribute("connected-label"))&&void 0!==c?c:void 0})}}l(e,"observedAttributes",["authorize-url","app-theme","label","variant","theme","platforms","more-count","description","accent-color","connected-label"]),customElements.define("one-connect-button",e)}}();const x=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},moreCount:{type:Number,default:void 0},description:{type:String,default:void 0},accentColor:{type:String,default:void 0},connectedLabel:{type:String,default:void 0}},emits:["success","error","close"],setup(e,{emit:l}){const c=t(null);let a=null;const s=()=>{var t;null===(t=a)||void 0===t||t.destroy(),a=null,c.value&&(a=g(c.value,function(e,t){const n=null!=t?t:e;return{connect:{authorize:{url:e.authorizeUrl},appTheme:e.appTheme,onSuccess:()=>{var e;return null===(e=n.onSuccess)||void 0===e?void 0:e.call(n)},onError:e=>{var t;return null===(t=n.onError)||void 0===t?void 0:t.call(n,e)},onClose:()=>{var e;return null===(e=n.onClose)||void 0===e?void 0:e.call(n)}},label:e.label,variant:e.variant,theme:e.theme,platforms:e.platforms,moreCount:e.moreCount,description:e.description,accentColor:e.accentColor,connectedLabel:e.connectedLabel}}({...e},{onSuccess:()=>l("success"),onError:e=>l("error",e),onClose:()=>l("close")})))};return n(s),o(()=>{var t;return[e.authorizeUrl,e.appTheme,e.label,e.variant,e.theme,JSON.stringify(null!==(t=e.platforms)&&void 0!==t?t:[]),e.moreCount,e.description,e.accentColor,e.connectedLabel]},s),i(()=>{var e;null===(e=a)||void 0===e||e.destroy(),a=null}),()=>r("div",{ref:c})}});export{x as ConnectButton};
+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},moreCount:{type:Number,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 v=()=>{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(v),o(()=>l({...e}),v),n(()=>{var e;null===(e=s)||void 0===e||e.destroy(),s=null}),()=>i("div",{ref:p})}});export{a as ConnectButton};

package/dist/wrapper-options.d.ts

@@ -1,24 +1,29 @@
-import type { ConnectButtonOptions, ConnectButtonPlatform } from "./types";
-/** The flat prop shape every framework wrapper exposes (React props,
- *  Vue props, Svelte action options) — one place to translate it into
- *  the core mountConnectButton options. */
-export interface ConnectButtonWrapperProps {
+import type { ConnectButtonOptions, ConnectButtonPlatformInput, ConnectButtonVariant, OneConnectTheme } from "./types";
+/** The flat prop shape every framework wrapper exposes: React props,
+ *  Vue props, the Svelte action's options. One place turns it into the
+ *  core mountConnectButton options. */
+export interface ConnectButtonProps {
+    /** The app's own backend authorize route; relative is fine. */
     authorizeUrl: string;
-    appTheme?: "light" | "dark";
+    /** Theme of One's hosted page. */
+    appTheme?: OneConnectTheme;
     onSuccess?: () => void;
-    onError?: (error: string) => void;
-    onClose?: () => void;
+    onError?: (message: string) => void;
     label?: string;
-    variant?: "default" | "accent" | "block";
-    theme?: "light" | "dark";
-    platforms?: ConnectButtonPlatform[];
+    variant?: ConnectButtonVariant;
+    /** Matches the host page. */
+    theme?: OneConnectTheme;
+    /** Connector slugs, or objects to override name or logo. */
+    platforms?: ConnectButtonPlatformInput[];
     moreCount?: number;
     description?: string;
     accentColor?: string;
     connectedLabel?: string;
 }
-export declare function optionsFromWrapperProps(props: ConnectButtonWrapperProps, callbacks?: {
+export interface ConnectButtonCallbacks {
     onSuccess?: () => void;
-    onError?: (error: string) => void;
-    onClose?: () => void;
-}): ConnectButtonOptions;
+    onError?: (message: string) => void;
+}
+export declare function optionsFromProps(props: ConnectButtonProps, callbacks?: ConnectButtonCallbacks): ConnectButtonOptions;
+/** The inputs whose change should remount the button. */
+export declare function propsIdentity(props: ConnectButtonProps): string;

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@withone/connect",
-  "version": "0.8.3",
-  "description": "Frontend bindings for One Connect, a drop-in OAuth flow that lets your users grant your application scoped, revocable access to their own connected tools. The user owns the connections; you hold a token scoped to exactly what they granted.",
+  "version": "0.9.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",
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
-  "main": "dist/index.umd.js",
+  "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
   "devDependencies": {
@@ -24,17 +25,15 @@
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@tsconfig/recommended": "^1.0.3",
+    "@types/node": "^22.15.0",
     "@types/react": "^19.2.18",
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^7.0.0",
-    "eslint": "^8.57.0",
     "prettier": "^3.2.5",
     "react": "^19.2.8",
     "rollup": "^4.12.0",
-    "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-typescript2": "^0.36.0",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3",
+    "vitest": "^3.2.4",
     "vue": "^3.5.42"
   },
   "author": "@withoneai",
@@ -42,11 +41,15 @@
     "access": "public"
   },
   "scripts": {
-    "prepublishOnly": "npm run build",
-    "build": "rollup -c && npm run verify",
-    "verify": "node -e \"const fs=require('fs'),p=require('./package.json');const miss=[p.main,p.module,p.types].filter(f=>!fs.existsSync(f));if(miss.length){console.error('Build output missing: '+miss.join(', '));process.exit(1)}console.log('Build verified: '+[p.main,p.module,p.types].join(', '))\"",
-    "lint": "eslint src --ext .ts,.tsx",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c && npm run declarations && npm run verify",
+    "verify": "node scripts/verify-build.js",
+    "typecheck": "tsc --noEmit -p tsconfig.tests.json",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test && npm run build",
+    "prepublishOnly": "npm run check",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "declarations": "tsc -p tsconfig.build.json"
   },
   "repository": {
     "type": "git",
@@ -67,7 +70,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.esm.js",
-      "require": "./dist/index.umd.js"
+      "require": "./dist/index.cjs.js"
     },
     "./react": {
       "types": "./dist/react.d.ts",
@@ -83,7 +86,23 @@
       "types": "./dist/svelte.d.ts",
       "import": "./dist/svelte.esm.js",
       "require": "./dist/svelte.cjs.js"
-    }
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.esm.js",
+      "require": "./dist/server/index.cjs.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.esm.js",
+      "require": "./dist/next.cjs.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.esm.js",
+      "require": "./dist/node.cjs.js"
+    },
+    "./package.json": "./package.json"
   },
   "peerDependencies": {
     "react": ">=17",
@@ -96,5 +115,8 @@
     "vue": {
       "optional": true
     }
+  },
+  "engines": {
+    "node": ">=18"
   }
-}
+}

package/skills/one-connect/SKILL.md

@@ -0,0 +1,194 @@
+---
+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, 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 One-connected tools. The package does
+the OAuth work; you wire three things: a button, the two routes, and the
+calls you make with the grant.
+
+```
+Browser                    Your backend                              One
+<ConnectButton>  ------>   GET /api/one/authorize   ---302--->  One's hosted page (connect.withone.ai)
+                                                                sign-in code, pick tools, set access
+                           GET /api/one/callback    <--302----  ?code=...&state=...
+                             exchanges the code, stores the tokens
+                             302 -> /?one_connect=success
+                 <------   SDK reads the param and fires onSuccess
+Later:                     oneConnect.runAction(userId, ...) -> /v1/passthrough, grant enforced by One
+```
+
+Secrets and tokens never reach the browser.
+
+## 1 - Collect from the human first
+
+The human creates the app in the One dashboard: Developers -> Connect ->
+New app. Confidential client. The secret is shown once.
+
+| Value | Notes |
+|---|---|
+| `ONE_CLIENT_ID` | 40 hex characters |
+| `ONE_CLIENT_SECRET` | starts with `one_secret_` |
+| Registered redirect URI | Must be the exact URL of the callback route (scheme, host, path, no trailing slash). One compares the string as-is and answers `invalid redirect_uri` on any difference. Use `https` for anything public; `http://localhost:3000/api/one/callback` is fine locally. |
+| `ONE_PERMISSION_SET` (optional) | The id of the app's ask: the connectors and levels the consent page opens on. Users can narrow it, never widen it. Without one, the page lists everything the user has connected. |
+| Environment | Production is the default. For the development dashboard set `ONE_API_URL=https://development-api.withone.ai`. |
+
+Two facts to tell the human:
+
+- The app can show its users one line saying why it asks. It is set on the
+  app in the dashboard, not sent by this package.
+- Users can change or revoke the grant from their One dashboard at any time.
+  Treat a `401` from One as "ask the user to reconnect", never as a bug.
+
+## 2 - Environment (server only)
+
+```bash
+ONE_CLIENT_ID=...
+ONE_CLIENT_SECRET=one_secret_...
+ONE_REDIRECT_URI=https://yourapp.com/api/one/callback   # exactly the registered value
+ONE_PERMISSION_SET=...                                     # optional
+ONE_API_URL=https://api.withone.ai                         # optional; development-api.withone.ai for development
+```
+
+## 3 - Install and create the client
+
+```bash
+npm install @withone/connect
+```
+
+```ts
+// lib/one.ts  (server only)
+import { createOneConnect } from "@withone/connect/server";
+
+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) => /* write to this app's database, encrypted, keyed by its user */,
+    loadTokens: (userId) => /* read; null when the user never connected */,
+    clearTokens: (userId) => /* delete */,
+  },
+});
+```
+
+`tokens` is `{ accessToken, refreshToken, expiresAt }`. Use the app's own user
+id as the key. Implement the store on whatever the app already uses; do not
+add a database for it.
+
+## 4 - The two routes
+
+Next.js App Router (also Remix, SvelteKit, Hono, Bun: anything with the web `Request`):
+
+```ts
+// app/api/one/[action]/route.ts
+import { createOneConnectRoutes } from "@withone/connect/next";
+import { oneConnect } from "@/lib/one";
+
+export const { GET } = createOneConnectRoutes(oneConnect, {
+  identifyUser: async (request) => /* this app's signed-in user id, or null */,
+  loginHintFor: async (request) => /* their email, to pre-fill One's sign-in; or null */,
+  signInUrl: "/login",   // where to send a visitor who is not signed in
+});
+```
+
+That file serves `/api/one/authorize` and `/api/one/callback`.
+
+Express, Fastify, Koa, plain Node:
+
+```ts
+import { createOneConnectHandlers } from "@withone/connect/node";
+import { oneConnect } from "./one";
+
+const { authorize, callback } = createOneConnectHandlers(oneConnect, {
+  identifyUser: (request) => /* user id or null */,
+});
+app.get("/api/one/authorize", authorize);
+app.get("/api/one/callback", callback);
+```
+
+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
+`createOneConnect` to land somewhere else.
+
+## 5 - The button
+
+```tsx
+import { ConnectButton } from "@withone/connect/react";
+
+<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 */ }}
+/>
+```
+
+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.
+
+## 6 - Calling One with the grant
+
+Everything runs on the server through the client. Tokens refresh themselves.
+
+```ts
+const connections = await oneConnect.listConnections(userId);
+// [{ key, platform, name, title, image, access }]
+// access.policy: "full" | "methods" (+ methods: ["GET", ...]) | "actions" (+ actions: [{ actionId, title, method }])
+
+const actions = await oneConnect.listActions(userId, "gmail");
+// [{ _id, title, method, path }]  - what exists, not what is permitted
+
+const reply = await oneConnect.runAction(userId, {
+  connectionKey: connection.key,
+  actionId: action._id,
+  method: action.method,
+  path: action.path,
+  body: payload,
+});
+// { status, ok, blockedByGrant, data }
+```
+
+`blockedByGrant` true means One refused the call because it is outside the
+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).
+
+## 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.
+- 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.
+
+## 8 - Done when all of these pass
+
+1. Button -> One's hosted page -> sign-in code from a real inbox -> choose
+   tools and levels -> "You're all set" -> back in the app with `onSuccess`
+   fired. Repeat once in a private window.
+2. `listConnections` returns only the granted connections, each with `access`.
+3. `runAction` on an action inside the grant reaches the provider; one outside
+   it returns `blockedByGrant: true`.
+4. Revoking the app from the user's One dashboard makes the next call throw
+   `refresh_failed` or return `401`, and the app shows its reconnect prompt.