@emilia-protocol/sdk 0.1.0 → 0.9.0

package/dist/index.d.ts

@@ -1,194 +1,517 @@
-/**
- * @emilia-protocol/sdk
- *
- * TypeScript SDK for EMILIA Protocol (EP).
- * The trust layer for agentic commerce.
- *
- * Usage:
- *   import { EmiliaClient } from '@emilia-protocol/sdk';
- *   const ep = new EmiliaClient({ apiKey: 'ep_live_...' });
- *   const score = await ep.getScore('rex-booking-v1');
- *
- * @license Apache-2.0
- */
-export interface EmiliaConfig {
-    /** Base URL of the EP implementation. Default: https://emiliaprotocol.ai */
-    baseUrl?: string;
-    /** API key for write operations (ep_live_...) */
+/** EMILIA Protocol — Full SDK. Zero dependencies, native fetch. @license Apache-2.0 */
+export interface EPClientOptions {
+    baseUrl: string;
     apiKey?: string;
-    /** Request timeout in ms. Default: 10000 */
     timeout?: number;
+    retries?: number;
 }
-export interface ScoreBreakdown {
-    delivery_accuracy: number | null;
-    product_accuracy: number | null;
-    price_integrity: number | null;
-    return_processing: number | null;
-    agent_satisfaction: number | null;
-    consistency: number | null;
-}
-export interface ScoreResult {
-    entity_id: string;
-    display_name: string;
-    entity_type: 'agent' | 'merchant' | 'service_provider';
-    description?: string;
-    category?: string;
-    capabilities?: string[];
-    emilia_score: number;
-    established: boolean;
-    total_receipts: number;
-    successful_receipts: number;
-    success_rate: number | null;
-    breakdown: ScoreBreakdown | null;
-    verified: boolean;
-    a2a_endpoint?: string;
-    ucp_profile_url?: string;
-    member_since: string;
-}
-export type TransactionType = 'purchase' | 'service' | 'task_completion' | 'delivery' | 'return';
-export interface SubmitReceiptInput {
-    entity_id: string;
-    transaction_type: TransactionType;
-    transaction_ref?: string;
-    delivery_accuracy?: number;
-    product_accuracy?: number;
-    price_integrity?: number;
-    return_processing?: number;
-    agent_satisfaction?: number;
-    evidence?: Record<string, unknown>;
-}
-export interface ReceiptResult {
-    receipt: {
-        receipt_id: string;
-        entity_id: string;
-        composite_score: number;
-        receipt_hash: string;
-        created_at: string;
-    };
-    entity_score: {
-        emilia_score: number;
-        total_receipts: number;
-    };
-}
-export interface RegisterEntityInput {
-    entity_id: string;
-    display_name: string;
-    entity_type: 'agent' | 'merchant' | 'service_provider';
+export interface Party {
+    entityRef: string;
+    role: 'initiator' | 'responder';
+}
+export interface InitiateHandshakeParams {
+    mode: 'mutual' | 'one-way' | 'delegated';
+    policyId: string;
+    parties: Party[];
+    binding?: Record<string, unknown>;
+    interactionId?: string;
+}
+export interface PresentParams {
+    partyRole: string;
+    presentationType: 'ep_trust_profile' | 'verifiable_credential' | 'attestation';
+    claims: Record<string, unknown>;
+    issuerRef?: string;
+    disclosureMode?: 'full' | 'selective' | 'zk';
+}
+export interface GateParams {
+    entityId: string;
+    action: string;
+    policy?: 'strict' | 'standard' | 'permissive' | string;
+    handshakeId?: string;
+    valueUsd?: number;
+    delegationId?: string;
+}
+export interface ConsumeParams {
+    receiptData?: Record<string, unknown>;
+}
+export interface IssueChallengeParams {
+    entityId: string;
+    scope: string;
+    context?: Record<string, unknown>;
+}
+export interface AttestParams {
+    signature: string;
+    payload: Record<string, unknown>;
+}
+export interface ConsumeSignoffParams {
+    action: string;
+    context?: Record<string, unknown>;
+}
+export interface DenyChallengeParams {
+    reason?: string;
+}
+export interface RevokeSignoffOptions {
+    reason?: string;
+    force?: boolean;
+}
+export interface CreateDelegationParams {
+    delegatorId: string;
+    delegateeId: string;
+    scope: string;
+    policyId: string;
+    constraints?: Record<string, unknown>;
+    expiresAt?: string;
+}
+export interface IssueCommitParams {
+    handshakeId: string;
+    action: string;
+    payload: Record<string, unknown>;
+    binding?: Record<string, unknown>;
+}
+export interface RecordObservationParams {
+    source_type: string;
+    source_ref: string;
+    subject_ref: string;
+    actor_ref: string;
+    action_type: string;
+    target_ref?: string;
+    issuer_ref?: string;
+    observation_type: string;
+    severity_hint: string;
+    evidence_hash?: string;
+    expires_at: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CheckActionParams {
+    subject_ref: string;
+    actor_ref: string;
+    action_type: string;
+    target_ref?: string;
+    issuer_ref?: string;
+    context_hash: string;
+    payload_hash?: string;
+    policy_class?: string;
+}
+export interface CreateSuppressionParams {
+    scope_binding_hash: string;
+    reason_code: string;
+    justification: string;
+    expires_at: string;
+}
+export interface ObservationResponse {
+    observation_id: string;
+    observation_type: string;
+    severity_hint: string;
+    observed_at: string;
+    expires_at: string;
+}
+export interface AdvisoryResponse {
+    advisory_id: string;
+    status: string;
+    reason_codes: string[];
+    recommended_policy_action: string;
+    evidence_refs: string[];
+    scope_binding_hash: string;
+    issued_at: string;
+    expires_at: string;
+    version: number;
+}
+export interface SuppressionResponse {
+    suppression_id: string;
+    status: string;
+    created_at: string;
+    expires_at: string;
+}
+export interface SignoffFilters {
+    entityId?: string;
+    scope?: string;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface DateRange {
+    from?: string;
+    to?: string;
+}
+export interface EscalateSignoffParams {
+    challengeId: string;
+    escalateTo: string;
+    reason: string;
+}
+export interface NotifySignoffParams {
+    challengeId: string;
+    channel: string;
+}
+export interface SearchEventsParams {
+    query: string;
+    filters?: Record<string, unknown>;
+}
+export interface ExportAuditParams {
+    format?: 'json' | 'csv' | 'pdf';
+    dateRange?: DateRange;
+    entityId?: string;
+    eventTypes?: string[];
+}
+export interface GetAuditReportParams {
+    reportType: string;
+    dateRange: DateRange;
+}
+export interface SimulatePolicyParams {
+    policyId: string;
+    context: Record<string, unknown>;
+}
+export interface RolloutPolicyParams {
+    policyId: string;
+    strategy: 'canary' | 'blue-green' | 'linear' | string;
+    percentage?: number;
+}
+export interface DiffPolicyVersionsParams {
+    policyId: string;
+    versionA: string;
+    versionB: string;
+}
+export interface Policy {
+    name: string;
+    family: string;
     description: string;
-    capabilities?: string[];
-    website_url?: string;
-    category?: string;
-    service_area?: string;
-    a2a_endpoint?: string;
-    ucp_profile_url?: string;
-}
-export interface RegisterResult {
-    entity: {
-        id: string;
-        entity_id: string;
-        display_name: string;
-        entity_number?: number;
-        emilia_score: number;
-    };
-    api_key: string;
-}
-export interface VerifyResult {
-    receipt_id: string;
-    receipt_hash: string;
-    anchored: boolean;
-    batch?: {
-        id: string;
-        merkle_root: string;
-        leaf_count: number;
-        tx_hash: string | null;
-        block_number: number | null;
-        status: string;
-        created_at: string;
-    };
-    proof?: Array<{
-        hash: string;
-        position: 'left' | 'right';
-    }>;
-    verified: boolean;
-    how_to_verify?: Record<string, string | null>;
-}
-export interface SearchResult {
-    entities: Array<{
-        entity_id: string;
-        display_name: string;
-        entity_type: string;
-        description: string;
-        emilia_score: number;
-        total_receipts: number;
-        verified: boolean;
-    }>;
-}
-export interface LeaderboardResult {
-    entities: Array<{
-        entity_id: string;
-        display_name: string;
-        entity_type: string;
-        emilia_score: number;
-        total_receipts: number;
-    }>;
-}
-export declare class EmiliaError extends Error {
-    status: number;
-    constructor(message: string, status: number);
-}
-export declare class EmiliaClient {
-    private baseUrl;
-    private apiKey;
-    private timeout;
-    constructor(config?: EmiliaConfig);
+    minConfidence?: string;
+    minScore?: number;
+}
+export interface Handshake {
+    id: string;
+    status: string;
+    mode: string;
+    policyId: string;
+    parties: Party[];
+    createdAt: string;
+}
+export interface Presentation {
+    presentationId: string;
+    partyRole: string;
+    status: string;
+    createdAt: string;
+}
+export interface VerificationResult {
+    handshakeId: string;
+    result: 'accepted' | 'rejected' | 'partial';
+    reasonCodes: string[];
+    evaluatedAt: string;
+}
+export interface GateResult {
+    decision: 'allow' | 'deny' | 'review';
+    commitRef?: string;
+    reasons: string[];
+    appealPath?: string;
+}
+export interface SignoffChallenge {
+    challengeId: string;
+    entityId: string;
+    scope: string;
+    nonce: string;
+    expiresAt: string;
+}
+export interface SignoffAttestation {
+    attestationId: string;
+    challengeId: string;
+    status: 'valid' | 'invalid' | 'expired';
+    signoffId?: string;
+    createdAt: string;
+}
+export interface SignoffConsumption {
+    signoffId: string;
+    consumed: boolean;
+    action: string;
+    consumedAt?: string;
+}
+export interface Consumption {
+    handshakeId: string;
+    consumed: boolean;
+    receiptId?: string;
+    consumedAt?: string;
+}
+export interface RevokeResult {
+    id: string;
+    revoked: boolean;
+    revokedAt: string;
+}
+export interface DenyResult {
+    challengeId: string;
+    denied: boolean;
+    reason?: string;
+    deniedAt: string;
+}
+export interface Delegation {
+    delegationId: string;
+    delegatorId: string;
+    delegateeId: string;
+    scope: string;
+    policyId: string;
+    status: string;
+    constraints?: Record<string, unknown>;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface DelegationVerification {
+    delegationId: string;
+    valid: boolean;
+    status: string;
+    reasonCodes: string[];
+    verifiedAt: string;
+}
+export interface Commit {
+    commitId: string;
+    handshakeId: string;
+    action: string;
+    status: string;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+export interface CommitVerification {
+    commitId: string;
+    valid: boolean;
+    status: string;
+    reasonCodes: string[];
+    verifiedAt: string;
+}
+export interface PendingSignoff {
+    challengeId: string;
+    entityId: string;
+    scope: string;
+    status: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface PendingSignoffsResponse {
+    items: PendingSignoff[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+export interface SignoffQueueItem {
+    challengeId: string;
+    entityId: string;
+    scope: string;
+    priority: string;
+    status: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface SignoffQueueResponse {
+    items: SignoffQueueItem[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+export interface SignoffDashboard {
+    pending: number;
+    approved: number;
+    denied: number;
+    expired: number;
+    averageResponseTime: number;
+    recentActivity: DashboardActivity[];
+}
+export interface DashboardActivity {
+    challengeId: string;
+    action: string;
+    entityId: string;
+    timestamp: string;
+}
+export interface SignoffAnalytics {
+    totalChallenges: number;
+    approvalRate: number;
+    averageResponseTime: number;
+    byScope: Record<string, number>;
+    timeseries: AnalyticsDataPoint[];
+}
+export interface AnalyticsDataPoint {
+    timestamp: string;
+    count: number;
+    approved: number;
+    denied: number;
+}
+export interface EscalationResult {
+    challengeId: string;
+    escalatedTo: string;
+    escalatedAt: string;
+    status: string;
+}
+export interface NotificationResult {
+    challengeId: string;
+    channel: string;
+    sent: boolean;
+    sentAt: string;
+}
+export interface AuditEvent {
+    eventId: string;
+    type: string;
+    entityId: string;
+    action: string;
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+export interface SearchEventsResponse {
+    items: AuditEvent[];
+    total: number;
+}
+export interface EventTimeline {
+    handshakeId: string;
+    events: AuditEvent[];
+}
+export interface ExportAuditResult {
+    exportId: string;
+    format: string;
+    status: string;
+    downloadUrl?: string;
+    createdAt: string;
+}
+export interface AuditReport {
+    reportType: string;
+    dateRange: DateRange;
+    summary: Record<string, unknown>;
+    items: AuditEvent[];
+    generatedAt: string;
+}
+export interface IntegrityCheckResult {
+    healthy: boolean;
+    checks: IntegrityCheck[];
+    checkedAt: string;
+}
+export interface IntegrityCheck {
+    name: string;
+    status: 'pass' | 'fail' | 'warn';
+    message?: string;
+}
+export interface PolicySimulationResult {
+    policyId: string;
+    decision: 'allow' | 'deny' | 'review';
+    reasons: string[];
+    evaluatedAt: string;
+}
+export interface PolicyRolloutResult {
+    policyId: string;
+    strategy: string;
+    percentage: number;
+    status: string;
+    startedAt: string;
+}
+export interface PolicyVersion {
+    versionId: string;
+    policyId: string;
+    version: number;
+    createdAt: string;
+    createdBy: string;
+    changelog?: string;
+}
+export interface PolicyDiff {
+    policyId: string;
+    versionA: string;
+    versionB: string;
+    changes: PolicyChange[];
+}
+export interface PolicyChange {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+    type: 'added' | 'removed' | 'modified';
+}
+export declare class EPError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+export declare class EPCloudClient {
+    private readonly _request;
+    /** @internal */
+    constructor(_request: <T>(method: string, path: string, body?: unknown, auth?: boolean) => Promise<T>);
+    /** Get pending signoffs, optionally filtered by entity, scope, or status. */
+    getPendingSignoffs(filters?: SignoffFilters): Promise<PendingSignoffsResponse>;
+    /** Get the signoff queue with optional filtering. */
+    getSignoffQueue(filters?: SignoffFilters): Promise<SignoffQueueResponse>;
+    /** Get a dashboard summary of signoff activity over a date range. */
+    getSignoffDashboard(dateRange?: DateRange): Promise<SignoffDashboard>;
+    /** Get analytics for signoff activity with optional granularity. */
+    getSignoffAnalytics(dateRange?: DateRange, granularity?: 'hour' | 'day' | 'week' | 'month'): Promise<SignoffAnalytics>;
+    /** Escalate a signoff challenge to another entity. */
+    escalateSignoff(challengeId: string, escalateTo: string, reason: string): Promise<EscalationResult>;
+    /** Send a notification about a signoff challenge via the specified channel. */
+    notifySignoff(challengeId: string, channel: string): Promise<NotificationResult>;
+    /** Search audit events by query string and optional filters. */
+    searchEvents(query: string, filters?: Record<string, unknown>): Promise<SearchEventsResponse>;
+    /** Get a chronological timeline of events for a specific handshake. */
+    getEventTimeline(handshakeId: string): Promise<EventTimeline>;
+    /** Export audit data in the specified format. */
+    exportAudit(params: ExportAuditParams): Promise<ExportAuditResult>;
+    /** Generate an audit report for the given type and date range. */
+    getAuditReport(reportType: string, dateRange: DateRange): Promise<AuditReport>;
+    /** Run an integrity check on the protocol data store. */
+    checkIntegrity(): Promise<IntegrityCheckResult>;
+    /** Simulate a policy against a hypothetical context without persisting any state. */
+    simulatePolicy(policyId: string, context: Record<string, unknown>): Promise<PolicySimulationResult>;
+    /** Begin a rollout of a policy using the specified strategy. */
+    rolloutPolicy(policyId: string, strategy: string, percentage?: number): Promise<PolicyRolloutResult>;
+    /** List all versions of a policy. */
+    getPolicyVersions(policyId: string): Promise<PolicyVersion[]>;
+    /** Diff two versions of a policy to see what changed. */
+    diffPolicyVersions(policyId: string, versionA: string, versionB: string): Promise<PolicyDiff>;
+    /** @internal Build query string from SignoffFilters. */
+    private _buildQs;
+    /** @internal Build query string from DateRange. */
+    private _buildDateRangeQs;
+    /** @internal Convert key-value pairs to a query string. */
+    private _toQs;
+}
+export declare class EPClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly retries;
+    /** Cloud-specific endpoints (dashboards, analytics, audit, policy management). */
+    readonly cloud: EPCloudClient;
+    constructor(options: EPClientOptions);
     private request;
-    /**
-     * Look up an entity's EMILIA Score.
-     * No authentication required — scores are public by design.
-     */
-    getScore(entityId: string): Promise<ScoreResult>;
-    /**
-     * Submit a transaction receipt.
-     * Requires API key.
-     */
-    submitReceipt(input: SubmitReceiptInput): Promise<ReceiptResult>;
-    /**
-     * Register a new entity.
-     * Requires API key.
-     */
-    registerEntity(input: RegisterEntityInput): Promise<RegisterResult>;
-    /**
-     * Verify a receipt against the on-chain Merkle root.
-     * No authentication required.
-     */
-    verifyReceipt(receiptId: string): Promise<VerifyResult>;
-    /**
-     * Search for entities.
-     * No authentication required.
-     */
-    searchEntities(query: string, options?: {
-        entityType?: 'agent' | 'merchant' | 'service_provider';
-        minScore?: number;
-    }): Promise<SearchResult>;
-    /**
-     * Get the leaderboard.
-     * No authentication required.
-     */
-    getLeaderboard(options?: {
-        limit?: number;
-        entityType?: 'agent' | 'merchant' | 'service_provider';
-    }): Promise<LeaderboardResult>;
-    /**
-     * Check if an entity meets a minimum trust threshold.
-     * Returns true if the entity's score >= minScore.
-     */
-    isTrusted(entityId: string, minScore?: number): Promise<boolean>;
-    /**
-     * Submit a receipt and verify the entity meets a threshold in one call.
-     * Returns the receipt result and whether the entity is still trusted.
-     */
-    submitAndCheck(input: SubmitReceiptInput, minScore?: number): Promise<ReceiptResult & {
-        still_trusted: boolean;
-    }>;
-}
-export default EmiliaClient;
+    /** List available trust policies. */
+    listPolicies(params?: {
+        scope?: string;
+    }): Promise<Policy[]>;
+    /** Initiate a trust handshake between parties. */
+    initiateHandshake(params: InitiateHandshakeParams): Promise<Handshake>;
+    /** Present credentials to a handshake. */
+    present(handshakeId: string, params: PresentParams): Promise<Presentation>;
+    /** Verify a handshake -- evaluate all presentations against policy. */
+    verify(handshakeId: string): Promise<VerificationResult>;
+    /** Pre-action trust gate. Returns allow/deny/review with commit ref. */
+    gate(params: GateParams): Promise<GateResult>;
+    /** Retrieve details of a specific handshake by ID. */
+    getHandshake(handshakeId: string): Promise<Handshake>;
+    /** Revoke an active handshake, invalidating all associated state. */
+    revokeHandshake(handshakeId: string): Promise<RevokeResult>;
+    /** Consume a handshake -- finalize and optionally bind a receipt. */
+    consume(handshakeId: string, params?: ConsumeParams): Promise<Consumption>;
+    /** Issue a signoff challenge for an entity. */
+    issueChallenge(params: IssueChallengeParams): Promise<SignoffChallenge>;
+    /** Attest to a signoff challenge with a cryptographic signature. */
+    attest(challengeId: string, params: AttestParams): Promise<SignoffAttestation>;
+    /** Deny a signoff challenge with an optional reason. */
+    denyChallenge(challengeId: string, reason?: string): Promise<DenyResult>;
+    /** Revoke a previously granted signoff. */
+    revokeSignoff(challengeId: string, options?: RevokeSignoffOptions): Promise<RevokeResult>;
+    /** Consume a signoff -- mark it as used for a specific action. */
+    consumeSignoff(signoffId: string, params: ConsumeSignoffParams): Promise<SignoffConsumption>;
+    /** Create a trust delegation from one entity to another. */
+    createDelegation(params: CreateDelegationParams): Promise<Delegation>;
+    /** Verify the validity of an existing delegation. */
+    verifyDelegation(delegationId: string): Promise<DelegationVerification>;
+    /** Issue a trust commit binding a handshake to a specific action. */
+    issueCommit(params: IssueCommitParams): Promise<Commit>;
+    /** Verify a previously issued commit. */
+    verifyCommit(commitId: string): Promise<CommitVerification>;
+    /** Record a behavioral or contextual observation for the Eye subsystem. */
+    recordObservation(params: RecordObservationParams): Promise<ObservationResponse>;
+    /** Check an action against recorded observations and return an advisory. */
+    checkAction(params: CheckActionParams): Promise<AdvisoryResponse>;
+    /** Retrieve an existing advisory by ID. */
+    getAdvisory(advisoryId: string): Promise<AdvisoryResponse>;
+    /** Create a suppression to exclude a reason code from future advisories. */
+    createSuppression(params: CreateSuppressionParams): Promise<SuppressionResponse>;
+}
+//# sourceMappingURL=index.d.ts.map