@labyrinthe/connect 0.0.0-stage → 1.2.0

package/dist/index.js

@@ -0,0 +1,1667 @@
+// src/errors.ts
+var LabyrintheError = class extends Error {
+  /** Stable machine-readable code, e.g. "INSUFFICIENT_CREDITS" or "TIMEOUT". */
+  code;
+  /** HTTP status of the response; null when there was no response (network, timeout, local validation…). */
+  status;
+  /** Error details, depending on the code (`{}` when there are none). */
+  details;
+  constructor(message, code, status = null, details = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var ApiError = class extends LabyrintheError {
+  /** Response headers (lower-case names). */
+  headers;
+  constructor(message, code, status, details = {}, headers = {}) {
+    super(message, code, status, details);
+    this.headers = headers;
+  }
+  /**
+   * 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() {
+    return this.headers["x-request-id"] ?? null;
+  }
+  /** Major API version that served the response (`X-Api-Version`, e.g. "1"); null when absent. */
+  get apiVersion() {
+    return this.headers["x-api-version"] ?? null;
+  }
+  detailInt(key) {
+    return toInt(this.details[key]);
+  }
+};
+var AuthenticationError = class extends ApiError {
+};
+var PermissionError = class extends ApiError {
+};
+var AccountSuspendedError = class extends PermissionError {
+};
+var NotFoundError = class extends ApiError {
+};
+var ValidationError = class extends ApiError {
+  /** Error messages per field, e.g. `{ body: ["Le champ body est obligatoire."] }`. */
+  get fieldErrors() {
+    const errors = {};
+    for (const [field, messages] of Object.entries(this.details)) {
+      const list = Array.isArray(messages) ? messages : [messages];
+      errors[field] = list.filter((m) => ["string", "number", "boolean"].includes(typeof m)).map(String);
+    }
+    return errors;
+  }
+};
+var RecipientNotSendableError = class extends ApiError {
+  /** Reason of the first rejection. */
+  get reason() {
+    return rejectionReason(this.details["reason"]);
+  }
+  /** Every rejected recipient (`sms.send` / `sms.sendMany`). Empty for OTP sends. */
+  get rejected() {
+    const rejected = this.details["rejected"];
+    if (!Array.isArray(rejected)) {
+      return [];
+    }
+    const items = [];
+    for (const item of rejected) {
+      if (isRecord(item) && typeof item["recipient"] === "string") {
+        items.push({ recipient: item["recipient"], reason: rejectionReason(item["reason"]) });
+      }
+    }
+    return items;
+  }
+};
+var SenderIdNotApprovedError = class extends ApiError {
+};
+var InvalidPhoneError = class extends ApiError {
+};
+var InsufficientCreditsError = class extends ApiError {
+  /** Credits available on the account. */
+  get available() {
+    return this.detailInt("available");
+  }
+  /** Credits needed for this send. */
+  get required() {
+    return this.detailInt("required");
+  }
+};
+var IdempotencyKeyReusedError = class extends ApiError {
+};
+var IdempotencyKeyUnresolvedError = class extends ApiError {
+};
+var IdempotencyRequestInProgressError = class extends ApiError {
+  /** Milliseconds to wait (Retry-After header or `details.retry_after_seconds`); null when the API does not say. */
+  get retryAfterMs() {
+    return retryAfterMsOf(this.headers, this.details);
+  }
+};
+var RateLimitError = class 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() {
+    return retryAfterMsOf(this.headers, this.details);
+  }
+};
+var OtpResendTooSoonError = class extends RateLimitError {
+};
+var OtpRateLimitedError = class extends RateLimitError {
+  get scope() {
+    const scope = this.details["scope"];
+    return scope === "phone" || scope === "account" ? scope : "unknown";
+  }
+  /** The hourly cap that was reached. */
+  get limit() {
+    return this.detailInt("limit");
+  }
+};
+var ServiceUnavailableError = class extends ApiError {
+};
+var FeatureDisabledError = class extends ServiceUnavailableError {
+  /** Feature requested by the call ("api", "api.sms_send", "api.otp_send", "api.otp_verify", "otp"… open list). */
+  get feature() {
+    return this.detailString("feature");
+  }
+  /** Feature actually shut down: `feature` itself or a parent (e.g. "api" when the whole API is off). */
+  get blockedBy() {
+    return this.detailString("blocked_by");
+  }
+  /** Message written by the administrator (`details.message`), null when there is none. */
+  get adminMessage() {
+    return this.detailString("message");
+  }
+  /** Scheduled automatic re-enable (`details.until`), null when unknown or invalid. */
+  get until() {
+    const value = this.details["until"];
+    if (typeof value !== "string" || value === "") {
+      return null;
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  /** Seconds until the scheduled re-enable (`Retry-After` header), null when the API does not say. */
+  get retryAfter() {
+    const ms = this.retryAfterMs;
+    return ms === null ? null : Math.ceil(ms / 1e3);
+  }
+  /** Same as `retryAfter`, in milliseconds (`Retry-After` header only), null when absent. */
+  get retryAfterMs() {
+    return retryAfterMsOf(this.headers, {});
+  }
+  detailString(key) {
+    const value = this.details[key];
+    return typeof value === "string" && value !== "" ? value : null;
+  }
+};
+var ConnectionError = class extends LabyrintheError {
+  constructor(message, code = "CONNECTION_ERROR") {
+    super(message, code);
+  }
+};
+var TimeoutError = class extends ConnectionError {
+  constructor(message) {
+    super(message, "TIMEOUT");
+  }
+};
+var RequestAbortedError = class extends LabyrintheError {
+  constructor(message = "The request was aborted.") {
+    super(message, "REQUEST_ABORTED");
+  }
+};
+var InvalidArgumentError = class extends LabyrintheError {
+  constructor(message) {
+    super(message, "INVALID_ARGUMENT");
+  }
+};
+var UnexpectedResponseError = class extends LabyrintheError {
+  constructor(message, status = null) {
+    super(message, "UNEXPECTED_RESPONSE", status);
+  }
+};
+var SignatureVerificationError = class extends LabyrintheError {
+  constructor(message) {
+    super(message, "SIGNATURE_VERIFICATION_FAILED");
+  }
+};
+var InvalidWebhookPayloadError = class extends LabyrintheError {
+  constructor(message) {
+    super(message, "INVALID_WEBHOOK_PAYLOAD");
+  }
+};
+var ERROR_CLASSES_BY_CODE = {
+  UNAUTHENTICATED: AuthenticationError,
+  FORBIDDEN: PermissionError,
+  ACCOUNT_SUSPENDED: AccountSuspendedError,
+  OTP_DISABLED_FOR_ACCOUNT: PermissionError,
+  NOT_FOUND: NotFoundError,
+  VALIDATION_ERROR: ValidationError,
+  RECIPIENT_NOT_SENDABLE: RecipientNotSendableError,
+  SENDER_ID_NOT_APPROVED: SenderIdNotApprovedError,
+  INVALID_PHONE: InvalidPhoneError,
+  INSUFFICIENT_CREDITS: InsufficientCreditsError,
+  IDEMPOTENCY_KEY_REUSED: IdempotencyKeyReusedError,
+  IDEMPOTENCY_KEY_UNRESOLVED: IdempotencyKeyUnresolvedError,
+  IDEMPOTENCY_REQUEST_IN_PROGRESS: IdempotencyRequestInProgressError,
+  TOO_MANY_REQUESTS: RateLimitError,
+  OTP_RESEND_TOO_SOON: OtpResendTooSoonError,
+  OTP_RATE_LIMITED: OtpRateLimitedError,
+  OTP_SERVICE_DISABLED: FeatureDisabledError,
+  FEATURE_DISABLED: FeatureDisabledError
+};
+function errorFromResponse(status, rawBody, headers) {
+  let code = null;
+  let message = null;
+  let details = {};
+  let decoded = null;
+  try {
+    decoded = JSON.parse(rawBody);
+  } catch {
+    decoded = null;
+  }
+  if (isRecord(decoded) && isRecord(decoded["error"])) {
+    const error = decoded["error"];
+    code = typeof error["code"] === "string" ? error["code"] : null;
+    message = typeof error["message"] === "string" ? error["message"] : null;
+    details = isRecord(error["details"]) ? error["details"] : {};
+  }
+  code ??= status === 429 ? "TOO_MANY_REQUESTS" : "HTTP_ERROR";
+  message ??= `Labyrinthe Connect API returned HTTP ${String(status)}.`;
+  const ErrorClass = ERROR_CLASSES_BY_CODE[code] ?? classForStatus(status);
+  return new ErrorClass(message, code, status, details, headers);
+}
+function classForStatus(status) {
+  if (status === 401) return AuthenticationError;
+  if (status === 403) return PermissionError;
+  if (status === 404) return NotFoundError;
+  if (status === 429) return RateLimitError;
+  if (status >= 500) return ServiceUnavailableError;
+  return ApiError;
+}
+function rejectionReason(value) {
+  return value === "invalid_phone" || value === "blacklisted" || value === "opted_out" ? value : "unknown";
+}
+function retryAfterMsOf(headers, details) {
+  const header = headers["retry-after"]?.trim();
+  if (header !== void 0 && header !== "") {
+    if (/^\d+(\.\d+)?$/.test(header)) {
+      return Math.round(Number(header) * 1e3);
+    }
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+      return Math.max(0, date - Date.now());
+    }
+  }
+  const seconds = toInt(details["retry_after_seconds"]);
+  return seconds === null || seconds < 0 ? null : seconds * 1e3;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toInt(value) {
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    return Number(value);
+  }
+  return null;
+}
+
+// src/phone.ts
+var DEFAULT_COUNTRY_CODE = "243";
+var PhoneNumber = Object.freeze({
+  /** Normalises a number, or returns null when it cannot be a valid phone number. */
+  normalize(raw, defaultCountryCode = DEFAULT_COUNTRY_CODE) {
+    assertCountryCode(defaultCountryCode);
+    const input = raw.trim();
+    if (input === "") {
+      return null;
+    }
+    const explicitInternational = input.startsWith("+") || input.startsWith("00");
+    let digits = input.replace(/\D/g, "");
+    if (explicitInternational) {
+      digits = input.startsWith("00") ? digits.slice(2) : digits;
+    } else if (digits.startsWith(defaultCountryCode) && digits.length > 10) ; else if (digits.length >= 11 && !digits.startsWith("0")) ; else {
+      digits = defaultCountryCode + digits.replace(/^0+/, "");
+    }
+    return digits.length >= 8 && digits.length <= 15 ? digits : null;
+  },
+  /** Normalises a number or throws an InvalidArgumentError (the number itself is never part of the message). */
+  normalizeOrThrow(raw, defaultCountryCode = DEFAULT_COUNTRY_CODE, field = "phone") {
+    const normalized = PhoneNumber.normalize(raw, defaultCountryCode);
+    if (normalized === null) {
+      throw new InvalidArgumentError(
+        `Invalid phone number in "${field}": expected an international number (e.g. 243812345678) or a local number.`
+      );
+    }
+    return normalized;
+  },
+  isValid(raw, defaultCountryCode = DEFAULT_COUNTRY_CODE) {
+    return PhoneNumber.normalize(raw, defaultCountryCode) !== null;
+  },
+  /** Masks a number for logs: "243812345678" → "24381*****78". */
+  mask(phone) {
+    const digits = phone.replace(/\D/g, "");
+    const length = digits.length;
+    if (length <= 4) {
+      return "*".repeat(length);
+    }
+    const visibleStart = Math.min(5, Math.max(1, length - 7));
+    return digits.slice(0, visibleStart) + "*".repeat(length - visibleStart - 2) + digits.slice(-2);
+  }
+});
+function toApiNumber(digits) {
+  return "+" + digits;
+}
+function assertCountryCode(countryCode) {
+  if (!/^[1-9]\d{0,2}$/.test(countryCode)) {
+    throw new InvalidArgumentError('The default country code must be 1 to 3 digits without "+" (e.g. "243").');
+  }
+}
+
+// src/internal/redact.ts
+var PHONE_PARAMS = ["recipient", "phone"];
+function redactApiKey(apiKey) {
+  const match = /^(lsk_(?:live|test)_)/.exec(apiKey);
+  return match?.[1] !== void 0 ? `${match[1]}****` : "****";
+}
+function redactPath(path, query) {
+  if ([...query.keys()].length === 0) {
+    return path;
+  }
+  const parts = [];
+  for (const [name, value] of query) {
+    const shown = PHONE_PARAMS.includes(name) ? PhoneNumber.mask(value) : encodeURIComponent(value);
+    parts.push(`${encodeURIComponent(name)}=${shown}`);
+  }
+  return `${path}?${parts.join("&")}`;
+}
+function stripQueryStrings(text) {
+  return text.replace(/\?[^\s"']*/g, "?\u2026");
+}
+
+// src/version.ts
+var VERSION = "1.2.0";
+
+// src/internal/runtime.ts
+var g = globalThis;
+function env(name) {
+  try {
+    const value = g.process?.env?.[name];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isBrowser() {
+  return g.window?.document !== void 0;
+}
+function runtimeName() {
+  if (typeof g.Bun?.version === "string") return `bun/${g.Bun.version}`;
+  if (typeof g.Deno?.version?.deno === "string") return `deno/${g.Deno.version.deno}`;
+  if (typeof g.EdgeRuntime === "string") return "edge-runtime";
+  const node = g.process?.versions?.["node"];
+  if (typeof node === "string") return `node/${node}`;
+  if (g.navigator?.userAgent === "Cloudflare-Workers") return "workerd";
+  return "unknown";
+}
+function clientIdentifier() {
+  return `labyrinthe-node/${VERSION} ${runtimeName()}`;
+}
+var cryptoPromise;
+function getCrypto() {
+  if (g.crypto?.subtle !== void 0 && typeof g.crypto.randomUUID === "function") {
+    return Promise.resolve(g.crypto);
+  }
+  cryptoPromise ??= loadNodeCrypto();
+  return cryptoPromise;
+}
+async function loadNodeCrypto() {
+  if (typeof g.process?.versions?.["node"] === "string") {
+    const specifier = ["node", "crypto"].join(":");
+    try {
+      const mod = await import(
+        /* webpackIgnore: true */
+        /* @vite-ignore */
+        specifier
+      );
+      if (mod.webcrypto?.subtle !== void 0) {
+        return mod.webcrypto;
+      }
+    } catch {
+    }
+  }
+  cryptoPromise = void 0;
+  throw new Error("Web Crypto (globalThis.crypto) is not available in this runtime.");
+}
+
+// src/internal/transport.ts
+var REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+var BASE_DELAY_MS = 500;
+var MAX_BACKOFF_MS = 8e3;
+var defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted === true) {
+    reject(new RequestAbortedError());
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(timer);
+    reject(new RequestAbortedError());
+  };
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+var Transport = class {
+  #apiKey;
+  #config;
+  #identityHeader;
+  constructor(config) {
+    const { apiKey, ...rest } = config;
+    this.#apiKey = apiKey;
+    this.#config = rest;
+    this.#identityHeader = [isBrowser() ? "X-Labyrinthe-Client" : "User-Agent", clientIdentifier()];
+  }
+  get baseUrl() {
+    return this.#config.baseUrl;
+  }
+  async request(method, path, mode, params = {}) {
+    const { fetch, logger, maxRetries, sleep } = this.#config;
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries(params.query ?? {})) {
+      if (value !== void 0) query.append(name, String(value));
+    }
+    const queryString = query.toString();
+    const url = this.#config.baseUrl + path + (queryString === "" ? "" : `?${queryString}`);
+    const logPath = redactPath(path, query);
+    const payload = params.body === void 0 ? void 0 : JSON.stringify(params.body);
+    const timeoutMs = params.timeoutMs ?? this.#config.timeoutMs;
+    const signal = params.signal;
+    const requestId = params.requestId;
+    if (requestId !== void 0 && (typeof requestId !== "string" || !REQUEST_ID_PATTERN.test(requestId))) {
+      throw new InvalidArgumentError("requestId must be 1 to 128 characters among A-Z a-z 0-9 . _ : -");
+    }
+    const headers = {
+      Authorization: `Bearer ${this.#apiKey}`,
+      Accept: "application/json",
+      [this.#identityHeader[0]]: this.#identityHeader[1],
+      ...params.headers
+    };
+    if (payload !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (requestId !== void 0) {
+      headers["X-Request-Id"] = requestId;
+    }
+    const idempotent = headers["Idempotency-Key"] !== void 0;
+    for (let attempt = 0; ; attempt++) {
+      if (signal?.aborted === true) {
+        throw new RequestAbortedError();
+      }
+      log(logger, "debug", "Labyrinthe Connect request", { method, path: logPath, attempt: attempt + 1 });
+      const startedAt = Date.now();
+      const result = await this.#attempt(fetch, url, { method, headers, body: payload }, timeoutMs, signal);
+      if ("kind" in result) {
+        const timeout = result.kind === "timeout";
+        if (mode === "safe" && attempt < maxRetries) {
+          const delay = this.#backoff(attempt);
+          log(logger, "warn", "Labyrinthe Connect network error, retrying", {
+            method,
+            path: logPath,
+            attempt: attempt + 1,
+            delayMs: Math.round(delay),
+            timeout
+          });
+          await sleep(delay, signal);
+          continue;
+        }
+        log(logger, "error", "Labyrinthe Connect network error", { method, path: logPath, timeout });
+        const suffix = mode === "throttled-only" ? " The request may have been processed; it was not retried automatically." : idempotent ? " Calling again with the same idempotencyKey is safe (nothing is sent twice)." : "";
+        if (result.kind === "timeout") {
+          throw new TimeoutError(
+            `The Labyrinthe Connect API did not answer within ${String(timeoutMs)} ms (${method} ${path}).${suffix}`
+          );
+        }
+        throw new ConnectionError(
+          `Could not reach the Labyrinthe Connect API (${method} ${path}): ${result.reason}.${suffix}`
+        );
+      }
+      const { status, headers: responseHeaders, text } = result;
+      log(logger, "debug", "Labyrinthe Connect response", {
+        method,
+        path: logPath,
+        status,
+        durationMs: Date.now() - startedAt,
+        replayed: responseHeaders["idempotent-replayed"] === "true",
+        requestId: responseHeaders["x-request-id"] ?? null
+      });
+      if (status >= 200 && status < 300) {
+        const body = decode(text, status);
+        if (params.onResponse !== void 0) {
+          try {
+            params.onResponse(responseInfo(status, responseHeaders));
+          } catch (error2) {
+            log(logger, "warn", "Labyrinthe Connect onResponse callback threw", {
+              method,
+              path: logPath,
+              error: error2 instanceof Error ? error2.name : typeof error2
+            });
+          }
+        }
+        return { status, body, headers: responseHeaders };
+      }
+      const error = errorFromResponse(status, text, responseHeaders);
+      if (attempt < maxRetries && isRetryable(mode, error)) {
+        const delay = this.#retryDelay(error, attempt);
+        if (delay !== null) {
+          log(logger, "warn", "Labyrinthe Connect request failed, retrying", {
+            method,
+            path: logPath,
+            status,
+            code: error.code,
+            requestId: error.requestId,
+            attempt: attempt + 1,
+            delayMs: Math.round(delay)
+          });
+          await sleep(delay, signal);
+          continue;
+        }
+      }
+      log(logger, "info", "Labyrinthe Connect API error", {
+        method,
+        path: logPath,
+        status,
+        code: error.code,
+        requestId: error.requestId
+      });
+      throw error;
+    }
+  }
+  async #attempt(fetch, url, init, timeoutMs, signal) {
+    const controller = new AbortController();
+    const state = { timedOut: false };
+    const timer = setTimeout(() => {
+      state.timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    const onAbort = () => {
+      controller.abort();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      const response = await fetch(url, {
+        method: init.method,
+        headers: init.headers,
+        ...init.body === void 0 ? {} : { body: init.body },
+        signal: controller.signal,
+        redirect: "manual"
+      });
+      const headers = {};
+      response.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+      });
+      const text = await response.text();
+      return { status: response.status, headers, text };
+    } catch (error) {
+      if (signal?.aborted === true) {
+        throw new RequestAbortedError();
+      }
+      if (state.timedOut) {
+        return { kind: "timeout" };
+      }
+      return { kind: "network", reason: describeNetworkError(error) };
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  /** Délai avant la prochaine tentative, ou null pour abandonner (l'API demande d'attendre plus que le maximum). */
+  #retryDelay(error, attempt) {
+    if (error instanceof FeatureDisabledError) {
+      const retryAfter = error.retryAfterMs;
+      return retryAfter !== null && retryAfter <= this.#config.maxRetryWaitMs ? retryAfter : null;
+    }
+    if (error.status === 429 || error.code === IN_PROGRESS) {
+      const retryAfter = retryAfterMsOf(error.headers, error.details);
+      if (retryAfter !== null) {
+        return retryAfter <= this.#config.maxRetryWaitMs ? retryAfter : null;
+      }
+    }
+    return this.#backoff(attempt);
+  }
+  /** Backoff exponentiel avec jitter : 0,5 s, 1 s, 2 s… (50 à 100 %), plafonné. */
+  #backoff(attempt) {
+    const delay = Math.min(MAX_BACKOFF_MS, BASE_DELAY_MS * 2 ** attempt);
+    const jitter = 0.5 + Math.random() * 0.5;
+    return Math.min(this.#config.maxRetryWaitMs, delay * jitter);
+  }
+  toJSON() {
+    return { apiKey: redactApiKey(this.#apiKey), baseUrl: this.#config.baseUrl, maxRetries: this.#config.maxRetries };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toJSON();
+  }
+};
+var IN_PROGRESS = "IDEMPOTENCY_REQUEST_IN_PROGRESS";
+function isRetryable(mode, error) {
+  if (error instanceof FeatureDisabledError) {
+    return true;
+  }
+  if (error.status === 429) {
+    return error.code === "TOO_MANY_REQUESTS";
+  }
+  if (mode !== "safe") {
+    return false;
+  }
+  return error.code === IN_PROGRESS || error.status >= 500;
+}
+function responseInfo(status, headers) {
+  return {
+    status,
+    requestId: headers["x-request-id"] ?? null,
+    apiVersion: headers["x-api-version"] ?? null,
+    replayed: headers["idempotent-replayed"] === "true",
+    rateLimit: { limit: toInt(headers["x-ratelimit-limit"]), remaining: toInt(headers["x-ratelimit-remaining"]) },
+    headers
+  };
+}
+function decode(text, status) {
+  if (text.trim() === "") {
+    return {};
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(text);
+  } catch {
+    throw new UnexpectedResponseError("Unexpected API response: the body is not valid JSON.", status);
+  }
+  if (!isRecord(decoded)) {
+    throw new UnexpectedResponseError("Unexpected API response: a JSON object was expected.", status);
+  }
+  return decoded;
+}
+function describeNetworkError(error) {
+  if (!(error instanceof Error)) {
+    return "network error";
+  }
+  const cause = error.cause;
+  const code = isRecord(cause) && typeof cause["code"] === "string" ? cause["code"] : void 0;
+  const message = stripQueryStrings(error.message);
+  return code === void 0 ? message : `${message} (${code})`;
+}
+function log(logger, level, message, context) {
+  try {
+    logger?.[level]?.(message, context);
+  } catch {
+  }
+}
+
+// src/internal/data.ts
+function characterCount(value) {
+  let count = 0;
+  for (const _char of value) count++;
+  return count;
+}
+var MESSAGE_STATUSES = [
+  "queued",
+  "submitted",
+  "sent",
+  "delivered",
+  "failed",
+  "rejected",
+  "expired",
+  "undeliverable"
+];
+var SENDER_ID_STATUSES = ["pending", "pending_provider", "approved", "rejected", "suspended"];
+var OTP_FAILURE_REASONS = ["invalid_code", "expired", "already_used", "max_attempts_reached"];
+var Reader = class {
+  constructor(context = "Unexpected API payload") {
+    this.context = context;
+  }
+  context;
+  invalid(key, expected) {
+    return new UnexpectedResponseError(`${this.context}: field "${key}" should be ${expected}.`);
+  }
+  string(data, key) {
+    const value = data[key];
+    if (typeof value === "string") return value;
+    if (typeof value === "number") return String(value);
+    throw this.invalid(key, "a string");
+  }
+  nullableString(data, key) {
+    return data[key] === void 0 || data[key] === null ? null : this.string(data, key);
+  }
+  int(data, key) {
+    const value = toInt(data[key]);
+    if (value === null) throw this.invalid(key, "an integer");
+    return value;
+  }
+  nullableInt(data, key) {
+    return data[key] === void 0 || data[key] === null ? null : this.int(data, key);
+  }
+  bool(data, key) {
+    const value = data[key];
+    if (typeof value === "boolean") return value;
+    if (value === 0 || value === 1) return value === 1;
+    throw this.invalid(key, "a boolean");
+  }
+  object(data, key) {
+    const value = data[key];
+    if (isRecord(value)) return value;
+    throw this.invalid(key, "an object");
+  }
+  /** Objet facultatif : absent, nul ou `[]` (PHP) donnent `{}`. */
+  optionalObject(data, key) {
+    const value = data[key];
+    if (value === void 0 || value === null || Array.isArray(value) && value.length === 0) return {};
+    return this.object(data, key);
+  }
+  objects(data, key) {
+    const value = data[key];
+    if (!Array.isArray(value)) throw this.invalid(key, "an array");
+    return value.map((item) => {
+      if (!isRecord(item)) throw this.invalid(`${key}[]`, "an object");
+      return item;
+    });
+  }
+  date(data, key) {
+    const value = data[key];
+    const date = typeof value === "string" ? new Date(value) : null;
+    if (date === null || Number.isNaN(date.getTime())) throw this.invalid(key, "an ISO 8601 date-time");
+    return date;
+  }
+  nullableDate(data, key) {
+    return data[key] === void 0 || data[key] === null ? null : this.date(data, key);
+  }
+};
+var api = new Reader();
+function messageStatus(value) {
+  return MESSAGE_STATUSES.includes(value) ? value : "unknown";
+}
+function encoding(value) {
+  return value === "gsm7" || value === "ucs2" ? value : null;
+}
+function toMessage(data) {
+  return {
+    id: api.string(data, "id"),
+    reference: api.nullableString(data, "reference"),
+    recipient: api.string(data, "recipient"),
+    sender: api.nullableString(data, "sender"),
+    // Jamais null depuis la spec 1.2.0 (BACKEND-TODO n° 9) ; null toléré pour un backend plus ancien.
+    encoding: encoding(api.nullableString(data, "encoding")),
+    status: messageStatus(api.string(data, "status")),
+    segments: api.nullableInt(data, "segments") ?? 0,
+    creditsCharged: api.nullableInt(data, "credits_charged") ?? 0,
+    campaignId: api.nullableString(data, "campaign_id"),
+    providerMessageId: api.nullableString(data, "provider_message_id"),
+    errorCode: api.nullableString(data, "error_code"),
+    errorMessage: api.nullableString(data, "error_message"),
+    createdAt: api.nullableDate(data, "created_at"),
+    submittedAt: api.nullableDate(data, "submitted_at"),
+    deliveredAt: api.nullableDate(data, "delivered_at")
+  };
+}
+function toEstimate(data) {
+  const balanceAfter = api.nullableInt(data, "balance_after");
+  return {
+    encoding: encoding(api.string(data, "encoding")) ?? "ucs2",
+    characters: api.int(data, "characters"),
+    segmentsPerMessage: api.int(data, "segments_per_message"),
+    recipientsCount: api.int(data, "recipients_count"),
+    totalCredits: api.int(data, "total_credits"),
+    balanceAfter,
+    isAffordable: balanceAfter !== null && balanceAfter >= 0
+  };
+}
+function toBalance(data) {
+  return { balance: api.int(data, "balance"), held: api.int(data, "held") };
+}
+function toSenderId(data) {
+  const status = api.string(data, "status");
+  return {
+    id: api.string(data, "id"),
+    value: api.string(data, "value"),
+    status: SENDER_ID_STATUSES.includes(status) ? status : "unknown",
+    purpose: api.nullableString(data, "purpose"),
+    rejectionReason: api.nullableString(data, "rejection_reason"),
+    isDefault: data["is_default"] !== void 0 && data["is_default"] !== null && api.bool(data, "is_default"),
+    createdAt: api.nullableDate(data, "created_at")
+  };
+}
+function toOtpVerifyResult(data) {
+  if (api.bool(data, "verified")) {
+    return { verified: true, reason: null, attemptsRemaining: null };
+  }
+  const reason = api.nullableString(data, "reason") ?? "unknown";
+  const remaining = api.nullableInt(data, "attempts_remaining");
+  return {
+    verified: false,
+    reason: OTP_FAILURE_REASONS.includes(reason) ? reason : "unknown",
+    attemptsRemaining: remaining === null ? null : Math.max(0, remaining)
+  };
+}
+
+// src/resources/account.ts
+var BalanceResource = class {
+  #transport;
+  /** @internal */
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async get(options = {}) {
+    const response = await this.#transport.request("GET", "/balance", "safe", options);
+    return toBalance(api.object(response.body, "data"));
+  }
+  toJSON() {
+    return { transport: this.#transport.toJSON() };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toJSON();
+  }
+};
+var SenderIds = class {
+  #transport;
+  /** @internal */
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  /** Sender IDs with the `approved` status, usable as `sender`. */
+  async list(options = {}) {
+    const response = await this.#transport.request("GET", "/sender-ids", "safe", options);
+    return api.objects(response.body, "data").map(toSenderId);
+  }
+  toJSON() {
+    return { transport: this.#transport.toJSON() };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toJSON();
+  }
+};
+
+// src/internal/idempotency.ts
+var MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+async function resolveIdempotencyKey(value) {
+  if (value === void 0) {
+    return (await getCrypto()).randomUUID();
+  }
+  if (typeof value !== "string" || value === "" || value.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+    throw new InvalidArgumentError(`idempotencyKey must be 1 to ${String(MAX_IDEMPOTENCY_KEY_LENGTH)} characters.`);
+  }
+  return value;
+}
+function assertStripAccents(value) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    throw new InvalidArgumentError("stripAccents must be a boolean.");
+  }
+}
+
+// src/types.ts
+var MessageStatus = {
+  /** Queued at Labyrinthe Connect. */
+  Queued: "queued",
+  /** Handed over to the SMS provider. */
+  Submitted: "submitted",
+  /** Accepted by the mobile operator. */
+  Sent: "sent",
+  /** Delivered to the handset (final). */
+  Delivered: "delivered",
+  /** Failed (final). */
+  Failed: "failed",
+  /** Rejected by the provider or the operator (final). */
+  Rejected: "rejected",
+  /** Expired before delivery (final). */
+  Expired: "expired",
+  /** Cannot be delivered to this number (final). */
+  Undeliverable: "undeliverable",
+  /** Status not known by this SDK version. */
+  Unknown: "unknown"
+};
+var PENDING_STATUSES = ["queued", "submitted", "sent"];
+var FAILED_STATUSES = ["failed", "rejected", "expired", "undeliverable"];
+function isFinalStatus(status) {
+  return status === "delivered" || FAILED_STATUSES.includes(status);
+}
+function isFailedStatus(status) {
+  return FAILED_STATUSES.includes(status);
+}
+function isPendingStatus(status) {
+  return PENDING_STATUSES.includes(status);
+}
+var Encoding = {
+  Gsm7: "gsm7",
+  Ucs2: "ucs2"
+};
+var SenderIdStatus = {
+  Pending: "pending",
+  PendingProvider: "pending_provider",
+  Approved: "approved",
+  Rejected: "rejected",
+  Suspended: "suspended",
+  /** Status not known by this SDK version. */
+  Unknown: "unknown"
+};
+var RejectionReason = {
+  InvalidPhone: "invalid_phone",
+  Blacklisted: "blacklisted",
+  OptedOut: "opted_out",
+  /** Reason not known by this SDK version. */
+  Unknown: "unknown"
+};
+var OtpFailureReason = {
+  /** Wrong code: one attempt was consumed, the user may try again. */
+  InvalidCode: "invalid_code",
+  /** The code expired: send a new one. */
+  Expired: "expired",
+  /** The code was already verified (each code is single-use). */
+  AlreadyUsed: "already_used",
+  /** Too many wrong attempts: the code is permanently blocked. */
+  MaxAttemptsReached: "max_attempts_reached",
+  /** Reason not known by this SDK version. */
+  Unknown: "unknown"
+};
+var OtpRateLimitScope = {
+  Phone: "phone",
+  Account: "account",
+  /** Scope not known by this SDK version. */
+  Unknown: "unknown"
+};
+var OtpCodeType = {
+  /** Digits 0-9. */
+  Numeric: "numeric",
+  /** Upper-case letters and digits without ambiguous characters; typing is case-insensitive. */
+  Alphanumeric: "alphanumeric",
+  /** Alphabet not known by this SDK version. */
+  Unknown: "unknown"
+};
+var OtpVerificationStatus = {
+  /** The right code was typed (`otp.verified`). */
+  Verified: "verified",
+  /** Too many wrong attempts (`otp.failed`, reason `max_attempts_reached`). */
+  Failed: "failed",
+  /** The code expired (`otp.failed`, reason `expired`). */
+  Expired: "expired",
+  /** Status not known by this SDK version. */
+  Unknown: "unknown"
+};
+var WebhookEventType = {
+  MessageStatusChanged: "message.status_changed",
+  CampaignCompleted: "campaign.completed",
+  BalanceLow: "balance.low",
+  OtpVerified: "otp.verified",
+  OtpFailed: "otp.failed",
+  TestPing: "test.ping"
+};
+
+// src/resources/otp.ts
+var MAX_TEMPLATE_LENGTH = 1600;
+var MAX_CODE_LENGTH = 20;
+var WEB_OTP_DOMAIN_PATTERN = /^(?=.{1,253}$)([A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var DENO_INSPECT = /* @__PURE__ */ Symbol.for("Deno.customInspect");
+var CODE_TYPES = [OtpCodeType.Numeric, OtpCodeType.Alphanumeric];
+var OtpSendResult = class {
+  otpId;
+  expiresAt;
+  maxAttempts;
+  /** Number of characters of the code (4 to 8, account's OTP settings); null only with an API older than 1.2.0. */
+  codeLength;
+  /** `numeric` (0-9) or `alphanumeric` (case-insensitive); null only with an API older than 1.2.0. */
+  codeType;
+  /**
+   * 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.
+   */
+  resendAfterSeconds;
+  /** The Idempotency-Key of this send (yours, or the one generated by the SDK). */
+  idempotencyKey;
+  /** True when the API replayed an earlier send with the same Idempotency-Key: no new SMS, no new charge. */
+  replayed;
+  /** `X-Request-Id` of the response, for the support; null when absent. */
+  requestId;
+  #testCode;
+  /** @internal */
+  constructor(init) {
+    this.otpId = init.otpId;
+    this.expiresAt = init.expiresAt;
+    this.maxAttempts = init.maxAttempts;
+    this.codeLength = init.codeLength;
+    this.codeType = init.codeType;
+    this.resendAfterSeconds = init.resendAfterSeconds;
+    this.idempotencyKey = init.idempotencyKey;
+    this.replayed = init.replayed;
+    this.requestId = init.requestId;
+    this.#testCode = init.testCode;
+  }
+  /**
+   * 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() {
+    return this.#testCode;
+  }
+  toJSON() {
+    return {
+      otpId: this.otpId,
+      expiresAt: this.expiresAt.toISOString(),
+      maxAttempts: this.maxAttempts,
+      codeLength: this.codeLength,
+      codeType: this.codeType,
+      resendAfterSeconds: this.resendAfterSeconds,
+      replayed: this.replayed,
+      requestId: this.requestId
+    };
+  }
+  [INSPECT]() {
+    return this.#redacted();
+  }
+  [DENO_INSPECT]() {
+    return `OtpSendResult ${JSON.stringify(this.#redacted())}`;
+  }
+  #redacted() {
+    return {
+      ...this.toJSON(),
+      expiresAt: this.expiresAt,
+      testCode: this.#testCode === null ? null : "[redacted]"
+    };
+  }
+};
+var Otp = class {
+  #transport;
+  #defaultCountryCode;
+  /** @internal */
+  constructor(transport, defaultCountryCode) {
+    this.#transport = transport;
+    this.#defaultCountryCode = defaultCountryCode;
+  }
+  /**
+   * 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`.
+   */
+  async send(params, options = {}) {
+    const body = {
+      phone: toApiNumber(PhoneNumber.normalizeOrThrow(params.phone, this.#defaultCountryCode, "phone"))
+    };
+    const template = params.template;
+    const locale = params.locale;
+    const webOtpDomain = params.webOtpDomain;
+    const stripAccents = params.stripAccents;
+    if (template !== void 0) {
+      if (typeof template !== "string" || !template.includes("{code}")) {
+        throw new InvalidArgumentError("The OTP template must contain the {code} token.");
+      }
+      if (characterCount(template) > MAX_TEMPLATE_LENGTH) {
+        throw new InvalidArgumentError(`The OTP template must be at most ${String(MAX_TEMPLATE_LENGTH)} characters.`);
+      }
+      body["template"] = template;
+    }
+    if (locale !== void 0) {
+      if (locale !== "fr" && locale !== "en") {
+        throw new InvalidArgumentError('locale must be "fr" or "en".');
+      }
+      body["locale"] = locale;
+    }
+    if (webOtpDomain !== void 0) {
+      if (typeof webOtpDomain !== "string" || !WEB_OTP_DOMAIN_PATTERN.test(webOtpDomain)) {
+        throw new InvalidArgumentError(
+          'webOtpDomain must be a host name with at least two labels, without scheme, port or path (e.g. "app.example.com").'
+        );
+      }
+      body["web_otp_domain"] = webOtpDomain.toLowerCase();
+    }
+    assertStripAccents(stripAccents);
+    if (stripAccents !== void 0) {
+      body["strip_accents"] = stripAccents;
+    }
+    const idempotencyKey = await resolveIdempotencyKey(params.idempotencyKey);
+    const response = await this.#transport.request("POST", "/otp/send", "safe", {
+      body,
+      ...options,
+      headers: { "Idempotency-Key": idempotencyKey }
+    });
+    const data = api.object(response.body, "data");
+    const codeType = api.nullableString(data, "code_type");
+    return new OtpSendResult({
+      otpId: api.string(data, "otp_id"),
+      expiresAt: api.date(data, "expires_at"),
+      maxAttempts: api.int(data, "max_attempts"),
+      // Champs de la spec 1.2.0 : null avec un backend plus ancien (l'envoi a réussi, on ne le fait pas échouer).
+      codeLength: api.nullableInt(data, "code_length"),
+      codeType: codeType === null ? null : CODE_TYPES.includes(codeType) ? codeType : "unknown",
+      resendAfterSeconds: api.nullableInt(data, "resend_after_seconds"),
+      testCode: api.nullableString(data, "test_code"),
+      idempotencyKey,
+      replayed: response.headers["idempotent-replayed"] === "true",
+      requestId: response.headers["x-request-id"] ?? null
+    });
+  }
+  /**
+   * 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.
+   */
+  async verify(params, options = {}) {
+    const { otpId, code } = params;
+    if (typeof otpId !== "string" || otpId.trim() === "") {
+      throw new InvalidArgumentError("otpId cannot be empty.");
+    }
+    if (typeof code !== "string" || code.trim() === "" || code.length > MAX_CODE_LENGTH) {
+      throw new InvalidArgumentError(`The code must be 1 to ${String(MAX_CODE_LENGTH)} characters.`);
+    }
+    const response = await this.#transport.request("POST", "/otp/verify", "throttled-only", {
+      body: { otp_id: otpId, code },
+      ...options
+    });
+    return toOtpVerifyResult(api.object(response.body, "data"));
+  }
+  toJSON() {
+    return { transport: this.#transport.toJSON(), defaultCountryCode: this.#defaultCountryCode };
+  }
+  [INSPECT]() {
+    return this.toJSON();
+  }
+};
+
+// src/pagination.ts
+var Page = class {
+  data;
+  currentPage;
+  lastPage;
+  perPage;
+  total;
+  #fetchPage;
+  /** @internal */
+  constructor(meta, fetchPage) {
+    this.data = meta.data;
+    this.currentPage = meta.currentPage;
+    this.lastPage = meta.lastPage;
+    this.perPage = meta.perPage;
+    this.total = meta.total;
+    this.#fetchPage = fetchPage;
+  }
+  get hasMore() {
+    return this.currentPage < this.lastPage;
+  }
+  /** The next page, or null on the last one. */
+  async nextPage() {
+    return this.hasMore ? this.#fetchPage(this.currentPage + 1) : null;
+  }
+  /** Every item from this page to the last one (pages are fetched lazily). */
+  async *[Symbol.asyncIterator]() {
+    yield* this.data;
+    let page = await this.nextPage();
+    while (page !== null) {
+      yield* page.data;
+      page = await page.nextPage();
+    }
+  }
+  toJSON() {
+    return {
+      data: this.data,
+      currentPage: this.currentPage,
+      lastPage: this.lastPage,
+      perPage: this.perPage,
+      total: this.total
+    };
+  }
+};
+var PagePromise = class {
+  #load;
+  #promise;
+  /** @internal */
+  constructor(load) {
+    this.#load = load;
+  }
+  #first() {
+    this.#promise ??= this.#load();
+    return this.#promise;
+  }
+  then(onFulfilled, onRejected) {
+    return this.#first().then(onFulfilled, onRejected);
+  }
+  catch(onRejected) {
+    return this.#first().catch(onRejected);
+  }
+  finally(onFinally) {
+    return this.#first().finally(onFinally);
+  }
+  async *[Symbol.asyncIterator]() {
+    yield* await this.#first();
+  }
+};
+
+// src/resources/sms.ts
+var MAX_BODY_LENGTH = 1600;
+var MAX_RECIPIENTS = 1e3;
+var MAX_SENDER_LENGTH = 11;
+var MAX_REFERENCE_LENGTH = 64;
+var MAX_PER_PAGE = 100;
+var Sms = class {
+  #transport;
+  #defaultCountryCode;
+  #defaultSender;
+  /** @internal */
+  constructor(transport, defaultCountryCode, defaultSender) {
+    this.#transport = transport;
+    this.#defaultCountryCode = defaultCountryCode;
+    this.#defaultSender = defaultSender;
+  }
+  /**
+   * 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.
+   */
+  async send(params, options = {}) {
+    const recipient = toApiNumber(PhoneNumber.normalizeOrThrow(params.to, this.#defaultCountryCode, "to"));
+    const batch = await this.#dispatch({ recipient }, params, options);
+    const message = batch.messages[0];
+    if (message === void 0) {
+      throw new UnexpectedResponseError("Unexpected API response: no message was returned.");
+    }
+    return 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).
+   */
+  async sendMany(params, options = {}) {
+    const recipients = params.recipients;
+    if (!Array.isArray(recipients) || recipients.length === 0) {
+      throw new InvalidArgumentError("At least one recipient is required.");
+    }
+    if (recipients.length > MAX_RECIPIENTS) {
+      throw new InvalidArgumentError(`At most ${String(MAX_RECIPIENTS)} recipients per request.`);
+    }
+    const normalized = [];
+    const invalid = [];
+    recipients.forEach((recipient, index) => {
+      const number = typeof recipient === "string" ? PhoneNumber.normalize(recipient, this.#defaultCountryCode) : null;
+      if (number === null) {
+        invalid.push(index);
+      } else {
+        normalized.push(toApiNumber(number));
+      }
+    });
+    if (invalid.length > 0) {
+      const shown = invalid.slice(0, 20).join(", ") + (invalid.length > 20 ? "\u2026" : "");
+      throw new InvalidArgumentError(`Invalid phone number(s) at recipients index ${shown}. Nothing was sent.`);
+    }
+    return this.#dispatch({ recipients: normalized }, params, options);
+  }
+  /** Computes encoding, segments and credits without sending anything. */
+  async estimate(params, options = {}) {
+    assertBody(params.body);
+    const list = typeof params.recipients === "string" ? [params.recipients] : [...params.recipients];
+    if (list.length === 0) {
+      throw new InvalidArgumentError("At least one recipient is required.");
+    }
+    const recipients = list.map((r) => toApiNumberOrRaw(r, this.#defaultCountryCode));
+    const stripAccents = params.stripAccents;
+    assertStripAccents(stripAccents);
+    const body = { body: params.body, recipients };
+    if (stripAccents !== void 0) body["strip_accents"] = stripAccents;
+    const response = await this.#transport.request("POST", "/sms/estimate", "safe", { body, ...options });
+    return toEstimate(api.object(response.body, "data"));
+  }
+  /** One message of the account, by id. Throws `NotFoundError` when unknown. */
+  async get(id, options = {}) {
+    if (typeof id !== "string" || id.trim() === "") {
+      throw new InvalidArgumentError("The message id cannot be empty.");
+    }
+    const response = await this.#transport.request("GET", `/sms/${encodeURIComponent(id)}`, "safe", options);
+    return toMessage(api.object(response.body, "data"));
+  }
+  /**
+   * 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 = {}, options = {}) {
+    const page = params.page ?? 1;
+    const perPage = params.perPage ?? 15;
+    if (!Number.isInteger(page) || page < 1) {
+      throw new InvalidArgumentError("page must be an integer >= 1.");
+    }
+    if (!Number.isInteger(perPage) || perPage < 1 || perPage > MAX_PER_PAGE) {
+      throw new InvalidArgumentError(`perPage must be an integer between 1 and ${String(MAX_PER_PAGE)}.`);
+    }
+    const query = {
+      status: params.status,
+      recipient: params.recipient === void 0 ? void 0 : toApiNumberOrRaw(params.recipient, this.#defaultCountryCode),
+      reference: params.reference,
+      from: formatDate(params.from),
+      to: formatDate(params.to),
+      per_page: perPage
+    };
+    return new PagePromise(() => this.#fetchPage(query, page, options));
+  }
+  async #fetchPage(query, page, options) {
+    const response = await this.#transport.request("GET", "/sms", "safe", { query: { ...query, page }, ...options });
+    const meta = api.optionalObject(response.body, "meta");
+    const data = api.objects(response.body, "data").map(toMessage);
+    return new Page(
+      {
+        data,
+        currentPage: api.nullableInt(meta, "current_page") ?? page,
+        lastPage: api.nullableInt(meta, "last_page") ?? page,
+        perPage: api.nullableInt(meta, "per_page") ?? data.length,
+        total: api.nullableInt(meta, "total") ?? data.length
+      },
+      (next) => this.#fetchPage(query, next, options)
+    );
+  }
+  async #dispatch(target, params, options) {
+    assertBody(params.body);
+    const sender = params.sender ?? this.#defaultSender;
+    if (sender !== void 0 && (typeof sender !== "string" || sender === "" || characterCount(sender) > MAX_SENDER_LENGTH)) {
+      throw new InvalidArgumentError(`sender must be 1 to ${String(MAX_SENDER_LENGTH)} characters.`);
+    }
+    const reference = params.reference;
+    if (reference !== void 0 && (typeof reference !== "string" || characterCount(reference) > MAX_REFERENCE_LENGTH)) {
+      throw new InvalidArgumentError(`reference must be at most ${String(MAX_REFERENCE_LENGTH)} characters.`);
+    }
+    const stripAccents = params.stripAccents;
+    assertStripAccents(stripAccents);
+    const idempotencyKey = await resolveIdempotencyKey(params.idempotencyKey);
+    const body = { ...target, body: params.body };
+    if (sender !== void 0) body["sender"] = sender;
+    if (reference !== void 0 && reference !== "") body["reference"] = reference;
+    if (stripAccents !== void 0) body["strip_accents"] = stripAccents;
+    const response = await this.#transport.request("POST", "/sms", "safe", {
+      body,
+      ...options,
+      headers: { "Idempotency-Key": idempotencyKey }
+    });
+    return {
+      messages: api.objects(response.body, "data").map(toMessage),
+      idempotencyKey,
+      replayed: response.headers["idempotent-replayed"] === "true",
+      requestId: response.headers["x-request-id"] ?? null
+    };
+  }
+  toJSON() {
+    return { transport: this.#transport.toJSON(), defaultCountryCode: this.#defaultCountryCode };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toJSON();
+  }
+};
+function assertBody(body) {
+  if (typeof body !== "string" || body === "") {
+    throw new InvalidArgumentError("The SMS body cannot be empty.");
+  }
+  if (characterCount(body) > MAX_BODY_LENGTH) {
+    throw new InvalidArgumentError(`The SMS body must be at most ${String(MAX_BODY_LENGTH)} characters.`);
+  }
+}
+function formatDate(date) {
+  if (date instanceof Date) {
+    if (Number.isNaN(date.getTime())) {
+      throw new InvalidArgumentError("Invalid date in the list filters.");
+    }
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+  }
+  return date;
+}
+function toApiNumberOrRaw(raw, defaultCountryCode) {
+  const number = PhoneNumber.normalize(raw, defaultCountryCode);
+  return number === null ? raw : toApiNumber(number);
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.labyrinthe-rdc.com/api/public/v1";
+var API_PATH = "/api/public/v1";
+var INSPECT2 = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var DENO_INSPECT2 = /* @__PURE__ */ Symbol.for("Deno.customInspect");
+var Labyrinthe = class {
+  /** Send and track SMS. */
+  sms;
+  /** Credit balance. */
+  balance;
+  /** Approved Sender IDs. */
+  senderIds;
+  /** One-time passwords by SMS. */
+  otp;
+  #apiKey;
+  #baseUrl;
+  constructor(options = {}) {
+    const apiKey = (options.apiKey ?? env("LABYRINTHE_API_KEY") ?? "").trim();
+    if (apiKey === "") {
+      throw new InvalidArgumentError(
+        "A Labyrinthe Connect API key is required (lsk_live_\u2026 or lsk_test_\u2026): pass `apiKey` or set LABYRINTHE_API_KEY."
+      );
+    }
+    if (isBrowser() && options.dangerouslyAllowBrowser !== true) {
+      throw new InvalidArgumentError(
+        "The Labyrinthe Connect client must run server-side: your API key would be exposed in the browser. Call your own backend instead (or set dangerouslyAllowBrowser: true if you really know what you are doing)."
+      );
+    }
+    const timeoutMs = options.timeoutMs ?? 3e4;
+    const maxRetries = options.maxRetries ?? 2;
+    const maxRetryWaitMs = options.maxRetryWaitMs ?? 1e4;
+    const defaultCountryCode = options.defaultCountryCode ?? DEFAULT_COUNTRY_CODE;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new InvalidArgumentError("timeoutMs must be greater than 0.");
+    }
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 10) {
+      throw new InvalidArgumentError("maxRetries must be an integer between 0 and 10.");
+    }
+    if (!Number.isFinite(maxRetryWaitMs) || maxRetryWaitMs < 0) {
+      throw new InvalidArgumentError("maxRetryWaitMs cannot be negative.");
+    }
+    assertCountryCode(defaultCountryCode);
+    const defaultSender = options.defaultSender === "" ? void 0 : options.defaultSender;
+    this.#apiKey = apiKey;
+    this.#baseUrl = normalizeBaseUrl(options.baseUrl ?? env("LABYRINTHE_BASE_URL") ?? DEFAULT_BASE_URL);
+    const customFetch = options.fetch;
+    const transport = new Transport({
+      apiKey,
+      baseUrl: this.#baseUrl,
+      timeoutMs,
+      maxRetries,
+      maxRetryWaitMs,
+      // Lu à chaque appel (et lié à globalThis : Workers refuse un fetch détaché).
+      fetch: customFetch ?? ((url, init) => globalThis.fetch(url, init)),
+      logger: options.logger,
+      sleep: options.sleep ?? defaultSleep
+    });
+    this.sms = new Sms(transport, defaultCountryCode, defaultSender);
+    this.balance = new BalanceResource(transport);
+    this.senderIds = new SenderIds(transport);
+    this.otp = new Otp(transport, defaultCountryCode);
+  }
+  /** True with a sandbox key (`lsk_test_…`): nothing is sent, no credit is used. */
+  get isTestMode() {
+    return this.#apiKey.startsWith("lsk_test_");
+  }
+  /** True with a production key (`lsk_live_…`). */
+  get isLiveMode() {
+    return this.#apiKey.startsWith("lsk_live_");
+  }
+  /** The API root used by this client. */
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+  toJSON() {
+    return { apiKey: redactApiKey(this.#apiKey), baseUrl: this.#baseUrl, testMode: this.isTestMode };
+  }
+  [INSPECT2]() {
+    return this.toJSON();
+  }
+  [DENO_INSPECT2]() {
+    return `Labyrinthe ${JSON.stringify(this.toJSON())}`;
+  }
+};
+function normalizeBaseUrl(baseUrl) {
+  const trimmed = baseUrl.trim().replace(/\/+$/, "");
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    url = new URL("invalid:");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new InvalidArgumentError(
+      "baseUrl must be an absolute http(s) URL, e.g. https://api.labyrinthe-rdc.com/api/public/v1."
+    );
+  }
+  return url.pathname === "/" || url.pathname === "" ? trimmed + API_PATH : trimmed;
+}
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "X-Signature";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var PREFIX = "sha256=";
+var encoder = new TextEncoder();
+var reader = new Reader("Invalid webhook payload");
+var Webhooks = Object.freeze({
+  SIGNATURE_HEADER,
+  DEFAULT_TOLERANCE_SECONDS,
+  /**
+   * 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
+   */
+  async constructEvent(rawBody, signatureHeader, secret, options = {}) {
+    const bytes = toBytes(rawBody);
+    if (!await Webhooks.verifySignature(bytes, signatureHeader, secret)) {
+      throw new SignatureVerificationError("Invalid webhook signature: the body was not signed with this secret.");
+    }
+    let envelope;
+    try {
+      envelope = JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      throw new InvalidWebhookPayloadError("The webhook body is not valid JSON.");
+    }
+    if (!isRecord(envelope)) {
+      throw new InvalidWebhookPayloadError("The webhook body is not a JSON object.");
+    }
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (!Number.isFinite(tolerance) || tolerance < 0) {
+      throw new InvalidArgumentError("toleranceSeconds cannot be negative.");
+    }
+    try {
+      const timestamp = reader.int(envelope, "timestamp");
+      const nowMs = options.now === void 0 ? Date.now() : new Date(options.now).getTime();
+      if (tolerance > 0 && Math.abs(nowMs / 1e3 - timestamp) > tolerance) {
+        throw new SignatureVerificationError(
+          `Webhook timestamp is outside the ${String(tolerance)} s tolerance (possible replay).`
+        );
+      }
+      return buildEvent(envelope, timestamp);
+    } catch (error) {
+      if (error instanceof UnexpectedResponseError) {
+        throw new InvalidWebhookPayloadError(error.message);
+      }
+      throw error;
+    }
+  },
+  /** Constant-time check of the X-Signature header against the raw body. */
+  async verifySignature(rawBody, signatureHeader, secret) {
+    const key = await importKey(secret);
+    const signature = (signatureHeader ?? "").trim().toLowerCase();
+    if (!signature.startsWith(PREFIX)) {
+      return false;
+    }
+    const hex = signature.slice(PREFIX.length);
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+      return false;
+    }
+    const expected = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      expected[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    const crypto = await getCrypto();
+    return crypto.subtle.verify("HMAC", key, expected, toBytes(rawBody));
+  },
+  /** The X-Signature header value for a body: "sha256=<hex>". Useful to test your webhook endpoint. */
+  async sign(rawBody, secret) {
+    const key = await importKey(secret);
+    const crypto = await getCrypto();
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, toBytes(rawBody)));
+    return PREFIX + Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+});
+async function importKey(secret) {
+  if (typeof secret !== "string" || secret === "") {
+    throw new InvalidArgumentError("The webhook secret cannot be empty.");
+  }
+  const crypto = await getCrypto();
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify"
+  ]);
+}
+var OTP_STATUSES = ["verified", "failed", "expired"];
+function toOtpWebhookData(data) {
+  const status = reader.string(data, "status");
+  const reason = reader.nullableString(data, "reason");
+  return {
+    otpId: reader.string(data, "otp_id"),
+    phone: reader.string(data, "phone"),
+    status: OTP_STATUSES.includes(status) ? status : "unknown",
+    reason: reason === null ? null : reason === "max_attempts_reached" || reason === "expired" ? reason : "unknown",
+    verifiedAt: reader.nullableDate(data, "verified_at")
+  };
+}
+function toBytes(rawBody) {
+  if (typeof rawBody === "string") {
+    return encoder.encode(rawBody);
+  }
+  if (rawBody instanceof ArrayBuffer) {
+    return new Uint8Array(rawBody);
+  }
+  if (ArrayBuffer.isView(rawBody)) {
+    return new Uint8Array(rawBody);
+  }
+  throw new InvalidArgumentError(
+    "The webhook body must be the RAW request body (string, Uint8Array/Buffer or ArrayBuffer), not a parsed object."
+  );
+}
+function buildEvent(envelope, timestamp) {
+  const id = reader.string(envelope, "id");
+  const event = reader.string(envelope, "event");
+  const data = reader.optionalObject(envelope, "data");
+  const base = { id, type: event, timestamp: new Date(timestamp * 1e3), raw: envelope };
+  switch (event) {
+    case "message.status_changed":
+      return {
+        ...base,
+        event,
+        data: {
+          messageId: reader.string(data, "message_id"),
+          recipient: reader.string(data, "recipient"),
+          status: messageStatus(reader.string(data, "status")),
+          providerMessageId: reader.nullableString(data, "provider_message_id"),
+          campaignId: reader.nullableString(data, "campaign_id"),
+          // Spec 1.2.0 : absents d'un backend plus ancien → null.
+          reference: reader.nullableString(data, "reference"),
+          errorCode: reader.nullableString(data, "error_code"),
+          errorMessage: reader.nullableString(data, "error_message")
+        }
+      };
+    case "campaign.completed": {
+      const counts = reader.optionalObject(data, "messages_by_status");
+      const messagesByStatus = {};
+      for (const status of Object.keys(counts)) {
+        messagesByStatus[status] = reader.int(counts, status);
+      }
+      return {
+        ...base,
+        event,
+        data: {
+          campaignId: reader.string(data, "campaign_id"),
+          name: reader.nullableString(data, "name") ?? "",
+          recipientsCount: reader.nullableInt(data, "recipients_count") ?? 0,
+          messagesByStatus,
+          creditsCharged: reader.nullableInt(data, "credits_charged") ?? 0,
+          completedAt: reader.nullableDate(data, "completed_at")
+        }
+      };
+    }
+    case "balance.low":
+      return {
+        ...base,
+        event,
+        data: { balance: reader.int(data, "balance"), threshold: reader.int(data, "threshold") }
+      };
+    case "otp.verified":
+    case "otp.failed":
+      return { ...base, event, data: toOtpWebhookData(data) };
+    case "test.ping":
+      return { ...base, event, data };
+    default:
+      return { ...base, event: "unknown", data };
+  }
+}
+
+export { AccountSuspendedError, ApiError, AuthenticationError, BalanceResource, ConnectionError, DEFAULT_BASE_URL, DEFAULT_COUNTRY_CODE, DEFAULT_TOLERANCE_SECONDS, Encoding, FeatureDisabledError, IdempotencyKeyReusedError, IdempotencyKeyUnresolvedError, IdempotencyRequestInProgressError, InsufficientCreditsError, InvalidArgumentError, InvalidPhoneError, InvalidWebhookPayloadError, Labyrinthe, LabyrintheError, MessageStatus, NotFoundError, Otp, OtpCodeType, OtpFailureReason, OtpRateLimitScope, OtpRateLimitedError, OtpResendTooSoonError, OtpSendResult, OtpVerificationStatus, Page, PagePromise, PermissionError, PhoneNumber, RateLimitError, RecipientNotSendableError, RejectionReason, RequestAbortedError, SIGNATURE_HEADER, SenderIdNotApprovedError, SenderIdStatus, SenderIds, ServiceUnavailableError, SignatureVerificationError, Sms, TimeoutError, UnexpectedResponseError, VERSION, ValidationError, WebhookEventType, Webhooks, isFailedStatus, isFinalStatus, isPendingStatus };