bolbol-sdk 2.0.2 → 2.1.0

package/README.md

@@ -1,7 +1,8 @@
 # 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
+Console (Next.js) and the Academy CLI (Node) today, and the Academy Application
+through the CLI's services and these types - goes through this package
 instead of calling `fetch` itself, so the shape of every request and answer is
 declared exactly once.
 
@@ -25,6 +26,10 @@ console.log(response.result.user.name);
   - [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)
+  - [Owned content: `owner_type`, `owner_uid`](#owned-content-owner_type-owner_uid)
+  - [Learning scope: `exam_id`, `exam_skill_id`, `exam_skill_task_id`](#learning-scope-exam_id-exam_skill_id-exam_skill_task_id)
+  - [Products and signing](#products-and-signing)
+  - [Contracts, templates and pricing assignments](#contracts-templates-and-pricing-assignments)
   - [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)
@@ -40,11 +45,40 @@ src/
 ├── 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
+│   ├── BolbolAcademyScope.ts      mirrors Bolbol API src/controller/academy - the academy's collections
+│   │                              (each with its contract list, template slots and pricing
+│   │                              assignments), series, items, assets and pricings, its contract
+│   │                              templates and the contracts it negotiates and signs, its verification
+│   │                              profile (documents, certificates, experiences, publications,
+│   │                              requests - each, and the academy itself, Pending until Bolbol
+│   │                              approves it: AcademyStatusEnum), its authorizations, and the
+│   │                              learning content and products it owns like a teacher: the twins of
+│   │                              every teacher content endpoint
+│   ├── BolbolTeacherScope.ts      mirrors Bolbol API src/controller/teacher - the teacher profile and
+│   │                              authorizations, and the teacher's learning content: learning kits
+│   │                              and the per-exam lists of their children, the resource library
+│   │                              (folders, videos, podcasts, files, URLs) and components; its
+│   │                              products - extensions, materials with their resources, courses,
+│   │                              events and packages of products, each with its contract list, its
+│   │                              pricing assignments and (all but the package) its template slots;
+│   │                              its pricings, its contract templates and the contracts it
+│   │                              negotiates and signs
+│   ├── BolbolBolbolScope.ts       mirrors Bolbol API src/controller/bolbol - staff calls: the pending
+│   │                              queues (teacher and academy verification, teacher and academy
+│   │                              authorization requests), the contract queue (every contract, and the
+│   │                              Bolbol commission contracts staff negotiate, sign and chat on - the
+│   │                              ones waiting for Bolbol's signature counted), Bolbol's six contract
+│   │                              templates, and acting as a user
+│   ├── BolbolExtensionScope.ts    mirrors Bolbol API src/controller/extension - the public extension
+│   │                              directory, shaped like BolbolCollectionScope's
+│   ├── BolbolMaterialScope.ts     mirrors Bolbol API src/controller/material - the public material
+│   │                              directory
+│   ├── BolbolCourseScope.ts       mirrors Bolbol API src/controller/course - the public course
+│   │                              directory
+│   ├── BolbolEventScope.ts        mirrors Bolbol API src/controller/event - the public event directory
+│   │                              (only the events that have not ended, soonest first)
+│   ├── BolbolPackageScope.ts      mirrors Bolbol API src/controller/package - the public package
+│   │                              directory and what a listed package bundles
 │   ├── BolbolLexemaScope.ts       mirrors Bolbol API src/controller/lexema - lexemas (dictionary
 │   │                              entries) and their senses, behind every vocabulary picker
 │   └── ...                        one file per backend controller folder
@@ -124,6 +158,11 @@ catch (error)
 }
 ```
 
+A call its caller stops with an `AbortSignal` (a streamed upload,
+[4. Wire format](#4-wire-format)) is the one failure that is not an
+`HTTPError`: it rejects with the signal's reason, an `AbortError` for a plain
+`abort()`.
+
 ## The rules
 
 These keep the SDK a faithful, predictable mirror of the backend. Follow them
@@ -141,6 +180,14 @@ for every change; `npm test` enforces them.
   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`.
+  So does the one rule the API and every app must agree on without a call:
+  `BolbolServer.AUTHORIZATION_PERMANENT` (`"0001-01-01"`, what a `manage_*`
+  authorization column holds for a grant with no end date) and
+  `BolbolServer.authorizationStatus(value, today)`, which turns such a date
+  into an `AuthorizationStatusEnum` (both "YYYY-MM-DD", compared as strings).
+  The API fills `OwnerAuthorizationType.status` and
+  `PendingAuthorizationType.status` with it, and the Console judges a date it
+  holds with it (its authorization guard, the Bolbol authorization queue).
 
 ### 2. One method per controller
 
@@ -195,7 +242,16 @@ top-level folder:
   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.
+  sending one must be deliberate. The one exception is `request.approve`
+  (`RequestApproveRequestType`), whose body defaults to `{}`: approving
+  clears nothing, every request but an authorization one is approved with an
+  empty body, and an authorization request (`BolbolTeacherManage*` /
+  `BolbolAcademyManage*`) is approved with the `authorized_until` it grants.
+- **Last, an optional `options: { signal?: AbortSignal } = {}`** where a
+  caller must be able to stop the call - today only
+  `userFile.file.content.upload`, the streamed upload no timeout bounds
+  ([4. Wire format](#4-wire-format)). It is sent as `signal: options.signal`
+  and never reaches the controller, so `npm test` reads the arguments before it.
 - **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
@@ -208,8 +264,10 @@ update: (teacher_uid: string, certificate_id: number, request: TeacherCertificat
 ```
 
 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.
+base64 before an upload, streaming one in two calls (`userFile.file.uploadStream`:
+`content.upload`, then `create`), turning a path into a URL - may wrap the
+calls, but the arguments that reach the wire must still be exactly each
+controller's.
 
 ### 3. Types: one per file, named by what they are
 
@@ -250,7 +308,11 @@ Rules that make the table work:
   ```
 
   This keeps "what does endpoint X take and answer" a single lookup, and lets
-  one endpoint change shape without dragging the others along.
+  one endpoint change shape without dragging the others along. An academy
+  twin of a teacher content endpoint (the same sub-path under
+  `/academy/:academy_uid`, see [Owned content](#owned-content-owner_type-owner_uid))
+  aliases the teacher's types the same way:
+  `export type AcademyVideoCreateRequestType = TeacherVideoCreateRequestType;`.
 - **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
@@ -267,6 +329,28 @@ Rules that make the table work:
   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(...)`.
+- **Contract types are named `{producer}_{entity}_{deal}_{consumer}`**
+  (`ContractTypeEnum`, 26 members, Bolbol API decision P8): the producer is
+  party 1 and the consumer party 2, the entity is a `ProductTypeEnum` (none
+  on a membership) and the deal a `ContractDealTypeEnum` - Sell, Licensing,
+  Commission, Membership or Packaging, what an owner takes of a packager's
+  sales of its product. `Academy`, `Teacher`, `Bolbol` and `User` name one
+  party type each; the role words stand for party types: `Educator` is
+  whoever extends a collection, a teacher or an academy (P11 - the
+  collection's own academy signs no Educator type), `Owner` the owner of
+  the product the contract is about, `Packager` the owner of the package
+  that bundles it, and `Student` a user (`Owner_Extension_Licensing_Packager`,
+  `Educator_Collection_Commission_Academy`, `Teacher_Membership_Student`).
+  So one type accepts a set of producer types and a set of consumer types.
+  `Bolbol_` names the platform as the producer
+  (`ContractProducerTypeEnum.Bolbol`, whose uid is `""`): the six
+  `Bolbol_<Product>_Commission_Owner` types are Bolbol's commission on one
+  product, one contract per product, written by the product's create from
+  Bolbol's seeded template (P12) - the sign-up commissions and their
+  `commission_on_type` are gone. The enum's header comment holds the whole
+  matrix: each type's party types, its owner and the product it is
+  required by ([Contracts, templates and pricing
+  assignments](#contracts-templates-and-pricing-assignments)).
 
 ### Translatable columns: `TranslationType`
 
@@ -327,6 +411,11 @@ export type TranslationType = { [language_code in LanguageCodeType]?: string };
   `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`.
+- **A request party's label** (`RequestPartyType.name`, both ends of every
+  `RequestRowType`) carries `name_translations` too (decision N16): an
+  academy's stored map, so an inbox reads an academy's name in the reader's
+  language; `{}` for a teacher, a user, `Bolbol` and a party that could not
+  be resolved - a person's name is never translated.
 - 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
@@ -352,12 +441,469 @@ notes_private: string | null;        // the owner's own notes
   `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">`, ...).
+- The previews a package can show of another owner's product leave it out
+  wherever they are answered, the owner's own preview tab included:
+  `ExtensionPreviewType`, `MaterialPreviewType`, `CoursePreviewType`,
+  `EventPreviewType` and `ComponentPreviewType` with its children carry
+  their rows as `Omit<..., "notes_private">`, so one shape serves both
+  (`PackagePreviewType`, whose own `package` row is the packager's). An
+  `Omit` only narrows the type: the backend builds these shapes field by
+  field (`Bolbol API/rules/Notes.md`).
 - 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.
+  `description` - those are not content notes. Nor are a course's and an
+  event's `title`, `description`, `prerequirement` and `location`: they are
+  what a learner reads about the course or the event, each with its own
+  `_translations`, and show in previews and directories alike.
+- A product's notes sit on its version, not its identity (Bolbol API
+  decision P3): its row carries the latest version's, a directory row the
+  latest published version's, and an update writes them to the draft
+  ([Products and signing](#products-and-signing)). A contract template has
+  the trio too, unversioned.
+
+### Owned content: `owner_type`, `owner_uid`
+
+An academy and a teacher own the same kinds of learning content (learning
+kits and their children, components, resource folders and resources), the
+same products (extensions, materials, courses, events and packages - see
+[Products and signing](#products-and-signing)) and contract templates, so
+the rows that name their owner carry one pair instead of a `teacher_uid`:
+
+```ts
+owner_type: OwnerTypeEnum;  // Academy | Teacher
+owner_uid: string;          // its academy_uid or teacher_uid, by owner_type
+```
+
+- `OwnerType` (`{ type, uid }`) is the same pair as one value, for an app
+  that addresses either owner's URL family. `OwnerTypeEnum` is also a
+  pricing's `owner_type` - a pricing keeps its two uid columns
+  (`PricingRowType`) - and a notification's recipient party
+  (`MessageRowType`). The collection is the one product only an academy
+  owns: it keeps its `academy_uid`, and a shape that names any product's
+  owner (`ProductSummaryType`, a directory row's owner block) says `Academy`
+  for it. A contract template and a contract may also be Bolbol's, so their
+  `owner_type` is a `ContractProducerTypeEnum` (Academy | Teacher | Bolbol,
+  `owner_uid` `""` for Bolbol).
+- Every owner endpoint is nested under its owner: the academy twin of a
+  teacher content endpoint has the same sub-path under `/academy/:academy_uid`,
+  the same file name under `controller/academy/<same folder>/`, the API name
+  `Academy...`, the same method on `BolbolAcademyScope`, and types that
+  alias the teacher's (rule 3). Kit children, component children, ref rows
+  and material resources reach their owner through their kit / component /
+  material and carry no pair, and so do a product's pricing assignments and
+  template slots.
+- No product carries a price or a pricing setting of its own: the package's
+  `pricing_uid_package_sell_user`, the collection's four `pricing_uid_*`
+  settings and two percent shares, and the endpoints that set them
+  (`TeacherPackageUpdateSettingPricing`,
+  `AcademyCollectionUpdateSettingPricing`) are gone. What a learner pays is
+  the product's pricing assignment in force, and the terms an owner offers
+  other owners - licensing, commission, packaging - are the contract
+  templates it attaches to the product's slots ([Contracts, templates and
+  pricing assignments](#contracts-templates-and-pricing-assignments)). An
+  academy extending its own collection signs none of the collection's
+  contracts (P11).
+- What an owner may create is granted per kind by Bolbol
+  (`ManageAuthorizationEnum`, ten kinds: Collection - academy only -
+  Extension, Material, Course, Event, Package, Video, Podcast, File, Url).
+  `teacher.authorization.get` / `academy.authorization.get` answer one
+  `OwnerAuthorizationType` per kind (nine for a teacher); a gated call
+  without a grant is a 403 `AUTHORIZATION_REQUIRED` /
+  `AUTHORIZATION_EXPIRED`, and a grant is asked for with a
+  `BolbolTeacherManage*` / `BolbolAcademyManage*` request, one per kind and
+  owner (rule 1 has the date helpers). Every gated call asks exactly one
+  kind: a product's kind gates its create and its publish (Package also a
+  product add, Collection also the series, asset and item creates), a
+  resource's kind its create - and Extension gates components too: an
+  extension's component add and every component create ask Extension alone
+  (Bolbol API decision P16, which retires N14's pair of Package and
+  ComponentForCollection / ComponentForResources). Learning kits and their
+  children, a component's children, material resources, folders, pricings,
+  pricing assignments and contract templates are never gated.
+
+### Learning scope: `exam_id`, `exam_skill_id`, `exam_skill_task_id`
+
+Learning kits and their children, components, resources and materials are
+placed by a learning scope: an exam, optionally narrowed to one skill of it
+and to one task of that skill (the backend rule is
+`Bolbol API/rules/Teacher.md`, "The learning scope"). The three fields are
+spelled the same everywhere, and the two narrowing ones are nullable:
+
+```ts
+exam_id: number;
+exam_skill_id: number | null;       // null: every skill of the exam
+exam_skill_task_id: number | null;  // null: every task of the skill; never set without exam_skill_id
+```
+
+- `LearningScopeType` is the same three fields as one value - a resource
+  and a material carry a list of them (`scopes`, also what their create and
+  scope-set bodies send). A material's language sits on the material itself
+  (`language_id`, fixed at create, P4): every exam of its scopes is of that
+  language, and a material with no scope (`[]`) is listed under its language
+  only. Collection content (series, items, assets) is not scoped this way:
+  it names a real skill / task of its own, set at create.
+- Courses and events are placed one level up, by `ProductScopeType`: a
+  language, optionally narrowed to one of its exams and from there like a
+  learning scope (P5), each narrowing step needing the one before it:
+
+  ```ts
+  language_id: number;
+  exam_id: number | null;             // null: the whole language
+  exam_skill_id: number | null;       // never set without exam_id
+  exam_skill_task_id: number | null;  // never set without exam_skill_id
+  ```
+
+  A course or an event carries a list of them (`scopes`, at most 64, none
+  twice), kept on its identity: the create and `course.scope.set` /
+  `event.scope.set` replace the whole list, and no publish freezes it. A row
+  covers a target when it is of the target's language and, for an exam, of
+  that exam or of no exam (a row without an exam covers every exam of its
+  language), and each of skill / task, when the filter sends one, null or
+  equal: a level the filter leaves out is not narrowed, so `exam_id` alone
+  finds every row of the exam, whatever skill or task it narrows to. The
+  owner lists and the directories read their filters that way - the
+  material list too, over its `LearningScopeType` scopes - and a package
+  bundles a course or an event only with a row of the package's language
+  (P6).
+- The other products are placed by plain columns: a collection and a
+  package fix `language_id` + `exam_id` at create, and an extension carries
+  its collection's, read-only.
+- A kit, a kit child and a component get their pair at create and keep it:
+  no update type carries it, so an update cannot move a row to another
+  skill or task. A kit child's pair lies inside its kit's; omitted, it is the
+  kit's.
+- Kit material applies where its scope **covers** the target: the same exam,
+  and each of skill / task null or equal - a level the target leaves open
+  is covered by a null alone. The comments of the list, pin and tag types
+  say where the API reads a scope that way (`covering` on the kit list, a
+  resource's kits, the resource lists), where it matches the pair exactly
+  (the component and extension lists' skill / task filters), and where a
+  level the filter leaves out narrows nothing (the material, course and
+  event lists, above).
+- Every component is built on a published collection version - the
+  Resource type is gone, its bundles are materials now (P4) - so its create
+  takes a required `collection_version_uid` and no `exam_id` (the
+  collection's), and it is filed under a skill / task that version
+  reaches. `teacher.collection.version.reach` /
+  `academy.collection.version.reach` (decision N15) answer what one
+  published version reaches - the `LearningScopeType` of every item it pins,
+  each once - which is the very list the component create judges the pair
+  against (400 `COMPONENT_SCOPE_NOT_IN_COLLECTION`): accepted when it names
+  neither (the whole exam) or covers one entry. A form narrows its skill /
+  task pickers with it; the type's comment spells the rule out.
+- The per-exam lists of the kit children (`*ListAll`) take a required
+  `exam_id`, so their `request` has no `{}` default.
+
+### Products and signing
+
+What is sold, signed for and bundled is one of six products, named by
+`ProductTypeEnum` (the backend rule is `Bolbol API/rules/Product.md`; the
+P numbers are the decisions of `Bolbol API/Plan.html`, as implemented and
+stated in the "Decisions" section of `Bolbol API/rules/Product.md`):
+
+| Product | Owner | What it is | Language and exam |
+| --- | --- | --- | --- |
+| Collection | an academy | the academy's versioned set of series, with their items and assets | `language_id` + `exam_id`, fixed at create |
+| Extension | an educator: a teacher or an academy, the collection's own included (P11) | a versioned set of components (`extension.component`) on one published collection version - the former package (P2) | its collection's, read-only on the row |
+| Material | an academy or a teacher | a versioned bundle of the owner's library resources, pinned by material resources (`material.resource`) under copied folder names - the former Resource component and its ref resources (P4) | `language_id`, fixed at create, and `scopes: LearningScopeType[]` |
+| Course | an academy or a teacher | sessions that repeat weekly or monthly (`CourseRecurrenceEnum`) in the windows of its schedule (`course.schedule.set`) | `scopes: ProductScopeType[]` |
+| Event | an academy or a teacher | one session with a start, an end and a registration limit | `scopes: ProductScopeType[]` |
+| Package | an academy or a teacher - the packager | an ordered list of pins of published versions of the five single products, of any owner (`package.product`; P2, P6) | `language_id` + `exam_id`, fixed at create |
+
+- **Naming a product.** `ProductTypeEnum` (it replaces
+  `ContractEntityTypeEnum`) is the kind wherever a field may point at any
+  product: a contract's entity and product, a pricing assignment, a
+  template slot, a package's pins. `ProductRefType`
+  (`{ product_type, product_uid }`) names one product - a uid is unique
+  within its own kind only - in a package create's `products` and the pin
+  bodies, and the pin endpoints address a pin by
+  `:product_type/:product_uid`. `ProductSummaryType` is how a row that
+  names a product draws it (a pin's `product`): kind, uid, name with its
+  translations, the owner pair, `is_published` and `deleted` - nothing
+  private, so it reads the same for everyone.
+- **Identity and version.** A product row carries its identity - the owner
+  pair (a collection its `academy_uid`), `name` + `name_translations` (1-128
+  characters), `signed` and its language / exam or scopes - and its
+  latest version's content, flattened. The name and the scopes are edited in
+  place (P3, P5); the notes trio and every other descriptive column (a
+  course's schedule included) live on the version, so an edit lands on a
+  draft that only `<product>.version.publish` publishes. A package bundles
+  products of its language only - and of its exam too, for a collection or
+  an extension (P6) - and pins their published versions: its publish moves
+  every pin to the product's latest published version and never publishes
+  a product.
+- **`signed` and the gate** (P15). Every product row carries
+  `signed: boolean`. A create answers `{ item }` with `signed: false`,
+  having written the contracts the product requires: Bolbol's commission
+  (`Bolbol_<Product>_Commission_Owner`, Bolbol's side already signed); for
+  an extension, unless its owner is the collection's own academy, the
+  collection's three educator contracts (P11); for a package, the licensing
+  and packaging contracts of every product of another owner it bundles - a
+  collection's packaging contract only (P10). Until every contract the
+  product requires is signed by both parties, every write to it and every
+  read below its identity - versions, children, count, hierarchy, preview,
+  template slots, pricing assignments - answers 403 `PRODUCT_NOT_SIGNED`.
+  Open while unsigned: the list, the create, the get, the delete and
+  `<product>.contract.list`, and the owner's `contract` noun the product is
+  signed through. The signature that completes the last contract unlocks
+  the product (the sign answer's `product_signed`). A single product stays
+  signed; a package turns unsigned again when a product of another owner is
+  added to it, until that product's contracts are signed (P6).
+- **Product updates are patches** (P3). Every field of
+  `TeacherExtensionUpdate`, `TeacherMaterialUpdate`, `TeacherCourseUpdate`,
+  `TeacherEventUpdate`, `TeacherPackageUpdate` and `AcademyCollectionUpdate`
+  (and of the academy twins) is optional: a field left out keeps its stored
+  value, `null` clears a nullable one, the `_translations` are patches, and
+  `name` is `name?: string` - renamed, never cleared. A body that changes
+  nothing on the version (a rename alone) opens no draft.
+- **An upload never signs** (P19). A project upload creates a product
+  unsigned, as its create endpoint does, and logs whatever else its files
+  ask of it as `deferred` (`TeacherPackageUploadChangeType`,
+  `AcademyCollectionUploadActionType`): the first upload after the product
+  is signed in the Console writes it. `teacher.uid.check` /
+  `academy.uid.check` answer `signed` for the product kinds, so a client can
+  say what waits.
+
+**The common endpoints.** Every product has the same three nouns under its
+own path `X`: `/teacher/:teacher_uid/<product>/:<product>_uid` (and its
+academy twin) for the `extension`, `material`, `course`, `event` and
+`package` nouns of both owner scopes, and
+`/academy/:academy_uid/collection/:collection_uid` for `academy.collection`:
+
+| Endpoint | Method | Request | Response |
+| --- | --- | --- | --- |
+| `GET X/contract` | `contract.list` | - | `ListType<ContractRowType>`: the contracts the product requires, oldest first; open while unsigned |
+| `GET X/contract-template` | `contractTemplate.get` | - | `ProductContractTemplatesType`: every slot of the product kind once |
+| `PUT X/contract-template` | `contractTemplate.set` | `ProductContractTemplatesType` | the same, as set |
+| `GET X/pricing-assignment` | `pricingAssignment.list` | - | `ListType<PricingAssignmentRowType>` |
+| `POST X/pricing-assignment` | `pricingAssignment.create` | `PricingAssignmentBodyType` | `{ item: PricingAssignmentRowType }` |
+| `PUT X/pricing-assignment/:pricing_assignment_uid` | `pricingAssignment.update` | `PricingAssignmentBodyType` | `{ item: PricingAssignmentRowType }` |
+| `DELETE X/pricing-assignment/:pricing_assignment_uid` | `pricingAssignment.delete` | - | `{}` |
+
+A package has no template slots, so no `contractTemplate`. The API names
+follow rule 2 (`TeacherCourseContractTemplateSet`,
+`AcademyCollectionPricingAssignmentCreate`, ...), and every endpoint keeps
+its own RequestType / ResponseType, an alias of the shared type
+(`TeacherCourseContractTemplateSetRequestType = ProductContractTemplatesType`);
+the collection's are `AcademyCollection*` types of their own, since a
+teacher owns no collection to twin. [Contracts, templates and pricing
+assignments](#contracts-templates-and-pricing-assignments) explains the
+shared types.
+
+**The public directories.** Each product has one, on its own scope (rule 1):
+`collection.directory`, `extension.directory`, `material.directory`,
+`course.directory`, `event.directory` and `package.directory` - `list` and
+`profile.get`, and `profile.structure.get` on the collection (its skills and
+tasks, counted) and on the package (its pins).
+
+- The lists filter by `language_id`, `exam_id`, `owner_type` + `owner_uid`
+  and `search`, 20 rows a page by default and 60 at most (asking for more
+  is a 400); a language, exam or owner that does not exist or is not listed
+  is a 404, never a wider page. The collection's names its owner by
+  `academy_uid` instead and also takes `teacher_uid`, for the collections a
+  teacher's published extensions build on (P18); the extension's also takes
+  `collection_uid`.
+- Only signed products with a published version, of an approved owner that
+  is not winding down, are listed, so `signed` and `is_published` are true
+  on every row, and a profile answers 404 for a product the directory would
+  not list (an ended event aside, below). A row (`Directory<Product>Type`)
+  is the owner's row minus `notes_private`, at the latest published
+  version, plus `price` and the owner block a card names the owner from:
+  `owner_name`, `owner_name_translations` (an academy's map, `{}` for a
+  teacher - decision N16) and `owner_photo_user_file_uid`. On
+  `DirectoryCollectionType` they replace `academy_name`,
+  `academy_name_translations` and `academy_photo_user_file_uid`.
+- **The price rule.** `price: PriceQuoteType | null` is the product's
+  `Owner_<Product>_Sell_User` quote over its pricing assignment in force, at
+  the reader's region (a guest's at the fallback region), and `null` while
+  no assignment is in force: the app then shows no price at all
+  (instruction item 9). `null` only means that no price is drawn, not what
+  taking the product costs - that is answered where it is taken: for a
+  collection, `UserCollectionGet`'s `price`, a Free quote while no
+  assignment is in force. Reading it signs nothing.
+- **The event directory** lists only the events that have not ended
+  (`ends_at` still ahead, one under way included), soonest first by
+  `starts_at`; an ended event stays readable through its profile.
+  Every other directory lists oldest first.
+- **Series and items are read through a held collection** (P17); they are
+  no longer browsed. `series.directory.list` and `item.directory.list` take
+  a required `collection_uid`, so their `request` has no `{}` default. Every
+  series and item directory call needs a signed-in caller: the lists, the
+  series profile and its item list answer 403 `COLLECTION_NOT_HELD` unless
+  the caller holds the collection (for a series, one that runs it), owns
+  its academy or is staff, and an item profile no held collection reaches
+  answers the cut-down `locked` shape.
+
+### Contracts, templates and pricing assignments
+
+A contract is one agreement between two parties about one product (the
+backend rule is `Bolbol API/rules/Contract.md`). Only the server writes
+one, at a product's create and at a package's product add ([Products and
+signing](#products-and-signing)), with the terms of the template its slot
+holds (Bolbol's seeded one for a `Bolbol_` commission) or the defaults, and
+nothing deletes one. `ContractRowType` names its parties, what it is about,
+the product it is required by and its owner:
+
+```ts
+producer_type: ContractProducerTypeEnum;  // party 1 (P7): Academy | Teacher | Bolbol
+producer_uid: string;                     // "" for Bolbol
+consumer_type: ContractConsumerTypeEnum;  // party 2: Academy | Teacher | User
+consumer_uid: string;
+entity_type: ProductTypeEnum | null;      // what it is about; null on a membership
+entity_uid: string | null;
+product_type: ProductTypeEnum | null;     // the product that requires it: whose `signed` it gates
+product_uid: string | null;
+owner_type: ContractProducerTypeEnum;     // the one party that may edit its terms
+owner_uid: string;                        // "" for Bolbol
+```
+
+- **About and required by.** The entity and the product differ only where
+  one product signs about another: the two collection contracts an
+  extension requires (about the collection) and every contract a package
+  requires about a bundled product of another owner - its
+  `Owner_<Product>_Licensing_Packager` and
+  `Owner_<Product>_Packaging_Packager`, a collection's
+  `Owner_Collection_Packaging_Packager` alone (about the bundled product,
+  required by the package). `<product>.contract.list` answers what one
+  product requires; the owner lists narrow by `product_type` +
+  `product_uid`.
+- **The owner** is the owner of the template slot the contract was written
+  from - Bolbol on a `Bolbol_` type (P7) - and the one party that may edit
+  the terms (`contract.update`) while a signature is missing; the other
+  party only signs and chats (403 `CONTRACT_NOT_OWNER`). It is the producer
+  on every type but the two `Educator_*_Academy` ones, which the
+  collection's academy owns as their consumer. `template_uid` keeps the
+  template the terms were copied from, as provenance.
+- **The terms.** `pricing_uid` and the price quoted from it at the
+  consumer's region (`free`, `oneoff`, `subscription`, `pricing_region_id`,
+  `country_id`); the producer's share as a fraction, `percentage_numerator`
+  / `percentage_denominator` (0 <= numerator <= denominator, denominator >=
+  1; it replaces the whole-percent `percentage`); `exclusive`; and a
+  duration, `duration_unit` (`ContractDurationUnitEnum`: Day, Week, Month,
+  Year) with `duration_value`, both or neither. `contract.update` writes
+  every field, requotes the price and clears all four signature columns.
+- **Signing.** `party_1_signed_at` / `party_1_signed_from` and the
+  `party_2_` pair hold when each side signed and from which IP. Every
+  signature records its address, but the parties never see each other's: a
+  party - a teacher, an academy or a learner - reads only its own side's
+  `party_<n>_signed_from`, the other side's null. The teacher's and the
+  academy's endpoints answer a contract as the owner in the path sees it -
+  staff calling them included - and `billing.contract` as the signed-in user
+  does; only staff, on the Bolbol contract endpoints, read both addresses.
+  Both `party_<n>_signed_at` show to everyone who sees the contract.
+  `contract.sign` takes no body and stamps the caller's own side
+  (`ContractRoleEnum`: Producer is party 1, Consumer party 2), answering
+  `{ item, product_signed, message }`. A `Bolbol_` contract is written with
+  Bolbol's side signed (`party_1_signed_at` = `created_at`, no address), so
+  only the owner signs - and Bolbol again only after staff edited its terms.
+  The second signature sets `signed_at` (`is_signed`) and `expires_at` =
+  `signed_at` + the duration (null without one), and freezes the contract:
+  409 `CONTRACT_ALREADY_SIGNED` from then on, 409
+  `CONTRACT_ALREADY_SIGNED_BY_PARTY` for a side that signs twice.
+- **Exclusivity** (plan 2.5), judged on an extension create, a package
+  create and a package product add: while a product holds a signed,
+  unexpired, exclusive contract of a type, nobody else may extend or bundle
+  it under that type (409 `CONTRACT_EXCLUSIVE_HELD`); and a slot whose
+  template is exclusive refuses a new counterpart while another party holds
+  any unexpired contract of the type on it, signed or not (409
+  `CONTRACT_EXCLUSIVE_CONFLICT`).
+- **Expiry only shows** (P21): `is_expired` is computed as of the read; the
+  product keeps its pins, its listing and its sales, and nobody is notified.
+  The one thing expiry ends is an exclusive contract's hold.
+- The owners' endpoints are `teacher.contract` / `academy.contract`: `list`
+  (newest first; `role`, `type`, `product_type` + `product_uid`, `signed`),
+  `get`, `update`, `sign` and `message.list` / `message.add`. The
+  learner-phase types (`Owner_<Product>_Sell_User`, the memberships) are
+  defined, but nothing writes them yet.
+
+**Templates and slots.** A contract template (`ContractTemplateRowType`)
+holds the terms an owner offers under one contract type (`type`, fixed at
+create): `pricing_uid` (null = free), the fraction, `exclusive` and the
+duration pair, under an owner-internal `name` (no translations) with the
+notes trio. Its `owner_type` / `owner_uid` are typed like a contract's (`""`
+for Bolbol), and the template's owner owns every contract written from it.
+Which types an owner may define:
+
+| Owner | Types | Endpoints |
+| --- | --- | --- |
+| Academy | twelve: the three `Educator` collection types and the nine `Owner_*_Packager` types | `academy.contractTemplate`: list, create, get, update, delete |
+| Teacher | eight: the `Owner_*_Packager` types of extensions, materials, courses and events | `teacher.contractTemplate`: the same |
+| Bolbol | the six `Bolbol_<Product>_Commission_Owner` types, one template each, seeded from Bolbol API `seed/contract_templates.json`; `pricing_uid` always null | `contractTemplate` on `BolbolBolbolScope`: list, get, update - never created or deleted |
+
+- A product attaches at most one of its owner's templates per C slot (plan
+  2.2): `ProductContractTemplateType` is one slot,
+  `{ type, contract_template_uid | null }`, and `ProductContractTemplatesType`
+  (`{ templates }`) is what `<product>.contractTemplate.get` answers - every
+  slot of the kind once - and `.set` takes, replacing them all: a slot left
+  out or null has no template afterwards. A collection has four slots (C1
+  to C3 for an educator extending it, C4 for a packager bundling it); an
+  extension, a material, a course and an event two each
+  (`Owner_<Product>_Licensing_Packager`, `Owner_<Product>_Packaging_Packager`);
+  a package none.
+- A slot without a template - or whose template has since been deleted -
+  gives the default terms: free, 0/1, not exclusive, no duration. Templates
+  are not versioned, and deleting one is soft and never refused. A changed
+  template or slot reaches only the contracts written after it.
+
+**The chat and notifications.** The two parties of a contract chat on it
+(`contract.message.list` / `.add`), oldest first, before and after signing
+and after expiry; a message is never edited or deleted (P22).
+`ContractMessageRowType.party` is the side it was sent from (a
+`ContractRoleEnum`), `user_uid` / `user_name` the user who wrote it (a
+person's name, never translated), `text` 1-4000 characters. A signature, a
+terms edit and a chat message each notify the other party when it is an
+academy or a teacher: a `system.message` for that one recipient, written in
+the recipient's language (so its `_translations` stay `{}`). `MessageRowType`
+links it (P14): `entity_type` (`MessageEntityTypeEnum.Contract`) with
+`entity_uid` names the contract, `owner_type` with `owner_uid` the
+recipient's party, so the app opens the contract in that workspace; all four
+are null on an announcement. Bolbol has no user to notify, so an owner's
+signature or message on a `Bolbol_` contract notifies nobody (open:
+`Bolbol API/rules/Contract.md`, "Open points").
+
+**Pricing assignments and quotes.** A product is priced by putting one of
+its owner's pricings on it for a window (`PricingAssignmentRowType`:
+`pricing_uid`, `product_type` / `product_uid`, `starts_at` / `ends_at` - a
+null end is open - and `is_in_force`). Assignments are not versioned, so no
+publish is needed; they are soft-deleted and never overlap (409
+`PRICING_ASSIGNMENT_OVERLAP`), so at most one is in force. The create and
+the update both take `PricingAssignmentBodyType`, and an update replaces
+the whole assignment: an end left out is open afterwards. A pricing that a
+live assignment, a live template or a membership column names cannot be
+deleted (409 `PRICING_IN_USE`). `PriceQuoteType` is what a consumer would
+pay under one contract type right now: the contract in force when there is
+one, else what a new contract would copy - for a Sell type, from the
+product's assignment in force (P13). It carries `source`
+(`PriceQuoteSourceEnum`: Contract, Assignment - formerly Pricing - or Free),
+`pricing_assignment_uid`, and the fraction with its rounded whole
+`percentage` (0-100). Every directory row's `price` and `UserCollectionGet`'s
+`price` are such quotes.
+
+**The Bolbol queue.** Staff work on contracts through `BolbolBolbolScope`,
+behind two policies: `UserPolicyEnum.ManageContract` for `contract`,
+`ManageContractTemplate` for `contractTemplate`.
+
+- `contract.list` lists every contract, newest first, narrowed by `type`,
+  `product_type`, `owner_type`, `signed`, `bolbol_only` (the `Bolbol_` types,
+  which Bolbol owns and is party 1 of), `pending` and `search` (the uid);
+  `contract.get` reads any contract.
+- Bolbol is a party of its commission contracts only. Staff negotiate them
+  as their owner (`contract.update`: the fraction, `exclusive` and the
+  duration - no `pricing_uid`, Bolbol's contracts are free), which clears
+  Bolbol's pre-signature too; sign Bolbol's side again (`contract.sign`);
+  and chat as the Bolbol party (`contract.message.*` - 403
+  `CONTRACT_FORBIDDEN` on a contract Bolbol is no party of).
+- **Pending.** `contract.pending.count` counts the Bolbol-owned
+  contracts waiting for Bolbol's signature since a staff edit cleared it,
+  and `contract.list({ pending: true })` lists exactly those rows - the
+  Approval card's Contracts badge and the page it links to.
+- `contractTemplate.list` (the six, unpaged, in `ContractTypeEnum` order),
+  `get` and `update` edit Bolbol's templates. A template staff edited is
+  never overwritten by the seeder again, and contracts already written keep
+  their terms.
 
 ### 4. Wire format
 
@@ -374,11 +920,29 @@ notes_private: string | null;        // the owner's own notes
   `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.
+  have no body schema; their method takes `content: HTTPRawBody` (a Blob, or a
+  ReadableStream to count the bytes as they go), then rule 2's optional
+  `options`, and sends them as `{ raw: content, signal: options.signal }`
+  (`Content-Type: application/octet-stream`, no per-request timeout). In Node,
+  pass `await fs.openAsBlob(path)` so a large file streams from disk.
+  `userFile.file.uploadStream` sends a Blob this way and then makes its
+  UserFile (`UserFileCreate`): the upload for a file too large for a JSON body,
+  which carries it as base64.
+- No timeout bounds a streamed upload, so the caller's `AbortSignal` is what
+  stops one: `content.upload(content, { signal })`,
+  `uploadStream(blob, name, { is_public, signal })` (`HTTPClient` takes one
+  for any call, `HTTPRequestOptions.signal`). Nothing is sent once the signal
+  has aborted, and a later abort cuts the request off wherever it is. The call
+  rejects with the signal's reason - the platform's `AbortError` (a
+  `DOMException` named `"AbortError"`, in browsers and in Node) unless
+  `abort()` was given another - never with an `HTTPError`. What an abort
+  leaves behind: no UserFile, since `uploadStream` sends no `create` once the
+  signal has aborted; no bytes of a stream cut off part-way (the API drops its
+  temp file); and the bytes the server had already stored in full, when the
+  abort came while its answer was on the way, which stay in the caller's
+  storage as an unfinished project sync's do (`Bolbol API/rules/ProjectFiles.md`).
+  A `create` already sent runs to its end, and the call resolves with its
+  file, the caller's to delete.
 
 ## Adding or changing an endpoint
 
@@ -392,7 +956,8 @@ notes_private: string | null;        // the owner's own notes
    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.
+6. Bump `bolbol-sdk` in the Console, the CLI and the Academy Application and
+   fix their callers.
 
 ## Checking the SDK against the API
 
@@ -416,13 +981,18 @@ BOLBOL_API_PATH=<path to Bolbol API> npm test
 
 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.
+A method's trailing `options` that only carries an abort signal (rule 2) is no
+part of the contract, and the checks read the arguments before it.
 
 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.
+because TypeScript 7, which builds the SDK, has no stable JavaScript API. Both
+packages ship a `tsc` bin and `node_modules/.bin/tsc` may link either, so
+`build` and `typecheck` call TypeScript 7 by its path
+(`node node_modules/typescript/bin/tsc`).
 
 ## Scripts