SDK Overview

The @the-shift/sdk package provides typed TypeScript clients for the platform services. It wraps the gateway's REST API in a small promise-based interface so you can interact with Yellow Pages, Passport, Inference, Pulse, Ledger, Stage, and Palette without constructing HTTP requests manually.

Installation

npm install @the-shift/sdk

Or with other package managers:

# Bun
bun add @the-shift/sdk

# pnpm
pnpm add @the-shift/sdk

# Yarn
yarn add @the-shift/sdk

Initialization

Create a client with your gateway URL and either an API key or delegated bearer token:

import { createClient } from "@the-shift/sdk";

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  apiKey: process.env.SHIFT_API_KEY,
});

For local development, point to your local gateway:

const client = createClient({
  gatewayUrl: "http://localhost:3000",
  apiKey: process.env.SHIFT_API_KEY,
});

Basic Usage

Every service is available as a property on the client. Methods return typed promises that resolve to the response data field from the standard envelope:

// List all services in the catalog
const services = await client.yellowpages.services.list();

// List inference providers
const providers = await client.inference.providers.list();

// Track an analytics event
await client.pulse.events.track({
  name: "user.signup",
  properties: { plan: "pro" },
});

// Create a sandbox session
const session = await client.stage.sessions.create({ name: "my-app" });

Response Handling

The SDK unwraps the platform's response envelope automatically. On success, you receive the data field directly. On error, the SDK throws a ShiftApiError with the error code and message:

import { createClient, ShiftApiError } from "@the-shift/sdk";

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  apiKey: process.env.SHIFT_API_KEY,
});

try {
  const service = await client.yellowpages.services.get("nonexistent");
} catch (err) {
  if (err instanceof ShiftApiError) {
    console.error(err.code);    // "NOT_FOUND"
    console.error(err.message); // "Service not found"
    console.error(err.status);  // 404
  }
}

Authentication

The SDK sends either:

• Authorization: Bearer <token> when token or SHIFT_AGENT_TOKEN is present
• X-API-Key: <key> when apiKey or SHIFT_API_KEY is present and no token is set

You can pass a bearer token explicitly:

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  token: process.env.SHIFT_AGENT_TOKEN,
});

Service Clients

The SDK exposes the following service clients:

Property	Service	Reference
client.yellowpages	Yellow Pages (Service Catalog)	SDK: Yellow Pages
client.passport	Passport (Identity/Auth)	SDK: Passport
client.inference	Inference (AI model routing)	SDK: Inference
client.pulse	Pulse (Analytics)	SDK: Pulse
client.ledger	Ledger (Data Governance)	SDK: Ledger
client.stage	Stage (Sandbox Execution)	SDK: Stage
client.palette	Palette (Design System)	SDK: Palette

The package also exports @the-shift/sdk/testing helpers for delegated Stage session setup and browser bootstrapping. See SDK: Testing.