@synapsemedcom/contacts-types

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

Installation

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

Usage

Import Types and Schemas

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

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

// Validate user input before sending to API
const contactData = createContactSchema.parse({
  firstName: 'John',
  lastName: 'Doe', 
  email: '[email protected]'
});

Validate API Responses

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

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

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