npm package: @synapsemedcom/contacts-types
Description: Shared types and schemas for Synapse Contacts API
Author: Synapse MedCom
Latest version: 1.0.1

# @synapsemedcom/contacts-types

Shared TypeScript types and Zod schemas for the Synapse Contacts API.

## Installation

```bash
npm install @synapsemedcom/contacts-types
# or
yarn add @synapsemedcom/contacts-types
# or  
bun add @synapsemedcom/contacts-types
```

## Usage

### Import Types and Schemas

```typescript
import { 
  // Request/Response types
  Contact,
  CreateContact,
  UpdateContact,
  Interaction,
  CreateInteraction,
  
  // Zod schemas for validation
  createContactSchema,
  updateContactSchema,
  contactResponseSchema,
  
  // Auth helpers
  generateServiceAuthHeaders,
  createAuthenticatedFetch
} from '@synapsemedcom/contacts-types';
```

### Validate API Requests

```typescript
import { createContactSchema } from '@synapsemedcom/contacts-types';

// Validate user input before sending to API
const contactData = createContactSchema.parse({
  firstName: 'John',
  lastName: 'Doe', 
  email: 'john@example.com'
});
```

### Validate API Responses

```typescript
import { contactResponseSchema } from '@synapsemedcom/contacts-types';

const response = await fetch('/api/contacts/123');
const data = await response.json();

// Ensure API response matches expected shape
const contact = contactResponseSchema.parse(data);
```

### Service-to-Service Authentication

```typescript
import { generateServiceAuthHeaders, createAuthenticatedFetch } from '@synapsemedcom/contacts-types';

// Option 1: Generate headers manually
const headers = generateServiceAuthHeaders('email-service', process.env.API_SECRET);
const response = await fetch('/api/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    ...headers
  },
  body: JSON.stringify(contactData)
});

// Option 2: Use authenticated fetch helper  
const authenticatedFetch = createAuthenticatedFetch(
  'https://contacts-api.vercel.app',
  'email-service', 
  process.env.CONTACTS_API_SECRET
);

const response = await authenticatedFetch('/api/contacts', {
  method: 'POST',
  body: JSON.stringify(contactData)
});
```

### Example: Email Service Integration

```typescript
import { 
  Contact, 
  CreateInteraction, 
  createAuthenticatedFetch,
  listContactsQuerySchema 
} from '@synapsemedcom/contacts-types';

class EmailService {
  private contactsAPI = createAuthenticatedFetch(
    process.env.CONTACTS_API_URL!,
    'email-service',
    process.env.CONTACTS_API_SECRET!
  );

  async sendCampaignToSpecialty(specialty: string) {
    // Get contacts - validated query params
    const query = listContactsQuerySchema.parse({ 
      specialty, 
      limit: '100' 
    });
    
    const response = await this.contactsAPI(
      `/api/contacts?${new URLSearchParams(query as any).toString()}`
    );
    
    const { contacts } = await response.json();
    
    for (const contact of contacts) {
      await this.sendEmail(contact.email);
      
      // Log interaction
      const interaction: CreateInteraction = {
        type: 'email',
        content: `Sent campaign: ${specialty} specialists`,
        metadata: { campaignId: '2025-trial' }
      };
      
      await this.contactsAPI(`/api/contacts/${contact.id}/interactions`, {
        method: 'POST',
        body: JSON.stringify(interaction)
      });
    }
  }
}
```

## Available Types

### Request Types
- `CreateContact` - For POST /api/contacts
- `UpdateContact` - For PUT /api/contacts/:id  
- `CreateInteraction` - For POST /api/contacts/:id/interactions
- `CreateTag` - For POST /api/tags
- `ListContactsQuery` - Query parameters for GET /api/contacts

### Response Types  
- `Contact` - Contact record with all fields
- `Interaction` - Interaction/note record
- `Tag` - Tag record
- `ContactListResponse` - Paginated contacts list
- `InteractionListResponse` - List of interactions

### Configuration
- `ContactsAPIConfig` - API configuration interface

## Available Schemas

All Zod schemas for request/response validation:
- `createContactSchema`
- `updateContactSchema` 
- `contactResponseSchema`
- `createInteractionSchema`
- `interactionResponseSchema`
- `listContactsQuerySchema`
- And more...

## Auth Helpers

- `generateServiceAuthHeaders(serviceId, apiSecret)` - Generate HMAC headers
- `createAuthenticatedFetch(baseUrl, serviceId, apiSecret)` - Get authenticated fetch function