@threnn/acap-sdk 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,293 @@
+import { AttestationRun, CapabilityCertificate, VerificationResult, NutritionLabel, RegistryListing, BenchmarkSuite, CapabilityDriftEvent, NistExport, OpenBadgeCredential, AgentAdapter, RunProgress } from '@threnn/acap-core';
+export { AgentAdapter, AgentMetadata, AgentResponse, AttestationRun, BenchmarkSuite, CapabilityCertificate, CapabilityDriftEvent, ComparisonResult, DimensionScore, DriftSummary, InteroperabilityLevel, NistExport, NutritionLabel, OpenBadgeCredential, RegistryListing, RegistrySearchParams, RegistrySearchResult, RunProgress, TaskResult, VerificationResult } from '@threnn/acap-core';
+
+/**
+ * SDK-specific types for the ACAP client.
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface ListCertificatesOptions {
+    agentId?: string;
+    domain?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface SearchRegistryOptions {
+    domain?: string;
+    minScore?: number;
+    maxScore?: number;
+    tier?: string;
+    query?: string;
+    sortBy?: 'score' | 'recent' | 'name';
+    page?: number;
+    pageSize?: number;
+}
+interface ListSuitesOptions {
+    domain?: string;
+    isPublic?: boolean;
+}
+interface LeaderboardEntry {
+    rank: number;
+    id: string;
+    certificate_id: string;
+    agent_name: string;
+    agent_description: string;
+    overall_score: number;
+    capability_tier: string;
+    listed_at: string;
+}
+/** Options for starting an attestation run */
+interface StartAttestationOptions {
+    /** Agent identifier */
+    agentId: string;
+    /** Benchmark suite ID (UUID) */
+    suiteId: string;
+    /** Agent's HTTP endpoint URL */
+    agentEndpoint: string;
+    /** API key for authenticating with the agent (optional) */
+    agentApiKey?: string;
+    /** Adapter type (default: 'http') */
+    agentAdapter?: 'http' | 'anthropic' | 'openai' | 'mcp';
+    /** Model ID for Anthropic/OpenAI adapters */
+    agentModel?: string;
+    /** System prompt for the agent (optional) */
+    agentSystemPrompt?: string;
+    /** MCP tool name (required if agentAdapter='mcp') */
+    mcpToolName?: string;
+    /** Agent metadata overrides */
+    agentMetadata?: {
+        modelProvider?: string;
+        modelVersion?: string;
+        temperature?: number;
+    };
+    /** Max parallel tasks (1-10, default: 1) */
+    concurrency?: number;
+    /** Per-task timeout in ms (1000-300000, default: 30000) */
+    timeout_ms?: number;
+}
+interface ListRunsOptions {
+    agentId?: string;
+    suiteId?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface ListDriftOptions {
+    agentId?: string;
+    severity?: string;
+    acknowledged?: boolean;
+    page?: number;
+    pageSize?: number;
+}
+interface AcknowledgeDriftResult {
+    success: boolean;
+    acknowledged: number;
+}
+/** Result from a completed attestation */
+interface AttestationResult {
+    id: string;
+    status: string;
+    agentId: string;
+    benchmarkSuiteId: string;
+    certificateId?: string;
+    overallScore?: number;
+    capabilityTier?: string;
+    duration_ms?: number;
+    taskProgress?: {
+        totalTasks: number;
+        completedTasks: number;
+        passedTasks: number;
+        failedTasks: number;
+    };
+    certificate?: unknown;
+    error?: string;
+}
+
+/**
+ * ACAP SDK Client — submit attestations, query certificates, search the registry.
+ */
+
+interface ACAPClientConfig {
+    /** Base URL of the ACAP API (e.g., 'https://app.threnn.ai') */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Custom fetch implementation (defaults to global fetch) */
+    fetch?: typeof globalThis.fetch;
+}
+declare class ACAPClient {
+    private baseUrl;
+    private apiKey;
+    private fetchFn;
+    constructor(config: ACAPClientConfig);
+    private headers;
+    private get;
+    private post;
+    private put;
+    private del;
+    private patch;
+    private handleResponse;
+    /**
+     * Start an attestation run — executes the benchmark and returns the result with certificate.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.startAttestation({
+     *   agentId: 'my-agent',
+     *   suiteId: 'suite-uuid',
+     *   agentEndpoint: 'https://my-agent.example.com/api/chat',
+     *   agentAdapter: 'http',
+     * });
+     * console.log(result.certificate); // Signed CapabilityCertificate
+     * ```
+     */
+    startAttestation(opts: StartAttestationOptions): Promise<AttestationResult>;
+    /** Get the status of an attestation run */
+    getAttestationStatus(runId: string): Promise<AttestationRun>;
+    /** Cancel a running attestation */
+    cancelAttestation(runId: string): Promise<void>;
+    /** List attestation runs with optional filters */
+    listRuns(opts?: ListRunsOptions): Promise<PaginatedResult<AttestationRun>>;
+    /** Get a certificate by ID */
+    getCertificate(id: string): Promise<CapabilityCertificate>;
+    /** List certificates with optional filters */
+    listCertificates(opts?: ListCertificatesOptions): Promise<PaginatedResult<CapabilityCertificate>>;
+    /** Get certificates for a specific agent */
+    getCertificatesForAgent(agentId: string, opts?: {
+        domain?: string;
+        status?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResult<CapabilityCertificate>>;
+    /** Verify a certificate's integrity and validity */
+    verifyCertificate(id: string): Promise<VerificationResult>;
+    /** Revoke a certificate */
+    revokeCertificate(id: string, reason?: string): Promise<void>;
+    /** Get a nutrition label for a certificate */
+    getNutritionLabel(id: string): Promise<NutritionLabel>;
+    /** Publish a certificate to the public registry */
+    publishToRegistry(certificateId: string, agentName: string, agentDescription: string): Promise<RegistryListing>;
+    /** Search the public registry */
+    searchRegistry(opts?: SearchRegistryOptions): Promise<PaginatedResult<RegistryListing>>;
+    /** Get leaderboard for a domain */
+    getLeaderboard(domain: string, limit?: number): Promise<{
+        domain: string;
+        entries: LeaderboardEntry[];
+    }>;
+    /** Get a benchmark suite by ID */
+    getSuite(id: string): Promise<BenchmarkSuite>;
+    /** List benchmark suites (public + own) */
+    listSuites(opts?: ListSuitesOptions): Promise<BenchmarkSuite[]>;
+    /** Create a custom benchmark suite */
+    createSuite(input: Partial<BenchmarkSuite>): Promise<BenchmarkSuite>;
+    /** Update a benchmark suite */
+    updateSuite(id: string, input: Partial<BenchmarkSuite>): Promise<BenchmarkSuite>;
+    /** Delete a benchmark suite */
+    deleteSuite(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** List capability drift events with optional filters */
+    listDrift(opts?: ListDriftOptions): Promise<PaginatedResult<CapabilityDriftEvent>>;
+    /** Acknowledge drift events by IDs */
+    acknowledgeDrift(eventIds: string[], note?: string): Promise<AcknowledgeDriftResult>;
+    /** Compare multiple certificates side-by-side */
+    compareAgents(certIds: string[]): Promise<{
+        certificates: Array<{
+            id: string;
+            agentId: string;
+            domain: string;
+            overallScore: number;
+            tier: string;
+            issuedAt: string;
+        }>;
+        dimensionComparisons: Array<{
+            dimension: string;
+            scores: Array<{
+                certificateId: string;
+                agentId: string;
+                score: number;
+            }>;
+            maxDelta: number;
+        }>;
+        overallRanking: Array<{
+            certificateId: string;
+            agentId: string;
+            overallScore: number;
+            tier: string;
+        }>;
+    }>;
+    /** Get NIST-aligned JSON-LD export for a certificate */
+    getNistExport(id: string): Promise<NistExport>;
+    /** Get OpenBadges v3 (W3C Verifiable Credential) export for a certificate */
+    getOpenBadge(id: string): Promise<OpenBadgeCredential>;
+    /** Get Markdown nutrition label for a certificate */
+    getMarkdownLabel(id: string): Promise<string>;
+    /** Get current webhook configuration */
+    getWebhookConfig(): Promise<{
+        url: string | null;
+    }>;
+    /** Set webhook URL (auto-generates secret, returned once) */
+    setWebhookConfig(url: string): Promise<{
+        url: string;
+        secret: string;
+    }>;
+    /** Remove webhook configuration */
+    deleteWebhookConfig(): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface AttesterConfig {
+    agentAdapter: AgentAdapter;
+    suite: BenchmarkSuite;
+    concurrency?: number;
+    timeout_ms?: number;
+    signerCredential: string;
+    onProgress?: (progress: RunProgress) => void;
+}
+/**
+ * ACAP Attester — runs benchmark suites against agents locally and produces certificates.
+ *
+ * @beta Local attestation is not yet implemented. Use `ACAPClient.startAttestation()`
+ * for server-side attestation, which is fully functional.
+ *
+ * @example
+ * ```typescript
+ * // Server-side attestation (recommended):
+ * const client = new ACAPClient({ baseUrl: '...', apiKey: '...' });
+ * const run = await client.startAttestation({ agentId: '...', suiteId: '...' });
+ * ```
+ */
+declare class Attester {
+    private config;
+    constructor(config: AttesterConfig);
+    /**
+     * Run the benchmark suite against the configured agent.
+     * @beta Not yet implemented. Use `ACAPClient.startAttestation()` instead.
+     */
+    run(): Promise<AttestationRun & {
+        certificate: CapabilityCertificate;
+    }>;
+    /**
+     * Cancel a running attestation.
+     * @beta Not yet implemented. Use `ACAPClient.cancelAttestation()` instead.
+     */
+    cancel(): Promise<void>;
+    getProgress(): RunProgress;
+}
+
+/**
+ * Error class for ACAP SDK operations.
+ */
+declare class ACAPError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+export { ACAPClient, type ACAPClientConfig, ACAPError, type AcknowledgeDriftResult, type AttestationResult, Attester, type AttesterConfig, type LeaderboardEntry, type ListCertificatesOptions, type ListDriftOptions, type ListRunsOptions, type ListSuitesOptions, type PaginatedResult, type SearchRegistryOptions, type StartAttestationOptions };

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+import { AttestationRun, CapabilityCertificate, VerificationResult, NutritionLabel, RegistryListing, BenchmarkSuite, CapabilityDriftEvent, NistExport, OpenBadgeCredential, AgentAdapter, RunProgress } from '@threnn/acap-core';
+export { AgentAdapter, AgentMetadata, AgentResponse, AttestationRun, BenchmarkSuite, CapabilityCertificate, CapabilityDriftEvent, ComparisonResult, DimensionScore, DriftSummary, InteroperabilityLevel, NistExport, NutritionLabel, OpenBadgeCredential, RegistryListing, RegistrySearchParams, RegistrySearchResult, RunProgress, TaskResult, VerificationResult } from '@threnn/acap-core';
+
+/**
+ * SDK-specific types for the ACAP client.
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface ListCertificatesOptions {
+    agentId?: string;
+    domain?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface SearchRegistryOptions {
+    domain?: string;
+    minScore?: number;
+    maxScore?: number;
+    tier?: string;
+    query?: string;
+    sortBy?: 'score' | 'recent' | 'name';
+    page?: number;
+    pageSize?: number;
+}
+interface ListSuitesOptions {
+    domain?: string;
+    isPublic?: boolean;
+}
+interface LeaderboardEntry {
+    rank: number;
+    id: string;
+    certificate_id: string;
+    agent_name: string;
+    agent_description: string;
+    overall_score: number;
+    capability_tier: string;
+    listed_at: string;
+}
+/** Options for starting an attestation run */
+interface StartAttestationOptions {
+    /** Agent identifier */
+    agentId: string;
+    /** Benchmark suite ID (UUID) */
+    suiteId: string;
+    /** Agent's HTTP endpoint URL */
+    agentEndpoint: string;
+    /** API key for authenticating with the agent (optional) */
+    agentApiKey?: string;
+    /** Adapter type (default: 'http') */
+    agentAdapter?: 'http' | 'anthropic' | 'openai' | 'mcp';
+    /** Model ID for Anthropic/OpenAI adapters */
+    agentModel?: string;
+    /** System prompt for the agent (optional) */
+    agentSystemPrompt?: string;
+    /** MCP tool name (required if agentAdapter='mcp') */
+    mcpToolName?: string;
+    /** Agent metadata overrides */
+    agentMetadata?: {
+        modelProvider?: string;
+        modelVersion?: string;
+        temperature?: number;
+    };
+    /** Max parallel tasks (1-10, default: 1) */
+    concurrency?: number;
+    /** Per-task timeout in ms (1000-300000, default: 30000) */
+    timeout_ms?: number;
+}
+interface ListRunsOptions {
+    agentId?: string;
+    suiteId?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface ListDriftOptions {
+    agentId?: string;
+    severity?: string;
+    acknowledged?: boolean;
+    page?: number;
+    pageSize?: number;
+}
+interface AcknowledgeDriftResult {
+    success: boolean;
+    acknowledged: number;
+}
+/** Result from a completed attestation */
+interface AttestationResult {
+    id: string;
+    status: string;
+    agentId: string;
+    benchmarkSuiteId: string;
+    certificateId?: string;
+    overallScore?: number;
+    capabilityTier?: string;
+    duration_ms?: number;
+    taskProgress?: {
+        totalTasks: number;
+        completedTasks: number;
+        passedTasks: number;
+        failedTasks: number;
+    };
+    certificate?: unknown;
+    error?: string;
+}
+
+/**
+ * ACAP SDK Client — submit attestations, query certificates, search the registry.
+ */
+
+interface ACAPClientConfig {
+    /** Base URL of the ACAP API (e.g., 'https://app.threnn.ai') */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Custom fetch implementation (defaults to global fetch) */
+    fetch?: typeof globalThis.fetch;
+}
+declare class ACAPClient {
+    private baseUrl;
+    private apiKey;
+    private fetchFn;
+    constructor(config: ACAPClientConfig);
+    private headers;
+    private get;
+    private post;
+    private put;
+    private del;
+    private patch;
+    private handleResponse;
+    /**
+     * Start an attestation run — executes the benchmark and returns the result with certificate.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.startAttestation({
+     *   agentId: 'my-agent',
+     *   suiteId: 'suite-uuid',
+     *   agentEndpoint: 'https://my-agent.example.com/api/chat',
+     *   agentAdapter: 'http',
+     * });
+     * console.log(result.certificate); // Signed CapabilityCertificate
+     * ```
+     */
+    startAttestation(opts: StartAttestationOptions): Promise<AttestationResult>;
+    /** Get the status of an attestation run */
+    getAttestationStatus(runId: string): Promise<AttestationRun>;
+    /** Cancel a running attestation */
+    cancelAttestation(runId: string): Promise<void>;
+    /** List attestation runs with optional filters */
+    listRuns(opts?: ListRunsOptions): Promise<PaginatedResult<AttestationRun>>;
+    /** Get a certificate by ID */
+    getCertificate(id: string): Promise<CapabilityCertificate>;
+    /** List certificates with optional filters */
+    listCertificates(opts?: ListCertificatesOptions): Promise<PaginatedResult<CapabilityCertificate>>;
+    /** Get certificates for a specific agent */
+    getCertificatesForAgent(agentId: string, opts?: {
+        domain?: string;
+        status?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResult<CapabilityCertificate>>;
+    /** Verify a certificate's integrity and validity */
+    verifyCertificate(id: string): Promise<VerificationResult>;
+    /** Revoke a certificate */
+    revokeCertificate(id: string, reason?: string): Promise<void>;
+    /** Get a nutrition label for a certificate */
+    getNutritionLabel(id: string): Promise<NutritionLabel>;
+    /** Publish a certificate to the public registry */
+    publishToRegistry(certificateId: string, agentName: string, agentDescription: string): Promise<RegistryListing>;
+    /** Search the public registry */
+    searchRegistry(opts?: SearchRegistryOptions): Promise<PaginatedResult<RegistryListing>>;
+    /** Get leaderboard for a domain */
+    getLeaderboard(domain: string, limit?: number): Promise<{
+        domain: string;
+        entries: LeaderboardEntry[];
+    }>;
+    /** Get a benchmark suite by ID */
+    getSuite(id: string): Promise<BenchmarkSuite>;
+    /** List benchmark suites (public + own) */
+    listSuites(opts?: ListSuitesOptions): Promise<BenchmarkSuite[]>;
+    /** Create a custom benchmark suite */
+    createSuite(input: Partial<BenchmarkSuite>): Promise<BenchmarkSuite>;
+    /** Update a benchmark suite */
+    updateSuite(id: string, input: Partial<BenchmarkSuite>): Promise<BenchmarkSuite>;
+    /** Delete a benchmark suite */
+    deleteSuite(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** List capability drift events with optional filters */
+    listDrift(opts?: ListDriftOptions): Promise<PaginatedResult<CapabilityDriftEvent>>;
+    /** Acknowledge drift events by IDs */
+    acknowledgeDrift(eventIds: string[], note?: string): Promise<AcknowledgeDriftResult>;
+    /** Compare multiple certificates side-by-side */
+    compareAgents(certIds: string[]): Promise<{
+        certificates: Array<{
+            id: string;
+            agentId: string;
+            domain: string;
+            overallScore: number;
+            tier: string;
+            issuedAt: string;
+        }>;
+        dimensionComparisons: Array<{
+            dimension: string;
+            scores: Array<{
+                certificateId: string;
+                agentId: string;
+                score: number;
+            }>;
+            maxDelta: number;
+        }>;
+        overallRanking: Array<{
+            certificateId: string;
+            agentId: string;
+            overallScore: number;
+            tier: string;
+        }>;
+    }>;
+    /** Get NIST-aligned JSON-LD export for a certificate */
+    getNistExport(id: string): Promise<NistExport>;
+    /** Get OpenBadges v3 (W3C Verifiable Credential) export for a certificate */
+    getOpenBadge(id: string): Promise<OpenBadgeCredential>;
+    /** Get Markdown nutrition label for a certificate */
+    getMarkdownLabel(id: string): Promise<string>;
+    /** Get current webhook configuration */
+    getWebhookConfig(): Promise<{
+        url: string | null;
+    }>;
+    /** Set webhook URL (auto-generates secret, returned once) */
+    setWebhookConfig(url: string): Promise<{
+        url: string;
+        secret: string;
+    }>;
+    /** Remove webhook configuration */
+    deleteWebhookConfig(): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface AttesterConfig {
+    agentAdapter: AgentAdapter;
+    suite: BenchmarkSuite;
+    concurrency?: number;
+    timeout_ms?: number;
+    signerCredential: string;
+    onProgress?: (progress: RunProgress) => void;
+}
+/**
+ * ACAP Attester — runs benchmark suites against agents locally and produces certificates.
+ *
+ * @beta Local attestation is not yet implemented. Use `ACAPClient.startAttestation()`
+ * for server-side attestation, which is fully functional.
+ *
+ * @example
+ * ```typescript
+ * // Server-side attestation (recommended):
+ * const client = new ACAPClient({ baseUrl: '...', apiKey: '...' });
+ * const run = await client.startAttestation({ agentId: '...', suiteId: '...' });
+ * ```
+ */
+declare class Attester {
+    private config;
+    constructor(config: AttesterConfig);
+    /**
+     * Run the benchmark suite against the configured agent.
+     * @beta Not yet implemented. Use `ACAPClient.startAttestation()` instead.
+     */
+    run(): Promise<AttestationRun & {
+        certificate: CapabilityCertificate;
+    }>;
+    /**
+     * Cancel a running attestation.
+     * @beta Not yet implemented. Use `ACAPClient.cancelAttestation()` instead.
+     */
+    cancel(): Promise<void>;
+    getProgress(): RunProgress;
+}
+
+/**
+ * Error class for ACAP SDK operations.
+ */
+declare class ACAPError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+export { ACAPClient, type ACAPClientConfig, ACAPError, type AcknowledgeDriftResult, type AttestationResult, Attester, type AttesterConfig, type LeaderboardEntry, type ListCertificatesOptions, type ListDriftOptions, type ListRunsOptions, type ListSuitesOptions, type PaginatedResult, type SearchRegistryOptions, type StartAttestationOptions };