notaryos 2.1.0 → 2.2.0

package/README.md

@@ -1,8 +1,8 @@
 # NotaryOS SDK for TypeScript
 
-Cryptographic receipts for AI agent actions. Issue, verify, and audit agent behavior with Ed25519 signatures.
+> **v2.2.0** — Cryptographic receipts for AI agent actions.
 
-**Zero dependencies.** Uses native `fetch()` and Web Crypto API. Works in Node 18+, Deno, Bun, and modern browsers.
+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
 
@@ -10,86 +10,140 @@ Cryptographic receipts for AI agent actions. Issue, verify, and audit agent beha
 npm install notaryos
 ```
 
-## Quick Start
-
-### Issue a Receipt (3 lines)
+## Quick Start — 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
+const notary = new NotaryClient();  // works instantly, no signup needed
+const receipt = await notary.seal('data_processing', { key: 'value' });
 ```
 
-### Verify a Receipt (no API key needed)
+That's it. No API key needed to start — the SDK uses a free demo key automatically (10 req/min).
+For production, sign up at [notaryos.org](https://notaryos.org) and pass your own key:
 
 ```typescript
-import { verifyReceipt } from 'notaryos';
-
-const isValid = await verifyReceipt(receiptJson);
-// true
+const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });  // unlimited
 ```
 
-### Full Example
+## What You Get
+
+Every receipt includes:
+- **Ed25519 signature** — tamper-evident proof
+- **Merkle chain linking** — ordered history via `previous_receipt_hash`
+- **Receipt hash** — SHA-256 for public lookup
+- **Verify URL** — anyone can verify without an API key
+
+## Examples
+
+### Seal an Action
 
 ```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', {
+// Positional arguments (recommended)
+const receipt = await notary.seal('financial.transfer', {
   from: 'billing-agent',
   to: 'ledger-agent',
   amount: 150.00,
   currency: 'USD',
 });
 
-// Verify it
+// Object form (also works)
+const receipt2 = await notary.seal({
+  actionType: 'financial.transfer',
+  payload: { amount: 150.00, currency: 'USD' },
+});
+
+console.log(receipt.receipt_id);     // receipt_abc123...
+console.log(receipt.receipt_hash);   // sha256 hex
+console.log(receipt.signature);      // Ed25519 signature
+console.log(receipt.chain_sequence); // position in chain
+```
+
+### Verify a Receipt
+
+```typescript
+// With API key (full details)
 const result = await notary.verify(receipt);
 console.log(result.valid);        // true
 console.log(result.signature_ok); // true
+console.log(result.structure_ok); // true
+
+// Without API key (public, returns boolean)
+import { verifyReceipt } from 'notaryos';
+const isValid = await verifyReceipt(receiptJson); // true
+```
+
+### Compute Hashes (Client-Side)
 
-// Check service health
-const status = await notary.status();
-console.log(status.status); // "active"
+```typescript
+import { computeHash } from 'notaryos';
 
-// Get public key for offline verification
-const keyInfo = await notary.publicKey();
-console.log(keyInfo.public_key_pem);
+const hash = await computeHash({ key: 'value' });
+// Matches server-side SHA-256 computation
 ```
 
-## API Reference
+## Full API Reference
 
 ### `NotaryClient`
 
+```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
+});
+```
+
 | Method | Auth | Description |
 |--------|------|-------------|
+| `seal(actionType, payload, options?)` | API Key | Issue a signed receipt (alias for `issue`) |
+| `seal({ actionType, payload, ... })` | API Key | Object-form issue |
 | `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 |
+| `issue({ actionType, payload, ... })` | API Key | Object-form issue |
+| `verify(receipt)` | API Key | Verify a receipt's signature and integrity |
+| `verifyById(receiptId)` | API Key | Verify by receipt ID (server-side lookup) |
 | `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`.
+| `publicKey()` | API Key | Get Ed25519 public key for offline verification |
+| `me()` | API Key | Get authenticated agent info (id, tier, scopes) |
 
-### `computeHash(payload)`
+### Standalone Functions
 
-SHA-256 hash matching server-side computation. Returns hex string.
+| Function | Auth | Description |
+|----------|------|-------------|
+| `verifyReceipt(receipt, baseUrl?)` | Public | Quick verification, returns `boolean` |
+| `computeHash(payload)` | None | SHA-256 hash matching server computation |
 
-## Configuration
+### Types
 
 ```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
-});
+interface Receipt {
+  receipt_id: string;
+  timestamp: string;
+  agent_id: string;
+  action_type: string;
+  payload_hash: string;
+  signature: string;
+  signature_type: string;
+  key_id: string;
+  chain_sequence?: number;
+  previous_receipt_hash?: string;
+  receipt_hash?: string;
+  verify_url?: string;
+}
+
+interface VerificationResult {
+  valid: boolean;
+  signature_ok: boolean;
+  structure_ok: boolean;
+  chain_ok?: boolean;
+  reason: string;
+  details: Record<string, unknown>;
+}
 ```
 
 ## Error Handling
@@ -98,30 +152,45 @@ const notary = new NotaryClient({
 import { NotaryClient, AuthenticationError, RateLimitError, ValidationError } from 'notaryos';
 
 try {
-  const receipt = await notary.issue('action', payload);
+  const receipt = await notary.seal('action', { key: 'value' });
 } catch (err) {
   if (err instanceof AuthenticationError) {
-    // Invalid API key
+    // Invalid or expired API key (401)
   } else if (err instanceof RateLimitError) {
-    // Wait err.retryAfter seconds
+    // Too many requests — wait err.retryAfter seconds (429)
   } else if (err instanceof ValidationError) {
-    // Check err.details
+    // Request validation failed — check err.details (422)
   }
 }
 ```
 
