클라이언트 옵션

createClient(opts)가 받는 모든 필드입니다. ClientOptions TypeScript 타입과 동일합니다.

필수

`tenant: string`

클라이언트가 동작할 워크스페이스 id (t_…). 안 넘기면 NORA_TENANT env에서 읽습니다.

자격증명

`token?: string`

관리용 호출에 쓸 PAT (nora_pat_…). 안 넘기면 NORA_PAT env에서 읽습니다. 트리거 시크릿으로 부르는 호출(flows.run · feedback · signals.report)만 쓸 거면 필수는 아닙니다.

`triggerSecret?: string`

Flow별 실행 시크릿. 안 넘기면 NORA_TRIGGER_SECRET env에서 읽습니다. flows.run과 signals.report에 필수입니다.

`triggerHeader?: string`

트리거가 시크릿을 기대하는 헤더. Trigger 블록에 설정된 api_auth_header와 맞춰야 합니다. 기본 authorization, Bearer <secret>으로 보냅니다. 트리거가 비표준 헤더를 받도록 설정된 경우에 오버라이드:

createClient({
  // …
  triggerHeader: "x-nora-trigger",   // 트리거 설정이 x-nora-trigger 였을 때
});

전송

`baseUrl?: string`

서버 base URL. 기본 https://platform.nora.my/api/v1 (또는 NORA_BASE_URL env). self-hosted · 스테이징 배포엔 오버라이드:

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

`timeoutMs?: number`

호출별 기본 타임아웃 (ms). 기본 30_000 (30초). 개별 verb는 자기 옵션 객체에 timeoutMs를 넘겨 덮을 수 있습니다 (예: flows.run(slug, input, { timeoutMs: 60_000 })).

`maxRetries?: number`

서버가 retryable로 판정한 실패(NoraProviderError · NoraPlatformError의 .retryable === true)에 대한 재시도 횟수. 기본 2. 모든 시도가 attempt와 실패 code로 로깅됩니다. 조용한 재시도는 없습니다. 에러 · 로깅 참고. SDK 레이어 재시도를 끄려면 0 (앱 레이어에서 직접 처리):

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

`fetchImpl?: typeof fetch`

커스텀 fetch 구현. 기본은 globalThis.fetch입니다. 이럴 때 씁니다:

테스트 seam. mock 주입:

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

커스텀 런타임. undici 붙인 Node, 특정 fetch 폴리필의 엣지 워커, HTTP 프록시 shim.

시그니처는 표준 fetch(input, init?)와 맞아야 합니다.

관측

`logger?: Logger`

SDK 내부 기록을 받을 구조화 로거. pino · winston · bunyan, 또는 이 인터페이스와 맞는 것 아무거나:

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;
}

SDK는 기본으로 레드액션입니다. 토큰 · 시크릿 · onBehalfOf 값 · 요청/응답 본문은 debug: true 없이는 로그에 남지 않습니다.

`debug?: boolean`

true면 요청/응답 본문이 로그에 실립니다 (지정한 logger로). 기본은 off입니다. 사고 재현할 때만 켜세요. 공유 클라이언트가 아니라 스코프드 클론에서 켜는 게 좋습니다. 본문에 PII가 들어 있을 수 있습니다.

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

메트릭용으로 SDK 내부 이벤트 관측 (request · response · retry · error). 이벤트 모양:

interface LogEvent {
  event: "request" | "response" | "retry" | "error";
  traceId?: string;
  flow?: string;      // 이벤트가 특정 Flow에 걸렸을 때 slug
  attempt?: number;   // retry 때 채워짐
  durationMs?: number;// response · error 때 채워짐
  status?: string;    // HTTP 상태 또는 "aborted"
  code?: string;      // error · retry 때의 실패 code
}

시크릿·요청 본문은 절대 안 실립니다. 메트릭 싱크 어디에든 그대로 보내도 안전합니다. 메트릭 스택에 꽂기:

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

재시도율 · 폴백 빈도 · 서킷 오픈율은 상위 프로바이더가 삐걱대기 시작할 때 가장 먼저 움직이는 지표입니다.

전체 예시

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,     // 안 넘기면 기본 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

클라이언트 옵션

필수

`tenant: string`

자격증명

`token?: string`

`triggerSecret?: string`

`triggerHeader?: string`

전송

`baseUrl?: string`

`timeoutMs?: number`

`maxRetries?: number`

`fetchImpl?: typeof fetch`

관측

`logger?: Logger`

`debug?: boolean`

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

전체 예시

관련

​필수

​tenant: string

​자격증명

​token?: string

​triggerSecret?: string

​triggerHeader?: string

​전송

​baseUrl?: string

​timeoutMs?: number

​maxRetries?: number

​fetchImpl?: typeof fetch

​관측

​logger?: Logger

​debug?: boolean

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

​전체 예시

​관련

필수

`tenant: string`

자격증명

`token?: string`

`triggerSecret?: string`

`triggerHeader?: string`

전송

`baseUrl?: string`

`timeoutMs?: number`

`maxRetries?: number`

`fetchImpl?: typeof fetch`

관측

`logger?: Logger`

`debug?: boolean`

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

전체 예시

관련