@keelapi/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keel
+
+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/README.md

@@ -0,0 +1,196 @@
+# @keelapi/sdk
+
+TypeScript SDK for the [Keel](https://keel.so) AI governance API.
+
+Keel lets you issue permits before AI calls, enforce policies, track usage, and audit decisions — across any provider.
+
+## Install
+
+```bash
+npm install @keelapi/sdk
+```
+
+## Setup
+
+```ts
+import { KeelClient } from "@keelapi/sdk";
+
+const client = new KeelClient({
+  baseUrl: process.env.KEEL_BASE_URL!,
+  apiKey: process.env.KEEL_API_KEY!,
+});
+```
+
+## Permits
+
+Request a permit before making an AI call:
+
+```ts
+const permit = await client.permits.create({
+  project_id: "proj_123",
+  idempotency_key: crypto.randomUUID(),
+  subject: { type: "user", id: "usr_123" },
+  action: { name: "ai.generate" },
+  resource: {
+    type: "request",
+    id: "req_123",
+    attributes: {
+      provider: "openai",
+      model: "gpt-4o-mini",
+      estimated_input_tokens: 200,
+      estimated_output_tokens: 500,
+    },
+  },
+});
+
+if (permit.decision === "allow") {
+  // proceed with AI call
+}
+```
+
+### Dry run
+
+```ts
+const result = await client.permits.dryRun(permitRequest);
+```
+
+### List and get
+
+```ts
+const list = await client.permits.list({ project_id: "proj_123", limit: 50 });
+const permit = await client.permits.get("permit_id");
+```
+
+### Report usage
+
+```ts
+await client.permits.reportUsage("permit_id", {
+  input_tokens: 180,
+  output_tokens: 420,
+});
+```
+
+### Attestation, evidence, lineage
+
+```ts
+await client.permits.attest("permit_id", { outcome: "success" });
+await client.permits.addEvidence("permit_id", { label: "response_hash", value: "abc123" });
+const evidence = await client.permits.listEvidence("permit_id");
+const lineage = await client.permits.lineage("permit_id");
+const bundle = await client.permits.bundle("permit_id");
+```
+
+## Executions
+
+Run a model synchronously:
+
+```ts
+const result = await client.executions.create({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Summarize this document." }],
+  permit_id: permit.id,
+});
+```
+
+Stream tokens as they arrive:
+
+```ts
+for await (const event of client.executions.stream({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Write a poem." }],
+  permit_id: permit.id,
+})) {
+  if (event.type === "content_delta") process.stdout.write(event.delta);
+  if (event.type === "done") console.log("\nFinished.");
+}
+```
+
+## Execute (unified)
+
+```ts
+const result = await client.execute.run({
+  model: "gpt-4o-mini",
+  input: "Translate to Spanish: Hello world",
+  provider: "openai",
+});
+```
+
+## Proxy
+
+Pass requests through to providers with Keel governance applied:
+
+```ts
+const response = await client.proxy.openai({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+// Also: client.proxy.anthropic(), .google(), .xai(), .meta()
+```
+
+## Jobs
+
+Submit async jobs and poll for results:
+
+```ts
+const job = await client.jobs.create({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Analyze this dataset." }],
+});
+
+const status = await client.jobs.get(job.job_id);
+// status.status: "pending" | "running" | "completed" | "failed"
+```
+
+## API Keys
+
+```ts
+const key = await client.apiKeys.create();
+const keys = await client.apiKeys.list();
+const single = await client.apiKeys.get(key.id);
+await client.apiKeys.revoke(key.id);
+```
+
+## Request Timeline
+
+```ts
+const timeline = await client.requests.timeline("request_id");
+```
+
+## Error Handling
+
+```ts
+import { KeelError } from "@keelapi/sdk";
+
+try {
+  await client.permits.create(request);
+} catch (err) {
+  if (err instanceof KeelError) {
+    console.error(err.status);  // HTTP status code
+    console.error(err.code);    // e.g. "permit_denied"
+    console.error(err.message); // human-readable message
+    console.error(err.field);   // field that caused the error, if any
+  }
+}
+```
+
+## Freshness Headers
+
+For replay-protected endpoints, enable freshness headers:
+
+```ts
+const client = new KeelClient({
+  baseUrl: process.env.KEEL_BASE_URL!,
+  apiKey: process.env.KEEL_API_KEY!,
+  requestFreshness: { enabled: true },
+});
+```
+
+This adds `X-Keel-Timestamp` and `X-Keel-Nonce` to every request.
+
+## License
+
+MIT

package/dist/examples/express.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/express.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const src_1 = require("../src");
+const app = (0, express_1.default)();
+app.use(express_1.default.json());
+app.get("/protected", (0, src_1.keelExpress)({
+    projectId: "prj_demo",
+    getSubject: (req) => ({
+        type: "user",
+        id: String(req.header("x-user-id") || "anonymous"),
+        attributes: {},
+    }),
+    getResource: (req) => ({
+        type: "request",
+        id: `${req.method}:${req.path}`,
+        attributes: {
+            provider: "openai",
+            model: "gpt-4o-mini",
+            estimated_input_tokens: 16,
+            estimated_output_tokens: 32,
+            max_output_tokens_requested: 128,
+        },
+    }),
+}), (_req, res) => {
+    res.json({ ok: true });
+});
+app.listen(3000, () => {
+    console.log("Express example listening on http://localhost:3000");
+});

package/dist/examples/next-route.d.ts

@@ -0,0 +1,6 @@
+import { type NextApiRequestLike, type NextApiResponseLike } from "../src";
+type Req = NextApiRequestLike & {
+    headers?: Record<string, string | string[] | undefined>;
+};
+declare const _default: import("../src").NextApiHandler<Req, NextApiResponseLike>;
+export default _default;

package/dist/examples/next-route.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const src_1 = require("../src");
+async function handler(_req, res) {
+    res.status(200).json({ ok: true });
+}
+exports.default = (0, src_1.withKeel)(handler, {
+    projectId: "prj_demo",
+    getSubject: (req) => {
+        const rawHeader = req.headers?.["x-user-id"];
+        const id = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+        return {
+            type: "user",
+            id: id || "anonymous",
+            attributes: {},
+        };
+    },
+    getResource: (req) => ({
+        type: "request",
+        id: `${req.method || "GET"}:${req.url || ""}`,
+        attributes: {
+            provider: "openai",
+            model: "gpt-4o-mini",
+            estimated_input_tokens: 16,
+            estimated_output_tokens: 32,
+            max_output_tokens_requested: 128,
+        },
+    }),
+});

package/dist/examples/permit.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/permit.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const src_1 = require("../src");
+async function main() {
+    const baseUrl = process.env.KEEL_BASE_URL;
+    const apiKey = process.env.KEEL_API_KEY;
+    if (!baseUrl) {
+        throw new Error("KEEL_BASE_URL is required");
+    }
+    if (!apiKey) {
+        throw new Error("KEEL_API_KEY is required");
+    }
+    const client = new src_1.KeelClient({ baseUrl, apiKey });
+    const request = {
+        project_id: "prj_demo",
+        idempotency_key: `idem_example_${Date.now()}`,
+        subject: {
+            type: "user",
+            id: "usr_example",
+            attributes: {},
+        },
+        action: {
+            name: "ai.generate.summary",
+            attributes: {},
+        },
+        resource: {
+            type: "request",
+            id: "req_example",
+            attributes: {
+                provider: "openai",
+                model: "gpt-4o-mini",
+                estimated_input_tokens: 10,
+                estimated_output_tokens: 20,
+                max_output_tokens_requested: 64,
+            },
+        },
+    };
+    const permit = await client.createPermit(request);
+    console.log(`decision=${permit.decision} reason=${permit.reason}`);
+}
+main().catch((error) => {
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    else {
+        console.error(error);
+    }
+    process.exit(1);
+});

package/dist/src/client.d.ts

@@ -0,0 +1,28 @@
+import { PermitsClient } from "./clients/permits";
+import { ExecutionsClient } from "./clients/executions";
+import { ExecuteClient } from "./clients/execute";
+import { ProxyClient } from "./clients/proxy";
+import { JobsClient } from "./clients/jobs";
+import { RequestsClient } from "./clients/requests";
+import { type HttpTransportOptions, type RequestFreshnessOptions, type RequestIdProvider } from "./http";
+import type { AuthedHealthResponse, CreateApiKeyResponse, HealthResponse, ListApiKeysResponse, PermitRequest, PermitResponse, PermitWithMetaResponse } from "./types";
+export type { RequestIdProvider, RequestFreshnessOptions };
+export interface KeelClientOptions extends HttpTransportOptions {
+}
+export declare class KeelClient {
+    readonly permits: PermitsClient;
+    readonly executions: ExecutionsClient;
+    readonly execute: ExecuteClient;
+    readonly proxy: ProxyClient;
+    readonly jobs: JobsClient;
+    readonly requests: RequestsClient;
+    private readonly http;
+    constructor(options: KeelClientOptions);
+    createPermit(request: PermitRequest): Promise<PermitResponse>;
+    createPermitWithMeta(request: PermitRequest): Promise<PermitWithMetaResponse>;
+    createApiKey(): Promise<CreateApiKeyResponse>;
+    listApiKeys(): Promise<ListApiKeysResponse>;
+    revokeApiKey(keyId: string): Promise<void>;
+    getHealth(): Promise<HealthResponse>;
+    getAuthedHealth(): Promise<AuthedHealthResponse>;
+}

package/dist/src/client.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeelClient = void 0;
+const permits_1 = require("./clients/permits");
+const executions_1 = require("./clients/executions");
+const execute_1 = require("./clients/execute");
+const proxy_1 = require("./clients/proxy");
+const jobs_1 = require("./clients/jobs");
+const requests_1 = require("./clients/requests");
+const http_1 = require("./http");
+class KeelClient {
+    constructor(options) {
+        this.http = new http_1.HttpTransport(options);
+        this.permits = new permits_1.PermitsClient(this.http);
+        this.executions = new executions_1.ExecutionsClient(this.http);
+        this.execute = new execute_1.ExecuteClient(this.http);
+        this.proxy = new proxy_1.ProxyClient(this.http);
+        this.jobs = new jobs_1.JobsClient(this.http);
+        this.requests = new requests_1.RequestsClient(this.http);
+    }
+    async createPermit(request) {
+        return this.permits.create(request);
+    }
+    async createPermitWithMeta(request) {
+        return this.permits.createWithMeta(request);
+    }
+    async createApiKey() {
+        const { payload, request_id } = await this.http.postWithMeta("/v1/api-keys");
+        return { ...payload, request_id };
+    }
+    async listApiKeys() {
+        const { payload, request_id } = await this.http.getWithMeta("/v1/api-keys");
+        return { ...payload, request_id };
+    }
+    async revokeApiKey(keyId) {
+        if (!keyId || !keyId.trim()) {
+            throw new Error("keyId is required");
+        }
+        await this.http.delete(`/v1/api-keys/${encodeURIComponent(keyId)}`);
+    }
+    async getHealth() {
+        return this.http.get("/health");
+    }
+    async getAuthedHealth() {
+        return this.http.get("/v1/health");
+    }
+}
+exports.KeelClient = KeelClient;

package/dist/src/clients/execute.d.ts

@@ -0,0 +1,8 @@
+import type { HttpTransport } from "../http";
+import type { ExecuteRequest, ExecutionResponse, RoutingProvider } from "../types";
+export declare class ExecuteClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    run(request: ExecuteRequest): Promise<ExecutionResponse>;
+    run(model: string, input: Record<string, unknown>, provider?: RoutingProvider): Promise<ExecutionResponse>;
+}

