@withone/connect 0.11.0 → 0.12.0

package/src/constants.ts

@@ -2,7 +2,11 @@
  *  The SDK reads them off the page URL when the tab comes home, so
  *  there is no completion page to build. */
 export const RETURN_STATUS_PARAM = "one_connect";
-export const RETURN_MESSAGE_PARAM = "one_connect_message";
+/** Why the flow failed, as a code (see ConnectFailureCode). */
+export const RETURN_ERROR_PARAM = "one_connect_error";
+/** Free text that routes before 0.12 put on the URL. Stripped from the
+ *  address bar, never shown: anyone can write a link that carries it. */
+export const LEGACY_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

package/src/flow.ts

@@ -0,0 +1,171 @@
+import { THEME_PARAM } from "./constants";
+import { hasReturnParams, parseReturn, stripReturnParams } from "./return";
+import type {
+  OneConnectFlow,
+  OneConnectFlowOptions,
+  OneConnectReturn,
+} from "./types";
+
+/**
+ * The browser half of the flow, shared by every button and hook on the
+ * page. 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 with `?one_connect=…`.
+ *
+ * That return is a fact about the page load, not about one button, so it
+ * is read once here. Every button renders it; the callbacks go to the
+ * first flow still mounted when they fire, which is what makes React's
+ * StrictMode (mount, unmount, mount) and a second button on the page
+ * behave.
+ */
+
+interface Subscriber {
+  deliver: (outcome: OneConnectReturn) => void;
+  restored: () => void;
+}
+
+/** undefined until read; null when this load is not a return. */
+let pageReturn: OneConnectReturn | null | undefined;
+let delivered = false;
+let deliveryScheduled = false;
+let pageshowBound = false;
+const subscribers: Subscriber[] = [];
+
+/** How this page load ended a flow, if it did: `{ status: "success" }`,
+ *  `{ status: "error", code, message }`, or null. Read once per load, so
+ *  every caller sees the same answer after the address bar is cleaned. */
+export function readConnectReturn(): OneConnectReturn | null {
+  return readPageReturn();
+}
+
+function readPageReturn(): OneConnectReturn | null {
+  if (typeof window === "undefined") return null;
+  if (pageReturn === undefined) {
+    pageReturn = parseReturn(window.location.search);
+    if (pageReturn || hasReturnParams(window.location.search))
+      scrubAddressBar();
+  }
+  return pageReturn;
+}
+
+/** Removes the params so a refresh does not replay the outcome.
+ *  Frameworks that manage history themselves (the Next.js App Router)
+ *  put their own URL back when hydration completes, undoing a single
+ *  replaceState, so scrub now and re-check a few beats later. */
+function scrubAddressBar(): void {
+  const scrub = () => {
+    if (!hasReturnParams(window.location.search)) return;
+    window.history.replaceState(
+      window.history.state,
+      "",
+      stripReturnParams(window.location),
+    );
+  };
+  scrub();
+  for (const delay of [50, 500, 2000]) window.setTimeout(scrub, delay);
+}
+
+function scheduleDelivery(): void {
+  if (delivered || deliveryScheduled) return;
+  const outcome = readPageReturn();
+  if (!outcome) return;
+  deliveryScheduled = true;
+  window.setTimeout(() => {
+    deliveryScheduled = false;
+    const target = subscribers[0];
+    // Nobody mounted yet: the next flow to subscribe receives it.
+    if (!target || delivered) return;
+    delivered = true;
+    target.deliver(outcome);
+  }, 0);
+}
+
+/** A page restored from the back-forward cache keeps its JavaScript
+ *  state, so a flow that was mid-redirect would still say Connecting. */
+function bindPageshow(): void {
+  if (pageshowBound || typeof window === "undefined") return;
+  pageshowBound = true;
+  window.addEventListener("pageshow", (event) => {
+    if (!event.persisted) return;
+    for (const subscriber of [...subscribers]) subscriber.restored();
+  });
+}
+
+const authorizeUrlFor = (options: OneConnectFlowOptions): string => {
+  const theme = options.connectTheme ?? options.appTheme;
+  try {
+    const url = new URL(options.authorizeUrl, window.location.origin);
+    if (theme) url.hash = `${THEME_PARAM}=${theme}`;
+    return url.toString();
+  } catch {
+    return options.authorizeUrl;
+  }
+};
+
+/**
+ * Wires the connect flow to any element: call it once where your button
+ * lives, pass `open` to a click, and `destroy` when the element goes.
+ * A plain function, so it works from every framework; React apps can use
+ * the `useOneConnect` hook from `@withone/connect/react` instead.
+ */
+export function createConnectFlow(
+  options: OneConnectFlowOptions,
+): OneConnectFlow {
+  let current = options;
+  let connecting = false;
+
+  const subscriber: Subscriber = {
+    deliver: (outcome) => {
+      try {
+        if (outcome.status === "success") current.onSuccess?.();
+        else current.onError?.(outcome.message ?? "", outcome.code ?? "failed");
+      } catch {
+        /* the app's own callback threw; not ours to handle */
+      }
+    },
+    restored: () => {
+      if (!connecting) return;
+      connecting = false;
+      try {
+        current.onCancel?.();
+      } catch {
+        /* the app's own callback threw; not ours to handle */
+      }
+    },
+  };
+
+  if (typeof window !== "undefined") {
+    subscribers.push(subscriber);
+    bindPageshow();
+    scheduleDelivery();
+  }
+
+  return {
+    open: () => {
+      if (typeof window === "undefined") return;
+      connecting = true;
+      window.location.assign(authorizeUrlFor(current));
+    },
+    update: (next) => {
+      current = next;
+    },
+    destroy: () => {
+      const index = subscribers.indexOf(subscriber);
+      if (index >= 0) subscribers.splice(index, 1);
+    },
+  };
+}
+
+/** @deprecated Renamed to `createConnectFlow` (it is not a React hook;
+ *  React apps can use `useOneConnect` from `@withone/connect/react`).
+ *  Removed in the next minor. */
+export const useOneConnect = (options: OneConnectFlowOptions): OneConnectFlow =>
+  createConnectFlow(options);
+
+/** Test seam: forget this page load's outcome. */
+export function resetPageReturnForTests(): void {
+  pageReturn = undefined;
+  delivered = false;
+  deliveryScheduled = false;
+  subscribers.length = 0;
+}

