@sfutureapps/db-sdk 0.3.31 → 0.3.33

package/README.md

@@ -1,17 +1,59 @@
 # @sfutureapps/db-sdk
 
-JS SDK for ThinkPHP DB Gateway (MySQL)
+JS SDK for a ThinkPHP DB Gateway (MySQL).
+
+It provides a chainable query builder for:
+- selecting rows with filters, ordering, pagination
+- joins, group/having, distinct
+- aggregate helpers (`count`, `sum`, `avg`, `min`, `max`)
+- inserts, updates, deletes (updates/deletes require filters)
+
+Under the hood it calls the gateway endpoints:
+- `POST v3/api/query`
+- `POST v3/api/insert`
+- `POST v3/api/update`
+- `POST v3/api/delete`
+
+## Install
+
+```bash
+npm i @sfutureapps/db-sdk
+# or
+pnpm add @sfutureapps/db-sdk
+# or
+bun add @sfutureapps/db-sdk
+```
+
+## Create a client
 
-## Create client
 ```ts
 import { createClient } from "@sfutureapps/db-sdk";
 
-const db = createClient("https://yourdomain.com", {
+const db = createClient("https://yourdomain.com/api", {
+  // optional
+  apiKey: "YOUR_API_KEY",
+  // optional (recommended for SSR or custom storage)
   accessToken: () => localStorage.getItem("token"),
+  // optional extra headers
+  headers: { "X-App-Version": "1.0.0" },
 });
 ```
 
-## Select + pagination
+### Environment-variable configuration (optional)
+
+If you prefer env vars (or you already have apps using them), the SDK also reads:
+- `API_URL` (also supports `VITE_API_URL`, `NEXT_PUBLIC_API_URL`, `REACT_APP_API_URL`)
+- `API_KEY`
+- `TOKEN_NAME` (default: `token`)
+- `IS_AUTH` (`true/1/yes` enables token requirement)
+- `INCLUDE_TOKEN_IN_GET` (default: `true`)
+
+If you pass `baseUrl` to `createClient(...)`, it takes precedence over `API_URL`.
+
+## How to use
+
+### Select + pagination
+
 ```ts
 const res = await db
   .from("booking_paginate_view")
@@ -22,25 +64,129 @@ const res = await db
   .withCount()
   .execute();
 
-console.log(res.data);
-console.log(res.meta); // { page, limit, offset, total, last_page }
+if (res.error) throw new Error(res.error.message);
+
+console.log(res.data); // rows
+console.log(res.paginate); // { page, limit, offset, total, last_page, ... }
+```
+
+### Single row
+
+```ts
+const res = await db.from("bookings").select("*").eq("id", 123).single().execute();
+if (res.error) throw new Error(res.error.message);
+console.log(res.data); // object | null
 ```
 
-## Insert / Update / Delete
+### Insert / Update / Delete
+
 ```ts
 await db.from("bookings").insert({ property_id: 1, user_id: 2, total_amount: 50 });
 
+// Update/Delete require at least one filter
 await db.from("bookings").eq("id", 123).update({ status: "paid" });
-
 await db.from("bookings").eq("id", 123).delete();
 ```
 
-## Aggregate
+### Aggregates
+
 ```ts
 const totalPaid = await db.from("bookings").eq("status", "paid").sum("total_amount");
+if (totalPaid.error) throw new Error(totalPaid.error.message);
 console.log(totalPaid.data);
+
+// Notes:
+// - .withCount() = pagination total rows (res.paginate.total)
+// - .count() = aggregate COUNT(*) result in res.data
 ```
 
