# {{pascalCase serviceName}} Service

> {{description}}

## Installation

```bash
npm install @aiox/{{kebabCase serviceName}}
```

## Quick Start

```typescript
import { create{{pascalCase serviceName}}Service } from '@aiox/{{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 '@aiox/{{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 '@aiox/{{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 AIOX-FullStack Service Template*
*Story: {{storyId}}*