+## Works With Any AI Stack
+
+NotaryOS is LLM-agnostic. It seals *actions*, not model calls:
+
+```typescript
+// Your custom LLM — any model, any provider
+const result = await myCustomLLM.generate('Analyze this document');
+
+// Seal the proof
+const receipt = await notary.seal('llm.inference', {
+  model: 'my-custom-llm-v3',
+  outputHash: await computeHash(result),
+});
+```
+
 ## Get an API Key
 
-1. Sign up at [agenttownsquare.com/notary](https://agenttownsquare.com/notary)
+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://agenttownsquare.com/notary)
-- [API Reference](https://api.agenttownsquare.com/v1/notary/status)
-- [Public Verification](https://api.agenttownsquare.com/v1/notary/r/{hash})
+- [NotaryOS Documentation](https://notaryos.org/docs)
+- [API Reference](https://notaryos.org/api-docs)
+- [GitHub](https://github.com/hellothere012/notaryos)
 
 ## License
 
-MIT
+BSL 1.1 (Apache 2.0 after 2029-02-25)

package/dist/index.d.mts

@@ -4,11 +4,15 @@
  * Issue, verify, and audit agent behavior with Ed25519 signatures.
  * Zero dependencies. Uses native fetch() and Web Crypto API.
  *
- * Quick start:
+ * Quick start (no signup needed):
  *
  *   import { NotaryClient } from 'notaryos';
+ *   const notary = new NotaryClient();  // uses free demo key (10 req/min)
+ *   const receipt = await notary.seal('my_action', { key: 'value' });
+ *
+ * Production (unlimited):
+ *
  *   const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
- *   const receipt = await notary.issue('my_action', { key: 'value' });
  *
  * Verify without API key:
  *
@@ -17,11 +21,11 @@
  *
  * @packageDocumentation
  */
-declare const SDK_VERSION = "2.1.0";
+declare const SDK_VERSION = "2.2.0";
 /** Client configuration options. */
 interface NotaryConfig {
-    /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
-    apiKey: string;
+    /** Your Notary API key. If omitted, uses the free demo key (10 req/min). */
+    apiKey?: string;
     /** API base URL (default: https://api.agenttownsquare.com). */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000). */
@@ -124,17 +128,16 @@ declare class ValidationError extends NotaryError {
  *
  * @example
  * ```typescript
- * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ * // No signup needed — uses free demo key (10 req/min)
+ * const notary = new NotaryClient();
+ * const receipt = await notary.seal('data_processing', { key: 'value' });
  *
- * // Issue a receipt
- * const receipt = await notary.issue('data_processing', { key: 'value' });
+ * // Production (unlimited)
+ * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
  *
  * // 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 {
@@ -144,7 +147,8 @@ declare class NotaryClient {
     private maxRetries;
     static readonly DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
     static readonly DEFAULT_TIMEOUT = 30000;
-    constructor(config: NotaryConfig);
+    static readonly DEMO_API_KEY = "notary_test_public_demo_b0821da365e0e8ce";
+    constructor(config?: NotaryConfig);
     private request;
     private sleep;
     /**

package/dist/index.d.ts

@@ -4,11 +4,15 @@
  * Issue, verify, and audit agent behavior with Ed25519 signatures.
  * Zero dependencies. Uses native fetch() and Web Crypto API.
  *
- * Quick start:
+ * Quick start (no signup needed):
  *
  *   import { NotaryClient } from 'notaryos';
+ *   const notary = new NotaryClient();  // uses free demo key (10 req/min)
+ *   const receipt = await notary.seal('my_action', { key: 'value' });
+ *
+ * Production (unlimited):
+ *
  *   const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
- *   const receipt = await notary.issue('my_action', { key: 'value' });
  *
  * Verify without API key:
  *
@@ -17,11 +21,11 @@
  *
  * @packageDocumentation
  */
-declare const SDK_VERSION = "2.1.0";
+declare const SDK_VERSION = "2.2.0";
 /** Client configuration options. */
 interface NotaryConfig {
-    /** Your Notary API key (notary_live_xxx or notary_test_xxx). */
-    apiKey: string;
+    /** Your Notary API key. If omitted, uses the free demo key (10 req/min). */
+    apiKey?: string;
     /** API base URL (default: https://api.agenttownsquare.com). */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000). */
@@ -124,17 +128,16 @@ declare class ValidationError extends NotaryError {
  *
  * @example
  * ```typescript
- * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
+ * // No signup needed — uses free demo key (10 req/min)
+ * const notary = new NotaryClient();
+ * const receipt = await notary.seal('data_processing', { key: 'value' });
  *
- * // Issue a receipt
- * const receipt = await notary.issue('data_processing', { key: 'value' });
+ * // Production (unlimited)
+ * const notary = new NotaryClient({ apiKey: 'notary_live_xxx' });
  *
  * // 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 {
@@ -144,7 +147,8 @@ declare class NotaryClient {
     private maxRetries;
     static readonly DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
     static readonly DEFAULT_TIMEOUT = 30000;
-    constructor(config: NotaryConfig);
+    static readonly DEMO_API_KEY = "notary_test_public_demo_b0821da365e0e8ce";
+    constructor(config?: NotaryConfig);
     private request;
     private sleep;
     /**

package/dist/index.js

@@ -30,7 +30,7 @@ __export(index_exports, {
   verifyReceipt: () => verifyReceipt
 });
 module.exports = __toCommonJS(index_exports);
-var SDK_VERSION = "2.1.0";
+var SDK_VERSION = "2.2.0";
 var NotaryError = class extends Error {
   constructor(message, code = "", status = 0, details = {}) {
     super(message);
@@ -60,13 +60,14 @@ var ValidationError = class extends NotaryError {
   }
 };
 var _NotaryClient = class _NotaryClient {
-  constructor(config) {
+  constructor(config = {}) {
     /** Alias: seal() → issue() for the 3-line integration pattern. */
     this.seal = this.issue.bind(this);
-    const { apiKey, baseUrl, timeout, maxRetries } = config;
-    if (!apiKey || !(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
+    const { baseUrl, timeout, maxRetries } = config;
+    const apiKey = config.apiKey || _NotaryClient.DEMO_API_KEY;
+    if (!(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
       throw new AuthenticationError(
-        "Invalid API key format. Keys must start with notary_live_ or notary_test_"
+        "Invalid API key format. Keys must start with notary_live_ or notary_test_.\n\n  Quick start (no signup):\n    new NotaryClient()  // uses free demo key\n\n  Production (unlimited):\n    Sign up at https://notaryos.org to get your own key.\n"
       );
     }
     this.apiKey = apiKey;
@@ -175,6 +176,9 @@ var _NotaryClient = class _NotaryClient {
       actionType = actionTypeOrRequest;
       actionPayload = payload || {};
     }
+    if (!actionType || typeof actionType !== "string") {
+      throw new ValidationError("actionType is required and must be a non-empty string");
+    }
     const body = {
       action_type: actionType,
       payload: actionPayload
@@ -237,6 +241,7 @@ var _NotaryClient = class _NotaryClient {
 };
 _NotaryClient.DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
 _NotaryClient.DEFAULT_TIMEOUT = 3e4;
+_NotaryClient.DEMO_API_KEY = "notary_test_public_demo_b0821da365e0e8ce";
 var NotaryClient = _NotaryClient;
 async function verifyReceipt(receipt, baseUrl = NotaryClient.DEFAULT_BASE_URL) {
   try {

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-var SDK_VERSION = "2.1.0";
+var SDK_VERSION = "2.2.0";
 var NotaryError = class extends Error {
   constructor(message, code = "", status = 0, details = {}) {
     super(message);
@@ -29,13 +29,14 @@ var ValidationError = class extends NotaryError {
   }
 };
 var _NotaryClient = class _NotaryClient {
-  constructor(config) {
+  constructor(config = {}) {
     /** Alias: seal() → issue() for the 3-line integration pattern. */
     this.seal = this.issue.bind(this);
-    const { apiKey, baseUrl, timeout, maxRetries } = config;
-    if (!apiKey || !(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
+    const { baseUrl, timeout, maxRetries } = config;
+    const apiKey = config.apiKey || _NotaryClient.DEMO_API_KEY;
+    if (!(apiKey.startsWith("notary_live_") || apiKey.startsWith("notary_test_"))) {
       throw new AuthenticationError(
-        "Invalid API key format. Keys must start with notary_live_ or notary_test_"
+        "Invalid API key format. Keys must start with notary_live_ or notary_test_.\n\n  Quick start (no signup):\n    new NotaryClient()  // uses free demo key\n\n  Production (unlimited):\n    Sign up at https://notaryos.org to get your own key.\n"
       );
     }
     this.apiKey = apiKey;
@@ -144,6 +145,9 @@ var _NotaryClient = class _NotaryClient {
       actionType = actionTypeOrRequest;
       actionPayload = payload || {};
     }
+    if (!actionType || typeof actionType !== "string") {
+      throw new ValidationError("actionType is required and must be a non-empty string");
+    }
     const body = {
       action_type: actionType,
       payload: actionPayload
@@ -206,6 +210,7 @@ var _NotaryClient = class _NotaryClient {
 };
 _NotaryClient.DEFAULT_BASE_URL = "https://api.agenttownsquare.com";
 _NotaryClient.DEFAULT_TIMEOUT = 3e4;
+_NotaryClient.DEMO_API_KEY = "notary_test_public_demo_b0821da365e0e8ce";
 var NotaryClient = _NotaryClient;
 async function verifyReceipt(receipt, baseUrl = NotaryClient.DEFAULT_BASE_URL) {
   try {

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "notaryos",
-  "version": "2.1.0",
+  "version": "2.2.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",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [
@@ -37,18 +37,18 @@
     "agent-to-agent"
   ],
   "author": {
-    "name": "Agent Town Square",
-    "email": "hello@agenttownsquare.com",
-    "url": "https://agenttownsquare.com"
+    "name": "NotaryOS",
+    "email": "hello@notaryos.org",
+    "url": "https://notaryos.org"
   },
-  "license": "MIT",
+  "license": "BSL-1.1",
   "repository": {
     "type": "git",
-    "url": "https://github.com/agenttownsquare/notaryos-sdk-typescript"
+    "url": "https://github.com/hellothere012/notaryos"
   },
-  "homepage": "https://agenttownsquare.com/notary",
+  "homepage": "https://notaryos.org",
   "bugs": {
-    "url": "https://github.com/agenttownsquare/notaryos-sdk-typescript/issues"
+    "url": "https://github.com/hellothere012/notaryos/issues"
   },
   "engines": {
     "node": ">=18.0.0"