@agnt-id/resolve 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+import type { AgntClientOptions, DiscoverOptions, DiscoverResult, DomainResult, OwnerOptions, OwnerResult, ResolveResult, ReverseResult, TrustResult } from "./types.js";
+export declare class AgntClient {
+    private gateway;
+    private chainId;
+    private _fetch;
+    constructor(options?: AgntClientOptions);
+    /**
+     * Resolve a .agnt name to its records.
+     *
+     * @param name - Full name (e.g. "alice.agnt") or label (e.g. "alice")
+     * @returns Resolved name data, or null if not found
+     */
+    resolve(name: string): Promise<ResolveResult | null>;
+    /**
+     * Reverse lookup: address to .agnt name.
+     *
+     * @param address - EVM address (0x...)
+     * @param options - Optional chain_id (CAIP-2) and verify flag
+     * @returns The primary name for that address, or null
+     */
+    reverse(address: string, options?: {
+        chainId?: string;
+        verify?: boolean;
+    }): Promise<ReverseResult | null>;
+    /**
+     * Discover agents matching search criteria.
+     */
+    discover(options?: DiscoverOptions): Promise<DiscoverResult>;
+    /**
+     * Get all names owned by an address.
+     */
+    owner(address: string, options?: OwnerOptions): Promise<OwnerResult>;
+    /**
+     * Get trust score and signals for a name.
+     */
+    trust(name: string, options?: {
+        chainId?: string;
+    }): Promise<TrustResult>;
+    /**
+     * Get domain verifications for a name.
+     */
+    domains(name: string, options?: {
+        chainId?: string;
+    }): Promise<DomainResult>;
+    /**
+     * Check if a name is available for registration.
+     */
+    available(name: string): Promise<boolean>;
+}
+export declare class AgntError extends Error {
+    status: number;
+    constructor(status: number, body: string);
+}

package/dist/client.js

