@appweaver/client 1.0.22 → 1.0.24

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

@@ -0,0 +1,42 @@
+import { BaseModule } from './base-module.js';
+export class FilesClient extends BaseModule {
+    basePath;
+    constructor(client, basePath) {
+        super(client);
+        this.basePath = basePath;
+    }
+    /**
+     * 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.
+     */
+    async public(fileName, options = {}) {
+        const { error, response } = await this.sendRequestRaw('get', `${this.basePath}/public/${fileName}`, {
+            ...options,
+            parseAs: 'stream'
+        });
+        if (error) {
+            this.handleError(error, response);
+        }
+        return this.toFileResponse(response, fileName);
+    }
+    /**
+     * 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.
+     */
+    async protected(fileName, options = {}) {
+        const { error, response } = await this.sendRequestRaw('get', `${this.basePath}/protected/${fileName}`, {
+            ...options,
+            parseAs: 'stream'
+        });
+        if (error) {
+            this.handleError(error, response);
+        }
+        return this.toFileResponse(response, fileName);
+    }
+}

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

@@ -0,0 +1,25 @@
+import { BaseModule, RequestOptions } from './base-module.js';
+import { BaseClientInterface } from '../base-client-interface.js';
+import { HEALTH_OPERATIONS, HEALTH_TYPES } from '../../constants.js';
+export type HealthType = Record<(typeof HEALTH_TYPES)[number], unknown>;
+export type HealthInterface = {
+    [K in keyof typeof HEALTH_OPERATIONS]: (...args: any[]) => Promise<any>;
+};
+export declare class HealthClient<Health extends HealthType> extends BaseModule implements HealthInterface {
+    readonly basePath: string;
+    constructor(client: BaseClientInterface, basePath: string);
+    /**
+     * Performs a basic health check against the server.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The health check response indicating overall server and it's services status.
+     */
+    check(options?: RequestOptions): Promise<Health['checkResponse']>;
+    /**
+     * Checks whether the server is ready to accept traffic (e.g., database connected, migrations applied).
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The readiness response indicating whether the server is fully operational.
+     */
+    ready(options?: RequestOptions): Promise<Health['readyResponse']>;
+}

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

@@ -0,0 +1,30 @@
+import { BaseModule } from './base-module.js';
+export class HealthClient extends BaseModule {
+    basePath;
+    constructor(client, basePath) {
+        super(client);
+        this.basePath = basePath;
+    }
+    /**
+     * Performs a basic health check against the server.
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The health check response indicating overall server and it's services status.
+     */
+    async check(options = {}) {
+        const { data, error, response } = await this.sendRequestRaw('get', `${this.basePath}/check`, options);
+        if (error && response.status !== 503) {
+            this.handleError(error, response);
+        }
+        return data ?? error;
+    }
+    /**
+     * Checks whether the server is ready to accept traffic (e.g., database connected, migrations applied).
+     *
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The readiness response indicating whether the server is fully operational.
+     */
+    async ready(options = {}) {
+        return this.sendRequest('get', `${this.basePath}/ready`, options);
+    }
+}

package/esm/clients/modules/index.d.ts

@@ -0,0 +1,6 @@
+export * from './account-client.js';
+export * from './auth-client.js';
+export * from './base-module.js';
+export * from './files-client.js';
+export * from './health-client.js';
+export * from './resource-client.js';

package/esm/clients/modules/index.js

@@ -0,0 +1,6 @@
+export * from './account-client.js';
+export * from './auth-client.js';
+export * from './base-module.js';
+export * from './files-client.js';
+export * from './health-client.js';
+export * from './resource-client.js';

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

