Telephony

export interface CallAuthorization {
    operation: "create" | "read" | "hangup" | "reconcile" | "event";
    identity: CallIdentity;
    request: OutboundCallRequest;
    ref?: CallReference;
}

export type CallErrorCode = "invalid-input" | "unauthorized" | "conflict" | "not-found" | "capacity" | "aborted" | "timeout" | "provider-rejected" | "provider-unavailable" | "invalid-response" | "unresolved" | "store-unavailable";

export type CallFailureOutcome = "not-dispatched" | "rejected" | "unknown";

export interface CallHangupResult {
    ref: CallReference;
    /** Acceptance of the command is not terminal call evidence. */
    acknowledged: true;
}

/** Host-verified identity. Never populate this from a dial payload or webhook alone. */
export interface CallIdentity {
    tenantId: string;
    userId: string;
}

export interface CallIntentKey {
    tenantId: string;
    intentId: string;
}

export interface CallIntentRecord {
    request: OutboundCallRequest;
    providerId: string;
    digest: string;
    revision: number;
    creation: "dispatching" | "accepted" | "rejected" | "unknown";
    snapshot?: CallSnapshot;
    hangup: "none" | "dispatching" | "acknowledged" | "unknown" | "rejected";
    errorCode?: CallErrorCode;
}

/** Production implementations MUST make claim and revision CAS atomic and durable.
 * Never expire unresolved entries: eviction permits a duplicate outbound call.
 * Scope the unique index to tenantId + intentId, and enforce immutable request/digest/provider.
 */
export interface CallIntentStore {
    claim(record: CallIntentRecord): Promise<{
        claimed: boolean;
        record: CallIntentRecord;
    }>;
    get(key: CallIntentKey): Promise<CallIntentRecord | undefined>;
    compareAndSet(key: CallIntentKey, revision: number, next: CallIntentRecord): Promise<boolean>;
}

export interface CallOperationOptions {
    /** Aborts local waiting/network, never promises a remote hangup. */
    signal?: AbortSignal;
    timeoutMs?: number;
}

export interface CallReference {
    providerId: string;
    routeId: string;
    callId: string;
    /** Only LiveKit uses these, with a configured room and deterministic participant. */
    roomName?: string;
    participantIdentity?: string;
}

export interface CallRouteConfig {
    routeId: string;
    /** A host allowlist, snapshotted when the provider is constructed. */
    allowedFrom: readonly string[];
}

export interface CallSnapshot {
    ref: CallReference;
    status: CallStatus;
    /** Bounded native status; no raw responses, credentials or recording URLs. */
    providerStatus: string;
}

export type CallStatus = "queued" | "ringing" | "active" | "completed" | "busy" | "no-answer" | "cancelled" | "failed" | "unknown";

export declare function createExotelCallProvider(config: ExotelCallConfig): OutboundCallProvider;

export declare function createLiveKitSipCallProvider(config: LiveKitSipCallConfig): OutboundCallProvider;

/** SignalWire Compatibility/cXML API; not the separate SWML Calling API. */
export declare function createSignalWireCallProvider(config: SignalWireCallConfig): OutboundCallProvider;

export declare function createTelnyxCallProvider(config: TelnyxCallConfig): OutboundCallProvider;

/** Twilio Programmable Voice Call resource (2010-04-01). */
export declare function createTwilioCallProvider(config: TwilioCallConfig): OutboundCallProvider;

export declare function createVonageCallProvider(config: VonageCallConfig): OutboundCallProvider;

export interface ExotelCallConfig extends TelephonyHttpConfig {
    accountSid: string;
    region: "mumbai" | "singapore";
    /** AgentStream endpoint operated by the host. Media framing remains host-owned. */
    streamUrl: string;
    statusCallbackUrl?: string;
}

/** Local/test store only. It does not survive process loss or coordinate multiple workers. */
export declare class InMemoryCallIntentStore implements CallIntentStore {
    constructor(maxIntents?: number);
    claim(value: CallIntentRecord): Promise<{
        claimed: boolean;
        record: CallIntentRecord;
    }>;
    get(value: CallIntentKey): Promise<CallIntentRecord | undefined>;
    compareAndSet(value: CallIntentKey, revision: number, next: CallIntentRecord): Promise<boolean>;
}

export interface LiveKitCallRoomPort {
    getParticipant(roomName: string, identity: string): Promise<{
        identity: string;
        attributes: Record<string, string>;
    }>;
    removeParticipant(roomName: string, identity: string): Promise<unknown>;
}

