@lionhummer/constellation 0.3.0 → 0.4.0

package/README.md

@@ -94,6 +94,10 @@ Each invocation creates a new request. For application retries, persist the comp
 | `waiting` | Handle the pending input. Tools always require a consumer; wait checkpoints do too. SSE observation does not answer inputs. |
 | `failed` | Inspect `request.reason`, `request.error`, attempts and timeline for provider, routing or deadline failure. |
 
+## Release 0.4.0
+
+Telemetry now returns metadata by default. Use `include: "content"` for full content, with the same permission/scope. Adds key-aware `discover`, explicit request timings, accurate endpoint filter types, HTTP chunk pagination, and billing/traffic methods. Deploy the matching server before using these methods.
+
 ## Release 0.3.0
 
 This pre-1.0 release breaks the earlier SDK contract. Use namespaced execution methods; flat aliases and the old drive/protocol surface are removed. Keys, credentials, users and capacity administration are internal-only. Provider-definition writes also require an internal operator. External telemetry and other registry authoring remain available. Deploy a server containing these API changes before switching clients; publishing this package does not deploy the server or upgrade any downstream application dependency.
@@ -156,3 +160,44 @@ Use the documented namespaces throughout: `requests.create`, `requests.get`,
 `requests.streamEvents`, `inputs.claim`, `inputs.respond`, `spans.start`,
 `spans.add`, and `logs.add`. Their implementation helpers are private; flat
 method aliases are not part of the client API.
+
+## Caller failures and delivery retries
+
+A failed webhook delivery is one attempt, not the final request outcome. Constellation retains failed attempts even when a later retry succeeds. Retryable delivery warnings include the input ID, attempt number, callback HTTP failure and retry delay; terminal failures remain errors. The callback drawer shows that delivery and the current request state.
+
+The SDK records checkpoint and tool exceptions in `attributes.error` on the caller span and preserves the original exception. Root-cause name, bounded message and optional code are included; SQL dumps, stack traces and arbitrary error object fields are omitted, and common credential forms are redacted. This is best-effort redaction: keep sensitive values out of exception messages. Closed error spans with these details produce one linked request error log. Keep complete diagnostics in your application's own logs. Historical spans without error attributes cannot reconstruct the original exception.
+
+## Discover available HTTP operations
+
+```ts
+const contract = await client.discover();
+console.log(contract["x-constellation-access"]);
+console.log(Object.keys(contract.paths));
+```
+
+`discover(signal?)` calls `GET /v1/discover` with the client's bearer key and returns a typed OpenAPI document filtered to that key's permissions and workspace/user scope. It works with execution, management or telemetry keys. `/v1/openapi.json` is the secondary HTTP path. This describes available operations; resource ownership, model access and request lifecycle are still validated when calling them. Discovery does not grant additional access. Requires a server with the discovery endpoint deployed.
+
+## Scoped telemetry and timing
+
+Telemetry returns metadata by default: request identity/status, timestamps, costs, token counts, attempt commitment/fallback flags and record metadata. Full request/log/HTTP content requires `include: "content"`; this uses the same telemetry permission and key scope, with no extra permission. SDK content fields are optional because the default omits them. Workspace and user scope applies to hot and archived requests, events, records, HTTP, timing and timeline navigation. Global telemetry endpoints require an unscoped key.
+
+```typescript
+const page = await client.telemetry.requests.list({ externalId: "thread-123", limit: 25 });
+for (const request of page.items) {
+  const timing = await client.telemetry.requests.getTimings(request.id);
+  console.log(request.status, timing.queueMs, timing.attempts);
+}
+const detail = await client.telemetry.requests.get(requestId, { include: "content" });
+const logs = await client.telemetry.requests.listRecords(requestId, "logs", {
+  level: "warn", offset: 0, limit: 25, include: "content",
+});
+const body = await client.telemetry.requests.getHttpBody(requestId, attemptId, {
+  direction: "response", offset: 0, limit: 16384, include: "content",
+});
+```
+
+`requests.getTimings` is also available with execution authority. Timing responses include admission, queue, worker preparation, provider attempts and caller waits. Admission and preparation have recorded child/detail spans; IDs and provenance match the console. Concurrent waits count once in `callerWaitMs`. Missing/incomplete measurements are null. Read `complete`, `truncated` and `asOf`; grouped totals can overlap and are not additive.
+
+Request lists accept `RequestListQuery`, including exact `externalId` and requested-model filters, exclusions and substring matches. Record lists accept `RequestRecordsQuery` (`id`, `q`, log-only `level`, `offset`, `limit`). `PageQuery.filters` belongs only to registry list rows. Every other method has its endpoint's exact query type. See the [HTTP filter matrix](../../docs/api.md#filter-audit-and-exact-query-support) for search semantics, caps, cursor behavior and capabilities not currently provided.
+
+Unscoped telemetry also exposes `observability.getBilling`, `getTraffic`, `getTiming`, dashboard and measurement series. Use `providerId` for local series and `upstream` for gateway series. `system.getComponent(component, { status, statusNot, q, offset })` and `jobs.listHistory` page matching operational records; notifications use fixed 25-item pages and status/offset, not generic filters.

