@objectstack/client 1.0.4 → 1.0.5

package/dist/index.mjs

@@ -0,0 +1,684 @@
+// src/index.ts
+import { createLogger } from "@objectstack/core";
+
+// src/query-builder.ts
+var FilterBuilder = class {
+  constructor() {
+    this.conditions = [];
+  }
+  /**
+   * Equality filter: field = value
+   */
+  equals(field, value) {
+    this.conditions.push([field, "=", value]);
+    return this;
+  }
+  /**
+   * Not equals filter: field != value
+   */
+  notEquals(field, value) {
+    this.conditions.push([field, "!=", value]);
+    return this;
+  }
+  /**
+   * Greater than filter: field > value
+   */
+  greaterThan(field, value) {
+    this.conditions.push([field, ">", value]);
+    return this;
+  }
+  /**
+   * Greater than or equal filter: field >= value
+   */
+  greaterThanOrEqual(field, value) {
+    this.conditions.push([field, ">=", value]);
+    return this;
+  }
+  /**
+   * Less than filter: field < value
+   */
+  lessThan(field, value) {
+    this.conditions.push([field, "<", value]);
+    return this;
+  }
+  /**
+   * Less than or equal filter: field <= value
+   */
+  lessThanOrEqual(field, value) {
+    this.conditions.push([field, "<=", value]);
+    return this;
+  }
+  /**
+   * IN filter: field IN (value1, value2, ...)
+   */
+  in(field, values) {
+    this.conditions.push([field, "in", values]);
+    return this;
+  }
+  /**
+   * NOT IN filter: field NOT IN (value1, value2, ...)
+   */
+  notIn(field, values) {
+    this.conditions.push([field, "not_in", values]);
+    return this;
+  }
+  /**
+   * LIKE filter: field LIKE pattern
+   */
+  like(field, pattern) {
+    this.conditions.push([field, "like", pattern]);
+    return this;
+  }
+  /**
+   * IS NULL filter: field IS NULL
+   */
+  isNull(field) {
+    this.conditions.push([field, "is_null", null]);
+    return this;
+  }
+  /**
+   * IS NOT NULL filter: field IS NOT NULL
+   */
+  isNotNull(field) {
+    this.conditions.push([field, "is_not_null", null]);
+    return this;
+  }
+  /**
+   * Build the filter condition
+   */
+  build() {
+    if (this.conditions.length === 0) {
+      throw new Error("Filter builder has no conditions");
+    }
+    if (this.conditions.length === 1) {
+      return this.conditions[0];
+    }
+    return ["and", ...this.conditions];
+  }
+  /**
+   * Get raw conditions array
+   */
+  getConditions() {
+    return this.conditions;
+  }
+};
+var QueryBuilder = class {
+  constructor(object) {
+    this.query = {};
+    this._object = object;
+    this.query.object = object;
+  }
+  /**
+   * Select specific fields
+   */
+  select(...fields) {
+    this.query.fields = fields;
+    return this;
+  }
+  /**
+   * Add filters using a builder function
+   */
+  where(builderFn) {
+    const builder = new FilterBuilder();
+    builderFn(builder);
+    const conditions = builder.getConditions();
+    if (conditions.length === 1) {
+      this.query.where = conditions[0];
+    } else if (conditions.length > 1) {
+      this.query.where = ["and", ...conditions];
+    }
+    return this;
+  }
+  /**
+   * Add raw filter condition
+   */
+  filter(condition) {
+    this.query.where = condition;
+    return this;
+  }
+  /**
+   * Sort by fields
+   */
+  orderBy(field, order = "asc") {
+    if (!this.query.orderBy) {
+      this.query.orderBy = [];
+    }
+    this.query.orderBy.push({
+      field,
+      order
+    });
+    return this;
+  }
+  /**
+   * Limit the number of results
+   */
+  limit(count) {
+    this.query.limit = count;
+    return this;
+  }
+  /**
+   * Skip records (for pagination)
+   */
+  skip(count) {
+    this.query.offset = count;
+    return this;
+  }
+  /**
+   * Paginate results
+   */
+  paginate(page, pageSize) {
+    this.query.limit = pageSize;
+    this.query.offset = (page - 1) * pageSize;
+    return this;
+  }
+  /**
+   * Group by fields
+   */
+  groupBy(...fields) {
+    this.query.groupBy = fields;
+    return this;
+  }
+  /**
+   * Build the final query AST
+   */
+  build() {
+    return {
+      object: this._object,
+      ...this.query
+    };
+  }
+  /**
+   * Get the current query state
+   */
+  getQuery() {
+    return { ...this.query };
+  }
+};
+function createQuery(object) {
+  return new QueryBuilder(object);
+}
+function createFilter() {
+  return new FilterBuilder();
+}
+
+// src/index.ts
+var ObjectStackClient = class {
+  constructor(config) {
+    /**
+     * Metadata Operations
+     */
+    this.meta = {
+      /**
+       * Get all available metadata types
+       * Returns types like 'object', 'plugin', 'view', etc.
+       */
+      getTypes: async () => {
+        const route = this.getRoute("metadata");
+        const res = await this.fetch(`${this.baseUrl}${route}`);
+        return res.json();
+      },
+      /**
+       * Get all items of a specific metadata type
+       * @param type - Metadata type name (e.g., 'object', 'plugin')
+       */
+      getItems: async (type) => {
+        const route = this.getRoute("metadata");
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}`);
+        return res.json();
+      },
+      /**
+       * Get a specific object definition by name
+       * @deprecated Use `getItem('object', name)` instead for consistency with spec protocol
+       * @param name - Object name (snake_case identifier)
+       */
+      getObject: async (name) => {
+        const route = this.getRoute("metadata");
+        const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`);
+        return res.json();
+      },
+      /**
+       * Get a specific metadata item by type and name
+       * @param type - Metadata type (e.g., 'object', 'plugin')
+       * @param name - Item name (snake_case identifier)
+       */
+      getItem: async (type, name) => {
+        const route = this.getRoute("metadata");
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
+        return res.json();
+      },
+      /**
+       * Save a metadata item
+       * @param type - Metadata type (e.g., 'object', 'plugin')
+       * @param name - Item name
+       * @param item - The metadata content to save
+       */
+      saveItem: async (type, name, item) => {
+        const route = this.getRoute("metadata");
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`, {
+          method: "PUT",
+          body: JSON.stringify(item)
+        });
+        return res.json();
+      },
+      /**
+       * Get object metadata with cache support
+       * Supports ETag-based conditional requests for efficient caching
+       */
+      getCached: async (name, cacheOptions) => {
+        const route = this.getRoute("metadata");
+        const headers = {};
+        if (cacheOptions?.ifNoneMatch) {
+          headers["If-None-Match"] = cacheOptions.ifNoneMatch;
+        }
+        if (cacheOptions?.ifModifiedSince) {
+          headers["If-Modified-Since"] = cacheOptions.ifModifiedSince;
+        }
+        const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`, {
+          headers
+        });
+        if (res.status === 304) {
+          return {
+            notModified: true,
+            etag: cacheOptions?.ifNoneMatch ? {
+              value: cacheOptions.ifNoneMatch.replace(/^W\/|"/g, ""),
+              weak: cacheOptions.ifNoneMatch.startsWith("W/")
+            } : void 0
+          };
+        }
+        const data = await res.json();
+        const etag = res.headers.get("ETag");
+        const lastModified = res.headers.get("Last-Modified");
+        return {
+          data,
+          etag: etag ? {
+            value: etag.replace(/^W\/|"/g, ""),
+            weak: etag.startsWith("W/")
+          } : void 0,
+          lastModified: lastModified || void 0,
+          notModified: false
+        };
+      },
+      getView: async (object, type = "list") => {
+        const route = this.getRoute("ui");
+        const res = await this.fetch(`${this.baseUrl}${route}/view/${object}?type=${type}`);
+        return res.json();
+      }
+    };
+    /**
+     * Analytics Services
+     */
+    this.analytics = {
+      query: async (payload) => {
+        const route = this.getRoute("analytics");
+        const res = await this.fetch(`${this.baseUrl}${route}/query`, {
+          method: "POST",
+          body: JSON.stringify(payload)
+        });
+        return res.json();
+      },
+      meta: async (cube) => {
+        const route = this.getRoute("analytics");
+        const res = await this.fetch(`${this.baseUrl}${route}/meta/${cube}`);
+        return res.json();
+      },
+      explain: async (payload) => {
+        const route = this.getRoute("analytics");
+        const res = await this.fetch(`${this.baseUrl}${route}/explain`, {
+          method: "POST",
+          body: JSON.stringify(payload)
+        });
+        return res.json();
+      }
+    };
+    /**
+     * Hub Management Services
+     */
+    this.hub = {
+      spaces: {
+        list: async () => {
+          const route = this.getRoute("hub");
+          const res = await this.fetch(`${this.baseUrl}${route}/spaces`);
+          return res.json();
+        },
+        create: async (payload) => {
+          const route = this.getRoute("hub");
+          const res = await this.fetch(`${this.baseUrl}${route}/spaces`, {
+            method: "POST",
+            body: JSON.stringify(payload)
+          });
+          return res.json();
+        }
+      },
+      plugins: {
+        install: async (pkg, version) => {
+          const route = this.getRoute("hub");
+          const res = await this.fetch(`${this.baseUrl}${route}/plugins/install`, {
+            method: "POST",
+            body: JSON.stringify({ pkg, version })
+          });
+          return res.json();
+        }
+      }
+    };
+    /**
+     * Authentication Services
+     */
+    this.auth = {
+      login: async (request) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/login`, {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        const data = await res.json();
+        if (data.data?.token) {
+          this.token = data.data.token;
+        }
+        return data;
+      },
+      logout: async () => {
+        const route = this.getRoute("auth");
+        await this.fetch(`${this.baseUrl}${route}/logout`, { method: "POST" });
+        this.token = void 0;
+      },
+      me: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/me`);
+        return res.json();
+      }
+    };
+    /**
+     * Storage Services
+     */
+    this.storage = {
+      upload: async (file, scope = "user") => {
+        const presignedReq = {
+          filename: file.name,
+          mimeType: file.type,
+          size: file.size,
+          scope
+        };
+        const route = this.getRoute("storage");
+        const presignedRes = await this.fetch(`${this.baseUrl}${route}/upload/presigned`, {
+          method: "POST",
+          body: JSON.stringify(presignedReq)
+        });
+        const { data: presigned } = await presignedRes.json();
+        const uploadRes = await this.fetchImpl(presigned.uploadUrl, {
+          method: presigned.method,
+          headers: presigned.headers,
+          body: file
+        });
+        if (!uploadRes.ok) {
+          throw new Error(`Storage Upload Failed: ${uploadRes.statusText}`);
+        }
+        const completeReq = {
+          fileId: presigned.fileId
+        };
+        const completeRes = await this.fetch(`${this.baseUrl}${route}/upload/complete`, {
+          method: "POST",
+          body: JSON.stringify(completeReq)
+        });
+        return completeRes.json();
+      },
+      getDownloadUrl: async (fileId) => {
+        const route = this.getRoute("storage");
+        const res = await this.fetch(`${this.baseUrl}${route}/files/${fileId}/url`);
+        const data = await res.json();
+        return data.url;
+      }
+    };
+    /**
+     * Automation Services
+     */
+    this.automation = {
+      trigger: async (triggerName, payload) => {
+        const route = this.getRoute("automation");
+        const res = await this.fetch(`${this.baseUrl}${route}/trigger/${triggerName}`, {
+          method: "POST",
+          body: JSON.stringify(payload)
+        });
+        return res.json();
+      }
+    };
+    /**
+     * Data Operations
+     */
+    this.data = {
+      /**
+       * Advanced Query using ObjectStack Query Protocol
+       * Supports both simplified options and full AST
+       */
+      query: async (object, query) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/query`, {
+          method: "POST",
+          body: JSON.stringify(query)
+        });
+        return res.json();
+      },
+      find: async (object, options = {}) => {
+        const route = this.getRoute("data");
+        const queryParams = new URLSearchParams();
+        if (options.top) queryParams.set("top", options.top.toString());
+        if (options.skip) queryParams.set("skip", options.skip.toString());
+        if (options.sort) {
+          if (Array.isArray(options.sort) && typeof options.sort[0] === "object") {
+            queryParams.set("sort", JSON.stringify(options.sort));
+          } else {
+            const sortVal = Array.isArray(options.sort) ? options.sort.join(",") : options.sort;
+            queryParams.set("sort", sortVal);
+          }
+        }
+        if (options.select) {
+          queryParams.set("select", options.select.join(","));
+        }
+        if (options.filters) {
+          if (this.isFilterAST(options.filters)) {
+            queryParams.set("filters", JSON.stringify(options.filters));
+          } else {
+            Object.entries(options.filters).forEach(([k, v]) => {
+              if (v !== void 0 && v !== null) {
+                queryParams.append(k, String(v));
+              }
+            });
+          }
+        }
+        if (options.aggregations) {
+          queryParams.set("aggregations", JSON.stringify(options.aggregations));
+        }
+        if (options.groupBy) {
+          queryParams.set("groupBy", options.groupBy.join(","));
+        }
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}?${queryParams.toString()}`);
+        return res.json();
+      },
+      get: async (object, id) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`);
+        return res.json();
+      },
+      create: async (object, data) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}`, {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+        return res.json();
+      },
+      createMany: async (object, data) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/createMany`, {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+        return res.json();
+      },
+      update: async (object, id, data) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
+          method: "PATCH",
+          body: JSON.stringify(data)
+        });
+        return res.json();
+      },
+      /**
+       * Batch update multiple records
+       * Uses the new BatchUpdateRequest schema with full control over options
+       */
+      batch: async (object, request) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/batch`, {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return res.json();
+      },
+      /**
+       * Update multiple records (simplified batch update)
+       * Convenience method for batch updates without full BatchUpdateRequest
+       */
+      updateMany: async (object, records, options) => {
+        const route = this.getRoute("data");
+        const request = {
+          records,
+          options
+        };
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/updateMany`, {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return res.json();
+      },
+      delete: async (object, id) => {
+        const route = this.getRoute("data");
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
+          method: "DELETE"
+        });
+        return res.json();
+      },
+      /**
+       * Delete multiple records by IDs
+       */
+      deleteMany: async (object, ids, options) => {
+        const route = this.getRoute("data");
+        const request = {
+          ids,
+          options
+        };
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/deleteMany`, {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return res.json();
+      }
+    };
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.token = config.token;
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
+    this.logger = config.logger || createLogger({
+      level: config.debug ? "debug" : "info",
+      format: "pretty"
+    });
+    this.logger.debug("ObjectStack client created", { baseUrl: this.baseUrl });
+  }
+  /**
+   * Initialize the client by discovering server capabilities.
+   */
+  async connect() {
+    this.logger.debug("Connecting to ObjectStack server", { baseUrl: this.baseUrl });
+    try {
+      const res = await this.fetch(`${this.baseUrl}/api/v1`);
+      const data = await res.json();
+      this.discoveryInfo = data;
+      this.logger.info("Connected to ObjectStack server", {
+        version: data.version,
+        apiName: data.apiName,
+        capabilities: data.capabilities
+      });
+      return data;
+    } catch (e) {
+      this.logger.error("Failed to connect to ObjectStack server", e, { baseUrl: this.baseUrl });
+      throw e;
+    }
+  }
+  /**
+   * Private Helpers
+   */
+  isFilterAST(filter) {
+    return Array.isArray(filter);
+  }
+  async fetch(url, options = {}) {
+    this.logger.debug("HTTP request", {
+      method: options.method || "GET",
+      url,
+      hasBody: !!options.body
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers || {}
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, { ...options, headers });
+    this.logger.debug("HTTP response", {
+      method: options.method || "GET",
+      url,
+      status: res.status,
+      ok: res.ok
+    });
+    if (!res.ok) {
+      let errorBody;
+      try {
+        errorBody = await res.json();
+      } catch {
+        errorBody = { message: res.statusText };
+      }
+      this.logger.error("HTTP request failed", void 0, {
+        method: options.method || "GET",
+        url,
+        status: res.status,
+        error: errorBody
+      });
+      const errorMessage = errorBody?.message || errorBody?.error?.message || res.statusText;
+      const errorCode = errorBody?.code || errorBody?.error?.code;
+      const error = new Error(`[ObjectStack] ${errorCode ? `${errorCode}: ` : ""}${errorMessage}`);
+      error.code = errorCode;
+      error.category = errorBody?.category;
+      error.httpStatus = res.status;
+      error.retryable = errorBody?.retryable;
+      error.details = errorBody?.details || errorBody;
+      throw error;
+    }
+    return res;
+  }
+  /**
+   * Get the conventional route path for a given API endpoint type
+   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/metadata, /api/v1/ui
+   */
+  getRoute(type) {
+    if (this.discoveryInfo?.endpoints && this.discoveryInfo.endpoints[type]) {
+      return this.discoveryInfo.endpoints[type];
+    }
+    const routeMap = {
+      data: "/api/v1/data",
+      metadata: "/api/v1/metadata",
+      ui: "/api/v1/ui",
+      auth: "/api/v1/auth",
+      analytics: "/api/v1/analytics",
+      hub: "/api/v1/hub",
+      storage: "/api/v1/storage",
+      automation: "/api/v1/automation"
+    };
+    return routeMap[type] || `/api/v1/${type}`;
+  }
+};
+export {
+  FilterBuilder,
+  ObjectStackClient,
+  QueryBuilder,
+  createFilter,
+  createQuery
+};
+//# sourceMappingURL=index.mjs.map