/**
 * مزوّد إرسال OTP واحد (docs/17 — D5؛ نمط سيرو auth/otp/providers.php).
 *
 * كل مزوّد يرسل رمزاً **نولّده نحن** (لا يولّده المزوّد) — فالرمز يبقى مصدره
 * السيرفر ومخزَّناً في Redis، والمزوّد قناة توصيل فقط. هذا يختلف عن مزوّد
 * Intaleq عند سيرو الذي يولّد الرمز بنفسه ويرجعه — استبعدناه عمداً حفاظاً على
 * مصدر واحد للرمز.
 */
export interface OtpSendContext {
  /** دولة المستأجر (jo | sy | eg) — تحدّد المزوّد. */
  countryPack: string;
  /** passenger | driver | admin | service — لتخصيص نصّ الرسالة. */
  userType?: string;
}

export interface OtpProvider {
  /** اسم قصير للتشخيص واللوغ. */
  readonly name: string;

  /** الدول التي يخدمها هذا المزوّد (رموز countryPack). */
  supports(countryPack: string): boolean;

  /**
   * يرسل الرمز. يرجع `true` عند النجاح المؤكَّد فقط — أي فشل أو استجابة
   * غامضة = `false` كي يجرّب المُوزِّع المزوّد التالي في السلسلة.
   * **لا يرمي**: الرمي يقطع سلسلة الـfailover.
   */
  send(phone: string, code: string, ctx: OtpSendContext): Promise<boolean>;
}

export const OTP_PROVIDERS = Symbol('OTP_PROVIDERS');