@vorionsys/cognigate 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,506 @@
+import { z } from 'zod';
+export { z } from 'zod';
+
+/**
+ * Cognigate TypeScript SDK - Type Definitions
+ *
+ * Core types for the Cognigate AI governance API
+ */
+
+declare enum TrustTier {
+    T0_SANDBOX = 0,
+    T1_OBSERVED = 1,
+    T2_PROVISIONAL = 2,
+    T3_VERIFIED = 3,
+    T4_OPERATIONAL = 4,
+    T5_TRUSTED = 5,
+    T6_CERTIFIED = 6,
+    T7_AUTONOMOUS = 7
+}
+declare const TIER_THRESHOLDS: Record<TrustTier, {
+    min: number;
+    max: number;
+    name: string;
+}>;
+type GovernanceDecision = 'ALLOW' | 'DENY' | 'ESCALATE' | 'DEGRADE';
+interface GovernanceResult {
+    decision: GovernanceDecision;
+    trustScore: number;
+    trustTier: TrustTier;
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    reasoning: string;
+    constraints?: Record<string, unknown>;
+    proofId?: string;
+    timestamp: Date;
+}
+interface Intent {
+    id: string;
+    entityId: string;
+    rawInput: string;
+    parsedAction: string;
+    parameters: Record<string, unknown>;
+    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    requiredCapabilities: string[];
+    timestamp: Date;
+}
+interface IntentParseResult {
+    intent: Intent;
+    confidence: number;
+    alternativeInterpretations?: Intent[];
+}
+interface TrustStatus {
+    entityId: string;
+    trustScore: number;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}
+interface ProofRecord {
+    id: string;
+    entityId: string;
+    intentId: string;
+    decision: GovernanceDecision;
+    action: string;
+    outcome: 'SUCCESS' | 'FAILURE' | 'PARTIAL' | 'PENDING';
+    trustScoreBefore: number;
+    trustScoreAfter: number;
+    timestamp: Date;
+    hash: string;
+    previousHash: string;
+    metadata?: Record<string, unknown>;
+}
+interface ProofChainStats {
+    totalRecords: number;
+    successRate: number;
+    averageTrustScore: number;
+    chainIntegrity: boolean;
+    lastVerified: Date;
+}
+interface Agent {
+    id: string;
+    name: string;
+    description: string;
+    ownerId: string;
+    trustScore: number;
+    trustTier: TrustTier;
+    status: 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'TERMINATED';
+    capabilities: string[];
+    executions: number;
+    successRate: number;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown>;
+}
+interface CreateAgentRequest {
+    name: string;
+    description?: string;
+    template?: string;
+    initialCapabilities?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface UpdateAgentRequest {
+    name?: string;
+    description?: string;
+    status?: 'ACTIVE' | 'PAUSED';
+    metadata?: Record<string, unknown>;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: ApiError;
+    requestId: string;
+    timestamp: Date;
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+}
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    entityId: string;
+    payload: Record<string, unknown>;
+    timestamp: Date;
+    signature: string;
+}
+type WebhookEventType = 'agent.created' | 'agent.updated' | 'agent.deleted' | 'agent.status_changed' | 'trust.score_changed' | 'trust.tier_changed' | 'governance.decision' | 'proof.recorded' | 'alert.triggered';
+interface CognigateConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+    webhookSecret?: string;
+}
+declare const TrustStatusSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    tierName: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    factorScores: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    lastEvaluated: z.ZodDate;
+    compliant: z.ZodBoolean;
+    warnings: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    entityId: string;
+    trustScore: number;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}, {
+    entityId: string;
+    trustScore: number;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}>;
+declare const GovernanceResultSchema: z.ZodObject<{
+    decision: z.ZodEnum<["ALLOW", "DENY", "ESCALATE", "DEGRADE"]>;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    grantedCapabilities: z.ZodArray<z.ZodString, "many">;
+    deniedCapabilities: z.ZodArray<z.ZodString, "many">;
+    reasoning: z.ZodString;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    proofId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    trustScore: number;
+    trustTier: TrustTier;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    reasoning: string;
+    timestamp: Date;
+    constraints?: Record<string, unknown> | undefined;
+    proofId?: string | undefined;
+}, {
+    trustScore: number;
+    trustTier: TrustTier;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    reasoning: string;
+    timestamp: Date;
+    constraints?: Record<string, unknown> | undefined;
+    proofId?: string | undefined;
+}>;
+declare const ProofRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    entityId: z.ZodString;
+    intentId: z.ZodString;
+    decision: z.ZodEnum<["ALLOW", "DENY", "ESCALATE", "DEGRADE"]>;
+    action: z.ZodString;
+    outcome: z.ZodEnum<["SUCCESS", "FAILURE", "PARTIAL", "PENDING"]>;
+    trustScoreBefore: z.ZodNumber;
+    trustScoreAfter: z.ZodNumber;
+    timestamp: z.ZodDate;
+    hash: z.ZodString;
+    previousHash: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    entityId: string;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    timestamp: Date;
+    id: string;
+    intentId: string;
+    action: string;
+    outcome: "SUCCESS" | "FAILURE" | "PARTIAL" | "PENDING";
+    trustScoreBefore: number;
+    trustScoreAfter: number;
+    hash: string;
+    previousHash: string;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    entityId: string;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    timestamp: Date;
+    id: string;
+    intentId: string;
+    action: string;
+    outcome: "SUCCESS" | "FAILURE" | "PARTIAL" | "PENDING";
+    trustScoreBefore: number;
+    trustScoreAfter: number;
+    hash: string;
+    previousHash: string;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const AgentSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    ownerId: z.ZodString;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    status: z.ZodEnum<["ACTIVE", "PAUSED", "SUSPENDED", "TERMINATED"]>;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    executions: z.ZodNumber;
+    successRate: z.ZodNumber;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    trustScore: number;
+    trustTier: TrustTier;
+    status: "ACTIVE" | "PAUSED" | "SUSPENDED" | "TERMINATED";
+    capabilities: string[];
+    id: string;
+    name: string;
+    description: string;
+    ownerId: string;
+    executions: number;
+    successRate: number;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    trustScore: number;
+    trustTier: TrustTier;
+    status: "ACTIVE" | "PAUSED" | "SUSPENDED" | "TERMINATED";
+    capabilities: string[];
+    id: string;
+    name: string;
+    description: string;
+    ownerId: string;
+    executions: number;
+    successRate: number;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+
+/**
+ * Cognigate TypeScript SDK - Client
+ *
+ * Main client class for interacting with the Cognigate API
+ */
+
+declare class CognigateError extends Error {
+    code: string;
+    status?: number | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, status?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+declare class Cognigate {
+    private readonly config;
+    readonly agents: AgentsClient;
+    readonly trust: TrustClient;
+    readonly governance: GovernanceClient;
+    readonly proofs: ProofsClient;
+    constructor(config: CognigateConfig);
+    /**
+     * Make an authenticated request to the Cognigate API
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown): Promise<T>;
+    /**
+     * Check API health
+     */
+    health(): Promise<{
+        status: string;
+        version: string;
+        timestamp: Date;
+    }>;
+    /**
+     * Get tier from trust score
+     */
+    static getTierFromScore(score: number): TrustTier;
+    /**
+     * Get tier name
+     */
+    static getTierName(tier: TrustTier): string;
+    /**
+     * Get tier thresholds
+     */
+    static getTierThresholds(tier: TrustTier): {
+        min: number;
+        max: number;
+        name: string;
+    };
+}
+declare class AgentsClient {
+    private client;
+    constructor(client: Cognigate);
+    /**
+     * List all agents
+     */
+    list(params?: {
+        page?: number;
+        pageSize?: number;
+        status?: 'ACTIVE' | 'PAUSED' | 'SUSPENDED';
+    }): Promise<PaginatedResponse<Agent>>;
+    /**
+     * Get a specific agent
+     */
+    get(agentId: string): Promise<Agent>;
+    /**
+     * Create a new agent
+     */
+    create(data: CreateAgentRequest): Promise<Agent>;
+    /**
+     * Update an agent
+     */
+    update(agentId: string, data: UpdateAgentRequest): Promise<Agent>;
+    /**
+     * Delete an agent
+     */
+    delete(agentId: string): Promise<void>;
+    /**
+     * Pause an agent
+     */
+    pause(agentId: string): Promise<Agent>;
+    /**
+     * Resume an agent
+     */
+    resume(agentId: string): Promise<Agent>;
+}
+declare class TrustClient {
+    private client;
+    constructor(client: Cognigate);
+    /**
+     * Get trust status for an entity
+     */
+    getStatus(entityId: string): Promise<TrustStatus>;
+    /**
+     * Get trust history
+     */
+    getHistory(entityId: string, params?: {
+        from?: Date;
+        to?: Date;
+        limit?: number;
+    }): Promise<Array<{
+        score: number;
+        tier: TrustTier;
+        timestamp: Date;
+    }>>;
+    /**
+     * Submit an outcome to update trust score
+     */
+    submitOutcome(entityId: string, proofId: string, outcome: {
+        success: boolean;
+        metrics?: Record<string, number>;
+        notes?: string;
+    }): Promise<TrustStatus>;
+}
+declare class GovernanceClient {
+    private client;
+    constructor(client: Cognigate);
+    /**
+     * Parse user intent into structured format
+     */
+    parseIntent(entityId: string, rawInput: string): Promise<IntentParseResult>;
+    /**
+     * Enforce governance rules on an intent
+     */
+    enforce(intent: Intent): Promise<GovernanceResult>;
+    /**
+     * Convenience method: parse and enforce in one call
+     */
+    evaluate(entityId: string, rawInput: string): Promise<{
+        intent: Intent;
+        result: GovernanceResult;
+    }>;
+    /**
+     * Check if an action is allowed without creating a proof record
+     */
+    canPerform(entityId: string, action: string, capabilities: string[]): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
+}
+declare class ProofsClient {
+    private client;
+    constructor(client: Cognigate);
+    /**
+     * Get a specific proof record
+     */
+    get(proofId: string): Promise<ProofRecord>;
+    /**
+     * List proof records for an entity
+     */
+    list(entityId: string, params?: {
+        page?: number;
+        pageSize?: number;
+        from?: Date;
+        to?: Date;
+        outcome?: 'SUCCESS' | 'FAILURE' | 'PARTIAL';
+    }): Promise<PaginatedResponse<ProofRecord>>;
+    /**
+     * Get proof chain statistics
+     */
+    getStats(entityId: string): Promise<ProofChainStats>;
+    /**
+     * Verify proof chain integrity
+     */
+    verify(entityId: string): Promise<{
+        valid: boolean;
+        errors: string[];
+        lastVerified: Date;
+    }>;
+}
+
+/**
+ * Cognigate TypeScript SDK - Webhook Utilities
+ *
+ * Helpers for handling Cognigate webhooks
+ */
+
+/**
+ * Verify webhook signature
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+/**
+ * Parse and validate a webhook payload
+ */
+declare function parseWebhookPayload(body: string, signature: string, secret: string): Promise<WebhookEvent>;
+/**
+ * Webhook handler type
+ */
+type WebhookHandler<T extends WebhookEventType = WebhookEventType> = (event: WebhookEvent & {
+    type: T;
+}) => void | Promise<void>;
+/**
+ * Webhook router for handling different event types
+ */
+declare class WebhookRouter {
+    private handlers;
+    /**
+     * Register a handler for a specific event type
+     */
+    on<T extends WebhookEventType>(type: T, handler: WebhookHandler<T>): this;
+    /**
+     * Register a handler for all events
+     */
+    onAll(handler: WebhookHandler): this;
+    /**
+     * Handle a webhook event
+     */
+    handle(event: WebhookEvent): Promise<void>;
+    /**
+     * Create an Express/Connect compatible middleware
+     */
+    middleware(secret: string): (req: any, res: any, _next?: () => void) => Promise<void>;
+}
+
+export { type Agent, AgentSchema, AgentsClient, type ApiError, type ApiResponse, Cognigate, type CognigateConfig, CognigateError, type CreateAgentRequest, GovernanceClient, type GovernanceDecision, type GovernanceResult, GovernanceResultSchema, type Intent, type IntentParseResult, type PaginatedResponse, type ProofChainStats, type ProofRecord, ProofRecordSchema, ProofsClient, TIER_THRESHOLDS, TrustClient, type TrustStatus, TrustStatusSchema, TrustTier, type UpdateAgentRequest, type WebhookEvent, type WebhookEventType, type WebhookHandler, WebhookRouter, parseWebhookPayload, verifyWebhookSignature };