@totalaudiopromo/tap-sdk

TypeScript SDK for the TAP REST API — contacts, campaigns, outcomes, keys, and webhooks for music PR automation.

Zero dependencies. Uses native fetch. Works in Node.js, Deno, Bun, and edge runtimes.

Install

npm install @totalaudiopromo/tap-sdk
# or
pnpm add @totalaudiopromo/tap-sdk

Quick start

import { TapClient } from '@totalaudiopromo/tap-sdk';

const tap = new TapClient({ apiKey: 'tap_ak_...' });

// List contacts
const { contacts, total } = await tap.contacts.list({ search: 'BBC', limit: 10 });

// Import contacts
const result = await tap.contacts.create([
  { name: 'Jo Whiley', email: '[email protected]', outlet: 'BBC Radio 2' },
  { name: 'Clara Amfo', email: '[email protected]', outlet: 'BBC Radio 1' },
]);
console.log(`Imported ${result.imported}, skipped ${result.skipped}`);

// Enrich contacts with AI
const enrichment = await tap.contacts.enrich(['contact-id-1', 'contact-id-2']);

// Validate emails
const validation = await tap.contacts.validate(['[email protected]']);

// List campaigns
const { campaigns } = await tap.campaigns.list({ status: 'active' });

// Create a campaign
const { campaign } = await tap.campaigns.create({
  name: 'Spring Release',
  artist_name: 'Artist',
  status: 'draft',
});

// Get campaign details with stats
const details = await tap.campaigns.get(campaign.id);

// Update a campaign
await tap.campaigns.update(campaign.id, { status: 'active' });

// Add contacts to a campaign
await tap.campaigns.addContacts(campaign.id, ['contact-id-1']);

// List campaign contacts
const { contacts: campaignContacts } = await tap.campaigns.listContacts(campaign.id);

// Log an outcome
await tap.outcomes.log({
  campaign_id: campaign.id,
  contact_id: 'contact-id-1',
  outcome_type: 'coverage',
  notes: 'BBC 6 Music playlist add',
});

// List outcomes
const { outcomes } = await tap.outcomes.list({ campaign_id: campaign.id });

// Webhooks
const { webhook } = await tap.webhooks.create({
  url: 'https://example.com/hook',
  events: ['outcome.logged', 'contact.imported'],
});
const { webhooks } = await tap.webhooks.list();
await tap.webhooks.delete(webhook.id);

Error handling

All methods throw TapApiError on non-2xx responses:

import { TapClient, TapApiError } from '@totalaudiopromo/tap-sdk';

try {
  await tap.contacts.get('nonexistent-id');
} catch (err) {
  if (err instanceof TapApiError) {
    console.error(err.status); // 404
    console.error(err.message); // "Contact not found"
    console.error(err.body); // { error: "Contact not found" }
  }
}

Configuration

const tap = new TapClient({
  apiKey: 'tap_ak_...', // Required
  baseUrl: 'http://localhost:3010', // Optional, defaults to https://totalaudiopromo.com
  fetch: customFetch, // Optional, for testing or custom runtimes
});

API coverage

| Resource | Methods | | ----------- | ---------------------------------------------------------------- | | contacts | list, get, create, update, erase, enrich, validate | | campaigns | list, get, create, update, listContacts, addContacts | | outcomes | list, log | | keys | list, create, revoke | | webhooks | list, create, delete |

Licence

MIT