Configuration.
Constructor options, trusted base URLs, and per-instance isolation.
MatildaClientOptions
Extends ClientConfig. All fields are optional except baseUrl.
| Field | type | description |
|---|---|---|
| baseUrl | string | The Matilda API base URL. Must be absolute for auth flows. Defaults to '/api'. |
| accessToken | string | A static access token. Use this for simple setups, or use getToken for managed refresh. |
| getToken | GetToken | Dynamic token provider. Called on every request. The SDK's TokenManager implements this. |
| apiVersion | string | null | API version sent via the X-Matilda-API-Version header. Omit to use the current version. |
| urlPolicy | TrustedApiBaseUrlPolicy | URL validation policy for trustApiBaseUrl(). |
| publicConfigEndpoint | PublicConfigEndpoint | Which public runtime config endpoint to use. |
| getCsrfToken | () => string | null | CSRF token provider for web BFF cookie auth. |
| reportedRequestMetadata | ReportedRequestMetadataConfig | null | SDK identification metadata. Auto-set to { sdkName: 'matilda-client', version }. |
TrustedApiBaseUrlPolicy
| Field | type | description |
|---|---|---|
| allowRelative | boolean | Allow relative URLs (e.g. /api). |
| allowedHosts | readonly string[] | Allowlist of hostnames. |
| allowLocalHttp | boolean | Allow http://localhost / 127.0.0.1 (development). |
| requiredPathPrefix | string | Require a specific path prefix (e.g. /api). |
| requireHttps | boolean | Enforce HTTPS (loopback exempt). |
PublicConfigEndpoint
type PublicConfigEndpoint =
| 'web-bff'
| 'core-api-relative'
| 'core-api-localhost'
| 'core-api-localhost-3000'
| 'core-api-android-emulator'
| 'core-api-production';Environment URLs
| Environment | Base URL |
|---|---|
| Production | https://matilda.maincode.com/api |
| Staging | https://staging.matilda.maincode.com/api |
Instance isolation
Each Matilda instance holds its own independent config. Multiple instances in the same process are fully isolated — constructor options and configure() writes are scoped to that instance.
const staging = new Matilda({ baseUrl: 'https://staging.matilda.maincode.com/api' });
const prod = new Matilda({ baseUrl: 'https://matilda.maincode.com/api' });
console.log(staging.config.baseUrl); // https://staging.matilda.maincode.com/api
console.log(prod.config.baseUrl); // https://matilda.maincode.com/api
// Reconfiguring one never affects the other:
staging.configure({ baseUrl: 'https://override.example/api' });
console.log(staging.config.baseUrl); // https://override.example/api
console.log(prod.config.baseUrl); // https://matilda.maincode.com/api (unchanged)configure(options)
Updates the instance config in place. Returns this for chaining.
client.configure({ accessToken: newToken }).chat.create(/* … */);| Field | type | description |
|---|---|---|
| options | MatildaClientOptions | New config to merge. |
config (getter)
Returns the current ClientConfig.
const cfg = client.config;
console.log(cfg.baseUrl, cfg.accessToken);trustApiBaseUrl(rawUrl, policy?)
Validates and brands a URL as a trusted API base URL.
| Field | type | description |
|---|---|---|
| rawUrl | string | The URL to validate. |
| policy | TrustedApiBaseUrlPolicy | Optional override policy. |
Returns a TrustedApiBaseUrl (a branded string).