@classic-homes/api 1.0.0

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@classic-homes/api",
+  "version": "1.0.0",
+  "description": "Typed client for the CHAPI API, generated from the committed OpenAPI contract.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Classic-Homes/chapi.git",
+    "directory": "packages/chapi-client"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "openapi-typescript ../../openapi.json -o src/types.ts",
+    "build": "npm run generate && tsc -p tsconfig.json",
+    "typecheck": "npm run generate && tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.8"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,172 @@
+/**
+ * Auth helpers for the CHAPI client.
+ *
+ * The base client only gives you a `token` injection point. This module adds the pieces
+ * every consumer would otherwise hand-roll: typed login/refresh/logout calls, a typed error
+ * taxonomy, and an auto-refreshing session that transparently keeps a short-lived access
+ * token fresh and follows refresh-token ROTATION (every refresh returns a new refresh token
+ * that must replace the old one).
+ */
+import { createChapiClient, type ChapiClient } from './client';
+
+// ---------------------------------------------------------------------------
+// Typed error predicates
+// ---------------------------------------------------------------------------
+
+/** Shape of a CHAPI error body: `{ error: { code, message } }`. */
+export interface ChapiApiError {
+  error?: { code?: string; message?: string } | null;
+}
+
+function hasCode(err: unknown, ...codes: string[]): boolean {
+  const code = (err as ChapiApiError | undefined | null)?.error?.code;
+  return typeof code === 'string' && codes.includes(code);
+}
+
+/** True for 401-class failures (missing/invalid/expired/revoked credentials). */
+export function isUnauthorized(err: unknown): boolean {
+  return hasCode(err, 'UNAUTHORIZED', 'INVALID_TOKEN', 'TOKEN_REVOKED');
+}
+
+/** True when authenticated but not permitted (403). */
+export function isForbidden(err: unknown): boolean {
+  return hasCode(err, 'FORBIDDEN', 'INSUFFICIENT_PERMISSIONS');
+}
+
+/** True when rate limited (429). */
+export function isRateLimited(err: unknown): boolean {
+  return hasCode(err, 'RATE_LIMIT_EXCEEDED');
+}
+
+/** True when the account is locked (423). */
+export function isAccountLocked(err: unknown): boolean {
+  return hasCode(err, 'ACCOUNT_LOCKED');
+}
+
+// ---------------------------------------------------------------------------
+// Typed auth calls
+// ---------------------------------------------------------------------------
+
+export interface AuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  sessionToken?: string;
+}
+
+/** `POST /v1/auth/login`. Returns the openapi-fetch `{ data, error }` result. */
+export function login(
+  client: ChapiClient,
+  body: { username?: string; email?: string; password: string; [k: string]: unknown },
+) {
+  // Cast: the generated body type is exact; consumers pass username OR email + password.
+  return client.POST('/v1/auth/login', { body: body as never });
+}
+
+/** `POST /v1/auth/refresh`. Returns a NEW access token AND a NEW (rotated) refresh token. */
+export function refresh(client: ChapiClient, refreshToken: string) {
+  return client.POST('/v1/auth/refresh', { body: { refreshToken } as never });
+}
+
+/** `POST /v1/auth/logout`. Requires the client to be authenticated. */
+export function logout(client: ChapiClient) {
+  return client.POST('/v1/auth/logout', {} as never);
+}
+
+// ---------------------------------------------------------------------------
+// Auto-refreshing session
+// ---------------------------------------------------------------------------
+
+/** Decode a JWT's `exp` (seconds since epoch), or null if it can't be read. */
+function jwtExp(token: string): number | null {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return null;
+    const json = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
+    const exp = (JSON.parse(json) as { exp?: number }).exp;
+    return typeof exp === 'number' ? exp : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AuthSessionOptions {
+  /** API origin, e.g. https://api.example.com */
+  baseUrl: string;
+  /** Initial tokens (e.g. from a prior login or SSO callback). */
+  tokens: AuthTokens;
+  /**
+   * Called whenever the tokens change (after a refresh rotates them). Persist BOTH the new
+   * access token and the new refresh token — the previous refresh token is now invalid.
+   */
+  onTokensChanged?: (tokens: AuthTokens) => void;
+  /** Refresh this many seconds before the access token actually expires. Default 30. */
+  refreshSkewSeconds?: number;
+}
+
+export interface AuthSession {
+  /** A `token` provider to pass to `createChapiClient({ token })` — refreshes as needed. */
+  token: () => Promise<string>;
+  /** Current tokens snapshot. */
+  getTokens: () => AuthTokens;
+  /** Force a refresh now (rotates the refresh token). Returns the new access token. */
+  refreshNow: () => Promise<string>;
+}
+
+/**
+ * Create a session that keeps the access token fresh and follows refresh-token rotation.
+ *
+ * Pass `session.token` as the `token` option of `createChapiClient`. Before each request the
+ * provider checks the access token's `exp`; if it is expired (or within the skew window) it
+ * calls `/v1/auth/refresh`, stores the rotated tokens, and fires `onTokensChanged`.
+ *
+ * @example
+ * const session = createAuthSession({ baseUrl, tokens, onTokensChanged: save });
+ * const chapi = createChapiClient({ baseUrl, token: session.token });
+ */
+export function createAuthSession(options: AuthSessionOptions): AuthSession {
+  const skew = options.refreshSkewSeconds ?? 30;
+  let tokens: AuthTokens = { ...options.tokens };
+  // A bare client used only to call /v1/auth/refresh (no token middleware → no recursion).
+  const refreshClient = createChapiClient({ baseUrl: options.baseUrl });
+  let inFlight: Promise<string> | null = null;
+
+  async function doRefresh(): Promise<string> {
+    if (!tokens.refreshToken) {
+      throw new Error('No refresh token available; the user must log in again.');
+    }
+    const { data, error } = await refresh(refreshClient, tokens.refreshToken);
+    if (error || !data) {
+      throw new Error('Refresh failed; the user must log in again.');
+    }
+    const next = data as { accessToken: string; refreshToken?: string };
+    tokens = {
+      accessToken: next.accessToken,
+      // Rotation: prefer the new refresh token; fall back only if the server omitted it.
+      refreshToken: next.refreshToken ?? tokens.refreshToken,
+      sessionToken: tokens.sessionToken,
+    };
+    options.onTokensChanged?.({ ...tokens });
+    return tokens.accessToken;
+  }
+
+  function refreshNow(): Promise<string> {
+    // Collapse concurrent refreshes so a burst of requests triggers exactly one refresh.
+    if (!inFlight) {
+      inFlight = doRefresh().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  }
+
+  async function token(): Promise<string> {
+    const exp = jwtExp(tokens.accessToken);
+    const now = Math.floor(Date.now() / 1000);
+    if (exp !== null && exp - skew <= now) {
+      return refreshNow();
+    }
+    return tokens.accessToken;
+  }
+
+  return { token, getTokens: () => ({ ...tokens }), refreshNow };
+}

package/src/client.ts

@@ -0,0 +1,49 @@
+/**
+ * @cos/chapi-client — typed client for the CHAPI API.
+ *
+ * Thin wrapper over openapi-fetch: every path, method, query param, request
+ * body and response is typed from the committed `openapi.json` (regenerated
+ * into `types.ts`). No hand-maintained call signatures.
+ */
+import createClient, { type ClientOptions, type Client } from 'openapi-fetch';
+import type { paths } from './types';
+
+export interface ChapiClientOptions extends ClientOptions {
+  /** API origin, e.g. https://api.example.com (no trailing slash needed). */
+  baseUrl: string;
+  /**
+   * Bearer token, or a function returning one (sync or async) so callers can
+   * refresh short-lived tokens per request. Attached as `Authorization: Bearer`.
+   */
+  token?: string | (() => string | Promise<string>);
+}
+
+export type ChapiClient = Client<paths>;
+
+/**
+ * Create a typed CHAPI client.
+ *
+ * @example
+ * const chapi = createChapiClient({ baseUrl: 'https://api.example.com', token });
+ * const { data, error } = await chapi.GET('/v2/lots', {
+ *   params: { query: { page: 1, limit: 25, sort: '-lotNumber' } },
+ * });
+ * if (error) throw new Error('request failed');
+ * data.data.forEach((lot) => { ... }); // fully typed
+ */
+export function createChapiClient(options: ChapiClientOptions): ChapiClient {
+  const { token, ...rest } = options;
+  const client = createClient<paths>(rest);
+
+  if (token) {
+    client.use({
+      async onRequest({ request }) {
+        const value = typeof token === 'function' ? await token() : token;
+        if (value) request.headers.set('Authorization', `Bearer ${value}`);
+        return request;
+      },
+    });
+  }
+
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { createChapiClient } from './client';
+export type { ChapiClient, ChapiClientOptions } from './client';
+export type { paths, components, operations } from './types';
+
+// Auth helpers: typed login/refresh/logout, error predicates, auto-refreshing session.
+export {
+  login,
+  refresh,
+  logout,
+  createAuthSession,
+  isUnauthorized,
+  isForbidden,
+  isRateLimited,
+  isAccountLocked,
+} from './auth';
+export type { AuthTokens, AuthSession, AuthSessionOptions, ChapiApiError } from './auth';