Definitions

Feedback

import { type OccupantRole } from "../timeline/types";

export type OccupantRoleFeedbackResult =
  | "ACCEPTED"
  | "TRANSPORT_IS_PROVISIONAL"
  | "TRANSPORT_TYPE_NOT_SUPPORTED"
  | "TRANSPORT_NOT_FOUND"
  | "TRANSPORT_NOT_YET_COMPLETE"
  | "FEEDBACK_ALREADY_PROVIDED"
  | "UNEXPECTED_ERROR";

export type OccupantRoleFeedback = Exclude<OccupantRole, "UNAVAILABLE">;

/**
 * The vehicle crash detection feedback.
 */
export type VehicleCrashDetectionFeedback = {
    /**
     * Indicates that this is feedback for a crash that did occur.
     */
    type: "CRASH";
    /**
     * The epoch time of the crash event reported by the Sentiance SDK.
     */
    crashTimeEpoch: number;
    /**
     * Whether the Sentiance SDK detected and reported the crash.
     */
    wasCrashDetectedBySentiance: boolean;
    /**
     * The location where the crash happened.
     */
    crashLocation?: {
        latitude: number;
        longitude: number;
    };
} | {
    /**
     * Indicates that this is feedback for a crash that did not occur.
     */
    type: "NO_CRASH";
    /**
     * The date of the crash event reported by the Sentiance SDK.
     */
    eventTimeEpoch: number;
};

/**
 * Result of submitting vehicle crash detection feedback.
 *
 * - `ACCEPTED`: Feedback accepted.
 * - `INVALID_EVENT_DATE`: The event/crash date specified in the {@link VehicleCrashDetectionFeedback} is either in the future, or is too old.
 * - `INVALID_LOCATION`: The location coordinates specified in the {@link VehicleCrashDetectionFeedback} are invalid.
 * - `FEEDBACK_ALREADY_PROVIDED`: Feedback has already been provided for an event with the provided date.
 * - `NO_USER`: No Sentiance user on the device.
 */
export type VehicleCrashDetectionFeedbackResult = 
  | "ACCEPTED" 
  | "INVALID_EVENT_DATE" 
  | "INVALID_LOCATION" 
  | "FEEDBACK_ALREADY_PROVIDED" 
  | "NO_USER";

export interface SentianceFeedback {
    /**
     * Submits feedback for the detected occupant role of a specified transport.
     *
     * @remarks
     * This feedback is utilized to enhance the accuracy of occupant role detection
     * in future transport instances. It is important to note that submitting feedback
     * will not alter the occupant role currently assigned to the transport.
     *
     * @param transportId The identifier of the transport for which feedback is being provided.
     * @param occupantRoleFeedback The correct occupant role.
     *
     * @returns A Promise that resolves with a result object that you can use to check whether feedback was successfully
     * submitted, or if it failed for a certain reason.
     *
     * @example
     * ```typescript
     * import {submitOccupantRoleFeedback} from "@sentiance-react-native/event-timeline";
     *
     * const transportId = "some_transport_id";
     * let result = await submitOccupantRoleFeedback(transportId, "DRIVER");
     * ```
     */
    submitOccupantRoleFeedback(transportId: string, occupantRoleFeedback: OccupantRoleFeedback): Promise<OccupantRoleFeedbackResult>;
    
    /**
     * Submits feedback about a vehicle crash, whether it was detected and reported by the
     * Sentiance SDK or occurred in real life but was not detected.
     *
     * @remarks
     * This feedback is used by Sentiance to analyze incidents and improve the accuracy
     * and reliability of future crash detections.
     *
     * @param vehicleCrashDetectionFeedback The vehicle crash detection feedback.
     *
     * @returns A Promise that resolves with a result object that you can use to check whether feedback was successfully
     * submitted, or if it failed for a certain reason.
     *
     * @example
     * ```typescript
     * import {submitVehicleCrashDetectionFeedback} from "@sentiance-react-native/event-timeline";
     *
     * const feedback: VehicleCrashDetectionFeedback = {
     *     type: "CRASH",
     *     crashTimeEpoch: 1761048047000,
     *     wasCrashDetectedBySentiance: true,
     *     crashLocation: {
     *         latitude: 5.66,
     *         longitude: -2.45
     *     }
     * };
     * const result = await submitVehicleCrashDetectionFeedback(feedback);
     *
     * switch (result) {
     *   case "ACCEPTED": {
     *     console.log("Feedback accepted.");
     *     break;
     *   }
     *   case "INVALID_EVENT_DATE": {
     *     console.warn("The provided event date is in the future, or too old.");
     *     break;
     *   }
     *   case "INVALID_LOCATION": {
     *     console.warn("The provided crash location was invalid.");
     *     break;
     *   }
     *   case "FEEDBACK_ALREADY_PROVIDED": {
     *     console.warn("Feedback already provided for an event with the given date.");
     *     break;
     *   }
     *   case "NO_USER": {
     *     console.warn("SDK not initialized with a user.");
     *     break;
     *   }
     *   default: {
     *     // Exhaustiveness check
     *     const _exhaustive: never = result;
     *     throw new Error(`Unhandled result: ${_exhaustive}`);
     *   }
     * }
     * ```
     */
    submitVehicleCrashDetectionFeedback(vehicleCrashDetectionFeedback: VehicleCrashDetectionFeedback): Promise<VehicleCrashDetectionFeedbackResult>;
}