@bodhiapp/reference-api-types 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -12,10 +12,8 @@ export type ModelType = 'gguf';
 export type ModelSource = 'huggingface';
 /** Derived specialisation tags that are filterable in v1. */
 export type Specialisation = 'coding' | 'reasoning' | 'vision';
-/** Sort keys for the list endpoint. */
+/** Sort keys for the list endpoint. Always sorted descending (HuggingFace supports descending only). */
 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;
@@ -110,10 +108,8 @@ export interface ListModelsQuery {
     tag?: string | string[];
     /** Repeatable; AND. Catalog-wide. */
     specialisation?: Specialisation | Specialisation[];
-    /** Default "downloads". */
+    /** Default "downloads". Always sorted descending (HuggingFace supports descending only). */
     sort?: SortKey;
-    /** Default "desc". */
-    order?: SortOrder;
     /** Min params (billions). Page-local filter. */
     params_min?: number;
     /** Max params (billions). Page-local filter. */
@@ -138,9 +134,258 @@ export interface GetModelQuery {
 }
 /** 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';
+/** A HuggingFace namespace is either an organization or a user account. */
+export type NamespaceKind = 'org' | 'user';
+/** One autocomplete suggestion for `GET /api/v1/namespaces`. */
+export interface NamespaceSuggestion {
+    /** The handle used as the `{namespace}` in a `{namespace}/{repo}` path (e.g. "meta-llama"). */
+    name: string;
+    /** Display name, may differ from the handle (e.g. "Meta Llama"); null when HF omits it. */
+    fullname: string | null;
+    /** Absolute avatar URL (HF's relative ones are resolved to absolute); null when none. */
+    avatar_url: string | null;
+    kind: NamespaceKind;
+}
+/** Query parameters for `GET /api/v1/namespaces`. */
+export interface ListNamespacesQuery {
+    /** Search prefix/substring the user is typing. Required. */
+    q: string;
+    /** Restrict to orgs or users. Omit to return both. */
+    kind?: NamespaceKind;
+    /** Max suggestions to return. 1–50, default 10. */
+    limit?: number;
+}
+export interface ListNamespacesResponse {
+    items: NamespaceSuggestion[];
+}
+export type ErrorCode = 'validation' | 'unauthorized' | 'not_found' | 'unsupported_source' | 'unsupported_type' | 'upstream' | 'internal';
 /** Error envelope returned on non-2xx responses. */
 export interface ErrorResponse {
     error: ErrorCode | string;
     message?: string;
 }
+/**
+ * Error envelope when an upstream (HuggingFace) call fails: the upstream status and raw body are
+ * forwarded verbatim. Returned with the upstream HTTP status as the response status.
+ */
+export interface UpstreamErrorResponse {
+    error: 'upstream';
+    status: number;
+    body: unknown;
+}
+export type Modality = 'text' | 'audio' | 'image' | 'video' | 'pdf';
+/** Only real models.dev values; absent ⇒ "Stable" (synthesized by the UI). */
+export type ModelStatus = 'alpha' | 'beta' | 'deprecated';
+/** Derived from the boolean fields + modalities (`vision` = modalities_in includes 'image'). */
+export type Capability = 'reasoning' | 'tool_call' | 'structured_output' | 'attachment' | 'vision';
+/** The BodhiApp api_format the configure bridge can target. */
+export type BridgeApiFormat = 'openai' | 'openai_responses' | 'anthropic' | 'anthropic_oauth' | 'gemini';
+export type ProviderShape = 'openai' | 'openai-compatible' | 'anthropic' | 'openrouter' | 'kiro' | 'native';
+export type ApiFormatHint = BridgeApiFormat | 'other';
+/** Band-relevant pricing for list rows / served-by rows. null = field absent at source. */
+export interface PricingLite {
+    input_per_m: number | null;
+    output_per_m: number | null;
+    cache_read_per_m: number | null;
+    cache_write_per_m: number | null;
+}
+/**
+ * Full unified pricing (model-detail). The opaque blob fields carry Portkey gap dimensions and are
+ * deferred — they ship `null`/absent in the models.dev-only release and are filled later without a
+ * breaking change.
+ */
+export interface Pricing extends PricingLite {
+    currency: string;
+    reasoning_per_m: number | null;
+    input_audio_per_m: number | null;
+    output_audio_per_m: number | null;
+    /** Deferred Portkey-gap blobs; present-but-null until Portkey enrichment lands. */
+    cache_write_1h_per_m?: number | null;
+    context_over_200k?: unknown | null;
+    batch?: unknown | null;
+    finetune?: unknown | null;
+    tool_surcharges?: unknown | null;
+    image_pricing?: unknown | null;
+    video_pricing?: unknown | null;
+    custom_pricing?: unknown | null;
+    calculate?: unknown | null;
+    /** Which source filled this row. */
+    pricing_source: 'modelsdev' | 'portkey' | 'both' | null;
+    /** Deferred; whether filled from Portkey's per-provider `default` fallback. */
+    portkey_default_used?: boolean;
+}
+export interface PageMeta {
+    page: number;
+    page_size: number;
+    total: number;
+}
+/** value → count over the current (post-filter, pre-pagination) result set. */
+export type FacetBucket = Record<string, number>;
+export interface ModelFacets {
+    capability: FacetBucket;
+    modality: FacetBucket;
+    /** keys: alpha|beta|deprecated|stable (stable = status absent). */
+    status: FacetBucket;
+    /** provider slug → model count. */
+    provider: FacetBucket;
+    /** keys: open|closed. */
+    open_weights: FacetBucket;
+}
+export interface ConfigureBridge {
+    api_format: BridgeApiFormat;
+    /** models.dev `api` when present, else a BodhiApp preset; null ⇒ the form shows "base URL required". */
+    base_url: string | null;
+    base_url_source: 'modelsdev_api' | 'bodhi_preset' | 'user_required';
+    /** Bedrock's `api` is a literal AWS_REGION placeholder — flag it. */
+    base_url_requires_substitution: boolean;
+}
+export interface ProviderSummary {
+    slug: string;
+    name: string;
+    /** Served from our own R2 (images.<env>-api.getbodhi.app); null ⇒ UI falls back to a monogram. */
+    logo_url: string | null;
+    model_count: number;
+    /** 1-based, by model_count desc. */
+    rank: number;
+    /** models.dev `api`; null for native providers (the bridge fills from a BodhiApp preset). */
+    api_base_url: string | null;
+    provider_shape: ProviderShape;
+    api_format_hint: ApiFormatHint;
+    /** Union of capability flags across the provider's models. */
+    capabilities_summary: Capability[];
+    pricing_summary: {
+        min_in_per_m: number | null;
+        min_out_per_m: number | null;
+    };
+}
+export interface ProviderListResponse extends PageMeta {
+    items: ProviderSummary[];
+    facets: {
+        capability: FacetBucket;
+        api_format: FacetBucket;
+    };
+}
+export interface ProviderDetailResponse {
+    slug: string;
+    name: string;
+    logo_url: string | null;
+    model_count: number;
+    /** credential env var names, e.g. ["ANTHROPIC_API_KEY"]. */
+    env: string[];
+    npm: string | null;
+    doc_url: string | null;
+    api_base_url: string | null;
+    provider_shape: ProviderShape;
+    bridge: ConfigureBridge;
+}
+export interface ListProvidersQuery {
+    q?: string;
+    capability?: Capability | Capability[];
+    api_format?: ApiFormatHint | ApiFormatHint[];
+    pricing_max?: number;
+    sort?: 'rank' | 'name' | 'model_count';
+    page?: number;
+    page_size?: number;
+}
+export interface ProviderModelRow {
+    model_id: string;
+    name: string;
+    caps: Capability[];
+    context_limit: number | null;
+    output_limit: number | null;
+    pricing: PricingLite;
+    status: ModelStatus | null;
+    modalities_in: Modality[];
+    modalities_out: Modality[];
+}
+export interface ProviderModelsResponse {
+    items: ProviderModelRow[];
+    total: number;
+}
+export interface ListProviderModelsQuery {
+    sort?: 'name' | 'context' | 'price';
+}
+/** One logical model (serving rows grouped by canonical_id). `slug`/`model_id`/`pricing` are the
+ * primary (cheapest input_per_m) provider in the group. */
+export interface ModelLite {
+    slug: string;
+    model_id: string;
+    name: string;
+    family: string | null;
+    context_limit: number | null;
+    output_limit: number | null;
+    pricing: PricingLite;
+    caps: Capability[];
+    status: ModelStatus | null;
+    open_weights: boolean;
+    modalities_in: Modality[];
+    modalities_out: Modality[];
+    /** COUNT(DISTINCT provider_slug) in the canonical_id group. */
+    provider_count: number;
+    release_date: string | null;
+    last_updated: string | null;
+}
+export interface ListCatalogModelsQuery {
+    q?: string;
+    /** Repeatable; AND. */
+    capability?: Capability | Capability[];
+    /** Repeatable; OR. Matches modalities_in ∪ modalities_out. */
+    modality?: Modality | Modality[];
+    pricing_max?: number;
+    pricing_band?: 'free' | 'low' | 'mid' | 'high';
+    context_min?: number;
+    /** Repeatable. "stable" selects rows whose status is ABSENT. */
+    status?: ('alpha' | 'beta' | 'deprecated' | 'stable') | ('alpha' | 'beta' | 'deprecated' | 'stable')[];
+    /** Repeatable; OR. */
+    provider?: string | string[];
+    open_weights?: 'open' | 'closed';
+    sort?: 'updated' | 'context' | 'price' | 'name' | 'providers';
+    page?: number;
+    page_size?: number;
+}
+export interface ModelsListResponse extends PageMeta {
+    items: ModelLite[];
+    facets: ModelFacets;
+}
+export interface ServedBy {
+    slug: string;
+    name: string;
+    logo_url: string | null;
+    base_url: string | null;
+    pricing: PricingLite;
+}
+export interface ModelDetailResponse {
+    /** primary/representative provider of the canonical_id group. */
+    slug: string;
+    model_id: string;
+    name: string;
+    family: string | null;
+    status: ModelStatus | null;
+    reasoning: boolean;
+    tool_call: boolean;
+    structured_output: boolean | null;
+    attachment: boolean;
+    open_weights: boolean;
+    temperature: boolean | number | null;
+    reasoning_options: unknown | null;
+    context_limit: number | null;
+    output_limit: number | null;
+    modalities_in: Modality[];
+    modalities_out: Modality[];
+    release_date: string | null;
+    last_updated: string | null;
+    knowledge_cutoff: string | null;
+    pricing: Pricing;
+    /** Enrichment (models.json) — deferred with Portkey; null in the models.dev-only release. */
+    license: string | null;
+    links: unknown | null;
+    weights: unknown | null;
+    benchmarks: unknown | null;
+    /** The other serving rows in the same canonical_id group, each with its own price. */
+    served_by: ServedBy[];
+    bridge: ConfigureBridge;
+}
+export interface GetCatalogModelQuery {
+    /** reserved */
+    include?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bodhiapp/reference-api-types",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "TypeScript request/response types for the Bodhi Models Reference API (types only — no runtime).",
   "type": "module",
   "types": "dist/index.d.ts",