notaryos 1.0.0 → 2.0.0

package/dist/index.mjs

@@ -1,5 +1,25 @@
 // src/index.ts
-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);
@@ -28,6 +48,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;
@@ -41,6 +134,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 = {
@@ -108,9 +208,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.
    *
@@ -118,13 +249,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 = {
@@ -145,20 +269,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 });
   }
@@ -166,15 +277,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");
   }
@@ -186,54 +289,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;
@@ -263,10 +462,21 @@ 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}>`;
+}
 export {
   AuthenticationError,
+  CounterfactualClient,
   NotaryClient,
   NotaryError,
+  NotaryErrorCode,
   RateLimitError,
   SDK_VERSION,
   ValidationError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notaryos",
-  "version": "1.0.0",
+  "version": "2.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",
@@ -38,10 +38,10 @@
   ],
   "author": {
     "name": "Agent Town Square",
-    "email": "hello@agenttownsquare.com",
-    "url": "https://agenttownsquare.com"
+    "email": "hello@notaryos.org",
+    "url": "https://notaryos.org"
   },
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/hellothere012/notaryos"