Core ==== .. This page is generated by smarter-nodejs's scripts/generate-reference.ts. Do not edit it. Configuration, errors, the http transport, logging, Server-Sent Events, and type aliases. .. js:class:: APIConnectionError(message, options) The request did not get a response, e.g. the server is unreachable. Extends ``APIError``, and has its methods. :param message: A human-readable description of the error. :type message: string :param options: The request, the body, and the cause. :type options: APIErrorOptions .. js:attribute:: name :type: string .. js:class:: APIError(message, options) A request to the Smarter api failed. Extends ``SmarterError``, and has its methods. :param message: A human-readable description of the error. :type message: string :param options: The request, the body, and the cause. :type options: APIErrorOptions .. js:attribute:: body The response's parsed JSON body, or its text, or ``undefined`` when there is no response. :type: unknown .. js:attribute:: name :type: string .. js:attribute:: request The request that failed. :type: FailedRequest .. js: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. :param message: A description of the mismatch. :type message: string :param options: The request, the response's status and body, and the validation error. :type options: unknown .. js:attribute:: name :type: string .. js:attribute:: statusCode The response's http status. :type: number .. js:class:: APIStatusError(message, options) The api returned a 4xx or 5xx status. Extends ``APIError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: error The Smarter Journal error body, when the response is a journaled error. :type: object | undefined .. js:attribute:: headers The response's headers. :type: Headers .. js:attribute:: name :type: string .. js:attribute:: statusCode The response's http status. :type: number .. js:attribute:: errorClass The name of the server-side exception class, e.g. ``SAMBrokerErrorNotFound``, when the platform sent it. :type: string | undefined .. js:method:: toString() Returns a string representation of an object. :rtype: string .. js:class:: APITimeoutError(request, cause?) The request timed out. Extends ``APIConnectionError``, and has its methods. :param request: The request that timed out. :type request: FailedRequest :param cause: The abort that ended it. :type cause: unknown | undefined .. js:attribute:: name :type: string .. js:class:: AuthenticationError(message, options) 401: the api key is missing, invalid, or inactive. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:class:: BadRequestError(message, options) 400: the request is invalid, e.g. a malformed manifest. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:class:: ConflictError(message, options) 409: the request conflicts with the resource's current state. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:class:: InternalServerError(message, options) 5xx: the platform failed to process the request. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js: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. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:class:: PermissionDeniedError(message, options) 403: the api key's user may not perform the operation. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:class:: RateLimitError(message, options) 429: too many requests. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js: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. :param message: :type message: string | undefined .. js:attribute:: name :type: string .. js:method:: [hasInstance](value) :param value: :type value: unknown :rtype: boolean .. js: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. :param message: :type message: string | undefined .. js:attribute:: name :type: string .. js:class:: SmarterError(message?) The base class of every error that the Smarter SDK throws. Extends ``Error``, and has its methods. :param message: :type message: string | undefined .. js:attribute:: name :type: string .. js:class:: SmarterHttpClient(config, options) Sends the requests of a Smarter client. :param config: The client's resolved configuration. :type config: ClientConfig :param options: Default headers, a ``fetch``, and the logger. :type options: SmarterHttpClientOptions .. js:attribute:: config The client's resolved configuration. :type: ClientConfig .. js:attribute:: baseUrl The api's base url, e.g. ``https://platform.smarter.sh/api/v1/``. :type: string .. js:attribute:: maxRetries How many times a failed request is retried. :type: number .. js:method:: 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. :param method: The http method. :type method: string :param path: The path, relative to the api's base url. :type path: string :param input: What to send. Its timeout applies to each read. :type input: RequestInput :returns: The events. :rtype: AsyncGenerator .. js:method:: headers(extra?) The headers of a request. :param extra: Headers for this request, which override the defaults. :type extra: Record | undefined :returns: The headers. :rtype: Record .. js:method:: request(method, path, schema, input) Send a request, and validate its JSON response. :param method: The http method, e.g. ``GET``. :type method: string :param path: The path, relative to the api's base url, e.g. ``guardrails/``. :type path: string :param schema: The schema of the response's JSON, e.g. ``Guardrail`` or ``z.array(Guardrail)``. :type schema: S :param input: What to send. :type input: RequestInput :returns: The validated response. :throws APIResponseValidationError: If the response does not match the schema. :rtype: Promise> .. js:method:: send(method, path, input, stream) Send a request, with retries, and throw for an error status. :param method: The http method. :type method: string :param path: The path, relative to the api's base url. :type path: string :param input: What to send. :type input: RequestInput :param stream: True to return as soon as the headers arrive, with the timeout applied to each read instead. :type stream: boolean :returns: The successful response, and the controller whose abort ends a stream. :throws APIConnectionError: If no response was received after the retries. :throws APITimeoutError: If the request timed out after the retries. :throws APIStatusError: For a 4xx or 5xx response, as the status's subclass. :rtype: Promise .. js:method:: url(path, params?) The absolute url of an api path. :param path: A path relative to the base url, e.g. ``cli/whoami/``. An absolute url is returned as is. :type path: string :param params: Query parameters. :type params: Record | undefined :returns: The url. :rtype: string .. js:class:: SmarterPromptError(message, response) A streamed prompt failed: its ``result`` event carried an error response. Extends ``SmarterError``, and has its methods. :param message: The error's description. :type message: string :param response: The error response. :type response: object | object .. js:attribute:: name :type: string .. js:attribute:: response The error response. :type: object | object .. js:class:: SmarterValueError(message?) An argument is invalid. Thrown before a request is sent. Extends ``SmarterError``, and has its methods. :param message: :type message: string | undefined .. js:attribute:: name :type: string .. js:class:: UnprocessableEntityError(message, options) 422: the request is well-formed but cannot be processed. Extends ``APIStatusError``, and has its methods. :param message: The error's description, from the response when it has one. :type message: string :param options: The request, the response's status, headers and body, and its journal error. :type options: APIStatusErrorOptions .. js:attribute:: name :type: string .. js:function:: 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/``. :param url: A platform url, with or without the api's path. :type url: string :returns: The url, with the api's path and a trailing slash. :throws SmarterConfigurationError: If the url is not an http or https url. :rtype: string .. js:function:: environmentUrl(environment, rootDomain) The platform url of an environment, as the smarter cli derives it. :param environment: The environment. :type environment: SmarterEnvironment :param rootDomain: The platform's root domain, e.g. ``platform.smarter.sh``. :type rootDomain: string :returns: e.g. ``https://alpha.platform.smarter.sh``. :rtype: string .. js:function:: 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. :param lines: The stream's lines, without their line endings. :type lines: AsyncIterable | Iterable :returns: The events, in order. :rtype: AsyncGenerator .. js:function:: maskSecret(secret) A secret, masked for logging: its last four characters. :param secret: The secret, e.g. an api key. :type secret: string | null | undefined :returns: e.g. ``****5150``, or ``None`` when there is no secret. :rtype: string .. js:function:: resolveClientConfig(options, settings, logger?) Resolve a client's configuration from its options, the environment, and the cli's configuration file. :param options: The client's options. :type options: ConfigOptions :param settings: The settings to use instead of reading the environment variables, for tests. :type settings: SmarterSettings :param logger: Where to log why the cli's file was ignored. :type logger: Logger | undefined :returns: The configuration. :throws SmarterConfigurationError: If no api key is found, or a value is invalid. :rtype: ClientConfig .. js:data:: API_PATH The path of the Smarter api, which every request url is relative to. :type: "/api/v1/" .. js:data:: DEFAULT_ENVIRONMENT The environment when none is configured. :type: SmarterEnvironment .. js:data:: DEFAULT_MAX_RETRIES How many times a failed request is retried. :type: 2 .. js:data:: DEFAULT_ROOT_DOMAIN The platform's root domain when none is configured. :type: "platform.smarter.sh" .. js:data:: DEFAULT_TIMEOUT The request timeout, in seconds. Prompts that call several tools can take tens of seconds. :type: 60 .. js:data:: ENVIRONMENTS Every ``SmarterEnvironment``. :type: unknown .. js:data:: JsonObject The Zod schema of ``JsonObject``. :type: JsonObject .. js:data:: JsonValue The Zod schema of ``JsonValue``. :type: JsonValue .. js:data:: LOCAL_URL The url of the Smarter platform's local development server. :type: "http://localhost:9357" .. js:class:: ClientConfig A client's resolved configuration. .. js:attribute:: apiKey The api key. :type: string .. js:attribute:: baseUrl The api's base url, ending in ``/api/v1/``. :type: string .. js:attribute:: environment The environment. :type: SmarterEnvironment .. js:attribute:: maxRetries How many times a failed request is retried. :type: number .. js:attribute:: timeout The request timeout, in seconds. :type: number .. js:class:: FailedRequest The method and url of a request that failed. .. js:attribute:: method The http method, e.g. ``POST``. :type: string .. js:attribute:: url The request's url. :type: string .. js:class:: RequestOptions Per-request options, which every method of the SDK takes as its last argument. .. js:attribute:: headers Headers for this request, which override the client's. :type: Record .. js:attribute:: signal A signal to cancel the request. The request then rejects with the signal's reason. :type: AbortSignal .. js:attribute:: timeout The timeout in seconds, instead of the client's. For a stream, it applies to each read. :type: number .. js:class:: ServerSentEvent One Server-Sent Event. .. js:attribute:: data The event's data: its ``data:`` lines, joined by newlines. :type: string .. js:attribute:: event The event's type, e.g. ``progress``, or null for an unnamed event. :type: string | null .. js:attribute:: id The event's id, if any. :type: string | null .. js:attribute:: retry The reconnection time that the server asked for, in milliseconds, if any. :type: number | null .. js:class:: SmarterLogger A logger: ``console``, or any object with the same four methods. .. js:method:: debug(message, args) :param message: :type message: string :param args: :type args: unknown[] :rtype: void .. js:method:: error(message, args) :param message: :type message: string :param args: :type args: unknown[] :rtype: void .. js:method:: info(message, args) :param message: :type message: string :param args: :type args: unknown[] :rtype: void .. js:method:: warn(message, args) :param message: :type message: string :param args: :type args: unknown[] :rtype: void .. js:data:: Fetch The ``fetch`` function that the client sends requests with. :type: object .. js:data:: QueryParamValue A query parameter's value. ``null`` and ``undefined`` leave the parameter out. :type: string | number | boolean | null | undefined .. js:data:: SmarterEnvironment The environments of the smarter cli's configuration file. :type: "local" | "alpha" | "beta" | "next" | "prod" .. js:data:: SmarterId A resource's id: its integer primary key, or its hashed id, e.g. ``rMTAwMDAwNQx``. :type: number | string .. js:data:: SmarterLogLevel How much the SDK logs. ``debug`` includes request and response bodies. :type: "debug" | "info" | "warn" | "error" | "off"