Destination Implementation Generator

This skill generates complete Segment action-destination code from analysis documents and user-selected actions.

Supported Analysis Sources:

• OpenAPI specifications (via /openapi-analyze)
• Website documentation (via /web-analyze)
• Any analysis document following the Standard Analysis Format

All analysis documents must follow the format defined in .claude/skills/implement-destination/analysis-format.md.

Instructions

Step 1: Gather Inputs

Ask the user for the following information:

1. Analysis Document Path - Path to the analysis markdown file (should be in packages/destination-actions/.claude/openapi-analyses/)
2. Destination Name - Human-readable name (e.g., "Acme Marketing", "Braze")
3. Destination Slug - Auto-suggest based on name (e.g., "acme-marketing" from "Acme Marketing")
   • Remove "actions-" prefix if user includes it - this is added automatically to the path
   • Use lowercase, hyphens instead of spaces
4. Selected Actions - Comma-separated list of action names to implement (from the analysis doc)

Step 2: Parse Analysis Document

Read the analysis markdown file and extract:

• API name, version, base URL
• Authentication scheme and required fields
• Test authentication endpoint
• Selected action specifications:
  • Endpoint path and method
  • Operation ID
  • Description
  • Field mappings table
  • Request body schema
  • Batch support
  • Default subscription

Step 3: Create Destination Structure

Create the following directory structure:

packages/destination-actions/src/destinations/[slug]/
├── index.ts                    # Destination definition
├── generated-types.ts          # Placeholder (auto-generated later)
├── [action-1]/
│   ├── index.ts               # Action definition
│   ├── generated-types.ts     # Placeholder
│   └── __tests__/
│       └── index.test.ts      # Basic test
├── [action-2]/
│   └── ... (same structure)
└── __tests__/
    └── index.test.ts          # Destination test

Step 4: Generate Destination index.ts

Read the template at .claude/skills/implement-destination/templates/destination-index.md and customize it with:

• Destination name and slug
• Description from OpenAPI
• Authentication scheme and fields
• Test authentication endpoint (or TODO if not found)
• Import statements for all selected actions
• extendRequest implementation with proper headers
• Regional endpoint handling if applicable

Authentication Scheme Templates:

Custom (API Key in Header):

typescript
1authentication: {
2  scheme: 'custom',
3  fields: {
4    apiKey: {
5      label: 'API Key',
6      description: 'Your [API Name] API key',
7      type: 'password',
8      required: true
9    }
10  },
11  testAuthentication: (request, { settings }) => {
12    return request('[TEST_ENDPOINT]', {
13      method: 'GET'
14    })
15  }
16},
17
18extendRequest({ settings }) {
19  return {
20    headers: {
21      Authorization: `Bearer ${settings.apiKey}`,
22      'Content-Type': 'application/json'
23    }
24  }
25}

Basic Auth:

typescript
1authentication: {
2  scheme: 'basic',
3  fields: {
4    username: {
5      label: 'Username',
6      description: 'Your [API Name] username',
7      type: 'string',
8      required: true
9    },
10    password: {
11      label: 'Password',
12      description: 'Your [API Name] password',
13      type: 'password',
14      required: true
15    }
16  },
17  testAuthentication: (request) => {
18    return request('[TEST_ENDPOINT]', {
19      method: 'GET'
20    })
21  }
22}

OAuth2 Managed:

typescript
1authentication: {
2  scheme: 'oauth-managed',
3  fields: {
4    // No additional fields needed for managed OAuth
5  },
6  testAuthentication: (request) => {
7    return request('[TEST_ENDPOINT]', {
8      method: 'GET'
9    })
10  }
11}

Step 5: Generate Action Files

For each selected action, generate three files:

5.1: Action index.ts

Read the template at .claude/skills/implement-destination/templates/action-index.md and customize with:

• Action title and description
• Default subscription from analysis
• Fields from the field mappings table:
  • Convert each field to an InputField definition
  • Set type, label, description, required
  • Add default path where suggested
  • Handle special types (objects, arrays, datetime)
