Headlessly

The @headlessly/* SDK gives you typed access to all 35 entities across 11 product domains. Install the full SDK or pick individual domain packages.

Install

# Full SDK — all 35 entities, $ global, domain namespaces
npm install @headlessly/sdk

# Or install only what you need
npm install @headlessly/crm
npm install @headlessly/billing
npm install @headlessly/projects

Three Import Styles

Universal context (`$`)

Use $ when your code touches multiple domains in a single operation.

import { $ } from '@headlessly/sdk'

const contact = await $.Contact.create({ name: 'Alice', stage: 'Lead' })
await $.Deal.create({ title: 'Enterprise deal', contact: contact.id, value: 50000 })
await $.Subscription.create({ plan: 'pro', contact: contact.id })

Direct entity imports

Use direct imports when you work within a single domain. This is the most common style.

import { Contact, Deal } from '@headlessly/crm'
import { Subscription } from '@headlessly/billing'

const contact = await Contact.create({ name: 'Alice', stage: 'Lead' })
await Deal.create({ title: 'Enterprise deal', contact: contact.id, value: 50000 })

Domain namespace imports

Use namespaces when you want explicit domain grouping without the full $ graph.

import { crm, billing } from '@headlessly/sdk'

await crm.Contact.create({ name: 'Alice', stage: 'Lead' })
await billing.Subscription.create({ plan: 'pro', contact: 'contact_fX9bL5nRd' })

Package Hierarchy

Layer	Packages	Purpose
SDK	`@headlessly/sdk`	Full 35-entity graph, exports `$` and domain namespaces
Domain	`crm`, `billing`, `projects`, `content`, `support`, `analytics`, `marketing`, `experiments`, `platform`, plus Identity and Communication via `sdk`	Each owns a set of entities
Lifecycle	`build`, `launch`, `experiment`, `grow`, `sell`, `market`, `automate`, `scale`	Same entities, organized by startup phase
Business Model	`b2b`, `b2c`, `b2d`, `b2a`	Same entities, organized by business model
CLI	`@headlessly/cli`	CLI entry point (`npx @headlessly/cli`)

Domain-to-Entity Mapping

Domain	Package	Entities
Identity	`@headlessly/sdk`	User, ApiKey
CRM	`@headlessly/crm`	Organization, Contact, Lead, Deal, Activity, Pipeline
Billing	`@headlessly/billing`	Customer, Product, Plan, Price, Subscription, Invoice, Payment
Projects	`@headlessly/projects`	Project, Issue, Comment
Content	`@headlessly/content`	Content, Asset, Site
Support	`@headlessly/support`	Ticket
Analytics	`@headlessly/analytics`	Event, Metric, Funnel, Goal
Marketing	`@headlessly/marketing`	Campaign, Segment, Form
Experimentation	`@headlessly/experiments`	Experiment, FeatureFlag
Platform	`@headlessly/platform`	Workflow, Integration, Agent
Communication	`@headlessly/sdk`	Message

Tenant Configuration

Set the HEADLESSLY_TENANT environment variable. The SDK reads it automatically -- never pass it explicitly.

export HEADLESSLY_TENANT=my-startup

Entity IDs

All entity IDs use the format {type}_{sqid} where the suffix is generated by sqids -- short, unique, URL-safe identifiers with a built-in blocklist.

'contact_fX9bL5nRd'   // Contact
'deal_k7TmPvQx'       // Deal
'project_e5JhLzXc'    // Project
'sub_nR4wKpYm'        // Subscription

What This Section Covers

Entity Operations -- CRUD operations, custom verbs, and type signatures for all 35 entities
Queries and Filters -- MongoDB-style filters, sorting, pagination, and time travel
Event Handlers -- BEFORE and AFTER hooks, the $ context, and subscription patterns
Business Status -- The $.status() endpoint for full business-state visibility
React SDK -- Hooks and providers for React applications
Browser SDK -- Lightweight client-side analytics and feature flags
Node.js SDK -- Server-side integrations
API Client -- Low-level REST client for direct HTTP access

SDK Reference