@@ -0,0 +1,90 @@
+import { BaseModule, RequestOptions } from './base-module.js';
+import { BaseClientInterface } from '../base-client-interface.js';
+import { FileDataResponse } from '../responses/index.js';
+import { RESOURCE_OPERATIONS, RESOURCE_TYPES } from '../../constants.js';
+export type ResourceType = Record<(typeof RESOURCE_TYPES)[number], unknown>;
+export type ResourceInterface = {
+    [K in keyof typeof RESOURCE_OPERATIONS]: (...args: any[]) => Promise<any>;
+};
+export declare class ResourceClient<Resource extends ResourceType> extends BaseModule implements ResourceInterface {
+    readonly basePath: string;
+    constructor(client: BaseClientInterface, basePath: string);
+    /**
+     * Fetches a single resource by its numeric ID.
+     *
+     * @param {number} id - The ID of the resource to retrieve.
+     * @param {RequestOptions} options - Additional request options (headers, query params, etc.).
+     * @returns The resource record matching the given ID.
+     */
+    find(id: number, options?: RequestOptions): Promise<Resource['single']>;
+    /**
+     * Executes a query against the resource collection.
+     *
+     * @param {Object} request - The query payload (filters, sorting, pagination, etc.).
+     * @param {RequestOptions}  options - Additional request options.
+     * @returns A paginated or filtered list of matching resource records.
+     */
+    query(request: Resource['queryRequest'], options?: RequestOptions): Promise<Resource['queryResponse']>;
+    /**
+     * Runs an aggregation query (e.g., count, sum, avg) against the resource collection.
+     *
+     * @param {Object} request - The aggregation payload describing the desired computation.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The aggregated result for the given query.
+     */
+    aggregate(request: Resource['aggregateRequest'], options?: RequestOptions): Promise<Resource['aggregateResponse']>;
+    /**
+     * Creates a new resource record.
+     *
+     * @param {Object} resource - The data for the resource to create.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The newly created resource record.
+     */
+    create(resource: Resource['create'], options?: RequestOptions): Promise<Resource['single']>;
+    /**
+     * Updates an existing resource record identified by `id`.
+     *
+     * @param {Object} resource - The updated field values including the mandatory `id`.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated resource record.
+     */
+    update(resource: Resource['update'] & {
+        id: number;
+    }, options?: RequestOptions): Promise<Resource['single']>;
+    /**
+     * Deletes a resource record by its numeric ID.
+     *
+     * @param {number} id - The ID of the resource to delete.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The deleted resource record.
+     */
+    delete(id: number, options?: RequestOptions): Promise<Resource['single']>;
+    /**
+     * Exports resource records as a file (e.g., CSV) and returns a streaming response.
+     *
+     * @param {Object} request - The export request payload (filters, format, etc.).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns {@link FileDataResponse} containing the readable stream and file metadata.
+     */
+    export(request: Resource['exportRequest'], options?: RequestOptions): Promise<FileDataResponse>;
+    /**
+     * Uploads one or more files to the resource record.
+     *
+     * Each entry in `files` maps a field name to a single `File` or an array of `File` objects.
+     *
+     * @param {number} id - The ID of the resource for which to upload files.
+     * @param {Object} files - A map of field names to the file(s) to upload.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated file metadata for the resource.
+     */
+    uploadFiles(id: number, files: Resource['fileUpload'], options?: RequestOptions): Promise<Resource['files']>;
+    /**
+     * Removes specific files from the resource record.
+     *
+     * @param {number} id - The ID of the resource for which to delete files.
+     * @param {Object} files - The file deletion payload identifying which files to remove.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated file metadata for the resource after deletion.
+     */
+    deleteFiles(id: number, files: Resource['fileDelete'], options?: RequestOptions): Promise<Resource['files']>;
+}

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

