@withone/connect 0.8.3 → 0.10.0

package/src/next.ts

@@ -0,0 +1,133 @@
+/**
+ * `@withone/connect/next`: the two routes as one file, for any server
+ * that speaks the web `Request` and `Response` (Next.js App Router,
+ * Remix, SvelteKit, Nuxt/h3 via its adapters, Hono, Bun).
+ *
+ *   // 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) => getSessionUserId(request),
+ *   });
+ *
+ * That serves /api/one/authorize and /api/one/callback. Register
+ * `https://yourapp.com/api/one/callback` as the app's redirect URI.
+ */
+import type { OneConnect } from "./server";
+
+export interface OneConnectRoutesOptions {
+  /** The app's own id for the signed-in user, or null when nobody is
+   *  signed in. The grant is stored under this id. */
+  identifyUser: (request: Request) => Promise<string | null> | string | null;
+  /** Pre-fills the sign-in email on One's page for this user. */
+  loginHintFor?: (request: Request) => Promise<string | null> | string | null;
+  /** Where to send the browser when nobody is signed in. Answers 401
+   *  when omitted. */
+  signInUrl?: string;
+}
+
+export interface OneConnectRoutes {
+  GET: (request: Request) => Promise<Response>;
+}
+
+export const AUTHORIZE_ROUTE = "authorize";
+export const CALLBACK_ROUTE = "callback";
+
+function redirectWithCookies(
+  location: string,
+  setCookies: string[],
+): Response {
+  const headers = new Headers({ Location: location });
+  for (const cookie of setCookies) headers.append("Set-Cookie", cookie);
+  return new Response(null, { status: 302, headers });
+}
+
+function serializeCookie(
+  name: string,
+  value: string,
+  options: { httpOnly: boolean; secure: boolean; sameSite: "lax"; maxAge: number; path: string },
+): string {
+  const parts = [
+    `${name}=${encodeURIComponent(value)}`,
+    `Path=${options.path}`,
+    `Max-Age=${options.maxAge}`,
+    `SameSite=Lax`,
+  ];
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+function expireCookie(name: string, path: string): string {
+  return `${name}=; Path=${path}; Max-Age=0; SameSite=Lax; HttpOnly`;
+}
+
+export function readCookie(request: Request, name: string): string | undefined {
+  const header = request.headers.get("cookie");
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const [rawName, ...rest] = part.trim().split("=");
+    if (rawName === name) return decodeURIComponent(rest.join("="));
+  }
+  return undefined;
+}
+
+/** The last path segment names the leg: ".../authorize" or ".../callback". */
+export function routeFor(url: string): string {
+  const pathname = new URL(url).pathname.replace(/\/+$/, "");
+  return pathname.slice(pathname.lastIndexOf("/") + 1);
+}
+
+export function createOneConnectRoutes(
+  oneConnect: OneConnect,
+  options: OneConnectRoutesOptions,
+): OneConnectRoutes {
+  const cookiePath = (): string =>
+    oneConnect.startAuthorization().cookie.options.path;
+
+  const requireUser = async (request: Request): Promise<string | Response> => {
+    const userId = await options.identifyUser(request);
+    if (userId) return userId;
+    if (options.signInUrl)
+      return redirectWithCookies(new URL(options.signInUrl, request.url).toString(), []);
+    return new Response("Sign in to your account before connecting One.", {
+      status: 401,
+    });
+  };
+
+  const authorize = async (request: Request): Promise<Response> => {
+    const user = await requireUser(request);
+    if (user instanceof Response) return user;
+    const loginHint = (await options.loginHintFor?.(request)) ?? undefined;
+    const { redirectUrl, cookie } = oneConnect.startAuthorization({ loginHint });
+    return redirectWithCookies(redirectUrl, [
+      serializeCookie(cookie.name, cookie.value, cookie.options),
+    ]);
+  };
+
+  const callback = async (request: Request): Promise<Response> => {
+    const user = await requireUser(request);
+    if (user instanceof Response) return user;
+    const result = await oneConnect.completeAuthorization({
+      userId: user,
+      url: request.url,
+      getCookie: (name) => readCookie(request, name),
+    });
+    return redirectWithCookies(
+      result.redirectUrl,
+      result.clearCookieName
+        ? [expireCookie(result.clearCookieName, cookiePath())]
+        : [],
+    );
+  };
+
+  return {
+    GET: async (request: Request): Promise<Response> => {
+      const route = routeFor(request.url);
+      if (route === AUTHORIZE_ROUTE) return authorize(request);
+      if (route === CALLBACK_ROUTE) return callback(request);
+      return new Response("Not found", { status: 404 });
+    },
+  };
+}

