@appweaver/client 1.0.0

package/constants.js

@@ -0,0 +1,97 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_OPERATIONS = exports.HEALTH_TYPES = exports.HEALTH_OPERATIONS = exports.HEALTH_MODULE_TYPE = exports.ACCOUNT_TYPES = exports.ACCOUNT_OPERATIONS = exports.ACCOUNT_MODULE_TYPE = exports.AUTH_TYPES = exports.AUTH_OPERATIONS = exports.AUTH_MODULE_TYPE = exports.RESOURCE_TYPES = exports.RESOURCE_OPERATIONS = exports.RESOURCE_MODULE_TYPE = exports.CONFIG_RESOURCE_FIELD = exports.CONFIG_FIELD = exports.FRAMEWORKS = void 0;
+/** Supported frameworks for generating the client class. */
+exports.FRAMEWORKS = ['fetch', 'angular'];
+/** Custom OpenAPI extension key used for extracting route prefixes and base paths to their resources. */
+exports.CONFIG_FIELD = 'x-appweaver-config';
+/** Custom OpenAPI extension key used for extracting resources names from schema CRUD objects. */
+exports.CONFIG_RESOURCE_FIELD = 'x-appweaver-resource';
+/** Suffix used when generating the TypeScript module type name for a resource. */
+exports.RESOURCE_MODULE_TYPE = 'ResourceModuleType';
+/** Maps CRUD operation names to HTTP methods used for matching OpenAPI paths to `ResourceClient` methods. */
+exports.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. */
+exports.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. */
+exports.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. */
+exports.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. */
+exports.AUTH_TYPES = [
+    'loginRequest',
+    'authenticationResponse',
+    'logoutResponse',
+    'changePasswordRequest',
+    'exchangeTokenRequest',
+    'identity'
+];
+/** Type name used when generating the TypeScript module type for the account module. */
+exports.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. */
+exports.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. */
+exports.ACCOUNT_TYPES = [
+    'sendEmailVerificationRequest',
+    'statusResponse',
+    'emailVerificationRequest',
+    'sendResetPasswordRequest',
+    'resetPasswordRequest',
+    'send2FACodeRequest',
+    'send2FAResponse',
+    'verify2FARequest',
+    'verify2FAResponse'
+];
+/** Type name used when generating the TypeScript module type for the health module. */
+exports.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. */
+exports.HEALTH_OPERATIONS = { check: 'get', ready: 'get' };
+/** Expected type keys for the health module used for `HealthClient` response typing. */
+exports.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. */
+exports.FILE_OPERATIONS = { public: 'get', protected: 'get' };

package/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/errors/client-error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientError = void 0;
+class ClientError extends Error {
+    errorCode;
+    response;
+    data;
+    constructor(text, errorCode, response, data) {
+        super(text);
+        this.errorCode = errorCode;
+        this.response = response;
+        this.data = data;
+    }
+}
+exports.ClientError = ClientError;

package/errors/index.d.ts

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

package/errors/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client-error"), exports);

package/generators/generate-client.d.ts

