# mazemaze

One Melange runtime, many typed API-client surfaces, generated from one OCaml
generator. A spec (or a GraphQL schema + operations) goes in; an idiomatic,
typed client comes out in three surfaces — **Melange**, **ReScript**, and
**TypeScript (JSDoc-in-the-`.js`)** — all sourced from a single IR so they
cannot drift.

This is an npm-workspaces monorepo. The packages publish independently under
`@f3liz/`; they live here together because the clients are *generated by* the
generator, and a generator change should regenerate, build, and test every
client atomically.

## The family

| Package | Dir | What |
|---|---|---|
| `@f3liz/mazemaze-generator` | `generator/` | the OCaml generator (OpenAPI **and** GraphQL front-ends → one IR → three surfaces) |
| `@f3liz/mazemaze-api-misskey` | `api-misskey/` | typed Misskey client (+ a `Misskey.*` convenience layer) |
| `@f3liz/mazemaze-api-mastodon` | `api-mastodon/` | typed Mastodon client |
| `@f3liz/mazemaze-api-bluesky` | `api-bluesky/` | typed Bluesky (atproto `app.bsky`) client |
| `@f3liz/mazemaze` | `umbrella/` | umbrella — a stable import that re-exports a client |

The generator is the engine; each `api-*` is its output for one spec. Clients
declare the generator as a `devDependency` (`workspace:*`), so the build-time
coupling is explicit rather than relying on a sibling checkout.

## Two front-ends

- **OpenAPI** — `Openapi.lower` turns a spec into the IR. Drives misskey,
  mastodon, bluesky.
- **GraphQL** — `Graphql.lower` turns a probe's normalized output (schema +
  executable documents, resolved by graphql-js) into the same IR. Document-
  driven: each operation becomes one `POST /graphql` send; unions/interfaces
  become `__typename`-discriminated types. Targeted at hackerspub (a future
  `api-hackerspub`); see `generator/graphql-probe/`.

## Commands

```sh
npm install        # link the workspaces
npm run regen      # regenerate every client from the generator
npm run build      # build every package
npm test           # the generator's harness + each client's tests
```

Per package: `npm run build -w @f3liz/mazemaze-api-misskey`, etc. The generator
needs the opam/dune toolchain; the clients need node + the Melange runtime
(vendored per package).
