Client options

Every field createClient(opts) accepts. Same as the exported ClientOptions TypeScript type.

Required

`tenant: string`

Workspace id (t_…) the client acts under. Can be read from NORA_TENANT env if omitted.

Credentials

`token?: string`

PAT (nora_pat_…) for management calls. Read from NORA_PAT env if omitted. Not required if you only call the trigger-secret surfaces (flows.run, feedback, signals.report).

`triggerSecret?: string`

Per-Flow execution secret. Read from NORA_TRIGGER_SECRET env if omitted. Required for flows.run and signals.report.

`triggerHeader?: string`

Header the trigger expects its secret on. Matches the trigger block’s configured api_auth_header. Defaults to authorization sent as Bearer <secret>. Override when your trigger is configured to accept a non-standard header:

createClient({
  // …
  triggerHeader: "x-nora-trigger",   // trigger config was set to x-nora-trigger
});

Transport

`baseUrl?: string`

Server base URL. Defaults to https://platform.nora.my/api/v1 (or NORA_BASE_URL env if set). Override for self-hosted / staging deployments:

createClient({
  // …
  baseUrl: "https://staging.platform.example.com/api/v1",
});

`timeoutMs?: number`

Per-call default timeout in milliseconds. Default 30_000 (30 s). Individual verbs can override with a timeoutMs in their own options object (e.g. flows.run(slug, input, { timeoutMs: 60_000 })).

`maxRetries?: number`

Retry count for server-declared-retryable failures (NoraProviderError and NoraPlatformError when .retryable === true). Default 2. Every attempt is logged with attempt and the failure code — no silent retries. See Errors · Logging. Set to 0 to disable SDK-layer retry (do your own at the application layer):

createClient({
  // …
  maxRetries: 0,
});

`fetchImpl?: typeof fetch`

Custom fetch implementation. Defaults to globalThis.fetch. Use this for:

Test seams — inject a mock:

createClient({ /* … */ fetchImpl: mockFetch });

Custom runtimes — Node with undici, edge workers with a specific fetch polyfill, HTTP proxy shims.

Signature must match the standard fetch(input, init?).

Observability

`logger?: Logger`

Structured logger the SDK pipes internal records into. Compatible with pino, winston, bunyan, or anything matching:

interface Logger {
  debug?(msg: string, meta?: unknown): void;
  info?(msg: string, meta?: unknown): void;
  warn?(msg: string, meta?: unknown): void;
  error?(msg: string, meta?: unknown): void;
}

The SDK redacts by default — tokens, secrets, onBehalfOf values, and request/response bodies do not appear in logs unless debug: true.

`debug?: boolean`

When true, request and response bodies get logged (via the logger). Off by default. Turn on per-incident only, ideally via a scoped clone rather than the shared client. Bodies can contain PII.

`onLog?: (event: LogEvent) => void`

Observe SDK-internal events for metrics — request / response / retry / error. Event shape:

interface LogEvent {
  event: "request" | "response" | "retry" | "error";
  traceId?: string;
  flow?: string;      // slug when the event was scoped to a flow
  attempt?: number;   // populated on retries
  durationMs?: number;// populated on response / error
  status?: string;    // HTTP status or "aborted"
  code?: string;      // failure code when error / retry
}

Never carries secrets or request bodies — safe to ship to any metrics sink. Wire it to your metrics stack:

createClient({
  // …
  onLog: (e) => {
    switch (e.event) {
      case "retry":              metrics.increment("nora.retry", { code: e.code }); break;
      case "provider.fallback":  metrics.increment("nora.fallback"); break;
    }
  },
});

Retry rate, fallback frequency, and circuit-open rate are leading indicators when something upstream is degrading.

Full example

import { createClient } from "@conscience-technology/nora-sdk";
import pino from "pino";

const nora = createClient({
  tenant: process.env.NORA_TENANT!,
  token: process.env.NORA_PAT,
  triggerSecret: process.env.NORA_TRIGGER_SECRET,
  baseUrl: process.env.NORA_BASE_URL,     // omit → default platform.nora.my
  timeoutMs: 30_000,
  maxRetries: 2,
  logger: pino({ level: "info", redact: ["*.token", "*.secret"] }),
  debug: false,
  onLog: (e) => metrics.count("nora." + e.event),
});

CLI

SDK

Client options

Required

`tenant: string`

Credentials

`token?: string`

`triggerSecret?: string`

`triggerHeader?: string`

Transport

`baseUrl?: string`

`timeoutMs?: number`

`maxRetries?: number`

`fetchImpl?: typeof fetch`

Observability

`logger?: Logger`

`debug?: boolean`

`onLog?: (event: LogEvent) => void`

Full example

See also

​Required

​tenant: string

​Credentials

​token?: string

​triggerSecret?: string

​triggerHeader?: string

​Transport

​baseUrl?: string

​timeoutMs?: number

​maxRetries?: number

​fetchImpl?: typeof fetch

​Observability

​logger?: Logger

​debug?: boolean

​onLog?: (event: LogEvent) => void

​Full example

​See also

Required

`tenant: string`

Credentials

`token?: string`

`triggerSecret?: string`

`triggerHeader?: string`

Transport

`baseUrl?: string`

`timeoutMs?: number`

`maxRetries?: number`

`fetchImpl?: typeof fetch`

Observability

`logger?: Logger`

`debug?: boolean`

`onLog?: (event: LogEvent) => void`

Full example

See also