export interface LiveKitSipCallConfig extends CallRouteConfig {
    sip: LiveKitSipCallPort;
    rooms: LiveKitCallRoomPort;
    trunkId: string;
    /** Host-owned room. Use one route per room, never accept a caller-supplied room. */
    roomName: string;
    timeoutMs?: number;
}

/** Structural subset of livekit-server-sdk SipClient; no SDK import or credentials. */
export interface LiveKitSipCallPort {
    createSipParticipant(trunkId: string, number: string, roomName: string, options: {
        participantIdentity: string;
        fromNumber: string;
        waitUntilAnswered: false;
        hidePhoneNumber: true;
    }): Promise<{
        participantIdentity: string;
        roomName: string;
        sipCallId: string;
    }>;
}

export interface NormalizedCallEvent extends CallSnapshot {
    eventId?: string;
    occurredAt?: string;
}

export interface OutboundCallProvider {
    readonly id: string;
    readonly routeId: string;
    readonly capabilities: Readonly<{
        transport: "http" | "livekit-sip";
        /** All supplied adapters require reconciliation after ambiguous dispatch. */
        automaticCreateRetry: false;
        callbackVerification: "host";
        hangup: "call" | "active-legs" | "sip-participant";
    }>;
    create(request: OutboundCallRequest, options?: CallOperationOptions): Promise<CallSnapshot>;
    get(ref: CallReference, options?: CallOperationOptions): Promise<CallSnapshot>;
    hangup(ref: CallReference, options?: CallOperationOptions): Promise<CallHangupResult>;
    /** Parse only AFTER the host verifies provider signature, account, freshness and replay. */
    normalizeVerifiedEvent(payload: unknown): NormalizedCallEvent;
}

export interface OutboundCallRequest {
    /** Stable within the tenant; persisted before dispatch. Reuse only for identical input. */
    intentId: string;
    identity: CallIdentity;
    routeId: string;
    to: string;
    from: string;
}

export declare class OutboundCallService {
    constructor(config: OutboundCallServiceConfig);
    create(value: OutboundCallRequest, options?: CallOperationOptions): Promise<CallIntentRecord>;
    getIntent(identity: CallIdentity, intentId: string): Promise<CallIntentRecord>;
    get(identity: CallIdentity, intentId: string, options?: CallOperationOptions): Promise<CallIntentRecord>;
    hangup(identity: CallIdentity, intentId: string, options?: CallOperationOptions): Promise<CallIntentRecord>;
    /** Host must establish correspondence to the original intent independently (provider logs/callback).
     * A failed/unknown create is never retried here. Binding cannot replace a known call.
     */
    reconcile(identity: CallIdentity, intentId: string, ref: CallReference, options?: CallOperationOptions): Promise<CallIntentRecord>;
    /** The host verifies signatures/account/freshness before invoking; no HTTP webhook endpoint is exposed. */
    applyVerifiedEvent(identity: CallIdentity, intentId: string, event: NormalizedCallEvent): Promise<CallIntentRecord>;
}

export interface OutboundCallServiceConfig {
    providers: readonly OutboundCallProvider[];
    store: CallIntentStore;
    /** Required for every operation, including deduplicated reads and callbacks. */
    authorize: (request: CallAuthorization) => boolean | Promise<boolean>;
}

export interface SignalWireCallConfig extends TwilioCallConfig {
    spaceUrl: string;
}

/** Safe to log: does not retain raw provider errors, payloads, URLs or credential causes. */
export declare class TelephonyError extends Error {
    readonly code: CallErrorCode;
    readonly outcome: CallFailureOutcome;
    readonly httpStatus?: number | undefined;
    constructor(code: CallErrorCode, outcome: CallFailureOutcome, httpStatus?: number | undefined);
}

export interface TelephonyHttpConfig extends CallRouteConfig {
    /** Resolves a complete Authorization header; allows rotating Basic/Bearer credentials. */
    authorization: () => string | Promise<string>;
    fetch?: typeof globalThis.fetch;
    timeoutMs?: number;
}

export interface TelnyxCallConfig extends TelephonyHttpConfig {
    connectionId: string;
    webhookUrl?: string;
}

export interface TwilioCallConfig extends TelephonyHttpConfig {
    accountSid: string;
    answerUrl: string;
    statusCallbackUrl?: string;
}

export interface VonageCallConfig extends TelephonyHttpConfig {
    answerUrl: string;
    eventUrl?: string;
    /** Official regional API origins may be selected by the host. */
    apiOrigin?: "https://api.nexmo.com" | "https://api-us.vonage.com" | "https://api-eu.vonage.com" | "https://api-ap.vonage.com";
}