@aouda/client 0.1.7 → 0.1.9

package/dist/cli/index.cjs

@@ -421,7 +421,7 @@ var import_node_url = require("url");
 // package.json
 var package_default = {
   name: "@aouda/client",
-  version: "0.1.7",
+  version: "0.1.9",
   description: "Official TypeScript/JavaScript client library for Aouda",
   type: "module",
   main: "./dist/index.cjs",
@@ -536,12 +536,13 @@ var AoudaResponseError = class extends AoudaError {
   }
 };
 var AoudaApiError = class extends AoudaError {
-  constructor(message, code, statusCode, details, requestId) {
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.details = details;
     this.requestId = requestId;
+    this.retryAfterSeconds = retryAfterSeconds;
     this.name = "AoudaApiError";
   }
 };
@@ -564,8 +565,8 @@ var AoudaValidationError = class extends AoudaApiError {
   }
 };
 var AoudaServerError = class extends AoudaApiError {
-  constructor(message, code, statusCode, details, requestId) {
-    super(message, code, statusCode, details, requestId);
+  constructor(message, code, statusCode, details, requestId, retryAfterSeconds) {
+    super(message, code, statusCode, details, requestId, retryAfterSeconds);
     this.name = "AoudaServerError";
   }
 };
@@ -1504,6 +1505,8 @@ var ERROR_CODE_MAP = {
   SERVICE_UNAVAILABLE: AoudaServerError,
   TIMEOUT: AoudaServerError,
   OVERLOADED: AoudaServerError,
+  MEMORY_BUDGET_EXCEEDED: AoudaServerError,
+  WAL_CAPACITY_EXCEEDED: AoudaServerError,
   AUTH_TOKEN_MISSING: AoudaAuthenticationError,
   AUTH_TOKEN_EXPIRED: AoudaAuthenticationError,
   AUTH_TOKEN_INVALID: AoudaAuthenticationError,
@@ -1531,13 +1534,22 @@ function createComposedAbortController(...signals) {
   }
   return controller;
 }
-function createApiError(statusCode, statusText, body) {
+function parseRetryAfterSeconds(header) {
+  if (header == null || header.trim() === "") return void 0;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return void 0;
+  const n = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n < 0) return void 0;
+  return n;
+}
+function createApiError(statusCode, statusText, body, retryAfterHeader) {
   const message = body.error ?? `${statusCode} ${statusText}`;
   const code = body.code ?? "UNKNOWN";
   const details = body.details;
   const requestId = body.requestId;
+  const retryAfterSeconds = parseRetryAfterSeconds(retryAfterHeader ?? null);
   const Ctor = ERROR_CODE_MAP[code] ?? AoudaApiError;
-  return new Ctor(message, code, statusCode, details, requestId);
+  return new Ctor(message, code, statusCode, details, requestId, retryAfterSeconds);
 }
 var HttpTransport = class {
   constructor(options) {
@@ -1630,7 +1642,8 @@ var HttpTransport = class {
           throw createApiError(
             response.status,
             response.statusText,
-            errorBody
+            errorBody,
+            response.headers.get("Retry-After")
           );
         }
         throw new AoudaResponseError(
@@ -1740,7 +1753,8 @@ var HttpTransport = class {
         throw createApiError(
           response.status,
           response.statusText,
-          errorBody
+          errorBody,
+          response.headers.get("Retry-After")
         );
       }
       throw new AoudaResponseError(
@@ -2086,6 +2100,17 @@ var CIRCUIT_BREAKER_POLICY_DISABLED = {
 
 // src/resilience/resilient-transport.ts
 var REQUEST_ID_HEADER3 = "X-Request-Id";
+function isCapacityBackPressure(error) {
+  return error instanceof AoudaApiError && (error.code === "MEMORY_BUDGET_EXCEEDED" || error.code === "WAL_CAPACITY_EXCEEDED");
+}
+function retryDelayMs(retryPolicy, attempt, error) {
+  const backoff = calculateDelay(retryPolicy, attempt);
+  if (!isCapacityBackPressure(error) || !(error instanceof AoudaApiError)) {
+    return backoff;
+  }
+  const headerMs = error.retryAfterSeconds != null ? error.retryAfterSeconds * 1e3 : 0;
+  return Math.max(backoff, headerMs);
+}
 function delayMs(ms, signal) {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve4, reject) => {
@@ -2140,7 +2165,7 @@ var ResilientTransport = class {
       } catch (error) {
         lastError = error;
         const retryable = isRetryable(error);
-        if (retryable) {
+        if (retryable && !isCapacityBackPressure(error)) {
           this.circuitBreaker.recordFailure(error);
         }
         if (!retryable) {
@@ -2150,7 +2175,7 @@ var ResilientTransport = class {
         if (attempt > this.retryPolicy.maxRetries) {
           throw error;
         }
-        const delay = calculateDelay(this.retryPolicy, attempt);
+        const delay = retryDelayMs(this.retryPolicy, attempt, error);
         try {
           await delayMs(delay, config.signal);
         } catch {
@@ -2186,7 +2211,7 @@ var ResilientTransport = class {
       } catch (error) {
         lastError = error;
         const retryable = isRetryable(error);
-        if (retryable) {
+        if (retryable && !isCapacityBackPressure(error)) {
           this.circuitBreaker.recordFailure(error);
         }
         if (!retryable) {
@@ -2196,7 +2221,7 @@ var ResilientTransport = class {
         if (attempt > this.retryPolicy.maxRetries) {
           throw error;
         }
-        const delay = calculateDelay(this.retryPolicy, attempt);
+        const delay = retryDelayMs(this.retryPolicy, attempt, error);
         try {
           await delayMs(delay, config.signal);
         } catch {
@@ -3953,23 +3978,68 @@ var TablesApi = class {
     );
   }
   /**
-   * Renames a column.
+   * Alters a column (type, nullable, encoder, autoIncrement, references, and/or rename).
+   * PATCH /api/databases/{db}/tables/{t}/columns/{c}.
+   * Omit a property to leave it unchanged. For `references`, omit unchanged; `""` or `null` clears.
    * @param tableName - Table name.
    * @param columnName - Current column name.
-   * @param body - Request body (database, newName).
-   * @returns 200 response body (column detail).
-   * @throws AoudaNotFoundError if table or column does not exist; AoudaApiError for WRITE_NOT_ALLOWED, etc.
+   * @param body - Fields to change. `database` is injected from the client scope when omitted.
+   * @returns Updated column detail.
    */
-  async renameColumn(tableName, columnName, body) {
+  async alterColumn(tableName, columnName, body) {
     validateNonEmptyString(tableName, "Table name");
     validateNonEmptyString(columnName, "Column name");
-    validateNonEmptyString(body.newName, "New column name");
+    const hasField = body.newName !== void 0 || body.type !== void 0 || body.nullable !== void 0 || body.encoder !== void 0 || body.autoIncrement !== void 0 || body.references !== void 0;
+    if (!hasField) {
+      throw new Error(
+        "AlterColumnRequest must set at least one of: newName, type, nullable, encoder, autoIncrement, references"
+      );
+    }
     const prefix = databasePath2(this.database);
     const encodedTable = encodeURIComponent(tableName);
     const encodedColumn = encodeURIComponent(columnName);
+    const requestBody = {
+      database: this.database,
+      ...body
+    };
     return this.transport.patch(
       `${prefix}/tables/${encodedTable}/columns/${encodedColumn}`,
-      body
+      requestBody
+    );
+  }
+  /**
+   * Renames a column (convenience wrapper over {@link alterColumn}).
+   * @param tableName - Table name.
+   * @param columnName - Current column name.
+   * @param body - Request body with newName (database optional; injected when omitted).
+   * @returns 200 response body (column detail).
+   * @throws AoudaNotFoundError if table or column does not exist; AoudaApiError for WRITE_NOT_ALLOWED, etc.
+   */
+  async renameColumn(tableName, columnName, body) {
+    validateNonEmptyString(body.newName ?? "", "New column name");
+    return this.alterColumn(tableName, columnName, { newName: body.newName });
+  }
+  /**
+   * Reorders columns in a table.
+   * PUT /api/databases/{db}/tables/{t}/columns:order (204 No Content).
+   * @param tableName - Table name.
+   * @param columnsOrBody - Ordered column names, or a request body with `columns`.
+   */
+  async reorderColumns(tableName, columnsOrBody) {
+    validateNonEmptyString(tableName, "Table name");
+    const columns = Array.isArray(columnsOrBody) ? columnsOrBody : columnsOrBody.columns;
+    if (!columns?.length) {
+      throw new Error("columns array is required and must be non-empty");
+    }
+    const prefix = databasePath2(this.database);
+    const encodedTable = encodeURIComponent(tableName);
+    const requestBody = {
+      database: this.database,
+      columns
+    };
+    await this.transport.put(
+      `${prefix}/tables/${encodedTable}/columns:order`,
+      requestBody
     );
   }
   /**
@@ -4209,6 +4279,37 @@ var BranchesApi = class {
   }
 };
 
+// src/jobs.ts
+function validateNonEmptyString2(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+var JobsApi = class {
+  constructor(transport, database) {
+    this.transport = transport;
+    this.database = database;
+  }
+  get prefix() {
+    return `${databasePath2(this.database)}/jobs`;
+  }
+  /**
+   * Lists jobs whose params target this database.
+   */
+  async list() {
+    return this.transport.get(this.prefix);
+  }
+  /**
+   * Gets a single job by id when it belongs to this database.
+   * @param jobId - Job GUID string.
+   */
+  async get(jobId) {
+    validateNonEmptyString2(jobId, "Job id");
+    const encoded = encodeURIComponent(jobId);
+    return this.transport.get(`${this.prefix}/${encoded}`);
+  }
+};
+
 // src/admin/server.ts
 var ServerAdminApi = class {
   constructor(transport) {
@@ -5486,7 +5587,7 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 function normalizeBaseUrl(url) {
   return url.replace(/\/+$/, "");
 }
-function validateNonEmptyString2(value, name) {
+function validateNonEmptyString3(value, name) {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`${name} must be a non-empty string`);
   }
@@ -5501,8 +5602,8 @@ var AoudaClient = class {
   constructor(options) {
     this.connected = false;
     this._wsTransport = null;
-    validateNonEmptyString2(options.serverUrl, "serverUrl");
-    validateNonEmptyString2(options.database, "database");
+    validateNonEmptyString3(options.serverUrl, "serverUrl");
+    validateNonEmptyString3(options.database, "database");
     this.baseUrl = normalizeBaseUrl(options.serverUrl);
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.database = options.database.trim();
@@ -5584,6 +5685,7 @@ var AoudaClient = class {
       this._authHandler = null;
     }
     this._tables = new TablesApi(this.transport, this.database);
+    this._jobs = new JobsApi(this.transport, this.database);
     this._databases = new DatabasesApi(this.transport);
     this._schema = new SchemaApi(this.transport, this.database);
     this._branches = new BranchesApi(this.transport, this.database);
@@ -5677,7 +5779,7 @@ var AoudaClient = class {
    * ```
    */
   table(name) {
-    validateNonEmptyString2(name, "Table name");
+    validateNonEmptyString3(name, "Table name");
     return new TableQuery(
       this.transport,
       name,
@@ -5693,6 +5795,13 @@ var AoudaClient = class {
   get tables() {
     return this._tables;
   }
+  /**
+   * Access pending/background jobs for the current database (e.g. ColumnRewrite).
+   * @returns The jobs API.
+   */
+  get jobs() {
+    return this._jobs;
+  }
   /**
    * Access server-level database operations (list, create, get, drop).
    * @returns The databases API.
@@ -5789,7 +5898,7 @@ var AoudaClient = class {
    * ```
    */
   bulkLoad(tableName, rows, options) {
-    validateNonEmptyString2(tableName, "tableName");
+    validateNonEmptyString3(tableName, "tableName");
     return new BulkLoadCoordinator(this.transport, this.database).run(
       [tableName],
       rows,