@front-of-house/sdk

TypeScript SDK for the Front Of House Partner API.

• Typed client for agents, channels, leads, conversations, webhooks, org, and reporting.
• Auth helper for exchanging email/password into a service token.
• Idempotency-key helper for safe retry behavior on mutations.

Install

npm install @front-of-house/sdk

Quick Start

import { FohClient, getServiceToken } from '@front-of-house/sdk'

const { token } = await getServiceToken(
  process.env.FOH_EMAIL!,
  process.env.FOH_PASSWORD!,
)

const client = new FohClient({
  token,
  orgId: process.env.FOH_ORG_ID!,
})

const { agents } = await client.agents.list()
console.log(agents.map((agent) => agent.name))

Auth and Org Scoping

Every request is sent with:

• Authorization: Bearer <token>
• x-org-id: <org-uuid> when orgId is set in FohClient

You can switch org context without re-authenticating:

const orgA = new FohClient({ token, orgId: 'org-a-uuid' })
const orgB = orgA.withOrg('org-b-uuid')

Resource Surface

• client.agents
  • create, list, get, getDraft, patchDraft, validate, publish, readiness
• client.channels
  • ensureWidget
  • connectWhatsApp, getWhatsAppStatus, verifyWhatsApp, testWhatsApp
  • connectInstagram, getInstagramStatus, verifyInstagram, testInstagram
• client.voice
  • catalog, voiceCatalog, preview, realtimeHealth
  • verify, reward, optimize, scorecard
• client.tools
  • list, testConnection, enable, disable
• client.knowledge
  • list, create, delete, reindex
• client.leads
  • handoff, updateExtraction
• client.conversations
  • reply, submitFeedback, getFeedback
• client.webhooks
  • register, list, delete, deliveries, observability
• client.org
  • listMine, create, onboarding, listMembers, invite
• client.reporting
  • listTraces

Idempotency

Use an idempotency key for retry-safe mutation requests:

import { generateIdempotencyKey } from '@front-of-house/sdk'

const key = generateIdempotencyKey('publish')
// Publish is fail-closed unless the current draft has a fresh passing
// simulation certificate. Run `foh sim certify-loop --agent agent-uuid --full`
// before calling publish from SDK-first automation.
await client.agents.publish('agent-uuid', {}, key)

Most mutating SDK methods accept idempotencyKey as the final argument.

Error Handling

The client throws FohApiError for non-2xx responses:

import { FohApiError } from '@front-of-house/sdk'

try {
  await client.agents.list()
} catch (err) {
  if (err instanceof FohApiError) {
    console.error(err.status, err.message, err.detail, err.remediation)
  }
}

OpenAPI Contract Metadata

This package exports generated OpenAPI metadata used by CI drift checks:

• PARTNER_OPENAPI_VERSION
• PARTNER_OPENAPI_OPERATIONS
• PARTNER_OPENAPI_OPERATION_PATH
• PARTNER_OPENAPI_OPERATION_METHOD
• PARTNER_OPENAPI_IDEMPOTENT_OPERATION_IDS

Security Model

• This SDK is for calling FOH Partner API endpoints from trusted server-side code.
• Do not expose service tokens in browser code.
• For FOH -> your tool endpoint authenticity verification, use @front-of-house/tool-sdk (createToolAuthMiddleware / verifyToolRequest).
• For FOH outbound webhooks, verify X-FOH-Signature-V2 with canonical ${x-foh-timestamp}.${rawBody} and enforce a replay window (recommended 300s).
• X-FOH-Signature remains available as a legacy compatibility header during receiver migration.

See:

• Docs/PARTNER_QUICKSTART.md
• Docs/PARTNER_API_VERSIONING.md
• examples/booking-tool/README.md
• packages/sdk-ts/examples/channel-onboarding-dry-run.ts