package/src/node.ts

@@ -0,0 +1,107 @@
+/**
+ * `@withone/connect/node`: the two routes as handlers for Node's
+ * `http` request and response objects, which is what Express, Fastify
+ * (via `reply.raw`), Koa (via `ctx.req`/`ctx.res`) and plain
+ * `http.createServer` hand you.
+ *
+ *   import express from "express";
+ *   import { createOneConnectHandlers } from "@withone/connect/node";
+ *   import { oneConnect } from "./one";
+ *
+ *   const { authorize, callback } = createOneConnectHandlers(oneConnect, {
+ *     identifyUser: (request) => request.session?.userId ?? null,
+ *   });
+ *   app.get("/api/one/authorize", authorize);
+ *   app.get("/api/one/callback", callback);
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { createOneConnectRoutes, type OneConnectRoutesOptions } from "@withone/connect/next";
+import type { OneConnect } from "./server";
+
+export interface OneConnectNodeOptions {
+  /** The app's own id for the signed-in user, or null when nobody is
+   *  signed in. */
+  identifyUser: (
+    request: IncomingMessage,
+  ) => Promise<string | null> | string | null;
+  /** Pre-fills the sign-in email on One's page for this user. */
+  loginHintFor?: (
+    request: IncomingMessage,
+  ) => Promise<string | null> | string | null;
+  /** Where to send the browser when nobody is signed in. */
+  signInUrl?: string;
+}
+
+export type NodeHandler = (
+  request: IncomingMessage,
+  response: ServerResponse,
+) => Promise<void>;
+
+export interface OneConnectHandlers {
+  authorize: NodeHandler;
+  callback: NodeHandler;
+}
+
+/** The incoming request as a web Request, so both adapters share one
+ *  implementation. */
+function toWebRequest(request: IncomingMessage): Request {
+  const protocol =
+    request.headers["x-forwarded-proto"]?.toString().split(",")[0] ??
+    ((request.socket as { encrypted?: boolean }).encrypted ? "https" : "http");
+  const host = request.headers["x-forwarded-host"] ?? request.headers.host ?? "localhost";
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (typeof value === "string") headers.set(name, value);
+    else if (Array.isArray(value)) headers.set(name, value.join(", "));
+  }
+  return new Request(`${protocol}://${host}${request.url ?? "/"}`, {
+    method: request.method ?? "GET",
+    headers,
+  });
+}
+
+async function send(response: ServerResponse, web: Response): Promise<void> {
+  const setCookies =
+    typeof (web.headers as Headers & { getSetCookie?: () => string[] })
+      .getSetCookie === "function"
+      ? (web.headers as Headers & { getSetCookie: () => string[] }).getSetCookie()
+      : [];
+  web.headers.forEach((value, name) => {
+    if (name.toLowerCase() !== "set-cookie") response.setHeader(name, value);
+  });
+  if (setCookies.length > 0) response.setHeader("Set-Cookie", setCookies);
+  response.statusCode = web.status;
+  response.end(await web.text());
+}
+
+export function createOneConnectHandlers(
+  oneConnect: OneConnect,
+  options: OneConnectNodeOptions,
+): OneConnectHandlers {
+  // The web adapter receives a Request; the Node callbacks want the
+  // original IncomingMessage, so it is carried alongside by closure.
+  let current: IncomingMessage | null = null;
+  const routeOptions: OneConnectRoutesOptions = {
+    identifyUser: () => options.identifyUser(current as IncomingMessage),
+    loginHintFor: options.loginHintFor
+      ? () => options.loginHintFor!(current as IncomingMessage)
+      : undefined,
+    signInUrl: options.signInUrl,
+  };
+  const routes = createOneConnectRoutes(oneConnect, routeOptions);
+
+  const handle = async (
+    request: IncomingMessage,
+    response: ServerResponse,
+  ): Promise<void> => {
+    current = request;
+    try {
+      await send(response, await routes.GET(toWebRequest(request)));
+    } finally {
+      current = null;
+    }
+  };
+
+  return { authorize: handle, callback: handle };
+}

