@appweaver/client 1.0.22 → 1.0.24

package/esm/clients/base-client.js

@@ -0,0 +1,242 @@
+import createClient from 'openapi-fetch';
+import { AccountClient, AuthClient, FilesClient, HealthClient, ResourceClient } from './modules/index.js';
+import { ClientError } from '../errors/index.js';
+/**
+ * Type-safe HTTP client built on top of `openapi-fetch`.
+ *
+ * `BaseClient` wires up a base URL, optional request timeout, optional authentication
+ * middleware, and any additional custom middlewares into a single reusable client instance.
+ * Subclasses expose domain-specific helpers by composing the protected factory methods
+ * (`resourceClient`, `authClient`, `accountClient`, `healthClient`, `fileClient`).
+ *
+ * @typeParam Paths - The OpenAPI path map generated by `openapi-typescript` for the target API.
+ * @typeParam UseObservable - Boolean flag indicating whether to return Observables (true) or Promises (false).
+ * Defaults to false for Promise-based clients like `FetchClient`. Set to true in `AngularClient` to enable RxJS
+ * Observable support.
+ */
+export class BaseClient {
+    _config;
+    _client;
+    _modules = {
+        resources: []
+    };
+    constructor(_config) {
+        this._config = _config;
+        const { baseUrl, timeout, middlewares, auth, fetch } = _config;
+        this._client = createClient({ baseUrl, fetch });
+        if (timeout) {
+            this._client.use({
+                onRequest: async ({ request }) => {
+                    const timeoutSignal = AbortSignal.timeout(timeout);
+                    return new Request(request, {
+                        signal: request.signal
+                            ? AbortSignal.any([request.signal, timeoutSignal])
+                            : timeoutSignal
+                    });
+                }
+            });
+        }
+        if (auth) {
+            this._client.use({
+                onRequest: async ({ request, schemaPath }) => {
+                    const headers = new Headers(request.headers);
+                    if ('jwt' in auth) {
+                        const jwt = typeof auth.jwt === 'function'
+                            ? await auth.jwt(request)
+                            : auth.jwt;
+                        let token;
+                        if (typeof jwt === 'object') {
+                            token = jwt.accessToken;
+                            const refreshPath = `/${this._modules.auth?.basePath}/refresh`.replace(/\/+/g, '/');
+                            if (schemaPath === refreshPath && jwt.refreshToken) {
+                                token = jwt.refreshToken;
+                            }
+                        }
+                        else {
+                            token = jwt;
+                        }
+                        headers.set('Authorization', `Bearer ${token}`);
+                    }
+                    else if ('basic' in auth) {
+                        const basic = typeof auth.basic === 'function'
+                            ? await auth.basic(request)
+                            : auth.basic;
+                        const secret = typeof basic === 'string'
+                            ? basic
+                            : btoa(`${basic.username}:${basic.password}`);
+                        headers.set('Authorization', `Basic ${secret}`);
+                    }
+                    if ('apiKey' in auth) {
+                        const apiKey = typeof auth.apiKey === 'function'
+                            ? await auth.apiKey(request)
+                            : auth.apiKey;
+                        const key = typeof apiKey === 'string' ? apiKey : apiKey.key;
+                        const header = typeof apiKey !== 'string' ? apiKey?.header : undefined;
+                        headers.set(header ?? 'X-Api-Key', key);
+                    }
+                    return new Request(request, {
+                        headers
+                    });
+                }
+            });
+        }
+        if (middlewares) {
+            for (const middleware of middlewares) {
+                this._client.use(middleware);
+            }
+        }
+    }
+    /**
+     * Returns the underlying `openapi-fetch` client instance.
+     *
+     * Use this when direct access to the raw client is required to call methods
+     * not exposed by `FetchClient` directly.
+     */
+    getClient() {
+        return this._client;
+    }
+    /**
+     * Retrieves the client configuration.
+     *
+     * @return {ClientConfig} The current client configuration instance.
+     */
+    getConfig() {
+        return this._config;
+    }
+    /**
+     * Sends an HTTP request and returns the parsed response data.
+     *
+     * Returns a `Promise` by default. In `AngularClient` (where `UseObservable = true`)
+     * this method is overridden to return an `Observable` instead.
+     *
+     * Throws a {@link ClientError} if the server returns an error response, including the
+     * error message and status code from the response body when available.
+     *
+     * @typeParam Method - The HTTP method (e.g. `"get"`, `"post"`).
+     * @typeParam Path - A path in `Paths` that supports `Method`.
+     * @typeParam Init - The request init inferred from the OpenAPI schema for this operation.
+     * @param {HttpMethod} method - The HTTP method to use.
+     * @param {string} url - The API path to request.
+     * @param {Object} params - Optional request parameters (body, query, headers, etc.) as defined by the schema.
+     * @returns The non-nullable `data` field from the response.
+     * @throws {ClientError} When the server returns an error response.
+     */
+    sendRequest(method, url, ...params) {
+        return this.sendRequestPromise(method, url, ...params);
+    }
+    /**
+     * Sends an HTTP request and returns the raw `openapi-fetch` response tuple.
+     *
+     * Returns a `Promise` by default. In `AngularClient` (where `UseObservable = true`)
+     * this method is overridden to return an `Observable` instead.
+     *
+     * Unlike {@link sendRequest}, this method does **not** throw on error responses — callers
+     * receive the full `{ data, error, response }` object and are responsible for handling
+     * error cases themselves.
+     *
+     * @typeParam Method - The HTTP method (e.g. `"get"`, `"post"`).
+     * @typeParam Path - A path in `Paths` that supports `Method`.
+     * @typeParam Init - The request init inferred from the OpenAPI schema for this operation.
+     * @param {HttpMethod} method - The HTTP method to use.
+     * @param {string} url - The API path to request.
+     * @param {Object} params - Optional request parameters (body, query, headers, etc.) as defined by the schema.
+     * @returns The raw `FetchResponse` containing `data`, `error`, and the native `Response`.
+     */
+    sendRequestRaw(method, url, ...params) {
+        return this.sendRequestRawPromise(method, url, ...params);
+    }
+    /**
+     * Sends an HTTP request and returns the parsed response data as a Promise.
+     *
+     * This protected helper always returns a `Promise` and is intended to be called
+     * by {@link sendRequest} and overrides in subclasses such as `AngularClient`.
+     *
+     * @throws {ClientError} When the server returns an error response.
+     */
+    async sendRequestPromise(method, url, ...params) {
+        const { data, error, response } = await this._client.request(method, url, ...params);
+        if (error) {
+            const err = error;
+            throw new ClientError(err.message ?? response.statusText ?? 'Unknown error', err.errorCode ?? response.status, response, error);
+        }
+        return data;
+    }
+    /**
+     * Sends an HTTP request and returns the raw `openapi-fetch` response tuple as a Promise.
+     *
+     * This protected helper always returns a `Promise` and is intended to be called
+     * by {@link sendRequestRaw} and overrides in subclasses such as `AngularClient`.
+     */
+    sendRequestRawPromise(method, url, ...params) {
+        return this._client.request(method, url, ...params);
+    }
+    /**
+     * Handles a custom HTTP request based on the provided method, URL, and initialization parameters.
+     *
+     * @param {Method} method - The HTTP method to be used (e.g., GET, POST).
+     * @param {Path} url - The endpoint URL corresponding to the specified method.
+     * @return A function that accepts initialization parameters and returns an observable or promise of the fetched data.
+     */
+    customRequest(method, url) {
+        return (...params) => {
+            return this.sendRequest(method, url, ...params);
+        };
+    }
+    /**
+     * Creates and returns a new instance of a ResourceClient for managing a specific resource type.
+     *
+     * @param {string} resourcePath - The API path or endpoint for the resource.
+     * @template Resource - The type of the resource being managed.
+     * @template OmitFields - An optional array of resource interface fields to omit.
+     * @return {ResourceClient} A ResourceClient instance for interacting with the specified resource.
+     */
+    resourceClient(resourcePath) {
+        const resource = new ResourceClient(this, resourcePath);
+        this._modules.resources.push(resource);
+        return resource;
+    }
+    /**
+     * Creates and returns an AuthClient instance for managing authentication operations.
+     *
+     * @param {string} authPath - The authentication path used to configure the AuthClient instance.
+     * @return {AuthClient} An instance of AuthClient initialized with the provided authentication path.
+     */
+    authClient(authPath) {
+        const auth = new AuthClient(this, authPath);
+        this._modules.auth = auth;
+        return auth;
+    }
+    /**
+     * Creates and returns an AccountClient instance for managing account-related operations.
+     *
+     * @param {string} accountPath - The path to the account resource.
+     * @return {AccountClient} An instance of AccountClient configured with the provided account path.
+     */
+    accountClient(accountPath) {
+        const account = new AccountClient(this, accountPath);
+        this._modules.account = account;
+        return account;
+    }
+    /**
+     * Creates and returns a HealthClient instance for interacting with health-related data.
+     *
+     * @param {string} healthPath - The path to the health resource endpoint.
+     * @return {HealthClient} An instance of HealthClient configured with the provided health path.
+     */
+    healthClient(healthPath) {
+        const health = new HealthClient(this, healthPath);
+        this._modules.health = health;
+        return health;
+    }
+    /**
+     * Creates and returns an instance of `FilesClient` for the specified file path.
+     *
+     * @param {string} filesPath - The file path used to initialize the `FilesClient`.
+     * @return {FilesClient} An instance of FilesClient configured with the provided files' path.
+     */
+    filesClient(filesPath) {
+        const files = new FilesClient(this, filesPath);
+        this._modules.files = files;
+        return files;
+    }
+}

