@agledger/sdk 1.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2026 AGLedger LLC. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are the
+proprietary property of AGLedger LLC. The Software is provided for use
+exclusively with the AGLedger API (https://api.agledger.ai).
+
+Permission is hereby granted to use the Software solely for the purpose of
+integrating with AGLedger services via the AGLedger API, subject to the
+following conditions:
+
+1. You may not copy, modify, merge, publish, distribute, sublicense, or sell
+   copies of the Software, except as required to use it with the AGLedger API.
+
+2. You may not use the Software to create a competing product or service.
+
+3. You may not reverse engineer, decompile, or disassemble the Software,
+   except to the extent permitted by applicable law.
+
+Use of this SDK is subject to the AGLedger Terms of Service at
+https://agledger.ai/terms.
+
+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
+AGLEDGER LLC 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.
+
+---
+
+AGLedger™ and the Agentic Contract Specification™ are trademarks of
+AGLedger LLC. Patent pending.

package/README.md

@@ -0,0 +1,209 @@
+# @agledger/sdk
+
+The official TypeScript SDK for the [AGLedger](https://agledger.ai) API -- accountability and audit infrastructure for agentic systems.
+
+Zero runtime dependencies. TypeScript strict. 113 tests. Works with Node.js 18+, Deno, and Bun.
+
+## Why AGLedger?
+
+Enterprises deploying AI agents need to know what each agent was asked to do, what it actually did, and whether the result met expectations. AGLedger provides the accountability record -- what was agreed to, by whom, when, and the delegation of that agreement through other systems.
+
+- Record what was asked and who it was delegated to (mandates)
+- Capture what was reported to be done (task attestations)
+- Check whether the creator accepted the results (verification)
+- Track agent reliability across your organization over time (reputation)
+
+## The Accountability Record
+
+The core of AGLedger is the contract. A mandate is a structured, deterministic record of what was agreed to -- the acceptance criteria, tolerance bands, and delegation chain. It works the same way regardless of which AI agent, platform, or framework is executing the work.
+
+On top of the contract, AGLedger provides:
+
+- **Tamper-evident audit trail** -- every state change is hash-chained and independently verifiable
+- **Encrypted operating mode** -- for sensitive operations where criteria and evidence must be encrypted at rest
+- **Governance sidecar** -- passive detection of agent operations via MCP proxy, with observe/advisory/enforced modes
+- **Compliance exports** -- audit-ready reports for internal review, regulators, and EU AI Act assessments
+
+## Get Started
+
+1. Create an account at [agledger.ai](https://agledger.ai)
+2. Get your API key from the dashboard
+3. Install the SDK: `npm install @agledger/sdk`
+4. Follow the Quick Start below
+
+## Quick Start
+
+```typescript
+import { AgledgerClient } from '@agledger/sdk';
+
+const client = new AgledgerClient({
+  apiKey: process.env.AGLEDGER_API_KEY!,
+});
+
+// Create a mandate (what the agent is being asked to do)
+const mandate = await client.mandates.create({
+  enterpriseId: 'ent-123',
+  contractType: 'ACH-DATA-v1',
+  contractVersion: '1',
+  platform: 'internal-etl',
+  criteria: {
+    source_system: 'warehouse-db',
+    target_format: 'parquet',
+    max_records: 500_000,
+  },
+});
+
+// Activate the mandate
+await client.mandates.transition(mandate.id, 'activate');
+
+// Submit a receipt (what the agent reported back)
+const receipt = await client.receipts.submit(mandate.id, {
+  agentId: 'agent-456',
+  evidence: {
+    records_processed: 487_231,
+    output_path: '/data/exports/2026-03-10.parquet',
+    duration_ms: 12_400,
+  },
+});
+
+// Check whether the results meet the original criteria
+const result = await client.verification.verify(mandate.id);
+```
+
+## Features
+
+- **Stripe-style client** with resource sub-clients (`client.mandates`, `client.receipts`, etc.)
+- **Automatic retries** with exponential backoff + jitter for 429/5xx errors
+- **Idempotency keys** auto-generated for all mutating requests
+- **Auto-pagination** via async iterators
+- **Webhook signature verification** (separate import to keep browser bundles lean)
+- **TypeScript-first** with full type coverage and forward-compatible enums
+- **Sandbox support** via `environment: 'sandbox'` option
+
+## Configuration
+
+```typescript
+const client = new AgledgerClient({
+  apiKey: 'your_api_key',
+
+  // Environment shorthand (sets baseUrl automatically)
+  environment: 'sandbox', // or 'production' (default)
+
+  // Or explicit base URL
+  baseUrl: 'https://api.agledger.ai',
+
+  // Retry configuration
+  maxRetries: 3,        // default: 3
+  timeout: 30_000,      // default: 30s
+
+  // Idempotency key prefix
+  idempotencyKeyPrefix: 'my-app-',
+});
+```
+
+## Resources
+
+| Resource | Description |
+|----------|-------------|
+| `client.mandates` | Create, search, transition, and delegate mandates |
+| `client.receipts` | Submit and manage task attestation reports |
+| `client.verification` | Trigger and check verification status |
+| `client.disputes` | File, escalate, and resolve disputes |
+| `client.webhooks` | Manage webhook endpoints and deliveries |
+| `client.reputation` | Query agent health scores and history |
+| `client.events` | List audit events and hash-chained audit trails |
+| `client.schemas` | Browse and validate against contract type schemas |
+| `client.dashboard` | Dashboard summaries, metrics, and agent leaderboards |
+| `client.compliance` | Compliance exports, EU AI Act assessments |
+| `client.registration` | Account registration and API key management |
+| `client.health` | Platform health, status, and conformance |
+| `client.admin` | Platform administration (requires platform API key) |
+| `client.a2a` | A2A Protocol support (AgentCard, JSON-RPC 2.0) |
+| `client.capabilities` | Agent contract type capability management |
+| `client.proxy` | Governance sidecar session sync and analytics |
+
+## Contract Types
+
+Contract types are defined by the Agentic Contract Specification™:
+
+| Type | Use Case |
+|------|----------|
+| `ACH-PROC-v1` | Resource acquisition and provisioning requests |
+| `ACH-DLVR-v1` | Reports, documents, and generated artifacts |
+| `ACH-DATA-v1` | Data processing, ETL, analysis, and transformation |
+| `ACH-TXN-v1` | Internal transfers, ledger entries, and settlements |
+| `ACH-ORCH-v1` | Task delegation and multi-agent coordination |
+| `ACH-COMM-v1` | Notifications, messages, and alerting |
+| `ACH-AUTH-v1` | Permission changes, credential grants, and access control |
+| `ACH-INFRA-v1` | Infrastructure changes, cloud provisioning, and config updates |
+| `ACH-DEL-v1` | Deletions, cancellations, and reversals |
+
+## Pagination
+
+All list methods return `Page<T>`:
+
+```typescript
+// Single page
+const page = await client.mandates.list({ enterpriseId: 'ent-123' });
+console.log(page.data);    // Mandate[]
+console.log(page.hasMore); // boolean
+console.log(page.total);   // number | undefined
+
+// Auto-pagination with async iterator
+for await (const mandate of client.mandates.listAll({ enterpriseId: 'ent-123' })) {
+  console.log(mandate.id);
+}
+```
+
+## Error Handling
+
+```typescript
+import { AgledgerApiError, NotFoundError, RateLimitError } from '@agledger/sdk';
+
+try {
+  await client.mandates.get('mnd-nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Mandate not found');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${err.retryAfter}ms`);
+  } else if (err instanceof AgledgerApiError) {
+    console.log(err.status);           // HTTP status
+    console.log(err.code);             // Machine-readable code
+    console.log(err.retryable);        // Can this be retried?
+    console.log(err.validationErrors); // Field-level details
+  }
+}
+```
+
+Error classes: `AuthenticationError`, `PermissionError`, `NotFoundError`, `ValidationError`, `UnprocessableError`, `RateLimitError`, `ConnectionError`, `TimeoutError`.
+
+## Webhook Verification
+
+```typescript
+import { verifySignature } from '@agledger/sdk/webhooks';
+
+const isValid = verifySignature(
+  rawBody,                    // Raw request body string
+  req.headers['x-agledger-signature'], // Signature header
+  process.env.WEBHOOK_SECRET!, // Your webhook secret
+);
+```
+
+## Mandate Lifecycle
+
+```
+DRAFT → REGISTERED → ACTIVE → PENDING_VERIFICATION → FULFILLED / FAILED / DISPUTED
+                                                                    ↓
+                                                              REMEDIATED
+```
+
+## API Documentation
+
+Full API documentation is available at [https://api.agledger.ai/docs](https://api.agledger.ai/docs).
+
+## License
+
+Proprietary. Copyright (c) 2026 AGLedger LLC. All rights reserved. See [LICENSE](./LICENSE) for details.
+
+AGLedger™ and the Agentic Contract Specification™ are trademarks of AGLedger LLC. Patent pending.

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AGLedger™ SDK — Client
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ */
+import type { AgledgerClientOptions, RateLimitInfo } from './types.js';
+import { MandatesResource } from './resources/mandates.js';
+import { ReceiptsResource } from './resources/receipts.js';
+import { VerificationResource } from './resources/verification.js';
+import { DisputesResource } from './resources/disputes.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { ReputationResource } from './resources/reputation.js';
+import { EventsResource } from './resources/events.js';
+import { SchemasResource } from './resources/schemas.js';
+import { DashboardResource } from './resources/dashboard.js';
+import { ComplianceResource } from './resources/compliance.js';
+import { RegistrationResource } from './resources/registration.js';
+import { HealthResource } from './resources/health.js';
+import { ProxyResource } from './resources/proxy.js';
+import { AdminResource } from './resources/admin.js';
+import { A2aResource } from './resources/a2a.js';
+import { CapabilitiesResource } from './resources/capabilities.js';
+import { NotarizeResource } from './resources/notarize.js';
+export declare class AgledgerClient {
+    private readonly http;
+    readonly mandates: MandatesResource;
+    readonly receipts: ReceiptsResource;
+    readonly verification: VerificationResource;
+    readonly disputes: DisputesResource;
+    readonly webhooks: WebhooksResource;
+    readonly reputation: ReputationResource;
+    readonly events: EventsResource;
+    readonly schemas: SchemasResource;
+    readonly dashboard: DashboardResource;
+    readonly compliance: ComplianceResource;
+    readonly registration: RegistrationResource;
+    readonly health: HealthResource;
+    readonly proxy: ProxyResource;
+    readonly admin: AdminResource;
+    readonly a2a: A2aResource;
+    readonly capabilities: CapabilitiesResource;
+    readonly notarize: NotarizeResource;
+    /** Rate limit info from the most recent API response. Null if headers not present. */
+    get rateLimitInfo(): RateLimitInfo | null;
+    constructor(options: AgledgerClientOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,68 @@
+/**
+ * AGLedger™ SDK — Client
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ */
+import { HttpClient } from './http.js';
+import { MandatesResource } from './resources/mandates.js';
+import { ReceiptsResource } from './resources/receipts.js';
+import { VerificationResource } from './resources/verification.js';
+import { DisputesResource } from './resources/disputes.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { ReputationResource } from './resources/reputation.js';
+import { EventsResource } from './resources/events.js';
+import { SchemasResource } from './resources/schemas.js';
+import { DashboardResource } from './resources/dashboard.js';
+import { ComplianceResource } from './resources/compliance.js';
+import { RegistrationResource } from './resources/registration.js';
+import { HealthResource } from './resources/health.js';
+import { ProxyResource } from './resources/proxy.js';
+import { AdminResource } from './resources/admin.js';
+import { A2aResource } from './resources/a2a.js';
+import { CapabilitiesResource } from './resources/capabilities.js';
+import { NotarizeResource } from './resources/notarize.js';
+export class AgledgerClient {
+    http;
+    mandates;
+    receipts;
+    verification;
+    disputes;
+    webhooks;
+    reputation;
+    events;
+    schemas;
+    dashboard;
+    compliance;
+    registration;
+    health;
+    proxy;
+    admin;
+    a2a;
+    capabilities;
+    notarize;
+    /** Rate limit info from the most recent API response. Null if headers not present. */
+    get rateLimitInfo() {
+        return this.http.rateLimitInfo;
+    }
+    constructor(options) {
+        const http = new HttpClient(options);
+        this.http = http;
+        this.mandates = new MandatesResource(http);
+        this.receipts = new ReceiptsResource(http);
+        this.verification = new VerificationResource(http);
+        this.disputes = new DisputesResource(http);
+        this.webhooks = new WebhooksResource(http);
+        this.reputation = new ReputationResource(http);
+        this.events = new EventsResource(http);
+        this.schemas = new SchemasResource(http);
+        this.dashboard = new DashboardResource(http);
+        this.compliance = new ComplianceResource(http);
+        this.registration = new RegistrationResource(http);
+        this.health = new HealthResource(http);
+        this.proxy = new ProxyResource(http);
+        this.admin = new AdminResource(http);
+        this.a2a = new A2aResource(http);
+        this.capabilities = new CapabilitiesResource(http);
+        this.notarize = new NotarizeResource(http);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AGLedger™ SDK — Error Classes
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ */
+import type { ApiErrorResponse, ValidationErrorDetail } from './types.js';
+/**
+ * Base error for all SDK errors (network, timeout, etc.).
+ * Not an API error — no status code.
+ */
+export declare class AgledgerError extends Error {
+    constructor(message: string);
+}
+/**
+ * API returned an error response. All HTTP errors extend this.
+ *
+ * Key properties for agent consumers:
+ * - `status` — HTTP status code
+ * - `code` — stable machine-readable error code (e.g., 'MANDATE_NOT_ACTIVE')
+ * - `retryable` — whether this error can be retried
+ * - `requestId` — correlation ID for debugging
+ * - `validationErrors` — field-level validation details (for 400/422)
+ */
+export declare class AgledgerApiError extends AgledgerError {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly details?: ValidationErrorDetail[] | Record<string, unknown>;
+    /**
+     * Whether this error is retryable.
+     * - Uses the API's `retryable` field if present
+     * - Falls back to status-based classification: 429 and 5xx are retryable
+     */
+    readonly retryable: boolean;
+    constructor(status: number, body: ApiErrorResponse);
+    /** Field-level validation errors, normalized from various API formats. */
+    get validationErrors(): ValidationErrorDetail[];
+}
+export declare class AuthenticationError extends AgledgerApiError {
+    constructor(body: ApiErrorResponse);
+}
+export declare class PermissionError extends AgledgerApiError {
+    constructor(body: ApiErrorResponse);
+}
+export declare class NotFoundError extends AgledgerApiError {
+    constructor(body: ApiErrorResponse);
+}
+export declare class ValidationError extends AgledgerApiError {
+    constructor(body: ApiErrorResponse);
+}
+export declare class UnprocessableError extends AgledgerApiError {
+    constructor(body: ApiErrorResponse);
+}
+export declare class RateLimitError extends AgledgerApiError {
+    readonly retryAfter: number | null;
+    constructor(body: ApiErrorResponse, retryAfter: number | null);
+}
+export declare class ConnectionError extends AgledgerError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+export declare class TimeoutError extends ConnectionError {
+    constructor(method: string, url: string, timeoutMs: number, cause?: Error);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,114 @@
+/**
+ * AGLedger™ SDK — Error Classes
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ */
+/**
+ * Base error for all SDK errors (network, timeout, etc.).
+ * Not an API error — no status code.
+ */
+export class AgledgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgledgerError';
+    }
+}
+/**
+ * API returned an error response. All HTTP errors extend this.
+ *
+ * Key properties for agent consumers:
+ * - `status` — HTTP status code
+ * - `code` — stable machine-readable error code (e.g., 'MANDATE_NOT_ACTIVE')
+ * - `retryable` — whether this error can be retried
+ * - `requestId` — correlation ID for debugging
+ * - `validationErrors` — field-level validation details (for 400/422)
+ */
+export class AgledgerApiError extends AgledgerError {
+    status;
+    code;
+    requestId;
+    details;
+    /**
+     * Whether this error is retryable.
+     * - Uses the API's `retryable` field if present
+     * - Falls back to status-based classification: 429 and 5xx are retryable
+     */
+    retryable;
+    constructor(status, body) {
+        super(body.message || `API error ${status}`);
+        this.name = 'AgledgerApiError';
+        this.status = status;
+        this.code = body.code || body.error || 'unknown';
+        this.requestId = body.requestId;
+        this.details = body.details;
+        this.retryable = body.retryable ?? (status === 429 || status >= 500);
+    }
+    /** Field-level validation errors, normalized from various API formats. */
+    get validationErrors() {
+        if (!this.details)
+            return [];
+        if (Array.isArray(this.details))
+            return this.details;
+        // Handle Ajv-style errors nested under .errors
+        const rec = this.details;
+        if (Array.isArray(rec.errors)) {
+            return rec.errors.map((e) => ({
+                field: e.instancePath || e.dataPath || '',
+                message: e.message || '',
+            }));
+        }
+        return [];
+    }
+}
+export class AuthenticationError extends AgledgerApiError {
+    constructor(body) {
+        super(401, body);
+        this.name = 'AuthenticationError';
+    }
+}
+export class PermissionError extends AgledgerApiError {
+    constructor(body) {
+        super(403, body);
+        this.name = 'PermissionError';
+    }
+}
+export class NotFoundError extends AgledgerApiError {
+    constructor(body) {
+        super(404, body);
+        this.name = 'NotFoundError';
+    }
+}
+export class ValidationError extends AgledgerApiError {
+    constructor(body) {
+        super(400, body);
+        this.name = 'ValidationError';
+    }
+}
+export class UnprocessableError extends AgledgerApiError {
+    constructor(body) {
+        super(422, body);
+        this.name = 'UnprocessableError';
+    }
+}
+export class RateLimitError extends AgledgerApiError {
+    retryAfter;
+    constructor(body, retryAfter) {
+        super(429, body);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+export class ConnectionError extends AgledgerError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'ConnectionError';
+        this.cause = cause;
+    }
+}
+export class TimeoutError extends ConnectionError {
+    constructor(method, url, timeoutMs, cause) {
+        super(`Request timed out after ${timeoutMs}ms: ${method} ${url}`, cause);
+        this.name = 'TimeoutError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/http.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AGLedger™ SDK — HTTP Client
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ *
+ * Zero runtime dependencies. Uses native fetch + crypto.
+ */
+import type { AgledgerClientOptions, RequestOptions, RateLimitInfo, Page, AutoPaginateOptions } from './types.js';
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly fetchFn;
+    private readonly idempotencyKeyPrefix;
+    private _rateLimitInfo;
+    /** Rate limit info from the most recent response. Null if headers not present. */
+    get rateLimitInfo(): RateLimitInfo | null;
+    constructor(options: AgledgerClientOptions);
+    get<T>(path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Fetch a list endpoint and normalize the response into Page<T>.
+     * Handles both current inconsistent responses (bare arrays, various envelope shapes)
+     * and the target format ({ data, hasMore, nextCursor, total }).
+     */
+    getPage<T>(path: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<Page<T>>;
+    /**
+     * Async iterator for auto-paginating through all pages.
+     * Yields individual items. Stops after maxPages (default: 100) as a safety ceiling.
+     */
+    paginate<T>(path: string, params?: Record<string, unknown>, options?: RequestOptions & AutoPaginateOptions): AsyncGenerator<T, void, undefined>;
+    private buildUrl;
+    private request;
+    private mapError;
+    private backoff;
+    private parseRateLimitHeaders;
+    /**
+     * Normalize any list response shape into Page<T>.
+     * Handles: bare array, { data }, { data, hasMore, nextCursor, total },
+     * { data, total, limit, offset }, { data, next_cursor }.
+     */
+    private normalizePage;
+    private sleep;
+}
+//# sourceMappingURL=http.d.ts.map