// SPDX-FileCopyrightText: 2025 Contributors to the CitrineOS Project
//
// SPDX-License-Identifier: Apache-2.0

import type { IModule } from '@interfaces/modules/Module.js';

/**
 * Interface for the ocpp router
 */
export interface IMessageRouter extends IModule {
  networkHook: (identifier: string, message: string) => Promise<void>;

  /**
   * Register a connection to the message handler with the given connection identifier.
   *
   * @param {number} tenantId
   * @param ocppConnectionName - The connection name of the charging station
   * @param {string} protocol - The protocol of the Websocket.
   * @return {Promise<boolean>} true if both request and response subscriptions are successful, false otherwise
   */
  registerConnection(
    tenantId: number,
    ocppConnectionName: string,
    protocol: string,
  ): Promise<boolean>;
  deregisterConnection(tenantId: number, ocppConnectionName: string): Promise<boolean>;

  /**
   * Check if a charging station exists for a given tenant.
   *
   * @param tenantId The tenant ID.
   * @param ocppConnectionName - The connection name of the charging station
   * @returns true if the station exists for this tenant, false otherwise
   */
  doesChargingStationExistByStationId?(
    tenantId: number,
    ocppConnectionName: string,
  ): Promise<boolean>;

  /**
   * Receive a message from the Network Connection.
   * Timestamp here should be when the message was received from the charger.
   * If CitrineOS is running behind cloud infrastructure, it is optimal for the timestamp to be generated when the infrastructure receives the message rather than when CitrineOS is first notified.
   * Otherwise, lag or outages could result in a desync, causing CitrineOS to process messages as if they had been generated long after the charging station actually sent them.
   *
   * @param identifier Unique identifier for the charging station, i.e. the combination of tenantId and ocppConnectionName.
   * @param message The unvalidated, raw OCPP text, i.e. [2, "123", "Heartbeat", {}]
   * @param timestamp Time at which the message was received from the charger.
   * @param protocol The OCPP protocol version of the message
   * @returns true if the message was successfully processed, false otherwise
   */
  onMessage(
    identifier: string,
    message: string,
    timestamp: Date,
    protocol: string,
  ): Promise<boolean>;
}
