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

callcloud-partner

v0.2.0

Published

CallCloud partner SDK: embed the parallel-dialer softphone, call the Partner API, verify webhooks.

Readme

callcloud-partner

Build your own dialer UI on CallCloud's parallel dialer. CallCloud handles the calling: lines, carriers, voicemail handling, recordings and transcripts. You keep your leads, your screens and your outcomes.

The package has two halves:

| Where | What | Import | |---|---|---| | Browser | Softphone: the rep's line, embedded once in your app, with typed methods and events | callcloud-partner/softphone | | Your server | PartnerClient for rep tokens, reps, numbers, pools, settings, recorded messages, the calls feed and abandon stats; verifyWebhook for call events | callcloud-partner/server |

It has no dependencies. The server half runs on Node 18+, Deno, Bun, Cloudflare Workers and edge runtimes.

Install

npm install callcloud-partner

Before you start

You need a CallCloud partner workspace, which CallCloud sets up for you. Then:

  1. In Settings > Developers, create an API key (ccp_...). Keep it on your server only.
  2. In the same tab, set your webhook URL and copy the signing secret (whsec_...).
  3. Tell CallCloud the origin your app runs on, e.g. https://app.example.com. The softphone only loads inside, and only talks to, origins on your workspace's list.

1. Mint a rep token (your server)

Reps never sign in to CallCloud. Your server mints a 1-hour token for the rep who is signed in to your app. The first token for a new email adds that rep as a seat.

import { PartnerClient } from 'callcloud-partner/server';

const cc = new PartnerClient({ apiKey: process.env.CALLCLOUD_API_KEY! });

// e.g. GET /api/callcloud-token, behind your own auth
export async function GET(req: Request) {
  const user = await requireUser(req);
  const { token } = await cc.tokens.mint({ repEmail: user.email, repName: user.name });
  return Response.json({ token });
}

2. Mount the softphone (browser)

Mount it once, at your app root, and keep it mounted for the whole session. Remounting it between calls drops the line and adds seconds to every call.

import { Softphone } from 'callcloud-partner/softphone';

const phone = Softphone.mount({
  container: '#callcloud-phone',  // keep it visible; a hidden frame can be throttled or muted
  getToken: () => fetch('/api/callcloud-token').then((r) => r.json()).then((d) => d.token),
  rep: { email: user.email, name: user.name },
  callerId: 'rep',                // or 'group:<name>', or one of your E.164 numbers
});

await phone.ready;                // the rep's line is registered

getToken is called for the first token. It is called again each time the softphone warns that the token is about to expire, and the new token is swapped in without touching the line. Calls you make before ready are held until the line is up.

Dial

phone.on('answered', ({ callId, metadata }) => openLeadCard(metadata.leadId));
phone.on('ended', (e) => saveAttempt(e.metadata.leadId, e.status, e.talkSeconds));
phone.on('error', ({ code, message }) => toast(message));

phone.dial({ to: '+14155550123', name: 'Dana Lee', metadata: { leadId: 'L1' } });

// or ring up to 5 at once; the first human is put through
phone.dialBatch({ legs: [
  { to: '+14155550123', metadata: { leadId: 'L1' } },
  { to: '+12125550100', metadata: { leadId: 'L2' } },
] });

Whatever you send as metadata (about 1 KB) comes back on every event and every webhook for that call. Put the data your lead card needs on the dial itself, so you can draw the card the moment answered fires. Drive your UI from these events, never from webhooks: webhooks arrive later.

In-call controls:

phone.mute(); phone.unmute();
phone.dtmf('1');
phone.judge(callId, 'voicemail');   // or 'skip': the rep's call on what picked up
phone.hangup();
const state = await phone.getState(); // { phase, registered, callId, poolId, available, ... }

Team pools

A pool is one shared dialing session for a team. CallCloud dials the pool's queue and routes each answered call to a free rep. You create and fill the pool on your server:

const pool = await cc.pools.create({ name: 'Monday blitz', lineCount: 10, routing: 'longest_idle', localPresence: true });
await cc.pools.queue(pool.id, leads.map((l) => ({ to: l.phone, name: l.name, metadata: { leadId: l.id } })));
await cc.pools.update(pool.id, { lineCount: 6 });   // takes effect at once

