@object-ui/data-objectstack 0.3.1 → 2.0.0

package/dist/index.cjs

@@ -22,17 +22,370 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  BulkOperationError: () => BulkOperationError,
+  ConnectionError: () => ConnectionError,
+  MetadataNotFoundError: () => MetadataNotFoundError,
   ObjectStackAdapter: () => ObjectStackAdapter,
-  createObjectStackAdapter: () => createObjectStackAdapter
+  ObjectStackError: () => ObjectStackError,
+  ValidationError: () => ValidationError,
+  createErrorFromResponse: () => createErrorFromResponse,
+  createObjectStackAdapter: () => createObjectStackAdapter,
+  isErrorType: () => isErrorType,
+  isObjectStackError: () => isObjectStackError
 });
 module.exports = __toCommonJS(index_exports);
 var import_client = require("@objectstack/client");
 var import_core = require("@object-ui/core");
+
+// src/cache/MetadataCache.ts
+var MetadataCache = class {
+  /**
+   * Create a new MetadataCache instance
+   * 
+   * @param options - Configuration options
+   * @param options.maxSize - Maximum number of entries (default: 100)
+   * @param options.ttl - Time to live in milliseconds (default: 5 minutes)
+   */
+  constructor(options = {}) {
+    __publicField(this, "cache");
+    __publicField(this, "maxSize");
+    __publicField(this, "ttl");
+    __publicField(this, "stats");
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 5 * 60 * 1e3;
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0
+    };
+  }
+  /**
+   * Get a value from cache or fetch it using the provided fetcher function
+   * 
+   * @param key - Cache key
+   * @param fetcher - Async function to fetch data if not in cache
+   * @returns Promise resolving to the cached or fetched data
+   */
+  async get(key, fetcher) {
+    const now = Date.now();
+    const cached = this.cache.get(key);
+    if (cached) {
+      const age = now - cached.timestamp;
+      if (age < this.ttl) {
+        cached.accessCount++;
+        cached.lastAccessed = now;
+        this.stats.hits++;
+        this.cache.delete(key);
+        this.cache.set(key, cached);
+        return cached.data;
+      } else {
+        this.cache.delete(key);
+      }
+    }
+    this.stats.misses++;
+    const data = await fetcher();
+    this.set(key, data);
+    return data;
+  }
+  /**
+   * Set a value in the cache
+   * 
+   * @param key - Cache key
+   * @param data - Data to cache
+   */
+  set(key, data) {
+    const now = Date.now();
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      this.evictLRU();
+    }
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      accessCount: 1,
+      lastAccessed: now
+    });
+  }
+  /**
+   * Evict the least recently used entry
+   */
+  evictLRU() {
+    const firstKey = this.cache.keys().next().value;
+    if (firstKey !== void 0) {
+      this.cache.delete(firstKey);
+      this.stats.evictions++;
+    }
+  }
+  /**
+   * Invalidate a specific cache entry or all entries
+   * 
+   * @param key - Optional key to invalidate. If omitted, invalidates all entries
+   */
+  invalidate(key) {
+    if (key) {
+      this.cache.delete(key);
+    } else {
+      this.cache.clear();
+    }
+  }
+  /**
+   * Clear all cache entries and reset statistics
+   */
+  clear() {
+    this.cache.clear();
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0
+    };
+  }
+  /**
+   * Get cache statistics
+   * 
+   * @returns Cache statistics including hit rate
+   */
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    const hitRate = total > 0 ? this.stats.hits / total : 0;
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      evictions: this.stats.evictions,
+      hitRate
+    };
+  }
+  /**
+   * Check if a key exists in the cache (and is not expired)
+   * 
+   * @param key - Cache key to check
+   * @returns true if the key exists and is not expired
+   */
+  has(key) {
+    const cached = this.cache.get(key);
+    if (!cached) {
+      return false;
+    }
+    const age = Date.now() - cached.timestamp;
+    if (age >= this.ttl) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/errors.ts
+var ObjectStackError = class extends Error {
+  /**
+   * Create a new ObjectStackError
+   * 
+   * @param message - Human-readable error message
+   * @param code - Unique error code for programmatic handling
+   * @param statusCode - Optional HTTP status code
+   * @param details - Optional additional error details for debugging
+   */
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "ObjectStackError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Convert error to JSON for logging/debugging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    };
+  }
+};
+var MetadataNotFoundError = class extends ObjectStackError {
+  constructor(objectName, details) {
+    super(
+      `Metadata not found for object: ${objectName}`,
+      "METADATA_NOT_FOUND",
+      404,
+      { objectName, ...details }
+    );
+    this.name = "MetadataNotFoundError";
+  }
+};
+var BulkOperationError = class extends ObjectStackError {
+  /**
+   * Create a new BulkOperationError
+   * 
+   * @param operation - The bulk operation that failed (create, update, delete)
+   * @param successCount - Number of successful operations
+   * @param failureCount - Number of failed operations
+   * @param errors - Array of individual errors
+   * @param details - Additional error details
+   */
+  constructor(operation, successCount, failureCount, errors, details) {
+    super(
+      `Bulk ${operation} operation failed: ${successCount} succeeded, ${failureCount} failed`,
+      "BULK_OPERATION_ERROR",
+      500,
+      {
+        operation,
+        successCount,
+        failureCount,
+        errors,
+        ...details
+      }
+    );
+    this.successCount = successCount;
+    this.failureCount = failureCount;
+    this.errors = errors;
+    this.name = "BulkOperationError";
+  }
+  /**
+   * Get a summary of the bulk operation failure
+   */
+  getSummary() {
+    const total = this.successCount + this.failureCount;
+    const failureRate = total > 0 ? this.failureCount / total : 0;
+    return {
+      operation: this.details?.operation,
+      total,
+      successful: this.successCount,
+      failed: this.failureCount,
+      failureRate,
+      errors: this.errors
+    };
+  }
+};
+var ConnectionError = class extends ObjectStackError {
+  constructor(message, url, details, statusCode) {
+    super(
+      `Connection error: ${message}`,
+      "CONNECTION_ERROR",
+      statusCode || 503,
+      { url, ...details }
+    );
+    this.url = url;
+    this.name = "ConnectionError";
+  }
+};
+var AuthenticationError = class extends ObjectStackError {
+  constructor(message = "Authentication failed", details, statusCode) {
+    super(
+      message,
+      "AUTHENTICATION_ERROR",
+      statusCode || 401,
+      details
+    );
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends ObjectStackError {
+  /**
+   * Create a new ValidationError
+   * 
+   * @param message - Human-readable error message
+   * @param field - The field that failed validation (optional)
+   * @param validationErrors - Array of validation error details
+   * @param details - Additional error details
+   */
+  constructor(message, field, validationErrors, details) {
+    super(
+      message,
+      "VALIDATION_ERROR",
+      400,
+      {
+        field,
+        validationErrors,
+        ...details
+      }
+    );
+    this.field = field;
+    this.validationErrors = validationErrors;
+    this.name = "ValidationError";
+  }
+  /**
+   * Get all validation errors as a formatted list
+   */
+  getValidationErrors() {
+    return this.validationErrors || [];
+  }
+};
+function createErrorFromResponse(response, context) {
+  const status = response?.status || response?.statusCode || 500;
+  const message = response?.message || response?.statusText || "Unknown error";
+  const details = {
+    context,
+    response: {
+      status,
+      data: response?.data,
+      headers: response?.headers
+    }
+  };
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message, details, 401);
+    case 403:
+      return new AuthenticationError(message, details, 403);
+    case 404:
+      if (context?.includes("metadata") || context?.includes("schema") || context?.includes("getObjectSchema")) {
+        const objectName = extractObjectName(context);
+        return new MetadataNotFoundError(objectName, details);
+      }
+      return new ObjectStackError(message, "NOT_FOUND", 404, details);
+    case 400:
+      return new ValidationError(message, void 0, response?.data?.errors, details);
+    case 503:
+      return new ConnectionError(message, response?.config?.url, details, 503);
+    case 504:
+      return new ConnectionError(message, response?.config?.url, details, 504);
+    default:
+      return new ObjectStackError(message, "UNKNOWN_ERROR", status, details);
+  }
+}
+function extractObjectName(context) {
+  if (!context) return "unknown";
+  const match = context.match(/\(([^)]+)\)/);
+  return match ? match[1] : "unknown";
+}
+function isObjectStackError(error) {
+  return error instanceof ObjectStackError;
+}
+function isErrorType(error, errorClass) {
+  return error instanceof errorClass;
+}
+
+// src/index.ts
 var ObjectStackAdapter = class {
   constructor(config) {
     __publicField(this, "client");
     __publicField(this, "connected", false);
+    __publicField(this, "metadataCache");
+    __publicField(this, "connectionState", "disconnected");
+    __publicField(this, "connectionStateListeners", []);
+    __publicField(this, "batchProgressListeners", []);
+    __publicField(this, "autoReconnect");
+    __publicField(this, "maxReconnectAttempts");
+    __publicField(this, "reconnectDelay");
+    __publicField(this, "reconnectAttempts", 0);
+    __publicField(this, "baseUrl");
+    __publicField(this, "token");
     this.client = new import_client.ObjectStackClient(config);
+    this.metadataCache = new MetadataCache(config.cache);
+    this.autoReconnect = config.autoReconnect ?? true;
+    this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
+    this.reconnectDelay = config.reconnectDelay ?? 1e3;
+    this.baseUrl = config.baseUrl;
+    this.token = config.token;
   }
   /**
    * Ensure the client is connected to the server.
@@ -40,10 +393,105 @@ var ObjectStackAdapter = class {
    */
   async connect() {
     if (!this.connected) {
-      await this.client.connect();
-      this.connected = true;
+      this.setConnectionState("connecting");
+      try {
+        await this.client.connect();
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        this.setConnectionState("connected");
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Failed to connect to ObjectStack server";
+        const connectionError = new ConnectionError(
+          errorMessage,
+          void 0,
+          { originalError: error }
+        );
+        this.setConnectionState("error", connectionError);
+        if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+          await this.attemptReconnect();
+        } else {
+          throw connectionError;
+        }
+      }
     }
   }
