npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@political-comms/sdk

v0.22.1

Published

TypeScript SDK for the Political Comms REST API. Zero dependencies, native fetch, built-in retries and rate limit handling.

Readme

@political-comms/sdk

TypeScript SDK for the Political Comms REST API. Direct-to-carrier political texting for campaigns, PACs, advocacy organizations, fundraisers, and elected officials.

Zero runtime dependencies. Uses native fetch. Node 20 or later.

The full API reference lives at docs.politicalcomms.com and the OpenAPI 3.1 specification at politicalcomms.com/openapi.json.

Install

npm install @political-comms/sdk

Authentication

Requests authenticate with an API key in the X-API-Key header. Keys are created in the dashboard under Admin > API and are prefixed pc_live_.

Set the key in the environment:

export POLITICAL_COMMS_API_KEY=pc_live_...
import { PoliticalCommsClient } from '@political-comms/sdk';

const client = new PoliticalCommsClient();

Or pass it to the constructor:

const client = new PoliticalCommsClient({ apiKey: 'pc_live_...' });

Quickstart

Verify the credential, then run the standard send workflow: create a project, send yourself a test, and schedule it.

import { PoliticalCommsClient } from '@political-comms/sdk';

const client = new PoliticalCommsClient();

// 1. Verify the credential.
const orgs = await client.listOrganizations();
console.log(orgs.data.map((o) => o.display_name));

// 2. Create a project.
const created = await client.createProject({
  organization_id: 'org_...',
  brand_id: 'brand_...',
  campaign_id: 'camp_...',
  phone_number_ids: ['pn_...'],
  name: 'GOTV reminder',
  protocol: 'sms',
  contact_list_ids: ['cl_...'],
  message_text: 'Polls are open until 8pm. Find your polling place: {link}',
});
const projectId = created.data.id!;

// 3. Send a test to yourself.
await client.testProject(projectId, {
  test_contacts: [{ phone: '+15555550100' }],
});

// 4. Schedule the send.
await client.scheduleProject(projectId, {
  scheduled_at: '2026-11-03T09:00:00',
  scheduled_timezone: 'America/New_York',
  // Optional. Past a brand's T-Mobile daily limit, T-Mobile recipients send at
  // a reduced rate; set this to skip the reduced rate and send them at full
  // speed. A carrier rejection still pauses the project, and rejected messages
  // are still billed. Defaults to false.
  // daily_cap_bypass: true,
});

A test, or any send, can also target a test phone number such as +12025550101 (any number ending 555-0100 through 555-0199) to get a fixed delivered or failed outcome without texting a real phone. See Test phone numbers.

One method exists per API operation, named after its operationId: listOrganizations, getHierarchy, listBrands, listCampaigns, getCampaignThroughput, listTrackingDomains, listPhoneNumbers, listWebhookEndpoints, getWebhookEndpoint, listTollFreeVerifications, getTollFreeVerification, listContactLists, getContactList, importContactList, analyzeContactList, downloadContactList, deleteContactList, listMedia, importMedia, getMedia, deleteMedia, listProjects, createProject, getAllProjectStats, getProject, updateProject, getProjectStats, getProjectSurveyResults, getProjectThroughput, testProject, scheduleProject, unscheduleProject, pauseProject, startProject, endProject, addProjectRecipient, createProjectHook, copyProject, listConversations, getConversation, listConversationMessages, replyToConversation, getMessageStats, getLedgerUsage, getLedgerUsageByInitiator.

Triggered projects and campaigns

A triggered text project or email campaign has no contact list. Recipients arrive one at a time when its trigger fires, and each gets its one message, immediately or after delay_minutes. It stays active until paused or ended. A trigger source is donation (a connected WinRed or Anedot list), event (a text link click, text reply, email open, email click, or email reply in another project or campaign), or api (you add the recipient, or a tool POSTs to the inbound hook URL).

const { data: project } = await client.createProject({
  type: 'triggered',
  organization_id: 'org_1',
  phone_number_ids: ['pn_1'],
  name: 'Donor thank-you',
  protocol: 'sms',
  message_text: 'Thanks {first_name}, your ${amount} gift matters.',
  trigger: {
    source: 'donation',
    donation: { integrations: [{ provider: 'winred', id: 'int_1' }], gift: 'one_time' },
    delay_minutes: 10,
    reentry: { mode: 'once' },
  },
});

