radosgw-admin 0.1.0

package/dist/index.js

@@ -0,0 +1,1869 @@
+// src/signer.ts
+import { createHmac, createHash } from "crypto";
+var ALGORITHM = "AWS4-HMAC-SHA256";
+var SERVICE = "s3";
+var UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+function hmacSha256(key, data) {
+  return createHmac("sha256", key).update(data).digest();
+}
+function hmacSha256Hex(key, data) {
+  return createHmac("sha256", key).update(data).digest("hex");
+}
+function getDateStamp(date) {
+  return date.toISOString().replace(/[-:]/g, "").slice(0, 8);
+}
+function getAmzDate(date) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+function getSigningKey(secretKey, dateStamp, region) {
+  const kDate = hmacSha256(`AWS4${secretKey}`, dateStamp);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, SERVICE);
+  return hmacSha256(kService, "aws4_request");
+}
+function getCanonicalQueryString(url) {
+  const params = Array.from(url.searchParams.entries());
+  params.sort((a, b) => {
+    if (a[0] === b[0]) return a[1].localeCompare(b[1]);
+    return a[0].localeCompare(b[0]);
+  });
+  return params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+}
+function signRequest(request, date) {
+  const now = date ?? /* @__PURE__ */ new Date();
+  const dateStamp = getDateStamp(now);
+  const amzDate = getAmzDate(now);
+  const { method, url, accessKey, secretKey, region } = request;
+  const headers = {};
+  for (const [k, v] of Object.entries(request.headers)) {
+    headers[k.toLowerCase()] = v;
+  }
+  headers["host"] = url.host;
+  headers["x-amz-date"] = amzDate;
+  headers["x-amz-content-sha256"] = UNSIGNED_PAYLOAD;
+  const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+  const canonicalHeaders = sortedHeaderKeys.map((k) => `${k}:${headers[k].trim()}`).join("\n");
+  const signedHeaders = sortedHeaderKeys.join(";");
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    getCanonicalQueryString(url),
+    canonicalHeaders + "\n",
+    signedHeaders,
+    UNSIGNED_PAYLOAD
+  ].join("\n");
+  const credentialScope = `${dateStamp}/${region}/${SERVICE}/aws4_request`;
+  const stringToSign = [ALGORITHM, amzDate, credentialScope, sha256(canonicalRequest)].join("\n");
+  const signingKey = getSigningKey(secretKey, dateStamp, region);
+  const signature = hmacSha256Hex(signingKey, stringToSign);
+  const authorization = `${ALGORITHM} Credential=${accessKey}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  return {
+    "x-amz-date": amzDate,
+    "x-amz-content-sha256": UNSIGNED_PAYLOAD,
+    Authorization: authorization
+  };
+}
+
+// src/errors.ts
+var RGWError = class extends Error {
+  constructor(message, statusCode, code, uid) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.uid = uid;
+    this.name = "RGWError";
+  }
+};
+var RGWNotFoundError = class extends RGWError {
+  constructor(resource, id) {
+    super(`${resource} not found: "${id}"`, 404, "NoSuchResource");
+    this.name = "RGWNotFoundError";
+  }
+};
+var RGWValidationError = class extends RGWError {
+  constructor(message) {
+    super(message, void 0, "ValidationError");
+    this.name = "RGWValidationError";
+  }
+};
+var RGWAuthError = class extends RGWError {
+  constructor(message) {
+    super(message, 403, "AccessDenied");
+    this.name = "RGWAuthError";
+  }
+};
+var RGWConflictError = class extends RGWError {
+  constructor(resource, id) {
+    super(`${resource} already exists: "${id}"`, 409, "AlreadyExists");
+    this.name = "RGWConflictError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_ADMIN_PATH = "/admin";
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_REGION = "us-east-1";
+function validateConfig(config) {
+  if (!config.host || typeof config.host !== "string") {
+    throw new RGWValidationError("host is required and must be a non-empty string");
+  }
+  if (!config.accessKey || typeof config.accessKey !== "string") {
+    throw new RGWValidationError("accessKey is required and must be a non-empty string");
+  }
+  if (!config.secretKey || typeof config.secretKey !== "string") {
+    throw new RGWValidationError("secretKey is required and must be a non-empty string");
+  }
+  if (config.port !== void 0 && (config.port < 1 || config.port > 65535 || !Number.isInteger(config.port))) {
+    throw new RGWValidationError("port must be an integer between 1 and 65535");
+  }
+  if (config.timeout !== void 0 && (config.timeout < 0 || !Number.isFinite(config.timeout))) {
+    throw new RGWValidationError("timeout must be a non-negative finite number");
+  }
+  if (config.maxRetries !== void 0 && (config.maxRetries < 0 || !Number.isInteger(config.maxRetries))) {
+    throw new RGWValidationError("maxRetries must be a non-negative integer");
+  }
+  if (config.retryDelay !== void 0 && (config.retryDelay < 0 || !Number.isFinite(config.retryDelay))) {
+    throw new RGWValidationError("retryDelay must be a non-negative finite number");
+  }
+}
+function toCamelCase(obj) {
+  if (Array.isArray(obj)) return obj.map(toCamelCase);
+  if (obj !== null && typeof obj === "object") {
+    return Object.fromEntries(
+      Object.entries(obj).map(([k, v]) => [
+        k.replaceAll(/[-_.]([a-z])/g, (_, c) => c.toUpperCase()),
+        toCamelCase(v)
+      ])
+    );
+  }
+  return obj;
+}
+function toKebabCase(key) {
+  return key.replaceAll(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+function mapHttpError(status, body, code) {
+  switch (status) {
+    case 404:
+      return new RGWNotFoundError("Resource", code ?? "unknown");
+    case 403:
+      return new RGWAuthError(
+        body || "Access denied. Check your admin credentials and user capabilities."
+      );
+    case 409:
+      return new RGWConflictError("Resource", code ?? "unknown");
+    case 400:
+      return new RGWValidationError(body || "Invalid request parameters");
+    default:
+      return new RGWError(body || `HTTP ${status}`, status, code);
+  }
+}
+var BaseClient = class {
+  host;
+  port;
+  accessKey;
+  secretKey;
+  adminPath;
+  timeout;
+  region;
+  debug;
+  maxRetries;
+  retryDelay;
+  insecure;
+  constructor(config) {
+    validateConfig(config);
+    let host = config.host;
+    while (host.endsWith("/")) {
+      host = host.slice(0, -1);
+    }
+    this.host = host;
+    this.port = config.port;
+    this.accessKey = config.accessKey;
+    this.secretKey = config.secretKey;
+    this.adminPath = config.adminPath ?? DEFAULT_ADMIN_PATH;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.region = config.region ?? DEFAULT_REGION;
+    this.debug = config.debug ?? false;
+    this.maxRetries = config.maxRetries ?? 0;
+    this.retryDelay = config.retryDelay ?? 200;
+    this.insecure = config.insecure ?? false;
+    if (this.insecure) {
+      this.log("WARNING: TLS certificate verification is disabled");
+    }
+  }
+  /**
+   * Logs a debug message with optional structured data.
+   */
+  log(message, data) {
+    if (!this.debug) return;
+    const prefix = "[radosgw-admin]";
+    if (data) {
+      console.debug(prefix, message, JSON.stringify(data, null, 2));
+    } else {
+      console.debug(prefix, message);
+    }
+  }
+  /**
+   * Determines whether an error is retryable (5xx, timeouts, network errors).
+   */
+  isRetryable(error) {
+    if (error instanceof RGWError) {
+      if (error.statusCode !== void 0) {
+        return error.statusCode >= 500;
+      }
+      if (error.code === "NetworkError" || error.code === "Timeout") {
+        return true;
+      }
+    }
+    if (error instanceof Error) {
+      return error.name === "AbortError" || this.hasNetworkErrorPattern(error);
+    }
+    return false;
+  }
+  /**
+   * Checks an error and its cause chain for network error patterns.
+   */
+  hasNetworkErrorPattern(error) {
+    const patterns = [
+      "ECONNRESET",
+      "ECONNREFUSED",
+      "ETIMEDOUT",
+      "ENOTFOUND",
+      "EHOSTUNREACH",
+      "ENETUNREACH",
+      "ECONNABORTED",
+      "fetch failed"
+    ];
+    let current = error;
+    while (current) {
+      if (patterns.some((p) => current.message.includes(p))) {
+        return true;
+      }
+      current = current.cause instanceof Error ? current.cause : void 0;
+    }
+    return false;
+  }
+  /**
+   * Returns a promise that resolves after the given number of milliseconds.
+   */
+  async delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Makes a signed HTTP request to the RGW Admin API with retry support.
+   *
+   * @param options - Request method, path, query params, and optional body
+   * @returns Parsed and camelCase-transformed JSON response, or void for empty responses
+   */
+  async request(options) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        const backoff = this.retryDelay * Math.pow(2, attempt - 1);
+        this.log(`retry ${attempt}/${this.maxRetries} after ${backoff}ms`);
+        await this.delay(backoff);
+      }
+      try {
+        return await this.executeRequest(options);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        this.log("error", { error: lastError.message });
+        if (attempt < this.maxRetries && this.isRetryable(error)) {
+          this.log("retryable error", { error: lastError.message, attempt });
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError ?? new RGWError("Request failed after retries", void 0, "RetryExhausted");
+  }
+  /**
+   * Builds the full request URL with query parameters.
+   */
+  buildUrl(path, query) {
+    const baseUrl = this.port ? `${this.host}:${this.port}` : this.host;
+    const fullPath = `${this.adminPath}${path}`;
+    const url = new URL(fullPath, baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          url.searchParams.set(toKebabCase(key), String(value));
+        }
+      }
+    }
+    url.searchParams.set("format", "json");
+    return url;
+  }
+  /**
+   * Temporarily disables TLS certificate verification for insecure mode.
+   * Returns the previous value so it can be restored.
+   */
+  disableTlsVerification() {
+    const prev = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    return prev;
+  }
+  /**
+   * Restores the TLS verification setting to its previous value.
+   */
+  restoreTlsVerification(prev) {
+    if (prev === void 0) {
+      delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    } else {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = prev;
+    }
+  }
+  /**
+   * Parses an error response body to extract the RGW error code.
+   */
+  parseErrorCode(text) {
+    try {
+      const errorBody = JSON.parse(text);
+      return errorBody.Code ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Wraps a non-RGW error into the appropriate RGW error type.
+   */
+  wrapFetchError(error) {
+    if (error instanceof RGWError) return error;
+    if (error instanceof Error && error.name === "AbortError") {
+      return new RGWError(`Request timed out after ${this.timeout}ms`, void 0, "Timeout");
+    }
+    return new RGWError(
+      error instanceof Error ? error.message : "Unknown error occurred",
+      void 0,
+      "NetworkError"
+    );
+  }
+  /**
+   * Executes a single signed HTTP request to the RGW Admin API.
+   */
+  async executeRequest(options) {
+    const { method, path, query, body } = options;
+    const url = this.buildUrl(path, query);
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const signedHeaders = signRequest({
+      method,
+      url,
+      headers,
+      accessKey: this.accessKey,
+      secretKey: this.secretKey,
+      region: this.region
+    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const prevTls = this.insecure ? this.disableTlsVerification() : void 0;
+    try {
+      const fetchOptions = {
+        method,
+        headers: { ...headers, ...signedHeaders },
+        signal: controller.signal
+      };
+      if (body) {
+        fetchOptions.body = JSON.stringify(body);
+      }
+      const safeUrl = url.toString().replaceAll(/([?&]secret-key=)[^&]*/gi, "$1[REDACTED]");
+      this.log("request", { method, url: safeUrl });
+      const response = await fetch(url.toString(), fetchOptions);
+      const text = await response.text();
+      if (!response.ok) {
+        throw mapHttpError(response.status, text, this.parseErrorCode(text));
+      }
+      this.log("response", { status: response.status, body: text.slice(0, 500) });
+      if (!text) {
+        return void 0;
+      }
+      const parsed = JSON.parse(text);
+      return toCamelCase(parsed);
+    } catch (error) {
+      throw this.wrapFetchError(error);
+    } finally {
+      clearTimeout(timeoutId);
+      if (this.insecure) {
+        this.restoreTlsVerification(prevTls);
+      }
+    }
+  }
+};
+
+// src/validators.ts
+function validateUid(uid) {
+  if (!uid || typeof uid !== "string" || uid.trim() !== uid || uid.trim().length === 0) {
+    throw new RGWValidationError(
+      "uid is required and must be a non-empty string without leading/trailing whitespace"
+    );
+  }
+}
+function validateUidNoColon(uid) {
+  validateUid(uid);
+  if (uid.includes(":")) {
+    throw new RGWValidationError(
+      'uid must not contain colons \u2014 colons are reserved for subuser notation (e.g. "uid:subuser")'
+    );
+  }
+}
+
+// src/modules/users.ts
+function validateEmail(email) {
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw new RGWValidationError(
+      `Invalid email address: "${email}". Expected format: "user@domain.tld"`
+    );
+  }
+}
+function validateUserCaps(caps) {
+  if (!caps.trim()) {
+    throw new RGWValidationError("userCaps must not be empty if provided");
+  }
+  const capSegment = /^[a-z][a-z-]*=(?:\*|read,\s*write|read|write)$/i;
+  const valid = caps.split(";").map((s) => s.trim()).every((seg) => capSegment.test(seg));
+  if (!valid) {
+    throw new RGWValidationError(
+      `Invalid userCaps format: "${caps}". Expected "type=perm" or "type1=perm;type2=perm". Valid perms: *, read, write, "read, write". Example: "users=*;buckets=read"`
+    );
+  }
+}
+var UsersModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new RGW user.
+   *
+   * @param input - User creation parameters. `uid` and `displayName` are required.
+   * @returns The newly created user object with keys, caps, and quotas.
+   * @throws {RGWValidationError} If `uid` contains colons, `displayName` is blank,
+   *   `email` is malformed, or `userCaps` is an invalid capability string.
+   * @throws {RGWConflictError} If a user with the given `uid` already exists.
+   *
+   * @example
+   * ```typescript
+   * const user = await client.users.create({
+   *   uid: 'alice',
+   *   displayName: 'Alice Example',
+   *   email: 'alice@example.com',
+   *   maxBuckets: 100,
+   *   userCaps: 'users=read;buckets=*',
+   * });
+   * console.log(user.keys[0].accessKey);
+   * ```
+   */
+  async create(input) {
+    validateUidNoColon(input.uid);
+    if (!input.displayName || typeof input.displayName !== "string" || input.displayName.trim().length === 0) {
+      throw new RGWValidationError("displayName is required and must be a non-empty string");
+    }
+    if (input.displayName !== input.displayName.trim()) {
+      throw new RGWValidationError("displayName must not have leading or trailing whitespace");
+    }
+    if (input.email !== void 0) {
+      validateEmail(input.email);
+    }
+    if (input.userCaps !== void 0) {
+      validateUserCaps(input.userCaps);
+    }
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: {
+        uid: input.uid,
+        displayName: input.displayName,
+        email: input.email,
+        keyType: input.keyType,
+        accessKey: input.accessKey,
+        secretKey: input.secretKey,
+        userCaps: input.userCaps,
+        generateKey: input.generateKey,
+        maxBuckets: input.maxBuckets,
+        suspended: input.suspended,
+        tenant: input.tenant,
+        opMask: input.opMask
+      }
+    });
+  }
+  /**
+   * Get full user information including keys, caps, and quotas.
+   *
+   * For multi-tenant setups pass the `tenant` parameter instead of embedding
+   * it in the uid string. Both `get('alice', 'acme')` and `get('acme$alice')`
+   * resolve to the same user; the former is preferred for clarity.
+   *
+   * @param uid - The user ID (without tenant prefix).
+   * @param tenant - Optional tenant name. When provided, resolves to `tenant$uid`.
+   * @returns Full user object.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Standard lookup
+   * const user = await client.users.get('alice');
+   *
+   * // Multi-tenant lookup
+   * const tenantUser = await client.users.get('alice', 'acme');
+   * ```
+   */
+  async get(uid, tenant) {
+    validateUid(uid);
+    const effectiveUid = tenant ? `${tenant}$${uid}` : uid;
+    return this.client.request({
+      method: "GET",
+      path: "/user",
+      query: { uid: effectiveUid }
+    });
+  }
+  /**
+   * Look up a user by their S3 access key.
+   *
+   * Useful for mapping an incoming S3 request's access key to the owning user
+   * without knowing the uid in advance.
+   *
+   * @param accessKey - The S3 access key to look up.
+   * @returns The user that owns this access key.
+   * @throws {RGWValidationError} If `accessKey` is empty.
+   * @throws {RGWNotFoundError} If no user owns this access key.
+   *
+   * @example
+   * ```typescript
+   * const user = await client.users.getByAccessKey('AKIAIOSFODNN7EXAMPLE');
+   * console.log('Key belongs to:', user.userId);
+   * ```
+   */
+  async getByAccessKey(accessKey) {
+    if (!accessKey || typeof accessKey !== "string" || accessKey.trim().length === 0) {
+      throw new RGWValidationError("accessKey is required and must be a non-empty string");
+    }
+    return this.client.request({
+      method: "GET",
+      path: "/user",
+      query: { accessKey }
+    });
+  }
+  /**
+   * Modify an existing user's properties.
+   *
+   * Only the provided fields are updated — omitted fields retain their current values.
+   *
+   * @param input - Properties to update. `uid` is required; all other fields are optional.
+   * @returns The updated user object.
+   * @throws {RGWValidationError} If `uid` is empty, `email` is malformed,
+   *   or `userCaps` is an invalid capability string.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.users.modify({
+   *   uid: 'alice',
+   *   displayName: 'Alice Updated',
+   *   maxBuckets: 200,
+   *   opMask: 'read, write',
+   * });
+   * ```
+   */
+  async modify(input) {
+    validateUid(input.uid);
+    if (input.email !== void 0) {
+      validateEmail(input.email);
+    }
+    if (input.userCaps !== void 0) {
+      validateUserCaps(input.userCaps);
+    }
+    return this.client.request({
+      method: "POST",
+      path: "/user",
+      query: {
+        uid: input.uid,
+        displayName: input.displayName,
+        email: input.email,
+        maxBuckets: input.maxBuckets,
+        suspended: input.suspended,
+        userCaps: input.userCaps,
+        opMask: input.opMask
+      }
+    });
+  }
+  /**
+   * Delete a user. Optionally purge all user data (buckets and objects).
+   *
+   * @param input - `uid` is required. Set `purgeData: true` to delete all objects.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Safe delete — fails if user owns buckets
+   * await client.users.delete({ uid: 'alice' });
+   *
+   * // ⚠️  Force delete with full data purge
+   * await client.users.delete({ uid: 'alice', purgeData: true });
+   * ```
+   */
+  async delete(input) {
+    validateUid(input.uid);
+    if (input.purgeData) {
+      console.warn(
+        `[radosgw-admin] WARNING: purgeData=true will permanently delete all objects for user "${input.uid}"`
+      );
+    }
+    return this.client.request({
+      method: "DELETE",
+      path: "/user",
+      query: {
+        uid: input.uid,
+        purgeData: input.purgeData
+      }
+    });
+  }
+  /**
+   * List all user IDs in the cluster (or tenant).
+   *
+   * Returns the full list in a single call. The RGW `/metadata/user` endpoint
+   * supports `marker` and `max-entries` for server-side pagination, but has a
+   * default limit of 1000 entries. This method requests up to 100,000 entries
+   * to avoid silent truncation on large clusters.
+   *
+   * For clusters with more than 100k users, use the planned `paginate()` method
+   * (see v1.6 roadmap).
+   *
+   * @returns Array of user ID strings.
+   *
+   * @example
+   * ```typescript
+   * const uids = await client.users.list();
+   * console.log('Total users:', uids.length);
+   * ```
+   */
+  async list() {
+    const result = await this.client.request({
+      method: "GET",
+      path: "/metadata/user",
+      query: { maxEntries: 1e5 }
+    });
+    if (Array.isArray(result)) {
+      return result;
+    }
+    return result.keys;
+  }
+  /**
+   * Suspend a user account. The user's data is preserved but all API access is denied.
+   *
+   * @param uid - The user ID to suspend.
+   * @returns The updated user object with `suspended: 1`.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const suspended = await client.users.suspend('alice');
+   * console.log(suspended.suspended); // 1
+   * ```
+   */
+  async suspend(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "POST",
+      path: "/user",
+      query: { uid, suspended: true }
+    });
+  }
+  /**
+   * Re-enable a suspended user account.
+   *
+   * @param uid - The user ID to enable.
+   * @returns The updated user object with `suspended: 0`.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const enabled = await client.users.enable('alice');
+   * console.log(enabled.suspended); // 0
+   * ```
+   */
+  async enable(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "POST",
+      path: "/user",
+      query: { uid, suspended: false }
+    });
+  }
+  /**
+   * Get storage usage statistics for a user.
+   *
+   * Returns the full user object with an additional `stats` field containing:
+   * - `size` / `sizeKb` — logical bytes/KB used
+   * - `sizeActual` / `sizeKbActual` — bytes/KB on disk (accounting for alignment)
+   * - `sizeUtilized` / `sizeKbUtilized` — bytes/KB utilized (used + overhead)
+   * - `numObjects` — total number of objects stored
+   *
+   * Pass `sync: true` to force RGW to recalculate stats from the backing store
+   * before returning (slower but accurate).
+   *
+   * @param uid - The user ID.
+   * @param sync - If true, forces a stats sync before returning. Default: false.
+   * @returns User object with embedded {@link RGWUserStatData} `stats` field.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Fast read (may be slightly stale)
+   * const result = await client.users.getStats('alice');
+   *
+   * // Force sync — accurate but slower
+   * const synced = await client.users.getStats('alice', true);
+   *
+   * console.log('Objects:', result.stats.numObjects);
+   * console.log('Size (KB):', result.stats.sizeKb);
+   * console.log('Actual disk (KB):', result.stats.sizeKbActual);
+   * ```
+   */
+  async getStats(uid, sync) {
+    validateUid(uid);
+    return this.client.request({
+      method: "GET",
+      path: "/user",
+      query: {
+        uid,
+        stats: true,
+        sync
+      }
+    });
+  }
+};
+
+// src/modules/keys.ts
+var KeysModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Generate a new S3 or Swift key for a user.
+   *
+   * Returns the user's **entire** key list after the operation, not just the
+   * newly created key. To identify the new key, compare with the key list
+   * before generation or look for the last entry.
+   *
+   * @param input - Key generation parameters. `uid` is required.
+   * @returns Array of **all** keys belonging to the user after generation.
+   * @throws {RGWValidationError} If `uid` is missing or invalid.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Auto-generate a new S3 key
+   * const allKeys = await client.keys.generate({ uid: 'alice' });
+   * const newKey = allKeys[allKeys.length - 1]; // newest key is last
+   * console.log('New key:', newKey.accessKey);
+   *
+   * // Supply specific credentials (disable auto-generation)
+   * const allKeys = await client.keys.generate({
+   *   uid: 'alice',
+   *   accessKey: 'MY_ACCESS_KEY',
+   *   secretKey: 'MY_SECRET_KEY',
+   *   generateKey: false,
+   * });
+   * ```
+   */
+  async generate(input) {
+    validateUid(input.uid);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: {
+        key: "",
+        uid: input.uid,
+        keyType: input.keyType,
+        accessKey: input.accessKey,
+        secretKey: input.secretKey,
+        generateKey: input.generateKey
+      }
+    });
+  }
+  /**
+   * Revoke an S3 or Swift key.
+   *
+   * @param input - `accessKey` is required. `uid` is required for Swift keys.
+   * @returns Resolves when the key has been revoked.
+   * @throws {RGWValidationError} If `accessKey` is missing.
+   * @throws {RGWNotFoundError} If the key does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Revoke an S3 key by access key ID
+   * await client.keys.revoke({ accessKey: 'OLDKEY123' });
+   *
+   * // Revoke a Swift key (uid required)
+   * await client.keys.revoke({
+   *   accessKey: 'SWIFTKEY',
+   *   uid: 'alice',
+   *   keyType: 'swift',
+   * });
+   * ```
+   */
+  async revoke(input) {
+    if (!input.accessKey || typeof input.accessKey !== "string" || input.accessKey.trim().length === 0) {
+      throw new RGWValidationError("accessKey is required and must be a non-empty string");
+    }
+    if (input.keyType === "swift" && !input.uid) {
+      throw new RGWValidationError('uid is required when revoking a Swift key (keyType: "swift")');
+    }
+    return this.client.request({
+      method: "DELETE",
+      path: "/user",
+      query: {
+        key: "",
+        accessKey: input.accessKey,
+        uid: input.uid,
+        keyType: input.keyType
+      }
+    });
+  }
+};
+
+// src/modules/subusers.ts
+function validateSubuser(subuser) {
+  if (!subuser || typeof subuser !== "string" || subuser.trim().length === 0) {
+    throw new RGWValidationError("subuser is required and must be a non-empty string");
+  }
+  if (!subuser.includes(":")) {
+    throw new RGWValidationError('subuser must be in "uid:name" format (e.g. "alice:swift")');
+  }
+}
+var SubusersModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new subuser for a user.
+   *
+   * Returns the user's **entire** subuser list after the operation, not just the
+   * newly created subuser. To identify the new entry, compare with the list
+   * before creation or look for the matching `id`.
+   *
+   * @param input - Subuser creation parameters. `uid` and `subuser` are required.
+   *   `subuser` must be in `uid:name` format (e.g. `"alice:swift"`).
+   * @returns Array of **all** subusers belonging to the user after creation.
+   * @throws {RGWValidationError} If `uid` or `subuser` is missing, invalid, or not in `uid:name` format.
+   * @throws {RGWNotFoundError} If the parent user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const subusers = await client.subusers.create({
+   *   uid: 'alice',
+   *   subuser: 'alice:swift',
+   *   access: 'readwrite',
+   *   keyType: 'swift',
+   *   generateSecret: true,
+   * });
+   * console.log(subusers[0].id, subusers[0].permissions);
+   * ```
+   */
+  async create(input) {
+    validateUid(input.uid);
+    validateSubuser(input.subuser);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: {
+        subuser: input.subuser,
+        uid: input.uid,
+        secretKey: input.secretKey,
+        keyType: input.keyType,
+        access: input.access,
+        generateSecret: input.generateSecret
+      }
+    });
+  }
+  /**
+   * Modify an existing subuser's properties.
+   *
+   * @param input - Properties to update. `uid` and `subuser` are required.
+   * @returns Array of subusers belonging to the user after modification.
+   * @throws {RGWValidationError} If `uid` or `subuser` is missing or invalid.
+   * @throws {RGWNotFoundError} If the parent user or subuser does not exist.
+   *
+   * @example
+   * ```typescript
+   * const subusers = await client.subusers.modify({
+   *   uid: 'alice',
+   *   subuser: 'alice:swift',
+   *   access: 'full',
+   * });
+   * ```
+   */
+  async modify(input) {
+    validateUid(input.uid);
+    validateSubuser(input.subuser);
+    return this.client.request({
+      method: "POST",
+      path: "/user",
+      query: {
+        subuser: input.subuser,
+        uid: input.uid,
+        secretKey: input.secretKey,
+        keyType: input.keyType,
+        access: input.access,
+        generateSecret: input.generateSecret
+      }
+    });
+  }
+  /**
+   * Remove a subuser from a user. Optionally purge the subuser's keys.
+   *
+   * @param input - `uid` and `subuser` are required. `purgeKeys` defaults to true.
+   * @returns Resolves when the subuser has been removed.
+   * @throws {RGWValidationError} If `uid` or `subuser` is missing or invalid.
+   * @throws {RGWNotFoundError} If the parent user or subuser does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Remove subuser and purge keys
+   * await client.subusers.remove({
+   *   uid: 'alice',
+   *   subuser: 'alice:swift',
+   * });
+   *
+   * // Remove subuser but keep keys
+   * await client.subusers.remove({
+   *   uid: 'alice',
+   *   subuser: 'alice:swift',
+   *   purgeKeys: false,
+   * });
+   * ```
+   */
+  async remove(input) {
+    validateUid(input.uid);
+    validateSubuser(input.subuser);
+    if (input.purgeKeys === true) {
+      console.warn(
+        `[radosgw-admin] WARNING: purgeKeys=true will permanently delete all keys for subuser "${input.subuser}"`
+      );
+    }
+    return this.client.request({
+      method: "DELETE",
+      path: "/user",
+      query: {
+        subuser: input.subuser,
+        uid: input.uid,
+        purgeKeys: input.purgeKeys
+      }
+    });
+  }
+};
+
+// src/modules/buckets.ts
+function validateBucket(bucket) {
+  if (!bucket || typeof bucket !== "string" || bucket.trim().length === 0) {
+    throw new RGWValidationError("bucket is required and must be a non-empty string");
+  }
+}
+var BucketsModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all buckets in the cluster.
+   *
+   * The RGW `/bucket` endpoint has a default limit of 1000 entries.
+   * This method requests up to 100,000 entries to avoid silent truncation
+   * on large clusters.
+   *
+   * For clusters with more than 100k buckets, use the planned `paginate()`
+   * method (see v1.6 roadmap).
+   *
+   * @returns Array of bucket name strings.
+   *
+   * @example
+   * ```typescript
+   * const all = await client.buckets.list();
+   * console.log(`Cluster has ${all.length} buckets`);
+   * ```
+   */
+  async list() {
+    const result = await this.client.request({
+      method: "GET",
+      path: "/bucket",
+      query: { maxEntries: 1e5 }
+    });
+    if (Array.isArray(result)) {
+      return result;
+    }
+    return result.buckets;
+  }
+  /**
+   * List buckets owned by a specific user.
+   *
+   * @param uid - User ID to filter buckets by. Required.
+   * @returns Array of bucket name strings owned by the user.
+   * @throws {RGWValidationError} If `uid` is missing or invalid.
+   *
+   * @example
+   * ```typescript
+   * const userBuckets = await client.buckets.listByUser('alice');
+   * console.log(`alice has ${userBuckets.length} buckets`);
+   * ```
+   */
+  async listByUser(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "GET",
+      path: "/bucket",
+      query: { uid }
+    });
+  }
+  /**
+   * Get detailed metadata about a bucket.
+   *
+   * @param bucket - The bucket name to inspect.
+   * @returns Full bucket object with owner, usage, quota, and placement info.
+   * @throws {RGWValidationError} If `bucket` is empty.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * const info = await client.buckets.getInfo('my-bucket');
+   * console.log(`Owner: ${info.owner}`);
+   * console.log(`Objects: ${info.usage.rgwMain.numObjects}`);
+   * console.log(`Size: ${(info.usage.rgwMain.sizeKb / 1024).toFixed(2)} MB`);
+   * ```
+   */
+  async getInfo(bucket) {
+    validateBucket(bucket);
+    return this.client.request({
+      method: "GET",
+      path: "/bucket",
+      query: { bucket }
+    });
+  }
+  /**
+   * Delete a bucket. Optionally purge all objects inside it.
+   *
+   * @param input - `bucket` is required. Set `purgeObjects: true` to delete all objects.
+   * @returns Resolves when the bucket has been deleted.
+   * @throws {RGWValidationError} If `bucket` is empty.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Safe delete (fails if bucket has objects)
+   * await client.buckets.delete({ bucket: 'my-bucket' });
+   *
+   * // Force delete with object purge
+   * await client.buckets.delete({ bucket: 'my-bucket', purgeObjects: true });
+   * ```
+   */
+  async delete(input) {
+    validateBucket(input.bucket);
+    if (input.purgeObjects) {
+      console.warn(
+        `[radosgw-admin] WARNING: purgeObjects=true will permanently delete all objects in bucket "${input.bucket}"`
+      );
+    }
+    return this.client.request({
+      method: "DELETE",
+      path: "/bucket",
+      query: {
+        bucket: input.bucket,
+        purgeObjects: input.purgeObjects
+      }
+    });
+  }
+  /**
+   * Transfer ownership of a bucket to a different user.
+   *
+   * @param input - `bucket`, `bucketId`, and `uid` are all required.
+   * @returns Resolves when ownership has been transferred.
+   * @throws {RGWValidationError} If any required field is missing.
+   * @throws {RGWNotFoundError} If the bucket or user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const info = await client.buckets.getInfo('my-bucket');
+   * await client.buckets.transferOwnership({
+   *   bucket: 'my-bucket',
+   *   bucketId: info.id,
+   *   uid: 'bob',
+   * });
+   * ```
+   */
+  async transferOwnership(input) {
+    validateBucket(input.bucket);
+    validateUid(input.uid);
+    if (!input.bucketId || typeof input.bucketId !== "string" || input.bucketId.trim().length === 0) {
+      throw new RGWValidationError("bucketId is required and must be a non-empty string");
+    }
+    return this.client.request({
+      method: "PUT",
+      path: "/bucket",
+      query: {
+        bucket: input.bucket,
+        bucketId: input.bucketId,
+        uid: input.uid
+      }
+    });
+  }
+  /**
+   * Remove ownership of a bucket from a user without deleting the bucket.
+   *
+   * **Warning:** This leaves the bucket in an orphaned state with no owner.
+   * The bucket and its objects remain intact but cannot be managed via the
+   * S3 API until ownership is reassigned with {@link transferOwnership}.
+   *
+   * @param input - `bucket` and `uid` are required.
+   * @returns Resolves when ownership has been removed.
+   * @throws {RGWValidationError} If any required field is missing.
+   * @throws {RGWNotFoundError} If the bucket or user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.buckets.removeOwnership({
+   *   bucket: 'my-bucket',
+   *   uid: 'alice',
+   * });
+   * ```
+   */
+  async removeOwnership(input) {
+    validateBucket(input.bucket);
+    validateUid(input.uid);
+    return this.client.request({
+      method: "POST",
+      path: "/bucket",
+      query: {
+        bucket: input.bucket,
+        uid: input.uid
+      }
+    });
+  }
+  /**
+   * Verify and optionally repair a bucket's index.
+   *
+   * With `fix: false` (default), this is a safe read-only operation that reports
+   * any inconsistencies. Set `fix: true` to actually repair detected issues.
+   *
+   * @param input - `bucket` is required. `checkObjects` and `fix` are optional.
+   * @returns Index check result with invalid entries and header comparison.
+   * @throws {RGWValidationError} If `bucket` is empty.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * // Dry run — check only
+   * const result = await client.buckets.verifyIndex({
+   *   bucket: 'my-bucket',
+   *   checkObjects: true,
+   *   fix: false,
+   * });
+   * console.log('Invalid entries:', result.invalidMultipartEntries);
+   *
+   * // Fix detected issues
+   * await client.buckets.verifyIndex({
+   *   bucket: 'my-bucket',
+   *   fix: true,
+   * });
+   * ```
+   */
+  async verifyIndex(input) {
+    validateBucket(input.bucket);
+    if (input.fix === true) {
+      console.warn(
+        `[radosgw-admin] WARNING: fix=true will repair the bucket index for "${input.bucket}" \u2014 this mutates index data`
+      );
+    }
+    return this.client.request({
+      method: "GET",
+      path: "/bucket",
+      query: {
+        index: "",
+        bucket: input.bucket,
+        checkObjects: input.checkObjects,
+        fix: input.fix
+      }
+    });
+  }
+};
+
+// src/modules/quota.ts
+function validateQuotaValue(field, value) {
+  if (value !== void 0 && typeof value === "number" && value < -1) {
+    throw new RGWValidationError(`${field} must be -1 (unlimited) or >= 0, got ${value}`);
+  }
+}
+function parseSizeString(size) {
+  if (typeof size === "number") return size;
+  const units = {
+    K: 1024,
+    M: 1024 ** 2,
+    G: 1024 ** 3,
+    T: 1024 ** 4
+  };
+  const match = size.toUpperCase().trim().match(/^(\d+(?:\.\d+)?)\s*([KMGT]?)B?$/);
+  if (!match) {
+    throw new RGWValidationError(
+      `Invalid size string: "${size}". Use format like "10G", "500M", "1T", or a number in bytes`
+    );
+  }
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+  return Math.floor(value * (units[unit] ?? 1));
+}
+var QuotaModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the user-level quota for a user.
+   *
+   * @param uid - The user ID.
+   * @returns The user's quota configuration.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const quota = await client.quota.getUserQuota('alice');
+   * console.log('Enabled:', quota.enabled);
+   * console.log('Max size:', quota.maxSize, 'bytes');
+   * console.log('Max objects:', quota.maxObjects);
+   * ```
+   */
+  async getUserQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "GET",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "user" }
+    });
+  }
+  /**
+   * Set the user-level quota for a user.
+   *
+   * The `maxSize` field accepts either a number (bytes) or a human-readable string
+   * like `"10G"`, `"500M"`, `"1T"`.
+   *
+   * @param input - Quota settings. `uid` is required.
+   * @throws {RGWValidationError} If `uid` is empty, `maxSize` format is invalid, or `maxSize`/`maxObjects` is a negative number other than -1.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.setUserQuota({
+   *   uid: 'alice',
+   *   maxSize: '10G',
+   *   maxObjects: 50000,
+   *   enabled: true,
+   * });
+   * ```
+   */
+  async setUserQuota(input) {
+    validateUid(input.uid);
+    validateQuotaValue("maxObjects", input.maxObjects);
+    const maxSize = input.maxSize !== void 0 ? parseSizeString(input.maxSize) : void 0;
+    validateQuotaValue("maxSize", maxSize);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: {
+        uid: input.uid,
+        quota: "",
+        quotaType: "user",
+        maxSize,
+        maxObjects: input.maxObjects,
+        enabled: input.enabled ?? true
+      }
+    });
+  }
+  /**
+   * Enable the user-level quota for a user without changing quota values.
+   *
+   * @param uid - The user ID.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.enableUserQuota('alice');
+   * ```
+   */
+  async enableUserQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "user", enabled: true }
+    });
+  }
+  /**
+   * Disable the user-level quota for a user without changing quota values.
+   *
+   * @param uid - The user ID.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.disableUserQuota('alice');
+   * ```
+   */
+  async disableUserQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "user", enabled: false }
+    });
+  }
+  /**
+   * Get the bucket-level quota for a user.
+   *
+   * This returns the per-bucket quota applied to all buckets owned by the user,
+   * not a quota for a specific bucket. RGW bucket quotas are configured per-user.
+   *
+   * @param uid - The user ID (bucket owner), not a bucket name.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const quota = await client.quota.getBucketQuota('alice');
+   * console.log('Bucket quota enabled:', quota.enabled);
+   * ```
+   */
+  async getBucketQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "GET",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "bucket" }
+    });
+  }
+  /**
+   * Set the bucket-level quota for a user's buckets.
+   *
+   * The `maxSize` field accepts either a number (bytes) or a human-readable string
+   * like `"1G"`, `"500M"`.
+   *
+   * @param input - Quota settings. `uid` is required.
+   * @throws {RGWValidationError} If `uid` is empty, `maxSize` format is invalid, or `maxSize`/`maxObjects` is a negative number other than -1.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.setBucketQuota({
+   *   uid: 'alice',
+   *   maxSize: '1G',
+   *   maxObjects: 10000,
+   *   enabled: true,
+   * });
+   * ```
+   */
+  async setBucketQuota(input) {
+    validateUid(input.uid);
+    validateQuotaValue("maxObjects", input.maxObjects);
+    const maxSize = input.maxSize !== void 0 ? parseSizeString(input.maxSize) : void 0;
+    validateQuotaValue("maxSize", maxSize);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: {
+        uid: input.uid,
+        quota: "",
+        quotaType: "bucket",
+        maxSize,
+        maxObjects: input.maxObjects,
+        enabled: input.enabled ?? true
+      }
+    });
+  }
+  /**
+   * Enable the bucket-level quota for a user without changing quota values.
+   *
+   * @param uid - The user ID.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.enableBucketQuota('alice');
+   * ```
+   */
+  async enableBucketQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "bucket", enabled: true }
+    });
+  }
+  /**
+   * Disable the bucket-level quota for a user without changing quota values.
+   *
+   * @param uid - The user ID.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.quota.disableBucketQuota('alice');
+   * ```
+   */
+  async disableBucketQuota(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "PUT",
+      path: "/user",
+      query: { uid, quota: "", quotaType: "bucket", enabled: false }
+    });
+  }
+};
+
+// src/modules/ratelimit.ts
+function validateBucket2(bucket) {
+  if (!bucket || typeof bucket !== "string" || bucket.trim().length === 0) {
+    throw new RGWValidationError("bucket is required and must be a non-empty string");
+  }
+}
+function validateRateLimitValue(field, value) {
+  if (value !== void 0 && typeof value === "number" && value < 0) {
+    throw new RGWValidationError(`${field} must be >= 0 (0 = unlimited), got ${value}`);
+  }
+}
+function validateRateLimitFields(input) {
+  validateRateLimitValue("maxReadOps", input.maxReadOps);
+  validateRateLimitValue("maxWriteOps", input.maxWriteOps);
+  validateRateLimitValue("maxReadBytes", input.maxReadBytes);
+  validateRateLimitValue("maxWriteBytes", input.maxWriteBytes);
+}
+var RateLimitModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the rate limit configuration for a user.
+   *
+   * @param uid - The user ID.
+   * @returns The user's rate limit configuration.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * const limit = await client.rateLimit.getUserLimit('alice');
+   * console.log('Read ops/min:', limit.maxReadOps);
+   * console.log('Write ops/min:', limit.maxWriteOps);
+   * ```
+   */
+  async getUserLimit(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "GET",
+      path: "/ratelimit",
+      query: { ratelimit: "", uid, scope: "user" }
+    });
+  }
+  /**
+   * Set the rate limit for a user.
+   *
+   * Values are per RGW instance. Divide by the number of RGW daemons for cluster-wide limits.
+   *
+   * @param input - Rate limit settings. `uid` is required. `enabled` defaults to `true`.
+   * @throws {RGWValidationError} If `uid` is empty or any rate limit value is negative.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.rateLimit.setUserLimit({
+   *   uid: 'alice',
+   *   maxReadOps: 100,
+   *   maxWriteOps: 50,
+   *   maxWriteBytes: 52428800, // 50MB/min
+   *   enabled: true,
+   * });
+   * ```
+   */
+  async setUserLimit(input) {
+    validateUid(input.uid);
+    validateRateLimitFields(input);
+    return this.client.request({
+      method: "POST",
+      path: "/ratelimit",
+      query: {
+        ratelimit: "",
+        uid: input.uid,
+        scope: "user",
+        maxReadOps: input.maxReadOps,
+        maxWriteOps: input.maxWriteOps,
+        maxReadBytes: input.maxReadBytes,
+        maxWriteBytes: input.maxWriteBytes,
+        enabled: input.enabled ?? true
+      }
+    });
+  }
+  /**
+   * Disable the rate limit for a user without changing the configured values.
+   *
+   * @param uid - The user ID.
+   * @throws {RGWValidationError} If `uid` is empty.
+   * @throws {RGWNotFoundError} If the user does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.rateLimit.disableUserLimit('alice');
+   * ```
+   */
+  async disableUserLimit(uid) {
+    validateUid(uid);
+    return this.client.request({
+      method: "POST",
+      path: "/ratelimit",
+      query: { ratelimit: "", uid, scope: "user", enabled: false }
+    });
+  }
+  /**
+   * Get the rate limit configuration for a bucket.
+   *
+   * @param bucket - The bucket name.
+   * @returns The bucket's rate limit configuration.
+   * @throws {RGWValidationError} If `bucket` is empty.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * const limit = await client.rateLimit.getBucketLimit('my-bucket');
+   * console.log('Read ops/min:', limit.maxReadOps);
+   * ```
+   */
+  async getBucketLimit(bucket) {
+    validateBucket2(bucket);
+    return this.client.request({
+      method: "GET",
+      path: "/ratelimit",
+      query: { ratelimit: "", bucket, scope: "bucket" }
+    });
+  }
+  /**
+   * Set the rate limit for a bucket.
+   *
+   * Values are per RGW instance. Divide by the number of RGW daemons for cluster-wide limits.
+   *
+   * @param input - Rate limit settings. `bucket` is required. `enabled` defaults to `true`.
+   * @throws {RGWValidationError} If `bucket` is empty or any rate limit value is negative.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.rateLimit.setBucketLimit({
+   *   bucket: 'my-bucket',
+   *   maxReadOps: 200,
+   *   maxWriteOps: 100,
+   *   enabled: true,
+   * });
+   * ```
+   */
+  async setBucketLimit(input) {
+    validateBucket2(input.bucket);
+    validateRateLimitFields(input);
+    return this.client.request({
+      method: "POST",
+      path: "/ratelimit",
+      query: {
+        ratelimit: "",
+        bucket: input.bucket,
+        scope: "bucket",
+        maxReadOps: input.maxReadOps,
+        maxWriteOps: input.maxWriteOps,
+        maxReadBytes: input.maxReadBytes,
+        maxWriteBytes: input.maxWriteBytes,
+        enabled: input.enabled ?? true
+      }
+    });
+  }
+  /**
+   * Disable the rate limit for a bucket without changing the configured values.
+   *
+   * @param bucket - The bucket name.
+   * @throws {RGWValidationError} If `bucket` is empty.
+   * @throws {RGWNotFoundError} If the bucket does not exist.
+   *
+   * @example
+   * ```typescript
+   * await client.rateLimit.disableBucketLimit('my-bucket');
+   * ```
+   */
+  async disableBucketLimit(bucket) {
+    validateBucket2(bucket);
+    return this.client.request({
+      method: "POST",
+      path: "/ratelimit",
+      query: { ratelimit: "", bucket, scope: "bucket", enabled: false }
+    });
+  }
+  /**
+   * Get the global rate limit configuration for all scopes (user, bucket, anonymous).
+   *
+   * @returns Global rate limits for user, bucket, and anonymous scopes.
+   *
+   * @example
+   * ```typescript
+   * const global = await client.rateLimit.getGlobal();
+   * console.log('Anonymous read limit:', global.anonymous.maxReadOps);
+   * ```
+   */
+  async getGlobal() {
+    return this.client.request({
+      method: "GET",
+      path: "/ratelimit",
+      query: { ratelimit: "", global: "" }
+    });
+  }
+  /**
+   * Set a global rate limit for a specific scope.
+   *
+   * Use `scope: 'anonymous'` to protect public-read buckets from abuse.
+   *
+   * @param input - Rate limit settings. `scope` is required. `enabled` defaults to `true`.
+   * @throws {RGWValidationError} If `scope` is invalid or any rate limit value is negative.
+   *
+   * @example
+   * ```typescript
+   * // Limit anonymous access globally
+   * await client.rateLimit.setGlobal({
+   *   scope: 'anonymous',
+   *   maxReadOps: 50,
+   *   maxWriteOps: 0,
+   *   enabled: true,
+   * });
+   * ```
+   */
+  async setGlobal(input) {
+    const validScopes = ["user", "bucket", "anonymous"];
+    if (!validScopes.includes(input.scope)) {
+      throw new RGWValidationError(
+        `scope must be one of: ${validScopes.join(", ")}. Got: "${input.scope}"`
+      );
+    }
+    validateRateLimitFields(input);
+    return this.client.request({
+      method: "POST",
+      path: "/ratelimit",
+      query: {
+        ratelimit: "",
+        global: "",
+        scope: input.scope,
+        maxReadOps: input.maxReadOps,
+        maxWriteOps: input.maxWriteOps,
+        maxReadBytes: input.maxReadBytes,
+        maxWriteBytes: input.maxWriteBytes,
+        enabled: input.enabled ?? true
+      }
+    });
+  }
+};
+
+// src/modules/usage.ts
+function normalizeDate(value) {
+  if (value instanceof Date) {
+    if (isNaN(value.getTime())) {
+      throw new RGWValidationError("Invalid Date object provided for date range filter");
+    }
+    return value.toISOString().slice(0, 10);
+  }
+  if (!/^\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2}:\d{2})?$/.test(value.trim())) {
+    throw new RGWValidationError(
+      `Invalid date string: "${value}". Use "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS"`
+    );
+  }
+  return value.trim();
+}
+function warnIfInvertedRange(start, end) {
+  if (start !== void 0 && end !== void 0 && start > end) {
+    console.warn(
+      `[radosgw-admin] WARNING: start "${start}" is after end "${end}" \u2014 RGW will return empty results`
+    );
+  }
+}
+var UsageModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve a usage report for a user or the entire cluster.
+   *
+   * Omit `uid` to get cluster-wide usage across all users.
+   * Omit `start`/`end` to get all available usage data.
+   *
+   * > **Note:** Usage logging must be enabled in `ceph.conf`:
+   * > `rgw enable usage log = true`
+   *
+   * @param input - Optional filters: `uid`, `start`, `end`, `showEntries`, `showSummary`.
+   * @returns A usage report with `entries` (per-bucket detail) and `summary` (per-user totals).
+   * @throws {RGWValidationError} If `uid` is provided but empty/whitespace.
+   * @throws {RGWValidationError} If a date string is not in a recognised format.
+   *
+   * @example
+   * ```typescript
+   * // Cluster-wide usage, all time
+   * const all = await client.usage.get();
+   *
+   * // Single user, date range
+   * const report = await client.usage.get({
+   *   uid: 'alice',
+   *   start: '2025-01-01',
+   *   end: '2025-01-31',
+   * });
+   *
+   * for (const s of report.summary) {
+   *   console.log(s.user, 'sent', s.total.bytesSent, 'bytes');
+   * }
+   * ```
+   */
+  async get(input = {}) {
+    if (input.uid !== void 0) {
+      validateUid(input.uid);
+    }
+    const start = input.start !== void 0 ? normalizeDate(input.start) : void 0;
+    const end = input.end !== void 0 ? normalizeDate(input.end) : void 0;
+    warnIfInvertedRange(start, end);
+    return this.client.request({
+      method: "GET",
+      path: "/usage",
+      query: {
+        uid: input.uid,
+        start,
+        end,
+        showEntries: input.showEntries,
+        showSummary: input.showSummary
+      }
+    });
+  }
+  /**
+   * Delete (trim) usage log entries matching the given filters.
+   *
+   * **Destructive operation** — deleted log entries cannot be recovered.
+   *
+   * When no `uid` is provided the trim applies cluster-wide. In that case
+   * `removeAll: true` is required to prevent accidental full-cluster log wipes.
+   *
+   * @param input - Trim filters. Omit entirely to trim nothing (use `removeAll: true` explicitly).
+   * @throws {RGWValidationError} If `uid` is provided but empty/whitespace.
+   * @throws {RGWValidationError} If `uid` is omitted but `removeAll` is not `true`.
+   * @throws {RGWValidationError} If a date string is not in a recognised format.
+   *
+   * @example
+   * ```typescript
+   * // Trim a specific user's logs up to end of 2024
+   * await client.usage.trim({ uid: 'alice', end: '2024-12-31' });
+   *
+   * // ⚠️  Trim all logs before 2024 across the entire cluster
+   * await client.usage.trim({ end: '2023-12-31', removeAll: true });
+   * ```
+   */
+  async trim(input = {}) {
+    if (input.uid !== void 0) {
+      validateUid(input.uid);
+    }
+    if (!input.uid && input.removeAll !== true) {
+      throw new RGWValidationError(
+        "trim() without a uid removes logs for ALL users. Set removeAll: true to confirm."
+      );
+    }
+    if (input.removeAll) {
+      console.warn(
+        "[radosgw-admin] WARNING: usage.trim() with removeAll=true will permanently delete usage logs" + (input.uid ? ` for user "${input.uid}"` : " for ALL users")
+      );
+    }
+    const start = input.start !== void 0 ? normalizeDate(input.start) : void 0;
+    const end = input.end !== void 0 ? normalizeDate(input.end) : void 0;
+    warnIfInvertedRange(start, end);
+    return this.client.request({
+      method: "DELETE",
+      path: "/usage",
+      query: {
+        uid: input.uid,
+        start,
+        end,
+        removeAll: input.removeAll
+      }
+    });
+  }
+};
+
+// src/modules/info.ts
+var InfoModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get basic cluster information including the Ceph cluster FSID.
+   *
+   * Useful for confirming connectivity and identifying which cluster the
+   * client is connected to when managing multiple environments.
+   *
+   * @returns Cluster info containing the cluster ID (FSID).
+   * @throws {RGWAuthError} If the credentials are invalid or lack permission.
+   *
+   * @example
+   * ```typescript
+   * const info = await client.info.get();
+   * console.log('Cluster FSID:', info.info.storageBackends[0].clusterId);
+   * ```
+   */
+  async get() {
+    return this.client.request({
+      method: "GET",
+      path: "/info",
+      query: {}
+    });
+  }
+};
+
+// src/index.ts
+var RadosGWAdminClient = class {
+  /** @internal */
+  _client;
+  /** User management operations. */
+  users;
+  /** S3/Swift key management operations. */
+  keys;
+  /** Subuser management operations. */
+  subusers;
+  /** Bucket management operations. */
+  buckets;
+  /** Quota management operations (user-level and bucket-level). */
+  quota;
+  /** Rate limit management operations (user, bucket, and global). */
+  rateLimit;
+  /** Usage & analytics operations — query and trim RGW usage logs. */
+  usage;
+  /** Cluster info operations. */
+  info;
+  constructor(config) {
+    this._client = new BaseClient(config);
+    this.users = new UsersModule(this._client);
+    this.keys = new KeysModule(this._client);
+    this.subusers = new SubusersModule(this._client);
+    this.buckets = new BucketsModule(this._client);
+    this.quota = new QuotaModule(this._client);
+    this.rateLimit = new RateLimitModule(this._client);
+    this.usage = new UsageModule(this._client);
+    this.info = new InfoModule(this._client);
+  }
+};
+export {
+  BaseClient,
+  RGWAuthError,
+  RGWConflictError,
+  RGWError,
+  RGWNotFoundError,
+  RGWValidationError,
+  RadosGWAdminClient,
+  signRequest
+};