Configuration

A client needs a Smarter API key and the url of your Smarter platform. Every option of new Smarter({...}) is optional, because each value is looked up in this order:

1. the options of new Smarter({...}),

2. environment variables,

3. the Smarter CLI’s configuration file, ~/.smarter/config.yaml,

4. the defaults: the prod environment of platform.smarter.sh.

This is the lookup of every Smarter SDK, so the same environment configures the Node.js SDK, the Python SDK and the CLI.

import { Smarter } from "@smarter.sh/api";

const client = new Smarter({
  apiKey: "your 64-character Smarter api key",
  baseUrl: "https://platform.example.com",
  timeout: 60, // seconds
  maxRetries: 2,
});

API keys

An API key belongs to a user of an account, and the SDK can do whatever that user can do. Create one in the web console, or with a SmarterAuthToken manifest. See Authentication. Keep it out of your source code: use an environment variable or a secret manager. Never ship it to a browser: call the Smarter API from your own back end.

Environment variables

Variable	Meaning
SMARTER_API_KEY	The API key.
SMARTER_BASE_URL	Your platform’s url, e.g. https://platform.example.com or http://localhost:9357. The API’s path, /api/v1/, is added for you.
SMARTER_ENVIRONMENT	local, alpha, beta, next or prod: which environment of the CLI’s configuration file to use, and how to derive the url when there is no base url.
SMARTER_ROOT_DOMAIN	The platform’s root domain, e.g. platform.example.com, for deriving the url.
SMARTER_TIMEOUT	Seconds to wait for a response, as in every Smarter SDK, not milliseconds. The default is 60, because a prompt that calls several tools can take tens of seconds.
SMARTER_MAX_RETRIES	How many times to retry a request that failed for a transient reason. The default is 2.
SMARTER_LOG	info logs each request, and debug its body too. API keys are never logged. See Errors and Reliability.
SMARTER_CONFIG_FILE	Another path for the CLI’s configuration file.

Without a base url, the url is derived from the environment, exactly as the CLI derives it: local is http://localhost:9357, alpha, beta and next are https://<environment>.<root domain>, and prod is https://<root domain>.

The SDK never reads a .env file itself. Load one the way your application does, e.g. with node --env-file=.env.

Sharing the CLI’s configuration

smarter configure writes the CLI’s configuration file, with an API key per environment:

config:
  environment: local
  root_domain: platform.example.com
local:
  api_key: <your local api key>
prod:
  api_key: <your production api key>

The SDK reads it too, so new Smarter() connects to the CLI’s current environment, with that environment’s key, and new Smarter({ environment: "prod" }) to another one.

Your own fetch

The SDK sends its requests with Node.js’s built-in fetch, and has no HTTP dependency. Pass your own fetch to send requests through a corporate proxy, with custom TLS settings, or through a test double:

import { ProxyAgent, fetch as undiciFetch } from "undici";
import { Smarter } from "@smarter.sh/api";

const dispatcher = new ProxyAgent("http://proxy.example.com:3128");
const client = new Smarter({
  fetch: (input, init) => undiciFetch(input, { ...init, dispatcher }),
});

defaultHeaders adds headers to every request. A client holds no connections of its own, so there is nothing to close.