TypeScript SDK

The TypeScript SDK ships full type definitions for every endpoint, request payload, and response object, so your editor catches mistakes before they hit production. It runs in Node.js 18+ and any modern bundler-based environment. This page covers installing @surgeapi/node, sending your first request, paginating list endpoints, narrowing typed errors, and verifying webhook signatures in your handler.

Install and authenticate

npm install @surgeapi/node

Set your API key as an environment variable:

export SURGE_API_KEY=sk_live_your_key_here

import Surge from "@surgeapi/node";

const surge = new Surge();

Your first request

const message = await surge.messages.create("acct_01jrzhe8d9enptypyx360pcmxj", {
  to: "+18015551234",
  body: "Your appointment is confirmed for Friday at 2pm.",
});

console.log(message.id); // msg_01j...

Type imports

Every resource and parameter has a corresponding TypeScript type:

import type { Message, MessageCreateParams } from "@surgeapi/node";

const params: MessageCreateParams = {
  to: "+18015551234",
  body: "Hello",
};

const message: Message = await surge.messages.create("acct_01j...", params);

Pagination

The SDK returns auto-paginating iterators using async iteration:

// Iterates through all messages
for await (const message of surge.messages.list("acct_01j...")) {
  console.log(message.id);
}

Page manually when you need cursor control:

const page = await surge.messages.list("acct_01j...", { limit: 25 });

console.log(page.data);
console.log(page.pagination.next_cursor);

Retries and timeouts

The SDK retries transient failures automatically. Configure on the client:

const surge = new Surge({
  maxRetries: 5,
  timeout: 30_000, // milliseconds
});

Error handling

Errors are typed exceptions:

import { APIError, AuthenticationError } from "@surgeapi/node";

try {
  await surge.messages.create("acct_01j...", { to: "+18015551234", body: "Hello" });
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status);                  // e.g. 422
    console.log(error.error.error.type);        // e.g. "opted_out"
    console.log(error.error.error.message);
  }
}

Webhooks

Use the SDK’s built-in webhook helper to verify signatures and parse events:

// Express example:
const surge = new Surge({ webhookSigningSecret: process.env.SURGE_WEBHOOK_SECRET });

app.post("/webhooks/surge", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = surge.webhooks.unwrap(req.body.toString(), { headers: req.headers });
  } catch {
    return res.status(400).end();
  }

  switch (event.type) {
    case "message.received":
      handleInbound(event.data);
      break;
    case "contact.opted_out":
      handleOptOut(event.data);
      break;
  }

  res.status(200).end();
});

Pass the raw request body (string) to surge.webhooks.unwrap, not the parsed JSON. Signature verification requires the exact byte sequence that was signed. Use express.raw() or your framework’s equivalent. The webhook secret is passed to the Surge client constructor as webhookSigningSecret, or it can be passed per-call as the key option.

​Install and authenticate

​Your first request

​Type imports

​Pagination

​Retries and timeouts

​Error handling

​Webhooks

Install and authenticate

Your first request

Type imports

Pagination

Retries and timeouts

Error handling

Webhooks