@cat-factory/sdk 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+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

@@ -0,0 +1,109 @@
+# `@cat-factory/sdk`
+
+TypeScript / JavaScript client for the cat-factory **public API** (`/api/v1`).
+
+```sh
+npm install @cat-factory/sdk
+```
+
+Node 20+. No dependencies: the transport is `fetch`.
+
+```ts
+import { CatFactoryClient, CatFactoryNotFoundError } from '@cat-factory/sdk'
+
+const client = new CatFactoryClient({
+  baseUrl: 'https://cat-factory.example.com',
+  apiKey: process.env.CAT_FACTORY_API_KEY!,
+})
+
+const { services } = await client.services.list()
+const task = await client.tasks.create(services[0].serviceId, {
+  title: 'Add a health check endpoint',
+  taskType: 'feature',
+})
+await client.tasks.start(task.taskId, {})
+```
+
+## Resource clients
+
+`jobs`, `services`, `tasks`, `pipelines`, `notifications`, `usage`, `decisions`, `debug`:
+one per tag of the published OpenAPI surface. Every call is scoped to the key's workspace.
+
+## Watching a run
+
+```ts
+const stream = await client.tasks.stream(task.taskId)
+try {
+  for await (const event of stream) {
+    if (event.event === 'decision') {
+      // The run PARKED on a human decision and waits indefinitely. Answer it through
+      // `client.decisions` (needs a `decide`-scope key) or free it with `tasks.stop`.
+      const { decisions } = await client.decisions.list(runId)
+    }
+    if (event.event === 'done' || event.event === 'error') break
+    // `timeout` means the deployment's connection cap was reached, NOT that the run finished.
+  }
+} finally {
+  await stream.close()
+}
+```
+
+## Paging
+
+Every bounded list has an auto-paging companion that follows `nextCursor` for you:
+
+```ts
+for await (const task of client.tasks.listByServiceAll(serviceId)) {
+  console.log(task.taskId)
+}
+```
+
+## Errors
+
+The exception CLASS comes from the HTTP status; `code` carries the specific cause and is a plain
+string, because this surface adds new codes without a major version.
+
+```ts
+try {
+  await client.tasks.get(taskId)
+} catch (error) {
+  if (error instanceof CatFactoryNotFoundError) return null
+  if (error instanceof CatFactoryForbiddenError && error.code === 'insufficient_scope') {
+    throw new Error('this key needs a higher scope')
+  }
+  throw error
+}
+```
+
+Classes: `CatFactoryValidationError` (400/422), `…Unauthorized` (401), `…Forbidden` (403),
+`…NotFound` (404), `…Conflict` (409), `…CredentialRequired` (428), `…RateLimited` (429),
+`…ServerError` (5xx), plus `…ConnectionError`, `…TimeoutError` and `…DecodeError`. All extend
+`CatFactoryError`. Every API error carries `status`, `code`, `details`, `issues` and the
+`requestId` to quote when reporting a fault.
+
+## Options
+
+```ts
+new CatFactoryClient({
+  baseUrl,
+  apiKey,
+  timeoutMs: 30_000, // 0 disables
+  maxRetries: 2, // idempotent requests only - a POST is never auto-retried
+  headers: {},
+  userAgent: 'my-integration/1.2.3',
+  fetch: myFetch, // a proxy agent, or a test double
+})
+```
+
+## Local development and mocks
+
+The base URL takes any origin (`http://localhost:8787`, a fixture server, a mock) and no scheme
+validation is applied. Each client also accepts a custom transport, so you can intercept in-process
+instead. See [the SDK guide](../README.md#pointing-an-sdk-at-localhost-or-a-mock).
+
+## Notes
+
+- `src/*.generated.ts` are generated from `docs/openapi.json`; see [`../README.md`](../README.md).
+- The sources are **erasable-only** TypeScript (no enums, namespaces or parameter properties), so
+  they run under Node's type stripping and `erasableSyntaxOnly` builds.
+- API reference: [`backend/docs/public-api.md`](../../backend/docs/public-api.md).

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { type ClientOptions } from './http.ts';
+import { CatFactoryResources } from './operations.generated.ts';
+/**
+ * A cat-factory public-API client.
+ *
+ * ```ts
+ * const client = new CatFactoryClient({
+ *   baseUrl: 'https://cat-factory.example.com',
+ *   apiKey: process.env.CAT_FACTORY_API_KEY!,
+ * })
+ * const { services } = await client.services.list()
+ * const task = await client.tasks.create(services[0].serviceId, { title: 'Add a health check' })
+ * await client.tasks.start(task.taskId, {})
+ * ```
+ *
+ * Every call is scoped to the key's workspace, and each resource client mirrors one tag of the
+ * published OpenAPI surface: `jobs`, `services`, `tasks`, `pipelines`, `notifications`,
+ * `usage`, `decisions`, `debug`.
+ *
+ * The client is stateless beyond its configuration, so one instance is safe to share across
+ * concurrent work.
+ */
+export declare class CatFactoryClient extends CatFactoryResources {
+    constructor(options: ClientOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,WAAW,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;GAmBG;AASH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,YAAY,OAAO,EAAE,aAAa,EAEjC;CACF"}

package/dist/client.js

@@ -0,0 +1,37 @@
+// The client a caller constructs: a transport plus the generated resource clients mounted on it.
+import { Transport } from './http.js';
+import { CatFactoryResources } from './operations.generated.js';
+/**
+ * A cat-factory public-API client.
+ *
+ * ```ts
+ * const client = new CatFactoryClient({
+ *   baseUrl: 'https://cat-factory.example.com',
+ *   apiKey: process.env.CAT_FACTORY_API_KEY!,
+ * })
+ * const { services } = await client.services.list()
+ * const task = await client.tasks.create(services[0].serviceId, { title: 'Add a health check' })
+ * await client.tasks.start(task.taskId, {})
+ * ```
+ *
+ * Every call is scoped to the key's workspace, and each resource client mirrors one tag of the
+ * published OpenAPI surface: `jobs`, `services`, `tasks`, `pipelines`, `notifications`,
+ * `usage`, `decisions`, `debug`.
+ *
+ * The client is stateless beyond its configuration, so one instance is safe to share across
+ * concurrent work.
+ */
+// The resource properties are INHERITED from the generated `CatFactoryResources` rather than
+// re-declared here. Listing them by hand would be a second copy of the surface table that nothing
+// keeps in sync — a resource group added to `scripts/sdk/surface.mjs` would generate, compile, and
+// simply not be reachable from the client anyone actually constructs.
+//
+// A base class rather than a declaration-merged `interface CatFactoryClient extends Resources {}`:
+// the merge reads more cleanly, but TypeScript cannot see that such properties are ever
+// initialised, so it silently gives up checking them (`no-unsafe-declaration-merging`).
+export class CatFactoryClient extends CatFactoryResources {
+    constructor(options) {
+        super(new Transport(options));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,iGAAiG;AAEjG,OAAO,EAAsB,SAAS,EAAE,MAAM,WAAW,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6FAA6F;AAC7F,kGAAkG;AAClG,mGAAmG;AACnG,sEAAsE;AACtE,EAAE;AACF,mGAAmG;AACnG,wFAAwF;AACxF,wFAAwF;AACxF,MAAM,OAAO,gBAAiB,SAAQ,mBAAmB;IACvD,YAAY,OAAsB;QAChC,KAAK,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/B,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,127 @@
+/** The wire error envelope every `/api/v1` failure carries. */
+export interface ApiErrorBody {
+    error: {
+        /**
+         * Machine-readable. Either a status-class code (`validation`, `not_found`, `conflict`,
+         * `unauthorized`, `forbidden`, `credential_required`, `rate_limited`, `unavailable`,
+         * `internal`) or one specific to this surface (`insufficient_scope`, `invalid_cursor`,
+         * `pipeline_not_public`, …). Branch on this, never on `message`.
+         */
+        code: string;
+        /** Operator prose. Not localized, and not a stable identifier — do not branch on it. */
+        message: string;
+        /** Cause detail, shape depending on `code`. */
+        details?: unknown;
+        /** Per-field validation failures, on a 400 whose body or query did not parse. */
+        issues?: {
+            path?: string;
+            message: string;
+        }[];
+    };
+}
+/** Base class for everything this SDK throws, so one `catch` can bound the whole client. */
+export declare class CatFactoryError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request never produced an HTTP response: DNS, TCP, TLS, or an aborted socket. */
+export declare class CatFactoryConnectionError extends CatFactoryError {
+}
+/** The request exceeded the client-side deadline (`timeoutMs`), so no verdict was reached. */
+export declare class CatFactoryTimeoutError extends CatFactoryError {
+}
+/**
+ * An auto-pager was answered with the SAME `nextCursor` it had just sent.
+ *
+ * That is a server fault, and the pagers stop rather than follow it — the walk would otherwise
+ * never terminate, re-fetching one page forever against the caller's rate limit. It throws rather
+ * than returning quietly because a silent stop is indistinguishable from a completed walk, and a
+ * caller acting on "these are all the tasks" when they have seen one page is the worse failure.
+ */
+export declare class CatFactoryPaginationError extends CatFactoryError {
+}
+/** Build the pagination fault above. Called from the generated pagers. */
+export declare function repeatedCursorError(): CatFactoryPaginationError;
+/**
+ * A 2xx response whose body was not the JSON the contract promises — in practice a proxy or
+ * gateway answering in the deployment's place. Carries the raw text, because "invalid JSON" on
+ * its own does not tell you that something in front of the backend returned an HTML error page.
+ */
+export declare class CatFactoryDecodeError extends CatFactoryError {
+    readonly rawBody: string;
+    constructor(message: string, rawBody: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The server answered, and the answer was a refusal. Subclasses below name the status CLASS;
+ * `code` names the specific cause.
+ */
+export declare class CatFactoryApiError extends CatFactoryError {
+    /** The HTTP status. */
+    readonly status: number;
+    /** The machine-readable `error.code` — see the note at the top of this file. */
+    readonly code: string;
+    /** `error.details`, whose shape depends on `code`. */
+    readonly details: unknown;
+    /** Per-field validation failures, when the server reported any. */
+    readonly issues: {
+        path?: string;
+        message: string;
+    }[];
+    /**
+     * The `X-Request-Id` of the failing call. Every response carries one (the backend mints or
+     * adopts it in `mountRequestLogging`), and it is the id to quote when reporting a fault —
+     * it is what correlates this call with the deployment's own logs.
+     */
+    readonly requestId: string | null;
+    /** The raw body, for a failure whose `details` this SDK does not model. */
+    readonly body: unknown;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        details?: unknown;
+        issues?: {
+            path?: string;
+            message: string;
+        }[];
+        requestId: string | null;
+        body: unknown;
+    });
+}
+/** 400 / 422 — the request was malformed, or a domain rule refused it. */
+export declare class CatFactoryValidationError extends CatFactoryApiError {
+}
+/** 401 — no key, or a key that has been revoked. */
+export declare class CatFactoryUnauthorizedError extends CatFactoryApiError {
+}
+/** 403 — a valid key whose scope is too low (`insufficient_scope`), or a forbidden action. */
+export declare class CatFactoryForbiddenError extends CatFactoryApiError {
+}
+/** 404 — no such resource, or one outside this key's workspace (the two are indistinguishable). */
+export declare class CatFactoryNotFoundError extends CatFactoryApiError {
+}
+/** 409 — the resource is not in a state that admits this action. */
+export declare class CatFactoryConflictError extends CatFactoryApiError {
+}
+/** 428 — a credential the action needs has not been supplied. */
+export declare class CatFactoryCredentialRequiredError extends CatFactoryApiError {
+}
+/** 429 — rate limited, or a counted cap is already full (`too_many_active_runs`). */
+export declare class CatFactoryRateLimitedError extends CatFactoryApiError {
+}
+/** 5xx — the deployment faulted or a dependency it needs is unavailable. */
+export declare class CatFactoryServerError extends CatFactoryApiError {
+}
+/**
+ * Build the typed error for a failed response.
+ *
+ * A body that is not the documented envelope (a proxy's HTML error page, a truncated stream)
+ * still yields a usable error: the status is always known, and the unparsed body is retained on
+ * `body` rather than discarded, so a caller diagnosing an unexpected failure is not left with
+ * "something went wrong".
+ */
+export declare function toApiError(status: number, body: unknown, requestId: string | null): CatFactoryApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,143 @@
+// The SDK's error hierarchy.
+//
+// Every failure the API reports arrives as one envelope — `{ error: { code, message, details?,
+// issues? } }` — and the SDK turns it into a typed exception. Which class you get is decided by
+// the HTTP STATUS, never by `code`.
+//
+// That split is deliberate. `/api/v1` puts two families of value in `error.code`: the status-class
+// codes (`validation`, `not_found`, `conflict`, …) and codes specific to this surface
+// (`insufficient_scope`, `invalid_cursor`, `pipeline_not_public`, `too_many_active_runs`, …), and
+// the surface is additive forever — new codes appear without a major version. So the status is the
+// part that is safe to branch a CLASS on, and `code` is exposed verbatim as a plain string for the
+// caller to branch on precisely. Narrowing `code` to a closed union in the SDK would mean an
+// SDK release is required before a caller can even NAME a refusal the server already sends, and
+// a copy of the vocabulary here would be a second place for it to go stale. The authoritative
+// list is `backend/docs/public-api.md`.
+/** Base class for everything this SDK throws, so one `catch` can bound the whole client. */
+export class CatFactoryError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** The request never produced an HTTP response: DNS, TCP, TLS, or an aborted socket. */
+export class CatFactoryConnectionError extends CatFactoryError {
+}
+/** The request exceeded the client-side deadline (`timeoutMs`), so no verdict was reached. */
+export class CatFactoryTimeoutError extends CatFactoryError {
+}
+/**
+ * An auto-pager was answered with the SAME `nextCursor` it had just sent.
+ *
+ * That is a server fault, and the pagers stop rather than follow it — the walk would otherwise
+ * never terminate, re-fetching one page forever against the caller's rate limit. It throws rather
+ * than returning quietly because a silent stop is indistinguishable from a completed walk, and a
+ * caller acting on "these are all the tasks" when they have seen one page is the worse failure.
+ */
+export class CatFactoryPaginationError extends CatFactoryError {
+}
+/** Build the pagination fault above. Called from the generated pagers. */
+export function repeatedCursorError() {
+    return new CatFactoryPaginationError('cat-factory SDK: the server repeated a pagination cursor; stopping rather than looping forever.');
+}
+/**
+ * A 2xx response whose body was not the JSON the contract promises — in practice a proxy or
+ * gateway answering in the deployment's place. Carries the raw text, because "invalid JSON" on
+ * its own does not tell you that something in front of the backend returned an HTML error page.
+ */
+export class CatFactoryDecodeError extends CatFactoryError {
+    rawBody;
+    constructor(message, rawBody, options) {
+        super(message, options);
+        this.rawBody = rawBody;
+    }
+}
+/**
+ * The server answered, and the answer was a refusal. Subclasses below name the status CLASS;
+ * `code` names the specific cause.
+ */
+export class CatFactoryApiError extends CatFactoryError {
+    /** The HTTP status. */
+    status;
+    /** The machine-readable `error.code` — see the note at the top of this file. */
+    code;
+    /** `error.details`, whose shape depends on `code`. */
+    details;
+    /** Per-field validation failures, when the server reported any. */
+    issues;
+    /**
+     * The `X-Request-Id` of the failing call. Every response carries one (the backend mints or
+     * adopts it in `mountRequestLogging`), and it is the id to quote when reporting a fault —
+     * it is what correlates this call with the deployment's own logs.
+     */
+    requestId;
+    /** The raw body, for a failure whose `details` this SDK does not model. */
+    body;
+    constructor(args) {
+        super(`${args.status} ${args.code}: ${args.message}`);
+        this.status = args.status;
+        this.code = args.code;
+        this.details = args.details;
+        this.issues = args.issues ?? [];
+        this.requestId = args.requestId;
+        this.body = args.body;
+    }
+}
+/** 400 / 422 — the request was malformed, or a domain rule refused it. */
+export class CatFactoryValidationError extends CatFactoryApiError {
+}
+/** 401 — no key, or a key that has been revoked. */
+export class CatFactoryUnauthorizedError extends CatFactoryApiError {
+}
+/** 403 — a valid key whose scope is too low (`insufficient_scope`), or a forbidden action. */
+export class CatFactoryForbiddenError extends CatFactoryApiError {
+}
+/** 404 — no such resource, or one outside this key's workspace (the two are indistinguishable). */
+export class CatFactoryNotFoundError extends CatFactoryApiError {
+}
+/** 409 — the resource is not in a state that admits this action. */
+export class CatFactoryConflictError extends CatFactoryApiError {
+}
+/** 428 — a credential the action needs has not been supplied. */
+export class CatFactoryCredentialRequiredError extends CatFactoryApiError {
+}
+/** 429 — rate limited, or a counted cap is already full (`too_many_active_runs`). */
+export class CatFactoryRateLimitedError extends CatFactoryApiError {
+}
+/** 5xx — the deployment faulted or a dependency it needs is unavailable. */
+export class CatFactoryServerError extends CatFactoryApiError {
+}
+const BY_STATUS = {
+    400: CatFactoryValidationError,
+    401: CatFactoryUnauthorizedError,
+    403: CatFactoryForbiddenError,
+    404: CatFactoryNotFoundError,
+    409: CatFactoryConflictError,
+    422: CatFactoryValidationError,
+    428: CatFactoryCredentialRequiredError,
+    429: CatFactoryRateLimitedError,
+};
+/**
+ * Build the typed error for a failed response.
+ *
+ * A body that is not the documented envelope (a proxy's HTML error page, a truncated stream)
+ * still yields a usable error: the status is always known, and the unparsed body is retained on
+ * `body` rather than discarded, so a caller diagnosing an unexpected failure is not left with
+ * "something went wrong".
+ */
+export function toApiError(status, body, requestId) {
+    const envelope = typeof body === 'object' && body !== null && 'error' in body
+        ? body.error
+        : null;
+    const Ctor = BY_STATUS[status] ?? (status >= 500 ? CatFactoryServerError : CatFactoryApiError);
+    return new Ctor({
+        status,
+        code: envelope?.code ?? (status >= 500 ? 'internal' : 'unknown'),
+        message: envelope?.message ?? `HTTP ${status}`,
+        details: envelope?.details,
+        issues: envelope?.issues,
+        requestId,
+        body,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,70 @@
+import { type EventStream } from './sse.ts';
+/** Per-call overrides. Every operation method takes one as its last argument. */
+export interface RequestOptions {
+    /** Abort the call from the outside (composed with the client's own timeout). */
+    signal?: AbortSignal;
+    /** Override the client's `timeoutMs` for this call. `0` disables the deadline. */
+    timeoutMs?: number;
+    /** Extra headers, merged over the client's. */
+    headers?: Record<string, string>;
+    /**
+     * Override the retry budget for this call. Note the default policy below: a non-idempotent
+     * request is never retried automatically, so raising this does not make `POST /jobs`
+     * retry-safe.
+     */
+    maxRetries?: number;
+}
+export interface ClientOptions {
+    /** The deployment's origin, e.g. `https://cat-factory.example.com`. */
+    baseUrl: string;
+    /** A public-API key: `cf_live_<keyId>.<secret>`. */
+    apiKey: string;
+    /** Per-request deadline in ms; `0` disables it. Default 30_000. */
+    timeoutMs?: number;
+    /** Retries for a RETRIABLE failure (see `isRetriable`). Default 2. */
+    maxRetries?: number;
+    /** Headers sent on every request. */
+    headers?: Record<string, string>;
+    /** Swap the HTTP implementation (a proxy agent, a test double). Defaults to global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Prefixed to `User-Agent`, so a deployment's logs can attribute calls to your integration. */
+    userAgent?: string;
+}
+export interface RequestSpec {
+    method: string;
+    path: string;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    options: RequestOptions;
+}
+/** SDK version, stamped into `User-Agent`. Kept in step with package.json by `check:sdk`. */
+export declare const SDK_VERSION = "0.5.0";
+/**
+ * Percent-encode a path parameter.
+ *
+ * `encodeURIComponent` and not a raw interpolation: an id is server-supplied but travels through
+ * a caller's own storage, and one carrying a `/` or a `?` would otherwise silently re-target the
+ * request at a different route rather than 404 on the id it names.
+ */
+export declare function encodePathSegment(value: string): string;
+export declare class Transport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly headers;
+    private readonly doFetch;
+    constructor(options: ClientOptions);
+    /** Perform a request, returning the decoded JSON body. */
+    request<T>(spec: RequestSpec): Promise<T>;
+    /** Perform a request whose success carries no body (a 204). */
+    requestNoContent(spec: RequestSpec): Promise<void>;
+    /**
+     * Open a server-sent event stream. Deliberately NOT retried: a reconnect would replay the
+     * stream from its start, and the caller — who knows which events it has already acted on —
+     * is the only party that can decide whether that is safe.
+     */
+    stream(spec: RequestSpec): Promise<EventStream>;
+    private send;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,UAAU,CAAA;AAE5D,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,+FAA+F;IAC/F,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,6FAA6F;AAC7F,eAAO,MAAM,WAAW,UAAU,CAAA;AAElC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAiCD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,YAAY,OAAO,EAAE,aAAa,EAcjC;IAED,0DAA0D;IACpD,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAa9C;IAED,+DAA+D;IACzD,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvD;IAED;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CASpD;YAEa,IAAI;CA2EnB"}