@withone/connect 0.1.0

package/README.md

@@ -0,0 +1,361 @@
+<img src="https://assets.withone.ai/banners/connect.png" alt="One Connect — Let your users grant your app scoped, revocable access to their own tools." style="border-radius: 5px;">
+
+<h3 align="center">One Connect</h3>
+
+<p align="center">
+  <a href="https://withone.ai"><strong>Website</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://withone.ai/docs/connect"><strong>Docs</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://app.withone.ai"><strong>Dashboard</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://withone.ai/changelog"><strong>Changelog</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://x.com/withoneai"><strong>X</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://linkedin.com/company/withoneai"><strong>LinkedIn</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/@withone/connect"><img src="https://img.shields.io/npm/v/%40withone%2Fconnect" alt="npm version"></a>
+</p>
+
+One Connect lets your users grant your application **scoped, revocable access to their own One-connected tools** — Gmail, Slack, Notion, Stripe and 500+ more — through the standard OAuth 2.1 authorization-code flow with PKCE.
+
+Your user owns their connections inside One. You never see their Gmail password — you hold a One access token scoped to **exactly what they granted**, and they can narrow or revoke it at any time. One enforces the grant on every call.
+
+Fully compatible with popular frameworks such as React, Next.js, Vue, Svelte, and more.
+
+> **Connect vs. Auth** — [`@withone/auth`](https://github.com/withoneai/auth) puts connections **in your One project** (you own them). Connect puts connections **in your user's own One account** and hands you a scoped grant.
+
+## Install
+
+With npm:
+
+```bash
+npm i @withone/connect
+```
+
+With yarn:
+
+```bash
+yarn add @withone/connect
+```
+
+## How it works
+
+Everything sensitive — `state`, the PKCE verifier, your client secret, the tokens — lives on **your server**. The SDK is a thin modal opener: it never touches a token.
+
+You build exactly **two backend routes and one button**.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant YourApp as Your Application
+    participant YourBackend as Your Backend
+    participant One as One Connect
+
+    User->>YourApp: Clicks "Connect your tools"
+    YourApp->>YourBackend: Open modal → GET /api/one/authorize
+    YourBackend->>YourBackend: Mint state + PKCE, set httpOnly cookie
+    YourBackend->>One: 302 → /oauth/authorize
+    User->>One: Sign in, connect tools, narrow & grant access
+    One->>YourBackend: 302 → /api/one/callback?code&state
+    YourBackend->>YourBackend: Verify state
+    YourBackend->>One: POST /oauth/token (code + verifier + secret)
+    One->>YourBackend: Access token + refresh token
+    YourBackend->>YourApp: 302 → /?one_connect=success
+    YourApp->>User: SDK closes the modal, onSuccess() fires
+```
+
+The SDK watches the modal frame for `?one_connect=` on your own origin — so **there is no completion page to build**.
+
+## 1 · Create your OAuth app
+
+Dashboard → **Settings → OAuth Apps → New OAuth app**.
+
+- You get a **Client ID** (public) and a **Client Secret** (shown once — server-only, never in a browser).
+- Register your **redirect URI** (e.g. `https://yourapp.com/api/one/callback`).
+- Pick the **access-token lifetime**: 7 days, 30 days, 90 days or 1 year.
+- Optionally create a **permission set** — the connectors your app needs and the access level for each (full / read & write / read only / specific actions). Your user sees it pre-filled at consent and can only *narrow* it. Without one, your app asks for access to the user's connections generally, which they can also narrow.
+
+### Environment Variables
+
+```env
+ONE_CLIENT_ID=...
+ONE_CLIENT_SECRET=one_secret_...
+ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
+ONE_PERMISSION_SET=79659c66-...
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `ONE_CLIENT_ID` | Yes | Public client ID from your OAuth app |
+| `ONE_CLIENT_SECRET` | Yes | Server-only secret. Never ship to a browser. |
+| `ONE_REDIRECT_URI` | Yes | Must exactly match the URI registered in the dashboard |
+| `ONE_PERMISSION_SET` | No | Pre-fills the consent screen with the access your app needs |
+
+## 2 · Using the Connect component
+
+Replace the `authorize URL` with your backend authorize endpoint.
+
+> ⚠️ **Must be a full URL** — relative paths like `/api/one/authorize` won't work because the Connect card runs in an iframe. Use the complete URL (e.g., `https://your-domain.com/api/one/authorize`).
+
+```tsx
+"use client";
+
+import { useOneConnect } from "@withone/connect";
+
+export function ConnectWithOne() {
+  const { open } = useOneConnect({
+    authorize: {
+      url: "https://your-domain.com/api/one/authorize",
+    },
+    appTheme: "light",
+    onSuccess: () => {
+      // Your backend already stored the tokens by the time this fires.
+      console.log("Access granted");
+    },
+    onError: (error) => {
+      console.error("Connect failed:", error);
+    },
+    onClose: () => {
+      console.log("Connect modal closed");
+    },
+  });
+
+  return <button onClick={open}>Connect your tools</button>;
+}
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|---|---|---|
+| `authorize.url` | `string` | Full URL of your backend authorize endpoint. Must be absolute. |
+| `appTheme` | `"dark" \| "light"` | Theme for the Connect card. The SDK carries it on the URL fragment — nothing for your backend to forward. |
+| `onSuccess` | `() => void` | The grant completed and your server stored the tokens |
+| `onError` | `(error: string) => void` | The flow failed, with a human-readable message |
+| `onClose` | `() => void` | The user closed the card without a result |
+
+### Returned handle
+
+| Method | Description |
+|---|---|
+| `open()` | Opens the Connect modal over the current page |
+| `close()` | Tears down the modal frame and its listeners |
+
+## 3 · Backend — the authorize route
+
+Generates `state` (CSRF proof) and PKCE (proof that whoever redeems the code is this server), stashes both in an httpOnly cookie, and 302s the browser to One.
+
+```typescript
+// app/api/one/authorize/route.ts (Next.js App Router)
+import { createHash, randomBytes } from "crypto";
+import { NextRequest, NextResponse } from "next/server";
+
+const ONE_AUTHORIZE_URL = "https://api.withone.ai/oauth/authorize";
+
+export async function GET(req: NextRequest) {
+  const state = randomBytes(16).toString("hex");
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+
+  const url = new URL(ONE_AUTHORIZE_URL);
+  url.searchParams.set("client_id", process.env.ONE_CLIENT_ID!);
+  url.searchParams.set("redirect_uri", process.env.ONE_REDIRECT_URI!);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", "user:connections:read user:connections:write");
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+
+  if (process.env.ONE_PERMISSION_SET) {
+    url.searchParams.set("permission_set", process.env.ONE_PERMISSION_SET);
+  }
+
+  // Optional: your user's email. One pre-fills (never locks) their sign-in.
+  const userEmail = await getCurrentUserEmail(req); // ← your code
+  if (userEmail) url.searchParams.set("login_hint", userEmail);
+
+  const res = NextResponse.redirect(url.toString(), 302);
+  res.cookies.set("one_tx", JSON.stringify({ state, verifier }), {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    maxAge: 600, // matches One's 10-minute authorization-code lifetime
+    path: "/api/one",
+  });
+  return res;
+}
+```
+
+## 4 · Backend — the callback route
+
+One redirects back with a **single-use code**, worthless without your secret and the PKCE verifier. Exchange it server-side, store the tokens, then redirect anywhere on your site with `?one_connect=success` appended — the SDK watches the frame for that parameter and closes the modal.
+
+```typescript
+// app/api/one/callback/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+const ONE_TOKEN_URL = "https://api.withone.ai/oauth/token";
+
+export async function GET(req: NextRequest) {
+  const code = req.nextUrl.searchParams.get("code");
+  const state = req.nextUrl.searchParams.get("state");
+  const tx = req.cookies.get("one_tx")?.value;
+
+  const parsed = tx ? JSON.parse(tx) : null;
+  if (!code || !state || !parsed || parsed.state !== state) {
+    return NextResponse.redirect(
+      new URL(
+        "/?one_connect=error&one_connect_message=" +
+          encodeURIComponent("The sign-in attempt expired or was tampered with."),
+        req.url,
+      ),
+      302,
+    );
+  }
+
+  const basic = Buffer.from(
+    `${process.env.ONE_CLIENT_ID}:${process.env.ONE_CLIENT_SECRET}`,
+  ).toString("base64");
+
+  const tokenRes = await fetch(ONE_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${basic}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: process.env.ONE_REDIRECT_URI!,
+      code_verifier: parsed.verifier,
+    }),
+  });
+
+  const res = NextResponse.redirect(
+    new URL(
+      tokenRes.ok
+        ? "/?one_connect=success"
+        : "/?one_connect=error&one_connect_message=" +
+          encodeURIComponent("Token exchange failed."),
+      req.url,
+    ),
+    302,
+  );
+  res.cookies.delete("one_tx");
+
+  if (tokenRes.ok) {
+    // { access_token, refresh_token, token_type: "bearer", expires_in, scope }
+    const tokens = await tokenRes.json();
+    await saveOneTokens(req, {                    // ← your code
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresAt: Date.now() + tokens.expires_in * 1000,
+    });
+  }
+  return res;
+}
+```
+
+**Token response (200):**
+
+```json
+{
+  "access_token": "one_at_...",
+  "refresh_token": "one_rt_...",
+  "token_type": "bearer",
+  "expires_in": 2592000,
+  "scope": "user:connections:read user:connections:write"
+}
+```
+
+## 5 · Backend — refreshing the token
+
+Access tokens last as long as you chose when creating the app (7 days to 1 year). Refresh tokens last **30 days** and are **rotated on every use** — always store BOTH new tokens. Reusing an old refresh token revokes the entire token family (theft protection).
+
+```typescript
+const ONE_TOKEN_URL = "https://api.withone.ai/oauth/token";
+
+export async function getOneAccessToken(userId: string): Promise<string> {
+  const t = await loadOneTokens(userId);           // ← your code
+  if (Date.now() < t.expiresAt - 60_000) return t.accessToken;
+
+  // The refresh exchange is authenticated exactly like the code exchange —
+  // same Basic header. The public-client form (client_id in the body, no
+  // secret) is rejected with 401.
+  const basic = Buffer.from(
+    `${process.env.ONE_CLIENT_ID}:${process.env.ONE_CLIENT_SECRET}`,
+  ).toString("base64");
+
+  const res = await fetch(ONE_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${basic}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: t.refreshToken,
+    }),
+  });
+  if (!res.ok) throw new Error("One refresh failed — re-run the connect flow");
+
+  const tokens = await res.json();
+  await saveOneTokens(userId, {                    // BOTH tokens — rotation!
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt: Date.now() + tokens.expires_in * 1000,
+  });
+  return tokens.access_token;
+}
+```
+
+## 6 · Backend — using the grant
+
+The bearer token works on One's standard `/v1` API — the same routes every other credential uses.
+
+```typescript
+const token = await getOneAccessToken(userId);
+
+// Discover what the user granted. Ungranted connections are invisible,
+// not merely forbidden.
+const res = await fetch("https://api.withone.ai/v1/connections", {
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+Execute actions through `/v1/passthrough/*` with the same bearer. Every call is checked inside One against what the user granted — a call outside the grant returns `403`, and your code cannot override it. That is the point.
+
+## Custom completion pages
+
+The standard integration needs no completion page: your callback's final redirect carries `?one_connect=success` on any same-origin URL, and the SDK reads it off the frame directly.
+
+If you render your own completion page instead, signal the SDK explicitly:
+
+```tsx
+import { completeOneConnect } from "@withone/connect";
+
+// Returns false when there was nothing to do (not inside a frame) —
+// render fallback UI in that case.
+completeOneConnect({ status: "success" });
+```
+
+## What your users see
+
+In their own One dashboard, your app appears under **Authorized apps** with what they granted and when it was last used. They can revoke it at any time — handle `401`/`403` by prompting them to reconnect.
+
+In *your* dashboard, your OAuth app lists every user who granted access, and you can revoke individual users too.
+
+## Security notes
+
+- The client secret lives on your server only. Authenticate the token exchange with the `Authorization: Basic` header, as shown above.
+- The authorization code is single-use and expires in 10 minutes.
+- The SDK never handles tokens. It opens One's card in a modal iframe and watches for the `?one_connect=` result — there is nothing sensitive in the browser to leak.
+- The SDK only trusts messages originating from its own iframe, and only accepts results from your own origin.
+
+## License
+
+This project is licensed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for details.

package/dist/complete.d.ts

@@ -0,0 +1,12 @@
+import type { OneConnectResult } from "./types";
+/**
+ * OPTIONAL. The standard integration needs no completion page at all:
+ * the callback route's final redirect carries ?one_connect=success (or
+ * error) on any same-origin URL, and the SDK reads it off the frame's
+ * location directly. Use this helper only if you render a custom
+ * completion page and want to signal the SDK from it explicitly.
+ *
+ * Returns false when it had nothing to do (not inside a frame) — e.g.
+ * the user opened the page directly. Render fallback UI in that case.
+ */
+export declare function completeOneConnect(result?: OneConnectResult): boolean;

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+/** postMessage envelope type for the result, completion page → host. */
+export declare const MESSAGE_TYPE = "@withone/connect:result";
+/** Posted by One's connect page (cross-origin) when the user closes the
+ *  card without a result. */
+export declare const EXIT_MESSAGE_TYPE = "@withone/connect:exit";
+/** Query params the consumer's callback route puts on its final
+ *  redirect (any same-origin URL). The SDK reads them straight off the
+ *  iframe's location once the frame is back on the consumer's origin —
+ *  no completion page, no postMessage required. */
+export declare const RETURN_STATUS_PARAM = "one_connect";
+export declare const RETURN_MESSAGE_PARAM = "one_connect_message";
+/** Fragment key on the authorize URL carrying the app-chosen theme.
+ *  A fragment never reaches any server and survives the whole redirect
+ *  chain, so the consumer's backend forwards nothing. */
+export declare const THEME_PARAM = "one_theme";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useOneConnect } from "./useOneConnect";
+export { completeOneConnect } from "./complete";
+export type { OneConnectProps, OneConnectHandle, OneConnectResult, } from "./types";

package/dist/index.esm.js

@@ -0,0 +1 @@
+const e="@withone/connect:result",t="one-connect-frame";function n(){const e=document.getElementById(t);e&&e.remove()}const o="one-connect-success";function i(){var e;null===(e=document.getElementById(o))||void 0===e||e.remove()}function r(){return document.getElementById(t)}const s=s=>{let a=null,c=!1;const d=()=>{"undefined"!=typeof window&&a&&(window.removeEventListener("message",a),a=null),n()},l=(e,t)=>{if(!c){c=!0,d(),"success"===e&&function(e){var t;i();const n="dark"===e,r=document.createElement("div");r.id=o,Object.assign(r.style,{position:"fixed",inset:"0",zIndex:"2147483000",display:"flex",alignItems:"center",justifyContent:"center",background:"rgba(8, 8, 8, 0.5)",opacity:"0",transition:"opacity 160ms ease"});const s=document.createElement("div");Object.assign(s.style,{width:"320px",maxWidth:"calc(100vw - 32px)",padding:"40px 32px",borderRadius:"28px",background:n?"rgba(25, 25, 25, 0.97)":"rgba(255, 255, 255, 0.97)",border:"1px solid "+(n?"rgba(255,255,255,0.08)":"rgba(228,228,223,0.9)"),display:"flex",flexDirection:"column",alignItems:"center",gap:"16px",textAlign:"center",fontFamily:"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"});const a=n?"#a1a1aa":"#6b7280";s.style.position="relative",s.innerHTML=`<button data-one-close aria-label="Close" style="position:absolute;top:16px;right:16px;width:20px;height:20px;padding:0;border:0;background:none;cursor:pointer;color:${a};line-height:0;"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M18 6L6 18M6 6l12 12"/></svg></button><div style="width:56px;height:56px;border-radius:50%;background:#10b981;display:flex;align-items:center;justify-content:center;"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M5 13l4 4L19 7"/></svg></div><div style="font-size:17px;font-weight:600;letter-spacing:-0.01em;color:${n?"#fafafa":"#111114"};">Access granted</div><div style="font-size:13px;line-height:1.5;max-width:240px;color:${a};">Your tools are connected. You can pick up right where you left off.</div><button data-one-close style="width:100%;margin-top:8px;padding:10px 0;border:0;border-radius:12px;cursor:pointer;font-size:14px;font-weight:500;background:${n?"#fafafa":"#111114"};color:${n?"#111114":"#fafafa"};">Close</button>`,r.appendChild(s),document.body.appendChild(r),requestAnimationFrame(()=>{r.style.opacity="1"});const c=()=>{window.removeEventListener("keydown",d),r.style.opacity="0",window.setTimeout(()=>r.remove(),180)};function d(e){"Escape"===e.key&&c()}for(const e of s.querySelectorAll("[data-one-close]"))e.addEventListener("click",c);r.addEventListener("click",e=>{e.target===r&&c()}),window.addEventListener("keydown",d),null===(t=s.querySelector("[data-one-close]"))||void 0===t||t.focus()}(s.appTheme);try{var n,r;if("success"===e)null===(n=s.onSuccess)||void 0===n||n.call(s);else null===(r=s.onError)||void 0===r||r.call(s,null!=t?t:"The connection was not completed.")}catch{}}},u=t=>{const n=t.data;if(!n)return;const o=r();if(o&&t.source===o.contentWindow)if("@withone/connect:exit"!==n.type)n.type!==e||t.origin!==window.location.origin||"success"!==n.status&&"error"!==n.status||l(n.status,n.message);else{d();try{var i;null===(i=s.onClose)||void 0===i||i.call(s)}catch{}}},p=()=>{var e;const t=r();if(!t)return;let n,o;try{var i,s;n=null!==(i=null===(s=t.contentWindow)||void 0===s?void 0:s.location.href)&&void 0!==i?i:""}catch{return}try{o=new URL(n).searchParams}catch{return}const a=o.get("one_connect");"success"!==a&&"error"!==a||(t.style.visibility="hidden",l(a,null!==(e=o.get("one_connect_message"))&&void 0!==e?e:void 0))};return{open:()=>{if("undefined"==typeof window)return;c=!1,a=u,window.addEventListener("message",a);(function(e){n();const o=document.createElement("iframe");return o.id=t,o.src=e,o.setAttribute("allowtransparency","true"),Object.assign(o.style,{position:"fixed",inset:"0",width:"100%",height:"100%",border:"0",zIndex:"2147483000",background:"transparent",colorScheme:"normal"}),document.body.appendChild(o),o})((()=>{try{const e=new URL(s.authorize.url);return s.appTheme&&(e.hash=`one_theme=${s.appTheme}`),e.toString()}catch{return s.authorize.url}})()).addEventListener("load",p)},close:()=>{i(),d()}}};function a(t={status:"success"}){if("undefined"==typeof window)return!1;if(window.parent&&window.parent!==window){const n={type:e,status:t.status,message:t.message};try{return window.parent.postMessage(n,window.location.origin),!0}catch{return!1}}return!1}export{a as completeOneConnect,s as useOneConnect};

package/dist/index.umd.js

@@ -0,0 +1 @@
+"use strict";const e="@withone/connect:result",t="one-connect-frame";function n(){const e=document.getElementById(t);e&&e.remove()}const o="one-connect-success";function i(){var e;null===(e=document.getElementById(o))||void 0===e||e.remove()}function r(){return document.getElementById(t)}exports.completeOneConnect=function(t={status:"success"}){if("undefined"==typeof window)return!1;if(window.parent&&window.parent!==window){const n={type:e,status:t.status,message:t.message};try{return window.parent.postMessage(n,window.location.origin),!0}catch{return!1}}return!1},exports.useOneConnect=s=>{let c=null,a=!1;const d=()=>{"undefined"!=typeof window&&c&&(window.removeEventListener("message",c),c=null),n()},l=(e,t)=>{if(!a){a=!0,d(),"success"===e&&function(e){var t;i();const n="dark"===e,r=document.createElement("div");r.id=o,Object.assign(r.style,{position:"fixed",inset:"0",zIndex:"2147483000",display:"flex",alignItems:"center",justifyContent:"center",background:"rgba(8, 8, 8, 0.5)",opacity:"0",transition:"opacity 160ms ease"});const s=document.createElement("div");Object.assign(s.style,{width:"320px",maxWidth:"calc(100vw - 32px)",padding:"40px 32px",borderRadius:"28px",background:n?"rgba(25, 25, 25, 0.97)":"rgba(255, 255, 255, 0.97)",border:"1px solid "+(n?"rgba(255,255,255,0.08)":"rgba(228,228,223,0.9)"),display:"flex",flexDirection:"column",alignItems:"center",gap:"16px",textAlign:"center",fontFamily:"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"});const c=n?"#a1a1aa":"#6b7280";s.style.position="relative",s.innerHTML=`<button data-one-close aria-label="Close" style="position:absolute;top:16px;right:16px;width:20px;height:20px;padding:0;border:0;background:none;cursor:pointer;color:${c};line-height:0;"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M18 6L6 18M6 6l12 12"/></svg></button><div style="width:56px;height:56px;border-radius:50%;background:#10b981;display:flex;align-items:center;justify-content:center;"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M5 13l4 4L19 7"/></svg></div><div style="font-size:17px;font-weight:600;letter-spacing:-0.01em;color:${n?"#fafafa":"#111114"};">Access granted</div><div style="font-size:13px;line-height:1.5;max-width:240px;color:${c};">Your tools are connected. You can pick up right where you left off.</div><button data-one-close style="width:100%;margin-top:8px;padding:10px 0;border:0;border-radius:12px;cursor:pointer;font-size:14px;font-weight:500;background:${n?"#fafafa":"#111114"};color:${n?"#111114":"#fafafa"};">Close</button>`,r.appendChild(s),document.body.appendChild(r),requestAnimationFrame(()=>{r.style.opacity="1"});const a=()=>{window.removeEventListener("keydown",d),r.style.opacity="0",window.setTimeout(()=>r.remove(),180)};function d(e){"Escape"===e.key&&a()}for(const e of s.querySelectorAll("[data-one-close]"))e.addEventListener("click",a);r.addEventListener("click",e=>{e.target===r&&a()}),window.addEventListener("keydown",d),null===(t=s.querySelector("[data-one-close]"))||void 0===t||t.focus()}(s.appTheme);try{var n,r;if("success"===e)null===(n=s.onSuccess)||void 0===n||n.call(s);else null===(r=s.onError)||void 0===r||r.call(s,null!=t?t:"The connection was not completed.")}catch{}}},u=t=>{const n=t.data;if(!n)return;const o=r();if(o&&t.source===o.contentWindow)if("@withone/connect:exit"!==n.type)n.type!==e||t.origin!==window.location.origin||"success"!==n.status&&"error"!==n.status||l(n.status,n.message);else{d();try{var i;null===(i=s.onClose)||void 0===i||i.call(s)}catch{}}},p=()=>{var e;const t=r();if(!t)return;let n,o;try{var i,s;n=null!==(i=null===(s=t.contentWindow)||void 0===s?void 0:s.location.href)&&void 0!==i?i:""}catch{return}try{o=new URL(n).searchParams}catch{return}const c=o.get("one_connect");"success"!==c&&"error"!==c||(t.style.visibility="hidden",l(c,null!==(e=o.get("one_connect_message"))&&void 0!==e?e:void 0))};return{open:()=>{if("undefined"==typeof window)return;a=!1,c=u,window.addEventListener("message",c);(function(e){n();const o=document.createElement("iframe");return o.id=t,o.src=e,o.setAttribute("allowtransparency","true"),Object.assign(o.style,{position:"fixed",inset:"0",width:"100%",height:"100%",border:"0",zIndex:"2147483000",background:"transparent",colorScheme:"normal"}),document.body.appendChild(o),o})((()=>{try{const e=new URL(s.authorize.url);return s.appTheme&&(e.hash=`one_theme=${s.appTheme}`),e.toString()}catch{return s.authorize.url}})()).addEventListener("load",p)},close:()=>{i(),d()}}};

package/dist/types/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Public types for @withone/connect.
+ *
+ * The SDK deliberately knows nothing about OAuth internals: state, PKCE
+ * and the client secret live on the consumer's backend (see README).
+ * The SDK only opens One's connect experience as a modal over the host
+ * page and reports how the flow ended.
+ */
+
+/** Result posted back from the consumer's completion page. */
+export interface OneConnectResult {
+  status: "success" | "error";
+  /** Human-readable detail for the error case. */
+  message?: string;
+}
+
+export interface OneConnectProps {
+  /**
+   * The consumer's OWN backend route that starts the flow. It must
+   * generate `state` + PKCE, set them in an httpOnly cookie, and 302
+   * to One's /oauth/authorize (full recipe in the README). Must be an
+   * absolute URL.
+   */
+  authorize: {
+    url: string;
+  };
+  /** Theme for One's card. Carried on the URL fragment (#one_theme=…),
+   *  which survives the redirect chain — the consumer's backend forwards
+   *  nothing. */
+  appTheme?: "dark" | "light";
+  /** Fired when the completion page reports success. The token exchange
+   *  already happened on the consumer's backend by this point. */
+  onSuccess?: () => void;
+  /** Fired when the completion page reports an error. */
+  onError?: (error: string) => void;
+  /** Fired when the user closes the card without a result. */
+  onClose?: () => void;
+}
+
+export interface OneConnectHandle {
+  /** Opens One's connect modal over the current page. */
+  open: () => void;
+  /** Tears everything down: modal frame + listeners. */
+  close: () => void;
+}
+
+/** Message posted from the completion page up to the host page. */
+export interface OneConnectMessage {
+  type: string; // MESSAGE_TYPE constant
+  status: "success" | "error";
+  message?: string;
+}

package/dist/useOneConnect.d.ts

@@ -0,0 +1,2 @@
+import type { OneConnectHandle, OneConnectProps } from "./types";
+export declare const useOneConnect: (props: OneConnectProps) => OneConnectHandle;

package/dist/window/index.d.ts

@@ -0,0 +1,13 @@
+export declare const IFRAME_ID = "one-connect-frame";
+export declare function createEmbedIframe(url: string): HTMLIFrameElement;
+export declare function removeEmbedIframe(): void;
+export declare const SUCCESS_ID = "one-connect-success";
+/** The "Access granted" confirmation shown after the grant completes —
+ *  the same beat as authkit's "Connection established" screen, and
+ *  dismissed the same way: the user closes it with the ✕ or the Close
+ *  button, never a timer. By this point the card's iframe has already
+ *  navigated home and been removed, so the SDK paints this itself.
+ *  Pure inline styles — the SDK ships no CSS and loads no assets. */
+export declare function showSuccessOverlay(theme?: "dark" | "light"): void;
+export declare function removeSuccessOverlay(): void;
+export declare function getEmbedIframe(): HTMLIFrameElement | null;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@withone/connect",
+  "version": "0.1.0",
+  "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.",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "dist/index.umd.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/plugin-transform-class-properties": "^7.28.6",
+    "@babel/plugin-transform-nullish-coalescing-operator": "^7.28.6",
+    "@babel/plugin-transform-optional-chaining": "^7.28.6",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-typescript": "^7.28.5",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@tsconfig/recommended": "^1.0.3",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.5",
+    "rollup": "^4.12.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "author": "@withoneai",
+  "publishConfig": {
+    "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}\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withoneai/connect"
+  },
+  "bugs": {
+    "url": "https://github.com/withoneai/connect/issues"
+  },
+  "keywords": [
+    "withone",
+    "oauth",
+    "integrations",
+    "agents"
+  ],
+  "license": "GPL-3.0",
+  "homepage": "https://withone.ai"
+}

