@truealter/sdk 0.2.4 → 0.5.0

package/README.md

@@ -5,13 +5,14 @@ ALTER Identity SDK — query the continuous identity field from any JavaScript/T
 [![npm version](https://img.shields.io/npm/v/@truealter/sdk.svg)](https://www.npmjs.com/package/@truealter/sdk)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 [![Glama score](https://glama.ai/mcp/servers/true-alter/alter-identity/badges/score.svg)](https://glama.ai/mcp/servers/true-alter/alter-identity)
+[![AI Agent Marketplace](https://www.deepnlp.org/api/ai_agent_marketplace/svg?name=truealter/alter-identity)](https://www.deepnlp.org/store/ai-agent/identity/pub-truealter/alter-identity)
 
 A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec `2025-11-25`) with x402 micropayment support, ES256 provenance verification, and config generators for Claude Code, Cursor, and generic MCP clients.
 
 - **Branded host:** `https://mcp.truealter.com` (serves `.well-known/mcp.json` for discovery)
 - **JSON-RPC wire endpoint:** `https://mcp.truealter.com/api/v1/mcp` — this is what Streamable HTTP POSTs target (the SDK default)
 - **Wire protocol:** Streamable HTTP, JSON-RPC 2.0, MCP `2025-11-25` (server negotiates `2025-06-18` + `2025-03-26` for backwards-compatible clients)
-- **Tools:** **32 typed and wired** — 24 free (L0) + 8 premium (L1–L5). Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
+- **Tools:** **40 typed and wired** — 24 free (L0) + 9 premium (L1–L5) + 7 alter-to-alter messaging. Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` / `MESSAGING_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
 - **Runtime:** Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
 - **Crypto:** `@noble/ed25519` + `@noble/hashes` (no other dependencies)
 - **Bundle:** ESM + CJS dual output
@@ -24,6 +25,38 @@ npx alter-identity init
 npx alter-identity verify ~truealter
 ```
 
+## Bridge vs SDK
+
+The `alter-mcp-bridge` binary shipped in this package (`bin/mcp-bridge.ts`)
+is a **dev/demo surface** for dropping ALTER into MCP hosts that speak the
+stdio transport (Claude Code, Cursor, Continue, Windsurf). It is useful for
+handshake, `tools/list`, and L0 tool calls, but it does not carry Q5c
+per-invocation signing — authenticated MCP tools will fail at the server
+edge when reached through the bridge. For production use, import
+`@truealter/sdk` directly and construct an `MCPClient` / `AlterClient` with
+the optional `signing` parameter; that path is the load-bearing one and
+carries the provenance envelope end-to-end. Bridge signing lands in Wave-2
+alongside the CLI wallet/consent verbs.
+
+## CLI
+
+The package ships two binaries. `alter-identity` is the full SDK-feature
+binary (`init`, `verify`, `whoami`, wire/unwire, signing, etc). `alter`
+is a slim, task-oriented binary for day-to-day use:
+
+| Command | Purpose |
+|---|---|
+| `alter login` | OAuth loopback sign-in; stores a session at `~/.config/alter/session.json` (mode `0600`). |
+| `alter depth [--json]` | GET `/api/v1/identity/depth` — identity-depth score, agentic activity, top/bottom five traits. |
+<!-- TODO(D4): "claim" is a Recognition Over Qualification violation — rename to "redeem" or "accept-invite" in alter-cli + update here -->
+| `alter claim <claim_code>` | Accept an identity invite. Prompts for email, password (min 12 chars, hidden), and explicit TOS acceptance, then POSTs `/api/v1/identity/claim`. |
+| `alter mirror` | Day-2 Mirror phase + streak. `alter mirror daily` claims today's Mirror; `alter mirror next` shows the next revelation window. |
+| `alter discover [--limit N]` | MCP-backed summary — calls `alter_whoami` and `alter_verify` against your bound handle. Degrades gracefully if the MCP endpoint is 5xx. |
+
+The session file is created with `0600` permissions; its parent dir
+(`~/.config/alter/`) is created with `0700`. Override the config root
+via `XDG_CONFIG_HOME`. Run `alter --help` for the inline reference.
+
 ## Why ALTER ≠ IAM
 
 Identity Access Management answers *who is logged in*. ALTER answers *who they actually are* — a continuous field of recognition that any IAM stack can sit on top of.
@@ -64,7 +97,7 @@ const archetypes = await alter.listArchetypes();
 
 // Identity depth and available tool tiers
 const depth = await alter.getEngagementLevel({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
 // Search by trait criteria — no PII exposed, max 5 results
@@ -90,18 +123,18 @@ const signals = await alter.assessTraits({
 
 // L2 — Full 33-trait vector ($0.01)
 const vector = await alter.getFullTraitVector({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
 // L4 — Belonging probability for a person-job pairing ($0.05)
 const belonging = await alter.computeBelonging({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
   job_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
 });
 
 // L5 — Top match recommendations ($0.50)
 const recommendations = await alter.getMatchRecommendations({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
   limit: 5,
 });
 
@@ -117,7 +150,7 @@ const narrative = await alter.generateMatchNarrative({
 // Every medium- and high-blast-radius response is signed with ES256.
 // Verification is opt-in — call alter.verifyProvenance(...) yourself.
 const result = await alter.getFullTraitVector({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
 const check = await alter.verifyProvenance(result._meta?.provenance);
@@ -151,7 +184,7 @@ const mcp = new MCPClient({ endpoint: "https://mcp.truealter.com/api/v1/mcp" });
 await mcp.initialize();
 const tools = await mcp.listTools();
 const response = await mcp.callTool("verify_identity", {
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 ```
 
@@ -237,34 +270,17 @@ ALTER monetises premium tools via the [x402](https://x402.org) standard — HTTP
 2. Server replies `402 Payment Required` with a payment requirement (amount, recipient, asset, network).
 3. Client signs and broadcasts a USDC transfer on Base L2, attaches the proof, retries.
 4. Server validates the proof, executes the tool, signs the response with ES256, returns it.
-5. The treasury splits the payment within seconds.
+5. AlterRouter executes the split on-chain in the same transaction. The data subject receives Identity Income directly; ALTER receives only its protocol cut. No custodian, no broker.
 
 The SDK handles steps 2–4 automatically when an `X402Client` with a configured `signer` is passed in.
 
 ### Tier structure
 
-| Tier | Cost     | Tools                                               |
-|------|----------|-----------------------------------------------------|
-| L1   | $0.005   | `assess_traits`, `get_trait_snapshot`               |
-| L2   | $0.01    | `get_full_trait_vector`, `get_side_quest_graph`     |
-| L3   | $0.025   | `query_graph_similarity`                            |
-| L4   | $0.05    | `compute_belonging`                                 |
-| L5   | $0.50    | `get_match_recommendations`, `generate_match_narrative` |
-
-The first **100 calls per bot are free** before x402 settlement engages — enough to evaluate the network without spending a cent.
+x402 micropayments at L0–L5 trust tiers. Per-call pricing visible after `alter login`.
 
 ### Identity income split
 
-Every settled call is split four ways:
-
-| Recipient            | Share |
-|----------------------|-------|
-| Data subject         | 75%   |
-| Facilitator agent    | 5%    |
-| ALTER (protocol)     | 15%   |
-| Cooperative treasury | 5%    |
-
-The 75% to the data subject is the foundation of *Identity Income* — humans earn from queries against their own identity field, automatically, without intermediation.
+The majority of every settled call flows to the data subject as Identity Income. Split details available post-authentication via `alter status`.
 
 ### Code example
 
@@ -301,7 +317,7 @@ const alter = new AlterClient({
 
 // Auto-retries with payment when the server returns 402
 const vector = await alter.getFullTraitVector({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 ```
 
@@ -313,7 +329,7 @@ Every response from a medium- or high-blast-radius tool ships with an ES256 JWS
 
 ```ts
 const result = await alter.getFullTraitVector({
-  candidate_id: "550e8400-e29b-41d4-a716-446655440000",
+  member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
 const check = await alter.verifyProvenance(result._meta?.provenance);
@@ -363,7 +379,7 @@ const descriptor = await discover("truealter.com");
 const httpsOnly = await discover("truealter.com", { skipDns: true });
 ```
 
-The IETF draft is being progressed through the IETF; until adoption, the cascade order may change. Pin the SDK version to a specific minor release if you depend on this behaviour.
+This draft is the author's Internet-Draft (not yet adopted by an IETF working group); until adoption, the cascade order may change. Pin the SDK version to a specific minor release if you depend on this behaviour.
 
 ## Local Daemon vs Remote MCP
 
@@ -385,12 +401,12 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 |---------------------------|------|-------|----------------------------------------------------------------------------------------------------------------------|
 | `hello_agent`             | L0   | free  | First handshake with ALTER — returns server version, authentication status, your trust tier, and available tool counts. |
 | `alter_resolve_handle`    | L0   | free  | Resolve a `~handle` (e.g. `~drew`) to its canonical form and kind. No auth required — the handle-wedge entry point.  |
-| `list_archetypes`         | L0   | free  | List all 12 ALTER identity archetypes with names, descriptions, and protective equations.                            |
+| `list_archetypes`         | L0   | free  | Returns archetype reference data.                                                                                    |
 | `verify_identity`         | L0   | free  | Verify whether a person is registered with ALTER and validate optional identity claims.                              |
 | `initiate_assessment`     | L0   | free  | Get a URL where a person can complete their ALTER Discovery assessment.                                              |
 | `get_engagement_level`    | L0   | free  | Get a person's identity depth — engagement level, data quality tier, and available query tiers.                      |
 | `get_profile`             | L0   | free  | Get a person's profile summary including assessment phase, archetype, engagement level, and key attributes.       |
-| `query_matches`           | L0   | free  | Query matches for a person. Returns a list of job matches with quality tiers (never numeric scores).              |
+| `query_matches`           | L0   | free  | Query matches for a person. Returns a list of matches with quality tiers (never numeric scores).                  |
 | `get_competencies`        | L0   | free  | Get a person's competency portfolio including verified competencies, evidence records, and earned badges.         |
 | `search_identities`       | L0   | free  | Search identity stubs and profiles by trait criteria. Returns up to 5 matches with no PII.                           |
 | `get_identity_earnings`   | L0   | free  | Get accrued Identity Income earnings for a person (75% of every x402 transaction goes to the data subject).       |
@@ -412,9 +428,9 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 
 | Name                       | Tier | Cost    | Description                                                                                                   |
 |----------------------------|------|---------|---------------------------------------------------------------------------------------------------------------|
-| `assess_traits`            | L1   | $0.005  | Extract trait signals from a text passage against ALTER's 33-trait taxonomy (first 100 free per bot).         |
+| `assess_traits`            | L1   | $0.005  | Extract trait signals from a text passage against ALTER's trait taxonomy.                                     |
 | `get_trait_snapshot`       | L1   | $0.005  | Get the top 5 traits for a person with confidence scores and archetype.                                    |
-| `get_full_trait_vector`    | L2   | $0.01   | Get the complete trait vector for a person — all 33 traits (29 continuous + 4 categorical) with scores, intervals, and category groupings. |
+| `get_full_trait_vector`    | L2   | $0.01   | Get the complete trait vector for a person — complete trait vector with scores and confidence intervals.                                    |
 | `get_side_quest_graph`     | L2   | $0.01   | Get a person's Side Quest Graph — multi-domain identity model with differential privacy noise (ε=1.0).     |
 | `query_graph_similarity`   | L3   | $0.025  | Compare two Side Quest Graphs for team composition and matching (ε=0.5 differential privacy).                 |
 | `compute_belonging`        | L4   | $0.05   | Compute belonging probability for a person-job pairing (authenticity, acceptance, complementarity).        |
@@ -428,5 +444,3 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 Apache License 2.0. See [LICENSE](./LICENSE) for the full text.
 
 Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).
-
-ALTER, the Trill (`~`), and the Golden Thread are trademarks of Alter Meridian Pty Ltd.