@supernovae-st/nika-client 0.63.0

package/dist/index.d.cts

@@ -0,0 +1,274 @@
+interface NikaLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+interface NikaConfig {
+    /** URL of nika serve (e.g. http://localhost:3000) */
+    url: string;
+    /** Bearer token for authentication */
+    token: string;
+    /** Global HTTP request timeout in ms. Default: 30_000 */
+    timeout?: number;
+    /** Retries on 429/5xx. Default: 2 */
+    retries?: number;
+    /** Initial polling interval in ms. Default: 2_000 */
+    pollInterval?: number;
+    /** Max polling timeout in ms. Default: 300_000 (5 min) */
+    pollTimeout?: number;
+    /** Backoff multiplier for polling. Default: 1.5 */
+    pollBackoff?: number;
+    /** Max concurrent HTTP requests to nika serve. Default: 24 */
+    concurrency?: number;
+    /** Custom fetch function. Default: globalThis.fetch */
+    fetch?: typeof globalThis.fetch;
+    /** Logger for request/response tracing. Default: silent */
+    logger?: NikaLogger;
+}
+interface RunRequest {
+    workflow: string;
+    inputs?: Record<string, unknown>;
+    resume_from?: string;
+}
+/** POST /v1/run response */
+interface RunResponse {
+    job_id: string;
+    status: string;
+}
+interface RunOptions {
+    resumeFrom?: string;
+    signal?: AbortSignal;
+}
+type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** GET /v1/status/{id} response */
+interface NikaJob {
+    job_id: string;
+    status: JobStatus;
+    workflow: string;
+    created_at: string;
+    started_at?: string;
+    completed_at?: string;
+    exit_code?: number;
+    output?: string;
+}
+interface CancelResponse {
+    job_id: string;
+    status: string;
+    message?: string;
+}
+interface NikaArtifact {
+    name: string;
+    size: number;
+    format: string;
+    content_type: string;
+    checksum?: string;
+}
+/** GET /v1/jobs/{id}/artifacts response */
+interface ArtifactsResponse {
+    job_id: string;
+    count: number;
+    artifacts: NikaArtifact[];
+}
+/** GET /health response */
+interface NikaHealth {
+    status: 'ok';
+    version: string;
+    service: string;
+}
+interface WorkflowInfo {
+    name: string;
+    size: number;
+}
+/** GET /v1/workflows response */
+interface ListWorkflowsResponse {
+    workflows: WorkflowInfo[];
+    count: number;
+    /** Whether more results exist (present when `limit` is set). */
+    has_more?: boolean;
+}
+type NikaEvent = {
+    type: 'started';
+    job_id: string;
+} | {
+    type: 'task_start';
+    job_id: string;
+    task_id: string;
+    verb: string;
+} | {
+    type: 'task_complete';
+    job_id: string;
+    task_id: string;
+    duration_ms: number;
+} | {
+    type: 'task_failed';
+    job_id: string;
+    task_id: string;
+    error: string;
+    duration_ms: number;
+} | {
+    type: 'artifact_written';
+    job_id: string;
+    task_id: string;
+    path: string;
+    size: number;
+} | {
+    type: 'completed';
+    job_id: string;
+    output: string | null;
+} | {
+    type: 'failed';
+    job_id: string;
+    error: string | null;
+} | {
+    type: 'cancelled';
+    job_id: string;
+};
+type NikaEventType = NikaEvent['type'];
+interface StreamOptions {
+    signal?: AbortSignal;
+    /** Max ms without any event before treating connection as dead. Default: 60_000 */
+    idleTimeout?: number;
+    /** Max reconnection attempts on stream drop. Default: 3 */
+    maxReconnects?: number;
+    /** Initial reconnect delay in ms (multiplied by attempt). Default: 1000 */
+    reconnectDelay?: number;
+}
+interface PollOptions {
+    interval: number;
+    timeout: number;
+    backoff: number;
+    signal?: AbortSignal;
+}
+
+declare class ApiClient {
+    readonly url: string;
+    readonly timeout: number;
+    readonly retries: number;
+    readonly logger?: NikaLogger;
+    private readonly token;
+    private readonly _fetch;
+    private readonly semaphore;
+    constructor(url: string, token: string, timeout: number, retries: number, fetchFn: typeof globalThis.fetch, concurrency: number, logger?: NikaLogger);
+    request(path: string, init?: RequestInit): Promise<Response>;
+    private _request;
+    json<T>(path: string, init?: RequestInit): Promise<T>;
+    connectSSE(path: string, signal?: AbortSignal, extraHeaders?: Record<string, string>): Promise<Response>;
+    fetchHealth(): Promise<Response>;
+}
+
+interface JobsPollConfig {
+    pollInterval: number;
+    pollTimeout: number;
+    pollBackoff: number;
+}
+declare class Jobs {
+    private readonly api;
+    private readonly poll;
+    constructor(api: ApiClient, poll: JobsPollConfig);
+    /** Submit a workflow and return immediately with job ID. */
+    submit(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<RunResponse>;
+    /** Get current job status. */
+    status(jobId: string): Promise<NikaJob>;
+    /** Cancel a running job. */
+    cancel(jobId: string): Promise<CancelResponse>;
+    /** Run a workflow and wait for completion (polling). */
+    run(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<NikaJob>;
+    /** Stream job events via SSE (AsyncIterable). */
+    stream(jobId: string, options?: StreamOptions): AsyncIterable<NikaEvent>;
+    /** List artifacts for a job. */
+    artifacts(jobId: string): Promise<NikaArtifact[]>;
+    /** Download a specific artifact as string. */
+    artifact(jobId: string, name: string): Promise<string>;
+    /** Download a specific artifact as parsed JSON. */
+    artifactJson<T = unknown>(jobId: string, name: string): Promise<T>;
+    /** Download a specific artifact as raw bytes. */
+    artifactBinary(jobId: string, name: string): Promise<Uint8Array>;
+    /** Stream an artifact as a ReadableStream (for large files). */
+    artifactStream(jobId: string, name: string): Promise<ReadableStream<Uint8Array>>;
+    /** Run workflow, wait, and collect all non-binary artifacts into a map. */
+    runAndCollect(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<Record<string, unknown>>;
+}
+
+interface ListPageOptions {
+    /** Max workflows to return per page. */
+    limit?: number;
+    /** Cursor: return workflows after this name (from previous page's last item). */
+    after?: string;
+}
+declare class Workflows {
+    private readonly api;
+    constructor(api: ApiClient);
+    /**
+     * List all workflows. Auto-paginates if server supports it.
+     * For large lists, use `listPage()` for manual pagination.
+     */
+    list(): Promise<WorkflowInfo[]>;
+    /** List a single page of workflows (manual pagination). */
+    listPage(options?: ListPageOptions): Promise<ListWorkflowsResponse>;
+    /** Reload workflows from disk and return the refreshed list. */
+    reload(): Promise<WorkflowInfo[]>;
+    /** Get the raw YAML source of a workflow. */
+    source(name: string): Promise<string>;
+}
+
+/**
+ * Verify nika serve webhook signatures (Stripe-style HMAC-SHA256).
+ *
+ * Signature header format: "t=<unix_timestamp>,v1=<hmac_sha256_hex>"
+ * Signed payload: "<timestamp>.<body>"
+ */
+declare function verifyWebhookSignature(payload: string, signatureHeader: string, secret: string, tolerance?: number): Promise<boolean>;
+
+/** Base error for all SDK errors. Catch this to handle any nika-client error. */
+declare class NikaError extends Error {
+    constructor(message: string);
+}
+/** HTTP error from nika serve (non-2xx response). */
+declare class NikaAPIError extends NikaError {
+    readonly status: number;
+    readonly body: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, body: string, requestId?: string);
+}
+/** Network or connection error (DNS, TCP reset, refused). */
+declare class NikaConnectionError extends NikaError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/** Request or poll timeout exceeded. */
+declare class NikaTimeoutError extends NikaError {
+    constructor(message: string);
+}
+/** Job terminated with status 'failed'. */
+declare class NikaJobError extends NikaError {
+    readonly job: NikaJob;
+    readonly exitCode: number | undefined;
+    constructor(job: NikaJob);
+}
+/** Job was cancelled. Extends NikaJobError — catch NikaJobError to get both. */
+declare class NikaJobCancelledError extends NikaJobError {
+    constructor(job: NikaJob);
+}
+
+declare class Nika {
+    /** Job operations: submit, status, cancel, run, stream, artifacts. */
+    readonly jobs: Jobs;
+    /** Workflow operations: list, reload. */
+    readonly workflows: Workflows;
+    private readonly api;
+    constructor(config: NikaConfig);
+    /** Health check (no auth required, uses timeout). */
+    health(): Promise<NikaHealth>;
+    /**
+     * Verify a webhook signature from nika serve.
+     *
+     * @param payload — raw request body string
+     * @param signature — value of X-Nika-Signature header
+     * @param secret — shared webhook secret (NIKA_WEBHOOK_SECRET)
+     * @param tolerance — max age in seconds (default: 300)
+     */
+    static verifyWebhook: typeof verifyWebhookSignature;
+}
+
+export { type ArtifactsResponse, type CancelResponse, type JobStatus, Jobs, type ListPageOptions, type ListWorkflowsResponse, Nika, NikaAPIError, type NikaArtifact, type NikaConfig, NikaConnectionError, NikaError, type NikaEvent, type NikaEventType, type NikaHealth, type NikaJob, NikaJobCancelledError, NikaJobError, type NikaLogger, NikaTimeoutError, type PollOptions, type RunOptions, type RunRequest, type RunResponse, type StreamOptions, type WorkflowInfo, Workflows, verifyWebhookSignature };

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+interface NikaLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+interface NikaConfig {
+    /** URL of nika serve (e.g. http://localhost:3000) */
+    url: string;
+    /** Bearer token for authentication */
+    token: string;
+    /** Global HTTP request timeout in ms. Default: 30_000 */
+    timeout?: number;
+    /** Retries on 429/5xx. Default: 2 */
+    retries?: number;
+    /** Initial polling interval in ms. Default: 2_000 */
+    pollInterval?: number;
+    /** Max polling timeout in ms. Default: 300_000 (5 min) */
+    pollTimeout?: number;
+    /** Backoff multiplier for polling. Default: 1.5 */
+    pollBackoff?: number;
+    /** Max concurrent HTTP requests to nika serve. Default: 24 */
+    concurrency?: number;
+    /** Custom fetch function. Default: globalThis.fetch */
+    fetch?: typeof globalThis.fetch;
+    /** Logger for request/response tracing. Default: silent */
+    logger?: NikaLogger;
+}
+interface RunRequest {
+    workflow: string;
+    inputs?: Record<string, unknown>;
+    resume_from?: string;
+}
+/** POST /v1/run response */
+interface RunResponse {
+    job_id: string;
+    status: string;
+}
+interface RunOptions {
+    resumeFrom?: string;
+    signal?: AbortSignal;
+}
+type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** GET /v1/status/{id} response */
+interface NikaJob {
+    job_id: string;
+    status: JobStatus;
+    workflow: string;
+    created_at: string;
+    started_at?: string;
+    completed_at?: string;
+    exit_code?: number;
+    output?: string;
+}
+interface CancelResponse {
+    job_id: string;
+    status: string;
+    message?: string;
+}
+interface NikaArtifact {
+    name: string;
+    size: number;
+    format: string;
+    content_type: string;
+    checksum?: string;
+}
+/** GET /v1/jobs/{id}/artifacts response */
+interface ArtifactsResponse {
+    job_id: string;
+    count: number;
+    artifacts: NikaArtifact[];
+}
+/** GET /health response */
+interface NikaHealth {
+    status: 'ok';
+    version: string;
+    service: string;
+}
+interface WorkflowInfo {
+    name: string;
+    size: number;
+}
+/** GET /v1/workflows response */
+interface ListWorkflowsResponse {
+    workflows: WorkflowInfo[];
+    count: number;
+    /** Whether more results exist (present when `limit` is set). */
+    has_more?: boolean;
+}
+type NikaEvent = {
+    type: 'started';
+    job_id: string;
+} | {
+    type: 'task_start';
+    job_id: string;
+    task_id: string;
+    verb: string;
+} | {
+    type: 'task_complete';
+    job_id: string;
+    task_id: string;
+    duration_ms: number;
+} | {
+    type: 'task_failed';
+    job_id: string;
+    task_id: string;
+    error: string;
+    duration_ms: number;
+} | {
+    type: 'artifact_written';
+    job_id: string;
+    task_id: string;
+    path: string;
+    size: number;
+} | {
+    type: 'completed';
+    job_id: string;
+    output: string | null;
+} | {
+    type: 'failed';
+    job_id: string;
+    error: string | null;
+} | {
+    type: 'cancelled';
+    job_id: string;
+};
+type NikaEventType = NikaEvent['type'];
+interface StreamOptions {
+    signal?: AbortSignal;
+    /** Max ms without any event before treating connection as dead. Default: 60_000 */
+    idleTimeout?: number;
+    /** Max reconnection attempts on stream drop. Default: 3 */
+    maxReconnects?: number;
+    /** Initial reconnect delay in ms (multiplied by attempt). Default: 1000 */
+    reconnectDelay?: number;
+}
+interface PollOptions {
+    interval: number;
+    timeout: number;
+    backoff: number;
+    signal?: AbortSignal;
+}
+
+declare class ApiClient {
+    readonly url: string;
+    readonly timeout: number;
+    readonly retries: number;
+    readonly logger?: NikaLogger;
+    private readonly token;
+    private readonly _fetch;
+    private readonly semaphore;
+    constructor(url: string, token: string, timeout: number, retries: number, fetchFn: typeof globalThis.fetch, concurrency: number, logger?: NikaLogger);
+    request(path: string, init?: RequestInit): Promise<Response>;
+    private _request;
+    json<T>(path: string, init?: RequestInit): Promise<T>;
+    connectSSE(path: string, signal?: AbortSignal, extraHeaders?: Record<string, string>): Promise<Response>;
+    fetchHealth(): Promise<Response>;
+}
+
+interface JobsPollConfig {
+    pollInterval: number;
+    pollTimeout: number;
+    pollBackoff: number;
+}
+declare class Jobs {
+    private readonly api;
+    private readonly poll;
+    constructor(api: ApiClient, poll: JobsPollConfig);
+    /** Submit a workflow and return immediately with job ID. */
+    submit(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<RunResponse>;
+    /** Get current job status. */
+    status(jobId: string): Promise<NikaJob>;
+    /** Cancel a running job. */
+    cancel(jobId: string): Promise<CancelResponse>;
+    /** Run a workflow and wait for completion (polling). */
+    run(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<NikaJob>;
+    /** Stream job events via SSE (AsyncIterable). */
+    stream(jobId: string, options?: StreamOptions): AsyncIterable<NikaEvent>;
+    /** List artifacts for a job. */
+    artifacts(jobId: string): Promise<NikaArtifact[]>;
+    /** Download a specific artifact as string. */
+    artifact(jobId: string, name: string): Promise<string>;
+    /** Download a specific artifact as parsed JSON. */
+    artifactJson<T = unknown>(jobId: string, name: string): Promise<T>;
+    /** Download a specific artifact as raw bytes. */
+    artifactBinary(jobId: string, name: string): Promise<Uint8Array>;
+    /** Stream an artifact as a ReadableStream (for large files). */
+    artifactStream(jobId: string, name: string): Promise<ReadableStream<Uint8Array>>;
+    /** Run workflow, wait, and collect all non-binary artifacts into a map. */
+    runAndCollect(workflow: string, inputs?: Record<string, unknown>, options?: RunOptions): Promise<Record<string, unknown>>;
+}
+
+interface ListPageOptions {
+    /** Max workflows to return per page. */
+    limit?: number;
+    /** Cursor: return workflows after this name (from previous page's last item). */
+    after?: string;
+}
+declare class Workflows {
+    private readonly api;
+    constructor(api: ApiClient);
+    /**
+     * List all workflows. Auto-paginates if server supports it.
+     * For large lists, use `listPage()` for manual pagination.
+     */
+    list(): Promise<WorkflowInfo[]>;
+    /** List a single page of workflows (manual pagination). */
+    listPage(options?: ListPageOptions): Promise<ListWorkflowsResponse>;
+    /** Reload workflows from disk and return the refreshed list. */
+    reload(): Promise<WorkflowInfo[]>;
+    /** Get the raw YAML source of a workflow. */
+    source(name: string): Promise<string>;
+}
+
+/**
+ * Verify nika serve webhook signatures (Stripe-style HMAC-SHA256).
+ *
+ * Signature header format: "t=<unix_timestamp>,v1=<hmac_sha256_hex>"
+ * Signed payload: "<timestamp>.<body>"
+ */
+declare function verifyWebhookSignature(payload: string, signatureHeader: string, secret: string, tolerance?: number): Promise<boolean>;
+
+/** Base error for all SDK errors. Catch this to handle any nika-client error. */
+declare class NikaError extends Error {
+    constructor(message: string);
+}
+/** HTTP error from nika serve (non-2xx response). */
+declare class NikaAPIError extends NikaError {
+    readonly status: number;
+    readonly body: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, body: string, requestId?: string);
+}
+/** Network or connection error (DNS, TCP reset, refused). */
+declare class NikaConnectionError extends NikaError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/** Request or poll timeout exceeded. */
+declare class NikaTimeoutError extends NikaError {
+    constructor(message: string);
+}
+/** Job terminated with status 'failed'. */
+declare class NikaJobError extends NikaError {
+    readonly job: NikaJob;
+    readonly exitCode: number | undefined;
+    constructor(job: NikaJob);
+}
+/** Job was cancelled. Extends NikaJobError — catch NikaJobError to get both. */
+declare class NikaJobCancelledError extends NikaJobError {
+    constructor(job: NikaJob);
+}
+
+declare class Nika {
+    /** Job operations: submit, status, cancel, run, stream, artifacts. */
+    readonly jobs: Jobs;
+    /** Workflow operations: list, reload. */
+    readonly workflows: Workflows;
+    private readonly api;
+    constructor(config: NikaConfig);
+    /** Health check (no auth required, uses timeout). */
+    health(): Promise<NikaHealth>;
+    /**
+     * Verify a webhook signature from nika serve.
+     *
+     * @param payload — raw request body string
+     * @param signature — value of X-Nika-Signature header
+     * @param secret — shared webhook secret (NIKA_WEBHOOK_SECRET)
+     * @param tolerance — max age in seconds (default: 300)
+     */
+    static verifyWebhook: typeof verifyWebhookSignature;
+}
+
+export { type ArtifactsResponse, type CancelResponse, type JobStatus, Jobs, type ListPageOptions, type ListWorkflowsResponse, Nika, NikaAPIError, type NikaArtifact, type NikaConfig, NikaConnectionError, NikaError, type NikaEvent, type NikaEventType, type NikaHealth, type NikaJob, NikaJobCancelledError, NikaJobError, type NikaLogger, NikaTimeoutError, type PollOptions, type RunOptions, type RunRequest, type RunResponse, type StreamOptions, type WorkflowInfo, Workflows, verifyWebhookSignature };