package/src/index.ts

@@ -1,25 +1,23 @@
-export { useOneConnect } from "./useOneConnect";
+export { createConnectFlow, readConnectReturn, useOneConnect } from "./flow";
 export { mountConnectButton, registerConnectButton } from "./button";
-export {
-  optionsFromProps,
-  propsIdentity,
-  type ConnectButtonProps,
-  type ConnectButtonCallbacks,
-} from "./wrapper-options";
-export {
-  normalizePlatform,
-  normalizePlatforms,
-  parsePlatformsAttribute,
-} from "./platforms";
 export type {
-  OneConnectOptions,
-  OneConnectHandle,
-  OneConnectReturn,
-  OneConnectTheme,
-  ConnectButtonOptions,
+  ConnectButtonHandle,
   ConnectButtonPlatform,
   ConnectButtonPlatformInput,
-  ConnectButtonVariant,
+  ConnectButtonProps,
+  ConnectButtonSize,
   ConnectButtonState,
-  ConnectButtonHandle,
+  ConnectButtonTheme,
+  ConnectButtonVariant,
+  ConnectFailureCode,
+  OneConnectFlow,
+  OneConnectFlowOptions,
+  OneConnectReturn,
+  OneConnectTheme,
 } from "./types";
+
+import type { OneConnectFlow, OneConnectFlowOptions } from "./types";
+/** @deprecated Renamed to `OneConnectFlowOptions`; removed in the next minor. */
+export type OneConnectOptions = OneConnectFlowOptions;
+/** @deprecated Renamed to `OneConnectFlow`; removed in the next minor. */
+export type OneConnectHandle = OneConnectFlow;

package/src/platforms.ts

@@ -13,13 +13,48 @@ export function slugFromName(name: string): string {
     .replace(/^-+|-+$/g, "");
 }
 