+  /**
+   * Attempt to reconnect to the server with exponential backoff
+   */
+  async attemptReconnect() {
+    this.reconnectAttempts++;
+    this.setConnectionState("reconnecting");
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    this.connected = false;
+    await this.connect();
+  }
+  /**
+   * Get the current connection state
+   */
+  getConnectionState() {
+    return this.connectionState;
+  }
+  /**
+   * Check if the adapter is currently connected
+   */
+  isConnected() {
+    return this.connected && this.connectionState === "connected";
+  }
+  /**
+   * Register a listener for connection state changes
+   */
+  onConnectionStateChange(listener) {
+    this.connectionStateListeners.push(listener);
+    return () => {
+      const index = this.connectionStateListeners.indexOf(listener);
+      if (index > -1) {
+        this.connectionStateListeners.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Register a listener for batch operation progress
+   */
+  onBatchProgress(listener) {
+    this.batchProgressListeners.push(listener);
+    return () => {
+      const index = this.batchProgressListeners.indexOf(listener);
+      if (index > -1) {
+        this.batchProgressListeners.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Set connection state and notify listeners
+   */
+  setConnectionState(state, error) {
+    this.connectionState = state;
+    const event = {
+      state,
+      timestamp: Date.now(),
+      error
+    };
+    this.connectionStateListeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error("Error in connection state listener:", err);
+      }
+    });
+  }
+  /**
+   * Emit batch progress event to listeners
+   */
+  emitBatchProgress(event) {
+    this.batchProgressListeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error("Error in batch progress listener:", err);
+      }
+    });
+  }
   /**
    * Find multiple records with query parameters.
    * Converts OData-style params to ObjectStack query options.
@@ -52,12 +500,23 @@ var ObjectStackAdapter = class {
     await this.connect();
     const queryOptions = this.convertQueryParams(params);
     const result = await this.client.data.find(resource, queryOptions);
+    if (Array.isArray(result)) {
+      return {
+        data: result,
+        total: result.length,
+        page: 1,
+        pageSize: result.length,
+        hasMore: false
+      };
+    }
+    const resultObj = result;
     return {
-      data: result.value,
-      total: result.count,
-      page: params?.$skip ? Math.floor(params.$skip / (params.$top || 20)) + 1 : 1,
+      data: resultObj.value || [],
+      total: resultObj.count || (resultObj.value ? resultObj.value.length : 0),
+      // Calculate page number safely
+      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: result.value.length === params?.$top
+      hasMore: params?.$top ? (resultObj.value?.length || 0) === params.$top : false
     };
   }
   /**
@@ -66,8 +525,8 @@ var ObjectStackAdapter = class {
   async findOne(resource, id, _params) {
     await this.connect();
     try {
-      const record = await this.client.data.get(resource, String(id));
-      return record;
+      const result = await this.client.data.get(resource, String(id));
+      return result.record;
     } catch (error) {
       if (error?.status === 404) {
         return null;
@@ -80,14 +539,16 @@ var ObjectStackAdapter = class {
    */
   async create(resource, data) {
     await this.connect();
-    return this.client.data.create(resource, data);
+    const result = await this.client.data.create(resource, data);
+    return result.record;
   }
   /**
    * Update an existing record.
    */
   async update(resource, id, data) {
     await this.connect();
-    return this.client.data.update(resource, String(id), data);
+    const result = await this.client.data.update(resource, String(id), data);
+    return result.record;
   }
   /**
    * Delete a record.
@@ -95,31 +556,136 @@ var ObjectStackAdapter = class {
   async delete(resource, id) {
     await this.connect();
     const result = await this.client.data.delete(resource, String(id));
-    return result.success;
+    return result.deleted;
   }
   /**
-   * Bulk operations (optional implementation).
+   * Bulk operations with optimized batch processing and error handling.
+   * Emits progress events for tracking operation status.
+   * 
+   * @param resource - Resource name
+   * @param operation - Operation type (create, update, delete)
+   * @param data - Array of records to process
+   * @returns Promise resolving to array of results
    */
   async bulk(resource, operation, data) {
     await this.connect();
-    switch (operation) {
-      case "create":
-        return this.client.data.createMany(resource, data);
-      case "delete": {
-        const ids = data.map((item) => item.id).filter(Boolean);
-        await this.client.data.deleteMany(resource, ids);
-        return [];
-      }
-      case "update": {
-        const results = await Promise.all(
-          data.map(
-            (item) => this.client.data.update(resource, String(item.id), item)
-          )
-        );
-        return results;
+    if (!data || data.length === 0) {
+      return [];
+    }
+    const total = data.length;
+    let completed = 0;
+    let failed = 0;
+    const emitProgress = () => {
+      this.emitBatchProgress({
+        operation,
+        total,
+        completed,
+        failed,
+        percentage: total > 0 ? (completed + failed) / total * 100 : 0
+      });
+    };
+    try {
+      switch (operation) {
+        case "create": {
+          emitProgress();
+          const created = await this.client.data.createMany(resource, data);
+          completed = created.length;
+          failed = total - completed;
+          emitProgress();
+          return created;
+        }
+        case "delete": {
+          const ids = data.map((item) => item.id).filter(Boolean);
+          if (ids.length === 0) {
+            const errors = data.map((_, index) => ({
+              index,
+              error: `Missing ID for item at index ${index}`
+            }));
+            failed = data.length;
+            emitProgress();
+            throw new BulkOperationError("delete", 0, data.length, errors);
+          }
+          emitProgress();
+          await this.client.data.deleteMany(resource, ids);
+          completed = ids.length;
+          failed = total - completed;
+          emitProgress();
+          return [];
+        }
+        case "update": {
+          if (typeof this.client.data.updateMany === "function") {
+            try {
+              emitProgress();
+              const updateMany = this.client.data.updateMany;
+              const updated = await updateMany(resource, data);
+              completed = updated.length;
+              failed = total - completed;
+              emitProgress();
+              return updated;
+            } catch {
+            }
+          }
+          const results = [];
+          const errors = [];
+          for (let i = 0; i < data.length; i++) {
+            const item = data[i];
+            const id = item.id;
+            if (!id) {
+              errors.push({ index: i, error: "Missing ID" });
+              failed++;
+              emitProgress();
+              continue;
+            }
+            try {
+              const result = await this.client.data.update(resource, String(id), item);
+              results.push(result.record);
+              completed++;
+              emitProgress();
+            } catch (error) {
+              const errorMessage = error instanceof Error ? error.message : String(error);
+              errors.push({ index: i, error: errorMessage });
+              failed++;
+              emitProgress();
+            }
+          }
+          if (errors.length > 0) {
+            throw new BulkOperationError(
+              "update",
+              results.length,
+              errors.length,
+              errors,
+              { resource, totalRecords: data.length }
+            );
+          }
+          return results;
+        }
+        default:
+          throw new ObjectStackError(
+            `Unsupported bulk operation: ${operation}`,
+            "UNSUPPORTED_OPERATION",
+            400
+          );
       }
-      default:
-        throw new Error(`Unsupported bulk operation: ${operation}`);
+    } catch (error) {
+      emitProgress();
+      if (error instanceof BulkOperationError) {
+        throw error;
+      }
+      if (error instanceof ObjectStackError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errors = data.map((_, index) => ({
+        index,
+        error: errorMessage
+      }));
+      throw new BulkOperationError(
+        operation,
+        0,
+        data.length,
+        errors,
+        { resource, originalError: error }
+      );
     }
   }
   /**
@@ -133,13 +699,26 @@ var ObjectStackAdapter = class {
       options.select = params.$select;
     }
     if (params.$filter) {
-      options.filters = (0, import_core.convertFiltersToAST)(params.$filter);
+      if (Array.isArray(params.$filter)) {
+        options.filters = params.$filter;
+      } else {
+        options.filters = (0, import_core.convertFiltersToAST)(params.$filter);
+      }
     }
     if (params.$orderby) {
-      const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
-        return order === "desc" ? `-${field}` : field;
-      });
-      options.sort = sortArray;
+      if (Array.isArray(params.$orderby)) {
+        options.sort = params.$orderby.map((item) => {
+          if (typeof item === "string") return item;
+          const field = item.field;
+          const order = item.order || "asc";
+          return order === "desc" ? `-${field}` : field;
+        });
+      } else {
+        const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
+          return order === "desc" ? `-${field}` : field;
+        });
+        options.sort = sortArray;
+      }
     }
     if (params.$skip !== void 0) {
       options.skip = params.$skip;
@@ -151,6 +730,7 @@ var ObjectStackAdapter = class {
   }
   /**
    * Get object schema/metadata from ObjectStack.
+   * Uses caching to improve performance for repeated requests.
    * 
    * @param objectName - Object name
    * @returns Promise resolving to the object schema
@@ -158,11 +738,23 @@ var ObjectStackAdapter = class {
   async getObjectSchema(objectName) {
     await this.connect();
     try {
-      const schema = await this.client.meta.getObject(objectName);
+      const schema = await this.metadataCache.get(objectName, async () => {
+        const result = await this.client.meta.getObject(objectName);
+        if (result && result.item) {
+          return result.item;
+        }
+        return result;
+      });
       return schema;
     } catch (error) {
-      console.error(`Failed to fetch schema for ${objectName}:`, error);
-      throw error;
+      const errorObj = error;
+      if (errorObj?.status === 404 || errorObj?.statusCode === 404) {
+        throw new MetadataNotFoundError(objectName, { originalError: error });
+      }
+      if (error instanceof ObjectStackError) {
+        throw error;
+      }
+      throw createErrorFromResponse(errorObj, `getObjectSchema(${objectName})`);
     }
   }
   /**
@@ -171,12 +763,195 @@ var ObjectStackAdapter = class {
   getClient() {
     return this.client;
   }
+  /**
+   * Get the discovery information from the connected server.
+   * Returns the capabilities and service status of the ObjectStack server.
+   * 
+   * Note: This accesses an internal property of the ObjectStackClient.
+   * The discovery data is populated during client.connect() and cached.
+   * 
+   * @returns Promise resolving to discovery data, or null if not connected
+   */
+  async getDiscovery() {
+    try {
+      await this.connect();
+      return this.client.discoveryInfo || null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get a view definition for an object.
+   * Attempts to fetch from the server metadata API.
+   * Falls back to null if the server doesn't provide view definitions,
+   * allowing the consumer to use static config.
+   * 
+   * @param objectName - Object name
+   * @param viewId - View identifier
+   * @returns Promise resolving to the view definition or null
+   */
+  async getView(objectName, viewId) {
+    await this.connect();
+    try {
+      const cacheKey = `view:${objectName}:${viewId}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result = await this.client.meta.getItem(objectName, `views/${viewId}`);
+        if (result && result.item) return result.item;
+        return result ?? null;
+      });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get an application definition by name or ID.
+   * Attempts to fetch from the server metadata API.
+   * Falls back to null if the server doesn't provide app definitions,
+   * allowing the consumer to use static config.
+   * 
+   * @param appId - Application identifier
+   * @returns Promise resolving to the app definition or null
+   */
+  async getApp(appId) {
+    await this.connect();
+    try {
+      const cacheKey = `app:${appId}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result = await this.client.meta.getItem("apps", appId);
+        if (result && result.item) return result.item;
+        return result ?? null;
+      });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get cache statistics for monitoring performance.
+   */
+  getCacheStats() {
+    return this.metadataCache.getStats();
+  }
+  /**
+   * Invalidate metadata cache entries.
+   * 
+   * @param key - Optional key to invalidate. If omitted, invalidates all entries.
+   */
+  invalidateCache(key) {
+    this.metadataCache.invalidate(key);
+  }
+  /**
+   * Clear all cache entries and statistics.
+   */
+  clearCache() {
+    this.metadataCache.clear();
+  }
+  /**
+   * Upload a single file to a resource.
+   * Posts the file as multipart/form-data to the ObjectStack server.
+   *
+   * @param resource - The resource/object name to attach the file to
+   * @param file - File object or Blob to upload
+   * @param options - Additional upload options (recordId, fieldName, metadata)
+   * @returns Promise resolving to the upload result (file URL, metadata)
+   */
+  async uploadFile(resource, file, options) {
+    await this.connect();
+    const formData = new FormData();
+    formData.append("file", file);
+    if (options?.recordId) {
+      formData.append("recordId", options.recordId);
+    }
+    if (options?.fieldName) {
+      formData.append("fieldName", options.fieldName);
+    }
+    if (options?.metadata) {
+      formData.append("metadata", JSON.stringify(options.metadata));
+    }
+    const url = `${this.baseUrl}/api/data/${encodeURIComponent(resource)}/upload`;
+    const response = await fetch(url, {
+      method: "POST",
+      body: formData,
+      headers: {
+        ...this.getAuthHeaders()
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.message || `Upload failed with status ${response.status}`,
+        "UPLOAD_ERROR",
+        response.status
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Upload multiple files to a resource.
+   * Posts all files as a single multipart/form-data request.
+   *
+   * @param resource - The resource/object name to attach the files to
+   * @param files - Array of File objects or Blobs to upload
+   * @param options - Additional upload options
+   * @returns Promise resolving to array of upload results
+   */
+  async uploadFiles(resource, files, options) {
+    await this.connect();
+    const formData = new FormData();
+    files.forEach((file, idx) => {
+      formData.append(`files`, file, file.name || `file-${idx}`);
+    });
+    if (options?.recordId) {
+      formData.append("recordId", options.recordId);
+    }
+    if (options?.fieldName) {
+      formData.append("fieldName", options.fieldName);
+    }
+    if (options?.metadata) {
+      formData.append("metadata", JSON.stringify(options.metadata));
+    }
+    const url = `${this.baseUrl}/api/data/${encodeURIComponent(resource)}/upload`;
+    const response = await fetch(url, {
+      method: "POST",
+      body: formData,
+      headers: {
+        ...this.getAuthHeaders()
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.message || `Upload failed with status ${response.status}`,
+        "UPLOAD_ERROR",
+        response.status
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Get authorization headers from the adapter config.
+   */
+  getAuthHeaders() {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
 };
 function createObjectStackAdapter(config) {
   return new ObjectStackAdapter(config);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthenticationError,
+  BulkOperationError,
+  ConnectionError,
+  MetadataNotFoundError,
   ObjectStackAdapter,
-  createObjectStackAdapter
+  ObjectStackError,
+  ValidationError,
+  createErrorFromResponse,
+  createObjectStackAdapter,
+  isErrorType,
+  isObjectStackError
 });