docs menu

Clients

Every client wraps the same HTTP API: queries, documents, media, export and import, and every tool by name. Use the TypeScript client in Node.js, browsers, Deno, Bun and edge runtimes, and the Python or PHP client on servers that run those languages. For Next.js sites, the Next.js kit builds on the TypeScript client and adds caching and previews.

TypeScript#

bash
npm i @galerne/client
ts
import { createClient } from '@galerne/client'

const galerne = createClient({
  project: 'acme',
  apiUrl: 'https://api.galerne.cloud',
  token: process.env.GALERNE_TOKEN,
  perspective: 'published',
})

const { items, total } = await galerne.query({ type: 'post', order: '-_publishedAt', limit: 10 })
const about = await galerne.getDoc('about', { format: 'markdown' })
OptionWhat it sets
projectThe project slug
apiUrlThe API base URL, https://api.galerne.cloud
tokenA gal_… token. Leave it out for public reads of published content
branchThe default branch for queries and for every tool that takes one
perspectivepublished or drafts for queries
mediaUrlA public media base, when media are served from another host
fetch, headersYour own fetch, and extra headers on every request

The client has no runtime dependencies and runs wherever fetch exists.

Types from your schema#

DocsOf turns the types of galerne.config.ts into TypeScript types, so query returns typed items:

ts
import config from './galerne.config.ts'
import { createClient, type DocsOf, type InferDoc } from '@galerne/client'

type Post = InferDoc<typeof config, 'post'>

const galerne = createClient<DocsOf<typeof config>>({ project: 'acme', apiUrl: 'https://api.galerne.cloud' })
const { items } = await galerne.query({ type: 'post', limit: 10 })
items[0].title

Fields with required: true are required in the type, string fields with options become unions, localized fields become a record per language, and references become the referenced type when you pass expand. The third parameter follows the query, such as { format: 'json', lang: true, expand: { project: ['title', 'slug'] } }: see references.

Tools#

Every tool is a typed method. Inputs and outputs are generated from the tool registry:

ts
const agent = createClient({ project: 'acme', apiUrl: 'https://api.galerne.cloud', token: process.env.GALERNE_TOKEN, branch: 'agent/seo' })

await agent.tools.create_branch({ name: 'agent/seo' })
const doc = await agent.tools.get_doc({ id: 'harbours' })
await agent.tools.patch_doc({ id: 'harbours', set: { 'seo.description': 'Ten harbours of Brittany, from Douarnenez to Saint-Malo.' }, rev: doc.rev })
await agent.tools.request_review({ note: 'Meta descriptions for the travel posts' })

await agent.tools.call('get_schema')

The client's branch fills every tool input that takes one, unless the call sets it.

Media#

ts
const media = await galerne.uploadMedia(bytes, { filename: 'harbour.jpg', contentType: 'image/jpeg', alt: 'Harbour at dawn' })
galerne.mediaUrl(media.id, { w: 1200, fm: 'webp' })

Export and import#

ts
for await (const line of galerne.export({ branch: 'main' })) {
  if (line.kind === 'doc') console.log(line.id)
}

await galerne.import([{ kind: 'doc', id: 'harbours', type: 'post', values: { title: 'Harbours of Brittany' }, publish: true }], { branch: 'import/blog' })

export streams the lines of the export format. import takes an array or an async iterable and returns the import report. getSchemaConfig(branch?) returns the deployed galerne.config.ts as JSON.

Errors#

Failed calls throw a GalerneError with code, status, message, errors (the field path, rule and message of each problem) and details:

ts
import { GalerneError } from '@galerne/client'

try {
  await galerne.tools.create_doc({ branch: 'agent/seo', type: 'post', values: {} })
} catch (error) {
  if (error instanceof GalerneError && error.code === 'validation') console.log(error.errors)
}

Webhook signatures#

verifyWebhook(secret, rawBody, signatureHeader) checks the x-galerne-signature header of a webhook and refuses signatures older than 5 minutes. signWebhook makes one, for tests.

Python#

One module, standard library only, Python 3.10 or later. Copy clients/python/galerne.py from the Galerne repository into your project.

python
from galerne import Client, GalerneError, verify_webhook

client = Client("acme", token="gal_…", api_url="https://api.galerne.cloud", perspective="published")

posts = client.query(type="post", order="-_publishedAt", limit=10)
doc = client.get_doc("about", format="markdown")

agent = Client("acme", token="gal_…", api_url="https://api.galerne.cloud", branch="agent/alt-text")
agent.tools.create_branch(name="agent/alt-text")
agent.tools.update_media(id="m_7Qk2…", alt="Fishing boats in the harbour at dawn")
agent.tools.request_review(note="Alt text for 12 images")

media = client.upload_media("cover.jpg", content_type="image/jpeg", alt="The harbour at dawn")
client.media_url(media["id"], w=800, fm="webp")

client.tools.list() returns the tools the token may call. export, import_docs and verify_webhook work like their TypeScript twins. Errors raise GalerneError with code, status, message, errors and details.

PHP#

One file, curl only, PHP 8.1 or later. Copy clients/php/src/Galerne.php from the Galerne repository and require it, or add the folder as a Composer path repository.

php
require 'Galerne.php';

$client = new Galerne\Client('acme', token: 'gal_…', apiUrl: 'https://api.galerne.cloud', perspective: 'published');

$posts = $client->query(['type' => 'post', 'order' => '-_publishedAt', 'limit' => 10]);
$doc = $client->getDoc('about', format: 'markdown');

$agent = new Galerne\Client('acme', token: 'gal_…', apiUrl: 'https://api.galerne.cloud', branch: 'agent/alt-text');
$agent->tools->create_branch(['name' => 'agent/alt-text']);
$agent->tools->request_review(['note' => 'Alt text for 12 images']);

$client->tools->list() returns the tools the token may call, and $client->tools->call('get_schema') calls any tool by name.