package/dist/src/clients/execute.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecuteClient = void 0;
+class ExecuteClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async run(requestOrModel, input, provider) {
+        const body = typeof requestOrModel === "string"
+            ? { model: requestOrModel, input: input, provider }
+            : requestOrModel;
+        return this.http.post("/v1/execute", body);
+    }
+}
+exports.ExecuteClient = ExecuteClient;

package/dist/src/clients/executions.d.ts

@@ -0,0 +1,9 @@
+import type { HttpTransport } from "../http";
+import type { ExecutionCreateRequest, ExecutionResponse, ExecutionStreamEvent, ExecutionTimelineResponse } from "../types";
+export declare class ExecutionsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    create(request: ExecutionCreateRequest): Promise<ExecutionResponse>;
+    stream(request: ExecutionCreateRequest): Promise<AsyncGenerator<ExecutionStreamEvent>>;
+    get(requestId: string): Promise<ExecutionTimelineResponse>;
+}

package/dist/src/clients/executions.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionsClient = void 0;
+const streaming_1 = require("../streaming");
+class ExecutionsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async create(request) {
+        const body = { ...request, mode: "sync" };
+        return this.http.post("/v1/executions", body);
+    }
+    async stream(request) {
+        const body = { ...request, mode: "stream" };
+        const response = await this.http.postStream("/v1/executions", body);
+        return (0, streaming_1.parseSSEStream)(response);
+    }
+    async get(requestId) {
+        return this.http.get(`/v1/executions/${encodeURIComponent(requestId)}`);
+    }
+}
+exports.ExecutionsClient = ExecutionsClient;