package/src/platforms.ts

@@ -0,0 +1,89 @@
+import { CONNECTOR_ASSETS_URL } from "./constants";
+import type {
+  ConnectButtonPlatform,
+  ConnectButtonPlatformInput,
+} from "./types";
+
+/** "Google Calendar" -> "google-calendar". */
+export function slugFromName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** "google-calendar" -> "Google Calendar". */
+export function nameFromSlug(slug: string): string {
+  return slug
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+/** One's logo for a connector slug. */
+export function logoUrlForSlug(slug: string): string {
+  return slug ? `${CONNECTOR_ASSETS_URL}/${slug}.svg` : "";
+}
+
+/**
+ * Turns whatever the developer passed into what the button draws. A bare
+ * string is a slug; an object may carry any of slug, name and imageUrl.
+ * Entries with neither a slug nor a name are dropped rather than drawn
+ * as an empty chip.
+ */
+export function normalizePlatform(
+  input: ConnectButtonPlatformInput,
+): ConnectButtonPlatform | null {
+  const raw = typeof input === "string" ? { slug: input } : input;
+  const slug = raw.slug?.trim()
+    ? slugFromName(raw.slug)
+    : raw.name?.trim()
+      ? slugFromName(raw.name)
+      : "";
+  if (!slug) return null;
+  return {
+    slug,
+    name: raw.name?.trim() || nameFromSlug(slug),
+    imageUrl: raw.imageUrl?.trim() || logoUrlForSlug(slug),
+  };
+}
+
+export function normalizePlatforms(
+  inputs: ConnectButtonPlatformInput[] | undefined,
+): ConnectButtonPlatform[] {
+  return (inputs ?? [])
+    .map(normalizePlatform)
+    .filter((p): p is ConnectButtonPlatform => p !== null);
+}
+
+/**
+ * The `platforms` attribute on <one-connect-button>: a comma list of
+ * slugs ("stripe, notion") or, for overrides, a JSON array of
+ * {slug, name, imageUrl} objects.
+ */
+export function parsePlatformsAttribute(
+  raw: string | null,
+): ConnectButtonPlatformInput[] {
+  const value = raw?.trim();
+  if (!value) return [];
+  if (value.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      return Array.isArray(parsed)
+        ? parsed.filter(
+            (entry): entry is ConnectButtonPlatformInput =>
+              typeof entry === "string" ||
+              (typeof entry === "object" && entry !== null),
+          )
+        : [];
+    } catch {
+      return [];
+    }
+  }
+  return value
+    .split(",")
+    .map((slug) => slug.trim())
+    .filter(Boolean);
+}

package/src/react.ts

@@ -1,39 +1,22 @@
 /**
- * React wrapper — `import { ConnectButton } from "@withone/connect/react"`.
+ * React: `import { ConnectButton } from "@withone/connect/react"`.
  *
- * A real component over the framework-agnostic core, so React apps get
- * idiomatic props (arrays, functions) instead of the custom element's
- * string attributes. React is a peer dependency of THIS subpath only;
- * the core package stays dependency-free for every other framework.
+ * 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.
  */
 import { createElement, useEffect, useRef } from "react";
 import type { CSSProperties, ReactElement } from "react";
 
