Core

Configuration, errors, the http transport, logging, Server-Sent Events, and type aliases.

class APIConnectionError(message, options)

The request did not get a response, e.g. the server is unreachable.

Extends APIError, and has its methods.

Arguments:

message (string) – A human-readable description of the error.
options (APIErrorOptions) – The request, the body, and the cause.

APIConnectionError.name

Type:: string

class APIError(message, options)

A request to the Smarter api failed.

Extends SmarterError, and has its methods.

Arguments:

message (string) – A human-readable description of the error.
options (APIErrorOptions) – The request, the body, and the cause.

APIError.body

The response’s parsed JSON body, or its text, or undefined when there is no response.

Type:: unknown

APIError.name

Type:: string

APIError.request

The request that failed.

Type:: FailedRequest

class APIResponseValidationError(message, options)

The api’s response does not match the SDK’s schema of it.

This usually means that the SDK and the Smarter platform are of incompatible versions.

Extends APIError, and has its methods.

Arguments:

message (string) – A description of the mismatch.
options (unknown) – The request, the response’s status and body, and the validation error.

APIResponseValidationError.name

Type:: string

APIResponseValidationError.statusCode

The response’s http status.

Type:: number

class APIStatusError(message, options)

The api returned a 4xx or 5xx status.

Extends APIError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

APIStatusError.error

The Smarter Journal error body, when the response is a journaled error.

Type:: object | undefined

APIStatusError.headers

The response’s headers.

Type:: Headers

APIStatusError.name

Type:: string

APIStatusError.statusCode

The response’s http status.

Type:: number

APIStatusError.errorClass

The name of the server-side exception class, e.g. SAMBrokerErrorNotFound, when the platform sent it.

Type:: string | undefined

APIStatusError.toString()

Returns a string representation of an object.

Return type:: string

class APITimeoutError(request, cause?)

The request timed out.

Extends APIConnectionError, and has its methods.

Arguments:

request (FailedRequest) – The request that timed out.
cause (unknown | undefined) – The abort that ended it.

APITimeoutError.name

Type:: string

class AuthenticationError(message, options)

401: the api key is missing, invalid, or inactive.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

AuthenticationError.name

Type:: string

class BadRequestError(message, options)

400: the request is invalid, e.g. a malformed manifest.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

BadRequestError.name

Type:: string

class ConflictError(message, options)

409: the request conflicts with the resource’s current state.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

ConflictError.name

Type:: string

class InternalServerError(message, options)

5xx: the platform failed to process the request.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

InternalServerError.name

Type:: string

class NotFoundError(message, options)

404: the resource does not exist, or the api key’s user may not read it. Also an instanceof ResourceNotFoundError.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

NotFoundError.name

Type:: string

class PermissionDeniedError(message, options)

403: the api key’s user may not perform the operation.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

PermissionDeniedError.name

Type:: string

class RateLimitError(message, options)

429: too many requests.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

RateLimitError.name

Type:: string

class ResourceNotFoundError(message?)

A resource was not found: the api answered 404 (NotFoundError), or find() found no resource of that name.

err instanceof ResourceNotFoundError is also true for a NotFoundError, as in the Python SDK, where NotFoundError subclasses both.

Extends SmarterError, and has its methods.

Arguments:

message (string | undefined)

ResourceNotFoundError.name

Type:: string

ResourceNotFoundError.[hasInstance](value)

Arguments:

value (unknown)

Return type:

boolean

class SmarterConfigurationError(message?)

The client is missing configuration that it needs, e.g. an api key or a base url.

Extends SmarterError, and has its methods.

Arguments:

message (string | undefined)

SmarterConfigurationError.name

Type:: string

class SmarterError(message?)

The base class of every error that the Smarter SDK throws.

Extends Error, and has its methods.

Arguments:

message (string | undefined)

SmarterError.name

Type:: string

class SmarterHttpClient(config, options)

Sends the requests of a Smarter client.

Arguments:

config (ClientConfig) – The client’s resolved configuration.
options (SmarterHttpClientOptions) – Default headers, a fetch, and the logger.

SmarterHttpClient.config

The client’s resolved configuration.

