Deep Dive: Integrating with Medal Social SDK

The Medal Social SDK is a typed, lightweight TypeScript client designed to simplify interactions with the Medal Social API. Instead of manually constructing HTTP requests and handling authentication headers, developers can use a robust, method-based interface to integrate social and CRM features into their applications.

Why use the SDK?

Integrating directly with REST APIs can be error-prone, requiring boilerplate code for fetch operations, error handling, and type definitions. The Medal Social SDK solves these challenges by providing:

• Full Type Safety: Written in TypeScript, it provides autocomplete and compile-time checking for all request payloads.Simplified Authentication: Supports both Basic (Client ID/Secret) and Bearer token authentication out of the box.Convenience Methods: Dedicated methods for common actions like creating leads, notes, and events.

Installation & Setup

Get started by installing the package via your preferred package manager:

pnpm add @medalsocial/sdk

Initialize the client with your credentials. You can use environment variables to keep secrets safe.

import MedalSocialClient from '@medalsocial/sdk';

const client = new MedalSocialClient({
  auth: { 
    kind: 'basic', 
    clientId: process.env.MEDAL_CLIENT_ID!, 
    clientSecret: process.env.MEDAL_CLIENT_SECRET! 
  },
  // Alternatively use a bearer token
  // auth: { kind: 'bearer', token: process.env.MEDAL_API_TOKEN! },
});

Key Features & Use Cases

1. Lead Generation

Capture interest from your marketing site or landing pages directly into your CRM system. The `createLead` method accepts an array, allowing for bulk creation.

await client.createLead([
  {
    name: 'Alex Example',
    email: 'lead.test@example.com',
    company: 'Tech Corp',
    source: 'website-landing-page',
  },
]);

2. Customer Context (Notes)

Enrich user profiles with context using `createNote`. This is perfect for sales teams needing to log interactions or support teams recording user details.

await client.createNote({
  name: 'Test Testnes',
  email: 'test@medalsocial.com',
  company: 'Medal Social Test company',
  content: 'Customer is interested in the enterprise plan. Follow up next week.',
  metadata: { Budget: '$100,000', Urgency: 'High' },
});

3. Event Management

Seamlessly register users for webinars, product launches, or conferences using `createEventSignup`. It links the contact details with specific event metadata.

await client.createEventSignup({
  contact: {
    name: 'Test Testnes',
    email: 'test@medalsocial.com',
    company: 'Medal Social Test company',
  },
  event: {
    externalId: 'launch-2025',
    name: 'Product Launch 2025',
    description: 'Unveiling our latest tools',
    time: '2025-06-15T14:00:00Z',
    location: 'Online Stream',
  },
});

4. Compliance & Privacy

Manage user consent and ensure GDPR/CCPA compliance by recording cookie preferences via `createCookieConsent`.

await client.createCookieConsent({
  domain: 'example.com',
  consentStatus: 'partial',
  consentTimestamp: new Date().toISOString(),
  ipAddress: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  cookiePreferences: {
    necessary: { allowed: true },
    marketing: { allowed: false },
    analytics: { allowed: true }
  },
});