await client.testProject(project!.project_id!, { test_contacts: [{ phone: '+12025550141' }] });
await client.startProject(project!.project_id!);

// source: 'api' triggers: add one recipient. occurrence_id makes a retry of the same event a no-op.
const { data } = await client.addProjectRecipient(id, {
  phone_number: '+12025550141',
  fields: { first_name: 'Ada', amount: 25 },
  occurrence_id: 'evt_123',
});
if (data.status === 'queued') console.log('sends at', data.send_at);
else console.log('skipped:', data.reason); // duplicate | already_entered | too_soon

const { data: hook } = await client.createProjectHook(id); // hook.hook_url (or hook.endpoint_url + hook.secret in X-Hook-Secret), shown only once
await client.endProject(id); // final: recipients still waiting are not sent

Email campaigns work the same way: createEmailCampaign({ ..., trigger }) with no list_ids, scheduleEmailCampaign(id) with no scheduled_at to start, then addEmailCampaignRecipient, createEmailCampaignHook, and endEmailCampaign. While paused, new recipients are refused with a 409, not queued. Opted-out phone numbers and suppressed addresses are never sent to (409 CONTACT_OPTED_OUT or a 422).

Webhook endpoints

listWebhookEndpoints and getWebhookEndpoint read the outbound webhook endpoints of your organization. They are read-only: endpoints and their signing secret are created and edited in the dashboard. Use them to check delivery health from a script. failing_since is the start of the current run of failed deliveries (null while healthy), and disabled_reason is consecutive_failures when the platform switched an endpoint off after 3 days with no successful delivery. Re-enabling the endpoint clears both. The list is keyset paginated: page until next_cursor is null. The API key needs the public:read permission.

const { data: page } = await client.listWebhookEndpoints({ limit: 100 });
for (const endpoint of page.data) {
  if (!endpoint.enabled || endpoint.failing_since) console.log(endpoint.name, endpoint.disabled_reason);
}

Conversations

A conversation is one thread between one of your sending numbers and one contact, created by a project send. The API never creates a conversation; it replies inside an existing one, from the same number, on the same project. listConversations and listConversationMessages are keyset paginated like the email endpoints.

// Reply to an inbound message.message.replied webhook.
await client.replyToConversation(conversationId, { text: 'Thanks for reaching out!' }, {
  idempotencyKey: 'reply-' + messageId,
});

// Reply with an image or video from the media library (one flat-rate MMS).
await client.replyToConversation(conversationId, { text: 'Here is the flyer', media_ids: [mediaId] });

// Recover inbound messages missed while a webhook endpoint was down.
const { data: page } = await client.listConversations({ updated_since: lastSeenAt });
for (const conversation of page.data) console.log(conversation.conversation_id, conversation.status);

Email

The /v1/email surface is wrapped in full: sending domains, sender identities, suppressions, templates, and campaigns. Paid and human-driven workflows (AI drafting, result exports) run in the dashboard. Write methods need the email entitlement on the organization and return 403 ENTITLEMENT_REQUIRED without it. Reads are open.

Email endpoints are keyset paginated: the payload is { data, has_more, next_cursor }. Page until next_cursor is null, and never parse or construct a cursor.

There is no inbound email or inbox surface, and no A/B testing.

// Page through campaigns.
let cursor: string | undefined;
do {
  const page = await client.listEmailCampaigns({ limit: 100, cursor });
  for (const campaign of page.data!.data) console.log(campaign.name, campaign.status);
  cursor = page.data!.next_cursor ?? undefined;
} while (cursor);

// Check what is blocking a campaign before scheduling it.
const { data: campaign } = await client.getEmailCampaign(id);
if (campaign?.blocked?.length) {
  for (const reason of campaign.blocked) console.log(reason.code, reason.message);
} else {
  await client.scheduleEmailCampaign(id, { scheduled_at: '2026-09-05T15:00:00Z' });
}

Pause and resume

