@auctra/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.3.0
+
+- Extend `evaluateAction` with trust infrastructure fields: `claimedIntentId`, `parentActionId`, `actor`, and `action` (target, description, riskLevel, metadata).
+- Return intelligence metadata on evaluation: authority validity, root intent validity, intent status, trust summary.
+- Add `listIntents`, `createIntent`, `getIntent`, `getAuthorityGraph`, `getActionEvaluation`, and `getRootIntentChain`.
+
+## 0.2.1
+
+- Add complete response types for agents, delegations, action requests, policies, audit events, and API keys.
+- Add `getDelegation`, `createPolicy`, and `listApiKeys`.
+- Honor `Retry-After`, preserve caller cancellation, and validate client options.
+- Correct the REST example to use the API's snake_case contract.
+- Add package-level integration tests and npm provenance metadata.
+- Ship tested ESM and CommonJS entry points.
+
+## 0.2.0
+
+- Add bounded retries, request deadlines, idempotent evaluation, and structured API errors.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Auctra
+
+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

@@ -16,6 +16,8 @@ Evaluate every agent action against delegated authority and org policies before
 npm install @auctra/sdk
 ```
 
+Both ESM (`import`) and CommonJS (`require`) entry points are included.
+
 ## Quick start
 
 ```typescript
@@ -46,6 +48,31 @@ if (decision.decision === "allowed") {
 }
 ```
 
+### Trust infrastructure (0.3.0+)
+
+Declare why an action is happening and trace it back to human-approved intent:
+
+```typescript
+const intent = await auctra.createIntent({
+  title: "Renew SaaS contracts under $500/month for Q3",
+  description: "Procurement agent may renew eligible vendor subscriptions.",
+});
+
+const decision = await auctra.evaluateAction({
+  agentId: "your-agent-uuid",
+  actionType: "send_payment",
+  claimedIntentId: intent.intent.id,
+  action: {
+    target: "vendor:slack",
+    description: "Renew Slack Team plan",
+    riskLevel: "medium",
+  },
+  payload: { amount: 420, currency: "USD" },
+});
+
+console.log(decision.intelligence?.trust_summary);
+```
+
 ## Get an API key
 
 1. [Sign up](https://console.auctra.tech/auth/signup) and create an organization
@@ -57,10 +84,18 @@ if (decision.decision === "allowed") {
 
 | Method                                      | Description                                       |
 | ------------------------------------------- | ------------------------------------------------- |
-| `evaluateAction(input, options)`            | Idempotently check authority before an agent acts |
-| `listAgents()`                              | List registered agents                            |
+| `evaluateAction(input, options)`            | Idempotently check authority + trust trace before an agent acts |
+| `listIntents()`                             | List human-approved intents                                     |
+| `createIntent(input)`                       | Declare a new intent                                            |
+| `getIntent(id)`                             | Get intent detail and linked actions                            |
+| `getAuthorityGraph()`                       | Fetch authority graph nodes and edges                           |
+| `getActionEvaluation(actionRequestId)`      | Get decision record for an action                               |
+| `getRootIntentChain(actionRequestId)`       | Get root human intent chain (trust trace)                         |
+| `listAgents()`                              | List registered agents                                          |
 | `createAgent(input)`                        | Register a new agent                              |
+| `getAgent(id)`                              | Get one registered agent                          |
 | `listDelegations()`                         | List authority delegations                        |
+| `getDelegation(id)`                         | Get one authority delegation                      |
 | `createDelegation(input)`                   | Grant bounded authority                           |
 | `revokeDelegation(id)`                      | Revoke a delegation                               |
 | `listActionRequests()`                      | List recent evaluations                           |
@@ -68,7 +103,9 @@ if (decision.decision === "allowed") {
 | `rejectActionRequest(id, approverUserId)`   | Reject as an accountable reviewer                 |
 | `escalateActionRequest(id, approverUserId)` | Escalate as an accountable reviewer               |
 | `listPolicies()`                            | List org policies                                 |
+| `createPolicy(input)`                       | Create an org policy                              |
 | `listAuditEvents()`                         | List audit ledger events                          |
+| `listApiKeys()`                             | List API key metadata                             |
 
 ## REST API (curl)
 
@@ -78,8 +115,8 @@ curl -X POST https://console.auctra.tech/v1/action-requests/evaluate \
   -H "Idempotency-Key: $(uuidgen)" \
   -H "Content-Type: application/json" \
   -d '{
-    "agentId": "your-agent-uuid",
-    "actionType": "send_payment",
+    "agent_id": "your-agent-uuid",
+    "action_type": "send_payment",
     "payload": { "amount": 100, "currency": "USD" }
   }'
 ```

