@agentic-trust/agentic-trust-sdk 1.0.43

package/dist/AIAgentDiscoveryClient.d.ts

@@ -0,0 +1,673 @@
+/**
+ * AI Agent Discovery Client
+ *
+ * Fronts for discovery-index GraphQL requests to the indexer
+ * Provides a clean interface for querying agent data
+ */
+import { GraphQLClient } from 'graphql-request';
+/**
+ * Agent data interface (raw data from GraphQL)
+ */
+export interface AgentData {
+    agentId?: number | string;
+    uaid?: string | null;
+    agentName?: string;
+    chainId?: number;
+    agentAccount?: string;
+    agentIdentityOwnerAccount?: string;
+    eoaAgentIdentityOwnerAccount?: string | null;
+    eoaAgentAccount?: string | null;
+    agentCategory?: string | null;
+    didIdentity?: string | null;
+    didAccount?: string | null;
+    didName?: string | null;
+    agentUri?: string | null;
+    createdAtBlock?: number;
+    createdAtTime?: string | number;
+    updatedAtTime?: string | number;
+    type?: string | null;
+    description?: string | null;
+    image?: string | null;
+    a2aEndpoint?: string | null;
+    did?: string | null;
+    mcp?: boolean | null;
+    x402support?: boolean | null;
+    active?: boolean | null;
+    supportedTrust?: string | null;
+    rawJson?: string | null;
+    onchainMetadataJson?: string | null;
+    agentCardJson?: string | null;
+    agentCardReadAt?: number | null;
+    feedbackCount?: number | null;
+    feedbackAverageScore?: number | null;
+    validationPendingCount?: number | null;
+    validationCompletedCount?: number | null;
+    validationRequestedCount?: number | null;
+    initiatedAssociationCount?: number | null;
+    approvedAssociationCount?: number | null;
+    atiOverallScore?: number | null;
+    atiOverallConfidence?: number | null;
+    atiVersion?: string | null;
+    atiComputedAt?: number | null;
+    atiBundleJson?: string | null;
+    trustLedgerScore?: number | null;
+    trustLedgerBadgeCount?: number | null;
+    trustLedgerBadges?: unknown[] | null;
+    trustLedgerOverallRank?: number | null;
+    trustLedgerCapabilityRank?: number | null;
+    identity8004Did?: string | null;
+    identity8122Did?: string | null;
+    identityEnsDid?: string | null;
+    identityHolDid?: string | null;
+    identityHolUaid?: string | null;
+    identity8004DescriptorJson?: string | null;
+    identity8122DescriptorJson?: string | null;
+    identityEnsDescriptorJson?: string | null;
+    identityHolDescriptorJson?: string | null;
+    identity8004OnchainMetadataJson?: string | null;
+    identity8122OnchainMetadataJson?: string | null;
+    identityEnsOnchainMetadataJson?: string | null;
+    identityHolOnchainMetadataJson?: string | null;
+    identity8122?: unknown | null;
+    [key: string]: unknown;
+}
+export interface SemanticAgentMetadataEntry {
+    key: string;
+    valueText?: string | null;
+}
+export interface SemanticAgentMatch {
+    score?: number | null;
+    matchReasons?: string[] | null;
+    agent: AgentData & {
+        metadata?: SemanticAgentMetadataEntry[] | null;
+    };
+}
+export interface SemanticAgentSearchResult {
+    total: number;
+    matches: SemanticAgentMatch[];
+}
+/**
+ * KB v2 GraphQL types (graphql-kb).
+ */
+export type KbDescriptor = {
+    iri: string;
+    name?: string | null;
+    description?: string | null;
+    image?: string | null;
+};
+export type KbProtocolDescriptor = {
+    iri: string;
+    name?: string | null;
+    description?: string | null;
+    image?: string | null;
+    agentCardJson?: string | null;
+};
+export type KbProtocol = {
+    iri: string;
+    protocol: string;
+    serviceUrl: string;
+    protocolVersion?: string | null;
+    descriptor?: KbProtocolDescriptor | null;
+    skills: string[];
+    domains: string[];
+};
+export type KbIdentityDescriptor = {
+    iri: string;
+    kind: string;
+    name?: string | null;
+    description?: string | null;
+    image?: string | null;
+    registrationJson?: string | null;
+    nftMetadataJson?: string | null;
+    registeredBy?: string | null;
+    registryNamespace?: string | null;
+    skills: string[];
+    domains: string[];
+};
+export type KbServiceEndpoint = {
+    iri: string;
+    name?: string | null;
+    descriptor?: KbDescriptor | null;
+    protocol?: KbProtocol | null;
+};
+export type KbIdentity = {
+    iri: string;
+    kind: string;
+    did: string;
+    uaidHOL?: string | null;
+    descriptor?: KbIdentityDescriptor | null;
+    serviceEndpoints?: KbServiceEndpoint[] | null;
+};
+export type KbIdentity8004 = {
+    iri: string;
+    kind: string;
+    did: string;
+    did8004?: string | null;
+    agentId8004?: number | null;
+    isSmartAgent?: boolean | null;
+    descriptor?: KbIdentityDescriptor | null;
+    serviceEndpoints?: KbServiceEndpoint[] | null;
+    ownerAccount?: KbAccount | null;
+    operatorAccount?: KbAccount | null;
+    walletAccount?: KbAccount | null;
+    ownerEOAAccount?: KbAccount | null;
+    agentAccount?: KbAccount | null;
+};
+export type KbIdentity8122 = {
+    iri: string;
+    kind: string;
+    did: string;
+    did8122?: string | null;
+    agentId8122?: string | null;
+    registryAddress?: string | null;
+    /**
+     * Human-friendly collection/registry name (when KB schema supports it).
+     * Note: some KB deployments may use alternate names like `collectionName`.
+     */
+    registryName?: string | null;
+    collectionName?: string | null;
+    endpointType?: string | null;
+    endpoint?: string | null;
+    descriptor?: KbIdentityDescriptor | null;
+    serviceEndpoints?: KbServiceEndpoint[] | null;
+    ownerAccount?: KbAccount | null;
+    agentAccount?: KbAccount | null;
+};
+export type KbAccount = {
+    iri: string;
+    chainId?: number | null;
+    address?: string | null;
+    accountType?: string | null;
+    didEthr?: string | null;
+};
+export type KbAssertionsSummary = {
+    reviewResponses?: {
+        total: number;
+    } | null;
+    validationResponses?: {
+        total: number;
+    } | null;
+    total?: number | null;
+};
+export type KbAgentDescriptor = {
+    iri: string;
+    name?: string | null;
+    description?: string | null;
+    image?: string | null;
+};
+export type KbAgent = {
+    iri: string;
+    uaid?: string | null;
+    agentName?: string | null;
+    agentDescription?: string | null;
+    agentImage?: string | null;
+    agentDescriptor?: KbAgentDescriptor | null;
+    agentTypes: string[];
+    did8004?: string | null;
+    agentId8004?: number | null;
+    isSmartAgent?: boolean | null;
+    createdAtBlock?: number | null;
+    createdAtTime?: number | string | null;
+    updatedAtTime?: number | string | null;
+    trustLedgerTotalPoints?: number | null;
+    trustLedgerBadgeCount?: number | null;
+    trustLedgerComputedAt?: number | null;
+    atiOverallScore?: number | null;
+    atiOverallConfidence?: number | null;
+    atiVersion?: string | null;
+    atiComputedAt?: number | null;
+    assertions?: KbAssertionsSummary | null;
+    /** Primary identity (GraphDB KB v2); prefer identity8004/identityEns when absent */
+    identity?: KbIdentity | null;
+    identity8004?: KbIdentity8004 | null;
+    identity8122?: KbIdentity8122 | null;
+    identityHol?: KbIdentity | null;
+    identityEns?: KbIdentity | null;
+    serviceEndpoints?: KbServiceEndpoint[] | null;
+};
+/**
+ * OASF taxonomy types (served by discovery GraphQL when enabled)
+ */
+export interface OasfSkill {
+    key: string;
+    nameKey?: string | null;
+    uid?: number | null;
+    caption?: string | null;
+    extendsKey?: string | null;
+    category?: string | null;
+}
+export interface OasfDomain {
+    key: string;
+    nameKey?: string | null;
+    uid?: number | null;
+    caption?: string | null;
+    extendsKey?: string | null;
+    category?: string | null;
+}
+/** Intent type from discovery GraphQL */
+export interface DiscoveryIntentType {
+    key: string;
+    label?: string | null;
+    description?: string | null;
+}
+/** Task type from discovery GraphQL */
+export interface DiscoveryTaskType {
+    key: string;
+    label?: string | null;
+    description?: string | null;
+}
+/** Intent-to-task mapping from discovery GraphQL */
+export interface DiscoveryIntentTaskMapping {
+    intent: DiscoveryIntentType;
+    task: DiscoveryTaskType;
+    requiredSkills: string[];
+    optionalSkills: string[];
+}
+/**
+ * Discovery query response types
+ */
+export interface ListAgentsResponse {
+    agents: AgentData[];
+}
+export interface GetAgentResponse {
+    agent: AgentData;
+}
+export interface GetAgentByNameResponse {
+    agentByName: AgentData | null;
+}
+export interface SearchAgentsResponse {
+    searchAgents: AgentData[];
+}
+export interface SearchAgentsAdvancedOptions {
+    query?: string;
+    params?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+export interface ValidationResponseData {
+    id?: string;
+    agentId?: string | number;
+    validatorAddress?: string;
+    requestHash?: string;
+    response?: number;
+    responseUri?: string;
+    responseJson?: string;
+    responseHash?: string;
+    tag?: string;
+    txHash?: string;
+    blockNumber?: number;
+    timestamp?: string | number;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface ValidationRequestData {
+    id?: string;
+    agentId?: string | number;
+    validatorAddress?: string;
+    requestUri?: string;
+    requestJson?: string;
+    requestHash?: string;
+    txHash?: string;
+    blockNumber?: number;
+    timestamp?: string | number;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+/** Review assertion item (was FeedbackData; renamed to align with schema review/validation) */
+export interface ReviewData {
+    id?: string;
+    agentId?: string | number;
+    clientAddress?: string;
+    score?: number;
+    feedbackUri?: string;
+    /** JSON payload; schema field is `json` */
+    reviewJson?: string;
+    comment?: string;
+    ratingPct?: number;
+    txHash?: string;
+    blockNumber?: number;
+    timestamp?: string | number;
+    isRevoked?: boolean;
+    responseCount?: number;
+    [key: string]: unknown;
+}
+/** @deprecated use ReviewData */
+export type FeedbackData = ReviewData;
+export interface SearchReviewsAdvancedOptions {
+    uaid: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+/** @deprecated use SearchReviewsAdvancedOptions with uaid (build uaid from did:8004:chainId:agentId) */
+export interface SearchFeedbackAdvancedOptions {
+    uaid?: string;
+    chainId?: number;
+    agentId?: string | number;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+export interface SearchValidationRequestsAdvancedOptions {
+    uaid: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+export interface RefreshAgentResponse {
+    indexAgent: {
+        success: boolean;
+        message: string;
+        processedChains: number[];
+    };
+}
+/**
+ * Configuration for AIAgentDiscoveryClient
+ */
+export interface AIAgentDiscoveryClientConfig {
+    /**
+     * GraphQL endpoint URL
+     */
+    endpoint: string;
+    /**
+     * Optional API key for authentication
+     */
+    apiKey?: string;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Additional headers to include in requests
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * AI Agent Discovery Client
+ *
+ * Provides methods for querying agent data from the indexer
+ */
+export declare class AIAgentDiscoveryClient {
+    private client;
+    private config;
+    private searchStrategy?;
+    private searchStrategyPromise?;
+    private typeFieldsCache;
+    private enumValuesCache;
+    private tokenMetadataCollectionSupported?;
+    private agentMetadataValueField?;
+    private queryFieldsCache?;
+    private queryFieldsPromise?;
+    private kbV2SupportCache?;
+    private kbV2SupportPromise?;
+    constructor(config: AIAgentDiscoveryClientConfig);
+    private extractOperationName;
+    private decorateGraphqlError;
+    private gqlRequest;
+    private getQueryFields;
+    private getEnumValues;
+    private pickKbAgentOrderBy;
+    private buildKbIdentityAndAccountsSelectionBase;
+    private hasQueryField;
+    private supportsKbV2Queries;
+    /**
+     * Map a KB v2 agent node into the legacy AgentData shape used across the monorepo.
+     */
+    private mapKbAgentToAgentData;
+    private kbAgentSelectionCache;
+    private kbAgentSelectionPromise;
+    private getKbAgentSelection;
+    private supportsQueryField;
+    private normalizeAgent;
+    /**
+     * List agents with a deterministic default ordering (agentId DESC).
+     *
+     * @param limit - Maximum number of agents to return per page
+     * @param offset - Number of agents to skip
+     * @returns List of agents
+     */
+    listAgents(limit?: number, offset?: number): Promise<AgentData[]>;
+    /**
+     * Run a semantic search over agents using the discovery indexer's
+     * `semanticAgentSearch` GraphQL field.
+     *
+     * NOTE: This expects the KB GraphQL schema. If the backend does not expose
+     * `kbSemanticAgentSearch`, it will throw.
+     */
+    semanticAgentSearch(params: {
+        text?: string;
+        intentJson?: string;
+        topK?: number;
+        requiredSkills?: string[];
+        intentType?: string;
+    }): Promise<SemanticAgentSearchResult>;
+    /**
+     * Fetch OASF skills taxonomy from the discovery GraphQL endpoint (best-effort).
+     * Returns [] if the backend does not expose `oasfSkills`.
+     */
+    oasfSkills(params?: {
+        key?: string;
+        nameKey?: string;
+        category?: string;
+        extendsKey?: string;
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        orderDirection?: string;
+    }): Promise<OasfSkill[]>;
+    /**
+     * Fetch OASF domains taxonomy from the discovery GraphQL endpoint (best-effort).
+     * Returns [] if the backend does not expose `oasfDomains`.
+     */
+    oasfDomains(params?: {
+        key?: string;
+        nameKey?: string;
+        category?: string;
+        extendsKey?: string;
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        orderDirection?: string;
+    }): Promise<OasfDomain[]>;
+    /**
+     * Fetch intent types from the discovery GraphQL endpoint (best-effort).
+     * Returns [] if the backend does not expose `intentTypes`.
+     */
+    intentTypes(params?: {
+        key?: string;
+        label?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<DiscoveryIntentType[]>;
+    /**
+     * Fetch task types from the discovery GraphQL endpoint (best-effort).
+     * Returns [] if the backend does not expose `taskTypes`.
+     */
+    taskTypes(params?: {
+        key?: string;
+        label?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<DiscoveryTaskType[]>;
+    /**
+     * Fetch intent-task mappings from the discovery GraphQL endpoint (best-effort).
+     * Returns [] if the backend does not expose `intentTaskMappings`.
+     */
+    intentTaskMappings(params?: {
+        intentKey?: string;
+        taskKey?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<DiscoveryIntentTaskMapping[]>;
+    searchAgentsAdvanced(options: SearchAgentsAdvancedOptions): Promise<{
+        agents: AgentData[];
+        total?: number | null;
+    } | null>;
+    /**
+     * Search agents using the strongly-typed AgentWhereInput / searchAgentsGraph API.
+     * This is tailored to the indexer schema that exposes AgentWhereInput and
+     * searchAgentsGraph(where:, first:, skip:, orderBy:, orderDirection:).
+     */
+    searchAgentsGraph(options: {
+        where?: Record<string, unknown>;
+        first?: number;
+        skip?: number;
+        orderBy?: 'agentId' | 'agentName' | 'createdAtTime' | 'createdAtBlock' | 'agentIdentityOwnerAccount' | 'eoaAgentIdentityOwnerAccount' | 'eoaAgentAccount' | 'agentCategory' | 'trustLedgerScore' | 'trustLedgerBadgeCount' | 'trustLedgerOverallRank' | 'trustLedgerCapabilityRank';
+        orderDirection?: 'ASC' | 'DESC';
+    }): Promise<{
+        agents: AgentData[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    erc8122Registries(params: {
+        chainId: number;
+        first?: number;
+        skip?: number;
+    }): Promise<Array<{
+        iri?: string | null;
+        chainId: number;
+        registryAddress: string;
+        registrarAddress?: string | null;
+        registryName?: string | null;
+        registryImplementationAddress?: string | null;
+        registrarImplementationAddress?: string | null;
+        registeredAgentCount?: number | null;
+        lastAgentUpdatedAtTime?: number | null;
+    }>>;
+    private detectSearchStrategy;
+    private buildStrategyFromField;
+    private getTypeFields;
+    /**
+     * Some indexers expose `metadata { key valueText }`, others expose `metadata { key value }`.
+     * Introspect once and cache so we can query metadata reliably.
+     */
+    private getAgentMetadataValueField;
+    /**
+     * Get all token metadata from The Graph indexer for an agent
+     * Uses agentMetadata_collection (The Graph subgraph) or agentMetadata (custom schema) query
+     * to get all metadata key-value pairs. Tries subgraph format first, falls back to custom schema.
+     * Handles pagination if an agent has more than 1000 metadata entries
+     * @param chainId - Chain ID
+     * @param agentId - Agent ID
+     * @returns Record of all metadata key-value pairs, or null if not available
+     */
+    /**
+     * @deprecated Use getAllAgentMetadata instead. This method name is misleading.
+     */
+    getTokenMetadata(chainId: number, agentId: number | string): Promise<Record<string, string> | null>;
+    /**
+     * Get all agent metadata entries from the discovery GraphQL backend.
+     * Uses agentMetadata_collection (The Graph subgraph) or agentMetadata (custom schema) query.
+     * Tries subgraph format first, falls back to custom schema.
+     * Handles pagination if an agent has more than 1000 metadata entries.
+     * @param chainId - Chain ID
+     * @param agentId - Agent ID
+     * @returns Record of all metadata key-value pairs, or null if not available
+     */
+    getAllAgentMetadata(chainId: number, agentId: number | string): Promise<Record<string, string> | null>;
+    /**
+     * Fallback method: Uses agentMetadata query (custom schema format) to get all metadata key-value pairs
+     * @param chainId - Chain ID
+     * @param agentId - Agent ID
+     * @returns Record of all metadata key-value pairs, or null if not available
+     */
+    private getTokenMetadataCustomSchema;
+    /**
+     * Get a single agent by chainId+agentId (convenience).
+     * Discovery is UAID-only: builds uaid and calls getAgentByUaid(uaid).
+     */
+    getAgent(chainId: number, agentId: number | string): Promise<AgentData | null>;
+    getAgentByName(agentName: string): Promise<AgentData | null>;
+    /**
+     * Resolve a single agent by UAID (KB v2). UAID-only; no fallback to chainId/agentId.
+     */
+    getAgentByUaid(uaid: string): Promise<AgentData | null>;
+    /**
+     * Resolve a single agent by UAID including identity/accounts (KB v2). UAID-only; no fallback.
+     */
+    getAgentByUaidFull(uaid: string): Promise<AgentData | null>;
+    /**
+     * Search agents by name
+     * @param searchTerm - Search term to match against agent names
+     * @param limit - Maximum number of results
+     * @returns List of matching agents
+     */
+    searchAgents(searchTerm: string, limit?: number): Promise<AgentData[]>;
+    /**
+     * Refresh/Index an agent in the indexer
+     * Triggers the indexer to re-index the specified agent
+     * @param agentId - Agent ID to refresh (required)
+     * @param chainId - Optional chain ID (if not provided, indexer may use default)
+     * @param apiKey - Optional API key override (uses config API key if not provided)
+     * @returns Refresh result with success status and processed chains
+     */
+    refreshAgent(agentId: string | number, chainId?: number, apiKey?: string): Promise<RefreshAgentResponse['indexAgent']>;
+    /**
+     * Normalize identifier to UAID form required by KB GraphQL.
+     *
+     * Important: kbAgentByUaid expects the *canonical UAID key* (prefix up to the first ';').
+     * Any routing metadata after ';' is not part of the lookup key.
+     */
+    private normalizeUaidForKb;
+    /**
+     * Search validation requests for an agent by UAID (GraphQL kbAgentByUaid + validationAssertions)
+     */
+    searchValidationRequestsAdvanced(options: SearchValidationRequestsAdvancedOptions): Promise<{
+        validationRequests: ValidationRequestData[];
+    } | null>;
+    /**
+     * Search reviews for an agent by UAID (GraphQL kbAgentByUaid + reviewAssertions)
+     */
+    searchReviewsAdvanced(options: SearchReviewsAdvancedOptions): Promise<{
+        reviews: ReviewData[];
+    } | null>;
+    /**
+     * Search feedback/reviews for an agent (UAID or legacy chainId+agentId). Prefer searchReviewsAdvanced(uaid).
+     */
+    searchFeedbackAdvanced(options: SearchFeedbackAdvancedOptions): Promise<{
+        feedbacks: FeedbackData[];
+    } | null>;
+    /**
+     * Execute a raw GraphQL query
+     * @param query - GraphQL query string
+     * @param variables - Query variables
+     * @returns Query response
+     */
+    request<T = any>(query: string, variables?: Record<string, any>): Promise<T>;
+    /**
+     * Execute a raw GraphQL mutation
+     * @param mutation - GraphQL mutation string
+     * @param variables - Mutation variables
+     * @returns Mutation response
+     */
+    mutate<T = any>(mutation: string, variables?: Record<string, any>): Promise<T>;
+    /**
+     * Get the underlying GraphQLClient instance
+     * @returns The GraphQLClient instance
+     */
+    getClient(): GraphQLClient;
+    /**
+     * Get agents owned by a specific EOA address
+     * @param eoaAddress - The EOA (Externally Owned Account) address to search for
+     * @param options - Optional search options (limit, offset, orderBy, orderDirection)
+     * @returns List of agents owned by the EOA address
+     */
+    getOwnedAgents(eoaAddress: string, options?: {
+        limit?: number;
+        offset?: number;
+        orderBy?: 'agentId' | 'agentName' | 'createdAtTime' | 'createdAtBlock' | 'agentIdentityOwnerAccount' | 'eoaAgentIdentityOwnerAccount' | 'eoaAgentAccount' | 'agentCategory' | 'trustLedgerScore' | 'trustLedgerBadgeCount' | 'trustLedgerOverallRank' | 'trustLedgerCapabilityRank';
+        orderDirection?: 'ASC' | 'DESC';
+    }): Promise<AgentData[]>;
+    /**
+     * UAID-native ownership check (KB v2).
+     */
+    isOwnerByUaid(uaid: string, walletAddress: string): Promise<boolean>;
+}
+//# sourceMappingURL=AIAgentDiscoveryClient.d.ts.map