SDK Reference

The textpilot npm package provides a typed, zero-dependency client for the TextPilot API.

Installation

npm install textpilot

Client

import { TextPilot } from 'textpilot'

const tp = new TextPilot('tp_live_...', {
  baseUrl: 'https://textpilot-api.jackrgisel.workers.dev', // optional, defaults to this
})

Constructor Options

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your API key starting with `tp_live_`
`baseUrl`	`string`	`https://textpilot-api.jackrgisel.workers.dev`	API base URL

Methods

`tp.send(to, message, options?)`

Send an SMS message.

const result = await tp.send('+16195551234', 'Your code is 4821', {
  tag: 'otp',
})

Parameters:

Param	Type	Required	Description
`to`	`string`	Yes	Phone number in E.164 format (e.g., `+16195551234`)
`message`	`string`	Yes	Message body (max 1600 characters)
`options.tag`	`string`	No	Optional tag for filtering in the dashboard

Returns: SendResponse

{
  id: string        // Message ID (e.g., 'msg_...')
  status: string    // 'queued'
  to: string        // The recipient number
  createdAt: string // ISO timestamp
}

`tp.messages.list(options?)`

List messages for the authenticated project.

const result = await tp.messages.list({ limit: 20, cursor: 'msg_...' })

Parameters:

Param	Type	Required	Description
`options.limit`	`number`	No	Max messages to return (default 50)
`options.cursor`	`string`	No	Cursor for pagination

Returns: ListMessagesResponse

{
  data: Message[]   // Array of message objects
  cursor?: string   // Next page cursor (undefined if no more)
}

`tp.webhooks.set(url)`

Set a webhook URL to receive delivery status updates.

await tp.webhooks.set('https://myapp.com/webhooks/sms')

`tp.webhooks.delete()`

Remove the project's webhook.

await tp.webhooks.delete()

Error Handling

import { TextPilot, TextPilotError } from 'textpilot'

try {
  await tp.send('+1invalid', 'test')
} catch (err) {
  if (err instanceof TextPilotError) {
    console.log(err.status)  // 400
    console.log(err.message) // 'Invalid E.164 phone number'
  }
}

Error Codes

Status	Meaning
`400`	Invalid request (bad phone number, empty message, etc.)
`401`	Invalid or missing API key
`402`	Insufficient credits
`403`	Plan limit exceeded
`404`	Resource not found
`500`	Server error

Types

All types are exported from the package:

import type {
  SendResponse,
  ListMessagesResponse,
  Message,
  WebhookResponse,
  TextPilotError,
} from 'textpilot'