cogfy-messenger 0.1.0

package/.github/workflows/tests.yml

@@ -0,0 +1,18 @@
+on: [push, workflow_dispatch]
+
+jobs:
+  tests:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npm run test
+      - run: npm run build

package/README.md

@@ -0,0 +1,25 @@
+# Cogfy Messenger Node.js SDK
+
+A Node.js SDK for integrating with the Cogfy Messenger API.
+
+## Installation
+
+```bash
+npm install cogfy-messenger
+```
+
+## Usage
+
+1. Import the CogfyMessenger class from the package
+2. Create an instance of CogfyMessenger with your API key
+3. Use the instance to interact with the API
+
+```typescript
+import { CogfyMessenger } from 'cogfy-messenger'
+
+const cogfy = new CogfyMessenger({
+  apiKey: process.env.COGFY_MESSENGER_API_KEY
+})
+
+const contacts = await cogfy.contacts.list()
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "cogfy-messenger",
+  "version": "0.1.0",
+  "main": "index.js",
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@faker-js/faker": "^9.9.0",
+    "axios-mock-adapter": "^2.1.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "axios": "^1.11.0"
+  }
+}

package/src/clients/base-client.ts

@@ -0,0 +1,13 @@
+import { AxiosInstance } from 'axios'
+
+export type BaseClientOptions = {
+  axios: AxiosInstance
+}
+
+export abstract class BaseClient {
+  protected axios: AxiosInstance
+
+  constructor (options: BaseClientOptions) {
+    this.axios = options.axios
+  }
+}

package/src/clients/contacts/contacts-client.test.ts

@@ -0,0 +1,89 @@
+import AxiosMockAdapter from 'axios-mock-adapter'
+import { afterEach, describe, expect, test } from 'vitest'
+import { CogfyMessenger } from '../../cogfy-messenger'
+import axios from 'axios'
+import { faker } from '@faker-js/faker'
+
+describe('contacts', () => {
+  const mock = new AxiosMockAdapter(axios)
+  const cogfy = new CogfyMessenger({ apiKey: 'test' })
+
+  afterEach(() => {
+    mock.restore()
+  })
+
+  describe('list', () => {
+    test('calls the list endpoint', async () => {
+      mock.onGet('/contacts').reply(200, { data: [{ id: '1' }]})
+
+      const result = await cogfy.contacts.list()
+
+      expect(result).toMatchObject({ data: [{ id: '1' }] })
+    })
+  })
+
+  describe('get', () => {
+    test('calls the get endpoint', async () => {
+      const randomId = faker.string.uuid()
+      mock.onGet(`/contacts/${randomId}`).reply(200, { id: randomId })
+
+      const result = await cogfy.contacts.get(randomId)
+
+      expect(result).toMatchObject({ id: randomId })
+    })
+  })
+
+  describe('create', () => {
+    test('calls the create endpoint', async () => {
+      const randomId = faker.string.uuid()
+      mock.onPost(`/contacts`).reply(201, { id: randomId })
+
+      const result = await cogfy.contacts.create({
+        waProfileName: faker.person.fullName(),
+        firstName: faker.person.firstName(),
+        lastName: faker.person.lastName(),
+        email: faker.internet.email(),
+        phone: faker.phone.number(),
+        occupation: faker.person.jobTitle(),
+        gender: faker.person.gender(),
+        birthdate: faker.date.birthdate().toISOString(),
+        age: faker.number.int({ min: 18, max: 80 }),
+        notes: faker.lorem.sentence()
+      })
+
+      expect(result).toMatchObject({ id: randomId })
+    })
+  })
+
+  describe('delete', () => {
+    test('calls the delete endpoint', async () => {
+      const randomId = faker.string.uuid()
+      mock.onDelete(`/contacts/${randomId}`).reply(200, { id: randomId })
+
+      const result = await cogfy.contacts.delete(randomId)
+
+      expect(result).toMatchObject({ id: randomId })
+    })
+  })
+
+  describe('update', () => {
+    test('calls the update endpoint', async () => {
+      const randomId = faker.string.uuid()
+      mock.onPatch(`/contacts/${randomId}`).reply(200, { id: randomId })
+
+      const result = await cogfy.contacts.update(randomId, {
+        firstName: faker.person.firstName(),
+        lastName: faker.person.lastName(),
+        email: faker.internet.email(),
+        phone: faker.phone.number(),
+        occupation: faker.person.jobTitle(),
+        gender: faker.person.gender(),
+        birthdate: faker.date.birthdate().toISOString(),
+        age: faker.number.int({ min: 18, max: 80 }),
+        notes: faker.lorem.sentence()
+      })
+
+      expect(result).toMatchObject({ id: randomId })
+    })
+  })
+})

package/src/clients/contacts/contacts-client.ts

@@ -0,0 +1,49 @@
+import { BaseClient } from '../base-client'
+import { CreateContactCommand, CreateContactResult, DeleteContactResult, GetContactResult, ListContactsResult, UpdateContactCommand, UpdateContactResult } from './types'
+
+export class ContactsClient extends BaseClient {
+  /**
+   * Calls the POST /contacts endpoint
+   * @param contact The contact data to create
+   * @returns An object with the ID of the newly created contact
+  */
+  async create (contact: CreateContactCommand): Promise<CreateContactResult> {
+    return (await this.axios.post('/contacts', contact)).data
+  }
+
+  /**
+   * Calls the GET /contacts/:id endpoint
+   * @param id The ID of the contact to retrieve
+   * @returns The contact with the specified ID
+  */
+  async get (id: string): Promise<GetContactResult> {
+    return (await this.axios.get(`/contacts/${id}`)).data
+  }
+
+  /**
+   * Calls the GET /contacts endpoint
+   * @returns A list of all contacts in the workspace
+  */
+  async list (): Promise<ListContactsResult> {
+    return (await this.axios.get('/contacts')).data
+  }
+
+  /**
+   * Calls the PATCH /contacts/:id endpoint
+   * @param id The ID of the contact to update
+   * @param contact The updated contact data
+   * @returns An object with the ID of the updated contact
+   */
+  async update (id: string, contact: UpdateContactCommand): Promise<UpdateContactResult> {
+    return (await this.axios.patch(`/contacts/${id}`, contact)).data
+  }
+
+  /**
+   * Calls the DELETE /contacts/:id endpoint
+   * @param id The ID of the contact to delete
+   * @returns An object with the ID of the deleted contact
+  */
+  async delete (id: string): Promise<DeleteContactResult> {
+    return (await this.axios.delete(`/contacts/${id}`)).data
+  }
+}

package/src/clients/contacts/index.ts

@@ -0,0 +1,2 @@
+export * from './contacts-client'
+export * from './types'

package/src/clients/contacts/types/create-contact.ts

@@ -0,0 +1,16 @@
+export type CreateContactResult = {
+  id: string
+}
+
+export type CreateContactCommand = {
+  waProfileName: string | null
+  firstName: string | null
+  lastName: string | null
+  email: string | null
+  phone: string | null
+  occupation: string | null
+  gender: string | null
+  birthdate: string | null
+  age: number | null
+  notes: string | null
+}

package/src/clients/contacts/types/delete-contact.ts

@@ -0,0 +1,3 @@
+export type DeleteContactResult = {
+  id: string
+}

package/src/clients/contacts/types/get-contact.ts

@@ -0,0 +1,18 @@
+export type GetContactResult = {
+  id: string
+  workspaceId: string
+  statusId: string | null
+  waId: string | null
+  waProfileName: string | null
+  firstName: string | null
+  lastName: string | null
+  email: string | null
+  phone: string | null
+  occupation: string | null
+  gender: string | null
+  birthdate: string | null
+  age: number | null
+  notes: string | null
+  createDate: string
+  updateDate: string
+}

package/src/clients/contacts/types/index.ts

@@ -0,0 +1,5 @@
+export * from './create-contact'
+export * from './update-contact'
+export * from './get-contact'
+export * from './list-contacts'
+export * from './delete-contact'

package/src/clients/contacts/types/list-contacts.ts

@@ -0,0 +1,20 @@
+export type ListContactsResult = {
+  data: {
+    id: string
+    workspaceId: string
+    statusId: string | null
+    waId: string | null
+    waProfileName: string | null
+    firstName: string | null
+    lastName: string | null
+    email: string | null
+    phone: string | null
+    occupation: string | null
+    gender: string | null
+    birthdate: string | null
+    age: number | null
+    notes: string | null
+    createDate: string
+    updateDate: string
+  }[]
+}

package/src/clients/contacts/types/update-contact.ts

@@ -0,0 +1,15 @@
+export type UpdateContactCommand = {
+  firstName: string | null
+  lastName: string | null
+  email: string | null
+  phone: string | null
+  occupation: string | null
+  gender: string | null
+  birthdate: string | null
+  age: number | null
+  notes: string | null
+}
+
+export type UpdateContactResult = {
+  id: string
+}

package/src/clients/conversations/conversations-client.test.ts

@@ -0,0 +1,56 @@
+import AxiosMockAdapter from 'axios-mock-adapter'
+import { ConversationsClient } from './conversations-client'
+import axios from 'axios'
+import { CogfyMessenger } from '../../cogfy-messenger'
+import { faker } from '@faker-js/faker'
+import { describe, expect, it, beforeEach } from 'vitest'
+
+describe(ConversationsClient, () => {
+  const axiosMock = new AxiosMockAdapter(axios)
+  const cogfy = new CogfyMessenger({ apiKey: 'test' })
+
+  beforeEach(() => {
+    axiosMock.restore()
+  })
+
+  describe(ConversationsClient.prototype.get, () => {
+    it('should call GET /conversations/:id endpoint', async () => {
+      const id = faker.string.uuid()
+      const name = faker.lorem.word()
+      axiosMock.onGet(`/conversations/${id}`).reply(200, { id, name })
+
+      const result = await cogfy.conversations.get(id)
+
+      expect(result).toEqual({ id, name })
+    })
+  })
+
+  describe(ConversationsClient.prototype.list, () => {
+    it('should call GET /conversations endpoint', async () => {
+      const conversations = Array.from({ length: 3 }, () => ({
+        id: faker.string.uuid(),
+        name: faker.lorem.word()
+      }))
+      axiosMock.onGet('/conversations').reply(200, { data: conversations })
+
+      const result = await cogfy.conversations.list({ phoneNumberId: faker.string.uuid() })
+
+      expect(result.data).toEqual(conversations)
+    })
+  })
+
+  describe('send message', () => {
+    it('calls the send message endpoint', async () => {
+      const conversationId = faker.string.uuid()
+      const messageId = faker.string.uuid()
+      axiosMock.onPost(`/conversations/${conversationId}/messages`).reply(201, { id: messageId })
+
+      const result = await cogfy.conversations.sendMessage(conversationId, {
+        type: 'text',
+        content: faker.lorem.sentence()
+      })
+
+      expect(result).toMatchObject({ id: messageId })
+    })
+  })
+})

package/src/clients/conversations/conversations-client.ts

@@ -0,0 +1,41 @@
+import { BaseClient } from '../base-client'
+import { SendMessageCommand } from './types/send-message'
+import { GetConversationResult, GetMessagesResult, ListConversationsParams, ListConversationsResult, ListMessagesParams } from './types'
+
+export class ConversationsClient extends BaseClient {
+  /**
+   * Calls the GET /conversations/:id endpoint
+   * @param id The ID of the conversation to retrieve
+   * @returns The conversation with the specified ID
+  */
+  async get (id: string): Promise<GetConversationResult> {
+    return (await this.axios.get(`/conversations/${id}`)).data
+  }
+
+  /**
+   * Calls the GET /conversations endpoint
+   * @param params Params for listing conversations, such as pagination cursors
+   * @returns A list of all conversations in the workspace
+  */
+  async list (params: ListConversationsParams): Promise<ListConversationsResult> {
+    const axiosResponse = await this.axios.get(`/conversations`, {
+      params,
+    })
+    return axiosResponse.data
+  }
+
+  /**
+   * Calls the GET /conversations/:id/messages endpoint
+   * @param params Params for listing messages in a conversation, such as pagination cursors
+   * @returns A list of all messages in the specified conversation
+  */
+  async getMessages (params: ListMessagesParams): Promise<GetMessagesResult> {
+    const axiosResponse = await this.axios.get(`/conversations/${params.conversationId}/messages`, {
+      params
+    })
+    return axiosResponse.data
+  }
+  async sendMessage (id: string, payload: SendMessageCommand): Promise<any> {
+    return (await this.axios.post(`/conversations/${id}/messages`, payload)).data
+  }
+}

package/src/clients/conversations/index.ts

@@ -0,0 +1,2 @@
+export * from './conversations-client'
+export * from './types'

package/src/clients/conversations/types/get-conversation.ts

@@ -0,0 +1,11 @@
+export type GetConversationResult = {
+  id: string
+  workspaceId: string
+  phoneNumberId: string | null
+  recipientId: string | null
+  assigneeId: string | null
+  lastMessageId: string | null
+  data: any | null
+  createDate: string
+  serviceWindowExpireDate: string | null
+}

package/src/clients/conversations/types/get-messages.ts

@@ -0,0 +1,35 @@
+export type GetMessagesResult = {
+  data: {
+    id: string
+    workspaceId: string
+    conversationId: string | null
+    assistantId: string | null
+    userId: string | null
+    broadcastId: string | null
+    whatsappMessageId: string | null
+    from: string | null
+    to: string | null
+    role: string
+    status: string | null
+    type: string | null
+    content: string | null
+    contentData: string | null
+    toolCallId: string | null
+    toolCalls: string | null
+    data: string | null
+    contextId: string | null
+    contextFrom: string | null
+    createDate: Date
+    sendDate: Date
+    deliverDate: Date | null
+    readDate: Date | null
+    promptTokens: number | null
+    completionTokens: number | null
+    order: number
+    traceId: string | null
+  }[]
+  cursors: {
+    next: string | null
+    prev: string | null
+  }
+}

package/src/clients/conversations/types/index.ts

@@ -0,0 +1,4 @@
+export * from './get-conversation'
+export * from './get-messages'
+export * from './send-message'
+export * from './list-conversations'

package/src/clients/conversations/types/list-conversations.ts

@@ -0,0 +1,37 @@
+export type ListConversationsParams =
+  | {
+      phoneNumberId: string
+      cursor?: never
+    }
+  | {
+      phoneNumberId?: never
+      cursor: string
+    }
+
+export type ListMessagesParams =
+  | {
+      conversationId: string
+      cursor?: never
+    }
+  | {
+      conversationId?: never
+      cursor: string
+    }
+
+export type ListConversationsResult = {
+  data: ListConversationsResultData[]
+  cursors: {
+    next: string | null
+  }
+}
+
+export type ListConversationsResultData = {
+  id: string
+  workspaceId: string
+  phoneNumberId: string | null
+  recipientId: string | null
+  assigneeId: string | null
+  lastMessageId: string | null
+  createDate: string
+  serviceWindowExpireDate: string | null
+}

package/src/clients/conversations/types/send-message.ts

@@ -0,0 +1,13 @@
+export type SendMessageCommand = {
+  type: 'text' | 'image' | 'document'
+  content?: string | null
+  media?: {
+    name: string | null
+    mimeType: string
+    base64: string
+  } | null
+}
+
+export type SendMessageResult = {
+  id: string
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export * from './contacts/types'
+export * from './tags/types'

package/src/clients/tags/index.ts

@@ -0,0 +1,2 @@
+export * from './tags-client'
+export * from './types'

package/src/clients/tags/tags-client.test.ts

@@ -0,0 +1,80 @@
+import AxiosMockAdapter from 'axios-mock-adapter'
+import { TagsClient } from './tags-client'
+import axios from 'axios'
+import { CogfyMessenger } from '../../cogfy-messenger'
+import { faker } from '@faker-js/faker'
+import { describe, expect, it, beforeEach } from 'vitest'
+
+describe(TagsClient, () => {
+  const axiosMock = new AxiosMockAdapter(axios)
+  const cogfy = new CogfyMessenger({ apiKey: 'test' })
+
+  beforeEach(() => {
+    axiosMock.restore()
+  })
+
+  describe(TagsClient.prototype.create, () => {
+    it('should call POST /tags endpoint', async () => {
+      const fakeId = faker.string.uuid()
+      axiosMock.onPost('/tags').reply(201, { id: fakeId })
+
+      const result = await cogfy.tags.create({
+        name: faker.lorem.word()
+      })
+
+      expect(result).toEqual({
+        id: fakeId
+      })
+    })
+  })
+
+  describe(TagsClient.prototype.delete, () => {
+    it('should call DELETE /tags/:id endpoint', async () => {
+      const name = faker.lorem.word()
+      const id = faker.string.uuid()
+      axiosMock.onDelete(`/tags/${id}`).reply(200, { id, name })
+
+      const result = await cogfy.tags.delete(id)
+
+      expect(result).toEqual({ id, name })
+    })
+  })
+
+  describe(TagsClient.prototype.get, () => {
+    it('should call GET /tags/:id endpoint', async () => {
+      const id = faker.string.uuid()
+      const name = faker.lorem.word()
+      axiosMock.onGet(`/tags/${id}`).reply(200, { id, name })
+
+      const result = await cogfy.tags.get(id)
+
+      expect(result).toEqual({ id, name })
+    })
+  })
+
+  describe(TagsClient.prototype.list, () => {
+    it('should call GET /tags endpoint', async () => {
+      const tags = Array.from({ length: 3 }, () => ({
+        id: faker.string.uuid(),
+        name: faker.lorem.word()
+      }))
+      axiosMock.onGet('/tags').reply(200, { data: tags })
+
+      const result = await cogfy.tags.list()
+
+      expect(result.data).toEqual(tags)
+    })
+  })
+
+  describe(TagsClient.prototype.update, () => {
+    it('should call PATCH /tags/:id endpoint', async () => {
+      const id = faker.string.uuid()
+      const name = faker.lorem.word()
+      axiosMock.onPatch(`/tags/${id}`).reply(200, { id, name })
+
+      const result = await cogfy.tags.update(id, { name })
+
+      expect(result).toEqual({ id, name })
+    })
+  })
+})

package/src/clients/tags/tags-client.ts

@@ -0,0 +1,49 @@
+import { BaseClient } from '../base-client'
+import { CreateTagCommand, CreateTagResult, DeleteTagResult, GetTagResult, ListTagsResult, UpdateTagCommand, UpdateTagResult } from './types'
+
+export class TagsClient extends BaseClient {
+  /**
+   * Calls the POST /tags endpoint
+   * @param payload The tag data to create
+   * @returns An object with the ID and the name of the newly created tag
+   */
+  async create(payload: CreateTagCommand): Promise<CreateTagResult> {
+    return (await this.axios.post('/tags', payload)).data
+  }
+
+  /**
+   * Calls the DELETE /tags/:id endpoint
+   * @param id The ID of the tag to delete
+   * @returns An object with the ID and the name of the deleted tag
+   */
+  async delete(id: string): Promise<DeleteTagResult> {
+    return (await this.axios.delete(`/tags/${id}`)).data
+  }
+
+  /**
+   * Calls the GET /tags/:id endpoint
+   * @param id The ID of the tag to retrieve
+   * @returns The tag with the specified ID
+   */
+  async get(id: string): Promise<GetTagResult> {
+    return (await this.axios.get(`/tags/${id}`)).data
+  }
+
+  /**
+   * Calls the GET /tags endpoint
+   * @returns A list of all tags in the workspace
+   */
+  async list(): Promise<ListTagsResult> {
+    return (await this.axios.get('/tags')).data
+  }
+
+  /**
+   * Calls the PATCH /tags/:id endpoint
+   * @param id The ID of the tag to update
+   * @param payload The updated tag data
+   * @returns An object with the ID and the name of the updated tag
+   */
+  async update(id: string, payload: UpdateTagCommand): Promise<UpdateTagResult> {
+    return (await this.axios.patch(`/tags/${id}`, payload)).data
+  }
+}

package/src/clients/tags/types/create-tag.ts

@@ -0,0 +1,8 @@
+export type CreateTagCommand = {
+  name: string
+}
+
+export type CreateTagResult = {
+  id: string
+  name: string
+}

package/src/clients/tags/types/delete-tag.ts

@@ -0,0 +1,4 @@
+export type DeleteTagResult = {
+  id: string
+  name: string
+}

package/src/clients/tags/types/get-tag.ts

@@ -0,0 +1,4 @@
+export type GetTagResult = {
+  id: string
+  name: string
+}

package/src/clients/tags/types/index.ts

@@ -0,0 +1,5 @@
+export * from './create-tag'
+export * from './delete-tag'
+export * from './get-tag'
+export * from './list-tags'
+export * from './update-tag'

package/src/clients/tags/types/list-tags.ts

@@ -0,0 +1,6 @@
+export type ListTagsResult = {
+  data: {
+    id: string
+    name: string
+  }[]
+}

package/src/clients/tags/types/update-tag.ts

@@ -0,0 +1,8 @@
+export type UpdateTagCommand = {
+  name: string
+}
+
+export type UpdateTagResult = {
+  id: string
+  name: string
+}

package/src/cogfy-messenger.ts

@@ -0,0 +1,33 @@
+import axios from 'axios'
+import { ContactsClient } from './clients/contacts'
+import { BaseClientOptions } from './clients/base-client'
+import { TagsClient } from './clients/tags'
+import { ConversationsClient } from './clients/conversations'
+
+export type CogfyMessengerOptions = {
+  apiKey: string
+  baseURL?: string
+}
+
+const DEFAULT_BASE_URL = 'https://messenger-public-api.cogfy.com'
+
+export class CogfyMessenger {
+  contacts: ContactsClient
+  conversations: ConversationsClient
+  tags: TagsClient
+
+  constructor (options: CogfyMessengerOptions) {
+    const clientOptions: BaseClientOptions = {
+      axios: axios.create({
+        baseURL: options.baseURL || DEFAULT_BASE_URL,
+        headers: {
+          'Authorization': `Bearer ${options.apiKey}`
+        }
+      })
+    }
+
+    this.contacts = new ContactsClient(clientOptions)
+    this.conversations = new ConversationsClient(clientOptions)
+    this.tags = new TagsClient(clientOptions)
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './clients'
+export * from './cogfy-messenger'

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "exclude": [
+    "dist",
+    "**/*.test.ts"
+  ],
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}