@bunbase-ae/js 1.2.2-next.45.452b4e1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "1.2.2-next.45.452b4e1",
+  "version": "1.3.0",
   "type": "module",
   "description": "TypeScript/JavaScript SDK for BunBase",
   "license": "UNLICENSED",

package/src/admin.ts

@@ -14,6 +14,7 @@
 //   client.admin.system      — health + stats
 
 import type { HttpClient } from "./http";
+import type { Filter } from "./types";
 
 // ─── Shared admin types ───────────────────────────────────────────────────────
 
@@ -507,7 +508,16 @@ class AdminCollectionsClient {
 
   // ── Records ─────────────────────────────────────────────────────────────────
 
-  async listRecords(
+  /**
+   * List records from a collection with optional filtering, sorting, and pagination.
+   *
+   * Pass a type parameter to get typed records:
+   * ```ts
+   * const data = await bbClient.admin.collections.listRecords<Device>("devices", { ... });
+   * // data.items is (Device & AdminRecord)[]
+   * ```
+   */
+  async listRecords<T extends Record<string, unknown> = Record<string, unknown>>(
     collection: string,
     opts: {
       /** @deprecated Use `after` for keyset pagination. */
@@ -515,11 +525,12 @@ class AdminCollectionsClient {
       limit?: number;
       after?: string;
       sort?: string;
-      filter?: Record<string, string>;
+      /** Typed filter supporting equality and operator filters ({ gte, lte, in, like, ne, eq }). */
+      filter?: Filter<T>;
       includeDeleted?: boolean;
       search?: string;
     } = {},
-  ): Promise<AdminListResult<AdminRecord>> {
+  ): Promise<AdminListResult<T & AdminRecord>> {
     const params: Record<string, string> = {
       limit: String(opts.limit ?? 50),
     };
@@ -530,19 +541,45 @@ class AdminCollectionsClient {
     if (opts.search) params.search = opts.search;
     if (opts.filter) {
       for (const [key, value] of Object.entries(opts.filter)) {
-        params[`filter[${key}]`] = value;
+        if (value === undefined || value === null) continue;
+        if (typeof value === "object" && !Array.isArray(value)) {
+          // Operator filter: { age: { gte: 18 } } → filter[age][gte]=18
+          for (const [op, opVal] of Object.entries(value as Record<string, unknown>)) {
+            if (opVal !== undefined && opVal !== null) {
+              params[`filter[${key}][${op}]`] = String(opVal);
+            }
+          }
+        } else if (Array.isArray(value)) {
+          // Array shorthand: { stage: ["a", "b"] } → filter[stage][in]=a,b
+          params[`filter[${key}][in]`] = value.join(",");
+        } else {
+          // Equality filter: { status: "active" } → filter[status]=active
+          params[`filter[${key}]`] = String(value);
+        }
       }
     }
-    return this.http.request<AdminListResult<AdminRecord>>(
+    return this.http.request<AdminListResult<T & AdminRecord>>(
       "GET",
       `/api/v1/admin/collections/${collection}/records`,
       { query: params },
     );
   }
 
-  async getRecord(collection: string, id: string): Promise<AdminRecord | null> {
+  /**
+   * Fetch a single record by ID, returning null when not found.
+   *
+   * Pass a type parameter to get a typed record:
+   * ```ts
+   * const rec = await bbClient.admin.collections.getRecord<PosOrderItem>("pos_order_items", id);
+   * // rec is (PosOrderItem & AdminRecord) | null
+   * ```
+   */
+  async getRecord<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    id: string,
+  ): Promise<(T & AdminRecord) | null> {
     try {
-      return await this.http.request<AdminRecord>(
+      return await this.http.request<T & AdminRecord>(
         "GET",
         `/api/v1/admin/collections/${collection}/records/${id}`,
       );
@@ -551,20 +588,41 @@ class AdminCollectionsClient {
     }
   }
 
-  async createRecord(collection: string, data: Record<string, unknown>): Promise<AdminRecord> {
-    return this.http.request<AdminRecord>(
+  /**
+   * Create a new record in a collection.
+   *
+   * Pass a type parameter to get a typed result:
+   * ```ts
+   * const rec = await bbClient.admin.collections.createRecord<Device>("devices", data);
+   * // rec is Device & AdminRecord
+   * ```
+   */
+  async createRecord<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    data: Partial<T>,
+  ): Promise<T & AdminRecord> {
+    return this.http.request<T & AdminRecord>(
       "POST",
       `/api/v1/admin/collections/${collection}/records`,
       { body: data },
     );
   }
 
-  async updateRecord(
+  /**
+   * Update a record by ID.
+   *
+   * Pass a type parameter to get a typed result:
+   * ```ts
+   * const rec = await bbClient.admin.collections.updateRecord<Device>("devices", id, patch);
+   * // rec is Device & AdminRecord
+   * ```
+   */
+  async updateRecord<T extends Record<string, unknown> = Record<string, unknown>>(
     collection: string,
     id: string,
-    patch: Record<string, unknown>,
-  ): Promise<AdminRecord> {
-    return this.http.request<AdminRecord>(
+    patch: Partial<T>,
+  ): Promise<T & AdminRecord> {
+    return this.http.request<T & AdminRecord>(
       "PATCH",
       `/api/v1/admin/collections/${collection}/records/${id}`,
       { body: patch },
@@ -578,8 +636,20 @@ class AdminCollectionsClient {
     );
   }
 
-  async restoreRecord(collection: string, id: string): Promise<AdminRecord> {
-    return this.http.request<AdminRecord>(
+  /**
+   * Restore a soft-deleted record.
+   *
+   * Pass a type parameter to get a typed result:
+   * ```ts
+   * const rec = await bbClient.admin.collections.restoreRecord<Device>("devices", id);
+   * // rec is Device & AdminRecord
+   * ```
+   */
+  async restoreRecord<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    id: string,
+  ): Promise<T & AdminRecord> {
+    return this.http.request<T & AdminRecord>(
       "POST",
       `/api/v1/admin/collections/${collection}/records/${id}/restore`,
       { body: {} },

package/src/collection.ts

@@ -8,7 +8,8 @@
 import type { HttpClient } from "./http";
 import type {
   AggregateFunction,
-  AggregateResult,
+  AggregateGroupedResult,
+  AggregateScalarResult,
   BatchOperation,
   BatchResult,
   BunBaseRecord,
@@ -90,15 +91,19 @@ export class CollectionClient<T extends Record<string, unknown> = Record<string,
   }
 
   // Compute an aggregate (sum, avg, min, max, count) over the collection.
-  async aggregate(
+  //
+  // The return type is discriminated by whether group_by is provided:
+  //   without group_by → { value: number | null }
+  //   with    group_by → { groups: Array<{ group: unknown; value: number | null }> }
+  async aggregate<TGroupBy extends string | undefined = undefined>(
     fn: AggregateFunction,
     options: {
       field?: string;
-      group_by?: string;
+      group_by?: TGroupBy;
       filter?: Filter<T>;
       include_deleted?: boolean;
     } = {},
-  ): Promise<AggregateResult> {
+  ): Promise<[TGroupBy] extends [string] ? AggregateGroupedResult : AggregateScalarResult> {
     const qs: Record<string, string> = { fn };
     if (options.field) qs.field = options.field;
     if (options.group_by) qs.group_by = options.group_by;
@@ -107,9 +112,9 @@ export class CollectionClient<T extends Record<string, unknown> = Record<string,
       const filterQs = buildQueryString({ filter: options.filter });
       Object.assign(qs, filterQs);
     }
-    return this.http.request<AggregateResult>("GET", `/api/v1/${this.name}/aggregate`, {
-      query: qs,
-    });
+    return this.http.request<
+      [TGroupBy] extends [string] ? AggregateGroupedResult : AggregateScalarResult
+    >("GET", `/api/v1/${this.name}/aggregate`, { query: qs });
   }
 
   // Count records matching the query filters.
@@ -150,7 +155,9 @@ export class CollectionClient<T extends Record<string, unknown> = Record<string,
 
 // ─── Query string builder ──────────────────────────────────────────────────────
 
-export function buildQueryString<T>(query: ListQuery<T>): Record<string, string> {
+export function buildQueryString<T extends Record<string, unknown> = Record<string, unknown>>(
+  query: ListQuery<T>,
+): Record<string, string> {
   const params: Record<string, string> = {};
 
   if (query.filter) {
@@ -159,14 +166,17 @@ export function buildQueryString<T>(query: ListQuery<T>): Record<string, string>
 
       if (typeof value === "object" && !Array.isArray(value)) {
         // Operator filter: { age: { gte: 18 } } → filter[age][gte]=18
-        for (const [op, opVal] of Object.entries(value as Filter)) {
+        for (const [op, opVal] of Object.entries(value as Record<string, unknown>)) {
           if (opVal !== undefined && opVal !== null) {
             params[`filter[${field}][${op}]`] = String(opVal);
           }
         }
+      } else if (Array.isArray(value)) {
+        // Array shorthand: { stage: ["a", "b"] } → filter[stage][in]=a,b
+        params[`filter[${field}][in]`] = value.join(",");
       } else {
         // Equality filter: { status: "published" } → filter[status]=published
-        params[`filter[${field}]`] = Array.isArray(value) ? value.join(",") : String(value);
+        params[`filter[${field}]`] = String(value);
       }
     }
   }

package/src/index.ts

@@ -41,7 +41,9 @@ export { RealtimeClient, type SubscribeOptions } from "./realtime";
 export { type SignedUploadResult, StorageClient, type UploadOptions } from "./storage";
 export {
   type AggregateFunction,
+  type AggregateGroupedResult,
   type AggregateResult,
+  type AggregateScalarResult,
   type ApiKey,
   type AuthResult,
   type AuthUser,
@@ -60,7 +62,9 @@ export {
   type FieldRule,
   type FileRecord,
   type Filter,
+  type FilterFieldValue,
   type FilterOperator,
+  type FilterOperatorValue,
   type FilterValue,
   type GetQuery,
   type ListQuery,

package/src/types.ts

@@ -89,18 +89,88 @@ export interface FileRecord {
 
 export type FilterOperator = "eq" | "ne" | "gt" | "lt" | "gte" | "lte" | "like" | "in";
 
+/** Scalar filter value for plain equality filters. @deprecated Use FilterFieldValue<V> for typed filters. */
 export type FilterValue = string | number | boolean | string[] | number[];
 
+/** @deprecated Use FilterOperatorValue<V> for typed operator filters. */
 export interface FieldFilter {
   [op: string]: FilterValue;
 }
 
+/**
+ * Typed operator object for a single field.
+ * Constrains each operator's value to the field's own type V.
+ *
+ * @example
+ * // Numeric field:  { gte: 18, lte: 65 }
+ * // String field:   { in: ["draft", "published"] }
+ * // Any field:      { ne: null }
+ */
+export type FilterOperatorValue<V> = {
+  eq?: V;
+  ne?: V;
+  gt?: V;
+  lt?: V;
+  gte?: V;
+  lte?: V;
+  like?: string;
+  in?: V[];
+};
+
+/**
+ * Array shorthand for "in" filters.
+ *
+ * This preserves the existing SDK ergonomics:
+ * `{ stage: ["draft", "published"] }`
+ *
+ * The shorthand is only meaningful for scalar string/number-like fields.
+ */
+export type FilterArrayShorthandValue<V> =
+  Exclude<V, null | undefined> extends string
+    ? string[]
+    : Exclude<V, null | undefined> extends number
+      ? number[]
+      : never;
+
+/**
+ * A filter field accepts either a plain value (equality) or an operator object.
+ *
+ * @example
+ * // Equality:   "published"
+ * // Operator:   { gte: 18 }
+ * // Array-in:   { in: ["a", "b"] }
+ */
+export type FilterFieldValue<V> = V | FilterArrayShorthandValue<V> | FilterOperatorValue<V>;
+
+/**
+ * Filter over collection records of type T.
+ *
+ * Supports both equality filters `{ stage: "chopping" }` and operator
+ * filters `{ _created_at: { gte: timestamp }, rfid_tag: { in: ["a","b"] } }`.
+ *
+ * BunBaseRecord system fields (_id, _created_at, _updated_at, _owner_id,
+ * _deleted_at) are always available for filtering regardless of T.
+ *
+ * @example
+ * // Simple equality
+ * filter: { stage: "chopping" }
+ *
+ * // Operator filters — no cast required
+ * filter: { _created_at: { gte: timestamp } }
+ * filter: { rfid_tag: { in: ["a", "b"] } }
+ * filter: { score: { gte: 0, lte: 100 } }
+ */
 // Simple: { status: "published" }  → filter[status]=published
 // Operator: { age: { gte: 18 } }  → filter[age][gte]=18
 export type Filter<T = Record<string, unknown>> = {
-  [K in keyof T]?: T[K] | FieldFilter;
+  [K in Exclude<keyof T, keyof BunBaseRecord>]?: FilterFieldValue<T[K]>;
 } & {
-  [key: string]: FilterValue | FieldFilter | undefined;
+  // BunBaseRecord system fields — always filterable, typed to their canonical types
+  _id?: FilterFieldValue<string>;
+  _created_at?: FilterFieldValue<number>;
+  _updated_at?: FilterFieldValue<number>;
+  _owner_id?: FilterFieldValue<string | null>;
+  _deleted_at?: FilterFieldValue<number | null | undefined>;
 };
 
 export interface ListQuery<T = Record<string, unknown>> {
@@ -193,9 +263,14 @@ export interface FieldRule {
 
 export type AggregateFunction = "sum" | "avg" | "min" | "max" | "count";
 
-export type AggregateResult =
-  | { value: number | null }
-  | { groups: Array<{ group: unknown; value: number | null }> };
+/** Result shape when no group_by is provided. */
+export type AggregateScalarResult = { value: number | null };
+
+/** Result shape when group_by is provided. */
+export type AggregateGroupedResult = { groups: Array<{ group: unknown; value: number | null }> };
+
+/** Union of all possible aggregate result shapes. Narrow via `'groups' in result`. */
+export type AggregateResult = AggregateScalarResult | AggregateGroupedResult;
 
 // ─── Realtime types ───────────────────────────────────────────────────────────