@ikatec/digisac-api-sdk 2.2.1 → 3.1.0

package/src/apis/terms/TermsApi.test.ts

@@ -1,8 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { TermsApi } from './TermsApi'
 import type { ApiClient } from '../../core/ApiClient'
-import type { Term, CreateTermPayload } from './types'
-import type { Paginated } from '../../core/types'
+import type { Term } from './types'
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -34,17 +33,6 @@ const term: Term = {
   updatedAt: '2024-01-01T00:00:00Z',
 }
 
-const paginated: Paginated<Term> = {
-  data: [term],
-  total: 1,
-  limit: 10,
-  skip: 0,
-  currentPage: 1,
-  lastPage: 1,
-  from: 1,
-  to: 1,
-}
-
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('TermsApi', () => {
@@ -56,30 +44,13 @@ describe('TermsApi', () => {
     api = new TermsApi(client)
   })
 
-  // ── getMany ──────────────────────────────────────────────────────
-
-  describe('getMany', () => {
-    it('calls client.get with /terms when no query is provided', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      const result = await api.getMany()
-      expect(client.get).toHaveBeenCalledWith('/terms', undefined)
-      expect(result).toEqual(paginated)
-    })
-
-    it('serializes query parameters', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      await api.getMany({ page: 2 })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
-      expect(url).toContain('/terms?')
-      expect(url).toContain('page=2')
-    })
-
-    it('forwards custom headers', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      const headers = { 'X-Custom': 'value' }
-      await api.getMany(undefined, headers)
-      expect(client.get).toHaveBeenCalledWith('/terms', headers)
-    })
+  it('exposes only the read routes served by the backend', () => {
+    expect(api.basePath).toBe('/terms')
+    // /terms has no list/create/update/delete routes (404 "Route not found.")
+    expect(api).not.toHaveProperty('getMany')
+    expect(api).not.toHaveProperty('create')
+    expect(api).not.toHaveProperty('updateById')
+    expect(api).not.toHaveProperty('deleteById')
   })
 
   // ── getById ──────────────────────────────────────────────────────
@@ -92,100 +63,83 @@ describe('TermsApi', () => {
       expect(result).toEqual(term)
     })
 
+    it('serializes the query', async () => {
+      vi.mocked(client.get).mockResolvedValue(term)
+      await api.getById('term-1', { attributes: ['id', 'version'] })
+      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      expect(url).toContain('/terms/term-1?')
+      expect(url).toContain('attributes')
+    })
+
     it('forwards custom headers', async () => {
       vi.mocked(client.get).mockResolvedValue(term)
       const headers = { 'X-Tenant': 'abc' }
       await api.getById('term-1', undefined, headers)
       expect(client.get).toHaveBeenCalledWith('/terms/term-1', headers)
     })
-  })
 
