Client SDK (@kyqu/client)

A zero-dependency JavaScript/TypeScript client for the Kyqu auth platform. Works in browsers, Node.js, Deno, Bun, and any fetch-capable runtime.

Installation

npm install @kyqu/client

Quick Start

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

const client = new KyquClient({
  baseUrl: "https://auth.example.com",
  projectId: "your-project-id",
  publicKey: "pk_your_public_key"
});

// Sign up
const { user, session } = await client.signup({
  email: "user@example.com",
  password: "secure-password-42",
  name: "User Name"
});

// Log in
const { user, session } = await client.login({
  email: "user@example.com",
  password: "secure-password-42"
});

// Get current user
const user = await client.getUser(session.token);

API

Constructor

new KyquClient(options: KyquClientOptions)

Option	Type	Required	Description
baseUrl	string	Yes	Root URL of your Kyqu API
projectId	string	Yes	Project UUID from dashboard
publicKey	string	Yes	pk_ key from dashboard

Methods (32)

Method	Description
getFields()	Returns custom field definitions for building dynamic signup forms
signup(input)	Registers a new user. Custom field values as top-level keys.
login(input)	Authenticates a user. Include totpCode or backupCode for 2FA.
logout(token)	Revokes a bearer token.
getUser(token)	Returns the user for a bearer token.
updateMetadata(token, metadata)	Updates client-writable metadata for the authenticated user
requestEmailVerification(email)	Sends verification email.
confirmEmailVerification(token)	Confirms verification token.
requestPasswordReset(email)	Initiates password reset.
confirmPasswordReset(input)	Confirms reset with token + new password.
changePassword(token, input)	Changes password (requires bearer token + current password).
requestMagicLink(email)	Sends magic sign-in link.
confirmMagicLink(token)	Confirms magic link via POST API.
exchangeSessionCode(sessionCode)	Exchanges browser session_code from magic-link redirect
enrollTotp(token)	Starts TOTP enrollment; returns enrollmentUrl (QR code).
confirmTotp(token, code)	Confirms TOTP enrollment; returns 8 backup codes.
disableTotp(token, code)	Disables TOTP for the authenticated user.
getOAuthAuthorizeUrl(provider, redirectUrl?)	Build OAuth provider authorize URL (synchronous, no HTTP call)
getOAuthUser(token)	Get OAuth-linked user profile (delegates to getUser)
getPasskeyRegistrationOptions(token)	Get WebAuthn registration options
registerPasskey(token, credential, name?)	Register WebAuthn passkey
getPasskeyAuthenticationOptions(userId?)	Get WebAuthn authentication options
authenticateWithPasskey(assertion)	Authenticate with passkey assertion
listPasskeys(token)	List registered passkeys
deletePasskey(token, credentialId)	Delete passkey
getIdToken(token)	Issue RS256 JWT ID token for OIDC
getOidcDiscovery()	Get OpenID Connect discovery document
getJwks()	Get JSON Web Key Set
getLogs(token, filters?)	Get audit logs for current user
withAutoRefresh(session, options?)	Wrap session with auto-refresh timer
listSessions(token)	Lists all active sessions.
revokeSession(token, sessionId)	Revokes a specific session.

Types

interface KyquUser {
  id: string;
  projectId: string;
  email: string;
  name: string;
  status: string;
  emailVerifiedAt: string;
  passwordResetRequired: boolean;
  totpEnabled: boolean;
  lockedUntil: string;
  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 codes, display once
}

interface KyquFieldDef {
  id: string;
  name: string;
  label: string;
  fieldType: "text" | "number" | "boolean" | "date" | "select";
  required: boolean;
  defaultValue: string;
  sortOrder: number;
  clientWritable?: boolean;
  adminWritable?: boolean;
  visibleInAuth?: boolean;
  options?: string[];
}

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

interface KyquPasskey {
  id: string;
  credentialId: string;
  name: string;
  createdAt: string;
  lastUsedAt: string | null;
  signCount: number;
}

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

interface KyquOidcDiscovery {
  issuer: string;
  jwks_uri: string;
  token_endpoint: string;
  userinfo_endpoint: string;
  response_types_supported: string[];
  id_token_signing_alg_values_supported: string[];
}

interface KyquJwks {
  keys: Array<{ kty: string; use: string; alg: string; kid: string; n: string; e: string }>;
}

React Integration (@kyqu/client/react)

The SDK exports a React package with context provider and hooks:

Export	Description
KyquProvider	Context provider with session persistence (localStorage) and auto-refresh
useKyqu()	Full context: client, user, session, login, signup, logout, applySession
useKyquUser()	Current user or null
useKyquSession()	Current session or null
useKyquLoading()	true while restoring session on mount

Error Handling

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

Package Details

• Package name: @kyqu/client
• Version: 0.2.0
• License: MIT
• Runtime dependencies: None (uses global fetch)
• ESM: Yes ("type": "module")
• Dual format: ESM (src/index.js) + CJS (dist/index.cjs)
• TypeScript: Declarations in src/index.d.ts
• React: Optional hooks entry point at @kyqu/client/react (requires React 18+)