-/** "google-calendar" -> "Google Calendar". */
+/** Brands whose name is not their slug in title case. Everything else
+ *  reads right from the slug ("google-calendar" -> "Google Calendar"). */
+const BRAND_NAMES: Record<string, string> = {
+  "cal-com": "Cal.com",
+  "click-up": "ClickUp",
+  clickup: "ClickUp",
+  docusign: "DocuSign",
+  elevenlabs: "ElevenLabs",
+  "fireflies-ai": "Fireflies.ai",
+  github: "GitHub",
+  gitlab: "GitLab",
+  hubspot: "HubSpot",
+  "linked-in": "LinkedIn",
+  linkedin: "LinkedIn",
+  "one-drive": "OneDrive",
+  onedrive: "OneDrive",
+  openai: "OpenAI",
+  "otter-ai": "Otter.ai",
+  paypal: "PayPal",
+  posthog: "PostHog",
+  quickbooks: "QuickBooks",
+  sharepoint: "SharePoint",
+  "spotify-web": "Spotify",
+  teams: "Microsoft Teams",
+  "telegram-bot": "Telegram",
+  "whatsapp-business": "WhatsApp Business",
+  woocommerce: "WooCommerce",
+  x: "X",
+  "youtube-data": "YouTube",
+  youtube: "YouTube",
+};
+
+/** "google-calendar" -> "Google Calendar"; "hubspot" -> "HubSpot". */
 export function nameFromSlug(slug: string): string {
-  return slug
-    .split(/[-_]+/)
-    .filter(Boolean)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
+  return (
+    BRAND_NAMES[slug] ??
+    slug
+      .split(/[-_]+/)
+      .filter(Boolean)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(" ")
+  );
 }
 
 /** One's logo for a connector slug. */

package/src/react.ts

@@ -1,56 +1,85 @@
 /**
- * React: `import { ConnectButton } from "@withone/connect/react"`.
+ * React: `import { ConnectButton, useOneConnect } from "@withone/connect/react"`.
  *
- * A component over the framework-agnostic core, so React apps get real
- * props (arrays, functions) instead of the custom element's string
- * attributes. React is a peer dependency of this subpath only.
+ * Ships with a "use client" directive, so it imports straight into a
+ * Next.js Server Component tree. React is a peer dependency of this
+ * subpath only.
  */
