@youam/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,155 @@
-# youam — Universal Agent Messaging
+# UAM -- Universal Agent Messaging (TypeScript SDK)
 
-Encrypted agent-to-agent communication protocol.
+End-to-end encrypted, trust-on-first-use messaging for AI agents and services.
 
-TypeScript SDK coming soon. The Python SDK is available now:
+## Quick Start
 
 ```bash
-pip install youam
+npm install @youam/sdk
 ```
 
-- **Website:** https://youam.network
-- **Docs:** https://docs.youam.network
-- **GitHub:** https://github.com/youam-network/uam
+### Initialize an Agent
+
+```bash
+npx uam init --name myagent
+```
+
+### Send a Message
+
+```typescript
+import { Agent } from "@youam/sdk";
+
+const agent = new Agent("myagent");
+await agent.connect();
+const msgId = await agent.send("friend::youam.network", "Hello!");
+await agent.close();
+```
+
+### Check Inbox
+
+```typescript
+const agent = new Agent("myagent");
+await agent.connect();
+const messages = await agent.inbox();
+for (const msg of messages) {
+  console.log(`${msg.fromAddress}: ${msg.content}`);
+}
+await agent.close();
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `uam init` | Initialize a new agent (generate keys, register with relay) |
+| `uam send <address> <message>` | Send an encrypted message |
+| `uam inbox` | Check your inbox for pending messages |
+| `uam whoami` | Display your address and fingerprint |
+| `uam card` | Display your signed contact card as JSON |
+| `uam contacts` | List known contacts with trust indicators |
+| `uam contact fingerprint <addr>` | Show a contact's public key fingerprint |
+| `uam contact verify <addr>` | Manually verify a contact |
+| `uam contact remove <addr>` | Remove a contact |
+| `uam pending` | List pending handshake requests |
+| `uam approve <addr>` | Approve a handshake request |
+| `uam deny <addr>` | Deny a handshake request |
+| `uam block <pattern>` | Block an address or domain pattern |
+| `uam unblock <pattern>` | Remove a block |
+| `uam verify-domain <domain>` | Verify domain ownership (Tier 2) |
+
+## API Reference
+
+### Agent
+
+The primary SDK interface.
+
+```typescript
+const agent = new Agent("name", {
+  relay: "https://relay.youam.network",
+  trustPolicy: "auto-accept",  // or "approval-required", "require_verify"
+});
+
+await agent.connect();
+
+// Messaging
+const msgId = await agent.send(address, message);
+const messages = await agent.inbox(limit);
+
+// Trust management
+const pending = await agent.pending();
+await agent.approve(address);
+await agent.deny(address);
+await agent.block(pattern);
+await agent.unblock(pattern);
+
+// Domain verification
+await agent.verifyDomain("example.com");
+
+// Contact card
+const card = await agent.contactCard();
+
+// Properties
+agent.address;    // "name::youam.network"
+agent.publicKey;  // base64-encoded Ed25519 verify key
+agent.isConnected;
+
+await agent.close();
+```
+
+### ContactBook
+
+Local SQLite-backed contact storage with TOFU trust lifecycle.
+
+```typescript
+import { ContactBook } from "@youam/sdk";
+
+const book = new ContactBook(dataDir);
+book.open();
+
+book.isKnown(address);
+book.isBlocked(address);
+book.getPublicKey(address);
+book.getTrustState(address);
+book.listContacts();
+book.addContact(address, publicKey, { trustState: "trusted" });
+book.removeContact(address);
+book.addBlock("*::evil.com");
+book.removeBlock("*::evil.com");
+
+book.close();
+```
+
+### Protocol
+
+Low-level cryptographic operations.
+
+```typescript
+import {
+  generateKeypair,
+  createEnvelope,
+  verifyEnvelope,
+  createContactCard,
+  verifyContactCard,
+  publicKeyFingerprint,
+} from "@youam/sdk";
+```
+
+## Trust States
+
+| Indicator | State | Meaning |
+|-----------|-------|---------|
+| `(!)` | provisional | First contact, unverified |
+| `[T]` | trusted | Explicitly approved |
+| `[P]` | pinned | Key locked (TOFU) |
+| `[V]` | verified | Manually verified fingerprint |
+| `[?]` | unknown | Legacy or unresolved |
+
+## Requirements
+
+- Node.js >= 18
+- SQLite (via better-sqlite3, bundled)
+- libsodium (via libsodium-wrappers)
+
+## License
+
+MIT