@covia/covia-sdk 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Covia AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @covia/covia-sdk
+
+[![npm version](https://badge.fury.io/js/@covia%2Fcovia-sdk.svg)](https://www.npmjs.com/package/@covia/covia-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScript SDK for [Covia.ai](https://covia.ai) - The Universal Grid for AI Orchestration & Multi-Agent Workflows.
+
+Covia.ai provides federated execution, cryptographic verification, and shared state management for AI agents across organizations, clouds, and platforms.
+
+## Features
+
+- 🔒 **Type-Safe API** - Full TypeScript support with complete type definitions
+- 🎯 **Asset Management** - Work with Operations and Data Assets through a unified interface
+- 🔄 **Streaming Support** - Built-in support for streaming content and responses
+- 💾 **Intelligent Caching** - Automatic caching for improved performance
+- 🛡️ **Error Handling** - Comprehensive error handling with typed exceptions
+- 🌐 **Federated Execution** - Connect to Covia venues for cross-organizational workflows
+- 📦 **Dual Module Support** - Works with both CommonJS and ES Modules
+
+## Installation
+
+```bash
+npm install @covia/covia-sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @covia/covia-sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @covia/covia-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Grid } from '@covia/covia-sdk';
+
+// Connect to a venue
+const venue = await Grid.connect("venue-did");
+
+// Get assets (returns Operation or DataAsset based on metadata)
+const operation = await venue.getAsset('op-id');
+const dataAsset = await venue.getAsset('data-id');
+
+// Invoke an operation
+await operation.invoke({ param: 'value' });
+
+// Upload data to a data asset
+await dataAsset.uploadContent(content);
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (for TypeScript users)
+
+## TypeScript Support
+
+`@covia/covia-sdk` is written in TypeScript and ships with full type declarations. No `@types/` package is needed.
+
+```typescript
+import { Venue, Operation, DataAsset, CoviaError, AssetMetadata } from '@covia/covia-sdk';
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Resources
+
+- [Covia.ai Platform](https://covia.ai)
+- [Official Documentation](https://docs.covia.ai/)
+- [GitHub Repository](https://github.com/covia-ai/covia-sdk)
+- [Issue Tracker](https://github.com/covia-ai/covia-sdk/issues)
+- [npm Package](https://www.npmjs.com/package/@covia/covia-sdk)
+
+## License
+
+MIT © Covia AI
+
+## Support
+
+For questions, issues, or feature requests:
+
+- 📧 Email: info@covia.ai
+- 💬 GitHub Issues: [github.com/covia-ai/covia-sdk/issues](https://github.com/covia-ai/covia-sdk/issues)
+- 📚 Documentation: [docs.covia.ai](https://docs.covia.ai/)
+
+---
+
+Built with ❤️ by [Covia Labs](https://covia.ai) - Foundational infrastructure for the agent economy

package/dist/index.d.mts

@@ -0,0 +1,343 @@
+declare class Job {
+    id: string;
+    venue: VenueInterface;
+    metadata: JobMetadata;
+    constructor(id: string, venue: VenueInterface, metadata: JobMetadata);
+    /**
+    * Cancels the execution of the job
+    * @returns {Promise<number>}
+    */
+    cancelJob(): Promise<number>;
+    /**
+     * Delete the job
+     * @returns {Promise<number>}
+     */
+    deleteJob(): Promise<number>;
+}
+
+declare abstract class Asset {
+    id: AssetID;
+    venue: VenueInterface;
+    metadata: AssetMetadata;
+    status?: RunStatus;
+    error?: string;
+    constructor(id: AssetID, venue: VenueInterface, metadata?: AssetMetadata);
+    /**
+     * Get asset metadata
+     * @returns {Promise<AssetMetadata>}
+     */
+    getMetadata(): Promise<AssetMetadata>;
+    /**
+     * Read stream from asset
+     * @param reader - ReadableStreamDefaultReader
+     */
+    readStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+    /**
+     * Upload content to asset
+     * @param content - Content to upload
+     * @returns {Promise<ReadableStream<Uint8Array> | null>}
+     */
+    uploadContent(content: BodyInit): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * Get asset content
+     * @returns {Promise<ReadableStream<Uint8Array> | null>}
+     */
+    getContent(): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * Get the URL for downloading asset content
+     * @returns {string} The URL for downloading the asset content
+     */
+    getContentURL(): string;
+    /**
+     * Execute the operation
+     * @param input - Operation input parameters
+     * @returns {Promise<any>}
+     */
+    run(input: any): Promise<any>;
+    /**
+    * Execute the operation
+    * @param input - Operation input parameters
+    * @returns {Promise<any>}
+    */
+    invoke(input: any): Promise<Job>;
+}
+
+interface Credentials {
+    venueId: string;
+    apiKey: string;
+    userId: string;
+}
+declare class CredentialsHTTP implements Credentials {
+    venueId: string;
+    apiKey: string;
+    userId: string;
+    constructor(venueId: string, apiKey: string, userId: string);
+}
+
+declare class Venue implements VenueInterface {
+    baseUrl: string;
+    venueId: string;
+    credentials: Credentials;
+    metadata: VenueData;
+    constructor(options?: VenueOptions);
+    /**
+     * Static method to connect to a venue
+     * @param venueId - Can be a HTTP base URL, DNS name, or existing Venue instance
+     * @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>;
+    /**
+     * Create a new asset
+     * @param assetData - Asset configuration
+     * @returns {Promise<Asset>}
+     */
+    createAsset(assetData: any): Promise<Asset>;
+    /**
+     * Read stream from asset
+     * @param reader - ReadableStreamDefaultReader
+     */
+    readStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+    /**
+     * Get asset by ID
+     * @param assetId - Asset identifier
+     * @returns {Promise<Asset>} Returns either an Operation or DataAsset based on the asset's metadata
+     */
+    getAsset(assetId: AssetID): Promise<Asset>;
+    /**
+     * Get all assets
+     * @returns {Promise<Asset[]>}
+     */
+    getAssets(): Promise<Asset[]>;
+    /**
+     * Get all jobs
+     * @returns {Promise<string[]>}
+     */
+    getJobs(): Promise<string[]>;
+    /**
+     * Get job by ID
+     * @param jobId - Job identifier
+     * @returns {Promise<Job>}
+     */
+    getJob(jobId: string): Promise<Job>;
+    /**
+    * Cancel job by ID
+    * @param jobId - Job identifier
+    * @returns {Promise<number>}
+    */
+    cancelJob(jobId: string): Promise<number>;
+    /**
+    * Delete job by ID
+    * @param jobId - Job identifier
+    * @returns {Promise<number>}
+    */
+    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 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>;
+    /**
+     * Get asset content
+     * @returns {Promise<ReadableStream<Uint8Array> | null>}
+     */
+    getContent(assetId: string): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+       * Execute the operation
+       * @param input - Operation input parameters
+       * @returns {Promise<any>}
+       */
+    run(assetId: string, input: any): Promise<any>;
+    /**
+    * Execute the operation
+    * @param input - Operation input parameters
+    * @returns {Promise<Job>}
+    */
+    invoke(assetId: string, input: any): Promise<Job>;
+    private setCredentialsInHeader;
+}
+
+interface VenueOptions {
+    baseUrl?: string;
+    venueId?: string;
+    name?: string;
+    description?: string;
+    credentials?: Credentials;
+}
+interface VenueConstructor {
+    new (): VenueInterface;
+    connect(venueId: string | Venue, credentials?: CredentialsHTTP): Promise<Venue>;
+}
+interface VenueInterface {
+    baseUrl: string;
+    venueId: string;
+    metadata: VenueData;
+    cancelJob(jobId: string): Promise<number>;
+    deleteJob(jobId: string): Promise<number>;
+    getStats(): Promise<StatusData>;
+    getJob(jobId: string): Promise<Job>;
+    getJobs(): Promise<string[]>;
+    getAsset(assetId: AssetID): Promise<Asset>;
+    createAsset(assetData: any, userEmail: string): Promise<Asset>;
+    getAssets(): Promise<Asset[]>;
+    getMetadata(assetId: string): Promise<AssetMetadata>;
+    readStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+    uploadContent(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>;
+}
+type AssetID = string;
+interface AssetMetadata {
+    [key: string]: any;
+    name?: string;
+    description?: string;
+    type?: string;
+    created?: string;
+    updated?: string;
+    operation?: OperationDetails;
+    content?: ContentDetails;
+    input?: any;
+    output?: any;
+}
+interface VenueData {
+    description?: string;
+    name?: string;
+}
+/** Type for metadata.operation */
+interface OperationDetails {
+    [key: string]: any;
+    adapter?: string;
+    input?: any;
+    output?: any;
+    steps?: any[];
+    result?: any;
+}
+/** Type for metadata.content */
+interface ContentDetails {
+    [key: string]: any;
+}
+interface OperationPayload {
+    [key: string]: any;
+}
+interface JobMetadata {
+    name?: string;
+    status?: RunStatus;
+    created?: string;
+    updated?: string;
+    input?: any;
+    output?: any;
+    op?: string;
+    [key: string]: any;
+}
+interface InvokePayload {
+    assetId: AssetID;
+    payload: OperationPayload;
+}
+declare enum RunStatus {
+    COMPLETE = "COMPLETE",
+    FAILED = "FAILED",
+    PENDING = "PENDING",
+    STARTED = "STARTED",
+    CANCELLED = "CANCELLED",
+    TIMEOUT = "TIMEOUT",
+    REJECTED = "REJECTED",
+    INPUT_REQUIRED = "INPUT_REQUIRED",
+    AUTH_REQUIRED = "AUTH_REQUIRED",
+    PAUSED = "PAUSED"
+}
+interface StatusData {
+    url?: string;
+    ts?: string;
+    status?: string;
+    did?: string;
+    name?: string;
+    stats?: StatsData;
+}
+interface StatsData {
+    assets?: number;
+    users?: number;
+    ops?: number;
+    jobs?: number;
+}
+declare class CoviaError extends Error {
+    code: number | null;
+    constructor(message: string, code?: number | null);
+}
+
+/**
+ * Utility function to handle API calls with consistent error handling
+ * @param url - The URL to fetch
+ * @param options - Fetch options
+ * @returns {Promise<T>} The response data
+ */
+declare function fetchWithError<T>(url: string, options?: RequestInit): Promise<T>;
+/**
+ * Utility function to handle fetch requests that return streams
+ * @param url - The URL to fetch
+ * @param options - Fetch options
+ * @returns {Promise<Response>} The fetch response
+ */
+declare function fetchStreamWithError(url: string, options?: RequestInit): Promise<Response>;
+/**
+ * Utility function to check if job is considered completed
+ * @param jobStatus - The status of the job
+ * @returns {boolean} - Returns false if job is not completed , else returns true
+ */
+declare function isJobComplete(jobStatus: RunStatus): boolean;
+/**
+ * Utility function to check if job is considered paused
+ * @param jobStatus - The status of the job
+ * @returns {boolean} - Returns false if job is not paused , else returns true
+ */
+declare function isJobPaused(jobStatus: RunStatus): boolean;
+/**
+ * Utility function to check if job is considered finished
+ * @param jobStatus - The status of the job
+ * @returns {boolean} - Returns false if job is not finished , else returns true
+ */
+declare function isJobFinished(jobStatus: RunStatus): boolean;
+/**
+ * Utility function to parse the asset hex from the compelte assetId
+ * @param assetId - The complete assetId
+ * @returns {string} - Returns the parsed hexIdof the asset
+ */
+declare function getParsedAssetId(assetId: string): string;
+/**
+ * Utility function to return complete assetId from hex and path
+ * @param assetHex - The asset hex
+ * @param assetPath - The asset path
+ * @returns {string} - Returns the complete assetId
+ */
+declare function getAssetIdFromPath(assetHex: string, assetPath: string): string;
+declare function getAssetIdFromVenueId(assetHex: string, venueId: string): string;
+
+declare class Grid {
+    /**
+    * Static method to connect to a venue
+    * @param venueId - Can be a HTTP base URL, DNS name, or existing Venue instance
+    * @returns {Promise<Venue>} A new Venue instance configured appropriately
+    */
+    static connect(venueId: string, credentials?: CredentialsHTTP): Promise<Venue>;
+}
+
+declare class Operation extends Asset {
+    constructor(id: AssetID, venue: VenueInterface, metadata?: AssetMetadata);
+}
+
+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 };