@covia/covia-sdk 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -4,9 +4,52 @@ declare class Job {
     metadata: JobMetadata;
     constructor(id: string, venue: VenueInterface, metadata: JobMetadata);
     /**
-    * Cancels the execution of the job
-    * @returns {Promise<number>}
-    */
+     * Whether the job has reached a terminal state
+     */
+    get isFinished(): boolean;
+    /**
+     * Whether the job completed successfully
+     */
+    get isComplete(): boolean;
+    /**
+     * The job output.
+     * @throws {Error} If the job has not finished yet.
+     * @throws {JobFailedError} If the job finished with a non-COMPLETE status.
+     */
+    get output(): any;
+    /**
+     * Poll the venue for the latest job status.
+     * @throws {Error} If the job has no ID.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Wait until the job reaches a terminal state.
+     * Uses exponential backoff polling (initial 300ms, factor 1.5, max 10s).
+     * @param options.timeout - Maximum milliseconds to wait. Undefined waits indefinitely.
+     * @throws {CoviaTimeoutError} If timeout is exceeded.
+     */
+    wait(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Wait for the job to complete and return its output.
+     * @param options.timeout - Maximum milliseconds to wait.
+     * @returns The job output.
+     * @throws {JobFailedError} If the job finishes with a non-COMPLETE status.
+     * @throws {CoviaTimeoutError} If timeout is exceeded.
+     */
+    result(options?: {
+        timeout?: number;
+    }): Promise<any>;
+    /**
+     * Stream server-sent events for this job.
+     * @returns AsyncGenerator yielding SSEEvent objects
+     */
+    stream(): AsyncGenerator<SSEEvent>;
+    /**
+     * Cancels the execution of the job
+     * @returns {Promise<number>}
+     */
     cancelJob(): Promise<number>;
     /**
      * Delete the job
@@ -33,11 +76,11 @@ declare abstract class Asset {
      */
     readStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
     /**
-     * Upload content to asset
+     * Put content to asset
      * @param content - Content to upload
      * @returns {Promise<ReadableStream<Uint8Array> | null>}
      */
-    uploadContent(content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
+    putContent(content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
     /**
      * Get asset content
      * @returns {Promise<ReadableStream<Uint8Array> | null>}
@@ -62,11 +105,63 @@ declare abstract class Asset {
     invoke(input: any): Promise<Job>;
 }
 
+/**
+ * Abstract base class for authentication strategies.
+ * Subclass this to implement custom authentication.
+ *
+ * Example — custom API-key auth:
+ *
+ *   class ApiKeyAuth extends Auth {
+ *     constructor(private key: string) { super(); }
+ *     apply(headers: Record<string, string>): void {
+ *       headers["X-Api-Key"] = this.key;
+ *     }
+ *   }
+ */
+declare abstract class Auth {
+    /** Apply authentication credentials to request headers (mutates in place). */
+    abstract apply(headers: Record<string, string>): void;
+}
+/** No-op authentication provider. Sends no credentials. */
+declare class NoAuth extends Auth {
+    apply(_headers: Record<string, string>): void;
+}
+/**
+ * Bearer token authentication.
+ * Adds `Authorization: Bearer <token>` to every request.
+ *
+ * Example:
+ *   const venue = await Grid.connect("https://venue.covia.ai", new BearerAuth("my-token"));
+ */
+declare class BearerAuth extends Auth {
+    private _token;
+    constructor(token: string);
+    apply(headers: Record<string, string>): void;
+}
+/**
+ * HTTP Basic authentication.
+ * Adds `Authorization: Basic <base64(username:password)>` to every request.
+ */
+declare class BasicAuth extends Auth {
+    private _encoded;
+    constructor(username: string, password: string);
+    apply(headers: Record<string, string>): void;
+}
+/**
+ * Custom auth that sets the X-Covia-User header for user identity tracking.
+ */
+declare class CoviaUserAuth extends Auth {
+    private _userId;
+    constructor(userId: string);
+    apply(headers: Record<string, string>): void;
+}
+/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, BasicAuth, CoviaUserAuth). */
 interface Credentials {
     venueId: string;
     apiKey: string;
     userId: string;
 }
+/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, BasicAuth, CoviaUserAuth). */
 declare class CredentialsHTTP implements Credentials {
     venueId: string;
     apiKey: string;
@@ -77,7 +172,7 @@ declare class CredentialsHTTP implements Credentials {
 declare class Venue implements VenueInterface {
     baseUrl: string;
     venueId: string;
-    credentials: Credentials;
+    auth: Auth;
     metadata: VenueData;
     constructor(options?: VenueOptions);
     /**
@@ -86,13 +181,13 @@ declare class Venue implements VenueInterface {
      * @param credentials - Optional credentials for venue authentication
      * @returns {Promise<Venue>} A new Venue instance configured appropriately
      */
-    static connect(venueId: string | Venue, credentials?: CredentialsHTTP): Promise<Venue>;
+    static connect(venueId: string | Venue, auth?: Auth): Promise<Venue>;
     /**
-     * Create a new asset
+     * Register a new asset
      * @param assetData - Asset configuration
      * @returns {Promise<Asset>}
      */
-    createAsset(assetData: any): Promise<Asset>;
+    register(assetData: any): Promise<Asset>;
     /**
      * Read stream from asset
      * @param reader - ReadableStreamDefaultReader
@@ -105,15 +200,16 @@ declare class Venue implements VenueInterface {
      */
     getAsset(assetId: AssetID): Promise<Asset>;
     /**
-     * Get all assets
-     * @returns {Promise<Asset[]>}
+     * List assets with pagination support
+     * @param options - Pagination options (offset, limit)
+     * @returns {Promise<AssetList>} Paginated list of asset IDs with metadata
      */
-    getAssets(): Promise<Asset[]>;
+    listAssets(options?: AssetListOptions): Promise<AssetList>;
     /**
-     * Get all jobs
+     * List all jobs
      * @returns {Promise<string[]>}
      */
-    getJobs(): Promise<string[]>;
+    listJobs(): Promise<string[]>;
     /**
      * Get job by ID
      * @param jobId - Job identifier
@@ -133,21 +229,47 @@ declare class Venue implements VenueInterface {
     */
     deleteJob(jobId: string): Promise<number>;
     /**
-   * Get the DID (Decentralized Identifier) for this venue
-   * @returns {string} DID in the format did:web:domain
-   */
-    getStats(): Promise<StatusData>;
+     * Get venue status
+     * @returns {Promise<StatusData>}
+     */
+    status(): Promise<StatusData>;
+    /**
+     * List all named operations available on this venue
+     * @returns {Promise<OperationInfo[]>}
+     */
+    listOperations(): Promise<OperationInfo[]>;
+    /**
+     * Get details of a named operation
+     * @param name - Operation name (e.g., "test:echo")
+     * @returns {Promise<OperationInfo>}
+     */
+    getOperation(name: string): Promise<OperationInfo>;
+    /**
+     * Get the full DID document for this venue
+     * @returns {Promise<DIDDocument>}
+     */
+    didDocument(): Promise<DIDDocument>;
+    /**
+     * Get MCP (Model Context Protocol) discovery information
+     * @returns {Promise<MCPDiscovery>}
+     */
+    mcpDiscovery(): Promise<MCPDiscovery>;
+    /**
+     * Get the A2A (Agent-to-Agent) agent card
+     * @returns {Promise<AgentCard>}
+     */
+    agentCard(): Promise<AgentCard>;
     /**
      * Get asset metadata
      * @returns {Promise<AssetMetadata>}
      */
     getMetadata(assetId: string): Promise<AssetMetadata>;
     /**
- * Upload content to asset
- * @param content - Content to upload
- * @returns {Promise<ReadableStream<Uint8Array> | null>}
- */
-    uploadContent(assetId: string, content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
+     * Put content to asset
+     * @param content - Content to upload
+     * @returns {Promise<ReadableStream<Uint8Array> | null>}
+     */
+    putContent(assetId: string, content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
     /**
      * Get asset content
      * @returns {Promise<ReadableStream<Uint8Array> | null>}
@@ -165,7 +287,22 @@ declare class Venue implements VenueInterface {
     * @returns {Promise<Job>}
     */
     invoke(assetId: string, input: any): Promise<Job>;
-    private setCredentialsInHeader;
+    /**
+     * Stream server-sent events for a job.
+     * @param jobId - Job identifier
+     * @returns AsyncGenerator yielding SSEEvent objects
+     */
+    streamJobEvents(jobId: string): AsyncGenerator<SSEEvent>;
+    /**
+     * Close the venue and release resources.
+     * Clears cached asset data for this venue.
+     */
+    close(): void;
+    /**
+     * Disposable support — allows `using venue = await Grid.connect(...)` in TS 5.2+.
+     */
+    [Symbol.dispose](): void;
+    private _buildHeaders;
 }
 
 interface VenueOptions {
@@ -173,11 +310,11 @@ interface VenueOptions {
     venueId?: string;
     name?: string;
     description?: string;
-    credentials?: Credentials;
+    auth?: Auth;
 }
 interface VenueConstructor {
     new (): VenueInterface;
-    connect(venueId: string | Venue, credentials?: CredentialsHTTP): Promise<Venue>;
+    connect(venueId: string | Venue, auth?: Auth): Promise<Venue>;
 }
 interface VenueInterface {
     baseUrl: string;
@@ -185,18 +322,25 @@ interface VenueInterface {
     metadata: VenueData;
     cancelJob(jobId: string): Promise<number>;
     deleteJob(jobId: string): Promise<number>;
-    getStats(): Promise<StatusData>;
+    status(): Promise<StatusData>;
     getJob(jobId: string): Promise<Job>;
-    getJobs(): Promise<string[]>;
+    listJobs(): Promise<string[]>;
     getAsset(assetId: AssetID): Promise<Asset>;
-    createAsset(assetData: any, userEmail: string): Promise<Asset>;
-    getAssets(): Promise<Asset[]>;
+    register(assetData: any): Promise<Asset>;
     getMetadata(assetId: string): Promise<AssetMetadata>;
     readStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
-    uploadContent(assetId: string, content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
+    putContent(assetId: string, content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
     getContent(assetId: string): Promise<ReadableStream<Uint8Array> | null>;
     run(assetId: string, input: any): Promise<any>;
     invoke(assetId: string, input: any): Promise<Job>;
+    listAssets(options?: AssetListOptions): Promise<AssetList>;
+    listOperations(): Promise<OperationInfo[]>;
+    getOperation(name: string): Promise<OperationInfo>;
+    didDocument(): Promise<DIDDocument>;
+    mcpDiscovery(): Promise<MCPDiscovery>;
+    agentCard(): Promise<AgentCard>;
+    streamJobEvents(jobId: string): AsyncGenerator<SSEEvent>;
+    close(): void;
 }
 type AssetID = string;
 interface AssetMetadata {
@@ -257,6 +401,9 @@ declare enum RunStatus {
     AUTH_REQUIRED = "AUTH_REQUIRED",
     PAUSED = "PAUSED"
 }
+/** Alias for RunStatus — matches Python SDK naming */
+declare const JobStatus: typeof RunStatus;
+type JobStatus = RunStatus;
 interface StatusData {
     url?: string;
     ts?: string;
@@ -271,10 +418,92 @@ interface StatsData {
     ops?: number;
     jobs?: number;
 }
+interface AssetListOptions {
+    offset?: number;
+    limit?: number;
+}
+interface AssetList {
+    items: string[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+interface MCPDiscovery {
+    mcp_version?: string;
+    server_url?: string;
+    description?: string;
+    tools_endpoint?: string;
+    endpoint?: Record<string, any> | string;
+    [key: string]: any;
+}
+interface AgentCard {
+    agentProvider?: Record<string, any>;
+    agentCapabilities?: Record<string, any>;
+    agentSkills?: Record<string, any>[];
+    agentInterfaces?: Record<string, any>[];
+    securityScheme?: Record<string, any>;
+    preferredTransport?: Record<string, any>;
+    [key: string]: any;
+}
+interface DIDDocument {
+    id: string;
+    '@context'?: string | string[];
+    [key: string]: any;
+}
+interface OperationInfo {
+    name: string;
+    asset: string;
+    description?: string;
+    input?: any;
+    output?: any;
+    [key: string]: any;
+}
+/** A single server-sent event received from a Covia venue. */
+interface SSEEvent {
+    event: string | null;
+    data: string;
+    id: string | null;
+    retry: number | null;
+    /** Parse the event data as JSON. */
+    json: () => any;
+}
 declare class CoviaError extends Error {
     code: number | null;
     constructor(message: string, code?: number | null);
 }
+/** Raised when the Covia API returns an error response (4xx/5xx). */
+declare class GridError extends CoviaError {
+    statusCode: number;
+    responseBody: any;
+    constructor(statusCode: number, message: string, responseBody?: any);
+}
+/** Raised when the SDK cannot connect to the venue. */
+declare class CoviaConnectionError extends CoviaError {
+    constructor(message: string);
+}
+/** Raised when an operation or polling loop times out. */
+declare class CoviaTimeoutError extends CoviaError {
+    constructor(message: string);
+}
+/** Raised when a job finishes with a non-COMPLETE status. */
+declare class JobFailedError extends CoviaError {
+    jobData: JobMetadata;
+    constructor(jobData: JobMetadata);
+}
+/** Raised when a requested resource is not found (404). */
+declare class NotFoundError extends GridError {
+    constructor(message: string);
+}
+/** Raised when an asset is not found (404). */
+declare class AssetNotFoundError extends NotFoundError {
+    assetId: string;
+    constructor(assetId: string);
+}
+/** Raised when a job is not found (404). */
+declare class JobNotFoundError extends NotFoundError {
+    jobId: string;
+    constructor(jobId: string);
+}
 
 /**
  * Utility function to handle API calls with consistent error handling
@@ -322,14 +551,47 @@ declare function getParsedAssetId(assetId: string): string;
  */
 declare function getAssetIdFromPath(assetHex: string, assetPath: string): string;
 declare function getAssetIdFromVenueId(assetHex: string, venueId: string): string;
+/**
+ * Create an SSEEvent object from parsed fields.
+ */
+declare function createSSEEvent(fields: {
+    event?: string;
+    data?: string;
+    id?: string;
+    retry?: number;
+}): SSEEvent;
+/**
+ * Parse an SSE stream from a fetch Response body.
+ * Yields SSEEvent objects as they arrive.
+ */
+declare function parseSSEStream(response: Response): AsyncGenerator<SSEEvent>;
+
+/**
+ * Simple logger for the Covia SDK.
+ *
+ * By default logging is disabled (level = 'none'). Enable debug output with:
+ *   import { logger } from '@covia/covia-sdk';
+ *   logger.level = 'debug';
+ *
+ * Or provide a custom log function:
+ *   logger.handler = (level, msg) => myLogger.log(level, msg);
+ */
+type LogLevel = 'debug' | 'none';
+type LogHandler = (level: string, message: string) => void;
+declare const logger: {
+    level: LogLevel;
+    handler: LogHandler;
+    debug(message: string): void;
+};
 
 declare class Grid {
     /**
     * Static method to connect to a venue
     * @param venueId - Can be a HTTP base URL, DNS name, or existing Venue instance
+    * @param auth - Optional authentication provider (BearerAuth, BasicAuth, etc.)
     * @returns {Promise<Venue>} A new Venue instance configured appropriately
     */
-    static connect(venueId: string, credentials?: CredentialsHTTP): Promise<Venue>;
+    static connect(venueId: string, auth?: Auth): Promise<Venue>;
 }
 
 declare class Operation extends Asset {
@@ -340,4 +602,4 @@ declare class DataAsset extends Asset {
     constructor(id: AssetID, venue: VenueInterface, metadata?: AssetMetadata);
 }
 
-export { Asset, type AssetID, type AssetMetadata, type ContentDetails, CoviaError, type Credentials, CredentialsHTTP, DataAsset, Grid, type InvokePayload, Job, type JobMetadata, Operation, type OperationDetails, type OperationPayload, RunStatus, type StatsData, type StatusData, Venue, type VenueConstructor, type VenueData, type VenueInterface, type VenueOptions, fetchStreamWithError, fetchWithError, getAssetIdFromPath, getAssetIdFromVenueId, getParsedAssetId, isJobComplete, isJobFinished, isJobPaused };
+export { type AgentCard, Asset, type AssetID, type AssetList, type AssetListOptions, type AssetMetadata, AssetNotFoundError, Auth, BasicAuth, BearerAuth, type ContentDetails, CoviaConnectionError, CoviaError, CoviaTimeoutError, CoviaUserAuth, type Credentials, CredentialsHTTP, type DIDDocument, DataAsset, Grid, GridError, type InvokePayload, Job, JobFailedError, type JobMetadata, JobNotFoundError, JobStatus, type MCPDiscovery, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, type OperationPayload, RunStatus, type SSEEvent, type StatsData, type StatusData, Venue, type VenueConstructor, type VenueData, type VenueInterface, type VenueOptions, createSSEEvent, fetchStreamWithError, fetchWithError, getAssetIdFromPath, getAssetIdFromVenueId, getParsedAssetId, isJobComplete, isJobFinished, isJobPaused, logger, parseSSEStream };