@@ -0,0 +1,173 @@
+import { BaseModule } from './base-module.js';
+export class ResourceClient extends BaseModule {
+    basePath;
+    constructor(client, basePath) {
+        super(client);
+        this.basePath = basePath;
+    }
+    /**
+     * Fetches a single resource by its numeric ID.
+     *
+     * @param {number} id - The ID of the resource to retrieve.
+     * @param {RequestOptions} options - Additional request options (headers, query params, etc.).
+     * @returns The resource record matching the given ID.
+     */
+    async find(id, options = {}) {
+        return this.sendRequest('get', `${this.basePath}/{id}`, {
+            ...options,
+            params: {
+                ...(options.params ?? {}),
+                path: {
+                    id
+                }
+            }
+        });
+    }
+    /**
+     * Executes a query against the resource collection.
+     *
+     * @param {Object} request - The query payload (filters, sorting, pagination, etc.).
+     * @param {RequestOptions}  options - Additional request options.
+     * @returns A paginated or filtered list of matching resource records.
+     */
+    async query(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/query`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Runs an aggregation query (e.g., count, sum, avg) against the resource collection.
+     *
+     * @param {Object} request - The aggregation payload describing the desired computation.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The aggregated result for the given query.
+     */
+    async aggregate(request, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/aggregate`, {
+            ...options,
+            body: request
+        });
+    }
+    /**
+     * Creates a new resource record.
+     *
+     * @param {Object} resource - The data for the resource to create.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The newly created resource record.
+     */
+    async create(resource, options = {}) {
+        return this.sendRequest('post', `${this.basePath}`, {
+            ...options,
+            body: resource
+        });
+    }
+    /**
+     * Updates an existing resource record identified by `id`.
+     *
+     * @param {Object} resource - The updated field values including the mandatory `id`.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated resource record.
+     */
+    async update(resource, options = {}) {
+        return this.sendRequest('put', `${this.basePath}/{id}`, {
+            ...options,
+            params: {
+                ...(options.params ?? {}),
+                path: {
+                    id: resource['id']
+                }
+            },
+            body: resource
+        });
+    }
+    /**
+     * Deletes a resource record by its numeric ID.
+     *
+     * @param {number} id - The ID of the resource to delete.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The deleted resource record.
+     */
+    async delete(id, options = {}) {
+        return this.sendRequest('delete', `${this.basePath}/{id}`, {
+            ...options,
+            params: {
+                ...(options.params ?? {}),
+                path: {
+                    id
+                }
+            }
+        });
+    }
+    /**
+     * Exports resource records as a file (e.g., CSV) and returns a streaming response.
+     *
+     * @param {Object} request - The export request payload (filters, format, etc.).
+     * @param {RequestOptions} options - Additional request options.
+     * @returns {@link FileDataResponse} containing the readable stream and file metadata.
+     */
+    async export(request, options = {}) {
+        const { error, response } = await this.sendRequestRaw('post', `${this.basePath}/export`, {
+            ...options,
+            parseAs: 'stream',
+            body: request
+        });
+        if (error) {
+            this.handleError(error, response);
+        }
+        return this.toFileResponse(response);
+    }
+    /**
+     * Uploads one or more files to the resource record.
+     *
+     * Each entry in `files` maps a field name to a single `File` or an array of `File` objects.
+     *
+     * @param {number} id - The ID of the resource for which to upload files.
+     * @param {Object} files - A map of field names to the file(s) to upload.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated file metadata for the resource.
+     */
+    async uploadFiles(id, files, options = {}) {
+        const formData = new FormData();
+        for (const [fieldName, fileData] of Object.entries(files)) {
+            if (Array.isArray(fileData)) {
+                for (const file of fileData) {
+                    formData.append(fieldName, file);
+                }
+            }
+            else {
+                formData.append(fieldName, fileData);
+            }
+        }
+        return this.sendRequest('post', `${this.basePath}/{id}/files`, {
+            ...options,
+            body: formData,
+            params: {
+                ...(options.params ?? {}),
+                path: {
+                    id
+                }
+            }
+        });
+    }
+    /**
+     * Removes specific files from the resource record.
+     *
+     * @param {number} id - The ID of the resource for which to delete files.
+     * @param {Object} files - The file deletion payload identifying which files to remove.
+     * @param {RequestOptions} options - Additional request options.
+     * @returns The updated file metadata for the resource after deletion.
+     */
+    async deleteFiles(id, files, options = {}) {
+        return this.sendRequest('post', `${this.basePath}/{id}/delete-files`, {
+            ...options,
+            body: files,
+            params: {
+                ...(options.params ?? {}),
+                path: {
+                    id
+                }
+            }
+        });
+    }
+}

package/esm/clients/responses/file-data-response.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Response object containing file data and metadata from a file download request.
+ * Provides helper methods to consume the stream as text, base64 data URL, or Buffer.
+ */
+export declare class FileDataResponse {
+    /** Readable stream of the file content. */
+    readonly stream: ReadableStream;
+    /** Name of the file extracted from the Content-Disposition header or provided default. */
+    readonly fileName: string;
+    /** MIME type of the file from the Content-Type header. */
+    readonly type: string;
+    /** Size of the file in bytes from the Content-Length header. */
+    readonly length: number;
+    /** Range information if the response is a partial content response (HTTP 206). */
+    readonly range?: FileContentRange;
+    /** Cache duration in seconds from the Cache-Control max-age directive. */
+    readonly maxAge?: number;
+    /** Expiration timestamp from Expires header. */
+    readonly expiresAt?: string;
+    private _buffer;
+    constructor(data: {
+        stream: ReadableStream;
+        fileName: string;
+        type: string;
+        length: number;
+        range?: FileContentRange;
+        maxAge?: number;
+        expiresAt?: string;
+    });
+    /**
+     * Reads and returns the content of the buffer as an ArrayBuffer.
+     *
+     * @return {Promise<ArrayBuffer>} A promise that resolves to an ArrayBuffer containing the data read from the buffer.
+     */
+    buffer(): Promise<ArrayBuffer>;
+    /**
+     * Reads and returns the content of the buffer as a Blob object.
+     *
+     * The method reads an ArrayBuffer from an internal data source, then constructs,
+     * and returns a Blob object using the buffer's content and a specified MIME type.
+     *
+     * @return {Promise<Blob>} A promise that resolves to a Blob object containing the read data.
+     */
+    blob(): Promise<Blob>;
+    /**
+     * Reads and decodes the content of the buffer into a string using the TextDecoder API.
+     *
+     * @param {string} encoding - The character encoding to use for decoding. Defaults to 'utf-8'.
+     * @return {Promise<string>} A promise that resolves to the decoded string.
+     */
+    text(encoding?: string): Promise<string>;
+    /**
+     * Reads and converts the buffer into a Base64-encoded data URL string.
+     *
+     * @return {Promise<string>} A promise that resolves to a Base64-encoded string
+     * representing the file, prefixed with the appropriate data MIME type.
+     */
+    base64(): Promise<string>;
+    /**
+     * Reads and concatenates data chunks from a readable stream into a single ArrayBuffer.
+     * If the buffer has already been read, it returns the cached ArrayBuffer.
+     *
+     * @return {Promise<ArrayBuffer>} A promise that resolves to the ArrayBuffer containing
+     * the concatenated data from the stream.
+     */
+    private _readArrayBuffer;
+}
+/**
+ * Represents byte range information for partial content responses.
+ */
+export type FileContentRange = {
+    /** Starting byte position of the range (inclusive). */
+    start: number;
+    /** Ending byte position of the range (inclusive). */
+    end: number;
+    /** Total size of the complete file in bytes. */
+    total: number;
+};

