BaryoDev / BaryoDev/barakoCMS

Split barako-client into a hand-written base and generated slices

Open
#182 3 comments 0 reactions 1 assignee Claimed by @arnelirobles View on GitHub
enhancement
Dominant language
C#
Stars
6
Forks
7
Avg merge
4h 42m
Merged PRs (30d)
307

Description

**Foundation.** Blocked by #181.

## The decision

**A hand-written base client, extended by generated slices.** The same architecture as the CMS itself: core is espresso, modules are what you add, and the client mirrors that so anyone who understands one understands the other.

### What stays hand-written

The plumbing that does not change and that generators produce badly:

- transport, base URL, headers
- authentication: login, refresh, logout, the token store, `recover()`
- the tenant header
- one error shape, so a failure is the same object whatever produced it
- the ergonomic helpers already earning their place: `bySlug`, `menu`, `fileUrl`

None of that is described well by an OpenAPI document, and all of it is what makes the current client pleasant to use. baryo.dev depends on it in production.

### What is generated

The typed method surface, one slice per tag. After #181 that means one slice per feature area and one per module.

```ts
const client = createClient({ baseUrl, tenant }) // base: transport, auth, tenancy
client.use(coreApi) // generated, ships in the package
client.use(accountingApi) // generated, ships with the Accounting module
client.use(myCrmApi) // generated from your own instance
```

## Why this shape rather than one generated client

| problem | answer |
|---|---|
| a third-party module can never be in a document we publish | they publish a slice, or you generate one from your instance |
| generated clients are unpleasant to use | ergonomics live in the base, not the generated part |
| a hand-written client drifts from the API | slices regenerate; the base is small enough not to drift |
| an evaluator has no instance to generate against | `npm install` gives base plus the core slice |
| calling a module the instance does not run | the method does not exist unless you registered that slice |

That last row matters most: it turns a runtime 404 into a compile error for anyone using types, with no runtime check involved.

## The current client is the starting point, not a rewrite

`@baryodev/barako-client` 0.3.0 is in production on baryo.dev. Its whole surface today is `list`, `bySlug`, `create`, `update`, `setStatus`, `history`, `menu`, `tenants`, `switch`, `fileUrl`, `login`, `logout`, `refresh`. No delete, no upload, against an API of roughly 98 operations.

The work is to separate what it already does well, which is the base, from what it does incompletely, which is the method surface, and let the latter be generated. Publish base plus generated core slice under the existing name so baryo.dev keeps working without a change.

## Open question the implementer has to settle

Whether a generated slice carries its module name explicitly, or the runtime diagnostic matches tag name to module name by assumption. Tags and module names look identical today, `Accounting` and `Accounting`, but that is a convention rather than a guarantee, and a third-party module's tag depends on its namespace.

## Blocks

`BarakoCMS.Client` for .NET, `barako client generate` in #169, and every starter template.

Design: `docs/2026-08-18-client-layer-design.md`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.