package/esm/clients/fetch-client.d.ts

@@ -0,0 +1,6 @@
+import { ClientConfig, BaseClient } from './base-client.js';
+export declare class FetchClient<Paths extends {} = {
+    [key: string]: any;
+}> extends BaseClient<Paths> {
+    constructor(config: ClientConfig);
+}

package/esm/clients/fetch-client.js

@@ -0,0 +1,6 @@
+import { BaseClient } from './base-client.js';
+export class FetchClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+}

package/esm/clients/index.d.ts

@@ -0,0 +1,4 @@
+export * from './modules/index.js';
+export * from './base-client.js';
+export * from './base-client-interface.js';
+export * from './fetch-client.js';

package/esm/clients/index.js

@@ -0,0 +1,4 @@
+export * from './modules/index.js';
+export * from './base-client.js';
+export * from './base-client-interface.js';
+export * from './fetch-client.js';

package/esm/clients/modules/account-client.d.ts

@@ -0,0 +1,69 @@
+import { BaseModule, RequestOptions } from './base-module.js';
+import { BaseClientInterface } from '../base-client-interface.js';
+import { ACCOUNT_OPERATIONS, ACCOUNT_TYPES } from '../../constants.js';
+export type AccountType = Record<(typeof ACCOUNT_TYPES)[number], unknown>;
+export type AccountInterface = {
+    [K in keyof typeof ACCOUNT_OPERATIONS]: (...args: any[]) => Promise<any>;
+};
+export declare class AccountClient<Account extends AccountType> extends BaseModule implements AccountInterface {
+    readonly basePath: string;
+    constructor(client: BaseClientInterface, basePath: string);
+    /**
+     * Sends a verification email to the user's registered email address.
+     *
+     * @param {Object} request - The payload identifying the account to send the email to.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the email was dispatched successfully.
+     */
+    sendVerifyEmail(request: Account['sendEmailVerificationRequest'], options?: RequestOptions): Promise<Account['statusResponse']>;
+    /**
+     * Verifies a user's email address using a verification token.
+     *
+     * @param {Object} request - The payload containing the verification token.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the email was verified successfully.
+     */
+    verifyEmail(request: Account['emailVerificationRequest'], options?: RequestOptions): Promise<Account['statusResponse']>;
+    /**
+     * Handles the redirect-based email verification flow by passing the token as a query parameter.
+     *
+     * Typically used as the target of a link sent in a verification email.
+     *
+     * @param {string} token - The email verification token from the redirect URL.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The server response for the redirect verification (shape depends on the API).
+     */
+    verifyEmailRedirect(token: string, options?: RequestOptions): Promise<any>;
+    /**
+     * Sends a password reset email to the user's registered email address.
+     *
+     * @param {Object} request - The payload identifying the account (e.g., email address).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the reset email was dispatched successfully.
+     */
+    sendResetPassword(request: Account['sendResetPasswordRequest'], options?: RequestOptions): Promise<Account['statusResponse']>;
+    /**
+     * Resets the user's password using a reset token.
+     *
+     * @param {Object} request - The payload containing the reset token and the new password.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the password was reset successfully.
+     */
+    resetPassword(request: Account['resetPasswordRequest'], options?: RequestOptions): Promise<Account['statusResponse']>;
+    /**
+     * Sends a two-factor authentication (2FA) code to the user (e.g., via SMS or email).
+     *
+     * @param {Object} request - The payload identifying the account to send the code to.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A response confirming the 2FA code was sent.
+     */
+    send2FACode(request: Account['send2FACodeRequest'], options?: RequestOptions): Promise<Account['send2FAResponse']>;
+    /**
+     * Verifies a two-factor authentication (2FA) code submitted by the user.
+     *
+     * @param {Object} request - The payload containing the 2FA code to verify.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A response indicating whether the 2FA verification succeeded.
+     */
+    verify2FACode(request: Account['verify2FARequest'], options?: RequestOptions): Promise<Account['verify2FAResponse']>;
+}

