@labyrinthe/connect 0.0.0-stage → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,943 @@
+/**
+ * Public types of the SDK: camelCase versions of the API objects described in
+ * openapi/openapi.yaml. Dates are `Date` objects; enums are unions of string
+ * literals with a constant object of the same name.
+ */
+/**
+ * Lifecycle of a message.
+ *
+ * `unknown` is never sent by the API: the SDK uses it when the API returns a
+ * status this version does not know yet.
+ */
+declare const MessageStatus: {
+    /** Queued at Labyrinthe Connect. */
+    readonly Queued: "queued";
+    /** Handed over to the SMS provider. */
+    readonly Submitted: "submitted";
+    /** Accepted by the mobile operator. */
+    readonly Sent: "sent";
+    /** Delivered to the handset (final). */
+    readonly Delivered: "delivered";
+    /** Failed (final). */
+    readonly Failed: "failed";
+    /** Rejected by the provider or the operator (final). */
+    readonly Rejected: "rejected";
+    /** Expired before delivery (final). */
+    readonly Expired: "expired";
+    /** Cannot be delivered to this number (final). */
+    readonly Undeliverable: "undeliverable";
+    /** Status not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type MessageStatus = (typeof MessageStatus)[keyof typeof MessageStatus];
+/** True when the status will not change any more (delivered or failed). */
+declare function isFinalStatus(status: MessageStatus): boolean;
+/** True for `failed`, `rejected`, `expired` and `undeliverable`. */
+declare function isFailedStatus(status: MessageStatus): boolean;
+/** True for `queued`, `submitted` and `sent`. */
+declare function isPendingStatus(status: MessageStatus): boolean;
+/** Character encoding of an SMS: GSM-7 (160 characters) or UCS-2 (70 characters). */
+declare const Encoding: {
+    readonly Gsm7: "gsm7";
+    readonly Ucs2: "ucs2";
+};
+type Encoding = (typeof Encoding)[keyof typeof Encoding];
+declare const SenderIdStatus: {
+    readonly Pending: "pending";
+    readonly PendingProvider: "pending_provider";
+    readonly Approved: "approved";
+    readonly Rejected: "rejected";
+    readonly Suspended: "suspended";
+    /** Status not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type SenderIdStatus = (typeof SenderIdStatus)[keyof typeof SenderIdStatus];
+/** Why a recipient was refused (`RecipientNotSendableError`). */
+declare const RejectionReason: {
+    readonly InvalidPhone: "invalid_phone";
+    readonly Blacklisted: "blacklisted";
+    readonly OptedOut: "opted_out";
+    /** Reason not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type RejectionReason = (typeof RejectionReason)[keyof typeof RejectionReason];
+/** Why an OTP verification failed (`verified: false`). */
+declare const OtpFailureReason: {
+    /** Wrong code: one attempt was consumed, the user may try again. */
+    readonly InvalidCode: "invalid_code";
+    /** The code expired: send a new one. */
+    readonly Expired: "expired";
+    /** The code was already verified (each code is single-use). */
+    readonly AlreadyUsed: "already_used";
+    /** Too many wrong attempts: the code is permanently blocked. */
+    readonly MaxAttemptsReached: "max_attempts_reached";
+    /** Reason not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type OtpFailureReason = (typeof OtpFailureReason)[keyof typeof OtpFailureReason];
+/** Scope of an `OTP_RATE_LIMITED` error: the phone number or the whole account. */
+declare const OtpRateLimitScope: {
+    readonly Phone: "phone";
+    readonly Account: "account";
+    /** Scope not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type OtpRateLimitScope = (typeof OtpRateLimitScope)[keyof typeof OtpRateLimitScope];
+/** Alphabet of an OTP code (`otp.send()` → `codeType`). */
+declare const OtpCodeType: {
+    /** Digits 0-9. */
+    readonly Numeric: "numeric";
+    /** Upper-case letters and digits without ambiguous characters; typing is case-insensitive. */
+    readonly Alphanumeric: "alphanumeric";
+    /** Alphabet not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type OtpCodeType = (typeof OtpCodeType)[keyof typeof OtpCodeType];
+/** Final status of an OTP verification, in the `otp.verified` / `otp.failed` webhooks. */
+declare const OtpVerificationStatus: {
+    /** The right code was typed (`otp.verified`). */
+    readonly Verified: "verified";
+    /** Too many wrong attempts (`otp.failed`, reason `max_attempts_reached`). */
+    readonly Failed: "failed";
+    /** The code expired (`otp.failed`, reason `expired`). */
+    readonly Expired: "expired";
+    /** Status not known by this SDK version. */
+    readonly Unknown: "unknown";
+};
+type OtpVerificationStatus = (typeof OtpVerificationStatus)[keyof typeof OtpVerificationStatus];
+/** Webhook event types emitted by the API. */
+declare const WebhookEventType: {
+    readonly MessageStatusChanged: "message.status_changed";
+    readonly CampaignCompleted: "campaign.completed";
+    readonly BalanceLow: "balance.low";
+    readonly OtpVerified: "otp.verified";
+    readonly OtpFailed: "otp.failed";
+    readonly TestPing: "test.ping";
+};
+type WebhookEventType = (typeof WebhookEventType)[keyof typeof WebhookEventType];
+/** OTP message languages of the standard templates. */
+type OtpLocale = 'fr' | 'en';
+/** An SMS, one per recipient. The text is deliberately not returned by the API (it may contain an OTP code). */
+interface Message {
+    id: string;
+    /** Your reference, given at send time. */
+    reference: string | null;
+    /** International format without "+", e.g. "243812345678". */
+    recipient: string;
+    /** Sender shown on the handset. */
+    sender: string | null;
+    encoding: Encoding | null;
+    status: MessageStatus;
+    segments: number;
+    /** Credits charged (equal to `segments`; fictitious with a test key). */
+    creditsCharged: number;
+    /** Campaign of origin (messages sent from the client area). */
+    campaignId: string | null;
+    providerMessageId: string | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    createdAt: Date | null;
+    /** Handed over to the provider. */
+    submittedAt: Date | null;
+    /** Delivery receipt. */
+    deliveredAt: Date | null;
+}
+/** Result of `sms.sendMany()`: one message per distinct recipient. */
+interface MessageBatch {
+    messages: Message[];
+    /** The Idempotency-Key used for this send (yours, or the one generated by the SDK). */
+    idempotencyKey: string;
+    /** True when the API replayed an earlier identical request: nothing was sent or billed again. */
+    replayed: boolean;
+    /** `X-Request-Id` of the response, for the support; null when absent. */
+    requestId: string | null;
+}
+/** Cost of a send, computed by the API without sending anything. */
+interface Estimate {
+    encoding: Encoding;
+    characters: number;
+    segmentsPerMessage: number;
+    /** Valid recipients only (invalid numbers are ignored, not rejected). */
+    recipientsCount: number;
+    totalCredits: number;
+    /** Balance after the send (negative when insufficient); null if the account never had credits. */
+    balanceAfter: number | null;
+    /** True when the current balance covers the send (`balanceAfter >= 0`). */
+    isAffordable: boolean;
+}
+/** Credit balance, in SMS credits (1 credit = 1 segment). */
+interface Balance {
+    /** Available credits. */
+    balance: number;
+    /** Credits held by running campaigns. */
+    held: number;
+}
+/** An approved sender name, usable as `sender` when sending. */
+interface SenderId {
+    id: string;
+    /** The name shown on the handset, e.g. "MYSHOP" (11 characters max). */
+    value: string;
+    status: SenderIdStatus;
+    purpose: string | null;
+    rejectionReason: string | null;
+    isDefault: boolean;
+    createdAt: Date | null;
+}
+/** A refused recipient of an all-or-nothing send. */
+interface RejectedRecipient {
+    /** Number as received, or normalised. */
+    recipient: string;
+    reason: RejectionReason;
+}
+/**
+ * Result of `otp.verify()`. A wrong code is not an exception.
+ *
+ * `attemptsRemaining`: attempts still possible for this code — an integer
+ * after `invalid_code`, `0` with `max_attempts_reached`, null when the code is
+ * verified, already used or expired (and with an API older than 1.2.0).
+ */
+type OtpVerifyResult = {
+    verified: true;
+    reason: null;
+    attemptsRemaining: null;
+} | {
+    verified: false;
+    reason: OtpFailureReason;
+    attemptsRemaining: number | null;
+};
+/** What the SDK read from a successful response (`onResponse` option). */
+interface ResponseInfo {
+    /** HTTP status, e.g. 200, 201, 202. */
+    status: number;
+    /** `X-Request-Id`: yours when you passed `requestId`, otherwise generated by the API. Null when absent. */
+    requestId: string | null;
+    /** `X-Api-Version`, the major API version (e.g. "1"); null when absent. */
+    apiVersion: string | null;
+    /** `Idempotent-Replayed: true`: replay of an earlier request with the same Idempotency-Key. */
+    replayed: boolean;
+    /** `X-RateLimit-Limit` / `X-RateLimit-Remaining`; null when absent. */
+    rateLimit: {
+        limit: number | null;
+        remaining: number | null;
+    };
+    /** Every response header (lower-case names). */
+    headers: Readonly<Record<string, string>>;
+}
+/** Per-call options, accepted as the last argument of every method. */
+interface RequestOptions {
+    /** Cancels the call (including the waits between retries). */
+    signal?: AbortSignal;
+    /** Timeout of each attempt, in milliseconds (defaults to the client's `timeoutMs`). */
+    timeoutMs?: number;
+    /**
+     * Your own request identifier, sent as `X-Request-Id` (on every retry of
+     * this call) and echoed by the API in its logs and responses: 1 to 128
+     * characters among `A-Z a-z 0-9 . _ : -`. Without it, the API generates one.
+     */
+    requestId?: string;
+    /** Called with the headers of the successful response (request id, rate limit, replay…). Errors carry them too. */
+    onResponse?: (response: ResponseInfo) => void;
+}
+
+type Json = Record<string, unknown>;
+
+/** Minimal logger: `console`, pino, winston… Never receives the key, codes, bodies or full phone numbers. */
+interface Logger {
+    debug?(message: string, context?: Record<string, unknown>): void;
+    info?(message: string, context?: Record<string, unknown>): void;
+    warn?(message: string, context?: Record<string, unknown>): void;
+    error?(message: string, context?: Record<string, unknown>): void;
+}
+/** Options passed to `fetch` by the SDK. */
+interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+    redirect: 'manual';
+}
+/** The subset of the Fetch `Response` the SDK reads. */
+interface FetchResponse {
+    status: number;
+    headers: {
+        forEach(callback: (value: string, key: string) => void): void;
+    };
+    text(): Promise<string>;
+}
+/** Any WHATWG-compatible `fetch` (global fetch, undici, a mock…). */
+type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponse>;
+
+/** Credit balance (`client.balance`). */
+declare class BalanceResource {
+    #private;
+    get(options?: RequestOptions): Promise<Balance>;
+    toJSON(): Record<string, unknown>;
+}
+/** Approved Sender IDs (`client.senderIds`). */
+declare class SenderIds {
+    #private;
+    /** Sender IDs with the `approved` status, usable as `sender`. */
+    list(options?: RequestOptions): Promise<SenderId[]>;
+    toJSON(): Record<string, unknown>;
+}
+
+interface SendOtpParams {
+    /** Phone number, international or local format. */
+    phone: string;
+    /** Must contain "{code}"; optional "{app_name}", "{minutes}". Defaults to the account's OTP settings. */
+    template?: string;
+    /** Language of the standard template. Defaults to the account's OTP settings. */
+    locale?: OtpLocale;
+    /**
+     * Web OTP API: host name of the site that reads the code (e.g. "app.example.com":
+     * no scheme, port or path). The API adds the last line `@app.example.com #123456`
+     * to the SMS, so that Chrome on Android offers to fill the code automatically.
+     */
+    webOtpDomain?: string;
+    /** Replace accents and typographic characters with ASCII (GSM-7: often half the cost). Default false. */
+    stripAccents?: boolean;
+    /**
+     * Max 255 characters. Generated (UUID v4) when absent, and reused by the
+     * SDK's retries: a retried send never sends a second SMS. Pass your own to
+     * also protect against your own retries for 24 hours (a replay returns the
+     * same `otpId`, without a new SMS).
+     */
+    idempotencyKey?: string;
+}
+interface VerifyOtpParams {
+    /** The `otpId` returned by `otp.send()`, kept server-side. */
+    otpId: string;
+    /** The code typed by the user (spaces and case are ignored by the API). */
+    code: string;
+}
+declare const INSPECT$1: unique symbol;
+declare const DENO_INSPECT$1: unique symbol;
+/**
+ * Result of an OTP send. Store `otpId` server-side (session, cache…) and pass
+ * it to `otp.verify()` with the code typed by the user.
+ */
+declare class OtpSendResult {
+    #private;
+    readonly otpId: string;
+    readonly expiresAt: Date;
+    readonly maxAttempts: number;
+    /** Number of characters of the code (4 to 8, account's OTP settings); null only with an API older than 1.2.0. */
+    readonly codeLength: number | null;
+    /** `numeric` (0-9) or `alphanumeric` (case-insensitive); null only with an API older than 1.2.0. */
+    readonly codeType: OtpCodeType | null;
+    /**
+     * Seconds before a new send to this number is accepted while this code is
+     * not verified: show a "Resend the code" countdown. Null only with an API older than 1.2.0.
+     */
+    readonly resendAfterSeconds: number | null;
+    /** The Idempotency-Key of this send (yours, or the one generated by the SDK). */
+    readonly idempotencyKey: string;
+    /** True when the API replayed an earlier send with the same Idempotency-Key: no new SMS, no new charge. */
+    readonly replayed: boolean;
+    /** `X-Request-Id` of the response, for the support; null when absent. */
+    readonly requestId: string | null;
+    /**
+     * The code, ONLY with a test key (`lsk_test_…`): nothing is sent by SMS in
+     * test mode, so the API returns the code to let you test `verify()`. Always
+     * null with a live key. Never log it, never show it to end users. Hidden
+     * from `JSON.stringify()` and `console.log()`.
+     */
+    get testCode(): string | null;
+    toJSON(): {
+        otpId: string;
+        expiresAt: string;
+        maxAttempts: number;
+        codeLength: number | null;
+        codeType: OtpCodeType | null;
+        resendAfterSeconds: number | null;
+        replayed: boolean;
+        requestId: string | null;
+    };
+    [INSPECT$1](): Record<string, unknown>;
+    [DENO_INSPECT$1](): string;
+}
+/**
+ * One-time passwords by SMS (`client.otp`).
+ *
+ * 1. `send({ phone })` and keep `otpId` server-side (session);
+ * 2. the user types the code received by SMS (`codeLength`, `codeType`);
+ * 3. `verify({ otpId, code })`: log the user in when `verified` is true.
+ *
+ * Code length, alphabet, validity, attempts, anti-resend delay, sender and
+ * template come from the account's OTP settings (client area > OTP verification).
+ */
+declare class Otp {
+    #private;
+    /**
+     * Generates a code and sends it by SMS (billed like any SMS). A new send to
+     * the same number invalidates the previous code.
+     *
+     * An Idempotency-Key is always sent (generated when you give none), so the
+     * SDK retries network errors, 5xx, 429 TOO_MANY_REQUESTS and 409
+     * IDEMPOTENCY_REQUEST_IN_PROGRESS with the same key: a retry never sends a
+     * second SMS. The business limits (OTP_RESEND_TOO_SOON, OTP_RATE_LIMITED)
+     * are never retried. 503 FEATURE_DISABLED / OTP_SERVICE_DISABLED
+     * (`FeatureDisabledError`) is retried only after a `Retry-After` no longer
+     * than `maxRetryWaitMs`.
+     */
+    send(params: SendOtpParams, options?: RequestOptions): Promise<OtpSendResult>;
+    /**
+     * Checks a code. A wrong code is NOT an error: the result says
+     * `verified: false` with a `reason` and `attemptsRemaining`, and one attempt
+     * is consumed. Free. Throws `NotFoundError` for an unknown `otpId` (or one
+     * from another account).
+     *
+     * Retried only on 429 TOO_MANY_REQUESTS and on 503 FEATURE_DISABLED with a
+     * `Retry-After` no longer than `maxRetryWaitMs` (both refused before
+     * processing): after a network error or another 5xx, an attempt may have
+     * been consumed.
+     */
+    verify(params: VerifyOtpParams, options?: RequestOptions): Promise<OtpVerifyResult>;
+    toJSON(): Record<string, unknown>;
+    [INSPECT$1](): Record<string, unknown>;
+}
+
+/** One page of a paginated list. Iterate it with `for await` to walk this page and the following ones. */
+declare class Page<T> implements AsyncIterable<T> {
+    #private;
+    readonly data: T[];
+    readonly currentPage: number;
+    readonly lastPage: number;
+    readonly perPage: number;
+    readonly total: number;
+    get hasMore(): boolean;
+    /** The next page, or null on the last one. */
+    nextPage(): Promise<Page<T> | null>;
+    /** Every item from this page to the last one (pages are fetched lazily). */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Result of a list call: `await` it for the first page, or iterate it with
+ * `for await` to walk every item of every page. The first request is sent
+ * when the result is awaited or iterated.
+ */
+declare class PagePromise<T> implements PromiseLike<Page<T>>, AsyncIterable<T> {
+    #private;
+    then<R1 = Page<T>, R2 = never>(onFulfilled?: ((page: Page<T>) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onRejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<Page<T> | R>;
+    finally(onFinally?: (() => void) | null): Promise<Page<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+interface SendCommon {
+    /** Text, 1 to 1600 characters. Any non-ASCII character switches to UCS-2 (70 characters per SMS). */
+    body: string;
+    /** Approved Sender ID (see `senderIds.list()`). Defaults to the client's `defaultSender`, then the platform's. */
+    sender?: string;
+    /** Your own reference (order number…), max 64 characters, filterable with `sms.list({ reference })`. */
+    reference?: string;
+    /**
+     * Replace accents and typographic characters (curly quotes, long dashes…) with
+     * their ASCII equivalent before sending: the message switches to GSM-7, often
+     * half the cost. The transliteration depends on the server: do not rely on it
+     * for an exact text. Default false.
+     */
+    stripAccents?: boolean;
+    /**
+     * Max 255 characters. Generated (UUID v4) when absent, and reused by the
+     * SDK's retries. Pass your own (e.g. "order-1042-ready") to also protect
+     * against your own retries for 24 hours.
+     */
+    idempotencyKey?: string;
+}
+interface SendSmsParams extends SendCommon {
+    /** Phone number, international ("+243…", "243…", "00243…") or local ("0812…", "812…"). */
+    to: string;
+}
+interface SendManySmsParams extends SendCommon {
+    /** 1 to 1000 phone numbers. All or nothing: one refused number means nothing is sent. */
+    recipients: readonly string[];
+}
+interface EstimateSmsParams {
+    body: string;
+    /** Normalised and deduplicated like a send; invalid numbers are not counted (no error). */
+    recipients: string | readonly string[];
+    /** Estimate the text after `stripAccents` (see `sms.send()`). Default false. */
+    stripAccents?: boolean;
+}
+interface ListSmsParams {
+    status?: MessageStatus;
+    /** Any format, normalised before the search. */
+    recipient?: string;
+    /** Exact match. */
+    reference?: string;
+    /** Inclusive: a date ("2026-11-01") or a date-time. */
+    from?: Date | string;
+    /** Inclusive: a date covers the whole day. */
+    to?: Date | string;
+    /** Default 1. */
+    page?: number;
+    /** 1 to 100, default 15. */
+    perPage?: number;
+}
+/** Send and track SMS (`client.sms`). */
+declare class Sms {
+    #private;
+    /**
+     * Sends one SMS. Asynchronous: the returned message is `queued`; follow its
+     * status with webhooks (`message.status_changed`) or `get()`.
+     *
+     * An Idempotency-Key is always sent, so network errors are retried safely:
+     * the SMS is never sent twice.
+     */
+    send(params: SendSmsParams, options?: RequestOptions): Promise<Message>;
+    /**
+     * Sends the same SMS to several recipients (up to 1000), all or nothing: if
+     * a single recipient is refused, nothing is sent and a
+     * `RecipientNotSendableError` lists every refused number. Duplicates are
+     * merged by the API (one message per distinct number).
+     */
+    sendMany(params: SendManySmsParams, options?: RequestOptions): Promise<MessageBatch>;
+    /** Computes encoding, segments and credits without sending anything. */
+    estimate(params: EstimateSmsParams, options?: RequestOptions): Promise<Estimate>;
+    /** One message of the account, by id. Throws `NotFoundError` when unknown. */
+    get(id: string, options?: RequestOptions): Promise<Message>;
+    /**
+     * Messages sent with this API key, newest first.
+     *
+     *     const page = await client.sms.list({ status: 'failed' });   // one page
+     *     for await (const message of client.sms.list()) { … }         // every page
+     */
+    list(params?: ListSmsParams, options?: RequestOptions): PagePromise<Message>;
+    toJSON(): Record<string, unknown>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.labyrinthe-rdc.com/api/public/v1";
+interface LabyrintheOptions {
+    /** `lsk_live_…` or `lsk_test_…`. Defaults to `process.env.LABYRINTHE_API_KEY`. Keep it server-side. */
+    apiKey?: string;
+    /**
+     * API root. Defaults to `process.env.LABYRINTHE_BASE_URL`, then production.
+     * A bare host ("http://localhost:8000") is completed with `/api/public/v1`.
+     */
+    baseUrl?: string;
+    /** Timeout of each attempt, in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Automatic retries, only when they are safe (0 disables them). Default 2, max 10. */
+    maxRetries?: number;
+    /**
+     * Longest wait accepted before a retry (Retry-After), in milliseconds. Default 10000.
+     * A 503 FEATURE_DISABLED is retried only when its Retry-After fits in this wait.
+     */
+    maxRetryWaitMs?: number;
+    /** Added to local numbers: "0812345678" → "243812345678". Default "243" (DR Congo). */
+    defaultCountryCode?: string;
+    /** Sender ID used when `sms.send()` gets none. */
+    defaultSender?: string;
+    /** Custom `fetch` implementation (defaults to the global `fetch`). */
+    fetch?: FetchLike;
+    /** Receives debug/info/warn/error logs: no key, no code, no body, masked phone numbers. */
+    logger?: Logger;
+    /**
+     * The API key gives full access to your account: it must never reach a
+     * browser. The client refuses to start in a browser unless this is true.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+declare const INSPECT: unique symbol;
+declare const DENO_INSPECT: unique symbol;
+/**
+ * Labyrinthe Connect API client.
+ *
+ *     const client = new Labyrinthe({ apiKey: 'lsk_test_…' });
+ *     const message = await client.sms.send({ to: '0812345678', body: 'Hello!' });
+ *
+ * Keys starting with `lsk_test_` use the sandbox: nothing is sent, no credit
+ * is used, responses have the same shape as in production.
+ */
+declare class Labyrinthe {
+    #private;
+    /** Send and track SMS. */
+    readonly sms: Sms;
+    /** Credit balance. */
+    readonly balance: BalanceResource;
+    /** Approved Sender IDs. */
+    readonly senderIds: SenderIds;
+    /** One-time passwords by SMS. */
+    readonly otp: Otp;
+    constructor(options?: LabyrintheOptions);
+    /** True with a sandbox key (`lsk_test_…`): nothing is sent, no credit is used. */
+    get isTestMode(): boolean;
+    /** True with a production key (`lsk_live_…`). */
+    get isLiveMode(): boolean;
+    /** The API root used by this client. */
+    get baseUrl(): string;
+    toJSON(): Record<string, unknown>;
+    [INSPECT](): Record<string, unknown>;
+    [DENO_INSPECT](): string;
+}
+
+/** SDK version, sent in the User-Agent header. Kept in sync with package.json (checked by the tests). */
+declare const VERSION = "1.2.0";
+
+/** Error codes documented by the API. The list is open: new codes may appear. */
+type ApiErrorCode = 'UNAUTHENTICATED' | 'FORBIDDEN' | 'ACCOUNT_SUSPENDED' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'TOO_MANY_REQUESTS' | 'INSUFFICIENT_CREDITS' | 'IDEMPOTENCY_KEY_REUSED' | 'IDEMPOTENCY_KEY_UNRESOLVED' | 'IDEMPOTENCY_REQUEST_IN_PROGRESS' | 'RECIPIENT_NOT_SENDABLE' | 'SENDER_ID_NOT_APPROVED' | 'INVALID_PHONE' | 'INVALID_OTP_TEMPLATE' | 'OTP_RESEND_TOO_SOON' | 'OTP_RATE_LIMITED' | 'OTP_DISABLED_FOR_ACCOUNT' | 'OTP_SERVICE_DISABLED' | 'FEATURE_DISABLED' | 'HTTP_ERROR';
+/** Codes of the errors raised by the SDK itself (no API response). */
+type SdkErrorCode = 'CONNECTION_ERROR' | 'TIMEOUT' | 'REQUEST_ABORTED' | 'INVALID_ARGUMENT' | 'UNEXPECTED_RESPONSE' | 'SIGNATURE_VERIFICATION_FAILED' | 'INVALID_WEBHOOK_PAYLOAD';
+/** Known codes, or any other string (the `string & {}` keeps autocompletion on the known ones). */
+type ErrorCode = ApiErrorCode | SdkErrorCode | (string & {});
+type ErrorDetails = Record<string, unknown>;
+/**
+ * Base class of every error thrown by the SDK: catch it to handle any
+ * Labyrinthe Connect failure in one place.
+ *
+ * Always switch on `code` (stable), never on `message` (API messages are in
+ * French, for humans).
+ */
+declare class LabyrintheError extends Error {
+    /** Stable machine-readable code, e.g. "INSUFFICIENT_CREDITS" or "TIMEOUT". */
+    readonly code: ErrorCode;
+    /** HTTP status of the response; null when there was no response (network, timeout, local validation…). */
+    readonly status: number | null;
+    /** Error details, depending on the code (`{}` when there are none). */
+    readonly details: ErrorDetails;
+    constructor(message: string, code: ErrorCode, status?: number | null, details?: ErrorDetails);
+}
+/**
+ * The API answered with an error (`{ "error": { "code", "message", "details" } }`).
+ * Subclasses exist for the codes an integration usually handles; any other
+ * code (including codes added to the API later) is thrown as a plain ApiError.
+ */
+declare class ApiError extends LabyrintheError {
+    readonly status: number;
+    /** Response headers (lower-case names). */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(message: string, code: ErrorCode, status: number, details?: ErrorDetails, headers?: Record<string, string>);
+    /**
+     * Request identifier (`X-Request-Id` response header): give it to the
+     * Labyrinthe support. Yours when you passed `requestId`, otherwise
+     * generated by the API; null only when the response had none.
+     */
+    get requestId(): string | null;
+    /** Major API version that served the response (`X-Api-Version`, e.g. "1"); null when absent. */
+    get apiVersion(): string | null;
+    protected detailInt(key: string): number | null;
+}
+/** 401: missing, invalid or revoked API key. */
+declare class AuthenticationError extends ApiError {
+}
+/**
+ * 403: IP not allowed for this key (`FORBIDDEN`), OTP disabled for the
+ * account (`OTP_DISABLED_FOR_ACCOUNT`) or account suspended
+ * (`ACCOUNT_SUSPENDED`, see `AccountSuspendedError`).
+ */
+declare class PermissionError extends ApiError {
+}
+/**
+ * 403 ACCOUNT_SUSPENDED: the account was suspended by the platform. The whole
+ * API is closed until it is reactivated: retrying does not help, contact the
+ * Labyrinthe support (with `requestId`).
+ */
+declare class AccountSuspendedError extends PermissionError {
+}
+/** 404: unknown message or `otpId` (or one from another account). */
+declare class NotFoundError extends ApiError {
+}
+/** 422 VALIDATION_ERROR: one or more fields are missing or invalid. */
+declare class ValidationError extends ApiError {
+    /** Error messages per field, e.g. `{ body: ["Le champ body est obligatoire."] }`. */
+    get fieldErrors(): Record<string, string[]>;
+}
+/**
+ * 422 RECIPIENT_NOT_SENDABLE: at least one recipient is invalid, blacklisted
+ * or opted out. Sending is all-or-nothing: NOTHING was sent and no credit
+ * was used. Remove the `rejected` numbers and send again.
+ */
+declare class RecipientNotSendableError extends ApiError {
+    /** Reason of the first rejection. */
+    get reason(): RejectionReason;
+    /** Every rejected recipient (`sms.send` / `sms.sendMany`). Empty for OTP sends. */
+    get rejected(): RejectedRecipient[];
+}
+/** 422 SENDER_ID_NOT_APPROVED: `sender` is not an approved Sender ID of the account. */
+declare class SenderIdNotApprovedError extends ApiError {
+}
+/** 422 INVALID_PHONE: the phone number cannot be used (OTP). */
+declare class InvalidPhoneError extends ApiError {
+}
+/** 409 INSUFFICIENT_CREDITS: the balance does not cover the whole send. Nothing was sent. */
+declare class InsufficientCreditsError extends ApiError {
+    /** Credits available on the account. */
+    get available(): number | null;
+    /** Credits needed for this send. */
+    get required(): number | null;
+}
+/** 409 IDEMPOTENCY_KEY_REUSED: the same Idempotency-Key was used for a different request. */
+declare class IdempotencyKeyReusedError extends ApiError {
+}
+/**
+ * 409 IDEMPOTENCY_KEY_UNRESOLVED (POST /sms, POST /otp/send): the original
+ * request with this Idempotency-Key failed unexpectedly and its outcome is
+ * unknown: an SMS may have been sent. The SDK never retries it. Do not retry
+ * automatically: check first (`sms.list({ reference })`, or ask the user
+ * whether the code arrived), then send again with a NEW idempotency key.
+ */
+declare class IdempotencyKeyUnresolvedError extends ApiError {
+}
+/**
+ * 409 IDEMPOTENCY_REQUEST_IN_PROGRESS: the original request with this
+ * Idempotency-Key is still being processed. The SDK already retried it with
+ * the same key after `Retry-After`; when you get this error, wait
+ * `retryAfterMs` and call again with the same `idempotencyKey` (safe: nothing
+ * can be sent twice).
+ */
+declare class IdempotencyRequestInProgressError extends ApiError {
+    /** Milliseconds to wait (Retry-After header or `details.retry_after_seconds`); null when the API does not say. */
+    get retryAfterMs(): number | null;
+}
+/**
+ * 429: too many requests. The SDK already retried TOO_MANY_REQUESTS when it
+ * was safe to do so; when you get this error, wait `retryAfterMs`.
+ */
+declare class RateLimitError extends ApiError {
+    /**
+     * Milliseconds to wait before retrying, from the Retry-After header or
+     * `details.retry_after_seconds`; null when the API does not say.
+     */
+    get retryAfterMs(): number | null;
+}
+/**
+ * 429 OTP_RESEND_TOO_SOON: a code was sent to this number too recently. Never
+ * retried; show a countdown of `retryAfterMs` (Retry-After header, equal to
+ * `details.retry_after_seconds`).
+ */
+declare class OtpResendTooSoonError extends RateLimitError {
+}
+/**
+ * 429 OTP_RATE_LIMITED: hourly cap reached for this phone number or for the
+ * whole account. Never retried; `retryAfterMs` is the time before the sliding
+ * one-hour window falls back under the cap.
+ */
+declare class OtpRateLimitedError extends RateLimitError {
+    get scope(): OtpRateLimitScope;
+    /** The hourly cap that was reached. */
+    get limit(): number | null;
+}
+/** 5xx, including 503 FEATURE_DISABLED and OTP_SERVICE_DISABLED (see `FeatureDisabledError`). */
+declare class ServiceUnavailableError extends ApiError {
+}
+/**
+ * 503 FEATURE_DISABLED: a platform administrator temporarily shut down the
+ * whole API (`blockedBy` = "api") or one function ("api.sms_send",
+ * "api.otp_send", "api.otp_verify"). Also 503 OTP_SERVICE_DISABLED (whole OTP
+ * service off, `feature` = `blockedBy` = "otp"). Nothing was done: no SMS
+ * sent, no credit used.
+ *
+ * Never retried with blind backoff: the SDK retries only when the API gives a
+ * `Retry-After` no longer than `maxRetryWaitMs` (automatic re-enable
+ * scheduled), waiting exactly that long. Otherwise, treat the call as a
+ * temporary failure (queue it, tell the user, show `adminMessage`).
+ */
+declare class FeatureDisabledError extends ServiceUnavailableError {
+    /** Feature requested by the call ("api", "api.sms_send", "api.otp_send", "api.otp_verify", "otp"… open list). */
+    get feature(): string | null;
+    /** Feature actually shut down: `feature` itself or a parent (e.g. "api" when the whole API is off). */
+    get blockedBy(): string | null;
+    /** Message written by the administrator (`details.message`), null when there is none. */
+    get adminMessage(): string | null;
+    /** Scheduled automatic re-enable (`details.until`), null when unknown or invalid. */
+    get until(): Date | null;
+    /** Seconds until the scheduled re-enable (`Retry-After` header), null when the API does not say. */
+    get retryAfter(): number | null;
+    /** Same as `retryAfter`, in milliseconds (`Retry-After` header only), null when absent. */
+    get retryAfterMs(): number | null;
+    private detailString;
+}
+/**
+ * The API could not be reached (DNS, TLS, connection refused…).
+ *
+ * `sms.send()`, `sms.sendMany()` and `otp.send()` carry an Idempotency-Key:
+ * they were already retried, and calling again with the same `idempotencyKey`
+ * is safe. For `otp.verify()` the request may or may not have been processed
+ * (an attempt may have been consumed): the SDK never retries it after a
+ * network error.
+ */
+declare class ConnectionError extends LabyrintheError {
+    constructor(message: string, code?: ErrorCode);
+}
+/** An attempt took longer than `timeoutMs`. */
+declare class TimeoutError extends ConnectionError {
+    constructor(message: string);
+}
+/** The call was cancelled through its `signal`. Never retried. */
+declare class RequestAbortedError extends LabyrintheError {
+    constructor(message?: string);
+}
+/** Invalid input detected by the SDK, before any network call. */
+declare class InvalidArgumentError extends LabyrintheError {
+    constructor(message: string);
+}
+/** A successful response that the SDK cannot read (not JSON, missing field…). */
+declare class UnexpectedResponseError extends LabyrintheError {
+    constructor(message: string, status?: number | null);
+}
+/** A webhook failed verification: missing or wrong signature, or a timestamp outside the tolerance. Answer 400. */
+declare class SignatureVerificationError extends LabyrintheError {
+    constructor(message: string);
+}
+/** A correctly signed webhook body is not a valid event envelope. Answer 400. */
+declare class InvalidWebhookPayloadError extends LabyrintheError {
+    constructor(message: string);
+}
+
+/** Default country code added to local numbers (DR Congo). */
+declare const DEFAULT_COUNTRY_CODE = "243";
+/**
+ * Phone number helpers, consistent with the API's own normalisation.
+ *
+ * `normalize()` returns international digits without "+" (e.g. "243812345678"), the format of API
+ * responses. Requests carry the same number in E.164 with "+" ("+243812345678"), so the API keeps the
+ * country code of a short foreign number.
+ * Accepted input formats (with the default country code 243, DR Congo):
+ *
+ *  - "+243 81 234 5678", "00243812345678" → "243812345678" (explicit international prefix kept)
+ *  - "243812345678"                       → "243812345678"
+ *  - "0812345678", "812345678"            → "243812345678" (local format, 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)
+ *
+ * Idempotent, like the API: normalising an output again does not change it.
+ * For a short foreign number (10 digits or less), always use the "+".
+ *
+ * Validation is deliberately light (8 to 15 digits, E.164): the API remains
+ * the authority on whether a number can receive SMS.
+ */
+declare const PhoneNumber: Readonly<{
+    /** Normalises a number, or returns null when it cannot be a valid phone number. */
+    normalize(raw: string, defaultCountryCode?: string): string | null;
+    /** Normalises a number or throws an InvalidArgumentError (the number itself is never part of the message). */
+    normalizeOrThrow(raw: string, defaultCountryCode?: string, field?: string): string;
+    isValid(raw: string, defaultCountryCode?: string): boolean;
+    /** Masks a number for logs: "243812345678" → "24381*****78". */
+    mask(phone: string): string;
+}>;
+
+/** Name of the signature header. */
+declare const SIGNATURE_HEADER = "X-Signature";
+/** Default maximum age of a delivery, in seconds. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Fields shared by every event. */
+interface EventEnvelope {
+    /** Event identifier, identical across delivery attempts: deduplicate on it. */
+    id: string;
+    /** Event name exactly as sent by the API, e.g. "message.status_changed" (also for unknown events). */
+    type: string;
+    /** Time of this delivery attempt (signed). */
+    timestamp: Date;
+    /** Decoded envelope `{ id, event, data, timestamp }`, as sent by the API. */
+    raw: Json;
+}
+interface MessageStatusChangedEvent extends EventEnvelope {
+    event: 'message.status_changed';
+    data: {
+        messageId: string;
+        recipient: string;
+        status: MessageStatus;
+        providerMessageId: string | null;
+        campaignId: string | null;
+        /** The `reference` given at send time (`sms.send({ reference })`). */
+        reference: string | null;
+        /** Provider or platform error code when the message failed. */
+        errorCode: string | null;
+        errorMessage: string | null;
+    };
+}
+interface CampaignCompletedEvent extends EventEnvelope {
+    event: 'campaign.completed';
+    data: {
+        campaignId: string;
+        name: string;
+        recipientsCount: number;
+        /** Number of messages per final status, e.g. `{ delivered: 1150, failed: 30 }`. */
+        messagesByStatus: Partial<Record<MessageStatus, number>> & Record<string, number>;
+        creditsCharged: number;
+        completedAt: Date | null;
+    };
+}
+interface BalanceLowEvent extends EventEnvelope {
+    event: 'balance.low';
+    data: {
+        /** Balance after the operation that crossed the threshold. */
+        balance: number;
+        threshold: number;
+    };
+}
+/** Outcome of an OTP verification (`otp.verified`, `otp.failed`). Never contains the code. */
+interface OtpWebhookData {
+    otpId: string;
+    /** Normalised number (international, no "+"). */
+    phone: string;
+    /** `verified` with `otp.verified`; `failed` or `expired` with `otp.failed`. */
+    status: OtpVerificationStatus;
+    /** Null when verified; `max_attempts_reached` (status `failed`) or `expired` (status `expired`). */
+    reason: 'max_attempts_reached' | 'expired' | 'unknown' | null;
+    /** Verification date; null for `otp.failed`. */
+    verifiedAt: Date | null;
+}
+/** A code was verified (sent once, after `otp.verify()` got the right code — API or client area console). */
+interface OtpVerifiedEvent extends EventEnvelope {
+    event: 'otp.verified';
+    data: OtpWebhookData;
+}
+/** A verification failed for good: attempts exhausted or code expired (sent once). */
+interface OtpFailedEvent extends EventEnvelope {
+    event: 'otp.failed';
+    data: OtpWebhookData;
+}
+interface TestPingEvent extends EventEnvelope {
+    event: 'test.ping';
+    data: Json;
+}
+/**
+ * An event type added to the API after this SDK version. Its signature was
+ * verified: `type` holds its name and `data` its content (as sent, snake_case).
+ * Acknowledge it with a 2xx. (`event` is the constant "unknown" so that
+ * `switch (event.event)` narrows the known events.)
+ */
+interface UnknownEvent extends EventEnvelope {
+    event: 'unknown';
+    data: Json;
+}
+/** A verified webhook event: switch on `event` to get the typed `data`. */
+type WebhookEvent = MessageStatusChangedEvent | CampaignCompletedEvent | BalanceLowEvent | OtpVerifiedEvent | OtpFailedEvent | TestPingEvent | UnknownEvent;
+interface ConstructEventOptions {
+    /** Max age of the signed timestamp, in seconds; 0 disables the check (not recommended). Default 300. */
+    toleranceSeconds?: number;
+    /** Current time (tests). */
+    now?: Date | number;
+}
+/** Raw request body: the exact bytes, or the text decoded as UTF-8. Never a re-encoded object. */
+type RawBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Webhook verification, with Web Crypto (Node, edge runtimes, Deno, Bun).
+ *
+ *     const event = await Webhooks.constructEvent(rawBody, request.headers.get('x-signature'), secret);
+ *
+ * The signature (`X-Signature: sha256=<hex HMAC-SHA256 of the raw body>`) is
+ * checked in constant time on the RAW body, before any JSON parsing; then the
+ * signed `timestamp` must be within the tolerance (replay protection).
+ */
+declare const Webhooks: Readonly<{
+    SIGNATURE_HEADER: "X-Signature";
+    DEFAULT_TOLERANCE_SECONDS: 300;
+    /**
+     * Verifies a delivery and returns the typed event.
+     *
+     * @throws SignatureVerificationError wrong/missing signature or timestamp out of tolerance: answer 400
+     * @throws InvalidWebhookPayloadError signed body that is not a valid envelope: answer 400
+     */
+    constructEvent(rawBody: RawBody, signatureHeader: string | null | undefined, secret: string, options?: ConstructEventOptions): Promise<WebhookEvent>;
+    /** Constant-time check of the X-Signature header against the raw body. */
+    verifySignature(rawBody: RawBody, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+    /** The X-Signature header value for a body: "sha256=<hex>". Useful to test your webhook endpoint. */
+    sign(rawBody: RawBody, secret: string): Promise<string>;
+}>;
+
+export { AccountSuspendedError, ApiError, type ApiErrorCode, AuthenticationError, type Balance, type BalanceLowEvent, BalanceResource, type CampaignCompletedEvent, ConnectionError, type ConstructEventOptions, DEFAULT_BASE_URL, DEFAULT_COUNTRY_CODE, DEFAULT_TOLERANCE_SECONDS, Encoding, type ErrorCode, type ErrorDetails, type Estimate, type EstimateSmsParams, FeatureDisabledError, type FetchInit, type FetchLike, type FetchResponse, IdempotencyKeyReusedError, IdempotencyKeyUnresolvedError, IdempotencyRequestInProgressError, InsufficientCreditsError, InvalidArgumentError, InvalidPhoneError, InvalidWebhookPayloadError, Labyrinthe, LabyrintheError, type LabyrintheOptions, type ListSmsParams, type Logger, type Message, type MessageBatch, MessageStatus, type MessageStatusChangedEvent, NotFoundError, Otp, OtpCodeType, type OtpFailedEvent, OtpFailureReason, type OtpLocale, OtpRateLimitScope, OtpRateLimitedError, OtpResendTooSoonError, OtpSendResult, OtpVerificationStatus, type OtpVerifiedEvent, type OtpVerifyResult, type OtpWebhookData, Page, PagePromise, PermissionError, PhoneNumber, RateLimitError, type RawBody, RecipientNotSendableError, type RejectedRecipient, RejectionReason, RequestAbortedError, type RequestOptions, type ResponseInfo, SIGNATURE_HEADER, type SdkErrorCode, type SendManySmsParams, type SendOtpParams, type SendSmsParams, type SenderId, SenderIdNotApprovedError, SenderIdStatus, SenderIds, ServiceUnavailableError, SignatureVerificationError, Sms, type TestPingEvent, TimeoutError, UnexpectedResponseError, type UnknownEvent, VERSION, ValidationError, type VerifyOtpParams, type WebhookEvent, WebhookEventType, Webhooks, isFailedStatus, isFinalStatus, isPendingStatus };