@acms-subir/client 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# @acms-subir/client
+
+Dependency-free ESM TypeScript client for ACMS public API v1. Supports Expo/React
+Native, browsers and Node 18+ using global `fetch`, `URL`, `Headers` and
+`AbortController`. Supply `fetch` when your environment needs an adapter.
+
+```sh
+npm install @acms-subir/client
+```
+
+```ts
+import { createClient, isAcmsError } from '@acms-subir/client';
+
+const client = createClient({ baseUrl: 'https://example.com', locale: 'es' });
+const site = await client.site();
+const home = await client.home();
+const page = await client.page('about/team');
+for await (const post of client.paginate.posts({ collection: 'blog', limit: 50 })) {
+  console.log(post.title);
+}
+const english = client.withLocale('en');
+```
+
+`baseUrl` accepts a site origin or a full `/api/v1` URL, with an optional
+hosting prefix. All methods return **unwrapped `data`**; `openapi()` returns the
+raw document. Every method accepts `locale` and `signal` in its options object.
+Locale is sent only for routes that support translations. `withLocale` shares
+the cache and transport configuration with the original client.
+
+| Method | Options / behavior |
+| --- | --- |
+| `site()`, `theme()`, `home()` | Identity, tokens, resolved homepage |
+| `page(slug, opts)` | Resolved page including sections; nested slugs supported |
+| `content(opts)` | `kind`, `collection`, `page`, `limit`, `cursor` |
+| `contentById(id, opts)` | Optional `kind` to disambiguate imported IDs |
+| `posts(opts)` | Content filtered to posts; `collection`, `tag`, pagination |
+| `post(slug, opts)` | Scans post summaries, then loads detail by ID; pass `collection` for ambiguous slugs |
+| `pages(opts)` | Page **summaries**, with pagination; use `page()` for sections |
+| `events(opts)` | Occurrences with `from`, `to`, `calendar`, `q`, pagination |
+| `event(slug, opts)` | First matching event from occurrences in the requested window |
+| `calendars()` | Public calendars |
+| `resources(opts)`, `resource(slug, opts)` | Public resources; slug lookup scans list pages |
+| `availability(opts)` | Required `resource`, `link`; optional `from`, `days`, `minutes` |
+| `book(opts)` | Resource booking or RSVP input, optional `idempotencyKey` |
+| `openapi()` | Raw OpenAPI document |
+| `registerDevice({ token, platform, locale?, topics? })` | Register or refresh an Expo push token (call on every app start); `{ created, device }` |
+| `updateDevice(token, { topics?, locale? })` | Change a device's topics or language |
+| `unregisterDevice(token)` | Opt out (idempotent) |
+| `pushTopics()` | Topics to offer as notification toggles |
+
+The server has no post-slug, event-detail or resource-detail endpoint. Those
+convenience methods may make multiple requests. `event()` only finds events
+with occurrences in its window (default: next 30 UTC days); an unlisted
+calendar requires `calendar`. It does not fetch arbitrary historical events.
+If post slugs collide and no collection is supplied, the first listed match wins.
+
+Pagination uses `page`/`nextPage`, not opaque cursors. `cursor` is a numeric
+alias for `page`; an explicit `page` wins. `tag` filters **each fetched page
+locally**, so a page can be empty with a non-null `nextPage`. Iterators continue
+through these pages. `paginate.content/posts/pages/events/resources` yield
+individual items (events yields occurrences). They do not deduplicate changing
+server results or provide snapshot consistency; deduplicate IDs in your app.
+
+## Bookings, errors and cancellation
+
+```ts
+// Persist a UUID v4 with this booking intent before submitting; reuse it until
+// the outcome is known. Use your platform's secure UUID/storage facilities.
+const idempotencyKey = crypto.randomUUID();
+try {
+  const result = await client.book({
+    resource: 'hall', link: 'meeting', start: '2026-10-05T14:00:00Z', minutes: 60,
+    name: 'Example Guest', email: 'guest@example.com', idempotencyKey,
+  });
+  // Store result.manageToken securely; it grants booking-management access.
+} catch (error) {
+  if (isAcmsError(error)) {
+    console.log(error.status, error.code, error.message, error.retryAfter);
+    // error.idempotencyKey preserves even an automatically generated key.
+  }
+}
+
+const controller = new AbortController();
+const pending = client.home({ signal: controller.signal });
+controller.abort();
+await pending.catch(() => {});
+```
+
+GET and booking POST requests retry network failures, 5xx and 429 responses at
+most twice (three attempts total), with 250/500ms backoff and at least the
+server's `Retry-After` delay (seconds or HTTP date). Booking retries always
+reuse the same serialized body and UUID. By default each `book()` call creates
+a key using `crypto.randomUUID`, falling back to a Math.random UUID v4 where
+unavailable. For recovery across calls/app restarts, supply and persist your own
+secure UUID. Never create a new intent merely because a response timed out.
+
+`timeoutMs` defaults to 30,000 and covers the entire request, including retries,
+cache access and body reading. A longer rate-limit delay may exhaust that
+budget. Explicit aborts and timeouts are not automatically retried; an uncertain
+booking must be retried with its existing key. `AcmsError` exposes `status`,
+`code`, `message`, `retryAfter` (seconds), optional validation `issues` and
+`idempotencyKey`. Local failures use status 0 and `network_error`, `timeout`,
+`aborted`, or `invalid_response`; non-JSON HTTP errors use `http_error`.
+Convenience lookups apply the timeout separately to each underlying request.
+
+## Push notifications
+
+Available when the site enables push (`acms({ mobile: { push: true } })`);
+otherwise these return a 404 `AcmsError`. Tokens come from
+`expo-notifications` (`getExpoPushTokenAsync`). The site stores the token,
+platform, language and topics only.
+
+```ts
+const { topics } = await client.pushTopics();          // [{ id: 'news', label: 'News', kind: 'general' }, …]
+await client.registerDevice({ token, platform: 'ios', locale: 'es', topics: ['news', 'events'] });
+await client.updateDevice(token, { topics: ['events'] });
+await client.unregisterDevice(token);
+```
+
+## Cache and headers
+
+ETag revalidation defaults to an in-memory URL-keyed cache. Each read contacts
+the server with `If-None-Match`; a 304 reuses the saved data. This is not an
+offline fallback. Treat returned cached objects as immutable. Use `cache: false`
+to disable it. Availability, booking results and errors are never cached.
+Responses without an ETag or with `no-store` invalidate an older entry.
+
+```ts
+import type { ClientCache } from '@acms-subir/client';
+const cache: ClientCache = {
+  async get(url) { /* retrieve { etag, body } from app storage */ return null; },
+  async set(url, entry) { /* persist entry; null means delete */ },
+};
+const persistent = createClient({ baseUrl: 'https://example.com/api/v1', cache });
+```
+
+Adapters may be synchronous or asynchronous. Keep persistent caches scoped to
+one site's public API and account for storage limits. Cache adapter failures
+propagate to the caller. Custom `headers` are supported; do not embed privileged
+credentials. Requests omit browser credentials. Conditional headers are managed
+by the client; a per-call booking key overrides a configured header key.
+
+## Development
+
+```sh
+npm run build -w packages/client
+npm run test -w packages/client
+npm run check:types -w packages/client
+npm run generate:types -w packages/client  # after reviewing core schema changes
+```
+
+The contract test imports the actual core OpenAPI generator using core's virtual
+module test stubs, compares all GET/POST paths to the client method registry,
+and checks generated request/response types byte-for-byte. HEAD and OPTIONS
+are transport operations and have no separate data-returning methods. No core
+code, Zod, or Node built-ins ship in this package's runtime.
+
+## Editor apps (staff sign-in)
+
+For sites with `acms({ mobile: { editor: { redirectUris } } })`. Staff sign in
+in the system browser (OAuth 2.0 + PKCE); the app never sees a password.
+
+```ts
+import { createEditorAuth, createEditorSession, createEditorClient } from '@acms-subir/client';
+
+const auth = createEditorAuth({ baseUrl: 'https://example.com', clientId: 'org.example.staff', redirectUri: 'org.example.staff://auth' });
+const session = createEditorSession({ auth, storage /* get/set backed by expo-secure-store */, onSignedOut });
+const api = createEditorClient({ baseUrl: 'https://example.com', session });
+
+const { url, verifier, state } = await auth.start({ deviceName: 'Ana’s iPhone' });
+// open `url` with expo-web-browser openAuthSessionAsync, then:
+const { code } = auth.parseRedirect(returnedUrl, state);
+await session.signIn(await auth.exchangeCode({ code, codeVerifier: verifier }));
+
+const doc = await api.getDocument('post', id);
+await api.saveDocument('post', id, { revision: doc.revision, fields: { title: 'New title' } });
+```
+
+In React Native pass `crypto: { randomBytes, sha256 }` from expo-crypto to
+`createEditorAuth` (Web Crypto is the default). Refreshes are single-flight;
+a 401 is retried once after a refresh, then `onAuthError` runs. Writes carry
+the `revision` you loaded (409 when someone saved first).