@@ -0,0 +1,16 @@
+import { OpenAPI3 } from 'openapi-typescript';
+import { FRAMEWORKS } from '../constants';
+/**
+ * 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>;

package/generators/generate-client.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateClient = generateClient;
+const clients_1 = require("../clients");
+const utils_1 = require("../utils");
+const constants_1 = require("../constants");
+/**
+ * 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.
+ */
+async function generateClient(schema, clientName, framework = 'fetch', typesPath, noTypes = false) {
+    const schemaObject = typeof schema === 'string' ? await (0, utils_1.toSchemaObject)(schema) : schema;
+    // Resolve the client class name
+    let className = clientName;
+    if (!className) {
+        const openApiTitle = schemaObject.info?.title || 'Weaver';
+        className = `${openApiTitle.replace(' ', '')}Client`;
+    }
+    // Resolve the type import statement and types prefix
+    const typeName = 'Type';
+    const typePrefix = typesPath ? `${typeName}.` : '';
+    const pathsTypeImport = typesPath && !noTypes
+        ? `import * as ${typeName} from '${typesPath}';\n`
+        : '';
+    const pathsTypeGeneric = !noTypes ? `<${typePrefix}paths>` : '';
+    const config = schemaObject[constants_1.CONFIG_FIELD];
+    const schemaRoutes = {
+        resource: {},
+        auth: [],
+        account: [],
+        health: [],
+        files: [],
+        custom: []
+    };
+    for (const [path, item] of Object.entries(schemaObject.paths || {})) {
+        // Skip object references
+        if (item['$ref']) {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(item)) {
+            // Pass only for valid HTTP methods
+            if (['servers', 'parameters'].includes(method)) {
+                continue;
+            }
+            const { type, operationName, resourceName } = routeDetails(path, method, operation, config);
+            // Populate schema routes based on route details
+            if (type === 'resource') {
+                if (!resourceName) {
+                    continue;
+                }
+                schemaRoutes.resource[resourceName] ??= [];
+                schemaRoutes.resource[resourceName].push(operationName);
+            }
+            else if (type === 'custom') {
+                if (path.startsWith(`${config.routePrefixes.auth}/login/`)) {
+                    continue;
+                }
+                schemaRoutes.custom.push({
+                    method,
+                    path,
+                    operationName
+                });
+            }
+            else {
+                schemaRoutes[type].push(operationName);
+            }
+        }
+    }
+    const clientMethods = [];
+    // Utility function for generating generic types for client methods using
+    // module type prefix and omitted types based on operations usage
+    const makeGenericTypes = (moduleTypeName, operations, usedOperations) => {
+        if (noTypes) {
+            return '';
+        }
+        const genericTypes = [];
+        if (moduleTypeName) {
+            genericTypes.push(`${typePrefix}${moduleTypeName}`);
+        }
+        const omittedFields = Object.keys(operations).filter((o) => !usedOperations.includes(o));
+        if (omittedFields.length > 0) {
+            genericTypes.push(`[${omittedFields.map((field) => "'" + field + "'").join(', ')}]`);
+        }
+        return genericTypes.length > 0 ? `<${genericTypes.join(', ')}>` : '';
+    };
+    // Add auth client
+    if (schemaRoutes.auth.length > 0) {
+        const genericTypes = makeGenericTypes(constants_1.AUTH_MODULE_TYPE, constants_1.AUTH_OPERATIONS, schemaRoutes.auth);
+        clientMethods.push({
+            name: 'auth',
+            expression: `this.authClient${genericTypes}('${config.routePrefixes.auth}')`
+        });
+    }
+    // Add account client
+    if (schemaRoutes.account.length > 0) {
+        const genericTypes = makeGenericTypes(constants_1.ACCOUNT_MODULE_TYPE, constants_1.ACCOUNT_OPERATIONS, schemaRoutes.account);
+        clientMethods.push({
+            name: 'account',
+            expression: `this.accountClient${genericTypes}('${config.routePrefixes.account}')`
+        });
+    }
+    // Add health client
+    if (schemaRoutes.health.length > 0) {
+        const genericTypes = makeGenericTypes(constants_1.HEALTH_MODULE_TYPE, constants_1.HEALTH_OPERATIONS, schemaRoutes.health);
+        clientMethods.push({
+            name: 'health',
+            expression: `this.healthClient${genericTypes}('${config.routePrefixes.health}')`
+        });
+    }
+    // Add file client
+    if (schemaRoutes.files.length > 0) {
+        const genericTypes = makeGenericTypes(undefined, constants_1.FILE_OPERATIONS, schemaRoutes.files);
+        clientMethods.push({
+            name: 'files',
+            expression: `this.filesClient${genericTypes}('${config.routePrefixes.files}')`
+        });
+    }
+    // Add resource clients
+    for (const [name, operations] of Object.entries(schemaRoutes.resource)) {
+        const basePath = config.resourcePaths.find((p) => p.name === name)?.basePath;
+        if (!basePath) {
+            continue;
+        }
+        const lowerName = name.charAt(0).toLowerCase() + name.slice(1);
+        const resourcePath = `${config.routePrefixes.api}${basePath}`;
+        const genericTypes = makeGenericTypes(`${name}${constants_1.RESOURCE_MODULE_TYPE}`, constants_1.RESOURCE_OPERATIONS, operations);
+        clientMethods.push({
+            name: lowerName,
+            expression: `this.resourceClient${genericTypes}('${resourcePath}')`
+        });
+    }
+    // Add custom requests
+    for (const customRoute of schemaRoutes.custom) {
+        const { method, path, operationName } = customRoute;
+        clientMethods.push({
+            name: operationName,
+            expression: `this.customRequest('${method}', '${path}')`
+        });
+    }
+    // Combine and resolve all client methods
+    let clientMethodContent = '';
+    const usedMethodNames = new Set(Object.getOwnPropertyNames(clients_1.FetchClient.prototype));
+    for (const { name, expression } of clientMethods) {
+        // Uppercase the method name if it conflicts with existing class properties
+        const propName = usedMethodNames.has(name)
+            ? name.charAt(0).toUpperCase() + name.slice(1)
+            : name;
+        clientMethodContent += `public ${propName} = ${expression};\n\n`;
+        usedMethodNames.add(propName);
+    }
+    // Generate framework-specific client code
+    return framework === 'angular'
+        ? generateAngularClient(pathsTypeImport, pathsTypeGeneric, className, clientMethodContent)
+        : generateFetchClient(pathsTypeImport, pathsTypeGeneric, className, clientMethodContent);
+}
+function generateFetchClient(pathsTypeImport, pathsTypeGeneric, className, clientMethodContent) {
+    return `import { ClientConfig, ClientError, FetchClient } from '@appweaver/client';
+${pathsTypeImport}
+export class ${className} extends FetchClient${pathsTypeGeneric} {
+  ${clientMethodContent}
+}
+
+export function createClient(config: ClientConfig): ${className} {
+  return new ${className}(config);
+}
+
+export { ClientError };
+`;
+}
+function generateAngularClient(pathsTypeImport, pathsTypeGeneric, className, clientMethodContent) {
+    return `import { ClientConfig, ClientError, AngularClient } from '@appweaver/client';
+import { HttpClient, HttpHeaders, HttpResponse } from '@angular/common/http';
+import { firstValueFrom } from 'rxjs';
+${pathsTypeImport}
+export class ${className} extends AngularClient${pathsTypeGeneric} {
+  constructor(http: HttpClient, config: ClientConfig) {
+    super(${className}.fetchHandler(http), config);
+  }
+
+  ${clientMethodContent}
+  
+  private static fetchHandler(http: HttpClient) {
+    return async (
+      input: RequestInfo | URL,
+      init?: RequestInit
+    ): Promise<Response> => {
+      const request = input instanceof Request ? input : null;
+
+      const url = request
+        ? request.url
+        : input instanceof URL
+          ? input.toString()
+          : input;
+
+      const method = init?.method ?? request?.method ?? 'GET';
+
+      const headers = new HttpHeaders(
+        Object.fromEntries(
+          new Headers(init?.headers ?? request?.headers ?? {}).entries()
+        )
+      );
+
+      const body =
+        method === 'GET' || method === 'HEAD'
+          ? undefined
+          : (init?.body ?? request?.body ?? undefined);
+
+      let parsedBody: any;
+      if (body) {
+        if (headers.get('Content-Type')?.includes('multipart')) {
+          parsedBody = await new Response(body).blob();
+        } else {
+          try {
+            parsedBody = JSON.parse(await new Response(body).text());
+          } catch (e) {
+            parsedBody = body;
+          }
+        }
+      }
+
+      const angularResponse: HttpResponse<Blob> = await firstValueFrom(
+        http.request(method, url as string, {
+          body: parsedBody,
+          headers: headers,
+          observe: 'response',
+          responseType: 'blob',
+          withCredentials: init?.credentials === 'include'
+        })
+      );
+
+      const responseHeaders = new Headers();
+
+      angularResponse.headers.keys().forEach((key: string) => {
+        const value = angularResponse.headers.get(key);
+        if (value !== null) {
+          responseHeaders.set(key, value);
+        }
+      });
+
+      return new Response(angularResponse.body, {
+        status: angularResponse.status,
+        statusText: angularResponse.statusText,
+        headers: responseHeaders
+      });
+    };
+  }
+}
+
+export { ClientError };
+`;
+}
+/**
+ * Retrieves the details for a specific route based on the provided path, HTTP method, and configuration.
+ *
+ * @param {string} path - The URL path for which route details are determined.
+ * @param {HttpMethod} method - The HTTP method associated with the route (e.g., GET, POST).
+ * @param {OperationObject} operation - The operation object containing metadata related to the route.
+ * @param {RoutePathConfig} config - The schema configuration object containing route prefixes and resource paths.
+ * @return {RouteDetails} An object representing the type of route, optionally including the operation name and
+ * resource name if applicable.
+ */
+function routeDetails(path, method, operation, config) {
+    try {
+        const prefixChecks = [
+            ['auth', config.routePrefixes.auth, constants_1.AUTH_OPERATIONS],
+            ['account', config.routePrefixes.account, constants_1.ACCOUNT_OPERATIONS],
+            ['health', config.routePrefixes.health, constants_1.HEALTH_OPERATIONS],
+            ['files', config.routePrefixes.files, constants_1.FILE_OPERATIONS]
+        ];
+        // Try to detect predefined module-specific routes
+        for (const [routeType, prefix, operations] of prefixChecks) {
+            const operationName = routeOperation(path, method, prefix, operations);
+            if (operationName) {
+                return { type: routeType, operationName };
+            }
+        }
+        // Try to detect resource routes using resource name and route prefix
+        const resourceName = operation[constants_1.CONFIG_RESOURCE_FIELD];
+        const resourcePath = config.resourcePaths.find((rp) => rp.name === resourceName)?.basePath;
+        const resourcePathPrefix = `${config.routePrefixes.api}${resourcePath}`;
+        if (resourceName && resourcePath && path.startsWith(resourcePathPrefix)) {
+            const pathSuffix = path.replace(resourcePathPrefix, '');
+            const operationName = resourceOperation(pathSuffix, method);
+            if (operationName) {
+                return { type: 'resource', resourceName, operationName };
+            }
+        }
+    }
+    catch {
+        // If schema config is invalid or missing, default to custom route type
+        return {
+            type: 'custom',
+            operationName: createOperationName(path, method, config)
+        };
+    }
+    return {
+        type: 'custom',
+        operationName: createOperationName(path, method, config)
+    };
+}
+/**
+ * Generates an operation name based on the provided API path, HTTP method, and schema configuration.
+ *
+ * @param {string} path - The API path for which the operation name is being generated.
+ * @param {HttpMethod} method - The HTTP method (e.g., GET, POST, PUT) associated with the operation.
+ * @param {RoutePathConfig} config - The configuration object containing schema details, including route prefixes.
+ * @return {string} A generated string representing the operation name.
+ */
+function createOperationName(path, method, config) {
+    if (path.replace(config.routePrefixes.api, '').replace('/', '') === '') {
+        return 'info';
+    }
+    const capitalize = (str) => {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    };
+    const parts = path.split('/');
+    const camelCasePath = parts
+        .filter((part) => part.length > 0)
+        .map((part, index) => {
+        if (part.startsWith('{') && part.endsWith('}')) {
+            const nextPart = parts[index + 1];
+            const partSlice = part.slice(1, -1).replace('*', 'Any');
+            if (nextPart && nextPart.length > 0) {
+                return 'By' + capitalize(partSlice);
+            }
+            return 'By' + capitalize(partSlice);
+        }
+        return capitalize(part);
+    })
+        .join('')
+        .replace(/-[a-z0-9]/g, (match) => match.replace('-', '').toUpperCase())
+        .replace(/^By(.*)/g, 'by$1');
+    return `${method}${camelCasePath}`;
+}
+/**
+ * Finds a route operation based on the given path, method, prefix, and operations mappings.
+ *
+ * @param {string} path - The request path to be matched against the operations.
+ * @param {HttpMethod} method - The HTTP method to be matched (e.g., GET, POST).
+ * @param {string} prefix - The prefix to be removed from the path before processing.
+ * @param {Record<string, HttpMethod>} operations - A record mapping operation names to their corresponding HTTP methods.
+ * @return {string | undefined} The matching operation name, or `undefined` if no match is found.
+ */
+function routeOperation(path, method, prefix, operations) {
+    if (!path.startsWith(prefix)) {
+        return undefined;
+    }
+    const normalizedRoute = path
+        .replace(prefix, '')
+        .replace(/^\//, '')
+        .replace(/\/\{[\w*]+}$/, '')
+        .replace(/-/g, '')
+        .toLowerCase();
+    return Object.entries(operations).find(([operation, operationMethod]) => normalizedRoute === operation.toLowerCase() && method === operationMethod)?.[0];
+}
+/**
+ * Determines the resource operation based on the provided path suffix and HTTP method.
+ *
+ * @param {string} pathSuffix - The suffix of the path used to identify a specific resource operation.
+ * @param {HttpMethod} method - The HTTP method (e.g., GET, POST, PUT, DELETE) corresponding to the operation.
+ * @return {string | undefined} - The matching resource operation key, or undefined if no
+ * match is found.
+ */
+function resourceOperation(pathSuffix, method) {
+    const operationMap = {
+        get: {
+            '{id}': 'find'
+        },
+        post: {
+            query: 'query',
+            aggregate: 'aggregate',
+            '': 'create',
+            export: 'export',
+            '{id}/files': 'uploadFiles',
+            '{id}/delete-files': 'deleteFiles'
+        },
+        put: {
+            '{id}': 'update'
+        },
+        delete: {
+            '{id}': 'delete'
+        }
+    };
+    return operationMap[method]?.[pathSuffix.replace(/^\//, '')];
+}

package/generators/generate-types.d.ts

@@ -0,0 +1,9 @@
+import { OpenAPI3 } from 'openapi-typescript';
+/**
+ * Generates TypeScript types based on an OpenAPI V3 schema content.
+ *
+ * @param {string | OpenAPI3} schema - The OpenAPI V3 schema to generate types from. The value can be a string
+ * representing JSON or YAML format, or already parsed OpenAPI3 object.
+ * @return {Promise<string>} A promise that resolves to a string containing the generated TypeScript types.
+ */
+export declare function generateTypes(schema: string | OpenAPI3): Promise<string>;