PerspectAPI TypeScript SDK

TypeScript SDK for the Perspect public API. The current API and SDK surface is v2.

v1 Is Deprecated

Do not use /api/v1, PerspectApiClient, createPerspectApiClient, or src/client/* for new code.

The v1 API and SDK surface sunsets on 2026-06-01. New integrations must use /api/v2 through PerspectApiV2Client or createPerspectApiV2Client.

Historical v1 examples have been moved to docs/v1-deprecated/sdk-readme.md for migration reference only.

Installation

npm install perspectapi-ts-sdk

Quick Start

Use the v2 subpath when you want the import itself to make the version explicit:

import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';

const client = createPerspectApiV2Client({
  baseUrl: 'https://api.perspect.com',
  apiKey: process.env.PERSPECTAPI_API_KEY!,
});

const site = await client.sites.get('my-site');
console.log(site.id, site.name);

The top-level package also exports v2:

import { createPerspectApiV2Client } from 'perspectapi-ts-sdk';

Common Resources

const content = await client.content.list('my-site', {
  type: 'post',
  status: 'publish',
  limit: 10,
});

const products = await client.products.list('my-site', {
  published: true,
  limit: 20,
});

const contacts = await client.contacts.list('my-site', {
  limit: 20,
});

Email & Newsletters

Send raw or template-based transactional email, and manage email templates, newsletter campaigns, series, and statistics — matching the MCP tool surface.

// Raw send
await client.email.send('my-site', {
  to: '[email protected]',
  subject: 'Hello',
  html: '<p>Hi there</p>',
});

// Template-based send (renders the published `customer_support` template).
// Provide every variable the template references — including any used in its
// subject line. A blank rendered subject is rejected; pass `subject` to
// override, and `strict: true` to fail fast on any missing variable.
await client.email.send('my-site', {
  to: '[email protected]',
  template_type: 'customer_support',
  subject: 'Re: your request',
  variables: {
    support_subject: 'Re: your request',
    support_message_html: '<p>How can we help?</p>',
    support_message_text: 'How can we help?',
  },
  strict: true,
});

// Author and publish an email template
const draft = await client.emailTemplates.create('my-site', {
  template_type: 'newsletter',
  template_name: 'Monthly digest',
  subject_template: '{{campaign_subject}}',
  html_template: '<main>{{{campaign_content_html}}}</main>',
  text_template: '{{campaign_content_text}}',
});
await client.emailTemplates.publish('my-site', draft.id);

// Create and schedule a newsletter campaign.
// Scheduling requires the newsletter plan entitlement AND a key with the
// `newsletters.publish` permission; a plain draft only needs `newsletters.create`.
const campaign = await client.newsletter.createCampaign('my-site', {
  campaign_name: 'July update',
  subject: 'What shipped in July',
  markdown_content: '# Highlights\n\n- ...',
  status: 'scheduled',
  scheduled_at: '2026-07-01T09:00',
  list_ids: ['nll_...'],
});

const stats = await client.newsletter.getStatistics('my-site');

Error Handling

import { PerspectV2Error } from 'perspectapi-ts-sdk/v2';

try {
  await client.products.get('my-site', 'prod_missing');
} catch (error) {
  if (error instanceof PerspectV2Error) {
    console.error(error.type, error.code, error.message);
  }
}

Caching

import {
  createPerspectApiV2Client,
  InMemoryCacheAdapter,
} from 'perspectapi-ts-sdk';

const client = createPerspectApiV2Client({
  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
  apiKey: process.env.PERSPECTAPI_API_KEY!,
  cache: {
    adapter: new InMemoryCacheAdapter(),
    defaultTtlSeconds: 300,
  },
});

API Reference

• Current SDK entry point: perspectapi-ts-sdk/v2
• Current REST base path: /api/v2
• Public docs: https://perspect.com/docs/sdk/typescript/v2-client
• LLM docs: https://perspect.com/llms.txt

Migration

If you are maintaining existing v1 code, migrate it before 2026-06-01. v1 runtime responses include Deprecation, Sunset, Warning, Link, and X-Perspect-Deprecation-Notice headers, and v1 SDK constructors emit a warning.