Initial commit

skills/documentation/templates/interface-template.md

@@ -0,0 +1,255 @@
+# [Service Name] Integration
+
+> **Category:** External Interface
+> **Service:** [Service Name]
+> **Last Updated:** [Date]
+> **Status:** [Active/Deprecated/Planned]
+
+## Overview
+
+**Service:** [Full service name]
+**Provider:** [Company/organization]
+**Purpose:** [What this integration accomplishes]
+**Documentation:** [Link to official API docs]
+
+## Authentication
+
+### Method
+
+[OAuth 2.0 / API Key / Basic Auth / JWT / etc.]
+
+### Credentials Management
+
+**Location:** [Where credentials are stored]
+**Environment Variables:**
+```bash
+SERVICE_API_KEY=xxx
+SERVICE_SECRET=xxx
+SERVICE_ENDPOINT=https://...
+```
+
+**Rotation Policy:** [How often credentials change]
+
+### Authentication Example
+
+```[language]
+// Example of authentication setup
+[Code snippet]
+```
+
+## API Endpoints Used
+
+### Endpoint 1: [Name]
+
+**URL:** `[METHOD] /path/to/endpoint`
+**Purpose:** [What this endpoint does]
+
+**Request:**
+```json
+{
+  "field1": "value",
+  "field2": "value"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": { }
+}
+```
+
+**Error Handling:**
+- `400`: [How we handle]
+- `401`: [How we handle]
+- `500`: [How we handle]
+
+### Endpoint 2: [Name]
+
+**URL:** `[METHOD] /path/to/endpoint`
+**Purpose:** [What this endpoint does]
+
+[Same structure as above]
+
+## Webhooks (if applicable)
+
+### Webhook 1: [Event Name]
+
+**Event Type:** `[event.type]`
+**Trigger:** [When this fires]
+**URL:** `[Your webhook endpoint]`
+
+**Payload:**
+```json
+{
+  "event": "type",
+  "data": { }
+}
+```
+
+**Signature Verification:**
+```[language]
+// How to verify webhook authenticity
+[Code snippet]
+```
+
+**Handling:**
+```[language]
+// How we process this webhook
+[Code snippet]
+```
+
+## Rate Limits
+
+- **Requests per second:** [Limit]
+- **Requests per day:** [Limit]
+- **Burst limit:** [Limit]
+
+**Handling Strategy:** [How we respect limits]
+```[language]
+// Rate limiting implementation
+[Code snippet]
+```
+
+## Data Mapping
+
+### Our Model → Service Model
+
+| Our Field | Service Field | Transformation |
+|-----------|---------------|----------------|
+| `userId` | `external_id` | String conversion |
+| `email` | `email_address` | Direct mapping |
+| `amount` | `total_cents` | Multiply by 100 |
+
+### Service Model → Our Model
+
+| Service Field | Our Field | Transformation |
+|---------------|-----------|----------------|
+| `id` | `externalId` | Direct mapping |
+| `status` | `state` | Enum mapping |
+| `created_at` | `createdAt` | ISO 8601 parse |
+
+## Error Handling
+
+### Common Errors
+
+**Error 1: [Name/Code]**
+- **Cause:** [What triggers this]
+- **Recovery:** [How we handle it]
+- **Retry:** [Yes/No, strategy]
+
+**Error 2: [Name/Code]**
+- **Cause:** [What triggers this]
+- **Recovery:** [How we handle it]
+- **Retry:** [Yes/No, strategy]
+
+### Retry Strategy
+
+```[language]
+// Exponential backoff implementation
+[Code snippet]
+```
+
+## Testing
+
+### Test Credentials
+
+**Sandbox URL:** `https://sandbox.service.com`
+**Test API Key:** `[Where to get it]`
+
+### Mock Server
+
+**Location:** `tests/mocks/[service]-mock.ts`
+**Usage:**
+```[language]
+// How to use mock in tests
+[Code snippet]
+```
+
+### Integration Tests
+
+```[language]
+// Example integration test
+[Code snippet]
+```
+
+## Monitoring
+
+### Health Checks
+
+**Endpoint:** `[Service status endpoint]`
+**Frequency:** [How often we check]
+
+### Metrics to Track
+
+- Request success rate
+- Response time (p50, p95, p99)
+- Error rate by type
+- Rate limit proximity
+
+### Alerts
+
+- **Critical:** [Conditions that trigger urgent alerts]
+- **Warning:** [Conditions that trigger warnings]
+
+## Security Considerations
+
+- [Security consideration 1]
+- [Security consideration 2]
+- [Security consideration 3]
+
+## Compliance
+
+**Data Handling:**
+- PII fields: [List]
+- Retention policy: [Duration]
+- Geographic restrictions: [Any]
+
+**Regulations:**
+- GDPR: [Compliance notes]
+- CCPA: [Compliance notes]
+- Other: [Relevant regulations]
+
+## Cost Considerations
+
+**Pricing Model:** [How service charges]
+**Cost per request:** [Estimate]
+**Monthly estimate:** [Based on usage]
+
+## Migration/Upgrade Path
+
+**Current Version:** [Version]
+**Upgrade Available:** [Yes/No, version]
+**Breaking Changes:** [List if applicable]
+
+**Migration Steps:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Related Documentation
+
+- **Patterns:** [Pattern Doc](../patterns/doc.md) - [How we use this service]
+- **Domain:** [Domain Doc](../domain/doc.md) - [Business rules related to this]
+- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Implementation details]
+
+## External Resources
+
+- [Official API documentation]
+- [Status page]
+- [Developer community/forum]
+- [SDK/library used]
+
+## Contact
+
+**Support:** [How to get help]
+**Account Manager:** [If applicable]
+**Escalation:** [Critical issue contact]
+
+## Version History
+
+| Date | Change | Author |
+|------|--------|--------|
+| [Date] | Initial integration | [Name/Tool] |
+| [Date] | Updated to v2 API | [Name/Tool] |