# Types

## Core types

### `PromptlyClient`

The main client type returned by `createPromptlyClient()`.

```typescript
type PromptlyClient = {
  getPrompt: <T extends string, V extends PromptVersion<T> | 'latest' = 'latest'>(
    promptId: T,
    options?: GetOptions<V>,
  ) => Promise<PromptResult<VariablesFor<T, V>>>;

  getPrompts: <const T extends readonly PromptRequest[]>(
    entries: T,
  ) => Promise<GetPromptsResults<T>>;

  getComposer: <T extends ComposerId, V extends ComposerVersion<T> | 'latest' = 'latest'>(
    composerId: T,
    options?: GetComposerOptions<T, V>,
  ) => Promise<ComposerResult<ComposerPromptNamesFor<T>>>;

  getComposers: <const T extends readonly ComposerRequest[]>(
    entries: T,
  ) => Promise<GetComposersResults<T>>;
};
```

### `PromptlyClientConfig`

Configuration options for `createPromptlyClient()`.

```typescript
type PromptlyClientConfig = {
  apiKey?: string;
  baseUrl?: string;
  model?: (modelId: string) => import('ai').LanguageModel;
};
```

---

## Prompt types

### `PromptResult<V>`

The return type of `getPrompt()`.

```typescript
type PromptResult<V extends Record<string, string> = Record<string, string>> =
  Omit<PromptResponse, 'userMessage'> & {
    userMessage: PromptMessage<V>;
    temperature: number;
    model: import('ai').LanguageModel;
  };
```

### `PromptMessage<V>`

A callable function for template variable interpolation. Also has a `toString()` method that returns the raw template string.

```typescript
type PromptMessage<V extends Record<string, string> = Record<string, string>> = {
  (variables: V): string;
  toString(): string;
};
```

### `PromptResponse`

The raw API response shape.

```typescript
type PromptResponse = {
  promptId: string;
  promptName: string;
  version: string;
  systemMessage: string;
  userMessage: string;
  config: PromptConfig;
  publishedVersions?: PublishedVersion[];
};
```

### `PromptConfig`

```typescript
type PromptConfig = {
  schema: SchemaField[];
  model: string;
  temperature: number;
  inputData: unknown;
  inputDataRootName: string | null;
};
```

### `PublishedVersion`

```typescript
type PublishedVersion = {
  version: string;
  userMessage: string;
};
```

---

## Composer types

### `ComposerResult<Names>`

The return type of `getComposer()`. Includes resolved prompts as named properties and a `formatComposer()` function.

```typescript
type ComposerResult<Names extends string = string> = {
  composerId: string;
  composerName: string;
  version: string;
  config: ComposerConfig;
  segments: ComposerSegment[];
  prompts: ComposerPrompt[];
  formatComposer: ComposerFormatFn<Names>;
  compose: (generate: ComposerGenerateFn) => Promise<string>;
} & {
  [K in Names]: ComposerPrompt;
};
```

### `ComposerPrompt`

An AI SDK-compatible prompt shape. Can be spread directly into `generateText()` or `streamText()`.

```typescript
type ComposerPrompt = {
  model: import('ai').LanguageModel;
  system: string | undefined;
  prompt: string;
  temperature: number;
  promptId: string;
  promptName: string;
};
```

### `ComposerSegment`

A discriminated union of static and prompt segments.

```typescript
type ComposerStaticSegment = {
  type: 'static';
  content: string;
};

type ComposerPromptSegment = {
  type: 'prompt';
  promptId: string;
  promptName: string;
  version: string;
  systemMessage: string | null;
  userMessage: string | null;
  config: Record<string, unknown>;
};

type ComposerSegment = ComposerStaticSegment | ComposerPromptSegment;
```

### `ComposerConfig`

```typescript
type ComposerConfig = {
  schema: SchemaField[];
  inputData: unknown;
  inputDataRootName: string | null;
};
```

### `ComposerResponse`

The raw API response shape for composers.

```typescript
type ComposerResponse = {
  composerId: string;
  composerName: string;
  version: string;
  config: ComposerConfig;
  segments: ComposerSegment[];
  publishedVersions?: { version: string }[];
};
```

### `FormatInput`

The value type accepted by `formatComposer()` for each prompt result. Accepts a plain string, an object with a `text` property (matching the `generateText()` return shape), or an explicit raw HTML object.

```typescript
type FormatInput = { text: string } | { html: string } | string;
```

String and `{ text }` values preserve newlines as `<br>` tags in the assembled composer output. Use `{ html }` only for trusted HTML that should be inserted unchanged.

### `ComposerGenerateFn`

The function type accepted by `compose()`. Any function that takes a `ComposerPrompt` and returns a `FormatInput`.

```typescript
type ComposerGenerateFn = (
  prompt: ComposerPrompt,
) => Promise<FormatInput>;
```

Compatible with `generateText` from the Vercel AI SDK.

### `ComposerFormatFn<Names>`

The function type for `formatComposer()`.

```typescript
type ComposerFormatFn<Names extends string = string> = (
  results: Record<Names, FormatInput>,
) => string;
```

---

## Request/option types

