notaryos 2.0.0 → 2.1.1

package/README.md

@@ -31,111 +31,65 @@ const isValid = await verifyReceipt(receiptJson);
 // true
 ```
 
-## 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
+### Full Example
 
 ```typescript
-import { NotaryErrorCode } from 'notaryos';
-
-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
-```
-
-## Auto-Receipting
+import { NotaryClient } from 'notaryos';
 
-```typescript
-const agent = notary.wrap(myAgent, { mode: 'all', fireAndForget: true });
-await agent.processData(input); // auto-receipted!
-```
+const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
 
-Options: `mode` (`'all'` | `'errors_only'` | `'sample'`), `sampleRate`, `fireAndForget`, `dryRun`.
+// 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',
+});
 
-## Counterfactual Receipts
+// Verify it
+const result = await notary.verify(receipt);
+console.log(result.valid);        // true
+console.log(result.signature_ok); // true
 
-```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',
-});
+// Check service health
+const status = await notary.status();
+console.log(status.status); // "active"
 
-// v2: Commit-reveal
-const commit = await notary.counterfactual.commit({ ...options });
-const reveal = await notary.counterfactual.reveal(hash, plaintext);
+// Get public key for offline verification
+const keyInfo = await notary.publicKey();
+console.log(keyInfo.public_key_pem);
 ```
 
-## Offline Verification
-
-```typescript
-import { OfflineVerifier } from 'notaryos/offline';
+## API Reference
 
-const verifier = await OfflineVerifier.fromJWKS();
-const result = await verifier.verify(receipt);
-console.log(result.valid); // true — no API call needed
-```
+### `NotaryClient`
 
-## Framework Integrations
+| 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 |
 
-### Vercel AI SDK
+### `verifyReceipt(receipt, baseUrl?)`
 
-```typescript
-import { notaryMiddleware } from 'notaryos/integrations/vercel-ai';
-```
+Public verification without API key. Returns `boolean`.
 
-### LangChain.js
+### `computeHash(payload)`
 
-```typescript
-import { NotaryCallbackHandler } from 'notaryos/integrations/langchain';
-const handler = new NotaryCallbackHandler(notary);
-```
+SHA-256 hash matching server-side computation. Returns hex string.
 
-### OpenAI Agents
+## Configuration
 
 ```typescript
-import { notaryToolWrapper } from 'notaryos/integrations/openai-agents';
-const wrappedTool = notaryToolWrapper(notary, myToolFn, 'my_tool');
+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
@@ -156,17 +110,18 @@ try {
 }
 ```
 
-## Configuration
+## Get an API Key
 
-```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
-});
-```
+1. Sign up at [agenttownsquare.com/notary](https://agenttownsquare.com/notary)
+2. Generate an API key from the dashboard
+3. Keys start with `notary_live_` (production) or `notary_test_` (sandbox)
+
+## Links
+
+- [NotaryOS Documentation](https://agenttownsquare.com/notary)
+- [API Reference](https://api.agenttownsquare.com/v1/notary/status)
+- [Public Verification](https://api.agenttownsquare.com/v1/notary/r/{hash})
 
 ## License
 
-BUSL-1.1
+MIT

package/dist/index.d.mts

@@ -17,27 +17,7 @@
  *
  * @packageDocumentation
  */
-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];
+declare const SDK_VERSION = "2.1.1";
 /** Client configuration options. */
 interface NotaryConfig {
     /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
@@ -93,13 +73,6 @@ interface PublicKeyInfo {
     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;
@@ -115,46 +88,16 @@ 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;
+/** Object-form argument for issue()/seal(). */
+interface IssueRequest {
+    /** Type of action (e.g., "data_processing", "api_call"). */
+    actionType: string;
+    /** Action payload to be receipted. */
+    payload: Record<string, unknown>;
+    /** 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 {
@@ -176,41 +119,6 @@ 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.
  *
@@ -225,11 +133,8 @@ declare class CounterfactualClient {
  * const result = await notary.verify(receipt);
  * console.log(result.valid); // true
  *
- * // Counterfactual receipts
- * const stamp = await notary.counterfactual.issue({ ... });
- *
- * // Auto-receipt wrapping
- * const agent = notary.wrap(myAgent, { mode: 'all' });
+ * // Check service health
+ * const status = await notary.status();
  * ```
  */
 declare class NotaryClient {
@@ -237,78 +142,88 @@ 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.
      *
-     * @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
-     */
-    issue(actionType: string, payload: Record<string, unknown>, options?: IssueOptions): Promise<Receipt>;
-    /** 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. */
-    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).
+     * Supports two calling conventions:
+     * - `issue('action_type', { key: 'value' })` — positional args
+     * - `issue({ actionType: 'action_type', payload: { key: 'value' } })` — object form
      *
-     * @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).
+     * @example
+     * ```typescript
+     * // Positional (recommended)
+     * const receipt = await notary.issue('transfer', { amount: 100 });
      *
-     * @param receiptHash - The receipt hash to check
-     * @returns Provenance report with grounding status, ancestors, paths
+     * // Object form
+     * const receipt = await notary.issue({ actionType: 'transfer', payload: { amount: 100 } });
+     * ```
      */
-    provenance(receiptHash: string): Promise<Record<string, unknown>>;
+    issue(actionTypeOrRequest: string | IssueRequest, payload?: Record<string, unknown>, options?: IssueOptions): Promise<Receipt>;
+    /** Alias: seal() → issue() for the 3-line integration pattern. */
+    seal: (actionTypeOrRequest: string | IssueRequest, payload?: Record<string, unknown>, options?: IssueOptions) => Promise<Receipt>;
     /**
-     * Wrap an object so method calls are automatically receipted.
+     * Verify a receipt's signature and integrity.
      *
-     * Uses ES6 Proxy to intercept method calls. Receipts are issued
-     * in the background via fire-and-forget (won't slow down your agent).
+     * @param receipt - Receipt object or raw receipt dict
+     * @returns VerificationResult with validity details
      *
-     * @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.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 agent = notary.wrap(myAgent, { mode: 'all', fireAndForget: true });
-     * await agent.processData(input); // auto-receipted!
+     * const status = await notary.status();
+     * console.log(status.status); // "active"
      * ```
      */
-    wrap<T extends object>(obj: T, config?: AutoReceiptConfig): T;
+    status(): Promise<ServiceStatus>;
+    /** Get the public key for offline verification. */
+    publicKey(): Promise<PublicKeyInfo>;
+    /** Get authenticated agent info. */
+    me(): Promise<AgentInfo>;
 }
 /**
  * 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 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 };
+export { type AgentInfo, AuthenticationError, type IssueOptions, type IssueRequest, NotaryClient, type NotaryConfig, NotaryError, type PublicKeyInfo, RateLimitError, type Receipt, SDK_VERSION, type ServiceStatus, ValidationError, type VerificationResult, computeHash, verifyReceipt };