@ikatec/digisac-api-sdk 3.0.0 → 4.0.0

package/src/core/errors.ts

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

package/src/core/index.ts

@@ -1,6 +1,22 @@
 export type { ApiClient, HttpMethod } from './ApiClient'
-export { BaseApiClient, ApiError } from './BaseApiClient'
-export type { ValidationError } from './BaseApiClient'
+export { BaseApiClient } from './BaseApiClient'
+export {
+  DigisacError,
+  ApiConnectionError,
+  ApiError,
+  BadRequestError,
+  ValidationError,
+  AuthenticationError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  NotFoundError,
+  ConflictError,
+  UnprocessableEntityError,
+  RateLimitError,
+  InternalServerError,
+  parseFieldErrors,
+} from './errors'
+export type { FieldError, ErrorClassName, ApiErrorOptions } from './errors'
 export { BaseCrudApi } from './BaseCrudApi'
 export { ArchivableCrudApi } from './ArchivableCrudApi'
 export type { WhereClause, IncludeItem, ListQuery, GetByIdQuery, Paginated } from './types'

package/src/incommingWebhooks/index.ts

@@ -5,7 +5,7 @@ import type { Department, DepartmentRelationships } from '../apis/departments'
 import type { Message, MessageRelationships } from '../apis/messages'
 import type { Organization, OrganizationRelationships } from '../apis/organizations'
 import type { Person, PersonRelationships } from '../apis/people'
-import type { Pipeline, PipelineRelationships } from '../apis/pipeline'
+import type { PipelineRecord } from '../apis/pipeline'
 import type { QuickReply, QuickReplyRelationships } from '../apis/quickReplies'
 import type { Role, RoleRelationships } from '../apis/roles'
 import type { Service, ServiceRelationships } from '../apis/services'
@@ -119,8 +119,8 @@ export interface WebhookEventPayloadMap {
   'campaign.created': Omit<Campaign, CampaignRelationships>
   'campaign.updated': Omit<Campaign, CampaignRelationships>
   'campaign.destroyed': Omit<Campaign, CampaignRelationships>
-  'pipeline.created': Omit<Pipeline, PipelineRelationships>
-  'pipeline.updated': Omit<Pipeline, PipelineRelationships>
+  'pipeline.created': PipelineRecord
+  'pipeline.updated': PipelineRecord
 }
 
 // ─── Webhook Envelope ────────────────────────────────────────────────────────