@whitewall/blip-sdk 0.0.136 → 0.0.137

package/src/sender/tcp/tcpsender.ts

@@ -0,0 +1,252 @@
+import type { Socket } from 'node:net'
+import type {
+    Command,
+    CommandMethods,
+    CommandResponse,
+    Envelope,
+    Message,
+    MessageTypes,
+    Notification,
+    UnknownCommandResponse,
+} from '../../types/index.ts'
+import { BlipError } from '../bliperror.ts'
+import { ConnectionSender, type ConnectionSenderConstructor, OpenConnectionSender } from '../sender.ts'
+import { SessionNegotiator } from '../sessionnegotiator.ts'
+import { EnvelopeThrottler } from '../throttler.ts'
+
+/**
+ * @remarks
+ * The TCP implementation has a known limitation where large command
+ * responses can be lost and the awaiting promise will never resolve.
+ * Unless TCP is explicitly required, prefer using {@link WebSocketSender}
+ */
+export class TCPSender extends OpenConnectionSender {
+    private readonly throttler = new EnvelopeThrottler()
+    private readonly connectionHandle: TCPHandle<Envelope>
+
+    constructor(options: ConstructorParameters<ConnectionSenderConstructor>[0]) {
+        super(options)
+
+        const prefix = options.tenantId ? `${options.tenantId}.` : ''
+        this.connectionHandle = new TCPHandle<Envelope>(
+            `${prefix}tcp.${this.domain}`,
+            443,
+            async (socket) => {
+                this.sessionNegotiator = new SessionNegotiator(this, (session) => {
+                    socket.write(JSON.stringify(session))
+                })
+                return this.sessionNegotiator.negotiate({
+                    node: options.node,
+                    authentication: options.authentication,
+                })
+            },
+            (envelope: Envelope) => {
+                if (this.sessionNegotiator?.negotiating) {
+                    return this.sessionNegotiator.handleEnvelope(envelope)
+                }
+                this.envelopeResolver.resolve(envelope)
+            },
+        )
+    }
+
+    public async sendNotification(notification: Notification): Promise<void> {
+        const socket = await this.connectionHandle.get()
+        socket.write(JSON.stringify(notification))
+    }
+
+    public async sendMessage<Type extends MessageTypes>(message: Message<Type>): Promise<void> {
+        await this.throttler.throttle('message')
+
+        const socket = await this.connectionHandle.get()
+        await this.sessionNegotiator?.ensurePresence()
+
+        socket.write(JSON.stringify(message))
+    }
+
+    public sendCommand(command: Command<CommandMethods>): Promise<unknown> {
+        return this.withRetryPolicy(async () => {
+            await this.throttler.throttle('command')
+
+            const envelopeResponsePromise = this.envelopeResolver.createEnvelopeResponsePromise(command.id)
+
+            const socket = await this.connectionHandle.get()
+            await this.sessionNegotiator?.ensurePresence(command.uri)
+
+            socket.write(JSON.stringify(command))
+
+            const response = (await envelopeResponsePromise) as CommandResponse<
+                unknown,
+                CommandMethods,
+                'success' | 'failure'
+            >
+            if (BlipError.isFailedCommandResponse(response)) {
+                throw BlipError.commandResponseToBlipError(command.uri, response)
+            } else if (response.status === 'success') {
+                return response.resource
+            } else {
+                throw new Error(`Unexpected response for command '${command.uri}': ${JSON.stringify(response)}`)
+            }
+        })
+    }
+
+    public async sendCommandResponse(response: UnknownCommandResponse): Promise<void> {
+        const socket = await this.connectionHandle.get()
+        socket.write(`${JSON.stringify(response)}\n`)
+    }
+
+    public async close() {
+        this.sessionNegotiator?.finish()
+        await this.connectionHandle.close()
+    }
+
+    public static login = ConnectionSender.login<TCPSender>
+
+    private async withRetryPolicy<T>(fn: () => Promise<T>, retries = 10): Promise<T> {
+        try {
+            return await fn()
+        } catch (err) {
+            if (retries > 0 && err instanceof BlipError && BlipError.retryableBlipErrors.includes(err.code)) {
+                // wait before retrying
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * 1000))
+                return this.withRetryPolicy(fn, retries - 1)
+            }
+
+            throw err
+        }
+    }
+}
+
+class TCPHandle<T> {
+    private currentSocketPromise: Promise<Socket> | null = null
+    private closing = false
+    private connectionAttempts = 0
+
+    constructor(
+        host: string,
+        port: number,
+        onConnected: (socket: Socket) => Promise<void>,
+        onMessage: (message: T) => void,
+    ) {
+        this.currentSocketPromise = this.connect(host, port, onConnected, onMessage)
+    }
+
+    public get() {
+        if (!this.currentSocketPromise) {
+            throw new Error('TCP connection is not available.')
+        }
+
+        return this.currentSocketPromise
+    }
+
+    public async close() {
+        if (!this.closing && this.currentSocketPromise) {
+            this.closing = true
+            const current = await this.currentSocketPromise
+            current.end()
+            current.destroy()
+        }
+    }
+
+    private async connect(
+        host: string,
+        port: number,
+        onConnected: (socket: Socket) => Promise<void>,
+        onMessage: (message: T) => void,
+    ): Promise<Socket> {
+        const { connect } = await import('node:net')
+
+        const socket = connect({ host, port }).setEncoding('utf8')
+        let buffer = ''
+
+        await new Promise<void>((resolve) => {
+            socket.once('connect', () => {
+                resolve()
+            })
+
+            socket.once('error', (err) => {
+                if (!this.closing) {
+                    throw err
+                }
+            })
+
+            socket.once('close', () => {
+                if (!this.closing) {
+                    this.connectionAttempts++
+                    if (this.connectionAttempts < 3) {
+                        this.currentSocketPromise = this.connect(host, port, onConnected, onMessage)
+                    } else {
+                        throw new Error('Failed to connect/reconnect to TCP socket')
+                    }
+                }
+            })
+
+            socket.on('data', (chunk) => {
+                const result = this.tryParseJSON(buffer + chunk)
+                buffer = result.remainingBuffer
+
+                for (const parsed of result.parsedObjects) {
+                    onMessage(parsed)
+                }
+            })
+        })
+
+        await onConnected(socket)
+        this.connectionAttempts = 0
+
+        return socket
+    }
+
+    private tryParseJSON(buffer: string): { parsedObjects: Array<T>; remainingBuffer: string } {
+        const parsedObjects: Array<T> = []
+        let currBuffer = buffer
+        let startIndex = buffer.indexOf('{')
+
+        while (startIndex !== -1) {
+            let braceCount = 0
+            let inString = false
+            let escaped = false
+            let foundEnd = false
+            let endIndex = startIndex
+
+            for (let i = startIndex; i < currBuffer.length; i++) {
+                const char = currBuffer[i]
+
+                if (inString) {
+                    if (escaped) {
+                        escaped = false
+                    } else if (char === '\\') {
+                        escaped = true
+                    } else if (char === '"') {
+                        inString = false
+                    }
+                } else if (char === '"') {
+                    inString = true
+                } else if (char === '{') {
+                    braceCount++
+                } else if (char === '}') {
+                    braceCount--
+                    // When all opened braces are closed, we found the end.
+                    if (braceCount === 0) {
+                        endIndex = i
+                        foundEnd = true
+                        break
+                    }
+                }
+            }
+
+            // If we haven't found a complete JSON object, break and wait for more data.
+            if (!foundEnd) {
+                break
+            }
+
+            const rawMessage = currBuffer.slice(startIndex, endIndex + 1).trim()
+            const parsed = JSON.parse(rawMessage) as T
+            parsedObjects.push(parsed)
+
+            currBuffer = currBuffer.slice(endIndex + 1)
+            startIndex = currBuffer.indexOf('{')
+        }
+
+        return { parsedObjects, remainingBuffer: currBuffer }
+    }
+}

