@classic-homes/api 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# @classic-homes/api
+
+Typed client for the CHAPI API. Every path, query param, request body and
+response is typed from CHAPI's OpenAPI contract (`openapi.json` at the repo
+root), so consuming repos get autocomplete and compile-time checks against the
+real API — including the v2 (D1-backed) endpoints. v2 response bodies are typed
+per resource (e.g. `LotV2`, `CommunityV2`) from the field registry.
+
+## Install
+
+```bash
+npm install @classic-homes/api
+```
+
+This is a scoped, restricted package published under the `@classic-homes` org, so a
+consuming repo must authenticate npm to that scope first. Add an `.npmrc` at the
+repo root:
+
+```ini
+# .npmrc (consuming repo)
+@classic-homes:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+Then export a token with read access to the org before installing / in CI:
+
+```bash
+export NPM_TOKEN=xxxxxxxx   # org read token; do NOT commit it
+npm install @classic-homes/api
+```
+
+## Usage
+
+```ts
+import { createChapiClient } from '@classic-homes/api';
+
+const chapi = createChapiClient({
+  baseUrl: 'https://api.example.com',
+  token: async () => getAccessToken(), // string | () => string | Promise<string>
+});
+
+// List v2 lots — params, query and response are fully typed.
+const { data, error } = await chapi.GET('/v2/lots', {
+  params: { query: { page: 1, limit: 25, sort: '-lotNumber' } },
+});
+if (error) throw new Error('request failed');
+for (const lot of data.data) {
+  // lot is typed from the OpenAPI schema
+}
+
+// PATCH v2 enrichment
+await chapi.PATCH('/v2/filings/{id}', {
+  params: { path: { id: 390 } },
+  body: { webStatus: 'Production' },
+});
+```
+
+The client is a thin wrapper over
+[`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/); `GET`/`POST`/`PATCH`/…
+methods and the `params`/`body` shapes come from it.
+
+## Authentication
+
+Every request is sent as `Authorization: Bearer <token>`. The API accepts either:
+
+- **A JWT** — obtained from CHAPI's auth flow. Use a `token` function to refresh
+  short-lived JWTs per request.
+- **An API key** — pass the key string as `token`. The API checks the bearer value
+  as an API key first, then falls back to JWT verification.
+
+```ts
+// static API key
+const chapi = createChapiClient({ baseUrl, token: process.env.CHAPI_API_KEY });
+
+// or a refreshing JWT
+const chapi = createChapiClient({ baseUrl, token: () => auth.getAccessToken() });
+```
+
+### Auth helpers
+
+The package also ships typed auth calls, error predicates, and an auto-refreshing
+session that handles CHAPI's short-lived access tokens and **refresh-token rotation**
+(every refresh returns a NEW refresh token that replaces the old one).
+
+```ts
+import {
+  createChapiClient,
+  createAuthSession,
+  login,
+  isUnauthorized,
+  isForbidden,
+  isRateLimited,
+} from '@cos/chapi-client';
+
+// 1. Log in (typed wrapper over POST /v1/auth/login)
+const bootstrap = createChapiClient({ baseUrl });
+const { data, error } = await login(bootstrap, { email, password });
+if (error) throw new Error('login failed');
+
+// 2. Create a session that keeps the access token fresh and follows rotation.
+//    Persist BOTH tokens on change — the previous refresh token is now invalid.
+const session = createAuthSession({
+  baseUrl,
+  tokens: data, // { accessToken, refreshToken, sessionToken }
+  onTokensChanged: (t) => saveToStorage(t),
+});
+
+// 3. Use the session's token provider — it refreshes transparently before expiry.
+const chapi = createChapiClient({ baseUrl, token: session.token });
+
+// 4. Branch on typed errors instead of string-matching codes
+const res = await chapi.GET('/v2/homes', { params: { query: { page: 1 } } });
+if (isUnauthorized(res.error)) redirectToLogin();
+else if (isForbidden(res.error)) showNoAccess();
+else if (isRateLimited(res.error)) backOff();
+```
+
+`logout(client)` and `refresh(client, refreshToken)` are also exported. See
+`docs/TOKEN_LIFECYCLE.md` in the API repo for the full lifecycle.
+
+## Errors, pagination & permissions
+
+- **Errors** — `openapi-fetch` returns `{ data, error }` (it does not throw on
+  non-2xx). `error` is the typed error body (`{ error: { code, message, ... } }`).
+  Always branch on `error` before using `data`.
+- **Pagination** — list responses carry `meta.pagination` (`page`, `limit`, `total`,
+  `totalPages`). `limit` max is 500. Page with `params.query.page` / `limit`.
+- **Sources & staleness** — `meta.sources` names the backing edge DB; `meta.sync`
+  (`lastCompleted`, `isStale`) and the `X-Data-Stale` header report data freshness.
+- **Permissions are exact-match** — v2 hides fields your token isn't explicitly
+  granted. A `*` wildcard does NOT unlock permission-scoped fields (e.g. financial
+  fields need `<resource>:read:financial`). Missing fields usually mean a missing
+  permission, not a bug.
+- **PATCH write-through** — `meta.writeThrough` is `'ok'` when the edge DB was
+  updated in-request, or `'deferred'` when the write is pending the next sync
+  (the underlying record was still updated; the read model just lags briefly).
+
+## Incremental sync (`updated-since`)
+
+Each resource exposes `GET /v2/<resource>/updated-since?since=<ISO>` returning rows
+with `lastUpdated >= since`, ordered by `lastUpdated` then primary key. To pull a
+stable incremental feed, page until empty, then advance `since` to the max
+`lastUpdated` seen and dedupe by `id` (rows sharing a boundary timestamp can repeat
+across polls):
+
+```ts
+async function pullSince(chapi, since: string) {
+  const seen = new Set<string>();
+  let page = 1;
+  let maxUpdated = since;
+  for (;;) {
+    const { data, error } = await chapi.GET('/v2/lots/updated-since', {
+      params: { query: { since, page, limit: 500 } },
+    });
+    if (error) throw new Error('updated-since failed');
+    for (const row of data.data) {
+      if (seen.has(String(row.id))) continue;
+      seen.add(String(row.id));
+      if (row.lastUpdated && row.lastUpdated > maxUpdated) maxUpdated = row.lastUpdated;
+      // ...upsert row into your store...
+    }
+    if (data.data.length < 500) break;
+    page += 1;
+  }
+  return maxUpdated; // pass as `since` on the next poll
+}
+```
+
+## How the types stay accurate
+
+- `openapi.json` (repo root) is generated from the endpoint registry via
+  `npm run openapi:generate` and committed.
+- CI runs `npm run openapi:check` to fail the build if the committed spec drifts
+  from the code.
+- This package's `npm run generate` regenerates `src/types.ts` from that spec
+  (`src/types.ts` is git-ignored — always built, never hand-edited).
+
+## Scripts
+
+| Script | Purpose |
+| --- | --- |
+| `npm run generate` | Regenerate `src/types.ts` from `../../openapi.json` |
+| `npm run build` | Generate types, then compile to `dist/` |
+| `npm run typecheck` | Type-check without emitting |
+
+## Publishing (maintainers)
+
+The package is published by the `Publish SDK` workflow on an `sdk-v*` tag. To cut a
+release:
+
+1. From the repo root, regenerate and verify the contract:
+   `npm run openapi:generate && npm run openapi:check`.
+2. Bump `version` in `packages/chapi-client/package.json` and add a `CHANGELOG.md`
+   entry.
+3. Commit, then tag: `git tag sdk-v<version> && git push origin sdk-v<version>`.
+
+The workflow rebuilds `src/types.ts` from the committed `openapi.json` and runs
+`npm publish --provenance`, so the published types always match the tagged
+contract. Deploy tags (`v*`) are separate from SDK tags (`sdk-v*`).
+
+## Example consumer
+
+A minimal runnable example lives at `examples/sdk-consumer/` in the CHAPI repo
+(list lots + PATCH a filing against a local `wrangler dev`).

