@onchaindb/sdk 0.4.5 → 2.0.0

package/src/types.ts

@@ -1,18 +1,74 @@
-// Core OnChainDB Types
+// Core OnDB Types
 import {QueryValue} from "./query-sdk";
 import {X402Quote} from "./x402/types";
 
-export interface OnChainDBConfig {
+export interface OnDBConfig {
     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)
+    agentKey?: string; // Agent Key with Pay permission (X-Agent-Key header)
     appId?: string; // Application ID for automatic root building
     timeout?: number;
     retryCount?: number;
     retryDelay?: number;
 }
 
+// ============================================================================
+// App Key Management Types
+// ============================================================================
+
+/**
+ * Permissions that can be granted to an app key.
+ * A key with "Pay" permission is an Agent Key — it can pay other apps inline
+ * when accessing their data using USDC via EIP-3009.
+ */
+export type AppKeyPermission = 'Read' | 'Write' | 'Admin' | 'Pay';
+
+/**
+ * Spend limits for Agent Keys (keys with "Pay" permission).
+ * All fields are optional — omitting a field means no limit on that dimension.
+ */
+export interface PayLimits {
+    /** Optional expiry time (ISO 8601). Key stops working after this. */
+    expires_at?: string;
+    /** Max USDC per single transaction, in base units (6 decimals). e.g. 5000000 = 5 USDC */
+    max_payment_per_tx?: number;
+    /** Lifetime spend cap in USDC base units. */
+    spend_allowance?: number;
+    /** Whitelist of target app IDs this key may pay. Omit to allow all apps. */
+    allowed_target_apps?: string[];
+}
+
+/**
+ * Request body for POST /api/apps/:app_id/regenerate-key
+ */
+export interface CreateKeyRequest {
+    name?: string;
+    permissions?: AppKeyPermission[];
+    /** Only used when permissions includes "Pay". Ignored otherwise. */
+    pay_limits?: PayLimits;
+}
+
+/**
+ * App key entry returned by POST /api/apps/:app_id/keys/list
+ */
+export interface AppKeyInfo {
+    key_hash: string;
+    name: string;
+    permissions: AppKeyPermission[];
+    /** ISO 8601 expiry (only present on keys with pay_limits.expires_at set) */
+    expires_at?: string;
+    /** Max USDC per transaction in base units (6 decimals) */
+    max_payment_per_tx?: number;
+    /** Lifetime spend cap in USDC base units */
+    spend_allowance?: number;
+    /** Cumulative USDC spent so far in base units — increments after each on-chain payment */
+    spend_allowance_used?: number;
+    /** Whitelisted target app IDs (undefined = no restriction) */
+    allowed_target_apps?: string[];
+}
+
 export interface StoreRequest {
     root?: string; // Format: "app::collection" or just "collection" for system
     collection?: string; // Collection name (will be combined with appId if provided)
@@ -93,8 +149,8 @@ export interface QueryRequest {
 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
+    find?: any; // Flexible find conditions from onDBSDK
+    select?: any; // Selection map from onDBSDK
 
     // All existing functionality stays the same
     filters?: Record<string, any>;
@@ -144,7 +200,7 @@ export interface TransactionEvents {
 }
 
 // Error Types
-export class OnChainDBError extends Error {
+export class OnDBError extends Error {
     constructor(
         message: string,
         public code: string,
@@ -152,11 +208,11 @@ export class OnChainDBError extends Error {
         public details?: any
     ) {
         super(message);
-        this.name = 'OnChainDBError';
+        this.name = 'OnDBError';
     }
 }
 
-export class TransactionError extends OnChainDBError {
+export class TransactionError extends OnDBError {
     constructor(
         message: string,
         public transactionId: string,
@@ -167,14 +223,14 @@ export class TransactionError extends OnChainDBError {
     }
 }
 
-export class ValidationError extends OnChainDBError {
+export class ValidationError extends OnDBError {
     constructor(message: string, details?: any) {
         super(message, 'VALIDATION_ERROR', 400, details);
         this.name = 'ValidationError';
     }
 }
 
-export class PaymentRequiredError extends OnChainDBError {
+export class PaymentRequiredError extends OnDBError {
     constructor(
         message: string,
         public quote: X402Quote,
@@ -185,7 +241,7 @@ export class PaymentRequiredError extends OnChainDBError {
     }
 }
 
-export class PaymentVerificationError extends OnChainDBError {
+export class PaymentVerificationError extends OnDBError {
     constructor(
         message: string,
         public txHash: string,
@@ -273,59 +329,15 @@ export interface PricingQuoteRequest {
     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';
 
 /**
@@ -519,10 +531,183 @@ export interface SyncCollectionResult {
         field: string;
         type: string;
     }[];
+    sharding_configured?: boolean;
     success: boolean;
     errors?: string[];
 }
 
+// ============================================================================
+// Collection Management
+// ============================================================================
+
+export interface UpdateCollectionRequest {
+    description?: string;
+    public?: boolean;
+    default_sort_column?: string;
+    retention_days?: number | null;
+    collection_type?: 'local' | 'offline' | 'api' | 'hybrid';
+    api_config?: ApiConfig;
+}
+
+export interface ApiConfig {
+    base_url: string;
+    authentication: any;
+    query_mapping: any;
+    response_mapping: any;
+}
+
+export interface CollectionResponse {
+    id: string;
+    name: string;
+    namespace: string;
+    primary_column: string;
+    sort_column?: string;
+    status: string;
+    collection_type: string;
+    document_count: number;
+    size_kb: number;
+    created_at: string;
+    last_modified: string;
+}
+
+export interface SetRetentionRequest {
+    retention_days: number | null;
+}
+
+export interface RetentionConfig {
+    collection: string;
+    retention_days?: number;
+    monthly_cost_per_kb: number;
+    last_cleanup?: string;
+    status: string;
+}
+
+export interface CollectionRetentionCost {
+    collection: string;
+    retention_days?: number;
+    size_kb: number;
+    monthly_cost_per_kb: number;
+    monthly_cost_tia: number;
+    projected_size_kb: number;
+    projected_monthly_cost_tia: number;
+}
+
+export interface RetentionCostResponse {
+    app_id: string;
+    collections: CollectionRetentionCost[];
+    total_monthly_cost_tia: number;
+    projected_next_month_cost_tia: number;
+}
+
+// ============================================================================
+// SQL Interface
+// ============================================================================
+
+export interface SqlQueryRequest {
+    sql: string;
+    include_history?: boolean;
+}
+
+export interface SqlQueryResponse {
+    data: any[];
+    count: number;
+    query: string;
+    app_id: string;
+    collection: string;
+}
+
+export interface SqlInsertRequest {
+    sql: string;
+}
+
+// ============================================================================
+// Predefined Queries
+// ============================================================================
+
+export interface QueryParameter {
+    /** Parameter name (used in URL query params) */
+    name: string;
+    /** Field path in the query (e.g., "market" or "price.$gte") */
+    field_path: string;
+    /** Default value if not provided */
+    default?: any;
+    /** Whether this parameter is required (no default, must be provided) */
+    required?: boolean;
+    /** Description of the parameter */
+    description?: string;
+}
+
+export interface QueryDefinition {
+    name: string;
+    source_collection: string;
+    base_query: any;
+    parameters?: QueryParameter[];
+    created_at: string;
+    description?: string;
+}
+
+export interface CreateQueryRequest {
+    name: string;
+    source_collection: string;
+    base_query: any;
+    parameters?: QueryParameter[];
+    description?: string;
+    version?: number;
+    response_schema?: any;
+    sample_response?: any;
+    example_request?: any;
+    example_response?: any;
+}
+
+export interface CreateQueryResponse {
+    success: boolean;
+    message: string;
+    query_name: string;
+}
+
+export interface QueryDataResponse {
+    success: boolean;
+    query_name: string;
+    data: any[];
+    count: number;
+    query_time_ms: number;
+}
+
+// ============================================================================
+// Views
+// ============================================================================
+
+export interface SqlCreateViewRequest {
+    sql: string;
+    refresh_mode?: 'live' | 'lazy';
+}
+
+export interface ViewDataResponse<T = any> {
+    success: boolean;
+    view_name: string;
+    data: T[];
+    count: number;
+    query_time_ms: number;
+}
+
+export interface ViewQueryRequest {
+    find?: any;
+    select?: string[];
+    sort_by?: string[];
+    limit?: number;
+    offset?: number;
+}
+
+// ============================================================================
+// API Collections
+// ============================================================================
+
+export interface CreateApiCollectionRequest {
+    name: string;
+    description: string;
+    api_config: ApiConfig;
+}
+
 /**
  * Base document fields (auto-added when useBaseFields is true)
  */

package/src/x402/types.ts

@@ -47,7 +47,7 @@ export interface X402PaymentRequirement {
 }
 
 /**
- * x402 Extra field with OnChainDB extensions
+ * x402 Extra field with OnDB extensions
  */
 export interface X402Extra {
     /** Extension identifier */
@@ -164,8 +164,8 @@ export interface X402PaymentResponse {
 export interface X402Quote {
     /** Quote ID */
     quoteId: string;
-    /** Total cost in TIA */
-    totalCostTia: number;
+    /** Total cost */
+    totalCost: number;
     /** Amount in smallest units */
     amountRaw: string;
     /** Broker/recipient address */

package/src/x402/utils.ts

@@ -79,9 +79,9 @@ export function requirementToQuote(
         chainType = 'solana';
     }
 
-    // Calculate TIA amount (for display purposes)
+    // Calculate total cost (for display purposes)
     const decimals = extra.tokenDecimals || 6;
-    const totalCostTia = parseInt(amountRaw) / Math.pow(10, decimals);
+    const totalCost = parseInt(amountRaw) / Math.pow(10, decimals);
 
     // Calculate expiration
     const expiresAt = extra.pricing?.expiresAt ||
@@ -89,7 +89,7 @@ export function requirementToQuote(
 
     return {
         quoteId: extra.quoteId || '',
-        totalCostTia,
+        totalCost,
         amountRaw,
         brokerAddress: requirement.payTo,
         description: requirement.description,

package/examples/blob-upload-example.ts

@@ -1,140 +0,0 @@
-/**
- * OnChainDB SDK - Blob Upload Example
- *
- * Demonstrates how to upload binary files (images, videos, documents)
- * to OnChainDB with the x402 payment protocol.
- *
- * Features:
- * - Get pricing quote for blob upload
- * - Upload blob with custom metadata
- * - Track upload progress with ticket_id
- * - Retrieve uploaded blob
- * - Query blob metadata
- */
-
-import { createClient } from '../src';
-
-const config = {
-  endpoint: 'http://localhost:9092',
-  apiKey: 'your_api_key',
-  appId: 'my_app'
-};
-
-const BROKER_ADDRESS = 'celestia1broker...';
-
-async function uploadProfilePhoto() {
-  console.log('OnChainDB Blob Upload Example\n');
-
-  const client = createClient(config);
-
-  // In a real app, get file from input:
-  // const file = document.querySelector('input[type="file"]').files[0];
-
-  // For this example, create a mock blob
-  const mockBlob = new Blob(['mock image data'], { type: 'image/jpeg' });
-  const fileSizeKB = Math.ceil(mockBlob.size / 1024);
-
-  // Step 1: Get pricing quote
-  console.log('1. Getting pricing quote...');
-  const quote = await client.getPricingQuote({
-    app_id: config.appId,
-    operation_type: 'write',
-    size_kb: fileSizeKB,
-    collection: 'avatars'
-  });
-
-  const costInUtia = Math.ceil(quote.total_cost * 1_000_000);
-  console.log(`   Size: ${fileSizeKB}KB`);
-  console.log(`   Cost: ${quote.total_cost} TIA (${costInUtia} utia)`);
-  console.log();
-
-  // Step 2: Create payment transaction
-  // In a real app with Keplr:
-  // const result = await wallet.signAndBroadcast(
-  //   BROKER_ADDRESS,
-  //   `${costInUtia}utia`,
-  //   'Image upload'
-  // );
-  // const paymentTxHash = result.transactionHash;
-
-  const paymentTxHash = 'mock_payment_tx_hash';
-  const userAddress = 'celestia1user...';
-
-  console.log('2. Payment transaction created');
-  console.log(`   TX Hash: ${paymentTxHash}`);
-  console.log();
-
-  // Step 3: Upload blob with metadata
-  console.log('3. Uploading blob...');
-  const uploadResult = await client.uploadBlob({
-    collection: 'avatars',
-    blob: mockBlob,
-    metadata: {
-      user_address: userAddress,
-      description: 'Profile photo',
-      is_primary: true
-    },
-    payment_tx_hash: paymentTxHash,
-    user_address: userAddress,
-    broker_address: BROKER_ADDRESS,
-    amount_utia: costInUtia
-  });
-
-  console.log('   Blob upload initiated!');
-  console.log(`   Blob ID: ${uploadResult.blob_id}`);
-  console.log(`   Ticket ID: ${uploadResult.ticket_id}`);
-  console.log();
-
-  // Step 4: Wait for upload completion
-  console.log('4. Waiting for upload to complete...');
-  const task = await client.waitForTaskCompletion(uploadResult.ticket_id);
-
-  console.log(`   Status: ${task.status}`);
-  if (task.status === 'Completed') {
-    console.log(`   TX Hash: ${task.transaction_hash}`);
-    console.log(`   Block Height: ${task.block_height}`);
-  }
-  console.log();
-
-  // Step 5: Query blob metadata
-  console.log('5. Querying blob metadata...');
-  const blobs = await client.queryBlobMetadata('avatars', {
-    user_address: userAddress
-  });
-
-  console.log(`   Found ${blobs.length} blobs for user`);
-  for (const blob of blobs) {
-    console.log(`   - Blob ID: ${blob.blob_id}`);
-    console.log(`     Type: ${blob.content_type}`);
-    console.log(`     Size: ${blob.size_bytes} bytes`);
-  }
-  console.log();
-
-  // Step 6: Retrieve blob
-  console.log('6. Retrieving blob...');
-  const retrievedBlob = await client.retrieveBlob({
-    collection: 'avatars',
-    blob_id: uploadResult.blob_id
-  });
-
-  console.log('   Blob retrieved successfully!');
-  console.log(`   Size: ${retrievedBlob instanceof Blob ? retrievedBlob.size : retrievedBlob.length} bytes`);
-
-  // In browser, display the image:
-  // const imageUrl = URL.createObjectURL(retrievedBlob);
-  // document.querySelector('img').src = imageUrl;
-
-  console.log('\nBlob upload example complete!');
-}
-
-// Run example
-if (require.main === module) {
-  uploadProfilePhoto()
-    .then(() => process.exit(0))
-    .catch((error) => {
-      console.error('Error:', error.message);
-      process.exit(1);
-    });
-}
-
-export { uploadProfilePhoto };