@surf-ai/sdk 1.0.0-alpha.0 → 1.0.0-alpha.10

package/README.md

@@ -14,7 +14,7 @@ SDK 1.0 uses a single direct-auth model.
 
 | Env Var | Default | Purpose |
 | --- | --- | --- |
-| `SURF_API_BASE_URL` | `https://api.ask.surf/gateway/v1` | Full Surf API base URL |
+| `SURF_API_BASE_URL` | `https://api.asksurf.ai/gateway/v1` | Full Surf API base URL |
 | `SURF_API_KEY` | none | Bearer token used for upstream requests and protected runtime endpoints |
 | `PORT` | none | Express server port when `createServer({ port })` is not provided |
 

package/dist/db/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/db/index.ts
@@ -24,12 +34,14 @@ __export(db_exports, {
   dbQuery: () => dbQuery,
   dbStatus: () => dbStatus,
   dbTableSchema: () => dbTableSchema,
-  dbTables: () => dbTables
+  dbTables: () => dbTables,
+  syncSchema: () => syncSchema,
+  watchSchema: () => watchSchema
 });
 module.exports = __toCommonJS(db_exports);
 
 // src/core/config.ts
-var DEFAULT_API_BASE_URL = "https://api.ask.surf/gateway/v1";
+var DEFAULT_API_BASE_URL = "https://api.asksurf.ai/gateway/v1";
 function trimTrailingSlashes(value) {
   return String(value || "").replace(/\/+$/, "");
 }
@@ -112,9 +124,148 @@ async function post(path, body) {
   return postJson(path, body);
 }
 
+// src/db/schema-sync.ts
+var import_fs = __toESM(require("fs"), 1);
+var syncing = false;
+async function syncSchema(options) {
+  const { schemaPath, retries = 3, retryDelay = 2e3 } = options;
+  for (let i = 0; i < retries; i++) {
+    try {
+      await doSyncSchema(schemaPath);
+      return;
+    } catch (err) {
+      console.error(`DB schema sync attempt ${i + 1}/${retries} failed: ${err.message}`);
+      if (i < retries - 1) await new Promise((r) => setTimeout(r, retryDelay * (i + 1)));
+    }
+  }
+  console.error("DB schema sync failed after all retries");
+}
+async function doSyncSchema(schemaPath) {
+  if (syncing) return;
+  syncing = true;
+  try {
+    if (!import_fs.default.existsSync(schemaPath)) return;
+    let schema;
+    if (schemaPath.endsWith(".ts")) {
+      try {
+        schema = await import(`${schemaPath}?t=${Date.now()}`);
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          console.log("DB: schema file has syntax error, waiting for next change...");
+          return;
+        }
+        if (err.message.includes("Cannot find module") || err.message.includes("is not a function")) {
+          return;
+        }
+        throw err;
+      }
+    } else {
+      try {
+        delete require.cache[require.resolve(schemaPath)];
+      } catch {
+      }
+      try {
+        schema = require(schemaPath);
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          console.log("DB: schema file has syntax error, waiting for next change...");
+          return;
+        }
+        if (err.message.includes("Cannot find module") || err.message.includes("is not a function")) {
+          return;
+        }
+        throw err;
+      }
+    }
+    let getTableConfig;
+    try {
+      getTableConfig = require("drizzle-orm/pg-core").getTableConfig;
+    } catch {
+      return;
+    }
+    const tables = Object.values(schema).filter(
+      (t) => t && typeof t === "object" && /* @__PURE__ */ Symbol.for("drizzle:Name") in t
+    );
+    if (tables.length === 0) return;
+    await post("db/provision", {});
+    const tablesResult = await get("db/tables");
+    const tablesList = Array.isArray(tablesResult) ? tablesResult : tablesResult.tables || [];
+    const existing = tablesList.map((t) => typeof t === "string" ? t : t.name);
+    const missing = tables.filter((t) => !existing.includes(getTableConfig(t).name));
+    if (missing.length > 0) {
+      const { generateDrizzleJson, generateMigration } = require("drizzle-kit/api");
+      const missingSchema = {};
+      for (const t of missing) missingSchema[getTableConfig(t).name] = t;
+      const sqls = await generateMigration(generateDrizzleJson({}), generateDrizzleJson(missingSchema));
+      for (const sql of sqls) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          try {
+            await post("db/query", { sql, params: [] });
+            console.log(`DB: Executed: ${sql.slice(0, 80)}...`);
+            break;
+          } catch (err) {
+            if (attempt === 0) {
+              console.warn(`DB: Retrying after: ${err.message}`);
+              await new Promise((r) => setTimeout(r, 1500));
+            } else {
+              console.error(`DB: Failed: ${sql.slice(0, 80)}... \u2014 ${err.message}`);
+            }
+          }
+        }
+      }
+    }
+    const existingTables = tables.filter((t) => existing.includes(getTableConfig(t).name));
+    for (const t of existingTables) {
+      const cfg = getTableConfig(t);
+      try {
+        const live = await get("db/table-schema", { table: cfg.name });
+        const liveCols = new Set((live.columns || []).map((c) => c.name));
+        for (const col of cfg.columns) {
+          if (!liveCols.has(col.name)) {
+            const colType = col.getSQLType();
+            const ddl = `ALTER TABLE "${cfg.name}" ADD COLUMN IF NOT EXISTS "${col.name}" ${colType}`;
+            try {
+              await post("db/query", { sql: ddl, params: [] });
+              console.log(`DB: Added column ${col.name} to ${cfg.name}`);
+            } catch (err) {
+              console.warn(`DB: Failed to add column ${col.name} to ${cfg.name}: ${err.message}`);
+            }
+          }
+        }
+      } catch (err) {
+        console.warn(`DB: Column check failed for ${cfg.name}: ${err.message}`);
+      }
+    }
+  } finally {
+    syncing = false;
+  }
+}
+function watchSchema(schemaPath, options) {
+  const { debounceMs = 1e3, retries = 2, retryDelay = 1500 } = options || {};
+  if (!import_fs.default.existsSync(schemaPath)) return () => {
+  };
+  let debounce = null;
+  import_fs.default.watchFile(schemaPath, { interval: 2e3 }, () => {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(async () => {
+      console.log("DB: schema file changed, re-syncing tables...");
+      try {
+        await syncSchema({ schemaPath, retries, retryDelay });
+        console.log("DB: schema re-sync complete");
+      } catch (err) {
+        console.error(`DB: schema re-sync failed: ${err.message}`);
+      }
+    }, debounceMs);
+  });
+  return () => {
+    import_fs.default.unwatchFile(schemaPath);
+    if (debounce) clearTimeout(debounce);
+  };
+}
+
 // src/db/index.ts
 async function dbProvision() {
-  return post("db/provision");
+  return post("db/provision", {});
 }
 async function dbQuery(sql, params, options) {
   return post("db/query", { sql, params, arrayMode: options?.arrayMode ?? false });
@@ -134,5 +285,7 @@ async function dbStatus() {
   dbQuery,
   dbStatus,
   dbTableSchema,
-  dbTables
+  dbTables,
+  syncSchema,
+  watchSchema
 });

package/dist/db/index.d.cts

