@withone/connect 0.11.0 → 0.12.1

package/src/types.ts

@@ -10,35 +10,60 @@
 /** Theme of One's hosted connect page. */
 export type OneConnectTheme = "light" | "dark";
 
-export interface OneConnectOptions {
+/** Theme of the button: fixed, or following the visitor's setting. */
+export type ConnectButtonTheme = "light" | "dark" | "auto";
+
+/**
+ * Why a flow ended without a grant. The callback route puts only this
+ * code on the return URL; the text shown for it is fixed in the SDK, so
+ * a crafted link can never put its own words in front of the user.
+ *
+ * - `declined`: the user cancelled on One's page.
+ * - `expired`: the attempt took too long or was started elsewhere.
+ * - `failed`: One could not complete the connection.
+ */
+export type ConnectFailureCode = "declined" | "expired" | "failed";
+
+export interface OneConnectFlowOptions {
   /** The app's own backend authorize route. Relative paths such as
    *  "/api/one/authorize" resolve against the page's origin. */
   authorizeUrl: string;
   /** Theme for One's hosted page. Carried on the URL fragment, which
    *  survives the redirect chain, so the backend forwards nothing. */
+  connectTheme?: OneConnectTheme;
+  /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
   appTheme?: OneConnectTheme;
-  /** The grant completed and the backend stored the tokens. */
+  /** The grant completed and the backend stored the tokens. Fires once
+   *  per page load, on the first flow still mounted when the tab
+   *  returns. Treat it as a hint to refetch: your server is the truth. */
   onSuccess?: () => void;
-  /** The flow ended without a grant: the user declined, the attempt
-   *  expired, or the exchange failed. `message` is safe to show. */
-  onError?: (message: string) => void;
+  /** The flow ended without a grant. `message` is fixed text for
+   *  `code`, safe to show. */
+  onError?: (message: string, code: ConnectFailureCode) => void;
+  /** The user came back with the browser's Back button before finishing
+   *  (the page was restored from the back-forward cache). */
+  onCancel?: () => void;
 }
 
-export interface OneConnectHandle {
+export interface OneConnectFlow {
   /** Navigates the tab to One's hosted connect flow. */
   open: () => void;
+  /** Swaps the options (callbacks, theme) without losing the flow. */
+  update: (options: OneConnectFlowOptions) => void;
+  /** Stops listening: callbacks no longer fire for this flow. */
+  destroy: () => void;
 }
 
-/** How the app's callback route reports the outcome on its final
- *  redirect, read off the page URL when the tab returns. */
+/** How the flow ended, read off the page URL when the tab returns. */
 export interface OneConnectReturn {
   status: "success" | "error";
+  code?: ConnectFailureCode;
   message?: string;
 }
 
 /**
  * A connector chip on the button. Pass One's connector slug ("stripe",
- * "google-calendar") and the SDK shows the logo and the name; pass an
+ * "google-calendar") and the SDK shows its logo and name; pass an
  * object to override either.
  */
 export type ConnectButtonPlatformInput =
@@ -52,33 +77,52 @@ export interface ConnectButtonPlatform {
 }
 
 export type ConnectButtonVariant = "default" | "accent" | "block";
+export type ConnectButtonSize = "sm" | "md" | "lg";
 export type ConnectButtonState = "idle" | "connecting" | "connected";
 
-export interface ConnectButtonOptions {
-  /** Everything the flow needs; the button wires open() and the
-   *  Connecting and Connected states around your callbacks. */
-  connect: OneConnectOptions;
-  /** "Connect your apps" unless overridden. */
-  label?: string;
-  /** default = neutral pill; accent = brand-colored pill; block =
-   *  full-width card with a description and a "Secured by One" foot. */
-  variant?: ConnectButtonVariant;
-  /** Matches the host page, not One's page (that is connect.appTheme). */
-  theme?: OneConnectTheme;
-  /** Connector chips. The first three render; the rest fold into a "+N"
-   *  chip, so that count only ever describes this list. */
+/** One prop shape for every surface: React, Vue, Svelte, the custom
+ *  element and `mountConnectButton`. */
+export interface ConnectButtonProps {
+  /** The app's own backend authorize route; relative is fine. */
+  authorizeUrl: string;
+  /** Connector slugs, or objects that override the name or the logo.
+   *  The first three draw as logos; the rest fold into a "+N" chip. */
   platforms?: ConnectButtonPlatformInput[];
-  /** Sub-line on the block variant, shown while idle. */
-  description?: string;
-  /** Fill of the accent variant; One's lime when omitted. */
+  /** Whether this user has a live grant, from your server. When set, it
+   *  decides the Connected state. When omitted, the button shows
+   *  Connected only right after a successful return. */
+  connected?: boolean;
+  /** Not clickable, for example until terms are accepted. */
+  disabled?: boolean;
+  /** default = neutral, accent = your brand colour, block = a card with
+   *  a description and a "Secured by One" foot. */
+  variant?: ConnectButtonVariant;
+  size?: ConnectButtonSize;
+  /** Stretches to the width of its container. */
+  fullWidth?: boolean;
+  /** Matches the host page. "auto" follows the visitor's setting. */
+  theme?: ConnectButtonTheme;
+  /** Theme of One's hosted page. */
+  connectTheme?: OneConnectTheme;
+  /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
+  appTheme?: OneConnectTheme;
+  /** Fill of the accent variant; One's lime when omitted. The label is
+   *  black or white, whichever reads better on it. */
   accentColor?: string;
-  /** Label for the connected state. */
+  /** "Connect your apps" unless set. */
+  label?: string;
+  /** "Connected" unless set. */
   connectedLabel?: string;
+  /** Sub-line on the block variant. */
+  description?: string;
+  onSuccess?: () => void;
+  onError?: (message: string, code: ConnectFailureCode) => void;
+  onCancel?: () => void;
 }
 
 export interface ConnectButtonHandle {
-  /** Override the visual state by hand. */
-  setState: (state: ConnectButtonState) => void;
-  /** Remove the button. */
+  /** Applies new props in place, keeping the button's state. */
+  update: (props: ConnectButtonProps) => void;
+  /** Removes the button and stops its callbacks. */
   destroy: () => void;
 }

package/src/vue.ts

@@ -4,6 +4,7 @@
  *   <ConnectButton
  *     authorize-url="/api/one/authorize"
  *     :platforms="['stripe', 'notion']"
+ *     :connected="user.hasOneGrant"
  *     @success="onConnected"
  *   />
  *
@@ -20,65 +21,87 @@ import {
 import type { PropType } from "vue";
 
 import {
-  mountConnectButton,
-  optionsFromProps,
-  propsIdentity,
+  renderConnectButton,
   type ConnectButtonHandle,
   type ConnectButtonPlatformInput,
+  type ConnectButtonProps,
+  type ConnectButtonSize,
+  type ConnectButtonTheme,
   type ConnectButtonVariant,
+  type ConnectFailureCode,
   type OneConnectTheme,
 } from "@withone/connect";
 
+/** Booleans default to undefined, not false, so "not set" stays
+ *  distinguishable from "false" (it matters for `connected`). */
+const optionalBoolean = { type: Boolean, default: undefined };
+
 export const ConnectButton = defineComponent({
   name: "OneConnectButton",
   props: {
     authorizeUrl: { type: String, required: true },
-    appTheme: { type: String as PropType<OneConnectTheme>, default: undefined },
-    label: { type: String, default: undefined },
+    platforms: {
+      type: Array as PropType<ConnectButtonPlatformInput[]>,
+      default: undefined,
+    },
+    connected: optionalBoolean,
+    disabled: optionalBoolean,
     variant: {
       type: String as PropType<ConnectButtonVariant>,
       default: undefined,
     },
-    theme: { type: String as PropType<OneConnectTheme>, default: undefined },
-    platforms: {
-      type: Array as PropType<ConnectButtonPlatformInput[]>,
+    size: { type: String as PropType<ConnectButtonSize>, default: undefined },
+    fullWidth: optionalBoolean,
+    theme: { type: String as PropType<ConnectButtonTheme>, default: undefined },
+    connectTheme: {
+      type: String as PropType<OneConnectTheme>,
       default: undefined,
     },
-    description: { type: String, default: undefined },
+    /** @deprecated use connectTheme */
+    appTheme: { type: String as PropType<OneConnectTheme>, default: undefined },
     accentColor: { type: String, default: undefined },
+    label: { type: String, default: undefined },
     connectedLabel: { type: String, default: undefined },
+    description: { type: String, default: undefined },
   },
   emits: {
     success: () => true,
-    error: (message: string) => typeof message === "string",
+    error: (message: string, code: ConnectFailureCode) =>
+      typeof message === "string" && typeof code === "string",
+    cancel: () => true,
   },
   setup(props, { emit }) {
-    const container = ref<HTMLElement | null>(null);
+    const host = ref<HTMLElement | null>(null);
     let handle: ConnectButtonHandle | null = null;
 
-    const mount = () => {
-      handle?.destroy();
-      handle = null;
-      if (!container.value) return;
-      handle = mountConnectButton(
-        container.value,
-        optionsFromProps(
-          { ...props },
-          {
-            onSuccess: () => emit("success"),
-            onError: (message) => emit("error", message),
-          },
-        ),
-      );
-    };
+    const current = (): ConnectButtonProps => ({
+      ...props,
+      onSuccess: () => emit("success"),
+      onError: (message, code) => emit("error", message, code),
+      onCancel: () => emit("cancel"),
+    });
 
-    onMounted(mount);
-    watch(() => propsIdentity({ ...props }), mount);
+    onMounted(() => {
+      if (host.value) handle = renderConnectButton(host.value, current());
+    });
+    watch(
+      () => ({ ...props }),
+      () => handle?.update(current()),
+      { deep: true },
+    );
     onBeforeUnmount(() => {
       handle?.destroy();
       handle = null;
     });
 
-    return () => h("div", { ref: container });
+    // The host carries its layout attributes from the render, so server
+    // and client HTML agree; the button lives in its shadow root.
+    return () =>
+      h("span", {
+        ref: host,
+        class: "one-connect",
+        "data-variant": props.variant ?? "default",
+        "data-full-width": props.fullWidth ? "" : undefined,
+      });
   },
 });

package/dist/useOneConnect.d.ts

@@ -1,13 +0,0 @@
-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/wrapper-options.d.ts

@@ -1,28 +0,0 @@
-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;
-    /** Theme of One's hosted page. */
-    appTheme?: OneConnectTheme;
-    onSuccess?: () => void;
-    onError?: (message: string) => void;
-    label?: string;
-    variant?: ConnectButtonVariant;
-    /** Matches the host page. */
-    theme?: OneConnectTheme;
-    /** Connector slugs, or objects to override name or logo. */
-    platforms?: ConnectButtonPlatformInput[];
-    description?: string;
-    accentColor?: string;
-    connectedLabel?: string;
-}
-export interface ConnectButtonCallbacks {
-    onSuccess?: () => void;
-    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/src/useOneConnect.ts

@@ -1,72 +0,0 @@
-import { THEME_PARAM } from "./constants";
-import { hasReturnParams, parseReturn, stripReturnParams } from "./return";
-import type { OneConnectHandle, OneConnectOptions } from "./types";
-
-/** The return leg is a page load, so it is delivered exactly once, to
- *  the first instance that reads it. */
-let returnConsumed = false;
-
-const DEFAULT_ERROR = "The connection was not completed.";
-
-/**
- * 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 const useOneConnect = (options: OneConnectOptions): OneConnectHandle => {
-  const buildAuthorizeUrl = (): string => {
-    try {
-      const url = new URL(
-        options.authorizeUrl,
-        typeof window === "undefined" ? undefined : window.location.origin,
-      );
-      if (options.appTheme) url.hash = `${THEME_PARAM}=${options.appTheme}`;
-      return url.toString();
-    } catch {
-      return options.authorizeUrl;
-    }
-  };
-
-  const open = () => {
-    if (typeof window === "undefined") return;
-    window.location.assign(buildAuthorizeUrl());
-  };
-
-  if (typeof window !== "undefined" && !returnConsumed) {
-    const outcome = parseReturn(window.location.search);
-    if (outcome) {
-      returnConsumed = true;
-      // Frameworks that manage the history themselves (the Next.js App
-      // Router) sync the address bar back to their own URL when hydration
-      // completes, undoing a single replaceState. Scrub now and re-check a
-      // few beats later.
-      const scrub = () => {
-        if (!hasReturnParams(window.location.search)) return;
-        window.history.replaceState(
-          null,
-          "",
-          stripReturnParams(window.location),
-        );
-      };
-      scrub();
-      for (const delay of [50, 500, 2000]) window.setTimeout(scrub, delay);
-
-      window.setTimeout(() => {
-        try {
-          if (outcome.status === "success") options.onSuccess?.();
-          else options.onError?.(outcome.message ?? DEFAULT_ERROR);
-        } catch {
-          /* the app's own callback threw; not ours to handle */
-        }
-      }, 0);
-    }
-  }
-
-  return { open };
-};