package/src/sender/throttler.ts

@@ -0,0 +1,36 @@
+export class EnvelopeThrottler {
+    private sent = {
+        message: {
+            max: 50,
+            started: 0,
+            count: 0,
+        },
+        command: {
+            max: 200,
+            started: 0,
+            count: 0,
+        },
+    }
+
+    public async throttle(type: keyof typeof this.sent): Promise<void> {
+        const throughput = this.sent[type].max * 0.9
+        const timeToReset = 1000
+
+        while (true) {
+            const elapsed = Date.now() - this.sent[type].started
+
+            if (elapsed >= timeToReset) {
+                this.sent[type].started = Date.now()
+                this.sent[type].count = 0
+            }
+
+            if (this.sent[type].count < throughput) {
+                this.sent[type].count++
+                break
+            } else {
+                const wait = timeToReset - elapsed
+                await new Promise((resolve) => setTimeout(resolve, wait))
+            }
+        }
+    }
+}

package/src/sender/websocket/websocketsender.ts

@@ -0,0 +1,175 @@
+import type {
+    Command,
+    CommandMethods,
+    CommandResponse,
+    Envelope,
+    Message,
+    MessageTypes,
+    Notification,
+    UnknownCommandResponse,
+} from '../../types/index.ts'
+import { BlipError } from '../bliperror.ts'
+import { ConnectionSender, type ConnectionSenderConstructor, OpenConnectionSender } from '../sender.ts'
+import { SessionNegotiator } from '../sessionnegotiator.ts'
+import { EnvelopeThrottler } from '../throttler.ts'
+
+export class WebSocketSender extends OpenConnectionSender {
+    private readonly throttler = new EnvelopeThrottler()
+    private readonly connectionHandle: WebSocketHandle<Envelope>
+
+    constructor(options: ConstructorParameters<ConnectionSenderConstructor>[0]) {
+        super(options)
+
+        const prefix = options.tenantId ? `${options.tenantId}.` : ''
+        this.connectionHandle = new WebSocketHandle<Envelope>(
+            `wss://${prefix}ws.${this.domain}`,
+            (webSocket) => {
+                this.sessionNegotiator = new SessionNegotiator(this, (session) => {
+                    webSocket.send(JSON.stringify(session))
+                })
+                return this.sessionNegotiator.negotiate({
+                    node: options.node,
+                    authentication: options.authentication,
+                })
+            },
+            (envelope: Envelope) => {
+                if (this.sessionNegotiator?.negotiating) {
+                    return this.sessionNegotiator.handleEnvelope(envelope)
+                }
+
+                this.envelopeResolver.resolve(envelope)
+            },
+        )
+    }
+
+    public async sendMessage<Type extends MessageTypes>(message: Message<Type>): Promise<void> {
+        await this.throttler.throttle('message')
+
+        const webSocket = await this.connectionHandle.get()
+        await this.sessionNegotiator?.ensurePresence()
+
+        webSocket.send(JSON.stringify(message))
+    }
+
+    public sendCommand(command: Command<CommandMethods>): Promise<unknown> {
+        return this.withRetryPolicy(async () => {
+            await this.throttler.throttle('command')
+
+            const envelopeResponsePromise = this.envelopeResolver.createEnvelopeResponsePromise(command.id)
+
+            const webSocket = await this.connectionHandle.get()
+            await this.sessionNegotiator?.ensurePresence(command.uri)
+            webSocket.send(JSON.stringify(command))
+
+            const response = (await envelopeResponsePromise) as CommandResponse<
+                unknown,
+                CommandMethods,
+                'success' | 'failure'
+            >
+            if (BlipError.isFailedCommandResponse(response)) {
+                throw BlipError.commandResponseToBlipError(command.uri, response)
+            } else if (response.status === 'success') {
+                return response.resource
+            } else {
+                throw new Error(`Unexpected response for command '${command.uri}': ${JSON.stringify(response)}`)
+            }
+        })
+    }
+
+    public async sendNotification(notification: Notification): Promise<void> {
+        const webSocket = await this.connectionHandle.get()
+        webSocket.send(JSON.stringify(notification))
+    }
+
+    public async sendCommandResponse(response: UnknownCommandResponse): Promise<void> {
+        const webSocket = await this.connectionHandle.get()
+        webSocket.send(JSON.stringify(response))
+    }
+
+    public async isConnected(): Promise<boolean> {
+        const webSocket = await this.connectionHandle.get()
+        return webSocket.readyState === WebSocket.OPEN
+    }
+
+    public async close() {
+        this.sessionNegotiator?.finish()
+        await this.connectionHandle.close()
+    }
+
+    public static login = ConnectionSender.login<WebSocketSender>
+
+    private async withRetryPolicy<T>(fn: () => Promise<T>, retries = 5): Promise<T> {
+        try {
+            return await fn()
+        } catch (err) {
+            if (retries > 0 && err instanceof BlipError && BlipError.retryableBlipErrors.includes(err.code)) {
+                // wait before retrying
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * 1000))
+                return this.withRetryPolicy(fn, retries - 1)
+            }
+
+            throw err
+        }
+    }
+}
+
+class WebSocketHandle<T> {
+    private currentWebSocketPromise: Promise<WebSocket> | null = null
+    private closing = false
+    private connectionAttempts = 0
+
+    constructor(url: string, onConnected: (webSocket: WebSocket) => Promise<void>, onMessage: (message: T) => void) {
+        this.currentWebSocketPromise = this.connect(url, onConnected, onMessage)
+    }
+
+    public get() {
+        return this.currentWebSocketPromise!
+    }
+
+    public async close() {
+        if (!this.closing && this.currentWebSocketPromise) {
+            this.closing = true
+            const current = await this.currentWebSocketPromise
+            current.close()
+        }
+    }
+
+    private async connect(
+        url: string,
+        onConnected: (webSocket: WebSocket) => Promise<void>,
+        onMessage: (message: T) => void,
+    ) {
+        const connection = new WebSocket(url, 'lime')
+
+        await new Promise<void>((resolve, reject) => {
+            connection.onopen = () => {
+                resolve()
+            }
+            connection.onclose = () => {
+                if (!this.closing) {
+                    this.connectionAttempts++
+                    if (this.connectionAttempts < 3) {
+                        this.currentWebSocketPromise = this.connect(url, onConnected, onMessage)
+                    } else {
+                        reject(new Error('Failed to connect to WebSocket'))
+                    }
+                }
+            }
+            connection.onmessage = (event) => {
+                onMessage(JSON.parse(event.data))
+            }
+            connection.onerror = (error) => {
+                if (error instanceof ErrorEvent) {
+                    throw new Error(`WebSocket error: ${error.message}`, { cause: error })
+                } else {
+                    throw error
+                }
+            }
+        })
+
+        await onConnected(connection)
+        this.connectionAttempts = 0
+
+        return connection
+    }
+}

