bolbol-sdk 1.0.0

package/README.md

@@ -0,0 +1,327 @@
+# bolbol-sdk
+
+The typed client for the Bolbol API. Every app that talks to the backend - the
+Console (Next.js) and the Academy CLI (Node) today - goes through this package
+instead of calling `fetch` itself, so the shape of every request and answer is
+declared exactly once.
+
+```ts
+import { BolbolServer, HTTPError } from "bolbol-sdk";
+
+const bolbol = new BolbolServer({
+    baseUrl: "https://bolbol.io/api",
+    getToken: () => readSessionToken(),
+});
+
+const response = await bolbol.auth.user.login({ email, password });
+console.log(response.result.user.name);
+```
+
+- [Layout](#layout)
+- [Using it](#using-it)
+- [The rules](#the-rules)
+  - [1. One scope per backend controller folder](#1-one-scope-per-backend-controller-folder)
+  - [2. One method per controller](#2-one-method-per-controller)
+  - [3. Types: one per file, named by what they are](#3-types-one-per-file-named-by-what-they-are)
+  - [4. Wire format](#4-wire-format)
+- [Adding or changing an endpoint](#adding-or-changing-an-endpoint)
+- [Checking the SDK against the API](#checking-the-sdk-against-the-api)
+- [Scripts](#scripts)
+
+## Layout
+
+```
+src/
+├── BolbolServer.ts        the entry point: builds the HTTPClient and one instance of every scope
+├── HTTPClient.ts          the only place that calls fetch
+├── HTTPError.ts           what every failed call throws
+├── index.ts               generated - re-exports everything below
+├── scope/
+│   ├── BolbolAuthScope.ts         mirrors Bolbol API src/controller/auth
+│   ├── BolbolAcademyScope.ts      mirrors Bolbol API src/controller/academy
+│   └── ...                        one file per backend controller folder
+└── type/
+    ├── UserRowType.ts             a table row
+    ├── AuthLoginRequestType.ts    what one endpoint takes
+    ├── AuthLoginResponseType.ts   what one endpoint answers
+    ├── RequestStatusEnum.ts       a database enum
+    ├── BolbolResponseType.ts      a shared shape
+    └── ...
+scripts/
+├── generate-index.mjs     writes src/index.ts
+test/
+└── api-contract.test.mjs  checks every backend controller against its SDK method
+```
+
+## Using it
+
+### Creating the server
+
+```ts
+new BolbolServer({
+    baseUrl: "https://bolbol.io/api",          // API base, mount path included, no trailing slash
+    getToken: () => token,                     // sync or async; read per request
+    timeoutMs: 30000,                          // optional
+    init: { credentials: "include", cache: "no-store" }, // optional extra fetch options
+});
+```
+
+`getToken` is asked for the session token on every call, so a
+browser app can read its cookie and a server can read its request's cookie with
+the same class. Create one `BolbolServer` per token source and reuse it.
+
+### Calling an endpoint
+
+Scopes hang off the server, one per backend controller folder, and group their
+methods by noun:
+
+```ts
+await bolbol.teacher.certificate.list(teacherUid);
+await bolbol.teacher.certificate.create(teacherUid, { name, issuer, issue_date });
+await bolbol.academy.asset.get(academyUid, assetUid);
+```
+
+Every method resolves to the API's envelope, `BolbolResponseType<T>`:
+
+```ts
+const response = await bolbol.auth.user.me();
+response.result.user;   // the controller's own output
+response.duration;      // plus the envelope metadata: id, code, status, started_at, duration
+```
+
+### Errors
+
+Every call that does not get a 2xx answer throws `HTTPError`:
+
+| Field | Meaning |
+| --- | --- |
+| `code` | The HTTP status, or `0` (`HTTPError.UNREACHABLE`) when the API could not be reached at all |
+| `message` | The API's own explanation, already localized, or an English fallback |
+| `lang` | The language of `message`, when the API said |
+| `errors` | For a validation 400: one `{ path, message }` per failed rule |
+
+```ts
+try
+{
+    await bolbol.auth.user.login(input);
+}
+catch (error)
+{
+    if (error instanceof HTTPError && error.code === 401)
+        showWrongPassword(error.message);
+    else
+        throw error;
+}
+```
+
+## The rules
+
+These keep the SDK a faithful, predictable mirror of the backend. Follow them
+for every change; `npm test` enforces them.
+
+### 1. One scope per backend controller folder
+
+- Every folder under `Bolbol API/src/controller/<folder>` has exactly one scope
+  file, `src/scope/Bolbol{Folder}Scope.ts`, where `{Folder}` is the folder name
+  in PascalCase: `auth` → `BolbolAuthScope`, `user_file` → `BolbolUserFileScope`.
+- `BolbolServer` creates **one instance of each scope** and exposes it as a
+  public readonly property named after the folder in camelCase:
+  `bolbol.auth`, `bolbol.userFile`, `bolbol.academy`.
+- A scope takes the shared `HTTPClient` in its constructor and nothing else. It
+  never calls `fetch` and never reads configuration of its own.
+- There are no scopes for anything that is not a controller folder. Helpers
+  that are not endpoints (resolving a static asset path) live on `BolbolServer`.
+
+### 2. One method per controller
+
+Every controller file in the folder gets exactly one method on its scope - no
+more, no fewer.
+
+**Name and grouping.** Methods are grouped into one object per noun, with a
+short verb as the key, so call sites read as `scope.noun.verb(...)`:
+
+```ts
+public readonly certificate = {
+    list:   (teacher_uid: string) => ...,
+    create: (teacher_uid: string, request: TeacherCertificateCreateRequestType) => ...,
+    update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType) => ...,
+    delete: (teacher_uid: string, certificate_id: number) => ...,
+};
+```
+
+Nest a noun inside another when the URL nests it (`academy.asset.version.publish`).
+
+**The marker comment.** The line right above every method is exactly:
+
+```ts
+// {METHOD} {path exactly as in the controller's info()} - {API name}
+// POST /auth/cli-login/:request_token/approve - AuthCLILoginApprove
+```
+
+`npm test` reads these markers to find the method for each controller.
+
+**The API name** identifies an endpoint everywhere in the SDK. It is every
+folder between `src/controller/` and the file, each in PascalCase, followed by
+the file name without `Controller`. The method lives on the scope of the
+top-level folder:
+
+| Controller file | API name |
+| --- | --- |
+| `auth/LoginController.ts` | `AuthLogin` |
+| `academy/AssetCreateController.ts` | `AcademyAssetCreate` |
+| `user_file/UploadController.ts` | `UserFileUpload` |
+| `teacher/UpdatePhotoController.ts` | `TeacherUpdatePhoto` |
+| `bolbol/teacher_exam/CountPendingController.ts` | `BolbolTeacherExamCountPending` (on `BolbolBolbolScope`) |
+
+**The signature mirrors the controller:**
+
+- **Path parameters** come first, as positional arguments in the order they
+  appear in the path, named exactly like the path segment (`teacher_uid`,
+  `certificate_id`) and typed like the controller's parameter schema
+  (`string` for a uid or token, `number` for a numeric id).
+- **Then one `request` argument** of type `{API name}RequestType`, when the
+  controller takes input beyond the path: its body schema for POST / PUT /
+  PATCH / DELETE, its query schema for GET. When every field of a **query** is
+  optional the argument defaults to `{}`. A body never defaults, even when all
+  its fields are optional: some updates clear every field they are not sent, so
+  sending one must be deliberate.
+- **The return type** is `Promise<BolbolResponseType<{API name}ResponseType>>`,
+  where the ResponseType is exactly what the controller's `handle()` returns.
+- The HTTP method and path are the controller's own. Interpolate path
+  parameters with `encodeURIComponent` for strings.
+
+```ts
+// PUT /teacher/:teacher_uid/certificate/:certificate_id - TeacherCertificateUpdate
+update: (teacher_uid: string, certificate_id: number, request: TeacherCertificateUpdateRequestType): Promise<BolbolResponseType<TeacherCertificateUpdateResponseType>> =>
+    this.http.put(`/teacher/${encodeURIComponent(teacher_uid)}/certificate/${certificate_id}`, { body: request }),
+```
+
+Convenience that the backend does not have - reading a browser `File` into
+base64 before an upload, turning a path into a URL - may wrap the call, but the
+arguments that reach the wire must still be exactly the controller's.
+
+### 3. Types: one per file, named by what they are
+
+Every type the SDK exposes lives in `src/type/`, **one exported type per file,
+file named exactly after the type**. No barrels, no `types.ts`, no type declared
+inside a scope file. The suffix says what kind of type it is, and there are only
+five:
+
+| Suffix | What it is | Named after | Example |
+| --- | --- | --- | --- |
+| `RowType` | One row of a database table, as the API sends it (the backend's `Public*` projection when it has one - fields that never leave the backend, like a numeric `id` behind a `uid`, are left out) | The table, in PascalCase | `UserRowType`, `TeacherCertificateRowType`, `ItemVersionRowType` |
+| `RequestType` | The input of one endpoint - its body (or query, for a GET) | The API name | `AuthLoginRequestType`, `AcademyAssetCreateRequestType` |
+| `ResponseType` | The `result` of one endpoint | The API name | `AuthLoginResponseType`, `AcademyAssetListResponseType` |
+| `Enum` | A database or API enum, as a TypeScript `enum`. Every member is PascalCase and its value is exactly its name (`PastDue = "PastDue"`) | The backend enum without its `Database_` prefix, in PascalCase | `RequestStatusEnum` (`Database_Request_Status`), `CLILoginRequestStatusEnum` |
+| `Type` | Anything else shared by several of the above: a JSON column's shape, a generic wrapper | What it describes | `BolbolResponseType<T>`, `ListPageType<T>`, `UserSettingGeneralType` |
+
+Rules that make the table work:
+
+- **Every endpoint has its own RequestType (if it takes input) and its own
+  ResponseType** - even when two endpoints answer the same shape. Then the
+  second one is an alias, not a copy:
+
+  ```ts
+  // AcademyAssetGetResponseType.ts
+  import { AssetRowType } from "./AssetRowType";
+
+  export interface AcademyAssetGetResponseType
+  {
+      item: AssetRowType;
+  }
+  ```
+
+  ```ts
+  // AcademyAssetUpdateResponseType.ts
+  import { AcademyAssetGetResponseType } from "./AcademyAssetGetResponseType";
+
+  export type AcademyAssetUpdateResponseType = AcademyAssetGetResponseType;
+  ```
+
+  This keeps "what does endpoint X take and answer" a single lookup, and lets
+  one endpoint change shape without dragging the others along.
+- **Paged list requests extend `ListPagingType`**; paged list answers use
+  `ListPageType<Row>`, unpaged ones `ListType<Row>`.
+- **Field names are the wire names** - snake_case, exactly as the backend's Zod
+  schema or projection spells them. Never camelCase a field.
+- **Optional vs nullable follow the backend**: `.optional()` → `field?: T`,
+  `.nullable()` → `field: T | null`, `.nullish()` → `field?: T | null`.
+- Dates travel as ISO strings, so they are `string` here, never `Date`.
+- Each type file starts with a comment naming its source in the backend
+  (`// Mirrors PublicTeacher in Bolbol API src/service/teacher/TeacherPublic.ts`).
+- **The Bolbol API imports these types too.** Its `toPublic*()` projections
+  return the SDK's RowTypes / Types, and the enums whose values go over the wire
+  (`UserPolicyEnum`, `RequestStatusEnum`, `ItemTypeEnum`, ...) exist ONLY here -
+  the backend's database columns are declared from them. So for those, this
+  package is the source of truth, not a mirror: a change here changes the
+  backend's database enum and its compile-time contract. Keep every enum's keys
+  equal to its values - the backend builds columns with `Object.keys(...)`.
+
+### 4. Wire format
+
+- The API reads the session token from the `b-token` header. `HTTPClient` adds
+  it to **every** request whenever `getToken` returns one - public endpoints
+  included - and scopes never set it by hand. There is no per-call auth flag on
+  purpose: a public endpoint treats a missing or stale token as a guest, while a
+  valid one personalises the answer (member-only items, the owner's private
+  files, the roster of an academy you own, errors in the user's language).
+  Sending the token only to endpoints that require sign-in would silently lose
+  all of that.
+- Bodies are JSON. Query values are strings on the wire; `HTTPClient`
+  serializes numbers and booleans, repeats a key for an array, and drops
+  `null` / `undefined`.
+- Endpoints that stream bytes instead of an envelope use `this.http.blob(...)`.
+
+## Adding or changing an endpoint
+
+1. Add or update the RowTypes / Enums the change needs in `src/type/`, and the
+   endpoint's RequestType / ResponseType, following rule 3.
+2. Add or update its method on the folder's scope, with the marker comment,
+   following rule 2. A new controller folder means a new
+   `Bolbol{Folder}Scope.ts` and one more property on `BolbolServer`.
+3. Bump the version and publish.
+4. In the Bolbol API: bump `bolbol-sdk`, change the controller, and make its
+   projection return the new type - the compiler shows everything that no
+   longer matches.
+5. `npm test` here (against the updated API) and `npm run build`.
+6. Bump `bolbol-sdk` in the Console and the CLI and fix their callers.
+
+## Checking the SDK against the API
+
+```
+npm test                                   # expects the API at ../Bolbol API
+BOLBOL_API_PATH=<path to Bolbol API> npm test
+```
+
+`test/api-contract.test.mjs` reads both code bases with the TypeScript compiler
+(nothing runs, no server needed) and, for **every** backend controller, checks:
+
+| # | Check |
+| --- | --- |
+| 1 | a scope method carries the controller's marker comment |
+| 2 | it lives on `Bolbol{TopFolder}Scope` |
+| 3 | the marker's path and the URL the method actually builds equal the controller's path |
+| 4 | it calls `this.http.<method>` as the controller's `info()` says (`blob` for a streamed GET) |
+| 5 | it takes `request: {API name}RequestType` exactly when the controller has a body (or, for a GET, a query) schema, sends it as `{ body: request }` / `{ query: request }`, and the RequestType's field names and optionality equal the Zod schema's |
+| 6 | it returns `Promise<BolbolResponseType<{API name}ResponseType>>` and that type exists |
+| 7 | its leading arguments are the path parameters - same names, path order, `number` / `string` as the parameter schema says |
+
+plus: no SDK method without a controller, no duplicates, and every type file
+exporting exactly one type named after the file, with one of the five suffixes.
+
+What it cannot read is the shape of a controller's *output* (`handle()` builds
+it in code), so a ResponseType's fields are still a review question - the
+marker comment and the one-file-per-type rule make that quick to answer.
+
+The parser is TypeScript 5's compiler API (dev dependency `typescript5`),
+because TypeScript 7, which builds the SDK, has no stable JavaScript API.
+
+## Scripts
+
+| Script | What it does |
+| --- | --- |
+| `npm run build` | Regenerate `src/index.ts`, then compile to `dist/` |
+| `npm run typecheck` | Regenerate `src/index.ts`, then type check without emitting |
+| `npm test` | Check every backend controller against the SDK (see above) |
+| `npm run index` | Regenerate `src/index.ts` only |
+| `npm run clean` | Remove `dist/` |

package/dist/BolbolServer.d.ts

@@ -0,0 +1,47 @@
+import { HTTPClient, HTTPClientOptions } from "./HTTPClient";
+import { BolbolAcademyScope } from "./scope/BolbolAcademyScope";
+import { BolbolAuthScope } from "./scope/BolbolAuthScope";
+import { BolbolBillingScope } from "./scope/BolbolBillingScope";
+import { BolbolBolbolScope } from "./scope/BolbolBolbolScope";
+import { BolbolCatalogScope } from "./scope/BolbolCatalogScope";
+import { BolbolCollectionScope } from "./scope/BolbolCollectionScope";
+import { BolbolHealthScope } from "./scope/BolbolHealthScope";
+import { BolbolItemScope } from "./scope/BolbolItemScope";
+import { BolbolLocationScope } from "./scope/BolbolLocationScope";
+import { BolbolMessageScope } from "./scope/BolbolMessageScope";
+import { BolbolRequestScope } from "./scope/BolbolRequestScope";
+import { BolbolSearchScope } from "./scope/BolbolSearchScope";
+import { BolbolSeriesScope } from "./scope/BolbolSeriesScope";
+import { BolbolTeacherScope } from "./scope/BolbolTeacherScope";
+import { BolbolTextScope } from "./scope/BolbolTextScope";
+import { BolbolUserCollectionScope } from "./scope/BolbolUserCollectionScope";
+import { BolbolUserFileScope } from "./scope/BolbolUserFileScope";
+import { BolbolUserItemScope } from "./scope/BolbolUserItemScope";
+import { BolbolUserScope } from "./scope/BolbolUserScope";
+import { BolbolWordScope } from "./scope/BolbolWordScope";
+export declare class BolbolServer {
+    readonly http: HTTPClient;
+    readonly academy: BolbolAcademyScope;
+    readonly auth: BolbolAuthScope;
+    readonly billing: BolbolBillingScope;
+    readonly bolbol: BolbolBolbolScope;
+    readonly catalog: BolbolCatalogScope;
+    readonly collection: BolbolCollectionScope;
+    readonly health: BolbolHealthScope;
+    readonly item: BolbolItemScope;
+    readonly location: BolbolLocationScope;
+    readonly message: BolbolMessageScope;
+    readonly request: BolbolRequestScope;
+    readonly search: BolbolSearchScope;
+    readonly series: BolbolSeriesScope;
+    readonly teacher: BolbolTeacherScope;
+    readonly text: BolbolTextScope;
+    readonly user: BolbolUserScope;
+    readonly userCollection: BolbolUserCollectionScope;
+    readonly userFile: BolbolUserFileScope;
+    readonly userItem: BolbolUserItemScope;
+    readonly word: BolbolWordScope;
+    constructor(options: HTTPClientOptions);
+    resolveUrl(path: string | null | undefined): string | null;
+}
+//# sourceMappingURL=BolbolServer.d.ts.map

package/dist/BolbolServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BolbolServer.d.ts","sourceRoot":"","sources":["../src/BolbolServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK1D,qBAAa,YAAY;IAErB,SAAgB,IAAI,EAAE,UAAU,CAAC;IAEjC,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,MAAM,EAAE,iBAAiB,CAAC;IAC1C,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,UAAU,EAAE,qBAAqB,CAAC;IAClD,SAAgB,MAAM,EAAE,iBAAiB,CAAC;IAC1C,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,QAAQ,EAAE,mBAAmB,CAAC;IAC9C,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,MAAM,EAAE,iBAAiB,CAAC;IAC1C,SAAgB,MAAM,EAAE,iBAAiB,CAAC;IAC1C,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAC5C,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,cAAc,EAAE,yBAAyB,CAAC;IAC1D,SAAgB,QAAQ,EAAE,mBAAmB,CAAC;IAC9C,SAAgB,QAAQ,EAAE,mBAAmB,CAAC;IAC9C,SAAgB,IAAI,EAAE,eAAe,CAAC;gBAEnB,OAAO,EAAE,iBAAiB;IA8BtC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI;CAQpE"}

package/dist/BolbolServer.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BolbolServer = void 0;
+const HTTPClient_1 = require("./HTTPClient");
+const BolbolAcademyScope_1 = require("./scope/BolbolAcademyScope");
+const BolbolAuthScope_1 = require("./scope/BolbolAuthScope");
+const BolbolBillingScope_1 = require("./scope/BolbolBillingScope");
+const BolbolBolbolScope_1 = require("./scope/BolbolBolbolScope");
+const BolbolCatalogScope_1 = require("./scope/BolbolCatalogScope");
+const BolbolCollectionScope_1 = require("./scope/BolbolCollectionScope");
+const BolbolHealthScope_1 = require("./scope/BolbolHealthScope");
+const BolbolItemScope_1 = require("./scope/BolbolItemScope");
+const BolbolLocationScope_1 = require("./scope/BolbolLocationScope");
+const BolbolMessageScope_1 = require("./scope/BolbolMessageScope");
+const BolbolRequestScope_1 = require("./scope/BolbolRequestScope");
+const BolbolSearchScope_1 = require("./scope/BolbolSearchScope");
+const BolbolSeriesScope_1 = require("./scope/BolbolSeriesScope");
+const BolbolTeacherScope_1 = require("./scope/BolbolTeacherScope");
+const BolbolTextScope_1 = require("./scope/BolbolTextScope");
+const BolbolUserCollectionScope_1 = require("./scope/BolbolUserCollectionScope");
+const BolbolUserFileScope_1 = require("./scope/BolbolUserFileScope");
+const BolbolUserItemScope_1 = require("./scope/BolbolUserItemScope");
+const BolbolUserScope_1 = require("./scope/BolbolUserScope");
+const BolbolWordScope_1 = require("./scope/BolbolWordScope");
+// The entry point of the SDK: one instance of every scope, all sharing one
+// HTTPClient. Each scope mirrors one folder of Bolbol API src/controller and is
+// exposed under that folder's name in camelCase (see README.md, rule 1).
+class BolbolServer {
+    http;
+    academy;
+    auth;
+    billing;
+    bolbol;
+    catalog;
+    collection;
+    health;
+    item;
+    location;
+    message;
+    request;
+    search;
+    series;
+    teacher;
+    text;
+    user;
+    userCollection;
+    userFile;
+    userItem;
+    word;
+    constructor(options) {
+        this.http = new HTTPClient_1.HTTPClient(options);
+        this.academy = new BolbolAcademyScope_1.BolbolAcademyScope(this.http);
+        this.auth = new BolbolAuthScope_1.BolbolAuthScope(this.http);
+        this.billing = new BolbolBillingScope_1.BolbolBillingScope(this.http);
+        this.bolbol = new BolbolBolbolScope_1.BolbolBolbolScope(this.http);
+        this.catalog = new BolbolCatalogScope_1.BolbolCatalogScope(this.http);
+        this.collection = new BolbolCollectionScope_1.BolbolCollectionScope(this.http);
+        this.health = new BolbolHealthScope_1.BolbolHealthScope(this.http);
+        this.item = new BolbolItemScope_1.BolbolItemScope(this.http);
+        this.location = new BolbolLocationScope_1.BolbolLocationScope(this.http);
+        this.message = new BolbolMessageScope_1.BolbolMessageScope(this.http);
+        this.request = new BolbolRequestScope_1.BolbolRequestScope(this.http);
+        this.search = new BolbolSearchScope_1.BolbolSearchScope(this.http);
+        this.series = new BolbolSeriesScope_1.BolbolSeriesScope(this.http);
+        this.teacher = new BolbolTeacherScope_1.BolbolTeacherScope(this.http);
+        this.text = new BolbolTextScope_1.BolbolTextScope(this.http);
+        this.user = new BolbolUserScope_1.BolbolUserScope(this.http);
+        this.userCollection = new BolbolUserCollectionScope_1.BolbolUserCollectionScope(this.http);
+        this.userFile = new BolbolUserFileScope_1.BolbolUserFileScope(this.http);
+        this.userItem = new BolbolUserItemScope_1.BolbolUserItemScope(this.http);
+        this.word = new BolbolWordScope_1.BolbolWordScope(this.http);
+    }
+    // Absolute URL for a path the API handed out - a static asset
+    // ("/api/static/language/en.svg"), a file's `url`. Those already carry the
+    // API's mount prefix, so they resolve against the origin. Absolute URLs
+    // pass through; null / empty give null so call sites need no guard.
+    resolveUrl(path) {
+        if (!path)
+            return null;
+        if (/^https?:\/\//i.test(path))
+            return path;
+        return `${this.http.origin}${path.startsWith("/") ? "" : "/"}${path}`;
+    }
+}
+exports.BolbolServer = BolbolServer;
+//# sourceMappingURL=BolbolServer.js.map

package/dist/BolbolServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BolbolServer.js","sourceRoot":"","sources":["../src/BolbolServer.ts"],"names":[],"mappings":";;;AAAA,6CAA6D;AAC7D,mEAAgE;AAChE,6DAA0D;AAC1D,mEAAgE;AAChE,iEAA8D;AAC9D,mEAAgE;AAChE,yEAAsE;AACtE,iEAA8D;AAC9D,6DAA0D;AAC1D,qEAAkE;AAClE,mEAAgE;AAChE,mEAAgE;AAChE,iEAA8D;AAC9D,iEAA8D;AAC9D,mEAAgE;AAChE,6DAA0D;AAC1D,iFAA8E;AAC9E,qEAAkE;AAClE,qEAAkE;AAClE,6DAA0D;AAC1D,6DAA0D;AAE1D,2EAA2E;AAC3E,gFAAgF;AAChF,yEAAyE;AACzE,MAAa,YAAY;IAEL,IAAI,CAAa;IAEjB,OAAO,CAAqB;IAC5B,IAAI,CAAkB;IACtB,OAAO,CAAqB;IAC5B,MAAM,CAAoB;IAC1B,OAAO,CAAqB;IAC5B,UAAU,CAAwB;IAClC,MAAM,CAAoB;IAC1B,IAAI,CAAkB;IACtB,QAAQ,CAAsB;IAC9B,OAAO,CAAqB;IAC5B,OAAO,CAAqB;IAC5B,MAAM,CAAoB;IAC1B,MAAM,CAAoB;IAC1B,OAAO,CAAqB;IAC5B,IAAI,CAAkB;IACtB,IAAI,CAAkB;IACtB,cAAc,CAA4B;IAC1C,QAAQ,CAAsB;IAC9B,QAAQ,CAAsB;IAC9B,IAAI,CAAkB;IAEtC,YAAmB,OAA0B;QAEzC,IAAI,CAAC,IAAI,GAAG,IAAI,uBAAU,CAAC,OAAO,CAAC,CAAC;QAEpC,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,IAAI,iCAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,IAAI,qCAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,GAAG,IAAI,6CAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,IAAI,qCAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,iCAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,GAAG,IAAI,yCAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,IAAI,qCAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,IAAI,qCAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO,GAAG,IAAI,uCAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,IAAI,iCAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,IAAI,iCAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,cAAc,GAAG,IAAI,qDAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/D,IAAI,CAAC,QAAQ,GAAG,IAAI,yCAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,IAAI,yCAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,IAAI,iCAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,8DAA8D;IAC9D,2EAA2E;IAC3E,wEAAwE;IACxE,oEAAoE;IAC7D,UAAU,CAAC,IAA+B;QAE7C,IAAI,CAAC,IAAI;YACL,OAAO,IAAI,CAAC;QAChB,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;YAC1B,OAAO,IAAI,CAAC;QAChB,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC;IAC1E,CAAC;CACJ;AA/DD,oCA+DC"}

package/dist/HTTPClient.d.ts

@@ -0,0 +1,34 @@
+import { BolbolResponseType } from "./type/BolbolResponseType";
+export type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type HTTPQueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+export type HTTPQuery = Record<string, HTTPQueryValue>;
+export interface HTTPRequestOptions {
+    body?: unknown;
+    query?: object;
+}
+export interface HTTPClientOptions {
+    baseUrl: string;
+    getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    timeoutMs?: number;
+    init?: RequestInit;
+}
+export declare class HTTPClient {
+    private readonly options;
+    readonly baseUrl: string;
+    constructor(options: HTTPClientOptions);
+    get origin(): string;
+    get<T>(path: string, options?: Omit<HTTPRequestOptions, "body">): Promise<BolbolResponseType<T>>;
+    post<T>(path: string, options?: HTTPRequestOptions): Promise<BolbolResponseType<T>>;
+    put<T>(path: string, options?: HTTPRequestOptions): Promise<BolbolResponseType<T>>;
+    patch<T>(path: string, options?: HTTPRequestOptions): Promise<BolbolResponseType<T>>;
+    delete<T>(path: string, options?: HTTPRequestOptions): Promise<BolbolResponseType<T>>;
+    blob(path: string, options?: Omit<HTTPRequestOptions, "body">): Promise<Blob>;
+    request<T>(method: HTTPMethod, path: string, options?: HTTPRequestOptions): Promise<BolbolResponseType<T>>;
+    url(path: string, query?: object): string;
+    private send;
+    private static search;
+    private static parse;
+    private static failure;
+    private static reason;
+}
+//# sourceMappingURL=HTTPClient.d.ts.map

package/dist/HTTPClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTTPClient.d.ts","sourceRoot":"","sources":["../src/HTTPClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAIrE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAErH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IAG/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAI9B,OAAO,EAAE,MAAM,CAAC;IAGhB,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAEhF,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,IAAI,CAAC,EAAE,WAAW,CAAC;CACtB;AAKD,qBAAa,UAAU;IAIA,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF3C,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEI,OAAO,EAAE,iBAAiB;IAQ9D,IAAW,MAAM,IAAI,MAAM,CAG1B;IAEM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAKpG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAKvF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAKtF,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAKxF,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAQnF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjF,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAapH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;YAMlC,IAAI;IAkDlB,OAAO,CAAC,MAAM,CAAC,MAAM;mBA2BA,KAAK;IAiB1B,OAAO,CAAC,MAAM,CAAC,OAAO;IAqBtB,OAAO,CAAC,MAAM,CAAC,MAAM;CAoBxB"}