SDK de TypeScript

npm install @niadra/sdk           # 0.11.7

import { Niadra, handles } from "@niadra/sdk";

const niadra = new Niadra(); // reads NIADRA_API_KEY

new Niadra(options?: ClientOptions)

const DEFAULT_TIMEOUTS = {
  context: 300,         // context(), every view except voice
  contextFirst: 1_000,  // the first read of a conversation, task or object: the API compiles its pack
  contextVoice: 200,    // context() with view: "voice": the wait for the read of the turn's words, already in flight
  contextVoiceStart: 1_500, // the call's first read, started by begin() while the phone rings
  navigation: 600,      // search(), timeline(), open(), objectState(), objectTimeline()
  navigationVoice: 300, // navigation through voice conversations and voice-bound tools
  write: 5_000,         // each attempt of a batch, feedback() or an upload reservation
  token: 2_000,         // subjectToken()
  upload: 60_000,       // each attempt of an uploadMedia() transfer
  prefetch: 1_000,      // the read prefetch() starts
  connect: 1_000,       // added once when no connection is likely open
};

new Niadra({ cache: { ttlMs: 10_000, staleWhileRevalidateMs: 600_000, maxStaleMs: 1_800_000, maxEntries: 1000 } });

new Niadra({ queue: { flushAt: 15, flushIntervalMs: 1000, turnFlushIntervalMs: 0, maxBatchSize: 100, maxQueueSize: 10_000, maxAttempts: 3 } });

niadra.context(params: ContextParams, options?: ContextOptions): Promise<ContextResult>

const caller = handles.phone("+14155550123");
await niadra.verify({ handle: caller, method: "network_attestation", level: "V1", conversation_id: "call-4471" }); // what the call proved
const ctx = await niadra.context({
  subject: caller,
  view: "voice",
  verification: "V1",
  conversation_id: "call-4471",
});

const system = `${AGENT_INSTRUCTIONS}\n\n${ctx.text}`;
const messages = [...history, { role: "user", content: `${ctx.suffix}\n\n${userTurn}` }];

niadra.search(params: SearchRequest, options?: RequestOptions): Promise<Result<SearchResponse>>

const { data, error } = await niadra.search({
  subject: handles.phone("+14155550123"),
  query: "credit for missed technician visit",
  max_tokens: 300,
  verification: "V1",
  conversation_id: "call-4471",
});
if (data?.recurrence) console.log(data.recurrence.occurrences, data.recurrence.last_resolution);

niadra.timeline(params: TimelineRequest, options?: RequestOptions): Promise<Result<TimelineResponse>>

const { data: page } = await niadra.timeline({
  subject: handles.phone("+14155550123"),
  limit: 20,
  verification: "V1",
  conversation_id: "call-4471",
});

niadra.open(id: string, params?: OpenParams, options?: RequestOptions): Promise<Result<OpenedItem>>

const { data: item } = await niadra.open("0192f7a3-7c32-7b0c-9e16-5b8a0f1c2d34", { verification: "V1", conversation_id: "call-4471" });

niadra.objectState(object: ObjectRef | string, options?: RequestOptions): Promise<Result<ObjectRead>>
niadra.objectTimeline(
  object: ObjectRef | string,
  params?: { cursor?: string; limit?: number },
  options?: RequestOptions,
): Promise<Result<ObjectTimeline>>

const { data: invoice } = await niadra.objectState("invoice:erp:0823");
const { data: page } = await niadra.objectTimeline("invoice:erp:0823", { limit: 20 });

niadra.track(event: TrackEvent): string | null

niadra.track({
  channel: "whatsapp",
  conversation_id: "wa-8812",
  idempotency_key: "wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ",
  handles: [handles.phone("+14155550123")],
  speaker: "customer",
  text: "The technician never showed up. I am calling you.",
});

niadra.action(event: ActionEvent): string | null

niadra.action({
  channel: "erp",
  task_id: "billing-7741",
  handles: [handles.systemId("48213", "crm")],
  object_refs: ["invoice:erp:0823"],
  operation: "credit",
  result: "$40 credit on the August bill",
  closes: { object: { type: "invoice", namespace: "erp", id: "0823" }, operation: "credit" },
});

niadra.identify(params: IdentifyParams): Promise<WriteResult>
niadra.verify(params: VerifyParams): Promise<WriteResult>
niadra.handoff(params: HandoffParams): Promise<WriteResult>

await niadra.verify({
  handle: handles.phone("+14155550123"),
  method: "otp_whatsapp",
  level: "V3",
  conversation_id: "wa-8812",
});

niadra.feedback(params: FeedbackParams): Promise<WriteResult>

await niadra.feedback({
  subject: handles.phone("+14155550123"),
  action: "resolve_open_item",
  open_item_id: "0192f7a2-8c41-7e3a-9b5d-2c4e6f8a0b13",
  reason: "Visit rescheduled",
});

await niadra.feedbackBatch([
  { subject: handles.phone("+14155550123"), action: "correct_fact", fact_id: FACT, value: "45778-204" },
  { subject: handles.phone("+14155550123"), action: "resolve_open_item", open_item_id: ITEM },
]);

const { data: report } = await niadra.contextUse({ since: "2026-09-01", group_by: ["source_id", "day"] });

const { data: link } = await niadra.link({
  person: handles.phone("+5511912345678"),
  organization: handles.systemId("ACC-2201", "crm", { subjectKind: "account" }),
  role: "buyer",
});
if (link) await niadra.endLink(link.link_id);