package/src/types/account.ts

@@ -0,0 +1,84 @@
+import type { UnknownMessageContent } from './message.ts'
+import type { Identity } from './node.ts'
+
+/* Impl ref: https://github.com/takenet/lime-csharp/blob/master/src/Lime.Messaging/Resources/Presence.cs */
+export type Presence = {
+    status: 'unavailable' | 'available' | 'busy' | 'away' | 'invisible'
+    /**
+     * Rule to the server route envelopes addressed to the identity
+     * - Instance Routing: Strict match on full node, including instance.
+     * - Identity Routing: Matches full node or base identity (no instance).
+     * - Promiscuous Identity: Matches base identity or any instance variation.
+     */
+    routingRule: 'instance' | 'identity'
+    /** The date of the last known presence status for the node */
+    lastSeen: string
+    /** If true, indicates that the delivery of envelopes for the current session should be distributed by using the round-robin strategy between the resolved routes with this setting */
+    roundRobin?: boolean
+    /** If true, indicates that the instance should be ignored in the routing rules */
+    promiscuous?: boolean
+    /** If true, indicates that the current session should receive the messages sent by itself */
+    echo?: boolean
+    /** The priority of the presence, higher means more priority */
+    priority?: number
+    /** Present instances for a identity */
+    instances: Array<string>
+}
+
+export type Account = {
+    identity: Identity
+    fullName: string
+    email?: Identity
+    phoneNumber?: string
+    photoUri?: string
+    // When the culture is missing, it should default to pt-BR
+    culture?: string
+    extras?: Record<string, string | null>
+    creationDate: string
+}
+
+export type BlipLanguage = 'en' | 'pt' | 'es'
+
+export type Tenant = {
+    canViewMobileDesk: boolean
+    creationDate: string
+    creationSource: string
+    id: string
+    isTestContract: boolean
+    name: string
+    ownerIdentity: string
+    paymentAccount?: string
+    photoUri?: string
+}
+
+export type Contact = {
+    identity: Identity
+    name?: string
+    group?: string
+    city?: string
+    email?: string
+    phoneNumber?: string
+    source?: string
+    taxDocument?: string
+    extras?: Record<string, string | null>
+    lastMessageDate?: string
+}
+
+export type ThreadItem = {
+    id: string
+    direction: 'sent' | 'received'
+    date: string
+    status: string
+    reason?: {
+        code: number
+        description: string
+    }
+    metadata?: Record<string, string | null>
+} & UnknownMessageContent
+
+export type Comment = {
+    id: Identity
+    storageDate: string
+    authorIdentity: Identity
+    content: string
+}

