Noukai Client

Noukai

Main async client for executing flows. The Node SDK is async-first — all methods return promises.

Constructor

class Noukai {
  constructor(options?: NoukaiOptions);
}
 
interface NoukaiOptions {
  /** API key starting with `nk_`. Falls back to `NOUKAI_API_KEY` env var. */
  apiKey?: string;
  /** Default organization name for flow lookups. Must be paired with `project`. */
  org?: string;
  /** Default project name for flow lookups. Must be paired with `org`. */
  project?: string;
  /** Environment for base URL resolution. "dev"/"development" → http://localhost:8080/api/v1; "production" → https://api.noukai.xyz/api/v1. Falls back to `NOUKAI_ENV` env var. */
  env?: NoukaiEnv;
  /** Request timeout in milliseconds. Default: 300000 (5 minutes). */
  timeout?: number;
  /** Max retries on 5xx errors. Default: 1. */
  maxRetries?: number;
  /** Logging hook for request/response/retry events. */
  onLog?: (event: LogEvent) => void;
  /** Include request/response bodies in log events. Default: false. */
  logPayloads?: boolean;
  /** AbortSignal for cancellation. */
  signal?: AbortSignal;
}
 
type NoukaiEnv = "dev" | "development" | "production";

Parameters:

• apiKey (string, optional): API key starting with nk_. Falls back to NOUKAI_API_KEY env var.
• org (string, optional): Default organization name for flow lookups. Must be paired with project. If set, client.flow("slug") uses the defaults; if omitted, client.flow("org/project/slug") is required.
• project (string, optional): Default project name for flow lookups. Must be paired with org. If set, client.flow("slug") uses the defaults; if omitted, client.flow("org/project/slug") is required.
• env (string, optional): Environment for base URL resolution. Accepts "dev"/"development" (→ http://localhost:8080/api/v1) or "production" (default → https://api.noukai.xyz/api/v1). Falls back to NOUKAI_ENV env var.
• timeout (number, optional): Request timeout in milliseconds. Default: 300000.
• maxRetries (number, optional): Number of retries on 5xx errors. Default: 1.
• onLog (function, optional): Logging hook that receives LogEvent objects.
• logPayloads (boolean, optional): If true, include request/response bodies in log events. Default: false.

Throws:

• AuthenticationError: If no API key is provided or the prefix is invalid.
• Error: If only one of org or project is provided (both required together).

Example:

// Production (default) with org/project defaults
const noukai = new Noukai({ org: "acme", project: "spelling" });
 
// Using explicit API key
const noukai = new Noukai({ apiKey: "nk_...", org: "acme", project: "spelling" });
 
// Local development — connects to http://localhost:8080/api/v1
const noukai = new Noukai({ env: "dev", org: "acme", project: "spelling" });
 
// Without defaults, use fully-qualified slug
const noukai = new Noukai();

Properties

defaultOrg (read-only)

Returns the organization name passed to the constructor, or undefined if not set.

const noukai = new Noukai({ org: "acme", project: "spelling" });
console.log(noukai.defaultOrg);  // "acme"

defaultProject (read-only)

Returns the project name passed to the constructor, or undefined if not set.

const noukai = new Noukai({ org: "acme", project: "spelling" });
console.log(noukai.defaultProject);  // "spelling"

Methods

flow(identifier) -> Flow

Get a flow proxy for executing a specific flow.

Parameters:

• identifier (string | object): Flow identifier in one of three forms:
  • Single-segment slug (e.g., "grade-3") — only valid if the client was constructed with org and project defaults
  • Three-segment path (e.g., "org/project/slug") — fully-qualified, works regardless of defaults
  • Object (e.g., { org: "acme", project: "spelling", slug: "grade-3" }) — kwargs form, overrides defaults if provided

Returns: Flow proxy object.

Throws:

• Error: If a single-segment slug is given without client-level defaults, or if the identifier format is invalid.

Example:

// With defaults set, use single-segment slug (recommended)
const noukai = new Noukai({ org: "acme", project: "spelling" });
const flow = noukai.flow("grade-3");
 
// Override defaults with fully-qualified path
const flow = noukai.flow("acme/spelling/grade-3");
 
// Override defaults with kwargs
const flow = noukai.flow({
  org: "acme",
  project: "spelling",
  slug: "grade-3"
});
 
// Without defaults, use fully-qualified
const noukai = new Noukai();
const flow = noukai.flow("acme/spelling/grade-3");

LogEvent (Type)

Structured logging event passed to onLog hook.

Attributes:

• phase (string): One of "request", "response", "retry"
• method (string): HTTP method (GET, POST, etc.)
• path (string): Request path
• attempt (number): Attempt number (1 for first try, 2+ for retries)
• statusCode (number, optional): HTTP status code (only on response)
• requestId (string, optional): Request ID from response headers
• requestBody (any, optional): Request body (if logPayloads=true)
• responseBody (any, optional): Response body (if logPayloads=true)

Example:

const noukai = new Noukai({
  onLog: (event) => {
    console.log(`[${event.phase}] ${event.method} ${event.path} (attempt ${event.attempt})`);
    if (event.statusCode) {
      console.log(`  Status: ${event.statusCode}`);
    }
  }
});

FlowIdentifier (Type)

Flow identifier can be a string or object:

type FlowIdentifier = string | {
  org: string;
  project: string;
  slug: string;
};

String format: "org/project/slug"
Object format: { org: "acme", project: "spelling", slug: "grade-3" }

Both refer to the same flow.