• Perform function with request to API endpoint
• PerformBatch function if batch is supported

Field Type Conversions:

typescript
1// String field
2fieldName: {
3  label: '[Label]',
4  description: '[Description]',
5  type: 'string',
6  required: [true|false],
7  default: { '@path': '$.path.to.field' }
8}
9
10// Integer/Number field
11fieldName: {
12  label: '[Label]',
13  description: '[Description]',
14  type: 'integer', // or 'number'
15  required: [true|false]
16}
17
18// Boolean field
19fieldName: {
20  label: '[Label]',
21  description: '[Description]',
22  type: 'boolean',
23  required: [true|false],
24  default: false
25}
26
27// Object field
28fieldName: {
29  label: '[Label]',
30  description: '[Description]',
31  type: 'object',
32  required: [true|false],
33  properties: {
34    nestedField: {
35      label: '[Nested Label]',
36      type: 'string'
37    }
38  }
39}
40
41// Array field (multiple values)
42fieldName: {
43  label: '[Label]',
44  description: '[Description]',
45  type: 'string', // or object
46  multiple: true,
47  required: [true|false]
48}
49
50// Datetime field
51fieldName: {
52  label: '[Label]',
53  description: '[Description]',
54  type: 'datetime',
55  required: [true|false],
56  default: { '@path': '$.timestamp' }
57}
58
59// Enum field
60fieldName: {
61  label: '[Label]',
62  description: '[Description]',
63  type: 'string',
64  required: [true|false],
65  choices: [
66    { label: 'Option 1', value: 'option1' },
67    { label: 'Option 2', value: 'option2' }
68  ]
69}

Perform Function Template:

typescript
1perform: (request, { payload, settings }) => {
2  return request('[API_ENDPOINT]', {
3    method: '[POST|PUT|PATCH]',
4    json: {
5      // Map payload fields to API fields
6      [apiField]: payload.[segmentField],
7      // ... more mappings
8    }
9  })
10}

PerformBatch Function Template (if supported):

typescript
1performBatch: (request, { payload, settings }) => {
2  return request('[API_ENDPOINT]', {
3    method: 'POST',
4    json: payload.map(event => ({
5      [apiField]: event.[segmentField],
6      // ... more mappings
7    }))
8  })
9}

5.2: Action generated-types.ts

Create placeholder file:

typescript
1// This file is generated automatically by the CLI
2// Run: ./bin/run generate:types --path packages/destination-actions/src/destinations/[slug]/index.ts
3
4export interface Payload {
5  // Types will be generated from the action definition
6}

5.3: Action Test File

Read the template at .claude/skills/implement-destination/templates/test-template.md and customize with:

• Action name
• Event type (track/identify/group)
• Sample event data
• Field mappings for test
• Assertions

Step 6: Generate Destination-Level Files

6.1: Destination generated-types.ts

typescript
1// This file is generated automatically by the CLI
2// Run: ./bin/run generate:types --path packages/destination-actions/src/destinations/[slug]/index.ts
3
4export interface Settings {
5  // Types will be generated from the destination definition
6}

6.2: Destination Test File

typescript
1import { createTestIntegration } from '@segment/actions-core'
2import Destination from '../index'
3
4const testDestination = createTestIntegration(Destination)
5
6describe('[Destination Name]', () => {
7  describe('testAuthentication', () => {
8    it('should validate authentication inputs', async () => {
9      const authData = { [authField]: 'test_value' }
10      await expect(testDestination.testAuthentication(authData)).resolves.not.toThrowError()
11    })
12  })
13})

Step 7: Generate TypeScript Types

Run the CLI command to generate proper types:

bash
1./bin/run generate:types --path packages/destination-actions/src/destinations/[slug]/index.ts

Step 8: Create Implementation Notes

Generate a markdown file at packages/destination-actions/src/destinations/[slug]/IMPLEMENTATION_NOTES.md:

