TypeScript SDK
Offizielles TypeScript-SDK für Audact. Abhängigkeitsfreier Node.js-Wrapper um die Audact-HTTP-Dienste — Validierung, Evidence, LLM-Proxy, Webhooks und mehr.
Offizielles TypeScript-SDK für Audact. Ein schlanker, abhängigkeitsfreier
Wrapper (nur Node ≥18 fetch/FormData/AbortSignal/URLSearchParams) um die
HTTP-Dienste von Audact — Validator, Evidence Layer, LLM Proxy, Tenant Management,
Voice Gateway, Agent Worker, Aggregator, Policy Engine, Audio Validator und Org Management.
Installation
bash
npm install @audactcore/sdk
Schnellstart
ts
import { AudactClient } from "@audactcore/sdk";
const client = new AudactClient({ apiKey: "aud_live_..." });
const result = await client.validator.validate({
call_id: "a1b2c3d4-...",
tenant_id: "t1t2t3...",
config_id: "c1c2c3...",
turn: 1,
content: "Hello, I am an AI assistant.",
context: {
previous_turns: [],
call_state: { disclosure_delivered: false },
},
});
if (result.verdict === "ALLOW") {
console.log("Content approved:", result.content);
}Basis-URL
In der Produktion liegt jeder Dienst hinter einem einzigen öffentlichen Host, der per Pfad
unter /v1 weitergeleitet wird. Den Host einmal übergeben:
ts
const client = new AudactClient({ apiKey: "aud_live_...", baseUrl: "https://api.audact.ai" });Ein abschließendes / oder /v1 in baseUrl wird entfernt; Anfragen gehen an
https://api.audact.ai/v1/.... serviceUrls (dienstspezifische Überschreibungen, die
baseUrl Vorrang geben) werden nur für individuelle Deployments benötigt.
Abdeckung
Das SDK deckt die dokumentierte API vollständig ab: 209 von 211 Operationen sind abgedeckt
(die verbleibenden 2 sind empfangsseitige Provider-zu-Plattform-Webhooks —
POST /telnyx/webhook und POST /webhooks/livekit — hierbei handelt es sich um
Ingress-Endpunkte, die Audact empfängt, aber nie aufruft).
| Sub-Client | Dienst | Authentifizierung | Abdeckung |
|---|---|---|---|
client.validator | Validator | API-Schlüssel | ACVF-Validierung pro Gesprächszug, Anruf-Score abschließen |
client.evidence | Evidence Layer | API-Schlüssel | Nachweis-Ereignisse, Ketten, Verifikation/Rekonstruktion, Anrufe, Verstöße, Artikel-50-Berichte/-Exporte, C2PA, Quittungen, Zustellung, Transkript-Abstimmung |
client.llmProxy | LLM Proxy | API-Schlüssel | Compliance-validierter LLM-Chat-Abschluss (synchron + Streaming) |
client.tenants | Tenant Management | API-Schlüssel | Mandanten-CRUD, Nutzung, API-Schlüssel, Konfigurationen |
client.numbers | Voice Gateway | API-Schlüssel | KYC-Dokumente/-Sets, Rufnummern-Bereitstellungslebenszyklus (Bestellen, Zuweisen, Sperren, Wiederaufnehmen, Freigeben, Trunk) |
client.calls | Voice Gateway | API-Schlüssel | SIP-Anruf-Lebenszyklus (ausgehend/eingehend/Browser, Auflegen, Status, Übergabe, Transfer), Trunks, Dispatch-Regeln, Admission-URL, WS-Tickets |
client.webhooks | Tenant Management | API-Schlüssel | Webhook-Endpunkt-CRUD, Test-Ping, Zustellungsverlauf/-Wiederholung, Event-Typ-/Schema-Ermittlung, Geheimnis-Status/-Rotation |
client.agents | Agent Worker | API-Schlüssel | Agent-CRUD + Duplizieren, TTS-Stimmen-Katalog-CRUD, Pipeline-Status |
client.tools | Agent Worker | API-Schlüssel | Function-Calling-Tool-CRUD/-Test, Agent-Tool-Anhängen/-Abhängen |
client.integrations | Agent Worker | API-Schlüssel | Cal.com-Verbindungs-CRUD, Health-Check, Event-Typ-Ermittlung |
client.knowledgeBases | Tenant Management | API-Schlüssel | Knowledge-Base (RAG)-CRUD, Quellen (url/text JSON + multipart Datei-Upload, erneutes Einlesen), Agent-Verknüpfungen mit Retrieval-Abstimmung, Crawl-Ausschlüsse, Retrieval-Testumgebung |
client.aggregation | Aggregator | API-Schlüssel (öffentlich: getMetachain, verifyInclusion) | Merkle-Aggregationsnachweise, öffentliche Meta-Chain, Offline-Einschlussverifikation |
client.policy | Policy Engine | API-Schlüssel | Policy-Auswertung, Jurisdictions-Policy-Dokumente, Anrufzeiten-Vorprüfung |
client.audio | Audio Validator | API-Schlüssel | Synchrone Audio-Validierung pro Gesprächszug, nachträgliche Audio-zu-Transkript-Abstimmung |
client.auth | Tenant Management | API-Schlüssel | API-Schlüssel ↔ JWT-Session-Bridge (Austausch, Aktualisierung) |
client.org | Org Management | OrgBearer (JWT) | Org-Self-Service: Registrierung/Anmeldung/Token-Aktualisierung/Abmeldung, Profil, KYC |
client.org (tenants) | Org Management | OrgBearer (JWT) | Org-eigener Mandanten-Lebenszyklus: auflisten/erstellen/abrufen, Soft-Delete/Aktivieren/Deaktivieren/Wiederherstellen, Initialisieren, Schlüssel ausstellen, Impersonation |
client.pii | Evidence Layer | API-Schlüssel | PII-Vault-Löschung nach Identität (shred, shredCall), Anruf-Identitäten (listCallIdentities, linkCallIdentity), Vault-Token entschlüsseln (decrypt), gelöschter-Keyset-Status (listErasedKeysets), Verschlüsselungseinstellungen (settings) |
Neu in 0.3.0
| Methode | Route |
|---|---|
client.pii.listErasedKeysets(callId, keysetIds) | GET /v1/calls/{call_id}/pii/erased-keysets |
client.evidence.listComplianceEvents(opts?) | GET /v1/compliance/events |
Fehlerbehandlung
Fehlgeschlagene Anfragen werfen AudactError, befüllt aus dem {"error": {...}}-Envelope der API:
ts
import { AudactError } from "@audactcore/sdk";
try {
await client.evidence.getCallDetail("missing");
} catch (err) {
if (err instanceof AudactError) {
console.error(err.status, err.code, err.message);
console.error("request id:", err.requestId); // quote this to support
if (err.hint) console.error("hint:", err.hint);
if (err.status === 429) console.error("retry in", err.retryAfter, "s");
}
}hint, details und retryAfter können undefined sein.
Authentifizierungsabläufe
Die meisten Sub-Clients senden Authorization: Bearer <apiKey> mit dem apiKey, der dem
AudactClient-Konstruktor übergeben wurde. Zwei Oberflächen verwenden einen anderen
Bearer-Token (Org und Plattform), der über setAuthToken() gesetzt wird (oder vorab in
AudactClientOptions angegeben wird):
- OrgBearer — ein JWT, der von
client.org.login()bezogen wird. Das SDK speichert ihn automatisch imorg-Sub-Client; jeder nachfolgendeclient.org.*-Aufruf (einschließlich der Mandanten-Lebenszyklus-Methoden) sendet ihn anstelle des API-Schlüssels.
Org-Anmeldeablauf
ts
import { AudactClient } from "@audactcore/sdk";
const client = new AudactClient({ apiKey: "aud_live_..." });
// login() is public (no bearer required) and stores the returned access
// token on client.org automatically.
await client.org.login({ email: "admin@example.com", password: "hunter2" });
// Subsequent calls send `Authorization: Bearer <jwt>`.
const profile = await client.org.getProfile();
const tenants = await client.org.listTenants();
// Rotate the token before it expires, then clear it when done.
await client.org.refresh();
await client.org.logout();Alternativ vorher authentifiziert starten:
ts
const client = new AudactClient({
apiKey: "aud_live_...",
orgToken: "<jwt from a prior login>",
});Ein neuer Client: webhooks
ts
const endpoint = await client.webhooks.createWebhook({
url: "https://example.com/hooks/audact",
events: ["call_ended", "compliance.violation_detected"],
scope: "account",
});
await client.webhooks.testWebhook(endpoint.id);
const deliveries = await client.webhooks.listWebhookDeliveries(endpoint.id);Entwicklung
bash
npm install npx tsc --noEmit # typecheck npm run build # emit dist/esm + dist/cjs npm run test # vitest