notaryos 1.0.0 → 2.0.0

package/README.md

@@ -31,65 +31,111 @@ const isValid = await verifyReceipt(receiptJson);
 // true
 ```
 
-### Full Example
+## API Reference
+
+### `NotaryClient`
+
+| Method | Auth | Description |
+|--------|------|-------------|
+| `issue(actionType, payload, options?)` | API Key | Issue a signed receipt |
+| `verify(receipt)` | Public | Verify a receipt |
+| `verifyById(receiptId)` | API Key | Verify by receipt ID |
+| `status()` | Public | Service health check |
+| `publicKey()` | Public | Get Ed25519 public key |
+| `me()` | API Key | Authenticated agent info |
+| `lookup(receiptHash)` | Public | Look up receipt by hash |
+| `history(options?)` | Clerk JWT | Paginated receipt history |
+| `provenance(receiptHash)` | Public | Provenance DAG report |
+| `wrap(obj, config?)` | API Key | Auto-receipt wrapping |
+
+### `notary.counterfactual.*`
+
+| Method | Auth | Description |
+|--------|------|-------------|
+| `issue(options)` | API Key | Issue v1 counterfactual |
+| `get(receiptHash)` | Public | Verify counterfactual |
+| `listByAgent(agentId)` | Public | List agent's counterfactuals |
+| `commit(options)` | API Key | v2 commit phase |
+| `reveal(hash, plaintext)` | API Key | v2 reveal phase |
+| `commitStatus(hash)` | Public | Check commit-reveal status |
+| `corroborate(hash, signals)` | API Key | Counter-sign |
+| `certificate(hash, format?)` | Public | Compliance certificate |
+| `verifyChain(agentId)` | Public | Chain continuity |
+
+### Standalone Functions
+
+| Function | Description |
+|----------|-------------|
+| `verifyReceipt(receipt, baseUrl?)` | Public verification (returns boolean) |
+| `computeHash(payload)` | SHA-256 matching server-side hashing |
+
+### Error Codes
 
 ```typescript
-import { NotaryClient } from 'notaryos';
+import { NotaryErrorCode } from 'notaryos';
 
-const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+NotaryErrorCode.ERR_RECEIPT_NOT_FOUND   // 404
+NotaryErrorCode.ERR_INVALID_API_KEY     // 401
+NotaryErrorCode.ERR_RATE_LIMIT_EXCEEDED // 429
+NotaryErrorCode.ERR_CHAIN_BROKEN        // 400
+// ... 16 total error codes
+```
 
-// 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',
-});
+## Auto-Receipting
+
+```typescript
+const agent = notary.wrap(myAgent, { mode: 'all', fireAndForget: true });
+await agent.processData(input); // auto-receipted!
+```
+
+Options: `mode` (`'all'` | `'errors_only'` | `'sample'`), `sampleRate`, `fireAndForget`, `dryRun`.
 
-// Verify it
-const result = await notary.verify(receipt);
-console.log(result.valid);        // true
-console.log(result.signature_ok); // true
+## Counterfactual Receipts
 
-// Check service health
-const status = await notary.status();
-console.log(status.status); // "active"
+```typescript
+// v1: Direct issuance
+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',
+});
 
-// Get public key for offline verification
-const keyInfo = await notary.publicKey();
-console.log(keyInfo.public_key_pem);
+// v2: Commit-reveal
+const commit = await notary.counterfactual.commit({ ...options });
+const reveal = await notary.counterfactual.reveal(hash, plaintext);
 ```
 
-## API Reference
+## Offline Verification
 
-### `NotaryClient`
+```typescript
+import { OfflineVerifier } from 'notaryos/offline';
 
-| 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 |
+const verifier = await OfflineVerifier.fromJWKS();
+const result = await verifier.verify(receipt);
+console.log(result.valid); // true — no API call needed
+```
 
-### `verifyReceipt(receipt, baseUrl?)`
+## Framework Integrations
 
-Public verification without API key. Returns `boolean`.
+### Vercel AI SDK
 
-### `computeHash(payload)`
+```typescript
+import { notaryMiddleware } from 'notaryos/integrations/vercel-ai';
+```
 
-SHA-256 hash matching server-side computation. Returns hex string.
+### LangChain.js
 
-## Configuration
+```typescript
+import { NotaryCallbackHandler } from 'notaryos/integrations/langchain';
+const handler = new NotaryCallbackHandler(notary);
+```
+
+### OpenAI Agents
 
 ```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
-});
+import { notaryToolWrapper } from 'notaryos/integrations/openai-agents';
+const wrappedTool = notaryToolWrapper(notary, myToolFn, 'my_tool');
 ```
 
 ## Error Handling
@@ -110,18 +156,17 @@ try {
 }
 ```
 
-## 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
+## Configuration
 
-- [NotaryOS Documentation](https://notaryos.org/docs)
-- [API Reference](https://api.agenttownsquare.com/v1/notary/status)
-- [Public Verification](https://notaryos.org/verify)
+```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
+});
+```
 
 ## License
 
-MIT
+BUSL-1.1

package/dist/index.d.mts

@@ -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 };