@kinqs/brainrouter-sdk 0.3.4

package/README.md

@@ -0,0 +1,17 @@
+# @kinqs/brainrouter-sdk
+
+Typed client helpers for talking to a [BrainRouter](https://github.com/kinqsradiollc/BrainRouter) MCP server from your own Node or browser code. Used internally by the [`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli) and the BrainRouter dashboard.
+
+## Install
+
+```bash
+npm install @kinqs/brainrouter-sdk @kinqs/brainrouter-types
+```
+
+## Status
+
+Pre-1.0 — the SDK surface is shaped around the BrainRouter monorepo's own consumers (CLI, dashboard). Stable enough to use; expect minor renames before 1.0.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,114 @@
+import { AddEvidenceRequest, AddEvidenceResponse, ContradictionsResponse, CursorPaginationParams, DiagnosticsBundle, EvidenceResponse, ExplainRecallRequest, HookRegisterRequest, HookRegisterResponse, HookStatusParams, HookStatusResponse, ImportMemoriesRequest, MeResponse, MemoriesResponse, MemoryEvidenceByRecordResponse, MemoryStatsResponse, MemoryWithEvidenceResponse, OperationsResponse, PublicUserRecord, ScenesResponse, SigninRequest, SigninResponse, SignupRequest, SignupResponse, UpdateMemoryRequest, WorkingContextRequest, WorkingContextResponse, WorkingOffloadRequest, WorkingOffloadResponse, WorkingResetRequest, WorkingResetResponse, ActiveSessionsResponse, CoreIdentityRecord, SkillActivationsResponse } from "@kinqs/brainrouter-types";
+export declare class BrainRouterApiError extends Error {
+    status: number;
+    body: string;
+    constructor(status: number, message: string, body: string);
+}
+export declare class BrainRouterClient {
+    private baseUrl;
+    private apiKey;
+    private token;
+    constructor(baseUrl?: string, apiKey?: string, token?: string);
+    withApiKey(apiKey: string): BrainRouterClient;
+    withToken(token: string): BrainRouterClient;
+    private headers;
+    private get;
+    private post;
+    private put;
+    private patch;
+    private deleteReq;
+    private deleteWithBody;
+    private toError;
+    signIn(body: SigninRequest): Promise<SigninResponse>;
+    signUp(body: SignupRequest): Promise<SignupResponse>;
+    me(): Promise<MeResponse>;
+    updateMe(body: {
+        displayName: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    rotateApiKey(): Promise<{
+        apiKey: string;
+    }>;
+    getUsers(params?: CursorPaginationParams): Promise<{
+        users: PublicUserRecord[];
+        nextCursor: string | null;
+        limit: number;
+        hasMore: boolean;
+    }>;
+    createUser(payload: {
+        userId: string;
+        displayName?: string;
+        isAdmin?: boolean;
+    }): Promise<{
+        user: PublicUserRecord;
+    }>;
+    updateUserStatus(userId: string, status: "active" | "disabled"): Promise<{
+        success: boolean;
+    }>;
+    resetUserApiKey(userId: string): Promise<{
+        apiKey: string;
+    }>;
+    deleteUser(id: string): Promise<{
+        success: boolean;
+    }>;
+    getStats(): Promise<MemoryStatsResponse>;
+    getSkillActivations(): Promise<SkillActivationsResponse>;
+    getDiagnostics(userId?: string): Promise<DiagnosticsBundle>;
+    getMemories(params?: CursorPaginationParams & {
+        query?: string;
+        type?: string;
+        scene?: string;
+        skill?: string;
+        archived?: boolean;
+    }): Promise<MemoriesResponse>;
+    archiveMemory(id: string): Promise<{
+        success: boolean;
+    }>;
+    governanceDeleteMemory(id: string, reason: string): Promise<{
+        success: boolean;
+    }>;
+    updateMemory(id: string, body: UpdateMemoryRequest): Promise<MemoryWithEvidenceResponse>;
+    addEvidence(recordId: string, body: AddEvidenceRequest): Promise<AddEvidenceResponse>;
+    exportMemories(): Promise<import("@kinqs/brainrouter-types").MemoryExport>;
+    importMemories(body: ImportMemoriesRequest): Promise<import("@kinqs/brainrouter-types").ImportResult>;
+    getScenes(params?: CursorPaginationParams): Promise<ScenesResponse>;
+    deleteScene(id: string): Promise<{
+        success: boolean;
+    }>;
+    getPersona(): Promise<{
+        persona: CoreIdentityRecord | null;
+    }>;
+    getContradictions(params?: CursorPaginationParams): Promise<ContradictionsResponse>;
+    resolveContradiction(id: string, status: "resolved" | "dismissed"): Promise<{
+        success: boolean;
+    }>;
+    /** Get the operations/audit log (timeline events). */
+    getOperations(params?: CursorPaginationParams & {
+        userId?: string;
+        operation?: string;
+        sessionKey?: string;
+        createdAfter?: string;
+        createdBefore?: string;
+    }): Promise<OperationsResponse>;
+    /** Get all evidence for a specific memory record. */
+    getEvidenceByRecord(recordId: string): Promise<MemoryEvidenceByRecordResponse>;
+    /** Get evidence, optionally filtered by recordId and kind. */
+    getEvidence(params?: CursorPaginationParams & {
+        userId?: string;
+        recordId?: string;
+        kind?: string;
+    }): Promise<EvidenceResponse>;
+    /** Get a memory with evidence by record ID. */
+    getMemory(recordId: string): Promise<MemoryWithEvidenceResponse>;
+    /** Explain a recall query — returns full pipeline breakdown + recallExplanation. */
+    explainRecall(body: ExplainRecallRequest): Promise<import("@kinqs/brainrouter-types").RecallResult>;
+    getWorkingContext(params: WorkingContextRequest): Promise<WorkingContextResponse>;
+    offloadWorkingPayload(body: WorkingOffloadRequest): Promise<WorkingOffloadResponse>;
+    resetWorkingMemory(body: WorkingResetRequest): Promise<WorkingResetResponse>;
+    getActiveSessions(params?: {
+        userId?: string;
+    }): Promise<ActiveSessionsResponse>;
+    registerHook(body: HookRegisterRequest): Promise<HookRegisterResponse>;
+    getHookStatus(params?: HookStatusParams): Promise<HookStatusResponse>;
+}

package/dist/client.js

@@ -0,0 +1,170 @@
+export class BrainRouterApiError extends Error {
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "BrainRouterApiError";
+    }
+}
+export class BrainRouterClient {
+    constructor(baseUrl = "", apiKey = "", token = "") {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.token = token;
+    }
+    withApiKey(apiKey) {
+        return new BrainRouterClient(this.baseUrl, apiKey, this.token);
+    }
+    withToken(token) {
+        return new BrainRouterClient(this.baseUrl, this.apiKey, token);
+    }
+    headers() {
+        if (this.token)
+            return { Authorization: `Bearer ${this.token}` };
+        if (this.apiKey)
+            return { Authorization: `Bearer ${this.apiKey}` };
+        return {};
+    }
+    async get(path, params) {
+        const query = params
+            ? new URLSearchParams(Object.entries(params)
+                .filter((entry) => {
+                const value = entry[1];
+                return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+            })
+                .map(([key, value]) => [key, String(value)])).toString()
+            : "";
+        const res = await fetch(`${this.baseUrl}${path}${query ? `?${query}` : ""}`, { headers: this.headers() });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async put(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async patch(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async deleteReq(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, { method: "DELETE", headers: this.headers() });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async deleteWithBody(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: "DELETE",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return res.json();
+    }
+    async toError(res) {
+        const body = await res.text();
+        let message = body || res.statusText;
+        try {
+            const parsed = JSON.parse(body);
+            if (typeof parsed.error === "string")
+                message = parsed.error;
+        }
+        catch {
+            // Keep raw text for non-JSON responses.
+        }
+        return new BrainRouterApiError(res.status, message, body);
+    }
+    // Auth Operations
+    signIn(body) { return this.post("/api/auth/signin", body); }
+    signUp(body) { return this.post("/api/auth/signup", body); }
+    me() { return this.get("/api/auth/me"); }
+    updateMe(body) { return this.put("/api/auth/me", body); }
+    rotateApiKey() { return this.post("/api/auth/rotate-key", {}); }
+    // Admin User Operations
+    getUsers(params) { return this.get("/api/users", params); }
+    createUser(payload) { return this.post("/api/users", payload); }
+    updateUserStatus(userId, status) { return this.put(`/api/users/${userId}/status`, { status }); }
+    resetUserApiKey(userId) { return this.post(`/api/users/${userId}/reset-key`, {}); }
+    deleteUser(id) { return this.deleteReq(`/api/users/${id}`); }
+    // Telemetry & L1/L2 Memory Operations
+    getStats() { return this.get("/api/stats"); }
+    getSkillActivations() { return this.get("/api/skills/activations"); }
+    getDiagnostics(userId) { return this.get("/api/governance/diagnostics", { userId }); }
+    getMemories(params) {
+        return this.get("/api/memories", params);
+    }
+    archiveMemory(id) { return this.deleteReq(`/api/memories/${id}`); }
+    governanceDeleteMemory(id, reason) { return this.deleteWithBody(`/api/memories/${id}`, { reason }); }
+    updateMemory(id, body) { return this.patch(`/api/memories/${id}`, body); }
+    addEvidence(recordId, body) { return this.post(`/api/memories/${recordId}/evidence`, body); }
+    exportMemories() { return this.get("/api/export"); }
+    importMemories(body) { return this.post("/api/import", body); }
+    getScenes(params) { return this.get("/api/scenes", params); }
+    deleteScene(id) { return this.deleteReq(`/api/scenes/${id}`); }
+    getPersona() { return this.get("/api/persona"); }
+    getContradictions(params) { return this.get("/api/contradictions", params); }
+    resolveContradiction(id, status) { return this.post(`/api/contradictions/${id}/resolve`, { status }); }
+    // Phase 3 — Observability & Recall Explainability
+    /** Get the operations/audit log (timeline events). */
+    getOperations(params) {
+        return this.get("/api/operations", params);
+    }
+    /** Get all evidence for a specific memory record. */
+    getEvidenceByRecord(recordId) {
+        return this.get(`/api/evidence/${recordId}`);
+    }
+    /** Get evidence, optionally filtered by recordId and kind. */
+    getEvidence(params) {
+        return this.get("/api/evidence", params);
+    }
+    /** Get a memory with evidence by record ID. */
+    getMemory(recordId) {
+        return this.get(`/api/memories/${recordId}`);
+    }
+    /** Explain a recall query — returns full pipeline breakdown + recallExplanation. */
+    explainRecall(body) {
+        return this.post("/api/recall/explain", body);
+    }
+    getWorkingContext(params) {
+        return this.get("/api/working/context", params);
+    }
+    offloadWorkingPayload(body) {
+        return this.post("/api/working/offload", body);
+    }
+    resetWorkingMemory(body) {
+        return this.post("/api/working/reset", body);
+    }
+    getActiveSessions(params) {
+        return this.get("/api/working/sessions", params);
+    }
+    registerHook(body) {
+        return this.post("/api/hooks/register", body);
+    }
+    getHookStatus(params) {
+        return this.get("/api/hooks/status", params);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./client.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@kinqs/brainrouter-sdk",
+  "version": "0.3.4",
+  "description": "BrainRouter SDK — typed client helpers for talking to a BrainRouter MCP server from your own Node/browser code.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@kinqs/brainrouter-types": "^0.3.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  },
+  "keywords": [
+    "brainrouter",
+    "sdk",
+    "mcp",
+    "model-context-protocol",
+    "client",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "BrainRouter contributors",
+  "homepage": "https://github.com/kinqsradiollc/BrainRouter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kinqsradiollc/BrainRouter.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/kinqsradiollc/BrainRouter/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}