@ikatec/digisac-api-sdk 4.15.0 → 4.17.0

package/dist/apis/webhooks/types.d.ts

@@ -1,13 +1,43 @@
 import type { Service } from '../services/types';
+/**
+ * `by_service` and `whatsapp_low_level` only get the events of the connections in `services`.
+ * Events not tied to a connection (users, departments, tags...) reach `by_service` too. A webhook
+ * with `services`, whatever its type, only gets the events of those connections (events not tied
+ * to a connection reach it too); a `general` webhook is meant to have none.
+ */
+export type WebhookType = 'general' | 'by_service' | 'whatsapp_low_level';
+/**
+ * The categories of message the `message.created` event delivers. Only `false` leaves a category
+ * out (an absent key keeps it); `null`, or no filter, delivers every message. The other events are
+ * not filtered. A key outside these answers 400.
+ */
+export type WebhookMessageFilters = {
+    /** Messages of the contact (not their reactions). */
+    received?: boolean;
+    /** Messages sent through the connection, except the bot's (and the reactions). */
+    sent?: boolean;
+    /** Messages sent by the bot. */
+    bot?: boolean;
+    /**
+     * Internal comments, ticket events, reactions, summaries, schedules, AI evaluations, the notices
+     * of the message block rule and the message types the platform does not know.
+     */
+    system?: boolean;
+};
 export type Webhook = {
     id: string;
     name: string;
     url: string;
-    type: string;
+    /** A webhook created before the type was validated may hold another value. */
+    type: WebhookType;
     active: boolean;
     events: string[];
+    /** `null` when `events` has no `message.created` (the backend clears it on every write). */
+    messageFilters?: WebhookMessageFilters | null;
     errorAt: string | null;
     errorNotifiedAt: string | null;
+    /** The average delivery latency, in ms (shown in the list of webhooks); `null` until measured. */
+    avgLatencyMs?: number | null;
     userId: string;
     accountId: string;
     createdAt: string;
@@ -19,15 +49,30 @@ export type WebhookRelationships = 'services';
 export type CreateWebhookPayload = {
     name: string;
     url: string;
-    type: string;
+    type: WebhookType;
     events: string[];
     active?: boolean;
+    /** The connections of a `by_service` or `whatsapp_low_level` webhook (none for `general`). */
+    services?: string[];
+    /** Only kept with the `message.created` event. */
+    messageFilters?: WebhookMessageFilters | null;
 };
+/**
+ * `updateById` sends a `PUT`: `name`, `url`, `type` and `events` are required (400 without them),
+ * as in the create.
+ */
 export type UpdateWebhookPayload = {
-    name?: string;
-    url?: string;
-    type?: string;
-    events?: string[];
+    name: string;
+    url: string;
+    type: WebhookType;
+    events: string[];
     active?: boolean;
+    /**
+     * Replaces the connections of the webhook; omitted keeps them. Send `[]` when the type becomes
+     * `general`: the connections kept also filter a `general` webhook.
+     */
+    services?: string[];
+    /** Only kept with the `message.created` event. */
+    messageFilters?: WebhookMessageFilters | null;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/apis/webhooks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/apis/webhooks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAExB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAA;AAE7C,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/apis/webhooks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,oBAAoB,CAAA;AAEzE;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,gCAAgC;IAChC,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,4FAA4F;IAC5F,cAAc,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAC7C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAExB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAA;AAE7C,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,kDAAkD;IAClD,cAAc,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;CAC9C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,kDAAkD;IAClD,cAAc,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;CAC9C,CAAA"}

package/dist/core/errors.cjs

@@ -107,7 +107,10 @@ var AuthenticationError = class extends ApiError {
 var PaymentRequiredError = class extends ApiError {
 	name = "PaymentRequiredError";
 };
-/** 403 — the user lacks the permission for this action. */
+/**
+* 403 — the user lacks the permission for this action, or the action is refused (e.g. out of
+* office hours, see `OutOfOfficeHoursErrorExtra`).
+*/
 var PermissionDeniedError = class extends ApiError {
 	name = "PermissionDeniedError";
 };

package/dist/core/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","names":[],"sources":["../../src/core/errors.ts"],"sourcesContent":["/**\n * A field-level error from the backend `validate` middleware — one entry per failed rule.\n */\nexport interface FieldError {\n  /** Where the field was read from: `body`, `params`, `query`, `headers` or `cookies`. */\n  location: string\n  /** The field name, e.g. `name`. */\n  field: string\n  /** `<location>.<field>`, e.g. `body.name`. */\n  path: string\n  message: string\n  /** The failed rule, e.g. `required` or `hasLengthLesserThanOrEqual`. */\n  code: string\n}\n\n/**\n * The backend error name sent as `error` in the body (`ApiError.errorClass`). Known names are listed\n * for autocomplete; any other string is still accepted. `HttpError` is the generic one: most 400s\n * and every unexpected 500.\n */\nexport type ErrorClassName =\n  | 'HttpError'\n  | 'ValidationError'\n  | 'BadRequestHttpError'\n  | 'UnauthorizedHttpError'\n  | 'PaymentRequired'\n  | 'ForbiddenHttpError'\n  | 'NotFoundHttpError'\n  | 'TooManyRequestsHttpError'\n  | (string & {})\n\nexport interface ApiErrorOptions {\n  /** Response headers. */\n  headers?: Headers\n  /** The parsed JSON error body, or the raw text when it is not JSON. */\n  body?: unknown\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Flattens the backend `errors` object — `{ <location>: { <field>: { messages: string[], types: string[] } } }`\n * — into one {@link FieldError} per message. Returns `null` when there are no field errors.\n */\nexport function parseFieldErrors(errors: unknown): FieldError[] | null {\n  if (!isRecord(errors)) {\n    return null\n  }\n\n  const parsed: FieldError[] = []\n  for (const [location, fields] of Object.entries(errors)) {\n    if (!isRecord(fields)) {\n      continue\n    }\n    for (const [field, detail] of Object.entries(fields)) {\n      if (!isRecord(detail)) {\n        continue\n      }\n      const messages = Array.isArray(detail.messages) ? detail.messages.map(String) : []\n      const types = Array.isArray(detail.types) ? detail.types.map(String) : []\n      messages.forEach((message, index) => {\n        parsed.push({\n          location,\n          field,\n          path: `${location}.${field}`,\n          message,\n          code: types[index] ?? types[0] ?? '',\n        })\n      })\n    }\n  }\n\n  return parsed.length ? parsed : null\n}\n\n/** Base class of every error thrown by the SDK. */\nexport class DigisacError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'DigisacError'\n  }\n}\n\n/** The request never got an HTTP response (network failure, DNS, connection refused, ...). */\nexport class ApiConnectionError extends DigisacError {\n  constructor(message = 'Connection error.', options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'ApiConnectionError'\n  }\n}\n\n/**\n * The API answered with a non-2xx status. Thrown as the subclass matching the status\n * (`NotFoundError`, `BadRequestError`, ...) — or `ValidationError` for a 400 field validation\n * failure — so callers can narrow with `instanceof`.\n */\nexport class ApiError extends DigisacError {\n  /** The backend error name (`error` in the body), e.g. `ValidationError` or `PaymentRequired`. */\n  public readonly errorClass?: ErrorClassName | undefined\n  public readonly status?: number | undefined\n  /** Field errors of a 400 `ValidationError`; `null` when the response carries none. */\n  public readonly validationErrors: FieldError[] | null\n  public readonly headers?: Headers | undefined\n  /** The parsed JSON error body (`{ error, message, status, errors?, extra? }`), or the raw text. */\n  public readonly body?: unknown\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message)\n    this.name = 'ApiError'\n    this.errorClass = errorClass\n    this.status = status\n    this.validationErrors = validationErrors\n    this.headers = options.headers\n    this.body = options.body\n  }\n\n  /**\n   * Builds the `ApiError` subclass for a response and its (already read) body: `ValidationError`\n   * for a 400 `ValidationError`, else the class of the status.\n   */\n  static fromResponse(\n    status: number,\n    statusText: string,\n    headers: Headers,\n    body: unknown,\n  ): ApiError {\n    let message = `HTTP Error ${status}: ${statusText}`\n    let errorClass: string | undefined\n    let validationErrors: FieldError[] | null = null\n\n    if (isRecord(body)) {\n      const apiMessage = typeof body.message === 'string' ? body.message : undefined\n      errorClass = typeof body.error === 'string' ? body.error : undefined\n      message = apiMessage || errorClass || message\n      validationErrors = parseFieldErrors(body.errors)\n    }\n\n    const ErrorClass = errorClassFor(status, errorClass)\n    return new ErrorClass(message, errorClass, status, validationErrors, { headers, body })\n  }\n}\n\n/** 400 (see {@link ValidationError} for field validation failures). */\nexport class BadRequestError extends ApiError {\n  override name = 'BadRequestError'\n}\n\n/**\n * 400 `ValidationError` — the request failed field validation. `validationErrors` is always an\n * array here (empty when the backend sent no field details).\n */\nexport class ValidationError extends BadRequestError {\n  override name = 'ValidationError'\n  declare public readonly validationErrors: FieldError[]\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message, errorClass, status, validationErrors ?? [], options)\n  }\n}\n\n/** 401 — missing or invalid access token. */\nexport class AuthenticationError extends ApiError {\n  override name = 'AuthenticationError'\n}\n\n/** 402 — the account is out of credits or over a plan limit. */\nexport class PaymentRequiredError extends ApiError {\n  override name = 'PaymentRequiredError'\n}\n\n/** 403 — the user lacks the permission for this action. */\nexport class PermissionDeniedError extends ApiError {\n  override name = 'PermissionDeniedError'\n}\n\n/** 404 */\nexport class NotFoundError extends ApiError {\n  override name = 'NotFoundError'\n}\n\n/** 409 */\nexport class ConflictError extends ApiError {\n  override name = 'ConflictError'\n}\n\n/** 422 */\nexport class UnprocessableEntityError extends ApiError {\n  override name = 'UnprocessableEntityError'\n}\n\n/** 429 */\nexport class RateLimitError extends ApiError {\n  override name = 'RateLimitError'\n\n  /**\n   * Seconds to wait before retrying, or `null` when the response does not say.\n   *\n   * Reads the standard `Retry-After` header (delay seconds or HTTP date) first, then the\n   * `X-RateLimit-Reset` header the Digisac backend sends (Unix time in seconds).\n   */\n  get retryAfter(): number | null {\n    return (\n      parseRetryAfter(this.headers?.get('Retry-After')) ??\n      parseRateLimitReset(this.headers?.get('X-RateLimit-Reset'))\n    )\n  }\n}\n\nconst secondsUntil = (epochMs: number): number =>\n  Math.max(0, Math.ceil((epochMs - Date.now()) / 1000))\n\n/** `Retry-After`: delay seconds or an HTTP date. */\nfunction parseRetryAfter(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const seconds = Number(value)\n  if (Number.isFinite(seconds)) {\n    return Math.max(0, seconds)\n  }\n  const date = Date.parse(value)\n  return Number.isNaN(date) ? null : secondsUntil(date)\n}\n\n/**\n * `X-RateLimit-Reset`: Unix time in seconds (what the Digisac backend sends). Small values are\n * read as delay seconds instead, the other convention in use for this header.\n */\nfunction parseRateLimitReset(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const reset = Number(value)\n  if (!Number.isFinite(reset)) {\n    return null\n  }\n  // Anything before 2001-09-09 (1e9 s) can't be a reset time, so it is a delay.\n  return reset < 1e9 ? Math.max(0, reset) : secondsUntil(reset * 1000)\n}\n\n/** 5xx */\nexport class InternalServerError extends ApiError {\n  override name = 'InternalServerError'\n}\n\nfunction errorClassFor(status: number, errorClass: string | undefined): typeof ApiError {\n  if (status === 400 && errorClass === 'ValidationError') {\n    return ValidationError\n  }\n\n  switch (status) {\n    case 400:\n      return BadRequestError\n    case 401:\n      return AuthenticationError\n    case 402:\n      return PaymentRequiredError\n    case 403:\n      return PermissionDeniedError\n    case 404:\n      return NotFoundError\n    case 409:\n      return ConflictError\n    case 422:\n      return UnprocessableEntityError\n    case 429:\n      return RateLimitError\n    default:\n      return status >= 500 ? InternalServerError : ApiError\n  }\n}\n"],"mappings":";;;AAsCA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;;;;;AAMtE,SAAgB,iBAAiB,QAAsC;AACrE,KAAI,CAAC,SAAS,OAAO,CACnB,QAAO;CAGT,MAAM,SAAuB,EAAE;AAC/B,MAAK,MAAM,CAAC,UAAU,WAAW,OAAO,QAAQ,OAAO,EAAE;AACvD,MAAI,CAAC,SAAS,OAAO,CACnB;AAEF,OAAK,MAAM,CAAC,OAAO,WAAW,OAAO,QAAQ,OAAO,EAAE;AACpD,OAAI,CAAC,SAAS,OAAO,CACnB;GAEF,MAAM,WAAW,MAAM,QAAQ,OAAO,SAAS,GAAG,OAAO,SAAS,IAAI,OAAO,GAAG,EAAE;GAClF,MAAM,QAAQ,MAAM,QAAQ,OAAO,MAAM,GAAG,OAAO,MAAM,IAAI,OAAO,GAAG,EAAE;AACzE,YAAS,SAAS,SAAS,UAAU;AACnC,WAAO,KAAK;KACV;KACA;KACA,MAAM,GAAG,SAAS,GAAG;KACrB;KACA,MAAM,MAAM,UAAU,MAAM,MAAM;KACnC,CAAC;KACF;;;AAIN,QAAO,OAAO,SAAS,SAAS;;;AAIlC,IAAa,eAAb,cAAkC,MAAM;CACtC,YAAY,SAAiB,SAA+B;AAC1D,QAAM,SAAS,QAAQ;AACvB,OAAK,OAAO;;;;AAKhB,IAAa,qBAAb,cAAwC,aAAa;CACnD,YAAY,UAAU,qBAAqB,SAA+B;AACxE,QAAM,SAAS,QAAQ;AACvB,OAAK,OAAO;;;;;;;;AAShB,IAAa,WAAb,cAA8B,aAAa;;CAEzC,AAAgB;CAChB,AAAgB;;CAEhB,AAAgB;CAChB,AAAgB;;CAEhB,AAAgB;CAEhB,YACE,SACA,YACA,QACA,mBAAwC,MACxC,UAA2B,EAAE,EAC7B;AACA,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,aAAa;AAClB,OAAK,SAAS;AACd,OAAK,mBAAmB;AACxB,OAAK,UAAU,QAAQ;AACvB,OAAK,OAAO,QAAQ;;;;;;CAOtB,OAAO,aACL,QACA,YACA,SACA,MACU;EACV,IAAI,UAAU,cAAc,OAAO,IAAI;EACvC,IAAI;EACJ,IAAI,mBAAwC;AAE5C,MAAI,SAAS,KAAK,EAAE;GAClB,MAAM,aAAa,OAAO,KAAK,YAAY,WAAW,KAAK,UAAU;AACrE,gBAAa,OAAO,KAAK,UAAU,WAAW,KAAK,QAAQ;AAC3D,aAAU,cAAc,cAAc;AACtC,sBAAmB,iBAAiB,KAAK,OAAO;;AAIlD,SAAO,KADY,cAAc,QAAQ,WAAW,EAC9B,SAAS,YAAY,QAAQ,kBAAkB;GAAE;GAAS;GAAM,CAAC;;;;AAK3F,IAAa,kBAAb,cAAqC,SAAS;CAC5C,AAAS,OAAO;;;;;;AAOlB,IAAa,kBAAb,cAAqC,gBAAgB;CACnD,AAAS,OAAO;CAGhB,YACE,SACA,YACA,QACA,mBAAwC,MACxC,UAA2B,EAAE,EAC7B;AACA,QAAM,SAAS,YAAY,QAAQ,oBAAoB,EAAE,EAAE,QAAQ;;;;AAKvE,IAAa,sBAAb,cAAyC,SAAS;CAChD,AAAS,OAAO;;;AAIlB,IAAa,uBAAb,cAA0C,SAAS;CACjD,AAAS,OAAO;;;AAIlB,IAAa,wBAAb,cAA2C,SAAS;CAClD,AAAS,OAAO;;;AAIlB,IAAa,gBAAb,cAAmC,SAAS;CAC1C,AAAS,OAAO;;;AAIlB,IAAa,gBAAb,cAAmC,SAAS;CAC1C,AAAS,OAAO;;;AAIlB,IAAa,2BAAb,cAA8C,SAAS;CACrD,AAAS,OAAO;;;AAIlB,IAAa,iBAAb,cAAoC,SAAS;CAC3C,AAAS,OAAO;;;;;;;CAQhB,IAAI,aAA4B;AAC9B,SACE,gBAAgB,KAAK,SAAS,IAAI,cAAc,CAAC,IACjD,oBAAoB,KAAK,SAAS,IAAI,oBAAoB,CAAC;;;AAKjE,MAAM,gBAAgB,YACpB,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,KAAK,KAAK,IAAI,IAAK,CAAC;;AAGvD,SAAS,gBAAgB,OAAiD;AACxE,KAAI,CAAC,OAAO,MAAM,CAChB,QAAO;CAET,MAAM,UAAU,OAAO,MAAM;AAC7B,KAAI,OAAO,SAAS,QAAQ,CAC1B,QAAO,KAAK,IAAI,GAAG,QAAQ;CAE7B,MAAM,OAAO,KAAK,MAAM,MAAM;AAC9B,QAAO,OAAO,MAAM,KAAK,GAAG,OAAO,aAAa,KAAK;;;;;;AAOvD,SAAS,oBAAoB,OAAiD;AAC5E,KAAI,CAAC,OAAO,MAAM,CAChB,QAAO;CAET,MAAM,QAAQ,OAAO,MAAM;AAC3B,KAAI,CAAC,OAAO,SAAS,MAAM,CACzB,QAAO;AAGT,QAAO,QAAQ,MAAM,KAAK,IAAI,GAAG,MAAM,GAAG,aAAa,QAAQ,IAAK;;;AAItE,IAAa,sBAAb,cAAyC,SAAS;CAChD,AAAS,OAAO;;AAGlB,SAAS,cAAc,QAAgB,YAAiD;AACtF,KAAI,WAAW,OAAO,eAAe,kBACnC,QAAO;AAGT,SAAQ,QAAR;EACE,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,KAAK,IACH,QAAO;EACT,QACE,QAAO,UAAU,MAAM,sBAAsB"}
+{"version":3,"file":"errors.cjs","names":[],"sources":["../../src/core/errors.ts"],"sourcesContent":["/**\n * A field-level error from the backend `validate` middleware — one entry per failed rule.\n */\nexport interface FieldError {\n  /** Where the field was read from: `body`, `params`, `query`, `headers` or `cookies`. */\n  location: string\n  /** The field name, e.g. `name`. */\n  field: string\n  /** `<location>.<field>`, e.g. `body.name`. */\n  path: string\n  message: string\n  /** The failed rule, e.g. `required` or `hasLengthLesserThanOrEqual`. */\n  code: string\n}\n\n/**\n * The backend error name sent as `error` in the body (`ApiError.errorClass`). Known names are listed\n * for autocomplete; any other string is still accepted. `HttpError` is the generic one: most 400s\n * and every unexpected 500.\n */\nexport type ErrorClassName =\n  | 'HttpError'\n  | 'ValidationError'\n  | 'BadRequestHttpError'\n  | 'UnauthorizedHttpError'\n  | 'PaymentRequired'\n  | 'ForbiddenHttpError'\n  | 'NotFoundHttpError'\n  | 'TooManyRequestsHttpError'\n  | (string & {})\n\nexport interface ApiErrorOptions {\n  /** Response headers. */\n  headers?: Headers\n  /** The parsed JSON error body, or the raw text when it is not JSON. */\n  body?: unknown\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Flattens the backend `errors` object — `{ <location>: { <field>: { messages: string[], types: string[] } } }`\n * — into one {@link FieldError} per message. Returns `null` when there are no field errors.\n */\nexport function parseFieldErrors(errors: unknown): FieldError[] | null {\n  if (!isRecord(errors)) {\n    return null\n  }\n\n  const parsed: FieldError[] = []\n  for (const [location, fields] of Object.entries(errors)) {\n    if (!isRecord(fields)) {\n      continue\n    }\n    for (const [field, detail] of Object.entries(fields)) {\n      if (!isRecord(detail)) {\n        continue\n      }\n      const messages = Array.isArray(detail.messages) ? detail.messages.map(String) : []\n      const types = Array.isArray(detail.types) ? detail.types.map(String) : []\n      messages.forEach((message, index) => {\n        parsed.push({\n          location,\n          field,\n          path: `${location}.${field}`,\n          message,\n          code: types[index] ?? types[0] ?? '',\n        })\n      })\n    }\n  }\n\n  return parsed.length ? parsed : null\n}\n\n/** Base class of every error thrown by the SDK. */\nexport class DigisacError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'DigisacError'\n  }\n}\n\n/** The request never got an HTTP response (network failure, DNS, connection refused, ...). */\nexport class ApiConnectionError extends DigisacError {\n  constructor(message = 'Connection error.', options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'ApiConnectionError'\n  }\n}\n\n/**\n * The API answered with a non-2xx status. Thrown as the subclass matching the status\n * (`NotFoundError`, `BadRequestError`, ...) — or `ValidationError` for a 400 field validation\n * failure — so callers can narrow with `instanceof`.\n */\nexport class ApiError extends DigisacError {\n  /** The backend error name (`error` in the body), e.g. `ValidationError` or `PaymentRequired`. */\n  public readonly errorClass?: ErrorClassName | undefined\n  public readonly status?: number | undefined\n  /** Field errors of a 400 `ValidationError`; `null` when the response carries none. */\n  public readonly validationErrors: FieldError[] | null\n  public readonly headers?: Headers | undefined\n  /** The parsed JSON error body (`{ error, message, status, errors?, extra? }`), or the raw text. */\n  public readonly body?: unknown\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message)\n    this.name = 'ApiError'\n    this.errorClass = errorClass\n    this.status = status\n    this.validationErrors = validationErrors\n    this.headers = options.headers\n    this.body = options.body\n  }\n\n  /**\n   * Builds the `ApiError` subclass for a response and its (already read) body: `ValidationError`\n   * for a 400 `ValidationError`, else the class of the status.\n   */\n  static fromResponse(\n    status: number,\n    statusText: string,\n    headers: Headers,\n    body: unknown,\n  ): ApiError {\n    let message = `HTTP Error ${status}: ${statusText}`\n    let errorClass: string | undefined\n    let validationErrors: FieldError[] | null = null\n\n    if (isRecord(body)) {\n      const apiMessage = typeof body.message === 'string' ? body.message : undefined\n      errorClass = typeof body.error === 'string' ? body.error : undefined\n      message = apiMessage || errorClass || message\n      validationErrors = parseFieldErrors(body.errors)\n    }\n\n    const ErrorClass = errorClassFor(status, errorClass)\n    return new ErrorClass(message, errorClass, status, validationErrors, { headers, body })\n  }\n}\n\n/** 400 (see {@link ValidationError} for field validation failures). */\nexport class BadRequestError extends ApiError {\n  override name = 'BadRequestError'\n}\n\n/**\n * 400 `ValidationError` — the request failed field validation. `validationErrors` is always an\n * array here (empty when the backend sent no field details).\n */\nexport class ValidationError extends BadRequestError {\n  override name = 'ValidationError'\n  declare public readonly validationErrors: FieldError[]\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message, errorClass, status, validationErrors ?? [], options)\n  }\n}\n\n/** 401 — missing or invalid access token. */\nexport class AuthenticationError extends ApiError {\n  override name = 'AuthenticationError'\n}\n\n/** 402 — the account is out of credits or over a plan limit. */\nexport class PaymentRequiredError extends ApiError {\n  override name = 'PaymentRequiredError'\n}\n\n/**\n * 403 — the user lacks the permission for this action, or the action is refused (e.g. out of\n * office hours, see `OutOfOfficeHoursErrorExtra`).\n */\nexport class PermissionDeniedError extends ApiError {\n  override name = 'PermissionDeniedError'\n}\n\n/** 404 */\nexport class NotFoundError extends ApiError {\n  override name = 'NotFoundError'\n}\n\n/** 409 */\nexport class ConflictError extends ApiError {\n  override name = 'ConflictError'\n}\n\n/** 422 */\nexport class UnprocessableEntityError extends ApiError {\n  override name = 'UnprocessableEntityError'\n}\n\n/** 429 */\nexport class RateLimitError extends ApiError {\n  override name = 'RateLimitError'\n\n  /**\n   * Seconds to wait before retrying, or `null` when the response does not say.\n   *\n   * Reads the standard `Retry-After` header (delay seconds or HTTP date) first, then the\n   * `X-RateLimit-Reset` header the Digisac backend sends (Unix time in seconds).\n   */\n  get retryAfter(): number | null {\n    return (\n      parseRetryAfter(this.headers?.get('Retry-After')) ??\n      parseRateLimitReset(this.headers?.get('X-RateLimit-Reset'))\n    )\n  }\n}\n\nconst secondsUntil = (epochMs: number): number =>\n  Math.max(0, Math.ceil((epochMs - Date.now()) / 1000))\n\n/** `Retry-After`: delay seconds or an HTTP date. */\nfunction parseRetryAfter(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const seconds = Number(value)\n  if (Number.isFinite(seconds)) {\n    return Math.max(0, seconds)\n  }\n  const date = Date.parse(value)\n  return Number.isNaN(date) ? null : secondsUntil(date)\n}\n\n/**\n * `X-RateLimit-Reset`: Unix time in seconds (what the Digisac backend sends). Small values are\n * read as delay seconds instead, the other convention in use for this header.\n */\nfunction parseRateLimitReset(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const reset = Number(value)\n  if (!Number.isFinite(reset)) {\n    return null\n  }\n  // Anything before 2001-09-09 (1e9 s) can't be a reset time, so it is a delay.\n  return reset < 1e9 ? Math.max(0, reset) : secondsUntil(reset * 1000)\n}\n\n/** 5xx */\nexport class InternalServerError extends ApiError {\n  override name = 'InternalServerError'\n}\n\nfunction errorClassFor(status: number, errorClass: string | undefined): typeof ApiError {\n  if (status === 400 && errorClass === 'ValidationError') {\n    return ValidationError\n  }\n\n  switch (status) {\n    case 400:\n      return BadRequestError\n    case 401:\n      return AuthenticationError\n    case 402:\n      return PaymentRequiredError\n    case 403:\n      return PermissionDeniedError\n    case 404:\n      return NotFoundError\n    case 409:\n      return ConflictError\n    case 422:\n      return UnprocessableEntityError\n    case 429:\n      return RateLimitError\n    default:\n      return status >= 500 ? InternalServerError : ApiError\n  }\n}\n"],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -83,7 +83,10 @@ export declare class AuthenticationError extends ApiError {
 export declare class PaymentRequiredError extends ApiError {
     name: string;
 }
-/** 403 — the user lacks the permission for this action. */
+/**
+ * 403 — the user lacks the permission for this action, or the action is refused (e.g. out of
+ * office hours, see `OutOfOfficeHoursErrorExtra`).
+ */
 export declare class PermissionDeniedError extends ApiError {
     name: string;
 }

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,iBAAiB,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,0BAA0B,GAC1B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAKD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,EAAE,GAAG,IAAI,CA6BrE;AAED,mDAAmD;AACnD,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,8FAA8F;AAC9F,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIzE;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,iGAAiG;IACjG,SAAgB,UAAU,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IACvD,SAAgB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,sFAAsF;IACtF,SAAgB,gBAAgB,EAAE,UAAU,EAAE,GAAG,IAAI,CAAA;IACrD,SAAgB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7C,mGAAmG;IACnG,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAA;gBAG5B,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,cAAc,EAC3B,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,GAAE,UAAU,EAAE,GAAG,IAAW,EAC5C,OAAO,GAAE,eAAoB;IAW/B;;;OAGG;IACH,MAAM,CAAC,YAAY,CACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,GACZ,QAAQ;CAeZ;AAED,uEAAuE;AACvE,qBAAa,eAAgB,SAAQ,QAAQ;IAClC,IAAI,SAAoB;CAClC;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,eAAe;IACzC,IAAI,SAAoB;IACjC,SAAwB,gBAAgB,EAAE,UAAU,EAAE,CAAA;gBAGpD,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,cAAc,EAC3B,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,GAAE,UAAU,EAAE,GAAG,IAAW,EAC5C,OAAO,GAAE,eAAoB;CAIhC;AAED,6CAA6C;AAC7C,qBAAa,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,SAAwB;CACtC;AAED,gEAAgE;AAChE,qBAAa,oBAAqB,SAAQ,QAAQ;IACvC,IAAI,SAAyB;CACvC;AAED,2DAA2D;AAC3D,qBAAa,qBAAsB,SAAQ,QAAQ;IACxC,IAAI,SAA0B;CACxC;AAED,UAAU;AACV,qBAAa,aAAc,SAAQ,QAAQ;IAChC,IAAI,SAAkB;CAChC;AAED,UAAU;AACV,qBAAa,aAAc,SAAQ,QAAQ;IAChC,IAAI,SAAkB;CAChC;AAED,UAAU;AACV,qBAAa,wBAAyB,SAAQ,QAAQ;IAC3C,IAAI,SAA6B;CAC3C;AAED,UAAU;AACV,qBAAa,cAAe,SAAQ,QAAQ;IACjC,IAAI,SAAmB;IAEhC;;;;;OAKG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAK9B;CACF;AAkCD,UAAU;AACV,qBAAa,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,SAAwB;CACtC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.mjs

@@ -105,7 +105,10 @@ var AuthenticationError = class extends ApiError {
 var PaymentRequiredError = class extends ApiError {
 	name = "PaymentRequiredError";
 };
-/** 403 — the user lacks the permission for this action. */
+/**
+* 403 — the user lacks the permission for this action, or the action is refused (e.g. out of
+* office hours, see `OutOfOfficeHoursErrorExtra`).
+*/
 var PermissionDeniedError = class extends ApiError {
 	name = "PermissionDeniedError";
 };

package/dist/core/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/core/errors.ts"],"sourcesContent":["/**\n * A field-level error from the backend `validate` middleware — one entry per failed rule.\n */\nexport interface FieldError {\n  /** Where the field was read from: `body`, `params`, `query`, `headers` or `cookies`. */\n  location: string\n  /** The field name, e.g. `name`. */\n  field: string\n  /** `<location>.<field>`, e.g. `body.name`. */\n  path: string\n  message: string\n  /** The failed rule, e.g. `required` or `hasLengthLesserThanOrEqual`. */\n  code: string\n}\n\n/**\n * The backend error name sent as `error` in the body (`ApiError.errorClass`). Known names are listed\n * for autocomplete; any other string is still accepted. `HttpError` is the generic one: most 400s\n * and every unexpected 500.\n */\nexport type ErrorClassName =\n  | 'HttpError'\n  | 'ValidationError'\n  | 'BadRequestHttpError'\n  | 'UnauthorizedHttpError'\n  | 'PaymentRequired'\n  | 'ForbiddenHttpError'\n  | 'NotFoundHttpError'\n  | 'TooManyRequestsHttpError'\n  | (string & {})\n\nexport interface ApiErrorOptions {\n  /** Response headers. */\n  headers?: Headers\n  /** The parsed JSON error body, or the raw text when it is not JSON. */\n  body?: unknown\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Flattens the backend `errors` object — `{ <location>: { <field>: { messages: string[], types: string[] } } }`\n * — into one {@link FieldError} per message. Returns `null` when there are no field errors.\n */\nexport function parseFieldErrors(errors: unknown): FieldError[] | null {\n  if (!isRecord(errors)) {\n    return null\n  }\n\n  const parsed: FieldError[] = []\n  for (const [location, fields] of Object.entries(errors)) {\n    if (!isRecord(fields)) {\n      continue\n    }\n    for (const [field, detail] of Object.entries(fields)) {\n      if (!isRecord(detail)) {\n        continue\n      }\n      const messages = Array.isArray(detail.messages) ? detail.messages.map(String) : []\n      const types = Array.isArray(detail.types) ? detail.types.map(String) : []\n      messages.forEach((message, index) => {\n        parsed.push({\n          location,\n          field,\n          path: `${location}.${field}`,\n          message,\n          code: types[index] ?? types[0] ?? '',\n        })\n      })\n    }\n  }\n\n  return parsed.length ? parsed : null\n}\n\n/** Base class of every error thrown by the SDK. */\nexport class DigisacError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'DigisacError'\n  }\n}\n\n/** The request never got an HTTP response (network failure, DNS, connection refused, ...). */\nexport class ApiConnectionError extends DigisacError {\n  constructor(message = 'Connection error.', options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'ApiConnectionError'\n  }\n}\n\n/**\n * The API answered with a non-2xx status. Thrown as the subclass matching the status\n * (`NotFoundError`, `BadRequestError`, ...) — or `ValidationError` for a 400 field validation\n * failure — so callers can narrow with `instanceof`.\n */\nexport class ApiError extends DigisacError {\n  /** The backend error name (`error` in the body), e.g. `ValidationError` or `PaymentRequired`. */\n  public readonly errorClass?: ErrorClassName | undefined\n  public readonly status?: number | undefined\n  /** Field errors of a 400 `ValidationError`; `null` when the response carries none. */\n  public readonly validationErrors: FieldError[] | null\n  public readonly headers?: Headers | undefined\n  /** The parsed JSON error body (`{ error, message, status, errors?, extra? }`), or the raw text. */\n  public readonly body?: unknown\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message)\n    this.name = 'ApiError'\n    this.errorClass = errorClass\n    this.status = status\n    this.validationErrors = validationErrors\n    this.headers = options.headers\n    this.body = options.body\n  }\n\n  /**\n   * Builds the `ApiError` subclass for a response and its (already read) body: `ValidationError`\n   * for a 400 `ValidationError`, else the class of the status.\n   */\n  static fromResponse(\n    status: number,\n    statusText: string,\n    headers: Headers,\n    body: unknown,\n  ): ApiError {\n    let message = `HTTP Error ${status}: ${statusText}`\n    let errorClass: string | undefined\n    let validationErrors: FieldError[] | null = null\n\n    if (isRecord(body)) {\n      const apiMessage = typeof body.message === 'string' ? body.message : undefined\n      errorClass = typeof body.error === 'string' ? body.error : undefined\n      message = apiMessage || errorClass || message\n      validationErrors = parseFieldErrors(body.errors)\n    }\n\n    const ErrorClass = errorClassFor(status, errorClass)\n    return new ErrorClass(message, errorClass, status, validationErrors, { headers, body })\n  }\n}\n\n/** 400 (see {@link ValidationError} for field validation failures). */\nexport class BadRequestError extends ApiError {\n  override name = 'BadRequestError'\n}\n\n/**\n * 400 `ValidationError` — the request failed field validation. `validationErrors` is always an\n * array here (empty when the backend sent no field details).\n */\nexport class ValidationError extends BadRequestError {\n  override name = 'ValidationError'\n  declare public readonly validationErrors: FieldError[]\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message, errorClass, status, validationErrors ?? [], options)\n  }\n}\n\n/** 401 — missing or invalid access token. */\nexport class AuthenticationError extends ApiError {\n  override name = 'AuthenticationError'\n}\n\n/** 402 — the account is out of credits or over a plan limit. */\nexport class PaymentRequiredError extends ApiError {\n  override name = 'PaymentRequiredError'\n}\n\n/** 403 — the user lacks the permission for this action. */\nexport class PermissionDeniedError extends ApiError {\n  override name = 'PermissionDeniedError'\n}\n\n/** 404 */\nexport class NotFoundError extends ApiError {\n  override name = 'NotFoundError'\n}\n\n/** 409 */\nexport class ConflictError extends ApiError {\n  override name = 'ConflictError'\n}\n\n/** 422 */\nexport class UnprocessableEntityError extends ApiError {\n  override name = 'UnprocessableEntityError'\n}\n\n/** 429 */\nexport class RateLimitError extends ApiError {\n  override name = 'RateLimitError'\n\n  /**\n   * Seconds to wait before retrying, or `null` when the response does not say.\n   *\n   * Reads the standard `Retry-After` header (delay seconds or HTTP date) first, then the\n   * `X-RateLimit-Reset` header the Digisac backend sends (Unix time in seconds).\n   */\n  get retryAfter(): number | null {\n    return (\n      parseRetryAfter(this.headers?.get('Retry-After')) ??\n      parseRateLimitReset(this.headers?.get('X-RateLimit-Reset'))\n    )\n  }\n}\n\nconst secondsUntil = (epochMs: number): number =>\n  Math.max(0, Math.ceil((epochMs - Date.now()) / 1000))\n\n/** `Retry-After`: delay seconds or an HTTP date. */\nfunction parseRetryAfter(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const seconds = Number(value)\n  if (Number.isFinite(seconds)) {\n    return Math.max(0, seconds)\n  }\n  const date = Date.parse(value)\n  return Number.isNaN(date) ? null : secondsUntil(date)\n}\n\n/**\n * `X-RateLimit-Reset`: Unix time in seconds (what the Digisac backend sends). Small values are\n * read as delay seconds instead, the other convention in use for this header.\n */\nfunction parseRateLimitReset(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const reset = Number(value)\n  if (!Number.isFinite(reset)) {\n    return null\n  }\n  // Anything before 2001-09-09 (1e9 s) can't be a reset time, so it is a delay.\n  return reset < 1e9 ? Math.max(0, reset) : secondsUntil(reset * 1000)\n}\n\n/** 5xx */\nexport class InternalServerError extends ApiError {\n  override name = 'InternalServerError'\n}\n\nfunction errorClassFor(status: number, errorClass: string | undefined): typeof ApiError {\n  if (status === 400 && errorClass === 'ValidationError') {\n    return ValidationError\n  }\n\n  switch (status) {\n    case 400:\n      return BadRequestError\n    case 401:\n      return AuthenticationError\n    case 402:\n      return PaymentRequiredError\n    case 403:\n      return PermissionDeniedError\n    case 404:\n      return NotFoundError\n    case 409:\n      return ConflictError\n    case 422:\n      return UnprocessableEntityError\n    case 429:\n      return RateLimitError\n    default:\n      return status >= 500 ? InternalServerError : ApiError\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/core/errors.ts"],"sourcesContent":["/**\n * A field-level error from the backend `validate` middleware — one entry per failed rule.\n */\nexport interface FieldError {\n  /** Where the field was read from: `body`, `params`, `query`, `headers` or `cookies`. */\n  location: string\n  /** The field name, e.g. `name`. */\n  field: string\n  /** `<location>.<field>`, e.g. `body.name`. */\n  path: string\n  message: string\n  /** The failed rule, e.g. `required` or `hasLengthLesserThanOrEqual`. */\n  code: string\n}\n\n/**\n * The backend error name sent as `error` in the body (`ApiError.errorClass`). Known names are listed\n * for autocomplete; any other string is still accepted. `HttpError` is the generic one: most 400s\n * and every unexpected 500.\n */\nexport type ErrorClassName =\n  | 'HttpError'\n  | 'ValidationError'\n  | 'BadRequestHttpError'\n  | 'UnauthorizedHttpError'\n  | 'PaymentRequired'\n  | 'ForbiddenHttpError'\n  | 'NotFoundHttpError'\n  | 'TooManyRequestsHttpError'\n  | (string & {})\n\nexport interface ApiErrorOptions {\n  /** Response headers. */\n  headers?: Headers\n  /** The parsed JSON error body, or the raw text when it is not JSON. */\n  body?: unknown\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Flattens the backend `errors` object — `{ <location>: { <field>: { messages: string[], types: string[] } } }`\n * — into one {@link FieldError} per message. Returns `null` when there are no field errors.\n */\nexport function parseFieldErrors(errors: unknown): FieldError[] | null {\n  if (!isRecord(errors)) {\n    return null\n  }\n\n  const parsed: FieldError[] = []\n  for (const [location, fields] of Object.entries(errors)) {\n    if (!isRecord(fields)) {\n      continue\n    }\n    for (const [field, detail] of Object.entries(fields)) {\n      if (!isRecord(detail)) {\n        continue\n      }\n      const messages = Array.isArray(detail.messages) ? detail.messages.map(String) : []\n      const types = Array.isArray(detail.types) ? detail.types.map(String) : []\n      messages.forEach((message, index) => {\n        parsed.push({\n          location,\n          field,\n          path: `${location}.${field}`,\n          message,\n          code: types[index] ?? types[0] ?? '',\n        })\n      })\n    }\n  }\n\n  return parsed.length ? parsed : null\n}\n\n/** Base class of every error thrown by the SDK. */\nexport class DigisacError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'DigisacError'\n  }\n}\n\n/** The request never got an HTTP response (network failure, DNS, connection refused, ...). */\nexport class ApiConnectionError extends DigisacError {\n  constructor(message = 'Connection error.', options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'ApiConnectionError'\n  }\n}\n\n/**\n * The API answered with a non-2xx status. Thrown as the subclass matching the status\n * (`NotFoundError`, `BadRequestError`, ...) — or `ValidationError` for a 400 field validation\n * failure — so callers can narrow with `instanceof`.\n */\nexport class ApiError extends DigisacError {\n  /** The backend error name (`error` in the body), e.g. `ValidationError` or `PaymentRequired`. */\n  public readonly errorClass?: ErrorClassName | undefined\n  public readonly status?: number | undefined\n  /** Field errors of a 400 `ValidationError`; `null` when the response carries none. */\n  public readonly validationErrors: FieldError[] | null\n  public readonly headers?: Headers | undefined\n  /** The parsed JSON error body (`{ error, message, status, errors?, extra? }`), or the raw text. */\n  public readonly body?: unknown\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message)\n    this.name = 'ApiError'\n    this.errorClass = errorClass\n    this.status = status\n    this.validationErrors = validationErrors\n    this.headers = options.headers\n    this.body = options.body\n  }\n\n  /**\n   * Builds the `ApiError` subclass for a response and its (already read) body: `ValidationError`\n   * for a 400 `ValidationError`, else the class of the status.\n   */\n  static fromResponse(\n    status: number,\n    statusText: string,\n    headers: Headers,\n    body: unknown,\n  ): ApiError {\n    let message = `HTTP Error ${status}: ${statusText}`\n    let errorClass: string | undefined\n    let validationErrors: FieldError[] | null = null\n\n    if (isRecord(body)) {\n      const apiMessage = typeof body.message === 'string' ? body.message : undefined\n      errorClass = typeof body.error === 'string' ? body.error : undefined\n      message = apiMessage || errorClass || message\n      validationErrors = parseFieldErrors(body.errors)\n    }\n\n    const ErrorClass = errorClassFor(status, errorClass)\n    return new ErrorClass(message, errorClass, status, validationErrors, { headers, body })\n  }\n}\n\n/** 400 (see {@link ValidationError} for field validation failures). */\nexport class BadRequestError extends ApiError {\n  override name = 'BadRequestError'\n}\n\n/**\n * 400 `ValidationError` — the request failed field validation. `validationErrors` is always an\n * array here (empty when the backend sent no field details).\n */\nexport class ValidationError extends BadRequestError {\n  override name = 'ValidationError'\n  declare public readonly validationErrors: FieldError[]\n\n  constructor(\n    message: string,\n    errorClass?: ErrorClassName,\n    status?: number,\n    validationErrors: FieldError[] | null = null,\n    options: ApiErrorOptions = {},\n  ) {\n    super(message, errorClass, status, validationErrors ?? [], options)\n  }\n}\n\n/** 401 — missing or invalid access token. */\nexport class AuthenticationError extends ApiError {\n  override name = 'AuthenticationError'\n}\n\n/** 402 — the account is out of credits or over a plan limit. */\nexport class PaymentRequiredError extends ApiError {\n  override name = 'PaymentRequiredError'\n}\n\n/**\n * 403 — the user lacks the permission for this action, or the action is refused (e.g. out of\n * office hours, see `OutOfOfficeHoursErrorExtra`).\n */\nexport class PermissionDeniedError extends ApiError {\n  override name = 'PermissionDeniedError'\n}\n\n/** 404 */\nexport class NotFoundError extends ApiError {\n  override name = 'NotFoundError'\n}\n\n/** 409 */\nexport class ConflictError extends ApiError {\n  override name = 'ConflictError'\n}\n\n/** 422 */\nexport class UnprocessableEntityError extends ApiError {\n  override name = 'UnprocessableEntityError'\n}\n\n/** 429 */\nexport class RateLimitError extends ApiError {\n  override name = 'RateLimitError'\n\n  /**\n   * Seconds to wait before retrying, or `null` when the response does not say.\n   *\n   * Reads the standard `Retry-After` header (delay seconds or HTTP date) first, then the\n   * `X-RateLimit-Reset` header the Digisac backend sends (Unix time in seconds).\n   */\n  get retryAfter(): number | null {\n    return (\n      parseRetryAfter(this.headers?.get('Retry-After')) ??\n      parseRateLimitReset(this.headers?.get('X-RateLimit-Reset'))\n    )\n  }\n}\n\nconst secondsUntil = (epochMs: number): number =>\n  Math.max(0, Math.ceil((epochMs - Date.now()) / 1000))\n\n/** `Retry-After`: delay seconds or an HTTP date. */\nfunction parseRetryAfter(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const seconds = Number(value)\n  if (Number.isFinite(seconds)) {\n    return Math.max(0, seconds)\n  }\n  const date = Date.parse(value)\n  return Number.isNaN(date) ? null : secondsUntil(date)\n}\n\n/**\n * `X-RateLimit-Reset`: Unix time in seconds (what the Digisac backend sends). Small values are\n * read as delay seconds instead, the other convention in use for this header.\n */\nfunction parseRateLimitReset(value: string | null | undefined): number | null {\n  if (!value?.trim()) {\n    return null\n  }\n  const reset = Number(value)\n  if (!Number.isFinite(reset)) {\n    return null\n  }\n  // Anything before 2001-09-09 (1e9 s) can't be a reset time, so it is a delay.\n  return reset < 1e9 ? Math.max(0, reset) : secondsUntil(reset * 1000)\n}\n\n/** 5xx */\nexport class InternalServerError extends ApiError {\n  override name = 'InternalServerError'\n}\n\nfunction errorClassFor(status: number, errorClass: string | undefined): typeof ApiError {\n  if (status === 400 && errorClass === 'ValidationError') {\n    return ValidationError\n  }\n\n  switch (status) {\n    case 400:\n      return BadRequestError\n    case 401:\n      return AuthenticationError\n    case 402:\n      return PaymentRequiredError\n    case 403:\n      return PermissionDeniedError\n    case 404:\n      return NotFoundError\n    case 409:\n      return ConflictError\n    case 422:\n      return UnprocessableEntityError\n    case 429:\n      return RateLimitError\n    default:\n      return status >= 500 ? InternalServerError : ApiError\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikatec/digisac-api-sdk",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/src/apis/absence/AbsenceApi.ts

@@ -23,8 +23,8 @@ export class AbsenceApi extends BaseCrudApi<Absence, CreateAbsencePayload, Updat
   }
 
   /**
-   * The absence report of the account (`GET /absence`), always paginated, with its own query (the rows are
-   * raw: see `AbsenceReportItem`). Prefer it to `getMany`, whose `where`/`include`/`paginate` the backend
+   * The absence report of the account (`GET /absence`), always paginated, with its own query (see
+   * `AbsenceReportItem`). Prefer it to `getMany`, whose `where`/`include`/`paginate` the backend
    * ignores. Requires both permissions, always: without them it answers 403
    * `MISSING_ABSENCE_REPORT_PERMISSION`.
    * @permissions overview.absence.view AND myAccount.absence

package/src/apis/absence/types.ts

@@ -56,7 +56,7 @@ export type AbsenceReportQuery = {
 }
 
 /**
- * A row of the report: the stored absence with its user, both raw (not transformed).
+ * A row of the report: the stored absence with its `user`.
  */
 export type AbsenceReportItem = Omit<Absence, 'deletedAt' | 'user'> & {
   user?: Record<string, unknown>

package/src/apis/answers/AnswersApi.test.ts

@@ -64,4 +64,36 @@ describe('AnswersApi', () => {
     expect(await api.deleteById('a1', headers)).toBe('OK')
     expect(client.delete).toHaveBeenCalledWith('/answers/a1', headers)
   })
+
+  it('exportTxtRaw resolves the whole Response of requestRaw', async () => {
+    const response = new Response('Protocolo: 1\n', { headers: { 'Content-Type': 'plain/text' } })
+    const requestRaw = vi.fn().mockResolvedValue(response)
+    client.requestRaw = requestRaw
+    expect(await api.exportTxtRaw(query, headers)).toBe(response)
+    expect(requestRaw).toHaveBeenCalledWith(
+      'GET',
+      `/answers/exportation-txt${encoded}`,
+      undefined,
+      headers,
+    )
+  })
+
+  it('exportCsvRaw calls requestRaw with /answers/exportation-csv', async () => {
+    const requestRaw = vi.fn().mockResolvedValue(new Response(''))
+    client.requestRaw = requestRaw
+    await api.exportCsvRaw(query, headers)
+    expect(requestRaw).toHaveBeenCalledWith(
+      'GET',
+      `/answers/exportation-csv${encoded}`,
+      undefined,
+      headers,
+    )
+  })
+
+  it.each(['exportCsvRaw', 'exportTxtRaw'] as const)(
+    '%s refuses a client without requestRaw',
+    async (method) => {
+      await expect(api[method](query)).rejects.toThrow(`${method} needs a client with requestRaw`)
+    },
+  )
 })

