@industriousoffice/mailchimp_marketing/TYPESCRIPT.md

This is a modified version of the official Node client library for the Mailchimp Marketing API meant to be usesd for both production and testing purposes.

# TypeScript Integration Guide

This guide explains how to resolve TypeScript import issues and use the `@industriousoffice/mailchimp_marketing` package with full type safety.

## The Problem You Were Experiencing

When importing the package in TypeScript, you might have seen this error:

```
Cannot find module '@industriousoffice/mailchimp_marketing' or its corresponding type declarations.
```

## The Solution

This package now includes comprehensive TypeScript declarations (`.d.ts` files) that provide full type safety and IntelliSense support.

## Installation & Setup

1. **Install the package**:
   ```bash
   npm install @industriousoffice/mailchimp_marketing
   ```

2. **The package now includes**:
   - `index.d.ts` - Main TypeScript declarations
   - `src/index.d.ts` - Additional type definitions
   - Full type support for all API endpoints

## Usage Examples

### Basic TypeScript Usage

```typescript
import mailchimp from '@industriousoffice/mailchimp_marketing';

// Configure with type checking
mailchimp.setConfig({
  apiKey: 'your-api-key-us1',
  server: 'us1'
});

// Type-safe API calls
async function example() {
  // Ping API - returns Promise<ApiResponse<{ health_status: string }>>
  const health = await mailchimp.ping.get();
  console.log(health.data.health_status); // TypeScript knows this is a string
  
  // Lists API with full type support
  const lists = await mailchimp.lists.getAllLists({
    count: 10,
    sort_dir: 'DESC' // TypeScript will validate this value
  });
  
  // Add member with typed interface
  const member = await mailchimp.lists.addListMember('list-id', {
    email_address: 'user@example.com',
    status: 'subscribed', // TypeScript validates allowed status values
    merge_fields: {
      FNAME: 'John',
      LNAME: 'Doe'
    }
  });
}
```

### CommonJS Usage (Node.js)

```typescript
const mailchimp = require('@industriousoffice/mailchimp_marketing');

// Types are still available with require()
mailchimp.setConfig({
  apiKey: 'your-key',
  server: 'us1'
});
```

### Testing with Mock Servers

```typescript
// Set up for testing
process.env.MAILCHIMP_BASE_URL = 'http://localhost:3001/3.0';

import mailchimp from '@industriousoffice/mailchimp_marketing';

mailchimp.setConfig({
  apiKey: 'test-key',
  server: 'ignored' // Server config ignored when MAILCHIMP_BASE_URL is set
});

// All API calls now go to your mock server
const response = await mailchimp.ping.get();
```

## Available Type Interfaces

### Core Interfaces

- **`MailchimpConfig`** - Configuration object
- **`ApiResponse<T>`** - Generic API response wrapper
- **`ErrorResponse`** - Error response structure
- **`PaginationOptions`** - Common pagination parameters

### Data Structures

- **`ListMember`** - Complete list member interface
- **`Campaign`** - Campaign data structure
- **`Automation`** - Automation workflow data
- And many more...

### API Endpoints

All API endpoints are fully typed:
- `mailchimp.lists.*` - Lists API
- `mailchimp.campaigns.*` - Campaigns API
- `mailchimp.automations.*` - Automations API
- `mailchimp.reports.*` - Reports API
- `mailchimp.ecommerce.*` - E-commerce API
- And all other endpoints...

## IDE Support

### VS Code
- Full IntelliSense support
- Parameter hints
- Type checking
- Error highlighting

### WebStorm/IntelliJ
- Complete autocompletion
- Type information on hover
- Refactoring support

### Other TypeScript-enabled IDEs
- Should work out of the box with included declaration files

## Troubleshooting

### If you still see type errors:

1. **Check TypeScript version**: Ensure you're using TypeScript 4.0+
   ```bash
   npx tsc --version
   ```

2. **Clear TypeScript cache**: In VS Code, use `Ctrl+Shift+P` → "TypeScript: Restart TS Server"

3. **Verify package installation**:
   ```bash
   npm list @industriousoffice/mailchimp_marketing
   ```

4. **Check tsconfig.json**: Ensure `moduleResolution` is set to `"node"`
   ```json
   {
     "compilerOptions": {
       "moduleResolution": "node"
     }
   }
   ```

### For older TypeScript versions:

If you're using an older TypeScript version, you might need to add a type reference:

```typescript
/// <reference types="@industriousoffice/mailchimp_marketing" />
```

## Migration from Untyped Usage

If you were previously using this package without types:

1. **Update your imports** - No changes needed, types are now included
2. **Fix type errors** - TypeScript will now catch previously hidden errors
3. **Add type annotations** - Optional, but recommended for better code quality

```typescript
// Before (JavaScript/untyped)
const response = await mailchimp.lists.getAllLists();

// After (TypeScript with full type safety)
const response: ApiResponse<{ lists: any[], total_items: number }> = 
  await mailchimp.lists.getAllLists({
    count: 100,
    sort_dir: 'DESC'
  });
```

## Benefits

✅ **Type Safety** - Catch errors at compile time  
✅ **IntelliSense** - Better developer experience  
✅ **Documentation** - Types serve as inline documentation  
✅ **Refactoring** - Safe code refactoring with IDE support  
✅ **Error Prevention** - Prevent runtime errors  

The package is now fully TypeScript-ready while maintaining 100% backward compatibility with JavaScript projects!