-import { createElement, useEffect, useRef } from "react";
+import { createElement, useCallback, useEffect, useRef, useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 
 import {
+  createConnectFlow,
   mountConnectButton,
-  optionsFromProps,
-  propsIdentity,
+  readConnectReturn,
   type ConnectButtonHandle,
   type ConnectButtonProps as ConnectButtonCoreProps,
+  type ConnectFailureCode,
+  type OneConnectFlow,
+  type OneConnectFlowOptions,
 } from "@withone/connect";
 
 export interface ConnectButtonProps extends ConnectButtonCoreProps {
+  /** On the wrapper element around the button. */
   className?: string;
   style?: CSSProperties;
 }
 
+/** The props that change what the button draws; callbacks are read
+ *  through a ref, so a new function each render costs nothing. */
+const visualKey = (props: ConnectButtonCoreProps): string =>
+  JSON.stringify([
+    props.authorizeUrl,
+    props.platforms ?? [],
+    props.connected,
+    props.disabled,
+    props.variant,
+    props.size,
+    props.fullWidth,
+    props.theme,
+    props.connectTheme ?? props.appTheme,
+    props.accentColor,
+    props.label,
+    props.connectedLabel,
+    props.description,
+  ]);
+
 export function ConnectButton(props: ConnectButtonProps): ReactElement {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const handleRef = useRef<ConnectButtonHandle | null>(null);
+  const keyRef = useRef<string>("");
+  const latest = useRef(props);
+  latest.current = props;
 
-  // Callbacks stay fresh without remounting the button.
-  const callbacksRef = useRef({
-    onSuccess: props.onSuccess,
-    onError: props.onError,
+  const withLatestCallbacks = (): ConnectButtonCoreProps => ({
+    ...latest.current,
+    onSuccess: () => latest.current.onSuccess?.(),
+    onError: (message, code) => latest.current.onError?.(message, code),
+    onCancel: () => latest.current.onCancel?.(),
   });
-  callbacksRef.current = { onSuccess: props.onSuccess, onError: props.onError };
-
-  const identity = propsIdentity(props);
 
   useEffect(() => {
     if (!containerRef.current) return;
     handleRef.current = mountConnectButton(
       containerRef.current,
-      optionsFromProps(props, {
-        onSuccess: () => callbacksRef.current.onSuccess?.(),
-        onError: (message) => callbacksRef.current.onError?.(message),
-      }),
+      withLatestCallbacks(),
     );
+    keyRef.current = visualKey(latest.current);
     return () => {
       handleRef.current?.destroy();
       handleRef.current = null;
     };
-    // Remount only when a visual or config input changes; `identity`
-    // captures exactly those.
+    // Mounted once; later changes go through update() below.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [identity]);
+  }, []);
+
+  const key = visualKey(props);
+  useEffect(() => {
+    if (!handleRef.current || key === keyRef.current) return;
+    keyRef.current = key;
+    handleRef.current.update(withLatestCallbacks());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
 
   return createElement("div", {
     ref: containerRef,
@@ -58,3 +87,72 @@ export function ConnectButton(props: ConnectButtonProps): ReactElement {
     style: props.style,
   });
 }
+
+export type OneConnectStatus = "idle" | "connecting" | "connected" | "error";
+
+export interface UseOneConnectResult {
+  /** Sends the tab to One's hosted connect flow. */
+  open: () => void;
+  /** "connected" and "error" reflect how this page load ended a flow. */
+  status: OneConnectStatus;
+  error: { message: string; code: ConnectFailureCode } | null;
+}
+
+/**
+ * The flow for your own button:
+ *
+ *   const { open, status, error } = useOneConnect({ authorizeUrl: "/api/one/authorize" });
+ *   <button onClick={open} disabled={status === "connecting"}>Connect</button>
+ */
+export function useOneConnect(
+  options: OneConnectFlowOptions,
+): UseOneConnectResult {
+  const [status, setStatus] = useState<OneConnectStatus>("idle");
+  const [error, setError] = useState<UseOneConnectResult["error"]>(null);
+  const latest = useRef(options);
+  latest.current = options;
+  const flowRef = useRef<OneConnectFlow | null>(null);
+
+  const withHandlers = (): OneConnectFlowOptions => ({
+    ...latest.current,
+    onSuccess: () => latest.current.onSuccess?.(),
+    onError: (message, code) => latest.current.onError?.(message, code),
+    onCancel: () => {
+      setStatus("idle");
+      latest.current.onCancel?.();
+    },
+  });
+
+  useEffect(() => {
+    const flow = createConnectFlow(withHandlers());
+    flowRef.current = flow;
+    // Read after mount, not during render, so server and client agree.
+    const outcome = readConnectReturn();
+    if (outcome?.status === "success") setStatus("connected");
+    else if (outcome?.status === "error") {
+      setStatus("error");
+      setError({
+        message: outcome.message ?? "",
+        code: outcome.code ?? "failed",
+      });
+    }
+    return () => {
+      flow.destroy();
+      flowRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    flowRef.current?.update(withHandlers());
+  });
+
+  const open = useCallback(() => {
+    if (!flowRef.current) return;
+    setError(null);
+    setStatus("connecting");
+    flowRef.current.open();
+  }, []);
+
+  return { open, status, error };
+}

package/src/return.ts

@@ -1,15 +1,38 @@
-import { RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "./constants";
-import type { OneConnectReturn } from "./types";
+import {
+  LEGACY_MESSAGE_PARAM,
+  RETURN_ERROR_PARAM,
+  RETURN_STATUS_PARAM,
+} from "./constants";
+import type { ConnectFailureCode, OneConnectReturn } from "./types";
 
-/** Reads the outcome the callback route put on the return URL. */
+/** The only text the SDK ever shows for a failed flow. */
+export const ERROR_MESSAGES: Record<ConnectFailureCode, string> = {
+  declined: "You cancelled the connection.",
+  expired: "The connection attempt expired. Please try again.",
+  failed: "The connection could not be completed. Please try again.",
+};
+
+const isErrorCode = (value: string | null): value is ConnectFailureCode =>
+  value !== null && Object.prototype.hasOwnProperty.call(ERROR_MESSAGES, value);
+
+/** Reads the outcome the callback route put on the return URL. The
+ *  message always comes from ERROR_MESSAGES, never from the URL. */
 export function parseReturn(search: string): OneConnectReturn | null {
   const params = new URLSearchParams(search);
   const status = params.get(RETURN_STATUS_PARAM);
-  if (status !== "success" && status !== "error") return null;
-  const message = params.get(RETURN_MESSAGE_PARAM) ?? undefined;
-  return message ? { status, message } : { status };
+  if (status === "success") return { status };
+  if (status !== "error") return null;
+  const raw = params.get(RETURN_ERROR_PARAM);
+  const code: ConnectFailureCode = isErrorCode(raw) ? raw : "failed";
+  return { status, code, message: ERROR_MESSAGES[code] };
 }
 
+const OWN_PARAMS = [
+  RETURN_STATUS_PARAM,
+  RETURN_ERROR_PARAM,
+  LEGACY_MESSAGE_PARAM,
+];
+
 /** The same URL without the return params, so a refresh does not
  *  re-fire the callbacks. */
 export function stripReturnParams(location: {
@@ -18,13 +41,12 @@ export function stripReturnParams(location: {
   hash: string;
 }): string {
   const params = new URLSearchParams(location.search);
-  params.delete(RETURN_STATUS_PARAM);
-  params.delete(RETURN_MESSAGE_PARAM);
+  for (const name of OWN_PARAMS) params.delete(name);
   const query = params.toString();
   return `${location.pathname}${query ? `?${query}` : ""}${location.hash}`;
 }
 
 export function hasReturnParams(search: string): boolean {
   const params = new URLSearchParams(search);
-  return params.has(RETURN_STATUS_PARAM) || params.has(RETURN_MESSAGE_PARAM);
+  return OWN_PARAMS.some((name) => params.has(name));
 }

package/src/server/index.ts

@@ -25,7 +25,7 @@
  * spending a refresh token, clears tokens only when One declares the
  * grant dead, and never lets a failing old pair delete a newer one.
  */
-import { DEFAULT_ONE_API_URL, RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "../constants";
+import { DEFAULT_ONE_API_URL, RETURN_ERROR_PARAM, RETURN_STATUS_PARAM } from "../constants";
 import {
   DEFAULT_SCOPES,
   basicAuthorization,
@@ -41,6 +41,7 @@ import {
   OneConnectError,
   type CompleteAuthorizationInput,
   type CompleteAuthorizationResult,
+  type ConnectFailureCode,
   type OneConnectServerConfig,
   type OneConnectTokens,
   type PlatformAction,
@@ -137,10 +138,10 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
    *  same refresh token trip One's reuse detection. */
   const refreshing = new Map<string, Promise<OneConnectTokens>>();
 
-  const returnUrl = (status: "success" | "error", message?: string): string => {
+  const returnUrl = (status: "success" | "error", code?: ConnectFailureCode): string => {
     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();
   };
 
@@ -231,23 +232,24 @@ export function createOneConnect(config: OneConnectServerConfig): OneConnect {
     const verifier = cookieName ? input.getCookie(cookieName) : undefined;
 
     const fail = (
-      outcome: "declined" | "failed",
+      failure: ConnectFailureCode,
       message: string,
     ): CompleteAuthorizationResult => ({
-      outcome,
+      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.");
+      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.
+    // 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("failed", "The sign-in attempt expired or was tampered with.");
+      return fail("expired", "The attempt expired, or its state cookie was missing.");
 
     try {
       const tokens = toTokens(

package/src/server/types.ts

@@ -110,11 +110,17 @@ export interface CompleteAuthorizationInput {
   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/src/svelte.ts

@@ -5,12 +5,11 @@
  * Svelte compiler or dependency is involved:
  *
  *   <div use:connectButton={{ authorizeUrl: "/api/one/authorize",
- *     platforms: ["stripe", "notion"],
+ *     platforms: ["stripe", "notion"], connected: data.hasOneGrant,
  *     onSuccess: () => { ... } }} />
  */
 import {
   mountConnectButton,
-  optionsFromProps,
   type ConnectButtonHandle,
   type ConnectButtonProps,
 } from "@withone/connect";
@@ -24,17 +23,10 @@ export function connectButton(
   update: (next: ConnectButtonProps) => void;
   destroy: () => void;
 } {
-  let handle: ConnectButtonHandle = mountConnectButton(
-    node,
-    optionsFromProps(props),
-  );
+  const handle: ConnectButtonHandle = mountConnectButton(node, props);
   return {
-    update(next: ConnectButtonProps) {
-      handle.destroy();
-      handle = mountConnectButton(node, optionsFromProps(next));
-    },
-    destroy() {
-      handle.destroy();
-    },
+    // In place: the button keeps its state and focus across updates.
+    update: (next) => handle.update(next),
+    destroy: () => handle.destroy(),
   };
 }