package/dist/auth.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { type ChapiClient } from './client';
+/** Shape of a CHAPI error body: `{ error: { code, message } }`. */
+export interface ChapiApiError {
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+}
+/** True for 401-class failures (missing/invalid/expired/revoked credentials). */
+export declare function isUnauthorized(err: unknown): boolean;
+/** True when authenticated but not permitted (403). */
+export declare function isForbidden(err: unknown): boolean;
+/** True when rate limited (429). */
+export declare function isRateLimited(err: unknown): boolean;
+/** True when the account is locked (423). */
+export declare function isAccountLocked(err: unknown): boolean;
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    sessionToken?: string;
+}
+/** `POST /v1/auth/login`. Returns the openapi-fetch `{ data, error }` result. */
+export declare function login(client: ChapiClient, body: {
+    username?: string;
+    email?: string;
+    password: string;
+    [k: string]: unknown;
+}): Promise<import("openapi-fetch").FetchResponse<{
+    parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+    };
+    requestBody: {
+        content: {
+            "application/json": import("./types").components["schemas"]["LoginRequest"];
+        };
+    };
+    responses: {
+        200: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["LoginResponse"];
+            };
+        };
+        400: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+        401: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+        423: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+        429: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+    };
+}, {
+    body: never;
+}, `${string}/${string}`>>;
+/** `POST /v1/auth/refresh`. Returns a NEW access token AND a NEW (rotated) refresh token. */
+export declare function refresh(client: ChapiClient, refreshToken: string): Promise<import("openapi-fetch").FetchResponse<{
+    parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+    };
+    requestBody: {
+        content: {
+            "application/json": {
+                refreshToken: string;
+            };
+        };
+    };
+    responses: {
+        200: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": {
+                    accessToken?: string;
+                    refreshToken?: string;
+                    tokenType?: "Bearer";
+                    expiresIn?: number;
+                };
+            };
+        };
+        401: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+    };
+}, {
+    body: never;
+}, `${string}/${string}`>>;
+/** `POST /v1/auth/logout`. Requires the client to be authenticated. */
+export declare function logout(client: ChapiClient): Promise<import("openapi-fetch").FetchResponse<{
+    parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+    };
+    requestBody?: never;
+    responses: {
+        200: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["MessageResponse"];
+            };
+        };
+        401: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": import("./types").components["schemas"]["Error"];
+            };
+        };
+    };
+}, never, `${string}/${string}`>>;
+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 declare function createAuthSession(options: AuthSessionOptions): AuthSession;

