@cadenya/widgets 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# CadenyaWidgets TypeScript SDK
+
+The official TypeScript client for the CadenyaWidgets API. Generated by redwood.
+Dependency-free ESM built on native `fetch`.
+
+## Install
+
+```sh
+npm install @cadenya/widgets
+```
+
+## Getting started
+
+```ts
+import CadenyaWidgets from '@cadenya/widgets';
+
+// Reads CADENYAWIDGETS_API_KEY from the environment when
+// options are omitted. Explicit blank values are configuration errors.
+const client = new CadenyaWidgets();
+
+const result = await client.config.retrieveWidget();
+```
+
+## Errors
+
+Non-2xx responses throw `APIError` (google.rpc Status: `status`, `code`,
+`message`, `details`). Connection failures throw `APIConnectionError`;
+user aborts throw `APIUserAbortError`; a request that cannot be
+constructed locally (unserializable body) throws `APIRequestError` with
+no network attempt and no retry.
+
+## Timeouts
+
+Ordinary requests have a 60s deadline (through body decode) that throws
+`APITimeoutError`; configure client-wide with `timeout` or per request
+with `options.timeout` (<= 0 disables). Streams bound only response-header
+acquisition — body lifetime stays under your `AbortSignal`.
+
+## Retries
+
+Automatic retries apply only to idempotent methods (GET/HEAD/PUT/DELETE)
+and default to 0. Enable client-wide with `maxRetries`; opt a single
+mutation in per request with `options.maxRetries`. Retry counts normalize
+to a bounded 0–10 integer; `Retry-After` (seconds or HTTP-date) is honored
+and backoff sleeps wake on abort.
+
+## Pagination
+
+```ts
+const page = await client.conversations.list();
+for await (const item of page) {
+  // auto-fetches every page
+}
+```
+
+## Raw response access
+
+Plain methods return an `APIPromise`: awaiting yields the decoded value;
+`.withResponse()` pairs it with the `Response` (status, headers);
+`.asResponse()` — called synchronously, before any `await` — yields the raw
+`Response` with the body UNCONSUMED, so you own reading it:
+
+```ts
+const { data, response } = await client.config.retrieveWidget().withResponse();
+console.log(response.status, response.headers.get('x-request-id'));
+
+const raw = await client.config.retrieveWidget().asResponse();
+const body = await raw.text();
+```
+
+A dropped (never-awaited) call still cleans up after itself: the response
+is consumed and the request deadline is released automatically.
+
+## Logging
+
+```ts
+const client = new CadenyaWidgets({ logLevel: 'debug' }); // or logger: myLogger
+```
+
+`'warn'` (default) logs only retries; `'debug'` adds one line per request
+and response (method, path, status, duration); `'off'` silences the SDK.
+Headers and bodies are NEVER logged.
+
+## Streaming (SSE)
+
+A stream wraps one HTTP response body, so it can be consumed **once**, with
+one of two views — pick whichever fits and iterate that one:
+
+```ts
+// View 1 (normal case): iterate decoded event payloads directly.
+const stream = await client.conversations.streamEvents(id, params);
+for await (const event of stream) {
+  // event is the typed payload
+}
+```
+
+```ts
+// View 2 (alternative): stream.events() keeps the SSE metadata envelope,
+// so the payload sits one level deeper: { event, data, id }.
+const envelopes = await client.conversations.streamEvents(id, params);
+for await (const { data, id } of envelopes.events()) {
+  // ...
+}
+```
+
+Streams RECONNECT AUTOMATICALLY on mid-stream transport drops (like
+EventSource): they resume from the last received event id, retry at most 5
+times per outage with backoff (honoring the server's `retry:` hint), and
+reset the budget once events flow again. A clean stream end, `close()`, and
+a caller abort never reconnect; HTTP-level reconnect failures (e.g. expired
+credentials) surface immediately. Opt out with `{ reconnect: false }` in
+request options — then drops raise `APIConnectionError` and you can resume
+manually:
+
+```ts
+const resumed = await client.conversations.streamEvents(id, params, {
+  lastEventId: stream.lastEventId,
+});
+try {
+  for await (const event of resumed) {
+    // ...
+  }
+} finally {
+  await resumed.close();
+}
+```
+
+Consume (or close) every opened stream — an unconsumed stream holds its
+connection until `close()`.
+
+## Reference
+
+See [api.md](api.md) for every method signature.

package/api.md

@@ -0,0 +1,66 @@
+# CadenyaWidgets TypeScript SDK reference
+
+Plain methods return an awaitable APIPromise (with `.withResponse()` and
+`.asResponse()` for raw Response access); pagination and streaming methods
+return a Promise of a Page or Stream. See README.md for usage patterns.
+
+## config
+
+Get widget config
+
+```ts
+client.config.retrieveWidget(options?: RequestOptions): APIPromise<WidgetConfig>
+```
+
+## conversations
+
+List conversations
+
+```ts
+client.conversations.list(params?: ConversationListParams, options?: RequestOptions): Promise<Page<WidgetConversation>>
+```
+Start a conversation
+
+```ts
+client.conversations.create(params: ConversationCreateParams, options?: RequestOptions): APIPromise<WidgetConversation>
+```
+Get a conversation
+
+```ts
+client.conversations.retrieve(id: string, options?: RequestOptions): APIPromise<WidgetConversation>
+```
+List conversation events
+
+```ts
+client.conversations.listEvents(id: string, params?: ConversationListEventsParams, options?: RequestOptions): Promise<Page<WidgetEvent>>
+```
+Stream conversation events
+
+```ts
+client.conversations.streamEvents(id: string, options?: RequestOptions): Promise<Stream<WidgetEvent>>
+```
+Submit conversation feedback
+
+```ts
+client.conversations.submitFeedback(id: string, params: ConversationSubmitFeedbackParams, options?: RequestOptions): APIPromise<void>
+```
+Approve a pending tool call
+
+```ts
+client.conversations.approveToolCall(id: string, params: ConversationApproveToolCallParams, options?: RequestOptions): APIPromise<void>
+```
+Deny a pending tool call
+
+```ts
+client.conversations.denyToolCall(id: string, params: ConversationDenyToolCallParams, options?: RequestOptions): APIPromise<void>
+```
+Supply a bare tool call's result
+
+```ts
+client.conversations.setToolCallContent(id: string, params: ConversationSetToolCallContentParams, options?: RequestOptions): APIPromise<void>
+```
+Send the next message
+
+```ts
+client.conversations.continue(id: string, params: ConversationContinueParams, options?: RequestOptions): APIPromise<WidgetConversation>
+```

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { Logger, LogLevel } from './core/http.js';
+import { Config } from './resources/config.js';
+import { Conversations } from './resources/conversations.js';
+export interface ClientOptions {
+    /** API key. Defaults to the CADENYAWIDGETS_API_KEY environment variable. */
+    apiKey?: string;
+    /** Override the API base URL. Defaults to . */
+    baseURL?: string;
+    /** Max automatic retries for retryable failures. Defaults to 0. */
+    maxRetries?: number;
+    /**
+     * Deadline for ordinary (non-streaming) requests in milliseconds; override
+     * per request with `options.timeout`. Streams bound only response-header
+     * acquisition — body lifetime stays under the caller's AbortSignal.
+     * Defaults to 60000; a non-finite or <= 0 value disables the deadline.
+     */
+    timeout?: number;
+    /** Headers sent with every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Destination for SDK logs. Defaults to `console`. */
+    logger?: Logger;
+    /** 'debug' | 'warn' (default) | 'off'. Never logs headers or bodies. */
+    logLevel?: LogLevel;
+}
+export declare class CadenyaWidgets {
+    readonly config: Config;
+    readonly conversations: Conversations;
+    private readonly _client;
+    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":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;gBAEzB,OAAO,GAAE,aAAkB;CAuBxC"}

package/dist/client.js

@@ -0,0 +1,49 @@
+// Generated by redwood. Do not edit by hand.
+import { HttpClient } from './core/http.js';
+import { Config } from './resources/config.js';
+import { Conversations } from './resources/conversations.js';
+export class CadenyaWidgets {
+    config;
+    conversations;
+    _client;
+    constructor(options = {}) {
+        // Presence is not validity: empty strings from options or environment
+        // are configuration mistakes, not credentials.
+        const apiKey = resolveOption('apiKey', options.apiKey, readEnv('CADENYAWIDGETS_API_KEY'));
+        if (!apiKey) {
+            throw new Error("Missing API key. Pass it with `new CadenyaWidgets({ apiKey })` or set the CADENYAWIDGETS_API_KEY environment variable.");
+        }
+        this._client = new HttpClient({
+            baseURL: resolveOption('baseURL', options.baseURL, readEnv('CADENYAWIDGETS_BASE_URL')) ?? '',
+            authHeader: () => ({ Authorization: `Bearer ${apiKey}` }),
+            maxRetries: options.maxRetries ?? 0,
+            timeout: options.timeout,
+            defaultHeaders: { 'User-Agent': 'cadenyawidgets-typescript/1.0.0 (api 1.0)', ...options.defaultHeaders },
+            fetch: options.fetch,
+            logger: options.logger,
+            logLevel: options.logLevel,
+            defaults: {},
+        });
+        this.config = new Config(this._client);
+        this.conversations = new Conversations(this._client);
+    }
+}
+function readEnv(name) {
+    const env = globalThis
+        .process?.env;
+    return env?.[name];
+}
+// Presence is not validity: an explicitly provided option must be usable —
+// a blank value is a configuration mistake and never silently falls back to
+// the environment or a default. Only an OMITTED option reads the env.
+function resolveOption(label, explicit, env) {
+    if (explicit !== undefined) {
+        const value = explicit.trim();
+        if (!value) {
+            throw new Error(`${label} must not be blank when provided explicitly; omit it to use the environment instead.`);
+        }
+        return value;
+    }
+    return env?.trim() || undefined;
+}
+//# 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,6CAA6C;AAE7C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AA0B7D,MAAM,OAAO,cAAc;IAChB,MAAM,CAAS;IACf,aAAa,CAAgB;IAErB,OAAO,CAAa;IAErC,YAAY,UAAyB,EAAE;QACrC,sEAAsE;QACtE,+CAA+C;QAC/C,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC;QAC1F,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,wHAAwH,CACzH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,UAAU,CAAC;YAC5B,OAAO,EAAE,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC,IAAI,EAAE;YAC5F,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC;YACzD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;YACnC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,EAAE,YAAY,EAAE,2CAA2C,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE;YACxG,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,EAAI;SACf,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;CACF;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,GAAG,GAAI,UAAyE;SACnF,OAAO,EAAE,GAAG,CAAC;IAChB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,2EAA2E;AAC3E,4EAA4E;AAC5E,sEAAsE;AACtE,SAAS,aAAa,CACpB,KAAa,EACb,QAA4B,EAC5B,GAAuB;IAEvB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,sFAAsF,CAC/F,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,GAAG,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;AAClC,CAAC","sourcesContent":["// Generated by redwood. Do not edit by hand.\n\nimport { HttpClient } from './core/http.js';\nimport type { Logger, LogLevel } from './core/http.js';\nimport { Config } from './resources/config.js';\nimport { Conversations } from './resources/conversations.js';\n\nexport interface ClientOptions {\n  /** API key. Defaults to the CADENYAWIDGETS_API_KEY environment variable. */\n  apiKey?: string;\n  /** Override the API base URL. Defaults to . */\n  baseURL?: string;\n  /** Max automatic retries for retryable failures. Defaults to 0. */\n  maxRetries?: number;\n  /**\n   * Deadline for ordinary (non-streaming) requests in milliseconds; override\n   * per request with `options.timeout`. Streams bound only response-header\n   * acquisition — body lifetime stays under the caller's AbortSignal.\n   * Defaults to 60000; a non-finite or <= 0 value disables the deadline.\n   */\n  timeout?: number;\n  /** Headers sent with every request. */\n  defaultHeaders?: Record<string, string>;\n  /** Custom fetch implementation. */\n  fetch?: typeof fetch;\n  /** Destination for SDK logs. Defaults to `console`. */\n  logger?: Logger;\n  /** 'debug' | 'warn' (default) | 'off'. Never logs headers or bodies. */\n  logLevel?: LogLevel;\n}\n\nexport class CadenyaWidgets {\n  readonly config: Config;\n  readonly conversations: Conversations;\n\n  private readonly _client: HttpClient;\n\n  constructor(options: ClientOptions = {}) {\n    // Presence is not validity: empty strings from options or environment\n    // are configuration mistakes, not credentials.\n    const apiKey = resolveOption('apiKey', options.apiKey, readEnv('CADENYAWIDGETS_API_KEY'));\n    if (!apiKey) {\n      throw new Error(\n        \"Missing API key. Pass it with `new CadenyaWidgets({ apiKey })` or set the CADENYAWIDGETS_API_KEY environment variable.\",\n      );\n    }\n    this._client = new HttpClient({\n      baseURL: resolveOption('baseURL', options.baseURL, readEnv('CADENYAWIDGETS_BASE_URL')) ?? '',\n      authHeader: () => ({ Authorization: `Bearer ${apiKey}` }),\n      maxRetries: options.maxRetries ?? 0,\n      timeout: options.timeout,\n      defaultHeaders: { 'User-Agent': 'cadenyawidgets-typescript/1.0.0 (api 1.0)', ...options.defaultHeaders },\n      fetch: options.fetch,\n      logger: options.logger,\n      logLevel: options.logLevel,\n      defaults: {  },\n    });\n    this.config = new Config(this._client);\n    this.conversations = new Conversations(this._client);\n  }\n}\n\nfunction readEnv(name: string): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  return env?.[name];\n}\n\n// Presence is not validity: an explicitly provided option must be usable —\n// a blank value is a configuration mistake and never silently falls back to\n// the environment or a default. Only an OMITTED option reads the env.\nfunction resolveOption(\n  label: string,\n  explicit: string | undefined,\n  env: string | undefined,\n): string | undefined {\n  if (explicit !== undefined) {\n    const value = explicit.trim();\n    if (!value) {\n      throw new Error(\n        `${label} must not be blank when provided explicitly; omit it to use the environment instead.`,\n      );\n    }\n    return value;\n  }\n  return env?.trim() || undefined;\n}\n"]}

package/dist/core/error.d.ts

@@ -0,0 +1,39 @@
+/** Error model. The API reports failures as a google.rpc.Status payload. */
+export interface ErrorStatus {
+    code?: number;
+    message?: string;
+    details?: Array<Record<string, unknown>>;
+}
+export declare class APIError extends Error {
+    readonly status: number;
+    readonly code: number | undefined;
+    readonly details: Array<Record<string, unknown>> | undefined;
+    constructor(status: number, body: ErrorStatus | undefined, message?: string);
+}
+export declare class APIConnectionError extends Error {
+    constructor(cause: unknown);
+}
+export declare class APIUserAbortError extends Error {
+    constructor();
+}
+/**
+ * The request could not be constructed locally (unserializable body, invalid
+ * argument). No network attempt was made and the call is never retried.
+ */
+export declare class APIRequestError extends Error {
+    constructor(message: string, cause: unknown);
+}
+/** The configured request deadline elapsed before the response completed. */
+export declare class APITimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * The server answered outside the declared protocol: an empty/null body
+ * where a JSON document was promised, malformed JSON, or a 204 on an
+ * output-bearing operation.
+ */
+export declare class APIResponseError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string, cause?: unknown);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/core/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;gBAEjD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM;CAO5E;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,OAAO;CAI3B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAI5C;AAED,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,SAAS,EAAE,MAAM;CAI9B;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7D"}

