aios-core 3.6.0 → 3.8.0

package/.aios-core/development/templates/service-template/README.md.hbs

@@ -0,0 +1,158 @@
+# {{pascalCase serviceName}} Service
+
+> {{description}}
+
+## Installation
+
+```bash
+npm install @aios/{{kebabCase serviceName}}
+```
+
+## Quick Start
+
+```typescript
+import { create{{pascalCase serviceName}}Service } from '@aios/{{kebabCase serviceName}}';
+
+const service = create{{pascalCase serviceName}}Service({
+{{#each envVars}}
+  {{camelCase this.name}}: process.env.{{this.name}},
+{{/each}}
+});
+
+// Use the service
+const result = await service.execute();
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+{{#each envVars}}
+| `{{this.name}}` | {{#if this.required}}Yes{{else}}No{{/if}} | {{this.description}} |
+{{/each}}
+
+### Programmatic Configuration
+
+```typescript
+import { create{{pascalCase serviceName}}Service, {{pascalCase serviceName}}Config } from '@aios/{{kebabCase serviceName}}';
+
+const config: {{pascalCase serviceName}}Config = {
+{{#each envVars}}
+  {{camelCase this.name}}: '{{this.example}}',
+{{/each}}
+};
+
+const service = create{{pascalCase serviceName}}Service(config);
+```
+
+{{#if isApiIntegration}}
+## API Integration
+
+This service integrates with an external API. Features include:
+
+- **Rate Limiting**: Automatic request throttling
+- **Retry Logic**: Exponential backoff on failures
+- **Error Handling**: Typed errors with actionable messages
+
+### Rate Limits
+
+> **Note:** The values below are placeholders. Update them according to your API's actual rate limits.
+
+| Tier | Requests/min | Burst |
+|------|--------------|-------|
+| Free | 60 | 10 |
+| Pro | 600 | 100 |
+
+{{/if}}
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+const service = create{{pascalCase serviceName}}Service(config);
+
+try {
+  const result = await service.execute();
+  console.log('Success:', result);
+} catch (error) {
+  if (error instanceof {{pascalCase serviceName}}Error) {
+    console.error('Service error:', error.code, error.message);
+  }
+  throw error;
+}
+```
+
+{{#if hasAuth}}
+### Authentication
+
+This service requires authentication. Set your credentials via environment variables or config:
+
+```typescript
+const service = create{{pascalCase serviceName}}Service({
+  apiKey: process.env.{{upperCase serviceName}}_API_KEY,
+  // or
+  accessToken: process.env.{{upperCase serviceName}}_ACCESS_TOKEN,
+});
+```
+
+{{/if}}
+## Error Handling
+
+The service provides typed errors for common failure scenarios:
+
+```typescript
+import { {{pascalCase serviceName}}Error, {{pascalCase serviceName}}ErrorCode } from '@aios/{{kebabCase serviceName}}';
+
+try {
+  await service.execute();
+} catch (error) {
+  if (error instanceof {{pascalCase serviceName}}Error) {
+    switch (error.code) {
+      case {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR:
+        // Handle configuration issues
+        break;
+      case {{pascalCase serviceName}}ErrorCode.NETWORK_ERROR:
+        // Handle network issues
+        break;
+{{#if isApiIntegration}}
+      case {{pascalCase serviceName}}ErrorCode.RATE_LIMIT_EXCEEDED:
+        // Handle rate limiting
+        break;
+{{/if}}
+      default:
+        // Handle other errors
+    }
+  }
+}
+```
+
+## API Reference
+
+See the [TypeScript definitions](./dist/types.d.ts) for complete API documentation.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT
+
+---
+
+*Generated by AIOS-FullStack Service Template*
+*Story: {{storyId}}*

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

@@ -0,0 +1,237 @@
+/**
+ * Tests for {{pascalCase serviceName}} service.
+ * @module @aios/{{kebabCase serviceName}}/tests
+ * @story {{storyId}}
+ */
+
+import {
+  create{{pascalCase serviceName}}Service,
+  {{pascalCase serviceName}}Error,
+  {{pascalCase serviceName}}ErrorCode,
+} from '../index';
+import type { {{pascalCase serviceName}}Config, {{pascalCase serviceName}}Service } from '../types';
+
+describe('{{pascalCase serviceName}}Service', () => {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Test Configuration
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  const validConfig: {{pascalCase serviceName}}Config = {
+{{#each envVars}}
+    {{camelCase this.name}}: 'test-{{kebabCase this.name}}',
+{{/each}}
+  };
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Factory Function Tests
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe('create{{pascalCase serviceName}}Service', () => {
+    it('should create a service instance with valid config', () => {
+      const service = create{{pascalCase serviceName}}Service(validConfig);
+
+      expect(service).toBeDefined();
+      expect(typeof service.execute).toBe('function');
+      expect(typeof service.getConfig).toBe('function');
+      expect(typeof service.healthCheck).toBe('function');
+    });
+
+    it('should throw on null config', () => {
+      expect(() => {
+        create{{pascalCase serviceName}}Service(null as unknown as {{pascalCase serviceName}}Config);
+      }).toThrow({{pascalCase serviceName}}Error);
+    });
+
+    it('should throw on undefined config', () => {
+      expect(() => {
+        create{{pascalCase serviceName}}Service(undefined as unknown as {{pascalCase serviceName}}Config);
+      }).toThrow({{pascalCase serviceName}}Error);
+    });
+
+{{#each envVars}}
+{{#if this.required}}
+    it('should throw when {{this.name}} is missing', () => {
+      const configWithoutField = { ...validConfig };
+      delete (configWithoutField as Record<string, unknown>).{{camelCase this.name}};
+
+      expect(() => {
+        create{{pascalCase serviceName}}Service(configWithoutField as {{pascalCase serviceName}}Config);
+      }).toThrow(expect.objectContaining({
+        code: {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR,
+      }));
+    });
+
+{{/if}}
+{{/each}}
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Configuration Tests
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe('getConfig', () => {
+    let service: {{pascalCase serviceName}}Service;
+
+    beforeEach(() => {
+      service = create{{pascalCase serviceName}}Service(validConfig);
+    });
+
+    it('should return configuration without sensitive values', () => {
+      const config = service.getConfig();
+
+      expect(config).toBeDefined();
+      expect(typeof config).toBe('object');
+    });
+
+    it('should not expose sensitive configuration', () => {
+      const config = service.getConfig();
+
+      // Verify sensitive fields are not exposed
+{{#each envVars}}
+{{#if this.sensitive}}
+      expect(config.{{camelCase this.name}}).toBeUndefined();
+{{/if}}
+{{/each}}
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Service Method Tests
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe('execute', () => {
+    let service: {{pascalCase serviceName}}Service;
+
+    beforeEach(() => {
+      service = create{{pascalCase serviceName}}Service(validConfig);
+    });
+
+    it('should throw NOT_IMPLEMENTED for unimplemented execute', async () => {
+      await expect(service.execute()).rejects.toThrow(expect.objectContaining({
+        code: {{pascalCase serviceName}}ErrorCode.NOT_IMPLEMENTED,
+      }));
+    });
+  });
+
+  describe('healthCheck', () => {
+    let service: {{pascalCase serviceName}}Service;
+
+    beforeEach(() => {
+      service = create{{pascalCase serviceName}}Service(validConfig);
+    });
+
+    it('should return boolean', async () => {
+      const result = await service.healthCheck();
+
+      expect(typeof result).toBe('boolean');
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Error Handling Tests
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe('{{pascalCase serviceName}}Error', () => {
+    it('should have correct name', () => {
+      const error = new {{pascalCase serviceName}}Error('Test error');
+
+      expect(error.name).toBe('{{pascalCase serviceName}}Error');
+    });
+
+    it('should have default error code', () => {
+      const error = new {{pascalCase serviceName}}Error('Test error');
+
+      expect(error.code).toBe({{pascalCase serviceName}}ErrorCode.UNKNOWN_ERROR);
+    });
+
+    it('should accept custom error code', () => {
+      const error = new {{pascalCase serviceName}}Error(
+        'Config error',
+        {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR
+      );
+
+      expect(error.code).toBe({{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR);
+    });
+
+    it('should include error details', () => {
+      const details = { field: 'test', reason: 'invalid' };
+      const error = new {{pascalCase serviceName}}Error(
+        'Validation error',
+        {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR,
+        { details }
+      );
+
+      expect(error.details).toEqual(details);
+    });
+
+    it('should preserve cause error', () => {
+      const cause = new Error('Original error');
+      const error = new {{pascalCase serviceName}}Error(
+        'Wrapped error',
+        {{pascalCase serviceName}}ErrorCode.NETWORK_ERROR,
+        { cause }
+      );
+
+      expect(error.cause).toBe(cause);
+    });
+
+    it('should serialize to JSON correctly', () => {
+      const error = new {{pascalCase serviceName}}Error(
+        'Test error',
+        {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR,
+        { details: { key: 'value' } }
+      );
+
+      const json = error.toJSON();
+
+      expect(json.name).toBe('{{pascalCase serviceName}}Error');
+      expect(json.code).toBe({{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR);
+      expect(json.message).toBe('Test error');
+      expect(json.details).toEqual({ key: 'value' });
+    });
+  });
+});
+
+{{#if isApiIntegration}}
+// ─────────────────────────────────────────────────────────────────────────────
+// API Client Tests (API Integrations Only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('{{pascalCase serviceName}}Client', () => {
+  // Import client for API integration testing
+  const { {{pascalCase serviceName}}Client } = require('../client');
+
+  const clientConfig: {{pascalCase serviceName}}Config = {
+    ...validConfig,
+    baseUrl: 'https://api.example.com',
+    timeout: 5000,
+    maxRetries: 2,
+    debug: false,
+  };
+
+  describe('constructor', () => {
+    it('should create client with config', () => {
+      const client = new {{pascalCase serviceName}}Client(clientConfig);
+
+      expect(client).toBeDefined();
+    });
+
+    it('should use default values for optional config', () => {
+      const client = new {{pascalCase serviceName}}Client(validConfig);
+
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe('getRateLimit', () => {
+    it('should return null initially', () => {
+      const client = new {{pascalCase serviceName}}Client(clientConfig);
+
+      expect(client.getRateLimit()).toBeNull();
+    });
+  });
+
+  // Note: Additional client tests require mocking fetch/network
+  // These should be added based on specific API requirements
+});
+{{/if}}