bolbol-sdk 2.0.3 → 2.2.0

package/README.md

@@ -28,6 +28,9 @@ console.log(response.result.user.name);
   - [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)
+  - [Learners: `userCollection`, `userExtension`, `userItem`](#learners-usercollection-userextension-useritem)
   - [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)
@@ -43,23 +46,46 @@ 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, its verification
+│   ├── 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 it owns like a teacher: the twins of every
-│   │                              teacher content endpoint
+│   │                              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), components (ref resources
-│   │                              included), packages, pricings and contracts
+│   │                              (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) and acting as a user
+│   │                              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
+│   ├── BolbolUserExtensionScope.ts mirrors Bolbol API src/controller/user_extension - the learner's
+│   │                              extension list, held like BolbolUserCollectionScope's library (an
+│   │                              add takes the extension's collection too), each extension switched
+│   │                              on or off, and the components of the enabled ones
 │   └── ...                        one file per backend controller folder
 └── type/
     ├── UserRowType.ts             a table row
@@ -309,12 +335,27 @@ Rules that make the table work:
   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`, `Teacher_Package_Sell_User`; a membership has no
-  entity). The `Bolbol_*` members are the one exception: `Bolbol_` names the
-  producer - the platform, `ContractProducerTypeEnum.Bolbol`, whose
-  `producer_uid` is `""` - and the rest of the name is the earning type the
-  commission applies to, the contract's `commission_on_type`
-  (`Bolbol_Teacher_Package_Sell_User` → `Teacher_Package_Sell_User`).
+  (`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`
 
@@ -357,7 +398,7 @@ export type TranslationType = { [language_code in LanguageCodeType]?: string };
   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
+- **Flattened detail columns (`collection.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.
@@ -365,7 +406,7 @@ export type TranslationType = { [language_code in LanguageCodeType]?: string };
   `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
+  `Bolbol API/rules/Translation.md`, "Translating `collection.item_version` detail
   columns".
 - **Translation overlays.** A teacher's ref asset / ref item
   (`RefAssetRowType`, `RefItemRowType`) carries only the `_translations`
@@ -405,19 +446,38 @@ 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) - and a
+  learner too: the per-item read answers `ComponentPreviewType` as it is
+  ([Learners](#learners-usercollection-userextension-useritem)). 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, packages, resource folders and
-resources - so the rows that name their owner carry one pair instead of a
-`teacher_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
@@ -426,42 +486,59 @@ 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`).
+  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 and ref rows
-  reach their owner through their kit / component and carry no pair.
-- Field names follow the owner-neutral columns: a package's sell pricing is
-  `pricing_uid_package_sell_user` (formerly
-  `pricing_uid_teacher_package_sell_user`) on the row and in the create /
-  setting bodies alike. The collection's licensing and commission settings
-  keep their names (`pricing_uid_academy_collection_licensing_teacher`, ...,
-  `teacher_percent_share_of_selling_collection`, on `CollectionRowType`):
-  they also price an academy that builds on another academy's collection
-  (`Academy_Collection_Licensing_Academy`, ...), so there `teacher` reads as
-  "licensee". An academy building on its own collection signs nothing.
+  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`: Collection - academy only - Package,
-  ComponentForCollection, ComponentForResources, Video, Podcast, File, Url,
-  Course). `teacher.authorization.get` / `academy.authorization.get`
-  answer one `OwnerAuthorizationType` per kind; a gated create without a
-  grant is a 403 `AUTHORIZATION_REQUIRED` / `AUTHORIZATION_EXPIRED`, and a
-  grant is asked for with a `BolbolTeacherManage*` / `BolbolAcademyManage*`
-  request (rule 1 has the date helpers). A component create needs two kinds:
-  Package, and ComponentForCollection or ComponentForResources by its type;
-  the 403 names the first one missing, Package first (Bolbol API decision
-  N14).
+  (`ManageAuthorizationEnum`, six kinds: Collection - academy only -
+  Extension, Material, Course, Event, Package).
+  `teacher.authorization.get` / `academy.authorization.get` answer one
+  `OwnerAuthorizationType` per kind (five 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),
+  Material also every folder and resource 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, 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 and resources 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:
+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;
@@ -470,20 +547,55 @@ exam_skill_task_id: number | null;  // null: every task of the skill; never set
 ```
 
 - `LearningScopeType` is the same three fields as one value - a resource
-  carries a list of them (`scopes`, also what its create and scope-set bodies
-  send). Collection content (series, items, assets) is not scoped this way:
+  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.
-- Material applies where its scope **covers** the target: the same exam, and
-  each of skill / task null or equal. 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) and where it matches the pair exactly (the component and
-  package lists' skill / task filters).
-- A component of a collection type is filed under a skill / task its
-  collection version reaches. `teacher.collection.version.reach` /
+- 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
@@ -493,6 +605,414 @@ exam_skill_task_id: number | null;  // null: every task of the skill; never set
 - 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, an extension also
+  its `color` and `icon` (Bolbol API decision E7) - and its latest version's
+  content, flattened. The name, the scopes and an extension's colour and
+  icon are edited in place (P3, P5, E7); 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`, for an extension
+  `UserExtensionGet`'s, each 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.
+- **A void ends a learner's sale**: `userCollection.collection.remove` and
+  `userExtension.extension.remove` void the signed contract (`voided_at`,
+  `is_voided`). The row stays as the record, and the learner's `get` still
+  answers it, but it is no longer in force: adding the product again writes
+  a new contract to sign.
+- 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`. Of the
+  learner-phase types (`Owner_<Product>_Sell_User`, the memberships) a
+  collection's and an extension's Sell are written so far
+  (`Owner_Collection_Sell_User`, `Owner_Extension_Sell_User`), each by a
+  learner's add ([Learners](#learners-usercollection-userextension-useritem)).
+
+**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. `pricingAssignment.list`
+on the owner scope itself (`academy` / `teacher`) lists those of all the
+owner's products, each row (`OwnerPricingAssignmentRowType`) naming its
+product in `product` (`ProductSummaryType`); a row is written through its
+product's own endpoints. 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 the `price` of
+`UserCollectionGet` and `UserExtensionGet` 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.
+
+### Learners: `userCollection`, `userExtension`, `userItem`
+
+What a signed-in learner takes and studies sits under `/user/...`, on three
+scopes (the backend rule is `Bolbol API/rules/Student.md`; the E numbers are
+the decisions of `Bolbol API/plan.html`). Every call acts for the session's
+user, whose uid is never sent. Besides the learner's own note and
+annotations on an item (`userItem.item.get` / `save`,
+`userItem.item.annotation`), they are:
+
+| Endpoint | Method | Request | Response |
+| --- | --- | --- | --- |
+| `GET /user/collection` | `userCollection.collection.list` | paging | `ListPageType<DirectoryCollectionType>`, the most recently added first |
+| `GET /user/collection/:collection_uid` | `userCollection.collection.get` | - | `UserCollectionRowType` |
+| `POST /user/collection` | `userCollection.collection.add` | `{ collection_uid }` | `UserCollectionRowType` |
+| `DELETE /user/collection/:collection_uid` | `userCollection.collection.remove` | - | `{ message }` |
+| `GET /user/extension` | `userExtension.extension.list` | `collection_uid?`, `enabled?`, paging | `ListPageType<UserExtensionEntryType>`, first added first |
+| `GET /user/extension/:extension_uid` | `userExtension.extension.get` | - | `UserExtensionRowType` |
+| `POST /user/extension` | `userExtension.extension.add` | `{ extension_uid }` | `UserExtensionRowType` |
+| `PUT /user/extension/:extension_uid` | `userExtension.extension.update` | `{ enabled }` | `UserExtensionRowType` |
+| `DELETE /user/extension/:extension_uid` | `userExtension.extension.remove` | - | `{ message }` |
+| `GET /user/extension/component` | `userExtension.component.list` | `collection_uid?`, `type?`, paging | `ListPageType<ExtensionVersion_ComponentVersionRowType>` |
+| `GET /user/item/:item_uid/component` | `userItem.item.component.list` | `extension_uids?`, `component_uids?` | `{ extensions: UserItemExtensionType[]; components: ComponentPreviewType[] }` |
+| `GET /user/item/rank` | `userItem.rank.list` | `collection_uid`, `component_uid`, `exam_skill_id?`, `exam_skill_task_id?`, `search?`, paging | `ListPageType<UserItemRankType>` |
+
+- **The library and the extension list.** A list row is the product itself
+  in its directory shape - a `DirectoryCollectionType`, or a
+  `DirectoryExtensionType` inside a `UserExtensionEntryType` with the
+  membership's `enabled` and `added_at` - so it renders the same wherever it
+  was found. `get` answers in one read where the learner stands with one
+  product: `added`, the `price` taking it costs and the `contract` it is
+  taken under; `UserExtensionRowType` adds `enabled` and, in `collection`,
+  the `UserCollectionRowType` of the collection the extension is built on.
+  The extension list's order, first added first, is the provider order
+  every page draws extensions in (E11).
+- **Taking a product** (E2). `add` writes the learner's Sell contract
+  (`Owner_Collection_Sell_User`, `Owner_Extension_Sell_User`), pre-signed by
+  the product's owner, free or paid; asking again answers the same state.
+  The product joins the list when the learner signs it
+  (`billing.contract.sign`), so `added` stays false until then. Nothing is
+  charged: a paid contract is granted like a free one.
+- **An extension sells its collection** (E3). Holding the collection is not
+  required to add an extension: while the learner does not hold it, the add
+  also writes the collection's contract (the row's `collection.contract`),
+  a new one recording the extension that sold it
+  (`ContractRowType.extension_uid_seller`, E25). That contract is a
+  dependency, settled first: the extension's signature answers 409
+  `USER_EXTENSION_COLLECTION_REQUIRED` until the collection is held.
+  Removing the extension leaves the collection in the library, and a
+  collection is not removed while an extension built on it is in the list,
+  enabled or not (409 `USER_COLLECTION_HAS_EXTENSIONS`): the learner removes
+  those first - `extension.list({ collection_uid })` lists them - and
+  nothing they can see cascades. A membership of an extension the list
+  cannot show (deleted by its owner, or unsigned again) leaves with the
+  collection, its signed sale voided (Bolbol API rules/Student.md). Either removal voids the signed contract ([A void ends
+  a learner's sale](#contracts-templates-and-pricing-assignments)).
+- **Enabled only** (E4). `extension.update` switches an extension on or off;
+  a re-added one starts enabled. A disabled extension stays in the list -
+  `extension.list` answers both unless `enabled` narrows it, for the one
+  place that switches it back on - but every other read of the extensions
+  in use skips it: `userExtension.component.list` (the pins of the enabled
+  extensions' latest published versions, the extensions first added first,
+  then each one's `sort_order`), the per-item read and the rank list.
+- **The per-item read** (E5). Extension content reaches a learner one item
+  at a time: `userItem.item.component.list` answers what the enabled
+  extensions change on the item - `extensions` in provider order, each
+  naming its components (`UserItemExtensionType`), and `components`, each
+  once, as the owner preview's `ComponentPreviewType` cut down to the entries
+  for this item and its asset, with the `kit` its ref items pin in the
+  learner-safe `Answering*` shapes (E6). A child applies only when it pins
+  the very version the learner is shown (`DirectoryItemType.item_version_uid`,
+  `AnsweringAssetType.asset_version_uid`), and an extension with no match is
+  left out. Only published versions are read, never a draft, and a locked
+  item answers both lists empty. `extension_uids` / `component_uids` narrow
+  it, sent as repeated keys ([4. Wire format](#4-wire-format)): an empty
+  list puts no key on the wire, so it reads as omitted.
+- **The rank list** (E16). `userItem.rank.list` lists the items of a
+  collection the learner holds (403 `COLLECTION_NOT_HELD` otherwise, as the
+  item directory answers) in one `RefItem_Rank` component's rank - one that
+  an enabled extension of the list pins, as `userExtension.component.list`
+  offers them with `type: RefItem_Rank` - the higher number first, items of
+  equal rank in the collection's order, unranked items last. A row
+  (`UserItemRankType`) is the item in its directory shape with its `rank`
+  and the series it opens in. `collection_uid` and `component_uid` are
+  required, so its `request` has no `{}` default; 20 rows a page by default,
+  60 at most.
+
 ### 4. Wire format
 
 - The API reads the session token from the `b-token` header. `HTTPClient` adds
@@ -572,6 +1092,11 @@ 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.
 
+Every check is one test case: seven per controller, and four for the whole
+run - the three above and one that the parse found controllers and methods
+at all. Against the API this version mirrors (944 controllers) that makes
+6612 cases, every one green; a new controller adds seven.
+
 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.