@giaeulate/baas-sdk 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 1.3.0 — 2026-06-04
+
+Backward-compatible additions + two dead-route fixes. Validated end-to-end (33 live checks) against a running golang-baas server.
+
+### Added
+
+- **`client.rpc(fn, params, { get })`** — invoke PL/pgSQL functions (PostgREST `.rpc()` parity), POST or GET.
+- **QueryBuilder**: `upsert(data, onConflict)`, `count()` (via `Prefer: count=exact` → `Content-Range`), `contains`/`containedBy`/`overlaps` (cs/cd/ov array ops), `textSearch` (fts/plfts/phfts/wfts), and `and`/`notAnd`/`notOr` logic groups.
+- **Auth**: `signInAnonymous()`, `requestOtp(email, createUser?)`, `verifyOtp(type, email, token)`, `upgradeAnonymous(email, password)`.
+- **Storage**: `download(fileId)` → `Blob` (streams via the backend download route; sends the Bearer so private-bucket files work).
+- HTTP errors now surface `status`, and 429 responses include `{ rateLimited, retryAfter }`.
+
+### Fixed
+
+- `functions.update()` no longer calls a non-existent `PUT /api/functions/{id}`; it upserts by name (`POST /api/functions`, the backend's `ON CONFLICT (name)`).
+- `graphql.getSchema()` no longer hits a non-existent `GET /api/graphql/schema`; it runs introspection through `POST /api/graphql`.
+
+### Changed
+
+- Removed the unused `axios` dependency — the SDK now has **zero runtime dependencies** (native `fetch`).
+
+## 1.2.0
+
+- Previous release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gianluca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @giaeulate/baas-sdk
+
+TypeScript SDK for [golang-baas](https://github.com/Giaeulate/golang-baas) — a Supabase-style Backend-as-a-Service. Auth, data (PostgREST-style), storage, realtime, edge functions, RPC, and the admin APIs. **Zero runtime dependencies** (native `fetch` + `WebSocket`).
+
+## Install
+
+```bash
+bun add @giaeulate/baas-sdk
+# or: pnpm add @giaeulate/baas-sdk
+```
+
+## Quick start
+
+```ts
+import { BaasClient } from '@giaeulate/baas-sdk';
+
+const baas = new BaasClient('https://your-baas.example.com', 'YOUR_ANON_KEY');
+
+// Auth
+await baas.auth.login('user@example.com', 'password');
+await baas.auth.signInAnonymous();
+
+// Data (PostgREST-style)
+const { data } = await baas.from('orders')
+  .select('id,total,status')
+  .eq('status', 'pending')
+  .gt('total', 100)
+  .order('created_at', { ascending: false })
+  .get();
+
+// Logic groups, array & full-text operators
+await baas.from('products').and('price.gt.10,price.lt.50').get();
+await baas.from('products').contains('tags', ['featured']).get();
+
+// Count (Content-Range)
+const { count } = await baas.from('orders').eq('status', 'pending').count();
+
+// Upsert
+await baas.from('settings').upsert({ id: 1, theme: 'dark' }, 'id');
+
+// RPC (PL/pgSQL)
+const result = await baas.rpc('accept_delivery_offer', { offer_id: '...' });
+
+// Storage
+const file = await baas.storage.upload(myFile, 'bucket-id');
+const blob = await baas.storage.download(file.id);
+
+// Realtime
+await baas.realtime.subscribe('orders', 'insert', (evt) => console.log(evt));
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+// src/cli/config.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+function getArg(argv, name) {
+  const idx = argv.indexOf(`--${name}`);
+  return idx !== -1 && idx + 1 < argv.length ? argv[idx + 1] : null;
+}
+function hasFlag(argv, name) {
+  return argv.includes(`--${name}`);
+}
+function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  const content = readFileSync(path, "utf-8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const val = trimmed.slice(eq + 1).trim();
+    if ((key === "VITE_BAAS_URL" || key === "BAAS_URL") && !process.env.BAAS_URL) {
+      process.env.BAAS_URL = val;
+    }
+    if ((key === "VITE_BAAS_API_KEY" || key === "BAAS_API_KEY") && !process.env.BAAS_API_KEY) {
+      process.env.BAAS_API_KEY = val;
+    }
+  }
+}
+function resolveConfig(argv) {
+  const migrationsDir = resolve(
+    getArg(argv, "dir") || process.env.BAAS_MIGRATIONS_DIR || process.cwd()
+  );
+  const candidates = [
+    resolve(process.cwd(), ".env"),
+    resolve(migrationsDir, "../../react-delivery-platform-admin-web/.env"),
+    resolve(process.cwd(), "../../react-delivery-platform-admin-web/.env"),
+    resolve(process.cwd(), "../react-delivery-platform-admin-web/.env"),
+    resolve(migrationsDir, ".env"),
+    resolve(migrationsDir, "../.env")
+  ];
+  for (const c of candidates) loadEnvFile(c);
+  const baasUrl = getArg(argv, "url") || process.env.BAAS_URL || "";
+  const token = getArg(argv, "token") || process.env.BAAS_API_KEY || "";
+  return { baasUrl, token, migrationsDir };
+}
+
+// src/cli/client.ts
+function msg(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var isPoisoned = (m) => /401|invalid or expired token/i.test(m);
+function createSqlClient(baasUrl, token) {
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+  const endpoint = `${baasUrl.replace(/\/$/, "")}/api/v1/sql`;
+  async function runSQL(sql, params) {
+    const body = { query: sql };
+    if (params && params.length > 0) body.params = params;
+    let res;
+    try {
+      res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      const cause = err?.cause;
+      const detail = cause ? ` (cause: ${cause.code || cause.message})` : "";
+      throw new Error(`Network failure: ${msg(err)}${detail}`);
+    }
+    const text = await res.text();
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${text}`);
+    return text;
+  }
+  async function runSQLResilient(sql, params) {
+    const maxAttempts = 8;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await runSQL(sql, params);
+      } catch (err) {
+        lastErr = err;
+        if (isPoisoned(msg(err)) && attempt < maxAttempts) {
+          process.stdout.write(`    (401 pool poisoned, retry ${attempt}/${maxAttempts - 1})
+`);
+          await sleep(400 * attempt);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastErr;
+  }
+  async function preflight() {
+    const maxAttempts = 6;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await runSQL("SELECT 1 AS ok");
+        return;
+      } catch (err) {
+        const poisoned = isPoisoned(msg(err));
+        if (poisoned && attempt < maxAttempts) {
+          await sleep(500 * attempt);
+          continue;
+        }
+        if (poisoned) {
+          throw new Error(
+            `${msg(err)}
+  -> Persistent 401. Do NOT regenerate the key (it is valid).
+     Cause: BaaS pool holding a connection in an aborted transaction.
+     Deterministic fix: restart the BaaS container to clear the pool.`
+          );
+        }
+        throw err;
+      }
+    }
+  }
+  return { runSQL, runSQLResilient, preflight };
+}
+
+// src/cli/migrations.ts
+import { createHash } from "crypto";
+import { readFileSync as readFileSync2, readdirSync, existsSync as existsSync2, writeFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+var MIGRATION_RE = /^(\d{3,})_(.+)\.sql$/;
+var SEED_FILE = "005_seed.sql";
+var TRACKING_TABLE = "public.schema_migrations";
+var BENIGN_RE = /already exists|duplicate entry|duplicate key|SQLSTATE 42710|SQLSTATE 42P07|SQLSTATE 42701|SQLSTATE 42P06|SQLSTATE 42723|SQLSTATE 23505|HTTP 409/i;
+function discover(dir, includeSeed = false) {
+  if (!existsSync2(dir)) throw new Error(`Migrations dir not found: ${dir}`);
+  return readdirSync(dir).filter((f) => MIGRATION_RE.test(f)).filter((f) => includeSeed || f !== SEED_FILE).sort().map((f) => {
+    const m = MIGRATION_RE.exec(f);
+    return { file: f, version: m[1], name: m[2], path: resolve2(dir, f) };
+  });
+}
+function checksum(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function fileKey(version, name) {
+  return `${version}_${name}.sql`;
+}
+function slugify(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function nextVersion(files) {
+  let max = 0;
+  for (const f of files) {
+    const n = parseInt(f.version, 10);
+    if (n > max) max = n;
+  }
+  return String(max + 1).padStart(3, "0");
+}
+async function ensureTrackingTable(client) {
+  await client.runSQLResilient(
+    `CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+      version    text NOT NULL,
+      name       text NOT NULL,
+      checksum   text NOT NULL,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    );
+    DO $$
+    BEGIN
+      IF EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'schema_migrations_pkey'
+          AND conrelid = '${TRACKING_TABLE}'::regclass
+      ) THEN
+        ALTER TABLE ${TRACKING_TABLE} DROP CONSTRAINT schema_migrations_pkey;
+      END IF;
+    END $$;
+    CREATE UNIQUE INDEX IF NOT EXISTS schema_migrations_version_name_key
+      ON ${TRACKING_TABLE} (version, name);`
+  );
+}
+async function getApplied(client) {
+  const body = await client.runSQLResilient(
+    `SELECT version, name, checksum FROM ${TRACKING_TABLE} ORDER BY version`
+  );
+  const parsed = JSON.parse(body);
+  const rows = Array.isArray(parsed.data) ? parsed.data : [];
+  const map = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const version = String(r.version);
+    const name = String(r.name ?? "");
+    map.set(fileKey(version, name), { version, name, checksum: String(r.checksum) });
+  }
+  return map;
+}
+async function recordApplied(client, m, sum) {
+  await client.runSQL(
+    `INSERT INTO ${TRACKING_TABLE} (version, name, checksum)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (version, name) DO NOTHING`,
+    [m.version, m.name, sum]
+  );
+}
+function dbNew(dir, rawName) {
+  if (!rawName) throw new Error("Usage: baas db new <name>");
+  const all = discover(dir, true);
+  const version = nextVersion(all);
+  const slug = slugify(rawName) || "migration";
+  const file = `${version}_${slug}.sql`;
+  const path = resolve2(dir, file);
+  if (existsSync2(path)) throw new Error(`Already exists: ${file}`);
+  const header = `-- ${file}
+-- Created ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+-- Apply with: baas db push
+
+`;
+  writeFileSync(path, header, "utf8");
+  return file;
+}
+async function dbStatus(client, dir, includeSeed) {
+  await ensureTrackingTable(client);
+  const applied = await getApplied(client);
+  const files = discover(dir, includeSeed);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const f of files) {
+    seen.add(f.file);
+    const a = applied.get(f.file);
+    if (!a) {
+      out.push({ version: f.version, file: f.file, state: "pending" });
+    } else if (a.checksum !== checksum(readFileSync2(f.path, "utf8"))) {
+      out.push({ version: f.version, file: f.file, state: "drift" });
+    } else {
+      out.push({ version: f.version, file: f.file, state: "applied" });
+    }
+  }
+  for (const [key, a] of applied) {
+    if (!seen.has(key)) {
+      out.push({ version: a.version, file: `${key} (missing)`, state: "orphan" });
+    }
+  }
+  out.sort((x, y) => x.version.localeCompare(y.version));
+  return out;
+}
+async function dbPush(client, dir, opts) {
+  await ensureTrackingTable(client);
+  const applied = await getApplied(client);
+  const files = discover(dir, !!opts.includeSeed);
+  const pending = files.filter((f) => !applied.has(f.file));
+  if (opts.dryRun) {
+    return { applied: [], skipped: [], pending: pending.map((f) => f.file) };
+  }
+  const result = { applied: [], skipped: [], pending: [] };
+  for (const f of pending) {
+    const content = readFileSync2(f.path, "utf8");
+    process.stdout.write(`  Applying ${f.file} (${content.length} chars)...
+`);
+    try {
+      await client.runSQLResilient(content);
+      await recordApplied(client, f, checksum(content));
+      result.applied.push(f.file);
+      process.stdout.write(`  OK ${f.file}
+`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!opts.strict && BENIGN_RE.test(message)) {
+        await recordApplied(client, f, checksum(content));
+        result.skipped.push(f.file);
+        process.stdout.write(`  SKIP ${f.file} (already applied) -> recorded
+`);
+        continue;
+      }
+      throw new Error(`FAIL ${f.file}: ${message}`);
+    }
+  }
+  return result;
+}
+async function dbBaseline(client, dir, opts) {
+  await ensureTrackingTable(client);
+  const applied = await getApplied(client);
+  const files = discover(dir, !!opts.includeSeed);
+  const throughNum = opts.through ? parseInt(opts.through, 10) : null;
+  const marked = [];
+  for (const f of files) {
+    if (throughNum !== null && parseInt(f.version, 10) > throughNum) continue;
+    if (applied.has(f.file)) continue;
+    await recordApplied(client, f, checksum(readFileSync2(f.path, "utf8")));
+    marked.push(f.file);
+  }
+  return marked;
+}
+
+// src/cli/index.ts
+var HELP = `baas \u2014 migration CLI for golang-baas
+
+Usage:
+  baas db new <name>        Scaffold the next NNN_<name>.sql migration
+  baas db status            Show applied / pending / drift / orphan per file
+  baas db list              Alias of status
+  baas db push              Apply pending migrations and record them
+  baas db baseline          Mark existing files as applied without running them
+
+Options:
+  --dir <path>     Migrations directory (default: cwd or BAAS_MIGRATIONS_DIR)
+  --url <url>      BaaS URL (default: BAAS_URL / .env)
+  --token <key>    API key (default: BAAS_API_KEY / .env)
+  --dry-run        push: list pending without applying
+  --strict         push: halt on any error (no benign "already exists" skip)
+  --through <NNN>  baseline: only mark files up to and including version NNN
+  --seed           include 005_seed.sql in discovery
+
+Credentials resolve from flags, then env (BAAS_URL/BAAS_API_KEY), then a .env
+file (supports VITE_BAAS_URL/VITE_BAAS_API_KEY).`;
+function printStatus(rows) {
+  const counts = { applied: 0, pending: 0, drift: 0, orphan: 0 };
+  for (const r of rows) {
+    counts[r.state]++;
+    console.log(`  ${r.state.toUpperCase().padEnd(7)} ${r.file}`);
+  }
+  if (rows.length === 0) console.log("  (no migration files found)");
+  console.log(
+    `
+${counts.applied} applied, ${counts.pending} pending, ${counts.drift} drift, ${counts.orphan} orphan.`
+  );
+  if (counts.drift > 0) {
+    console.log("\nWARNING: drift = a tracked file changed since it was applied.");
+  }
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const group = argv[0];
+  const sub = argv[1];
+  if (!group || group === "help" || group === "--help" || group === "-h") {
+    console.log(HELP);
+    return;
+  }
+  if (group !== "db") {
+    console.error(`Unknown command: ${group}
+`);
+    console.log(HELP);
+    process.exit(1);
+  }
+  const cfg = resolveConfig(argv);
+  const includeSeed = hasFlag(argv, "seed");
+  if (sub === "new") {
+    const positional = argv[2] && !argv[2].startsWith("--") ? argv[2] : "";
+    const name = positional || getArg(argv, "name") || "";
+    const file = dbNew(cfg.migrationsDir, name);
+    console.log(`Created ${file} in ${cfg.migrationsDir}`);
+    return;
+  }
+  if (!cfg.baasUrl || !cfg.token) {
+    console.error(
+      "ERROR: missing BaaS URL or token.\n  Provide --url/--token, set BAAS_URL/BAAS_API_KEY, or have a .env nearby."
+    );
+    process.exit(1);
+  }
+  console.log(`BaaS:  ${cfg.baasUrl}`);
+  console.log(`Dir:   ${cfg.migrationsDir}`);
+  console.log(`Token: ${cfg.token.slice(0, 16)}...
+`);
+  const client = createSqlClient(cfg.baasUrl, cfg.token);
+  switch (sub) {
+    case "status":
+    case "list": {
+      await client.preflight();
+      printStatus(await dbStatus(client, cfg.migrationsDir, includeSeed));
+      break;
+    }
+    case "push": {
+      const dryRun = hasFlag(argv, "dry-run");
+      await client.preflight();
+      const res = await dbPush(client, cfg.migrationsDir, {
+        dryRun,
+        includeSeed,
+        strict: hasFlag(argv, "strict")
+      });
+      if (dryRun) {
+        if (res.pending.length === 0) {
+          console.log("No pending migrations.");
+        } else {
+          console.log(`Pending (${res.pending.length}):`);
+          res.pending.forEach((f) => console.log(`  ${f}`));
+        }
+      } else if (res.applied.length === 0 && res.skipped.length === 0) {
+        console.log("No pending migrations.");
+      } else {
+        console.log(`
+Applied ${res.applied.length}, skipped ${res.skipped.length}.`);
+      }
+      break;
+    }
+    case "baseline": {
+      await client.preflight();
+      const marked = await dbBaseline(client, cfg.migrationsDir, {
+        through: getArg(argv, "through") || void 0,
+        includeSeed
+      });
+      if (marked.length === 0) {
+        console.log("Nothing to baseline (all discovered files already tracked).");
+      } else {
+        console.log(`Baselined ${marked.length} file(s) as applied (not executed):`);
+        marked.forEach((f) => console.log(`  ${f}`));
+      }
+      break;
+    }
+    default:
+      console.error(`Unknown db subcommand: ${sub ?? "(none)"}
+`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(`
+${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});