API Reference - Merci SDK

MerciClient

The main entry point for the SDK. It handles authentication, token refreshing, and serves as the factory for creating API clients.

Constructor

Initializes a new client instance.

new MerciClient(options: {
  token: string,
  authType?: 'user' | 'service' | 'application',
  endpoint?: string
})

Parameters

options.token {string} - Required. Your JSON Web Token (JWT).
options.authType {string} - Optional. The authentication type. Defaults to 'user'.
options.endpoint {string} - Optional. The API endpoint URL. Defaults to the production endpoint.

📚 See Getting Started for setup instructions.

Properties

.chat

Provides access to the Chat API for conversational interactions. Returns an instance of ChatAPI.

.tasks

Provides access to the Task API for structured, non-chat interactions like code generation. Returns an instance of TaskAPI.

📚 See Lesson 19 (Task API) and subsequent lessons.

Events

The client is an EventEmitter. Use client.on('eventName', callback) to listen.

api_request / api_response - Monitor network activity.
token_refresh_start / token_refresh_success - Track automatic token refreshing.
error - Catch SDK-internal errors.
tool_start / tool_finish - Observe the lifecycle of agentic tool calls.
tool_warning - Get notified of non-fatal issues during tool execution.
parameter_warning - Get notified when a parameter is ignored for a specific model.

📚 See Lesson 13 (Token Management) and Lesson 14 (Observability).

ChatAPI

Accessed via client.chat. This is the entry point for all conversational AI interactions.

.session(profile)

Creates a new, configurable chat session for a specific model profile.

.session(profile: string): ChatSession

ChatSession

Represents a configured chat session. This class uses a fluent, chainable interface for configuration before execution.

Configuration Methods

.withTools(tools)

Equips the session with a set of tools the model can use.

.withTools(tools: ToolDefinition[]): this

.withSystemMessage(content)

Configures a system message to guide the AI's behavior.

.withSystemMessage(content: string): this

.withParameters(builderFn)

Configures advanced model parameters for the request using a fluent builder.

.withParameters(builderFn: (builder: ParameterBuilder) => ParameterBuilder): this

Execution Methods

.stream(input)

Low-level method that returns an async iterator of real-time events.

.stream(input: string | ChatMessage[]): AsyncIterable<StreamEvent>

.run(input, options)

High-level "agent" method that automates the entire multi-step tool-use process.

.run(input: string | ChatMessage[], options?: { maxIterations?: number }): Promise<string>

.step(messages, options)

"Glass-box" agent method that executes a single turn of the agentic loop, yielding control when tools are requested.

.step(messages: ChatMessage[], options?: { forceTextResponse?: boolean }): AsyncGenerator<AgentToolRequest, AgentTextResponse, ToolExecutionResult[]>

TaskAPI

Accessed via client.tasks. Provides access to specialized, non-conversational tasks like code generation.

.roster()

Retrieves the list of available task IDs from the server.

.roster(): Promise<{ ids: string[] }>

.stream(id, parameters)

Executes a task and returns a stream of real-time events, including content and metadata.

.stream(id: string, parameters: object): AsyncIterable<TaskStreamEvent>

.execute(id, parameters)

Executes a task and returns the aggregated result once complete.

.execute(id: string, parameters: object): Promise<TaskResult>

📚 See Lesson 19 (Task API Usage) for practical examples.

ParameterBuilder

A fluent class for setting advanced model parameters via .withParameters().

.temperature(value: number)

.topP(value: number)

.topK(value: number)

.length(value: number)

.stopToken(value: string)

.seed(value: number)

.asJson()

.parallelToolCalls(isEnabled: boolean)

.toolChoiceAuto()

.toolChoiceRequired()

.toolChoiceNone()

.toolChoiceNamed(name: string)

.reasoningEffort(level: string)

.predictedOutput(text: string)

.cachePoints(cacheObject: object)

.thinkingBudget(value: number)

.numberOfChoices(value: number)

.verbosity(level: string)

Helpers

Exported functions to simplify common tasks.

Message Helpers

Use these functions to construct a valid chat history array.

createUserMessage(content: string)
createSystemMessage(content: string)
createAssistantTextMessage(content: string)
createAssistantToolCallMessage(...)
createToolResultMessage(...)
createMediaMessage(...): Promise<MediaMessage>

Tool Helpers

executeTools(toolCalls, toolLibrary)

A utility to execute a batch of tool calls requested by the model.

executeTools(toolCalls: ToolCall[], toolLibrary: ToolDefinition[]): Promise<ToolExecutionResult[]>

Type Definitions

Key TypeScript interfaces that define the shape of data used throughout the SDK.

ToolDefinition

The structure for defining a tool the model can use.

export interface ToolDefinition { ... }

StreamEvent (Chat)

A union of all possible event types yielded by the chat .stream() method.

export type StreamEvent = TextStreamEvent | ToolCallsStreamEvent | QuotaStreamEvent;

TaskStreamEvent (Task)

A union of all possible event types yielded by the task .stream() method.

export type TaskStreamEvent = TaskContentEvent | TaskMetadataEvent;

API Reference (v2.14.0)