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 both an app API URL and a gateway URL. The environment option selects the default URLs for you.

Configuration options

Option	Type	Description
`environment`	`'local' \| 'development' \| 'production'`	Selects the default app API and gateway URLs.
`projectId`	`string \| null`	Identifies the Preternatural project used for customer operations.
`sandboxMode`	`boolean`	Sets the initial sandbox state. Defaults to `false`.
`auth`	`ClientAuthConfig`	Configures customer authentication or restores an existing session.
`appApiUrl`	`string`	Overrides the resolved app API URL.
`gatewayBaseUrl`	`string`	Overrides the resolved gateway URL.
`transport`	`TransportConfig`	Configures `fetch`, timeouts, retries, and additional headers.
`customServerUrl`	`string`	Sets an application-owned authentication server URL.
`authProvider`	`string`	Identifies a custom authentication provider.

Choose a service environment


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

The SDK supports these environments:

Environment	App API	Gateway
`local`	`http://modem-app.localhost`	`http://preternatural-modem-gateway.localhost/v1`
`development`	`https://preternatural.ai`	`https://gateway.preternatural.ai/v1`
`production`	`https://preternatural.ai`	`https://gateway.preternatural.ai/v1`

environment chooses the service URLs. It does not choose between sandbox and production project data.

Configure sandbox mode

Set sandboxMode when working with a sandbox project:


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

Customer identification can replace this initial value with the sandbox state returned by the server.

See Sandbox mode for information about sandbox projects and synthetic customers.

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 applications may also use:


NEXT_PUBLIC_PRETERNATURAL_MODEM_APP_BACKEND_URL=https://preternatural.ai

The SDK resolves each service URL in this order:

An explicit gatewayBaseUrl or appApiUrl.
The corresponding URL environment variable.
The preset selected by environment or PRETERNATURAL_MODEM_ENV.

The constructor throws if it cannot resolve both service URLs.

Override service URLs

Pass explicit URLs when running the services locally or through a test harness:


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.

Production applications should normally use environment: 'production'.

Configure the network transport

Use transport to set a timeout, additional headers, a custom fetch implementation, or an explicit retry policy:


const client = createCustomerClient({
  environment: 'production',
  projectId: 'your-project-id',
  transport: {
    timeoutMs: 30_000,
    headers: {
      'x-request-id': crypto.randomUUID()
    }
  }
})

The transport configuration has this shape:


type TransportConfig = {
  fetch?: (
    input: RequestInfo | URL,
    init?: RequestInit
  ) => Promise<Response>
  timeoutMs?: number
  retries?: number
  headers?: HeadersInit
}

A completion can consume customer allowance before the application receives a response. The SDK defaults charged gateway requests to zero retries. Set transport.retries only when another billed request is acceptable.

Add authentication

A configured client still needs an authenticated customer before it can send provider requests or read customer usage.

The recommended production configuration supplies an identity-token callback:


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

See Authentication for the supported authentication methods.