Subversion Repositories SmartDukaan

package com.spice.profitmandi.service.lms;

import com.spice.profitmandi.dao.entity.auth.AuthUser;
import com.spice.profitmandi.dao.entity.user.LeadCall;
import com.spice.profitmandi.dao.enumuration.dtr.LeadCallProvider;

import java.io.InputStream;

/**
 * The seam between the LMS and whichever telephony vendor actually places the call.
 *
 * <p>Exists because the two candidate providers work in opposite directions: Vonage's Client SDK
 * places the call <em>from the browser</em> once we hand it a token, while Knowlarity places it
 * <em>from the server</em> and rings the agent's handset first. {@link Handshake} is what lets the
 * LMS front-end treat both the same — it either receives a token to dial with, or is told the call is
 * already on its way.
 *
 * <p>Everything else in the LMS (the {@code user.lead_call} history, DND, disposition binding, the
 * recording gate) is provider-agnostic and sits above this interface, so swapping vendors — which the
 * India VoIP position may yet force — does not reach into the lead record.
 */
public interface LmsDialerProvider {

    /** How a call gets started, from the browser's point of view. */
    enum Mode {
        /** Browser dials over WebRTC using {@link Handshake#token}. */
        WEBRTC,
        /** Server already placed the call; the agent's own handset will ring. */
        SERVER_PLACED
    }

    /** What the browser needs in order to start, or the reason it cannot. */
    class Handshake {
        public final boolean ok;
        public final Mode mode;
        /** Client credential for WEBRTC mode; null otherwise. Treat as a secret. */
        public final String token;
        /** Vonage application id, or the vendor's equivalent, when the client SDK needs it. */
        public final String applicationId;
        public final String reason;

        private Handshake(boolean ok, Mode mode, String token, String applicationId, String reason) {
            this.ok = ok;
            this.mode = mode;
            this.token = token;
            this.applicationId = applicationId;
            this.reason = reason;
        }

        public static Handshake webrtc(String token, String applicationId) {
            return new Handshake(true, Mode.WEBRTC, token, applicationId, null);
        }

        public static Handshake serverPlaced() {
            return new Handshake(true, Mode.SERVER_PLACED, null, null, null);
        }

        /** Refuse with a reason the agent can act on — never a bare failure. */
        public static Handshake refuse(String reason) {
            return new Handshake(false, null, null, null, reason);
        }
    }

    /**
     * Place the call server-side. Only meaningful for {@link Mode#SERVER_PLACED} providers — a
     * WebRTC provider dials from the browser and refuses this.
     *
     * @return the vendor's call id, stored so state can be polled and the recording found later
     */
    String placeCall(AuthUser agent, String agentEndpoint, String toNumber) throws Exception;

    LeadCallProvider provider();

    /** False when credentials are absent, so the UI can hide the dialer rather than fail mid-call. */
    boolean isConfigured();

    /** Prepare this agent to place a call. Never throws for an unprovisioned agent — refuses instead. */
    Handshake prepare(AuthUser agent);

    /**
     * Open the vendor's copy of a call recording for archival. The caller owns the stream and must
     * close it. Returns null when the vendor has no recording for this call.
     */
    InputStream fetchRecording(LeadCall call) throws Exception;

    /** A recording the vendor holds, before we have copied it anywhere. */
    class RecordingRef {
        /** The vendor's recording id, stored on {@code lead_call.recording_uuid}. */
        public final String id;
        public final int durationSeconds;

        public RecordingRef(String id, int durationSeconds) {
            this.id = id;
            this.durationSeconds = durationSeconds;
        }
    }

    /**
     * Find the vendor's recording for a finished call, or null if there is not one (yet).
     *
     * <p>Needed by providers that place calls server-side: they get no recording webhook, so the only
     * way a recording is ever attached to a lead is by asking after the fact. The default returns null
     * for webhook-driven providers, which are told about their recordings and have nothing to look up.
     */
    default RecordingRef findRecording(LeadCall call) {
        return null;
    }
}