@sfutureapps/db-sdk 0.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @sfuture/db-js
+
+Supabase-like JS SDK for ThinkPHP DB Gateway (MySQL)
+
+## Install (local)
+- copy this folder
+- run:
+```bash
+npm i
+npm run build
+```
+
+## Create client
+```ts
+import { createClient } from "@sfuture/db-js";
+
+const db = createClient("https://yourdomain.com", {
+  accessToken: () => localStorage.getItem("token"),
+});
+```
+
+## Select + pagination
+```ts
+const res = await db
+  .from("booking_paginate_view")
+  .select("*")
+  .like("property_name", "%Kampot%")
+  .order("createtime", { ascending: false })
+  .page(1, 20)
+  .withCount()
+  .execute();
+
+console.log(res.data);
+console.log(res.meta); // { page, limit, offset, total, last_page }
+```
+
+## Insert / Update / Delete
+```ts
+await db.from("bookings").insert({ property_id: 1, user_id: 2, total_amount: 50 });
+
+await db.from("bookings").eq("id", 123).update({ status: "paid" });
+
+await db.from("bookings").eq("id", 123).delete();
+```
+
+## Aggregate
+```ts
+const totalPaid = await db.from("bookings").eq("status", "paid").sum("total_amount");
+console.log(totalPaid.data);
+```
+
+## Count notes
+- `.withCount()` = pagination total rows (meta)
+- `.count()` = aggregate COUNT(*)

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "notLike" | "between" | "notBetween" | "in" | "notIn" | "isNull" | "notNull" | "regexp" | "notRegexp" | "time" | "findInSet";
+type Filter = {
+    col: string;
+    op: FilterOp;
+    val: any;
+};
+type Order = {
+    col: string;
+    dir: "asc" | "desc";
+};
+type DbError = {
+    status?: number;
+    message: string;
+    details?: any;
+};
+type DbResponse<T> = {
+    data: T | null;
+    error: DbError | null;
+    count?: number | null;
+    meta?: any;
+};
+type ClientOptions = {
+    apiKey?: string;
+    accessToken?: () => string | null;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+};
+
+declare class HttpClient {
+    private baseUrl;
+    private apiKey?;
+    private accessToken?;
+    private fetcher;
+    private extraHeaders;
+    constructor(baseUrl: string, opts?: ClientOptions);
+    post<T>(path: string, body: any): Promise<DbResponse<T>>;
+}
+
+type OrderOpts = {
+    ascending?: boolean;
+};
+declare class QueryBuilder<Row = any> {
+    private tableName;
+    private client;
+    private _select;
+    private _filters;
+    private _order;
+    private _limit;
+    private _page;
+    private _offset;
+    private _withCount;
+    private _single;
+    private _distinct;
+    private _group;
+    private _having;
+    constructor(client: HttpClient, table: string);
+    select(columns?: string): this;
+    private addFilter;
+    eq(col: string, val: any): this;
+    neq(col: string, val: any): this;
+    gt(col: string, val: any): this;
+    gte(col: string, val: any): this;
+    lt(col: string, val: any): this;
+    lte(col: string, val: any): this;
+    like(col: string, val: string): this;
+    notLike(col: string, val: string): this;
+    between(col: string, range: [any, any]): this;
+    notBetween(col: string, range: [any, any]): this;
+    in(col: string, vals: any[]): this;
+    notIn(col: string, vals: any[]): this;
+    isNull(col: string): this;
+    notNull(col: string): this;
+    regexp(col: string, pattern: string): this;
+    notRegexp(col: string, pattern: string): this;
+    whereTime(col: string, op: ">" | ">=" | "<" | "<=", time: string): this;
+    betweenTime(col: string, range: [string, string]): this;
+    findInSet(col: string, val: string | number): this;
+    order(col: string, opts?: OrderOpts): this;
+    limit(n: number): this;
+    page(page: number, limit: number): this;
+    range(from: number, to: number): this;
+    /** Pagination total rows (not aggregate). */
+    withCount(): this;
+    single(): this;
+    distinct(): this;
+    group(cols: string): this;
+    havingEq(col: string, val: any): this;
+    havingGte(col: string, val: any): this;
+    havingLte(col: string, val: any): this;
+    havingGt(col: string, val: any): this;
+    havingLt(col: string, val: any): this;
+    havingNeq(col: string, val: any): this;
+    execute(): Promise<DbResponse<Row[] | Row>>;
+    private agg;
+    /** Aggregate count value (COUNT(*)) */
+    count(field?: string): Promise<DbResponse<number>>;
+    sum(field: string): Promise<DbResponse<number>>;
+    avg(field: string): Promise<DbResponse<number>>;
+    min(field: string): Promise<DbResponse<number>>;
+    max(field: string): Promise<DbResponse<number>>;
+    insert(values: Partial<Row> | Array<Partial<Row>>): Promise<DbResponse<unknown>>;
+    update(values: Partial<Row>): Promise<DbResponse<unknown>> | Promise<{
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+    delete(): Promise<DbResponse<unknown>> | Promise<{
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+}
+
+declare function createClient(baseUrl: string, opts?: ClientOptions): {
+    from<Row = any>(table: string): QueryBuilder<Row>;
+};
+
+export { type ClientOptions, type DbError, type DbResponse, type Filter, type Order, createClient };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "notLike" | "between" | "notBetween" | "in" | "notIn" | "isNull" | "notNull" | "regexp" | "notRegexp" | "time" | "findInSet";
+type Filter = {
+    col: string;
+    op: FilterOp;
+    val: any;
+};
+type Order = {
+    col: string;
+    dir: "asc" | "desc";
+};
+type DbError = {
+    status?: number;
+    message: string;
+    details?: any;
+};
+type DbResponse<T> = {
+    data: T | null;
+    error: DbError | null;
+    count?: number | null;
+    meta?: any;
+};
+type ClientOptions = {
+    apiKey?: string;
+    accessToken?: () => string | null;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+};
+
+declare class HttpClient {
+    private baseUrl;
+    private apiKey?;
+    private accessToken?;
+    private fetcher;
+    private extraHeaders;
+    constructor(baseUrl: string, opts?: ClientOptions);
+    post<T>(path: string, body: any): Promise<DbResponse<T>>;
+}
+
+type OrderOpts = {
+    ascending?: boolean;
+};
+declare class QueryBuilder<Row = any> {
+    private tableName;
+    private client;
+    private _select;
+    private _filters;
+    private _order;
+    private _limit;
+    private _page;
+    private _offset;
+    private _withCount;
+    private _single;
+    private _distinct;
+    private _group;
+    private _having;
+    constructor(client: HttpClient, table: string);
+    select(columns?: string): this;
+    private addFilter;
+    eq(col: string, val: any): this;
+    neq(col: string, val: any): this;
+    gt(col: string, val: any): this;
+    gte(col: string, val: any): this;
+    lt(col: string, val: any): this;
+    lte(col: string, val: any): this;
+    like(col: string, val: string): this;
+    notLike(col: string, val: string): this;
+    between(col: string, range: [any, any]): this;
+    notBetween(col: string, range: [any, any]): this;
+    in(col: string, vals: any[]): this;
+    notIn(col: string, vals: any[]): this;
+    isNull(col: string): this;
+    notNull(col: string): this;
+    regexp(col: string, pattern: string): this;
+    notRegexp(col: string, pattern: string): this;
+    whereTime(col: string, op: ">" | ">=" | "<" | "<=", time: string): this;
+    betweenTime(col: string, range: [string, string]): this;
+    findInSet(col: string, val: string | number): this;
+    order(col: string, opts?: OrderOpts): this;
+    limit(n: number): this;
+    page(page: number, limit: number): this;
+    range(from: number, to: number): this;
+    /** Pagination total rows (not aggregate). */
+    withCount(): this;
+    single(): this;
+    distinct(): this;
+    group(cols: string): this;
+    havingEq(col: string, val: any): this;
+    havingGte(col: string, val: any): this;
+    havingLte(col: string, val: any): this;
+    havingGt(col: string, val: any): this;
+    havingLt(col: string, val: any): this;
+    havingNeq(col: string, val: any): this;
+    execute(): Promise<DbResponse<Row[] | Row>>;
+    private agg;
+    /** Aggregate count value (COUNT(*)) */
+    count(field?: string): Promise<DbResponse<number>>;
+    sum(field: string): Promise<DbResponse<number>>;
+    avg(field: string): Promise<DbResponse<number>>;
+    min(field: string): Promise<DbResponse<number>>;
+    max(field: string): Promise<DbResponse<number>>;
+    insert(values: Partial<Row> | Array<Partial<Row>>): Promise<DbResponse<unknown>>;
+    update(values: Partial<Row>): Promise<DbResponse<unknown>> | Promise<{
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+    delete(): Promise<DbResponse<unknown>> | Promise<{
+        data: null;
+        error: {
+            message: string;
+        };
+    }>;
+}
+
+declare function createClient(baseUrl: string, opts?: ClientOptions): {
+    from<Row = any>(table: string): QueryBuilder<Row>;
+};
+
+export { type ClientOptions, type DbError, type DbResponse, type Filter, type Order, createClient };

package/dist/index.js

@@ -0,0 +1,298 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var HttpClient = class {
+  constructor(baseUrl, opts = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.accessToken = opts.accessToken;
+    this.fetcher = opts.fetch ?? fetch;
+    this.extraHeaders = opts.headers ?? {};
+  }
+  async post(path, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.extraHeaders
+    };
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    const token = this.accessToken?.();
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    const res = await this.fetcher(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      return { data: null, error: { status: res.status, message: text || res.statusText } };
+    }
+    try {
+      const json = JSON.parse(text || "{}");
+      return {
+        data: json.data ?? null,
+        count: json.count ?? null,
+        meta: json.meta ?? null,
+        error: json.error ?? null
+      };
+    } catch {
+      return { data: null, error: { status: res.status, message: "Invalid JSON response", details: text } };
+    }
+  }
+};
+
+// src/query-builder.ts
+var QueryBuilder = class {
+  constructor(client, table) {
+    this._select = ["*"];
+    this._filters = [];
+    this._order = [];
+    this._limit = null;
+    this._page = null;
+    // ThinkPHP style
+    this._offset = null;
+    // offset style
+    this._withCount = false;
+    this._single = false;
+    this._distinct = false;
+    this._group = [];
+    this._having = [];
+    this.client = client;
+    this.tableName = table;
+  }
+  // ---- select ----
+  select(columns = "*") {
+    const cols = columns.trim();
+    this._select = cols === "*" || cols === "" ? ["*"] : cols.split(",").map((s) => s.trim()).filter(Boolean);
+    return this;
+  }
+  // ---- filters ----
+  addFilter(col, op, val) {
+    this._filters.push({ col, op, val });
+    return this;
+  }
+  eq(col, val) {
+    return this.addFilter(col, "eq", val);
+  }
+  neq(col, val) {
+    return this.addFilter(col, "neq", val);
+  }
+  gt(col, val) {
+    return this.addFilter(col, "gt", val);
+  }
+  gte(col, val) {
+    return this.addFilter(col, "gte", val);
+  }
+  lt(col, val) {
+    return this.addFilter(col, "lt", val);
+  }
+  lte(col, val) {
+    return this.addFilter(col, "lte", val);
+  }
+  like(col, val) {
+    return this.addFilter(col, "like", val);
+  }
+  notLike(col, val) {
+    return this.addFilter(col, "notLike", val);
+  }
+  between(col, range) {
+    return this.addFilter(col, "between", range);
+  }
+  notBetween(col, range) {
+    return this.addFilter(col, "notBetween", range);
+  }
+  in(col, vals) {
+    return this.addFilter(col, "in", vals);
+  }
+  notIn(col, vals) {
+    return this.addFilter(col, "notIn", vals);
+  }
+  isNull(col) {
+    return this.addFilter(col, "isNull", null);
+  }
+  notNull(col) {
+    return this.addFilter(col, "notNull", null);
+  }
+  regexp(col, pattern) {
+    return this.addFilter(col, "regexp", pattern);
+  }
+  notRegexp(col, pattern) {
+    return this.addFilter(col, "notRegexp", pattern);
+  }
+  whereTime(col, op, time) {
+    return this.addFilter(col, "time", { op, val: time });
+  }
+  betweenTime(col, range) {
+    return this.addFilter(col, "time", { op: "between", val: range });
+  }
+  findInSet(col, val) {
+    return this.addFilter(col, "findInSet", val);
+  }
+  // ---- order ----
+  order(col, opts = {}) {
+    this._order.push({ col, dir: opts.ascending === false ? "desc" : "asc" });
+    return this;
+  }
+  // ---- pagination ----
+  limit(n) {
+    this._limit = Math.max(1, n | 0);
+    return this;
+  }
+  page(page, limit) {
+    this._page = Math.max(1, page | 0);
+    this._limit = Math.max(1, limit | 0);
+    this._offset = null;
+    return this;
+  }
+  range(from, to) {
+    const f = Math.max(0, from | 0);
+    const t = Math.max(f, to | 0);
+    this._offset = f;
+    this._limit = t - f + 1;
+    this._page = null;
+    return this;
+  }
+  /** Pagination total rows (not aggregate). */
+  withCount() {
+    this._withCount = true;
+    return this;
+  }
+  single() {
+    this._single = true;
+    this.limit(1);
+    return this;
+  }
+  // ---- group/having/distinct ----
+  distinct() {
+    this._distinct = true;
+    return this;
+  }
+  group(cols) {
+    this._group = cols.split(",").map((s) => s.trim()).filter(Boolean);
+    return this;
+  }
+  havingEq(col, val) {
+    this._having.push({ col, op: "eq", val });
+    return this;
+  }
+  havingGte(col, val) {
+    this._having.push({ col, op: "gte", val });
+    return this;
+  }
+  havingLte(col, val) {
+    this._having.push({ col, op: "lte", val });
+    return this;
+  }
+  havingGt(col, val) {
+    this._having.push({ col, op: "gt", val });
+    return this;
+  }
+  havingLt(col, val) {
+    this._having.push({ col, op: "lt", val });
+    return this;
+  }
+  havingNeq(col, val) {
+    this._having.push({ col, op: "neq", val });
+    return this;
+  }
+  // ---- execute ----
+  async execute() {
+    const payload = {
+      table: this.tableName,
+      select: this._select,
+      filters: this._filters,
+      order: this._order,
+      limit: this._limit ?? 20,
+      count: this._withCount,
+      distinct: this._distinct,
+      group: this._group,
+      having: this._having
+    };
+    if (this._page !== null) payload.page = this._page;
+    if (this._offset !== null) payload.offset = this._offset;
+    const res = await this.client.post("/db/v1/query", payload);
+    if (res.error) return res;
+    if (this._single) {
+      const first = Array.isArray(res.data) ? res.data[0] ?? null : null;
+      return { data: first, error: null, count: res.count ?? null, meta: res.meta ?? null };
+    }
+    return res;
+  }
+  // ---- aggregates ----
+  agg(fn, field = "*") {
+    return this.client.post("/db/v1/query", {
+      table: this.tableName,
+      aggregate: { fn, field },
+      filters: this._filters
+    });
+  }
+  /** Aggregate count value (COUNT(*)) */
+  count(field = "*") {
+    return this.agg("count", field);
+  }
+  sum(field) {
+    return this.agg("sum", field);
+  }
+  avg(field) {
+    return this.agg("avg", field);
+  }
+  min(field) {
+    return this.agg("min", field);
+  }
+  max(field) {
+    return this.agg("max", field);
+  }
+  // ---- write ----
+  insert(values) {
+    return this.client.post("/db/v1/insert", { table: this.tableName, values });
+  }
+  update(values) {
+    if (this._filters.length === 0) {
+      return Promise.resolve({ data: null, error: { message: "Update requires filters (e.g. .eq('id', 1))" } });
+    }
+    return this.client.post("/db/v1/update", { table: this.tableName, values, filters: this._filters });
+  }
+  delete() {
+    if (this._filters.length === 0) {
+      return Promise.resolve({ data: null, error: { message: "Delete requires filters (e.g. .eq('id', 1))" } });
+    }
+    return this.client.post("/db/v1/delete", { table: this.tableName, filters: this._filters });
+  }
+};
+
+// src/main.ts
+function createClient(baseUrl, opts = {}) {
+  const http = new HttpClient(baseUrl, opts);
+  return {
+    from(table) {
+      return new QueryBuilder(http, table);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createClient
+});

package/dist/index.mjs

@@ -0,0 +1,271 @@
+// src/client.ts
+var HttpClient = class {
+  constructor(baseUrl, opts = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.accessToken = opts.accessToken;
+    this.fetcher = opts.fetch ?? fetch;
+    this.extraHeaders = opts.headers ?? {};
+  }
+  async post(path, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.extraHeaders
+    };
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    const token = this.accessToken?.();
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    const res = await this.fetcher(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      return { data: null, error: { status: res.status, message: text || res.statusText } };
+    }
+    try {
+      const json = JSON.parse(text || "{}");
+      return {
+        data: json.data ?? null,
+        count: json.count ?? null,
+        meta: json.meta ?? null,
+        error: json.error ?? null
+      };
+    } catch {
+      return { data: null, error: { status: res.status, message: "Invalid JSON response", details: text } };
+    }
+  }
+};
+
+// src/query-builder.ts
+var QueryBuilder = class {
+  constructor(client, table) {
+    this._select = ["*"];
+    this._filters = [];
+    this._order = [];
+    this._limit = null;
+    this._page = null;
+    // ThinkPHP style
+    this._offset = null;
+    // offset style
+    this._withCount = false;
+    this._single = false;
+    this._distinct = false;
+    this._group = [];
+    this._having = [];
+    this.client = client;
+    this.tableName = table;
+  }
+  // ---- select ----
+  select(columns = "*") {
+    const cols = columns.trim();
+    this._select = cols === "*" || cols === "" ? ["*"] : cols.split(",").map((s) => s.trim()).filter(Boolean);
+    return this;
+  }
+  // ---- filters ----
+  addFilter(col, op, val) {
+    this._filters.push({ col, op, val });
+    return this;
+  }
+  eq(col, val) {
+    return this.addFilter(col, "eq", val);
+  }
+  neq(col, val) {
+    return this.addFilter(col, "neq", val);
+  }
+  gt(col, val) {
+    return this.addFilter(col, "gt", val);
+  }
+  gte(col, val) {
+    return this.addFilter(col, "gte", val);
+  }
+  lt(col, val) {
+    return this.addFilter(col, "lt", val);
+  }
+  lte(col, val) {
+    return this.addFilter(col, "lte", val);
+  }
+  like(col, val) {
+    return this.addFilter(col, "like", val);
+  }
+  notLike(col, val) {
+    return this.addFilter(col, "notLike", val);
+  }
+  between(col, range) {
+    return this.addFilter(col, "between", range);
+  }
+  notBetween(col, range) {
+    return this.addFilter(col, "notBetween", range);
+  }
+  in(col, vals) {
+    return this.addFilter(col, "in", vals);
+  }
+  notIn(col, vals) {
+    return this.addFilter(col, "notIn", vals);
+  }
+  isNull(col) {
+    return this.addFilter(col, "isNull", null);
+  }
+  notNull(col) {
+    return this.addFilter(col, "notNull", null);
+  }
+  regexp(col, pattern) {
+    return this.addFilter(col, "regexp", pattern);
+  }
+  notRegexp(col, pattern) {
+    return this.addFilter(col, "notRegexp", pattern);
+  }
+  whereTime(col, op, time) {
+    return this.addFilter(col, "time", { op, val: time });
+  }
+  betweenTime(col, range) {
+    return this.addFilter(col, "time", { op: "between", val: range });
+  }
+  findInSet(col, val) {
+    return this.addFilter(col, "findInSet", val);
+  }
+  // ---- order ----
+  order(col, opts = {}) {
+    this._order.push({ col, dir: opts.ascending === false ? "desc" : "asc" });
+    return this;
+  }
+  // ---- pagination ----
+  limit(n) {
+    this._limit = Math.max(1, n | 0);
+    return this;
+  }
+  page(page, limit) {
+    this._page = Math.max(1, page | 0);
+    this._limit = Math.max(1, limit | 0);
+    this._offset = null;
+    return this;
+  }
+  range(from, to) {
+    const f = Math.max(0, from | 0);
+    const t = Math.max(f, to | 0);
+    this._offset = f;
+    this._limit = t - f + 1;
+    this._page = null;
+    return this;
+  }
+  /** Pagination total rows (not aggregate). */
+  withCount() {
+    this._withCount = true;
+    return this;
+  }
+  single() {
+    this._single = true;
+    this.limit(1);
+    return this;
+  }
+  // ---- group/having/distinct ----
+  distinct() {
+    this._distinct = true;
+    return this;
+  }
+  group(cols) {
+    this._group = cols.split(",").map((s) => s.trim()).filter(Boolean);
+    return this;
+  }
+  havingEq(col, val) {
+    this._having.push({ col, op: "eq", val });
+    return this;
+  }
+  havingGte(col, val) {
+    this._having.push({ col, op: "gte", val });
+    return this;
+  }
+  havingLte(col, val) {
+    this._having.push({ col, op: "lte", val });
+    return this;
+  }
+  havingGt(col, val) {
+    this._having.push({ col, op: "gt", val });
+    return this;
+  }
+  havingLt(col, val) {
+    this._having.push({ col, op: "lt", val });
+    return this;
+  }
+  havingNeq(col, val) {
+    this._having.push({ col, op: "neq", val });
+    return this;
+  }
+  // ---- execute ----
+  async execute() {
+    const payload = {
+      table: this.tableName,
+      select: this._select,
+      filters: this._filters,
+      order: this._order,
+      limit: this._limit ?? 20,
+      count: this._withCount,
+      distinct: this._distinct,
+      group: this._group,
+      having: this._having
+    };
+    if (this._page !== null) payload.page = this._page;
+    if (this._offset !== null) payload.offset = this._offset;
+    const res = await this.client.post("/db/v1/query", payload);
+    if (res.error) return res;
+    if (this._single) {
+      const first = Array.isArray(res.data) ? res.data[0] ?? null : null;
+      return { data: first, error: null, count: res.count ?? null, meta: res.meta ?? null };
+    }
+    return res;
+  }
+  // ---- aggregates ----
+  agg(fn, field = "*") {
+    return this.client.post("/db/v1/query", {
+      table: this.tableName,
+      aggregate: { fn, field },
+      filters: this._filters
+    });
+  }
+  /** Aggregate count value (COUNT(*)) */
+  count(field = "*") {
+    return this.agg("count", field);
+  }
+  sum(field) {
+    return this.agg("sum", field);
+  }
+  avg(field) {
+    return this.agg("avg", field);
+  }
+  min(field) {
+    return this.agg("min", field);
+  }
+  max(field) {
+    return this.agg("max", field);
+  }
+  // ---- write ----
+  insert(values) {
+    return this.client.post("/db/v1/insert", { table: this.tableName, values });
+  }
+  update(values) {
+    if (this._filters.length === 0) {
+      return Promise.resolve({ data: null, error: { message: "Update requires filters (e.g. .eq('id', 1))" } });
+    }
+    return this.client.post("/db/v1/update", { table: this.tableName, values, filters: this._filters });
+  }
+  delete() {
+    if (this._filters.length === 0) {
+      return Promise.resolve({ data: null, error: { message: "Delete requires filters (e.g. .eq('id', 1))" } });
+    }
+    return this.client.post("/db/v1/delete", { table: this.tableName, filters: this._filters });
+  }
+};
+
+// src/main.ts
+function createClient(baseUrl, opts = {}) {
+  const http = new HttpClient(baseUrl, opts);
+  return {
+    from(table) {
+      return new QueryBuilder(http, table);
+    }
+  };
+}
+export {
+  createClient
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sfutureapps/db-sdk",
+  "version": "0.3.0",
+  "description": "SfutureApps JS SDK for ThinkPHP DB Gateway (MySQL)",
+  "license": "MIT",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "thinkphp",
+    "mysql",
+    "sdk",
+    "database",
+    "rest",
+    "orm",
+    "js",
+    "typescript",
+    "sfutureApps"
+  ]
+}