aios-core 3.6.0 → 3.7.0

package/.aios-core/development/templates/service-template/errors.ts.hbs

@@ -0,0 +1,182 @@
+/**
+ * Error definitions for {{pascalCase serviceName}} service.
+ * @module @aios/{{kebabCase serviceName}}/errors
+ * @story {{storyId}}
+ */
+
+/**
+ * Error codes for {{pascalCase serviceName}} service.
+ */
+export enum {{pascalCase serviceName}}ErrorCode {
+  /** Configuration is missing or invalid */
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
+
+  /** Network or connectivity issue */
+  NETWORK_ERROR = 'NETWORK_ERROR',
+
+  /** Operation timed out */
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+
+  /** Feature not yet implemented */
+  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
+
+  /** Unknown or unexpected error */
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+
+{{#if isApiIntegration}}
+  /** API rate limit exceeded */
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+
+  /** API authentication failed */
+  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
+
+  /** API authorization failed */
+  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
+
+  /** API returned an error response */
+  API_ERROR = 'API_ERROR',
+
+  /** Invalid API response format */
+  INVALID_RESPONSE = 'INVALID_RESPONSE',
+{{/if}}
+}
+
+/**
+ * Custom error class for {{pascalCase serviceName}} service.
+ */
+export class {{pascalCase serviceName}}Error extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  public readonly code: {{pascalCase serviceName}}ErrorCode;
+
+  /**
+   * Additional error details.
+   */
+  public readonly details?: Record<string, unknown>;
+
+  /**
+   * Original error that caused this error.
+   */
+  public readonly cause?: Error;
+
+{{#if isApiIntegration}}
+  /**
+   * HTTP status code (for API errors).
+   */
+  public readonly statusCode?: number;
+
+  /**
+   * Rate limit information (for rate limit errors).
+   */
+  public readonly rateLimit?: {
+    remaining: number;
+    reset: number;
+  };
+{{/if}}
+
+  constructor(
+    message: string,
+    code: {{pascalCase serviceName}}ErrorCode = {{pascalCase serviceName}}ErrorCode.UNKNOWN_ERROR,
+    options?: {
+      details?: Record<string, unknown>;
+      cause?: Error;
+{{#if isApiIntegration}}
+      statusCode?: number;
+      rateLimit?: { remaining: number; reset: number };
+{{/if}}
+    }
+  ) {
+    super(message);
+    this.name = '{{pascalCase serviceName}}Error';
+    this.code = code;
+    this.details = options?.details;
+    this.cause = options?.cause;
+{{#if isApiIntegration}}
+    this.statusCode = options?.statusCode;
+    this.rateLimit = options?.rateLimit;
+{{/if}}
+
+    // Maintains proper stack trace for where error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, {{pascalCase serviceName}}Error);
+    }
+  }
+
+  /**
+   * Returns a JSON representation of the error.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      cause: this.cause ? { name: this.cause.name, message: this.cause.message } : undefined,
+{{#if isApiIntegration}}
+      statusCode: this.statusCode,
+      rateLimit: this.rateLimit,
+{{/if}}
+    };
+  }
+}
+
+/**
+ * Factory functions for creating typed errors.
+ */
+export const {{pascalCase serviceName}}Errors = {
+  /**
+   * Create a configuration error.
+   */
+  configurationError(message: string, details?: Record<string, unknown>): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR, { details });
+  },
+
+  /**
+   * Create a network error.
+   */
+  networkError(message: string, cause?: Error): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.NETWORK_ERROR, { cause });
+  },
+
+  /**
+   * Create a timeout error.
+   */
+  timeoutError(message: string, details?: Record<string, unknown>): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.TIMEOUT_ERROR, { details });
+  },
+
+{{#if isApiIntegration}}
+  /**
+   * Create a rate limit error.
+   */
+  rateLimitError(retryAfter: number, rateLimit: { remaining: number; reset: number }): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(
+      `Rate limit exceeded. Retry after ${retryAfter} seconds.`,
+      {{pascalCase serviceName}}ErrorCode.RATE_LIMIT_EXCEEDED,
+      { statusCode: 429, rateLimit }
+    );
+  },
+
+  /**
+   * Create an authentication error.
+   */
+  authenticationError(message: string = 'Authentication failed'): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.AUTHENTICATION_ERROR, { statusCode: 401 });
+  },
+
+  /**
+   * Create an authorization error.
+   */
+  authorizationError(message: string = 'Access denied'): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.AUTHORIZATION_ERROR, { statusCode: 403 });
+  },
+
+  /**
+   * Create an API error from response.
+   */
+  apiError(statusCode: number, message: string, details?: Record<string, unknown>): {{pascalCase serviceName}}Error {
+    return new {{pascalCase serviceName}}Error(message, {{pascalCase serviceName}}ErrorCode.API_ERROR, { statusCode, details });
+  },
+{{/if}}
+};