package/src/complete.ts

@@ -0,0 +1,36 @@
+import { MESSAGE_TYPE } from "./constants";
+import type { OneConnectMessage, OneConnectResult } from "./types";
+
+/**
+ * OPTIONAL. The standard integration needs no completion page at all:
+ * the callback route's final redirect carries ?one_connect=success (or
+ * error) on any same-origin URL, and the SDK reads it off the frame's
+ * location directly. Use this helper only if you render a custom
+ * completion page and want to signal the SDK from it explicitly.
+ *
+ * Returns false when it had nothing to do (not inside a frame) — e.g.
+ * the user opened the page directly. Render fallback UI in that case.
+ */
+export function completeOneConnect(
+  result: OneConnectResult = { status: "success" }
+): boolean {
+  if (typeof window === "undefined") return false;
+
+  if (window.parent && window.parent !== window) {
+    const message: OneConnectMessage = {
+      type: MESSAGE_TYPE,
+      status: result.status,
+      message: result.message,
+    };
+    try {
+      // Target the consumer origin only — never "*". The host page
+      // additionally checks event.origin before trusting the message.
+      window.parent.postMessage(message, window.location.origin);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+}

package/src/constants.ts

@@ -0,0 +1,23 @@
+// Wire-protocol constants shared by useOneConnect (host page) and
+// completeOneConnect (the consumer's completion page). Changing any of
+// these is a breaking change between SDK versions running on the two
+// pages — bump with care.
+
+/** postMessage envelope type for the result, completion page → host. */
+export const MESSAGE_TYPE = "@withone/connect:result";
+
+/** Posted by One's connect page (cross-origin) when the user closes the
+ *  card without a result. */
+export const EXIT_MESSAGE_TYPE = "@withone/connect:exit";
+
+/** Query params the consumer's callback route puts on its final
+ *  redirect (any same-origin URL). The SDK reads them straight off the
+ *  iframe's location once the frame is back on the consumer's origin —
+ *  no completion page, no postMessage required. */
+export const RETURN_STATUS_PARAM = "one_connect";
+export const RETURN_MESSAGE_PARAM = "one_connect_message";
+
+/** Fragment key on the authorize URL carrying the app-chosen theme.
+ *  A fragment never reaches any server and survives the whole redirect
+ *  chain, so the consumer's backend forwards nothing. */
+export const THEME_PARAM = "one_theme";

package/src/index.ts

@@ -0,0 +1,7 @@
+export { useOneConnect } from "./useOneConnect";
+export { completeOneConnect } from "./complete";
+export type {
+  OneConnectProps,
+  OneConnectHandle,
+  OneConnectResult,
+} from "./types";