agentcheck-sdk 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# agentcheck-sdk
+
+Record what your AI agent is allowed to do.
+
+## Install
+
+```bash
+npm install agentcheck-sdk
+```
+
+## Quickstart
+
+```typescript
+import { AgentCheckClient } from "agentcheck-sdk";
+
+const client = new AgentCheckClient("ak_live_...");
+
+// Create agreement - one call
+const proof = await client.record({
+  agent: "factory-bot",
+  scope: "order parts under $10K, monitor equipment 24/7",
+  authorized_by: "kim@factory.com",
+});
+
+// Kim gets an email, clicks "Approve"
+
+// Check status
+const record = await client.get(proof.id);
+console.log(record.status); // "approved"
+
+// List all
+const records = await client.list({ status: "approved" });
+
+// Revoke immediately
+await client.revoke(proof.id, "Security incident");
+```
+
+## Webhook Verification
+
+```typescript
+import { WebhookHandler } from "agentcheck-sdk";
+
+const handler = new WebhookHandler("whsec_...");
+
+// In your webhook endpoint
+const event = handler.verifyAndParse(req.body, req.headers["x-agentcheck-signature"]);
+
+if (event.type === "record.approved") {
+  enableAgent(event.data.agreement_id);
+}
+```
+
+## Sign Up
+
+```typescript
+import { AgentCheckClient } from "agentcheck-sdk";
+
+const result = await AgentCheckClient.signup("dev@company.com", "My Company");
+console.log(result.api_key); // Save this - shown once only
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+import { Agreement, AgreementList, AmendParams, CreateRecordParams, ListParams, SignupResult, WebhookResult } from "./types";
+export declare class AgentCheckClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    /** Create a new agreement and send approval email. */
+    record(params: CreateRecordParams): Promise<Agreement>;
+    /** Get agreement details by ID. */
+    get(agreementId: string): Promise<Agreement>;
+    /** List agreements with optional filters. */
+    list(params?: ListParams): Promise<AgreementList>;
+    /** Amend an agreement's scope. */
+    amend(agreementId: string, params: AmendParams): Promise<Agreement>;
+    /** Revoke an agreement immediately. */
+    revoke(agreementId: string, reason: string): Promise<Agreement>;
+    /** Register a webhook endpoint. */
+    registerWebhook(url: string, events: string[]): Promise<WebhookResult>;
+    /** Self-service signup. Returns API key (shown once). */
+    static signup(email: string, companyName?: string, baseUrl?: string): Promise<SignupResult>;
+}

package/dist/client.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentCheckClient = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_BASE_URL = "https://agentcheck.spaceplanning.work";
+class AgentCheckClient {
+    constructor(apiKey, baseUrl = DEFAULT_BASE_URL) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async request(method, path, body, auth = true) {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (auth) {
+            headers["X-API-Key"] = this.apiKey;
+        }
+        const resp = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (resp.status === 401)
+            throw new errors_1.AuthenticationError();
+        if (resp.status === 404)
+            throw new errors_1.NotFoundError();
+        if (resp.status === 429)
+            throw new errors_1.RateLimitError();
+        const data = (await resp.json());
+        if (resp.status === 400) {
+            throw new errors_1.ValidationError(data.error?.message ?? "Bad request");
+        }
+        if (!resp.ok) {
+            throw new errors_1.AgentCheckError(data.error?.message ?? `HTTP ${resp.status}`, data.error?.code ?? "server_error");
+        }
+        return data.data;
+    }
+    /** Create a new agreement and send approval email. */
+    async record(params) {
+        return this.request("POST", "/api/v1/record", params);
+    }
+    /** Get agreement details by ID. */
+    async get(agreementId) {
+        return this.request("GET", `/api/v1/record/${agreementId}`);
+    }
+    /** List agreements with optional filters. */
+    async list(params = {}) {
+        const query = new URLSearchParams();
+        if (params.status)
+            query.set("status", params.status);
+        if (params.agent)
+            query.set("agent", params.agent);
+        if (params.limit)
+            query.set("limit", String(params.limit));
+        if (params.offset)
+            query.set("offset", String(params.offset));
+        const qs = query.toString();
+        return this.request("GET", `/api/v1/records${qs ? `?${qs}` : ""}`);
+    }
+    /** Amend an agreement's scope. */
+    async amend(agreementId, params) {
+        return this.request("POST", `/api/v1/record/${agreementId}/amend`, params);
+    }
+    /** Revoke an agreement immediately. */
+    async revoke(agreementId, reason) {
+        return this.request("POST", `/api/v1/record/${agreementId}/revoke`, { reason });
+    }
+    /** Register a webhook endpoint. */
+    async registerWebhook(url, events) {
+        return this.request("POST", "/api/v1/webhooks", {
+            url,
+            events,
+        });
+    }
+    /** Self-service signup. Returns API key (shown once). */
+    static async signup(email, companyName, baseUrl = DEFAULT_BASE_URL) {
+        const body = { email };
+        if (companyName)
+            body.company_name = companyName;
+        const resp = await fetch(`${baseUrl}/api/v1/signup`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (resp.status === 429)
+            throw new errors_1.RateLimitError();
+        const data = (await resp.json());
+        if (!resp.ok) {
+            throw new errors_1.AgentCheckError(data.error?.message ?? "Signup failed", data.error?.code ?? "signup_error");
+        }
+        return data.data;
+    }
+}
+exports.AgentCheckClient = AgentCheckClient;

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export declare class AgentCheckError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+export declare class AuthenticationError extends AgentCheckError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends AgentCheckError {
+    constructor(message?: string);
+}
+export declare class ValidationError extends AgentCheckError {
+    constructor(message: string);
+}
+export declare class RateLimitError extends AgentCheckError {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = void 0;
+class AgentCheckError extends Error {
+    constructor(message, code = "unknown") {
+        super(message);
+        this.name = "AgentCheckError";
+        this.code = code;
+    }
+}
+exports.AgentCheckError = AgentCheckError;
+class AuthenticationError extends AgentCheckError {
+    constructor(message = "Invalid API key") {
+        super(message, "unauthorized");
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class NotFoundError extends AgentCheckError {
+    constructor(message = "Resource not found") {
+        super(message, "not_found");
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ValidationError extends AgentCheckError {
+    constructor(message) {
+        super(message, "bad_request");
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class RateLimitError extends AgentCheckError {
+    constructor(message = "Rate limited") {
+        super(message, "rate_limited");
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AgentCheckClient } from "./client";
+export { WebhookHandler } from "./webhook";
+export type { WebhookEvent } from "./webhook";
+export { AgentCheckError, AuthenticationError, NotFoundError, ValidationError, RateLimitError, } from "./errors";
+export type { Agreement, AgreementList, SignupResult, WebhookResult, CreateRecordParams, ListParams, AmendParams, } from "./types";

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.AgentCheckError = exports.WebhookHandler = exports.AgentCheckClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AgentCheckClient", { enumerable: true, get: function () { return client_1.AgentCheckClient; } });
+var webhook_1 = require("./webhook");
+Object.defineProperty(exports, "WebhookHandler", { enumerable: true, get: function () { return webhook_1.WebhookHandler; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AgentCheckError", { enumerable: true, get: function () { return errors_1.AgentCheckError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export interface Agreement {
+    id: string;
+    status: "pending" | "approved" | "rejected" | "expired" | "revoked";
+    agent: string;
+    agent_provider?: string;
+    scope: string;
+    authorized_by: string;
+    created_at: string;
+    approved_at?: string;
+    expires_at?: string;
+    verify_url: string;
+    signature?: string;
+    sig_algorithm: string;
+}
+export interface AgreementList {
+    records: Agreement[];
+    limit: number;
+    offset: number;
+}
+export interface SignupResult {
+    api_key: string;
+    email: string;
+    message: string;
+}
+export interface WebhookResult {
+    id: string;
+    url: string;
+    events: string[];
+    secret: string;
+    active: boolean;
+}
+export interface CreateRecordParams {
+    agent: string;
+    scope: string;
+    authorized_by: string;
+    agent_provider?: string;
+    expires_in_days?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ListParams {
+    status?: string;
+    agent?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface AmendParams {
+    new_scope: string;
+    reason?: string;
+    require_reauth?: boolean;
+}
+export interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+}
+export interface ApiError {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/webhook.d.ts

@@ -0,0 +1,12 @@
+export interface WebhookEvent {
+    id: string;
+    type: string;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+export declare class WebhookHandler {
+    private secret;
+    constructor(secret: string);
+    /** Verify HMAC signature and parse webhook payload. */
+    verifyAndParse(body: string | Buffer, signature: string): WebhookEvent;
+}

package/dist/webhook.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHandler = void 0;
+const crypto_1 = require("crypto");
+const errors_1 = require("./errors");
+class WebhookHandler {
+    constructor(secret) {
+        this.secret = secret;
+    }
+    /** Verify HMAC signature and parse webhook payload. */
+    verifyAndParse(body, signature) {
+        const bodyStr = typeof body === "string" ? body : body.toString("utf-8");
+        const expected = (0, crypto_1.createHmac)("sha256", this.secret)
+            .update(bodyStr)
+            .digest("hex");
+        const sigBuf = Buffer.from(signature, "utf-8");
+        const expBuf = Buffer.from(expected, "utf-8");
+        if (sigBuf.length !== expBuf.length ||
+            !(0, crypto_1.timingSafeEqual)(sigBuf, expBuf)) {
+            throw new errors_1.AgentCheckError("Invalid webhook signature", "invalid_signature");
+        }
+        const payload = JSON.parse(bodyStr);
+        return {
+            id: payload.id,
+            type: payload.type,
+            created_at: payload.created_at,
+            data: payload.data ?? {},
+        };
+    }
+}
+exports.WebhookHandler = WebhookHandler;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "agentcheck-sdk",
+  "version": "0.1.0",
+  "description": "Record what your AI agent is allowed to do",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "delegation",
+    "trust",
+    "authorization"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.0.0"
+  }
+}