@ave-id/sdk

bun add @ave-id/sdk

import { getQuickIdentity, startQuickSignIn } from "@ave-id/sdk/client";

const user = getQuickIdentity();
if (!user) await startQuickSignIn();

import { handleQuickCallback } from "@ave-id/sdk/client";

await handleQuickCallback();

async function startQuickSignIn(options?: {
  issuer?: string;       // default: "https://aveid.net"
  scope?: string;        // default: "openid profile email"
  redirectUri?: string;  // default: <origin>/ave/callback
  returnTo?: string;     // default: current URL
}): Promise<void>

async function handleQuickCallback(options?: {
  issuer?: string;
  redirectUri?: string;  // must match the redirectUri used in startQuickSignIn
  fallbackPath?: string; // where to go if no return-to is stored (default: "/")
}): Promise<QuickIdentity | null>

async function finishQuickSignIn(options?: {
  issuer?: string;
  redirectUri?: string;
  url?: string;          // override URL to parse (default: window.location.href)
}): Promise<QuickIdentity | null>

function getQuickIdentity(storageKey?: string): QuickIdentity | null

function clearQuickIdentity(storageKey?: string): void

async function checkQuickSession(options?: {
  issuer?: string;
  storageKey?: string;
  token?: string;  // supply a token directly instead of reading from storage
}): Promise<{
  status: "active" | "login_required" | "unsupported";
  reason?: string;
}>

function startQuickSessionMonitor(options?: {
  issuer?: string;
  storageKey?: string;
  intervalMs?: number;  // default: 60 000
  onLoginRequired?: (result: { reason?: string }) => void;
  onError?: (error: Error) => void;
}): { stop: () => void }

interface QuickIdentity {
  userId: string;        // Ave identity UUID
  handle?: string;       // @handle
  displayName?: string;
  email?: string;
  avatarUrl?: string;
  /**
   * JWT access token (`access_token_jwt`) for Ave APIs.
   * Its audience is Ave's resource audience, not your app. Use `idToken` or
   * your own session for app API authentication.
   * Always verify server-side: check `iss`, `aud`, `exp`, and the JWT signature
   * against the JWKS endpoint before trusting claims.
   * The JWT payload always contains `quick: true` — Standard-only API
   * middleware can check for the absence of this claim to reject Quick tokens.
   * Upgrade to Standard Ave for confidential flows.
   */
  token: string;
  /**
   * OIDC id_token — pass this to Convex (`convex.setAuth`) or any service
   * that validates OIDC identity. Only present when `openid` scope was
   * requested (the default). `aud` equals your Quick Ave clientId:
   * `"origin:https://yourapp.com"`.
   */
  idToken?: string;
  expiresIn: number;     // seconds until expiry
  receivedAt: number;    // Unix ms when the token was stored
}