package/dist/src/clients/jobs.d.ts

@@ -0,0 +1,8 @@
+import type { HttpTransport } from "../http";
+import type { JobCreateResponse, JobStatusResponse, JobSubmitRequest } from "../types";
+export declare class JobsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    create(request: JobSubmitRequest): Promise<JobCreateResponse>;
+    get(jobId: string): Promise<JobStatusResponse>;
+}

package/dist/src/clients/jobs.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobsClient = void 0;
+class JobsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async create(request) {
+        return this.http.post("/v1/jobs", request);
+    }
+    async get(jobId) {
+        return this.http.get(`/v1/jobs/${encodeURIComponent(jobId)}`);
+    }
+}
+exports.JobsClient = JobsClient;

package/dist/src/clients/permits.d.ts

@@ -0,0 +1,18 @@
+import type { HttpTransport } from "../http";
+import type { PermitAttestationRequest, PermitAuditBundle, PermitAuditItem, PermitAuditListResponse, PermitDryRunResponse, PermitEvidenceCreateRequest, PermitEvidenceListResponse, PermitEvidenceOut, PermitExportFormat, PermitLineageResponse, PermitListParams, PermitRequest, PermitResponse, PermitUsageReportRequest, PermitUsageReportResponse, PermitWithMetaResponse } from "../types";
+export declare class PermitsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    create(request: PermitRequest): Promise<PermitResponse>;
+    createWithMeta(request: PermitRequest): Promise<PermitWithMetaResponse>;
+    dryRun(request: PermitRequest): Promise<PermitDryRunResponse>;
+    list(params?: PermitListParams): Promise<PermitAuditListResponse>;
+    get(permitId: string): Promise<PermitAuditItem>;
+    export(from: string, to: string, format?: PermitExportFormat): Promise<unknown>;
+    reportUsage(permitId: string, request: PermitUsageReportRequest): Promise<PermitUsageReportResponse>;
+    attest(permitId: string, request: PermitAttestationRequest): Promise<PermitResponse>;
+    addEvidence(permitId: string, request: PermitEvidenceCreateRequest): Promise<PermitEvidenceOut>;
+    listEvidence(permitId: string): Promise<PermitEvidenceListResponse>;
+    lineage(permitId: string): Promise<PermitLineageResponse>;
+    bundle(permitId: string): Promise<PermitAuditBundle>;
+}

