@nexus-ai-fs/api-client 0.9.18

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+/**
+ * Base error hierarchy for all Nexus API interactions.
+ *
+ * HTTP-level errors live here; domain-specific errors (e.g. InsufficientCreditsError)
+ * belong in consumer packages that extend NexusApiError.
+ *
+ * Hierarchy:
+ *   NexusApiError (base)
+ *   ├── AuthenticationError   (401)
+ *   ├── ForbiddenError        (403)
+ *   ├── NotFoundError         (404)
+ *   ├── ConflictError         (409)
+ *   ├── RateLimitError        (429)
+ *   ├── ServerError           (5xx)
+ *   ├── NetworkError          (fetch failed)
+ *   ├── TimeoutError          (request timed out)
+ *   └── AbortError            (user-cancelled)
+ */
+declare class NexusApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+declare class AuthenticationError extends NexusApiError {
+    constructor(message: string);
+}
+declare class ForbiddenError extends NexusApiError {
+    constructor(message: string);
+}
+declare class NotFoundError extends NexusApiError {
+    constructor(message: string);
+}
+declare class ConflictError extends NexusApiError {
+    constructor(message: string);
+}
+declare class RateLimitError extends NexusApiError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, retryAfter?: number);
+}
+declare class ServerError extends NexusApiError {
+    constructor(message: string, status: number);
+}
+declare class NetworkError extends NexusApiError {
+    constructor(message: string);
+}
+declare class TimeoutError extends NexusApiError {
+    constructor(message: string);
+}
+declare class AbortError extends NexusApiError {
+    constructor(message: string);
+}
+
+/**
+ * Shared types for the Nexus API client.
+ */
+interface NexusClientOptions {
+    /** API key (e.g. `nx_live_<id>`, `nx_test_<id>`, or any bearer token). */
+    readonly apiKey: string;
+    /** Base URL of the Nexus API server. Default: "http://localhost:2026" */
+    readonly baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    readonly timeout?: number;
+    /** Maximum retries for retryable errors. Default: 3. Set to 0 to disable. */
+    readonly maxRetries?: number;
+    /** Custom fetch implementation for testing or proxying. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Disable automatic snake_case → camelCase key transformation. Default: true */
+    readonly transformKeys?: boolean;
+    /** Agent identity sent as X-Agent-ID header. */
+    readonly agentId?: string;
+    /** Subject identity sent as X-Nexus-Subject header. */
+    readonly subject?: string;
+    /** Zone ID sent as X-Nexus-Zone-ID header. */
+    readonly zoneId?: string;
+}
+interface RequestOptions {
+    /** Per-request timeout override in milliseconds. */
+    readonly timeout?: number;
+    /** AbortSignal for cancellation. */
+    readonly signal?: AbortSignal;
+    /** Idempotency key for retry-safe operations. */
+    readonly idempotencyKey?: string;
+    /** Extra headers merged with defaults. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+interface ApiErrorResponse {
+    readonly detail: string;
+    readonly error_code?: string;
+}
+interface PaginatedResponse<T> {
+    readonly items: readonly T[];
+    readonly total: number;
+    readonly page: number;
+    readonly limit: number;
+}
+interface SseEvent {
+    readonly id?: string;
+    readonly event: string;
+    readonly data: string;
+    readonly retry?: number;
+}
+interface AspectEnvelope {
+    readonly entityUrn: string;
+    readonly aspectName: string;
+    readonly version: number;
+    readonly payload: Record<string, unknown>;
+    readonly createdBy: string;
+    readonly createdAt: string | null;
+}
+interface AspectListResponse {
+    readonly entityUrn: string;
+    readonly aspects: readonly string[];
+}
+interface DatasetSchema {
+    readonly columns: readonly {
+        name: string;
+        type: string;
+        nullable: string;
+    }[];
+    readonly format: string;
+    readonly rowCount: number | null;
+    readonly confidence: number;
+    readonly warnings: readonly string[];
+}
+interface CatalogSchemaResponse {
+    readonly entityUrn: string;
+    readonly path: string;
+    readonly schema: DatasetSchema | null;
+}
+interface ColumnSearchResult {
+    readonly entityUrn: string;
+    readonly columnName: string;
+    readonly columnType: string;
+    readonly schema: Record<string, unknown>;
+}
+interface ColumnSearchResponse {
+    readonly results: readonly ColumnSearchResult[];
+    readonly total: number;
+    readonly capped: boolean;
+}
+interface ReplayRecord {
+    readonly sequenceNumber: number;
+    readonly entityUrn: string;
+    readonly aspectName: string;
+    readonly changeType: string;
+    readonly timestamp: string;
+    readonly operationType: string;
+}
+interface ReplayResponse {
+    readonly records: readonly ReplayRecord[];
+    readonly nextCursor: number | null;
+    readonly hasMore: boolean;
+}
+
+/**
+ * Core HTTP client with retry, timeout, auth, error mapping,
+ * and automatic snake_case ↔ camelCase key transformation.
+ *
+ * Generalized from nexus-pay-ts's FetchClient. Consumer packages
+ * can subclass and override `buildError()` for domain-specific error mapping.
+ */
+
+declare class FetchClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchFn;
+    private readonly transformEnabled;
+    private readonly agentId;
+    private readonly subject;
+    private readonly zoneId;
+    constructor(options: NexusClientOptions);
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    postNoContent(path: string, body?: unknown, options?: RequestOptions): Promise<void>;
+    deleteNoContent(path: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Execute an arbitrary HTTP request through the authenticated client.
+     *
+     * Returns the raw `Response` — no JSON parsing, no key transformation,
+     * no retries. Auth and identity headers are injected automatically.
+     * Timeout is enforced (defaults to client timeout, overridable per-request).
+     *
+     * Body is sent as-is (no JSON.stringify) since callers provide pre-formatted strings.
+     *
+     * Intended for the API Console and similar exploratory tools that need
+     * full control over the request/response while still using real auth.
+     */
+    rawRequest(method: string, path: string, body?: string, options?: RequestOptions): Promise<Response>;
+    private request;
+    private requestRaw;
+    private executeFetch;
+    private buildHeaders;
+    /**
+     * Map HTTP response to a typed error.
+     *
+     * Subclasses can override this to add domain-specific error mapping
+     * (e.g. 402 → InsufficientCreditsError in nexus-pay-ts).
+     */
+    protected buildError(response: Response): Promise<NexusApiError>;
+    private computeRetryDelay;
+    /**
+     * List all aspect names attached to an entity.
+     */
+    getAspects(urn: string): Promise<string[]>;
+    /**
+     * Get a specific aspect for an entity. Returns null if not found.
+     */
+    getAspect(urn: string, name: string): Promise<AspectEnvelope | null>;
+    /**
+     * Get extracted schema for a data file. Returns null if no schema.
+     */
+    getCatalogSchema(path: string): Promise<CatalogSchemaResponse["schema"]>;
+    /**
+     * Search for data files containing a specific column name.
+     */
+    searchByColumn(column: string): Promise<ColumnSearchResponse["results"]>;
+    /**
+     * Replay metadata change log records.
+     */
+    replayChanges(opts?: {
+        fromSequence?: number;
+        entityUrn?: string;
+        limit?: number;
+    }): Promise<ReplayResponse>;
+}
+
+/**
+ * SSE connection manager with ring buffer, throttled flush,
+ * and exponential backoff reconnection.
+ */
+
+/** Fixed-size circular buffer that drops oldest entries when full. */
+declare class RingBuffer<T> {
+    readonly capacity: number;
+    private readonly buffer;
+    private head;
+    private count;
+    /** Monotonically increasing counter of total items ever pushed (never wraps). */
+    private _totalPushed;
+    constructor(capacity: number);
+    get size(): number;
+    /** Total number of items pushed since creation/clear (never decreases). */
+    get totalPushed(): number;
+    push(item: T): void;
+    /** Return items in insertion order (oldest first). */
+    toArray(): readonly T[];
+    /** Return the last N items (newest first becomes oldest first). */
+    lastN(n: number): readonly T[];
+    clear(): void;
+}
+interface SseClientOptions {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly bufferCapacity?: number;
+    readonly flushIntervalMs?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Agent identity sent as X-Agent-ID header. */
+    readonly agentId?: string;
+    /** Subject identity sent as X-Nexus-Subject header. */
+    readonly subject?: string;
+    /** Zone ID sent as X-Nexus-Zone-ID header. */
+    readonly zoneId?: string;
+}
+type SseEventHandler = (events: readonly SseEvent[]) => void;
+type SseErrorHandler = (error: Error) => void;
+type SseReconnectHandler = (attempt: number) => void;
+declare class SseClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly buffer;
+    private readonly flushIntervalMs;
+    private readonly agentId;
+    private readonly subject;
+    private readonly zoneId;
+    private abortController;
+    private flushTimer;
+    private reconnectAttempt;
+    private lastEventId;
+    private connected;
+    private eventHandler;
+    private errorHandler;
+    private reconnectHandler;
+    constructor(options: SseClientOptions);
+    onEvent(handler: SseEventHandler): void;
+    onError(handler: SseErrorHandler): void;
+    onReconnect(handler: SseReconnectHandler): void;
+    get isConnected(): boolean;
+    connect(path: string): Promise<void>;
+    disconnect(): void;
+    getBufferedEvents(): readonly SseEvent[];
+    clearBuffer(): void;
+    private connectWithRetry;
+    private streamEvents;
+    private parseEvents;
+    /** Tracks total events flushed via the monotonic totalPushed counter. */
+    private lastFlushedTotal;
+    private startFlushTimer;
+    private stopFlushTimer;
+    private computeReconnectDelay;
+}
+
+/**
+ * Config resolution from multiple sources with precedence:
+ *
+ * 1. Explicit overrides (constructor args / CLI flags)
+ * 2. Config file (./nexus.yaml → ./nexus.yml → ~/.nexus/config.yaml)
+ * 3. Environment variables (NEXUS_URL, NEXUS_API_KEY, etc.)
+ * 4. Defaults
+ *
+ * Matches the Python CLI (`config.py:_auto_discover`): if a config file
+ * exists, its values take priority over environment variables.
+ */
+
+/**
+ * Resolve Nexus client config from multiple sources.
+ *
+ * Works in Node, Bun, and Deno. Gracefully degrades in browsers
+ * (no env vars or filesystem — uses defaults + overrides only).
+ */
+declare function resolveConfig(overrides?: Partial<NexusClientOptions>): NexusClientOptions;
+
+/**
+ * Pure utility functions for snake_case ↔ camelCase key transformation.
+ *
+ * Handles nested objects, arrays, null, and preserves non-plain values (Date, etc.).
+ */
+/** Convert a single snake_case string to camelCase. */
+declare function snakeToCamel(str: string): string;
+/** Convert a single camelCase string to snake_case. */
+declare function camelToSnake(str: string): string;
+/**
+ * Recursively transform all keys in an object/array using the given transformer.
+ *
+ * - Arrays: each element is recursively transformed
+ * - null/undefined: returned as-is
+ * - Primitives (string, number, boolean): returned as-is
+ * - Date: returned as-is (not a plain object)
+ * - Plain objects: keys are transformed, values are recursively transformed
+ */
+declare function transformKeys<T>(value: unknown, transformer: (key: string) => string): T;
+/** Transform all keys from snake_case to camelCase. */
+declare function snakeToCamelKeys<T>(value: unknown): T;
+/** Transform all keys from camelCase to snake_case. */
+declare function camelToSnakeKeys<T>(value: unknown): T;
+
+export { AbortError, type ApiErrorResponse, type AspectEnvelope, type AspectListResponse, AuthenticationError, type CatalogSchemaResponse, type ColumnSearchResponse, type ColumnSearchResult, ConflictError, type DatasetSchema, FetchClient, ForbiddenError, NetworkError, NexusApiError, type NexusClientOptions, NotFoundError, type PaginatedResponse, RateLimitError, type ReplayRecord, type ReplayResponse, type RequestOptions, RingBuffer, ServerError, SseClient, type SseClientOptions, type SseErrorHandler, type SseEvent, type SseEventHandler, type SseReconnectHandler, TimeoutError, camelToSnake, camelToSnakeKeys, resolveConfig, snakeToCamel, snakeToCamelKeys, transformKeys };