package/src/apis/answers/AnswersApi.ts

@@ -10,8 +10,7 @@ import type {
 } from './types'
 
 /**
- * Answers of the evaluation questions. They are written by the bot flow (`SEND_QUESTION`); the
- * CRUD routes exist but validate nothing.
+ * Answers of the evaluation questions. They are written by the bot flow (`SEND_QUESTION`).
  *
  * Permissions: `evaluation.view` to read, `evaluation.create`/`update`/`destroy` to write.
  */
@@ -70,4 +69,41 @@ export class AnswersApi extends BaseCrudApi<
       headers,
     )
   }
+
+  /**
+   * The {@link exportCsv} export as the whole `Response`, to read its headers (`Content-Type`,
+   * `Content-Disposition`) as well as the body. Needs a client with `requestRaw`. Errors are thrown
+   * as in `exportCsv`.
+   * @permissions overview.evaluation.view
+   */
+  exportCsvRaw(query?: AnswersReportQuery, headers?: Record<string, string>): Promise<Response> {
+    return this.exportResponse('exportation-csv', 'exportCsvRaw', query, headers)
+  }
+
+  /**
+   * The {@link exportTxt} export as the whole `Response`, to read its headers (`Content-Type`,
+   * `Content-Disposition`) as well as the body. The Content-Type is `plain/text` (not
+   * `text/plain`). Needs a client with `requestRaw`. Errors are thrown as in `exportTxt`.
+   * @permissions overview.evaluation.view
+   */
+  exportTxtRaw(query?: AnswersReportQuery, headers?: Record<string, string>): Promise<Response> {
+    return this.exportResponse('exportation-txt', 'exportTxtRaw', query, headers)
+  }
+
+  private async exportResponse(
+    route: 'exportation-csv' | 'exportation-txt',
+    method: 'exportCsvRaw' | 'exportTxtRaw',
+    query?: AnswersReportQuery,
+    headers?: Record<string, string>,
+  ): Promise<Response> {
+    if (!this.client.requestRaw) {
+      throw new Error(`${method} needs a client with requestRaw (the answer is read as a Response)`)
+    }
+    return this.client.requestRaw(
+      'GET',
+      `${this.basePath}/${route}${this.toQueryString(query)}`,
+      undefined,
+      headers,
+    )
+  }
 }

