@labyrinthe/otp-widget 0.0.0-stage → 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+/**
+ * Protocole JSON entre le widget (navigateur) et le serveur de l'intégrateur
+ * (`@labyrinthe/otp-widget/server`). Le navigateur ne voit jamais la clé API,
+ * ni `otp_id`, ni le code envoyé : seulement ce qui suit.
+ *
+ *     POST {sendUrl}    { "phone": "+243812345678", "locale": "fr", "send_id": "…" }
+ *       200 → SendSuccessBody            erreur → ErrorBody
+ *     POST {verifyUrl}  { "code": "482913" }
+ *       200 → VerifySuccessBody | VerifyFailureBody     erreur → ErrorBody
+ */
+/** Why a code was refused (same values as the Labyrinthe API `reason`). */
+type OtpFailureReason = 'invalid_code' | 'expired' | 'already_used' | 'max_attempts_reached';
+/** Error codes sent by the server helper (stable, lower case). */
+type ServerErrorCode = 
+/** The phone number cannot be used (invalid, blacklisted or opted out). */
+'invalid_phone'
+/** A code was sent to this number too recently: wait `retry_after_seconds`. */
+ | 'resend_too_soon'
+/** Too many requests (per number, per account or per API key). */
+ | 'rate_limited'
+/** No code is pending for this browser (cookie missing, expired or tampered with): send a new one. */
+ | 'no_pending_verification'
+/** Refused by the integrator (`beforeSend`) or by the origin / content-type checks. */
+ | 'forbidden'
+/** Malformed request (missing field, wrong content type…). */
+ | 'invalid_request'
+/**
+ * OTP service unavailable (Labyrinthe unreachable, misconfiguration, no credits…), or temporarily shut down by the
+ * Labyrinthe platform (FEATURE_DISABLED / OTP_SERVICE_DISABLED, maintenance): then `admin_message`, `until` and
+ * `retry_after_seconds` may be present.
+ */
+ | 'service_unavailable'
+/** The integrator's Labyrinthe account is suspended (ACCOUNT_SUSPENDED): nothing the user can do. */
+ | 'account_suspended'
+/**
+ * The send failed unexpectedly on the Labyrinthe side and its outcome is unknown (IDEMPOTENCY_KEY_UNRESOLVED):
+ * a code may have been sent. Never retried automatically; the user may ask for a new code (sent with a new key).
+ */
+ | 'send_failed'
+/** Unexpected server error. */
+ | 'server_error';
+/** Every error code the widget can report: server codes, refusal reasons and client-side errors. */
+type OtpWidgetErrorCode = ServerErrorCode | OtpFailureReason | 'network_error' | 'incomplete_code';
+type CodeType = 'numeric' | 'alphanumeric';
+interface SendSuccessBody {
+    sent: true;
+    /** Masked number, for display ("+243 81•••••78"). */
+    phone_masked: string;
+    /** ISO 8601. */
+    expires_at: string;
+    max_attempts: number;
+    /** Seconds before "Resend" is enabled (account's anti-resend delay, returned by the API). */
+    resend_after_seconds: number;
+    /** Code length / alphabet (account's OTP settings, returned by the API 1.2.0, or the server's override). */
+    code_length?: number;
+    code_type?: CodeType;
+    /** ONLY when the integrator enabled `exposeTestCode` in development, with a `lsk_test_` key. */
+    test_code?: string;
+}
+interface VerifySuccessBody {
+    verified: true;
+    /** Whatever the integrator's `onVerified` returned (e.g. `{ redirect: "/dashboard" }`). */
+    data?: unknown;
+}
+interface VerifyFailureBody {
+    verified: false;
+    reason: OtpFailureReason;
+    /** Attempts left for this code (`attempts_remaining` of the API; estimated with an older SDK); null when unknown. */
+    attempts_left: number | null;
+}
+interface ErrorBody {
+    error: {
+        code: ServerErrorCode;
+        message: string;
+        retry_after_seconds?: number;
+        /** Maintenance only: message written by the Labyrinthe platform administrator, meant for end users. */
+        admin_message?: string;
+        /** Maintenance only: scheduled end (ISO 8601). */
+        until?: string;
+    };
+}
+
+/**
+ * Texts of the widget. Placeholders: `{phone}`, `{time}`, `{count}`, `{index}`,
+ * `{total}`, `{code}`. Override any of them with the `texts` property (or React prop).
+ */
+interface OtpWidgetTexts {
+    title: string;
+    phoneLabel: string;
+    countryCodeLabel: string;
+    phonePlaceholder: string;
+    phoneHint: string;
+    send: string;
+    sending: string;
+    codeLabel: string;
+    codeSentTo: string;
+    /** Accessible name of each code box. */
+    cellLabel: string;
+    verify: string;
+    verifying: string;
+    changePhone: string;
+    resend: string;
+    resendIn: string;
+    resendAvailable: string;
+    attemptsLeftOne: string;
+    attemptsLeftOther: string;
+    success: string;
+    testMode: string;
+    /** Appended to `errors.service_unavailable` (or the maintenance message) when the end of a maintenance is known. */
+    retryIn: string;
+    errors: Record<OtpWidgetErrorCode, string>;
+}
+type OtpWidgetLocale = 'fr' | 'en';
+/** Partial override: top-level keys and `errors` entries are merged with the locale defaults. */
+type OtpWidgetTextsOverride = Partial<Omit<OtpWidgetTexts, 'errors'>> & {
+    errors?: Partial<OtpWidgetTexts['errors']>;
+};
+declare const LOCALES: Readonly<Record<OtpWidgetLocale, OtpWidgetTexts>>;
+/** Default texts of a locale merged with an override. */
+declare function resolveTexts(locale: string | null | undefined, override?: OtpWidgetTextsOverride | null): OtpWidgetTexts;
+
+declare const TAG_NAME = "labyrinthe-otp";
+declare const EVENT_SENT = "labyrinthe-otp:sent";
+declare const EVENT_VERIFIED = "labyrinthe-otp:verified";
+declare const EVENT_ERROR = "labyrinthe-otp:error";
+type OtpWidgetStep = 'phone' | 'code' | 'success';
+/** `labyrinthe-otp:sent` — a code was sent (first send or resend). */
+interface OtpSentDetail {
+    /** Normalised number (international, no "+"). */
+    phone: string;
+    phoneMasked: string;
+    expiresAt: Date;
+    maxAttempts: number;
+    resendAfterSeconds: number;
+    /** Only when the server exposes it (test key, development). */
+    testCode?: string;
+}
+/** `labyrinthe-otp:verified` — the code was accepted by the server. */
+interface OtpVerifiedDetail {
+    phone: string;
+    /** What the integrator's `onVerified` returned. */
+    data: unknown;
+}
+/** `labyrinthe-otp:error` — anything that went wrong; `message` is the localised text shown to the user. */
+interface OtpErrorDetail {
+    code: OtpWidgetErrorCode;
+    message: string;
+    /** HTTP status of the server response; null for local and network errors. */
+    status: number | null;
+    retryAfterSeconds?: number;
+    attemptsLeft?: number | null;
+    /** `service_unavailable` during a Labyrinthe maintenance: the administrator's message (shown instead of the text). */
+    adminMessage?: string;
+    /** `service_unavailable` during a Labyrinthe maintenance: scheduled end, when known. */
+    until?: Date;
+}
+/** Public API of the `<labyrinthe-otp>` element. */
+interface LabyrintheOtpElement extends HTMLElement {
+    /** Current step. */
+    readonly step: OtpWidgetStep;
+    /** Text overrides (merged with the locale defaults). */
+    texts: OtpWidgetTextsOverride | null;
+    /** Extra headers sent to your endpoints (e.g. a CSRF token). */
+    requestHeaders: Record<string, string>;
+    /** Back to the phone step, clearing the code. */
+    reset(): void;
+}
+
+/**
+ * Normalisation des numéros, identique à celle du SDK Node (`PhoneNumber.normalize`
+ * de `@labyrinthe/connect`) et de l'API. Copiée ici pour garder le widget sans
+ * dépendance ; un test vérifie la parité avec le SDK.
+ */
+/** Default country code added to local numbers (DR Congo). */
+declare const DEFAULT_COUNTRY_CODE = "243";
+/**
+ * Normalises a phone number to the API format (international, digits only, no "+"),
+ * or returns null when it cannot be a valid number.
+ *
+ *  - "+243 81 234 5678", "00243812345678", "243812345678" → "243812345678"
+ *  - "0812345678", "812345678" → "243812345678" (default country code added)
+ *  - "+33 6 12 34 56 78" → "33612345678" (other countries are never blocked)
+ *  - "33612345678" → "33612345678" (no "+", 11 digits or more not starting with 0: already international)
+ */
+declare function normalizePhone(raw: string, defaultCountryCode?: string): string | null;
+/** Masks a number for display and logs: "243812345678" → "+243 81•••••78". */
+declare function maskPhone(phone: string): string;
+
+declare const VERSION = "1.2.0";
+
+/**
+ * `<labyrinthe-otp>`: phone verification by SMS code, ready to use.
+ *
+ *     <script type="module">import '@labyrinthe/otp-widget';</script>
+ *     <labyrinthe-otp send-url="/api/otp/send" verify-url="/api/otp/verify"></labyrinthe-otp>
+ *
+ * The widget only talks to YOUR server (see `@labyrinthe/otp-widget/server`):
+ * no API key, no `otp_id` and no code ever reach the browser.
+ *
+ * Importing this module defines the element when `customElements` exists;
+ * on a server (SSR) it does nothing.
+ */
+
+/**
+ * Defines `<labyrinthe-otp>` (or another tag name) and returns its class.
+ * Idempotent; returns undefined where custom elements do not exist (SSR).
+ */
+declare function defineLabyrintheOtp(tagName?: string): CustomElementConstructor | undefined;
+declare global {
+    interface HTMLElementTagNameMap {
+        'labyrinthe-otp': LabyrintheOtpElement;
+    }
+}
+
+export { type CodeType, DEFAULT_COUNTRY_CODE, EVENT_ERROR, EVENT_SENT, EVENT_VERIFIED, type ErrorBody, LOCALES, type LabyrintheOtpElement, type OtpErrorDetail, type OtpFailureReason, type OtpSentDetail, type OtpVerifiedDetail, type OtpWidgetErrorCode, type OtpWidgetLocale, type OtpWidgetStep, type OtpWidgetTexts, type OtpWidgetTextsOverride, type SendSuccessBody, type ServerErrorCode, TAG_NAME, VERSION, type VerifyFailureBody, type VerifySuccessBody, defineLabyrintheOtp, maskPhone, normalizePhone, resolveTexts };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Protocole JSON entre le widget (navigateur) et le serveur de l'intégrateur
+ * (`@labyrinthe/otp-widget/server`). Le navigateur ne voit jamais la clé API,
+ * ni `otp_id`, ni le code envoyé : seulement ce qui suit.
+ *
+ *     POST {sendUrl}    { "phone": "+243812345678", "locale": "fr", "send_id": "…" }
+ *       200 → SendSuccessBody            erreur → ErrorBody
+ *     POST {verifyUrl}  { "code": "482913" }
+ *       200 → VerifySuccessBody | VerifyFailureBody     erreur → ErrorBody
+ */
+/** Why a code was refused (same values as the Labyrinthe API `reason`). */
+type OtpFailureReason = 'invalid_code' | 'expired' | 'already_used' | 'max_attempts_reached';
+/** Error codes sent by the server helper (stable, lower case). */
+type ServerErrorCode = 
+/** The phone number cannot be used (invalid, blacklisted or opted out). */
+'invalid_phone'
+/** A code was sent to this number too recently: wait `retry_after_seconds`. */
+ | 'resend_too_soon'
+/** Too many requests (per number, per account or per API key). */
+ | 'rate_limited'
+/** No code is pending for this browser (cookie missing, expired or tampered with): send a new one. */
+ | 'no_pending_verification'
+/** Refused by the integrator (`beforeSend`) or by the origin / content-type checks. */
+ | 'forbidden'
+/** Malformed request (missing field, wrong content type…). */
+ | 'invalid_request'
+/**
+ * OTP service unavailable (Labyrinthe unreachable, misconfiguration, no credits…), or temporarily shut down by the
+ * Labyrinthe platform (FEATURE_DISABLED / OTP_SERVICE_DISABLED, maintenance): then `admin_message`, `until` and
+ * `retry_after_seconds` may be present.
+ */
+ | 'service_unavailable'
+/** The integrator's Labyrinthe account is suspended (ACCOUNT_SUSPENDED): nothing the user can do. */
+ | 'account_suspended'
+/**
+ * The send failed unexpectedly on the Labyrinthe side and its outcome is unknown (IDEMPOTENCY_KEY_UNRESOLVED):
+ * a code may have been sent. Never retried automatically; the user may ask for a new code (sent with a new key).
+ */
+ | 'send_failed'
+/** Unexpected server error. */
+ | 'server_error';
+/** Every error code the widget can report: server codes, refusal reasons and client-side errors. */
+type OtpWidgetErrorCode = ServerErrorCode | OtpFailureReason | 'network_error' | 'incomplete_code';
+type CodeType = 'numeric' | 'alphanumeric';
+interface SendSuccessBody {
+    sent: true;
+    /** Masked number, for display ("+243 81•••••78"). */
+    phone_masked: string;
+    /** ISO 8601. */
+    expires_at: string;
+    max_attempts: number;
+    /** Seconds before "Resend" is enabled (account's anti-resend delay, returned by the API). */
+    resend_after_seconds: number;
+    /** Code length / alphabet (account's OTP settings, returned by the API 1.2.0, or the server's override). */
+    code_length?: number;
+    code_type?: CodeType;
+    /** ONLY when the integrator enabled `exposeTestCode` in development, with a `lsk_test_` key. */
+    test_code?: string;
+}
+interface VerifySuccessBody {
+    verified: true;
+    /** Whatever the integrator's `onVerified` returned (e.g. `{ redirect: "/dashboard" }`). */
+    data?: unknown;
+}
+interface VerifyFailureBody {
+    verified: false;
+    reason: OtpFailureReason;
+    /** Attempts left for this code (`attempts_remaining` of the API; estimated with an older SDK); null when unknown. */
+    attempts_left: number | null;
+}
+interface ErrorBody {
+    error: {
+        code: ServerErrorCode;
+        message: string;
+        retry_after_seconds?: number;
+        /** Maintenance only: message written by the Labyrinthe platform administrator, meant for end users. */
+        admin_message?: string;
+        /** Maintenance only: scheduled end (ISO 8601). */
+        until?: string;
+    };
+}
+
+/**
+ * Texts of the widget. Placeholders: `{phone}`, `{time}`, `{count}`, `{index}`,
+ * `{total}`, `{code}`. Override any of them with the `texts` property (or React prop).
+ */
+interface OtpWidgetTexts {
+    title: string;
+    phoneLabel: string;
+    countryCodeLabel: string;
+    phonePlaceholder: string;
+    phoneHint: string;
+    send: string;
+    sending: string;
+    codeLabel: string;
+    codeSentTo: string;
+    /** Accessible name of each code box. */
+    cellLabel: string;
+    verify: string;
+    verifying: string;
+    changePhone: string;
+    resend: string;
+    resendIn: string;
+    resendAvailable: string;
+    attemptsLeftOne: string;
+    attemptsLeftOther: string;
+    success: string;
+    testMode: string;
+    /** Appended to `errors.service_unavailable` (or the maintenance message) when the end of a maintenance is known. */
+    retryIn: string;
+    errors: Record<OtpWidgetErrorCode, string>;
+}
+type OtpWidgetLocale = 'fr' | 'en';
+/** Partial override: top-level keys and `errors` entries are merged with the locale defaults. */
+type OtpWidgetTextsOverride = Partial<Omit<OtpWidgetTexts, 'errors'>> & {
+    errors?: Partial<OtpWidgetTexts['errors']>;
+};
+declare const LOCALES: Readonly<Record<OtpWidgetLocale, OtpWidgetTexts>>;
+/** Default texts of a locale merged with an override. */
+declare function resolveTexts(locale: string | null | undefined, override?: OtpWidgetTextsOverride | null): OtpWidgetTexts;
+
+declare const TAG_NAME = "labyrinthe-otp";
+declare const EVENT_SENT = "labyrinthe-otp:sent";
+declare const EVENT_VERIFIED = "labyrinthe-otp:verified";
+declare const EVENT_ERROR = "labyrinthe-otp:error";
+type OtpWidgetStep = 'phone' | 'code' | 'success';
+/** `labyrinthe-otp:sent` — a code was sent (first send or resend). */
+interface OtpSentDetail {
+    /** Normalised number (international, no "+"). */
+    phone: string;
+    phoneMasked: string;
+    expiresAt: Date;
+    maxAttempts: number;
+    resendAfterSeconds: number;
+    /** Only when the server exposes it (test key, development). */
+    testCode?: string;
+}
+/** `labyrinthe-otp:verified` — the code was accepted by the server. */
+interface OtpVerifiedDetail {
+    phone: string;
+    /** What the integrator's `onVerified` returned. */
+    data: unknown;
+}
+/** `labyrinthe-otp:error` — anything that went wrong; `message` is the localised text shown to the user. */
+interface OtpErrorDetail {
+    code: OtpWidgetErrorCode;
+    message: string;
+    /** HTTP status of the server response; null for local and network errors. */
+    status: number | null;
+    retryAfterSeconds?: number;
+    attemptsLeft?: number | null;
+    /** `service_unavailable` during a Labyrinthe maintenance: the administrator's message (shown instead of the text). */
+    adminMessage?: string;
+    /** `service_unavailable` during a Labyrinthe maintenance: scheduled end, when known. */
+    until?: Date;
+}
+/** Public API of the `<labyrinthe-otp>` element. */
+interface LabyrintheOtpElement extends HTMLElement {
+    /** Current step. */
+    readonly step: OtpWidgetStep;
+    /** Text overrides (merged with the locale defaults). */
+    texts: OtpWidgetTextsOverride | null;
+    /** Extra headers sent to your endpoints (e.g. a CSRF token). */
+    requestHeaders: Record<string, string>;
+    /** Back to the phone step, clearing the code. */
+    reset(): void;
+}
+
+/**
+ * Normalisation des numéros, identique à celle du SDK Node (`PhoneNumber.normalize`
+ * de `@labyrinthe/connect`) et de l'API. Copiée ici pour garder le widget sans
+ * dépendance ; un test vérifie la parité avec le SDK.
+ */
+/** Default country code added to local numbers (DR Congo). */
+declare const DEFAULT_COUNTRY_CODE = "243";
+/**
+ * Normalises a phone number to the API format (international, digits only, no "+"),
+ * or returns null when it cannot be a valid number.
+ *
+ *  - "+243 81 234 5678", "00243812345678", "243812345678" → "243812345678"
+ *  - "0812345678", "812345678" → "243812345678" (default country code added)
+ *  - "+33 6 12 34 56 78" → "33612345678" (other countries are never blocked)
+ *  - "33612345678" → "33612345678" (no "+", 11 digits or more not starting with 0: already international)
+ */
+declare function normalizePhone(raw: string, defaultCountryCode?: string): string | null;
+/** Masks a number for display and logs: "243812345678" → "+243 81•••••78". */
+declare function maskPhone(phone: string): string;
+
+declare const VERSION = "1.2.0";
+
+/**
+ * `<labyrinthe-otp>`: phone verification by SMS code, ready to use.
+ *
+ *     <script type="module">import '@labyrinthe/otp-widget';</script>
+ *     <labyrinthe-otp send-url="/api/otp/send" verify-url="/api/otp/verify"></labyrinthe-otp>
+ *
+ * The widget only talks to YOUR server (see `@labyrinthe/otp-widget/server`):
+ * no API key, no `otp_id` and no code ever reach the browser.
+ *
+ * Importing this module defines the element when `customElements` exists;
+ * on a server (SSR) it does nothing.
+ */
+
+/**
+ * Defines `<labyrinthe-otp>` (or another tag name) and returns its class.
+ * Idempotent; returns undefined where custom elements do not exist (SSR).
+ */
+declare function defineLabyrintheOtp(tagName?: string): CustomElementConstructor | undefined;
+declare global {
+    interface HTMLElementTagNameMap {
+        'labyrinthe-otp': LabyrintheOtpElement;
+    }
+}
+
+export { type CodeType, DEFAULT_COUNTRY_CODE, EVENT_ERROR, EVENT_SENT, EVENT_VERIFIED, type ErrorBody, LOCALES, type LabyrintheOtpElement, type OtpErrorDetail, type OtpFailureReason, type OtpSentDetail, type OtpVerifiedDetail, type OtpWidgetErrorCode, type OtpWidgetLocale, type OtpWidgetStep, type OtpWidgetTexts, type OtpWidgetTextsOverride, type SendSuccessBody, type ServerErrorCode, TAG_NAME, VERSION, type VerifyFailureBody, type VerifySuccessBody, defineLabyrintheOtp, maskPhone, normalizePhone, resolveTexts };