Types

Core types

PromptlyClient

The main client type returned by createPromptlyClient().

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 string, 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().

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

---

Prompt types

PromptResult<V>

The return type of getPrompt().

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.

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

PromptResponse

The raw API response shape.

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

PromptConfig

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

PublishedVersion

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.

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().

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.

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

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

ComposerResponse

The raw API response shape for composers.

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 either a plain string or an object with a text property (matching the generateText() return shape).

type FormatInput = { text: string } | string;

ComposerGenerateFn

The function type accepted by compose(). Any function that takes a ComposerPrompt and returns a { text: string } object or a raw string.

type ComposerGenerateFn = (
  prompt: ComposerPrompt,
) => Promise<{ text: string } | string>;

Compatible with generateText from the Vercel AI SDK.

ComposerFormatFn<Names>

The function type for formatComposer().

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

---

Request/option types

PromptRequest

Used with getPrompts() for batch fetching.

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

GetOptions<V>

Options for getPrompt().

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

ComposerRequest

Used with getComposers() for batch fetching.

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

GetComposerOptions<Id, V>

Options for getComposer().

type GetComposerOptions<
  Id extends string = string,
  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.

interface PromptVariableMap {}

PromptId

Suggests known prompt IDs while accepting any string.

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

PromptVersion<Id>

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

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.

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.

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.

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.

interface ComposerPromptMap {}

ComposerId

Suggests known composer IDs while accepting any string.

type ComposerId = keyof ComposerVariableMap | (string & {});

ComposerVersion<Id>

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

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, string> for unknown IDs or versions.

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

ComposerPromptNamesFor<Id>

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

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

---

Error types

PromptlyError

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

ErrorCode

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.

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