@@ -0,0 +1,133 @@
+const DEFAULT_GATEWAY = "https://api.agnt.id";
+const DEFAULT_CHAIN = "eip155:1";
+export class AgntClient {
+    gateway;
+    chainId;
+    _fetch;
+    constructor(options = {}) {
+        this.gateway = (options.gateway ?? DEFAULT_GATEWAY).replace(/\/$/, "");
+        this.chainId = options.chainId ?? DEFAULT_CHAIN;
+        this._fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Resolve a .agnt name to its records.
+     *
+     * @param name - Full name (e.g. "alice.agnt") or label (e.g. "alice")
+     * @returns Resolved name data, or null if not found
+     */
+    async resolve(name) {
+        const full = ensureSuffix(name);
+        const res = await this._fetch(`${this.gateway}/v1/agnt/gateway/resolve/${encodeURIComponent(full)}`);
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Reverse lookup: address to .agnt name.
+     *
+     * @param address - EVM address (0x...)
+     * @param options - Optional chain_id (CAIP-2) and verify flag
+     * @returns The primary name for that address, or null
+     */
+    async reverse(address, options) {
+        const chain = options?.chainId ?? this.chainId;
+        const url = new URL(`${this.gateway}/v1/agnt/gateway/reverse/${chain}/${address}`);
+        if (options?.verify)
+            url.searchParams.set("verify", "true");
+        const res = await this._fetch(url.toString());
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Discover agents matching search criteria.
+     */
+    async discover(options = {}) {
+        const url = new URL(`${this.gateway}/v1/agnt/gateway/discover`);
+        url.searchParams.set("chain_id", options.chain_id ?? this.chainId);
+        if (options.q)
+            url.searchParams.set("q", options.q);
+        if (options.skill)
+            url.searchParams.set("skill", options.skill);
+        if (options.domain)
+            url.searchParams.set("domain", options.domain);
+        if (options.limit)
+            url.searchParams.set("limit", String(options.limit));
+        const res = await this._fetch(url.toString());
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Get all names owned by an address.
+     */
+    async owner(address, options = {}) {
+        const url = new URL(`${this.gateway}/v1/agnt/gateway/owner/${address}`);
+        url.searchParams.set("chain_id", options.chain_id ?? this.chainId);
+        if (options.limit)
+            url.searchParams.set("limit", String(options.limit));
+        const res = await this._fetch(url.toString());
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Get trust score and signals for a name.
+     */
+    async trust(name, options) {
+        const full = ensureSuffix(name);
+        const url = new URL(`${this.gateway}/v1/agnt/gateway/trust/${encodeURIComponent(full)}`);
+        url.searchParams.set("chain_id", options?.chainId ?? this.chainId);
+        const res = await this._fetch(url.toString());
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Get domain verifications for a name.
+     */
+    async domains(name, options) {
+        const full = ensureSuffix(name);
+        const url = new URL(`${this.gateway}/v1/agnt/gateway/domain/${encodeURIComponent(full)}`);
+        url.searchParams.set("chain_id", options?.chainId ?? this.chainId);
+        const res = await this._fetch(url.toString());
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        return res.json();
+    }
+    /**
+     * Check if a name is available for registration.
+     */
+    async available(name) {
+        const full = ensureSuffix(name);
+        const res = await this._fetch(`${this.gateway}/v1/agnt/available/${encodeURIComponent(full)}`);
+        if (!res.ok)
+            throw new AgntError(res.status, await safeText(res));
+        const data = await res.json();
+        return data.available;
+    }
+}
+export class AgntError extends Error {
+    status;
+    constructor(status, body) {
+        super(`agnt gateway ${status}: ${body}`);
+        this.name = "AgntError";
+        this.status = status;
+    }
+}
+function ensureSuffix(name) {
+    const n = name.trim().toLowerCase();
+    return n.endsWith(".agnt") ? n : `${n}.agnt`;
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "bun:test";
+import { AgntClient, AgntError } from "./client.js";
+describe("AgntClient", () => {
+    it("resolve returns null for 404", async () => {
+        const client = new AgntClient({
+            fetch: async () => new Response(null, { status: 404 }),
+        });
+        const result = await client.resolve("nonexistent");
+        expect(result).toBeNull();
+    });
+    it("resolve throws AgntError on 500", async () => {
+        const client = new AgntClient({
+            fetch: async () => new Response("internal error", { status: 500 }),
+        });
+        try {
+            await client.resolve("test");
+            expect(true).toBe(false);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(AgntError);
+            expect(err.status).toBe(500);
+        }
+    });
+    it("resolve parses gateway response", async () => {
+        const payload = {
+            name: "alice.agnt",
+            owner: "0x1234",
+            resolver: null,
+            expires_at: "2027-01-01T00:00:00Z",
+            records: { a2a: "https://alice.example.com/a2a" },
+            source: "onchain",
+        };
+        const client = new AgntClient({
+            fetch: async () => new Response(JSON.stringify(payload), { status: 200 }),
+        });
+        const result = await client.resolve("alice");
+        expect(result).toEqual(payload);
+    });
+    it("resolve appends .agnt suffix if missing", async () => {
+        let calledUrl = "";
+        const client = new AgntClient({
+            fetch: async (url) => {
+                calledUrl = url;
+                return new Response(null, { status: 404 });
+            },
+        });
+        await client.resolve("alice");
+        expect(calledUrl).toContain("alice.agnt");
+    });
+    it("available returns boolean", async () => {
+        const client = new AgntClient({
+            fetch: async () => new Response(JSON.stringify({ available: true }), { status: 200 }),
+        });
+        const result = await client.available("newname");
+        expect(result).toBe(true);
+    });
+    it("reverse returns null for 404", async () => {
+        const client = new AgntClient({
+            fetch: async () => new Response(null, { status: 404 }),
+        });
+        const result = await client.reverse("0x1234");
+        expect(result).toBeNull();
+    });
+    it("uses custom gateway URL", async () => {
+        let calledUrl = "";
+        const client = new AgntClient({
+            gateway: "https://custom.gateway.io",
+            fetch: async (url) => {
+                calledUrl = url;
+                return new Response(null, { status: 404 });
+            },
+        });
+        await client.resolve("test");
+        expect(calledUrl).toContain("custom.gateway.io");
+    });
+    it("uses custom chain ID for reverse", async () => {
+        let calledUrl = "";
+        const client = new AgntClient({
+            chainId: "eip155:8453",
+            fetch: async (url) => {
+                calledUrl = url;
+                return new Response(null, { status: 404 });
+            },
+        });
+        await client.reverse("0x1234");
+        expect(calledUrl).toContain("eip155:8453");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AgntClient, AgntError } from "./client.js";
+export type { AgntClientOptions, AgntName, AgntRecord, DiscoverEntry, DiscoverOptions, DiscoverResult, DomainEntry, DomainResult, OwnerEntry, OwnerOptions, OwnerResult, ResolveResult, ReverseResult, TrustResult, TrustScore, TrustSignal, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { AgntClient, AgntError } from "./client.js";

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+/** Record data attached to a .agnt name */
+export type AgntRecord = {
+    /** Multi-chain wallets keyed by CAIP-2 chain ID */
+    wallets?: Record<string, string>;
+    /** Default CAIP-2 chain for wallet resolution */
+    defaultWallet?: string;
+    /** Agent ID string */
+    agentId?: string;
+    /** Agent-to-Agent protocol endpoint URL */
+    a2a?: string;
+    /** Model Context Protocol endpoint URL */
+    mcp?: string;
+    /** Arbitrary key-value text records (avatar, description, etc.) */
+    texts?: Record<string, string>;
+    /** CAIP-10 identity with agent ID */
+    identity?: string;
+    /** Legacy single wallet (CAIP-10) */
+    wallet?: string;
+    /** Linked ENS name */
+    ens?: string;
+    /** Linked DID */
+    did?: string;
+    /** Trust model tags */
+    trustModels?: ("reputation" | "crypto-economic" | "tee-attestation" | "social-graph")[];
+    /** Whether the agent supports x402 payments */
+    x402Support?: boolean;
+    /** CAIP-10 address of reputation registry */
+    reputationRegistry?: string;
+    /** OASF skill slugs */
+    skills?: string[];
+    /** OASF domain slugs */
+    domains?: string[];
+    /** A2A protocol version */
+    a2aVersion?: string;
+    /** MCP protocol version (YYYY-MM-DD) */
+    mcpVersion?: string;
+    /** Profile metadata URI (ipfs: or ar:) */
+    profileURI?: string;
+};
+/** A resolved .agnt name */
+export type AgntName = {
+    name: string;
+    owner: string;
+    resolver: string | null;
+    expires_at: string | null;
+    records: AgntRecord;
+};
+/** Trust score breakdown */
+export type TrustScore = {
+    score: number;
+    baseScore: number;
+    confidence: number;
+    sampleCount: number;
+    explorationBoost: number;
+    stalePenalty: number;
+    breakdown: Record<string, number>;
+};
+/** Gateway resolve response */
+export type ResolveResult = AgntName & {
+    source: "onchain" | "cache" | "registry";
+};
+/** Gateway reverse lookup response */
+export type ReverseResult = {
+    name: string;
+    verified?: boolean;
+    source: "onchain" | "cache" | "registry";
+};
+/** A single discover/search result */
+export type DiscoverEntry = AgntName & {
+    ranking_score: number;
+    trust: TrustScore;
+    domain_verified: boolean;
+};
+/** Gateway discover response */
+export type DiscoverResult = {
+    chain_id: string;
+    results: DiscoverEntry[];
+};
+/** Gateway owner inventory entry */
+export type OwnerEntry = {
+    name: string;
+    owner: string;
+    resolver: string | null;
+    expires_at: string | null;
+    token_id: string;
+    node: string;
+};
+/** Gateway owner inventory response */
+export type OwnerResult = {
+    results: OwnerEntry[];
+    source: "onchain";
+};
+/** Trust signal from the gateway */
+export type TrustSignal = {
+    metric: string;
+    value: number;
+    value_decimals: number;
+    confidence: number;
+    source: string;
+    window_start: string | null;
+    window_end: string | null;
+    evidence_uri: string | null;
+    evidence_hash: string | null;
+    created_at: string;
+};
+/** Gateway trust response */
+export type TrustResult = {
+    chain_id: string;
+    name: string;
+    score: TrustScore;
+    signals: TrustSignal[];
+};
+/** Domain verification entry */
+export type DomainEntry = {
+    domain: string;
+    status: string;
+    method: string;
+    proof_uri: string | null;
+    proof_hash: string | null;
+    verified_by: string | null;
+    verified_at: string | null;
+    expires_at: string | null;
+    updated_at: string;
+};
+/** Gateway domain response */
+export type DomainResult = {
+    chain_id: string;
+    name: string;
+    domains: DomainEntry[];
+};
+/** Options for creating a client */
+export type AgntClientOptions = {
+    /** Gateway base URL (default: https://api.agnt.id) */
+    gateway?: string;
+    /** Default CAIP-2 chain ID (default: eip155:1) */
+    chainId?: string;
+    /** Custom fetch implementation (default: globalThis.fetch) */
+    fetch?: typeof globalThis.fetch;
+};
+/** Options for discover/search */
+export type DiscoverOptions = {
+    q?: string;
+    skill?: string;
+    domain?: string;
+    chain_id?: string;
+    limit?: number;
+};
+/** Options for owner inventory */
+export type OwnerOptions = {
+    chain_id?: string;
+    limit?: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@agnt-id/resolve",
+  "version": "0.1.0",
+  "description": "Resolve .agnt names to wallets, agent endpoints, and identity records",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": ["agnt", "agent", "naming", "web3", "ethereum", "resolve", "a2a", "mcp"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}