@touchque/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] — 2026-08-27
+
+Initial release.
+
+### Added
+- `useTouchQuePasskey(config)` — a hook over `@touchque/web` that memoizes one
+  client and tracks `status` (`idle` | `pending` | `success` | `stepup` |
+  `pending2fa` | `error`), `error` and `result`. Exposes `authenticate`,
+  `register`, `list`, `remove`, `reset` and `isSupported`.
+- `<PasskeyButton config email onSuccess onStepUp onPending2fa onError />` —
+  a button that runs the passwordless-primary flow and routes the outcome to
+  callbacks; `disabled` + `data-loading` while the ceremony runs;
+  `hideWhenUnsupported` to render nothing when WebAuthn is unavailable.
+- Re-exports `PasskeyDismissedError` / `PasskeyNotRegisteredError` /
+  `PasskeyDisabledError` from `@touchque/web`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TouchQue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @touchque/react
+
+React bindings for [`@touchque/web`](https://www.npmjs.com/package/@touchque/web) —
+a passkey sign-in hook and a drop-in button.
+
+```bash
+npm install @touchque/react @touchque/web react
+```
+
+```tsx
+import { PasskeyButton } from '@touchque/react';
+
+const config = { baseUrl: 'https://api.example.com' }; // your relay backend
+
+<PasskeyButton
+  config={config}
+  email={email}
+  onSuccess={(r) => (window.location.href = r.raw.redirect_url as string)}
+  onStepUp={() => startPushFlow()}
+  onError={(e) => setError(e.message)}
+/>;
+```
+
+Or drive it yourself with the hook:
+
+```tsx
+import { useTouchQuePasskey } from '@touchque/react';
+
+const pk = useTouchQuePasskey(config);
+// pk.status: 'idle' | 'pending' | 'success' | 'stepup' | 'pending2fa' | 'error'
+
+<button disabled={!pk.isSupported || pk.status === 'pending'} onClick={() => pk.authenticate(email)}>
+  Sign in with a passkey
+</button>;
+```
+
+Full documentation is in the repo.

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import { AuthenticateResult, RegisterResult, PasskeySummary, TouchQueWebConfig } from '@touchque/web';
+export { PasskeyDisabledError, PasskeyDismissedError, PasskeyNotRegisteredError } from '@touchque/web';
+import * as react from 'react';
+
+type PasskeyStatus = 'idle' | 'pending' | 'success' | 'stepup' | 'pending2fa' | 'error';
+interface UseTouchQuePasskey {
+    /** `true` if this browser exposes the WebAuthn API. */
+    isSupported: boolean;
+    /** Current state of the last `authenticate()` call. */
+    status: PasskeyStatus;
+    /** The last error, or `null`. */
+    error: Error | null;
+    /** The last `authenticate()` result, or `null`. */
+    result: AuthenticateResult | null;
+    /** Passwordless-primary sign-in. Updates `status` / `error` / `result`. */
+    authenticate: (email: string, context?: Record<string, unknown>) => Promise<AuthenticateResult>;
+    /** Register a passkey for the signed-in user. */
+    register: (extra?: Record<string, unknown>) => Promise<RegisterResult>;
+    /** List the signed-in user's passkeys. */
+    list: () => Promise<PasskeySummary[]>;
+    /** Remove one of the signed-in user's passkeys. */
+    remove: (id: string) => Promise<{
+        deleted: boolean;
+    }>;
+    /** Reset `status` / `error` / `result` to their initial values. */
+    reset: () => void;
+}
+
+/**
+ * React hook over `@touchque/web`. Memoizes one client for the given config
+ * and tracks the state of the passkey sign-in flow.
+ *
+ * ```tsx
+ * const pk = useTouchQuePasskey({ baseUrl: 'https://api.example.com' });
+ * <button disabled={!pk.isSupported} onClick={() => pk.authenticate(email)}>
+ *   Sign in with a passkey
+ * </button>
+ * ```
+ */
+declare function useTouchQuePasskey(config: TouchQueWebConfig): UseTouchQuePasskey;
+
+interface PasskeyButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onError' | 'children'> {
+    /** `@touchque/web` config (`baseUrl`, `paths?`, `credentials?`, …). */
+    config: TouchQueWebConfig;
+    /** The account to sign in. */
+    email: string;
+    /** Called when the passkey assertion signed the user in. */
+    onSuccess?: (result: AuthenticateResult) => void;
+    /** Called when risk/policy wants a second factor (push / number match). */
+    onStepUp?: (result: AuthenticateResult) => void;
+    /** Called when the relay wants the caller to continue a pending 2FA flow. */
+    onPending2fa?: (result: AuthenticateResult) => void;
+    /** Called on any error (dismissed prompt, no passkey, disabled, network). */
+    onError?: (error: Error) => void;
+    /** Hide the button entirely when WebAuthn is unavailable. Default: false. */
+    hideWhenUnsupported?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * A button that runs the passwordless-primary passkey sign-in and routes the
+ * outcome to `onSuccess` / `onStepUp` / `onPending2fa` / `onError`. While the
+ * ceremony is running the button is `disabled` and `data-loading` is set.
+ */
+declare function PasskeyButton({ config, email, onSuccess, onStepUp, onPending2fa, onError, hideWhenUnsupported, children, disabled, onClick, ...buttonProps }: PasskeyButtonProps): react.JSX.Element | null;
+
+export { PasskeyButton, type PasskeyButtonProps, type PasskeyStatus, type UseTouchQuePasskey, useTouchQuePasskey };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { AuthenticateResult, RegisterResult, PasskeySummary, TouchQueWebConfig } from '@touchque/web';
+export { PasskeyDisabledError, PasskeyDismissedError, PasskeyNotRegisteredError } from '@touchque/web';
+import * as react from 'react';
+
+type PasskeyStatus = 'idle' | 'pending' | 'success' | 'stepup' | 'pending2fa' | 'error';
+interface UseTouchQuePasskey {
+    /** `true` if this browser exposes the WebAuthn API. */
+    isSupported: boolean;
+    /** Current state of the last `authenticate()` call. */
+    status: PasskeyStatus;
+    /** The last error, or `null`. */
+    error: Error | null;
+    /** The last `authenticate()` result, or `null`. */
+    result: AuthenticateResult | null;
+    /** Passwordless-primary sign-in. Updates `status` / `error` / `result`. */
+    authenticate: (email: string, context?: Record<string, unknown>) => Promise<AuthenticateResult>;
+    /** Register a passkey for the signed-in user. */
+    register: (extra?: Record<string, unknown>) => Promise<RegisterResult>;
+    /** List the signed-in user's passkeys. */
+    list: () => Promise<PasskeySummary[]>;
+    /** Remove one of the signed-in user's passkeys. */
+    remove: (id: string) => Promise<{
+        deleted: boolean;
+    }>;
+    /** Reset `status` / `error` / `result` to their initial values. */
+    reset: () => void;
+}
+
+/**
+ * React hook over `@touchque/web`. Memoizes one client for the given config
+ * and tracks the state of the passkey sign-in flow.
+ *
+ * ```tsx
+ * const pk = useTouchQuePasskey({ baseUrl: 'https://api.example.com' });
+ * <button disabled={!pk.isSupported} onClick={() => pk.authenticate(email)}>
+ *   Sign in with a passkey
+ * </button>
+ * ```
+ */
+declare function useTouchQuePasskey(config: TouchQueWebConfig): UseTouchQuePasskey;
+
+interface PasskeyButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onError' | 'children'> {
+    /** `@touchque/web` config (`baseUrl`, `paths?`, `credentials?`, …). */
+    config: TouchQueWebConfig;
+    /** The account to sign in. */
+    email: string;
+    /** Called when the passkey assertion signed the user in. */
+    onSuccess?: (result: AuthenticateResult) => void;
+    /** Called when risk/policy wants a second factor (push / number match). */
+    onStepUp?: (result: AuthenticateResult) => void;
+    /** Called when the relay wants the caller to continue a pending 2FA flow. */
+    onPending2fa?: (result: AuthenticateResult) => void;
+    /** Called on any error (dismissed prompt, no passkey, disabled, network). */
+    onError?: (error: Error) => void;
+    /** Hide the button entirely when WebAuthn is unavailable. Default: false. */
+    hideWhenUnsupported?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * A button that runs the passwordless-primary passkey sign-in and routes the
+ * outcome to `onSuccess` / `onStepUp` / `onPending2fa` / `onError`. While the
+ * ceremony is running the button is `disabled` and `data-loading` is set.
+ */
+declare function PasskeyButton({ config, email, onSuccess, onStepUp, onPending2fa, onError, hideWhenUnsupported, children, disabled, onClick, ...buttonProps }: PasskeyButtonProps): react.JSX.Element | null;
+
+export { PasskeyButton, type PasskeyButtonProps, type PasskeyStatus, type UseTouchQuePasskey, useTouchQuePasskey };

package/dist/index.js

@@ -0,0 +1,114 @@
+'use strict';
+
+var react = require('react');
+var web = require('@touchque/web');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/useTouchQuePasskey.ts
+function classify(res) {
+  if (res.ok) return "success";
+  if (res.requiresStepUp) return "stepup";
+  if (res.pending2fa) return "pending2fa";
+  return "error";
+}
+function useTouchQuePasskey(config) {
+  const client = react.useMemo(
+    () => web.createTouchQueWeb(config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [config.baseUrl, config.credentials, JSON.stringify(config.paths ?? {})]
+  );
+  const [status, setStatus] = react.useState("idle");
+  const [error, setError] = react.useState(null);
+  const [result, setResult] = react.useState(null);
+  const inFlight = react.useRef(false);
+  const isSupported = react.useMemo(() => web.isPasskeySupported(), []);
+  const authenticate = react.useCallback(
+    async (email, context) => {
+      if (inFlight.current) throw new Error("A passkey sign-in is already in progress.");
+      inFlight.current = true;
+      setStatus("pending");
+      setError(null);
+      try {
+        const res = await client.passkeys.authenticate({ email, context });
+        setResult(res);
+        setStatus(classify(res));
+        return res;
+      } catch (e) {
+        setError(e);
+        setStatus("error");
+        throw e;
+      } finally {
+        inFlight.current = false;
+      }
+    },
+    [client]
+  );
+  const register = react.useCallback(
+    (extra) => client.passkeys.register(extra),
+    [client]
+  );
+  const list = react.useCallback(() => client.passkeys.list(), [client]);
+  const remove = react.useCallback((id) => client.passkeys.remove(id), [client]);
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setResult(null);
+  }, []);
+  return { isSupported, status, error, result, authenticate, register, list, remove, reset };
+}
+function PasskeyButton({
+  config,
+  email,
+  onSuccess,
+  onStepUp,
+  onPending2fa,
+  onError,
+  hideWhenUnsupported = false,
+  children,
+  disabled,
+  onClick,
+  ...buttonProps
+}) {
+  const pk = useTouchQuePasskey(config);
+  if (hideWhenUnsupported && !pk.isSupported) return null;
+  const busy = pk.status === "pending";
+  const handleClick = async (e) => {
+    onClick?.(e);
+    if (e.defaultPrevented || busy) return;
+    try {
+      const res = await pk.authenticate(email);
+      if (res.ok) onSuccess?.(res);
+      else if (res.requiresStepUp) onStepUp?.(res);
+      else if (res.pending2fa) onPending2fa?.(res);
+      else onError?.(new Error("Passkey sign-in did not complete."));
+    } catch (err) {
+      onError?.(err);
+    }
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      ...buttonProps,
+      disabled: disabled || busy || !pk.isSupported,
+      "data-loading": busy ? "" : void 0,
+      onClick: handleClick,
+      children: children ?? "Sign in with a passkey"
+    }
+  );
+}
+
+Object.defineProperty(exports, "PasskeyDisabledError", {
+  enumerable: true,
+  get: function () { return web.PasskeyDisabledError; }
+});
+Object.defineProperty(exports, "PasskeyDismissedError", {
+  enumerable: true,
+  get: function () { return web.PasskeyDismissedError; }
+});
+Object.defineProperty(exports, "PasskeyNotRegisteredError", {
+  enumerable: true,
+  get: function () { return web.PasskeyNotRegisteredError; }
+});
+exports.PasskeyButton = PasskeyButton;
+exports.useTouchQuePasskey = useTouchQuePasskey;

