Calling the API

Methods follow the URLs

Methods mirror the endpoint's path. Each part of the path, except the ids, is a property on the client, and the action is the method:

The common method names are list, get, create, update and delete. Other actions are named for what they do: pause, resume, send, duplicate. All methods lists every method with its endpoint. Each endpoint page in the API Reference names its SDK method at the top.

Arguments

A method takes, in order:

1. the ids in the path, in the order they appear in the URL;
2. one params object holding the query parameters and the body fields together;
3. the request options (timeout, signal, idempotencyKey, …), always optional.

// PATCH /campaigns/{id} with a body
await swarmhit.campaigns.update(campaignId, { name: 'Q4 founders (EU)' });

// GET /accounts/{id}/stats?days=30
const stats = await swarmhit.accounts.getStats(accountId, { days: 30 });

// GET /campaigns/{id}/leads/{leadId}: two ids, no params
const lead = await swarmhit.campaigns.leads.get(campaignId, leadId);

// With request options
await swarmhit.campaigns.list({ limit: 10 }, { timeout: 10_000 });

The SDK URL-encodes the ids, so pass them as they are.

Results

A method resolves to the object itself. The SDK removes the API's { "data": … } envelope, so there is nothing to unwrap.

const campaign = await swarmhit.campaigns.get(campaignId);
campaign.name; // not campaign.data.name

A list method resolves to a page you can iterate: see Lists and pagination. A few endpoints answer with more than one object, and resolve to the whole body. Connecting a LinkedIn sender, for example, gives { data, status, checkpoint }.

Dates are ISO 8601 strings.

Fields that can be empty

The API leaves a field out of the JSON when it has no value, and sends null for some others. A field the API always sends is required in the types (campaign.id: string); one that can be empty is optional and, where the API documents it, nullable (lead.email?: string | null). Test it with ?? or a plain truthiness check rather than === null:

const email = lead.email ?? 'no email yet';

TypeScript

Every parameter and result is typed, and the types are exported by name:

import Swarmhit from '@swarmhit/swarmhit-sdk';
import type { Campaign, CreateCampaignParams, LeadInCampaign } from '@swarmhit/swarmhit-sdk';

const params: CreateCampaignParams = { name: 'Q4 founders' };
const campaign = await swarmhit.campaigns.create(params);

Enumerations in results are open. A campaign's status, for example, is typed 'draft' | 'active' | 'paused' | 'finished' | (string & {}). You get autocompletion for today's values, and your code still compiles when the API adds a new one. The API may add values at any time within v1, so handle unknown values with a default branch.

Plain JavaScript works the same way. Your editor still shows the types and each method's documentation.

The HTTP response

To read the response's status or headers, add .withResponse() to the call:

const { data, response } = await swarmhit.campaigns.get(campaignId).withResponse();

data.name;
response.status; // 200
response.headers.get('content-type');

.asResponse() gives only the raw Response. The SDK has already read its body, so use .withResponse() when you also need the data.