Node SDK

Official TypeScript SDK for HeadshotMarketing — programmatic access to campaigns, leads, contacts, deals, pipelines, social, ads, SEO, content, and more.

Installation

bun add @headshotmarketing/sdk
# or
npm install @headshotmarketing/sdk

Quick start

import { HeadshotmarketingSDK } from '@headshotmarketing/sdk';

// Defaults to production gateways
const sdk = new HeadshotmarketingSDK();

// Sign in
await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });

// Fetch workspaces and issue workspace token
const workspaces = await sdk.auth.fetchWorkspaces();
await sdk.auth.issueWorkspaceToken(workspaces[0].id, workspaces[0].organizationId);

// Use the SDK
const campaigns = await sdk.headshotmarketing.campaigns.list();
const leads = await sdk.headshotmarketing.leads.list();

Environment

The SDK targets production by default. Set BURDENOFF_ENV or pass explicit endpoints:

// Production (default)
const sdk = new HeadshotmarketingSDK();

// Explicit alpha
const sdkAlpha = new HeadshotmarketingSDK({
  workspaceEndpoint: 'https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql',
  globalEndpoint: 'https://alphagraphql.burdenoff.com/global/graphql',
});

Authentication

Email / Password

const auth = await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });

OAuth2 Device Code Flow

const { userCode, verificationUri, promise } = await sdk.auth.loginWithDeviceCode();
console.log(`Open ${verificationUri} and enter: ${userCode}`);
const tokens = await promise;

OAuth2 Authorization Code + PKCE

const challenge = sdk.auth.getAuthorizationUrl({
  redirectUri: 'http://localhost:8400/callback',
  scopes: ['openid', 'profile', 'email', 'offline_access'],
});
// Redirect user to challenge.url, then exchange:
const tokens = await sdk.auth.exchangeAuthCode(code, challenge.codeVerifier, challenge.redirectUri);

Client Credentials (M2M / App Auth)

const result = await sdk.auth.authenticateApp(clientId, clientSecret);

Workspace Token

await sdk.auth.issueWorkspaceToken(workspaceId, organizationId);

Modules

The SDK is a thin shell over @burdenoff/sdk-libs; each domain is mounted as a nested namespace.

Namespace	Description
sdk.auth	Sign in/up, OAuth flows, token management
sdk.headshotmarketing	HeadshotMarketing domain — campaigns, leads, contacts, deals, pipelines, social, ads, seo, content, assets, landingPages, events, influencers, audiences, workflows, aiTools, reports, dashboards
sdk.sandbox	Ephemeral, TTL-bound sandbox environments
sdk.billing	Subscriptions, invoices, plans, addons, credits, refunds
sdk.channels	Channel-based pub/sub
sdk.conversations	Conversation CRUD + settings
sdk.devportal	Apps, OAuth, API keys, webhooks, delegations
sdk.export	Export jobs, templates, downloads
sdk.files	Browse, upload, share files
sdk.groups	Group management
sdk.health	Gateway/service health probes
sdk.integrations	Third-party integrations + connections
sdk.notifications	Notification center + preferences
sdk.organizations	Organizations + invites
sdk.products	Products, shortcuts, content pages, feature flags
sdk.rbac	Permissions, role assignment
sdk.scheduler	Scheduled jobs + executions
sdk.security	Vaults, secrets
sdk.store	Marketplace — search, cart, orders, installs, publisher
sdk.support	Tickets + knowledge base
sdk.tags	Tag CRUD + tagging
sdk.tours	Onboarding tours + progress
sdk.workspaces	Workspace CRUD + members + projects + invites

Configuration

interface HeadshotmarketingSDKConfig {
  workspaceEndpoint: string;   // Workspace gateway GraphQL endpoint
  globalEndpoint: string;      // Global gateway GraphQL endpoint
  oidcIssuer?: string;         // OIDC issuer URL (derived from globalEndpoint if omitted)
  clientId?: string;           // OAuth2 client ID
  clientSecret?: string;       // OAuth2 client secret
  redirectUri?: string;        // Redirect URI for auth code flow
  apiKey?: string;             // API key authentication
  accessToken?: string;        // Pre-existing access token
  refreshToken?: string;       // Pre-existing refresh token
  workspaceToken?: string;     // Pre-existing workspace token
  timeout?: number;            // Request timeout in ms (default: 30000)
  autoRefresh?: boolean;       // Auto-refresh tokens (default: true)
  onTokenRefresh?: (tokens: TokenPair) => void | Promise<void>;
}

Error handling

import { HeadshotmarketingError, AuthenticationError, NetworkError } from '@headshotmarketing/sdk';

try {
  await sdk.auth.signIn({ username: 'invalid', password: 'invalid' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Development

git clone https://github.com/algoshred/headshotmarketing-sdk-node.git
cd headshotmarketing-sdk-node
bun install
bun run dev          # Watch mode
bun run build        # Production build
bun run test         # Run tests
bun run sanity       # All checks (format, lint, type-check, test, build)

---

• Python SDK
• CLI Reference
• Environment Selection