package/dist/core/error.js

@@ -0,0 +1,56 @@
+/** Error model. The API reports failures as a google.rpc.Status payload. */
+export class APIError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, body, message) {
+        super(message ?? body?.message ?? `HTTP ${status}`);
+        this.name = 'APIError';
+        this.status = status;
+        this.code = body?.code;
+        this.details = body?.details;
+    }
+}
+export class APIConnectionError extends Error {
+    constructor(cause) {
+        super('Connection error', { cause });
+        this.name = 'APIConnectionError';
+    }
+}
+export class APIUserAbortError extends Error {
+    constructor() {
+        super('Request was aborted');
+        this.name = 'APIUserAbortError';
+    }
+}
+/**
+ * The request could not be constructed locally (unserializable body, invalid
+ * argument). No network attempt was made and the call is never retried.
+ */
+export class APIRequestError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'APIRequestError';
+    }
+}
+/** The configured request deadline elapsed before the response completed. */
+export class APITimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = 'APITimeoutError';
+    }
+}
+/**
+ * The server answered outside the declared protocol: an empty/null body
+ * where a JSON document was promised, malformed JSON, or a 204 on an
+ * output-bearing operation.
+ */
+export class APIResponseError extends Error {
+    status;
+    constructor(status, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'APIResponseError';
+        this.status = status;
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/core/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAQ5E,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,IAAI,CAAqB;IACzB,OAAO,CAA6C;IAE7D,YAAY,MAAc,EAAE,IAA6B,EAAE,OAAgB;QACzE,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,QAAQ,MAAM,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,KAAc;QACxB,KAAK,CAAC,kBAAkB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C;QACE,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAE,KAAc;QACzC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,SAAiB;QAC3B,KAAK,CAAC,2BAA2B,SAAS,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,OAAe,EAAE,KAAe;QAC1D,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF","sourcesContent":["/** Error model. The API reports failures as a google.rpc.Status payload. */\n\nexport interface ErrorStatus {\n  code?: number;\n  message?: string;\n  details?: Array<Record<string, unknown>>;\n}\n\nexport class APIError extends Error {\n  readonly status: number;\n  readonly code: number | undefined;\n  readonly details: Array<Record<string, unknown>> | undefined;\n\n  constructor(status: number, body: ErrorStatus | undefined, message?: string) {\n    super(message ?? body?.message ?? `HTTP ${status}`);\n    this.name = 'APIError';\n    this.status = status;\n    this.code = body?.code;\n    this.details = body?.details;\n  }\n}\n\nexport class APIConnectionError extends Error {\n  constructor(cause: unknown) {\n    super('Connection error', { cause });\n    this.name = 'APIConnectionError';\n  }\n}\n\nexport class APIUserAbortError extends Error {\n  constructor() {\n    super('Request was aborted');\n    this.name = 'APIUserAbortError';\n  }\n}\n\n/**\n * The request could not be constructed locally (unserializable body, invalid\n * argument). No network attempt was made and the call is never retried.\n */\nexport class APIRequestError extends Error {\n  constructor(message: string, cause: unknown) {\n    super(message, { cause });\n    this.name = 'APIRequestError';\n  }\n}\n\n/** The configured request deadline elapsed before the response completed. */\nexport class APITimeoutError extends Error {\n  constructor(timeoutMs: number) {\n    super(`Request timed out after ${timeoutMs}ms`);\n    this.name = 'APITimeoutError';\n  }\n}\n\n/**\n * The server answered outside the declared protocol: an empty/null body\n * where a JSON document was promised, malformed JSON, or a 204 on an\n * output-bearing operation.\n */\nexport class APIResponseError extends Error {\n  readonly status: number;\n\n  constructor(status: number, message: string, cause?: unknown) {\n    super(message, cause === undefined ? undefined : { cause });\n    this.name = 'APIResponseError';\n    this.status = status;\n  }\n}\n"]}

package/dist/core/http.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal, dependency-less HTTP core built on global fetch (Node 18+,
+ * browsers, Deno, Bun). Handles auth, query serialization, retries with
+ * backoff, timeouts, and error mapping.
+ */
+export interface RequestOptions {
+    /**
+     * Auto-reconnect for SSE streams (default true): a mid-stream transport
+     * drop resumes from the last received event id, like EventSource. Clean
+     * stream end, close(), and abort never reconnect. Set false to surface
+     * drops as APIConnectionError instead.
+     */
+    reconnect?: boolean;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    maxRetries?: number;
+    /**
+     * Per-request deadline in milliseconds (overrides the client default).
+     * Non-finite or <= 0 disables the deadline for this request.
+     */
+    timeout?: number;
+    /**
+     * For streaming (SSE) requests: resume after the event with this id by
+     * sending it as the Last-Event-ID request header.
+     */
+    lastEventId?: string;
+}
+export type QueryPrimitive = string | number | boolean;
+export type QueryValue = QueryPrimitive | QueryPrimitive[] | undefined | null;
+export interface RequestSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    stream?: boolean;
+    /** The operation declares no response body (void): 204/empty succeed. */
+    void?: boolean;
+}
+export type LogLevel = 'debug' | 'warn' | 'off';
+/** Minimal logger surface; `console` satisfies it. */
+export interface Logger {
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+export interface HttpClientOptions {
+    baseURL: string;
+    authHeader: () => Record<string, string>;
+    maxRetries?: number;
+    /** Deadline for ordinary (non-streaming) requests in ms. Default 60000. */
+    timeout?: number;
+    defaultHeaders?: Record<string, string>;
+    fetch?: typeof fetch;
+    /** Client-level default values for prominent params (e.g. a tenant/scope id). */
+    defaults?: Record<string, string | undefined>;
+    /** Destination for SDK logs. Defaults to `console`. */
+    logger?: Logger;
+    /**
+     * 'debug' logs every request/response line (method, path, status,
+     * duration — never headers or bodies); 'warn' (default) logs only
+     * retries; 'off' silences the SDK entirely.
+     */
+    logLevel?: LogLevel;
+}
+/**
+ * Encode one path segment, rejecting empty/whitespace values at the boundary
+ * — an empty segment would silently rewrite the route (/parents//children).
+ */
+export declare function pathSegment(name: string, value: string | undefined): string;
+/**
+ * Snapshot list params at call time so pagination cannot observe later
+ * caller mutations (array-valued filters are copied too). Auto-iteration
+ * must never combine pages from different result sets.
+ */
+export declare function snapshotParams<T>(params: T): T;
+/** Claim (and remove) the cleanup registered for a streaming response. */
+export declare function takeStreamCleanup(response: Response): (() => void) | undefined;
+/**
+ * A lazily-parsing promise for one API call. Awaiting it (or `.then`) yields
+ * the decoded value exactly like a plain promise; `withResponse()` yields the
+ * decoded value together with the raw `Response` (status, headers); and
+ * `asResponse()` yields the raw `Response` WITHOUT consuming the body, so
+ * the caller owns reading it.
+ */
+export declare class APIPromise<T> implements Promise<T> {
+    private readonly responsePromise;
+    private readonly parseFn;
+    private readonly onRawAccess;
+    private parsed;
+    private observedRaw;
+    constructor(responsePromise: Promise<Response>, parseFn: (response: Response) => Promise<T>, onRawAccess: () => void);
+    /**
+     * The raw `Response` after status checking and retries; the body is NOT
+     * consumed. Reading the body (and its timing) becomes the caller's
+     * responsibility — the request deadline stops at header acquisition.
+     */
+    asResponse(): Promise<Response>;
+    /** The decoded value together with the `Response` its body came from. */
+    withResponse(): Promise<{
+        data: T;
+        response: Response;
+    }>;
+    private parse;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+    readonly [Symbol.toStringTag] = "APIPromise";
+}
+export declare class HttpClient {
+    private readonly baseURL;
+    private readonly authHeader;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly defaultHeaders;
+    private readonly fetchFn;
+    private readonly logger;
+    private readonly logLevel;
+    /** Method + path + status only — headers and bodies are never logged. */
+    private logDebug;
+    private logWarn;
+    readonly defaults: Record<string, string | undefined>;
+    constructor(options: HttpClientOptions);
+    /**
+     * The APIPromise pipeline for JSON and void operations. The spec thunk
+     * runs inside the async context so synchronous setup failures (e.g. a
+     * missing client-default param) surface as rejections, exactly like the
+     * plain-promise path. The deadline spans fetch through decode; raw-access
+     * consumers release it at header acquisition and own body timing.
+     */
+    requestAPI<T>(makeSpec: () => RequestSpec, options?: RequestOptions): APIPromise<T>;
+    request<T>(spec: RequestSpec, options?: RequestOptions): Promise<T>;
+    rawRequest(spec: RequestSpec, options?: RequestOptions): Promise<Response>;
+    /**
+     * Merge the caller's signal with the configured deadline. The caller's
+     * abort always forwards; the timer marks timedOut so the thrown error can
+     * be classified as APITimeoutError rather than APIUserAbortError.
+     */
+    private deadline;
+    private buildURL;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/core/http.d.ts.map

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