bolbol-sdk 1.0.1 → 2.0.0

package/README.md

@@ -1,393 +1,435 @@
-# bolbol-sdk
-
-The typed client for the Bolbol API. Every app that talks to the backend - the
-Console (Next.js) and the Academy CLI (Node) today - goes through this package
-instead of calling `fetch` itself, so the shape of every request and answer is
-declared exactly once.
-
-```ts
-import { BolbolServer, HTTPError } from "bolbol-sdk";
-
-const bolbol = new BolbolServer({
-    baseUrl: "https://bolbol.io/api",
-    getToken: () => readSessionToken(),
-});
-
-const response = await bolbol.auth.user.login({ email, password });
-console.log(response.result.user.name);
-```
-
-- [Layout](#layout)
-- [Using it](#using-it)
-- [The rules](#the-rules)
-  - [1. One scope per backend controller folder](#1-one-scope-per-backend-controller-folder)
-  - [2. One method per controller](#2-one-method-per-controller)
-  - [3. Types: one per file, named by what they are](#3-types-one-per-file-named-by-what-they-are)
-  - [Translatable columns: `TranslationType`](#translatable-columns-translationtype)
-  - [4. Wire format](#4-wire-format)
-- [Adding or changing an endpoint](#adding-or-changing-an-endpoint)
-- [Checking the SDK against the API](#checking-the-sdk-against-the-api)
-- [Scripts](#scripts)
-
-## Layout
-
-```
-src/
-├── BolbolServer.ts        the entry point: builds the HTTPClient and one instance of every scope
-├── HTTPClient.ts          the only place that calls fetch
-├── HTTPError.ts           what every failed call throws
-├── index.ts               generated - re-exports everything below
-├── scope/
-│   ├── BolbolAuthScope.ts         mirrors Bolbol API src/controller/auth
-│   ├── BolbolAcademyScope.ts      mirrors Bolbol API src/controller/academy
-│   └── ...                        one file per backend controller folder
-└── type/
-    ├── UserRowType.ts             a table row
-    ├── AuthLoginRequestType.ts    what one endpoint takes
-    ├── AuthLoginResponseType.ts   what one endpoint answers
-    ├── RequestStatusEnum.ts       a database enum
-    ├── BolbolResponseType.ts      a shared shape
-    └── ...
-scripts/
-├── generate-index.mjs     writes src/index.ts
-test/
-└── api-contract.test.mjs  checks every backend controller against its SDK method
-```
-
-## Using it
-
-### Creating the server
-
-```ts
-new BolbolServer({
-    baseUrl: "https://bolbol.io/api",          // API base, mount path included, no trailing slash
-    getToken: () => token,                     // sync or async; read per request
-    timeoutMs: 30000,                          // optional
-    init: { credentials: "include", cache: "no-store" }, // optional extra fetch options
-});
-```
-
-`getToken` is asked for the session token on every call, so a
-browser app can read its cookie and a server can read its request's cookie with
-the same class. Create one `BolbolServer` per token source and reuse it.
-
-### Calling an endpoint
-
-Scopes hang off the server, one per backend controller folder, and group their
-methods by noun:
-
-```ts
-await bolbol.teacher.certificate.list(teacherUid);
-await bolbol.teacher.certificate.create(teacherUid, { name, issuer, issue_date });
-await bolbol.academy.asset.get(academyUid, assetUid);
-```
-
-Every method resolves to the API's envelope, `BolbolResponseType<T>`:
-
-```ts
-const response = await bolbol.auth.user.me();
-response.result.user;   // the controller's own output
-response.duration;      // plus the envelope metadata: id, code, status, started_at, duration
-```
-
-### Errors
-
-Every call that does not get a 2xx answer throws `HTTPError`:
-
-| Field | Meaning |
-| --- | --- |
-| `code` | The HTTP status, or `0` (`HTTPError.UNREACHABLE`) when the API could not be reached at all |
-| `message` | The API's own explanation, already localized, or an English fallback |
-| `lang` | The language of `message`, when the API said |
-| `errors` | For a validation 400: one `{ path, message }` per failed rule |
-
-```ts
-try
-{
-    await bolbol.auth.user.login(input);
-}
-catch (error)
-{
-    if (error instanceof HTTPError && error.code === 401)
-        showWrongPassword(error.message);
-    else
-        throw error;
-}
-```
-
-## The rules
-
-These keep the SDK a faithful, predictable mirror of the backend. Follow them
-for every change; `npm test` enforces them.
-
-### 1. One scope per backend controller folder
-
-- Every folder under `Bolbol API/src/controller/<folder>` has exactly one scope
-  file, `src/scope/Bolbol{Folder}Scope.ts`, where `{Folder}` is the folder name
-  in PascalCase: `auth` → `BolbolAuthScope`, `user_file` → `BolbolUserFileScope`.
-- `BolbolServer` creates **one instance of each scope** and exposes it as a
-  public readonly property named after the folder in camelCase:
-  `bolbol.auth`, `bolbol.userFile`, `bolbol.academy`.
-- A scope takes the shared `HTTPClient` in its constructor and nothing else. It
-  never calls `fetch` and never reads configuration of its own.
-- There are no scopes for anything that is not a controller folder. Helpers
-  that are not endpoints (resolving a static asset path) live on `BolbolServer`.
-
-### 2. One method per controller
-
-Every controller file in the folder gets exactly one method on its scope - no
-more, no fewer.
-
-**Name and grouping.** Methods are grouped into one object per noun, with a
-short verb as the key, so call sites read as `scope.noun.verb(...)`:
-
-```ts
-public readonly certificate = {
-    list:   (teacher_uid: string) => ...,
-    create: (teacher_uid: string, request: TeacherCertificateCreateRequestType) => ...,
-    update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType) => ...,
-    delete: (teacher_uid: string, certificate_id: number) => ...,
-};
-```
-
-Nest a noun inside another when the URL nests it (`academy.asset.version.publish`).
-
-**The marker comment.** The line right above every method is exactly:
-
-```ts
-// {METHOD} {path exactly as in the controller's info()} - {API name}
-// POST /auth/cli-login/:request_token/approve - AuthCLILoginApprove
-```
-
-`npm test` reads these markers to find the method for each controller.
-
-**The API name** identifies an endpoint everywhere in the SDK. It is every
-folder between `src/controller/` and the file, each in PascalCase, followed by
-the file name without `Controller`. The method lives on the scope of the
-top-level folder:
-
-| Controller file | API name |
-| --- | --- |
-| `auth/LoginController.ts` | `AuthLogin` |
-| `academy/AssetCreateController.ts` | `AcademyAssetCreate` |
-| `user_file/UploadController.ts` | `UserFileUpload` |
-| `teacher/UpdatePhotoController.ts` | `TeacherUpdatePhoto` |
-| `bolbol/teacher_exam/CountPendingController.ts` | `BolbolTeacherExamCountPending` (on `BolbolBolbolScope`) |
-
-**The signature mirrors the controller:**
-
-- **Path parameters** come first, as positional arguments in the order they
-  appear in the path, named exactly like the path segment (`teacher_uid`,
-  `certificate_id`) and typed like the controller's parameter schema
-  (`string` for a uid or token, `number` for a numeric id).
-- **Then one `request` argument** of type `{API name}RequestType`, when the
-  controller takes input beyond the path: its body schema for POST / PUT /
-  PATCH / DELETE, its query schema for GET. When every field of a **query** is
-  optional the argument defaults to `{}`. A body never defaults, even when all
-  its fields are optional: some updates clear every field they are not sent, so
-  sending one must be deliberate.
-- **The return type** is `Promise<BolbolResponseType<{API name}ResponseType>>`,
-  where the ResponseType is exactly what the controller's `handle()` returns.
-- The HTTP method and path are the controller's own. Interpolate path
-  parameters with `encodeURIComponent` for strings.
-
-```ts
-// PUT /teacher/:teacher_uid/certificate/:certificate_id - TeacherCertificateUpdate
-update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType): Promise<BolbolResponseType<TeacherCertificateUpdateResponseType>> =>
-    this.http.put(`/teacher/${encodeURIComponent(teacher_uid)}/certificate/${certificate_id}`, { body: request }),
-```
-
-Convenience that the backend does not have - reading a browser `File` into
-base64 before an upload, turning a path into a URL - may wrap the call, but the
-arguments that reach the wire must still be exactly the controller's.
-
-### 3. Types: one per file, named by what they are
-
-Every type the SDK exposes lives in `src/type/`, **one exported type per file,
-file named exactly after the type**. No barrels, no `types.ts`, no type declared
-inside a scope file. The suffix says what kind of type it is, and there are only
-five:
-
-| Suffix | What it is | Named after | Example |
-| --- | --- | --- | --- |
-| `RowType` | One row of a database table, as the API sends it (the backend's `Public*` projection when it has one - fields that never leave the backend, like a numeric `id` behind a `uid`, are left out) | The table, in PascalCase | `UserRowType`, `TeacherCertificateRowType`, `ItemVersionRowType` |
-| `RequestType` | The input of one endpoint - its body (or query, for a GET) | The API name | `AuthLoginRequestType`, `AcademyAssetCreateRequestType` |
-| `ResponseType` | The `result` of one endpoint | The API name | `AuthLoginResponseType`, `AcademyAssetListResponseType` |
-| `Enum` | A database or API enum, as a TypeScript `enum`. Every member is PascalCase and its value is exactly its name (`PastDue = "PastDue"`) | The backend enum without its `Database_` prefix, in PascalCase | `RequestStatusEnum` (`Database_Request_Status`), `CLILoginRequestStatusEnum` |
-| `Type` | Anything else shared by several of the above: a JSON column's shape, a generic wrapper | What it describes | `BolbolResponseType<T>`, `ListPageType<T>`, `UserSettingGeneralType` |
-
-Rules that make the table work:
-
-- **Every endpoint has its own RequestType (if it takes input) and its own
-  ResponseType** - even when two endpoints answer the same shape. Then the
-  second one is an alias, not a copy:
-
-  ```ts
-  // AcademyAssetGetResponseType.ts
-  import { AssetRowType } from "./AssetRowType";
-
-  export interface AcademyAssetGetResponseType
-  {
-      item: AssetRowType;
-  }
-  ```
-
-  ```ts
-  // AcademyAssetUpdateResponseType.ts
-  import { AcademyAssetGetResponseType } from "./AcademyAssetGetResponseType";
-
-  export type AcademyAssetUpdateResponseType = AcademyAssetGetResponseType;
-  ```
-
-  This keeps "what does endpoint X take and answer" a single lookup, and lets
-  one endpoint change shape without dragging the others along.
-- **Paged list requests extend `ListPagingType`**; paged list answers use
-  `ListPageType<Row>`, unpaged ones `ListType<Row>`.
-- **Field names are the wire names** - snake_case, exactly as the backend's Zod
-  schema or projection spells them. Never camelCase a field.
-- **Optional vs nullable follow the backend**: `.optional()` → `field?: T`,
-  `.nullable()` → `field: T | null`, `.nullish()` → `field?: T | null`.
-- Dates travel as ISO strings, so they are `string` here, never `Date`.
-- Each type file starts with a comment naming its source in the backend
-  (`// Mirrors PublicTeacher in Bolbol API src/service/teacher/TeacherPublic.ts`).
-- **The Bolbol API imports these types too.** Its `toPublic*()` projections
-  return the SDK's RowTypes / Types, and the enums whose values go over the wire
-  (`UserPolicyEnum`, `RequestStatusEnum`, `ItemTypeEnum`, ...) exist ONLY here -
-  the backend's database columns are declared from them. So for those, this
-  package is the source of truth, not a mirror: a change here changes the
-  backend's database enum and its compile-time contract. Keep every enum's keys
-  equal to its values - the backend builds columns with `Object.keys(...)`.
-
-### Translatable columns: `TranslationType`
-
-A database column whose text is read in several languages travels with a
-sibling `<column>_translations` field (the backend rule is
-`Bolbol API/rules/Translation.md`). Its shape is one shared type:
-
-```ts
-// TranslationType.ts - keyed by LanguageCodeType, the 32 hard-coded language
-// codes ("en", "fr", "fa", ...); a language with no translation is an absent key.
-export type TranslationType = { [language_code in LanguageCodeType]?: string };
-```
-
-- **RowType:** the field sits directly below its source field and is always
-  present - the backend stores `{}` for "no translations", never `null`, even
-  when the source field is nullable:
-
-  ```ts
-  name: string;
-  name_translations: TranslationType;
-  content: string | null;
-  content_translations: TranslationType;
-  ```
-
-  The map only ever holds languages that have a value - never all languages
-  with blanks.
-
-- **RequestType:** every Create / Update that takes the source field takes its
-  `<column>_translations` too, as a **patch of only the changed languages**, not
-  the whole map. Its type is the second shared type:
-
-  ```ts
-  // TranslationPatchType.ts
-  // Mirrors translationSchema() in Bolbol API src/controller/TranslationSchema.ts.
-  // Only the languages that changed: a string sets that language, null removes
-  // it, a language not listed is left as stored.
-  export type TranslationPatchType = { [language_code in LanguageCodeType]?: string | null };
-  ```
-
-  Optionality follows the Zod schema (`translationSchema(...).optional()` →
-  `name_translations?: TranslationPatchType`). Leave the field out when no
-  language changed.
-- **Flattened detail columns (`academy.item_version.details_*`)** each get their
-  own sibling `_translations` column, same convention as every other
-  translation column. Plain translations use `TranslationType` /
-  `TranslationPatchType`; choice-keyed translations (e.g.
-  `details_multiplechoice_choices_translations`) use
-  `ChoiceTranslationType<TranslationType>` on the RowType and
-  `ChoiceTranslationType<TranslationPatchType | null>` on the RequestType
-  (`null` on a choice removes all its translations). Shape and rules:
-  `Bolbol API/rules/Translation.md`, "Translating `academy.item_version` detail
-  columns".
-- Use `TranslationType` / `TranslationPatchType` by name. Never inline
-  `Record<string, string>` or `{ [k: string]: string }` in a RowType or
-  RequestType - one name is what lets every app find (and type-check) every
-  translatable field.
-- Reading one: `row.name_translations[code] ?? row.name`. The SDK has no helper
-  for this on purpose (rule 1: no non-endpoint code outside `BolbolServer`); each
-  app wraps that one expression in its own picker.
-
-### 4. Wire format
-
-- The API reads the session token from the `b-token` header. `HTTPClient` adds
-  it to **every** request whenever `getToken` returns one - public endpoints
-  included - and scopes never set it by hand. There is no per-call auth flag on
-  purpose: a public endpoint treats a missing or stale token as a guest, while a
-  valid one personalises the answer (member-only items, the owner's private
-  files, the roster of an academy you own, errors in the user's language).
-  Sending the token only to endpoints that require sign-in would silently lose
-  all of that.
-- Bodies are JSON. Query values are strings on the wire; `HTTPClient`
-  serializes numbers and booleans, repeats a key for an array, and drops
-  `null` / `undefined`.
-- Endpoints that stream bytes instead of an envelope use `this.http.blob(...)`.
-- Endpoints that take raw bytes instead of a JSON body (`UserFileContentUpload`)
-  have no body schema; their method takes a trailing `content: HTTPRawBody` (a
-  Blob, or a ReadableStream to count the bytes as they go) and sends
-  it as `{ raw: content }` (`Content-Type: application/octet-stream`, no
-  per-request timeout). In Node, pass `await fs.openAsBlob(path)` so a large
-  file streams from disk.
-
-## Adding or changing an endpoint
-
-1. Add or update the RowTypes / Enums the change needs in `src/type/`, and the
-   endpoint's RequestType / ResponseType, following rule 3.
-2. Add or update its method on the folder's scope, with the marker comment,
-   following rule 2. A new controller folder means a new
-   `Bolbol{Folder}Scope.ts` and one more property on `BolbolServer`.
-3. Bump the version and publish.
-4. In the Bolbol API: bump `bolbol-sdk`, change the controller, and make its
-   projection return the new type - the compiler shows everything that no
-   longer matches.
-5. `npm test` here (against the updated API) and `npm run build`.
-6. Bump `bolbol-sdk` in the Console and the CLI and fix their callers.
-
-## Checking the SDK against the API
-
-```
-npm test                                   # expects the API at ../Bolbol API
-BOLBOL_API_PATH=<path to Bolbol API> npm test
-```
-
-`test/api-contract.test.mjs` reads both code bases with the TypeScript compiler
-(nothing runs, no server needed) and, for **every** backend controller, checks:
-
-| # | Check |
-| --- | --- |
-| 1 | a scope method carries the controller's marker comment |
-| 2 | it lives on `Bolbol{TopFolder}Scope` |
-| 3 | the marker's path and the URL the method actually builds equal the controller's path |
-| 4 | it calls `this.http.<method>` as the controller's `info()` says (`blob` for a streamed GET) |
-| 5 | it takes `request: {API name}RequestType` exactly when the controller has a body (or, for a GET, a query) schema, sends it as `{ body: request }` / `{ query: request }`, and the RequestType's field names and optionality equal the Zod schema's |
-| 6 | it returns `Promise<BolbolResponseType<{API name}ResponseType>>` and that type exists |
-| 7 | its leading arguments are the path parameters - same names, path order, `number` / `string` as the parameter schema says |
-
-plus: no SDK method without a controller, no duplicates, and every type file
-exporting exactly one type named after the file, with one of the five suffixes.
-
-What it cannot read is the shape of a controller's *output* (`handle()` builds
-it in code), so a ResponseType's fields are still a review question - the
-marker comment and the one-file-per-type rule make that quick to answer.
-
-The parser is TypeScript 5's compiler API (dev dependency `typescript5`),
-because TypeScript 7, which builds the SDK, has no stable JavaScript API.
-
-## Scripts
-
-| Script | What it does |
-| --- | --- |
-| `npm run build` | Regenerate `src/index.ts`, then compile to `dist/` |
-| `npm run typecheck` | Regenerate `src/index.ts`, then type check without emitting |
-| `npm test` | Check every backend controller against the SDK (see above) |
-| `npm run index` | Regenerate `src/index.ts` only |
-| `npm run clean` | Remove `dist/` |
+# bolbol-sdk
+
+The typed client for the Bolbol API. Every app that talks to the backend - the
+Console (Next.js) and the Academy CLI (Node) today - goes through this package
+instead of calling `fetch` itself, so the shape of every request and answer is
+declared exactly once.
+
+```ts
+import { BolbolServer, HTTPError } from "bolbol-sdk";
+
+const bolbol = new BolbolServer({
+    baseUrl: "https://bolbol.io/api",
+    getToken: () => readSessionToken(),
+});
+
+const response = await bolbol.auth.user.login({ email, password });
+console.log(response.result.user.name);
+```
+
+- [Layout](#layout)
+- [Using it](#using-it)
+- [The rules](#the-rules)
+  - [1. One scope per backend controller folder](#1-one-scope-per-backend-controller-folder)
+  - [2. One method per controller](#2-one-method-per-controller)
+  - [3. Types: one per file, named by what they are](#3-types-one-per-file-named-by-what-they-are)
+  - [Translatable columns: `TranslationType`](#translatable-columns-translationtype)
+  - [Notes columns: `notes`, `notes_translations`, `notes_private`](#notes-columns-notes-notes_translations-notes_private)
+  - [4. Wire format](#4-wire-format)
+- [Adding or changing an endpoint](#adding-or-changing-an-endpoint)
+- [Checking the SDK against the API](#checking-the-sdk-against-the-api)
+- [Scripts](#scripts)
+
+## Layout
+
+```
+src/
+├── BolbolServer.ts        the entry point: builds the HTTPClient and one instance of every scope
+├── HTTPClient.ts          the only place that calls fetch
+├── HTTPError.ts           what every failed call throws
+├── index.ts               generated - re-exports everything below
+├── scope/
+│   ├── BolbolAuthScope.ts         mirrors Bolbol API src/controller/auth
+│   ├── BolbolAcademyScope.ts      mirrors Bolbol API src/controller/academy - the academy's collections,
+│   │                              series, items, assets, pricings and contracts
+│   ├── BolbolTeacherScope.ts      mirrors Bolbol API src/controller/teacher - the teacher profile and the
+│   │                              teacher content built on published collection versions: learning
+│   │                              kits, components, packages, pricings and contracts
+│   ├── BolbolLexemaScope.ts       mirrors Bolbol API src/controller/lexema - lexemas (dictionary
+│   │                              entries) and their senses, behind every vocabulary picker
+│   └── ...                        one file per backend controller folder
+└── type/
+    ├── UserRowType.ts             a table row
+    ├── AuthLoginRequestType.ts    what one endpoint takes
+    ├── AuthLoginResponseType.ts   what one endpoint answers
+    ├── RequestStatusEnum.ts       a database enum
+    ├── BolbolResponseType.ts      a shared shape
+    ├── ProjectTypeType.ts         a shape no endpoint sends: an Academy CLI project's bolbol.json
+    │                              `type` ("academy" | "teacher"); code compares ProjectTypeEnum
+    └── ...
+scripts/
+├── generate-index.mjs     writes src/index.ts
+test/
+└── api-contract.test.mjs  checks every backend controller against its SDK method
+```
+
+## Using it
+
+### Creating the server
+
+```ts
+new BolbolServer({
+    baseUrl: "https://bolbol.io/api",          // API base, mount path included, no trailing slash
+    getToken: () => token,                     // sync or async; read per request
+    timeoutMs: 30000,                          // optional
+    init: { credentials: "include", cache: "no-store" }, // optional extra fetch options
+});
+```
+
+`getToken` is asked for the session token on every call, so a
+browser app can read its cookie and a server can read its request's cookie with
+the same class. Create one `BolbolServer` per token source and reuse it.
+
+### Calling an endpoint
+
+Scopes hang off the server, one per backend controller folder, and group their
+methods by noun:
+
+```ts
+await bolbol.teacher.certificate.list(teacherUid);
+await bolbol.teacher.certificate.create(teacherUid, { name, issuer, issue_date });
+await bolbol.academy.asset.get(academyUid, assetUid);
+```
+
+Every method resolves to the API's envelope, `BolbolResponseType<T>`:
+
+```ts
+const response = await bolbol.auth.user.me();
+response.result.user;   // the controller's own output
+response.duration;      // plus the envelope metadata: id, code, status, started_at, duration
+```
+
+### Errors
+
+Every call that does not get a 2xx answer throws `HTTPError`:
+
+| Field | Meaning |
+| --- | --- |
+| `code` | The HTTP status, or `0` (`HTTPError.UNREACHABLE`) when the API could not be reached at all |
+| `message` | The API's own explanation, already localized, or an English fallback |
+| `lang` | The language of `message`, when the API said |
+| `errors` | For a validation 400: one `{ path, message }` per failed rule |
+
+```ts
+try
+{
+    await bolbol.auth.user.login(input);
+}
+catch (error)
+{
+    if (error instanceof HTTPError && error.code === 401)
+        showWrongPassword(error.message);
+    else
+        throw error;
+}
+```
+
+## The rules
+
+These keep the SDK a faithful, predictable mirror of the backend. Follow them
+for every change; `npm test` enforces them.
+
+### 1. One scope per backend controller folder
+
+- Every folder under `Bolbol API/src/controller/<folder>` has exactly one scope
+  file, `src/scope/Bolbol{Folder}Scope.ts`, where `{Folder}` is the folder name
+  in PascalCase: `auth` → `BolbolAuthScope`, `user_file` → `BolbolUserFileScope`.
+- `BolbolServer` creates **one instance of each scope** and exposes it as a
+  public readonly property named after the folder in camelCase:
+  `bolbol.auth`, `bolbol.userFile`, `bolbol.academy`.
+- A scope takes the shared `HTTPClient` in its constructor and nothing else. It
+  never calls `fetch` and never reads configuration of its own.
+- There are no scopes for anything that is not a controller folder. Helpers
+  that are not endpoints (resolving a static asset path) live on `BolbolServer`.
+
+### 2. One method per controller
+
+Every controller file in the folder gets exactly one method on its scope - no
+more, no fewer.
+
+**Name and grouping.** Methods are grouped into one object per noun, with a
+short verb as the key, so call sites read as `scope.noun.verb(...)`:
+
+```ts
+public readonly certificate = {
+    list:   (teacher_uid: string) => ...,
+    create: (teacher_uid: string, request: TeacherCertificateCreateRequestType) => ...,
+    update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType) => ...,
+    delete: (teacher_uid: string, certificate_id: number) => ...,
+};
+```
+
+Nest a noun inside another when the URL nests it (`academy.collection.version.publish`,
+`teacher.component.refItem.vocabulary.add`).
+
+**The marker comment.** The line right above every method is exactly:
+
+```ts
+// {METHOD} {path exactly as in the controller's info()} - {API name}
+// POST /auth/cli-login/:request_token/approve - AuthCLILoginApprove
+```
+
+`npm test` reads these markers to find the method for each controller.
+
+**The API name** identifies an endpoint everywhere in the SDK. It is every
+folder between `src/controller/` and the file, each in PascalCase, followed by
+the file name without `Controller`. The method lives on the scope of the
+top-level folder:
+
+| Controller file | API name |
+| --- | --- |
+| `auth/LoginController.ts` | `AuthLogin` |
+| `academy/AssetCreateController.ts` | `AcademyAssetCreate` |
+| `user_file/UploadController.ts` | `UserFileUpload` |
+| `teacher/UpdatePhotoController.ts` | `TeacherUpdatePhoto` |
+| `bolbol/teacher_exam/CountPendingController.ts` | `BolbolTeacherExamCountPending` (on `BolbolBolbolScope`) |
+
+**The signature mirrors the controller:**
+
+- **Path parameters** come first, as positional arguments in the order they
+  appear in the path, named exactly like the path segment (`teacher_uid`,
+  `certificate_id`) and typed like the controller's parameter schema
+  (`string` for a uid or token, `number` for a numeric id).
+- **Then one `request` argument** of type `{API name}RequestType`, when the
+  controller takes input beyond the path: its body schema for POST / PUT /
+  PATCH / DELETE, its query schema for GET. When every field of a **query** is
+  optional the argument defaults to `{}`. A body never defaults, even when all
+  its fields are optional: some updates clear every field they are not sent, so
+  sending one must be deliberate.
+- **The return type** is `Promise<BolbolResponseType<{API name}ResponseType>>`,
+  where the ResponseType is exactly what the controller's `handle()` returns.
+- The HTTP method and path are the controller's own. Interpolate path
+  parameters with `encodeURIComponent` for strings.
+
+```ts
+// PUT /teacher/:teacher_uid/certificate/:certificate_id - TeacherCertificateUpdate
+update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType): Promise<BolbolResponseType<TeacherCertificateUpdateResponseType>> =>
+    this.http.put(`/teacher/${encodeURIComponent(teacher_uid)}/certificate/${certificate_id}`, { body: request }),
+```
+
+Convenience that the backend does not have - reading a browser `File` into
+base64 before an upload, turning a path into a URL - may wrap the call, but the
+arguments that reach the wire must still be exactly the controller's.
+
+### 3. Types: one per file, named by what they are
+
+Every type the SDK exposes lives in `src/type/`, **one exported type per file,
+file named exactly after the type**. No barrels, no `types.ts`, no type declared
+inside a scope file. The suffix says what kind of type it is, and there are only
+five:
+
+| Suffix | What it is | Named after | Example |
+| --- | --- | --- | --- |
+| `RowType` | One row of a database table, as the API sends it (the backend's `Public*` projection when it has one - fields that never leave the backend, like a numeric `id` behind a `uid`, are left out) | The table, in PascalCase | `UserRowType`, `TeacherCertificateRowType`, `ItemVersionRowType` |
+| `RequestType` | The input of one endpoint - its body (or query, for a GET) | The API name | `AuthLoginRequestType`, `AcademyAssetCreateRequestType` |
+| `ResponseType` | The `result` of one endpoint | The API name | `AuthLoginResponseType`, `AcademyAssetListResponseType` |
+| `Enum` | A database or API enum, as a TypeScript `enum`. Every member is PascalCase and its value is exactly its name (`PastDue = "PastDue"`) | The backend enum without its `Database_` prefix, in PascalCase | `RequestStatusEnum` (`Database_Request_Status`), `CLILoginRequestStatusEnum` |
+| `Type` | Anything else shared by several of the above: a JSON column's shape, a generic wrapper | What it describes | `BolbolResponseType<T>`, `ListPageType<T>`, `UserSettingGeneralType` |
+
+Rules that make the table work:
+
+- **Every endpoint has its own RequestType (if it takes input) and its own
+  ResponseType** - even when two endpoints answer the same shape. Then the
+  second one is an alias, not a copy:
+
+  ```ts
+  // AcademyAssetGetResponseType.ts
+  import { AssetRowType } from "./AssetRowType";
+
+  export interface AcademyAssetGetResponseType
+  {
+      item: AssetRowType;
+  }
+  ```
+
+  ```ts
+  // AcademyAssetUpdateResponseType.ts
+  import { AcademyAssetGetResponseType } from "./AcademyAssetGetResponseType";
+
+  export type AcademyAssetUpdateResponseType = AcademyAssetGetResponseType;
+  ```
+
+  This keeps "what does endpoint X take and answer" a single lookup, and lets
+  one endpoint change shape without dragging the others along.
+- **Paged list requests extend `ListPagingType`**; paged list answers use
+  `ListPageType<Row>`, unpaged ones `ListType<Row>`.
+- **Field names are the wire names** - snake_case, exactly as the backend's Zod
+  schema or projection spells them. Never camelCase a field.
+- **Optional vs nullable follow the backend**: `.optional()` → `field?: T`,
+  `.nullable()` → `field: T | null`, `.nullish()` → `field?: T | null`.
+- Dates travel as ISO strings, so they are `string` here, never `Date`.
+- Each type file starts with a comment naming its source in the backend
+  (`// Mirrors PublicTeacher in Bolbol API src/service/teacher/TeacherPublic.ts`).
+- **The Bolbol API imports these types too.** Its `toPublic*()` projections
+  return the SDK's RowTypes / Types, and the enums whose values go over the wire
+  (`UserPolicyEnum`, `RequestStatusEnum`, `ItemTypeEnum`, ...) exist ONLY here -
+  the backend's database columns are declared from them. So for those, this
+  package is the source of truth, not a mirror: a change here changes the
+  backend's database enum and its compile-time contract. Keep every enum's keys
+  equal to its values - the backend builds columns with `Object.keys(...)`.
+
+### Translatable columns: `TranslationType`
+
+A database column whose text is read in several languages travels with a
+sibling `<column>_translations` field (the backend rule is
+`Bolbol API/rules/Translation.md`). Its shape is one shared type:
+
+```ts
+// TranslationType.ts - keyed by LanguageCodeType, the 32 hard-coded language
+// codes ("en", "fr", "fa", ...); a language with no translation is an absent key.
+export type TranslationType = { [language_code in LanguageCodeType]?: string };
+```
+
+- **RowType:** the field sits directly below its source field and is always
+  present - the backend stores `{}` for "no translations", never `null`, even
+  when the source field is nullable:
+
+  ```ts
+  name: string;
+  name_translations: TranslationType;
+  content: string | null;
+  content_translations: TranslationType;
+  ```
+
+  The map only ever holds languages that have a value - never all languages
+  with blanks.
+
+- **RequestType:** every Create / Update that takes the source field takes its
+  `<column>_translations` too, as a **patch of only the changed languages**, not
+  the whole map. Its type is the second shared type:
+
+  ```ts
+  // TranslationPatchType.ts
+  // Mirrors translationSchema() in Bolbol API src/controller/TranslationSchema.ts.
+  // Only the languages that changed: a string sets that language, null removes
+  // it, a language not listed is left as stored.
+  export type TranslationPatchType = { [language_code in LanguageCodeType]?: string | null };
+  ```
+
+  Optionality follows the Zod schema (`translationSchema(...).optional()` →
+  `name_translations?: TranslationPatchType`). Leave the field out when no
+  language changed.
+- **Flattened detail columns (`academy.item_version.details_*`)** each get their
+  own sibling `_translations` column, same convention as every other
+  translation column. Plain translations use `TranslationType` /
+  `TranslationPatchType`; choice-keyed translations (e.g.
+  `details_multiplechoice_choices_translations`) use
+  `ChoiceTranslationType<TranslationType>` on the RowType and
+  `ChoiceTranslationType<TranslationPatchType | null>` on the RequestType
+  (`null` on a choice removes all its translations). Shape and rules:
+  `Bolbol API/rules/Translation.md`, "Translating `academy.item_version` detail
+  columns".
+- **Translation overlays.** A teacher's ref asset / ref item
+  (`RefAssetRowType`, `RefItemRowType`) carries only the `_translations`
+  maps of the academy columns it translates (`title_translations`,
+  `text_translations`, the `details_*_translations`, ...), never the source
+  columns: the source text stays on the academy's row, served beside it as
+  `source` (`AssetSourceType` / `ItemSourceType`). Their update bodies send
+  the same patches. A language the overlay has wins over the academy's own
+  translation: `ref.title_translations[code] ?? source.title_translations[code] ?? source.title`.
+- Use `TranslationType` / `TranslationPatchType` by name. Never inline
+  `Record<string, string>` or `{ [k: string]: string }` in a RowType or
+  RequestType - one name is what lets every app find (and type-check) every
+  translatable field.
+- Reading one: `row.name_translations[code] ?? row.name`. The SDK has no helper
+  for this on purpose (rule 1: no non-endpoint code outside `BolbolServer`); each
+  app wraps that one expression in its own picker.
+
+### Notes columns: `notes`, `notes_translations`, `notes_private`
+
+Content rows carry three notes fields wherever the backend has the notes
+columns (the backend rule is `Bolbol API/rules/Notes.md`):
+
+```ts
+notes: string | null;                // public: previews, line items, learner views
+notes_translations: TranslationType; // its translations, like any translatable column
+notes_private: string | null;        // the owner's own notes
+```
+
+- `notes_private` appears only on the owner's shapes - the RowTypes the
+  `/academy/:academy_uid/**` and `/teacher/:teacher_uid/**` endpoints answer
+  for the caller's own rows. Learner and public shapes (`Directory*Type`,
+  `Answering*Type`) carry `notes` + `notes_translations` only, and academy
+  content shown to a teacher - who is not its owner - uses the `*SourceType`
+  aliases (`ItemSourceType = Omit<ItemRowType, "notes_private">`, ...).
+- Create / Update bodies take `notes?: string | null`,
+  `notes_translations?: TranslationPatchType` and `notes_private?: string | null`.
+- The backend's fourth column, `notes_systems`, is never sent and never
+  accepted: no type here has it.
+- Catalog, billing, request and teacher-profile rows keep their own
+  `description` - those are not content notes.
+
+### 4. Wire format
+
+- The API reads the session token from the `b-token` header. `HTTPClient` adds
+  it to **every** request whenever `getToken` returns one - public endpoints
+  included - and scopes never set it by hand. There is no per-call auth flag on
+  purpose: a public endpoint treats a missing or stale token as a guest, while a
+  valid one personalises the answer (member-only items, the owner's private
+  files, the roster of an academy you own, errors in the user's language).
+  Sending the token only to endpoints that require sign-in would silently lose
+  all of that.
+- Bodies are JSON. Query values are strings on the wire; `HTTPClient`
+  serializes numbers and booleans, repeats a key for an array, and drops
+  `null` / `undefined`.
+- Endpoints that stream bytes instead of an envelope use `this.http.blob(...)`.
+- Endpoints that take raw bytes instead of a JSON body (`UserFileContentUpload`)
+  have no body schema; their method takes a trailing `content: HTTPRawBody` (a
+  Blob, or a ReadableStream to count the bytes as they go) and sends
+  it as `{ raw: content }` (`Content-Type: application/octet-stream`, no
+  per-request timeout). In Node, pass `await fs.openAsBlob(path)` so a large
+  file streams from disk.
+
+## Adding or changing an endpoint
+
+1. Add or update the RowTypes / Enums the change needs in `src/type/`, and the
+   endpoint's RequestType / ResponseType, following rule 3.
+2. Add or update its method on the folder's scope, with the marker comment,
+   following rule 2. A new controller folder means a new
+   `Bolbol{Folder}Scope.ts` and one more property on `BolbolServer`.
+3. Bump the version and publish.
+4. In the Bolbol API: bump `bolbol-sdk`, change the controller, and make its
+   projection return the new type - the compiler shows everything that no
+   longer matches.
+5. `npm test` here (against the updated API) and `npm run build`.
+6. Bump `bolbol-sdk` in the Console and the CLI and fix their callers.
+
+## Checking the SDK against the API
+
+```
+npm test                                   # expects the API at ../Bolbol API
+BOLBOL_API_PATH=<path to Bolbol API> npm test
+```
+
+`test/api-contract.test.mjs` reads both code bases with the TypeScript compiler
+(nothing runs, no server needed) and, for **every** backend controller, checks:
+
+| # | Check |
+| --- | --- |
+| 1 | a scope method carries the controller's marker comment |
+| 2 | it lives on `Bolbol{TopFolder}Scope` |
+| 3 | the marker's path and the URL the method actually builds equal the controller's path |
+| 4 | it calls `this.http.<method>` as the controller's `info()` says (`blob` for a streamed GET) |
+| 5 | it takes `request: {API name}RequestType` exactly when the controller has a body (or, for a GET, a query) schema, sends it as `{ body: request }` / `{ query: request }`, and the RequestType's field names and optionality equal the Zod schema's |
+| 6 | it returns `Promise<BolbolResponseType<{API name}ResponseType>>` and that type exists |
+| 7 | its leading arguments are the path parameters - same names, path order, `number` / `string` as the parameter schema says |
+
+plus: no SDK method without a controller, no duplicates, and every type file
+exporting exactly one type named after the file, with one of the five suffixes.
+
+What it cannot read is the shape of a controller's *output* (`handle()` builds
+it in code), so a ResponseType's fields are still a review question - the
+marker comment and the one-file-per-type rule make that quick to answer.
+
+The parser is TypeScript 5's compiler API (dev dependency `typescript5`),
+because TypeScript 7, which builds the SDK, has no stable JavaScript API.
+
+## Scripts
+
+| Script | What it does |
+| --- | --- |
+| `npm run build` | Regenerate `src/index.ts`, then compile to `dist/` |
+| `npm run typecheck` | Regenerate `src/index.ts`, then type check without emitting |
+| `npm test` | Check every backend controller against the SDK (see above) |
+| `npm run index` | Regenerate `src/index.ts` only |
+| `npm run clean` | Remove `dist/` |