@byokapi/shared

The shared package is the source of truth for all data types in BYOK API. It exports Zod schemas that both the bridge and client use for validation.

Installation

npm install @byokapi/shared

Schemas

All schemas use Zod v4. Types are inferred from schemas — never define types manually.

Capabilities

import { CapabilitySchema, type Capability } from "@byokapi/shared"

// "language" | "image" | "speech" | "transcription"
const cap = CapabilitySchema.parse("language")

Grants

import {
  GrantRecordSchema,
  GrantStateSchema,
  GrantSummarySchema,
  type GrantRecord,
  type GrantState,
} from "@byokapi/shared"

GrantState is a discriminated union:

type GrantState =
  | { type: "none" }
  | { type: "pending"; requestId: string }
  | { type: "granted"; grantId: string; capabilities: Capability[] }
  | { type: "denied" }
  | { type: "revoked" }
  | { type: "expired" }

RPC types

import type { BridgeAPI, ConsumerAPI } from "@byokapi/shared"

BridgeAPI — methods exposed by the bridge iframe:

handshake() — register consumer and check existing grants
requestGrant() — trigger consent popup
revokeGrant() — revoke an active grant
doLanguage() / streamLanguage() — language model calls
doImage() — image generation
doSpeech() — text-to-speech
doTranscription() — speech-to-text

ConsumerAPI — methods exposed by the consumer app:

onGrantStateChanged() — receive grant state updates
openConsentPopup() — open the consent popup window

WASM models

import { WASM_MODELS, WasmModelSchema, type WasmModel } from "@byokapi/shared"

Pre-configured local model definitions with IDs, display names, and download sizes.

Model registry

import {
  MODELS,
  PROVIDERS,
  getModelsForProvider,
  getModelById,
  getLanguageModels,
} from "@byokapi/shared"

The model registry provides a unified database of all supported AI models across providers.

Validation pattern

Always validate external data with safeParse:

import { GrantStateSchema } from "@byokapi/shared"

const result = GrantStateSchema.safeParse(unknownData)
if (result.success) {
  // result.data is typed as GrantState
} else {
  console.error("Invalid grant state:", result.error)
}

Auto-generated API docs

See the full API reference for all exported types and schemas.

On this page