@tethral/acr-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tethral, Inc.
+
+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,64 @@
+# @tethral/acr-sdk
+
+Zero-dependency TypeScript SDK for the [ACR](https://acr.nfkey.ai) (Agent Composition Records) network.
+
+## Install
+
+```bash
+npm install @tethral/acr-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ACRClient } from '@tethral/acr-sdk';
+
+const acr = new ACRClient();
+
+// Register
+const { agent_id } = await acr.register({
+  public_key: 'your-unique-key-at-least-32-chars-long',
+  provider_class: 'anthropic',
+});
+
+// Log an interaction
+await acr.submitReceipt({
+  emitter: { agent_id, provider_class: 'anthropic' },
+  target: { system_id: 'mcp:github', system_type: 'mcp_server' },
+  interaction: {
+    category: 'tool_call', status: 'success',
+    duration_ms: 1200, request_timestamp_ms: Date.now() - 1200,
+  },
+  anomaly: { flagged: false },
+});
+
+// See what's costing you the most
+const report = await acr.getFrictionReport(agent_id, 'day');
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `register(request)` | Register an agent, get JWT credential |
+| `submitReceipt(receipt)` | Submit a single interaction receipt |
+| `submitReceipts(receipts)` | Submit a batch (max 50) |
+| `updateComposition(agentId, composition)` | Update skill composition |
+| `checkSkill(hash)` | Check a skill hash before installing |
+| `checkAgent(agentId)` | Look up an agent |
+| `getSystemHealth(systemId)` | Get system health status |
+| `getActiveThreats()` | Get current threat alerts |
+| `getFrictionReport(agentId, scope)` | Friction analysis report |
+| `getHealth()` | API health check |
+
+## Exported Types
+
+`RegistrationRequest`, `RegistrationResponse`, `InteractionReceipt`, `SkillCheckResponse`, `FrictionReport`, `ProviderClass`, `TargetSystemType`, `InteractionCategory`, `InteractionStatus`, `AnomalyCategory`, `ThreatLevel`, `FrictionSummary`, `TargetFriction`
+
+## Data Collection
+
+ACR collects interaction metadata only: target system names, timing, status, and provider class. No request/response content, API keys, prompts, or PII is collected. [Full terms](https://acr.nfkey.ai/terms).
+
+## License
+
+MIT

package/dist/src/index.d.ts

@@ -0,0 +1,58 @@
+import type { RegistrationRequest, RegistrationResponse, InteractionReceipt, SkillCheckResponse, FrictionReport } from './types.js';
+export type { RegistrationRequest, RegistrationResponse, InteractionReceipt, SkillCheckResponse, FrictionReport, ProviderClass, TargetSystemType, InteractionCategory, InteractionStatus, AnomalyCategory, ThreatLevel, FrictionSummary, TargetFriction, } from './types.js';
+export interface ACRClientConfig {
+    apiUrl?: string;
+    resolverUrl?: string;
+}
+export declare class ACRClient {
+    private apiUrl;
+    private resolverUrl;
+    constructor(config?: ACRClientConfig);
+    private post;
+    private get;
+    register(request: RegistrationRequest): Promise<RegistrationResponse>;
+    submitReceipt(receipt: Omit<InteractionReceipt, 'receipt_id'>): Promise<{
+        accepted: number;
+        receipt_ids: string[];
+    }>;
+    submitReceipts(receipts: Omit<InteractionReceipt, 'receipt_id'>[]): Promise<{
+        accepted: number;
+        receipt_ids: string[];
+    }>;
+    updateComposition(agentId: string, composition: {
+        skills?: string[];
+        skill_hashes?: string[];
+    }): Promise<{
+        composition_hash: string;
+        snapshot_id: string;
+    }>;
+    checkSkill(hash: string): Promise<SkillCheckResponse>;
+    checkAgent(agentId: string): Promise<{
+        found: boolean;
+        agent_id: string;
+        status?: string;
+        provider_class?: string;
+    }>;
+    getSystemHealth(systemId: string): Promise<{
+        found: boolean;
+        system_id: string;
+        health_status?: string;
+    }>;
+    getActiveThreats(): Promise<Array<{
+        threat_level: string;
+        skill_hash: string;
+        skill_name?: string;
+    }>>;
+    getFrictionReport(agentId: string, scope?: 'session' | 'day' | 'week'): Promise<FrictionReport>;
+    getHealth(): Promise<{
+        status: string;
+        database: string;
+        timestamp: string;
+    }>;
+}
+export declare class ACRError extends Error {
+    code: string;
+    statusCode: number;
+    constructor(code: string, message: string, statusCode: number);
+}
+export { ACRClient as default };

package/dist/src/index.js

@@ -0,0 +1,69 @@
+export class ACRClient {
+    apiUrl;
+    resolverUrl;
+    constructor(config = {}) {
+        this.apiUrl = config.apiUrl ?? process.env.ACR_API_URL ?? 'https://acr.nfkey.ai';
+        this.resolverUrl = config.resolverUrl ?? this.apiUrl;
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.apiUrl}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const data = await res.json();
+        if (!res.ok)
+            throw new ACRError(data.error?.code ?? 'UNKNOWN', data.error?.message ?? 'Request failed', res.status);
+        return data;
+    }
+    async get(path, useResolver = false) {
+        const base = useResolver ? this.resolverUrl : this.apiUrl;
+        const res = await fetch(`${base}${path}`);
+        const data = await res.json();
+        if (!res.ok)
+            throw new ACRError(data.error?.code ?? 'UNKNOWN', data.error?.message ?? 'Request failed', res.status);
+        return data;
+    }
+    async register(request) {
+        return this.post('/api/v1/register', request);
+    }
+    async submitReceipt(receipt) {
+        return this.post('/api/v1/receipts', receipt);
+    }
+    async submitReceipts(receipts) {
+        return this.post('/api/v1/receipts', { receipts });
+    }
+    async updateComposition(agentId, composition) {
+        return this.post('/api/v1/composition/update', { agent_id: agentId, composition });
+    }
+    async checkSkill(hash) {
+        return this.get(`/v1/skill/${hash}`, true);
+    }
+    async checkAgent(agentId) {
+        return this.get(`/v1/agent/${agentId}`, true);
+    }
+    async getSystemHealth(systemId) {
+        return this.get(`/v1/system/${encodeURIComponent(systemId)}/health`, true);
+    }
+    async getActiveThreats() {
+        return this.get('/v1/threats/active', true);
+    }
+    async getFrictionReport(agentId, scope = 'day') {
+        return this.get(`/api/v1/agent/${agentId}/friction?scope=${scope}`);
+    }
+    async getHealth() {
+        return this.get('/api/v1/health');
+    }
+}
+export class ACRError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode) {
+        super(message);
+        this.name = 'ACRError';
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+export { ACRClient as default };
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * ACR SDK Type Definitions
+ *
+ * Standalone interfaces mirroring the ACR API schema.
+ * No external dependencies — these are plain TypeScript types.
+ */
+export type ProviderClass = 'anthropic' | 'openai' | 'google' | 'openclaw' | 'langchain' | 'crewai' | 'autogen' | 'custom' | 'unknown';
+export type TargetSystemType = 'mcp_server' | 'api' | 'agent' | 'skill' | 'platform' | 'unknown';
+export type InteractionCategory = 'tool_call' | 'delegation' | 'data_exchange' | 'skill_install' | 'commerce' | 'research' | 'code' | 'communication';
+export type InteractionStatus = 'success' | 'failure' | 'timeout' | 'partial';
+export type AnomalyCategory = 'unexpected_behavior' | 'data_exfiltration' | 'prompt_injection' | 'malformed_output' | 'excessive_latency' | 'unauthorized_access' | 'other';
+export type ThreatLevel = 'none' | 'low' | 'medium' | 'high' | 'critical';
+export interface RegistrationRequest {
+    public_key: string;
+    provider_class: ProviderClass;
+    composition?: {
+        mcps?: string[];
+        tools?: string[];
+        skills?: string[];
+        skill_hashes?: string[];
+    };
+    operational_domain?: string;
+    system_prompt_hash?: string;
+}
+export interface RegistrationResponse {
+    agent_id: string;
+    credential: string;
+    composition_hash: string;
+    environment_briefing: {
+        connected_systems: Array<{
+            name: string;
+            type: string;
+            health_status: string;
+            anomaly_count: number;
+            agent_population: number;
+        }>;
+        active_threats: Array<{
+            threat_level: string;
+            component_hash: string;
+            description: string;
+            first_reported: string;
+        }>;
+    };
+}
+export interface InteractionReceipt {
+    receipt_id?: string;
+    emitter: {
+        agent_id: string;
+        composition_hash?: string;
+        provider_class: ProviderClass;
+    };
+    target: {
+        system_id: string;
+        system_type: TargetSystemType;
+    };
+    interaction: {
+        category: InteractionCategory;
+        duration_ms?: number;
+        status: InteractionStatus;
+        request_timestamp_ms: number;
+        response_timestamp_ms?: number;
+    };
+    anomaly: {
+        flagged: boolean;
+        category?: AnomalyCategory;
+        detail?: string;
+    };
+}
+export interface SkillCheckResponse {
+    found: boolean;
+    skill_hash: string;
+    skill_name?: string;
+    skill_source?: string;
+    agent_count?: number;
+    interaction_count?: number;
+    anomaly_rate?: number;
+    threat_level?: ThreatLevel;
+    first_seen?: string;
+    last_seen?: string;
+}
+export interface FrictionSummary {
+    total_interactions: number;
+    total_wait_time_ms: number;
+    friction_percentage: number;
+    total_failures: number;
+    failure_rate: number;
+}
+export interface TargetFriction {
+    target_system_id: string;
+    target_system_type: string;
+    interaction_count: number;
+    total_duration_ms: number;
+    proportion_of_total: number;
+    failure_count: number;
+    median_duration_ms: number;
+    vs_baseline?: number;
+    volatility?: number;
+    p95_duration_ms?: number;
+}
+export interface FrictionReport {
+    agent_id: string;
+    scope: 'session' | 'day' | 'week';
+    period_start: string;
+    period_end: string;
+    summary: FrictionSummary;
+    top_targets: TargetFriction[];
+    population_comparison?: {
+        total_agents_in_period: number;
+        baselines_available: number;
+    };
+    tier: string;
+}

package/dist/src/types.js

@@ -0,0 +1,8 @@
+/**
+ * ACR SDK Type Definitions
+ *
+ * Standalone interfaces mirroring the ACR API schema.
+ * No external dependencies — these are plain TypeScript types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tethral/acr-sdk",
+  "version": "0.1.0",
+  "description": "Zero-dependency TypeScript SDK for the ACR (Agent Composition Records) network.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": ["acr", "agent", "composition", "registry", "tethral", "sdk", "friction", "threat"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theAnthropol/AgentRegistry",
+    "directory": "packages/ts-sdk"
+  },
+  "homepage": "https://acr.nfkey.ai",
+  "engines": { "node": ">=18.0.0" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}