Add verification types, compliance policy, X-API-Key auth (TEC-177, TEC-179, TEC-182)

README.md

@@ -34,13 +34,23 @@ const result = await client.assess("0x1234...", {
 });
 console.log(result.decision, result.decision_reasons);
 
-// Browse agents
-const agents = await client.getAgents({ chain: "base", limit: 10 });
-console.log(agents.items.length, agents.count);
+// Compliance assessment with verification policy
+const gated = await client.assess("0x1234...", {
+  policy: {
+    require_kyc: true,
+    require_sanctions_clear: true,
+    min_age: 21,
+  },
+});
+
+if (gated.decision === "deny") {
+  console.log(gated.decision_reasons); // ["kyc_required"]
+  console.log(gated.verify_url);       // URL for operator verification
+}
 
-// Ecosystem stats
-const stats = await client.getStats();
-console.log(stats.erc8004?.known_agents);
+// Check verification level on reputation
+const verified = await client.getReputation("0x1234...");
+console.log(verified.verification_level); // "none" | "wallet_claimed" | "kyc_verified"
 ```
 
 ## Configuration

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-score/sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "TypeScript client for the AgentScore trust and reputation API",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -52,6 +52,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@vitest/coverage-v8": "^4.1.2",
+    "dotenv": "^17.4.1",
     "eslint": "^9.39.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-unused-imports": "^4.4.1",

src/index.ts

@@ -2,13 +2,10 @@ import { AgentScoreError } from './errors';
 import type {
   AgentScoreConfig,
   AgentScoreErrorBody,
-  AgentsListResponse,
   AssessOptions,
   AssessResponse,
-  GetAgentsOptions,
   GetReputationOptions,
   ReputationResponse,
-  StatsResponse,
 } from './types';
 
 export { AgentScoreError } from './errors';
@@ -57,27 +54,12 @@ export class AgentScore {
     });
   }
 
-  async getAgents(options?: GetAgentsOptions): Promise<AgentsListResponse> {
-    const params = new URLSearchParams();
-    if (options) {
-      for (const [key, value] of Object.entries(options)) {
-        if (value !== undefined) params.set(key, String(value));
-      }
-    }
-    const qs = params.toString();
-    return this.request<AgentsListResponse>(`/v1/agents${qs ? `?${qs}` : ''}`);
-  }
-
-  async getStats(): Promise<StatsResponse> {
-    return this.request<StatsResponse>('/v1/stats');
-  }
-
   private async request<T>(path: string, options?: RequestInit): Promise<T> {
     const url = `${this.baseUrl}${path}`;
 
     const headers: Record<string, string> = {
       ...(options?.headers as Record<string, string>),
-      Authorization: `Bearer ${this.apiKey}`,
+      'X-API-Key': this.apiKey,
       'User-Agent': `agentscore-sdk/${__VERSION__}`,
     };
 

src/types.ts

@@ -6,7 +6,7 @@ export interface AgentScoreConfig {
 
 export type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
 export type EntityType = 'agent' | 'service' | 'hybrid' | 'wallet' | 'bot' | 'unknown';
-export type ReputationStatus = 'unknown' | 'known_unscored' | 'scored' | 'stale' | 'indexing';
+export type ReputationStatus = 'scored' | 'stale' | 'known_unscored';
 
 export interface Subject {
   chains: string[];
@@ -34,8 +34,8 @@ export interface Score {
 export interface ChainScore {
   value: number | null;
   grade: Grade | null;
-  confidence: number | null;
-  dimensions: Record<string, number> | null;
+  confidence?: number | null;
+  dimensions?: Record<string, number> | null;
   scored_at: string | null;
   status: ReputationStatus;
   version: string;
@@ -64,30 +64,14 @@ export interface Activity {
 }
 
 export interface EvidenceSummary {
-  candidate_tx_count?: number;
-  confirmed_or_likely_tx?: number;
-  endpoint_count?: number;
-  github_stars?: number | null;
-  github_url?: string | null;
-  has_a2a_agent_card?: boolean;
-  has_ens?: boolean;
-  has_github?: boolean;
-  has_website?: boolean;
-  healthy_endpoints?: number;
-  is_erc8004?: boolean;
-  metadata_kind?: string | null;
-  metadata_quality?: string | null;
-  multi_chain_count?: number;
-  reputation_feedback_count?: number;
-  reputation_trust_avg?: number | null;
-  reputation_uptime_avg?: number | null;
-  reputation_activity_avg?: number | null;
-  reputation_client_count?: number;
-  verified_tx_count?: number;
-  website_mentions_mcp?: boolean;
-  website_mentions_x402?: boolean;
-  website_reachable?: boolean;
-  website_url?: string | null;
+  metadata_kind: string | null;
+  has_a2a_agent_card: boolean;
+  website_url: string | null;
+  website_reachable: boolean;
+  website_mentions_mcp: boolean;
+  website_mentions_x402: boolean;
+  github_url: string | null;
+  github_stars: number | null;
 }
 
 export interface Reputation {
@@ -102,8 +86,8 @@ export interface Reputation {
 export interface OperatorScore {
   score: number;
   grade: Grade;
-  agent_count: number;
-  chains_active: string[];
+  agent_count?: number;
+  chains_active?: string[];
 }
 
 export interface AgentSummary {
@@ -114,13 +98,17 @@ export interface AgentSummary {
   grade: Grade;
 }
 
+export interface RedactedClassification {
+  entity_type: EntityType;
+}
+
 export interface ChainEntry {
   chain: string;
   score: ChainScore;
-  classification: Classification;
-  identity: Identity;
-  activity: Activity;
-  evidence_summary: EvidenceSummary;
+  classification: Classification | RedactedClassification;
+  identity?: Identity;
+  activity?: Activity;
+  evidence_summary?: EvidenceSummary;
 }
 
 export interface ReputationResponse {
@@ -133,12 +121,27 @@ export interface ReputationResponse {
   reputation?: Reputation;
   operator_score?: OperatorScore;
   agents?: AgentSummary[];
+  verification_level?: VerificationLevel;
+}
+
+export type VerificationLevel = 'none' | 'wallet_claimed' | 'kyc_verified';
+
+export interface OperatorVerification {
+  level: VerificationLevel;
+  operator_type?: string | null;
+  claimed_at?: string | null;
+  verified_at?: string | null;
 }
 
 export interface DecisionPolicy {
   min_grade?: Grade;
   min_score?: number;
   require_verified_payment_activity?: boolean;
+  require_kyc?: boolean;
+  require_sanctions_clear?: boolean;
+  min_age?: number;
+  blocked_jurisdictions?: string[];
+  require_entity_type?: string;
 }
 
 export interface AssessRequest {
@@ -161,60 +164,9 @@ export interface AssessResponse {
   operator_score?: OperatorScore;
   reputation?: Reputation;
   agents?: AgentSummary[];
-}
-
-export interface AgentRecord {
-  chain: string;
-  token_id: number;
-  owner_address: string;
-  agent_wallet: string | null;
-  name: string | null;
-  description: string | null;
-  metadata_quality: string;
-  score: number | null;
-  grade: Grade | null;
-  entity_type: EntityType | null;
-  endpoint_count: number;
-  website_url: string | null;
-  github_url: string | null;
-  has_candidate_payment_activity: boolean;
-  has_verified_payment_activity: boolean;
-  agents_sharing_owner?: number;
-  updated_at: string;
-}
-
-export interface AgentsListResponse {
-  items: AgentRecord[];
-  next_cursor: string | null;
-  count: number;
-  version: string;
-}
-
-export interface StatsPayments {
-  addresses_with_candidate_payment_activity: number;
-  addresses_with_verified_payment_activity: number;
-  total_candidate_transactions: number;
-  total_verified_transactions: number;
-  verification_status_summary: Record<string, number>;
-}
-
-export interface StatsResponse {
-  version: string;
-  as_of_time: string;
-  data_semantics: string;
-  erc8004?: {
-    known_agents: number;
-    by_chain: Record<string, number>;
-    metadata_quality_distribution: Record<string, number>;
-  };
-  reputation?: {
-    total_addresses: number;
-    scored_addresses: number;
-    entity_distribution: Record<string, number>;
-    score_distribution: Record<string, number>;
-  };
-  payments: StatsPayments;
-  caveats: string[];
+  operator_verification?: OperatorVerification;
+  resolved_operator?: string;
+  verify_url?: string;
 }
 
 export interface AgentScoreErrorBody {
@@ -225,20 +177,6 @@ export interface AgentScoreErrorBody {
   };
 }
 
-export interface GetAgentsOptions {
-  chain?: string;
-  limit?: number;
-  offset?: number;
-  cursor?: string;
-  metadata_quality?: string;
-  grade?: Grade;
-  min_score?: number;
-  has_endpoint?: boolean;
-  entity_type?: EntityType;
-  has_candidate_payment_activity?: boolean;
-  has_verified_payment_activity?: boolean;
-}
-
 export interface GetReputationOptions {
   chain?: string;
 }