@bluecopa/core 0.1.58 → 0.1.59

package/README.md

@@ -24,6 +24,7 @@ The core package provides essential API utilities and functions for data managem
     - [Quick Start](#quick-start)
     - [CRUD](#crud)
     - [Query Operators](#query-operators)
+    - [Aggregate Queries](#aggregate-queries)
     - [Framework Integration](#framework-integration)
     - [WebSocket Provider (optional)](#websocket-provider-optional)
     - [Cleanup](#cleanup)
@@ -248,6 +249,70 @@ const unsub = copaInputTableDb.collection("invoices").count((n) => console.log(n
 | `in`      | in array        |
 | `not-in`  | not in array    |
 
+### Aggregate Queries
+
+Compute server-side aggregates (`sum`, `avg`, `count`, `min`, `max`) without fetching all rows. Combines with `where()`, `limit()`, and `skip()` filters.
+
+```typescript
+// Column aggregates
+const result = await copaInputTableDb
+  .collection("invoices")
+  .where("status", "==", "active")
+  .aggregate({ amount: ["sum", "avg"], price: ["min", "max"] });
+// => { amount: { sum: 1234.56, avg: 123.45 }, price: { min: 10, max: 999 } }
+
+// Row count
+const result = await copaInputTableDb
+  .collection("invoices")
+  .aggregate({ _count: true });
+// => { _count: 42 }
+
+// Column count (non-null values) + row count
+const result = await copaInputTableDb
+  .collection("invoices")
+  .aggregate({ name: ["count"], _count: true });
+// => { name: { count: 38 }, _count: 42 }
+```
+
+`.aggregate()` is a **terminal method** — it bypasses local RxDB and hits PostgREST directly. Errors throw `InputTableError`. An empty spec `{}` returns `{}` without calling the API.
+
+### Grouped Aggregates
+
+Add a `{ groupBy: [...columns] }` second argument to get per-group breakdowns. Returns an array instead of a single object.
+
+```typescript
+// Sum per status group
+const rows = await copaInputTableDb
+  .collection("invoices")
+  .aggregate({ amount: ["sum"] }, { groupBy: ["status"] });
+// => [{ status: "active", amount: { sum: 1234 } }, { status: "draft", amount: { sum: 100 } }]
+
+// Multi-column groupBy with filters and ordering
+const rows = await copaInputTableDb
+  .collection("invoices")
+  .where("year", "==", 2024)
+  .orderBy("order_date", "asc")
+  .aggregate({ amount: ["sum", "avg"] }, { groupBy: ["order_date", "status"] });
+
+// Count per group
+const rows = await copaInputTableDb
+  .collection("invoices")
+  .aggregate({ _count: true }, { groupBy: ["status"] });
+// => [{ status: "active", _count: 10 }, { status: "draft", _count: 4 }]
+
+// Distinct values (no aggregate functions)
+const rows = await copaInputTableDb
+  .collection("invoices")
+  .aggregate({}, { groupBy: ["status"] });
+// => [{ status: "active" }, { status: "draft" }]
+```
+
+**Notes:**
+- `orderBy()` is forwarded to PostgREST when `groupBy` is present (ignored otherwise)
+- `limit()`/`skip()` apply to the number of _groups_, not input rows
+- A column cannot appear in both the aggregate spec and `groupBy` — throws `InputTableError`
+- Empty `groupBy: []` behaves like no groupBy — returns a single object
+
 ### Framework Integration
 
 **Svelte 5**

package/dist/config.d.ts

@@ -6,6 +6,8 @@ export interface Config {
     workspaceId: string;
     userId: string;
     solutionId?: string;
+    solutionBranch?: string;
+    solutionBranchType?: string;
     websocketProvider?: IWebsocketProvider;
 }
 declare class ConfigSingleton {

package/dist/index.es.js

@@ -37,6 +37,8 @@ class ConfigSingleton {
       workspaceId: "",
       userId: "",
       solutionId: void 0,
+      solutionBranch: void 0,
+      solutionBranchType: void 0,
       websocketProvider: void 0
     };
   }
@@ -54,6 +56,22 @@ const createApiClient = () => {
     // Increased to 120 seconds for audit log queries
     headers: {
       "Content-Type": "application/json"
+    },
+    // PostgREST requires repeated params for multi-value filters: amount=gt.10&amount=lt.100
+    // Axios's default qs serializer uses indices format (amount[0]=gt.10) which PostgREST
+    // does not understand. This custom serializer produces the correct repeated-param format.
+    paramsSerializer: (params) => {
+      const parts = [];
+      for (const [key, value] of Object.entries(params)) {
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+          }
+        } else if (value !== null && value !== void 0) {
+          parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+      }
+      return parts.join("&");
     }
   });
   client.interceptors.request.use(
@@ -71,11 +89,6 @@ const createApiClient = () => {
       if (copaConfig.solutionId && config.headers) {
         config.headers["x-bluecopa-solution-id"] = copaConfig.solutionId;
       }
-      console.log("API Request Config:", {
-        baseURL: config.baseURL,
-        hasToken: !!copaConfig.accessToken,
-        hasWorkspaceId: !!copaConfig.workspaceId
-      });
       return config;
     },
     (error) => {
@@ -12260,6 +12273,75 @@ var InputTableColumnType = /* @__PURE__ */ ((InputTableColumnType2) => {
   InputTableColumnType2["JSONB"] = "jsonb";
   return InputTableColumnType2;
 })(InputTableColumnType || {});
+const IDENTIFIER_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const SOLUTION_BRANCH_COOKIE_NAME = "x-bluecopa-solution-branch";
+const SOLUTION_BRANCH_TYPE_COOKIE_NAME = "x-bluecopa-solution-branch-type";
+function readCookie(name) {
+  try {
+    const cookie = document.cookie.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${name}=`));
+    return cookie ? decodeURIComponent(cookie.split("=").slice(1).join("=")) : null;
+  } catch {
+    return null;
+  }
+}
+function getSolutionBranchHeaders() {
+  const config = getConfig();
+  const branch = config.solutionBranch ?? readCookie(SOLUTION_BRANCH_COOKIE_NAME);
+  const branchType = config.solutionBranchType ?? readCookie(SOLUTION_BRANCH_TYPE_COOKIE_NAME);
+  const headers = {};
+  if (branch) headers["x-bluecopa-solution-branch"] = branch;
+  if (branchType) headers["x-bluecopa-solution-branch-type"] = branchType;
+  return headers;
+}
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+class InputTableError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "InputTableError";
+  }
+}
+function validateIdentifier(value, label) {
+  const trimmed = value.trim();
+  if (!trimmed || !IDENTIFIER_PATTERN.test(trimmed)) {
+    throw new InputTableError(`Invalid ${label}: "${value}"`, 400);
+  }
+  return trimmed;
+}
+function validateCheckpointTimestamp(value) {
+  if (!ISO_TIMESTAMP_PATTERN.test(value)) {
+    throw new InputTableError(`Invalid checkpoint timestamp: "${value}"`, 400);
+  }
+  return value;
+}
+function validateCheckpointId(value) {
+  return validateIdentifier(value, "checkpoint id");
+}
+function stripNullsAndCoercePk(row, primaryKeyField) {
+  const doc = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (value === null) continue;
+    doc[key] = value;
+  }
+  doc[primaryKeyField] = String(row[primaryKeyField]);
+  return doc;
+}
+function deferSubscription(resolve, callback, fallback) {
+  let innerUnsub = null;
+  let cancelled = false;
+  resolve().then((subscribeFn) => {
+    if (!cancelled) {
+      innerUnsub = subscribeFn(callback);
+    }
+  }).catch((err) => {
+    console.error("[copaInputTableDb]", err);
+    if (!cancelled) callback(fallback);
+  });
+  return () => {
+    cancelled = true;
+    innerUnsub == null ? void 0 : innerUnsub();
+  };
+}
 const OP_MAP = {
   "==": "$eq",
   "!=": "$ne",
@@ -12271,8 +12353,9 @@ const OP_MAP = {
   "not-in": "$nin"
 };
 class QueryBuilderImpl {
-  constructor(collection, initialWhere, initialOrder, initialLimit, initialSkip) {
+  constructor(collection, initialWhere, initialOrder, initialLimit, initialSkip, aggregateExecutor) {
     this.collection = collection;
+    this.aggregateExecutor = aggregateExecutor;
     this.wheres = [];
     this.orders = [];
     if (initialWhere) this.wheres.push(initialWhere);
@@ -12308,6 +12391,22 @@ class QueryBuilderImpl {
     const docs = await query.exec();
     return docs.map((d) => d.toJSON());
   }
+  async aggregate(spec, options) {
+    if (!this.aggregateExecutor) {
+      throw new InputTableError(
+        "[copaInputTableDb] aggregate() is not available on this QueryBuilder instance",
+        500
+      );
+    }
+    return this.aggregateExecutor(
+      this.wheres,
+      this.orders,
+      this.limitCount,
+      this.skipCount,
+      spec,
+      options == null ? void 0 : options.groupBy
+    );
+  }
   buildQuery() {
     const selector = {};
     for (const { field, op, value } of this.wheres) {
@@ -12333,56 +12432,6 @@ const MAX_COLLECTIONS = 14;
 const REPLICATION_RETRY_TIME = 5e3;
 const PULL_BATCH_SIZE = 100;
 const PUSH_BATCH_SIZE = 10;
-const IDENTIFIER_PATTERN = /^[a-zA-Z0-9_-]+$/;
-const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
-class InputTableError extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "InputTableError";
-  }
-}
-function validateIdentifier(value, label) {
-  const trimmed = value.trim();
-  if (!trimmed || !IDENTIFIER_PATTERN.test(trimmed)) {
-    throw new InputTableError(`Invalid ${label}: "${value}"`, 400);
-  }
-  return trimmed;
-}
-function validateCheckpointTimestamp(value) {
-  if (!ISO_TIMESTAMP_PATTERN.test(value)) {
-    throw new InputTableError(`Invalid checkpoint timestamp: "${value}"`, 400);
-  }
-  return value;
-}
-function validateCheckpointId(value) {
-  return validateIdentifier(value, "checkpoint id");
-}
-function stripNullsAndCoercePk(row, primaryKeyField) {
-  const doc = {};
-  for (const [key, value] of Object.entries(row)) {
-    if (value === null) continue;
-    doc[key] = value;
-  }
-  doc[primaryKeyField] = String(row[primaryKeyField]);
-  return doc;
-}
-function deferSubscription(resolve, callback, fallback) {
-  let innerUnsub = null;
-  let cancelled = false;
-  resolve().then((subscribeFn) => {
-    if (!cancelled) {
-      innerUnsub = subscribeFn(callback);
-    }
-  }).catch((err) => {
-    console.error("[copaInputTableDb]", err);
-    if (!cancelled) callback(fallback);
-  });
-  return () => {
-    cancelled = true;
-    innerUnsub == null ? void 0 : innerUnsub();
-  };
-}
 class DocRefImpl {
   constructor(collection, id, solutionId, tableName, primaryKeyField, websocketProvider) {
     this.collection = collection;
@@ -12422,6 +12471,168 @@ class DocRefImpl {
     return () => rxSub.unsubscribe();
   }
 }
+const POSTGREST_OP_MAP = {
+  "==": "eq",
+  "!=": "neq",
+  "<": "lt",
+  "<=": "lte",
+  ">": "gt",
+  ">=": "gte",
+  in: "in",
+  "not-in": "not.in"
+};
+const VALID_AGGREGATE_FUNCTIONS = /* @__PURE__ */ new Set([
+  "sum",
+  "avg",
+  "count",
+  "min",
+  "max"
+]);
+function validateAggregateSpec(spec) {
+  for (const [key, value] of Object.entries(spec)) {
+    if (key === "_count") {
+      if (value !== true) {
+        throw new InputTableError(
+          `"_count" must be exactly \`true\`, got: ${JSON.stringify(value)}`,
+          400
+        );
+      }
+      continue;
+    }
+    validateIdentifier(key, `aggregate column "${key}"`);
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new InputTableError(
+        `Aggregate spec column "${key}" must have a non-empty array of functions`,
+        400
+      );
+    }
+    for (const fn of value) {
+      if (!VALID_AGGREGATE_FUNCTIONS.has(fn)) {
+        throw new InputTableError(
+          `Unknown aggregate function "${fn}" for column "${key}". Allowed: sum, avg, count, min, max`,
+          400
+        );
+      }
+    }
+  }
+}
+function validateGroupBySpec(groupBy, spec) {
+  const specKeys = new Set(Object.keys(spec).filter((k) => k !== "_count"));
+  if (specKeys.size === 0 && !spec._count) {
+    throw new InputTableError(
+      "groupBy requires at least one aggregate function or `_count: true` in the spec",
+      400
+    );
+  }
+  for (const col of groupBy) {
+    validateIdentifier(col, `groupBy column "${col}"`);
+    if (specKeys.has(col)) {
+      throw new InputTableError(
+        `groupBy column "${col}" overlaps with aggregate spec key. Use a different column name or separate the queries.`,
+        400
+      );
+    }
+  }
+}
+function buildAggregateSelect(spec, groupBy) {
+  const parts = [];
+  if (groupBy && groupBy.length > 0) {
+    for (const col of groupBy) {
+      parts.push(col);
+    }
+  }
+  for (const [key, value] of Object.entries(spec)) {
+    if (key === "_count") continue;
+    for (const fn of value) {
+      parts.push(`${key}_${fn}:${key}.${fn}()`);
+    }
+  }
+  if (spec._count) {
+    parts.push("count()");
+  }
+  return parts.join(",");
+}
+function buildPostgrestOrder(orders) {
+  for (const { field } of orders) {
+    validateIdentifier(field, `order field "${field}"`);
+  }
+  return orders.map(({ field, direction }) => `${field}.${direction}`).join(",");
+}
+const RESERVED_PARAMS = /* @__PURE__ */ new Set(["select", "order", "limit", "offset", "on_conflict", "columns", "and", "or", "not"]);
+function buildPostgrestFilters(wheres) {
+  const params = {};
+  for (const { field, op, value } of wheres) {
+    validateIdentifier(field, `where field "${field}"`);
+    if (RESERVED_PARAMS.has(field)) {
+      throw new InputTableError(
+        `Cannot filter on reserved PostgREST param name "${field}"`,
+        400
+      );
+    }
+    const pgOp = POSTGREST_OP_MAP[op];
+    let filterStr;
+    if (op === "in" || op === "not-in") {
+      const arr = Array.isArray(value) ? value : [value];
+      filterStr = `${pgOp}.(${arr.map(quotePostgrestValue).join(",")})`;
+    } else {
+      filterStr = `${pgOp}.${quotePostgrestValue(value)}`;
+    }
+    const existing = params[field];
+    if (existing === void 0) {
+      params[field] = filterStr;
+    } else if (Array.isArray(existing)) {
+      existing.push(filterStr);
+    } else {
+      params[field] = [existing, filterStr];
+    }
+  }
+  return params;
+}
+function quotePostgrestValue(value) {
+  if (value === null || value === void 0) {
+    throw new InputTableError("Filter value must not be null or undefined", 400);
+  }
+  if (typeof value === "object") {
+    throw new InputTableError(
+      `Filter value must be a primitive, got: ${Array.isArray(value) ? "array" : "object"}`,
+      400
+    );
+  }
+  const str = String(value);
+  if (/[,.:()\\"']/.test(str)) {
+    const escaped = str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `"${escaped}"`;
+  }
+  return str;
+}
+function parseRowAggregates(spec, row) {
+  const result = {};
+  for (const [key, value] of Object.entries(spec)) {
+    if (key === "_count") continue;
+    const nested = {};
+    for (const fn of value) {
+      const alias = `${key}_${fn}`;
+      nested[fn] = alias in row ? row[alias] : null;
+    }
+    result[key] = nested;
+  }
+  if (spec._count) {
+    result["_count"] = row["count"] ?? 0;
+  }
+  return result;
+}
+function parseAggregateResponse(spec, data) {
+  return parseRowAggregates(spec, data[0] ?? {});
+}
+function parseGroupedAggregateResponse(spec, groupBy, data) {
+  return data.map((row) => {
+    const result = parseRowAggregates(spec, row);
+    for (const col of groupBy) {
+      result[col] = row[col];
+    }
+    return result;
+  });
+}
 class CollectionRefImpl {
   constructor(collection, solutionId, tableName, primaryKeyField, pkColumn, replicationState, getWebsocketProvider) {
     this.collection = collection;
@@ -12432,17 +12643,27 @@ class CollectionRefImpl {
     this.replicationState = replicationState;
     this.getWebsocketProvider = getWebsocketProvider;
   }
+  makeQueryBuilder(initialWhere, initialOrder, initialLimit, initialSkip) {
+    return new QueryBuilderImpl(
+      this.collection,
+      initialWhere,
+      initialOrder,
+      initialLimit,
+      initialSkip,
+      (wheres, orders, limit, skip, spec, groupBy) => this.executeAggregate(wheres, orders, limit, skip, spec, groupBy)
+    );
+  }
   where(field, op, value) {
-    return new QueryBuilderImpl(this.collection, { field, op, value });
+    return this.makeQueryBuilder({ field, op, value });
   }
   orderBy(field, direction = "asc") {
-    return new QueryBuilderImpl(this.collection, void 0, { field, direction });
+    return this.makeQueryBuilder(void 0, { field, direction });
   }
   limit(count) {
-    return new QueryBuilderImpl(this.collection, void 0, void 0, count);
+    return this.makeQueryBuilder(void 0, void 0, count);
   }
   skip(count) {
-    return new QueryBuilderImpl(this.collection, void 0, void 0, void 0, count);
+    return this.makeQueryBuilder(void 0, void 0, void 0, count);
   }
   doc(id) {
     return new DocRefImpl(
@@ -12498,6 +12719,58 @@ class CollectionRefImpl {
     });
     return () => rxSub.unsubscribe();
   }
+  async aggregate(spec, options) {
+    return this.executeAggregate([], [], void 0, void 0, spec, options == null ? void 0 : options.groupBy);
+  }
+  async executeAggregate(wheres, orders, limit, skip, spec, groupBy) {
+    var _a, _b, _c;
+    validateAggregateSpec(spec);
+    const activeGroupBy = groupBy && groupBy.length > 0 ? groupBy : void 0;
+    if (activeGroupBy) {
+      validateGroupBySpec(activeGroupBy, spec);
+    }
+    const selectParam = buildAggregateSelect(spec, activeGroupBy);
+    if (!selectParam) {
+      return activeGroupBy ? [] : {};
+    }
+    const filterParams = buildPostgrestFilters(wheres);
+    const params = {
+      select: selectParam,
+      ...filterParams
+    };
+    if (limit !== void 0) params["limit"] = limit;
+    if (skip !== void 0) params["offset"] = skip;
+    if (activeGroupBy && orders.length > 0) {
+      const groupBySet = new Set(activeGroupBy);
+      for (const { field } of orders) {
+        if (!groupBySet.has(field)) {
+          throw new InputTableError(
+            `orderBy field "${field}" must be one of the groupBy columns: [${activeGroupBy.join(", ")}]`,
+            400
+          );
+        }
+      }
+      params["order"] = buildPostgrestOrder(orders);
+    }
+    let response;
+    try {
+      response = await apiClient.get(
+        `/input-table-v2/${this.solutionId}/rows/${this.tableName}`,
+        { params, headers: getSolutionBranchHeaders() }
+      );
+    } catch (err) {
+      const axiosErr = err;
+      throw new InputTableError(
+        ((_b = (_a = axiosErr.response) == null ? void 0 : _a.data) == null ? void 0 : _b.message) ?? axiosErr.message ?? "Aggregate query failed",
+        ((_c = axiosErr.response) == null ? void 0 : _c.status) ?? 500
+      );
+    }
+    const data = Array.isArray(response.data) ? response.data : [response.data];
+    if (activeGroupBy) {
+      return parseGroupedAggregateResponse(spec, activeGroupBy, data);
+    }
+    return parseAggregateResponse(spec, data);
+  }
 }
 let dbPromise = null;
 function getInputTableDatabase() {
@@ -12850,18 +13123,22 @@ async function evictLeastRecentlyUsed() {
   }
 }
 const SOLUTION_COOKIE_NAME = "x-bluecopa-solution-id";
+function getCookieValue(name) {
+  try {
+    const cookie = document.cookie.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${name}=`));
+    return cookie ? decodeURIComponent(cookie.split("=").slice(1).join("=")) : null;
+  } catch {
+    return null;
+  }
+}
 function getSolutionId() {
   const config = getConfig();
   if (config.solutionId) {
     return validateIdentifier(config.solutionId, "solutionId");
   }
-  try {
-    const cookie = document.cookie.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${SOLUTION_COOKIE_NAME}=`));
-    if (cookie) {
-      const value = decodeURIComponent(cookie.split("=").slice(1).join("="));
-      return validateIdentifier(value, "solutionId (cookie)");
-    }
-  } catch {
+  const cookieValue = getCookieValue(SOLUTION_COOKIE_NAME);
+  if (cookieValue) {
+    return validateIdentifier(cookieValue, "solutionId (cookie)");
   }
   throw new InputTableError(
     "[copaInputTableDb] No solutionId configured. Set via copaSetConfig({ solutionId }) or cookie.",
@@ -12933,7 +13210,8 @@ const _InputTableDBImpl = class _InputTableDBImpl {
     if (this.schemaPending.has(solutionId)) {
       return this.schemaPending.get(solutionId);
     }
-    const pending = apiClient.get(`/input-table-v2/${solutionId}/tables`).then((res) => {
+    const headers = getSolutionBranchHeaders();
+    const pending = apiClient.get(`/input-table-v2/${solutionId}/tables`, { headers }).then((res) => {
       const tables = res.data ?? [];
       this.schemaCache.set(solutionId, { tables, fetchedAt: Date.now() });
       this.schemaPending.delete(solutionId);
@@ -13013,6 +13291,13 @@ class LazyCollectionRef {
       0
     );
   }
+  async aggregate(spec, options) {
+    const ref = await this.getRef();
+    if (options) {
+      return ref.aggregate(spec, options);
+    }
+    return ref.aggregate(spec);
+  }
 }
 class LazyQueryBuilder {
   constructor(resolveBase) {
@@ -13058,6 +13343,13 @@ class LazyQueryBuilder {
       return [];
     }
   }
+  async aggregate(spec, options) {
+    const qb = await this.resolveWithOps();
+    if (options) {
+      return qb.aggregate(spec, options);
+    }
+    return qb.aggregate(spec);
+  }
 }
 class LazyDocRef {
   constructor(id, resolve) {