@ikatec/digisac-api-sdk 3.0.0 → 4.0.0

package/dist/index.cjs

@@ -1,10 +1,24 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_core_errors = require('./core/errors.cjs');
 const require_core_BaseApiClient = require('./core/BaseApiClient.cjs');
 const require_core_BaseCrudApi = require('./core/BaseCrudApi.cjs');
 const require_core_ArchivableCrudApi = require('./core/ArchivableCrudApi.cjs');
 require('./core/index.cjs');
 
-exports.ApiError = require_core_BaseApiClient.ApiError;
+exports.ApiConnectionError = require_core_errors.ApiConnectionError;
+exports.ApiError = require_core_errors.ApiError;
 exports.ArchivableCrudApi = require_core_ArchivableCrudApi.ArchivableCrudApi;
+exports.AuthenticationError = require_core_errors.AuthenticationError;
+exports.BadRequestError = require_core_errors.BadRequestError;
 exports.BaseApiClient = require_core_BaseApiClient.BaseApiClient;
-exports.BaseCrudApi = require_core_BaseCrudApi.BaseCrudApi;
+exports.BaseCrudApi = require_core_BaseCrudApi.BaseCrudApi;
+exports.ConflictError = require_core_errors.ConflictError;
+exports.DigisacError = require_core_errors.DigisacError;
+exports.InternalServerError = require_core_errors.InternalServerError;
+exports.NotFoundError = require_core_errors.NotFoundError;
+exports.PaymentRequiredError = require_core_errors.PaymentRequiredError;
+exports.PermissionDeniedError = require_core_errors.PermissionDeniedError;
+exports.RateLimitError = require_core_errors.RateLimitError;
+exports.UnprocessableEntityError = require_core_errors.UnprocessableEntityError;
+exports.ValidationError = require_core_errors.ValidationError;
+exports.parseFieldErrors = require_core_errors.parseFieldErrors;

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { ApiError, BaseApiClient } from "./core/BaseApiClient.mjs";
+import { ApiConnectionError, ApiError, AuthenticationError, BadRequestError, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors } from "./core/errors.mjs";
+import { BaseApiClient } from "./core/BaseApiClient.mjs";
 import { BaseCrudApi } from "./core/BaseCrudApi.mjs";
 import { ArchivableCrudApi } from "./core/ArchivableCrudApi.mjs";
 import "./core/index.mjs";
 
-export { ApiError, ArchivableCrudApi, BaseApiClient, BaseCrudApi };
+export { ApiConnectionError, ApiError, ArchivableCrudApi, AuthenticationError, BadRequestError, BaseApiClient, BaseCrudApi, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors };

package/package.json

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

package/src/apis/cards/types.ts

@@ -1,14 +1,79 @@
 import type { Contact } from '../contacts/types'
-import type { Pipeline } from '../pipeline/types'
+import type {
+  Pipeline,
+  PipelineStage,
+  PipelineStageReason,
+  PipelineStageStatus,
+} from '../pipeline/types'
 import type { User } from '../users/types'
 