package/dist/index.mjs

@@ -0,0 +1,100 @@
+import { useMemo, useState, useRef, useCallback } from 'react';
+import { createTouchQueWeb, isPasskeySupported } from '@touchque/web';
+export { PasskeyDisabledError, PasskeyDismissedError, PasskeyNotRegisteredError } from '@touchque/web';
+import { jsx } from 'react/jsx-runtime';
+
+// src/useTouchQuePasskey.ts
+function classify(res) {
+  if (res.ok) return "success";
+  if (res.requiresStepUp) return "stepup";
+  if (res.pending2fa) return "pending2fa";
+  return "error";
+}
+function useTouchQuePasskey(config) {
+  const client = useMemo(
+    () => createTouchQueWeb(config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [config.baseUrl, config.credentials, JSON.stringify(config.paths ?? {})]
+  );
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [result, setResult] = useState(null);
+  const inFlight = useRef(false);
+  const isSupported = useMemo(() => isPasskeySupported(), []);
+  const authenticate = useCallback(
+    async (email, context) => {
+      if (inFlight.current) throw new Error("A passkey sign-in is already in progress.");
+      inFlight.current = true;
+      setStatus("pending");
+      setError(null);
+      try {
+        const res = await client.passkeys.authenticate({ email, context });
+        setResult(res);
+        setStatus(classify(res));
+        return res;
+      } catch (e) {
+        setError(e);
+        setStatus("error");
+        throw e;
+      } finally {
+        inFlight.current = false;
+      }
+    },
+    [client]
+  );
+  const register = useCallback(
+    (extra) => client.passkeys.register(extra),
+    [client]
+  );
+  const list = useCallback(() => client.passkeys.list(), [client]);
+  const remove = useCallback((id) => client.passkeys.remove(id), [client]);
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setResult(null);
+  }, []);
+  return { isSupported, status, error, result, authenticate, register, list, remove, reset };
+}
+function PasskeyButton({
+  config,
+  email,
+  onSuccess,
+  onStepUp,
+  onPending2fa,
+  onError,
+  hideWhenUnsupported = false,
+  children,
+  disabled,
+  onClick,
+  ...buttonProps
+}) {
+  const pk = useTouchQuePasskey(config);
+  if (hideWhenUnsupported && !pk.isSupported) return null;
+  const busy = pk.status === "pending";
+  const handleClick = async (e) => {
+    onClick?.(e);
+    if (e.defaultPrevented || busy) return;
+    try {
+      const res = await pk.authenticate(email);
+      if (res.ok) onSuccess?.(res);
+      else if (res.requiresStepUp) onStepUp?.(res);
+      else if (res.pending2fa) onPending2fa?.(res);
+      else onError?.(new Error("Passkey sign-in did not complete."));
+    } catch (err) {
+      onError?.(err);
+    }
+  };
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      ...buttonProps,
+      disabled: disabled || busy || !pk.isSupported,
+      "data-loading": busy ? "" : void 0,
+      onClick: handleClick,
+      children: children ?? "Sign in with a passkey"
+    }
+  );
+}
+
+export { PasskeyButton, useTouchQuePasskey };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@touchque/react",
+  "version": "0.1.0",
+  "description": "React bindings for @touchque/web — passkey sign-in hook and button",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Touchque/touchque-sdks",
+    "directory": "touchque-react"
+  },
+  "homepage": "https://touchque.com",
+  "license": "MIT",
+  "author": "TouchQue",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "touchque",
+    "passkey",
+    "webauthn",
+    "passwordless",
+    "react",
+    "hooks"
+  ],
+  "peerDependencies": {
+    "@touchque/web": "^0.1.0",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@touchque/web": "file:../touchque-web",
+    "@types/react": "^18.3.12",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}