@kavachos/client 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KavachOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+interface Permission {
+    resource: string;
+    actions: string[];
+    constraints?: PermissionConstraints;
+}
+interface PermissionConstraints {
+    maxCallsPerHour?: number;
+    allowedArgPatterns?: string[];
+    requireApproval?: boolean;
+    timeWindow?: {
+        start: string;
+        end: string;
+    };
+    ipAllowlist?: string[];
+}
+interface Agent {
+    id: string;
+    ownerId: string;
+    name: string;
+    type: "autonomous" | "delegated" | "service";
+    token: string;
+    permissions: Permission[];
+    status: "active" | "revoked" | "expired";
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateAgentInput {
+    ownerId: string;
+    name: string;
+    type: "autonomous" | "delegated" | "service";
+    permissions: Permission[];
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateAgentInput {
+    name?: string;
+    permissions?: Permission[];
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AgentFilters {
+    userId?: string;
+    status?: "active" | "revoked" | "expired";
+    type?: "autonomous" | "delegated" | "service";
+}
+interface AuthorizeByTokenInput {
+    action: string;
+    resource: string;
+    arguments?: Record<string, unknown>;
+}
+interface AuthorizeResult {
+    allowed: boolean;
+    reason?: string;
+    auditId: string;
+}
+interface DelegateInput {
+    fromAgent: string;
+    toAgent: string;
+    permissions: Permission[];
+    expiresAt: string;
+    maxDepth?: number;
+}
+interface DelegationChain {
+    id: string;
+    fromAgent: string;
+    toAgent: string;
+    permissions: Permission[];
+    expiresAt: string;
+    depth: number;
+    createdAt: string;
+}
+interface AuditEntry {
+    id: string;
+    agentId: string;
+    userId: string;
+    action: string;
+    resource: string;
+    parameters: Record<string, unknown>;
+    result: "allowed" | "denied" | "rate_limited";
+    reason?: string;
+    durationMs: number;
+    tokensCost?: number;
+    timestamp: string;
+}
+interface AuditFilters {
+    agentId?: string;
+    userId?: string;
+    since?: string;
+    until?: string;
+    actions?: string[];
+    result?: "allowed" | "denied" | "rate_limited";
+    limit?: number;
+    offset?: number;
+}
+interface PaginatedAuditLogs {
+    entries: AuditEntry[];
+    total?: number;
+}
+interface ExportOptions {
+    format: "json" | "csv";
+    since?: string;
+    until?: string;
+}
+interface RegisterMcpServerInput {
+    name: string;
+    endpoint: string;
+    tools: string[];
+    authRequired?: boolean;
+    rateLimit?: {
+        rpm: number;
+    };
+}
+interface McpServer {
+    id: string;
+    name: string;
+    endpoint: string;
+    tools: string[];
+    authRequired: boolean;
+    createdAt: string;
+}
+interface KavachError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface KavachApiErrorBody {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+type KavachResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: KavachError;
+};
+
+interface KavachClientOptions {
+    baseUrl: string;
+    /** Bearer token sent as `Authorization: Bearer <token>` on every request. */
+    token?: string;
+    /** Additional headers merged into every request. */
+    headers?: Record<string, string>;
+}
+interface AuthorizeRequest {
+    action: string;
+    resource: string;
+    arguments?: Record<string, unknown>;
+}
+interface KavachClient {
+    agents: {
+        create: (input: CreateAgentInput) => Promise<Agent>;
+        list: (filters?: AgentFilters) => Promise<Agent[]>;
+        get: (id: string) => Promise<Agent | null>;
+        update: (id: string, input: UpdateAgentInput) => Promise<Agent>;
+        revoke: (id: string) => Promise<void>;
+        rotate: (id: string) => Promise<Agent>;
+    };
+    /** Authorize an action by agent ID. Calls POST /agents/:id/authorize. */
+    authorize: (agentId: string, request: AuthorizeRequest) => Promise<AuthorizeResult>;
+    /** Authorize an action using the agent's bearer token. Calls POST /authorize. */
+    authorizeByToken: (token: string, request: AuthorizeByTokenInput) => Promise<AuthorizeResult>;
+    delegations: {
+        create: (input: DelegateInput) => Promise<DelegationChain>;
+        list: (agentId: string) => Promise<DelegationChain[]>;
+        revoke: (id: string) => Promise<void>;
+        getEffectivePermissions: (agentId: string) => Promise<Permission[]>;
+    };
+    audit: {
+        query: (filters?: AuditFilters) => Promise<AuditEntry[]>;
+        export: (options: ExportOptions) => Promise<string>;
+    };
+    mcp: {
+        register: (input: RegisterMcpServerInput) => Promise<McpServer>;
+        list: () => Promise<McpServer[]>;
+        get: (id: string) => Promise<McpServer | null>;
+    };
+}
+declare function createKavachClient(options: KavachClientOptions): KavachClient;
+
+declare class KavachApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, unknown>;
+    constructor(error: KavachError, status: number);
+    toKavachError(): KavachError;
+}
+
+export { type Agent, type AgentFilters, type AuditEntry, type AuditFilters, type AuthorizeByTokenInput, type AuthorizeRequest, type AuthorizeResult, type CreateAgentInput, type DelegateInput, type DelegationChain, type ExportOptions, KavachApiError, type KavachApiErrorBody, type KavachClient, type KavachClientOptions, type KavachError, type KavachResult, type McpServer, type PaginatedAuditLogs, type Permission, type PermissionConstraints, type RegisterMcpServerInput, type UpdateAgentInput, createKavachClient };

package/dist/index.js

@@ -0,0 +1,243 @@
+// src/error.ts
+var KavachApiError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(error, status) {
+    super(error.message);
+    this.name = "KavachApiError";
+    this.code = error.code;
+    this.status = status;
+    this.details = error.details;
+  }
+  toKavachError() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details
+    };
+  }
+};
+
+// src/client.ts
+function buildQuery(params) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        parts.push(`${key}=${encodeURIComponent(value.join(","))}`);
+      }
+    } else {
+      parts.push(`${key}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+function createKavachClient(options) {
+  const base = options.baseUrl.replace(/\/$/, "");
+  function buildHeaders(overrides) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    if (options.token) {
+      headers.Authorization = `Bearer ${options.token}`;
+    }
+    if (overrides) {
+      Object.assign(headers, overrides);
+    }
+    return headers;
+  }
+  async function doFetch(path, init = {}) {
+    const { extraHeaders, ...fetchInit } = init;
+    const headers = buildHeaders(extraHeaders);
+    let response;
+    try {
+      response = await fetch(`${base}${path}`, { ...fetchInit, headers });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Network request failed";
+      throw new KavachApiError({ code: "NETWORK_ERROR", message }, 0);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    let body;
+    let parseOk = true;
+    try {
+      body = await response.json();
+    } catch {
+      parseOk = false;
+    }
+    if (!response.ok) {
+      if (parseOk && body !== null && typeof body === "object") {
+        const errBody = body;
+        const inner = typeof errBody.error === "object" && errBody.error !== null ? errBody.error : errBody;
+        const code = typeof inner.code === "string" ? inner.code : "API_ERROR";
+        const message = typeof inner.message === "string" ? inner.message : `HTTP ${response.status}`;
+        throw new KavachApiError({ code, message }, response.status);
+      }
+      throw new KavachApiError(
+        { code: "API_ERROR", message: `HTTP ${response.status}` },
+        response.status
+      );
+    }
+    return body;
+  }
+  async function fetchJson(path, init) {
+    return doFetch(path, init);
+  }
+  async function fetchNullable(path, init) {
+    try {
+      return await fetchJson(path, init);
+    } catch (err) {
+      if (err instanceof KavachApiError && err.status === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async function fetchRaw(path, init) {
+    const headers = buildHeaders();
+    let response;
+    try {
+      response = await fetch(`${base}${path}`, { ...init, headers });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Network request failed";
+      throw new KavachApiError({ code: "NETWORK_ERROR", message }, 0);
+    }
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        throw new KavachApiError(
+          { code: "API_ERROR", message: `HTTP ${response.status}` },
+          response.status
+        );
+      }
+      const errBody = body;
+      const inner = typeof errBody.error === "object" && errBody.error !== null ? errBody.error : errBody;
+      const code = typeof inner.code === "string" ? inner.code : "API_ERROR";
+      const message = typeof inner.message === "string" ? inner.message : `HTTP ${response.status}`;
+      throw new KavachApiError({ code, message }, response.status);
+    }
+    return response.text();
+  }
+  return {
+    // ── Agents ─────────────────────────────────────────────────────────────
+    agents: {
+      create(input) {
+        return fetchJson("/agents", {
+          method: "POST",
+          body: JSON.stringify(input)
+        });
+      },
+      list(filters) {
+        const qs = filters ? buildQuery({
+          userId: filters.userId,
+          status: filters.status,
+          type: filters.type
+        }) : "";
+        return fetchJson(`/agents${qs}`);
+      },
+      get(id) {
+        return fetchNullable(`/agents/${encodeURIComponent(id)}`);
+      },
+      update(id, input) {
+        return fetchJson(`/agents/${encodeURIComponent(id)}`, {
+          method: "PATCH",
+          body: JSON.stringify(input)
+        });
+      },
+      async revoke(id) {
+        await fetchJson(`/agents/${encodeURIComponent(id)}`, {
+          method: "DELETE"
+        });
+      },
+      rotate(id) {
+        return fetchJson(`/agents/${encodeURIComponent(id)}/rotate`, {
+          method: "POST"
+        });
+      }
+    },
+    // ── Authorization ───────────────────────────────────────────────────────
+    authorize(agentId, request) {
+      return fetchJson(`/agents/${encodeURIComponent(agentId)}/authorize`, {
+        method: "POST",
+        body: JSON.stringify(request)
+      });
+    },
+    authorizeByToken(token, request) {
+      return fetchJson("/authorize", {
+        method: "POST",
+        body: JSON.stringify(request),
+        // override the client-level token with the agent-specific token
+        extraHeaders: { Authorization: `Bearer ${token}` }
+      });
+    },
+    // ── Delegations ─────────────────────────────────────────────────────────
+    delegations: {
+      create(input) {
+        return fetchJson("/delegations", {
+          method: "POST",
+          body: JSON.stringify(input)
+        });
+      },
+      list(agentId) {
+        return fetchJson(`/delegations/${encodeURIComponent(agentId)}`);
+      },
+      async revoke(id) {
+        await fetchJson(`/delegations/${encodeURIComponent(id)}`, {
+          method: "DELETE"
+        });
+      },
+      getEffectivePermissions(agentId) {
+        return fetchJson(`/delegations/${encodeURIComponent(agentId)}/permissions`);
+      }
+    },
+    // ── Audit ───────────────────────────────────────────────────────────────
+    audit: {
+      query(filters) {
+        const qs = filters ? buildQuery({
+          agentId: filters.agentId,
+          userId: filters.userId,
+          since: filters.since,
+          until: filters.until,
+          actions: filters.actions,
+          result: filters.result,
+          limit: filters.limit,
+          offset: filters.offset
+        }) : "";
+        return fetchJson(`/audit${qs}`);
+      },
+      export(options2) {
+        const qs = buildQuery({
+          format: options2.format,
+          since: options2.since,
+          until: options2.until
+        });
+        return fetchRaw(`/audit/export${qs}`);
+      }
+    },
+    // ── MCP servers ─────────────────────────────────────────────────────────
+    mcp: {
+      register(input) {
+        return fetchJson("/mcp/servers", {
+          method: "POST",
+          body: JSON.stringify(input)
+        });
+      },
+      list() {
+        return fetchJson("/mcp/servers");
+      },
+      get(id) {
+        return fetchNullable(`/mcp/servers/${encodeURIComponent(id)}`);
+      }
+    }
+  };
+}
+export {
+  KavachApiError,
+  createKavachClient
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@kavachos/client",
+  "version": "0.0.2",
+  "description": "TypeScript client for the KavachOS REST API",
+  "license": "MIT",
+  "author": "KavachOS <hello@kavachos.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kavachos/kavachos.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}