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

package/dist/sql/index.d.cts

@@ -85,13 +85,54 @@ interface ExecuteResponse {
 interface BatchResponse {
     results: ExecuteResponse[];
 }
+/**
+ * A versioned SQL migration owned by an application or SDK subsystem.
+ */
+interface SqlMigration {
+    /**
+     * Stable migration id within the namespace, e.g. "001_initial".
+     */
+    id: string;
+    /**
+     * SQL statements to apply when this migration has not been recorded.
+     * Statements should be idempotent where SQLite supports it.
+     */
+    sql: Array<string | SqlStatement>;
+}
+/**
+ * Options for applying SQL migrations.
+ */
+interface SqlMigrationApplyOptions {
+    /**
+     * Namespace for this migration set, usually an app id or SDK subsystem.
+     */
+    namespace: string;
+    /**
+     * Ordered migration list.
+     */
+    migrations: SqlMigration[];
+    /**
+     * Custom abort signal for migration operations.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result from applying SQL migrations.
+ */
+interface SqlMigrationApplyResponse {
+    database: string;
+    namespace: string;
+    status: "already_current" | "applied";
+    applied: string[];
+    skipped: string[];
+}
 /**
  * SQL service action types.
  */
 declare const SQLAction: {
     readonly READ: "tinycloud.sql/read";
     readonly WRITE: "tinycloud.sql/write";
-    readonly DDL: "tinycloud.sql/ddl";
+    readonly SCHEMA: "tinycloud.sql/schema";
     readonly ADMIN: "tinycloud.sql/admin";
     readonly SELECT: "tinycloud.sql/select";
     readonly INSERT: "tinycloud.sql/insert";
@@ -109,12 +150,23 @@ type SQLActionType = (typeof SQLAction)[keyof typeof SQLAction];
  * Platform-agnostic interface for SQL database operations.
  */
 
+/**
+ * Migration helper bound to a specific database.
+ */
+interface ISQLMigrations {
+    /**
+     * Apply ordered, app-owned migrations and record completed ids.
+     */
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
 /**
  * Database handle interface for operations on a specific named database.
  */
 interface IDatabaseHandle {
     /** The database name */
     readonly name: string;
+    /** Versioned schema migration helper. */
+    readonly migrations: ISQLMigrations;
     /**
      * Execute a SQL query and return rows.
      */
@@ -179,6 +231,7 @@ interface ISQLService extends IService {
 declare class SQLService extends BaseService implements ISQLService {
     static readonly serviceName = "sql";
     protected _config: SQLServiceConfig;
+    private readonly migrationLocks;
     constructor(config?: SQLServiceConfig);
     get config(): SQLServiceConfig;
     private get defaultDbName();
@@ -199,11 +252,15 @@ declare class SQLService extends BaseService implements ISQLService {
      * Shortcut: batch on the default database.
      */
     batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    applyMigrationsOnDb(dbName: string, options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
     queryOnDb<T = Record<string, unknown>>(dbName: string, sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
     executeOnDb(dbName: string, sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
     batchOnDb(dbName: string, statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
     executeStatementOnDb(dbName: string, name: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
     exportDb(dbName: string, options?: QueryOptions): Promise<Result<Blob>>;
+    private applyMigrationsOnDbUnlocked;
+    private applyOneMigration;
+    private ensureMigrationsTable;
     private invokeSQL;
     private actionForSql;
     private actionsForSqlBatch;
@@ -222,6 +279,7 @@ declare class SQLService extends BaseService implements ISQLService {
 declare class DatabaseHandle implements IDatabaseHandle {
     private service;
     readonly name: string;
+    readonly migrations: ISQLMigrations;
     constructor(service: SQLService, name: string);
     query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
     execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
@@ -230,4 +288,11 @@ declare class DatabaseHandle implements IDatabaseHandle {
     export(options?: QueryOptions): Promise<Result<Blob>>;
 }
 
-export { type BatchOptions, type BatchResponse, DatabaseHandle, type ExecuteOptions, type ExecuteResponse, type IDatabaseHandle, type ISQLService, type QueryOptions, type QueryResponse, SQLAction, type SQLActionType, SQLService, type SQLServiceConfig, type SqlStatement, type SqlValue };
+declare class SQLMigrations implements ISQLMigrations {
+    private readonly service;
+    private readonly dbName;
+    constructor(service: SQLService, dbName: string);
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
+
+export { type BatchOptions, type BatchResponse, DatabaseHandle, type ExecuteOptions, type ExecuteResponse, type IDatabaseHandle, type ISQLMigrations, type ISQLService, type QueryOptions, type QueryResponse, SQLAction, type SQLActionType, SQLMigrations, SQLService, type SQLServiceConfig, type SqlMigration, type SqlMigrationApplyOptions, type SqlMigrationApplyResponse, type SqlStatement, type SqlValue };

package/dist/sql/index.d.ts

@@ -85,13 +85,54 @@ interface ExecuteResponse {
 interface BatchResponse {
     results: ExecuteResponse[];
 }
+/**
+ * A versioned SQL migration owned by an application or SDK subsystem.
+ */
+interface SqlMigration {
+    /**
+     * Stable migration id within the namespace, e.g. "001_initial".
+     */
+    id: string;
+    /**
+     * SQL statements to apply when this migration has not been recorded.
+     * Statements should be idempotent where SQLite supports it.
+     */
+    sql: Array<string | SqlStatement>;
+}
+/**
+ * Options for applying SQL migrations.
+ */
+interface SqlMigrationApplyOptions {
+    /**
+     * Namespace for this migration set, usually an app id or SDK subsystem.
+     */
+    namespace: string;
+    /**
+     * Ordered migration list.
+     */
+    migrations: SqlMigration[];
+    /**
+     * Custom abort signal for migration operations.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result from applying SQL migrations.
+ */
+interface SqlMigrationApplyResponse {
+    database: string;
+    namespace: string;
+    status: "already_current" | "applied";
+    applied: string[];
+    skipped: string[];
+}
 /**
  * SQL service action types.
  */
 declare const SQLAction: {
     readonly READ: "tinycloud.sql/read";
     readonly WRITE: "tinycloud.sql/write";
-    readonly DDL: "tinycloud.sql/ddl";
+    readonly SCHEMA: "tinycloud.sql/schema";
     readonly ADMIN: "tinycloud.sql/admin";
     readonly SELECT: "tinycloud.sql/select";
     readonly INSERT: "tinycloud.sql/insert";
@@ -109,12 +150,23 @@ type SQLActionType = (typeof SQLAction)[keyof typeof SQLAction];
  * Platform-agnostic interface for SQL database operations.
  */
 
+/**
+ * Migration helper bound to a specific database.
+ */
+interface ISQLMigrations {
+    /**
+     * Apply ordered, app-owned migrations and record completed ids.
+     */
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
 /**
  * Database handle interface for operations on a specific named database.
  */
 interface IDatabaseHandle {
     /** The database name */
     readonly name: string;
+    /** Versioned schema migration helper. */
+    readonly migrations: ISQLMigrations;
     /**
      * Execute a SQL query and return rows.
      */
@@ -179,6 +231,7 @@ interface ISQLService extends IService {
 declare class SQLService extends BaseService implements ISQLService {
     static readonly serviceName = "sql";
     protected _config: SQLServiceConfig;
+    private readonly migrationLocks;
     constructor(config?: SQLServiceConfig);
     get config(): SQLServiceConfig;
     private get defaultDbName();
@@ -199,11 +252,15 @@ declare class SQLService extends BaseService implements ISQLService {
      * Shortcut: batch on the default database.
      */
     batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    applyMigrationsOnDb(dbName: string, options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
     queryOnDb<T = Record<string, unknown>>(dbName: string, sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
     executeOnDb(dbName: string, sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
     batchOnDb(dbName: string, statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
     executeStatementOnDb(dbName: string, name: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
     exportDb(dbName: string, options?: QueryOptions): Promise<Result<Blob>>;
+    private applyMigrationsOnDbUnlocked;
+    private applyOneMigration;
+    private ensureMigrationsTable;
     private invokeSQL;
     private actionForSql;
     private actionsForSqlBatch;
@@ -222,6 +279,7 @@ declare class SQLService extends BaseService implements ISQLService {
 declare class DatabaseHandle implements IDatabaseHandle {
     private service;
     readonly name: string;
+    readonly migrations: ISQLMigrations;
     constructor(service: SQLService, name: string);
     query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
     execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
@@ -230,4 +288,11 @@ declare class DatabaseHandle implements IDatabaseHandle {
     export(options?: QueryOptions): Promise<Result<Blob>>;
 }
 
-export { type BatchOptions, type BatchResponse, DatabaseHandle, type ExecuteOptions, type ExecuteResponse, type IDatabaseHandle, type ISQLService, type QueryOptions, type QueryResponse, SQLAction, type SQLActionType, SQLService, type SQLServiceConfig, type SqlStatement, type SqlValue };
+declare class SQLMigrations implements ISQLMigrations {
+    private readonly service;
+    private readonly dbName;
+    constructor(service: SQLService, dbName: string);
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
+
+export { type BatchOptions, type BatchResponse, DatabaseHandle, type ExecuteOptions, type ExecuteResponse, type IDatabaseHandle, type ISQLMigrations, type ISQLService, type QueryOptions, type QueryResponse, SQLAction, type SQLActionType, SQLMigrations, SQLService, type SQLServiceConfig, type SqlMigration, type SqlMigrationApplyOptions, type SqlMigrationApplyResponse, type SqlStatement, type SqlValue };

package/dist/sql/index.js

@@ -324,11 +324,59 @@ var BaseService = class {
   }
 };
 
+// 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);
@@ -351,7 +399,7 @@ var DatabaseHandle = class {
 var SQLAction = {
   READ: "tinycloud.sql/read",
   WRITE: "tinycloud.sql/write",
-  DDL: "tinycloud.sql/ddl",
+  SCHEMA: "tinycloud.sql/schema",
   ADMIN: "tinycloud.sql/admin",
   SELECT: "tinycloud.sql/select",
   INSERT: "tinycloud.sql/insert",
@@ -364,9 +412,20 @@ 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() {
@@ -402,6 +461,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 () => {
@@ -442,7 +519,7 @@ var SQLService = class extends BaseService {
         const actions = [
           this.actionForSql(sql, SQLAction.WRITE),
           ...(options?.schema ?? []).map(
-            (statement) => this.actionForSql(statement, SQLAction.DDL)
+            (statement) => this.actionForSql(statement, SQLAction.SCHEMA)
           )
         ];
         const response = await this.invokeSQL(
@@ -532,6 +609,78 @@ 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, actions, body, signal) {
     const session = this.context.session;
@@ -550,7 +699,7 @@ var SQLService = class extends BaseService {
   actionForSql(sql, fallback) {
     const token = firstSqlToken(sql);
     if (token === "pragma") return SQLAction.ADMIN;
-    if (token !== void 0 && DDL_TOKENS.has(token)) return SQLAction.DDL;
+    if (token !== void 0 && DDL_TOKENS.has(token)) return SQLAction.SCHEMA;
     return fallback;
   }
   actionsForSqlBatch(statements) {
@@ -579,17 +728,19 @@ var SQLService = 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 || `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;
@@ -649,9 +800,57 @@ 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;
+}
 export {
   DatabaseHandle,
   SQLAction,
+  SQLMigrations,
   SQLService
 };
 //# sourceMappingURL=index.js.map