### `PromptRequest`

Used with `getPrompts()` for batch fetching.

```typescript
type PromptRequest = {
  promptId: string;
  version?: string;
};
```

### `GetOptions<V>`

Options for `getPrompt()`.

```typescript
type GetOptions<V extends string = string> = {
  version?: V;
};
```

### `ComposerRequest`

Used with `getComposers()` for batch fetching.

```typescript
type ComposerRequest = {
  composerId: ComposerId;
  input?: Record<string, unknown>;
  version?: string;
};
```

### `GetComposerOptions<Id, V>`

Options for `getComposer()`.

```typescript
type GetComposerOptions<
  Id extends string = ComposerId,
  V extends string = 'latest',
> = {
  input?: ComposerInputFor<Id, V>;
  version?: V;
};
```

---

## Type system types

These types power the declaration merging and type narrowing system.

### `PromptVariableMap`

Empty interface augmented by codegen. Must remain an `interface` (not `type`) for declaration merging to work.

```typescript
interface PromptVariableMap {}
```

### `PromptId`

Suggests known prompt IDs while accepting any string.

```typescript
type PromptId = keyof PromptVariableMap | (string & {});
```

### `PromptVersion<Id>`

Resolves to known version strings for a prompt ID, excluding `'latest'`.

```typescript
type PromptVersion<Id extends string> =
  Id extends keyof PromptVariableMap
    ? Exclude<keyof PromptVariableMap[Id], 'latest'>
    : string;
```

### `VariablesFor<Id, Ver>`

Resolves the variable shape for a prompt ID and version. Falls back to `Record<string, string>` for unknown IDs or versions.

```typescript
type VariablesFor<Id extends string, Ver extends string = 'latest'> =
  Id extends keyof PromptVariableMap
    ? Ver extends keyof PromptVariableMap[Id]
      ? PromptVariableMap[Id][Ver]
      : Record<string, string>
    : Record<string, string>;
```

### `GetPromptsResults<T>`

Mapped tuple type that types each position in batch results.

```typescript
type GetPromptsResults<T extends readonly PromptRequest[]> = {
  [K in keyof T]: T[K] extends {
    promptId: infer Id extends string;
    version: infer Ver extends string;
  }
    ? PromptResult<VariablesFor<Id, Ver>>
    : T[K] extends { promptId: infer Id extends string }
      ? PromptResult<VariablesFor<Id, 'latest'>>
      : PromptResult;
};
```

### `ComposerVariableMap`

Empty interface augmented by codegen. Must remain an `interface` (not `type`) for declaration merging to work. Maps composer IDs to their input variable shapes per version.

```typescript
interface ComposerVariableMap {}
```

### `ComposerPromptMap`

Empty interface augmented by codegen. Must remain an `interface` (not `type`) for declaration merging to work. Maps composer IDs to a union of their camelCase prompt name strings.

```typescript
interface ComposerPromptMap {}
```

### `ComposerId`

Accepts any string before codegen. Once generated composer types are present, narrows to the generated composer ID literals.

```typescript
type KnownComposerId = Extract<keyof ComposerVariableMap, string>;
type ComposerId = [KnownComposerId] extends [never]
  ? string
  : KnownComposerId;
```

### `ComposerVersion<Id>`

Resolves to known version strings for a composer ID, excluding `'latest'`.

```typescript
type ComposerVersion<Id extends string> =
  Id extends keyof ComposerVariableMap
    ? Exclude<keyof ComposerVariableMap[Id], 'latest'>
    : string;
```

### `ComposerInputFor<Id, Ver>`

Resolves the input variable shape for a composer ID and version. Falls back to `Record<string, unknown>` before codegen or for unknown helper type parameters.

```typescript
type ComposerInputFor<
  Id extends string,
  Ver extends string = 'latest',
> = Id extends keyof ComposerVariableMap
  ? Ver extends keyof ComposerVariableMap[Id]
    ? ComposerVariableMap[Id][Ver]
    : Record<string, unknown>
  : Record<string, unknown>;
```

### `ComposerPromptNamesFor<Id>`

Resolves the prompt name union for a composer ID from `ComposerPromptMap`. Falls back to `string` for unknown IDs.

```typescript
type ComposerPromptNamesFor<Id extends string> =
  Id extends keyof ComposerPromptMap ? ComposerPromptMap[Id] : string;
```

---

## Error types

### `PromptlyError`

```typescript
class PromptlyError extends Error {
  readonly code: ErrorCode;
  readonly status: number;
  readonly usage?: unknown;
  readonly upgradeUrl?: string;
}
```

### `ErrorCode`

```typescript
type ErrorCode =
  | 'UNAUTHORIZED'
  | 'INVALID_KEY'
  | 'NOT_FOUND'
  | 'VERSION_NOT_FOUND'
  | 'BAD_REQUEST'
  | 'USAGE_LIMIT_EXCEEDED'
  | 'UNRESOLVED_PROMPT';
```

### `ErrorResponse`

The raw error response shape from the API.

```typescript
type ErrorResponse = {
  error: string;
  code: ErrorCode;
  usage?: unknown;
  upgradeUrl?: string;
};
```