package/esm/clients/responses/file-data-response.js

@@ -0,0 +1,105 @@
+/**
+ * Response object containing file data and metadata from a file download request.
+ * Provides helper methods to consume the stream as text, base64 data URL, or Buffer.
+ */
+export class FileDataResponse {
+    /** Readable stream of the file content. */
+    stream;
+    /** Name of the file extracted from the Content-Disposition header or provided default. */
+    fileName;
+    /** MIME type of the file from the Content-Type header. */
+    type;
+    /** Size of the file in bytes from the Content-Length header. */
+    length;
+    /** Range information if the response is a partial content response (HTTP 206). */
+    range;
+    /** Cache duration in seconds from the Cache-Control max-age directive. */
+    maxAge;
+    /** Expiration timestamp from Expires header. */
+    expiresAt;
+    _buffer;
+    constructor(data) {
+        this.stream = data.stream;
+        this.fileName = data.fileName;
+        this.type = data.type;
+        this.length = data.length;
+        this.range = data.range;
+        this.maxAge = data.maxAge;
+        this.expiresAt = data.expiresAt;
+    }
+    /**
+     * Reads and returns the content of the buffer as an ArrayBuffer.
+     *
+     * @return {Promise<ArrayBuffer>} A promise that resolves to an ArrayBuffer containing the data read from the buffer.
+     */
+    async buffer() {
+        return this._readArrayBuffer();
+    }
+    /**
+     * Reads and returns the content of the buffer as a Blob object.
+     *
+     * The method reads an ArrayBuffer from an internal data source, then constructs,
+     * and returns a Blob object using the buffer's content and a specified MIME type.
+     *
+     * @return {Promise<Blob>} A promise that resolves to a Blob object containing the read data.
+     */
+    async blob() {
+        const buf = await this._readArrayBuffer();
+        return new Blob([buf], { type: this.type });
+    }
+    /**
+     * Reads and decodes the content of the buffer into a string using the TextDecoder API.
+     *
+     * @param {string} encoding - The character encoding to use for decoding. Defaults to 'utf-8'.
+     * @return {Promise<string>} A promise that resolves to the decoded string.
+     */
+    async text(encoding = 'utf-8') {
+        const buf = await this._readArrayBuffer();
+        return new TextDecoder(encoding).decode(buf);
+    }
+    /**
+     * Reads and converts the buffer into a Base64-encoded data URL string.
+     *
+     * @return {Promise<string>} A promise that resolves to a Base64-encoded string
+     * representing the file, prefixed with the appropriate data MIME type.
+     */
+    async base64() {
+        const buf = await this._readArrayBuffer();
+        const bytes = new Uint8Array(buf);
+        let binary = '';
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        const encoded = btoa(binary);
+        return `data:${this.type};base64,${encoded}`;
+    }
+    /**
+     * Reads and concatenates data chunks from a readable stream into a single ArrayBuffer.
+     * If the buffer has already been read, it returns the cached ArrayBuffer.
+     *
+     * @return {Promise<ArrayBuffer>} A promise that resolves to the ArrayBuffer containing
+     * the concatenated data from the stream.
+     */
+    async _readArrayBuffer() {
+        if (this._buffer !== undefined) {
+            return this._buffer;
+        }
+        const reader = this.stream.getReader();
+        const chunks = [];
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+        }
+        const totalLength = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        this._buffer = result.buffer;
+        return this._buffer;
+    }
+}

package/esm/clients/responses/index.d.ts

@@ -0,0 +1 @@
+export * from './file-data-response.js';

package/esm/clients/responses/index.js

@@ -0,0 +1 @@
+export * from './file-data-response.js';

package/esm/commands/generate-command.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function generateCommand(program: Command): void;
+export declare function relativePathFrom(firstPath: string, otherPath: string): string;