package/dist/src/clients/permits.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermitsClient = void 0;
+class PermitsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async create(request) {
+        return this.http.post("/v1/permits", request);
+    }
+    async createWithMeta(request) {
+        const { payload, request_id } = await this.http.postWithMeta("/v1/permits", request);
+        return { permit: payload, request_id };
+    }
+    async dryRun(request) {
+        return this.http.post("/v1/permits/dry-run", request);
+    }
+    async list(params) {
+        const query = {};
+        if (params) {
+            if (params.limit !== undefined)
+                query.limit = String(params.limit);
+            if (params.project_id)
+                query.project_id = params.project_id;
+            if (params.before)
+                query.before = params.before;
+            if (params.subject_id)
+                query.subject_id = params.subject_id;
+            if (params.subject_type)
+                query.subject_type = params.subject_type;
+            if (params.action_name)
+                query.action_name = params.action_name;
+            if (params.start_date)
+                query.start_date = params.start_date;
+            if (params.end_date)
+                query.end_date = params.end_date;
+            if (params.decision)
+                query.decision = params.decision;
+        }
+        return this.http.get("/v1/permits", query);
+    }
+    async get(permitId) {
+        return this.http.get(`/v1/permits/${encodeURIComponent(permitId)}`);
+    }
+    async export(from, to, format = "json") {
+        const query = { from, to, format };
+        if (format === "csv") {
+            const response = await this.http.getRaw("/v1/permits/export", query);
+            return response.text();
+        }
+        return this.http.get("/v1/permits/export", query);
+    }
+    async reportUsage(permitId, request) {
+        return this.http.post(`/v1/permits/${encodeURIComponent(permitId)}/usage`, request);
+    }
+    async attest(permitId, request) {
+        return this.http.post(`/v1/permits/${encodeURIComponent(permitId)}/attest`, request);
+    }
+    async addEvidence(permitId, request) {
+        return this.http.post(`/v1/permits/${encodeURIComponent(permitId)}/evidence`, request);
+    }
+    async listEvidence(permitId) {
+        return this.http.get(`/v1/permits/${encodeURIComponent(permitId)}/evidence`);
+    }
+    async lineage(permitId) {
+        return this.http.get(`/v1/permits/${encodeURIComponent(permitId)}/lineage`);
+    }
+    async bundle(permitId) {
+        return this.http.get(`/v1/permits/${encodeURIComponent(permitId)}/bundle`);
+    }
+}
+exports.PermitsClient = PermitsClient;

