@auctra/sdk 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @auctra/sdk
+
+Official TypeScript SDK for [Auctra](https://auctra.tech) — authority infrastructure for AI agents.
+
+Evaluate every agent action against delegated authority and org policies before execution.
+
+## Install
+
+```bash
+npm install @auctra/sdk
+```
+
+## Quick start
+
+```typescript
+import { Auctra } from "@auctra/sdk";
+
+const auctra = new Auctra({
+  apiKey: process.env.AUCTRA_API_KEY!,
+  // baseUrl defaults to https://console.auctra.tech
+});
+
+const decision = await auctra.evaluateAction({
+  agentId: "your-agent-uuid",
+  actionType: "send_payment",
+  payload: { amount: 1200, currency: "USD" },
+});
+
+if (decision.decision === "allowed") {
+  // proceed with action
+} else if (decision.decision === "require_approval") {
+  // pause for human review
+  console.log(decision.reason, decision.action_request_id);
+} else {
+  throw new Error(decision.reason);
+}
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `evaluateAction(input)` | Check authority before an agent acts |
+| `listAgents()` | List registered agents |
+| `createAgent(input)` | Register a new agent |
+| `listDelegations()` | List authority delegations |
+| `createDelegation(input)` | Grant bounded authority |
+| `revokeDelegation(id)` | Revoke a delegation |
+| `listActionRequests()` | List recent evaluations |
+| `approveActionRequest(id)` | Approve pending action |
+| `rejectActionRequest(id)` | Reject pending action |
+| `escalateActionRequest(id)` | Escalate for review |
+| `listPolicies()` | List org policies |
+| `listAuditEvents()` | List audit ledger events |
+
+## Get an API key
+
+1. Sign in to the [Auctra console](https://console.auctra.tech/auth/login)
+2. Go to **API Keys** → **Create API key**
+3. Use a key with `write` permission for `evaluateAction`
+
+## Publish to npm
+
+```bash
+cd packages/sdk
+npm login          # one-time, needs npm account with @auctra scope access
+npm run build
+npm publish --access public
+```
+
+Or from repo root: `npm run publish:sdk`
+
+Set `NPM_TOKEN` in GitHub Actions secrets if you add a publish workflow later.

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+export type EvaluateActionInput = {
+    agentId: string;
+    actionType: string;
+    payload?: Record<string, unknown>;
+};
+export type EvaluateActionResponse = {
+    decision: "allowed" | "blocked" | "require_approval";
+    risk_score: number;
+    reason: string;
+    delegation_id: string | null;
+    delegator: string | null;
+    sponsor: string;
+    matched_policies: string[];
+    action_request_id: string;
+};
+export type AuctraClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+};
+export declare class Auctra {
+    private apiKey;
+    private baseUrl;
+    constructor(options: AuctraClientOptions);
+    private request;
+    evaluateAction(input: EvaluateActionInput): Promise<EvaluateActionResponse>;
+    listAgents(): Promise<{
+        agents: unknown[];
+    }>;
+    getAgent(agentId: string): Promise<{
+        agent: unknown;
+    }>;
+    createAgent(input: {
+        name: string;
+        modelProvider: string;
+        modelName: string;
+        description?: string;
+        environment?: string;
+        authorityLevel?: string;
+        sponsorUserId?: string;
+    }): Promise<unknown>;
+    listDelegations(): Promise<{
+        delegations: unknown[];
+    }>;
+    createDelegation(input: {
+        agentId: string;
+        actionTypes: string[];
+        validUntil: string;
+        maxAmount?: number;
+        currency?: string;
+        delegatorUserId?: string;
+    }): Promise<unknown>;
+    revokeDelegation(delegationId: string): Promise<unknown>;
+    listActionRequests(): Promise<{
+        action_requests: unknown[];
+    }>;
+    approveActionRequest(actionRequestId: string, reason?: string): Promise<unknown>;
+    rejectActionRequest(actionRequestId: string, reason?: string): Promise<unknown>;
+    escalateActionRequest(actionRequestId: string, reason?: string): Promise<unknown>;
+    listPolicies(): Promise<{
+        policies: unknown[];
+    }>;
+    listAuditEvents(): Promise<{
+        audit_events: unknown[];
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,kBAAkB,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,mBAAmB;YAK1B,OAAO;IAqBf,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAQ3E,UAAU;gBACgB,OAAO,EAAE;;IAGnC,QAAQ,CAAC,OAAO,EAAE,MAAM;eACC,OAAO;;IAGhC,WAAW,CAAC,KAAK,EAAE;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYK,eAAe;qBACgB,OAAO,EAAE;;IAGxC,gBAAgB,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;IAWK,gBAAgB,CAAC,YAAY,EAAE,MAAM;IAIrC,kBAAkB;yBACiB,OAAO,EAAE;;IAG5C,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM7D,mBAAmB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM5D,qBAAqB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM9D,YAAY;kBACgB,OAAO,EAAE;;IAGrC,eAAe;sBACiB,OAAO,EAAE;;CAEhD"}

package/dist/index.js

@@ -0,0 +1,87 @@
+export class Auctra {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://console.auctra.tech").replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                ...(body ? { "content-type": "application/json" } : {}),
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new Error(data.error ?? `Auctra API error (${response.status})`);
+        }
+        return data;
+    }
+    async evaluateAction(input) {
+        return this.request("POST", "/v1/action-requests/evaluate", {
+            agent_id: input.agentId,
+            action_type: input.actionType,
+            payload: input.payload ?? {},
+        });
+    }
+    async listAgents() {
+        return this.request("GET", "/v1/agents");
+    }
+    async getAgent(agentId) {
+        return this.request("GET", `/v1/agents/${agentId}`);
+    }
+    async createAgent(input) {
+        return this.request("POST", "/v1/agents", {
+            name: input.name,
+            model_provider: input.modelProvider,
+            model_name: input.modelName,
+            description: input.description,
+            environment: input.environment,
+            authority_level: input.authorityLevel,
+            sponsor_user_id: input.sponsorUserId,
+        });
+    }
+    async listDelegations() {
+        return this.request("GET", "/v1/delegations");
+    }
+    async createDelegation(input) {
+        return this.request("POST", "/v1/delegations", {
+            agent_id: input.agentId,
+            action_types: input.actionTypes,
+            valid_until: input.validUntil,
+            max_amount: input.maxAmount,
+            currency: input.currency,
+            delegator_user_id: input.delegatorUserId,
+        });
+    }
+    async revokeDelegation(delegationId) {
+        return this.request("POST", `/v1/delegations/${delegationId}/revoke`, {});
+    }
+    async listActionRequests() {
+        return this.request("GET", "/v1/action-requests");
+    }
+    async approveActionRequest(actionRequestId, reason) {
+        return this.request("POST", `/v1/action-requests/${actionRequestId}/approve`, {
+            reason,
+        });
+    }
+    async rejectActionRequest(actionRequestId, reason) {
+        return this.request("POST", `/v1/action-requests/${actionRequestId}/reject`, {
+            reason,
+        });
+    }
+    async escalateActionRequest(actionRequestId, reason) {
+        return this.request("POST", `/v1/action-requests/${actionRequestId}/escalate`, {
+            reason,
+        });
+    }
+    async listPolicies() {
+        return this.request("GET", "/v1/policies");
+    }
+    async listAuditEvents() {
+        return this.request("GET", "/v1/audit-events");
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@auctra/sdk",
+  "version": "0.1.0",
+  "description": "Authority delegation SDK for AI agents — evaluate agent actions against delegated authority and org policies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Matik103/auctra.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": ["auctra", "ai-agents", "authority", "delegation", "governance", "agents"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}