package/dist/auth.js

@@ -0,0 +1,114 @@
+/**
+ * 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 } from './client';
+function hasCode(err, ...codes) {
+    const code = err?.error?.code;
+    return typeof code === 'string' && codes.includes(code);
+}
+/** True for 401-class failures (missing/invalid/expired/revoked credentials). */
+export function isUnauthorized(err) {
+    return hasCode(err, 'UNAUTHORIZED', 'INVALID_TOKEN', 'TOKEN_REVOKED');
+}
+/** True when authenticated but not permitted (403). */
+export function isForbidden(err) {
+    return hasCode(err, 'FORBIDDEN', 'INSUFFICIENT_PERMISSIONS');
+}
+/** True when rate limited (429). */
+export function isRateLimited(err) {
+    return hasCode(err, 'RATE_LIMIT_EXCEEDED');
+}
+/** True when the account is locked (423). */
+export function isAccountLocked(err) {
+    return hasCode(err, 'ACCOUNT_LOCKED');
+}
+/** `POST /v1/auth/login`. Returns the openapi-fetch `{ data, error }` result. */
+export function login(client, body) {
+    // Cast: the generated body type is exact; consumers pass username OR email + password.
+    return client.POST('/v1/auth/login', { body: body });
+}
+/** `POST /v1/auth/refresh`. Returns a NEW access token AND a NEW (rotated) refresh token. */
+export function refresh(client, refreshToken) {
+    return client.POST('/v1/auth/refresh', { body: { refreshToken } });
+}
+/** `POST /v1/auth/logout`. Requires the client to be authenticated. */
+export function logout(client) {
+    return client.POST('/v1/auth/logout', {});
+}
+// ---------------------------------------------------------------------------
+// Auto-refreshing session
+// ---------------------------------------------------------------------------
+/** Decode a JWT's `exp` (seconds since epoch), or null if it can't be read. */
+function jwtExp(token) {
+    try {
+        const payload = token.split('.')[1];
+        if (!payload)
+            return null;
+        const json = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
+        const exp = JSON.parse(json).exp;
+        return typeof exp === 'number' ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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) {
+    const skew = options.refreshSkewSeconds ?? 30;
+    let tokens = { ...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 = null;
+    async function doRefresh() {
+        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;
+        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() {
+        // Collapse concurrent refreshes so a burst of requests triggers exactly one refresh.
+        if (!inFlight) {
+            inFlight = doRefresh().finally(() => {
+                inFlight = null;
+            });
+        }
+        return inFlight;
+    }
+    async function token() {
+        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/dist/client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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 { 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 declare function createChapiClient(options: ChapiClientOptions): ChapiClient;

package/dist/client.js

@@ -0,0 +1,34 @@
+/**
+ * @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 from 'openapi-fetch';
+/**
+ * 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) {
+    const { token, ...rest } = options;
+    const client = createClient(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/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createChapiClient } from './client';
+export type { ChapiClient, ChapiClientOptions } from './client';
+export type { paths, components, operations } from './types';
+export { login, refresh, logout, createAuthSession, isUnauthorized, isForbidden, isRateLimited, isAccountLocked, } from './auth';
+export type { AuthTokens, AuthSession, AuthSessionOptions, ChapiApiError } from './auth';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createChapiClient } from './client';
+// Auth helpers: typed login/refresh/logout, error predicates, auto-refreshing session.
+export { login, refresh, logout, createAuthSession, isUnauthorized, isForbidden, isRateLimited, isAccountLocked, } from './auth';