@appweaver/client 1.0.22 → 1.0.24

package/esm/commands/generate-command.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import prettier from 'prettier';
+import { InvalidArgumentError, InvalidOptionArgumentError } from 'commander';
+import { generateClient, generateTypes } from '../generators/index.js';
+import { readSchemaContent, toSchemaObject } from '../utils/index.js';
+import { FRAMEWORKS } from '../constants.js';
+export function generateCommand(program) {
+    program
+        .command('generate')
+        .alias('g')
+        .description('Generates types and client class.')
+        .argument('<schemaPath>', 'The path to the OpenAPI schema (file or URL)', parseSchema)
+        .option('--outputPath [path]', 'Output path for both generated types and client class.', './generated/client.ts')
+        .option('--typesPath [path]', 'Output path for generated types. (default: output path)')
+        .option('--clientPath [path]', 'Output path for generated client class. (default: output path)')
+        .option('--clientName [name]', 'Name for generated client class. (default: OpenAPI schema title)')
+        .option('--framework [name]', `The framework for generated client class (${FRAMEWORKS.join(', ')})`, parseFramework, 'fetch')
+        .option('--typesOnly', 'Generate TypeScript types only (without client class).')
+        .option('--clientOnly', 'Generate only client class (without TypeScript types).')
+        .option('--noTypes', 'Generate client class without TypeScript type support.')
+        .action(async (schemaPath, _, command) => {
+        const outputPath = command.getOptionValue('outputPath');
+        const typesPath = command.getOptionValue('typesPath') || outputPath;
+        const clientPath = command.getOptionValue('clientPath') || outputPath;
+        const clientName = command.getOptionValue('clientName');
+        const framework = command.getOptionValue('framework');
+        const typesOnly = command.getOptionValue('typesOnly');
+        const clientOnly = command.getOptionValue('clientOnly');
+        const noTypes = command.getOptionValue('noTypes');
+        const cwd = process.cwd();
+        const schemaContent = await readSchemaContent(schemaPath);
+        const schemaObject = await toSchemaObject(schemaContent);
+        if (!clientOnly && !noTypes) {
+            const typesContent = await generateTypes(schemaObject);
+            await formatAndWriteFile(typesPath, typesContent, typesOnly || typesPath !== clientPath);
+            console.log(`Generated types to ${path.relative(cwd, typesPath)}`);
+        }
+        if (!typesOnly) {
+            const typesImportPath = typesPath === clientPath
+                ? undefined
+                : relativePathFrom(clientPath, typesPath);
+            const clientContent = await generateClient(schemaObject, clientName, framework, typesImportPath, noTypes);
+            await formatAndWriteFile(clientPath, clientContent, true, typesPath === clientPath);
+            console.log(`Generated client to ${path.relative(cwd, clientPath)}`);
+        }
+    });
+}
+async function formatAndWriteFile(filePath, content, addGeneratedComment = true, appendIfExists = false) {
+    const dirPath = path.resolve(path.dirname(filePath));
+    const dirExists = await pathExists(dirPath);
+    if (!dirExists) {
+        await fsp.mkdir(dirPath, { recursive: true });
+    }
+    const prettierConfig = await prettier.resolveConfig(filePath);
+    let formattedContent = await prettier.format(content, {
+        ...(prettierConfig ?? { singleQuote: true, trailingComma: 'none' }),
+        filepath: filePath
+    });
+    const fileExists = await pathExists(filePath);
+    if (appendIfExists && fileExists) {
+        const existingContent = await fsp.readFile(filePath, 'utf8');
+        formattedContent = formattedContent + '\n' + existingContent;
+    }
+    if (addGeneratedComment) {
+        formattedContent =
+            '// Generated by Appweaver. Please do not edit this file manually.\n\n' +
+                formattedContent;
+    }
+    await fsp.writeFile(filePath, formattedContent, 'utf8');
+}
+async function pathExists(filePath) {
+    try {
+        await fsp.access(filePath, fsp.constants.F_OK);
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+export function relativePathFrom(firstPath, otherPath) {
+    const firstDir = path.dirname(path.resolve(firstPath));
+    const otherAbs = path.resolve(otherPath);
+    let rel = path.relative(firstDir, otherAbs);
+    if (!rel.startsWith('.') && rel !== '') {
+        rel = `.${path.sep}${rel}`;
+    }
+    else if (rel === '') {
+        rel = '.';
+    }
+    if (rel.endsWith('.ts')) {
+        rel = rel.replace('.d.ts', '.ts').replace('.ts', '');
+    }
+    return rel.replace(/\\/g, '/');
+}
+function parseSchema(value) {
+    let schemaUrl;
+    try {
+        schemaUrl = new URL(value);
+    }
+    catch {
+        // Schema path is not in URL format
+    }
+    if (schemaUrl) {
+        if (!['http:', 'https:', 'file:'].includes(schemaUrl.protocol)) {
+            throw new InvalidArgumentError(`Unsupported schema URL protocol: ${schemaUrl.protocol}`);
+        }
+        return value;
+    }
+    if (!fs.existsSync(value)) {
+        throw new InvalidArgumentError(`Schema path "${value}" does not exist or is not a valid URL.`);
+    }
+    return value;
+}
+function parseFramework(value) {
+    const lowerFramework = value.toLowerCase();
+    if (!FRAMEWORKS.includes(lowerFramework)) {
+        throw new InvalidOptionArgumentError(`Must be one of following: ${FRAMEWORKS.join(', ')}.`);
+    }
+    return lowerFramework;
+}

package/esm/commands/index.d.ts

@@ -0,0 +1 @@
+export * from './generate-command.js';

package/esm/commands/index.js

@@ -0,0 +1 @@
+export * from './generate-command.js';

package/esm/constants.d.ts

@@ -0,0 +1,67 @@
+/** Supported frameworks for generating the client class. */
+export declare const FRAMEWORKS: readonly ["fetch", "angular"];
+/** Custom OpenAPI extension key used for extracting route prefixes and base paths to their resources. */
+export declare const CONFIG_FIELD = "x-appweaver-config";
+/** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
+export declare const CONFIG_RESOURCE_FIELD = "x-appweaver-resource";
+/** Suffix used when generating the TypeScript module type name for a resource. */
+export declare const RESOURCE_MODULE_TYPE = "ResourceModuleType";
+/** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */
+export declare const RESOURCE_OPERATIONS: {
+    readonly find: "get";
+    readonly query: "post";
+    readonly aggregate: "post";
+    readonly create: "post";
+    readonly update: "put";
+    readonly delete: "delete";
+    readonly export: "post";
+    readonly uploadFiles: "post";
+    readonly deleteFiles: "post";
+};
+/** Expected type keys for a resource used for type inference. */
+export declare const RESOURCE_TYPES: readonly ["single", "multiple", "create", "update", "queryRequest", "queryResponse", "aggregateRequest", "aggregateResponse", "exportRequest", "files", "fileUpload", "fileDelete"];
+/** Type name used when generating the TypeScript module type for the auth module. */
+export declare const AUTH_MODULE_TYPE = "AuthModuleType";
+/** Maps auth operation names to HTTP methods used for matchingOpenAPI paths to `AuthClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export declare const AUTH_OPERATIONS: {
+    readonly login: "post";
+    readonly logout: "post";
+    readonly refresh: "post";
+    readonly changePassword: "post";
+    readonly exchangeToken: "post";
+    readonly me: "get";
+};
+/** Expected type keys for the auth module used for type safety. */
+export declare const AUTH_TYPES: readonly ["loginRequest", "authenticationResponse", "logoutResponse", "changePasswordRequest", "exchangeTokenRequest", "identity"];
+/** Type name used when generating the TypeScript module type for the account module. */
+export declare const ACCOUNT_MODULE_TYPE = "AccountModuleType";
+/** Maps account operation names to HTTP methods used for matching OpenAPI paths to `AccountClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export declare const ACCOUNT_OPERATIONS: {
+    readonly sendVerifyEmail: "post";
+    readonly verifyEmail: "post";
+    readonly verifyEmailRedirect: "get";
+    readonly sendResetPassword: "post";
+    readonly resetPassword: "post";
+    readonly send2FACode: "post";
+    readonly verify2FACode: "post";
+};
+/** Expected type keys for the account module which covers email verification, password reset, and 2FA req/resp. */
+export declare const ACCOUNT_TYPES: readonly ["sendEmailVerificationRequest", "statusResponse", "emailVerificationRequest", "sendResetPasswordRequest", "resetPasswordRequest", "send2FACodeRequest", "send2FAResponse", "verify2FARequest", "verify2FAResponse"];
+/** Type name used when generating the TypeScript module type for the health module. */
+export declare const HEALTH_MODULE_TYPE = "HealthModuleType";
+/** Maps health check operations to HTTP GET methods used for matching OpenAPI paths to `HealthClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export declare const HEALTH_OPERATIONS: {
+    readonly check: "get";
+    readonly ready: "get";
+};
+/** Expected type keys for the health module used for `HealthClient` response typing. */
+export declare const HEALTH_TYPES: readonly ["checkResponse", "readyResponse"];
+/** Maps file-serving operations to HTTP GET methods used for identifying public and protected file endpoints.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export declare const FILE_OPERATIONS: {
+    readonly public: "get";
+    readonly protected: "get";
+};

package/esm/constants.js

@@ -0,0 +1,94 @@
+// CAUTION: The constants in this file should not be changed without good reason.
+// They are typically only modified when changes occur in other Appweaver packages
+// (such as core and common) to reflect new route paths or methods.
+/** Supported frameworks for generating the client class. */
+export const FRAMEWORKS = ['fetch', 'angular'];
+/** Custom OpenAPI extension key used for extracting route prefixes and base paths to their resources. */
+export const CONFIG_FIELD = 'x-appweaver-config';
+/** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
+export const CONFIG_RESOURCE_FIELD = 'x-appweaver-resource';
+/** Suffix used when generating the TypeScript module type name for a resource. */
+export const RESOURCE_MODULE_TYPE = 'ResourceModuleType';
+/** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */
+export const RESOURCE_OPERATIONS = {
+    find: 'get',
+    query: 'post',
+    aggregate: 'post',
+    create: 'post',
+    update: 'put',
+    delete: 'delete',
+    export: 'post',
+    uploadFiles: 'post',
+    deleteFiles: 'post'
+};
+/** Expected type keys for a resource used for type inference. */
+export const RESOURCE_TYPES = [
+    'single',
+    'multiple',
+    'create',
+    'update',
+    'queryRequest',
+    'queryResponse',
+    'aggregateRequest',
+    'aggregateResponse',
+    'exportRequest',
+    'files',
+    'fileUpload',
+    'fileDelete'
+];
+/** Type name used when generating the TypeScript module type for the auth module. */
+export const AUTH_MODULE_TYPE = 'AuthModuleType';
+/** Maps auth operation names to HTTP methods used for matchingOpenAPI paths to `AuthClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export const AUTH_OPERATIONS = {
+    login: 'post',
+    logout: 'post',
+    refresh: 'post',
+    changePassword: 'post',
+    exchangeToken: 'post',
+    me: 'get'
+};
+/** Expected type keys for the auth module used for type safety. */
+export const AUTH_TYPES = [
+    'loginRequest',
+    'authenticationResponse',
+    'logoutResponse',
+    'changePasswordRequest',
+    'exchangeTokenRequest',
+    'identity'
+];
+/** Type name used when generating the TypeScript module type for the account module. */
+export const ACCOUNT_MODULE_TYPE = 'AccountModuleType';
+/** Maps account operation names to HTTP methods used for matching OpenAPI paths to `AccountClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export const ACCOUNT_OPERATIONS = {
+    sendVerifyEmail: 'post',
+    verifyEmail: 'post',
+    verifyEmailRedirect: 'get',
+    sendResetPassword: 'post',
+    resetPassword: 'post',
+    send2FACode: 'post',
+    verify2FACode: 'post'
+};
+/** Expected type keys for the account module which covers email verification, password reset, and 2FA req/resp. */
+export const ACCOUNT_TYPES = [
+    'sendEmailVerificationRequest',
+    'statusResponse',
+    'emailVerificationRequest',
+    'sendResetPasswordRequest',
+    'resetPasswordRequest',
+    'send2FACodeRequest',
+    'send2FAResponse',
+    'verify2FARequest',
+    'verify2FAResponse'
+];
+/** Type name used when generating the TypeScript module type for the health module. */
+export const HEALTH_MODULE_TYPE = 'HealthModuleType';
+/** Maps health check operations to HTTP GET methods used for matching OpenAPI paths to `HealthClient` methods.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export const HEALTH_OPERATIONS = { check: 'get', ready: 'get' };
+/** Expected type keys for the health module used for `HealthClient` response typing. */
+export const HEALTH_TYPES = ['checkResponse', 'readyResponse'];
+/** Maps file-serving operations to HTTP GET methods used for identifying public and protected file endpoints.
+ * The operation names are matching the real API paths (without a prefix and in camelCase format) from the OpenAPI. */
+export const FILE_OPERATIONS = { public: 'get', protected: 'get' };

package/esm/errors/client-error.d.ts

@@ -0,0 +1,6 @@
+export declare class ClientError extends Error {
+    errorCode: number;
+    response?: Response | undefined;
+    data?: any | undefined;
+    constructor(text: string, errorCode: number, response?: Response | undefined, data?: any | undefined);
+}

package/esm/errors/client-error.js

@@ -0,0 +1,11 @@
+export class ClientError extends Error {
+    errorCode;
+    response;
+    data;
+    constructor(text, errorCode, response, data) {
+        super(text);
+        this.errorCode = errorCode;
+        this.response = response;
+        this.data = data;
+    }
+}

package/esm/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './client-error.js';

package/esm/errors/index.js

@@ -0,0 +1 @@
+export * from './client-error.js';

package/esm/generators/generate-client.d.ts

@@ -0,0 +1,16 @@
+import { OpenAPI3 } from 'openapi-typescript';
+import { FRAMEWORKS } from '../constants.js';
+/**
+ * Generates a client class based on the provided OpenAPI schema and already generated types.
+ *
+ * @param {string | OpenAPI3} schema - The OpenAPI schema used to generate the client. Can be a string
+ * (URL or JSON/YAML) or an object.
+ * @param {string} [clientName] - Optional name of the client class name to be generated. (default: derived from OpenAPI
+ * title or WeaverClient if title is missing)
+ * @param {string} [framework='fetch'] - Optional framework for which to generate the client class.
+ * @param {string} [typesPath] - Optional path to the types module, for importing related type definitions.
+ * @param {boolean} [noTypes=false] - Optional flag to disable client class generic types, useful for environments
+ * without type support.
+ * @return {Promise<string>} A Promise that resolves to the generated client class as a string.
+ */
+export declare function generateClient(schema: string | OpenAPI3, clientName?: string, framework?: (typeof FRAMEWORKS)[number], typesPath?: string, noTypes?: boolean): Promise<string>;