pauseEmailCampaign(id) pauses a scheduled, compiling, or sending campaign with pause_reason: 'api'; the platform never resumes an api pause by itself. resumeEmailCampaign(id, { resume_at }) resumes it now, or with a resume_at more than a minute ahead keeps it paused and resumes it at that time (the campaign's resume_at shows the plan; a later pause cancels it). Resume clears any pause reason, but if the cause still holds the platform pauses it again. Only api, manual, and provider_refused pauses wait for a person; the rest resume on their own once the cause clears. Resume returns 409 SENDING_PAUSED while sending is suspended, and 409 EMAIL_CAMPAIGN_TEST_REQUIRED when content changed during the pause (send a test from the dashboard, then resume).

await client.pauseEmailCampaign(id);
await client.resumeEmailCampaign(id); // now
await client.resumeEmailCampaign(id, { resume_at: '2026-12-01T15:00:00Z' }); // planned

Templates

Templates save the HTML a campaign sends. Create also returns lint: the save succeeds either way, but a campaign will not schedule while lint.errors is non-empty, so check it at save time rather than at send time. This endpoint only accepts HTML content; content.editor is 'html' for a template created here, or 'document' for one built in the dashboard's document editor, readable over the API as rendered HTML only. Updating the content of a 'document' template returns 409 CONFLICT with details.reason set to 'TEMPLATE_IS_DOCUMENT'.

List imports

importContactList is the one list import, for phones, emails, or both. The server fetches a CSV you host over https (50 MB cap) and returns 202. Name the columns: phone_column, email_column, or both (there is no automatic email column detection). consent is optional and allowed only for an audience list with emails; with merge_tags, phones map only the named columns while emails also map every remaining column. purpose: 'do_not_contact' turns phones into an opt-out list and emails into unsubscribes, and returns no list_id. For an audience import, poll getContactList(id): import is the phone side and email.status is the email side.

const { data: started } = await client.importContactList({
  source_url: 'https://example.com/donors.csv',
  list_name: 'August donors',
  phone_column: 'Phone',
  email_column: 'Email',
  merge_tags: { first_name: 'First Name' },
  consent: { source: 'donation_form', note: 'ActBlue donors, 2026 cycle' },
});
if (started.purpose === 'audience') console.log(started.list_id, started.channels);

listContactLists returns the lists that hold phone numbers by default; pass channel: 'email' or channel: 'all' for the others. Each list reports its channels and its email side (null when it has none). deleteContactList removes a list's phone numbers and its emails. The three delete methods (deleteContactList, deleteMedia, removeEmailSuppressions) need an API key with the public:delete permission, which is opt-in when the key is created and requires public:write; other keys get a 403.

Email addresses reach a list only through importContactList with email_column (a CSV import creates the list, with the email side). Poll getContactList and read email.status and email.counts; read unsubscribes and bounces with listEmailSuppressions.

Error handling

Non-success responses throw PoliticalCommsError with the API's machine readable code, the HTTP statusCode, and the raw response body.

import { PoliticalCommsError } from '@political-comms/sdk';

try {
  await client.getProject('proj_unknown');
} catch (err) {
  if (err instanceof PoliticalCommsError) {
    console.error(err.code, err.statusCode, err.message);
  }
}

Network failures throw PoliticalCommsError with code: 'NETWORK_ERROR' and statusCode: 0.

Retries

The client retries automatically with these rules:

  • 400, 401, 403, 404 are never retried.
  • 429 is retried after waiting until the X-RateLimit-Reset timestamp.
  • 500, 502, 503, 504 are retried with exponential backoff and jitter: 1 second base, 60 second cap, at most 5 attempts total.

Configure the retry budget with maxRetries (retries after the first attempt, default 4):

const client = new PoliticalCommsClient({ maxRetries: 2 });

Every POST and PATCH request carries an Idempotency-Key header (a random UUID) so retries are safe; the API returns the cached first response when a key is replayed. DELETE requests send the header only when you supply a key. Supply your own key per call when you need cross-process deduplication:

await client.createProject(body, { idempotencyKey: 'send-2026-11-03-wave-1' });

Each call also accepts an AbortSignal:

await client.listProjects({}, { signal: AbortSignal.timeout(10_000) });

Rate limits

The API allows 600 requests per minute per key: bursts of up to 600 at once, refilling at 10 per second, the same for every scope. The client exposes the most recent rate limit headers:

await client.listOrganizations();
console.log(client.lastRateLimit);
// { limit: 100, remaining: 97, reset: 1767225600 }  (reset is Unix seconds)

License

MIT. Questions: [email protected]