@airdraft/client

Typed HTTP client for the Airdraft CMS API. Use this in custom front-ends, scripts, or any environment that communicates with an Airdraft server over HTTP.

Installation

npm install @airdraft/client

Usage

import { AirdraftClient } from '@airdraft/client'

const client = new AirdraftClient({
  apiUrl: 'https://your-site.com/api/cms',
  auth: { type: 'apiKey', token: process.env.CMS_API_KEY! },
})

// List entries
const { data } = await client.entries.list('posts')

// Get single entry
const entry = await client.entries.get('posts', 'hello-world')

// Create entry
await client.entries.create('posts', { title: 'Hello', published: false })

// Update entry (optimistic lock via SHA)
await client.entries.update('posts', 'hello-world', { title: 'Updated' }, entry.meta.sha)

// Delete entry
await client.entries.delete('posts', 'hello-world', entry.meta.sha)

// Media
const items = await client.media.list()
const uploaded = await client.media.upload(file)

API

new AirdraftClient(options)

| Option | Type | Description | |---|---|---| | apiUrl | string | Base URL of the CMS API, e.g. https://example.com/api/cms (no trailing slash). | | auth? | AuthConfig | Auth method — see below. | | adminKey? | string | Admin key sent as X-Admin-Key for schema mutation routes. |

AuthConfig variants:

| Variant | When to use | |---|---| | { type: 'bearer', token } | JWT access token (browser session) | | { type: 'apiKey', token } | Static API key (server-to-server, CI) | | { type: 'embedToken', token } | Short-lived embed token (public embeds) | | { type: 'session' } | httpOnly cookie session (browser SSR — no token needed) |

AirdraftClientError

All non-2xx responses throw an AirdraftClientError:

import { AirdraftClientError } from '@airdraft/client'

try {
  await client.entries.update(...)
} catch (err) {
  if (err instanceof AirdraftClientError) {
    console.log(err.code)       // e.g. 'VALIDATION_ERROR'
    console.log(err.statusCode) // e.g. 422
    console.log(err.message)    // human-readable message
    console.log(err.details)    // Array<{ field, message }> for validation errors
  }
}

details is populated for VALIDATION_ERROR responses and contains per-field failure information.

Changelog

See CHANGELOG.md.