@upvoiced/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joao Pereira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# @upvoiced/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed TypeScript client for the [UpVoiced](https://upvoiced.com) API. Every path, parameter,
+request body and response type is generated from the API's OpenAPI 3.1 document
+(`/openapi.json`), and a thin `fetch` wrapper adds the API key, `X-Workspace`,
+`Idempotency-Key`, retries, cursor pagination and typed errors. No runtime dependencies: it needs
+only a standard `fetch` (Node 22+, Deno, Bun, Cloudflare Workers). API keys are secrets: use them
+from your server, never from a browser.
+
+```sh
+npm install @upvoiced/sdk
+```
+
+## Quick start
+
+The initial `0.1.0` preview uses the approved staging API contract. Set `baseUrl` explicitly;
+publishing the SDK does not certify production API availability. Use a key from your staging
+workspace. The client retains its production-origin default for later production use.
+
+```ts
+import { UpVoiced, UpVoicedError } from '@upvoiced/sdk';
+
+const upvoiced = new UpVoiced({
+  baseUrl: 'https://api-staging.upvoiced.com',
+  apiKey: process.env.UPVOICED_API_KEY, // from the staging workspace's Settings → API keys
+  workspace: process.env.UPVOICED_WORKSPACE_ID, // sent as X-Workspace
+});
+
+const { items: boards } = await upvoiced.get('/v1/boards');
+
+const post = await upvoiced.post('/v1/posts', {
+  body: { board_id: boards[0].id, title: 'Dark mode', body_md: 'From our CRM.' },
+});
+
+await upvoiced.patch('/v1/posts/{id}', { path: { id: post.id }, body: { title: 'Dark mode' } });
+
+for await (const item of upvoiced.paginate('/v1/posts', { query: { sort: 'top', limit: 100 } })) {
+  console.log(item.title, item.vote_count);
+}
+```
+
+Paths are the API's own (`/v1/posts/{id}`), so the [API reference](https://docs.upvoiced.com)
+and `curl` examples map one to one. Your editor completes paths, query parameters and bodies,
+and TypeScript rejects a missing path parameter, an unknown field or a wrong enum value.
+
+## Client options
+
+| Option            | Default                    | Meaning                                                                  |
+| ----------------- | -------------------------- | ------------------------------------------------------------------------ |
+| `apiKey`          | —                          | API key, sent as `Authorization: Bearer`. Omit for `/v1/public/*` reads. |
+| `workspace`       | —                          | Workspace id (`X-Workspace`); a workspace slug for `/v1/public/*`.       |
+| `baseUrl`         | `https://api.upvoiced.com` | API origin.                                                              |
+| `maxRetries`      | `2`                        | Retries after 429, 502/503/504 and network errors (see below).           |
+| `maxRetryDelayMs` | `60000`                    | A `Retry-After` longer than this is not waited for; the error is thrown. |
+| `fetch`           | global `fetch`             | Custom fetch (proxies, tests).                                           |
+| `headers`         | —                          | Extra headers on every request.                                          |
+
+Every call also accepts `workspace`, `idempotencyKey`, `headers` and an `AbortSignal` (`signal`).
+
+### Keys, scopes and workspaces
+
+Keys carry the `read`, `write` or `admin` scope. A workspace-bound key works on its workspace
+only; an operator-wide key ("all workspaces I admin") picks one per call:
+
+```ts
+const other = upvoiced.withWorkspace(otherWorkspaceId);
+await upvoiced.get('/v1/workspace', { workspace: otherWorkspaceId });
+```
+
+Key management, workspace creation and other session-only routes refuse API keys
+(`403 session_required`). Each key may send 600 GET and 120 other requests per minute.
+
+### Idempotency and retries
+
+The API deduplicates POSTs by `Idempotency-Key` for 24 hours. With retries on (the default),
+the client sends a generated key on every POST and reuses it on each retry, so a POST whose
+response was lost is answered from the first attempt instead of being applied twice. Pass your
+own `idempotencyKey` to make a POST safe across process restarts too.
+
+The client retries a 429 for any method (the request was refused before it ran), and a 502, 503,
+504 or network error for GET, PUT, DELETE and POST. It never retries a PATCH after a 5xx. It
+waits for `Retry-After` when present, else an exponential backoff with jitter.
+
+### Errors
+
+Every non-2xx response throws an `UpVoicedError` with the API's error shape:
+
+```ts
+try {
+  await upvoiced.post('/v1/posts', { body: { board_id, title: '' } });
+} catch (error) {
+  if (error instanceof UpVoicedError) {
+    error.status; // 400
+    error.code; // 'invalid_request' | 'insufficient_scope' | 'not_found' | 'rate_limited' | …
+    error.details; // [{ path: 'title', code: 'too_small' }]
+    error.retryAfter; // seconds, for 429/503
+    error.idempotencyKey; // reuse it to retry the same POST later
+  }
+}
+```
+
+### Status and headers
+
+`request()` resolves with the status and headers as well as the data:
+
+```ts
+const { data, status, headers } = await upvoiced.request('post', '/v1/posts', {
+  body,
+  idempotencyKey: 'import-2026-10-22-row-17',
+});
+headers.get('idempotent-replayed'); // 'true' when answered from an earlier attempt
+```
+
+### Types
+
+The generated OpenAPI types are exported for your own code:
+
+```ts
+import type { Operation, RequestBody, ResponseData, paths } from '@upvoiced/sdk';
+
+type Post = ResponseData<Operation<'/v1/posts/{id}', 'get'>>;
+type NewPost = RequestBody<Operation<'/v1/posts', 'post'>>;
+```
+
+## Versioning
+
+`/v1` changes are additive only (breaking changes go to `/v2` with a 12-month overlap). The
+package version follows UpVoiced releases; each release is regenerated from that release's API.
+
+## Development (UpVoiced monorepo)
+
+`src/generated/schema.ts` is generated, never edited: after changing API routes run
+`pnpm --filter @upvoiced/sdk generate` (needs a built `@upvoiced/api`). The SDK's tests fail
+while the committed file differs from the API. See ADR-0067.

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { ApiResponse, HttpMethod, Operation, PageItem, PaginatedPath, PathsWith, RequestArgs, ResponseData } from './types.js';
+/** Production API origin (ADR-0015). Staging: https://api-staging.upvoiced.com */
+export declare const defaultBaseUrl = "https://api.upvoiced.com";
+export declare const defaultMaxRetries = 2;
+export declare const defaultMaxRetryDelayMs = 60000;
+export interface ClientOptions {
+    /** API key (`uv_live_…` / `uv_test_…`), sent as `Authorization: Bearer`. Omit for public reads. */
+    apiKey?: string;
+    /** Workspace id (X-Workspace) for operator routes; a slug for `/v1/public/*`. */
+    workspace?: string;
+    /** API origin; defaults to production. */
+    baseUrl?: string;
+    /** fetch implementation (Node 22+, browsers, Workers and Deno have one). */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /**
+     * Retries after 429 (any method; the API refuses before running the handler), and after
+     * 502/503/504 or a network error for GET, PUT, DELETE and POST (POSTs always carry an
+     * Idempotency-Key when retries are on). PATCH is never retried after a 5xx. Default 2.
+     */
+    maxRetries?: number;
+    /** A Retry-After longer than this is not waited for: the error is thrown. Default 60 s. */
+    maxRetryDelayMs?: number;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+}
+/**
+ * P2-015 (ADR-0067, INT-004): thin typed client over `fetch`. Paths, parameters, bodies and
+ * responses are typed from the generated OpenAPI `paths`; at runtime it only adds credentials,
+ * X-Workspace, Idempotency-Key, retries, cursor pagination and the error shape.
+ *
+ * ```ts
+ * const upvoiced = new UpVoiced({ apiKey: process.env.UPVOICED_API_KEY, workspace });
+ * const post = await upvoiced.post('/v1/posts', { body: { board_id, title: 'Dark mode' } });
+ * for await (const item of upvoiced.paginate('/v1/posts', { query: { board: board_id } })) {}
+ * ```
+ */
+export declare class UpVoiced {
+    #private;
+    constructor(options?: ClientOptions);
+    /** A client with the same settings acting on another workspace (operator-wide keys). */
+    withWorkspace(workspace: string): UpVoiced;
+    get<P extends PathsWith<'get'>>(path: P, ...args: RequestArgs<Operation<P, 'get'>>): Promise<ResponseData<Operation<P, "get">>>;
+    post<P extends PathsWith<'post'>>(path: P, ...args: RequestArgs<Operation<P, 'post'>>): Promise<ResponseData<Operation<P, "post">>>;
+    put<P extends PathsWith<'put'>>(path: P, ...args: RequestArgs<Operation<P, 'put'>>): Promise<ResponseData<Operation<P, "put">>>;
+    patch<P extends PathsWith<'patch'>>(path: P, ...args: RequestArgs<Operation<P, 'patch'>>): Promise<ResponseData<Operation<P, "patch">>>;
+    delete<P extends PathsWith<'delete'>>(path: P, ...args: RequestArgs<Operation<P, 'delete'>>): Promise<ResponseData<Operation<P, "delete">>>;
+    /** Like the method helpers, but resolves with `{ data, status, headers }`. */
+    request<M extends HttpMethod, P extends PathsWith<M>>(method: M, path: P, ...args: RequestArgs<Operation<P, M>>): Promise<ApiResponse<ResponseData<Operation<P, M>>>>;
+    /**
+     * Every item of a cursor-paginated list (`{ items, next_cursor }`), fetching pages lazily.
+     * `query.limit` is the page size; stop iterating to stop fetching.
+     */
+    paginate<P extends PaginatedPath>(path: P, ...args: RequestArgs<Operation<P, 'get'>>): AsyncGenerator<PageItem<P>, void, undefined>;
+}

