@debros/network-ts-sdk 0.2.5 → 0.3.2

package/dist/index.d.ts

@@ -32,6 +32,17 @@ declare class HttpClient {
     post<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
     put<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
     delete<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    /**
+     * Upload a file using multipart/form-data
+     * This is a special method for file uploads that bypasses JSON serialization
+     */
+    uploadFile<T = any>(path: string, formData: FormData, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * Get a binary response (returns Response object for streaming)
+     */
+    getBinary(path: string): Promise<Response>;
     getToken(): string | undefined;
 }
 
@@ -489,6 +500,201 @@ declare class NetworkClient {
     proxyAnon(request: ProxyRequest): Promise<ProxyResponse>;
 }
 
+interface CacheGetRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheGetResponse {
+    key: string;
+    value: any;
+    dmap: string;
+}
+interface CachePutRequest {
+    dmap: string;
+    key: string;
+    value: any;
+    ttl?: string;
+}
+interface CachePutResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheDeleteRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheDeleteResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheMultiGetRequest {
+    dmap: string;
+    keys: string[];
+}
+interface CacheMultiGetResponse {
+    results: Array<{
+        key: string;
+        value: any;
+    }>;
+    dmap: string;
+}
+interface CacheScanRequest {
+    dmap: string;
+    match?: string;
+}
+interface CacheScanResponse {
+    keys: string[];
+    count: number;
+    dmap: string;
+}
+interface CacheHealthResponse {
+    status: string;
+    service: string;
+}
+declare class CacheClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Check cache service health
+     */
+    health(): Promise<CacheHealthResponse>;
+    /**
+     * Get a value from cache
+     * Returns null if the key is not found (cache miss/expired), which is normal behavior
+     */
+    get(dmap: string, key: string): Promise<CacheGetResponse | null>;
+    /**
+     * Put a value into cache
+     */
+    put(dmap: string, key: string, value: any, ttl?: string): Promise<CachePutResponse>;
+    /**
+     * Delete a value from cache
+     */
+    delete(dmap: string, key: string): Promise<CacheDeleteResponse>;
+    /**
+     * Get multiple values from cache in a single request
+     * Returns a map of key -> value (or null if not found)
+     * Gracefully handles 404 errors (endpoint not implemented) by returning empty results
+     */
+    multiGet(dmap: string, keys: string[]): Promise<Map<string, any | null>>;
+    /**
+     * Scan keys in a distributed map, optionally matching a regex pattern
+     */
+    scan(dmap: string, match?: string): Promise<CacheScanResponse>;
+}
+
+interface StorageUploadResponse {
+    cid: string;
+    name: string;
+    size: number;
+}
+interface StoragePinRequest {
+    cid: string;
+    name?: string;
+}
+interface StoragePinResponse {
+    cid: string;
+    name: string;
+}
+interface StorageStatus {
+    cid: string;
+    name: string;
+    status: string;
+    replication_min: number;
+    replication_max: number;
+    replication_factor: number;
+    peers: string[];
+    error?: string;
+}
+declare class StorageClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Upload content to IPFS and optionally pin it.
+     * Supports both File objects (browser) and Buffer/ReadableStream (Node.js).
+     *
+     * @param file - File to upload (File, Blob, or Buffer)
+     * @param name - Optional filename
+     * @param options - Optional upload options
+     * @param options.pin - Whether to pin the content (default: true). Pinning happens asynchronously on the backend.
+     * @returns Upload result with CID
+     *
+     * @example
+     * ```ts
+     * // Browser
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     * const result = await client.storage.upload(file, file.name);
+     * console.log(result.cid);
+     *
+     * // Node.js
+     * const fs = require('fs');
+     * const fileBuffer = fs.readFileSync('image.jpg');
+     * const result = await client.storage.upload(fileBuffer, 'image.jpg', { pin: true });
+     * ```
+     */
+    upload(file: File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, name?: string, options?: {
+        pin?: boolean;
+    }): Promise<StorageUploadResponse>;
+    /**
+     * Pin an existing CID
+     *
+     * @param cid - Content ID to pin
+     * @param name - Optional name for the pin
+     * @returns Pin result
+     */
+    pin(cid: string, name?: string): Promise<StoragePinResponse>;
+    /**
+     * Get the pin status for a CID
+     *
+     * @param cid - Content ID to check
+     * @returns Pin status information
+     */
+    status(cid: string): Promise<StorageStatus>;
+    /**
+     * Retrieve content from IPFS by CID
+     *
+     * @param cid - Content ID to retrieve
+     * @returns ReadableStream of the content
+     *
+     * @example
+     * ```ts
+     * const stream = await client.storage.get(cid);
+     * const reader = stream.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process chunk
+     * }
+     * ```
+     */
+    get(cid: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Retrieve content from IPFS by CID and return the full Response object
+     * Useful when you need access to response headers (e.g., content-length)
+     *
+     * @param cid - Content ID to retrieve
+     * @returns Response object with body stream and headers
+     *
+     * @example
+     * ```ts
+     * const response = await client.storage.getBinary(cid);
+     * const contentLength = response.headers.get('content-length');
+     * const reader = response.body.getReader();
+     * // ... read stream
+     * ```
+     */
+    getBinary(cid: string): Promise<Response>;
+    /**
+     * Unpin a CID
+     *
+     * @param cid - Content ID to unpin
+     */
+    unpin(cid: string): Promise<void>;
+}
+
 declare class SDKError extends Error {
     readonly httpStatus: number;
     readonly code: string;
@@ -516,7 +722,9 @@ interface Client {
     db: DBClient;
     pubsub: PubSubClient;
     network: NetworkClient;
+    cache: CacheClient;
+    storage: StorageClient;
 }
 declare function createClient(config: ClientConfig): Client;
 
-export { AuthClient, type AuthConfig, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type Entity, type ErrorHandler, type FindOptions, HttpClient, LocalStorageAdapter, MemoryStorage, type Message, type MessageHandler, NetworkClient, type NetworkStatus, type PeerInfo, type ProxyRequest, type ProxyResponse, PubSubClient, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, Subscription, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };
+export { AuthClient, type AuthConfig, CacheClient, type CacheDeleteRequest, type CacheDeleteResponse, type CacheGetRequest, type CacheGetResponse, type CacheHealthResponse, type CacheMultiGetRequest, type CacheMultiGetResponse, type CachePutRequest, type CachePutResponse, type CacheScanRequest, type CacheScanResponse, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type Entity, type ErrorHandler, type FindOptions, HttpClient, LocalStorageAdapter, MemoryStorage, type Message, type MessageHandler, NetworkClient, type NetworkStatus, type PeerInfo, type ProxyRequest, type ProxyResponse, PubSubClient, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, StorageClient, type StoragePinRequest, type StoragePinResponse, type StorageStatus, type StorageUploadResponse, Subscription, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };