@tinycloud/sdk-services 2.4.0-beta.2 → 2.4.0

package/dist/index.js

@@ -67,6 +67,202 @@ function serviceError(code, message, service, options) {
   };
 }
 
+// src/debug.ts
+var DEBUG_FLAG = "TinyCloud_debug";
+var MAX_EVENTS = 1e3;
+function getGlobal() {
+  return globalThis;
+}
+function nowMs() {
+  const performanceNow = globalThis.performance?.now?.bind(globalThis.performance);
+  return typeof performanceNow === "function" ? performanceNow() : Date.now();
+}
+function isTrue(value) {
+  return value === true || value === "true" || value === "1";
+}
+function getProcessDebugFlag() {
+  const processLike = globalThis.process;
+  return processLike?.env?.[DEBUG_FLAG];
+}
+function isBrowserWindow() {
+  const global = getGlobal();
+  return global.window === globalThis;
+}
+function getLocalStorage() {
+  if (!isBrowserWindow()) {
+    return void 0;
+  }
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function getStoredDebugFlag() {
+  const storage = getLocalStorage();
+  if (!storage) {
+    return void 0;
+  }
+  try {
+    return storage.getItem(DEBUG_FLAG);
+  } catch {
+    return void 0;
+  }
+}
+function setStoredDebugFlag(enabled) {
+  const storage = getLocalStorage();
+  if (!storage) {
+    return;
+  }
+  try {
+    if (enabled) {
+      storage.setItem(DEBUG_FLAG, "true");
+    } else {
+      storage.removeItem(DEBUG_FLAG);
+    }
+  } catch {
+  }
+}
+function shouldStartEnabled() {
+  const global = getGlobal();
+  return isTrue(global[DEBUG_FLAG]) || isTrue(getStoredDebugFlag()) || isTrue(getProcessDebugFlag());
+}
+var TinyCloudDebugLogger = class {
+  constructor() {
+    this.enabled = shouldStartEnabled();
+    this.sequence = 0;
+    this.events = [];
+    this.maxEvents = MAX_EVENTS;
+  }
+  isEnabled() {
+    return this.enabled || isTrue(getGlobal()[DEBUG_FLAG]) || isTrue(getProcessDebugFlag());
+  }
+  enable(options = {}) {
+    this.enabled = true;
+    getGlobal()[DEBUG_FLAG] = true;
+    if (options.persist !== false) {
+      setStoredDebugFlag(true);
+    }
+    this.log("debug.enabled", { persisted: options.persist !== false });
+  }
+  disable(options = {}) {
+    this.log("debug.disabled", { persisted: options.persist !== false });
+    this.enabled = false;
+    getGlobal()[DEBUG_FLAG] = false;
+    if (options.persist !== false) {
+      setStoredDebugFlag(false);
+    }
+  }
+  clear() {
+    this.events = [];
+  }
+  getLogs() {
+    return [...this.events];
+  }
+  log(event, data, message) {
+    if (!this.isEnabled()) {
+      return void 0;
+    }
+    return this.record({
+      event,
+      data,
+      message,
+      level: "debug",
+      timestamp: Date.now(),
+      timestampIso: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  startTimer(event, data) {
+    if (!this.isEnabled()) {
+      return { stop: () => void 0 };
+    }
+    const startedAt = nowMs();
+    this.log(`${event}.start`, data);
+    return {
+      stop: (finishData) => {
+        const endedAt = nowMs();
+        return this.record({
+          event: `${event}.end`,
+          data: finishData,
+          durationMs: endedAt - startedAt,
+          startedAt,
+          endedAt,
+          level: "debug",
+          timestamp: Date.now(),
+          timestampIso: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    };
+  }
+  async timeAsync(event, operation, data) {
+    if (!this.isEnabled()) {
+      return operation();
+    }
+    const timer = this.startTimer(event, data);
+    try {
+      const result = await operation();
+      timer.stop({ ok: true });
+      return result;
+    } catch (error) {
+      timer.stop({ ok: false, error });
+      throw error;
+    }
+  }
+  time(event, operation, data) {
+    if (!this.isEnabled()) {
+      return operation();
+    }
+    const timer = this.startTimer(event, data);
+    try {
+      const result = operation();
+      timer.stop({ ok: true });
+      return result;
+    } catch (error) {
+      timer.stop({ ok: false, error });
+      throw error;
+    }
+  }
+  record(event) {
+    const debugEvent = {
+      ...event,
+      sequence: ++this.sequence
+    };
+    this.events.push(debugEvent);
+    if (this.events.length > this.maxEvents) {
+      this.events.splice(0, this.events.length - this.maxEvents);
+    }
+    try {
+      globalThis.console?.debug?.("[TinyCloud]", debugEvent.event, debugEvent);
+    } catch {
+    }
+    return debugEvent;
+  }
+};
+var tinyCloudDebugLogger = new TinyCloudDebugLogger();
+function enableTinyCloudDebug(options) {
+  tinyCloudDebugLogger.enable(options);
+  return tinyCloudDebugLogger;
+}
+function disableTinyCloudDebug(options) {
+  tinyCloudDebugLogger.disable(options);
+  return tinyCloudDebugLogger;
+}
+function getTinyCloudDebugLogs() {
+  return tinyCloudDebugLogger.getLogs();
+}
+function clearTinyCloudDebugLogs() {
+  tinyCloudDebugLogger.clear();
+}
+function installTinyCloudDebugGlobals() {
+  const global = getGlobal();
+  global.TinyCloudDebug = tinyCloudDebugLogger;
+  global.enableTinyCloudDebug = enableTinyCloudDebug;
+  global.disableTinyCloudDebug = disableTinyCloudDebug;
+  global.getTinyCloudDebugLogs = getTinyCloudDebugLogs;
+  global.clearTinyCloudDebugLogs = clearTinyCloudDebugLogs;
+}
+installTinyCloudDebugGlobals();
+
 // src/types.schema.ts
 import { z } from "zod";
 var ServiceErrorSchema = z.object({
@@ -308,9 +504,9 @@ var ServiceContext = class {
     this._services = /* @__PURE__ */ new Map();
     this._eventHandlers = /* @__PURE__ */ new Map();
     this._abortController = new AbortController();
-    this._invoke = config.invoke;
-    this._invokeAny = config.invokeAny;
-    this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this._invoke = this.wrapInvoke(config.invoke);
+    this._invokeAny = config.invokeAny ? this.wrapInvokeAny(config.invokeAny) : void 0;
+    this._fetch = this.wrapFetch(config.fetch ?? globalThis.fetch.bind(globalThis));
     this._hosts = config.hosts;
     this._session = config.session ?? null;
     this._retryPolicy = {
@@ -413,6 +609,7 @@ var ServiceContext = class {
    * @param data - Event data
    */
   emit(event, data) {
+    tinyCloudDebugLogger.log(event, data);
     if (this._telemetryEnabled && this._telemetryHandler) {
       try {
         this._telemetryHandler(event, data);
@@ -502,6 +699,77 @@ var ServiceContext = class {
   get retryPolicy() {
     return this._retryPolicy;
   }
+  wrapInvoke(invoke) {
+    return (session, service, path, action, facts) => {
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return invoke(session, service, path, action, facts);
+      }
+      const timer = tinyCloudDebugLogger.startTimer("sdk.invoke", {
+        service,
+        path,
+        action,
+        facts
+      });
+      try {
+        const result = invoke(session, service, path, action, facts);
+        timer.stop({ ok: true, service, path, action });
+        return result;
+      } catch (error) {
+        timer.stop({ ok: false, service, path, action, error });
+        throw error;
+      }
+    };
+  }
+  wrapInvokeAny(invokeAny) {
+    return (session, entries, facts) => {
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return invokeAny(session, entries, facts);
+      }
+      const timer = tinyCloudDebugLogger.startTimer("sdk.invokeAny", {
+        entries,
+        facts
+      });
+      try {
+        const result = invokeAny(session, entries, facts);
+        timer.stop({ ok: true, entries });
+        return result;
+      } catch (error) {
+        timer.stop({ ok: false, entries, error });
+        throw error;
+      }
+    };
+  }
+  wrapFetch(fetchFn) {
+    return async (url, init) => {
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return fetchFn(url, init);
+      }
+      const timer = tinyCloudDebugLogger.startTimer("sdk.fetch", {
+        url,
+        method: init?.method ?? "GET",
+        init
+      });
+      try {
+        const response = await fetchFn(url, init);
+        timer.stop({
+          ok: response.ok,
+          url,
+          method: init?.method ?? "GET",
+          status: response.status,
+          statusText: response.statusText
+        });
+        return response;
+      } catch (error) {
+        timer.stop({
+          ok: false,
+          url,
+          method: init?.method ?? "GET",
+          error
+        });
+        throw error;
+      }
+    };
+  }
 };
 
 // src/errors.ts
@@ -1687,11 +1955,59 @@ var KVService = class extends BaseService {
  */
 KVService.serviceName = "kv";
 
+// src/responseErrors.ts
+function parseServiceErrorBody(errorText) {
+  try {
+    return JSON.parse(errorText);
+  } catch {
+    return {};
+  }
+}
+function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
+  if (parsed.message) {
+    return compactMessage(parsed.message);
+  }
+  if (looksLikeHtml(errorText)) {
+    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
+      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
+    }
+    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
+  }
+  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
+}
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+function looksLikeHtml(text) {
+  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
+
+// src/sql/SQLMigrations.ts
+var SQLMigrations = class {
+  constructor(service, dbName) {
+    this.service = service;
+    this.dbName = dbName;
+  }
+  apply(options) {
+    return this.service.applyMigrationsOnDb(this.dbName, options);
+  }
+};
+
 // src/sql/DatabaseHandle.ts
 var DatabaseHandle = class {
   constructor(service, name) {
     this.service = service;
     this.name = name;
+    this.migrations = new SQLMigrations(service, name);
   }
   async query(sql, params, options) {
     return this.service.queryOnDb(this.name, sql, params, options);
@@ -1714,6 +2030,7 @@ var DatabaseHandle = class {
 var SQLAction = {
   READ: "tinycloud.sql/read",
   WRITE: "tinycloud.sql/write",
+  SCHEMA: "tinycloud.sql/schema",
   ADMIN: "tinycloud.sql/admin",
   SELECT: "tinycloud.sql/select",
   INSERT: "tinycloud.sql/insert",
@@ -1725,9 +2042,21 @@ var SQLAction = {
 };
 
 // src/sql/SQLService.ts
+var DDL_TOKENS = /* @__PURE__ */ new Set(["alter", "create", "drop"]);
+var MIGRATIONS_TABLE = "__tinycloud_sql_migrations";
+var MIGRATIONS_SCHEMA = `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+  key TEXT PRIMARY KEY,
+  namespace TEXT NOT NULL,
+  id TEXT NOT NULL,
+  applied_at TEXT NOT NULL,
+  statement_count INTEGER NOT NULL
+)`;
+var MIGRATIONS_META_NAMESPACE = "tinycloud.sql.migrations";
+var MIGRATIONS_META_ID = "000_metadata";
 var SQLService = class extends BaseService {
   constructor(config = {}) {
     super();
+    this.migrationLocks = /* @__PURE__ */ new Map();
     this._config = config;
   }
   get config() {
@@ -1763,6 +2092,24 @@ var SQLService = class extends BaseService {
   async batch(statements, options) {
     return this.batchOnDb(this.defaultDbName, statements, options);
   }
+  async applyMigrationsOnDb(dbName, options) {
+    const validationError = validateMigrationOptions(options);
+    if (validationError) {
+      return err(serviceError(ErrorCodes.INVALID_INPUT, validationError, "sql"));
+    }
+    const lockKey = `${dbName}\0${options.namespace}`;
+    const existing = this.migrationLocks.get(lockKey);
+    if (existing) {
+      return existing;
+    }
+    const promise = this.applyMigrationsOnDbUnlocked(dbName, options);
+    this.migrationLocks.set(lockKey, promise);
+    try {
+      return await promise;
+    } finally {
+      this.migrationLocks.delete(lockKey);
+    }
+  }
   // === Internal methods called by DatabaseHandle ===
   async queryOnDb(dbName, sql, params, options) {
     return this.withTelemetry("query", dbName, async () => {
@@ -1800,9 +2147,15 @@ var SQLService = class extends BaseService {
         if (options?.schema) {
           body.schema = options.schema;
         }
+        const actions = [
+          this.actionForSql(sql, SQLAction.WRITE),
+          ...(options?.schema ?? []).map(
+            (statement) => this.actionForSql(statement, SQLAction.SCHEMA)
+          )
+        ];
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSql(sql, SQLAction.WRITE),
+          this.dedupeActions(actions),
           body,
           options?.signal
         );
@@ -1824,7 +2177,7 @@ var SQLService = class extends BaseService {
       try {
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSqlBatch(statements),
+          this.actionsForSqlBatch(statements),
           { action: "batch", statements },
           options?.signal
         );
@@ -1887,10 +2240,83 @@ var SQLService = class extends BaseService {
       }
     });
   }
+  async applyMigrationsOnDbUnlocked(dbName, options) {
+    return this.withTelemetry("migrations.apply", dbName, async () => {
+      const created = await this.ensureMigrationsTable(dbName, options.signal);
+      if (!created.ok) return created;
+      const listed = await this.queryOnDb(
+        dbName,
+        `SELECT id FROM ${MIGRATIONS_TABLE} WHERE namespace = ? ORDER BY applied_at, id`,
+        [options.namespace],
+        { signal: options.signal }
+      );
+      if (!listed.ok) return listed;
+      const appliedIds = new Set(
+        listed.data.rows.map((row) => rowValue(row, 0)).filter((id) => typeof id === "string")
+      );
+      const skipped = options.migrations.filter((migration) => appliedIds.has(migration.id)).map((migration) => migration.id);
+      const pending = options.migrations.filter((migration) => !appliedIds.has(migration.id));
+      const applied = [];
+      for (const migration of pending) {
+        const result = await this.applyOneMigration(dbName, options.namespace, migration, options.signal);
+        if (!result.ok) return result;
+        applied.push(migration.id);
+      }
+      return ok({
+        database: dbName,
+        namespace: options.namespace,
+        status: applied.length > 0 ? "applied" : "already_current",
+        applied,
+        skipped
+      });
+    });
+  }
+  async applyOneMigration(dbName, namespace, migration, signal) {
+    const statements = [
+      ...migration.sql.map(
+        (statement) => typeof statement === "string" ? { sql: statement } : statement
+      ),
+      {
+        sql: `INSERT OR REPLACE INTO ${MIGRATIONS_TABLE} (key, namespace, id, applied_at, statement_count) VALUES (?, ?, ?, ?, ?)`,
+        params: [
+          migrationKey(namespace, migration.id),
+          namespace,
+          migration.id,
+          (/* @__PURE__ */ new Date()).toISOString(),
+          migration.sql.length
+        ]
+      }
+    ];
+    const result = await this.batchOnDb(dbName, statements, { signal });
+    if (!result.ok) return result;
+    return ok(void 0);
+  }
+  async ensureMigrationsTable(dbName, signal) {
+    const result = await this.batchOnDb(
+      dbName,
+      [
+        { sql: MIGRATIONS_SCHEMA },
+        {
+          sql: `INSERT OR REPLACE INTO ${MIGRATIONS_TABLE} (key, namespace, id, applied_at, statement_count) VALUES (?, ?, ?, ?, ?)`,
+          params: [
+            migrationKey(MIGRATIONS_META_NAMESPACE, MIGRATIONS_META_ID),
+            MIGRATIONS_META_NAMESPACE,
+            MIGRATIONS_META_ID,
+            (/* @__PURE__ */ new Date()).toISOString(),
+            1
+          ]
+        }
+      ],
+      { signal }
+    );
+    if (!result.ok) return result;
+    return ok(void 0);
+  }
   // === Private helpers ===
-  async invokeSQL(dbName, action, body, signal) {
+  async invokeSQL(dbName, actions, body, signal) {
     const session = this.context.session;
-    const headers = this.context.invoke(session, "sql", dbName, action);
+    const actionList = Array.isArray(actions) ? actions : [actions];
+    const headers = actionList.length === 1 ? this.context.invoke(session, "sql", dbName, actionList[0]) : this.invokeSQLAny(session, dbName, actionList);
     return this.context.fetch(`${this.host}/invoke`, {
       method: "POST",
       headers: {
@@ -1902,26 +2328,50 @@ var SQLService = class extends BaseService {
     });
   }
   actionForSql(sql, fallback) {
-    return firstSqlToken(sql) === "pragma" ? SQLAction.ADMIN : fallback;
+    const token = firstSqlToken(sql);
+    if (token === "pragma") return SQLAction.ADMIN;
+    if (token !== void 0 && DDL_TOKENS.has(token)) return SQLAction.SCHEMA;
+    return fallback;
+  }
+  actionsForSqlBatch(statements) {
+    return this.dedupeActions(
+      statements.map((statement) => this.actionForSql(statement.sql, SQLAction.WRITE))
+    );
   }
-  actionForSqlBatch(statements) {
-    return statements.some(
-      (statement) => this.actionForSql(statement.sql, SQLAction.WRITE) === SQLAction.ADMIN
-    ) ? SQLAction.ADMIN : SQLAction.WRITE;
+  dedupeActions(actions) {
+    return [...new Set(actions)];
+  }
+  invokeSQLAny(session, dbName, actions) {
+    if (!this.context.invokeAny) {
+      throw new Error(
+        `SQL operation requires multiple permissions (${actions.join(", ")}) but this SDK runtime does not support multi-resource invocations`
+      );
+    }
+    return this.context.invokeAny(
+      session,
+      actions.map((action) => ({
+        spaceId: session.spaceId,
+        service: "sql",
+        path: dbName,
+        action
+      }))
+    );
   }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
-    let errorBody = {};
-    try {
-      errorBody = JSON.parse(errorText);
-    } catch {
-    }
+    const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
       errorBody.error
     );
-    const message = errorBody.message || `SQL ${operation} failed: ${response.status} - ${errorText}`;
-    const meta = { status: response.status, statusText: response.statusText };
+    const message = formatServiceResponseError(
+      "SQL",
+      operation,
+      response.status,
+      errorText,
+      errorBody
+    );
+    const meta = responseErrorMeta(response.status, response.statusText, errorText);
     if (response.status === 401) {
       const { resource, action } = parseAuthError(errorText);
       if (action) meta.requiredAction = action;
@@ -1981,6 +2431,53 @@ function firstSqlToken(sql) {
   const match = /^[A-Za-z_]+/.exec(sql.slice(index));
   return match?.[0].toLowerCase();
 }
+function validateMigrationOptions(options) {
+  if (!options || typeof options !== "object") {
+    return "SQL migrations require options";
+  }
+  if (!options.namespace || typeof options.namespace !== "string") {
+    return "SQL migrations require a non-empty namespace";
+  }
+  if (!Array.isArray(options.migrations)) {
+    return "SQL migrations require an ordered migrations array";
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const migration of options.migrations) {
+    if (!migration.id || typeof migration.id !== "string") {
+      return "SQL migrations require every migration to have a non-empty id";
+    }
+    if (ids.has(migration.id)) {
+      return `Duplicate SQL migration id: ${migration.id}`;
+    }
+    ids.add(migration.id);
+    if (!Array.isArray(migration.sql)) {
+      return `SQL migration ${migration.id} requires a sql array`;
+    }
+    for (const statement of migration.sql) {
+      if (typeof statement === "string") {
+        if (statement.trim() === "") {
+          return `SQL migration ${migration.id} contains an empty statement`;
+        }
+        continue;
+      }
+      if (!statement || typeof statement.sql !== "string" || statement.sql.trim() === "") {
+        return `SQL migration ${migration.id} contains an invalid statement`;
+      }
+    }
+  }
+  return null;
+}
+function migrationKey(namespace, id) {
+  return `${encodeURIComponent(namespace)}:${encodeURIComponent(id)}`;
+}
+function rowValue(row, index) {
+  if (Array.isArray(row)) return row[index];
+  if (row && typeof row === "object") {
+    const values = Object.values(row);
+    return values[index];
+  }
+  return void 0;
+}
 
 // src/duckdb/DuckDbDatabaseHandle.ts
 var DuckDbDatabaseHandle = class {
@@ -2290,17 +2787,19 @@ var DuckDbService = class extends BaseService {
   }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
-    let errorBody = {};
-    try {
-      errorBody = JSON.parse(errorText);
-    } catch {
-    }
+    const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
       errorBody.error
     );
-    const message = errorBody.message || `DuckDB ${operation} failed: ${response.status} - ${errorText}`;
-    const meta = { status: response.status, statusText: response.statusText };
+    const message = formatServiceResponseError(
+      "DuckDB",
+      operation,
+      response.status,
+      errorText,
+      errorBody
+    );
+    const meta = responseErrorMeta(response.status, response.statusText, errorText);
     if (response.status === 401) {
       const { resource, action } = parseAuthError(errorText);
       if (action) meta.requiredAction = action;
@@ -5648,6 +6147,7 @@ export {
   RetryPolicySchema,
   SECRET_NAME_RE,
   SQLAction,
+  SQLMigrations,
   SQLService,
   SecretsService,
   ServiceContext,
@@ -5659,6 +6159,7 @@ export {
   ServiceSessionSchema,
   TelemetryEvents,
   TelemetrySpanEventSchema,
+  TinyCloudDebugLogger,
   TinyCloudQuota,
   VaultHeaders,
   VaultPublicSpaceKVActions,
@@ -5678,21 +6179,26 @@ export {
   canonicalize as canonicalizeEncryptionJson,
   canonicalizeSecretScope,
   checkDecryptInvocationInput,
+  clearTinyCloudDebugLogs,
   createKVResponseSchema,
   createResultSchema,
   createVaultCrypto,
   decryptEnvelopeWithKey,
   defaultRetryPolicy,
   deriveSignedReceiverKey,
+  disableTinyCloudDebug,
   discoverNetwork,
+  enableTinyCloudDebug,
   encryptToNetwork,
   encryptionError,
   ensureNetworkUsableForDecrypt,
   err,
   errorResult,
   generateRandomReceiverKey,
+  getTinyCloudDebugLogs,
   hexDecode,
   hexEncode2 as hexEncode,
+  installTinyCloudDebugGlobals,
   isNetworkId,
   networkDiscoveryKey,
   networkError,
@@ -5708,6 +6214,7 @@ export {
   storageLimitReachedError,
   storageQuotaExceededError,
   timeoutError,
+  tinyCloudDebugLogger,
   utf8Decode,
   utf8Encode,
   validateEnvelope,