-  // ── create ───────────────────────────────────────────────────────
-
-  describe('create', () => {
-    it('calls client.post with /terms and body', async () => {
-      vi.mocked(client.post).mockResolvedValue(term)
-      const body: CreateTermPayload = {
-        title: { en: 'ToS' },
-        text: { en: 'Text' },
-        expirationDate: '2025-01-01',
-        version: '1.0',
-        agnusId: 'agnus-1',
-      }
-      const result = await api.create(body)
-      expect(client.post).toHaveBeenCalledWith('/terms', body, undefined)
-      expect(result).toEqual(term)
+    it('keeps working when detached from the instance', async () => {
+      vi.mocked(client.get).mockResolvedValue(term)
+      const { getById } = api
+      await getById('term-1')
+      expect(client.get).toHaveBeenCalledWith('/terms/term-1', undefined)
     })
   })
 
-  // ── updateById ───────────────────────────────────────────────────
+  // ── getNotAgreed ─────────────────────────────────────────────────
 
-  describe('updateById', () => {
-    it('calls client.put with /terms/:id and body', async () => {
-      vi.mocked(client.put).mockResolvedValue(term)
-      const result = await api.updateById('term-1', { version: '1.1' })
-      expect(client.put).toHaveBeenCalledWith('/terms/term-1', { version: '1.1' }, undefined)
-      expect(result).toEqual(term)
+  describe('getNotAgreed', () => {
+    it('calls client.get with /terms/terms-not-agreed and returns the plain array', async () => {
+      vi.mocked(client.get).mockResolvedValue([term])
+      const result = await api.getNotAgreed()
+      expect(client.get).toHaveBeenCalledWith('/terms/terms-not-agreed', undefined)
+      expect(result).toEqual([term])
     })
 
     it('forwards custom headers', async () => {
-      vi.mocked(client.put).mockResolvedValue(term)
-      const headers = { 'If-Match': 'etag' }
-      await api.updateById('term-1', { version: '2.0' }, headers)
-      expect(client.put).toHaveBeenCalledWith('/terms/term-1', { version: '2.0' }, headers)
+      vi.mocked(client.get).mockResolvedValue([])
+      const headers = { 'X-Custom': 'h' }
+      await api.getNotAgreed(headers)
+      expect(client.get).toHaveBeenCalledWith('/terms/terms-not-agreed', headers)
     })
   })
 
-  // ── deleteById ───────────────────────────────────────────────────
-
-  describe('deleteById', () => {
-    it('calls client.delete with /terms/:id', async () => {
-      vi.mocked(client.delete).mockResolvedValue(term)
-      const result = await api.deleteById('term-1')
-      expect(client.delete).toHaveBeenCalledWith('/terms/term-1', undefined)
-      expect(result).toEqual(term)
+  // ── agree ────────────────────────────────────────────────────────
+
+  describe('agree', () => {
+    it('calls client.patch with /terms/agree and the term ids', async () => {
+      const agnusResponse = { agreed: true }
+      vi.mocked(client.patch).mockResolvedValue(agnusResponse)
+      const result = await api.agree(['term-1', 'term-2'])
+      expect(client.patch).toHaveBeenCalledWith(
+        '/terms/agree',
+        { terms: ['term-1', 'term-2'] },
+        undefined,
+      )
+      expect(result).toEqual(agnusResponse)
     })
 
     it('forwards custom headers', async () => {
-      vi.mocked(client.delete).mockResolvedValue(term)
-      const headers = { 'X-Reason': 'cleanup' }
-      await api.deleteById('term-1', headers)
-      expect(client.delete).toHaveBeenCalledWith('/terms/term-1', headers)
-    })
-  })
-
-  // ── getNotAgreed ─────────────────────────────────────────────────
-
-  describe('getNotAgreed', () => {
-    it('calls client.get with /terms/terms-not-agreed when no query is provided', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      const result = await api.getNotAgreed()
-      expect(client.get).toHaveBeenCalledWith('/terms/terms-not-agreed', undefined)
-      expect(result).toEqual(paginated)
-    })
-
-    it('serializes query parameters', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      await api.getNotAgreed({ page: 1, perPage: 5 })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
-      expect(url).toContain('/terms/terms-not-agreed?')
-      expect(url).toContain('page=1')
+      vi.mocked(client.patch).mockResolvedValue({})
+      const headers = { 'X-Custom': 'h' }
+      await api.agree(['term-1'], headers)
+      expect(client.patch).toHaveBeenCalledWith('/terms/agree', { terms: ['term-1'] }, headers)
     })
 
-    it('forwards custom headers', async () => {
-      vi.mocked(client.get).mockResolvedValue(paginated)
-      const headers = { 'X-Custom': 'h' }
-      await api.getNotAgreed(undefined, headers)
-      expect(client.get).toHaveBeenCalledWith('/terms/terms-not-agreed', headers)
+    it('keeps working when detached from the instance', async () => {
+      vi.mocked(client.patch).mockResolvedValue({})
+      const { agree } = api
+      await agree(['term-1'])
+      expect(client.patch).toHaveBeenCalledWith('/terms/agree', { terms: ['term-1'] }, undefined)
     })
   })
 
   // ── Error propagation ────────────────────────────────────────────
 
   describe('error propagation', () => {
-    it('propagates errors from getMany', async () => {
+    it('propagates errors from getById', async () => {
       vi.mocked(client.get).mockRejectedValue(new Error('Network error'))
-      await expect(api.getMany()).rejects.toThrow('Network error')
+      await expect(api.getById('term-1')).rejects.toThrow('Network error')
     })
 
     it('propagates errors from getNotAgreed', async () => {

package/src/apis/terms/TermsApi.ts

@@ -1,22 +1,51 @@
 import qs from 'qs'
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { ListQuery, Paginated } from '../../core/types'
-import type { Term, CreateTermPayload, UpdateTermPayload } from './types'
+import type { GetByIdQuery, HasGetById } from '../../core/types'
+import type { Term } from './types'
+
+/**
+ * Platform terms of use. Terms are published by Agnus (billing) and accepted by the account users,
+ * so the `/terms` route has no create/list/update/delete — only the routes below.
+ *
+ * `GET /terms/:id/export-pdf` is not exposed: it answers a binary PDF, and `ApiClient` only
+ * handles JSON/text bodies.
+ */
+export class TermsApi implements HasGetById<Term> {
+  protected readonly client: ApiClient
+  public readonly basePath = '/terms'
 
-export class TermsApi extends BaseCrudApi<Term, CreateTermPayload, UpdateTermPayload> {
   constructor(client: ApiClient) {
-    super(client, '/terms')
+    this.client = client
+    this.getById = this.getById.bind(this)
+    this.getNotAgreed = this.getNotAgreed.bind(this)
+    this.agree = this.agree.bind(this)
   }
 
-  /** Returns all terms where agreementDate is null for the current user's account (i.e. terms not yet agreed to). */
-  getNotAgreed(
-    query?: ListQuery<Term>,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<Term>> {
+  /** Returns a single term by its ID, scoped to the current account (`null` when not found). */
+  getById(id: string, query?: GetByIdQuery<Term>, headers?: Record<string, string>): Promise<Term> {
     const queryString = query ? `?${qs.stringify(query)}` : ''
-    return this.client.get<Paginated<Term>>(
-      `${this.basePath}/terms-not-agreed${queryString}`,
+    return this.client.get<Term>(`${this.basePath}/${id}${queryString}`, headers)
+  }
+
+  /**
+   * Returns the terms of the current account that were not agreed to yet (`agreementDate` null).
+   * The backend answers a plain array (not paginated) and ignores query parameters.
+   */
+  getNotAgreed(headers?: Record<string, string>): Promise<Term[]> {
+    return this.client.get<Term[]>(`${this.basePath}/terms-not-agreed`, headers)
+  }
+
+  /**
+   * Agrees to the given terms on behalf of the authenticated user. IRREVERSIBLE: the acceptance is
+   * registered on Agnus, the terms get `agreementDate`/`userId`, and the signed PDFs are e-mailed
+   * to the user. Only terms of the current account are affected.
+   *
+   * The response is passed through from Agnus as-is, so it is not typed.
+   */
+  agree(termIds: string[], headers?: Record<string, string>): Promise<unknown> {
+    return this.client.patch<unknown, { terms: string[] }>(
+      `${this.basePath}/agree`,
+      { terms: termIds },
       headers,
     )
   }

package/src/apis/terms/types.ts

@@ -11,19 +11,3 @@ export type Term = {
   createdAt: string
   updatedAt: string
 }
-
-export type CreateTermPayload = {
-  title: Record<string, string>
-  text: Record<string, string>
-  expirationDate: string
-  version: string
-  agnusId: string
-  accountId?: string
-}
-
-export type UpdateTermPayload = {
-  title?: Record<string, string>
-  text?: Record<string, string>
-  expirationDate?: string
-  version?: string
-}

package/src/core/BaseApiClient.test.ts

@@ -230,6 +230,59 @@ describe('BaseApiClient', () => {
     })
   })
 
+  it('maps the Digisac field errors (errors.<location>.<field>) into validationErrors', async () => {
+    mockFetch({
+      ok: false,
+      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'] } },
+        },
+      }),
+    })
+    await expect(client.post('/fail', {})).rejects.toMatchObject({
+      errorClass: 'ValidationError',
+      status: 400,
+      validationErrors: [
+        { path: 'body.name', message: 'Required.', code: 'required' },
+        { path: 'body.title', message: 'Required.', code: 'required' },
+        {
+          path: 'body.title',
+          message: 'Should contain lesser than or equals 255 characters.',
+          code: 'hasLengthLesserThanOrEqual',
+        },
+        { 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 uma funil com esse nome',
+        status: 400,
+      }),
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({ validationErrors: null })
+  })
+
   it('falls back to default message when JSON parsing fails', async () => {
     mockFetch({
       ok: false,

package/src/core/BaseApiClient.ts

@@ -6,6 +6,42 @@ export interface ValidationError {
   code: string
 }
 
+/**
+ * Digisac field errors: `{ errors: { <location>: { <field>: { messages: string[], types: string[] } } } }`,
+ * where location is `body`, `params`, `query`, `headers` or `cookies` (backend `validate` middleware).
+ */
+type DigisacFieldErrors = Record<string, Record<string, { messages?: unknown; types?: unknown }>>
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/**
+ * Flattens the Digisac `errors` object into `ValidationError[]` — one entry per message, with
+ * `path` = `<location>.<field>` (e.g. `body.name`) and `code` = the rule type (e.g. `required`).
+ * Returns `null` when the body carries no field errors.
+ */
+function parseValidationErrors(errors: unknown): ValidationError[] | null {
+  if (!isRecord(errors)) {
+    return null
+  }
+
+  const parsed: ValidationError[] = []
+  for (const [location, fields] of Object.entries(errors as DigisacFieldErrors)) {
+    if (!isRecord(fields)) {
+      continue
+    }
+    for (const [field, detail] of Object.entries(fields)) {
+      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({ path: `${location}.${field}`, message, code: types[index] ?? types[0] ?? '' })
+      })
+    }
+  }
+
+  return parsed.length ? parsed : null
+}
+
 export class ApiError extends Error {
   public readonly errorClass?: string | undefined
   public readonly status?: number | undefined
@@ -76,7 +112,7 @@ export class BaseApiClient implements ApiClient {
             const errorData = JSON.parse(errorText)
             errorMessage = errorData.message || errorData.error || errorMessage
             errorClass = errorData.error
-            validationErrors = errorData.validationErrors ?? null
+            validationErrors = errorData.validationErrors ?? parseValidationErrors(errorData.errors)
           }
         } catch {
           // If JSON parsing fails, use the default error message

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 ────────────────────────────────────────────────────────