notaryos 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -17,7 +17,27 @@
  *
  * @packageDocumentation
  */
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "2.0.0";
+/** Standardized error codes mirroring the backend API. */
+declare const NotaryErrorCode: {
+    readonly ERR_RECEIPT_NOT_FOUND: "ERR_RECEIPT_NOT_FOUND";
+    readonly ERR_INVALID_SIGNATURE: "ERR_INVALID_SIGNATURE";
+    readonly ERR_INVALID_STRUCTURE: "ERR_INVALID_STRUCTURE";
+    readonly ERR_INVALID_TIMESTAMP: "ERR_INVALID_TIMESTAMP";
+    readonly ERR_UNKNOWN_SIGNER: "ERR_UNKNOWN_SIGNER";
+    readonly ERR_UNSUPPORTED_ALGORITHM: "ERR_UNSUPPORTED_ALGORITHM";
+    readonly ERR_CHAIN_BROKEN: "ERR_CHAIN_BROKEN";
+    readonly ERR_CHAIN_MISSING: "ERR_CHAIN_MISSING";
+    readonly ERR_PAYLOAD_TOO_LARGE: "ERR_PAYLOAD_TOO_LARGE";
+    readonly ERR_RATE_LIMIT_EXCEEDED: "ERR_RATE_LIMIT_EXCEEDED";
+    readonly ERR_INVALID_API_KEY: "ERR_INVALID_API_KEY";
+    readonly ERR_INSUFFICIENT_SCOPE: "ERR_INSUFFICIENT_SCOPE";
+    readonly ERR_VALIDATION_FAILED: "ERR_VALIDATION_FAILED";
+    readonly ERR_INTERNAL_ERROR: "ERR_INTERNAL_ERROR";
+    readonly ERR_DATABASE_ERROR: "ERR_DATABASE_ERROR";
+    readonly ERR_SIGNING_ERROR: "ERR_SIGNING_ERROR";
+};
+type NotaryErrorCodeType = (typeof NotaryErrorCode)[keyof typeof NotaryErrorCode];
 /** Client configuration options. */
 interface NotaryConfig {
     /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
@@ -95,6 +115,47 @@ interface IssueOptions {
     /** Additional metadata. */
     metadata?: Record<string, unknown>;
 }
+/** Paginated history result. */
+interface HistoryResult {
+    items: Record<string, unknown>[];
+    total: number;
+    totalPages: number;
+    page: number;
+    pageSize: number;
+}
+/** Options for history queries. */
+interface HistoryOptions {
+    page?: number;
+    pageSize?: number;
+    status?: string;
+    search?: string;
+    startDate?: string;
+    endDate?: string;
+    clerkToken?: string;
+}
+/** Counterfactual issue options. */
+interface CounterfactualIssueOptions {
+    actionNotTaken: string;
+    capabilityProof: Record<string, unknown>;
+    opportunityContext: Record<string, unknown>;
+    decisionReason: string;
+    declinationReason?: string;
+    provenanceRefs?: string[];
+    validityWindowMinutes?: number;
+}
+/** Counterfactual commit options (v2 commit-reveal). */
+interface CounterfactualCommitOptions extends CounterfactualIssueOptions {
+    minRevealDelaySeconds?: number;
+    maxRevealWindowSeconds?: number;
+}
+/** Auto-receipt configuration. */
+interface AutoReceiptConfig {
+    mode?: 'all' | 'errors_only' | 'sample';
+    sampleRate?: number;
+    fireAndForget?: boolean;
+    maxPayloadBytes?: number;
+    dryRun?: boolean;
+}
 /** Base error for all NotaryOS SDK errors. */
 declare class NotaryError extends Error {
     code: string;
@@ -115,6 +176,41 @@ declare class RateLimitError extends NotaryError {
 declare class ValidationError extends NotaryError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * Sub-client for counterfactual receipt operations (proof of non-action).
+ *
+ * @example
+ * ```typescript
+ * const stamp = await notary.counterfactual.issue({
+ *   actionNotTaken: 'delete_user_data',
+ *   capabilityProof: { scope: 'data:delete', granted: true },
+ *   opportunityContext: { user_id: 'u_123' },
+ *   decisionReason: 'GDPR retention period not yet expired',
+ * });
+ * ```
+ */
+declare class CounterfactualClient {
+    private client;
+    constructor(client: NotaryClient);
+    /** Issue a v1 counterfactual receipt (proof of non-action). */
+    issue(options: CounterfactualIssueOptions): Promise<Record<string, unknown>>;
+    /** Retrieve/verify a counterfactual receipt by hash (public). */
+    get(receiptHash: string): Promise<Record<string, unknown>>;
+    /** List counterfactual receipts for a specific agent (public). */
+    listByAgent(agentId: string, limit?: number, offset?: number): Promise<Record<string, unknown>>;
+    /** Commit a v2 counterfactual receipt (Phase 1 of commit-reveal). */
+    commit(options: CounterfactualCommitOptions): Promise<Record<string, unknown>>;
+    /** Reveal a committed counterfactual receipt (Phase 2). */
+    reveal(receiptHash: string, decisionReasonPlaintext: string): Promise<Record<string, unknown>>;
+    /** Check commit-reveal lifecycle status (public). */
+    commitStatus(receiptHash: string): Promise<Record<string, unknown>>;
+    /** Counter-sign a counterfactual receipt (corroboration). */
+    corroborate(receiptHash: string, signals: string[]): Promise<Record<string, unknown>>;
+    /** Generate a compliance certificate for a counterfactual receipt (public). */
+    certificate(receiptHash: string, format?: string): Promise<Record<string, unknown>>;
+    /** Verify counterfactual chain continuity for an agent (public). */
+    verifyChain(agentId: string): Promise<Record<string, unknown>>;
+}
 /**
  * NotaryOS API client.
  *
@@ -129,8 +225,11 @@ declare class ValidationError extends NotaryError {
  * const result = await notary.verify(receipt);
  * console.log(result.valid); // true
  *
- * // Check service health
- * const status = await notary.status();
+ * // Counterfactual receipts
+ * const stamp = await notary.counterfactual.issue({ ... });
+ *
+ * // Auto-receipt wrapping
+ * const agent = notary.wrap(myAgent, { mode: 'all' });
  * ```
  */
 declare class NotaryClient {
@@ -138,10 +237,15 @@ declare class NotaryClient {
     private baseUrl;
     private timeout;
     private maxRetries;
+    private _counterfactual?;
     static readonly DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
     static readonly DEFAULT_TIMEOUT = 30000;
     constructor(config: NotaryConfig);
+    /** Access counterfactual receipt operations (enterprise premium). */
+    get counterfactual(): CounterfactualClient;
     private request;
+    /** Public GET helper (no API key in headers). */
+    private publicGet;
     private sleep;
     /**
      * Issue a signed receipt for an action.
@@ -150,88 +254,61 @@ declare class NotaryClient {
      * @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 a receipt's signature and integrity. */
     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"
-     * ```
-     */
+    /** Get Notary service status. */
     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). */
+    lookup(receiptHash: string): Promise<LookupResult>;
+    /**
+     * Get paginated receipt history (requires Clerk JWT).
+     *
+     * @param options - Pagination, filters, and Clerk token
+     * @returns Paginated history with items, total, totalPages
+     */
+    history(options?: HistoryOptions): Promise<HistoryResult>;
+    /**
+     * Get the provenance DAG report for a receipt (public).
+     *
+     * @param receiptHash - The receipt hash to check
+     * @returns Provenance report with grounding status, ancestors, paths
+     */
+    provenance(receiptHash: string): Promise<Record<string, unknown>>;
     /**
-     * Look up a receipt by hash (public endpoint, no API key required for lookup).
+     * Wrap an object so method calls are automatically receipted.
+     *
+     * Uses ES6 Proxy to intercept method calls. Receipts are issued
+     * in the background via fire-and-forget (won't slow down your agent).
      *
-     * @param receiptHash - Full or partial receipt hash (min 16 chars)
-     * @returns Lookup result with receipt, verification, and meta
+     * @param obj - The agent or object to wrap
+     * @param config - Optional auto-receipt configuration
+     * @returns A proxied version of the object
      *
      * @example
      * ```typescript
-     * const result = await notary.lookup('abc123def456...');
-     * if (result.found && result.verification?.valid) {
-     *   console.log('Receipt is valid!');
-     * }
+     * const agent = notary.wrap(myAgent, { mode: 'all', fireAndForget: true });
+     * await agent.processData(input); // auto-receipted!
      * ```
      */
-    lookup(receiptHash: string): Promise<LookupResult>;
+    wrap<T extends object>(obj: T, config?: AutoReceiptConfig): T;
 }
 /**
  * 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 };
+export { type AgentInfo, AuthenticationError, type AutoReceiptConfig, CounterfactualClient, type CounterfactualCommitOptions, type CounterfactualIssueOptions, type HistoryOptions, type HistoryResult, type IssueOptions, type LookupResult, NotaryClient, type NotaryConfig, NotaryError, NotaryErrorCode, type NotaryErrorCodeType, type PublicKeyInfo, RateLimitError, type Receipt, SDK_VERSION, type ServiceStatus, ValidationError, type VerificationResult, computeHash, verifyReceipt };

package/dist/index.js

@@ -21,8 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
+  CounterfactualClient: () => CounterfactualClient,
   NotaryClient: () => NotaryClient,
   NotaryError: () => NotaryError,
+  NotaryErrorCode: () => NotaryErrorCode,
   RateLimitError: () => RateLimitError,
   SDK_VERSION: () => SDK_VERSION,
   ValidationError: () => ValidationError,
@@ -30,7 +32,27 @@ __export(index_exports, {
   verifyReceipt: () => verifyReceipt
 });
 module.exports = __toCommonJS(index_exports);
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "2.0.0";
+var NotaryErrorCode = {
+  // 4xx Client Errors
+  ERR_RECEIPT_NOT_FOUND: "ERR_RECEIPT_NOT_FOUND",
+  ERR_INVALID_SIGNATURE: "ERR_INVALID_SIGNATURE",
+  ERR_INVALID_STRUCTURE: "ERR_INVALID_STRUCTURE",
+  ERR_INVALID_TIMESTAMP: "ERR_INVALID_TIMESTAMP",
+  ERR_UNKNOWN_SIGNER: "ERR_UNKNOWN_SIGNER",
+  ERR_UNSUPPORTED_ALGORITHM: "ERR_UNSUPPORTED_ALGORITHM",
+  ERR_CHAIN_BROKEN: "ERR_CHAIN_BROKEN",
+  ERR_CHAIN_MISSING: "ERR_CHAIN_MISSING",
+  ERR_PAYLOAD_TOO_LARGE: "ERR_PAYLOAD_TOO_LARGE",
+  ERR_RATE_LIMIT_EXCEEDED: "ERR_RATE_LIMIT_EXCEEDED",
+  ERR_INVALID_API_KEY: "ERR_INVALID_API_KEY",
+  ERR_INSUFFICIENT_SCOPE: "ERR_INSUFFICIENT_SCOPE",
+  ERR_VALIDATION_FAILED: "ERR_VALIDATION_FAILED",
+  // 5xx Server Errors
+  ERR_INTERNAL_ERROR: "ERR_INTERNAL_ERROR",
+  ERR_DATABASE_ERROR: "ERR_DATABASE_ERROR",
+  ERR_SIGNING_ERROR: "ERR_SIGNING_ERROR"
+};
 var NotaryError = class extends Error {
   constructor(message, code = "", status = 0, details = {}) {
     super(message);
@@ -59,6 +81,79 @@ var ValidationError = class extends NotaryError {
     this.name = "ValidationError";
   }
 };
+var CounterfactualClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Issue a v1 counterfactual receipt (proof of non-action). */
+  async issue(options) {
+    return this.client["request"]("POST", "/counterfactual/issue", {
+      action_not_taken: options.actionNotTaken,
+      capability_proof: options.capabilityProof,
+      opportunity_context: options.opportunityContext,
+      decision_reason: options.decisionReason,
+      declination_reason: options.declinationReason || "unknown",
+      provenance_refs: options.provenanceRefs,
+      validity_window_minutes: options.validityWindowMinutes || 60
+    });
+  }
+  /** Retrieve/verify a counterfactual receipt by hash (public). */
+  async get(receiptHash) {
+    return this.client["publicGet"](`/v1/notary/counterfactual/r/${receiptHash}`);
+  }
+  /** List counterfactual receipts for a specific agent (public). */
+  async listByAgent(agentId, limit = 50, offset = 0) {
+    return this.client["publicGet"](
+      `/v1/notary/counterfactual/agent/${agentId}?limit=${limit}&offset=${offset}`
+    );
+  }
+  /** Commit a v2 counterfactual receipt (Phase 1 of commit-reveal). */
+  async commit(options) {
+    return this.client["request"]("POST", "/counterfactual/commit", {
+      action_not_taken: options.actionNotTaken,
+      capability_proof: options.capabilityProof,
+      opportunity_context: options.opportunityContext,
+      decision_reason: options.decisionReason,
+      declination_reason: options.declinationReason || "unknown",
+      provenance_refs: options.provenanceRefs,
+      validity_window_minutes: options.validityWindowMinutes || 60,
+      min_reveal_delay_seconds: options.minRevealDelaySeconds || 300,
+      max_reveal_window_seconds: options.maxRevealWindowSeconds || 86400
+    });
+  }
+  /** Reveal a committed counterfactual receipt (Phase 2). */
+  async reveal(receiptHash, decisionReasonPlaintext) {
+    return this.client["request"]("POST", "/counterfactual/reveal", {
+      receipt_hash: receiptHash,
+      decision_reason_plaintext: decisionReasonPlaintext
+    });
+  }
+  /** Check commit-reveal lifecycle status (public). */
+  async commitStatus(receiptHash) {
+    return this.client["publicGet"](
+      `/v1/notary/counterfactual/commit-status/${receiptHash}`
+    );
+  }
+  /** Counter-sign a counterfactual receipt (corroboration). */
+  async corroborate(receiptHash, signals) {
+    return this.client["request"]("POST", "/counterfactual/corroborate", {
+      receipt_hash: receiptHash,
+      corroboration_signals: signals
+    });
+  }
+  /** Generate a compliance certificate for a counterfactual receipt (public). */
+  async certificate(receiptHash, format = "markdown") {
+    return this.client["publicGet"](
+      `/v1/notary/counterfactual/r/${receiptHash}/certificate?format=${format}`
+    );
+  }
+  /** Verify counterfactual chain continuity for an agent (public). */
+  async verifyChain(agentId) {
+    return this.client["publicGet"](
+      `/v1/notary/counterfactual/chain/${agentId}/verify`
+    );
+  }
+};
 var _NotaryClient = class _NotaryClient {
   constructor(config) {
     const { apiKey, baseUrl, timeout, maxRetries } = config;
@@ -72,6 +167,13 @@ var _NotaryClient = class _NotaryClient {
     this.timeout = timeout || _NotaryClient.DEFAULT_TIMEOUT;
     this.maxRetries = maxRetries ?? 2;
   }
+  /** Access counterfactual receipt operations (enterprise premium). */
+  get counterfactual() {
+    if (!this._counterfactual) {
+      this._counterfactual = new CounterfactualClient(this);
+    }
+    return this._counterfactual;
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}/v1/notary${path}`;
     const headers = {
@@ -139,9 +241,40 @@ var _NotaryClient = class _NotaryClient {
     }
     throw lastError || new NotaryError("Request failed", "ERR_UNKNOWN");
   }
+  /** Public GET helper (no API key in headers). */
+  async publicGet(path) {
+    const url = `${this.baseUrl}${path}`;
+    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 };
+      }
+      if (!response.ok) {
+        throw new NotaryError(response.statusText, "ERR_REQUEST", 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");
+    }
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  // =========================================================================
+  // Core API
+  // =========================================================================
   /**
    * Issue a signed receipt for an action.
    *
@@ -149,13 +282,6 @@ var _NotaryClient = class _NotaryClient {
    * @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 = {
@@ -176,20 +302,7 @@ var _NotaryClient = class _NotaryClient {
       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');
-   * }
-   * ```
-   */
+  /** Verify a receipt's signature and integrity. */
   async verify(receipt) {
     return this.request("POST", "/verify", { receipt });
   }
@@ -197,15 +310,7 @@ var _NotaryClient = class _NotaryClient {
   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"
-   * ```
-   */
+  /** Get Notary service status. */
   async status() {
     return this.request("GET", "/status");
   }
@@ -217,54 +322,150 @@ var _NotaryClient = class _NotaryClient {
   async me() {
     return this.request("GET", "/agents/me");
   }
+  /** Look up a receipt by hash (public endpoint). */
+  async lookup(receiptHash) {
+    return this.publicGet(`/v1/notary/r/${receiptHash}`);
+  }
+  // =========================================================================
+  // History & Provenance
+  // =========================================================================
   /**
-   * 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
+   * Get paginated receipt history (requires Clerk JWT).
    *
-   * @example
-   * ```typescript
-   * const result = await notary.lookup('abc123def456...');
-   * if (result.found && result.verification?.valid) {
-   *   console.log('Receipt is valid!');
-   * }
-   * ```
+   * @param options - Pagination, filters, and Clerk token
+   * @returns Paginated history with items, total, totalPages
    */
-  async lookup(receiptHash) {
-    const url = `${this.baseUrl}/v1/notary/r/${receiptHash}`;
+  async history(options = {}) {
+    const params = new URLSearchParams();
+    params.set("page", String(options.page || 1));
+    params.set("page_size", String(options.pageSize || 10));
+    if (options.status) params.set("status", options.status);
+    if (options.search) params.set("search", options.search);
+    if (options.startDate) params.set("start_date", options.startDate);
+    if (options.endDate) params.set("end_date", options.endDate);
+    const url = `${this.baseUrl}/v1/notary/history?${params.toString()}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "User-Agent": `notary-typescript-sdk/${SDK_VERSION}`
+    };
+    if (options.clerkToken) {
+      headers["Authorization"] = `Bearer ${options.clerkToken}`;
+    } else {
+      headers["X-API-Key"] = this.apiKey;
+    }
     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}`
-        },
+        headers,
         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
-        );
+        throw new NotaryError(response.statusText, "ERR_HISTORY", 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"
-      );
+      throw new NotaryError(`Connection failed: ${err.message}`, "ERR_CONNECTION");
     }
   }
+  /**
+   * Get the provenance DAG report for a receipt (public).
+   *
+   * @param receiptHash - The receipt hash to check
+   * @returns Provenance report with grounding status, ancestors, paths
+   */
+  async provenance(receiptHash) {
+    return this.publicGet(`/v1/notary/r/${receiptHash}/provenance`);
+  }
+  // =========================================================================
+  // Auto-receipting (wrap)
+  // =========================================================================
+  /**
+   * Wrap an object so method calls are automatically receipted.
+   *
+   * Uses ES6 Proxy to intercept method calls. Receipts are issued
+   * in the background via fire-and-forget (won't slow down your agent).
+   *
+   * @param obj - The agent or object to wrap
+   * @param config - Optional auto-receipt configuration
+   * @returns A proxied version of the object
+   *
+   * @example
+   * ```typescript
+   * const agent = notary.wrap(myAgent, { mode: 'all', fireAndForget: true });
+   * await agent.processData(input); // auto-receipted!
+   * ```
+   */
+  wrap(obj, config = {}) {
+    const client = this;
+    const cfg = {
+      mode: config.mode || "all",
+      sampleRate: config.sampleRate ?? 1,
+      fireAndForget: config.fireAndForget ?? true,
+      maxPayloadBytes: config.maxPayloadBytes ?? 4096,
+      dryRun: config.dryRun ?? false
+    };
+    const className = obj.constructor?.name || "UnknownAgent";
+    let lastHash;
+    return new Proxy(obj, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value !== "function" || typeof prop !== "string" || prop.startsWith("_")) {
+          return value;
+        }
+        return async function(...args) {
+          const start = performance.now();
+          let status = "success";
+          let errorType;
+          let result;
+          try {
+            result = await value.apply(target, args);
+            return result;
+          } catch (err) {
+            status = "error";
+            errorType = err.constructor?.name || "Error";
+            throw err;
+          } finally {
+            const shouldReceipt = cfg.mode === "all" || cfg.mode === "errors_only" && status === "error" || cfg.mode === "sample" && Math.random() < cfg.sampleRate;
+            if (shouldReceipt) {
+              const durationMs = Math.round((performance.now() - start) * 100) / 100;
+              const payload = {
+                agent: className,
+                auto_receipt: true,
+                function: prop,
+                timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+                duration_ms: durationMs,
+                status,
+                error_type: errorType,
+                arguments: _safeRepr(args),
+                result_summary: _safeRepr(result)
+              };
+              if (cfg.dryRun) {
+                console.error(`[NotaryOS DRY RUN] ${String(prop)}: ${JSON.stringify(payload)}`);
+              } else if (cfg.fireAndForget) {
+                client.issue(String(prop), payload, { previousReceiptHash: lastHash }).then((r) => {
+                  if (r.receipt_hash) lastHash = r.receipt_hash;
+                }).catch(() => {
+                });
+              } else {
+                try {
+                  const r = await client.issue(String(prop), payload, {
+                    previousReceiptHash: lastHash
+                  });
+                  if (r.receipt_hash) lastHash = r.receipt_hash;
+                } catch {
+                }
+              }
+            }
+          }
+        };
+      }
+    });
+  }
 };
 _NotaryClient.DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
 _NotaryClient.DEFAULT_TIMEOUT = 3e4;
@@ -294,11 +495,22 @@ async function computeHash(payload) {
   }
   return hex;
 }
+function _safeRepr(value, depth = 3) {
+  if (depth <= 0) return value != null ? "..." : null;
+  if (value === null || value === void 0) return value;
+  if (typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") return value.length > 500 ? value.slice(0, 500) : value;
+  if (Array.isArray(value)) return `<array len=${value.length}>`;
+  if (typeof value === "object") return `<object keys=${Object.keys(value).length}>`;
+  return `<${typeof value}>`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
+  CounterfactualClient,
   NotaryClient,
   NotaryError,
+  NotaryErrorCode,
   RateLimitError,
   SDK_VERSION,
   ValidationError,