+type NamedRef = { id: string; name: string }
+
+/** One entry of the card history — written on create and on every stage/status/owner change. */
+export type CardMovement = {
+  id: string
+  cardId: string
+  accountId: string
+  /** The user who made the change (the requester), not the card owner. */
+  userId: string
+  pipelineId: string
+  fromPipelineId: string | null
+  toPipelineId: string | null
+  fromPipelineStageId: string | null
+  toPipelineStageId: string | null
+  fromStageStatusId: string | null
+  toStageStatusId: string | null
+  fromOwnerId: string | null
+  toOwnerId: string | null
+  createdAt: string
+  // relationships (GET /cards/{id})
+  user?: NamedRef | null
+  from_pipeline?: NamedRef | null
+  to_pipeline?: NamedRef | null
+  from_pipeline_stage?: NamedRef | null
+  to_pipeline_stage?: NamedRef | null
+  from_stage_status?: NamedRef | null
+  to_stage_status?: NamedRef | null
+  from_owner?: NamedRef | null
+  to_owner?: NamedRef | null
+}
+
+export type CardProduct = {
+  id: string
+  cardId: string
+  name: string
+  /** Quantity (the backend column is spelled `ammount`). */
+  ammount: number
+  value: number
+  createdAt: string
+  updatedAt: string
+}
+
+export type CardComment = {
+  id: string
+  cardId: string
+  userId: string | null
+  comment: string | null
+  createdAt: string
+  updatedAt: string
+  user?: User | null
+  files?: Record<string, unknown>[]
+}
+
+/**
+ * A sales funnel card (opportunity).
+ *
+ * `create` and `updateById` answer the raw entity (with `updatedAt`/`archivedAt`). `getMany` and
+ * `getById` go through the backend transformer: no `updatedAt`/`archivedAt`, plus `url`,
+ * `lastMessage` and `totalValue`; `getById` also joins the relationships below.
+ */
 export type Card = {
   id: string
   title: string
   description: string | null
+  /** Position in the stage — set by the backend to the number of cards already in it. */
   order: number | null
   isArchived: boolean
-  archivedAt: string | null
   success: boolean | null
   finishedAt: string | null
   organization: string | null
@@ -23,41 +88,73 @@ export type Card = {
   reasonId: string | null
   ownerId: string | null
   createdAt: string
-  updatedAt: string
+  /** Only on create/update answers. */
+  updatedAt?: string
+  /** Only on create/update answers. */
+  archivedAt?: string | null
+  /** Only on getMany/getById answers (contact avatar URL, or empty string). */
+  url?: unknown
+  /** Only on getMany/getById answers (contact last message, or empty string). */
+  lastMessage?: unknown
+  /** Only on getMany/getById answers: sum of the products (`ammount * value`). */
+  totalValue?: number
   // relationships
   contact?: Contact | null
   owner?: User | null
   pipeline?: Pipeline
+  pipeline_stage?: PipelineStage | null
+  stage_status?: PipelineStageStatus | null
+  stage_reason?: PipelineStageReason | null
+  movements?: CardMovement[]
+  products?: CardProduct[]
+  comments?: CardComment[]
 }
 
-export type CardRelationships = 'contact' | 'owner' | 'pipeline'
+export type CardRelationships =
+  | 'contact'
+  | 'owner'
+  | 'pipeline'
+  | 'pipeline_stage'
+  | 'stage_status'
+  | 'stage_reason'
+  | 'movements'
+  | 'products'
+  | 'comments'
 
 export type CreateCardPayload = {
+  /** Up to 255 characters. */
   title: string
   pipelineId: string
-  contactId?: string
-  pipelineStageId?: string
+  contactId: string
+  /** Must be a stage of `pipelineId`. */
+  pipelineStageId: string
   description?: string
+  ownerId?: string
+  statusId?: string
+  reasonId?: string
   organization?: string
   organizationSegment?: string
   originChannel?: string
   originCampaign?: string
-  ownerId?: string
 }
 
 export type UpdateCardPayload = {
   title?: string
   description?: string | null
   contactId?: string | null
+  /** Moves the card to another pipeline (send the target `pipelineStageId` along). */
+  pipelineId?: string
   pipelineStageId?: string | null
   statusId?: string | null
   reasonId?: string | null
   ownerId?: string | null
+  order?: number
   organization?: string | null
   organizationSegment?: string | null
   originChannel?: string | null
   originCampaign?: string | null
   isArchived?: boolean
+  /** Marks the card as won (`true`) or lost (`false`); the backend fills `finishedAt`. */
   success?: boolean | null
   finishedAt?: string | null
 }

package/src/apis/pipeline/types.ts

@@ -1,6 +1,50 @@
 import type { Department } from '../departments/types'
 
-export type Pipeline = {
+export type PipelineStageStatus = {
+  id: string
+  /** The default "Finalizados" stage carries `STATUS_WON` and `STATUS_LOOSE`. */
+  name: string
+  position: number
+  pipelineId: string
+  stageId: string
+  accountId: string
+  createdAt: string
+  updatedAt: string
+  deletedAt: string | null
+}
+
+export type PipelineStageReason = {
+  id: string
+  name: string
+  position: number
+  isWon: boolean
+  pipelineId: string
+  stageId: string
+  accountId: string
+  createdAt: string
+  updatedAt: string
+}
+
+export type PipelineStage = {
+  id: string
+  name: string
+  position: number
+  pipelineId: string
+  accountId: string
+  createdAt: string
+  updatedAt: string
+  deletedAt: string | null
+  statuses?: PipelineStageStatus[]
+  reasons?: PipelineStageReason[]
+  /** Card totals — present on create/update/getById, absent on the listing `include`. */
+  totalCards?: number
+  totalCardsValue?: number
+  totalWonCardsValue?: number
+  totalLostCardsValue?: number
+}
+
+/** The pipeline row as stored — what the webhook events (`pipeline.created`/`.updated`) carry. */
+export type PipelineRecord = {
   id: string
   name: string
   goBack: boolean
@@ -10,20 +54,44 @@ export type Pipeline = {
   createdAt: string
   updatedAt: string
   deletedAt: string | null
+}
+
+/**
+ * A sales funnel pipeline.
+ *
+ * `create`, `updateById` and `getById` answer the full entity, always with `stages`. The listing
+ * (`getMany`) goes through the backend transformer and only carries `id`, `name`, `goBack` and
+ * `archivedAt` (plus the included relationships) — hence the optional fields below.
+ */
+export type Pipeline = {
+  id: string
+  name: string
+  goBack: boolean
+  archivedAt: string | null
+  accountId?: string
+  permissionToViewCard?: boolean | null
+  createdAt?: string
+  updatedAt?: string
+  deletedAt?: string | null
   // relationships
+  stages?: PipelineStage[]
   departments?: Department[]
 }
 
-export type PipelineRelationships = 'departments'
+export type PipelineRelationships = 'departments' | 'stages'
 
 export type CreatePipelinePayload = {
+  /** Up to 100 characters; must be unique in the account. */
   name: string
+  /** `false` = only move forward, `true` = move forward and backward. */
   goBack?: boolean
+  /** When `true`, non-admin users only see the cards they own. */
   permissionToViewCard?: boolean
 }
 
 export type UpdatePipelinePayload = {
-  name?: string
+  /** Required by the backend on every update (400 `required` otherwise). */
+  name: string
   goBack?: boolean
   permissionToViewCard?: boolean | null
 }

package/src/core/BaseApiClient.test.ts

@@ -1,5 +1,20 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { BaseApiClient, ApiError } from './BaseApiClient'
+import { BaseApiClient } from './BaseApiClient'
+import {
+  ApiConnectionError,
+  ApiError,
+  AuthenticationError,
+  BadRequestError,
+  ConflictError,
+  DigisacError,
+  InternalServerError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  RateLimitError,
+  UnprocessableEntityError,
+  ValidationError,
+} from './errors'
 
 function mockFetch(response: {
   ok: boolean
@@ -216,20 +231,219 @@ describe('BaseApiClient', () => {
     })
   })
 
-  it('includes validationErrors from JSON error response', async () => {
-    const validationErrors = [{ path: 'name', message: 'required', code: 'REQUIRED' }]
+  it('maps the backend field errors (errors.<location>.<field>) into validationErrors', async () => {
     mockFetch({
       ok: false,
-      status: 422,
-      statusText: 'Unprocessable Entity',
+      status: 400,
+      statusText: 'Bad Request',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        error: 'ValidationError',
+        message: 'The given data was invalid.',
+        status: 400,
+        errors: {
+          body: {
+            name: { messages: ['Required.'], types: ['required'] },
+            title: {
+              messages: ['Required.', 'Should contain lesser than or equals 255 characters.'],
+              types: ['required', 'hasLengthLesserThanOrEqual'],
+            },
+          },
+          params: { contactId: { messages: ['Should be an UUID v4 string.'], types: ['uuid4'] } },
+        },
+      }),
+    })
+    const error = await client.post('/fail', {}).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ValidationError)
+    expect(error).toBeInstanceOf(BadRequestError)
+    expect(error).toMatchObject({
+      message: 'The given data was invalid.',
+      errorClass: 'ValidationError',
+      status: 400,
+      validationErrors: [
+        {
+          location: 'body',
+          field: 'name',
+          path: 'body.name',
+          message: 'Required.',
+          code: 'required',
+        },
+        {
+          location: 'body',
+          field: 'title',
+          path: 'body.title',
+          message: 'Required.',
+          code: 'required',
+        },
+        {
+          location: 'body',
+          field: 'title',
+          path: 'body.title',
+          message: 'Should contain lesser than or equals 255 characters.',
+          code: 'hasLengthLesserThanOrEqual',
+        },
+        {
+          location: 'params',
+          field: 'contactId',
+          path: 'params.contactId',
+          message: 'Should be an UUID v4 string.',
+          code: 'uuid4',
+        },
+      ],
+    })
+  })
+
+  it('keeps validationErrors null when the error body has no field errors', async () => {
+    mockFetch({
+      ok: false,
+      status: 400,
+      statusText: 'Bad Request',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ error: 'BadRequestHttpError', message: 'Já existe', status: 400 }),
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({ validationErrors: null })
+  })
+
+  it('ignores malformed field errors', async () => {
+    mockFetch({
+      ok: false,
+      status: 400,
+      statusText: 'Bad Request',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message: 'Bad input', validationErrors }),
+      body: JSON.stringify({
+        error: 'BadRequestHttpError',
+        errors: { body: { name: 'Required.', title: { messages: 'Required.' } }, query: [] },
+      }),
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({ validationErrors: null })
+  })
+
+  it.each([
+    [400, BadRequestError],
+    [401, AuthenticationError],
+    [402, PaymentRequiredError],
+    [403, PermissionDeniedError],
+    [404, NotFoundError],
+    [409, ConflictError],
+    [422, UnprocessableEntityError],
+    [429, RateLimitError],
+    [500, InternalServerError],
+    [503, InternalServerError],
+  ])('throws the matching subclass for status %i', async (status, ErrorClass) => {
+    mockFetch({ ok: false, status, statusText: 'Error' })
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ErrorClass)
+    expect(error).toBeInstanceOf(ApiError)
+    expect(error).toBeInstanceOf(DigisacError)
+    expect(error).toMatchObject({ name: ErrorClass.name, status })
+  })
+
+  it('throws a plain ApiError for unmapped statuses', async () => {
+    mockFetch({ ok: false, status: 418, statusText: "I'm a teapot" })
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiError)
+    expect(Object.getPrototypeOf(error)).toBe(ApiError.prototype)
+    expect(error).toMatchObject({ name: 'ApiError', status: 418 })
+  })
+
+  it('exposes the response headers and the parsed body', async () => {
+    const body = { error: 'PaymentRequired', message: 'Limit', status: 402, extra: { limit: 10 } }
+    mockFetch({
+      ok: false,
+      status: 402,
+      statusText: 'Payment Required',
+      headers: { 'Content-Type': 'application/json', 'X-Request-Id': 'req-1' },
+      body: JSON.stringify(body),
+    })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as ApiError
+    expect(error.body).toEqual(body)
+    expect(error.headers?.get('X-Request-Id')).toBe('req-1')
+  })
+
+  it('exposes a non-JSON error body as text', async () => {
+    mockFetch({
+      ok: false,
+      status: 502,
+      statusText: 'Bad Gateway',
+      body: '<html>bad gateway</html>',
     })
     await expect(client.get('/fail')).rejects.toMatchObject({
-      validationErrors,
+      message: 'HTTP Error 502: Bad Gateway',
+      body: '<html>bad gateway</html>',
+    })
+  })
+
+  it('reads Retry-After (seconds) on RateLimitError', async () => {
+    mockFetch({
+      ok: false,
+      status: 429,
+      statusText: 'Too Many Requests',
+      headers: { 'Retry-After': '30' },
+    })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+    expect(error.retryAfter).toBe(30)
+  })
+
+  it('reads Retry-After (HTTP date) on RateLimitError', async () => {
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+    try {
+      mockFetch({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: { 'Retry-After': 'Thu, 01 Jan 2026 00:01:00 GMT' },
+      })
+      const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+      expect(error.retryAfter).toBe(60)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('reads X-RateLimit-Reset (Unix seconds) on RateLimitError', async () => {
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+    try {
+      mockFetch({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: { 'X-RateLimit-Reset': String(Date.parse('2026-01-01T01:00:00Z') / 1000) },
+      })
+      const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+      expect(error.retryAfter).toBe(3600)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('returns null retryAfter when the header is absent', async () => {
+    mockFetch({ ok: false, status: 429, statusText: 'Too Many Requests' })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+    expect(error.retryAfter).toBeNull()
+  })
+
+  it('wraps network failures in ApiConnectionError', async () => {
+    const cause = new TypeError('fetch failed')
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(cause)
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiConnectionError)
+    expect(error).toBeInstanceOf(DigisacError)
+    expect(error).not.toBeInstanceOf(ApiError)
+    expect(error).toMatchObject({
+      message: 'Request to GET https://api.example.com/fail failed: fetch failed',
+      cause,
     })
   })
 
+  it('does not report a body serialization failure as a connection error', async () => {
+    const spy = vi.spyOn(globalThis, 'fetch')
+    const circular: Record<string, unknown> = {}
+    circular.self = circular
+    const error = await client.post('/fail', circular).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(TypeError)
+    expect(spy).not.toHaveBeenCalled()
+  })
+
   it('falls back to default message when JSON parsing fails', async () => {
     mockFetch({
       ok: false,

package/src/core/BaseApiClient.ts

@@ -1,29 +1,5 @@
 import type { ApiClient, HttpMethod } from './ApiClient'
-
-export interface ValidationError {
-  path: string
-  message: string
-  code: string
-}
-
-export class ApiError extends Error {
-  public readonly errorClass?: string | undefined
-  public readonly status?: number | undefined
-  public readonly validationErrors: ValidationError[] | null
-
-  constructor(
-    message: string,
-    errorClass?: string,
-    status?: number,
-    validationErrors: ValidationError[] | null = null,
-  ) {
-    super(message)
-    this.name = 'ApiError'
-    this.errorClass = errorClass
-    this.status = status
-    this.validationErrors = validationErrors
-  }
-}
+import { ApiConnectionError, ApiError } from './errors'
 
 export class BaseApiClient implements ApiClient {
   protected readonly baseUrl: string
@@ -46,8 +22,7 @@ export class BaseApiClient implements ApiClient {
     headers?: Record<string, string>,
   ): Promise<TResponse> {
     const url = `${this.baseUrl}/${endpoint.replace(/^\//, '')}`
-
-    const response = await fetch(url, {
+    const init: RequestInit = {
       method,
       headers: {
         'Content-Type': 'application/json',
@@ -55,35 +30,29 @@ export class BaseApiClient implements ApiClient {
         ...headers,
       },
       ...(body !== undefined && { body: JSON.stringify(body) }),
-    })
+    }
+
+    let response: Response
+    try {
+      response = await fetch(url, init)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new ApiConnectionError(`Request to ${method} ${url} failed: ${reason}`, {
+        cause: error,
+      })
+    }
 
     return this.handleResponse<TResponse>(response)
   }
 
   protected async handleResponse<TResponse>(response: Response): Promise<TResponse> {
     if (!response.ok) {
-      const contentType = response.headers.get('Content-Type')
-      const isJson = contentType?.includes('application/json') ?? false
-
-      let errorMessage = `HTTP Error ${response.status}: ${response.statusText}`
-      let errorClass: string | undefined
-      let validationErrors: ValidationError[] | null = null
-
-      if (isJson) {
-        try {
-          const errorText = await response.text()
-          if (errorText) {
-            const errorData = JSON.parse(errorText)
-            errorMessage = errorData.message || errorData.error || errorMessage
-            errorClass = errorData.error
-            validationErrors = errorData.validationErrors ?? null
-          }
-        } catch {
-          // If JSON parsing fails, use the default error message
-        }
-      }
-
-      throw new ApiError(errorMessage, errorClass, response.status, validationErrors)
+      throw ApiError.fromResponse(
+        response.status,
+        response.statusText,
+        response.headers,
+        await this.readErrorBody(response),
+      )
     }
 
     // 204 No Content never has a body; short-circuit before reading the stream.
@@ -115,6 +84,24 @@ export class BaseApiClient implements ApiClient {
     }
   }
 
+  /** Reads an error body: parsed JSON when possible, the raw text otherwise, `undefined` when empty. */
+  protected async readErrorBody(response: Response): Promise<unknown> {
+    let text: string
+    try {
+      text = await response.text()
+    } catch {
+      return undefined
+    }
+    if (!text) {
+      return undefined
+    }
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
+  }
+
   get<TResponse = unknown>(endpoint: string, headers?: Record<string, string>): Promise<TResponse> {
     return this.request<TResponse>('GET', endpoint, undefined, headers)
   }