package/src/apis/answers/types.ts

@@ -26,8 +26,7 @@ export type Answer = {
 export type AnswerRelationships = 'question' | 'ticket'
 
 /**
- * The route validates nothing: not the question, the ticket nor their account, and the answer is
- * saved even for an open ticket.
+ * The answer of a question of the account to a ticket of the account (an open ticket included).
  */
 export type CreateAnswerPayload = {
   text: string

package/src/apis/bots/BotsApi.test.ts

@@ -174,4 +174,20 @@ describe('BotsApi', () => {
       expect(client.post).toHaveBeenCalledWith('/bots/suggest-agent-prompt', body, undefined)
     })
   })
+
+  describe('exportErrors', () => {
+    it('resolves the binary xlsx of requestRaw', async () => {
+      const requestRaw = vi.fn().mockResolvedValue(new Response(new ArrayBuffer(8)))
+      client.requestRaw = requestRaw
+      const result = await api.exportErrors('b1', headers)
+      expect(result.byteLength).toBe(8)
+      expect(requestRaw).toHaveBeenCalledWith('GET', '/bots/b1/errors/export', undefined, headers)
+    })
+
+    it('refuses a client without requestRaw', async () => {
+      await expect(api.exportErrors('b1')).rejects.toThrow(
+        'exportErrors needs a client with requestRaw',
+      )
+    })
+  })
 })