package/dist/cjs/index.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Auctra = exports.AuctraApiError = exports.AUCTRA_SDK_VERSION = void 0;
+exports.AUCTRA_SDK_VERSION = "0.3.0";
+class AuctraApiError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(message, options) {
+        super(message);
+        this.name = "AuctraApiError";
+        this.status = options.status;
+        this.code = options.code;
+        this.details = options.details;
+        this.requestId = options.requestId;
+    }
+}
+exports.AuctraApiError = AuctraApiError;
+function retryDelay(response, attempt) {
+    const retryAfter = response?.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds))
+            return Math.min(30_000, Math.max(0, seconds * 1_000));
+        const dateDelay = Date.parse(retryAfter) - Date.now();
+        if (Number.isFinite(dateDelay))
+            return Math.min(30_000, Math.max(0, dateDelay));
+    }
+    return Math.min(5_000, 150 * 2 ** attempt);
+}
+function wait(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+class Auctra {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey.trim())
+            throw new Error("apiKey is required");
+        if (options.timeoutMs !== undefined && options.timeoutMs <= 0) {
+            throw new Error("timeoutMs must be greater than zero");
+        }
+        if (options.maxRetries !== undefined &&
+            (!Number.isInteger(options.maxRetries) || options.maxRetries < 0)) {
+            throw new Error("maxRetries must be a non-negative integer");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://console.auctra.tech").replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl)
+            throw new Error("A fetch implementation is required");
+    }
+    async request(method, path, body, options = {}) {
+        const retryableRequest = method === "GET" || Boolean(options.idempotencyKey);
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            if (options.signal?.aborted)
+                throw options.signal.reason;
+            const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+            const signal = options.signal
+                ? AbortSignal.any([options.signal, timeoutSignal])
+                : timeoutSignal;
+            let response;
+            try {
+                response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    method,
+                    signal,
+                    headers: {
+                        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                        ...(options.idempotencyKey ? { "idempotency-key": options.idempotencyKey } : {}),
+                        authorization: `Bearer ${this.apiKey}`,
+                        "x-auctra-sdk-version": exports.AUCTRA_SDK_VERSION,
+                    },
+                    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                });
+                const data = (await response.json().catch(() => ({})));
+                if (response.ok)
+                    return data;
+                if (retryableRequest &&
+                    (response.status === 429 || response.status >= 500) &&
+                    attempt < this.maxRetries) {
+                    await wait(retryDelay(response, attempt), options.signal);
+                    continue;
+                }
+                throw new AuctraApiError(typeof data.error === "string" ? data.error : `Auctra API error (${response.status})`, {
+                    status: response.status,
+                    code: typeof data.code === "string" ? data.code : undefined,
+                    details: data.details,
+                    requestId: response.headers.get("x-request-id") ?? undefined,
+                });
+            }
+            catch (error) {
+                lastError = error;
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                if (error instanceof AuctraApiError || !retryableRequest || attempt >= this.maxRetries) {
+                    throw error;
+                }
+                await wait(retryDelay(response, attempt), options.signal);
+            }
+        }
+        throw lastError;
+    }
+    async evaluateAction(input, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+        return this.request("POST", "/v1/action-requests/evaluate", {
+            agent_id: input.agentId,
+            action_type: input.actionType,
+            payload: input.payload ?? {},
+            claimed_intent_id: input.claimedIntentId,
+            parent_action_id: input.parentActionId,
+            actor: input.actor
+                ? {
+                    id: input.actor.id,
+                    type: input.actor.type,
+                    name: input.actor.name,
+                }
+                : undefined,
+            action: input.action
+                ? {
+                    target: input.action.target,
+                    description: input.action.description,
+                    risk_level: input.action.riskLevel,
+                    metadata: input.action.metadata,
+                }
+                : undefined,
+        }, { ...options, idempotencyKey });
+    }
+    async listIntents() {
+        return this.request("GET", "/v1/intents");
+    }
+    async createIntent(input) {
+        return this.request("POST", "/v1/intents", {
+            title: input.title,
+            description: input.description,
+            intent_type: input.intentType,
+            risk_level: input.riskLevel,
+            max_risk_level: input.maxRiskLevel,
+            expires_at: input.expiresAt,
+        });
+    }
+    async getIntent(intentId) {
+        return this.request("GET", `/v1/intents/${encodeURIComponent(intentId)}`);
+    }
+    async getAuthorityGraph() {
+        return this.request("GET", "/v1/authority/graph");
+    }
+    async getActionEvaluation(actionRequestId) {
+        return this.request("GET", `/v1/action-requests/${encodeURIComponent(actionRequestId)}/evaluation`);
+    }
+    async getRootIntentChain(actionRequestId) {
+        return this.request("GET", `/v1/action-requests/${encodeURIComponent(actionRequestId)}/root-intent`);
+    }
+    async listAgents() {
+        return this.request("GET", "/v1/agents");
+    }
+    async getAgent(agentId) {
+        return this.request("GET", `/v1/agents/${encodeURIComponent(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 getDelegation(delegationId) {
+        return this.request("GET", `/v1/delegations/${encodeURIComponent(delegationId)}`);
+    }
+    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,
+            max_count: input.maxCount,
+            environment: input.environment,
+            currency: input.currency,
+            delegator_user_id: input.delegatorUserId,
+        });
+    }
+    async revokeDelegation(delegationId) {
+        return this.request("POST", `/v1/delegations/${encodeURIComponent(delegationId)}/revoke`, {});
+    }
+    async listActionRequests() {
+        return this.request("GET", "/v1/action-requests");
+    }
+    async approveActionRequest(actionRequestId, approverUserId, reason) {
+        return this.resolveActionRequest(actionRequestId, "approve", approverUserId, reason);
+    }
+    async rejectActionRequest(actionRequestId, approverUserId, reason) {
+        return this.resolveActionRequest(actionRequestId, "reject", approverUserId, reason);
+    }
+    async escalateActionRequest(actionRequestId, approverUserId, reason) {
+        return this.resolveActionRequest(actionRequestId, "escalate", approverUserId, reason);
+    }
+    async resolveActionRequest(actionRequestId, action, approverUserId, reason) {
+        return this.request("POST", `/v1/action-requests/${encodeURIComponent(actionRequestId)}/${action}`, { reason, approver_user_id: approverUserId });
+    }
+    async listPolicies() {
+        return this.request("GET", "/v1/policies");
+    }
+    async createPolicy(input) {
+        return this.request("POST", "/v1/policies", {
+            name: input.name,
+            description: input.description,
+            policy_type: input.policyType,
+            status: input.status,
+            priority: input.priority,
+            action_type: input.actionType,
+            amount_greater_than: input.amountGreaterThan,
+            resource_sensitivity: input.resourceSensitivity,
+            external_recipient: input.externalRecipient,
+            environment: input.environment,
+            decision: input.decision,
+            approver_role: input.approverRole,
+        });
+    }
+    async listAuditEvents() {
+        return this.request("GET", "/v1/audit-events");
+    }
+    async listApiKeys() {
+        return this.request("GET", "/v1/api-keys");
+    }
+}
+exports.Auctra = Auctra;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}