package/esm/clients/modules/account-client.js

@@ -0,0 +1,107 @@
+import { BaseModule } from './base-module.js';
+export class AccountClient extends BaseModule {
+    basePath;
+    constructor(client, basePath) {
+        super(client);
+        this.basePath = basePath;
+    }
+    /**
+     * Sends a verification email to the user's registered email address.
+     *
+     * @param {Object} request - The payload identifying the account to send the email to.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the email was dispatched successfully.
+     */
+    async sendVerifyEmail(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/send-verify-email`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Verifies a user's email address using a verification token.
+     *
+     * @param {Object} request - The payload containing the verification token.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the email was verified successfully.
+     */
+    async verifyEmail(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/verify-email`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Handles the redirect-based email verification flow by passing the token as a query parameter.
+     *
+     * Typically used as the target of a link sent in a verification email.
+     *
+     * @param {string} token - The email verification token from the redirect URL.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The server response for the redirect verification (shape depends on the API).
+     */
+    async verifyEmailRedirect(token, options = {}) {
+        return this.sendRequest('get', `${this.basePath}/verify-email-redirect`, {
+            ...options,
+            params: {
+                ...(options.params ?? {}),
+                query: {
+                    ...(options.params?.query ?? {}),
+                    token
+                }
+            }
+        });
+    }
+    /**
+     * Sends a password reset email to the user's registered email address.
+     *
+     * @param {Object} request - The payload identifying the account (e.g., email address).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the reset email was dispatched successfully.
+     */
+    async sendResetPassword(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/send-reset-password`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Resets the user's password using a reset token.
+     *
+     * @param {Object} request - The payload containing the reset token and the new password.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A status response indicating whether the password was reset successfully.
+     */
+    async resetPassword(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/reset-password`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Sends a two-factor authentication (2FA) code to the user (e.g., via SMS or email).
+     *
+     * @param {Object} request - The payload identifying the account to send the code to.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A response confirming the 2FA code was sent.
+     */
+    async send2FACode(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/send-2fa-code`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Verifies a two-factor authentication (2FA) code submitted by the user.
+     *
+     * @param {Object} request - The payload containing the 2FA code to verify.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A response indicating whether the 2FA verification succeeded.
+     */
+    async verify2FACode(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/account/verify-2fa-code`, {
+            ...options,
+            body: request
+        });
+    }
+}

package/esm/clients/modules/auth-client.d.ts

@@ -0,0 +1,56 @@
+import { BaseModule, RequestOptions } from './base-module.js';
+import { BaseClientInterface } from '../base-client-interface.js';
+import { AUTH_OPERATIONS, AUTH_TYPES } from '../../constants.js';
+export type AuthType = Record<(typeof AUTH_TYPES)[number], unknown>;
+export type AuthInterface = {
+    [K in keyof typeof AUTH_OPERATIONS]: (...args: any[]) => Promise<any>;
+};
+export declare class AuthClient<Auth extends AuthType> extends BaseModule implements AuthInterface {
+    readonly basePath: string;
+    constructor(client: BaseClientInterface, basePath: string);
+    /**
+     * Authenticates a user with the provided credentials.
+     *
+     * @param {Object} request - The login payload (e.g., email and password).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An authentication response containing tokens and session info.
+     */
+    login(request: Auth['loginRequest'], options?: RequestOptions): Promise<Auth['authenticationResponse']>;
+    /**
+     * Logs out the currently authenticated user and invalidates the session.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The logout response from the server.
+     */
+    logout(options?: RequestOptions): Promise<Auth['logoutResponse']>;
+    /**
+     * Refreshes the current authentication session and issues new tokens.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A fresh authentication response with updated tokens.
+     */
+    refresh(options?: RequestOptions): Promise<Auth['authenticationResponse']>;
+    /**
+     * Changes the authenticated user's password.
+     *
+     * @param {Object} request - The change-password payload (e.g., current and new password).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An updated authentication response after the password change.
+     */
+    changePassword(request: Auth['changePasswordRequest'], options?: RequestOptions): Promise<Auth['authenticationResponse']>;
+    /**
+     * Exchanges a third-party or external token for an application authentication token.
+     *
+     * @param {Object} request - The token exchange payload (e.g., an OAuth code or external token).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An authentication response containing the issued application tokens.
+     */
+    exchangeToken(request: Auth['exchangeTokenRequest'], options?: RequestOptions): Promise<Auth['authenticationResponse']>;
+    /**
+     * Retrieves the identity of the currently authenticated user.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The identity object for the authenticated user.
+     */
+    me(options?: RequestOptions): Promise<Auth['identity']>;
+}

package/esm/clients/modules/auth-client.js

@@ -0,0 +1,74 @@
+import { BaseModule } from './base-module.js';
+export class AuthClient extends BaseModule {
+    basePath;
+    constructor(client, basePath) {
+        super(client);
+        this.basePath = basePath;
+    }
+    /**
+     * Authenticates a user with the provided credentials.
+     *
+     * @param {Object} request - The login payload (e.g., email and password).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An authentication response containing tokens and session info.
+     */
+    async login(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/login`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Logs out the currently authenticated user and invalidates the session.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The logout response from the server.
+     */
+    async logout(options = {}) {
+        return this.sendRequest('post', `${this.basePath}/logout`, options);
+    }
+    /**
+     * Refreshes the current authentication session and issues new tokens.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns A fresh authentication response with updated tokens.
+     */
+    async refresh(options = {}) {
+        return this.sendRequest('post', `${this.basePath}/refresh`, options);
+    }
+    /**
+     * Changes the authenticated user's password.
+     *
+     * @param {Object} request - The change-password payload (e.g., current and new password).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An updated authentication response after the password change.
+     */
+    async changePassword(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/change-password`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Exchanges a third-party or external token for an application authentication token.
+     *
+     * @param {Object} request - The token exchange payload (e.g., an OAuth code or external token).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns An authentication response containing the issued application tokens.
+     */
+    async exchangeToken(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/exchange-token`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Retrieves the identity of the currently authenticated user.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The identity object for the authenticated user.
+     */
+    async me(options = {}) {
+        return this.sendRequest('get', `${this.basePath}/me`, options);
+    }
+}

package/esm/clients/modules/base-module.d.ts

@@ -0,0 +1,17 @@
+import { FetchOptions } from 'openapi-fetch';
+import { HttpMethod } from 'openapi-typescript-helpers';
+import { BaseClientInterface, InitParam } from '../base-client-interface.js';
+import { FileDataResponse } from '../responses/index.js';
+export type RequestOptions<T = any> = FetchOptions<T>;
+export declare abstract class BaseModule {
+    private readonly _client;
+    protected constructor(_client: BaseClientInterface);
+    protected sendRequest<Resp = any>(method: HttpMethod, path: string, ...params: InitParam<any>): Promise<Resp>;
+    protected sendRequestRaw<Resp = any>(method: HttpMethod, path: string, ...params: InitParam<any>): Promise<{
+        data: Resp;
+        error: any;
+        response: Response;
+    }>;
+    protected toFileResponse(response: Response, defaultName?: string): FileDataResponse;
+    protected handleError(error: any, response: Response): void;
+}

package/esm/clients/modules/base-module.js

@@ -0,0 +1,49 @@
+import { FileDataResponse } from '../responses/index.js';
+import { ClientError } from '../../errors/index.js';
+export class BaseModule {
+    _client;
+    constructor(_client) {
+        this._client = _client;
+    }
+    async sendRequest(method, path, ...params) {
+        return this._client.sendRequestPromise(method, path, ...params);
+    }
+    async sendRequestRaw(method, path, ...params) {
+        return (await this._client.sendRequestRawPromise(method, path, ...params));
+    }
+    toFileResponse(response, defaultName = 'unknown') {
+        const fileName = response.headers
+            .get('Content-Disposition')
+            ?.split('filename=')[1]
+            ?.replace(/"/g, '') ?? defaultName;
+        const length = response.headers.get('Content-Length') ?? '0';
+        const maxAge = response.headers
+            .get('Cache-Control')
+            ?.split('max-age=')[1]
+            ?.replace(/"/g, '');
+        const matchRangeParts = response.headers
+            .get('Content-Range')
+            ?.match(/^bytes (\d+)-(\d+)\/(\d+)$/);
+        let range = undefined;
+        if (matchRangeParts) {
+            const [, start, end, total] = matchRangeParts;
+            range = {
+                start: parseInt(start, 10),
+                end: parseInt(end, 10),
+                total: parseInt(total, 10)
+            };
+        }
+        return new FileDataResponse({
+            fileName,
+            stream: response.body,
+            type: response.headers.get('Content-Type') ?? '',
+            length: parseInt(length, 10),
+            range,
+            maxAge: maxAge ? parseInt(maxAge, 10) : undefined,
+            expiresAt: response.headers.get('Expires') ?? undefined
+        });
+    }
+    handleError(error, response) {
+        throw new ClientError(error.message ?? response.statusText ?? 'Unknown error', error.errorCode ?? response.status, response, error);
+    }
+}

package/esm/clients/modules/files-client.d.ts

@@ -0,0 +1,27 @@
+import { BaseModule, RequestOptions } from './base-module.js';
+import { BaseClientInterface } from '../base-client-interface.js';
+import { FileDataResponse } from '../responses/index.js';
+import { FILE_OPERATIONS } from '../../constants.js';
+export type FilesInterface = {
+    [K in keyof typeof FILE_OPERATIONS]: (...args: any[]) => Promise<any>;
+};
+export declare class FilesClient extends BaseModule implements FilesInterface {
+    readonly basePath: string;
+    constructor(client: BaseClientInterface, basePath: string);
+    /**
+     * Downloads a publicly accessible file by its path/name.
+     *
+     * @param {string} fileName - The path or name of the file to retrieve from the public storage.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns {@link FileDataResponse} containing the readable stream and file metadata.
+     */
+    public(fileName: string, options?: RequestOptions): Promise<FileDataResponse>;
+    /**
+     * Downloads a protected file by its path/name. Requires the request to be authenticated.
+     *
+     * @param {string} fileName - The path or name of the file to retrieve from the protected storage.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns {@link FileDataResponse} containing the readable stream and file metadata.
+     */
+    protected(fileName: string, options?: RequestOptions): Promise<FileDataResponse>;
+}