@astrasyncai/verification-gateway 2.3.10 → 2.4.1

package/dist/registration/index.d.ts

@@ -0,0 +1,369 @@
+/** 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://astrasync.ai` (production).
+     * For staging, pass `https://staging.astrasync.ai`.
+     */
+    baseUrl?: string;
+}
+/**
+ * Multi-protocol declarations the agent participates in.
+ * Promoted from `metadata.protocols[]` to a first-class field in agent-registration v1.0.0.
+ */
+type AgentProtocol = 'a2a' | 'acp' | 'ap2' | 'ucp' | 'mpp' | 'x402' | 'erc8004' | 'vi' | 'agentpay' | 'tap' | 'other';
+/** 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;
+    /**
+     * URL where your agent's verification-gateway SDK is mounted for runtime
+     * challenges. Optional — if omitted, your agent declares no runtime-challenge
+     * support and some counterparties may decline access requests. Mirrors the
+     * webUI "API endpoint" field.
+     */
+    apiEndpoint?: string;
+    model?: ModelConfig;
+    framework?: FrameworkConfig;
+    /** Multi-protocol declarations (e.g. ['acp', 'ap2', 'a2a']). First-class as of v1.0.0. */
+    protocols?: AgentProtocol[];
+    metadata?: Record<string, unknown>;
+    pdlss?: PDLSSConfig;
+}
+/**
+ * Optional blocking-mode flags for `register()`. When `waitForApproval` is
+ * true and the backend returns 202 pending, the SDK polls until the request
+ * resolves (approved → returns Agent; denied/expired → throws; timeout →
+ * throws). The default is non-blocking: the SDK returns the pending result
+ * immediately and the caller handles polling itself.
+ */
+interface WaitForApprovalOptions {
+    /** Block until the request resolves. Default: false. */
+    waitForApproval?: boolean;
+    /** How long to wait in blocking mode. Default: 600_000ms (10 min). */
+    timeoutMs?: number;
+    /** Poll cadence in blocking mode. Default: 5000ms. */
+    pollIntervalMs?: number;
+    /** Called once per poll while still pending; useful for progress UX. */
+    onPending?: (event: {
+        requestId: string;
+        ageMs: number;
+    }) => void;
+}
+/**
+ * Discriminated registration result.
+ *
+ * - `active`: synchronous path (crypto-keypair signature verified, or
+ *   email+password auth). `agent` is the live record.
+ * - `pending_approval`: API-key auth path. The owner has been notified by
+ *   email and a dashboard alert. Poll `pollUrl` or call
+ *   `sdk.pollRegistration(requestId)` to track progress, or re-call
+ *   `register` with `waitForApproval: true` to block.
+ */
+type RegisterResult = {
+    status: 'active';
+    agent: AgentRecord;
+} | {
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+};
+/**
+ * Response shape from `pollRegistration(requestId)` and the internal poll
+ * loop. State `pending` means still awaiting owner; the others are terminal.
+ */
+interface PollRegistrationResult {
+    state: 'pending' | 'approved' | 'denied' | 'expired';
+    agent?: AgentRecord;
+    reason?: string;
+}
+/**
+ * Response from agent registration (raw 201 body). Use {@link RegisterResult}
+ * for the consumer-facing shape returned from `sdk.register()`.
+ */
+interface RegistrationResponse {
+    success: boolean;
+    message: string;
+    data: {
+        agent: AgentRecord;
+    };
+}
+/** Raw 202 body — internal type, exposed via {@link RegisterResult}. */
+interface PendingRegistrationResponse {
+    success: true;
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+}
+/** 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' },
+ * });
+ * ```
+ *
+ * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.
+ */
+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.
+     *
+     * The backend response depends on auth context:
+     * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+     *   returns `{ status: 'active', agent }`.
+     * - **API-key only** (no signature): 202 pending, returns
+     *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+     *   owner is notified by email and a dashboard alert is emitted; the agent
+     *   becomes active only after the owner approves.
+     *
+     * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+     * request until it resolves, then return the live agent record. The promise
+     * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+     * `RegistrationTimeoutError` on the corresponding terminal states.
+     *
+     * @example Non-blocking (default — best for serverless / scheduled agents):
+     * ```typescript
+     * const result = await sdk.register({ name, pdlss });
+     * if (result.status === 'pending_approval') {
+     *   storeRequestId(result.requestId);
+     *   return; // function exits; resume later via pollRegistration()
+     * }
+     * ```
+     *
+     * @example Blocking (best for long-running services + CLI):
+     * ```typescript
+     * const agent = await sdk.register({
+     *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+     *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+     * });
+     * ```
+     */
+    register(options: RegisterOptions & WaitForApprovalOptions): Promise<RegisterResult | AgentRecord>;
+    /**
+     * Poll the current state of a pending-approval registration request.
+     *
+     * Useful for caller-driven polling when `waitForApproval: false` (the
+     * default). The endpoint is unauthenticated — pass the `requestId` that
+     * was returned from the 202 response.
+     *
+     * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+     *          minted agent in `agent`; `'denied'` may carry the owner's
+     *          `reason`; `'expired'` is terminal after 14 days.
+     */
+    pollRegistration(requestId: string): Promise<PollRegistrationResult>;
+    /**
+     * Block until a pending registration request resolves to a terminal state.
+     * Resolves to the live `AgentRecord` on approval; rejects with the matching
+     * Registration*Error on deny/expire/timeout. Usually called via
+     * `register({ waitForApproval: true })`, but exposed for callers that want
+     * to fire-and-forget the initial register call and resume waiting later
+     * (e.g. after restoring a stored `requestId` on cold start).
+     */
+    waitForApproval(requestId: string, options?: WaitForApprovalOptions): Promise<AgentRecord>;
+    /**
+     * 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;
+    /**
+     * Variant of {@link request} that also returns the HTTP status code, so
+     * callers can branch on 201 vs 202 (or other success codes) without losing
+     * type information about the response body.
+     */
+    private requestWithStatus;
+    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);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the owner denies the
+ * pending registration request. The `reason` field, when present, mirrors the
+ * deny note the owner left in the dashboard.
+ */
+declare class RegistrationDeniedError extends AstraSyncError {
+    readonly requestId: string;
+    readonly reason?: string;
+    constructor(requestId: string, reason?: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the pending request
+ * passes its 14-day TTL with no owner decision. The agent must re-submit.
+ */
+declare class RegistrationExpiredError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the caller's local
+ * `timeoutMs` elapses before the owner makes a decision. The request is still
+ * live server-side — poll `pollRegistration(requestId)` to resume waiting, or
+ * call `waitForApproval` again with a longer timeout.
+ */
+declare class RegistrationTimeoutError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+
+export { type AgentProtocol, 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 PendingRegistrationResponse, type PollRegistrationResult, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type VerifyResponse, type WaitForApprovalOptions };