SDK Reference

@kyqu/client v0.2.0

Zero-dependency JavaScript/TypeScript client for the Kyqu auth platform.

Installation

npm install @kyqu/client

Exports

import { KyquClient, KyquError } from "@kyqu/client";

KyquError

class KyquError extends Error {
  name: "KyquError";
  status: number;           // HTTP status code
  data: Record<string, any>; // Full response body
}

KyquClient

Constructor

new KyquClient(options: KyquClientOptions)

KyquClientOptions

Property	Type	Required	Description
baseUrl	string	Yes	Root URL of Kyqu API
projectId	string	Yes	Project UUID from dashboard
publicKey	string	Yes	Public key (pk_...) from dashboard

Methods (32 total)

getFields()

Returns custom field definitions for building dynamic signup forms.

Returns: Promise<KyquFieldDef[]>

signup(input)

Registers a new user. Custom field values as top-level keys.

Input: { email: string, password: string, name?: string, [key: string]: any } Returns: Promise<KyquSignupResult>

login(input)

Authenticates a user. Include totpCode or backupCode for 2FA.

Input: { email: string, password: string, totpCode?: string, backupCode?: string } Returns: Promise<KyquLoginResult> Throws: KyquError with message: "TOTP_REQUIRED" (status 403) when 2FA is enabled and no code supplied.

logout(token)

Revokes the given bearer token.

Returns: Promise<{ ok: boolean }>

getUser(token)

Returns the user associated with the session token.

Returns: Promise<KyquUser>

updateMetadata(token, metadata)

Update custom metadata fields for the authenticated user.

Input: token (bearer), metadata key-value object Returns: Promise<{ user: KyquUser }>

requestEmailVerification(email)

Sends verification email.

Returns: Promise<{ ok: boolean }>

confirmEmailVerification(token)

Confirms verification token.

Returns: Promise<{ user: KyquUser }>

requestPasswordReset(email)

Initiates password reset.

Returns: Promise<{ ok: boolean }>

confirmPasswordReset(input)

Confirms reset with token and new password.

Input: { token: string, password: string } Returns: Promise<{ user: KyquUser, session: KyquSession }>

changePassword(token, input)

Changes password for the authenticated user.

Input: token (bearer), { currentPassword: string, newPassword: string } Returns: Promise<{ ok: boolean }> Note: Revokes all other active sessions on success.

deleteAccount(token, input)

Permanently deletes the authenticated user's account. Requires password confirmation for security.

Input: token (bearer), { password: string } Returns: Promise<{ ok: boolean }> Note: Revokes all sessions. Irreversible.

requestMagicLink(email)

Sends magic sign-in link.

Returns: Promise<{ ok: boolean }>

confirmMagicLink(token)

Confirms magic link token via API (POST). Returns session directly.

Returns: Promise<{ user: KyquUser, session: KyquSession }>

exchangeSessionCode(sessionCode)

Exchanges ?session_code=… from a browser magic-link redirect for a bearer session.

Returns: Promise<{ user: KyquUser, session: KyquSession }>

enrollTotp(token)

Starts TOTP enrollment.

Returns: Promise<KyquTotpEnrollResult> (contains enrollmentUrl: string)

confirmTotp(token, code)

Confirms TOTP enrollment with code from authenticator app.

Returns: Promise<KyquTotpConfirmResult> (contains backupCodes: string[])

disableTotp(token, code)

Disables TOTP after verifying one last code.

Returns: Promise<{ ok: boolean }>

listSessions(token)

Lists all active sessions for the user. Each entry indicates whether it's the current session.

Returns: Promise<KyquSessionInfo[]>

revokeSession(token, sessionId)

Revokes a specific session by ID. Useful for "sign out from other devices."

Returns: Promise<{ ok: boolean }>

OAuth / Social Login

getOAuthAuthorizeUrl(provider, redirectUrl = "")

Returns the provider's authorization URL for browser redirect (synchronous, no network call).

Input: provider: "google" | "github", optional redirect URL Returns: string

getOAuthUser(token)

Get user linked to an OAuth identity.

Returns: Promise<{ provider, providerId }>

Passkeys / WebAuthn

getPasskeyRegistrationOptions(token)

Get WebAuthn PublicKeyCredentialCreationOptions for registering a new passkey.

Returns: Promise<CreationOptions>

registerPasskey(token, credential, name = "")

Store a new WebAuthn credential after browser creates it.

Input: credential (from navigator.credentials.create), optional name Returns: Promise<{ passkey }>

getPasskeyAuthenticationOptions(userId = null)

Get WebAuthn assertion options for authenticating with a passkey.

Returns: Promise<AssertionOptions>

authenticateWithPasskey(assertion)

Authenticate with a WebAuthn assertion. Returns session directly.

Input: assertion (from navigator.credentials.get) Returns: Promise<{ user: KyquUser, session: KyquSession }>

listPasskeys(token)

List registered passkey credentials.

Returns: Promise<{ passkeys: KyquPasskeyInfo[] }>

deletePasskey(token, credentialId)