package/src/types/analytics.ts

@@ -0,0 +1,18 @@
+import type { Identity } from './node.ts'
+
+export type EventTrack = {
+    ownerIdentity?: Identity
+    category: string
+    action: string
+    extras: Record<string, string>
+    contact?: {
+        identity: Identity
+    }
+    messageId?: string
+    storageDate?: string
+    count?: number
+}
+
+export type NonNullableEventTracking = {
+    [P in keyof EventTrack]-?: NonNullable<EventTrack[P]>
+}

package/src/types/billing.ts

@@ -0,0 +1,15 @@
+export type Plan = {
+    name: string
+    ownerIdentity: string
+    planValue: number
+    currencyCode: string
+    extras: {
+        Cluster: string
+        CommandThroughput: string
+        DataRetentionPeriod: string
+        IdForHubSpotDeal: string
+        IsDefaultPlan: string
+        MessageThroughput: string
+        NotificationThroughput: string
+    }
+}

package/src/types/command.ts

@@ -0,0 +1,47 @@
+import type { Envelope } from './envelope.ts'
+import type { Reason } from './reason.ts'
+
+type ResourceCommand<TResource = unknown> = {
+    type: string
+    resource: TResource
+}
+
+type NoResourceCommand = object
+
+interface CommandMethodsProperties {
+    get: NoResourceCommand
+    set: ResourceCommand
+    merge: ResourceCommand
+    delete: NoResourceCommand | ResourceCommand
+    observe: ResourceCommand
+}
+
+export type CommandMethods = keyof CommandMethodsProperties
+
+export type Command<TMethod extends CommandMethods> = Envelope & {
+    uri: string
+    method: TMethod
+} & CommandMethodsProperties[TMethod]
+
+export type UnknownCommand = Command<CommandMethods>
+
+export type CommandResponse<
+    TResponse,
+    TMethod extends CommandMethods,
+    TStatus extends 'success' | 'failure',
+> = Envelope & {
+    method: TMethod
+} & (TStatus extends 'success'
+        ? {
+              status: 'success'
+              type?: string
+              resource?: TResponse
+          }
+        : {
+              status: 'failure'
+              reason: Reason
+          })
+
+export type UnknownCommandResponse = CommandResponse<unknown, CommandMethods, 'success' | 'failure'>
+
+export const isCommand = (envelope: Envelope): envelope is UnknownCommand => 'method' in envelope && 'uri' in envelope

