@onchaindb/sdk 0.4.0 → 0.4.2

package/src/types.d.ts

@@ -0,0 +1,131 @@
+import { QueryValue } from "./query-sdk";
+export interface OnChainDBConfig {
+    endpoint: string;
+    apiKey?: string;
+    appId?: string;
+    timeout?: number;
+    retryCount?: number;
+    retryDelay?: number;
+}
+export interface StoreRequest {
+    root?: string;
+    collection?: string;
+    data: Record<string, any>[];
+    payment_proof?: {
+        tx_hash: string;
+        user_address: string;
+        amount_utia: number;
+        broker_address: string;
+    };
+}
+export interface StoreResponse {
+    id: string;
+    namespace: string;
+    block_height: number;
+    transaction_hash: string;
+    confirmed: boolean;
+    celestia_height: number;
+}
+export interface TransactionStatus {
+    id: string;
+    status: 'pending' | 'confirmed' | 'failed';
+    block_height?: number;
+    transaction_hash?: string;
+    celestia_height?: number;
+    error?: string;
+}
+export interface QueryRequest {
+    root?: string;
+    collection?: string;
+    app?: string;
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortDirection?: string;
+    find?: QueryValue["find"];
+    select?: QueryValue["select"];
+}
+export interface AdvancedQueryRequest {
+    root?: string;
+    collection?: string;
+    find?: any;
+    select?: any;
+    filters?: Record<string, any>;
+    app?: string;
+    limit?: number;
+    offset?: number;
+    sort?: string[];
+}
+export interface QueryResponse<T extends Record<string, any>> {
+    records: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
+export interface TransactionEvents {
+    'transaction:pending': (tx: TransactionStatus) => void;
+    'transaction:confirmed': (tx: TransactionStatus) => void;
+    'transaction:failed': (tx: TransactionStatus) => void;
+    'error': (error: Error) => void;
+}
+export declare class OnChainDBError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: any | undefined);
+}
+export declare class TransactionError extends OnChainDBError {
+    transactionId: string;
+    constructor(message: string, transactionId: string, details?: any);
+}
+export declare class ValidationError extends OnChainDBError {
+    constructor(message: string, details?: any);
+}
+export declare class PaymentRequiredError extends OnChainDBError {
+    requiredAmount: number;
+    providedAmount?: number | undefined;
+    constructor(message: string, requiredAmount: number, providedAmount?: number | undefined, details?: any);
+}
+export declare class PaymentVerificationError extends OnChainDBError {
+    txHash: string;
+    constructor(message: string, txHash: string, details?: any);
+}
+export interface IndexRequest {
+    collection: string;
+    field: string;
+    type: 'string' | 'number' | 'boolean' | 'date';
+}
+export interface IndexResponse {
+    id: string;
+    collection: string;
+    field: string;
+    type: string;
+    status: 'active' | 'building' | 'failed';
+}
+export interface IndexPaymentProof {
+    tx_hash: string;
+    user_address: string;
+    broker_address: string;
+    amount_utia: number;
+    estimated_cost: IndexCostEstimate;
+}
+export interface IndexCostEstimate {
+    field_name: string;
+    index_type: string;
+    existing_records_count: number;
+    total_estimated_cost_utia: number;
+    ongoing_write_cost_per_record_utia: number;
+    index_size_estimate_mb: number;
+    breakdown: {
+        base_cost_utia: number;
+        per_record_cost_utia: number;
+        storage_cost_utia: number;
+    };
+}
+export interface StorageCostEstimate {
+    data_size_bytes: number;
+    total_cost_utia: number;
+    cost_per_kb_utia: number;
+    estimated_celestia_fee_utia: number;
+    broker_fee_utia: number;
+}

