@bodhiapp/reference-api-types 0.0.1

package/README.md

@@ -0,0 +1,60 @@
+# @bodhiapp/reference-api-types
+
+TypeScript **request/response types** for the [Bodhi Models Reference API](https://api.getbodhi.app) —
+the v1 live HuggingFace proxy for local (GGUF) models.
+
+**Types only.** This package ships **no runtime** — no `fetch`/`axios` wrapper, no HTTP client. It
+exports interfaces so you can type your own requests and responses. Use your existing client (e.g.
+BodhiApp's `referenceApiClient.ts`) and annotate it with these types.
+
+These types are the **single source of truth**: the API server imports the same definitions, so the
+published types cannot drift from the wire shapes.
+
+## Install
+
+```sh
+npm install @bodhiapp/reference-api-types
+```
+
+## Usage
+
+```ts
+import type {
+  Model,
+  ListModelsQuery,
+  ListModelsResponse,
+  GetModelResponse,
+  ErrorResponse,
+} from '@bodhiapp/reference-api-types'
+
+// Type a list request + response (you bring your own fetch).
+async function listModels(client: { get<T>(path: string): Promise<T> }, query: ListModelsQuery) {
+  const qs = new URLSearchParams(query as Record<string, string>).toString()
+  return client.get<ListModelsResponse>(`/api/v1/models?${qs}`)
+}
+
+// Type a single-model response (includes the quants[] table).
+async function getModel(client: { get<T>(path: string): Promise<T> }, ns: string, repo: string) {
+  return client.get<GetModelResponse>(`/api/v1/models/huggingface/${ns}/${repo}`)
+}
+```
+
+## Exports
+
+| Type | For |
+|---|---|
+| `Model`, `Quant` | the model DTO + its quantization entries |
+| `ListModelsQuery` | query params for `GET /api/v1/models` |
+| `ListModelsResponse` | response of the list endpoint |
+| `GetModelQuery`, `GetModelResponse` | the single-model endpoint |
+| `ErrorResponse`, `ErrorCode` | the error envelope |
+| `ModelType`, `ModelSource`, `Specialisation`, `SortKey`, `SortOrder` | the supported enum values |
+
+For the full API contract (semantics, auth, pagination, recipes) see `docs/functional/` in the
+[api-getbodhi-app](https://github.com/BodhiSearch/api-getbodhi-app) repo, or the live OpenAPI doc at
+`/api/openapi.json` (Swagger UI at `/api/doc`).
+
+## Release
+
+Published from local via `just publish-api-types` (version = next patch from npmjs). See the repo's
+`justfile` and `scripts/release.sh`.

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Request/response types for the Bodhi Models Reference API — the v1 live HuggingFace proxy for
+ * local (GGUF) models. Types only: this package ships no runtime, no fetch/HTTP client. Import these
+ * to type your own requests/responses.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the API's wire shapes — the API worker imports the same
+ * types, so the published types and the server cannot drift.
+ */
+/** v1 supports only GGUF. */
+export type ModelType = 'gguf';
+/** v1 supports only HuggingFace. */
+export type ModelSource = 'huggingface';
+/** Derived specialisation tags that are filterable in v1. */
+export type Specialisation = 'coding' | 'reasoning' | 'vision';
+/** Sort keys for the list endpoint. */
+export type SortKey = 'downloads' | 'likes' | 'last_modified' | 'created_at' | 'trending';
+/** Sort direction. */
+export type SortOrder = 'asc' | 'desc';
+/** One quantization variant of a model (single-model response only). */
+export interface Quant {
+    name: string;
+    /** Bytes. Split multi-part files are merged and summed. */
+    size: number | null;
+    /** Bit-width (Q4_K_M→4, Q8_0→8, F16/BF16→16). */
+    bits: number | null;
+    /** Method/mix variant (Q4_K_M→"K_M", Q8_0→"0", IQ4_XS→"XS"). */
+    method: string | null;
+    /** At most one per repo — the suggested default to pull. */
+    recommended: boolean;
+}
+/**
+ * A model, shared by list items and the single-model response. All fields are nullable unless noted.
+ * `quants` is present only on the single-model response.
+ *
+ * Note: `max_quant_size_bytes`, `total_size_bytes`, `context_max`, and `architecture` are typically
+ * null on LIST rows — they are populated on the single-model response (which fetches the file tree).
+ */
+export interface Model {
+    /** non-null. v1 always "huggingface". */
+    source: string;
+    /** non-null. v1 always "gguf". */
+    type: string;
+    /** non-null. HF org/user. */
+    namespace: string;
+    /** non-null. */
+    repo: string;
+    pipeline_tag: string | null;
+    library: string | null;
+    license: string | null;
+    languages: string[] | null;
+    tags: string[] | null;
+    /** Derived: tool-use | vision | reasoning | structured | embedding. Display-only (not filterable in v1). */
+    capabilities: string[] | null;
+    /** Derived: coding | reasoning | vision (etc.). */
+    specialisation: string[] | null;
+    quant_count: number | null;
+    /** Distinct bit-widths present (e.g. [4, 8]). */
+    quant_bits: number[] | null;
+    /** Distinct quant methods present (e.g. ["K_M", "0"]). */
+    quant_methods: string[] | null;
+    /** Largest GGUF quant, bytes. Null on list rows. */
+    max_quant_size_bytes: number | null;
+    /** Total of all GGUF artifacts, bytes. Null on list rows. */
+    total_size_bytes: number | null;
+    /** e.g. "qwen2", "Qwen3-MoE". Null on list rows. */
+    architecture: string | null;
+    /** Tokens. Null on list rows. */
+    context_max: number | null;
+    /** Billions of params. String for decimal precision. */
+    params_b: string | null;
+    provider: string | null;
+    downloads: number | null;
+    likes: number | null;
+    trending_score: number | null;
+    created_at: string | null;
+    last_modified: string | null;
+    /** non-null. Editorially curated. Default false. */
+    curated: boolean;
+    /** non-null. Publisher is a trusted/verified org. Default false. */
+    owner_verified: boolean;
+    /** non-null. When this row was last refreshed. */
+    fetched_at: string;
+    /** Only on the single-model response. */
+    quants?: Quant[];
+}
+/**
+ * Query parameters for `GET /api/v1/models`. All optional. Only the parameters listed here are
+ * supported in v1 — anything else is intentionally absent (a live HuggingFace proxy can only
+ * filter/sort on what HuggingFace supports server-side).
+ */
+export interface ListModelsQuery {
+    /** v1: "gguf" only; else 422. */
+    type?: ModelType | string;
+    /** v1: "huggingface" only; else 422. */
+    source?: ModelSource | string;
+    /** Full-text search. Setting `q` disables the cursor. */
+    q?: string;
+    /** Publisher/org (HF org/user). Repeatable. */
+    author?: string | string[];
+    /** Task/kind. Defaults to text-generation; e.g. "image-text-to-text" for multimodal GGUF models. */
+    pipeline_tag?: string;
+    library?: string;
+    /** Repeatable; OR. */
+    language?: string | string[];
+    /** Repeatable; OR. */
+    license?: string | string[];
+    /** Raw HF tags; repeatable; AND. */
+    tag?: string | string[];
+    /** Repeatable; AND. Catalog-wide. */
+    specialisation?: Specialisation | Specialisation[];
+    /** Default "downloads". */
+    sort?: SortKey;
+    /** Default "desc". */
+    order?: SortOrder;
+    /** Min params (billions). Page-local filter. */
+    params_min?: number;
+    /** Max params (billions). Page-local filter. */
+    params_max?: number;
+    /** Opaque keyset cursor from a prior next_cursor. Ignored when `q` is set. */
+    cursor?: string;
+    /** 1–200. Default 50. */
+    limit?: number;
+}
+/** Response of `GET /api/v1/models`. */
+export interface ListModelsResponse {
+    items: Model[];
+    /** Opaque keyset cursor; null = last page (or when `q` is set). */
+    next_cursor: string | null;
+    /** Reserved; always null (HuggingFace gives no cheap exact count). */
+    total_estimate: number | null;
+}
+/** Query parameters for `GET /api/v1/models/{source}/{namespace}/{repo}`. */
+export interface GetModelQuery {
+    /** Comma-separated extra sections: "files", "readme". Reserved. */
+    include?: string;
+}
+/** Response of the single-model endpoint: a Model with its `quants` table populated. */
+export type GetModelResponse = Model;
+export type ErrorCode = 'validation' | 'unauthorized' | 'not_found' | 'unsupported_source' | 'unsupported_type' | 'internal';
+/** Error envelope returned on non-2xx responses. */
+export interface ErrorResponse {
+    error: ErrorCode | string;
+    message?: string;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@bodhiapp/reference-api-types",
+  "version": "0.0.1",
+  "description": "TypeScript request/response types for the Bodhi Models Reference API (types only — no runtime).",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BodhiSearch/api-getbodhi-app.git",
+    "directory": "packages/api-types"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  }
+}