# Clients for TypeScript, Python and PHP

> The typed TypeScript client with types inferred from galerne.config.ts, and the small Python and PHP clients: queries, documents, every tool by name, media, export, import, errors and webhook signatures.

Every client wraps the same [HTTP API](/docs/api.md): 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](/docs/nextjs.md) 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' })
```

| Option | What it sets |
|---|---|
| `project` | The project slug |
| `apiUrl` | The API base URL, `https://api.galerne.cloud` |
| `token` | A `gal_…` token. Leave it out for public reads of published content |
| `branch` | The default branch for queries and for every tool that takes one |
| `perspective` | `published` or `drafts` for queries |
| `mediaUrl` | A public media base, when media are served from another host |
| `fetch`, `headers` | Your 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](/docs/query.md#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](/docs/export.md). `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](/docs/webhooks.md#verify-the-signature) 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.