package/src/types.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentVerificationError = exports.PaymentRequiredError = exports.ValidationError = exports.TransactionError = exports.OnChainDBError = void 0;
+// Error Types
+class OnChainDBError extends Error {
+    constructor(message, code, statusCode, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'OnChainDBError';
+    }
+}
+exports.OnChainDBError = OnChainDBError;
+class TransactionError extends OnChainDBError {
+    constructor(message, transactionId, details) {
+        super(message, 'TRANSACTION_ERROR', undefined, details);
+        this.transactionId = transactionId;
+        this.name = 'TransactionError';
+    }
+}
+exports.TransactionError = TransactionError;
+class ValidationError extends OnChainDBError {
+    constructor(message, details) {
+        super(message, 'VALIDATION_ERROR', 400, details);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class PaymentRequiredError extends OnChainDBError {
+    constructor(message, requiredAmount, providedAmount, details) {
+        super(message, 'PAYMENT_REQUIRED', 402, details);
+        this.requiredAmount = requiredAmount;
+        this.providedAmount = providedAmount;
+        this.name = 'PaymentRequiredError';
+    }
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+class PaymentVerificationError extends OnChainDBError {
+    constructor(message, txHash, details) {
+        super(message, 'PAYMENT_VERIFICATION_FAILED', 402, details);
+        this.txHash = txHash;
+        this.name = 'PaymentVerificationError';
+    }
+}
+exports.PaymentVerificationError = PaymentVerificationError;

package/src/types.ts

@@ -0,0 +1,534 @@
+// Core OnChainDB Types
+import {QueryValue} from "./query-sdk";
+import {X402Quote} from "./x402/types";
+
+export interface OnChainDBConfig {
+    endpoint: string;
+    apiKey?: string; // Deprecated: use appKey instead
+    appKey?: string; // App API key for write operations (X-App-Key header)
+    userKey?: string; // User API key for Auto-Pay (X-User-Key header)
+    appId?: string; // Application ID for automatic root building
+    timeout?: number;
+    retryCount?: number;
+    retryDelay?: number;
+}
+
+export interface StoreRequest {
+    root?: string; // Format: "app::collection" or just "collection" for system
+    collection?: string; // Collection name (will be combined with appId if provided)
+    data: Record<string, any>[];
+    // Payment is handled via x402 protocol (X-PAYMENT header)
+    // Use the paymentCallback parameter in store() method
+}
+
+export interface StoreResponse {
+    id: string;
+    namespace: string;
+    block_height: number;
+    transaction_hash: string;
+    confirmed: boolean;
+    celestia_height: number;
+    /** Ticket ID for async operations (when waitForConfirmation is false) */
+    ticket_id?: string;
+}
+
+// New async ticket-based response
+export interface AsyncStoreResponse {
+    ticket_id: string;
+    status: string;
+    message: string;
+}
+
+// Task status types
+export type TaskStatus =
+    | "Pending"
+    | "PaymentBroadcast"
+    | "PaymentConfirming"
+    | "PaymentConfirmed"
+    | "StoringData"
+    | "Completed"
+    | { Failed: { error: string } };
+
+export interface TaskInfo {
+    ticket_id: string;
+    status: TaskStatus;
+    created_at: string;
+    updated_at: string;
+    operation_type: string;
+    user_address?: string;
+    transaction_hash?: string;
+    block_height?: number;
+    result?: any;
+    progress_log: string[];
+}
+
+export interface UserTasksResponse {
+    user_address: string;
+    tasks: TaskInfo[];
+    total_tasks: number;
+}
+
+export interface TransactionStatus {
+    id: string;
+    status: 'pending' | 'confirmed' | 'failed';
+    block_height?: number;
+    transaction_hash?: string;
+    celestia_height?: number;
+    error?: string;
+}
+
+export interface QueryRequest {
+    root?: string; // Format: "app::collection" - ONLY NEW THING
+    collection?: string; // Collection name (will be combined with appId if provided)
+    app?: string;
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortDirection?: string,
+    find?: QueryValue["find"],
+    select?: QueryValue["select"],
+}
+
+// Enhanced query support for advanced query builder
+export interface AdvancedQueryRequest {
+    root?: string; // Format: "app::collection" - ONLY NEW THING
+    collection?: string; // Collection name (will be combined with appId if provided)
+    find?: any; // Flexible find conditions from onChainDBSDK
+    select?: any; // Selection map from onChainDBSDK
+
+    // All existing functionality stays the same
+    filters?: Record<string, any>;
+    app?: string;
+
+    // Pagination and sorting
+    limit?: number;
+    offset?: number;
+    sort?: string[];
+}
+
+
+export interface QueryResponse<T extends Record<string, any>> {
+    records: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
+
+export interface ReadQueryWithPayment {
+    // Original query fields
+    root?: string;
+    collection?: string;
+    find?: any;
+    select?: any;
+    limit?: number;
+    offset?: number;
+    sort?: string[];
+
+    // Payment is handled via x402 protocol (X-PAYMENT header)
+    // Use the paymentCallback parameter in query methods
+    quote_id: string;
+}
+
+// Union type for query responses - either data or quote
+export type QueryResult<T extends Record<string, any>> =
+    | QueryResponse<T>  // Normal response with data
+    | X402Quote;        // Quote response when payment required (x402 format)
+
+// Transaction Events
+export interface TransactionEvents {
+    'transaction:queued': (ticket: { ticket_id: string; status: string; message: string }) => void;
+    'transaction:pending': (tx: TransactionStatus) => void;
+    'transaction:confirmed': (tx: TransactionStatus) => void;
+    'transaction:failed': (tx: TransactionStatus) => void;
+    'error': (error: Error) => void;
+}
+
+// Error Types
+export class OnChainDBError extends Error {
+    constructor(
+        message: string,
+        public code: string,
+        public statusCode?: number,
+        public details?: any
+    ) {
+        super(message);
+        this.name = 'OnChainDBError';
+    }
+}
+
+export class TransactionError extends OnChainDBError {
+    constructor(
+        message: string,
+        public transactionId: string,
+        details?: any
+    ) {
+        super(message, 'TRANSACTION_ERROR', undefined, details);
+        this.name = 'TransactionError';
+    }
+}
+
+export class ValidationError extends OnChainDBError {
+    constructor(message: string, details?: any) {
+        super(message, 'VALIDATION_ERROR', 400, details);
+        this.name = 'ValidationError';
+    }
+}
+
+export class PaymentRequiredError extends OnChainDBError {
+    constructor(
+        message: string,
+        public quote: X402Quote,
+        details?: any
+    ) {
+        super(message, 'PAYMENT_REQUIRED', 402, details);
+        this.name = 'PaymentRequiredError';
+    }
+}
+
+export class PaymentVerificationError extends OnChainDBError {
+    constructor(
+        message: string,
+        public txHash: string,
+        details?: any
+    ) {
+        super(message, 'PAYMENT_VERIFICATION_FAILED', 402, details);
+        this.name = 'PaymentVerificationError';
+    }
+}
+
+// Index Management
+export interface IndexRequest {
+    collection: string;
+    field: string;
+    type: 'string' | 'number' | 'boolean' | 'date';
+}
+
+export interface IndexResponse {
+    id: string;
+    collection: string;
+    field: string;
+    type: string;
+    status: 'active' | 'building' | 'failed';
+}
+
+// Relation Management
+export interface RelationRequest {
+    parent_collection: string;
+    parent_field: string;
+    child_collection: string;
+    child_field: string;
+}
+
+export interface RelationResponse {
+    parent_collection: string;
+    parent_field: string;
+    child_field: string;
+    created_at: string;
+    indexes_created: {
+        parent_index: boolean;
+        child_index: boolean;
+    };
+}
+
+// Blob Storage (CDN) Types
+export interface UploadBlobRequest {
+    collection: string;
+    blob: File | Blob | Buffer; // File in browser, Buffer in Node.js
+    metadata?: Record<string, any>; // Additional custom fields for blob metadata
+    // Payment is handled via x402 protocol (X-PAYMENT header)
+    // Use the paymentCallback parameter in uploadBlob() method
+}
+
+export interface UploadBlobResponse {
+    ticket_id: string;
+    blob_id: string;
+    status: string;
+    message: string;
+}
+
+export interface RetrieveBlobRequest {
+    collection: string;
+    blob_id: string;
+}
+
+export interface BlobMetadata {
+    blob_id: string;
+    content_type: string;
+    size_bytes: number;
+    uploaded_at: string;
+    tx_hash: string;
+    celestia_height: number;
+
+    [key: string]: any; // Custom fields added by user
+}
+
+// Pricing Quote Types for cost estimation
+
+export interface PricingQuoteRequest {
+    app_id: string;
+    operation_type: 'read' | 'write';
+    size_kb: number;
+    collection: string;
+    monthly_volume_kb?: number;
+    data?: any; // Sample data for price index calculation
+}
+
+export interface PricingQuoteResponse {
+    type: 'write_quote_with_indexing' | 'read_quote';
+    // Base costs
+    base_celestia_cost: number;
+    base_celestia_cost_utia: number;
+    broker_fee: number;
+    broker_fee_utia: number;
+    // Indexing costs per field
+    indexing_costs: Record<string, number>;
+    indexing_costs_utia: Record<string, number>;
+    // Total before price index fees
+    base_total_cost: number;
+    base_total_cost_utia: number;
+    // Final total (includes price index fees if any)
+    total_cost: number;
+    total_cost_utia: number;
+    // Metadata
+    indexed_fields_count: number;
+    request: PricingQuoteRequest;
+    monthly_volume_kb: number;
+    currency: string;
+    // Optional breakdowns
+    creator_premium?: {
+        premium_total: number;
+        premium_total_utia: number;
+        premium_type: string;
+        premium_amount: number;
+        creator_revenue: number;
+        creator_revenue_utia: number;
+        platform_revenue: number;
+        platform_revenue_utia: number;
+        revenue_split: string;
+    };
+    price?: any; // Price index breakdown (single or multiple fields)
+}
+
+// ============================================================================
+// Collection Schema Types (for createCollection convenience method)
+// ============================================================================
+
+// Re-export from database.ts for consistency
+export type {
+    Collection,
+    CollectionSchema,
+    FieldDefinition,
+    FieldValidation,
+    Relationship,
+    Index,
+    IndexOptions,
+    IndexStatus,
+    IndexStatistics,
+    PriceConfig,
+    CollectionMetadata
+} from './database';
+
+/**
+ * Simplified schema for createCollection convenience method
+ *
+ * @example
+ * ```typescript
+ * const schema: SimpleCollectionSchema = {
+ *   name: 'users',
+ *   fields: {
+ *     email: { type: 'string', index: true },
+ *     username: { type: 'string', index: true },
+ *     age: { type: 'number' },
+ *     // Nested fields use dot notation
+ *     'address.city': { type: 'string', index: true },
+ *     'address.country': { type: 'string', index: true }
+ *   },
+ *   useBaseFields: true
+ * };
+ * ```
+ */
+export interface SimpleCollectionSchema {
+    /** Collection name */
+    name: string;
+    /** Field definitions */
+    fields: Record<string, SimpleFieldDefinition>;
+    /**
+     * Include base fields (id, createdAt, updatedAt, deletedAt)
+     * @default true
+     */
+    useBaseFields?: boolean;
+}
+
+/**
+ * Simplified field definition for createCollection
+ */
+export interface SimpleFieldDefinition {
+    /** Field data type */
+    type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+    /** Create an index on this field */
+    index?: boolean;
+    /** Unique constraint - enables automatic deduplication (returns only latest version by this field) */
+    unique?: boolean;
+    /** Index type (defaults based on field type). Use 'price' for payment splits. */
+    indexType?: 'btree' | 'hash' | 'fulltext' | 'price';
+    /** Read pricing (for monetized fields) */
+    readPricing?: {
+        pricePerAccess?: number;
+        pricePerKb?: number;
+    };
+}
+
+// ============================================================================
+// Sharding Types (for high-scale collections)
+// ============================================================================
+
+/**
+ * Sharding configuration for partitioning large collections
+ *
+ * Sharding splits a collection across multiple files based on field values,
+ * enabling efficient queries on massive datasets (e.g., 50+ markets × hourly data).
+ *
+ * @example
+ * ```typescript
+ * // Shard by market and hour for crypto orderbook data
+ * const sharding: ShardingStrategy = {
+ *   keys: [
+ *     { field: 'market', type: 'discrete' },
+ *     { field: 'timestamp', type: 'time_range', granularity: 'hour' }
+ *   ],
+ *   enforce_in_queries: true,
+ *   max_shard_size: 50_000_000 // 50MB max per shard
+ * };
+ * // Results in shards like: SUI/2025-01-15-12/metadata.jsonl
+ * // Query "market=SUI, hour=12" scans 600KB instead of 30GB (50,000x reduction)
+ * ```
+ */
+export interface ShardingStrategy {
+    /**
+     * Ordered list of shard keys - each adds a level to the shard hierarchy
+     * Example: [market, timestamp] creates shards like "SUI/2025-01-15-12"
+     */
+    keys: ShardKey[];
+
+    /**
+     * If true, queries MUST include all shard keys to prevent full table scans
+     * Recommended: true for production to ensure optimal performance
+     */
+    enforce_in_queries: boolean;
+
+    /**
+     * Maximum size per shard in bytes (optional)
+     * When exceeded, suggests creating finer-grained time buckets
+     */
+    max_shard_size?: number;
+}
+
+/**
+ * Individual shard key definition
+ */
+export interface ShardKey {
+    /**
+     * Field name to shard by (must be an indexed field)
+     */
+    field: string;
+
+    /**
+     * Sharding type:
+     * - 'discrete': Exact value matching (e.g., market symbols: SUI, BTC, ETH)
+     * - 'time_range': Time-based bucketing (e.g., hourly, daily partitions)
+     * - 'hash_distributed': Hash-based distribution for even spread
+     */
+    type: 'discrete' | 'time_range' | 'hash_distributed';
+
+    /**
+     * Time granularity (required for time_range sharding)
+     * - 'minute': YYYY-MM-DD-HH-MM
+     * - 'hour': YYYY-MM-DD-HH
+     * - 'day': YYYY-MM-DD
+     * - 'week': YYYY-WNN (ISO week)
+     * - 'month': YYYY-MM
+     */
+    granularity?: 'minute' | 'hour' | 'day' | 'week' | 'month';
+
+    /**
+     * Number of hash buckets (required for hash_distributed sharding)
+     * Example: 100 buckets for even user distribution
+     */
+    num_buckets?: number;
+}
+
+/**
+ * Extended SimpleCollectionSchema with sharding support
+ *
+ * @example
+ * ```typescript
+ * const schema: SimpleCollectionSchemaWithSharding = {
+ *   name: 'orderbook_snapshots',
+ *   fields: {
+ *     market: { type: 'string', index: true },
+ *     timestamp: { type: 'number', index: true },
+ *     mid_price: { type: 'number' }
+ *   },
+ *   sharding: {
+ *     keys: [
+ *       { field: 'market', type: 'discrete' },
+ *       { field: 'timestamp', type: 'time_range', granularity: 'hour' }
+ *     ],
+ *     enforce_in_queries: true
+ *   }
+ * };
+ * ```
+ */
+export interface SimpleCollectionSchemaWithSharding extends SimpleCollectionSchema {
+    /**
+     * Optional sharding configuration for high-scale collections
+     * When enabled, collection is partitioned across multiple files
+     */
+    sharding?: ShardingStrategy;
+}
+
+/**
+ * Result of createCollection operation
+ */
+export interface CreateCollectionResult {
+    collection: string;
+    indexes: {
+        field: string;
+        type: string;
+        status: 'created' | 'updated' | 'failed';
+        error?: string;
+    }[];
+    success: boolean;
+    warnings?: string[];
+}
+
+/**
+ * Result of syncCollection operation
+ */
+export interface SyncCollectionResult {
+    collection: string;
+    created: {
+        field: string;
+        type: string;
+    }[];
+    removed: {
+        field: string;
+        type: string;
+    }[];
+    unchanged: {
+        field: string;
+        type: string;
+    }[];
+    success: boolean;
+    errors?: string[];
+}
+
+/**
+ * Base document fields (auto-added when useBaseFields is true)
+ */
+export interface BaseDocument {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+}