@karmaniverous/jeeves-meta-sdk 0.0.0-stage → 0.1.0-0

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @karmaniverous/jeeves-meta-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 [jeeves-meta](https://github.com/karmaniverous/jeeves-meta) HTTP API: metas, synthesis, the queue, previews, seeding, unlocking, status and config.
+
+The client is generated from jeeves-meta's endpoint catalog (`META_CATALOG` in `@karmaniverous/jeeves-meta-core`), so every method, input and response type matches the routes the service registers. Requests are validated before they are sent and responses are parsed on arrival.
+
+## Install
+
+```bash
+npm install @karmaniverous/jeeves-meta-sdk
+```
+
+Requires Node.js 24.22.2 or later.
+
+## Usage
+
+```typescript
+import { createMetaClient, isMetaError } from '@karmaniverous/jeeves-meta-sdk';
+
+const meta = createMetaClient({ baseUrl: 'http://127.0.0.1:1938' });
+
+const { summary } = await meta.listMetas({ hasError: 'true' });
+const detail = await meta.metaDetail({ path: 'j:/domains/projects/x' });
+
+try {
+  const queued = await meta.synthesize({ path: 'j:/domains/projects/x' });
+  console.log(queued.status, summary.errors, detail.owedPhase);
+} catch (error) {
+  if (isMetaError(error) && error.code === 'META_WATCHER_UNAVAILABLE') {
+    console.log(`${error.message} (HTTP ${String(error.status)})`);
+  } else throw error;
+}
+```
+
+Every method is named after its catalog entry and takes one input object holding the entry's path parameters, query fields and body fields, flat. Query fields are strings, as on the wire (`hasError: 'true'`):
+
+| Method | Route | Input |
+| --- | --- | --- |
+| `status` | `GET /status` | none |
+| `listMetas` | `GET /metas` | `{ pathPrefix?, hasError?, staleHours?, neverSynthesized?, locked?, disabled?, fields? }` |
+| `metaDetail` | `GET /metas/:path` | `{ path, fields?, includeArchive? }` |
+| `updateMeta` | `PATCH /metas/:path` | `{ path, _steer?, _emphasis?, _depth?, _crossRefs?, _disabled? }` (`null` removes) |
+| `synthesize` | `POST /synthesize` | `{ path? }` |
+| `abort` | `POST /synthesize/abort` | none |
+| `preview` | `GET /preview` | `{ path? }` |
+| `seed` | `POST /seed` | `{ path, crossRefs?, steer? }` |
+| `unlock` | `POST /unlock` | `{ path }` |
+| `config` | `GET /config` | `{ path? }` (JSONPath) |
+| `configApply` | `POST /config/apply` | `{ patch, replace? }` |
+| `queue` | `GET /queue` | none |
+| `queueClear` | `POST /queue/clear` | none |
+
+`path` is a meta's owner path or `.meta/` path; the client encodes it once in the URL, so spaces, `/`, `:` and `%` are safe. The request and response types are exported (`MetaInput<'listMetas'>`, `MetaResponse<'synthesize'>`, `MetaHealth`, ...). Responses are parsed against the schemas of the meta-core version the SDK was built with: fields a newer jeeves-meta adds are dropped until you upgrade the SDK.
+
+`synthesize` only enqueues: it answers at once (`202` queued, or `200` skipped when nothing is owed). Follow progress with `status` or `queue`.
+
+## Timeouts
+
+- Every call times out after **120 s** by default (`timeoutMs` option).
+- Any call can override its timeout: `meta.preview({}, { timeoutMs: 10_000 })`.
+
+The SDK never retries.
+
+## Errors
+
+Every failure is a `MetaError`. Branch on `code`, never on `message`:
+
+| `code` | `status` | When |
+| --- | --- | --- |
+| the body's `code` | the HTTP status | jeeves-meta answered non-2xx with a code (`META_*`, `JEEVES_*`, `FST_ERR_*`, below); `message` is the body's `message`, `body` the whole body and `responseText` the body as received |
+| `http_<status>` | the HTTP status | jeeves-meta answered non-2xx without a code: a masked 500 (an unexpected failure; the cause is in the service log), an unknown route, or a body that isn't jeeves-meta's (a proxy's page) |
+| `invalid_request` | `0` | the input failed the entry's schema; nothing was sent (`issues`) |
+| `invalid_response` | 2xx | the response was not JSON or did not match the entry's schema |
+| `timeout` | `0` | no response within the call's timeout |
+| `network_error` | `0` | the request failed (service not running, DNS, ...) |
+| `invalid_options` | `0` | `createMetaClient` options are invalid |
+
+A non-2xx body is always Fastify's standard error body, `{ statusCode, code?, error, message }`. jeeves-meta's own codes (`META_ERROR_CODES` and `META_ERROR_STATUS`, exported here and by `@karmaniverous/jeeves-meta-core`):
+
+| `code` | Status | When |
+| --- | --- | --- |
+| `META_INVALID_JSONPATH` | 400 | `config` with a `path` that is not valid JSONPath |
+| `META_NOT_FOUND` | 404 | no meta at the path given to `metaDetail`, `updateMeta` or `preview` |
+| `META_ALREADY_EXISTS` | 409 | `seed` where a `.meta/` already exists |
+| `META_NOT_LOCKED` | 409 | `unlock` where there is no lock file |
+| `META_CONFIG_UNAVAILABLE` | 500 | `configApply` on a service started without a config file |
+| `META_WATCHER_UNAVAILABLE` | 503 | `listMetas`, `preview` or `synthesize` could not reach jeeves-watcher; retry later |
+| `META_NOT_READY` | 503 | the service is still starting; retry shortly (`config` and `configApply` are served during start-up) |
+
+Also: `FST_ERR_VALIDATION` (400) when a request fails the catalog's schemas (the SDK checks input first, so you see `invalid_request` instead), jeeves' `JEEVES_CONFIG_INVALID` from `configApply`, and `JEEVES_RESPONSE_VALIDATION` (500) if jeeves-meta's own response fails its schema. No error carries `Retry-After`.
+
+## OpenAPI
+
+The service serves its OpenAPI 3.1 document at `GET /openapi.json`; the same document ships as `@karmaniverous/jeeves-meta-core/openapi.json`.
+
+## License
+
+BSD-3-Clause

package/dist/MetaError.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module MetaError
+ * The single error class thrown by the SDK: client-side validation, timeouts, network failures, non-2xx responses and unparseable responses. Pure.
+ */
+import type { ErrorBody } from '@karmaniverous/jeeves/catalog';
+import type { MetaErrorCode } from '@karmaniverous/jeeves-meta-core';
+/**
+ * Codes the SDK assigns itself (lower case, so they never collide with a
+ * server code). An error from a non-2xx response carries the server's code
+ * instead: the body's `code` (a `MetaErrorCode` from core
+ * `META_ERROR_CODES`, a jeeves `JEEVES_*` code or a Fastify `FST_ERR_*`
+ * code), else `http_<status>` (a masked 500, an unknown route, a body that
+ * isn't Fastify's).
+ *
+ * - `invalid_options`: {@link createMetaClient} options are invalid.
+ * - `invalid_request`: the input failed the catalog entry's request schema; nothing was sent.
+ * - `invalid_response`: a 2xx response was not JSON or failed the entry's response schema.
+ * - `timeout`: no response within the call's timeout.
+ * - `network_error`: `fetch` rejected (connection refused, DNS failure, ...).
+ */
+export type MetaClientErrorCode = 'invalid_options' | 'invalid_request' | 'invalid_response' | 'timeout' | 'network_error';
+/**
+ * What {@link MetaError.code} holds: a meta code, a client code,
+ * `http_<status>`, or any other server code (`JEEVES_*`, `FST_ERR_*`); the
+ * named ones autocomplete.
+ */
+export type MetaErrorCodeValue = MetaErrorCode | MetaClientErrorCode | `http_${number}` | (string & {});
+/** Constructor fields of a {@link MetaError}. */
+export interface MetaErrorInit {
+    /** The server's code, `http_<status>` or a {@link MetaClientErrorCode}. */
+    code: MetaErrorCodeValue;
+    /** Human-readable message (a response's: the body's `message`). */
+    message: string;
+    /** HTTP status when a response arrived, else 0. */
+    status: number;
+    /** Parsed error body of a non-2xx response. */
+    body?: ErrorBody;
+    /** The non-2xx response body exactly as received. */
+    responseText?: string;
+    /** Zod issues of an `invalid_request` or `invalid_response`. */
+    issues?: unknown;
+    /** Underlying error, if any. */
+    cause?: unknown;
+}
+/**
+ * The one error type thrown by every SDK call. The SDK never retries;
+ * branch on `code` (`META_NOT_FOUND`, `META_WATCHER_UNAVAILABLE`,
+ * `META_NOT_READY`, ...), never on `message`;
+ * `status` is the HTTP status.
+ */
+export declare class MetaError extends Error {
+    /**
+     * Machine-readable code: the response body's `code` (`META_*`,
+     * `JEEVES_*`, `FST_ERR_*`), else `http_<status>`, or a
+     * {@link MetaClientErrorCode} when no usable response arrived.
+     */
+    readonly code: MetaErrorCodeValue;
+    /** HTTP status when a response arrived, else 0. */
+    readonly status: number;
+    /**
+     * Parsed error body of a non-2xx response: Fastify's standard body
+     * `{ statusCode, code?, error, message }`.
+     */
+    readonly body?: ErrorBody;
+    /** The non-2xx response body exactly as received (JSON or not). */
+    readonly responseText?: string;
+    /** Zod issues of an `invalid_request` or `invalid_response`. */
+    readonly issues?: unknown;
+    /**
+     * Create a meta error.
+     *
+     * @param init - Code, message, status and optional body, text, issues and cause.
+     */
+    constructor(init: MetaErrorInit);
+}
+/**
+ * The body of a non-2xx response as text: exactly as received when it was
+ * captured, else the parsed body as JSON (`{}` when there is none).
+ *
+ * @param error - A MetaError with an HTTP status.
+ * @returns The body text.
+ */
+export declare function errorBodyText(error: MetaError): string;
+/**
+ * Type guard for {@link MetaError}.
+ *
+ * @param value - Any value (typically a caught error).
+ * @returns `true` when `value` is a {@link MetaError}.
+ */
+export declare function isMetaError(value: unknown): value is MetaError;

package/dist/createMetaClient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module createMetaClient
+ * Typed meta API client built on jeeves' catalog client (Decision 186): one method per `META_CATALOG` entry, named by the entry, each taking its input and optional per-call options; every failure is a {@link MetaError}. Network I/O via fetch.
+ */
+import { type CatalogInput, type ClientResponse } from '@karmaniverous/jeeves/catalog';
+import { type MetaCatalog } from '@karmaniverous/jeeves-meta-core';
+import { type MetaClientOptions } from './options.js';
+/** Options for one call. */
+export interface CallOptions {
+    /** Timeout of this call in milliseconds (overrides the client's). */
+    timeoutMs?: number;
+}
+/** The client method for catalog entry `E`: input optional when no field is required. */
+type MethodOf<E extends MetaCatalog['entries'][number]> = Partial<CatalogInput<E>> extends CatalogInput<E> ? (input?: CatalogInput<E>, options?: CallOptions) => Promise<ClientResponse<E>> : (input: CatalogInput<E>, options?: CallOptions) => Promise<ClientResponse<E>>;
+/**
+ * A meta API client: one method per `META_CATALOG` entry, named by the
+ * entry (`status`, `listMetas`, `metaDetail`, `synthesize`, ...). Every
+ * method validates its input against the entry's schemas before sending,
+ * parses the response with the entry's response schema, and throws a
+ * {@link MetaError} on any failure. No retries.
+ */
+export type MetaClient = {
+    [E in MetaCatalog['entries'][number] as E['name']]: MethodOf<E>;
+};
+/**
+ * Create a meta API client.
+ *
+ * @example
+ * ```ts
+ * const meta = createMetaClient({ baseUrl: 'http://127.0.0.1:1938' });
+ * const { owedPhase } = await meta.synthesize({ path: 'j:/domains/x' });
+ * ```
+ *
+ * @param options - Base URL, timeout (default 120 s) and `fetch`.
+ * @returns A {@link MetaClient}.
+ * @throws {@link MetaError} `invalid_options` when the options are invalid.
+ */
+export declare function createMetaClient(options: MetaClientOptions): MetaClient;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module jeeves-meta-sdk
+ * Typed TypeScript client for the jeeves-meta HTTP API, built from jeeves-meta's endpoint catalog (`META_CATALOG`). Start with {@link createMetaClient}; every failure is a {@link MetaError}.
+ */
+export { type CallOptions, createMetaClient, type MetaClient, } from './createMetaClient.js';
+export { errorBodyText, isMetaError, type MetaClientErrorCode, MetaError, type MetaErrorCodeValue, type MetaErrorInit, } from './MetaError.js';
+export { DEFAULT_TIMEOUT_MS, type FetchLike, type MetaClientOptions, } from './options.js';
+export { META_ERROR_CODES, META_ERROR_STATUS, type MetaErrorCode, } from '@karmaniverous/jeeves-meta-core';
+export type { MetaEntryName, MetaHealth, MetaInput, MetaResponse, } from '@karmaniverous/jeeves-meta-core';

package/dist/index.js

@@ -0,0 +1,302 @@
+import { CatalogClientError, createCatalogClient } from '@karmaniverous/jeeves/catalog';
+import { META_CATALOG } from '@karmaniverous/jeeves-meta-core';
+export { META_ERROR_CODES, META_ERROR_STATUS } from '@karmaniverous/jeeves-meta-core';
+
+/**
+ * @module MetaError
+ * The single error class thrown by the SDK: client-side validation, timeouts, network failures, non-2xx responses and unparseable responses. Pure.
+ */
+/**
+ * The one error type thrown by every SDK call. The SDK never retries;
+ * branch on `code` (`META_NOT_FOUND`, `META_WATCHER_UNAVAILABLE`,
+ * `META_NOT_READY`, ...), never on `message`;
+ * `status` is the HTTP status.
+ */
+class MetaError extends Error {
+    /**
+     * Machine-readable code: the response body's `code` (`META_*`,
+     * `JEEVES_*`, `FST_ERR_*`), else `http_<status>`, or a
+     * {@link MetaClientErrorCode} when no usable response arrived.
+     */
+    code;
+    /** HTTP status when a response arrived, else 0. */
+    status;
+    /**
+     * Parsed error body of a non-2xx response: Fastify's standard body
+     * `{ statusCode, code?, error, message }`.
+     */
+    body;
+    /** The non-2xx response body exactly as received (JSON or not). */
+    responseText;
+    /** Zod issues of an `invalid_request` or `invalid_response`. */
+    issues;
+    /**
+     * Create a meta error.
+     *
+     * @param init - Code, message, status and optional body, text, issues and cause.
+     */
+    constructor(init) {
+        super(init.message, init.cause === undefined ? {} : { cause: init.cause });
+        this.name = 'MetaError';
+        this.code = init.code;
+        this.status = init.status;
+        this.body = init.body;
+        this.responseText = init.responseText;
+        this.issues = init.issues;
+    }
+}
+/**
+ * The body of a non-2xx response as text: exactly as received when it was
+ * captured, else the parsed body as JSON (`{}` when there is none).
+ *
+ * @param error - A MetaError with an HTTP status.
+ * @returns The body text.
+ */
+function errorBodyText(error) {
+    return error.responseText ?? JSON.stringify(error.body ?? {});
+}
+/**
+ * Type guard for {@link MetaError}.
+ *
+ * @param value - Any value (typically a caught error).
+ * @returns `true` when `value` is a {@link MetaError}.
+ */
+function isMetaError(value) {
+    return value instanceof MetaError;
+}
+
+/**
+ * @module options
+ * Client options for `createMetaClient`, their validation, and the `fetch` adapter that keeps each non-2xx response body as received (for `MetaError.responseText`). Pure apart from wrapping `fetch`.
+ */
+/**
+ * Default per-call timeout: 120 s, jeeves' `DEFAULT_FETCH_TIMEOUT_MS`.
+ */
+const DEFAULT_TIMEOUT_MS = 120_000;
+const invalid = (message) => new MetaError({ code: 'invalid_options', status: 0, message });
+/** Statuses whose responses carry no body. */
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+/**
+ * Adapt a {@link FetchLike} to the `fetch` signature jeeves' catalog client
+ * takes, keeping the body text of every non-2xx response in `errorTexts`.
+ *
+ * @remarks
+ * jeeves' client hands the response's own `Headers` object to the error it
+ * throws (`CatalogClientError.headers`), so the text is found again by that
+ * object. The client reads the body after this adapter, so the adapter
+ * returns a fresh response with the same status, headers and text.
+ *
+ * @param fetchImpl - The caller's fetch.
+ * @param errorTexts - Where non-2xx body texts are kept.
+ * @returns A `typeof fetch` that calls `fetchImpl`.
+ */
+function captureErrorText(fetchImpl, errorTexts) {
+    return async (input, init) => {
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        const res = await fetchImpl(url, init ?? {});
+        if (res.ok)
+            return res;
+        if (NULL_BODY_STATUSES.has(res.status)) {
+            errorTexts.set(res.headers, '');
+            return res;
+        }
+        const text = await res.text();
+        const copy = new Response(text, {
+            status: res.status,
+            statusText: res.statusText,
+            headers: res.headers,
+        });
+        errorTexts.set(copy.headers, text);
+        return copy;
+    };
+}
+/**
+ * Check a timeout option.
+ *
+ * @param name - Option name (for the message).
+ * @param value - The value.
+ * @returns The value.
+ * @throws {@link MetaError} `invalid_options` unless positive and finite.
+ */
+function checkTimeout(name, value) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw invalid(`${name} must be a positive number`);
+    return value;
+}
+/**
+ * Validate and normalise client options.
+ *
+ * @param options - Caller options.
+ * @returns Resolved options.
+ * @throws {@link MetaError} `invalid_options` on a bad base URL (not http(s), or carrying a query string or fragment), a non-positive timeout or no `fetch`.
+ */
+function resolveClientOptions(options) {
+    const { baseUrl } = options;
+    if (!URL.canParse(baseUrl) || !/^https?:$/.test(new URL(baseUrl).protocol)) {
+        throw invalid(`baseUrl must be an http(s) URL, got "${baseUrl}"`);
+    }
+    // Entry paths are appended to baseUrl, so a query or fragment would
+    // swallow them. Check the raw string: URL drops an empty `?` or `#`.
+    if (/[?#]/.test(baseUrl)) {
+        throw invalid(`baseUrl must not contain a query string or fragment, got "${baseUrl}"`);
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (fetchImpl === undefined) {
+        throw invalid('No fetch implementation available; pass options.fetch');
+    }
+    const errorTexts = new WeakMap();
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        timeoutMs: checkTimeout('timeoutMs', options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        fetch: captureErrorText(fetchImpl, errorTexts),
+        errorTexts,
+    };
+}
+
+/**
+ * @module toMetaError
+ * The one mapping from what jeeves' catalog client throws to {@link MetaError} (Decision 186): a response keeps its HTTP status, its body's `code` (else `http_<status>`) and its body's `message`; client-side failures get the SDK's own codes and status 0. Pure.
+ */
+/**
+ * The SDK code of a failure that produced no usable response.
+ *
+ * @param cause - The underlying error.
+ * @returns `timeout`, `invalid_response` (a 2xx body that is not JSON) or `network_error`.
+ */
+function noResponseCode(cause) {
+    if (cause instanceof Error && cause.name === 'TimeoutError')
+        return 'timeout';
+    if (cause instanceof SyntaxError)
+        return 'invalid_response';
+    return 'network_error';
+}
+/**
+ * Message of an underlying error.
+ *
+ * @param cause - Anything thrown.
+ * @returns Its message, or its string form.
+ */
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+/**
+ * A string field of an error body, treating empty as absent.
+ *
+ * @param value - The field.
+ * @returns It, or `undefined` when missing or empty.
+ */
+const nonEmpty = (value) => value === '' ? undefined : value;
+/**
+ * Convert a failed catalog call to a {@link MetaError}.
+ *
+ * @param error - What the catalog client threw.
+ * @param operation - Catalog entry name (used in messages).
+ * @param timeoutMs - The call's timeout (used in the timeout message).
+ * @param responseText - The non-2xx body as received, when captured.
+ * @returns The error to throw.
+ */
+function toMetaError(error, operation, timeoutMs, responseText) {
+    if (!(error instanceof CatalogClientError)) {
+        return new MetaError({
+            code: 'network_error',
+            status: 0,
+            message: `${operation} request failed: ${messageOf(error)}`,
+            cause: error,
+        });
+    }
+    if (error.status >= 300) {
+        return new MetaError({
+            code: nonEmpty(error.code) ?? `http_${String(error.status)}`,
+            status: error.status,
+            message: nonEmpty(error.body?.message) ??
+                nonEmpty(error.body?.error) ??
+                `HTTP ${String(error.status)}`,
+            ...(error.body === undefined ? {} : { body: error.body }),
+            ...(responseText === undefined ? {} : { responseText }),
+            cause: error,
+        });
+    }
+    if (error.issues !== undefined) {
+        const responded = error.status > 0;
+        return new MetaError({
+            code: responded ? 'invalid_response' : 'invalid_request',
+            status: error.status,
+            message: responded
+                ? `${operation} response did not match the expected shape`
+                : error.message,
+            issues: error.issues,
+            cause: error,
+        });
+    }
+    const code = noResponseCode(error.cause);
+    const message = code === 'timeout'
+        ? `${operation} timed out after ${String(timeoutMs)} ms`
+        : code === 'invalid_response'
+            ? `${operation} returned a response that is not JSON`
+            : `${operation} request failed: ${messageOf(error.cause)}`;
+    return new MetaError({
+        code,
+        // A non-JSON 2xx did arrive: keep its status.
+        status: code === 'invalid_response' ? error.status : 0,
+        message,
+        cause: error,
+    });
+}
+
+/**
+ * @module createMetaClient
+ * Typed meta API client built on jeeves' catalog client (Decision 186): one method per `META_CATALOG` entry, named by the entry, each taking its input and optional per-call options; every failure is a {@link MetaError}. Network I/O via fetch.
+ */
+/**
+ * Create a meta API client.
+ *
+ * @example
+ * ```ts
+ * const meta = createMetaClient({ baseUrl: 'http://127.0.0.1:1938' });
+ * const { owedPhase } = await meta.synthesize({ path: 'j:/domains/x' });
+ * ```
+ *
+ * @param options - Base URL, timeout (default 120 s) and `fetch`.
+ * @returns A {@link MetaClient}.
+ * @throws {@link MetaError} `invalid_options` when the options are invalid.
+ */
+function createMetaClient(options) {
+    const resolved = resolveClientOptions(options);
+    // jeeves' catalog client takes one timeout, so keep one per timeout used.
+    const clients = new Map();
+    const clientFor = (timeoutMs) => {
+        const existing = clients.get(timeoutMs);
+        if (existing)
+            return existing;
+        const created = createCatalogClient(META_CATALOG, {
+            baseUrl: resolved.baseUrl,
+            timeoutMs,
+            fetch: resolved.fetch,
+        });
+        clients.set(timeoutMs, created);
+        return created;
+    };
+    const methods = META_CATALOG.entries.map(({ name }) => {
+        const method = async (input, call = {}) => {
+            const timeoutMs = call.timeoutMs === undefined
+                ? resolved.timeoutMs
+                : checkTimeout('timeoutMs', call.timeoutMs);
+            const send = clientFor(timeoutMs)[name];
+            try {
+                return await send(input);
+            }
+            catch (error) {
+                const text = error instanceof CatalogClientError && error.headers
+                    ? resolved.errorTexts.get(error.headers)
+                    : undefined;
+                throw toMetaError(error, name, timeoutMs, text);
+            }
+        };
+        return [name, method];
+    });
+    return Object.fromEntries(methods);
+}
+
+export { DEFAULT_TIMEOUT_MS, MetaError, createMetaClient, errorBodyText, isMetaError };

package/dist/options.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module options
+ * Client options for `createMetaClient`, their validation, and the `fetch` adapter that keeps each non-2xx response body as received (for `MetaError.responseText`). Pure apart from wrapping `fetch`.
+ */
+/**
+ * Default per-call timeout: 120 s, jeeves' `DEFAULT_FETCH_TIMEOUT_MS`.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+/** A `fetch`-compatible function (the global `fetch` by default). */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Options for `createMetaClient`. */
+export interface MetaClientOptions {
+    /** Base URL of the meta API, e.g. `http://127.0.0.1:1938`. May carry a path prefix; must not carry a query string or fragment. */
+    baseUrl: string;
+    /** Per-call timeout in milliseconds. Default: 120000. */
+    timeoutMs?: number;
+    /** `fetch` implementation (for tests or custom agents). Default: global `fetch`. */
+    fetch?: FetchLike;
+}
+/** Validated, normalised client options. */
+export interface ResolvedClientOptions {
+    /** Base URL without trailing slashes. */
+    baseUrl: string;
+    /** Default timeout. */
+    timeoutMs: number;
+    /** The caller's fetch, adapted (see {@link captureErrorText}). */
+    fetch: typeof fetch;
+    /** Non-2xx body texts, keyed by the response's `Headers`. */
+    errorTexts: WeakMap<Headers, string>;
+}
+/**
+ * Adapt a {@link FetchLike} to the `fetch` signature jeeves' catalog client
+ * takes, keeping the body text of every non-2xx response in `errorTexts`.
+ *
+ * @remarks
+ * jeeves' client hands the response's own `Headers` object to the error it
+ * throws (`CatalogClientError.headers`), so the text is found again by that
+ * object. The client reads the body after this adapter, so the adapter
+ * returns a fresh response with the same status, headers and text.
+ *
+ * @param fetchImpl - The caller's fetch.
+ * @param errorTexts - Where non-2xx body texts are kept.
+ * @returns A `typeof fetch` that calls `fetchImpl`.
+ */
+export declare function captureErrorText(fetchImpl: FetchLike, errorTexts: WeakMap<Headers, string>): typeof fetch;
+/**
+ * Check a timeout option.
+ *
+ * @param name - Option name (for the message).
+ * @param value - The value.
+ * @returns The value.
+ * @throws {@link MetaError} `invalid_options` unless positive and finite.
+ */
+export declare function checkTimeout(name: string, value: number): number;
+/**
+ * Validate and normalise client options.
+ *
+ * @param options - Caller options.
+ * @returns Resolved options.
+ * @throws {@link MetaError} `invalid_options` on a bad base URL (not http(s), or carrying a query string or fragment), a non-positive timeout or no `fetch`.
+ */
+export declare function resolveClientOptions(options: MetaClientOptions): ResolvedClientOptions;

package/dist/toMetaError.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module toMetaError
+ * The one mapping from what jeeves' catalog client throws to {@link MetaError} (Decision 186): a response keeps its HTTP status, its body's `code` (else `http_<status>`) and its body's `message`; client-side failures get the SDK's own codes and status 0. Pure.
+ */
+import { MetaError } from './MetaError.js';
+/**
+ * Convert a failed catalog call to a {@link MetaError}.
+ *
+ * @param error - What the catalog client threw.
+ * @param operation - Catalog entry name (used in messages).
+ * @param timeoutMs - The call's timeout (used in the timeout message).
+ * @param responseText - The non-2xx body as received, when captured.
+ * @returns The error to throw.
+ */
+export declare function toMetaError(error: unknown, operation: string, timeoutMs: number, responseText?: string): MetaError;

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@karmaniverous/jeeves-meta-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-0",
+  "author": "Jason Williscroft",
+  "description": "Typed TypeScript client for the jeeves-meta HTTP API (metas, synthesis, queue, preview, seed, unlock, status and config), built from jeeves-meta's endpoint catalog.",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "jeeves-meta",
+    "sdk",
+    "client",
+    "synthesis"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/jeeves-meta.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/karmaniverous/jeeves-meta/issues"
+  },
+  "homepage": "https://github.com/karmaniverous/jeeves-meta#readme",
+  "engines": {
+    "node": ">=24.22.2"
+  },
+  "dependencies": {
+    "@karmaniverous/jeeves": "0.11.0",
+    "@karmaniverous/jeeves-meta-core": "^0.4.0-0"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^2.38.2",
+    "@rollup/plugin-typescript": "^12.3.1",
+    "cross-env": "^10.1.0",
+    "release-it": "^21.1.2",
+    "rollup": "^4.68.3",
+    "tslib": "^2.9.1",
+    "vitest": "^5.1.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "git-cliff -o CHANGELOG.md",
+    "knip": "knip",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.preRelease --preRelease",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "release-it": {
+    "git": {
+      "changelog": "npx git-cliff --unreleased --strip header",
+      "commitMessage": "chore: release @karmaniverous/jeeves-meta-sdk v${version}",
+      "tagName": "sdk/${version}",
+      "requireBranch": "main"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "${name.split('/').pop()}@${version}",
+      "releaseNotes": "npx git-cliff --tag sdk/${version} --unreleased --strip header"
+    },
+    "hooks": {
+      "after:init": [
+        "npm run lint",
+        "npm run typecheck",
+        "npm run test",
+        "npm run build"
+      ],
+      "after:bump": [
+        "npm install --package-lock-only --ignore-scripts"
+      ],
+      "before:npm:release": [
+        "npx git-cliff --tag sdk/${version} -o CHANGELOG.md",
+        "git add -A"
+      ],
+      "after:release": [
+        "git switch -c release/sdk/${version}",
+        "git push -u origin release/sdk/${version}",
+        "git switch ${branchName}"
+      ]
+    },
+    "npm": {
+      "publish": true
+    }
+  }
+}