package/dist/editor.d.ts

@@ -0,0 +1,291 @@
+import { AcmsError } from './errors.js';
+import type { EditorToken, EditorMe, EditorDocumentList, EditorDocument, EditorSections, EditorSectionResult, EditorRevision, EditorDocumentTranslation, EditorSectionTranslation, EditorMedia, EditorMediaList, EditorBooking, EditorBookingList, EditorCreateInput, EditorSaveInput, EditorListQuery, EditorSectionsQuery, EditorMediaQuery, EditorBookingsQuery } from './types.js';
+/** Randomness + SHA-256. Defaults to Web Crypto; in React Native pass expo-crypto:
+ *  { randomBytes: (n) => Crypto.getRandomBytes(n), sha256: (d) => Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, d) } */
+export interface PkceCrypto {
+    randomBytes(length: number): Uint8Array | Promise<Uint8Array>;
+    sha256(data: Uint8Array): ArrayBuffer | Uint8Array | Promise<ArrayBuffer | Uint8Array>;
+}
+export declare const webCrypto: PkceCrypto;
+/** base64url without padding (no btoa: works in every JS runtime) */
+export declare function base64url(bytes: Uint8Array): string;
+/** a 43-character verifier (32 random bytes), RFC 7636 */
+export declare function createCodeVerifier(crypto?: PkceCrypto): Promise<string>;
+export declare function codeChallengeFor(verifier: string, crypto?: PkceCrypto): Promise<string>;
+export declare function createPkce(crypto?: PkceCrypto): Promise<{
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}>;
+export declare function createState(crypto?: PkceCrypto): Promise<string>;
+export interface EditorTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** epoch ms when the access token expires */
+    expiresAt: number;
+    user: EditorToken['user'];
+    device: EditorToken['device'];
+}
+export declare const toTokens: (t: EditorToken, now?: number) => EditorTokens;
+export interface EditorAuthOptions {
+    /** Site origin (or its /api/v1 base) */
+    baseUrl: string;
+    /** Your app's id, shown on the consent screen (letters, digits, . _ : -) */
+    clientId: string;
+    /** Must be listed in acms({ mobile: { editor: { redirectUris } } }) */
+    redirectUri: string;
+    fetch?: typeof globalThis.fetch;
+    crypto?: PkceCrypto;
+    timeoutMs?: number;
+}
+export interface EditorAuth {
+    /** where to open the system browser (expo-web-browser openAuthSessionAsync) */
+    buildAuthorizeUrl(o: {
+        codeChallenge: string;
+        state: string;
+        deviceName?: string;
+    }): string;
+    /** PKCE + state + URL in one step; keep verifier and state until the redirect returns */
+    start(o?: {
+        deviceName?: string;
+    }): Promise<{
+        url: string;
+        verifier: string;
+        state: string;
+    }>;
+    /** read the redirect: returns the code, throws on error, cancel or state mismatch */
+    parseRedirect(url: string, expectedState: string): {
+        code: string;
+    };
+    exchangeCode(o: {
+        code: string;
+        codeVerifier: string;
+    }): Promise<EditorTokens>;
+    /** rotates: the old refresh token stops working; reusing it signs the device out */
+    refresh(refreshToken: string): Promise<EditorTokens>;
+    revoke(token: string): Promise<void>;
+}
+export declare function createEditorAuth(options: EditorAuthOptions): EditorAuth;
+export interface TokenStorage {
+    get(): EditorTokens | null | Promise<EditorTokens | null>;
+    /** null signs out */
+    set(tokens: EditorTokens | null): void | Promise<void>;
+}
+export interface EditorSession {
+    getAccessToken(): Promise<string | null>;
+    /** single-flight: concurrent callers share one refresh request */
+    refresh(): Promise<string | null>;
+    signIn(tokens: EditorTokens): Promise<void>;
+    signOut(): Promise<void>;
+    tokens(): Promise<EditorTokens | null>;
+}
+export declare function createEditorSession(o: {
+    auth: EditorAuth;
+    storage: TokenStorage;
+    onSignedOut?: () => void;
+    refreshSkewMs?: number;
+    now?: () => number;
+}): EditorSession;
+export declare const authEndpoints: {
+    readonly exchangeCode: {
+        readonly method: "POST";
+        readonly path: "/auth/token";
+    };
+    readonly revoke: {
+        readonly method: "POST";
+        readonly path: "/auth/revoke";
+    };
+};
+export declare const editorEndpoints: {
+    readonly me: {
+        readonly method: "GET";
+        readonly path: "/admin/me";
+    };
+    readonly listDocuments: {
+        readonly method: "GET";
+        readonly path: "/admin/documents";
+    };
+    readonly createDocument: {
+        readonly method: "POST";
+        readonly path: "/admin/documents";
+    };
+    readonly getDocument: {
+        readonly method: "GET";
+        readonly path: "/admin/documents/{kind}/{id}";
+    };
+    readonly saveDocument: {
+        readonly method: "PUT";
+        readonly path: "/admin/documents/{kind}/{id}";
+    };
+    readonly publishDocument: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/publish";
+    };
+    readonly unpublishDocument: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/unpublish";
+    };
+    readonly scheduleDocument: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/schedule";
+    };
+    readonly discardDocument: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/discard";
+    };
+    readonly getDocumentTranslation: {
+        readonly method: "GET";
+        readonly path: "/admin/documents/{kind}/{id}/translations/{locale}";
+    };
+    readonly setDocumentTranslation: {
+        readonly method: "PUT";
+        readonly path: "/admin/documents/{kind}/{id}/translations/{locale}";
+    };
+    readonly reviewDocumentTranslation: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/translations/{locale}/review";
+    };
+    readonly draftDocumentTranslation: {
+        readonly method: "POST";
+        readonly path: "/admin/documents/{kind}/{id}/translations/{locale}/ai-draft";
+    };
+    readonly listSections: {
+        readonly method: "GET";
+        readonly path: "/admin/sections";
+    };
+    readonly updateSection: {
+        readonly method: "PATCH";
+        readonly path: "/admin/sections/{pageId}/{sectionId}";
+    };
+    readonly publishSection: {
+        readonly method: "POST";
+        readonly path: "/admin/sections/{pageId}/{sectionId}/publish";
+    };
+    readonly getSectionTranslation: {
+        readonly method: "GET";
+        readonly path: "/admin/sections/{pageId}/{sectionId}/translations/{locale}";
+    };
+    readonly setSectionTranslation: {
+        readonly method: "PUT";
+        readonly path: "/admin/sections/{pageId}/{sectionId}/translations/{locale}";
+    };
+    readonly reviewSectionTranslation: {
+        readonly method: "POST";
+        readonly path: "/admin/sections/{pageId}/{sectionId}/translations/{locale}/review";
+    };
+    readonly draftSectionTranslation: {
+        readonly method: "POST";
+        readonly path: "/admin/sections/{pageId}/{sectionId}/translations/{locale}/ai-draft";
+    };
+    readonly listMedia: {
+        readonly method: "GET";
+        readonly path: "/admin/media";
+    };
+    readonly uploadMedia: {
+        readonly method: "POST";
+        readonly path: "/admin/media";
+    };
+    readonly listBookings: {
+        readonly method: "GET";
+        readonly path: "/admin/bookings";
+    };
+    readonly approveBooking: {
+        readonly method: "POST";
+        readonly path: "/admin/bookings/{id}/approve";
+    };
+    readonly declineBooking: {
+        readonly method: "POST";
+        readonly path: "/admin/bookings/{id}/decline";
+    };
+    readonly cancelBooking: {
+        readonly method: "POST";
+        readonly path: "/admin/bookings/{id}/cancel";
+    };
+};
+export type DocKind = 'post' | 'page' | 'event';
+/** React Native's FormData file shape, or a Blob/File on the web and Node */
+export type UploadFile = Blob | {
+    uri: string;
+    name: string;
+    type: string;
+};
+export interface EditorRequestOptions {
+    signal?: AbortSignal;
+}
+export interface EditorClientOptions {
+    baseUrl: string;
+    /** a session from createEditorSession, or the two functions below */
+    session?: Pick<EditorSession, 'getAccessToken' | 'refresh'>;
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /** return a fresh access token, or null when the person must sign in again */
+    refresh?: () => Promise<string | null>;
+    /** called when the API rejects the device (signed out, revoked, account changed) */
+    onAuthError?: (error: AcmsError) => void;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export declare function createEditorClient(options: EditorClientOptions): {
+    me: (o?: EditorRequestOptions) => Promise<EditorMe>;
+    listDocuments: (q?: EditorListQuery, o?: EditorRequestOptions) => Promise<EditorDocumentList>;
+    createDocument: (input: EditorCreateInput, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    getDocument: (kind: DocKind, id: string, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    /** send the revision you loaded; 409 means someone saved first */
+    saveDocument: (kind: DocKind, id: string, input: EditorSaveInput, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    publishDocument: (kind: DocKind, id: string, revision: string, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    unpublishDocument: (kind: DocKind, id: string, revision: string, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    scheduleDocument: (kind: DocKind, id: string, revision: string, at: string | Date, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    discardDocument: (kind: DocKind, id: string, revision: string, o?: EditorRequestOptions) => Promise<EditorDocument>;
+    getDocumentTranslation: (kind: DocKind, id: string, locale: string, o?: EditorRequestOptions) => Promise<EditorDocumentTranslation>;
+    setDocumentTranslation: (kind: DocKind, id: string, locale: string, input: {
+        revision: string;
+        values: Record<string, string>;
+    }, o?: EditorRequestOptions) => Promise<EditorDocumentTranslation>;
+    reviewDocumentTranslation: (kind: DocKind, id: string, locale: string, input: {
+        revision: string;
+        paths?: string[];
+    }, o?: EditorRequestOptions) => Promise<EditorDocumentTranslation>;
+    draftDocumentTranslation: (kind: DocKind, id: string, locale: string, input: {
+        revision: string;
+        paths?: string[];
+        includeReviewed?: boolean;
+    }, o?: EditorRequestOptions) => Promise<EditorDocumentTranslation>;
+    listSections: (q?: EditorSectionsQuery, o?: EditorRequestOptions) => Promise<EditorSections>;
+    updateSection: (pageId: string, sectionId: string, input: {
+        revision: number;
+        data: Record<string, unknown>;
+    }, o?: EditorRequestOptions) => Promise<EditorSectionResult>;
+    publishSection: (pageId: string, sectionId: string, revision: number, o?: EditorRequestOptions) => Promise<EditorRevision>;
+    getSectionTranslation: (pageId: string, sectionId: string, locale: string, o?: EditorRequestOptions) => Promise<EditorSectionTranslation>;
+    setSectionTranslation: (pageId: string, sectionId: string, locale: string, input: {
+        revision: number;
+        values: Record<string, string>;
+    }, o?: EditorRequestOptions) => Promise<EditorSectionTranslation>;
+    reviewSectionTranslation: (pageId: string, sectionId: string, locale: string, input: {
+        revision: number;
+        paths?: string[];
+    }, o?: EditorRequestOptions) => Promise<EditorSectionTranslation>;
+    draftSectionTranslation: (pageId: string, sectionId: string, locale: string, input: {
+        revision: number;
+        paths?: string[];
+        includeReviewed?: boolean;
+    }, o?: EditorRequestOptions) => Promise<EditorSectionTranslation>;
+    listMedia: (q?: EditorMediaQuery, o?: EditorRequestOptions) => Promise<EditorMediaList>;
+    /** compress images on the device first (same limits as the admin: 30 MB images, 25 MB documents) */
+    uploadMedia: (file: UploadFile, meta?: {
+        name?: string;
+        alt?: string;
+        width?: number;
+        height?: number;
+    }, o?: EditorRequestOptions) => Promise<EditorMedia>;
+    listBookings: (q?: EditorBookingsQuery, o?: EditorRequestOptions) => Promise<EditorBookingList>;
+    approveBooking: (id: string, input?: {
+        message?: string;
+    }, o?: EditorRequestOptions) => Promise<EditorBooking>;
+    declineBooking: (id: string, input?: {
+        message?: string;
+    }, o?: EditorRequestOptions) => Promise<EditorBooking>;
+    cancelBooking: (id: string, input?: {
+        message?: string;
+    }, o?: EditorRequestOptions) => Promise<EditorBooking>;
+};
+export type EditorClient = ReturnType<typeof createEditorClient>;