Skip to Content
Client SDKConfigure the Client SDK

Configure the Client SDK

Create a CustomerClient with createCustomerClient().

Basic configuration

import { createCustomerClient } from '@preternatural-js/client-sdk'
 
const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-project-id',
  sandboxMode: false
})

The client needs an app API URL and a gateway URL. environment picks both.

Configuration options

Every option is optional.

OptionTypeDescription
environment'local' | 'development' | 'production'Selects the default app API and gateway URLs. Defaults to the PRETERNATURAL_MODEM_ENV environment variable.
projectIdstringThe Modem project for customer operations. A session that names a project overrides it.
sandboxModebooleanThe customer’s initial Sandbox or Live classification, until a session sets it. Defaults to false.
authenticationCustomerAuthenticationAn identity-token provider or an existing customer session. Without it, call client.session.set().
appApiUrlstringOverrides the app API URL.
gatewayBaseUrlstringOverrides the gateway URL.
transportTransportConfigSets fetch, timeoutMs, retries, and headers.
customServerUrlstringThe URL of the project’s own authentication server.

Choose a service environment

const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-project-id'
})
EnvironmentApp APIGateway
localhttp://modem-app.localhosthttp://preternatural-modem-gateway.localhost/v1
developmenthttps://preternatural.aihttps://gateway.preternatural.ai/v1
productionhttps://preternatural.aihttps://gateway.preternatural.ai/v1

The development and production presets use the same URLs. environment picks service URLs only. It does not select Live or Sandbox.

Configure sandbox mode

Set sandboxMode for a Sandbox project:

const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-sandbox-project-id',
  sandboxMode: true
})

A customer session carries its own sandboxMode, which replaces this initial value. sandboxMode: true does not simulate providers, does not turn a customer token into a synthetic secret, and does not skip authentication. See Sandbox mode.

Configure with environment variables

The SDK reads these environment variables:

PRETERNATURAL_MODEM_ENV=production
PRETERNATURAL_MODEM_GATEWAY_URL=https://gateway.preternatural.ai/v1
PRETERNATURAL_MODEM_APP_BACKEND_URL=https://preternatural.ai

Client-side code can also use:

NEXT_PUBLIC_PRETERNATURAL_MODEM_APP_BACKEND_URL=https://preternatural.ai

The SDK resolves each service URL in this order:

  1. An explicit gatewayBaseUrl or appApiUrl.
  2. The URL environment variable.
  3. The preset selected by environment or PRETERNATURAL_MODEM_ENV.

createCustomerClient() throws an error naming the missing option when it cannot resolve both URLs.

Override service URLs

Pass explicit URLs for local services:

const client = createCustomerClient({
  appApiUrl: 'http://localhost:3000',
  gatewayBaseUrl: 'http://localhost:8787/v1',
  projectId: 'your-project-id'
})

The SDK removes trailing slashes and adds /v1 to a gateway URL when needed.

Configure the network transport

const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-project-id',
  transport: {
    timeoutMs: 30_000
  }
})
  • timeoutMs: milliseconds to wait for a response, on chat requests to the gateway and calls to the app API. Gateway catalog requests ignore it.
  • retries: how many times to retry a failed gateway call. Defaults to 0. Calls to the app API are not retried.
  • headers: default headers. A request’s own headers and the SDK’s credentials override them. The gateway drops request headers it does not read, including x-request-id.
  • fetch: a custom fetch implementation.
type TransportConfig = {
  fetch?: (
    input: RequestInfo | URL,
    init?: RequestInit
  ) => Promise<Response>
  timeoutMs?: number
  retries?: number
  headers?: HeadersInit
}

A retried completion can be billed twice. Set transport.retries only if that is acceptable.

Add authentication

The client needs a signed-in customer before it sends requests or reads usage. To sign in with your project’s identity provider, pass an identity-token callback:

const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-project-id',
  authentication: {
    type: 'identity-token-provider',
    getIdentityToken: async () => getIdentityTokenForCurrentUser()
  }
})

See Authentication for the other ways to give the client a session.

OverviewAuthentication