package/src/wrapper-options.ts

@@ -1,68 +0,0 @@
-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;
-  /** Theme of One's hosted page. */
-  appTheme?: OneConnectTheme;
-  onSuccess?: () => void;
-  onError?: (message: string) => void;
-  label?: string;
-  variant?: ConnectButtonVariant;
-  /** Matches the host page. */
-  theme?: OneConnectTheme;
-  /** Connector slugs, or objects to override name or logo. */
-  platforms?: ConnectButtonPlatformInput[];
-  description?: string;
-  accentColor?: string;
-  connectedLabel?: string;
-}
-
-export interface ConnectButtonCallbacks {
-  onSuccess?: () => void;
-  onError?: (message: string) => void;
-}
-
-export function optionsFromProps(
-  props: ConnectButtonProps,
-  callbacks: ConnectButtonCallbacks = props,
-): ConnectButtonOptions {
-  return {
-    connect: {
-      authorizeUrl: props.authorizeUrl,
-      appTheme: props.appTheme,
-      onSuccess: () => callbacks.onSuccess?.(),
-      onError: (message) => callbacks.onError?.(message),
-    },
-    label: props.label,
-    variant: props.variant,
-    theme: props.theme,
-    platforms: props.platforms,
-    description: props.description,
-    accentColor: props.accentColor,
-    connectedLabel: props.connectedLabel,
-  };
-}
-
-/** The inputs whose change should remount the button. */
-export function propsIdentity(props: ConnectButtonProps): string {
-  return JSON.stringify([
-    props.authorizeUrl,
-    props.appTheme,
-    props.label,
-    props.variant,
-    props.theme,
-    props.platforms ?? [],
-    props.description,
-    props.accentColor,
-    props.connectedLabel,
-  ]);
-}