-import { mountConnectButton } from "./button";
-import type {
-  ConnectButtonHandle,
-  ConnectButtonPlatform,
-  ConnectButtonOptions,
-} from "./types";
+import {
+  mountConnectButton,
+  optionsFromProps,
+  propsIdentity,
+  type ConnectButtonHandle,
+  type ConnectButtonProps as ConnectButtonCoreProps,
+} from "@withone/connect";
 
-export interface ConnectButtonProps {
-  /** The app's own backend authorize route ("/api/one/authorize" is
-   *  fine — relative resolves against the page). */
-  authorizeUrl: string;
-  /** Theme for One's hosted page (rides the URL fragment). */
-  appTheme?: "light" | "dark";
-  onSuccess?: () => void;
-  onError?: (error: string) => void;
-  onClose?: () => void;
-  label?: string;
-  variant?: "default" | "accent" | "block";
-  /** Matches the host page, not One's card. */
-  theme?: "light" | "dark";
-  platforms?: ConnectButtonPlatform[];
-  moreCount?: number;
-  description?: string;
-  accentColor?: string;
-  connectedLabel?: string;
+export interface ConnectButtonProps extends ConnectButtonCoreProps {
   className?: string;
   style?: CSSProperties;
 }
@@ -46,54 +29,28 @@ export function ConnectButton(props: ConnectButtonProps): ReactElement {
   const callbacksRef = useRef({
     onSuccess: props.onSuccess,
     onError: props.onError,
-    onClose: props.onClose,
   });
-  callbacksRef.current = {
-    onSuccess: props.onSuccess,
-    onError: props.onError,
-    onClose: props.onClose,
-  };
+  callbacksRef.current = { onSuccess: props.onSuccess, onError: props.onError };
 
-  const platformsKey = JSON.stringify(props.platforms ?? []);
+  const identity = propsIdentity(props);
 
   useEffect(() => {
     if (!containerRef.current) return;
-    const options: ConnectButtonOptions = {
-      connect: {
-        authorize: { url: props.authorizeUrl },
-        appTheme: props.appTheme,
+    handleRef.current = mountConnectButton(
+      containerRef.current,
+      optionsFromProps(props, {
         onSuccess: () => callbacksRef.current.onSuccess?.(),
-        onError: (error) => callbacksRef.current.onError?.(error),
-        onClose: () => callbacksRef.current.onClose?.(),
-      },
-      label: props.label,
-      variant: props.variant,
-      theme: props.theme,
-      platforms: props.platforms,
-      moreCount: props.moreCount,
-      description: props.description,
-      accentColor: props.accentColor,
-      connectedLabel: props.connectedLabel,
-    };
-    handleRef.current = mountConnectButton(containerRef.current, options);
+        onError: (message) => callbacksRef.current.onError?.(message),
+      }),
+    );
     return () => {
       handleRef.current?.destroy();
       handleRef.current = null;
     };
-    // Remount only when the visual/config inputs actually change.
+    // Remount only when a visual or config input changes; `identity`
+    // captures exactly those.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    props.authorizeUrl,
-    props.appTheme,
-    props.label,
-    props.variant,
-    props.theme,
-    platformsKey,
-    props.moreCount,
-    props.description,
-    props.accentColor,
-    props.connectedLabel,
-  ]);
+  }, [identity]);
 
   return createElement("div", {
     ref: containerRef,

package/src/return.ts

@@ -0,0 +1,30 @@
+import { RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "./constants";
+import type { OneConnectReturn } from "./types";
+
+/** Reads the outcome the callback route put on the return 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 };
+}
+
+/** The same URL without the return params, so a refresh does not
+ *  re-fire the callbacks. */
+export function stripReturnParams(location: {
+  pathname: string;
+  search: string;
+  hash: string;
+}): string {
+  const params = new URLSearchParams(location.search);
+  params.delete(RETURN_STATUS_PARAM);
+  params.delete(RETURN_MESSAGE_PARAM);
+  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);
+}