@@ -1,3 +1,36 @@
+/**
+ * Shared schema sync logic — used by both Express runtime (createServer)
+ * and Next.js template (instrumentation.ts).
+ *
+ * Reads a Drizzle schema file, provisions the database, creates missing
+ * tables, and adds missing columns to existing tables.
+ */
+interface SchemaSyncOptions {
+    /** Path to the schema file (e.g., 'db/schema.js' or 'db/schema.ts') */
+    schemaPath: string;
+    /** Number of retries on failure (default: 3) */
+    retries?: number;
+    /** Base delay between retries in ms (default: 2000) */
+    retryDelay?: number;
+}
+/**
+ * Sync a Drizzle schema file to the database.
+ *
+ * - Provisions the database via the Surf proxy
+ * - Creates missing tables using drizzle-kit DDL generation
+ * - Adds missing columns to existing tables via ALTER TABLE
+ */
+declare function syncSchema(options: SchemaSyncOptions): Promise<void>;
+/**
+ * Watch a schema file for changes and re-sync on edit.
+ * Returns a cleanup function to stop watching.
+ */
+declare function watchSchema(schemaPath: string, options?: {
+    debounceMs?: number;
+    retries?: number;
+    retryDelay?: number;
+}): () => void;
+
 /**
  * @surf-ai/sdk/db — Drizzle ORM + Neon PostgreSQL database helpers.
  *
@@ -12,6 +45,7 @@
  *   // Raw SQL:
  *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
+
 /**
  * Provision a database for the current user via db/provision.
  * Returns connection metadata. Neon auto-creates the DB if it doesn't exist.
@@ -48,4 +82,4 @@ declare function dbStatus(): Promise<{
     database?: string;
 }>;
 
-export { dbProvision, dbQuery, dbStatus, dbTableSchema, dbTables };
+export { type SchemaSyncOptions, dbProvision, dbQuery, dbStatus, dbTableSchema, dbTables, syncSchema, watchSchema };

package/dist/db/index.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Shared schema sync logic — used by both Express runtime (createServer)
+ * and Next.js template (instrumentation.ts).
+ *
+ * Reads a Drizzle schema file, provisions the database, creates missing
+ * tables, and adds missing columns to existing tables.
+ */
+interface SchemaSyncOptions {
+    /** Path to the schema file (e.g., 'db/schema.js' or 'db/schema.ts') */
+    schemaPath: string;
+    /** Number of retries on failure (default: 3) */
+    retries?: number;
+    /** Base delay between retries in ms (default: 2000) */
+    retryDelay?: number;
+}
+/**
+ * Sync a Drizzle schema file to the database.
+ *
+ * - Provisions the database via the Surf proxy
+ * - Creates missing tables using drizzle-kit DDL generation
+ * - Adds missing columns to existing tables via ALTER TABLE
+ */
+declare function syncSchema(options: SchemaSyncOptions): Promise<void>;
+/**
+ * Watch a schema file for changes and re-sync on edit.
+ * Returns a cleanup function to stop watching.
+ */
+declare function watchSchema(schemaPath: string, options?: {
+    debounceMs?: number;
+    retries?: number;
+    retryDelay?: number;
+}): () => void;
+
 /**
  * @surf-ai/sdk/db — Drizzle ORM + Neon PostgreSQL database helpers.
  *
@@ -12,6 +45,7 @@
  *   // Raw SQL:
  *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
+
 /**
  * Provision a database for the current user via db/provision.
  * Returns connection metadata. Neon auto-creates the DB if it doesn't exist.
@@ -48,4 +82,4 @@ declare function dbStatus(): Promise<{
     database?: string;
 }>;
 
-export { dbProvision, dbQuery, dbStatus, dbTableSchema, dbTables };
+export { type SchemaSyncOptions, dbProvision, dbQuery, dbStatus, dbTableSchema, dbTables, syncSchema, watchSchema };

package/dist/db/index.js

@@ -1,5 +1,12 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/core/config.ts
-var DEFAULT_API_BASE_URL = "https://api.ask.surf/gateway/v1";
+var DEFAULT_API_BASE_URL = "https://api.asksurf.ai/gateway/v1";
 function trimTrailingSlashes(value) {
   return String(value || "").replace(/\/+$/, "");
 }
@@ -82,9 +89,148 @@ async function post(path, body) {
   return postJson(path, body);
 }
 
+// src/db/schema-sync.ts
+import fs from "fs";
+var syncing = false;
+async function syncSchema(options) {
+  const { schemaPath, retries = 3, retryDelay = 2e3 } = options;
+  for (let i = 0; i < retries; i++) {
+    try {
+      await doSyncSchema(schemaPath);
+      return;
+    } catch (err) {
+      console.error(`DB schema sync attempt ${i + 1}/${retries} failed: ${err.message}`);
+      if (i < retries - 1) await new Promise((r) => setTimeout(r, retryDelay * (i + 1)));
+    }
+  }
+  console.error("DB schema sync failed after all retries");
+}
+async function doSyncSchema(schemaPath) {
+  if (syncing) return;
+  syncing = true;
+  try {
+    if (!fs.existsSync(schemaPath)) return;
+    let schema;
+    if (schemaPath.endsWith(".ts")) {
+      try {
+        schema = await import(`${schemaPath}?t=${Date.now()}`);
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          console.log("DB: schema file has syntax error, waiting for next change...");
+          return;
+        }
+        if (err.message.includes("Cannot find module") || err.message.includes("is not a function")) {
+          return;
+        }
+        throw err;
+      }
+    } else {
+      try {
+        delete __require.cache[__require.resolve(schemaPath)];
+      } catch {
+      }
+      try {
+        schema = __require(schemaPath);
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          console.log("DB: schema file has syntax error, waiting for next change...");
+          return;
+        }
+        if (err.message.includes("Cannot find module") || err.message.includes("is not a function")) {
+          return;
+        }
+        throw err;
+      }
+    }
+    let getTableConfig;
+    try {
+      getTableConfig = __require("drizzle-orm/pg-core").getTableConfig;
+    } catch {
+      return;
+    }
+    const tables = Object.values(schema).filter(
+      (t) => t && typeof t === "object" && /* @__PURE__ */ Symbol.for("drizzle:Name") in t
+    );
+    if (tables.length === 0) return;
+    await post("db/provision", {});
+    const tablesResult = await get("db/tables");
+    const tablesList = Array.isArray(tablesResult) ? tablesResult : tablesResult.tables || [];
+    const existing = tablesList.map((t) => typeof t === "string" ? t : t.name);
+    const missing = tables.filter((t) => !existing.includes(getTableConfig(t).name));
+    if (missing.length > 0) {
+      const { generateDrizzleJson, generateMigration } = __require("drizzle-kit/api");
+      const missingSchema = {};
+      for (const t of missing) missingSchema[getTableConfig(t).name] = t;
+      const sqls = await generateMigration(generateDrizzleJson({}), generateDrizzleJson(missingSchema));
+      for (const sql of sqls) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          try {
+            await post("db/query", { sql, params: [] });
+            console.log(`DB: Executed: ${sql.slice(0, 80)}...`);
+            break;
+          } catch (err) {
+            if (attempt === 0) {
+              console.warn(`DB: Retrying after: ${err.message}`);
+              await new Promise((r) => setTimeout(r, 1500));
+            } else {
+              console.error(`DB: Failed: ${sql.slice(0, 80)}... \u2014 ${err.message}`);
+            }
+          }
+        }
+      }
+    }
+    const existingTables = tables.filter((t) => existing.includes(getTableConfig(t).name));
+    for (const t of existingTables) {
+      const cfg = getTableConfig(t);
+      try {
+        const live = await get("db/table-schema", { table: cfg.name });
+        const liveCols = new Set((live.columns || []).map((c) => c.name));
+        for (const col of cfg.columns) {
+          if (!liveCols.has(col.name)) {
+            const colType = col.getSQLType();
+            const ddl = `ALTER TABLE "${cfg.name}" ADD COLUMN IF NOT EXISTS "${col.name}" ${colType}`;
+            try {
+              await post("db/query", { sql: ddl, params: [] });
+              console.log(`DB: Added column ${col.name} to ${cfg.name}`);
+            } catch (err) {
+              console.warn(`DB: Failed to add column ${col.name} to ${cfg.name}: ${err.message}`);
+            }
+          }
+        }
+      } catch (err) {
+        console.warn(`DB: Column check failed for ${cfg.name}: ${err.message}`);
+      }
+    }
+  } finally {
+    syncing = false;
+  }
+}
+function watchSchema(schemaPath, options) {
+  const { debounceMs = 1e3, retries = 2, retryDelay = 1500 } = options || {};
+  if (!fs.existsSync(schemaPath)) return () => {
+  };
+  let debounce = null;
+  fs.watchFile(schemaPath, { interval: 2e3 }, () => {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(async () => {
+      console.log("DB: schema file changed, re-syncing tables...");
+      try {
+        await syncSchema({ schemaPath, retries, retryDelay });
+        console.log("DB: schema re-sync complete");
+      } catch (err) {
+        console.error(`DB: schema re-sync failed: ${err.message}`);
+      }
+    }, debounceMs);
+  });
+  return () => {
+    fs.unwatchFile(schemaPath);
+    if (debounce) clearTimeout(debounce);
+  };
+}
+
 // src/db/index.ts
 async function dbProvision() {
-  return post("db/provision");
+  return post("db/provision", {});
 }
 async function dbQuery(sql, params, options) {
   return post("db/query", { sql, params, arrayMode: options?.arrayMode ?? false });
@@ -103,5 +249,7 @@ export {
   dbQuery,
   dbStatus,
   dbTableSchema,
-  dbTables
+  dbTables,
+  syncSchema,
+  watchSchema
 };