@tacitprotocol/sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,158 @@
+# @tacitprotocol/sdk
+
+The TypeScript SDK for the **Tacit Protocol** — verify identity, prevent fraud, and broker trusted introductions with cryptographic proof.
+
+[![npm](https://img.shields.io/npm/v/@tacitprotocol/sdk?color=blue)](https://www.npmjs.com/package/@tacitprotocol/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/tacitprotocol/tacit/blob/main/LICENSE)
+
+## Install
+
+```bash
+npm install @tacitprotocol/sdk
+```
+
+## Quick Start
+
+```typescript
+import { TacitAgent } from '@tacitprotocol/sdk';
+
+// Create an agent with a fresh DID identity
+const agent = await TacitAgent.create({
+  domain: 'professional',
+  preferences: {
+    languages: ['en'],
+    introductionStyle: 'professional',
+  },
+});
+
+// Publish an intent to the network
+await agent.publishIntent({
+  type: 'introduction',
+  domain: 'professional',
+  seeking: {
+    role: 'co-founder',
+    skills: ['backend', 'systems-architecture'],
+    industry: 'fintech',
+  },
+  context: {
+    offering: 'product leadership, 10 years in payments',
+    stage: 'pre-seed',
+  },
+});
+
+// Listen for verified matches
+agent.on('match', async (event) => {
+  const { match } = event;
+  console.log(`Match: ${match.score.overall}/100`);
+  console.log(`Authenticity: ${match.score.breakdown.authenticityCompatibility}`);
+});
+
+// Connect to the relay network
+await agent.connect();
+```
+
+## Core Modules
+
+### Identity (`createIdentity`, `sign`, `verify`)
+
+W3C DID-based identity using Ed25519 keypairs. Every agent gets a `did:key` identifier that is cryptographically verifiable.
+
+```typescript
+import { createIdentity, sign, verify } from '@tacitprotocol/sdk';
+
+const identity = await createIdentity();
+console.log(identity.did); // did:key:z6Mk...
+
+const data = new TextEncoder().encode('hello');
+const signature = await sign(data, identity.privateKey);
+const valid = await verify(data, signature, identity.publicKey);
+```
+
+### Authenticity (`AuthenticityEngine`)
+
+Multi-dimensional trust scores that are earned over time — impossible to fake overnight. Dimensions: tenure, consistency, attestations, network trust.
+
+```typescript
+import { AuthenticityEngine } from '@tacitprotocol/sdk';
+
+const engine = new AuthenticityEngine();
+const vector = engine.computeVector({
+  created: agent.card.agent.created,
+  consistencySignals: { intentFulfillmentRate: 0.9, responseRate: 0.85 },
+  credentials: agent.card.credentials,
+  networkTrust: { endorsements: 12, uniqueEndorsers: 8, mutualConnections: 3 },
+});
+console.log(vector.score); // 0-100
+```
+
+### Discovery (`IntentBuilder`, `IntentStore`)
+
+Publish and discover encrypted intents on the network. The `IntentBuilder` provides a fluent API for constructing intents.
+
+```typescript
+import { IntentBuilder, IntentStore } from '@tacitprotocol/sdk';
+
+const intent = new IntentBuilder(agent.did)
+  .type('introduction')
+  .domain('professional')
+  .seeking({ role: 'backend-engineer', skills: ['rust', 'distributed-systems'] })
+  .context({ offering: 'equity + salary', stage: 'seed' })
+  .minAuthenticity(70)
+  .ttl(86400) // 24 hours
+  .build();
+
+const store = new IntentStore();
+store.add(intent);
+const matches = store.query({ domain: 'professional', keywords: ['rust'] });
+```
+
+### Matching (`MatchScorer`)
+
+Score compatibility between two agents across five dimensions: intent alignment, domain fit, authenticity compatibility, preference match, and timing fit.
+
+```typescript
+import { MatchScorer } from '@tacitprotocol/sdk';
+
+const scorer = new MatchScorer({ autoPropose: 80, suggest: 60 });
+const result = scorer.score({
+  initiator: { intent: aliceIntent, card: aliceCard },
+  responder: { intent: bobIntent, card: bobCard },
+});
+
+console.log(result.score.overall);           // 0-100
+console.log(scorer.determineAction(result.score.overall)); // 'auto-propose' | 'suggest' | 'ignore'
+```
+
+## API Reference
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `TacitAgent` | Class | Main agent interface — identity, intents, matching, events |
+| `createIdentity` | Function | Generate a new Ed25519 DID identity |
+| `publicKeyToDid` | Function | Convert a public key to a `did:key` DID |
+| `resolveDid` | Function | Resolve a DID to its public key |
+| `sign` / `verify` | Functions | Ed25519 signing and verification |
+| `AuthenticityEngine` | Class | Compute multi-dimensional trust scores |
+| `IntentBuilder` | Class | Fluent builder for constructing intents |
+| `IntentStore` | Class | Local intent storage with lifecycle management |
+| `MatchScorer` | Class | Score compatibility between two agents |
+
+All types are fully exported — see the [type definitions](https://github.com/tacitprotocol/tacit/blob/main/packages/sdk-ts/src/types/index.ts) for the complete schema.
+
+## Requirements
+
+- Node.js >= 18.0.0 (Web Crypto API required)
+- TypeScript >= 5.0 (recommended)
+
+## Links
+
+- [Protocol Spec](https://github.com/tacitprotocol/tacit/blob/main/docs/PROTOCOL_SPEC.md)
+- [Whitepaper](https://github.com/tacitprotocol/tacit/blob/main/docs/WHITEPAPER.md)
+- [GitHub](https://github.com/tacitprotocol/tacit)
+- [Website](https://tacitprotocol.com)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -176,6 +176,9 @@ type TacitEvent = {
 } | {
     type: 'intent:matched';
     match: MatchResult;
+} | {
+    type: 'match';
+    match: MatchResult;
 } | {
     type: 'intent:expired';
     intentId: string;
@@ -253,10 +256,26 @@ declare class TacitAgent {
      * Returns an AgentIdentity that can be passed to the constructor.
      */
     static createIdentity(): Promise<AgentIdentity>;
+    /**
+     * Convenience factory: creates a new identity and returns a ready-to-use agent.
+     */
+    static create(options?: {
+        domain?: DomainType;
+        preferences?: Record<string, any>;
+        seeking?: string;
+        offering?: string;
+    }): Promise<TacitAgent>;
+    /** Get the agent's DID (shorthand). */
+    get did(): string;
+    /** Get the agent's Agent Card (shorthand). */
+    get card(): AgentCard;
     /**
      * Connect the agent to the Tacit network via a relay node.
+     * Pass `{ demo: true }` to simulate a match after 3 seconds (no relay needed).
      */
-    connect(): Promise<void>;
+    connect(options?: {
+        demo?: boolean;
+    }): Promise<void>;
     /**
      * Disconnect the agent from the network.
      * Active intents remain on the network until their TTL expires.

package/dist/index.d.ts

@@ -176,6 +176,9 @@ type TacitEvent = {
 } | {
     type: 'intent:matched';
     match: MatchResult;
+} | {
+    type: 'match';
+    match: MatchResult;
 } | {
     type: 'intent:expired';
     intentId: string;
@@ -253,10 +256,26 @@ declare class TacitAgent {
      * Returns an AgentIdentity that can be passed to the constructor.
      */
     static createIdentity(): Promise<AgentIdentity>;
+    /**
+     * Convenience factory: creates a new identity and returns a ready-to-use agent.
+     */
+    static create(options?: {
+        domain?: DomainType;
+        preferences?: Record<string, any>;
+        seeking?: string;
+        offering?: string;
+    }): Promise<TacitAgent>;
+    /** Get the agent's DID (shorthand). */
+    get did(): string;
+    /** Get the agent's Agent Card (shorthand). */
+    get card(): AgentCard;
     /**
      * Connect the agent to the Tacit network via a relay node.
+     * Pass `{ demo: true }` to simulate a match after 3 seconds (no relay needed).
      */
-    connect(): Promise<void>;
+    connect(options?: {
+        demo?: boolean;
+    }): Promise<void>;
     /**
      * Disconnect the agent from the network.
      * Active intents remain on the network until their TTL expires.

package/dist/index.js

@@ -340,7 +340,7 @@ var EventBus = class {
     }
   }
 };
-var TacitAgent = class {
+var TacitAgent = class _TacitAgent {
   identity = null;
   config;
   events = new EventBus();
@@ -367,7 +367,7 @@ var TacitAgent = class {
       this.identity = config.identity;
     }
   }
-  // ─── Static Factory ───────────────────────────────────────────
+  // ─── Static Factories ──────────────────────────────────────────
   /**
    * Create a new agent identity.
    * Returns an AgentIdentity that can be passed to the constructor.
@@ -375,11 +375,37 @@ var TacitAgent = class {
   static async createIdentity() {
     return createIdentity();
   }
+  /**
+   * Convenience factory: creates a new identity and returns a ready-to-use agent.
+   */
+  static async create(options = {}) {
+    const identity = await _TacitAgent.createIdentity();
+    return new _TacitAgent({
+      identity,
+      profile: {
+        name: "Tacit Agent",
+        domain: options.domain || "professional",
+        seeking: options.seeking || "",
+        offering: options.offering || ""
+      },
+      preferences: options.preferences
+    });
+  }
+  // ─── Convenience Getters ─────────────────────────────────────
+  /** Get the agent's DID (shorthand). */
+  get did() {
+    return this.getDid();
+  }
+  /** Get the agent's Agent Card (shorthand). */
+  get card() {
+    return this.getAgentCard();
+  }
   // ─── Lifecycle ────────────────────────────────────────────────
   /**
    * Connect the agent to the Tacit network via a relay node.
+   * Pass `{ demo: true }` to simulate a match after 3 seconds (no relay needed).
    */
-  async connect() {
+  async connect(options) {
     if (!this.identity) {
       this.identity = await createIdentity();
     }
@@ -388,6 +414,31 @@ var TacitAgent = class {
       type: "connection:established",
       endpoint: this.config.relayUrl
     });
+    if (options?.demo) {
+      setTimeout(async () => {
+        const simulatedMatch = {
+          matchId: `match:demo:${Date.now()}`,
+          agents: {
+            initiator: this.identity.did,
+            responder: "did:key:z6MkdemoAgent00000000000000000000000000000000"
+          },
+          score: {
+            overall: 87,
+            breakdown: {
+              intentAlignment: 0.92,
+              domainFit: 0.88,
+              authenticityCompatibility: 0.85,
+              preferenceMatch: 0.82,
+              timingFit: 0.9
+            }
+          },
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.events.emit({ type: "match", match: simulatedMatch });
+      }, 3e3);
+      await new Promise(() => {
+      });
+    }
   }
   /**
    * Disconnect the agent from the network.

package/dist/index.mjs

@@ -305,7 +305,7 @@ var EventBus = class {
     }
   }
 };
-var TacitAgent = class {
+var TacitAgent = class _TacitAgent {
   identity = null;
   config;
   events = new EventBus();
@@ -332,7 +332,7 @@ var TacitAgent = class {
       this.identity = config.identity;
     }
   }
-  // ─── Static Factory ───────────────────────────────────────────
+  // ─── Static Factories ──────────────────────────────────────────
   /**
    * Create a new agent identity.
    * Returns an AgentIdentity that can be passed to the constructor.
@@ -340,11 +340,37 @@ var TacitAgent = class {
   static async createIdentity() {
     return createIdentity();
   }
+  /**
+   * Convenience factory: creates a new identity and returns a ready-to-use agent.
+   */
+  static async create(options = {}) {
+    const identity = await _TacitAgent.createIdentity();
+    return new _TacitAgent({
+      identity,
+      profile: {
+        name: "Tacit Agent",
+        domain: options.domain || "professional",
+        seeking: options.seeking || "",
+        offering: options.offering || ""
+      },
+      preferences: options.preferences
+    });
+  }
+  // ─── Convenience Getters ─────────────────────────────────────
+  /** Get the agent's DID (shorthand). */
+  get did() {
+    return this.getDid();
+  }
+  /** Get the agent's Agent Card (shorthand). */
+  get card() {
+    return this.getAgentCard();
+  }
   // ─── Lifecycle ────────────────────────────────────────────────
   /**
    * Connect the agent to the Tacit network via a relay node.
+   * Pass `{ demo: true }` to simulate a match after 3 seconds (no relay needed).
    */
-  async connect() {
+  async connect(options) {
     if (!this.identity) {
       this.identity = await createIdentity();
     }
@@ -353,6 +379,31 @@ var TacitAgent = class {
       type: "connection:established",
       endpoint: this.config.relayUrl
     });
+    if (options?.demo) {
+      setTimeout(async () => {
+        const simulatedMatch = {
+          matchId: `match:demo:${Date.now()}`,
+          agents: {
+            initiator: this.identity.did,
+            responder: "did:key:z6MkdemoAgent00000000000000000000000000000000"
+          },
+          score: {
+            overall: 87,
+            breakdown: {
+              intentAlignment: 0.92,
+              domainFit: 0.88,
+              authenticityCompatibility: 0.85,
+              preferenceMatch: 0.82,
+              timingFit: 0.9
+            }
+          },
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.events.emit({ type: "match", match: simulatedMatch });
+      }, 3e3);
+      await new Promise(() => {
+      });
+    }
   }
   /**
    * Disconnect the agent from the network.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacitprotocol/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The Tacit Protocol SDK — verify identity, prevent fraud, and broker trusted introductions with cryptographic proof",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/agent.ts

@@ -91,7 +91,7 @@ export class TacitAgent {
     }
   }
 
-  // ─── Static Factory ───────────────────────────────────────────
+  // ─── Static Factories ──────────────────────────────────────────
 
   /**
    * Create a new agent identity.
@@ -101,12 +101,47 @@ export class TacitAgent {
     return createIdentity();
   }
 
+  /**
+   * Convenience factory: creates a new identity and returns a ready-to-use agent.
+   */
+  static async create(options: {
+    domain?: DomainType;
+    preferences?: Record<string, any>;
+    seeking?: string;
+    offering?: string;
+  } = {}): Promise<TacitAgent> {
+    const identity = await TacitAgent.createIdentity();
+    return new TacitAgent({
+      identity,
+      profile: {
+        name: 'Tacit Agent',
+        domain: options.domain || 'professional',
+        seeking: options.seeking || '',
+        offering: options.offering || '',
+      },
+      preferences: options.preferences as any,
+    });
+  }
+
+  // ─── Convenience Getters ─────────────────────────────────────
+
+  /** Get the agent's DID (shorthand). */
+  get did(): string {
+    return this.getDid();
+  }
+
+  /** Get the agent's Agent Card (shorthand). */
+  get card(): AgentCard {
+    return this.getAgentCard();
+  }
+
   // ─── Lifecycle ────────────────────────────────────────────────
 
   /**
    * Connect the agent to the Tacit network via a relay node.
+   * Pass `{ demo: true }` to simulate a match after 3 seconds (no relay needed).
    */
-  async connect(): Promise<void> {
+  async connect(options?: { demo?: boolean }): Promise<void> {
     if (!this.identity) {
       this.identity = await createIdentity();
     }
@@ -121,6 +156,34 @@ export class TacitAgent {
       type: 'connection:established',
       endpoint: this.config.relayUrl!,
     });
+
+    // Demo mode: simulate a match after 3 seconds
+    if (options?.demo) {
+      setTimeout(async () => {
+        const simulatedMatch: MatchResult = {
+          matchId: `match:demo:${Date.now()}`,
+          agents: {
+            initiator: this.identity!.did,
+            responder: 'did:key:z6MkdemoAgent00000000000000000000000000000000' as any,
+          },
+          score: {
+            overall: 87,
+            breakdown: {
+              intentAlignment: 0.92,
+              domainFit: 0.88,
+              authenticityCompatibility: 0.85,
+              preferenceMatch: 0.82,
+              timingFit: 0.90,
+            },
+          },
+          timestamp: new Date().toISOString(),
+        };
+        await this.events.emit({ type: 'match', match: simulatedMatch });
+      }, 3000);
+
+      // Keep the process alive
+      await new Promise(() => {});
+    }
   }
 
   /**

package/src/types/index.ts

@@ -248,6 +248,7 @@ export interface ServiceAttestation {
 export type TacitEvent =
   | { type: 'intent:published'; intent: Intent }
   | { type: 'intent:matched'; match: MatchResult }
+  | { type: 'match'; match: MatchResult }
   | { type: 'intent:expired'; intentId: string }
   | { type: 'proposal:received'; proposal: IntroProposal }
   | { type: 'proposal:accepted'; proposal: IntroProposal }