-## Count notes
-- `.withCount()` = pagination total rows (meta)
-- `.count()` = aggregate COUNT(*)
+## Full example (TypeScript)
+
+This is a complete end-to-end example covering read + paginate, joins, aggregates, and writes.
+
+```ts
+import { createClient } from "@sfutureapps/db-sdk";
+
+type Booking = {
+  id: number;
+  property_id: number;
+  user_id: number;
+  status: "draft" | "paid" | "cancelled" | string;
+  total_amount: number;
+  createtime: string;
+};
+
+async function main() {
+  const db = createClient("https://yourdomain.com/api", {
+    apiKey: "YOUR_API_KEY",
+    accessToken: () => {
+      // Browser: read from localStorage (or cookie)
+      // SSR/Node: return process.env.TOKEN
+      return typeof window !== "undefined" ? localStorage.getItem("token") : null;
+    },
+  });
+
+  // 1) List bookings (page 1, 20 per page) + total count
+  const list = await db
+    .from<Booking>("bookings")
+    .select(["id", "property_id", "user_id", "status", "total_amount", "createtime"])
+    .eq("status", "paid")
+    .order("createtime", { ascending: false })
+    .page(1, 20)
+    .withCount()
+    .execute();
+
+  if (list.error) throw new Error(list.error.message);
+  console.log("rows:", list.data.length);
+  console.log("paginate:", list.paginate);
+
+  // 2) Fetch a single booking
+  const one = await db.from<Booking>("bookings").select("*").eq("id", 123).single().execute();
+  if (one.error) throw new Error(one.error.message);
+  console.log("booking:", one.data);
+
+  // 3) Join example (join clause depends on your gateway/SQL conventions)
+  // NOTE: 'on' is passed through to the gateway.
+  const joined = await db
+    .from<any>("bookings b")
+    .select(["b.id", "b.total_amount", "p.name as property_name"])
+    .join("properties p", "p.id = b.property_id", "LEFT")
+    .gte("b.total_amount", 50)
+    .limit(10)
+    .execute();
+
+  if (joined.error) throw new Error(joined.error.message);
+  console.log("joined:", joined.data);
+
+  // 4) Aggregates
+  const sum = await db.from<Booking>("bookings").eq("status", "paid").sum("total_amount");
+  if (sum.error) throw new Error(sum.error.message);
+  console.log("total paid:", sum.data);
+
+  // 5) Insert
+  const inserted = await db.from<Booking>("bookings").insert({
+    property_id: 1,
+    user_id: 2,
+    status: "draft",
+    total_amount: 50,
+  });
+
+  if (inserted.error) throw new Error(inserted.error.message);
+  console.log("inserted:", inserted.data);
+
+  // 6) Update (requires filters)
+  const updated = await db.from<Booking>("bookings").eq("id", 123).update({ status: "paid" });
+  if (updated.error) throw new Error(updated.error.message);
+  console.log("updated:", updated.data);
+
+  // 7) Delete (requires filters)
+  const deleted = await db.from<Booking>("bookings").eq("id", 123).delete();
+  if (deleted.error) throw new Error(deleted.error.message);
+  console.log("deleted:", deleted.data);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sfutureapps/db-sdk",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "description": "SfutureApps JS SDK for ThinkPHP DB Gateway (MySQL)",
   "license": "MIT",
   "type": "module",

package/src/client.js

@@ -25,34 +25,64 @@ function getEnv(key, fallback = "") {
   return fallback;
 }
 
-// Only accept explicit API_URL (which also maps to NEXT_PUBLIC_API_URL / VITE_API_URL / REACT_APP_API_URL via getEnv)
-const API_URL = (getEnv("API_URL") || "").replace(/\/+$/, "");
-const API_KEY = getEnv("API_KEY") || "";
-const TOKEN_NAME = getEnv("TOKEN_NAME", "token") || "token";
-const IS_AUTH = String(getEnv("IS_AUTH") || "").toLowerCase();
-const REQUIRE_AUTH = [ "true", "1", "yes" ].includes(IS_AUTH);
+// --- Runtime configuration ---------------------------------------------------
+// Defaults come from env so existing apps keep working.
+const defaultBaseUrl = (getEnv("API_URL") || "").replace(/\/+$/, "");
+const defaultApiKey = getEnv("API_KEY") || "";
+const defaultTokenName = getEnv("TOKEN_NAME", "token") || "token";
+const defaultIsAuth = String(getEnv("IS_AUTH") || "").toLowerCase();
+const defaultRequireAuth = [ "true", "1", "yes" ].includes(defaultIsAuth);
 
 // If you never want token on GET, set INCLUDE_TOKEN_IN_GET=false explicitly.
-const INCLUDE_TOKEN_IN_GET = String(getEnv("INCLUDE_TOKEN_IN_GET", "true")).toLowerCase();
-const ADD_TOKEN_TO_GET = [ "true", "1", "yes" ].includes(INCLUDE_TOKEN_IN_GET);
-
-if (!API_URL) {
-  throw new Error(
-    "API_URL is required. For Vite use VITE_API_URL, for Next use NEXT_PUBLIC_API_URL, for CRA use REACT_APP_API_URL."
-  );
+const defaultIncludeTokenInGet = String(getEnv("INCLUDE_TOKEN_IN_GET", "true")).toLowerCase();
+const defaultAddTokenToGet = [ "true", "1", "yes" ].includes(defaultIncludeTokenInGet);
+
+const clientConfig = {
+  baseUrl: defaultBaseUrl,
+  apiKey: defaultApiKey,
+  tokenName: defaultTokenName,
+  requireAuth: defaultRequireAuth,
+  addTokenToGet: defaultAddTokenToGet,
+  accessToken: null,
+  headers: {},
+};
+
+export function configureClient(opts = {}) {
+  if (!opts || typeof opts !== "object") return;
+
+  if (typeof opts.baseUrl === "string") {
+    clientConfig.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  }
+  if (typeof opts.apiKey === "string") {
+    clientConfig.apiKey = opts.apiKey;
+  }
+  if (typeof opts.accessToken === "function") {
+    clientConfig.accessToken = opts.accessToken;
+  }
+  if (opts.headers && typeof opts.headers === "object") {
+    clientConfig.headers = { ...opts.headers };
+  }
 }
 
 // --- Utilities ---------------------------------------------------------------
 
 export function getToken() {
+  // Prefer explicit token provider (supports SSR + custom storage)
+  try {
+    if (typeof clientConfig.accessToken === "function") {
+      const t = clientConfig.accessToken();
+      if (t) return String(t);
+    }
+  } catch (_) { }
+
   try {
     if (typeof window !== "undefined" && window.localStorage) {
-      const t = window.localStorage.getItem(TOKEN_NAME);
+      const t = window.localStorage.getItem(clientConfig.tokenName);
       if (t) return t;
     }
   } catch (_) { }
   // Fallback (SSR): allow env var named as TOKEN_NAME to carry the value
-  const fromEnv = getEnv(TOKEN_NAME, "");
+  const fromEnv = getEnv(clientConfig.tokenName, "");
   return fromEnv || "";
 }
 
@@ -78,7 +108,12 @@ export function toForm(data) {
  * - Accepts endpoint with or without leading slash.
  */
 export function buildUrl(endpoint = "", params) {
-  const base = API_URL.replace(/\/+$/, ""); // trim trailing slashes
+  const base = String(clientConfig.baseUrl || "").replace(/\/+$/, ""); // trim trailing slashes
+  if (!base) {
+    throw new Error(
+      "Base URL is required. Pass it to createClient(baseUrl) or set API_URL (VITE_API_URL / NEXT_PUBLIC_API_URL / REACT_APP_API_URL)."
+    );
+  }
   const ep = String(endpoint || "").replace(/^\/+/, ""); // trim leading slashes
   const full = ep ? `${base}/${ep}` : base;
   const url = new URL(full);
@@ -129,15 +164,16 @@ export async function get({ endpoint, params } = {}) {
   // console.log("GET", url.toString());
 
 
-  if (REQUIRE_AUTH && ADD_TOKEN_TO_GET) {
+  if (clientConfig.requireAuth && clientConfig.addTokenToGet) {
     const token = getToken();
-    if (!token) throw new Error(`Auth required but token '${TOKEN_NAME}' not found`);
+    if (!token) throw new Error(`Auth required but token '${clientConfig.tokenName}' not found`);
     url.searchParams.set("token", token);
   }
 
   const headers = {
     Accept: "application/json",
-    ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+    ...(clientConfig.apiKey ? { "X-API-Key": clientConfig.apiKey } : {}),
+    ...(clientConfig.headers || {}),
   };
 
   return httpFetch(url.toString(), { method: "POST", headers });
@@ -162,14 +198,15 @@ export default async function post({ endpoint, data, params } = {}) {
 
   const headers = {
     "Content-Type": "application/x-www-form-urlencoded",
-    ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+    ...(clientConfig.apiKey ? { "X-API-Key": clientConfig.apiKey } : {}),
+    ...(clientConfig.headers || {}),
   };
 
   const bodyObj = { ...(data || {}) };
 
-  if (REQUIRE_AUTH) {
+  if (clientConfig.requireAuth) {
     const token = getToken();
-    if (!token) throw new Error(`Auth required but token '${TOKEN_NAME}' not found`);
+    if (!token) throw new Error(`Auth required but token '${clientConfig.tokenName}' not found`);
     bodyObj.token = token;
   }
 

package/src/index.js

@@ -1,6 +1,8 @@
 import { QueryBuilder } from "./query-builder.js";
+import { configureClient } from "./client.js";
 
 export function createClient(baseUrl, opts = {}) {
+  configureClient({ baseUrl, ...opts });
   return {
     from(table) {
       return new QueryBuilder(table);

package/src/query-builder.js

@@ -200,7 +200,7 @@ export class QueryBuilder {
     }
     return post({
       endpoint: "v3/api/update",
-      data: { table: this.tableName, values, filters: this._filters }
+      data: { table: this.tableName, values, filters: JSON.stringify(this._filters) }
     });
   }
 
@@ -210,7 +210,7 @@ export class QueryBuilder {
     }
     return post({
       endpoint: "v3/api/delete",
-      data: { table: this.tableName, filters: this._filters }
+      data: { table: this.tableName, filters: JSON.stringify(this._filters) }
     });
   }
 }