@astrasyncai/sdk/dist/index.d.ts

Official Node.js SDK for the AstraSync KYA Platform — register and manage AI agents with verified identities

/** Configuration for the AstraSync SDK client. */
interface AstraSyncConfig {
    /** API key (kya_ prefixed). Used as Bearer token. */
    apiKey?: string;
    /** Email for email+password authentication. */
    email?: string;
    /** Password for email+password authentication. */
    password?: string;
    /** secp256k1 private key for crypto signing. Used WITH apiKey or email+password. */
    privateKey?: string;
    /** Base URL for the AstraSync API. Defaults to ASTRASYNC_API_URL env or https://api.kya.astrasync.ai */
    baseUrl?: string;
}
/** PDLSS purpose configuration. */
interface PDLSSPurpose {
    categories: string[];
    allowedActions?: string[];
    deniedActions?: string[];
}
/** PDLSS duration configuration. */
interface PDLSSDuration {
    startTime?: string | null;
    endTime?: string | null;
    timezone?: string | null;
    maxSessionDuration?: number | null;
    ttl?: number | null;
    allowedDays?: number[] | null;
    allowedHours?: {
        start: number;
        end: number;
    } | null;
}
/** PDLSS limits configuration. */
interface PDLSSLimits {
    autonomousThreshold?: number | null;
    stepUpThreshold?: number | null;
    approvalThreshold?: number | null;
    maxTransactionsPerDay?: number | null;
    maxTransactionsPerHour?: number | null;
    maxTotalValue?: number | null;
    currency?: string;
}
/** PDLSS scope configuration. */
interface PDLSSScope {
    resources?: string[];
    resourceTypes?: string[];
    jurisdictions?: string[];
    excludedResources?: string[];
    counterparties?: string[];
    excludedCounterparties?: string[];
}
/** PDLSS self-instantiation configuration. */
interface PDLSSSelfInstantiation {
    allowed: boolean;
    maxSubAgents?: number | null;
    inheritPermissions?: boolean | null;
    allowedPurposes?: string[] | null;
    requireApproval?: boolean | null;
    maxDepth?: number | null;
}
/** Full PDLSS configuration. */
interface PDLSSConfig {
    purpose: PDLSSPurpose;
    duration?: PDLSSDuration;
    limits?: PDLSSLimits;
    scope?: PDLSSScope;
    selfInstantiation?: PDLSSSelfInstantiation;
}
/** Model metadata for registration. */
interface ModelConfig {
    modelName: string;
    modelProvider: string;
    modelType?: 'llm' | 'embedding' | 'image' | 'audio' | 'multimodal' | 'code' | 'other';
    contextWindow?: number;
    maxTokens?: number;
}
/** Framework metadata for registration. */
interface FrameworkConfig {
    frameworkName: string;
    frameworkVersion: string;
}
/** Options for agent registration. */
interface RegisterOptions {
    name: string;
    description?: string;
    agentType?: string;
    apiEndpoint?: string;
    model?: ModelConfig;
    framework?: FrameworkConfig;
    metadata?: Record<string, unknown>;
    pdlss?: PDLSSConfig;
}
/** Response from agent registration. */
interface RegistrationResponse {
    success: boolean;
    message: string;
    data: {
        agent: AgentRecord;
    };
}
/** Agent record from the API. */
interface AgentRecord {
    kyaAgentId: string;
    name: string;
    description?: string;
    agentType: string;
    agentStatus: string;
    trustScore: number;
    astrasyncIdLevel1?: string | null;
    tempId?: string | null;
    metadata?: Record<string, unknown>;
    createdAt: string;
    updatedAt: string;
}
/** Public agent verification response. */
interface VerifyResponse {
    success: boolean;
    data: {
        agentUuid: string;
        agentName: string;
        agentDescription: string;
        agentTrustScore: number;
        agentStatus: string;
        ownerName?: string;
    };
}
/** Health check response. */
interface HealthResponse {
    status: string;
    service: string;
    version: string;
}
/** Error response from the API. */
interface ApiErrorResponse {
    success: false;
    error: string;
    code?: string;
    kydUrl?: string;
    ownerNotified?: boolean;
}

/**
 * AstraSync SDK client for registering and managing AI agents.
 *
 * @example
 * ```typescript
 * const client = new AstraSync({ apiKey: 'kya_your_api_key' });
 * const result = await client.register({
 *   name: 'My Agent',
 *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },
 * });
 * ```
 */
declare class AstraSync {
    private readonly baseUrl;
    private readonly apiKey?;
    private readonly email?;
    private readonly password?;
    private readonly privateKey?;
    private cachedJwt?;
    private jwtExpiresAt?;
    constructor(config?: AstraSyncConfig);
    /**
     * Register a new AI agent on the AstraSync KYA Platform.
     * Sends full payload including model, framework, PDLSS, and metadata.
     */
    register(options: RegisterOptions): Promise<RegistrationResponse>;
    /**
     * Look up an agent's public profile by ASTRA ID or UUID.
     */
    verify(agentId: string): Promise<VerifyResponse>;
    /**
     * Check API health.
     */
    health(): Promise<HealthResponse>;
    private request;
    private getAuthToken;
    /**
     * Sign a request using secp256k1 (ethers.js).
     * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY
     * Must match apps/backend/src/services/signature-verify.service.ts exactly.
     */
    private signRequest;
    /** Recursively sort object keys for canonical JSON representation. */
    private sortObjectKeys;
}

/** Base error class for AstraSync SDK errors. */
declare class AstraSyncError extends Error {
    readonly code?: string;
    readonly statusCode: number;
    constructor(message: string, statusCode: number, code?: string);
}
/** Thrown when KYD verification is required before agent registration. */
declare class KYDRequiredError extends AstraSyncError {
    readonly kydUrl: string;
    readonly ownerNotified: boolean;
    constructor(response: ApiErrorResponse);
}
/** Thrown when authentication fails. */
declare class AuthenticationError extends AstraSyncError {
    constructor(message: string);
}

export { type AgentRecord, AstraSync, type AstraSyncConfig, AstraSyncError, AuthenticationError, type FrameworkConfig, type HealthResponse, KYDRequiredError, type ModelConfig, type PDLSSConfig, type PDLSSDuration, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, type RegisterOptions, type RegistrationResponse, type VerifyResponse };