Type:: ClientConfig

SmarterHttpClient.baseUrl

The api’s base url, e.g. https://platform.smarter.sh/api/v1/.

Type:: string

SmarterHttpClient.maxRetries

How many times a failed request is retried.

Type:: number

SmarterHttpClient.events(method, path, input)

Send a request that asks for Server-Sent Events, and iterate its events.

The request is sent when the iteration starts, and the response is closed when it ends, also when the caller stops early.

Arguments:

method (string) – The http method.
path (string) – The path, relative to the api’s base url.
input (RequestInput) – What to send. Its timeout applies to each read.

Returns:

The events.

Return type:

AsyncGenerator<ServerSentEvent>

SmarterHttpClient.headers(extra?)

The headers of a request.

Arguments:

extra (Record<string, string> | undefined) – Headers for this request, which override the defaults.

Returns:

The headers.

Return type:

Record<string, string>

SmarterHttpClient.request(method, path, schema, input)

Send a request, and validate its JSON response.

Arguments:

method (string) – The http method, e.g. GET.
path (string) – The path, relative to the api’s base url, e.g. guardrails/.
schema (S) – The schema of the response’s JSON, e.g. Guardrail or z.array(Guardrail).
input (RequestInput) – What to send.

Returns:

The validated response.

Throws:

APIResponseValidationError – If the response does not match the schema.

Return type:

Promise<output<S>>

SmarterHttpClient.send(method, path, input, stream)

Send a request, with retries, and throw for an error status.

Arguments:

method (string) – The http method.
path (string) – The path, relative to the api’s base url.
input (RequestInput) – What to send.
stream (boolean) – True to return as soon as the headers arrive, with the timeout applied to each read instead.

Returns:

The successful response, and the controller whose abort ends a stream.

Throws:

APIConnectionError – If no response was received after the retries.
APITimeoutError – If the request timed out after the retries.
APIStatusError – For a 4xx or 5xx response, as the status’s subclass.

Return type:

Promise<object>

SmarterHttpClient.url(path, params?)

The absolute url of an api path.

Arguments:

path (string) – A path relative to the base url, e.g. cli/whoami/. An absolute url is returned as is.
params (Record<string, QueryParamValue> | undefined) – Query parameters.

Returns:

The url.

Return type:

string

class SmarterPromptError(message, response)

A streamed prompt failed: its result event carried an error response.

Extends SmarterError, and has its methods.

Arguments:

message (string) – The error’s description.
response (object | object) – The error response.

SmarterPromptError.name

Type:: string

SmarterPromptError.response

The error response.

Type:: object | object

class SmarterValueError(message?)

An argument is invalid. Thrown before a request is sent.

Extends SmarterError, and has its methods.

Arguments:

message (string | undefined)

SmarterValueError.name

Type:: string

class UnprocessableEntityError(message, options)

422: the request is well-formed but cannot be processed.

Extends APIStatusError, and has its methods.

Arguments:

message (string) – The error’s description, from the response when it has one.
options (APIStatusErrorOptions) – The request, the response’s status, headers and body, and its journal error.

UnprocessableEntityError.name

Type:: string

apiBaseUrl(url)

The api’s base url for a platform url.

https://example.com and https://example.com/api/v1 both become https://example.com/api/v1/.

Arguments:

url (string) – A platform url, with or without the api’s path.

Returns:

The url, with the api’s path and a trailing slash.

Throws:

SmarterConfigurationError – If the url is not an http or https url.

Return type:

string

environmentUrl(environment, rootDomain)

The platform url of an environment, as the smarter cli derives it.

Arguments:

environment (SmarterEnvironment) – The environment.
rootDomain (string) – The platform’s root domain, e.g. platform.smarter.sh.

Returns:

e.g. https://alpha.platform.smarter.sh.

Return type:

string

iterSse(lines)

Parse a stream’s lines into events, as the HTML Living Standard specifies.

A blank line ends an event. Comments (lines that start with :), and blocks that set only retry, yield nothing.

Arguments:

lines (AsyncIterable) – The stream’s lines, without their line endings.

Returns:

The events, in order.

Return type:

AsyncGenerator<ServerSentEvent>

