radosgw-admin 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1599 @@
+/**
+ * Configuration for the RadosGW Admin Client.
+ */
+interface ClientConfig {
+    /** RGW endpoint, e.g. "http://192.168.1.10" or "https://ceph.example.com" */
+    host: string;
+    /** Port number. Omit to use the default from the host URL. */
+    port?: number;
+    /** Admin access key for AWS SigV4 authentication */
+    accessKey: string;
+    /** Admin secret key for AWS SigV4 authentication */
+    secretKey: string;
+    /** Admin API path prefix. Default: "/admin" */
+    adminPath?: string;
+    /** Request timeout in milliseconds. Default: 10000 */
+    timeout?: number;
+    /** Skip TLS certificate verification. Default: false */
+    insecure?: boolean;
+    /** Enable debug logging of requests and responses. Default: false */
+    debug?: boolean;
+    /** Maximum number of retries for transient errors (5xx, timeouts, network errors). Default: 0 (no retries) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff between retries. Default: 200 */
+    retryDelay?: number;
+    /** AWS region for SigV4 signing. Default: "us-east-1" */
+    region?: string;
+}
+/** HTTP methods used by the RGW Admin API */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** Internal request options passed to the base client */
+interface RequestOptions {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: Record<string, unknown>;
+}
+
+/**
+ * Core HTTP client for making signed requests to the RGW Admin API.
+ * @internal
+ */
+declare class BaseClient {
+    private readonly host;
+    private readonly port;
+    private readonly accessKey;
+    private readonly secretKey;
+    private readonly adminPath;
+    private readonly timeout;
+    private readonly region;
+    private readonly debug;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly insecure;
+    constructor(config: ClientConfig);
+    /**
+     * Logs a debug message with optional structured data.
+     */
+    private log;
+    /**
+     * Determines whether an error is retryable (5xx, timeouts, network errors).
+     */
+    private isRetryable;
+    /**
+     * Checks an error and its cause chain for network error patterns.
+     */
+    private hasNetworkErrorPattern;
+    /**
+     * Returns a promise that resolves after the given number of milliseconds.
+     */
+    private delay;
+    /**
+     * 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
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Builds the full request URL with query parameters.
+     */
+    private buildUrl;
+    /**
+     * Temporarily disables TLS certificate verification for insecure mode.
+     * Returns the previous value so it can be restored.
+     */
+    private disableTlsVerification;
+    /**
+     * Restores the TLS verification setting to its previous value.
+     */
+    private restoreTlsVerification;
+    /**
+     * Parses an error response body to extract the RGW error code.
+     */
+    private parseErrorCode;
+    /**
+     * Wraps a non-RGW error into the appropriate RGW error type.
+     */
+    private wrapFetchError;
+    /**
+     * Executes a single signed HTTP request to the RGW Admin API.
+     */
+    private executeRequest;
+}
+
+/** Input for creating a new RGW user. */
+interface CreateUserInput {
+    /** Unique user ID. Required. Must not contain colons (reserved for subuser notation). */
+    uid: string;
+    /** Display name for the user. Required. Must not be whitespace-only. */
+    displayName: string;
+    /** Email address. Basic format validation is applied. */
+    email?: string;
+    /** Key type to generate. Default: 's3'. */
+    keyType?: 's3' | 'swift';
+    /** Specify an access key instead of auto-generating. */
+    accessKey?: string;
+    /**
+     * Specify a secret key instead of auto-generating.
+     * @remarks This value is transmitted as a query parameter per the RGW Admin Ops API wire
+     * format. It is redacted from debug logs by the client.
+     */
+    secretKey?: string;
+    /**
+     * User capabilities string. Controls which admin operations the user may perform.
+     * Format: `"type=perm"` or `"type1=perm;type2=perm"`.
+     * Valid types: `users`, `buckets`, `metadata`, `usage`, `zone`, `info`, `bilog`,
+     *   `mdlog`, `datalog`, `user-policy`, `oidc-provider`, `roles`, `ratelimit`.
+     * Valid perms: `*`, `read`, `write`, `read, write`.
+     * @example `"users=*;buckets=read"`
+     */
+    userCaps?: string;
+    /** Whether to auto-generate a key pair. Default: true. */
+    generateKey?: boolean;
+    /** Maximum number of buckets allowed. Default: 1000. Use -1 for unlimited. */
+    maxBuckets?: number;
+    /** Whether the user is suspended on creation. Default: false. */
+    suspended?: boolean;
+    /** Tenant name for multi-tenancy. */
+    tenant?: string;
+    /**
+     * Operation mask — limits which S3 operations the user can perform.
+     * Comma-separated list of operations: `read`, `write`, `delete`, `*`.
+     * @example `"read, write"`
+     */
+    opMask?: string;
+}
+/** Input for modifying an existing user. */
+interface ModifyUserInput {
+    /** User ID to modify. Required. */
+    uid: string;
+    /** New display name. */
+    displayName?: string;
+    /** New email address. Basic format validation is applied. */
+    email?: string;
+    /** Maximum number of buckets. */
+    maxBuckets?: number;
+    /** Suspend or unsuspend the user. */
+    suspended?: boolean;
+    /** User capabilities string. See {@link CreateUserInput.userCaps} for format. */
+    userCaps?: string;
+    /** Operation mask. See {@link CreateUserInput.opMask} for format. */
+    opMask?: string;
+}
+/** Input for deleting a user. */
+interface DeleteUserInput {
+    /** User ID to delete. Required. */
+    uid: string;
+    /** If true, permanently deletes all buckets and objects owned by the user. Default: false. DESTRUCTIVE. */
+    purgeData?: boolean;
+}
+/** An S3 key pair associated with a user. */
+interface RGWKey {
+    user: string;
+    accessKey: string;
+    secretKey: string;
+}
+/** A Swift key associated with a user. */
+interface RGWSwiftKey {
+    user: string;
+    secretKey: string;
+}
+/** A subuser reference. */
+interface RGWSubuser {
+    id: string;
+    permissions: string;
+}
+/** A user capability entry. */
+interface RGWCap {
+    type: string;
+    perm: string;
+}
+/** Quota configuration (used for both user and bucket quotas). */
+interface RGWQuota {
+    enabled: boolean;
+    checkOnRaw: boolean;
+    /** Quota in bytes. -1 means unlimited. */
+    maxSize: number;
+    /** Quota in kilobytes. -1 means unlimited. */
+    maxSizeKb: number;
+    /** Maximum number of objects. -1 means unlimited. */
+    maxObjects: number;
+}
+/** Full RGW user object returned by the admin API. */
+interface RGWUser {
+    userId: string;
+    displayName: string;
+    email: string;
+    /**
+     * Whether the user is suspended. `0` = active, `1` = suspended.
+     * Use numeric comparison: `user.suspended === 1` or treat as truthy/falsy.
+     */
+    suspended: number;
+    maxBuckets: number;
+    subusers: RGWSubuser[];
+    keys: RGWKey[];
+    swiftKeys: RGWSwiftKey[];
+    caps: RGWCap[];
+    opMask: string;
+    defaultPlacement: string;
+    defaultStorageClass: string;
+    placementTags: string[];
+    tenant: string;
+    bucketQuota: RGWQuota;
+    userQuota: RGWQuota;
+    /**
+     * User type. Common values: `"rgw"`, `"ldap"`, `"s3"`.
+     * May be absent on older Ceph versions.
+     */
+    type?: string;
+    /** MFA device IDs associated with this user. May be absent on older Ceph versions. */
+    mfaIds?: string[];
+}
+/** The raw usage statistics returned by `GET /user?stats=true`. */
+interface RGWUserStatData {
+    /** Total bytes used (logical). */
+    size: number;
+    /** Total bytes actually consumed on disk (accounting for alignment). */
+    sizeActual: number;
+    /** Total bytes utilized (used + overhead). */
+    sizeUtilized: number;
+    /** Total kilobytes used (logical). */
+    sizeKb: number;
+    /** Total kilobytes actually on disk. */
+    sizeKbActual: number;
+    /** Total kilobytes utilized. */
+    sizeKbUtilized: number;
+    /** Total number of objects stored. */
+    numObjects: number;
+}
+/**
+ * Full user object with embedded storage statistics.
+ * Returned by `client.users.getStats()`.
+ * Contains all fields from {@link RGWUser} plus a `stats` field.
+ */
+interface RGWUserWithStats extends RGWUser {
+    stats: RGWUserStatData;
+}
+
+/**
+ * User management module — create, get, modify, delete, list, suspend, enable,
+ * get stats, and look up users by access key.
+ *
+ * @example
+ * ```typescript
+ * const user = await client.users.create({ uid: 'alice', displayName: 'Alice' });
+ * const same = await client.users.getByAccessKey(user.keys[0].accessKey);
+ * ```
+ */
+declare class UsersModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    create(input: CreateUserInput): Promise<RGWUser>;
+    /**
+     * 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');
+     * ```
+     */
+    get(uid: string, tenant?: string): Promise<RGWUser>;
+    /**
+     * 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);
+     * ```
+     */
+    getByAccessKey(accessKey: string): Promise<RGWUser>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    modify(input: ModifyUserInput): Promise<RGWUser>;
+    /**
+     * 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 });
+     * ```
+     */
+    delete(input: DeleteUserInput): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    list(): Promise<string[]>;
+    /**
+     * 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
+     * ```
+     */
+    suspend(uid: string): Promise<RGWUser>;
+    /**
+     * 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
+     * ```
+     */
+    enable(uid: string): Promise<RGWUser>;
+    /**
+     * 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);
+     * ```
+     */
+    getStats(uid: string, sync?: boolean): Promise<RGWUserWithStats>;
+}
+
+/** Input for creating a new S3 or Swift key for a user. */
+interface CreateKeyInput {
+    /** User ID to create the key for. Required. */
+    uid: string;
+    /** Key type. Default: 's3'. */
+    keyType?: 's3' | 'swift';
+    /** Specify an access key instead of auto-generating. */
+    accessKey?: string;
+    /**
+     * Specify a secret key instead of auto-generating.
+     * @remarks This value is transmitted as a query parameter per the RGW Admin Ops API wire
+     * format. It is redacted from debug logs by the client.
+     */
+    secretKey?: string;
+    /** Whether to auto-generate the key. Default: true. */
+    generateKey?: boolean;
+}
+/** Input for deleting an S3 or Swift key. */
+interface DeleteKeyInput {
+    /** The access key to delete. Required. */
+    accessKey: string;
+    /** User ID. Required for Swift keys. */
+    uid?: string;
+    /** Key type. Default: 's3'. */
+    keyType?: 's3' | 'swift';
+}
+/** Input for creating a subuser. */
+interface CreateSubuserInput {
+    /** Parent user UID. Required. */
+    uid: string;
+    /** Subuser ID in `uid:name` format (e.g. `"alice:swift"`). Required. */
+    subuser: string;
+    /**
+     * Secret key for the subuser. Auto-generated if omitted.
+     * @remarks This value is transmitted as a query parameter per the RGW Admin Ops API wire
+     * format. It is redacted from debug logs by the client.
+     */
+    secretKey?: string;
+    /** Key type for the subuser. */
+    keyType?: 'swift' | 's3';
+    /** Access level for the subuser. */
+    access?: 'read' | 'write' | 'readwrite' | 'full';
+    /** Whether to auto-generate a secret. Default: true. */
+    generateSecret?: boolean;
+}
+/** Input for modifying a subuser. */
+interface ModifySubuserInput {
+    /** Parent user UID. Required. */
+    uid: string;
+    /** Subuser ID in `uid:name` format (e.g. `"alice:swift"`). Required. */
+    subuser: string;
+    /**
+     * Secret key for the subuser.
+     * @remarks This value is transmitted as a query parameter per the RGW Admin Ops API wire
+     * format. It is redacted from debug logs by the client.
+     */
+    secretKey?: string;
+    /** Key type for the subuser. */
+    keyType?: 'swift' | 's3';
+    /** Updated access level. */
+    access?: 'read' | 'write' | 'readwrite' | 'full';
+    /** Whether to auto-generate a secret. */
+    generateSecret?: boolean;
+}
+/** Input for deleting a subuser. */
+interface DeleteSubuserInput {
+    /** Parent user UID. Required. */
+    uid: string;
+    /** Subuser ID in `uid:name` format (e.g. `"alice:swift"`). Required. */
+    subuser: string;
+    /** Whether to also purge the subuser's keys. Default: true. */
+    purgeKeys?: boolean;
+}
+
+/**
+ * Key management module — generate and revoke S3/Swift access keys.
+ *
+ * @example
+ * ```typescript
+ * // Generate a new key pair for a user
+ * const keys = await client.keys.generate({ uid: 'alice' });
+ * console.log(keys[0].accessKey, keys[0].secretKey);
+ *
+ * // Revoke a specific key
+ * await client.keys.revoke({ accessKey: 'OLDKEY123' });
+ * ```
+ */
+declare class KeysModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    generate(input: CreateKeyInput): Promise<RGWKey[]>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    revoke(input: DeleteKeyInput): Promise<void>;
+}
+
+/**
+ * Subuser management module — create, modify, and remove subusers with Swift keys.
+ *
+ * @example
+ * ```typescript
+ * // Create a subuser with Swift access
+ * const subusers = await client.subusers.create({
+ *   uid: 'alice',
+ *   subuser: 'alice:swift',
+ *   access: 'readwrite',
+ *   keyType: 'swift',
+ * });
+ * ```
+ */
+declare class SubusersModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    create(input: CreateSubuserInput): Promise<RGWSubuser[]>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    modify(input: ModifySubuserInput): Promise<RGWSubuser[]>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    remove(input: DeleteSubuserInput): Promise<void>;
+}
+
+/** Usage statistics for a bucket storage class. */
+interface RGWBucketUsage {
+    size: number;
+    sizeActual: number;
+    sizeUtilized: number;
+    sizeKb: number;
+    sizeKbActual: number;
+    numObjects: number;
+}
+/** Full RGW bucket object returned by the admin API. */
+interface RGWBucket {
+    bucket: string;
+    tenant: string;
+    explicitTenant: boolean;
+    id: string;
+    marker: string;
+    indexType: string;
+    owner: string;
+    ver: string;
+    masterVer: string;
+    mtime: string;
+    creationTime: string;
+    maxMarker: string;
+    usage: {
+        rgwMain: RGWBucketUsage;
+        rgwMultimeta?: RGWBucketUsage;
+        [storageClass: string]: RGWBucketUsage | undefined;
+    };
+    bucketQuota: RGWQuota;
+}
+/** Input for deleting a bucket. */
+interface DeleteBucketInput {
+    /** Bucket name. Required. */
+    bucket: string;
+    /** If true, permanently deletes all objects in the bucket. Default: false. DESTRUCTIVE. */
+    purgeObjects?: boolean;
+}
+/** Input for linking a bucket to a user. */
+interface LinkBucketInput {
+    /** Bucket name. Required. */
+    bucket: string;
+    /** Bucket ID (from getInfo). Required. */
+    bucketId: string;
+    /** User ID to link the bucket to. Required. */
+    uid: string;
+}
+/** Input for unlinking a bucket from a user. */
+interface UnlinkBucketInput {
+    /** Bucket name. Required. */
+    bucket: string;
+    /** User ID to unlink the bucket from. Required. */
+    uid: string;
+}
+/** Input for checking/repairing a bucket index. */
+interface CheckBucketIndexInput {
+    /** Bucket name. Required. */
+    bucket: string;
+    /** Whether to check object data consistency. Default: false. */
+    checkObjects?: boolean;
+    /** Whether to fix any detected issues. Default: false (dry run). */
+    fix?: boolean;
+}
+/** Result of a bucket index check. */
+interface CheckBucketIndexResult {
+    invalidMultipartEntries: string[];
+    checkResult: {
+        existingHeader: Record<string, unknown>;
+        calculatedHeader: Record<string, unknown>;
+    };
+}
+
+/**
+ * Bucket management module — list, inspect, delete, transfer ownership, and verify/repair bucket indexes.
+ *
+ * @example
+ * ```typescript
+ * const allBuckets = await client.buckets.list();
+ * const userBuckets = await client.buckets.listByUser('alice');
+ * const info = await client.buckets.getInfo('my-bucket');
+ * console.log(info.owner, info.usage.rgwMain.numObjects);
+ * ```
+ */
+declare class BucketsModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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`);
+     * ```
+     */
+    list(): Promise<string[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    listByUser(uid: string): Promise<string[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    getInfo(bucket: string): Promise<RGWBucket>;
+    /**
+     * 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 });
+     * ```
+     */
+    delete(input: DeleteBucketInput): Promise<void>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    transferOwnership(input: LinkBucketInput): Promise<void>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    removeOwnership(input: UnlinkBucketInput): Promise<void>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    verifyIndex(input: CheckBucketIndexInput): Promise<CheckBucketIndexResult>;
+}
+
+/** Input for setting a user-level quota. */
+interface SetUserQuotaInput {
+    /** User ID. Required. */
+    uid: string;
+    /** Maximum storage size in bytes, or a human-readable string like "10G", "500M". -1 for unlimited. */
+    maxSize?: number | string;
+    /** Maximum number of objects. -1 for unlimited. */
+    maxObjects?: number;
+    /** Whether the quota is enabled. Default: true when setting a quota. */
+    enabled?: boolean;
+}
+/** Input for setting a bucket-level quota. */
+interface SetBucketQuotaInput {
+    /** User ID. Required. */
+    uid: string;
+    /** Maximum storage size in bytes, or a human-readable string like "10G", "500M". -1 for unlimited. */
+    maxSize?: number | string;
+    /** Maximum number of objects. -1 for unlimited. */
+    maxObjects?: number;
+    /** Whether the quota is enabled. Default: true when setting a quota. */
+    enabled?: boolean;
+}
+/** Rate limit configuration returned by the RGW Admin API. */
+interface RGWRateLimit {
+    enabled: boolean;
+    /** Maximum read operations per minute per RGW instance. 0 = unlimited. */
+    maxReadOps: number;
+    /** Maximum write operations per minute per RGW instance. 0 = unlimited. */
+    maxWriteOps: number;
+    /** Maximum read bytes per minute per RGW instance. 0 = unlimited. */
+    maxReadBytes: number;
+    /** Maximum write bytes per minute per RGW instance. 0 = unlimited. */
+    maxWriteBytes: number;
+}
+/** Input for setting a user-level rate limit. */
+interface SetUserRateLimitInput {
+    /** User ID. Required. */
+    uid: string;
+    /** Max read ops per minute per RGW instance. 0 = unlimited. */
+    maxReadOps?: number;
+    /** Max write ops per minute per RGW instance. 0 = unlimited. */
+    maxWriteOps?: number;
+    /** Max read bytes per minute per RGW instance. 0 = unlimited. */
+    maxReadBytes?: number;
+    /** Max write bytes per minute per RGW instance. 0 = unlimited. */
+    maxWriteBytes?: number;
+    /** Whether the rate limit is enabled. Default: true. */
+    enabled?: boolean;
+}
+/** Input for setting a bucket-level rate limit. */
+interface SetBucketRateLimitInput {
+    /** Bucket name. Required. */
+    bucket: string;
+    /** Max read ops per minute per RGW instance. 0 = unlimited. */
+    maxReadOps?: number;
+    /** Max write ops per minute per RGW instance. 0 = unlimited. */
+    maxWriteOps?: number;
+    /** Max read bytes per minute per RGW instance. 0 = unlimited. */
+    maxReadBytes?: number;
+    /** Max write bytes per minute per RGW instance. 0 = unlimited. */
+    maxWriteBytes?: number;
+    /** Whether the rate limit is enabled. Default: true. */
+    enabled?: boolean;
+}
+/** Input for setting a global rate limit. */
+interface SetGlobalRateLimitInput {
+    /** Scope: 'user', 'bucket', or 'anonymous'. Required. */
+    scope: 'user' | 'bucket' | 'anonymous';
+    /** Max read ops per minute per RGW instance. 0 = unlimited. */
+    maxReadOps?: number;
+    /** Max write ops per minute per RGW instance. 0 = unlimited. */
+    maxWriteOps?: number;
+    /** Max read bytes per minute per RGW instance. 0 = unlimited. */
+    maxReadBytes?: number;
+    /** Max write bytes per minute per RGW instance. 0 = unlimited. */
+    maxWriteBytes?: number;
+    /** Whether the rate limit is enabled. Default: true. */
+    enabled?: boolean;
+}
+/** Global rate limit info returned by the RGW Admin API. */
+interface RGWGlobalRateLimit {
+    /** Rate limit for all users (per-user scope). */
+    user: RGWRateLimit;
+    /** Rate limit for all buckets (per-bucket scope). */
+    bucket: RGWRateLimit;
+    /** Rate limit for anonymous (unauthenticated) access. */
+    anonymous: RGWRateLimit;
+}
+
+/**
+ * Quota management module — get, set, enable, and disable user-level and bucket-level quotas.
+ *
+ * @example
+ * ```typescript
+ * // Set a 10GB user quota
+ * await client.quota.setUserQuota({ uid: 'alice', maxSize: '10G', maxObjects: 50000 });
+ *
+ * // Check current quota
+ * const quota = await client.quota.getUserQuota('alice');
+ * console.log(quota.enabled, quota.maxSize);
+ * ```
+ */
+declare class QuotaModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    getUserQuota(uid: string): Promise<RGWQuota>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    setUserQuota(input: SetUserQuotaInput): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    enableUserQuota(uid: string): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    disableUserQuota(uid: string): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    getBucketQuota(uid: string): Promise<RGWQuota>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    setBucketQuota(input: SetBucketQuotaInput): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    enableBucketQuota(uid: string): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    disableBucketQuota(uid: string): Promise<void>;
+}
+
+/**
+ * Rate limit management module — get, set, and disable rate limits for users, buckets, and globally.
+ *
+ * Rate limits are enforced **per RGW instance**. If you have 3 RGW daemons and want a
+ * cluster-wide limit of 300 ops/min, set `maxReadOps: 100` on each instance.
+ *
+ * Requires Ceph **Pacific (v16)** or later.
+ *
+ * @example
+ * ```typescript
+ * // Throttle alice to 100 read ops/min per RGW
+ * await client.rateLimit.setUserLimit({
+ *   uid: 'alice',
+ *   maxReadOps: 100,
+ *   maxWriteOps: 50,
+ * });
+ *
+ * // Get current rate limit
+ * const limit = await client.rateLimit.getUserLimit('alice');
+ * console.log(limit.enabled, limit.maxReadOps);
+ * ```
+ */
+declare class RateLimitModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    getUserLimit(uid: string): Promise<RGWRateLimit>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    setUserLimit(input: SetUserRateLimitInput): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    disableUserLimit(uid: string): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    getBucketLimit(bucket: string): Promise<RGWRateLimit>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    setBucketLimit(input: SetBucketRateLimitInput): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    disableBucketLimit(bucket: string): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    getGlobal(): Promise<RGWGlobalRateLimit>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    setGlobal(input: SetGlobalRateLimitInput): Promise<void>;
+}
+
+interface GetUsageInput {
+    /** Filter by user ID. Omit to retrieve cluster-wide usage for all users. */
+    uid?: string;
+    /** Start of the date range. Accepts ISO date string ("2024-01-01") or Date object. */
+    start?: string | Date;
+    /** End of the date range. Accepts ISO date string ("2024-01-31") or Date object. */
+    end?: string | Date;
+    /** Include per-bucket usage entries in the response. Default: true. */
+    showEntries?: boolean;
+    /** Include per-user summary totals in the response. Default: true. */
+    showSummary?: boolean;
+}
+interface TrimUsageInput {
+    /** Trim usage logs only for this user. Omit to trim across all users. */
+    uid?: string;
+    /** Start of the date range to trim. */
+    start?: string | Date;
+    /** End of the date range to trim. */
+    end?: string | Date;
+    /**
+     * Required when `uid` is not provided to prevent accidental cluster-wide log deletion.
+     * Setting this to `true` explicitly acknowledges that all matching logs will be removed.
+     */
+    removeAll?: boolean;
+}
+interface RGWUsageCategory {
+    /** Operation category, e.g. "get_obj", "put_obj", "delete_obj", "list_buckets". */
+    category: string;
+    /** Total bytes sent (egress) for this category. */
+    bytesSent: number;
+    /** Total bytes received (ingress) for this category. */
+    bytesReceived: number;
+    /** Total number of operations attempted. */
+    ops: number;
+    /** Total number of operations that succeeded. */
+    successfulOps: number;
+}
+interface RGWUsageBucket {
+    bucket: string;
+    time: string;
+    epoch: number;
+    owner: string;
+    categories: RGWUsageCategory[];
+}
+interface RGWUsageEntry {
+    /** The user ID this entry belongs to. */
+    user: string;
+    /** Per-bucket breakdown of usage. */
+    buckets: RGWUsageBucket[];
+}
+interface RGWUsageSummary {
+    /** The user ID this summary belongs to. */
+    user: string;
+    /** Per-category totals for this user. */
+    categories: RGWUsageCategory[];
+    /** Aggregate totals across all categories for this user. */
+    total: {
+        bytesSent: number;
+        bytesReceived: number;
+        ops: number;
+        successfulOps: number;
+    };
+}
+interface RGWUsageReport {
+    /** Detailed per-bucket usage entries (present when showEntries is true). */
+    entries: RGWUsageEntry[];
+    /** Per-user aggregated summaries (present when showSummary is true). */
+    summary: RGWUsageSummary[];
+}
+
+/**
+ * Usage & analytics module — query and trim RGW usage logs.
+ *
+ * > **Note:** Usage logging must be enabled in your Ceph config:
+ * > `rgw enable usage log = true`
+ *
+ * @example
+ * ```typescript
+ * // Get usage for a specific user in January 2025
+ * const report = await client.usage.get({
+ *   uid: 'alice',
+ *   start: '2025-01-01',
+ *   end: '2025-01-31',
+ * });
+ *
+ * // Trim all usage logs before a date (cluster-wide)
+ * await client.usage.trim({ end: '2024-12-31', removeAll: true });
+ * ```
+ */
+declare class UsageModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    get(input?: GetUsageInput): Promise<RGWUsageReport>;
+    /**
+     * 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 });
+     * ```
+     */
+    trim(input?: TrimUsageInput): Promise<void>;
+}
+
+interface RGWStorageBackend {
+    /** Backend name (e.g. "rados"). */
+    name: string;
+    /** The Ceph cluster FSID (unique identifier for the cluster). */
+    clusterId: string;
+}
+interface RGWClusterInfo {
+    info: {
+        /** Storage backends available in this cluster. */
+        storageBackends: RGWStorageBackend[];
+    };
+}
+
+/**
+ * Cluster info module — retrieve basic cluster/endpoint information.
+ *
+ * @example
+ * ```typescript
+ * const info = await client.info.get();
+ * console.log('Cluster FSID:', info.info.storageBackends[0].clusterId);
+ * ```
+ */
+declare class InfoModule {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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);
+     * ```
+     */
+    get(): Promise<RGWClusterInfo>;
+}
+
+/**
+ * Base error class for all RGW Admin API errors.
+ */
+declare class RGWError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly code?: string | undefined;
+    readonly uid?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, uid?: string | undefined);
+}
+/**
+ * Thrown when a requested resource (user, bucket, key) does not exist.
+ */
+declare class RGWNotFoundError extends RGWError {
+    constructor(resource: string, id: string);
+}
+/**
+ * Thrown when input validation fails before making an HTTP request.
+ */
+declare class RGWValidationError extends RGWError {
+    constructor(message: string);
+}
+/**
+ * Thrown on 403 Access Denied responses.
+ */
+declare class RGWAuthError extends RGWError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a resource already exists (409 Conflict).
+ */
+declare class RGWConflictError extends RGWError {
+    constructor(resource: string, id: string);
+}
+
+/**
+ * AWS Signature V4 signer for RGW Admin API requests.
+ * Implemented without external dependencies using node:crypto.
+ */
+interface SignedHeaders {
+    [header: string]: string;
+}
+interface SignRequest {
+    method: string;
+    url: URL;
+    headers: Record<string, string>;
+    body?: string;
+    accessKey: string;
+    secretKey: string;
+    region: string;
+}
+/**
+ * Signs an HTTP request using AWS Signature Version 4.
+ *
+ * @param request - The request details to sign
+ * @param date - Optional date override (used for testing)
+ * @returns Headers that must be added to the request
+ * @internal
+ */
+declare function signRequest(request: SignRequest, date?: Date): SignedHeaders;
+
+/**
+ * RadosGW Admin Client — the single entry point for all RGW Admin API operations.
+ *
+ * @example
+ * ```typescript
+ * import { RadosGWAdminClient } from 'radosgw-admin';
+ *
+ * const client = new RadosGWAdminClient({
+ *   host: 'http://192.168.1.100',
+ *   port: 8080,
+ *   accessKey: 'ADMIN_ACCESS_KEY',
+ *   secretKey: 'ADMIN_SECRET_KEY',
+ * });
+ *
+ * const user = await client.users.create({
+ *   uid: 'alice',
+ *   displayName: 'Alice',
+ * });
+ * ```
+ */
+declare class RadosGWAdminClient {
+    /** @internal */
+    readonly _client: BaseClient;
+    /** User management operations. */
+    readonly users: UsersModule;
+    /** S3/Swift key management operations. */
+    readonly keys: KeysModule;
+    /** Subuser management operations. */
+    readonly subusers: SubusersModule;
+    /** Bucket management operations. */
+    readonly buckets: BucketsModule;
+    /** Quota management operations (user-level and bucket-level). */
+    readonly quota: QuotaModule;
+    /** Rate limit management operations (user, bucket, and global). */
+    readonly rateLimit: RateLimitModule;
+    /** Usage & analytics operations — query and trim RGW usage logs. */
+    readonly usage: UsageModule;
+    /** Cluster info operations. */
+    readonly info: InfoModule;
+    constructor(config: ClientConfig);
+}
+
+export { BaseClient, type CheckBucketIndexInput, type CheckBucketIndexResult, type ClientConfig, type CreateKeyInput, type CreateSubuserInput, type CreateUserInput, type DeleteBucketInput, type DeleteKeyInput, type DeleteSubuserInput, type DeleteUserInput, type GetUsageInput, type HttpMethod, type LinkBucketInput, type ModifySubuserInput, type ModifyUserInput, RGWAuthError, type RGWBucket, type RGWBucketUsage, type RGWCap, type RGWClusterInfo, RGWConflictError, RGWError, type RGWGlobalRateLimit, type RGWKey, RGWNotFoundError, type RGWQuota, type RGWRateLimit, type RGWStorageBackend, type RGWSubuser, type RGWSwiftKey, type RGWUsageBucket, type RGWUsageCategory, type RGWUsageEntry, type RGWUsageReport, type RGWUsageSummary, type RGWUser, type RGWUserStatData, type RGWUserWithStats, RGWValidationError, RadosGWAdminClient, type RequestOptions, type SetBucketQuotaInput, type SetBucketRateLimitInput, type SetGlobalRateLimitInput, type SetUserQuotaInput, type SetUserRateLimitInput, type TrimUsageInput, type UnlinkBucketInput, signRequest };