@yuliaedomskikh/agentflow-client 1.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @yuliaedomskikh/agentflow-client
+
+> Published npm package: **`@yuliaedomskikh/agentflow-client`**.
+
+Install:
+
+```bash
+npm install @yuliaedomskikh/agentflow-client
+```
+
+```ts
+import { AgentFlowClient } from "@yuliaedomskikh/agentflow-client";
+const client = new AgentFlowClient("http://localhost:8000", "dev-key");
+const order = await client.getOrder("ORD-20260404-1001");
+console.log(order.status, (await client.getMetric("revenue", "24h")).value);
+```
+
+```ts
+import {
+  AgentFlowClient,
+  RetryPolicy,
+} from "@yuliaedomskikh/agentflow-client";
+
+const client = new AgentFlowClient("http://localhost:8000", "dev-key");
+client.configureResilience({
+  retryPolicy: new RetryPolicy({ maxAttempts: 5 }),
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { AgentFlowClient } from "./src/client.js";
+export { CircuitBreaker, CircuitOpenError, CircuitState, } from "./src/circuitBreaker.js";
+export { AgentFlowError, AuthError, DataFreshnessError, EntityNotFoundError, RateLimitError, } from "./src/exceptions.js";
+export { RetryPolicy } from "./src/retry.js";
+export type { BatchItem, BatchResponse, CatalogResponse, ClientOptions, EventFilters, HealthStatus, MetricName, MetricResult, OrderEntity, PipelineEvent, ProductEntity, QueryResult, SessionEntity, TimeWindow, UserEntity, } from "./src/models.js";
+export type { CircuitBreakerOptions } from "./src/circuitBreaker.js";
+export type { RetryPolicyOptions } from "./src/retry.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { AgentFlowClient } from "./src/client.js";
+export { CircuitBreaker, CircuitOpenError, CircuitState, } from "./src/circuitBreaker.js";
+export { AgentFlowError, AuthError, DataFreshnessError, EntityNotFoundError, RateLimitError, } from "./src/exceptions.js";
+export { RetryPolicy } from "./src/retry.js";

package/dist/src/circuitBreaker.d.ts

@@ -0,0 +1,28 @@
+import { AgentFlowError } from "./exceptions.js";
+export declare enum CircuitState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "half_open"
+}
+export declare class CircuitOpenError extends AgentFlowError {
+    constructor(message?: string);
+}
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    resetTimeoutMs?: number;
+    halfOpenMaxCalls?: number;
+}
+export declare class CircuitBreaker {
+    readonly failureThreshold: number;
+    readonly resetTimeoutMs: number;
+    readonly halfOpenMaxCalls: number;
+    private _state;
+    private failureCount;
+    private openedAt;
+    private halfOpenCalls;
+    constructor(options?: CircuitBreakerOptions);
+    beforeCall(): void;
+    recordSuccess(): void;
+    recordFailure(): void;
+    get state(): CircuitState;
+}

package/dist/src/circuitBreaker.js

@@ -0,0 +1,66 @@
+import { AgentFlowError } from "./exceptions.js";
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "closed";
+    CircuitState["OPEN"] = "open";
+    CircuitState["HALF_OPEN"] = "half_open";
+})(CircuitState || (CircuitState = {}));
+export class CircuitOpenError extends AgentFlowError {
+    constructor(message = "circuit is open") {
+        super(message);
+        this.name = "CircuitOpenError";
+    }
+}
+export class CircuitBreaker {
+    failureThreshold;
+    resetTimeoutMs;
+    halfOpenMaxCalls;
+    _state = CircuitState.CLOSED;
+    failureCount = 0;
+    openedAt = 0;
+    halfOpenCalls = 0;
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.resetTimeoutMs = options.resetTimeoutMs ?? 30_000;
+        this.halfOpenMaxCalls = options.halfOpenMaxCalls ?? 1;
+    }
+    beforeCall() {
+        if (this._state === CircuitState.OPEN) {
+            if (Date.now() - this.openedAt >= this.resetTimeoutMs) {
+                this._state = CircuitState.HALF_OPEN;
+                this.halfOpenCalls = 0;
+            }
+            else {
+                throw new CircuitOpenError("circuit is open");
+            }
+        }
+        if (this._state === CircuitState.HALF_OPEN) {
+            if (this.halfOpenCalls >= this.halfOpenMaxCalls) {
+                throw new CircuitOpenError("circuit is half-open, probe in flight");
+            }
+            this.halfOpenCalls += 1;
+        }
+    }
+    recordSuccess() {
+        this._state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.halfOpenCalls = 0;
+    }
+    recordFailure() {
+        if (this._state === CircuitState.HALF_OPEN) {
+            this._state = CircuitState.OPEN;
+            this.openedAt = Date.now();
+            this.halfOpenCalls = 0;
+            return;
+        }
+        this.failureCount += 1;
+        if (this.failureCount >= this.failureThreshold) {
+            this._state = CircuitState.OPEN;
+            this.openedAt = Date.now();
+            this.halfOpenCalls = 0;
+        }
+    }
+    get state() {
+        return this._state;
+    }
+}

package/dist/src/client.d.ts

@@ -0,0 +1,55 @@
+import type { BatchItem, BatchResponse, CatalogResponse, EventFilters, FetchLike, HealthStatus, MetricName, MetricResult, OrderEntity, PipelineEvent, ProductEntity, QueryResult, SessionEntity, TimeWindow, UserEntity } from "./models.js";
+import { CircuitBreaker } from "./circuitBreaker.js";
+import { RetryPolicy } from "./retry.js";
+export declare class AgentFlowClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly contractVersions;
+    private readonly contractCache;
+    retryPolicy: RetryPolicy;
+    circuitBreaker: CircuitBreaker;
+    constructor(baseUrl: string, apiKey: string, options?: {
+        fetch?: FetchLike;
+        timeoutMs?: number;
+        headers?: HeadersInit;
+        contractVersion?: string;
+    });
+    configureResilience(options: {
+        retryPolicy?: RetryPolicy;
+        circuitBreaker?: CircuitBreaker;
+    }): this;
+    getOrder(orderId: string): Promise<OrderEntity>;
+    getUser(userId: string): Promise<UserEntity>;
+    getProduct(productId: string): Promise<ProductEntity>;
+    getSession(sessionId: string): Promise<SessionEntity>;
+    getMetric(name: MetricName | string, window?: TimeWindow | string): Promise<MetricResult>;
+    query(question: string): Promise<QueryResult>;
+    health(): Promise<HealthStatus>;
+    isFresh(maxAgeSeconds?: number): Promise<boolean>;
+    catalog(): Promise<CatalogResponse>;
+    streamEvents(filters?: EventFilters): AsyncGenerator<PipelineEvent>;
+    batch(requests: BatchItem[]): Promise<BatchResponse>;
+    batchEntity(entityType: string, entityId: string, requestId?: string): BatchItem;
+    batchMetric(name: MetricName | string, window?: TimeWindow | string, requestId?: string): BatchItem;
+    batchQuery(question: string, context?: Record<string, unknown>, requestId?: string): BatchItem;
+    private resolveFetch;
+    private parseContractVersions;
+    private getEntity;
+    private applyContractVersion;
+    private getContract;
+    private requestJson;
+    private fetchResponse;
+    private throwHttpError;
+    private readJson;
+    private errorDetail;
+    private extractFreshnessSeconds;
+    private normalizeEntity;
+    private normalizeQueryMetadata;
+    private toNumber;
+    private toNullableNumber;
+    private objectHeaders;
+    private requestId;
+}

package/dist/src/client.js

@@ -0,0 +1,375 @@
+import { AgentFlowError, AuthError, DataFreshnessError, EntityNotFoundError, RateLimitError, } from "./exceptions.js";
+import { CircuitBreaker } from "./circuitBreaker.js";
+import { RETRYABLE_STATUS, RetryPolicy, isRetryableMethod, } from "./retry.js";
+import { streamSseJson } from "./stream.js";
+const ENTITY_NUMBER_FIELDS = {
+    order: ["total_amount"],
+    user: ["total_orders", "total_spent"],
+    product: ["price", "stock_quantity"],
+    session: ["duration_seconds", "event_count", "unique_pages"],
+};
+export class AgentFlowClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    timeoutMs;
+    headers;
+    contractVersions;
+    contractCache = new Map();
+    retryPolicy;
+    circuitBreaker;
+    constructor(baseUrl, apiKey, options = {}) {
+        const legacyOptions = options;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.fetchImpl = options.fetch ?? this.resolveFetch();
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.headers = options.headers;
+        this.contractVersions = this.parseContractVersions(options.contractVersion);
+        this.retryPolicy = legacyOptions.retryPolicy ?? new RetryPolicy();
+        this.circuitBreaker = legacyOptions.circuitBreaker ?? new CircuitBreaker();
+    }
+    configureResilience(options) {
+        if (options.retryPolicy) {
+            this.retryPolicy = options.retryPolicy;
+        }
+        if (options.circuitBreaker) {
+            this.circuitBreaker = options.circuitBreaker;
+        }
+        return this;
+    }
+    async getOrder(orderId) {
+        return this.getEntity("order", orderId);
+    }
+    async getUser(userId) {
+        return this.getEntity("user", userId);
+    }
+    async getProduct(productId) {
+        return this.getEntity("product", productId);
+    }
+    async getSession(sessionId) {
+        return this.getEntity("session", sessionId);
+    }
+    async getMetric(name, window = "1h") {
+        const payload = await this.requestJson("GET", `/v1/metrics/${encodeURIComponent(name)}`, { params: { window } });
+        return {
+            ...payload,
+            value: this.toNumber(payload.value),
+            components: payload.components ?? null,
+        };
+    }
+    async query(question) {
+        const payload = await this.requestJson("POST", "/v1/query", {
+            json: { question },
+        });
+        return {
+            ...payload,
+            metadata: this.normalizeQueryMetadata(payload.metadata ?? {}),
+        };
+    }
+    async health() {
+        const payload = await this.requestJson("GET", "/v1/health");
+        return {
+            ...payload,
+            freshness_seconds: this.extractFreshnessSeconds(payload.components),
+        };
+    }
+    async isFresh(maxAgeSeconds = 60) {
+        const health = await this.health();
+        if (health.status !== "healthy") {
+            throw new DataFreshnessError(`Pipeline is ${health.status}; freshness check cannot be trusted`);
+        }
+        if (health.freshness_seconds == null) {
+            throw new DataFreshnessError("Pipeline freshness metric is unavailable");
+        }
+        return health.freshness_seconds < maxAgeSeconds;
+    }
+    async catalog() {
+        return this.requestJson("GET", "/v1/catalog");
+    }
+    streamEvents(filters = {}) {
+        const self = this;
+        return (async function* () {
+            const response = await self.fetchResponse("GET", "/v1/stream/events", {
+                params: {
+                    event_type: filters.eventType,
+                    entity_id: filters.entityId,
+                },
+                accept: "text/event-stream",
+                signal: filters.signal,
+            });
+            yield* streamSseJson(response, filters.signal);
+        })();
+    }
+    async batch(requests) {
+        return this.requestJson("POST", "/v1/batch", {
+            json: { requests },
+        });
+    }
+    batchEntity(entityType, entityId, requestId) {
+        return {
+            id: requestId ?? this.requestId("entity"),
+            type: "entity",
+            params: {
+                entity_type: entityType,
+                entity_id: entityId,
+            },
+        };
+    }
+    batchMetric(name, window = "1h", requestId) {
+        return {
+            id: requestId ?? this.requestId("metric"),
+            type: "metric",
+            params: { name, window },
+        };
+    }
+    batchQuery(question, context, requestId) {
+        return {
+            id: requestId ?? this.requestId("query"),
+            type: "query",
+            params: context == null ? { question } : { question, context },
+        };
+    }
+    resolveFetch() {
+        if (typeof fetch !== "function") {
+            throw new AgentFlowError("Global fetch is unavailable. Pass options.fetch when constructing AgentFlowClient.");
+        }
+        return fetch.bind(globalThis);
+    }
+    parseContractVersions(contractVersion) {
+        if (!contractVersion) {
+            return {};
+        }
+        const [entity, rawVersion] = contractVersion.split(":", 2);
+        if (!entity || !rawVersion) {
+            throw new Error("contractVersion must use '<entity>:<version>' format.");
+        }
+        return {
+            [entity]: rawVersion.startsWith("v") ? rawVersion.slice(1) : rawVersion,
+        };
+    }
+    async getEntity(entityType, entityId) {
+        const envelope = await this.requestJson("GET", `/v1/entity/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`);
+        const versioned = await this.applyContractVersion(entityType, envelope.data);
+        return this.normalizeEntity(entityType, versioned);
+    }
+    async applyContractVersion(entityType, payload) {
+        const version = this.contractVersions[entityType];
+        if (!version) {
+            return payload;
+        }
+        const contract = await this.getContract(entityType, version);
+        const requiredFields = contract.fields
+            .filter((field) => field.required)
+            .map((field) => field.name);
+        const missingFields = requiredFields.filter((field) => !(field in payload));
+        if (missingFields.length > 0) {
+            throw new AgentFlowError("Contract validation failed. Missing required fields: "
+                + missingFields.join(", "));
+        }
+        const allowedFields = new Set(contract.fields.map((field) => field.name));
+        const filteredEntries = Object.entries(payload).filter(([key]) => allowedFields.has(key));
+        return Object.fromEntries(filteredEntries);
+    }
+    async getContract(entityType, version) {
+        const cacheKey = `${entityType}:${version}`;
+        const cached = this.contractCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const contract = await this.requestJson("GET", `/v1/contracts/${encodeURIComponent(entityType)}/${encodeURIComponent(version)}`);
+        this.contractCache.set(cacheKey, contract);
+        return contract;
+    }
+    async requestJson(method, path, options = {}) {
+        const response = await this.fetchResponse(method, path, options);
+        const payload = await this.readJson(response);
+        return payload;
+    }
+    async fetchResponse(method, path, options = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(options.params ?? {})) {
+            if (value != null) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = {
+            Accept: options.accept ?? "application/json",
+            "X-API-Key": this.apiKey,
+            ...(options.json ? { "Content-Type": "application/json" } : {}),
+            ...this.objectHeaders(this.headers),
+        };
+        const canRetry = isRetryableMethod(method, headers);
+        let attempt = 0;
+        this.circuitBreaker.beforeCall();
+        while (true) {
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            const timeoutId = this.timeoutMs > 0
+                ? setTimeout(() => controller.abort(), this.timeoutMs)
+                : undefined;
+            try {
+                const response = await this.fetchImpl(url.toString(), {
+                    method,
+                    headers,
+                    body: options.json ? JSON.stringify(options.json) : undefined,
+                    signal: controller.signal,
+                });
+                const retryAfterHeader = response.headers.get("retry-after");
+                const retryAfterSeconds = retryAfterHeader == null
+                    ? undefined
+                    : Number(retryAfterHeader);
+                if (canRetry
+                    && RETRYABLE_STATUS.has(response.status)
+                    && attempt < this.retryPolicy.maxAttempts - 1) {
+                    const delayMs = this.retryPolicy.computeDelay(attempt, Number.isFinite(retryAfterSeconds) ? retryAfterSeconds * 1_000 : undefined);
+                    attempt += 1;
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                    continue;
+                }
+                if (response.status >= 500) {
+                    this.circuitBreaker.recordFailure();
+                }
+                else {
+                    this.circuitBreaker.recordSuccess();
+                }
+                if (!response.ok) {
+                    await this.throwHttpError(response, path);
+                }
+                return response;
+            }
+            catch (error) {
+                if (error instanceof AgentFlowError
+                    || error instanceof AuthError
+                    || error instanceof RateLimitError
+                    || error instanceof EntityNotFoundError) {
+                    throw error;
+                }
+                const timedOut = controller.signal.aborted && !options.signal?.aborted;
+                const userAborted = controller.signal.aborted && !!options.signal?.aborted;
+                if (!userAborted && canRetry && attempt < this.retryPolicy.maxAttempts - 1) {
+                    const delayMs = this.retryPolicy.computeDelay(attempt);
+                    attempt += 1;
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                    continue;
+                }
+                if (!userAborted) {
+                    this.circuitBreaker.recordFailure();
+                }
+                const message = timedOut
+                    ? `Request timed out after ${this.timeoutMs}ms`
+                    : error instanceof Error
+                        ? error.message
+                        : "Unknown request error";
+                throw new AgentFlowError(`Request failed: ${message}`);
+            }
+            finally {
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+                options.signal?.removeEventListener("abort", onAbort);
+            }
+        }
+    }
+    async throwHttpError(response, path) {
+        const payload = await this.readJson(response, true);
+        const detail = this.errorDetail(payload, response);
+        if (response.status === 401) {
+            throw new AuthError(detail ?? "Unauthorized");
+        }
+        if (response.status === 429) {
+            const retryAfterHeader = response.headers.get("retry-after");
+            const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : 0;
+            throw new RateLimitError(detail ?? "Rate limit exceeded", retryAfter || 0);
+        }
+        if (response.status === 404) {
+            const parts = path.split("/").filter(Boolean);
+            if (parts.length >= 4 && parts[1] === "entity") {
+                throw new EntityNotFoundError(parts[2], parts[3], detail ?? undefined);
+            }
+        }
+        throw new AgentFlowError(detail ?? response.statusText, response.status);
+    }
+    async readJson(response, allowEmpty = false) {
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("application/json")) {
+            if (allowEmpty) {
+                return {};
+            }
+            throw new AgentFlowError(`Expected JSON response but received '${contentType || "unknown"}'`);
+        }
+        const payload = (await response.json());
+        if (payload && typeof payload === "object") {
+            return payload;
+        }
+        if (allowEmpty) {
+            return {};
+        }
+        throw new AgentFlowError("Response payload is not an object");
+    }
+    errorDetail(payload, response) {
+        const detail = payload.detail;
+        if (typeof detail === "string") {
+            return detail;
+        }
+        return response.statusText || undefined;
+    }
+    extractFreshnessSeconds(components) {
+        for (const component of components) {
+            if (component.name === "freshness") {
+                const value = component.metrics.last_event_age_seconds;
+                return typeof value === "number" ? value : value == null ? null : Number(value);
+            }
+        }
+        return null;
+    }
+    normalizeEntity(entityType, entity) {
+        const normalized = { ...entity };
+        for (const field of ENTITY_NUMBER_FIELDS[entityType] ?? []) {
+            if (field in normalized) {
+                normalized[field] = this.toNullableNumber(normalized[field]);
+            }
+        }
+        return normalized;
+    }
+    normalizeQueryMetadata(metadata) {
+        const normalized = { ...metadata };
+        for (const field of [
+            "rows_returned",
+            "execution_time_ms",
+            "data_freshness_seconds",
+        ]) {
+            if (field in normalized) {
+                normalized[field] = this.toNullableNumber(normalized[field]);
+            }
+        }
+        return normalized;
+    }
+    toNumber(value) {
+        return typeof value === "number" ? value : Number(value);
+    }
+    toNullableNumber(value) {
+        if (value == null) {
+            return null;
+        }
+        return this.toNumber(value);
+    }
+    objectHeaders(headers) {
+        if (!headers) {
+            return {};
+        }
+        if (headers instanceof Headers) {
+            return Object.fromEntries(headers.entries());
+        }
+        if (Array.isArray(headers)) {
+            return Object.fromEntries(headers);
+        }
+        return headers;
+    }
+    requestId(prefix) {
+        const token = globalThis.crypto?.randomUUID?.().replace(/-/g, "").slice(0, 8)
+            ?? Math.random().toString(16).slice(2, 10);
+        return `${prefix}-${token}`;
+    }
+}

package/dist/src/exceptions.d.ts

@@ -0,0 +1,19 @@
+export declare class AgentFlowError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare class AuthError extends AgentFlowError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends AgentFlowError {
+    readonly retryAfter: number;
+    constructor(message?: string, retryAfter?: number);
+}
+export declare class DataFreshnessError extends AgentFlowError {
+    constructor(message: string);
+}
+export declare class EntityNotFoundError extends AgentFlowError {
+    readonly entityType: string;
+    readonly entityId: string;
+    constructor(entityType: string, entityId: string, message?: string);
+}

package/dist/src/exceptions.js

@@ -0,0 +1,38 @@
+export class AgentFlowError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "AgentFlowError";
+        this.statusCode = statusCode;
+    }
+}
+export class AuthError extends AgentFlowError {
+    constructor(message = "Unauthorized") {
+        super(message, 401);
+        this.name = "AuthError";
+    }
+}
+export class RateLimitError extends AgentFlowError {
+    retryAfter;
+    constructor(message = "Rate limit exceeded", retryAfter = 0) {
+        super(message, 429);
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+export class DataFreshnessError extends AgentFlowError {
+    constructor(message) {
+        super(message);
+        this.name = "DataFreshnessError";
+    }
+}
+export class EntityNotFoundError extends AgentFlowError {
+    entityType;
+    entityId;
+    constructor(entityType, entityId, message) {
+        super(message ?? `${entityType}/${entityId} not found`, 404);
+        this.name = "EntityNotFoundError";
+        this.entityType = entityType;
+        this.entityId = entityId;
+    }
+}

package/dist/src/models.d.ts

@@ -0,0 +1,157 @@
+import type { CircuitBreaker } from "./circuitBreaker.js";
+import type { RetryPolicy } from "./retry.js";
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface ClientOptions {
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    headers?: HeadersInit;
+    contractVersion?: string;
+    retryPolicy?: RetryPolicy;
+    circuitBreaker?: CircuitBreaker;
+}
+export type MetricName = "revenue" | "order_count" | "avg_order_value" | "conversion_rate" | "active_sessions" | "error_rate";
+export type TimeWindow = "5m" | "15m" | "1h" | "6h" | "24h" | "7d" | "now";
+export interface EntityEnvelope<TData extends Record<string, unknown>> {
+    entity_type: string;
+    entity_id: string;
+    data: TData;
+    last_updated: string | null;
+    freshness_seconds: number | null;
+    meta?: Record<string, unknown>;
+}
+export interface OrderEntity {
+    order_id: string;
+    user_id: string;
+    status: string;
+    total_amount: number;
+    currency: string;
+    created_at: string;
+    is_overdue?: boolean;
+}
+export interface UserEntity {
+    user_id: string;
+    total_orders: number;
+    total_spent: number;
+    first_order_at: string;
+    last_order_at: string;
+    preferred_category: string;
+}
+export interface ProductEntity {
+    product_id: string;
+    name: string;
+    category: string;
+    price: number;
+    in_stock: boolean;
+    stock_quantity: number;
+}
+export interface SessionEntity {
+    session_id: string;
+    user_id: string | null;
+    started_at: string;
+    ended_at: string | null;
+    duration_seconds: number | null;
+    event_count: number;
+    unique_pages: number;
+    funnel_stage: string;
+    is_conversion: boolean;
+}
+export interface MetricResult {
+    metric_name: string;
+    value: number;
+    unit: string;
+    window: string;
+    computed_at: string;
+    components: Record<string, unknown> | null;
+    meta?: Record<string, unknown>;
+}
+export interface QueryMetadata {
+    rows_returned?: number;
+    execution_time_ms?: number;
+    data_freshness_seconds?: number | null;
+    [key: string]: unknown;
+}
+export interface QueryResult {
+    answer: Record<string, unknown> | Array<Record<string, unknown>>;
+    sql: string | null;
+    metadata: QueryMetadata;
+}
+export interface HealthComponent {
+    name: string;
+    status: string;
+    message: string;
+    metrics: Record<string, unknown>;
+    source: string;
+}
+export interface HealthStatus {
+    status: string;
+    checked_at: string;
+    components: HealthComponent[];
+    freshness_seconds: number | null;
+}
+export interface CatalogEntity {
+    description: string;
+    fields: Record<string, string>;
+    primary_key: string;
+    contract_version?: string | null;
+}
+export interface CatalogMetric {
+    description: string;
+    unit: string;
+    available_windows: string[];
+    contract_version?: string | null;
+}
+export interface StreamingSource {
+    path: string;
+    transport: string;
+    description: string;
+    filters?: Record<string, unknown>;
+}
+export interface AuditSource {
+    path: string;
+    description: string;
+    layers?: string[];
+}
+export interface CatalogResponse {
+    entities: Record<string, CatalogEntity>;
+    metrics: Record<string, CatalogMetric>;
+    streaming_sources?: Record<string, StreamingSource>;
+    audit_sources?: Record<string, AuditSource>;
+}
+export interface BatchItem {
+    id: string;
+    type: "entity" | "metric" | "query";
+    params: Record<string, unknown>;
+}
+export interface BatchResult {
+    id: string;
+    status: "ok" | "error";
+    data?: Record<string, unknown>;
+    error?: string;
+}
+export interface BatchResponse {
+    results: BatchResult[];
+    duration_ms: number;
+}
+export interface EventFilters {
+    eventType?: string;
+    entityId?: string;
+    signal?: AbortSignal;
+}
+export interface PipelineEvent {
+    event_id: string;
+    topic?: string | null;
+    processed_at?: string | null;
+    event_type?: string | null;
+    entity_id?: string | null;
+    latency_ms?: number | null;
+    [key: string]: unknown;
+}
+export interface ContractField {
+    name: string;
+    required?: boolean;
+}
+export interface ContractResponse {
+    entity: string;
+    version: string;
+    fields: ContractField[];
+}

package/dist/src/models.js

@@ -0,0 +1 @@
+export {};

package/dist/src/retry.d.ts

@@ -0,0 +1,16 @@
+export declare const RETRYABLE_STATUS: Set<number>;
+export interface RetryPolicyOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    jitterFactor?: number;
+}
+export declare class RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly jitterFactor: number;
+    constructor(options?: RetryPolicyOptions);
+    computeDelay(attempt: number, retryAfterMs?: number): number;
+}
+export declare function isRetryableMethod(method: string, headers?: HeadersInit): boolean;

package/dist/src/retry.js

@@ -0,0 +1,45 @@
+export const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 250;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_JITTER_FACTOR = 0.3;
+export class RetryPolicy {
+    maxAttempts;
+    initialDelayMs;
+    maxDelayMs;
+    jitterFactor;
+    constructor(options = {}) {
+        this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+        this.maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+        this.jitterFactor = options.jitterFactor ?? DEFAULT_JITTER_FACTOR;
+    }
+    computeDelay(attempt, retryAfterMs) {
+        if (retryAfterMs != null) {
+            return Math.min(Math.max(retryAfterMs, 0), this.maxDelayMs);
+        }
+        const base = Math.min(this.initialDelayMs * 2 ** attempt, this.maxDelayMs);
+        if (this.jitterFactor === 0) {
+            return base;
+        }
+        const jitterRange = base * this.jitterFactor;
+        const jitter = (Math.random() * jitterRange * 2) - jitterRange;
+        return Math.max(0, Math.min(base + jitter, this.maxDelayMs));
+    }
+}
+export function isRetryableMethod(method, headers) {
+    const normalizedMethod = method.toUpperCase();
+    if (["GET", "HEAD", "PUT", "DELETE", "OPTIONS"].includes(normalizedMethod)) {
+        return true;
+    }
+    if (normalizedMethod !== "POST" || headers == null) {
+        return false;
+    }
+    if (headers instanceof Headers) {
+        return headers.has("Idempotency-Key");
+    }
+    if (Array.isArray(headers)) {
+        return headers.some(([key]) => key.toLowerCase() === "idempotency-key");
+    }
+    return Object.keys(headers).some((key) => key.toLowerCase() === "idempotency-key");
+}

package/dist/src/stream.d.ts

@@ -0,0 +1 @@
+export declare function streamSseJson<T>(response: Response, signal?: AbortSignal): AsyncGenerator<T>;

package/dist/src/stream.js

@@ -0,0 +1,61 @@
+import { AgentFlowError } from "./exceptions.js";
+export async function* streamSseJson(response, signal) {
+    if (!response.body) {
+        throw new AgentFlowError("SSE response body is empty");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                await reader.cancel();
+                return;
+            }
+            const chunk = await reader.read();
+            if (chunk.done) {
+                break;
+            }
+            buffer += decoder.decode(chunk.value, { stream: true }).replace(/\r\n/g, "\n");
+            for (;;) {
+                const boundaryIndex = buffer.indexOf("\n\n");
+                if (boundaryIndex === -1) {
+                    break;
+                }
+                const frame = buffer.slice(0, boundaryIndex);
+                buffer = buffer.slice(boundaryIndex + 2);
+                const data = frame
+                    .split("\n")
+                    .filter((line) => line.startsWith("data:"))
+                    .map((line) => line.slice(5).trimStart())
+                    .join("\n");
+                if (data) {
+                    yield JSON.parse(data);
+                }
+            }
+        }
+        buffer += decoder.decode().replace(/\r\n/g, "\n");
+        if (buffer.trim().startsWith("data:")) {
+            const data = buffer
+                .split("\n")
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trimStart())
+                .join("\n");
+            if (data) {
+                yield JSON.parse(data);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof AgentFlowError) {
+            throw error;
+        }
+        if (error instanceof Error) {
+            throw new AgentFlowError(`Failed to read SSE stream: ${error.message}`);
+        }
+        throw new AgentFlowError("Failed to read SSE stream");
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@yuliaedomskikh/agentflow-client",
+  "version": "1.1.0",
+  "description": "TypeScript SDK for the AgentFlow API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test:unit": "vitest run --root .. --exclude=mutants/** tests/client.test.ts sdk-ts/tests/retry.test.ts sdk-ts/tests/circuitBreaker.test.ts sdk-ts/tests/resilience-integration.test.ts",
+    "test": "vitest run --root .. --exclude=mutants/** tests/client.test.ts sdk-ts/tests/retry.test.ts sdk-ts/tests/circuitBreaker.test.ts sdk-ts/tests/resilience-integration.test.ts"
+  },
+  "keywords": [
+    "agentflow",
+    "sdk",
+    "typescript",
+    "api"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brownjuly2003-code/agentflow.git",
+    "directory": "sdk-ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}