maskSecret(secret)

A secret, masked for logging: its last four characters.

Arguments:

secret (string | null | undefined) – The secret, e.g. an api key.

Returns:

e.g. ****5150, or None when there is no secret.

Return type:

string

resolveClientConfig(options, settings, logger?)

Resolve a client’s configuration from its options, the environment, and the cli’s configuration file.

Arguments:

options (ConfigOptions) – The client’s options.
settings (SmarterSettings) – The settings to use instead of reading the environment variables, for tests.
logger (Logger | undefined) – Where to log why the cli’s file was ignored.

Returns:

The configuration.

Throws:

SmarterConfigurationError – If no api key is found, or a value is invalid.

Return type:

ClientConfig

API_PATH

The path of the Smarter api, which every request url is relative to.

Type:: “/api/v1/”

DEFAULT_ENVIRONMENT

The environment when none is configured.

Type:: SmarterEnvironment

DEFAULT_MAX_RETRIES

How many times a failed request is retried.

Type:: 2

DEFAULT_ROOT_DOMAIN

The platform’s root domain when none is configured.

Type:: “platform.smarter.sh”

DEFAULT_TIMEOUT

The request timeout, in seconds. Prompts that call several tools can take tens of seconds.

Type:: 60

ENVIRONMENTS

Every SmarterEnvironment.

Type:: unknown

JsonObject

The Zod schema of JsonObject.

Type:: JsonObject

JsonValue

The Zod schema of JsonValue.

Type:: JsonValue

LOCAL_URL

The url of the Smarter platform’s local development server.

Type:: “http://localhost:9357”

class ClientConfig()

A client’s resolved configuration.

ClientConfig.apiKey

The api key.

Type:: string

ClientConfig.baseUrl

The api’s base url, ending in /api/v1/.

Type:: string

ClientConfig.environment

The environment.

Type:: SmarterEnvironment

ClientConfig.maxRetries

How many times a failed request is retried.

Type:: number

ClientConfig.timeout

The request timeout, in seconds.

Type:: number

class FailedRequest()

The method and url of a request that failed.

FailedRequest.method

The http method, e.g. POST.

Type:: string

FailedRequest.url

The request’s url.

Type:: string

class RequestOptions()

Per-request options, which every method of the SDK takes as its last argument.

RequestOptions.headers

Headers for this request, which override the client’s.

Type:: Record<string, string>

RequestOptions.signal

A signal to cancel the request. The request then rejects with the signal’s reason.

Type:: AbortSignal

RequestOptions.timeout

The timeout in seconds, instead of the client’s. For a stream, it applies to each read.

Type:: number

class ServerSentEvent()

One Server-Sent Event.

ServerSentEvent.data

The event’s data: its data: lines, joined by newlines.

Type:: string

ServerSentEvent.event

The event’s type, e.g. progress, or null for an unnamed event.

Type:: string | null

ServerSentEvent.id

The event’s id, if any.

Type:: string | null

ServerSentEvent.retry

The reconnection time that the server asked for, in milliseconds, if any.

Type:: number | null

class SmarterLogger()

A logger: console, or any object with the same four methods.

SmarterLogger.debug(message, args)

Arguments:

message (string)
args (unknown[])

Return type:

void

SmarterLogger.error(message, args)

Arguments:

message (string)
args (unknown[])

Return type:

void

SmarterLogger.info(message, args)

Arguments:

message (string)
args (unknown[])

Return type:

void

SmarterLogger.warn(message, args)

Arguments:

message (string)
args (unknown[])

Return type:

void

Fetch

The fetch function that the client sends requests with.

Type:: object

QueryParamValue

A query parameter’s value. null and undefined leave the parameter out.

Type:: string | number | boolean | null | undefined

SmarterEnvironment

The environments of the smarter cli’s configuration file.

Type:: “local” | “alpha” | “beta” | “next” | “prod”

SmarterId

A resource’s id: its integer primary key, or its hashed id, e.g. rMTAwMDAwNQx.

Type:: number | string

SmarterLogLevel

How much the SDK logs. debug includes request and response bodies.

Type:: “debug” | “info” | “warn” | “error” | “off”