markdown
1# [Destination Name] Implementation Notes
2
3**Generated:** [date]
4**From OpenAPI Analysis:** [analysis file path]
5
6## Summary
7
8This destination was generated from an OpenAPI specification analysis. The generated code provides ~70-80% of the implementation with clear TODOs for completion.
9
10## Generated Files
11
12- `index.ts` - Destination definition with [auth-type] authentication
13  [For each action:]
14- `[action-name]/index.ts` - [Action description]
15- `[action-name]/__tests__/index.test.ts` - Basic test for [action-name]
16
17## TODO: Required Completions
18
19### 1. Authentication
20
21- [ ] Test `testAuthentication` with real API credentials
22- [ ] Verify `extendRequest` headers are correct for API
23- [ ] Confirm authentication error handling works
24
25### 2. Actions
26
27[For each action:]
28
29- [ ] **[Action Name]:**
30  - [ ] Review field mappings accuracy
31  - [ ] Customize request body transformation if needed
32  - [ ] Add error handling for API-specific errors
33  - [ ] Test with real API (credentials required)
34
35### 3. Testing
36
37- [ ] Add comprehensive unit tests with mock API responses
38- [ ] Test error scenarios (network errors, API errors, validation errors)
39- [ ] Test batch operations (if applicable)
40- [ ] Add integration tests
41
42### 4. Documentation
43
44- [ ] Update field descriptions with user-friendly language
45- [ ] Add examples for complex fields
46- [ ] Document any prerequisites or setup steps
47- [ ] Add troubleshooting notes
48
49## Next Steps
50
511. **Build and verify types:**
52   ```bash
53   ./bin/run generate:types --path packages/destination-actions/src/destinations/[slug]/index.ts
54   yarn build
55   ```

2. Run tests:

   bash
   1yarn test packages/destination-actions/src/destinations/[slug]

3. Fix TypeScript errors (if any)

4. Complete TODO items above

5. Test with real API:

   • Obtain test credentials
   • Configure destination in local development
   • Send test events
   • Verify API receives correct data

6. Code review and polish:

   • Review generated code for any OpenAPI-specific quirks
   • Add any missing edge case handling
   • Ensure error messages are helpful

Known Limitations of Generated Code

• Error handling: Generic errors are thrown - customize for API-specific error codes
• Complex schemas: Nested objects may need manual refinement
• Dynamic fields: Cannot auto-generate dynamic field implementations
• Rate limiting: No automatic rate limit handling - add if needed
• Retries: No retry logic - add if API recommends it

API Documentation

• Base URL: [base URL]
• API Docs: [link if available]
• Support: [support contact if available]

### Step 9: Serve the Destination Locally

After generating the code, run the destination locally so the user can test it immediately:

```bash
./bin/run serve packages/destination-actions/src/destinations/[slug]

This starts a local HTTP server that exposes the destination's actions as endpoints. The user can send test requests directly to verify the destination behaves as expected before completing the TODO items.

If the serve command fails (e.g., due to TypeScript errors), inform the user and suggest running yarn build first to surface compilation errors.

Step 10: Present Results

Show the user a summary:

✓ Created destination: [Destination Name]
✓ Location: packages/destination-actions/src/destinations/[slug]/
✓ Generated [N] actions:
  - [action-1]: [one-line description]
  - [action-2]: [one-line description]
✓ Generated TypeScript type definitions
✓ Created test files
✓ Created IMPLEMENTATION_NOTES.md
✓ Destination server started

The destination is now running locally. Send test requests to verify behavior.

Next steps:
1. Review generated code in packages/destination-actions/src/destinations/[slug]/
2. Complete TODOs in IMPLEMENTATION_NOTES.md
3. Run: yarn test packages/destination-actions/src/destinations/[slug]
4. Test with real API credentials
5. To restart the server: ./bin/run serve packages/destination-actions/src/destinations/[slug]

Tips

• Always generate well-formatted, idiomatic TypeScript
• Follow existing destination patterns in the codebase
• Use proper imports from '@segment/actions-core'
• Leave clear TODO comments for manual work
• Ensure all files have proper error handling imports even if not fully implemented
• Keep perform functions simple - map payload to API request
• For complex transformations, add TODO comments explaining what's needed