Then each rep joins from the browser:

phone.joinPool(poolId);
phone.on('routed', ({ callId, metadata, answerToConnectMs }) => openLeadCard(metadata.leadId));
phone.on('available', ({ available, reason }) => setRepStatus(available, reason));
phone.on('pool.idle', ({ message }) => banner(message));   // e.g. no number to call from
phone.setAvailable(true);   // after wrap-up
phone.leavePool();

Each number is dialed at most once per pool. If the same rep joins from a second device, the newest device takes the line and the old one gets pool.left with reason replaced.

Inbound calls and callbacks

Turn inbound on once (cc.settings.update({ inbound: 'softphone' }); a softphone already signed in picks it up at its next token refresh) and keep the rep's line open with standby. A prospect who calls one of your numbers then rings the softphone of the rep they belong to: the one who called them last, or their owner.

const phone = Softphone.mount({ container: '#phone', getToken, standby: true });
phone.on('incoming', (c) => showRinging(c));        // { callId, kind: 'inbound' | 'transfer', from, name, company, fromRep }
phone.on('incoming.ended', ({ callId, reason }) => hideRinging(callId));
phone.answer(callId);                                 // or phone.decline(callId): forwarding phone, else voicemail + a callback

An answered call is an ordinary call: answered (with direction: 'inbound'), then ended, and the webhooks. If no softphone line is open, the call goes to the rep's forwarding phone or voicemail and becomes a callback, as before. A pool lane is an open line too.

Live transfer to another rep

phone.transfer({ toRep: '[email protected]' });   // warm: the closer's softphone rings (incoming, kind 'transfer')
phone.on('transfer.state', (t) => render(t));      // ringing -> joined (all three on) | no_answer
phone.hangup();                                    // once joined: leaves the closer the call (state 'completed')
phone.cancelTransfer();                            // stop ringing, or once joined send the closer back
phone.transfer({ to: '+14155550123' });            // cold, to a number: this rep drops at once

The closer needs an open line (standby, a pool, or dialing) and must not be on a call. Their side gets answered with transfer: { fromRep }, transfer.state with role: 'closer' (joined, then completed), and their own ended when they hang up. The rep who handed it over gets ended with transferred: { toRep }. Every event and webhook keeps your metadata.

Hold, voicemail drop and call screeners

phone.hold();            // the prospect hears a soft chime; the keypad waits; at most 10 minutes
phone.resume();          // hold.state { callId, on }
phone.dropVoicemail();   // leaves the rep's recorded voicemail at the beep and ends the call (voicemail.dropped)
phone.dial({ to, metadata, voicemail: 'drop', screener: 'rep' });

Upload each rep's messages first: cc.reps.messages.put(email, 'voicemail', { audioBase64, mime: 'audio/wav' }) and 'screener' (WAV or MP3, under 3 MB).

| Option | 'hangup' (default) | 'drop' | 'rep' | 'message' (pools only) | |---|---|---|---|---| | voicemail | hung up | the rep's voicemail at the beep | the rep hears the greeting | | | screener | hung up | | put through to the rep, who says who they are | the rep's screener message at the screener's silence; if the person picks up they go to a free rep |

Pools take the same two settings (cc.pools.create({ voicemail, screener })). call.machine.kind on ended and the webhooks says what answered: voicemail, screener or phone_menu.

Mic and speaker

const d = await phone.getDevices();   // { inputs, outputs, micId, speakerId }
phone.setDevices({ micId: d.inputs[1].id, speakerId: 'default' });   // a live call moves at once
phone.on('devices', (d) => render(d));   // also sent when a headset is plugged in or out

The choice is kept for this computer. Labels appear once the rep has allowed the microphone. The panel has its own Audio picker too.

Listen in

Turn monitoring on (cc.settings.update({ monitoring: true })), then from a free softphone (no call, not in a pool):

