@acms-subir/client 0.1.0

package/dist/index.js

@@ -0,0 +1,244 @@
+import { AcmsError } from './errors.js';
+export { AcmsError, isAcmsError } from './errors.js';
+export * from './editor.js';
+// The contract test compares this registry with the core OpenAPI generator.
+export const endpoints = {
+    site: { method: 'GET', path: '/site' }, theme: { method: 'GET', path: '/theme' },
+    home: { method: 'GET', path: '/pages/home' }, page: { method: 'GET', path: '/pages/{slug}' },
+    content: { method: 'GET', path: '/content' }, contentById: { method: 'GET', path: '/content/{id}' },
+    events: { method: 'GET', path: '/events' }, calendars: { method: 'GET', path: '/calendars' },
+    resources: { method: 'GET', path: '/resources' }, availability: { method: 'GET', path: '/availability' },
+    book: { method: 'POST', path: '/bookings' }, openapi: { method: 'GET', path: '/openapi.json' },
+    // push notifications (only when the site enables push; 404 otherwise)
+    registerDevice: { method: 'POST', path: '/devices' }, updateDevice: { method: 'PUT', path: '/devices/{token}' },
+    unregisterDevice: { method: 'DELETE', path: '/devices/{token}' }, pushTopics: { method: 'GET', path: '/push/topics' },
+};
+const localized = new Set(['home', 'page', 'content', 'contentById', 'events']);
+function uuid() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const n = Math.floor(Math.random() * 16);
+        return (c === 'x' ? n : (n & 3) | 8).toString(16);
+    });
+}
+function abortable(work, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { cleanup(); reject(signal.reason); };
+        const cleanup = () => signal.removeEventListener('abort', abort);
+        work.then(v => { cleanup(); resolve(v); }, e => { cleanup(); reject(e); });
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+    });
+}
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); reject(signal.reason); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, Math.min(ms, 2_147_483_647));
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+    });
+}
+const retrySeconds = (value) => {
+    if (!value)
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, (date - Date.now()) / 1000) : undefined;
+};
+export function createClient(options) {
+    const base = new URL(options.baseUrl);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new TypeError('baseUrl must be an HTTP(S) URL without credentials, query or fragment.');
+    const prefix = base.pathname.replace(/\/+$/, '');
+    base.pathname = prefix.endsWith('/api/v1') ? prefix : prefix + '/api/v1';
+    const baseUrl = base.href.replace(/\/$/, '');
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!fetcher)
+        throw new TypeError('A fetch implementation is required.');
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+        throw new TypeError('timeoutMs must be a positive finite timer duration.');
+    const memory = new Map();
+    const cache = options.cache === false ? false : !options.cache || options.cache === 'memory' ? {
+        get: url => memory.get(url), set: (url, entry) => { if (entry)
+            memory.set(url, entry);
+        else
+            memory.delete(url); },
+    } : options.cache;
+    const defaultHeaders = new Headers(options.headers);
+    async function request(name, opts = {}, query = {}, param, payload, key) {
+        const endpoint = endpoints[name];
+        const path = endpoint.path.replace(/\{\w+\}/, () => {
+            if (!param || param.split('/').some(p => p === '.' || p === '..'))
+                throw new TypeError('A nonempty identifier without dot segments is required.');
+            return name === 'page' ? param.split('/').map(encodeURIComponent).join('/') : encodeURIComponent(param);
+        });
+        const url = new URL(baseUrl + path);
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const locale = opts.locale ?? options.locale;
+        if (localized.has(name) && locale !== undefined)
+            url.searchParams.set('locale', locale);
+        const controller = new AbortController();
+        const abort = () => controller.abort(new AcmsError(0, 'aborted', 'Request aborted.', undefined, undefined, key));
+        if (opts.signal?.aborted)
+            abort();
+        else
+            opts.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => controller.abort(new AcmsError(0, 'timeout', 'Request timed out.', undefined, undefined, key)), timeoutMs);
+        const signal = controller.signal;
+        const cacheable = endpoint.method === 'GET' && name !== 'availability' && cache;
+        try {
+            if (signal.aborted)
+                throw signal.reason;
+            const cached = cacheable ? await abortable(Promise.resolve(cacheable.get(url.href)), signal) : undefined;
+            const headers = new Headers(defaultHeaders);
+            headers.set('Accept', 'application/json');
+            // Conditional requests are owned by this cache, including when caching is disabled.
+            headers.delete('If-None-Match');
+            if (cached)
+                headers.set('If-None-Match', cached.etag);
+            if (key)
+                headers.set('Idempotency-Key', key);
+            if (payload !== undefined)
+                headers.set('Content-Type', 'application/json');
+            const body = payload !== undefined ? JSON.stringify(payload) : undefined;
+            for (let attempt = 0;; attempt++) {
+                let res;
+                try {
+                    res = await abortable(fetcher(url.href, { method: endpoint.method, headers, body, signal, credentials: 'omit' }), signal);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw signal.reason;
+                    if (attempt < 2) {
+                        await pause(250 * 2 ** attempt, signal);
+                        continue;
+                    }
+                    throw new AcmsError(0, 'network_error', error instanceof Error ? error.message : 'Network request failed.', undefined, undefined, key);
+                }
+                const retryAfter = retrySeconds(res.headers.get('Retry-After'));
+                if ((res.status === 429 || res.status >= 500) && attempt < 2) {
+                    // Release the response stream before retrying.
+                    if (res.body)
+                        await abortable(res.body.cancel().catch(() => { }), signal);
+                    await pause(Math.max(250 * 2 ** attempt, (retryAfter ?? 0) * 1000), signal);
+                    continue;
+                }
+                if (res.status === 304 && cached)
+                    return cached.body;
+                let json;
+                try {
+                    json = await abortable(res.json(), signal);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw signal.reason;
+                    // fetch can succeed before a network failure interrupts the body stream.
+                    if (error instanceof TypeError) {
+                        if (attempt < 2) {
+                            await pause(250 * 2 ** attempt, signal);
+                            continue;
+                        }
+                        throw new AcmsError(0, 'network_error', error.message, undefined, undefined, key);
+                    }
+                    throw new AcmsError(res.status, res.ok ? 'invalid_response' : 'http_error', `HTTP ${res.status}: expected a JSON response.`, retryAfter, undefined, key);
+                }
+                if (!res.ok)
+                    throw new AcmsError(res.status, json?.error?.code ?? 'http_error', json?.error?.message ?? `HTTP ${res.status}`, retryAfter, json?.error?.issues, key);
+                if (name !== 'openapi' && (json?.version !== 1 || !Object.prototype.hasOwnProperty.call(json, 'data')))
+                    throw new AcmsError(res.status, 'invalid_response', 'Expected an ACMS v1 response.', undefined, undefined, key);
+                const data = name === 'openapi' ? json : json.data;
+                if (cacheable) {
+                    const etag = res.headers.get('ETag');
+                    await abortable(Promise.resolve(cacheable.set(url.href, etag && !/\bno-store\b/i.test(res.headers.get('Cache-Control') ?? '') ? { etag, body: data } : null)), signal);
+                }
+                return data;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', abort);
+        }
+    }
+    const paging = (o) => ({ page: o.page ?? o.cursor, limit: o.limit });
+    async function* iterate(load, field, opts) {
+        let page = opts.page ?? opts.cursor ?? 1;
+        const seen = new Set();
+        while (!seen.has(page)) {
+            seen.add(page);
+            const result = await load({ ...opts, page });
+            for (const item of result[field]) {
+                if (opts.signal?.aborted)
+                    throw new AcmsError(0, 'aborted', 'Request aborted.');
+                yield item;
+            }
+            if (result.pagination.nextPage === null)
+                return;
+            page = result.pagination.nextPage;
+        }
+        throw new AcmsError(0, 'invalid_response', 'Pagination repeated a page.');
+    }
+    const content = (o = {}) => request('content', o, { ...paging(o), kind: o.kind, collection: o.collection });
+    const posts = async (o = {}) => {
+        const result = await content({ ...o, kind: 'post' });
+        return { ...result, items: result.items.filter(p => !o.tag || p.tags.includes(o.tag)) };
+    };
+    const pages = (o = {}) => content({ ...o, kind: 'page' });
+    const events = (o = {}) => request('events', o, { ...paging(o), from: o.from, to: o.to, calendar: o.calendar, q: o.q });
+    const resources = (o = {}) => request('resources', o, paging(o));
+    const paginate = {
+        content: (o = {}) => iterate(content, 'items', o),
+        posts: (o = {}) => iterate(posts, 'items', o),
+        pages: (o = {}) => iterate(pages, 'items', o),
+        events: (o = {}) => iterate(events, 'occurrences', o),
+        resources: (o = {}) => iterate(resources, 'resources', o),
+    };
+    return {
+        site: (o = {}) => request('site', o),
+        theme: (o = {}) => request('theme', o),
+        home: (o = {}) => request('home', o),
+        page: (slug, o = {}) => request('page', o, {}, slug),
+        content, posts, pages, events, resources, paginate,
+        contentById: (id, o = {}) => request('contentById', o, { kind: o.kind }, id),
+        async post(slug, o = {}) {
+            for await (const item of paginate.posts(o))
+                if (item.slug === slug)
+                    return request('contentById', o, { kind: 'post' }, item.id);
+            throw new AcmsError(404, 'not_found', 'Post not found.');
+        },
+        /** Searches occurrences in the supplied window (server default: next 30 UTC days). */
+        async event(slug, o = {}) {
+            for await (const item of paginate.events(o))
+                if (item.event.slug === slug)
+                    return item.event;
+            throw new AcmsError(404, 'not_found', 'Event not found in the requested window.');
+        },
+        async resource(slug, o = {}) {
+            for await (const item of paginate.resources(o))
+                if (item.slug === slug)
+                    return item;
+            throw new AcmsError(404, 'not_found', 'Resource not found.');
+        },
+        calendars: (o = {}) => request('calendars', o),
+        availability: (o) => request('availability', o, { resource: o.resource, link: o.link, from: o.from, days: o.days, minutes: o.minutes }),
+        book: (o) => {
+            const { locale, signal, idempotencyKey, ...body } = o;
+            const key = idempotencyKey ?? defaultHeaders.get('Idempotency-Key') ?? uuid();
+            return request('book', { locale, signal }, {}, undefined, body, key);
+        },
+        openapi: (o = {}) => request('openapi', o),
+        registerDevice: (input, o = {}) => request('registerDevice', o, {}, undefined, input),
+        updateDevice: (token, input, o = {}) => request('updateDevice', o, {}, token, input),
+        unregisterDevice: (token, o = {}) => request('unregisterDevice', o, {}, token),
+        pushTopics: (o = {}) => request('pushTopics', o),
+        withLocale: (locale) => createClient({ ...options, locale, cache, headers: defaultHeaders }),
+    };
+}