package/dist/index.js

@@ -1,4 +1,22 @@
-// ../../packages/client-core/src/index.ts
+// ../client-core/src/error-details.ts
+function callerErrorDetails(error) {
+  let cause = error;
+  const seen = new Set;
+  for (let depth = 0;depth < 8 && cause instanceof Error && !seen.has(cause); depth++) {
+    seen.add(cause);
+    if (!(cause.cause instanceof Error))
+      break;
+    cause = cause.cause;
+  }
+  const record = cause && typeof cause === "object" ? cause : {};
+  const name = cause instanceof Error ? cause.name.slice(0, 80) : "CallerError";
+  const code = typeof record.code === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(record.code) ? record.code : undefined;
+  const raw = cause instanceof Error ? cause.message : "Caller handler threw a non-Error value";
+  const message = (/Failed query:|\bparams:/i.test(raw) ? "Caller database operation failed; see caller logs" : raw).replace(/\b(?:Bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(/((?:password|token|secret|api[_-]?key)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]").replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@").slice(0, 512);
+  return { name, message, ...code ? { code } : {} };
+}
+
+// ../client-core/src/index.ts
 class ConstellationError extends Error {
   status;
   code;
@@ -306,7 +324,7 @@ class RequestClient {
               await this.#respond(id, pending.id, { ...response, claimId: consumerId }, activeSignal);
             } catch (error) {
               if (!activeSignal?.aborted && !closed)
-                await span.end({ status: "error" }, activeSignal).catch(() => {});
+                await span.end({ status: "error", attributes: { error: callerErrorDetails(error) } }, activeSignal).catch(() => {});
               throw error;
             }
           }, options.signal);
@@ -347,6 +365,7 @@ class RequestClient {
           const span = await this.#startSpan(id, `tool.${pending.payload.name}`, { stepId: pending.stepId ?? undefined, inputId: pending.id }, activeSignal);
           let result;
           let isError = false;
+          let errorDetails;
           try {
             if (pending.payload.validationError)
               throw new Error(pending.payload.validationError);
@@ -361,9 +380,10 @@ class RequestClient {
           } catch (error) {
             activeSignal?.throwIfAborted();
             isError = true;
+            errorDetails = callerErrorDetails(error);
             result = { error: error instanceof Error ? error.message : "Tool failed" };
           }
-          await span.end({ status: isError ? "error" : "ok" }, activeSignal);
+          await span.end({ status: isError ? "error" : "ok", ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
           await this.#claim(id, pending.id, consumerId, activeSignal);
           await this.#respond(id, pending.id, { result, isError, claimId: consumerId }, activeSignal);
         }, options.signal);
@@ -389,13 +409,16 @@ class RequestClient {
       preview: (input, signal) => this.#resolve(input, signal),
       get: (id, signal) => this.#inspect(id, signal),
       getSummary: (id, signal) => this.#inspectSummary(id, signal),
+      getTimings: (id, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/timings`, "GET", undefined, signal),
       list: (query = {}, signal) => this.#list(query, signal),
       cancel: (id, signal) => this.#cancel(id, signal),
       listEvents: (id, after = 0, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/events${queryString({ after })}`, "GET", undefined, signal),
       streamEvents: (id, options = {}) => this.#events(id, options),
       listRecords: (id, kind, query = {}, signal) => this.#records(id, kind, query, signal),
       getTimeline: (id, options = {}) => this.#timeline(id, options),
-      getHttpExchange: (id, attemptId, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}`, "GET", undefined, signal),
+      getHttpExchange: (id, attemptId, query = {}, signal) => {
+        return this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}${queryString(query)}`, "GET", undefined, signal);
+      },
       getHttpBody: (id, attemptId, query, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}/body${queryString(query)}`, "GET", undefined, signal)
     };
   }
@@ -418,7 +441,7 @@ class RequestClient {
   }
 }
 
-// ../../packages/sdk/src/index.ts
+// src/index.ts
 function queryString2(values) {
   const params = new URLSearchParams;
   for (const [key, value] of Object.entries(values))
@@ -462,6 +485,9 @@ class Constellation extends RequestClient {
     }
     return response.status === 204 ? undefined : response.json();
   }
+  discover(signal) {
+    return this.#call("/v1/discover", "GET", undefined, signal);
+  }
   get management() {
     return {
       registry: {
@@ -478,26 +504,39 @@ class Constellation extends RequestClient {
   }
   get telemetry() {
     const requestPath = (id) => `/v1/telemetry/requests/${encodeURIComponent(id)}`;
+    const read = (path, options = {}, extra = {}) => {
+      const value = options;
+      return this.#call(`${path}${queryString2({ ...extra, include: value.include })}`, "GET", undefined, value.signal);
+    };
     return {
       requests: {
         list: (query = {}, signal) => this.#call(`/v1/telemetry/requests${queryString2(query)}`, "GET", undefined, signal),
-        get: (id, signal) => this.#call(requestPath(id), "GET", undefined, signal),
-        getSummary: (id, signal) => this.#call(`${requestPath(id)}?summary=true`, "GET", undefined, signal),
-        listEvents: (id, after = 0, signal) => this.#call(`${requestPath(id)}/events${queryString2({ after })}`, "GET", undefined, signal),
+        get: (id, options = {}) => read(requestPath(id), options),
+        getSummary: (id, options = {}) => read(requestPath(id), options, { summary: "true" }),
+        getTimings: (id, signal) => this.#call(`${requestPath(id)}/timings`, "GET", undefined, signal),
+        listEvents: (id, after = 0, options = {}) => read(`${requestPath(id)}/events`, options, { after }),
         listRecords: (id, kind, query = {}, signal) => this.#call(`${requestPath(id)}/records/${kind}${queryString2(query)}`, "GET", undefined, signal),
-        getTimeline: (id, options = {}) => this.#call(`${requestPath(id)}/timeline${queryString2({ requestId: options.requestId })}`, "GET", undefined, options.signal),
-        getHttpExchange: (id, attemptId, signal) => this.#call(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}`, "GET", undefined, signal),
+        getTimeline: (id, options = {}) => read(`${requestPath(id)}/timeline`, options, { requestId: options.requestId }),
+        getHttpExchange: (id, attemptId, options = {}) => {
+          const value = options;
+          return read(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}`, value, { offset: value.offset, limit: value.limit });
+        },
         getHttpBody: (id, attemptId, query, signal) => this.#call(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}/body${queryString2(query)}`, "GET", undefined, signal)
       },
       system: {
-        get: (signal) => this.#call("/v1/telemetry/system", "GET", undefined, signal),
+        get: (options = {}) => read("/v1/telemetry/system", options),
         listHistory: (query = {}, signal) => this.#call(`/v1/telemetry/system/history${queryString2(query)}`, "GET", undefined, signal),
-        getComponent: (component, signal) => this.#call(`/v1/telemetry/system/${encodeURIComponent(component)}`, "GET", undefined, signal)
+        getComponent: (component, options = {}) => {
+          const value = options;
+          return read(`/v1/telemetry/system/${encodeURIComponent(component)}`, value, { offset: value.offset, status: value.status, statusNot: value.statusNot, q: value.q });
+        }
       },
       observability: {
         get: (query = {}, signal) => this.#call(`/v1/telemetry/observability${queryString2(query)}`, "GET", undefined, signal),
         getSeries: (query, signal) => this.#call(`/v1/telemetry/observability/series${queryString2(query)}`, "GET", undefined, signal),
-        getTiming: (query = {}, signal) => this.#call(`/v1/telemetry/observability/timing${queryString2(query)}`, "GET", undefined, signal)
+        getTiming: (query = {}, signal) => this.#call(`/v1/telemetry/observability/timing${queryString2(query)}`, "GET", undefined, signal),
+        getTraffic: (query = {}, signal) => this.#call(`/v1/telemetry/observability/traffic${queryString2(query)}`, "GET", undefined, signal),
+        getBilling: (query = {}, signal) => this.#call(`/v1/telemetry/observability/billing${queryString2(query)}`, "GET", undefined, signal)
       },
       jobs: {
         listHistory: (query = {}, signal) => this.#call(`/v1/telemetry/jobs/history${queryString2(query)}`, "GET", undefined, signal)

package/dist/types/client-core/src/error-details.d.ts

@@ -0,0 +1,6 @@
+/** Error telemetry deliberately omits stack traces and arbitrary object fields. */
+export declare function callerErrorDetails(error: unknown): {
+    name: string;
+    message: string;
+    code?: string;
+};

package/dist/types/client-core/src/index.d.ts

@@ -91,6 +91,9 @@ export type RequestRecord = {
     resolution: Json;
     rules: Json;
     createdAt: string;
+    receivedAt: string | null;
+    queuedAt: string | null;
+    claimedAt: string | null;
     endedAt: string | null;
     deadline: string;
 };
@@ -194,7 +197,7 @@ export type TimelineRow = {
     id: string;
     requestId: string;
     parentId: string | null;
-    kind: "request" | "step" | "attempt" | "input" | "span" | "phase" | "http_phase";
+    kind: "request" | "step" | "attempt" | "input" | "span" | "phase" | "http_phase" | "delivery";
     label: string;
     status: string;
     start: string;
@@ -327,6 +330,55 @@ export declare class ConstellationError extends Error {
     constructor(status: number, code: string, message: string);
 }
 export declare function uuid7(): string;
+/** Provider-reported token counts. Missing usage is unknown, not zero. */
+export type TokenUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    partial?: boolean;
+};
+export type TimingInterval = {
+    id: string;
+    requestId: string;
+    parentId?: string | null;
+    start: string;
+    end: string | null;
+    durationMs: number | null;
+    kind?: string;
+    name?: string;
+    source?: string;
+    label?: string;
+    origin?: "recorded" | "derived";
+    derivedFrom?: string[];
+    providerId?: string;
+    actualModel?: string;
+    offeringId?: string;
+    committed?: boolean;
+    fallback?: boolean;
+    status?: string;
+    ttftMs?: number | null;
+    ttfbMs?: number | null;
+    reasoningMs?: number | null;
+    outputMs?: number | null;
+    httpStatus?: number | null;
+};
+export type RequestTimings = {
+    requestId: string;
+    totalMs: number | null;
+    admissionMs: number | null;
+    queueMs: number | null;
+    workerPreparationMs: number | null;
+    attemptMs: number | null;
+    callerWaitMs: number | null;
+    phases: TimingInterval[];
+    attempts: TimingInterval[];
+    callerWaits: TimingInterval[];
+    asOf: string;
+    complete: boolean;
+    truncated: boolean;
+};
 export type RequestRecordsQuery = {
     id?: string;
     q?: string;
@@ -393,6 +445,7 @@ export declare class RequestClient {
         }>;
         get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
         getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
+        getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
         list: (query?: RequestListQuery, signal?: AbortSignal) => Promise<{
             items: RequestRecord[];
             total: number;
@@ -417,7 +470,10 @@ export declare class RequestClient {
             requestId?: string;
             signal?: AbortSignal;
         }) => Promise<Timeline>;
-        getHttpExchange: (id: string, attemptId: string, signal?: AbortSignal) => Promise<Json>;
+        getHttpExchange: (id: string, attemptId: string, query?: {
+            offset?: number;
+            limit?: number;
+        }, signal?: AbortSignal) => Promise<Json>;
         getHttpBody: (id: string, attemptId: string, query: {
             direction: "request" | "response";
             offset?: number;

package/dist/types/sdk/src/index.d.ts

@@ -1,7 +1,97 @@
 /** External server SDK. Operator APIs and cookie sessions are internal-only clients. */
-import { RequestClient, type WebhookEvent, type Json, type Page, type PageQuery, type ModelResolution, type RequestRecord, type Inspection, type RequestEvent, type RecordTypes, type Timeline } from "../../client-core/src/index";
+import { RequestClient, type WebhookEvent, type Json, type Page, type PageQuery, type ModelResolution, type RequestRecord, type RequestEvent, type RecordTypes, type Timeline, type TimelineRow, type RequestListQuery, type RequestRecordsQuery, type RequestTimings, type TokenUsage } from "../../client-core/src/index";
 export { ConstellationError, uuid7 } from "../../client-core/src/index";
-export type { Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Status, RequestRecord, Step, Attempt, PreparedStep, PendingInput, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, InputResponse, InputHandlers, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, StartSpanOptions } from "../../client-core/src/index";
+export type { Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, RequestTimings, TimingInterval, TokenUsage, Status, RequestRecord, Step, Attempt, PreparedStep, PendingInput, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, InputResponse, InputHandlers, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, StartSpanOptions } from "../../client-core/src/index";
+/** OpenAPI contract filtered to this key's permissions and scope. */
+export type DiscoveryDocument = {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    paths: Record<string, Record<string, Json>>;
+    components: {
+        schemas: Record<string, Json>;
+        securitySchemes: Record<string, Json>;
+    };
+    "x-constellation-access": {
+        permissions: string[];
+        workspaceId: string | null;
+        userId: string | null;
+    };
+};
+/** Telemetry excludes request/log/HTTP content unless explicitly requested. No additional permission is required. */
+export type TelemetryPage<T> = Page<T> & {
+    metadataOnly?: true;
+};
+export type TelemetryQuery = {
+    include?: "content";
+};
+export type TelemetryReadOptions = TelemetryQuery & {
+    signal?: AbortSignal;
+};
+export type PaginationQuery = {
+    offset?: number;
+    limit?: number;
+};
+export type OperationsQuery = {
+    offset?: number;
+    status?: string;
+    statusNot?: string;
+    q?: string;
+};
+export type ObservabilityQuery = PaginationQuery & {
+    hours?: 1 | 24 | 168;
+    providerId?: string;
+    modelId?: string;
+    upstream?: string;
+    q?: string;
+};
+export type LogSearchQuery = PaginationQuery & {
+    q?: string;
+    level?: "trace" | "debug" | "info" | "warn" | "error";
+    levelNot?: "trace" | "debug" | "info" | "warn" | "error";
+    target?: string;
+    targetNot?: string;
+    requestId?: string;
+    requestIdNot?: string;
+    from?: string;
+    to?: string;
+};
+type OptionalContent<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type TelemetryRequest = OptionalContent<RequestRecord, "output" | "error" | "reason" | "resolution" | "rules">;
+export type TelemetryRecords = {
+    steps: OptionalContent<RecordTypes["steps"], "input" | "output" | "resolution" | "rules" | "customerPrice">;
+    attempts: OptionalContent<RecordTypes["attempts"], "endpoint" | "parameters" | "supplierPrice" | "customerPrice" | "error">;
+    inputs: Partial<RecordTypes["inputs"]> & {
+        id: string;
+        requestId: string;
+    };
+    spans: Partial<RecordTypes["spans"]> & {
+        id: string;
+        requestId: string;
+    };
+    logs: OptionalContent<RecordTypes["logs"], "message" | "attributes">;
+};
+export type TelemetryTimeline = Omit<Timeline, "rows"> & {
+    metadataOnly?: true;
+    rows: (Omit<TimelineRow, "label"> & {
+        label?: string;
+    })[];
+};
+export type TelemetryInspection = {
+    metadataOnly?: true;
+    request: TelemetryRequest;
+    usage?: TokenUsage;
+    input?: Json;
+    effectiveInput?: Json;
+    steps: TelemetryRecords["steps"][];
+    attempts: TelemetryRecords["attempts"][];
+    inputs: TelemetryRecords["inputs"][];
+    spans: TelemetryRecords["spans"][];
+    logs: TelemetryRecords["logs"][];
+};
 export declare class Constellation extends RequestClient {
     #private;
     constructor(options: {
@@ -10,6 +100,8 @@ export declare class Constellation extends RequestClient {
         fetch?: typeof fetch;
         timeoutMs?: number;
     });
+    /** Discover HTTP operations available to this bearer key. */
+    discover(signal?: AbortSignal): Promise<DiscoveryDocument>;
     /** Registry authoring only; keys, credentials and capacity controls are internal. */
     get management(): {
         registry: {
@@ -20,7 +112,7 @@ export declare class Constellation extends RequestClient {
                 catalog: Json;
             }, signal?: AbortSignal) => Promise<Json>;
             applyChanges: (changes: Json[], signal?: AbortSignal) => Promise<Json>;
-            listHistory: (kind: string, id: string, query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            listHistory: (kind: string, id: string, query?: PaginationQuery, signal?: AbortSignal) => Promise<Page<Json>>;
             rollback: (kind: string, id: string, input: {
                 toVersion: number;
                 expectedVersion: number;
@@ -32,62 +124,84 @@ export declare class Constellation extends RequestClient {
             }, signal?: AbortSignal) => Promise<Json>;
         };
     };
-    /** Read-only operational endpoints require a telemetry key. */
+    /** Request reads enforce key scope; global operational reads require an unscoped telemetry key. Metadata is the default. */
     get telemetry(): {
         requests: {
-            list: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<RequestRecord>>;
-            get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
-            getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
-            listEvents: (id: string, after?: number, signal?: AbortSignal) => Promise<{
+            list: (query?: RequestListQuery & TelemetryQuery, signal?: AbortSignal) => Promise<TelemetryPage<TelemetryRequest>>;
+            get: (id: string, options?: TelemetryReadOptions) => Promise<TelemetryInspection>;
+            getSummary: (id: string, options?: TelemetryReadOptions) => Promise<TelemetryInspection>;
+            getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
+            listEvents: (id: string, after?: number, options?: TelemetryReadOptions) => Promise<{
                 items: RequestEvent[];
+                metadataOnly?: true;
             }>;
-            listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: PageQuery, signal?: AbortSignal) => Promise<Page<RecordTypes[K]>>;
-            getTimeline: (id: string, options?: {
+            listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: RequestRecordsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<TelemetryPage<TelemetryRecords[K]>>;
+            getTimeline: (id: string, options?: TelemetryReadOptions & {
                 requestId?: string;
-                signal?: AbortSignal;
-            }) => Promise<Timeline>;
-            getHttpExchange: (id: string, attemptId: string, signal?: AbortSignal) => Promise<Json>;
-            getHttpBody: (id: string, attemptId: string, query: {
+            }) => Promise<TelemetryTimeline>;
+            getHttpExchange: (id: string, attemptId: string, options?: TelemetryReadOptions & PaginationQuery) => Promise<Json>;
+            getHttpBody: (id: string, attemptId: string, query: TelemetryQuery & {
                 direction: "request" | "response";
                 offset?: number;
                 limit?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
         system: {
-            get: (signal?: AbortSignal) => Promise<Json>;
-            listHistory: (query?: {
+            get: (options?: TelemetryReadOptions) => Promise<Json>;
+            listHistory: (query?: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
-            getComponent: (component: string, signal?: AbortSignal) => Promise<Json>;
+            getComponent: (component: string, options?: TelemetryReadOptions & OperationsQuery) => Promise<Json>;
         };
         observability: {
-            get: (query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            getSeries: (query: {
-                source: "local" | "gateway";
+            get: (query?: ObservabilityQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
+            getSeries: (query: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
-                providerId?: string;
                 modelId?: string;
+            } & ({
+                source: "local";
+                providerId?: string;
+                upstream?: never;
+            } | {
+                source: "gateway";
+                upstream?: string;
+                providerId?: never;
+            }), signal?: AbortSignal) => Promise<Json>;
+            getTiming: (query?: TelemetryQuery & {
+                hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
-            getTiming: (query?: {
+            getTraffic: (query?: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
+            getBilling: (query?: PaginationQuery & TelemetryQuery & {
+                hours?: 1 | 24 | 168 | 720;
+                providerId?: string;
+                modelId?: string;
+                groupBy?: "provider" | "model";
+            }, signal?: AbortSignal) => Promise<Json>;
         };
         jobs: {
-            listHistory: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            listHistory: (query?: OperationsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
         };
         notifications: {
-            list: (query?: PageQuery & {
+            list: (query?: TelemetryQuery & {
+                offset?: number;
                 status?: "active" | "resolved";
-            }, signal?: AbortSignal) => Promise<Page<Json>>;
-            get: (id: string, query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            listEvents: (query?: {
+            }, signal?: AbortSignal) => Promise<Json>;
+            get: (id: string, query?: TelemetryQuery & {
+                offset?: number;
+            }, signal?: AbortSignal) => Promise<Json>;
+            listEvents: (query?: TelemetryQuery & {
                 after?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
         logs: {
-            searchSystem: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            searchRequests: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            searchAudit: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchSystem: (query?: LogSearchQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchRequests: (query?: Omit<LogSearchQuery, "level" | "levelNot" | "target" | "targetNot"> & {
+                level?: "debug" | "info" | "warn" | "error";
+                levelNot?: "debug" | "info" | "warn" | "error";
+            } & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchAudit: (query?: Omit<LogSearchQuery, "requestId" | "requestIdNot"> & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
         };
     };
     get webhooks(): {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript client for durable model requests and caller events",
   "type": "module",
   "license": "UNLICENSED",