TypeScript Support

The Cobbl SDK is written in TypeScript and includes full type definitions for all APIs.

These types are shared between CobblAdminClient and CobblPublicClient.

Type Imports

Import types from the main package:

import type {
  PromptInput,
  RunPromptResponse,
  FeedbackSubmission,
  TokenUsage,
  CobblConfig,
} from '@cobbl-ai/sdk'

Core Types

CobblConfig

Configuration for the admin client:

interface CobblConfig {
  apiKey: string
}

See CobblAdminClient for configuration details.

PromptInput

Input variables for a prompt:

type PromptInput = Record<string, string>

// Example usage
const input: PromptInput = {
  topic: 'AI Safety',
  tone: 'professional',
  audience: 'developers',
}

RunPromptResponse

Response from running a prompt:

interface RunPromptResponse {
  runId: string
  output: string
  tokenUsage: TokenUsage
  renderedPrompt: string
  promptVersion: PromptVersionClient
}

See Running Prompts for usage examples.

TokenUsage

Token usage statistics:

interface TokenUsage {
  inputTokens: number
  outputTokens: number
  totalTokens: number
}

PromptVersionClient

Prompt version metadata:

interface PromptVersionClient {
  id: string
  versionNumber: number
  template: string
  variables: VariableConfig[]
  provider: Provider
  model: string
}

interface VariableConfig {
  key: string
  type: string
  required: boolean
}

type Provider = 'openai' | 'anthropic' | 'google'

Feedback Types

See Collecting Feedback for usage examples.

FeedbackSubmission

Create new feedback:

interface FeedbackSubmission {
  runId: string
  helpful?: Helpful
  userFeedback?: string
}

type Helpful = 'helpful' | 'not_helpful'

FeedbackUpdate

Update existing feedback:

interface FeedbackUpdate {
  helpful?: Helpful
  userFeedback?: string
}

Response Types

interface CreateFeedbackResponse {
  id: string
  message: string
}

interface UpdateFeedbackResponse {
  message: string
}

Error Types

See Error Handling for comprehensive error handling patterns.

CobblError

class CobblError extends Error {
  code: CobblErrorCode
  details?: unknown
}

type CobblErrorCode =
  | 'INVALID_CONFIG'
  | 'INVALID_REQUEST'
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'ARCHIVED'
  | 'RATE_LIMIT_EXCEEDED'
  | 'SERVER_ERROR'
  | 'NETWORK_ERROR'
  | 'API_ERROR'

Type-Safe Usage Examples

Type-Safe Prompt Input

import type { PromptInput, RunPromptResponse } from '@cobbl-ai/sdk'

const input: PromptInput = {
  topic: 'AI Safety',
  tone: 'professional',
}

const result: RunPromptResponse = await adminClient.runPrompt(
  'blog_post',
  input
)

Type-Safe Feedback

import type { FeedbackSubmission, Helpful } from '@cobbl-ai/sdk'

const helpful: Helpful = 'helpful'

const feedback: FeedbackSubmission = {
  runId: result.runId,
  helpful,
  userFeedback: 'Great response!',
}

await publicClient.createFeedback(feedback)

Type-Safe Token Usage

import type { TokenUsage } from '@cobbl-ai/sdk'

const result = await adminClient.runPrompt('summarizer', { text: longText })

const tokens: TokenUsage = result.tokenUsage

console.log(`Input: ${tokens.inputTokens}`)
console.log(`Output: ${tokens.outputTokens}`)
console.log(`Total: ${tokens.totalTokens}`)

Type Guards

import { CobblError } from '@cobbl-ai/sdk'

const isCobblError = (error: unknown): error is CobblError => {
  return error instanceof CobblError
}

try {
  await adminClient.runPrompt('test', {})
} catch (error) {
  if (isCobblError(error)) {
    // TypeScript knows this is CobblError
    console.log(error.code)
    console.log(error.message)
  }
}

Generic Wrapper Functions

Create type-safe wrapper functions for your application:

import type { PromptInput, RunPromptResponse } from '@cobbl-ai/sdk'
import { CobblAdminClient } from '@cobbl-ai/sdk'

const adminClient = new CobblAdminClient({
  apiKey: process.env.COBBL_API_KEY!,
})

// Type-safe wrapper with specific input type
interface GreetingInput {
  name: string
  occasion?: string
}

const generateGreeting = async (input: GreetingInput): Promise<string> => {
  const result = await adminClient.runPrompt('greeting', input as PromptInput)
  return result.output
}

// Usage
const greeting = await generateGreeting({ name: 'Alice' })

Declaration Files

The SDK ships with .d.ts declaration files for each entry point:

dist/
├── index.d.ts      # Main types
├── admin.d.ts      # Admin client types
└── public.d.ts     # Public client types