Delete a passkey credential by ID.

Returns: Promise<{ ok: boolean }>

OIDC / ID Token

getIdToken(token)

Issue an RS256-signed OIDC ID token.

Returns: Promise<{ idToken: string }>

getOidcDiscovery()

Fetch the OpenID Connect Discovery document.

Returns: Promise<OidcDiscovery>

getJwks()

Fetch the JSON Web Key Set.

Returns: Promise<{ keys: JsonWebKey[] }>

Event Logs

getLogs(token, filters = {})

Query auth event logs.

Input: filters: { limit?, offset?, event? } Returns: Promise<{ logs: KyquLogEntry[], total: number }>

Auto-Refresh Session

withAutoRefresh(session, options = {})

Wraps a session token with automatic refresh before expiry.

Input: session: { token, expiresAt }, options: { marginSeconds?, onRefresh?, onError?, storage? } Returns: ManagedSession

The ManagedSession class provides:

class ManagedSession {
  getToken(): string;         // Returns current valid token
  getSession(): KyquSession;  // Returns current session info
  destroy(): void;            // Stop refresh timer and clear
}

Usage:

const managed = kyqu.withAutoRefresh(session, {
  storage: localStorage,        // Persists/restores across page reloads
  marginSeconds: 60,            // Refresh 60s before expiry
  onRefresh: (newSession) => {},// Called when token refreshes
  onError: (err) => {}          // Called when refresh fails
});

const token = managed.getToken(); // Always fresh

Types

interface KyquUser {
  id: string;
  projectId: string;
  email: string;
  name: string;
  status: string;
  emailVerifiedAt: string | null;
  passwordResetRequired: boolean;
  totpEnabled: boolean;
  lockedUntil: string | null;
  metadata: Record<string, any>;
  createdAt: string;
}

interface KyquSession {
  token: string;
  expiresAt: string;
}

interface KyquSignupResult {
  user: KyquUser;
  session: KyquSession | null;   // null when email verification required
  verificationRequired: boolean;
  verificationQueued: { expiresAt: string } | null;
}

interface KyquLoginResult {
  user: KyquUser;
  session: KyquSession;
}

interface KyquTotpEnrollResult {
  enrollmentUrl: string;          // otpauth:// URI
}

interface KyquTotpConfirmResult {
  ok: boolean;
  backupCodes: string[];          // 8 one-time codes
}

interface KyquFieldDef {
  id: string;
  name: string;
  label: string;
  fieldType: "text" | "number" | "boolean" | "date";
  required: boolean;
  defaultValue: string | null;
  sortOrder: number;
}

interface KyquSessionInfo {
  id: string;
  isCurrent: boolean;
  ipAddress: string | null;
  userAgent: string | null;
  createdAt: string;
  expiresAt: string;
}

interface KyquPasskeyInfo {
  id: string;
  name: string;
  createdAt: string;
  lastUsedAt: string | null;
}

interface KyquLogEntry {
  id: string;
  event: string;
  ipAddress: string | null;
  userAgent: string | null;
  metadata: Record<string, any>;
  createdAt: string;
}

interface OidcDiscovery {
  issuer: string;
  authorization_endpoint: string;
  token_endpoint: string;
  jwks_uri: string;
  id_token_signing_alg_values_supported: string[];
  subject_types_supported: string[];
  claims_supported: string[];
}

interface KyquClientOptions {
  baseUrl: string;
  projectId: string;
  publicKey: string;
}

React Hooks (@kyqu/client/react)

import { KyquProvider, useKyqu, useKyquUser, useKyquSession, useKyquLoading } from "@kyqu/client/react";

KyquProvider

Wraps your app with auth state context. Restores session from storage on mount.

<KyquProvider client={kyquClient}>
  <App />
</KyquProvider>

Props:

Prop	Type	Required	Description
client	KyquClient	Yes	Initialized KyquClient instance
storage	Storage	No	Custom storage (defaults to localStorage)
storageKey	string	No	Key for session storage (default "kyqu_session")

useKyqu()

Returns the full auth context.

const { client, session, user, loading, login, signup, logout, applySession } = useKyqu();

Return	Type	Description
client	KyquClient	The client instance
session	KyquSession | null	Current session or null
user	KyquUser | null	Current user or null
loading	boolean	True while restoring session on mount
login	(input) => Promise	Logs in and stores session
signup	(input) => Promise	Signs up and optionally stores session
logout	() => Promise	Logs out and clears session
applySession	(result) => void	Manually apply a login/signup result

useKyquUser()

Shorthand for useKyqu().user.

Returns: KyquUser | null

useKyquSession()

Shorthand for useKyqu().session.

Returns: KyquSession | null

useKyquLoading()

Shorthand for useKyqu().loading.

Returns: boolean

Package Metadata

Field	Value
Name	@kyqu/client
Version	0.2.0
License	MIT
Runtime deps	None
Module format	ESM (src/index.js) + CJS (dist/index.cjs)
TypeScript	Declarations in src/index.d.ts
React entry	src/react.js (@kyqu/client/react)
Test runner	node:test