package/src/types/commons.ts

@@ -0,0 +1,16 @@
+// This type is weird because typescript doesn't like recursion types with generics
+// Error when done the clean way: Type instantiation is excessively deep and possibly infinite
+export type JsonValue<
+    D extends number = 8, // max depth
+    A extends Array<0> = [], // accumulator
+> =
+    | null
+    | boolean
+    | number
+    | string
+    | (A['length'] extends D ? unknown : Array<JsonValue<D, [0, ...A]>>) // arrays
+    | (A['length'] extends D ? unknown : { [k: string]: JsonValue<D, [0, ...A]> }) // objects
+
+export type JsonObject = Record<string, JsonValue>
+
+export type MaybePromise<T> = T | Promise<T>

package/src/types/desk.ts

@@ -0,0 +1,51 @@
+export type TicketStatus =
+    | 'Waiting'
+    | 'Open'
+    | 'ClosedAttendant'
+    | 'ClosedClient'
+    | 'Transferred'
+    | 'ClosedClientInactivity'
+    | 'ClosedAttendantInactivity'
+
+export type AttendanceHour = {
+    id: string
+    title: string
+    description: string
+    isMain: boolean
+}
+
+export enum DayOfWeek {
+    Sunday = 'Sunday',
+    Monday = 'Monday',
+    Tuesday = 'Tuesday',
+    Wednesday = 'Wednesday',
+    Thursday = 'Thursday',
+    Friday = 'Friday',
+    Saturday = 'Saturday',
+}
+
+export type AttendanceHourScheduleItem = {
+    id: string
+    startTime: string
+    endTime: string
+    dayOfWeek: DayOfWeek
+}
+
+export type AttendanceHourOffItem = {
+    id: string
+    reason: string
+    startDate: string
+    endDate: string
+}
+
+export type Queue = {
+    id: string
+    description: string
+}
+
+export type DetailedAttendanceHour = {
+    attendanceHour: AttendanceHour
+    attendanceHourScheduleItems: Array<AttendanceHourScheduleItem>
+    attendanceHourOffItems: Array<AttendanceHourOffItem>
+    queues: Array<Queue>
+}