package/.aios-core/development/templates/service-template/index.ts.hbs

@@ -0,0 +1,120 @@
+/**
+ * @module @aios/{{kebabCase serviceName}}
+ * @description {{description}}
+ * @story {{storyId}}
+ */
+
+// Re-export types
+export * from './types';
+
+// Re-export errors
+export * from './errors';
+
+{{#if isApiIntegration}}
+// Re-export client (API integrations only)
+export { {{pascalCase serviceName}}Client } from './client';
+{{/if}}
+
+import type { {{pascalCase serviceName}}Config, {{pascalCase serviceName}}Service } from './types';
+import { {{pascalCase serviceName}}Error, {{pascalCase serviceName}}ErrorCode } from './errors';
+{{#if isApiIntegration}}
+import { {{pascalCase serviceName}}Client } from './client';
+{{/if}}
+
+/**
+ * Creates a new {{pascalCase serviceName}} service instance.
+ *
+ * @param config - Service configuration
+ * @returns Configured service instance
+ * @throws {{{pascalCase serviceName}}Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const service = create{{pascalCase serviceName}}Service({
+ *   // configuration options
+ * });
+ *
+ * const result = await service.execute();
+ * ```
+ */
+export function create{{pascalCase serviceName}}Service(
+  config: {{pascalCase serviceName}}Config
+): {{pascalCase serviceName}}Service {
+  // Validate configuration
+  validateConfig(config);
+
+{{#if isApiIntegration}}
+  // Create API client
+  const client = new {{pascalCase serviceName}}Client(config);
+
+{{/if}}
+  return {
+    /**
+     * Execute the primary service operation.
+     */
+    async execute(): Promise<void> {
+      // TODO: Implement primary operation
+      throw new {{pascalCase serviceName}}Error(
+        'Not implemented',
+        {{pascalCase serviceName}}ErrorCode.NOT_IMPLEMENTED
+      );
+    },
+
+    /**
+     * Get the current configuration (without sensitive values).
+     */
+    getConfig(): Partial<{{pascalCase serviceName}}Config> {
+      return {
+        // Return non-sensitive config values
+{{#each envVars}}
+{{#unless this.sensitive}}
+        {{camelCase this.name}}: config.{{camelCase this.name}},
+{{/unless}}
+{{/each}}
+      };
+    },
+
+    /**
+     * Check if the service is properly configured and operational.
+     */
+    async healthCheck(): Promise<boolean> {
+      try {
+{{#if isApiIntegration}}
+        // Verify API connectivity
+        await client.ping();
+{{/if}}
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Validates the service configuration.
+ * @throws {{{pascalCase serviceName}}Error} If configuration is invalid
+ */
+function validateConfig(config: {{pascalCase serviceName}}Config): void {
+  if (!config) {
+    throw new {{pascalCase serviceName}}Error(
+      'Configuration is required',
+      {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR
+    );
+  }
+
+{{#each envVars}}
+{{#if this.required}}
+  if (config.{{camelCase this.name}} === undefined || config.{{camelCase this.name}} === null) {
+    throw new {{pascalCase serviceName}}Error(
+      '{{this.name}} is required',
+      {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR
+    );
+  }
+
+{{/if}}
+{{/each}}
+}
+
+// Default export
+export default create{{pascalCase serviceName}}Service;

package/.aios-core/development/templates/service-template/jest.config.js

@@ -0,0 +1,89 @@
+/**
+ * Jest configuration for service testing.
+ * @type {import('jest').Config}
+ */
+module.exports = {
+  // Use ts-jest for TypeScript support
+  preset: 'ts-jest',
+
+  // Test environment
+  testEnvironment: 'node',
+
+  // Root directories for tests
+  roots: ['<rootDir>'],
+
+  // Test file patterns
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/__tests__/**/*.spec.ts',
+  ],
+
+  // TypeScript transformation
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: {
+          module: 'ESNext',
+          moduleResolution: 'NodeNext',
+        },
+      },
+    ],
+  },
+
+  // Module file extensions
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+
+  // Coverage configuration
+  collectCoverageFrom: [
+    '**/*.ts',
+    '!**/*.d.ts',
+    '!**/__tests__/**',
+    '!**/node_modules/**',
+    '!**/dist/**',
+  ],
+
+  // Coverage thresholds (targeting >70%)
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70,
+    },
+  },
+
+  // Coverage reporters
+  coverageReporters: ['text', 'text-summary', 'lcov', 'html'],
+
+  // Coverage output directory
+  coverageDirectory: 'coverage',
+
+  // Clear mocks between tests
+  clearMocks: true,
+
+  // Verbose output
+  verbose: true,
+
+  // Test timeout (30 seconds)
+  testTimeout: 30000,
+
+  // Setup files
+  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+
+  // Module name mapper for path aliases
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+  },
+
+  // Ignore patterns
+  testPathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/',
+  ],
+
+  // Global setup/teardown
+  // globalSetup: '<rootDir>/jest.global-setup.ts',
+  // globalTeardown: '<rootDir>/jest.global-teardown.ts',
+};

package/.aios-core/development/templates/service-template/package.json.hbs

@@ -0,0 +1,87 @@
+{
+  "name": "@aios/{{kebabCase serviceName}}",
+  "version": "1.0.0",
+  "description": "{{description}}",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    }{{#if isApiIntegration}},
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }{{/if}}
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "aios",
+    "{{kebabCase serviceName}}",
+    "service"{{#if isApiIntegration}},
+    "api",
+    "integration"{{/if}}
+  ],
+  "author": "AIOS-FullStack",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aios-fullstack/{{kebabCase serviceName}}.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aios-fullstack/{{kebabCase serviceName}}/issues"
+  },
+  "homepage": "https://github.com/aios-fullstack/{{kebabCase serviceName}}#readme",
+  "aios": {
+    "storyId": "{{storyId}}",
+    "type": "{{#if isApiIntegration}}api-integration{{else}}utility-service{{/if}}",
+    "generatedAt": "{{generatedAt}}"
+  }
+}

package/.aios-core/development/templates/service-template/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": [
+    "./**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "__tests__"
+  ]
+}

package/.aios-core/development/templates/service-template/types.ts.hbs

@@ -0,0 +1,145 @@
+/**
+ * Type definitions for {{pascalCase serviceName}} service.
+ * @module @aios/{{kebabCase serviceName}}/types
+ * @story {{storyId}}
+ */
+
+/**
+ * Configuration options for the {{pascalCase serviceName}} service.
+ */
+export interface {{pascalCase serviceName}}Config {
+{{#each envVars}}
+  /**
+   * {{this.description}}
+   {{#if this.required}}
+   * @required
+   {{/if}}
+   */
+  {{camelCase this.name}}{{#unless this.required}}?{{/unless}}: string;
+
+{{/each}}
+{{#if isApiIntegration}}
+  /**
+   * Base URL for the API.
+   * @default '{{apiBaseUrl}}'
+   */
+  baseUrl?: string;
+
+  /**
+   * Request timeout in milliseconds.
+   * @default 30000
+   */
+  timeout?: number;
+
+  /**
+   * Maximum number of retry attempts.
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Enable debug logging.
+   * @default false
+   */
+  debug?: boolean;
+
+{{/if}}
+}
+
+/**
+ * The {{pascalCase serviceName}} service interface.
+ */
+export interface {{pascalCase serviceName}}Service {
+  /**
+   * Execute the primary service operation.
+   */
+  execute(): Promise<void>;
+
+  /**
+   * Get the current configuration (without sensitive values).
+   */
+  getConfig(): Partial<{{pascalCase serviceName}}Config>;
+
+  /**
+   * Check if the service is properly configured and operational.
+   */
+  healthCheck(): Promise<boolean>;
+}
+
+{{#if isApiIntegration}}
+/**
+ * Base API response structure.
+ */
+export interface {{pascalCase serviceName}}ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+  meta?: {
+    requestId?: string;
+    rateLimit?: {
+      remaining: number;
+      reset: number;
+    };
+  };
+}
+
+/**
+ * Request options for API calls.
+ */
+export interface {{pascalCase serviceName}}RequestOptions {
+  /**
+   * HTTP method.
+   */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+  /**
+   * Request headers.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Request body.
+   */
+  body?: unknown;
+
+  /**
+   * Query parameters.
+   */
+  params?: Record<string, string | number | boolean>;
+
+  /**
+   * Request timeout override.
+   */
+  timeout?: number;
+
+  /**
+   * Skip retry on failure.
+   */
+  noRetry?: boolean;
+}
+
+/**
+ * Rate limit information.
+ */
+export interface {{pascalCase serviceName}}RateLimit {
+  /**
+   * Maximum requests allowed.
+   */
+  limit: number;
+
+  /**
+   * Remaining requests in current window.
+   */
+  remaining: number;
+
+  /**
+   * Unix timestamp when the rate limit resets.
+   */
+  reset: number;
+}
+
+{{/if}}