notaryos 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# NotaryOS SDK for TypeScript
+
+Cryptographic receipts for AI agent actions. Issue, verify, and audit agent behavior with Ed25519 signatures.
+
+**Zero dependencies.** Uses native `fetch()` and Web Crypto API. Works in Node 18+, Deno, Bun, and modern browsers.
+
+## Install
+
+```bash
+npm install notaryos
+```
+
+## Quick Start
+
+### Issue a Receipt (3 lines)
+
+```typescript
+import { NotaryClient } from 'notaryos';
+
+const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+const receipt = await notary.issue('data_processing', { key: 'value' });
+console.log(receipt.verify_url); // https://api.agenttownsquare.com/v1/notary/r/abc123
+```
+
+### Verify a Receipt (no API key needed)
+
+```typescript
+import { verifyReceipt } from 'notaryos';
+
+const isValid = await verifyReceipt(receiptJson);
+// true
+```
+
+### Full Example
+
+```typescript
+import { NotaryClient } from 'notaryos';
+
+const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+
+// Issue a receipt for an agent action
+const receipt = await notary.issue('financial.transfer', {
+  from: 'billing-agent',
+  to: 'ledger-agent',
+  amount: 150.00,
+  currency: 'USD',
+});
+
+// Verify it
+const result = await notary.verify(receipt);
+console.log(result.valid);        // true
+console.log(result.signature_ok); // true
+
+// Check service health
+const status = await notary.status();
+console.log(status.status); // "active"
+
+// Get public key for offline verification
+const keyInfo = await notary.publicKey();
+console.log(keyInfo.public_key_pem);
+```
+
+## API Reference
+
+### `NotaryClient`
+
+| Method | Auth | Description |
+|--------|------|-------------|
+| `issue(actionType, payload, options?)` | API Key | Issue a signed receipt |
+| `verify(receipt)` | API Key | Verify a receipt |
+| `verifyById(receiptId)` | API Key | Verify by receipt ID |
+| `status()` | API Key | Service health check |
+| `publicKey()` | API Key | Get Ed25519 public key |
+| `me()` | API Key | Authenticated agent info |
+
+### `verifyReceipt(receipt, baseUrl?)`
+
+Public verification without API key. Returns `boolean`.
+
+### `computeHash(payload)`
+
+SHA-256 hash matching server-side computation. Returns hex string.
+
+## Configuration
+
+```typescript
+const notary = new NotaryClient({
+  apiKey: 'notary_live_xxx',     // Required
+  baseUrl: 'https://...',        // Default: https://api.agenttownsquare.com
+  timeout: 30_000,               // Default: 30s
+  maxRetries: 2,                 // Default: 2
+});
+```
+
+## Error Handling
+
+```typescript
+import { NotaryClient, AuthenticationError, RateLimitError, ValidationError } from 'notaryos';
+
+try {
+  const receipt = await notary.issue('action', payload);
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // Invalid API key
+  } else if (err instanceof RateLimitError) {
+    // Wait err.retryAfter seconds
+  } else if (err instanceof ValidationError) {
+    // Check err.details
+  }
+}
+```
+
+## Get an API Key
+
+1. Sign up at [notaryos.org](https://notaryos.org)
+2. Generate an API key from the dashboard
+3. Keys start with `notary_live_` (production) or `notary_test_` (sandbox)
+
+## Links
+
+- [NotaryOS Documentation](https://notaryos.org/docs)
+- [API Reference](https://api.agenttownsquare.com/v1/notary/status)
+- [Public Verification](https://notaryos.org/verify)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,237 @@
+/**
+ * NotaryOS SDK - Cryptographic receipts for AI agent actions.
+ *
+ * Issue, verify, and audit agent behavior with Ed25519 signatures.
+ * Zero dependencies. Uses native fetch() and Web Crypto API.
+ *
+ * Quick start:
+ *
+ *   import { NotaryClient } from 'notaryos';
+ *   const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ *   const receipt = await notary.issue('my_action', { key: 'value' });
+ *
+ * Verify without API key:
+ *
+ *   import { verifyReceipt } from 'notaryos';
+ *   const isValid = await verifyReceipt(receiptJson);
+ *
+ * @packageDocumentation
+ */
+declare const SDK_VERSION = "1.0.0";
+/** Client configuration options. */
+interface NotaryConfig {
+    /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
+    apiKey: string;
+    /** API base URL (default: https://api.agenttownsquare.com). */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+    /** Max retry attempts on transient failures (default: 2). */
+    maxRetries?: number;
+}
+/** A signed Notary receipt. */
+interface Receipt {
+    receipt_id: string;
+    timestamp: string;
+    agent_id: string;
+    action_type: string;
+    payload_hash: string;
+    signature: string;
+    signature_type: string;
+    key_id: string;
+    kid?: string;
+    alg?: string;
+    schema_version?: string;
+    chain_sequence?: number;
+    previous_receipt_hash?: string | null;
+    receipt_hash?: string;
+    verify_url?: string;
+}
+/** Result of receipt verification. */
+interface VerificationResult {
+    valid: boolean;
+    signature_ok: boolean;
+    structure_ok: boolean;
+    chain_ok?: boolean | null;
+    reason: string;
+    details: Record<string, unknown>;
+    from_cache?: boolean;
+}
+/** Notary service status. */
+interface ServiceStatus {
+    status: string;
+    signature_type: string;
+    key_id: string;
+    has_public_key: boolean;
+    capabilities: string[];
+    timestamp: string;
+}
+/** Public key for offline verification. */
+interface PublicKeyInfo {
+    key_id: string;
+    signature_type: string;
+    public_key_pem: string;
+    verification_note: string;
+}
+/** Result of a receipt lookup by hash. */
+interface LookupResult {
+    found: boolean;
+    receipt: Receipt | null;
+    verification: VerificationResult | null;
+    meta: Record<string, unknown> | null;
+}
+/** Authenticated agent information. */
+interface AgentInfo {
+    agent_id: string;
+    agent_name: string;
+    tier: string;
+    scopes: string[];
+    rate_limit_per_minute: number;
+}
+/** Options for issuing receipts. */
+interface IssueOptions {
+    /** Hash of previous receipt for chaining. */
+    previousReceiptHash?: string;
+    /** Additional metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Base error for all NotaryOS SDK errors. */
+declare class NotaryError extends Error {
+    code: string;
+    status: number;
+    details: Record<string, unknown>;
+    constructor(message: string, code?: string, status?: number, details?: Record<string, unknown>);
+}
+/** Invalid or missing API key. */
+declare class AuthenticationError extends NotaryError {
+    constructor(message: string, code?: string);
+}
+/** Rate limit exceeded. */
+declare class RateLimitError extends NotaryError {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+/** Request validation failed. */
+declare class ValidationError extends NotaryError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * NotaryOS API client.
+ *
+ * @example
+ * ```typescript
+ * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ *
+ * // Issue a receipt
+ * const receipt = await notary.issue('data_processing', { key: 'value' });
+ *
+ * // Verify a receipt
+ * const result = await notary.verify(receipt);
+ * console.log(result.valid); // true
+ *
+ * // Check service health
+ * const status = await notary.status();
+ * ```
+ */
+declare class NotaryClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    static readonly DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
+    static readonly DEFAULT_TIMEOUT = 30000;
+    constructor(config: NotaryConfig);
+    private request;
+    private sleep;
+    /**
+     * Issue a signed receipt for an action.
+     *
+     * @param actionType - Type of action (e.g., "data_processing", "api_call")
+     * @param payload - Action payload to be receipted
+     * @param options - Optional chaining and metadata
+     * @returns A signed Receipt
+     *
+     * @example
+     * ```typescript
+     * const receipt = await notary.issue('transfer', { amount: 100, to: 'agent-b' });
+     * console.log(receipt.receipt_id);
+     * console.log(receipt.verify_url); // https://...notary/r/abc123
+     * ```
+     */
+    issue(actionType: string, payload: Record<string, unknown>, options?: IssueOptions): Promise<Receipt>;
+    /**
+     * Verify a receipt's signature and integrity.
+     *
+     * @param receipt - Receipt object or raw receipt dict
+     * @returns VerificationResult with validity details
+     *
+     * @example
+     * ```typescript
+     * const result = await notary.verify(receipt);
+     * if (result.valid) {
+     *   console.log('Receipt is authentic');
+     * }
+     * ```
+     */
+    verify(receipt: Receipt | Record<string, unknown>): Promise<VerificationResult>;
+    /** Verify a receipt by its ID (server-side lookup). */
+    verifyById(receiptId: string): Promise<VerificationResult>;
+    /**
+     * Get Notary service status.
+     *
+     * @example
+     * ```typescript
+     * const status = await notary.status();
+     * console.log(status.status); // "active"
+     * ```
+     */
+    status(): Promise<ServiceStatus>;
+    /** Get the public key for offline verification. */
+    publicKey(): Promise<PublicKeyInfo>;
+    /** Get authenticated agent info. */
+    me(): Promise<AgentInfo>;
+    /**
+     * Look up a receipt by hash (public endpoint, no API key required for lookup).
+     *
+     * @param receiptHash - Full or partial receipt hash (min 16 chars)
+     * @returns Lookup result with receipt, verification, and meta
+     *
+     * @example
+     * ```typescript
+     * const result = await notary.lookup('abc123def456...');
+     * if (result.found && result.verification?.valid) {
+     *   console.log('Receipt is valid!');
+     * }
+     * ```
+     */
+    lookup(receiptHash: string): Promise<LookupResult>;
+}
+/**
+ * Quick receipt verification without API key.
+ *
+ * Uses the public /verify endpoint — no authentication needed.
+ *
+ * @param receipt - Receipt JSON object
+ * @param baseUrl - API base URL (default: production)
+ * @returns true if the receipt is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyReceipt } from 'notaryos';
+ *
+ * const isValid = await verifyReceipt(receiptJson);
+ * console.log(isValid); // true
+ * ```
+ */
+declare function verifyReceipt(receipt: Record<string, unknown>, baseUrl?: string): Promise<boolean>;
+/**
+ * Compute SHA-256 hash of a payload using Web Crypto API.
+ *
+ * Matches the server-side hashing for independent verification.
+ *
+ * @param payload - String or JSON-serializable object
+ * @returns Hex-encoded SHA-256 digest
+ */
+declare function computeHash(payload: Record<string, unknown> | string): Promise<string>;
+
+export { type AgentInfo, AuthenticationError, type IssueOptions, type LookupResult, NotaryClient, type NotaryConfig, NotaryError, type PublicKeyInfo, RateLimitError, type Receipt, SDK_VERSION, type ServiceStatus, ValidationError, type VerificationResult, computeHash, verifyReceipt };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+/**
+ * NotaryOS SDK - Cryptographic receipts for AI agent actions.
+ *
+ * Issue, verify, and audit agent behavior with Ed25519 signatures.
+ * Zero dependencies. Uses native fetch() and Web Crypto API.
+ *
+ * Quick start:
+ *
+ *   import { NotaryClient } from 'notaryos';
+ *   const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ *   const receipt = await notary.issue('my_action', { key: 'value' });
+ *
+ * Verify without API key:
+ *
+ *   import { verifyReceipt } from 'notaryos';
+ *   const isValid = await verifyReceipt(receiptJson);
+ *
+ * @packageDocumentation
+ */
+declare const SDK_VERSION = "1.0.0";
+/** Client configuration options. */
+interface NotaryConfig {
+    /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
+    apiKey: string;
+    /** API base URL (default: https://api.agenttownsquare.com). */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+    /** Max retry attempts on transient failures (default: 2). */
+    maxRetries?: number;
+}
+/** A signed Notary receipt. */
+interface Receipt {
+    receipt_id: string;
+    timestamp: string;
+    agent_id: string;
+    action_type: string;
+    payload_hash: string;
+    signature: string;
+    signature_type: string;
+    key_id: string;
+    kid?: string;
+    alg?: string;
+    schema_version?: string;
+    chain_sequence?: number;
+    previous_receipt_hash?: string | null;
+    receipt_hash?: string;
+    verify_url?: string;
+}
+/** Result of receipt verification. */
+interface VerificationResult {
+    valid: boolean;
+    signature_ok: boolean;
+    structure_ok: boolean;
+    chain_ok?: boolean | null;
+    reason: string;
+    details: Record<string, unknown>;
+    from_cache?: boolean;
+}
+/** Notary service status. */
+interface ServiceStatus {
+    status: string;
+    signature_type: string;
+    key_id: string;
+    has_public_key: boolean;
+    capabilities: string[];
+    timestamp: string;
+}
+/** Public key for offline verification. */
+interface PublicKeyInfo {
+    key_id: string;
+    signature_type: string;
+    public_key_pem: string;
+    verification_note: string;
+}
+/** Result of a receipt lookup by hash. */
+interface LookupResult {
+    found: boolean;
+    receipt: Receipt | null;
+    verification: VerificationResult | null;
+    meta: Record<string, unknown> | null;
+}
+/** Authenticated agent information. */
+interface AgentInfo {
+    agent_id: string;
+    agent_name: string;
+    tier: string;
+    scopes: string[];
+    rate_limit_per_minute: number;
+}
+/** Options for issuing receipts. */
+interface IssueOptions {
+    /** Hash of previous receipt for chaining. */
+    previousReceiptHash?: string;
+    /** Additional metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Base error for all NotaryOS SDK errors. */
+declare class NotaryError extends Error {
+    code: string;
+    status: number;
+    details: Record<string, unknown>;
+    constructor(message: string, code?: string, status?: number, details?: Record<string, unknown>);
+}
+/** Invalid or missing API key. */
+declare class AuthenticationError extends NotaryError {
+    constructor(message: string, code?: string);
+}
+/** Rate limit exceeded. */
+declare class RateLimitError extends NotaryError {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+/** Request validation failed. */
+declare class ValidationError extends NotaryError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * NotaryOS API client.
+ *
+ * @example
+ * ```typescript
+ * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ *
+ * // Issue a receipt
+ * const receipt = await notary.issue('data_processing', { key: 'value' });
+ *
+ * // Verify a receipt
+ * const result = await notary.verify(receipt);
+ * console.log(result.valid); // true
+ *
+ * // Check service health
+ * const status = await notary.status();
+ * ```
+ */
+declare class NotaryClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    static readonly DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
+    static readonly DEFAULT_TIMEOUT = 30000;
+    constructor(config: NotaryConfig);
+    private request;
+    private sleep;
+    /**
+     * Issue a signed receipt for an action.
+     *
+     * @param actionType - Type of action (e.g., "data_processing", "api_call")
+     * @param payload - Action payload to be receipted
+     * @param options - Optional chaining and metadata
+     * @returns A signed Receipt
+     *
+     * @example
+     * ```typescript
+     * const receipt = await notary.issue('transfer', { amount: 100, to: 'agent-b' });
+     * console.log(receipt.receipt_id);
+     * console.log(receipt.verify_url); // https://...notary/r/abc123
+     * ```
+     */
+    issue(actionType: string, payload: Record<string, unknown>, options?: IssueOptions): Promise<Receipt>;
+    /**
+     * Verify a receipt's signature and integrity.
+     *
+     * @param receipt - Receipt object or raw receipt dict
+     * @returns VerificationResult with validity details
+     *
+     * @example
+     * ```typescript
+     * const result = await notary.verify(receipt);
+     * if (result.valid) {
+     *   console.log('Receipt is authentic');
+     * }
+     * ```
+     */
+    verify(receipt: Receipt | Record<string, unknown>): Promise<VerificationResult>;
+    /** Verify a receipt by its ID (server-side lookup). */
+    verifyById(receiptId: string): Promise<VerificationResult>;
+    /**
+     * Get Notary service status.
+     *
+     * @example
+     * ```typescript
+     * const status = await notary.status();
+     * console.log(status.status); // "active"
+     * ```
+     */
+    status(): Promise<ServiceStatus>;
+    /** Get the public key for offline verification. */
+    publicKey(): Promise<PublicKeyInfo>;
+    /** Get authenticated agent info. */
+    me(): Promise<AgentInfo>;
+    /**
+     * Look up a receipt by hash (public endpoint, no API key required for lookup).
+     *
+     * @param receiptHash - Full or partial receipt hash (min 16 chars)
+     * @returns Lookup result with receipt, verification, and meta
+     *
+     * @example
+     * ```typescript
+     * const result = await notary.lookup('abc123def456...');
+     * if (result.found && result.verification?.valid) {
+     *   console.log('Receipt is valid!');
+     * }
+     * ```
+     */
+    lookup(receiptHash: string): Promise<LookupResult>;
+}
+/**
+ * Quick receipt verification without API key.
+ *
+ * Uses the public /verify endpoint — no authentication needed.
+ *
+ * @param receipt - Receipt JSON object
+ * @param baseUrl - API base URL (default: production)
+ * @returns true if the receipt is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyReceipt } from 'notaryos';
+ *
+ * const isValid = await verifyReceipt(receiptJson);
+ * console.log(isValid); // true
+ * ```
+ */
+declare function verifyReceipt(receipt: Record<string, unknown>, baseUrl?: string): Promise<boolean>;
+/**
+ * Compute SHA-256 hash of a payload using Web Crypto API.
+ *
+ * Matches the server-side hashing for independent verification.
+ *
+ * @param payload - String or JSON-serializable object
+ * @returns Hex-encoded SHA-256 digest
+ */
+declare function computeHash(payload: Record<string, unknown> | string): Promise<string>;
+
+export { type AgentInfo, AuthenticationError, type IssueOptions, type LookupResult, NotaryClient, type NotaryConfig, NotaryError, type PublicKeyInfo, RateLimitError, type Receipt, SDK_VERSION, type ServiceStatus, ValidationError, type VerificationResult, computeHash, verifyReceipt };

package/dist/index.js

@@ -0,0 +1,307 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  NotaryClient: () => NotaryClient,
+  NotaryError: () => NotaryError,
+  RateLimitError: () => RateLimitError,
+  SDK_VERSION: () => SDK_VERSION,
+  ValidationError: () => ValidationError,
+  computeHash: () => computeHash,
+  verifyReceipt: () => verifyReceipt
+});
+module.exports = __toCommonJS(index_exports);
+var SDK_VERSION = "1.0.0";
+var NotaryError = class extends Error {
+  constructor(message, code = "", status = 0, details = {}) {
+    super(message);
+    this.name = "NotaryError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var AuthenticationError = class extends NotaryError {
+  constructor(message, code = "ERR_INVALID_API_KEY") {
+    super(message, code, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends NotaryError {
+  constructor(message, retryAfter) {
+    super(message, "ERR_RATE_LIMIT_EXCEEDED", 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ValidationError = class extends NotaryError {
+  constructor(message, details = {}) {
+    super(message, "ERR_VALIDATION_FAILED", 422, details);
+    this.name = "ValidationError";
+  }
+};
+var _NotaryClient = class _NotaryClient {
+  constructor(config) {
+    const { apiKey, baseUrl, timeout, maxRetries } = config;
+    if (!apiKey || !(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
+      throw new AuthenticationError(
+        "Invalid API key format. Keys must start with notary_live_ or notary_test_"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (baseUrl || _NotaryClient.DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = timeout || _NotaryClient.DEFAULT_TIMEOUT;
+    this.maxRetries = maxRetries ?? 2;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/v1/notary${path}`;
+    const headers = {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      "User-Agent": `notary-typescript-sdk/${SDK_VERSION}`
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+          const text = await response.text();
+          return text ? JSON.parse(text) : {};
+        }
+        let errorData = {};
+        try {
+          errorData = await response.json();
+        } catch {
+        }
+        const errorInfo = errorData.error || { message: response.statusText, code: "" };
+        const errorMsg = errorInfo.message || response.statusText;
+        const errorCode = errorInfo.code || "";
+        if (response.status === 401) {
+          throw new AuthenticationError(errorMsg, errorCode);
+        }
+        if (response.status === 429) {
+          const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
+          if (attempt < this.maxRetries) {
+            await this.sleep(Math.min(retryAfter * 1e3, 5e3));
+            continue;
+          }
+          throw new RateLimitError(errorMsg, retryAfter);
+        }
+        if (response.status === 422) {
+          throw new ValidationError(errorMsg, errorInfo.details || {});
+        }
+        if (response.status >= 500 && attempt < this.maxRetries) {
+          await this.sleep(2 ** attempt * 1e3);
+          lastError = new NotaryError(errorMsg, errorCode, response.status);
+          continue;
+        }
+        throw new NotaryError(errorMsg, errorCode, response.status, errorInfo.details || {});
+      } catch (err) {
+        clearTimeout(timeoutId);
+        if (err instanceof NotaryError) throw err;
+        if (attempt < this.maxRetries) {
+          await this.sleep(2 ** attempt * 1e3);
+          lastError = err;
+          continue;
+        }
+        throw new NotaryError(
+          `Connection failed: ${err.message}`,
+          "ERR_CONNECTION"
+        );
+      }
+    }
+    throw lastError || new NotaryError("Request failed", "ERR_UNKNOWN");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Issue a signed receipt for an action.
+   *
+   * @param actionType - Type of action (e.g., "data_processing", "api_call")
+   * @param payload - Action payload to be receipted
+   * @param options - Optional chaining and metadata
+   * @returns A signed Receipt
+   *
+   * @example
+   * ```typescript
+   * const receipt = await notary.issue('transfer', { amount: 100, to: 'agent-b' });
+   * console.log(receipt.receipt_id);
+   * console.log(receipt.verify_url); // https://...notary/r/abc123
+   * ```
+   */
+  async issue(actionType, payload, options = {}) {
+    const body = {
+      action_type: actionType,
+      payload
+    };
+    if (options.previousReceiptHash) {
+      body.previous_receipt_hash = options.previousReceiptHash;
+    }
+    if (options.metadata) {
+      body.metadata = options.metadata;
+    }
+    const response = await this.request("POST", "/issue", body);
+    return {
+      ...response.receipt,
+      receipt_hash: response.receipt_hash,
+      verify_url: response.verify_url,
+      chain_sequence: response.chain_position
+    };
+  }
+  /**
+   * Verify a receipt's signature and integrity.
+   *
+   * @param receipt - Receipt object or raw receipt dict
+   * @returns VerificationResult with validity details
+   *
+   * @example
+   * ```typescript
+   * const result = await notary.verify(receipt);
+   * if (result.valid) {
+   *   console.log('Receipt is authentic');
+   * }
+   * ```
+   */
+  async verify(receipt) {
+    return this.request("POST", "/verify", { receipt });
+  }
+  /** Verify a receipt by its ID (server-side lookup). */
+  async verifyById(receiptId) {
+    return this.request("POST", "/verify", { receipt_id: receiptId });
+  }
+  /**
+   * Get Notary service status.
+   *
+   * @example
+   * ```typescript
+   * const status = await notary.status();
+   * console.log(status.status); // "active"
+   * ```
+   */
+  async status() {
+    return this.request("GET", "/status");
+  }
+  /** Get the public key for offline verification. */
+  async publicKey() {
+    return this.request("GET", "/public-key");
+  }
+  /** Get authenticated agent info. */
+  async me() {
+    return this.request("GET", "/agents/me");
+  }
+  /**
+   * Look up a receipt by hash (public endpoint, no API key required for lookup).
+   *
+   * @param receiptHash - Full or partial receipt hash (min 16 chars)
+   * @returns Lookup result with receipt, verification, and meta
+   *
+   * @example
+   * ```typescript
+   * const result = await notary.lookup('abc123def456...');
+   * if (result.found && result.verification?.valid) {
+   *   console.log('Receipt is valid!');
+   * }
+   * ```
+   */
+  async lookup(receiptHash) {
+    const url = `${this.baseUrl}/v1/notary/r/${receiptHash}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": `notary-typescript-sdk/${SDK_VERSION}`
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 404) {
+        return { found: false, receipt: null, verification: null, meta: null };
+      }
+      if (!response.ok) {
+        throw new NotaryError(
+          response.statusText,
+          "ERR_LOOKUP",
+          response.status
+        );
+      }
+      return await response.json();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof NotaryError) throw err;
+      throw new NotaryError(
+        `Connection failed: ${err.message}`,
+        "ERR_CONNECTION"
+      );
+    }
+  }
+};
+_NotaryClient.DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
+_NotaryClient.DEFAULT_TIMEOUT = 3e4;
+var NotaryClient = _NotaryClient;
+async function verifyReceipt(receipt, baseUrl = NotaryClient.DEFAULT_BASE_URL) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/notary/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ receipt })
+    });
+    if (!response.ok) return false;
+    const result = await response.json();
+    return result.valid === true;
+  } catch {
+    return false;
+  }
+}
+async function computeHash(payload) {
+  const data = typeof payload === "string" ? payload : JSON.stringify(payload, Object.keys(payload).sort());
+  const encoded = new TextEncoder().encode(data);
+  const buffer = await crypto.subtle.digest("SHA-256", encoded);
+  const bytes = new Uint8Array(buffer);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  NotaryClient,
+  NotaryError,
+  RateLimitError,
+  SDK_VERSION,
+  ValidationError,
+  computeHash,
+  verifyReceipt
+});

package/dist/index.mjs

@@ -0,0 +1,275 @@
+// src/index.ts
+var SDK_VERSION = "1.0.0";
+var NotaryError = class extends Error {
+  constructor(message, code = "", status = 0, details = {}) {
+    super(message);
+    this.name = "NotaryError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var AuthenticationError = class extends NotaryError {
+  constructor(message, code = "ERR_INVALID_API_KEY") {
+    super(message, code, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends NotaryError {
+  constructor(message, retryAfter) {
+    super(message, "ERR_RATE_LIMIT_EXCEEDED", 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ValidationError = class extends NotaryError {
+  constructor(message, details = {}) {
+    super(message, "ERR_VALIDATION_FAILED", 422, details);
+    this.name = "ValidationError";
+  }
+};
+var _NotaryClient = class _NotaryClient {
+  constructor(config) {
+    const { apiKey, baseUrl, timeout, maxRetries } = config;
+    if (!apiKey || !(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
+      throw new AuthenticationError(
+        "Invalid API key format. Keys must start with notary_live_ or notary_test_"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (baseUrl || _NotaryClient.DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = timeout || _NotaryClient.DEFAULT_TIMEOUT;
+    this.maxRetries = maxRetries ?? 2;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/v1/notary${path}`;
+    const headers = {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      "User-Agent": `notary-typescript-sdk/${SDK_VERSION}`
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+          const text = await response.text();
+          return text ? JSON.parse(text) : {};
+        }
+        let errorData = {};
+        try {
+          errorData = await response.json();
+        } catch {
+        }
+        const errorInfo = errorData.error || { message: response.statusText, code: "" };
+        const errorMsg = errorInfo.message || response.statusText;
+        const errorCode = errorInfo.code || "";
+        if (response.status === 401) {
+          throw new AuthenticationError(errorMsg, errorCode);
+        }
+        if (response.status === 429) {
+          const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
+          if (attempt < this.maxRetries) {
+            await this.sleep(Math.min(retryAfter * 1e3, 5e3));
+            continue;
+          }
+          throw new RateLimitError(errorMsg, retryAfter);
+        }
+        if (response.status === 422) {
+          throw new ValidationError(errorMsg, errorInfo.details || {});
+        }
+        if (response.status >= 500 && attempt < this.maxRetries) {
+          await this.sleep(2 ** attempt * 1e3);
+          lastError = new NotaryError(errorMsg, errorCode, response.status);
+          continue;
+        }
+        throw new NotaryError(errorMsg, errorCode, response.status, errorInfo.details || {});
+      } catch (err) {
+        clearTimeout(timeoutId);
+        if (err instanceof NotaryError) throw err;
+        if (attempt < this.maxRetries) {
+          await this.sleep(2 ** attempt * 1e3);
+          lastError = err;
+          continue;
+        }
+        throw new NotaryError(
+          `Connection failed: ${err.message}`,
+          "ERR_CONNECTION"
+        );
+      }
+    }
+    throw lastError || new NotaryError("Request failed", "ERR_UNKNOWN");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Issue a signed receipt for an action.
+   *
+   * @param actionType - Type of action (e.g., "data_processing", "api_call")
+   * @param payload - Action payload to be receipted
+   * @param options - Optional chaining and metadata
+   * @returns A signed Receipt
+   *
+   * @example
+   * ```typescript
+   * const receipt = await notary.issue('transfer', { amount: 100, to: 'agent-b' });
+   * console.log(receipt.receipt_id);
+   * console.log(receipt.verify_url); // https://...notary/r/abc123
+   * ```
+   */
+  async issue(actionType, payload, options = {}) {
+    const body = {
+      action_type: actionType,
+      payload
+    };
+    if (options.previousReceiptHash) {
+      body.previous_receipt_hash = options.previousReceiptHash;
+    }
+    if (options.metadata) {
+      body.metadata = options.metadata;
+    }
+    const response = await this.request("POST", "/issue", body);
+    return {
+      ...response.receipt,
+      receipt_hash: response.receipt_hash,
+      verify_url: response.verify_url,
+      chain_sequence: response.chain_position
+    };
+  }
+  /**
+   * Verify a receipt's signature and integrity.
+   *
+   * @param receipt - Receipt object or raw receipt dict
+   * @returns VerificationResult with validity details
+   *
+   * @example
+   * ```typescript
+   * const result = await notary.verify(receipt);
+   * if (result.valid) {
+   *   console.log('Receipt is authentic');
+   * }
+   * ```
+   */
+  async verify(receipt) {
+    return this.request("POST", "/verify", { receipt });
+  }
+  /** Verify a receipt by its ID (server-side lookup). */
+  async verifyById(receiptId) {
+    return this.request("POST", "/verify", { receipt_id: receiptId });
+  }
+  /**
+   * Get Notary service status.
+   *
+   * @example
+   * ```typescript
+   * const status = await notary.status();
+   * console.log(status.status); // "active"
+   * ```
+   */
+  async status() {
+    return this.request("GET", "/status");
+  }
+  /** Get the public key for offline verification. */
+  async publicKey() {
+    return this.request("GET", "/public-key");
+  }
+  /** Get authenticated agent info. */
+  async me() {
+    return this.request("GET", "/agents/me");
+  }
+  /**
+   * Look up a receipt by hash (public endpoint, no API key required for lookup).
+   *
+   * @param receiptHash - Full or partial receipt hash (min 16 chars)
+   * @returns Lookup result with receipt, verification, and meta
+   *
+   * @example
+   * ```typescript
+   * const result = await notary.lookup('abc123def456...');
+   * if (result.found && result.verification?.valid) {
+   *   console.log('Receipt is valid!');
+   * }
+   * ```
+   */
+  async lookup(receiptHash) {
+    const url = `${this.baseUrl}/v1/notary/r/${receiptHash}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": `notary-typescript-sdk/${SDK_VERSION}`
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 404) {
+        return { found: false, receipt: null, verification: null, meta: null };
+      }
+      if (!response.ok) {
+        throw new NotaryError(
+          response.statusText,
+          "ERR_LOOKUP",
+          response.status
+        );
+      }
+      return await response.json();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof NotaryError) throw err;
+      throw new NotaryError(
+        `Connection failed: ${err.message}`,
+        "ERR_CONNECTION"
+      );
+    }
+  }
+};
+_NotaryClient.DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
+_NotaryClient.DEFAULT_TIMEOUT = 3e4;
+var NotaryClient = _NotaryClient;
+async function verifyReceipt(receipt, baseUrl = NotaryClient.DEFAULT_BASE_URL) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/notary/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ receipt })
+    });
+    if (!response.ok) return false;
+    const result = await response.json();
+    return result.valid === true;
+  } catch {
+    return false;
+  }
+}
+async function computeHash(payload) {
+  const data = typeof payload === "string" ? payload : JSON.stringify(payload, Object.keys(payload).sort());
+  const encoded = new TextEncoder().encode(data);
+  const buffer = await crypto.subtle.digest("SHA-256", encoded);
+  const bytes = new Uint8Array(buffer);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+export {
+  AuthenticationError,
+  NotaryClient,
+  NotaryError,
+  RateLimitError,
+  SDK_VERSION,
+  ValidationError,
+  computeHash,
+  verifyReceipt
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "notaryos",
+  "version": "1.0.0",
+  "description": "NotaryOS SDK - Cryptographic receipts for AI agent actions. Issue, verify, and audit agent behavior with Ed25519 signatures.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test dist/test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "notary",
+    "cryptographic",
+    "receipt",
+    "verification",
+    "ai",
+    "agent",
+    "ed25519",
+    "audit",
+    "accountability",
+    "a2a",
+    "agent-to-agent"
+  ],
+  "author": {
+    "name": "Agent Town Square",
+    "email": "hello@agenttownsquare.com",
+    "url": "https://agenttownsquare.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hellothere012/notaryos"
+  },
+  "homepage": "https://notaryos.org",
+  "bugs": {
+    "url": "https://github.com/hellothere012/notaryos/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}