package/dist/src/clients/proxy.d.ts

@@ -0,0 +1,10 @@
+import type { HttpTransport } from "../http";
+export declare class ProxyClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    openai<T = unknown>(payload: Record<string, unknown>): Promise<T>;
+    anthropic<T = unknown>(payload: Record<string, unknown>): Promise<T>;
+    google<T = unknown>(payload: Record<string, unknown>): Promise<T>;
+    xai<T = unknown>(payload: Record<string, unknown>): Promise<T>;
+    meta<T = unknown>(payload: Record<string, unknown>): Promise<T>;
+}

package/dist/src/clients/proxy.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyClient = void 0;
+class ProxyClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async openai(payload) {
+        return this.http.post("/v1/proxy/openai", payload);
+    }
+    async anthropic(payload) {
+        return this.http.post("/v1/proxy/anthropic", payload);
+    }
+    async google(payload) {
+        return this.http.post("/v1/proxy/google", payload);
+    }
+    async xai(payload) {
+        return this.http.post("/v1/proxy/xai", payload);
+    }
+    async meta(payload) {
+        return this.http.post("/v1/proxy/meta", payload);
+    }
+}
+exports.ProxyClient = ProxyClient;

package/dist/src/clients/requests.d.ts

@@ -0,0 +1,7 @@
+import type { HttpTransport } from "../http";
+import type { RequestTimelineResponse } from "../types";
+export declare class RequestsClient {
+    private readonly http;
+    constructor(http: HttpTransport);
+    timeline(requestId: string): Promise<RequestTimelineResponse>;
+}

package/dist/src/clients/requests.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestsClient = void 0;
+class RequestsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    async timeline(requestId) {
+        return this.http.get(`/v1/requests/${encodeURIComponent(requestId)}/timeline`);
+    }
+}
+exports.RequestsClient = RequestsClient;

package/dist/src/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class KeelError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly field?: string;
+    readonly details?: unknown;
+    constructor(status: number, message: string, details?: unknown, code?: string, field?: string);
+}