niadra.ingestStatus({ conversation_id } | { task_id }, options?: RequestOptions): Promise<Result<IngestStatus>>

const { data: me } = await niadra.whoami();

niadra.uploadMedia(
  params: { data: Uint8Array | ArrayBuffer | Blob; content_type: string; subject?: Handle },
  options?: { signal?: AbortSignal },
): Promise<Result<MediaUpload>>

const { data: upload } = await niadra.uploadMedia({
  data: recording,
  content_type: "audio/wav",
  subject: handles.phone("+14155550123"),
});
if (upload) {
  niadra.track({
    channel: "voice",
    conversation_id: "call-4471",
    handles: [handles.phone("+14155550123")],
    speaker: "customer",
    content: { type: "audio", media_ref: upload.media_ref, media_sha256: upload.media_sha256, transcript },
  });
}

niadra.conversation(params: ConversationParams): Conversation

const conv = niadra.conversation({
  subject: handles.phone("+14155550123"),
  channel: "whatsapp",
  conversation_id: "wa-8812",
  verification: "V1",
});

// From her number: the turn proves V1 for this conversation
conv.track({ speaker: "customer", text: "The technician never showed up. I am calling you.", idempotency_key: "wamid.001", verification_hint: "V1" });
await niadra.flush(); // the proof lands before the first read
const ctx = await conv.context();
conv.markInjected(ctx);
conv.agent(await callModel(ctx.text, history, ctx.suffix));
await conv.verify({ method: "otp_whatsapp", level: "V3" });
await conv.handoff({ target: "human", reason: "asked for a person" });
await conv.end();

niadra.task(params: TaskParams): Task

const task = niadra.task({
  channel: "erp",
  task_id: "billing-7741",
  object: "invoice:erp:0823",
  view: "task:billing",
  verification: "no_customer",
});
const ctx = await task.context();
task.markInjected(ctx);
task.action({
  operation: "credit",
  result: "$40 credit on the August bill",
  closes: { object: { type: "invoice", namespace: "erp", id: "0823" }, operation: "credit" },
});
await task.end();

niadra.tools(subject: Handle, binding?: ToolBinding): BoundTools

const kit = niadra.tools(handles.phone("+14155550123"), { verification: "V1", conversation_id: "call-4471" });
const response = await openai.chat.completions.create({ model, messages, tools: kit.definitions });
for (const call of response.choices[0].message.tool_calls ?? []) {
  if (kit.has(call.function.name)) {
    messages.push({ role: "tool", tool_call_id: call.id, content: await kit.call(call.function.name, call.function.arguments) });
  }
}

niadra.subjectToken(params: SubjectTokenRequest, options?: RequestOptions): Promise<Result<SubjectToken>>

const { data: token } = await niadra.subjectToken({
  subject: handles.phone("+14155550123"),
  conversation_id: "call-4471",
  verification: "V1",
});

niadra.agentMemory(params?: { max_tokens?: number; tags?: string[]; view?: string }, options?: RequestOptions & { cache?: boolean }): Promise<AgentMemoryResult>
niadra.searchAgentMemory(params: { query: string; tags?: string[]; limit?: number; conversation_id?: string; task_id?: string }, options?: RequestOptions): Promise<Result<AgentMemorySearchResponse>>
niadra.remember(note: RememberParams, options?: RequestOptions): Promise<Result<RememberResult>>

const notes = await conv.agentMemory({ tags: ["scheduling"] });
const system = [AGENT_INSTRUCTIONS, notes.text, ctx.text].filter(Boolean).join("\n\n");

const { error } = await conv.remember({ kind: "pitfall", title: "Scheduling API", body: "Dates without a time zone are refused.", tags: ["scheduling"] });
if (error?.code === "personal_data_in_agent_memory") {
  // rewrite without the customer's data
}

wrap<C extends object>(client: C, session: WrapSession | (() => WrapSession | null | undefined)): C

import OpenAI from "openai";
import { wrap } from "@niadra/sdk";

const openai = wrap(new OpenAI(), conv);
const completion = await openai.chat.completions.create({ model: "gpt-4.1", messages });

const message = await anthropic.messages.create({ model: "claude-sonnet-4-5", max_tokens: 1024, system, messages });
conv.agent(textOf(message), { usage: message });

// ou monte você mesmo
conv.agent(reply, { usage: { provider: "openai", model: "gpt-4.1", prompt_tokens: 3000, cached_tokens: 2048 } });

niadra.flush(): Promise<void>
niadra.shutdown(): Promise<void>

const searchProducts = Niadra.tool("search_products", async (sku: string) => catalog.find(sku), {
  provenance: (r) => [{ ref: `product:store:${r.sku}`, fields: r.prices }],
});

await convo.turn({ kind: "message", build: Niadra.build({ prompts: { core: "v16" }, model: "gpt-4.1-mini" }) }, async (frame) => {
  // ... o turno, da mensagem do cliente à resposta
});

const decision = await convo.check("proposal_followup", { purpose: "marketing", channel: "whatsapp" });
convo.declare.contactMade(decision, { purpose: "marketing", channel: "whatsapp" });
convo.declare.effect(key, "done"); // done, failed ou unknown_outcome
convo.declare.kind("case.closed", { claim_id, epoch });
const claimed = await convo.claim({ kind: "case", leaseS: 600, intents: ["proposal_followup"] });
const allowed = await niadra.mayContact(customer, "marketing", { channel: "whatsapp" });
const gateway = niadra.contactGateway("wa_gateway", { space: SPACE_ID, key: GATEWAY_KEY });