@tinycloud/sdk-services 2.0.1 → 2.0.2-beta.0

package/dist/sql/index.cjs

@@ -0,0 +1,596 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sql/index.ts
+var sql_exports = {};
+__export(sql_exports, {
+  DatabaseHandle: () => DatabaseHandle,
+  SQLAction: () => SQLAction,
+  SQLService: () => SQLService
+});
+module.exports = __toCommonJS(sql_exports);
+
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  ABORTED: "ABORTED",
+  INVALID_INPUT: "INVALID_INPUT",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  // KV-specific errors
+  KV_NOT_FOUND: "KV_NOT_FOUND",
+  KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 3,
+  backoff: "exponential",
+  baseDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+};
+var TelemetryEvents = {
+  SERVICE_REQUEST: "service.request",
+  SERVICE_RESPONSE: "service.response",
+  SERVICE_ERROR: "service.error",
+  SERVICE_RETRY: "service.retry",
+  SESSION_CHANGED: "session.changed",
+  SESSION_EXPIRED: "session.expired"
+};
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function serviceError(code, message, service, options) {
+  return {
+    code,
+    message,
+    service,
+    cause: options?.cause,
+    meta: options?.meta
+  };
+}
+
+// src/errors.ts
+function authRequiredError(service) {
+  return {
+    code: ErrorCodes.AUTH_REQUIRED,
+    message: "Authentication required. Please sign in first.",
+    service
+  };
+}
+function timeoutError(service) {
+  return {
+    code: ErrorCodes.TIMEOUT,
+    message: "Request timed out.",
+    service
+  };
+}
+function abortedError(service) {
+  return {
+    code: ErrorCodes.ABORTED,
+    message: "Request was aborted.",
+    service
+  };
+}
+function parseAuthError(responseText) {
+  const match = responseText.match(/^Unauthorized Action:\s*(.+?)\s*\/\s*(tinycloud\.\S+)$/m);
+  if (match) {
+    return { resource: match[1].trim(), action: match[2].trim() };
+  }
+  return {};
+}
+function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+  if (error instanceof Error) {
+    if (error.name === "AbortError") {
+      return abortedError(service);
+    }
+    if (error.name === "TimeoutError" || error.message.toLowerCase().includes("timeout")) {
+      return timeoutError(service);
+    }
+    return {
+      code: defaultCode,
+      message: error.message,
+      service,
+      cause: error
+    };
+  }
+  return {
+    code: defaultCode,
+    message: String(error),
+    service
+  };
+}
+
+// src/base/BaseService.ts
+var BaseService = class {
+  constructor() {
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    this.abortController = new AbortController();
+    /**
+     * Service-specific configuration.
+     */
+    this._config = {};
+  }
+  /**
+   * Get the service configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Initialize the service with context.
+   * Called by the SDK after instantiation.
+   *
+   * @param context - The service context
+   */
+  initialize(context) {
+    this.context = context;
+  }
+  /**
+   * Called when session changes (sign-in, sign-out, refresh).
+   * Override in subclasses to handle session changes.
+   *
+   * @param session - The new session, or null if signed out
+   */
+  onSessionChange(session) {
+  }
+  /**
+   * Called when SDK signs out.
+   * Aborts all pending operations.
+   */
+  onSignOut() {
+    this.abortController.abort();
+    this.abortController = new AbortController();
+  }
+  /**
+   * Get the abort signal for this service.
+   * Combines the service-level abort with context-level abort.
+   */
+  get abortSignal() {
+    return this.abortController.signal;
+  }
+  /**
+   * Check if the service is authenticated.
+   */
+  get isAuthenticated() {
+    return this.context?.isAuthenticated ?? false;
+  }
+  /**
+   * Get the current session.
+   * Throws if not authenticated.
+   */
+  get session() {
+    if (!this.context?.session) {
+      throw new Error("Not authenticated");
+    }
+    return this.context.session;
+  }
+  /**
+   * Check authentication and return error result if not authenticated.
+   * Use this at the start of methods that require authentication.
+   *
+   * @returns true if authenticated, false otherwise
+   */
+  requireAuth() {
+    return this.isAuthenticated;
+  }
+  /**
+   * Emit a telemetry event.
+   *
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event, data) {
+    this.context?.emit(event, data);
+  }
+  /**
+   * Emit a service request event.
+   *
+   * @param action - The action being performed
+   * @param key - Optional key/path being accessed
+   */
+  emitRequest(action, key) {
+    this.emit(TelemetryEvents.SERVICE_REQUEST, {
+      service: this.getServiceName(),
+      action,
+      key,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Emit a service response event.
+   *
+   * @param action - The action that was performed
+   * @param ok - Whether the request was successful
+   * @param startTime - Start time for duration calculation
+   * @param status - Optional HTTP status code
+   */
+  emitResponse(action, ok2, startTime, status) {
+    this.emit(TelemetryEvents.SERVICE_RESPONSE, {
+      service: this.getServiceName(),
+      action,
+      ok: ok2,
+      duration: Date.now() - startTime,
+      status
+    });
+  }
+  /**
+   * Emit a service error event.
+   *
+   * @param error - The service error
+   */
+  emitError(error) {
+    this.emit(TelemetryEvents.SERVICE_ERROR, {
+      service: this.getServiceName(),
+      error
+    });
+  }
+  /**
+   * Get the service name from the static property.
+   * Subclasses must define static serviceName.
+   */
+  getServiceName() {
+    return this.constructor.serviceName;
+  }
+  /**
+   * Create a combined abort signal from multiple sources.
+   *
+   * @param signals - Additional abort signals to combine
+   * @returns A combined abort signal
+   */
+  combineSignals(...signals) {
+    const controller = new AbortController();
+    const allSignals = [this.abortSignal, ...signals.filter(Boolean)];
+    for (const signal of allSignals) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+        return controller.signal;
+      }
+      signal.addEventListener("abort", () => controller.abort(signal.reason), {
+        once: true
+      });
+    }
+    return controller.signal;
+  }
+  /**
+   * Wrap an operation with error handling and telemetry.
+   *
+   * @param action - The action name for telemetry
+   * @param key - Optional key for telemetry
+   * @param operation - The operation to execute
+   * @returns Result of the operation
+   */
+  async withTelemetry(action, key, operation) {
+    const startTime = Date.now();
+    this.emitRequest(action, key);
+    try {
+      const result = await operation();
+      if (result.ok) {
+        this.emitResponse(action, true, startTime);
+      } else {
+        this.emitResponse(action, false, startTime);
+        this.emitError(result.error);
+      }
+      return result;
+    } catch (error) {
+      const serviceError2 = wrapError(this.getServiceName(), error);
+      this.emitResponse(action, false, startTime);
+      this.emitError(serviceError2);
+      return err(serviceError2);
+    }
+  }
+};
+
+// src/sql/DatabaseHandle.ts
+var DatabaseHandle = class {
+  constructor(service, name) {
+    this.service = service;
+    this.name = name;
+  }
+  async query(sql, params, options) {
+    return this.service.queryOnDb(this.name, sql, params, options);
+  }
+  async execute(sql, params, options) {
+    return this.service.executeOnDb(this.name, sql, params, options);
+  }
+  async batch(statements, options) {
+    return this.service.batchOnDb(this.name, statements, options);
+  }
+  async executeStatement(name, params, options) {
+    return this.service.executeStatementOnDb(this.name, name, params, options);
+  }
+  async export(options) {
+    return this.service.exportDb(this.name, options);
+  }
+};
+
+// src/sql/types.ts
+var SQLAction = {
+  READ: "tinycloud.sql/read",
+  WRITE: "tinycloud.sql/write",
+  ADMIN: "tinycloud.sql/admin",
+  SELECT: "tinycloud.sql/select",
+  INSERT: "tinycloud.sql/insert",
+  UPDATE: "tinycloud.sql/update",
+  DELETE: "tinycloud.sql/delete",
+  EXECUTE: "tinycloud.sql/execute",
+  EXPORT: "tinycloud.sql/export",
+  ALL: "tinycloud.sql/*"
+};
+
+// src/sql/SQLService.ts
+var SQLService = class extends BaseService {
+  constructor(config = {}) {
+    super();
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  get defaultDbName() {
+    return this._config.defaultDatabase ?? "default";
+  }
+  get host() {
+    return this.context.hosts[0];
+  }
+  /**
+   * Get a handle to a named database.
+   */
+  db(name) {
+    return new DatabaseHandle(this, name ?? this.defaultDbName);
+  }
+  /**
+   * Shortcut: query the default database.
+   */
+  async query(sql, params, options) {
+    return this.queryOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: execute on the default database.
+   */
+  async execute(sql, params, options) {
+    return this.executeOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: batch on the default database.
+   */
+  async batch(statements, options) {
+    return this.batchOnDb(this.defaultDbName, statements, options);
+  }
+  // === Internal methods called by DatabaseHandle ===
+  async queryOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("query", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.READ,
+          { action: "query", sql, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "query");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async executeOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("execute", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const body = {
+          action: "execute",
+          sql,
+          params: params ?? []
+        };
+        if (options?.schema) {
+          body.schema = options.schema;
+        }
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.WRITE,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "execute");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async batchOnDb(dbName, statements, options) {
+    return this.withTelemetry("batch", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.WRITE,
+          { action: "batch", statements },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "batch");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async executeStatementOnDb(dbName, name, params, options) {
+    return this.withTelemetry("executeStatement", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.EXECUTE,
+          { action: "execute_statement", name, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "executeStatement");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async exportDb(dbName, options) {
+    return this.withTelemetry("export", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.EXPORT,
+          { action: "export" },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "export");
+        }
+        const resp = response;
+        if (typeof resp.blob === "function") {
+          const blob = await resp.blob();
+          return ok(blob);
+        }
+        const text = await response.text();
+        return ok(text);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  // === Private helpers ===
+  async invokeSQL(dbName, action, body, signal) {
+    const session = this.context.session;
+    const headers = this.context.invoke(session, "sql", dbName, action);
+    return this.context.fetch(`${this.host}/invoke`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal: this.combineSignals(signal)
+    });
+  }
+  async handleErrorResponse(response, operation) {
+    const errorText = await response.text();
+    let errorBody = {};
+    try {
+      errorBody = JSON.parse(errorText);
+    } catch {
+    }
+    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 };
+    if (response.status === 401) {
+      const { resource, action } = parseAuthError(errorText);
+      if (action) meta.requiredAction = action;
+      if (resource) meta.resource = resource;
+    }
+    return err(
+      serviceError(errorCode, message, "sql", { meta })
+    );
+  }
+  mapHttpStatusToErrorCode(status, serverError) {
+    switch (status) {
+      case 400:
+        return ErrorCodes.SQL_ERROR;
+      case 401:
+        return ErrorCodes.AUTH_UNAUTHORIZED;
+      case 403:
+        if (serverError === "sql_readonly_violation") {
+          return ErrorCodes.SQL_READONLY_VIOLATION;
+        }
+        return ErrorCodes.SQL_PERMISSION_DENIED;
+      case 404:
+        return ErrorCodes.SQL_DATABASE_NOT_FOUND;
+      case 413:
+        return ErrorCodes.SQL_RESPONSE_TOO_LARGE;
+      case 429:
+        return ErrorCodes.SQL_QUOTA_EXCEEDED;
+      default:
+        return ErrorCodes.NETWORK_ERROR;
+    }
+  }
+};
+SQLService.serviceName = "sql";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DatabaseHandle,
+  SQLAction,
+  SQLService
+});
+//# sourceMappingURL=index.cjs.map