@withone/connect 0.1.0

package/src/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/src/useOneConnect.ts

@@ -0,0 +1,142 @@
+import {
+  EXIT_MESSAGE_TYPE,
+  MESSAGE_TYPE,
+  RETURN_MESSAGE_PARAM,
+  RETURN_STATUS_PARAM,
+  THEME_PARAM,
+} from "./constants";
+import {
+  createEmbedIframe,
+  getEmbedIframe,
+  removeEmbedIframe,
+  removeSuccessOverlay,
+  showSuccessOverlay,
+} from "./window";
+import type {
+  OneConnectHandle,
+  OneConnectMessage,
+  OneConnectProps,
+} from "./types";
+
+// Like useOneAuth, this is a plain function rather than a React hook so
+// it works from any framework.
+export const useOneConnect = (props: OneConnectProps): OneConnectHandle => {
+  let messageHandler: ((event: MessageEvent) => void) | null = null;
+  let resultDelivered = false;
+
+  // The theme rides in the URL FRAGMENT: fragments never reach any
+  // server and browsers carry them through the whole redirect chain
+  // (consumer's authorize route -> One -> the card), so the consumer's
+  // backend forwards NOTHING. Embedding needs no signal at all -- the
+  // card detects its own iframe with window.self !== window.top.
+  const buildUrl = (): string => {
+    try {
+      const url = new URL(props.authorize.url);
+      if (props.appTheme) url.hash = `${THEME_PARAM}=${props.appTheme}`;
+      return url.toString();
+    } catch {
+      return props.authorize.url;
+    }
+  };
+
+  const teardown = () => {
+    if (typeof window !== "undefined" && messageHandler) {
+      window.removeEventListener("message", messageHandler);
+      messageHandler = null;
+    }
+    removeEmbedIframe();
+  };
+
+  const deliver = (status: "success" | "error", message?: string) => {
+    if (resultDelivered) return;
+    resultDelivered = true;
+    teardown();
+    // The confirmation beat: by now the frame is gone, so the SDK
+    // paints a brief "Access granted" card itself while the host page
+    // (already told via onSuccess below) updates underneath it.
+    if (status === "success") showSuccessOverlay(props.appTheme);
+    try {
+      if (status === "success") {
+        props.onSuccess?.();
+      } else {
+        props.onError?.(message ?? "The connection was not completed.");
+      }
+    } catch {
+      /* consumer callback errors are not our problem */
+    }
+  };
+
+  // Only trust messages from OUR iframe's browsing context. Exit can
+  // come from One's page (cross-origin); results come from the
+  // completion page, which is the consumer's own origin because the
+  // OAuth redirect brought the frame home.
+  const handleMessage = (event: MessageEvent) => {
+    const data = event.data as OneConnectMessage | undefined;
+    if (!data) return;
+
+    const iframe = getEmbedIframe();
+    if (!iframe || event.source !== iframe.contentWindow) return;
+
+    if (data.type === EXIT_MESSAGE_TYPE) {
+      teardown();
+      try {
+        props.onClose?.();
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    if (
+      data.type === MESSAGE_TYPE &&
+      event.origin === window.location.origin &&
+      (data.status === "success" || data.status === "error")
+    ) {
+      deliver(data.status, data.message);
+    }
+  };
+
+  // Fires on every navigation inside the frame. While the frame is on
+  // One's origin, reading its location throws (same-origin policy) and
+  // we ignore it. The moment the consumer's callback redirects home —
+  // to ANY same-origin URL carrying ?one_connect=success|error — the
+  // read succeeds and the flow completes. The consumer writes no
+  // completion page and no postMessage; their callback's final
+  // redirect IS the completion signal.
+  const handleFrameLoad = () => {
+    const iframe = getEmbedIframe();
+    if (!iframe) return;
+    let href: string;
+    try {
+      href = iframe.contentWindow?.location.href ?? "";
+    } catch {
+      return; // still cross-origin — not home yet
+    }
+    let params: URLSearchParams;
+    try {
+      params = new URL(href).searchParams;
+    } catch {
+      return;
+    }
+    const status = params.get(RETURN_STATUS_PARAM);
+    if (status !== "success" && status !== "error") return;
+    iframe.style.visibility = "hidden"; // no flash of the landing page
+    deliver(status, params.get(RETURN_MESSAGE_PARAM) ?? undefined);
+  };
+
+  const open = () => {
+    if (typeof window === "undefined") return;
+    resultDelivered = false;
+
+    messageHandler = handleMessage;
+    window.addEventListener("message", messageHandler);
+    const iframe = createEmbedIframe(buildUrl());
+    iframe.addEventListener("load", handleFrameLoad);
+  };
+
+  const close = () => {
+    removeSuccessOverlay();
+    teardown();
+  };
+
+  return { open, close };
+};

package/src/window/index.ts

@@ -0,0 +1,136 @@
+// Frame management for @withone/connect.
+//
+// The SDK has exactly one presentation: an authkit-style modal. A
+// full-viewport transparent iframe sits over the host page; One's
+// connect page renders a scrim + centered card inside it, so the host
+// app stays visible and dimmed underneath. Works at every viewport
+// size — the card is responsive and the frame is the viewport.
+//
+// Transport note: every step of the flow rides on the user's One
+// session cookie, which is a THIRD-PARTY cookie when the host page is
+// on a different site than One. Production embedding therefore relies
+// on One serving that cookie as `Partitioned` (CHIPS) and allowing the
+// client's domain via frame-ancestors (RFC 6749 §10.13). Same-site
+// setups (e.g. localhost dev) work everywhere as-is.
+
+export const IFRAME_ID = "one-connect-frame";
+
+export function createEmbedIframe(url: string): HTMLIFrameElement {
+  removeEmbedIframe();
+  const iframe = document.createElement("iframe");
+  iframe.id = IFRAME_ID;
+  iframe.src = url;
+  iframe.setAttribute("allowtransparency", "true");
+  Object.assign(iframe.style, {
+    position: "fixed",
+    inset: "0",
+    width: "100%",
+    height: "100%",
+    border: "0",
+    zIndex: "2147483000",
+    background: "transparent",
+    colorScheme: "normal", // keep the transparent viewport from being painted
+  } as Partial<CSSStyleDeclaration>);
+  document.body.appendChild(iframe);
+  return iframe;
+}
+
+export function removeEmbedIframe(): void {
+  const existing = document.getElementById(IFRAME_ID);
+  if (existing) existing.remove();
+}
+
+export 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 function showSuccessOverlay(theme?: "dark" | "light"): void {
+  removeSuccessOverlay();
+  const dark = theme === "dark";
+  const overlay = document.createElement("div");
+  overlay.id = SUCCESS_ID;
+  Object.assign(overlay.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",
+  } as Partial<CSSStyleDeclaration>);
+
+  const card = document.createElement("div");
+  Object.assign(card.style, {
+    width: "320px",
+    maxWidth: "calc(100vw - 32px)",
+    padding: "40px 32px",
+    borderRadius: "28px",
+    background: dark ? "rgba(25, 25, 25, 0.97)" : "rgba(255, 255, 255, 0.97)",
+    border: `1px solid ${dark ? "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",
+  } as Partial<CSSStyleDeclaration>);
+  const muted = dark ? "#a1a1aa" : "#6b7280";
+  card.style.position = "relative";
+  card.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:${muted};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:${dark ? "#fafafa" : "#111114"};">Access granted</div>` +
+    `<div style="font-size:13px;line-height:1.5;max-width:240px;color:${muted};">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:${dark ? "#fafafa" : "#111114"};color:${dark ? "#111114" : "#fafafa"};">Close</button>`;
+
+  overlay.appendChild(card);
+  document.body.appendChild(overlay);
+  requestAnimationFrame(() => {
+    overlay.style.opacity = "1";
+  });
+
+  const dismiss = () => {
+    window.removeEventListener("keydown", onKeydown);
+    overlay.style.opacity = "0";
+    window.setTimeout(() => overlay.remove(), 180);
+  };
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === "Escape") dismiss();
+  }
+
+  for (const button of card.querySelectorAll("[data-one-close]")) {
+    button.addEventListener("click", dismiss);
+  }
+  // The card is dismissed deliberately, never on a timer — but this
+  // overlay covers the host page at the top of the stacking context, so
+  // it must never be able to strand the app. Clicking the scrim outside
+  // the card and pressing Escape are both floors under the buttons: if a
+  // button ever fails to render or bind, the user is still not trapped.
+  overlay.addEventListener("click", (event) => {
+    if (event.target === overlay) dismiss();
+  });
+  window.addEventListener("keydown", onKeydown);
+
+  // Send focus somewhere sane for keyboard and screen-reader users, who
+  // otherwise land on a full-viewport overlay with no reachable control.
+  (card.querySelector("[data-one-close]") as HTMLElement | null)?.focus();
+}
+
+export function removeSuccessOverlay(): void {
+  document.getElementById(SUCCESS_ID)?.remove();
+}
+
+export function getEmbedIframe(): HTMLIFrameElement | null {
+  return document.getElementById(IFRAME_ID) as HTMLIFrameElement | null;
+}