package/dist/client.js

@@ -0,0 +1,209 @@
+import { UpVoicedError, errorShape, parseRetryAfter } from './errors.js';
+/** Production API origin (ADR-0015). Staging: https://api-staging.upvoiced.com */
+export const defaultBaseUrl = 'https://api.upvoiced.com';
+export const defaultMaxRetries = 2;
+export const defaultMaxRetryDelayMs = 60_000;
+const methods = ['get', 'put', 'post', 'patch', 'delete'];
+const retryableStatus = new Set([502, 503, 504]);
+function expandPath(template, values) {
+    return template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = values?.[name];
+        if (value === undefined || value === '')
+            throw new TypeError(`Missing path parameter "${name}" for ${template}.`);
+        return encodeURIComponent(String(value));
+    });
+}
+const queryValue = (item) => item instanceof Date
+    ? item.toISOString()
+    : typeof item === 'string'
+        ? item
+        : typeof item === 'number' || typeof item === 'boolean' || typeof item === 'bigint'
+            ? String(item)
+            : JSON.stringify(item);
+function searchOf(query) {
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(query ?? {})) {
+        if (value === undefined || value === null)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            search.append(name, queryValue(item));
+    }
+    const text = search.toString();
+    return text ? `?${text}` : '';
+}
+async function bodyOf(response) {
+    const text = await response.text();
+    if (text === '')
+        return undefined;
+    const type = response.headers.get('content-type') ?? '';
+    if (/\bjson\b/i.test(type)) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** Exponential backoff with jitter: ~0.5 s, 1 s, 2 s … capped at 8 s. */
+const backoff = (attempt) => Math.min(8000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
+/**
+ * P2-015 (ADR-0067, INT-004): thin typed client over `fetch`. Paths, parameters, bodies and
+ * responses are typed from the generated OpenAPI `paths`; at runtime it only adds credentials,
+ * X-Workspace, Idempotency-Key, retries, cursor pagination and the error shape.
+ *
+ * ```ts
+ * const upvoiced = new UpVoiced({ apiKey: process.env.UPVOICED_API_KEY, workspace });
+ * const post = await upvoiced.post('/v1/posts', { body: { board_id, title: 'Dark mode' } });
+ * for await (const item of upvoiced.paginate('/v1/posts', { query: { board: board_id } })) {}
+ * ```
+ */
+export class UpVoiced {
+    #options;
+    #baseUrl;
+    #maxRetries;
+    #maxRetryDelayMs;
+    constructor(options = {}) {
+        const base = new URL(options.baseUrl ?? defaultBaseUrl);
+        if (base.protocol !== 'https:' && base.protocol !== 'http:')
+            throw new TypeError(`baseUrl must be http(s), got ${base.protocol}`);
+        const maxRetries = options.maxRetries ?? defaultMaxRetries;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0)
+            throw new TypeError('maxRetries must be a non-negative integer.');
+        const maxRetryDelayMs = options.maxRetryDelayMs ?? defaultMaxRetryDelayMs;
+        if (!(maxRetryDelayMs >= 0))
+            throw new TypeError('maxRetryDelayMs must be ≥ 0.');
+        this.#options = options;
+        this.#baseUrl = base.href.replace(/\/+$/, '');
+        this.#maxRetries = maxRetries;
+        this.#maxRetryDelayMs = maxRetryDelayMs;
+    }
+    /** A client with the same settings acting on another workspace (operator-wide keys). */
+    withWorkspace(workspace) {
+        return new UpVoiced({ ...this.#options, workspace });
+    }
+    get(path, ...args) {
+        return this.#data('get', path, args[0]);
+    }
+    post(path, ...args) {
+        return this.#data('post', path, args[0]);
+    }
+    put(path, ...args) {
+        return this.#data('put', path, args[0]);
+    }
+    patch(path, ...args) {
+        return this.#data('patch', path, args[0]);
+    }
+    delete(path, ...args) {
+        return this.#data('delete', path, args[0]);
+    }
+    /** Like the method helpers, but resolves with `{ data, status, headers }`. */
+    request(method, path, ...args) {
+        return this.#send(method, path, args[0]);
+    }
+    /**
+     * Every item of a cursor-paginated list (`{ items, next_cursor }`), fetching pages lazily.
+     * `query.limit` is the page size; stop iterating to stop fetching.
+     */
+    async *paginate(path, ...args) {
+        const options = (args[0] ?? {});
+        let cursor = options.query?.['cursor'];
+        for (;;) {
+            const query = { ...options.query, ...(cursor ? { cursor } : {}) };
+            const { data } = await this.#send('get', path, { ...options, query });
+            const page = data;
+            yield* page.items;
+            if (!page.next_cursor)
+                return;
+            if (page.next_cursor === cursor)
+                throw new Error(`Pagination of ${path} did not advance (cursor repeated).`);
+            cursor = page.next_cursor;
+        }
+    }
+    async #data(method, path, options) {
+        return (await this.#send(method, path, options)).data;
+    }
+    async #send(method, template, raw) {
+        if (!methods.includes(method))
+            throw new TypeError(`Unsupported method ${method}.`);
+        const options = (raw ?? {});
+        const path = expandPath(template, options.path);
+        const url = `${this.#baseUrl}${path}${searchOf(options.query)}`;
+        const headers = new Headers({ ...this.#options.headers, ...options.headers });
+        headers.set('accept', 'application/json');
+        if (this.#options.apiKey)
+            headers.set('authorization', `Bearer ${this.#options.apiKey}`);
+        const workspace = options.workspace ?? this.#options.workspace;
+        if (workspace)
+            headers.set('x-workspace', workspace);
+        let body;
+        if (options.body !== undefined) {
+            body = JSON.stringify(options.body);
+            headers.set('content-type', 'application/json');
+        }
+        const idempotencyKey = method === 'post'
+            ? (options.idempotencyKey ?? (this.#maxRetries > 0 ? crypto.randomUUID() : null))
+            : null;
+        if (idempotencyKey)
+            headers.set('idempotency-key', idempotencyKey);
+        // A 5xx or a lost connection may follow a write that happened: retry only when repeating
+        // it is harmless (GET/PUT/DELETE, or a POST the API deduplicates by its Idempotency-Key).
+        const repeatable = method !== 'patch' && (method !== 'post' || idempotencyKey !== null);
+        const fetcher = this.#options.fetch ?? ((input, init) => fetch(input, init));
+        const init = {
+            method: method.toUpperCase(),
+            headers,
+            ...(body !== undefined ? { body } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        };
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await fetcher(url, init);
+            }
+            catch (error) {
+                if (options.signal?.aborted || !repeatable || attempt >= this.#maxRetries)
+                    throw error;
+                await sleep(backoff(attempt), options.signal);
+                continue;
+            }
+            const data = await bodyOf(response);
+            if (response.ok)
+                return { data, status: response.status, headers: response.headers };
+            const retryAfter = parseRetryAfter(response.headers.get('retry-after'));
+            const retryable = response.status === 429 || (retryableStatus.has(response.status) && repeatable);
+            const delay = retryAfter === null ? backoff(attempt) : retryAfter * 1000;
+            if (retryable && attempt < this.#maxRetries && delay <= this.#maxRetryDelayMs) {
+                await sleep(delay, options.signal);
+                continue;
+            }
+            throw new UpVoicedError({
+                status: response.status,
+                ...errorShape(response.status, response.statusText, data),
+                method: method.toUpperCase(),
+                path,
+                retryAfter,
+                idempotencyKey,
+                body: data,
+            });
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/** One failed field or rule, as the API reports it in `error.details`. */
+export interface ErrorDetail {
+    path: string;
+    code: string;
+}
+export interface UpVoicedErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    details: readonly ErrorDetail[];
+    method: string;
+    path: string;
+    retryAfter: number | null;
+    idempotencyKey: string | null;
+    body: unknown;
+}
+/**
+ * P2-015 (ADR-0067): every non-2xx answer becomes an UpVoicedError carrying the API's error
+ * shape `{ error: { code, message, details? } }` (spec 05). Bodies that are not that shape
+ * (a proxy's HTML 502) get `code: "http_<status>"`.
+ */
+export declare class UpVoicedError extends Error {
+    readonly name = "UpVoicedError";
+    /** HTTP status. */
+    readonly status: number;
+    /** Stable machine-readable code (`insufficient_scope`, `not_found`, `rate_limited`, …). */
+    readonly code: string;
+    readonly details: readonly ErrorDetail[];
+    readonly method: string;
+    /** Request path without the query string. */
+    readonly path: string;
+    /** Seconds from `Retry-After` (429/503), else null. */
+    readonly retryAfter: number | null;
+    /** The Idempotency-Key the request carried; reuse it to retry the same POST safely. */
+    readonly idempotencyKey: string | null;
+    /** The parsed (or raw text) response body. */
+    readonly body: unknown;
+    constructor(init: UpVoicedErrorInit);
+}
+/** Reads `{ error: { code, message, details? } }`, tolerating anything else. */
+export declare function errorShape(status: number, statusText: string, body: unknown): Pick<UpVoicedErrorInit, 'code' | 'message' | 'details'>;
+/** `Retry-After` as seconds: delta-seconds or an HTTP date; null when absent or invalid. */
+export declare function parseRetryAfter(value: string | null, now?: number): number | null;

package/dist/errors.js

@@ -0,0 +1,64 @@
+/**
+ * P2-015 (ADR-0067): every non-2xx answer becomes an UpVoicedError carrying the API's error
+ * shape `{ error: { code, message, details? } }` (spec 05). Bodies that are not that shape
+ * (a proxy's HTML 502) get `code: "http_<status>"`.
+ */
+export class UpVoicedError extends Error {
+    name = 'UpVoicedError';
+    /** HTTP status. */
+    status;
+    /** Stable machine-readable code (`insufficient_scope`, `not_found`, `rate_limited`, …). */
+    code;
+    details;
+    method;
+    /** Request path without the query string. */
+    path;
+    /** Seconds from `Retry-After` (429/503), else null. */
+    retryAfter;
+    /** The Idempotency-Key the request carried; reuse it to retry the same POST safely. */
+    idempotencyKey;
+    /** The parsed (or raw text) response body. */
+    body;
+    constructor(init) {
+        super(init.message);
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        this.method = init.method;
+        this.path = init.path;
+        this.retryAfter = init.retryAfter;
+        this.idempotencyKey = init.idempotencyKey;
+        this.body = init.body;
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const detailsOf = (value) => Array.isArray(value)
+    ? value.flatMap((item) => isRecord(item) && typeof item['path'] === 'string' && typeof item['code'] === 'string'
+        ? [{ path: item['path'], code: item['code'] }]
+        : [])
+    : [];
+/** Reads `{ error: { code, message, details? } }`, tolerating anything else. */
+export function errorShape(status, statusText, body) {
+    const error = isRecord(body) ? body['error'] : undefined;
+    if (isRecord(error) && typeof error['code'] === 'string')
+        return {
+            code: error['code'],
+            message: typeof error['message'] === 'string' ? error['message'] : error['code'],
+            details: detailsOf(error['details']),
+        };
+    return {
+        code: `http_${String(status)}`,
+        message: statusText || `HTTP ${String(status)}`,
+        details: [],
+    };
+}
+/** `Retry-After` as seconds: delta-seconds or an HTTP date; null when absent or invalid. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value === null || value.trim() === '')
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}