package/src/apis/bots/BotsApi.ts

@@ -21,9 +21,6 @@ import type {
  * Bots. The list route always paginates (`paginate: false` is ignored), so this class does not
  * extend `BaseCrudApi`. The contexts travel as a list (`BotContextInput` / `BotParsedContext`),
  * not as the stored map that `BotVersionsApi` serves.
- *
- * `GET /bots/:id/errors/export` is not exposed: it answers a binary xlsx, and `ApiClient` only
- * handles JSON/text bodies.
  */
 export class BotsApi
   extends BaseApi
@@ -107,10 +104,32 @@ export class BotsApi
     )
   }
 
+  /**
+   * Exports the failed steps of the bot runs of the last 30 days as an xlsx workbook (binary).
+   * Needs a client with `requestRaw`. A period without errors answers 400 `No errors found to
+   * export`; an unknown bot answers 404.
+   * @permissions bots.view
+   */
+  async exportErrors(id: string, headers?: Record<string, string>): Promise<ArrayBuffer> {
+    if (!this.client.requestRaw) {
+      throw new Error('exportErrors needs a client with requestRaw (the answer is a binary xlsx)')
+    }
+    const response = await this.client.requestRaw(
+      'GET',
+      `${this.basePath}/${id}/errors/export`,
+      undefined,
+      headers,
+    )
+    return response.arrayBuffer()
+  }
+
   /**
    * Fires the `API_SIGNAL` trigger of the bot for the contact, with an optional `flag` (read by
    * the `api_signal_flag` condition). Asynchronous: always resolves with no content, and the
-   * worker only runs it when the contact has an open ticket.
+   * worker only runs it when the contact has an open ticket. The worker runs the flow of `botId`
+   * on the engine of the bot of the contact's connection (see `BotSettings.botCreatedVersion`; when
+   * the connection has no bot, the engine of the `botId` bot). `triggerSignal` does not reach the
+   * bot simulator (there the `API_SIGNAL` path is picked by hand, with no `flag`).
    * @permissions bots.view
    */
   triggerSignal(
@@ -148,9 +167,8 @@ export class BotsApi
 
   /**
    * Generates a prompt for an AI agent of the bot. COSTS one AI agent credit of the account and
-   * calls OpenAI. No permission check: any authenticated user. A missing field answers 400; an
-   * option outside the lists, or the AI agent limit of the account reached
-   * (`Agent limit reached`), answers 500.
+   * calls OpenAI. A missing field answers 400; an option outside the lists, or the AI agent limit
+   * of the account reached (`Agent limit reached`), answers 500.
    */
   suggestAgentPrompt(
     body: SuggestAgentPromptPayload,

package/src/apis/bots/types.ts

@@ -14,7 +14,11 @@ export type BotLimitations = {
 export type BotSettings = {
   /** If true, only the first matching rule per trigger fires; otherwise all matching rules fire. */
   sequentialRuleExecution?: boolean
-  /** Version of the bot builder used to create this bot. v3 uses the visual flow builder. */
+  /**
+   * Version of the bot builder used to create this bot, which also picks the engine that runs it:
+   * `v3` (the visual flow builder) runs on the flow engine; `v1`, `v2` or absent, on the legacy
+   * engine. The bot simulator always runs the flow engine.
+   */
   botCreatedVersion?: BotCreatedVersion
   limitations?: BotLimitations
 }
@@ -191,6 +195,11 @@ export type BotActionDataMap = {
     /** Waits `waitSeconds` to group the contact's messages before answering. */
     messageGrouping?: { enabled?: boolean; waitSeconds?: number }
   }
+  /**
+   * Runs on the flow engine (`botCreatedVersion: 'v3'`). `endpointUrl`, `httpMethod`, `retries`,
+   * `timeout` and `bodyType` are required to run it: without one of them the step does not run.
+   * The bot simulator does not run it.
+   */
   HTTP_REQUEST: {
     requestName?: string
     endpointUrl?: string
@@ -204,8 +213,9 @@ export type BotActionDataMap = {
     requestBodyFormData?: { key: string; value: string }[]
     requestBodyJson?: string
     requestBodyXml?: string
+    /** Number of attempts (at least 1), not of retries after the first one. */
     retries?: number
-    /** Timeout in milliseconds. */
+    /** Timeout of each attempt, in SECONDS. */
     timeout?: number
     /** Response properties to extract into bot session variables. */
     variables?: { key: string; value: string }[]

package/src/apis/campaigns/CampaignsApi.test.ts

@@ -105,6 +105,54 @@ describe('CampaignsApi', () => {
     })
   })
 
+  // ── getOne ───────────────────────────────────────────────────────
+
+  describe('getOne', () => {
+    it('reads the first page of one campaign, leaving out paginate and limit', async () => {
+      vi.mocked(client.get).mockResolvedValue(paginated)
+      const result = await api.getOne({
+        where: { title: 'Test Campaign' },
+        status: 'ready',
+        paginate: false,
+        limit: 5,
+        page: 3,
+      })
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
+      expect(url.startsWith('/campaigns?query=')).toBe(true)
+      expect(JSON.parse(decodeURIComponent(url.slice('/campaigns?query='.length)))).toEqual({
+        where: { title: 'Test Campaign' },
+        status: 'ready',
+        page: 1,
+        perPage: 1,
+      })
+      expect(result).toEqual(campaign)
+    })
+
+    it('resolves null when no campaign matches', async () => {
+      vi.mocked(client.get).mockResolvedValue({ ...paginated, data: [], total: 0 })
+      expect(await api.getOne({ q: 'none' })).toBeNull()
+    })
+
+    it('resolves null for an empty body', async () => {
+      vi.mocked(client.get).mockResolvedValue(undefined)
+      expect(await api.getOne()).toBeNull()
+      expect(client.get).toHaveBeenCalledWith(
+        `/campaigns?query=${encodeURIComponent(JSON.stringify({ page: 1, perPage: 1 }))}`,
+        undefined,
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(paginated)
+      const headers = { 'X-Custom': 'value' }
+      await api.getOne(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/campaigns?query=${encodeURIComponent(JSON.stringify({ page: 1, perPage: 1 }))}`,
+        headers,
+      )
+    })
+  })
+
   // ── getById ──────────────────────────────────────────────────────
 
   describe('getById', () => {

package/src/apis/campaigns/CampaignsApi.ts

@@ -1,5 +1,5 @@
 import qs from 'qs'
-import type { ApiClient } from '../../core'
+import type { ApiClient, Paginated } from '../../core'
 import { BaseCrudApi } from '../../core'
 import type {
   AutoPauseModePayload,
@@ -25,6 +25,7 @@ import type {
  * {@link CampaignListQuery}); `getById` of an unknown id resolves `null`. `deleteById` answers the
  * text `'OK'`. `getMany({ paginate: false })` answers 400 `FILTER_PARAM_INVALID` with the default
  * `'json'` query format (the route only takes `paginate` as a string): use `withQueryFormat('qs')`.
+ * `getOne` reads a page of one campaign, so it works with every query format.
  */
 export class CampaignsApi extends BaseCrudApi<
   Campaign,
@@ -37,6 +38,28 @@ export class CampaignsApi extends BaseCrudApi<
     super(client, '/campaigns')
   }
 
+  /**
+   * Returns the first campaign matching the query, or `null` when none match. Reads the first page
+   * with one campaign (`page: 1`, `perPage: 1`: the `page` and `perPage` of the query are
+   * replaced, and its `paginate` and `limit` are left out), so the campaign comes with the `stats`
+   * of `getMany`.
+   * @permissions campaigns.view
+   */
+  override async getOne(
+    query?: CampaignListQuery,
+    headers?: Record<string, string>,
+  ): Promise<Campaign | null> {
+    const pageQuery: CampaignListQuery = { ...query, page: 1, perPage: 1 }
+    delete pageQuery.paginate
+    delete pageQuery.limit
+    const page = await this.client.get<Paginated<Campaign> | undefined>(
+      `${this.basePath}${this.toQueryString(pageQuery)}`,
+      headers,
+    )
+    // An empty response body resolves to `undefined`.
+    return page?.data?.[0] ?? null
+  }
+
   /**
    * Starts sending the campaign: answers it as `processing` (an `import_error` campaign goes back
    * to `importing_contacts`). It becomes `done` once every contact is fired.
@@ -205,7 +228,13 @@ export class CampaignsApi extends BaseCrudApi<
     )
   }
 
-  /** Returns the HSM message usage and limit of an account. */
+  /**
+   * Returns the HSM message usage and limit of the account of the current user (send its
+   * `accountId`).
+   * @deprecated Use `WhatsappBusinessTemplatesApi.getHsmLimit` (the same route, outside
+   * `/campaigns`).
+   * @permissions hsm.view
+   */
   getHsmLimit(accountId: string, headers?: Record<string, string>): Promise<HsmLimit> {
     return this.client.get<HsmLimit>(`/whatsapp-business-templates/${accountId}/hsmLimit`, headers)
   }