phone.listen(callId);                  // muted; listen.state connecting -> on
phone.setListenMode('whisper');        // only the rep hears you; 'barge' = everyone does; 'listen' = muted again
phone.stopListening();                 // also ends by itself when the call does (listen.state ended)

callId is the one your app got on that rep's answered or routed.

Softphone events

ready, registering, registered, error, tokenExpiring, state, call.state, answered, ended, batch.started, pool.joined, pool.left, available, routed, pool.idle, pool.resumed, incoming, incoming.ended, transfer.state, hold.state, voicemail.dropped, devices, line.state, listen.state. Every payload is typed (SoftphoneEvents). phone.onAny((type, payload) => ...) receives all of them.

3. Receive webhooks (your server)

import { verifyWebhook } from 'callcloud-partner/server';

export async function POST(req: Request) {
  const rawBody = await req.text();   // the untouched body; a re-serialised one won't verify
  let event;
  try {
    event = await verifyWebhook({ rawBody, headers: req.headers, secret: process.env.CALLCLOUD_WEBHOOK_SECRET! });
  } catch {
    return new Response('bad signature', { status: 401 });
  }
  if (await alreadySeen(event.id)) return new Response('ok');   // ids are stable across retries
  queueWork(event);                                             // answer fast, work after
  return new Response('ok');
}

On Express, use express.raw({ type: 'application/json' }) for this route and pass req.body (a Buffer) plus req.headers.

Recording links (recording.url, recording.shareUrl) are served by dialer.callcloud.app and do not expire.

| Event | When | Extra field | |---|---|---| | call.ended | every leg, once it's over | | | call.abandoned | someone answered while the rep was on another line | | | call.machine_detected | a voicemail or screener was caught | call.machine | | recording.ready | the stereo recording is stored (left = prospect, right = rep) | recording | | transcript.ready | the call is transcribed (only calls where the rep talked) | transcript | | summary.ready | the AI summary is done | summary |

Every event carries call: id, from, to, status, answeredBy, talkSeconds, hangupCause, sipCode, repEmail, poolId, requeued, metadata and more (WebhookCall). If requeued is true, the dialer cut that ring itself and put the number back in the queue, so don't count it as a try. Deliveries from Send test events have event.test === true. A delivery that doesn't get a 2xx is retried with backoff for up to 24 hours.

Catch up on missed events: the calls feed

Webhooks are the fast path; the feed is the safety net. It has every call your softphones and pools placed (and inbound calls to them), with the same call object as the webhooks plus the recording, transcript and summary once they exist.

for await (const c of cc.calls.all({ since: lastSyncedAt })) {
  upsert(c.call.id, c);           // c.final === false: still live, it comes back with its end next time
}
const one = await cc.calls.get(callId);

cc.calls.list({ since, cursor, limit }) gives one page ({ calls, nextCursor }, oldest first, up to 30 days back).

Settings

await cc.settings.get();
await cc.settings.update({ repeatCap: { day: 8, week: 20 } });   // null = back to 5 and 15

| Setting | Default | What | |---|---|---| | repeatCap | { day: 5, week: 15 } | How often ONE rep may ring ONE number: 1 to 10 a day, up to 30 a week. A dial past it is refused with repeat_cap; override: true rings it anyway. | | inbound | 'forward' | 'softphone': calls to your numbers ring the rep's open softphone line. | | monitoring | false | Calls get a listening room, so a softphone can listen in. |

Numbers

const options = await cc.numbers.search(415);
const num = await cc.numbers.buy(options[0].phone);      // billed monthly from today
await cc.numbers.update(num.id, { repEmail: '[email protected]' }); // Sam's caller ID
await cc.numbers.update(num.id, { group: 'west' });            // dial with callerId 'group:west'
await cc.numbers.release(num.id);

Errors

Partner API failures throw PartnerApiError with status, code and message, the same { error: { code, message } } the API returns. For example, buying a number during a card-free trial gives 402. Softphone failures arrive as error events. phone.ready rejects with a SoftphoneError, either invalid_token or ready_timeout.

Anything not wrapped yet: cc.request(method, path, body?, query?).

Questions or a new origin to allow: email [email protected].