@whitewall/blip-sdk 0.0.136 → 0.0.137

package/src/sender/http/httpsender.ts

@@ -0,0 +1,94 @@
+import type { Command, CommandMethods, Message, MessageTypes, UnknownCommandResponse } from '../../types/index.ts'
+import { BlipError } from '../bliperror.ts'
+import { ConnectionSender, type ConnectionSenderConstructor, type Sender } from '../sender.ts'
+import { EnvelopeThrottler } from '../throttler.ts'
+
+export class HttpSender extends ConnectionSender implements Sender {
+    private readonly baseurl: string
+    private readonly token: string
+    private readonly throttler = new EnvelopeThrottler()
+
+    constructor(options: ConstructorParameters<ConnectionSenderConstructor>[0]) {
+        super(options)
+
+        const prefix = options.tenantId ? `${options.tenantId}.` : ''
+        this.baseurl = `https://${prefix}http.${this.domain}`
+
+        if (options.authentication.scheme === 'key') {
+            this.token = HttpSender.createToken(options.node, options.authentication.key)
+        } else if (options.authentication.scheme === 'token') {
+            this.token = options.authentication.token
+        } else {
+            throw new Error('HttpSender only supports key or token authentication')
+        }
+    }
+
+    public sendMessage<Type extends MessageTypes>(message: Message<Type>): Promise<void> {
+        return this.withFetchRetryPolicy(async () => {
+            await this.throttler.throttle('message')
+            const response = await this.fetch('messages', JSON.stringify(message))
+
+            if (!response.ok) {
+                throw new Error(`Failed to send message: ${response.statusText} (${response.status})`)
+            }
+        })
+    }
+
+    public sendCommand(command: Command<CommandMethods>): Promise<unknown> {
+        return this.withFetchRetryPolicy(async () => {
+            await this.throttler.throttle('command')
+            const response = await this.fetch('commands', JSON.stringify(command))
+
+            if (!response.ok) {
+                throw new Error(`Failed to send command: ${response.statusText} (${response.status})`)
+            }
+
+            const result: UnknownCommandResponse = await response.json()
+            if (BlipError.isFailedCommandResponse(result)) {
+                throw BlipError.commandResponseToBlipError(command.uri, result)
+            } else if (result.status === 'success') {
+                return result.resource
+            } else {
+                throw new Error(`Unexpected response for command '${command.uri}': ${JSON.stringify(response)}`)
+            }
+        })
+    }
+
+    public static login = ConnectionSender.login<HttpSender>
+
+    private async fetch(path: 'commands' | 'messages', body: string) {
+        return await fetch(`${this.baseurl}/${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Key ${this.token}`,
+            },
+            body,
+        })
+    }
+
+    private async withFetchRetryPolicy<T>(fn: () => Promise<T>, retries = 5): Promise<T> {
+        try {
+            return await fn()
+        } catch (err) {
+            if (
+                retries > 0 &&
+                err instanceof Error &&
+                (err.message.endsWith('(429)') ||
+                    err.message.endsWith('(504)') ||
+                    err.message.endsWith('(502)') ||
+                    (err instanceof BlipError && BlipError.retryableBlipErrors.includes(err.code)) ||
+                    // Probably cloudflare trying to mitigate a DDoS attack
+                    (err.cause instanceof Error && err.cause?.name === 'ConnectTimeoutError') ||
+                    err.message === 'terminated' ||
+                    err.message === 'fetch failed')
+            ) {
+                // wait before retrying
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * 1000))
+                return this.withFetchRetryPolicy(fn, retries - 1)
+            }
+
+            throw err
+        }
+    }
+}

package/src/sender/index.ts

@@ -0,0 +1,7 @@
+export * from './sender.ts'
+export * from './bliperror.ts'
+export * from './gateway/customgatewaysender.ts'
+export * from './plugin/pluginsender.ts'
+export * from './websocket/websocketsender.ts'
+export * from './tcp/tcpsender.ts'
+export * from './http/httpsender.ts'

package/src/sender/plugin/communication.ts

@@ -0,0 +1,72 @@
+import { randomId } from '../../utils/random.ts'
+
+export const startChannel = () => {
+    const caller = window.name ?? randomId()
+    let isDesk = false
+
+    const waitingMessages: Record<string, Pick<PromiseWithResolvers<unknown>, 'reject' | 'resolve'>> = {}
+    const messageHandler = ({ data, origin }: MessageEvent) => {
+        if (origin.endsWith('.desk.blip.ai')) {
+            isDesk = true
+        }
+
+        const deferred = waitingMessages[data?.trackingProperties?.id]
+        if (deferred) {
+            if (data.message?.caller === caller) {
+                // This is a echo message, ignore it
+                return
+            }
+
+            delete waitingMessages[data.trackingProperties.id]
+            if (data.error) {
+                deferred.reject(JSON.parse(data.error))
+            } else {
+                deferred.resolve(data.response)
+            }
+        }
+    }
+    window.addEventListener('message', messageHandler)
+
+    let isDestroyed = false
+    return {
+        get isDesk() {
+            return isDesk
+        },
+        post: <T>(action: string, content: unknown, options?: { fireAndForget: T extends void ? never : true }) => {
+            if (isDestroyed) {
+                throw new Error('Channel is destroyed')
+            }
+
+            const id = randomId()
+
+            let promise: Promise<unknown>
+            if (options?.fireAndForget) {
+                promise = Promise.resolve()
+            } else {
+                const deferred = Promise.withResolvers()
+                waitingMessages[id] = { reject: deferred.reject, resolve: deferred.resolve }
+                promise = deferred.promise
+            }
+
+            window.parent.postMessage(
+                {
+                    message: {
+                        action: `blipEvent:${action}`,
+                        content,
+                        caller,
+                    },
+                    trackingProperties: {
+                        id,
+                    },
+                },
+                '*',
+            )
+
+            return promise as Promise<T>
+        },
+        destroy: () => {
+            window.removeEventListener('message', messageHandler)
+            isDestroyed = true
+        },
+    }
+}

package/src/sender/plugin/pluginsender.ts

@@ -0,0 +1,75 @@
+import {
+    type BlipClient,
+    BlipError,
+    type Command,
+    type CommandMethods,
+    type Message,
+    type MessageTypes,
+    Node,
+    type Sender,
+} from '../../index.ts'
+import { isReason } from '../../types/reason.ts'
+import { startChannel } from './communication.ts'
+
+export class PluginSender implements Sender {
+    public readonly channel
+
+    constructor() {
+        this.channel = startChannel()
+    }
+
+    public async sendMessage<Type extends MessageTypes>(message: Message<Type>) {
+        await this.sendCommand({
+            id: message.id,
+            to: 'postmaster@scheduler.msging.net',
+            uri: '/schedules',
+            method: 'set',
+            type: 'application/vnd.iris.schedule+json',
+            resource: {
+                message,
+                when: new Date().toISOString(),
+            },
+        })
+    }
+
+    public async sendCommand(command: Command<CommandMethods>): Promise<unknown> {
+        const destination =
+            this.getRealm() === 'desk'
+                ? undefined
+                : command.to && Node.from(command.to).domain?.endsWith('msging.net')
+                  ? 'MessagingHubService'
+                  : 'BlipService'
+
+        try {
+            return await this.channel.post('sendCommand', { command, destination })
+        } catch (err) {
+            if (isReason(err)) {
+                throw new BlipError(command.uri, err)
+            } else if (BlipError.isFailedCommandResponse(err)) {
+                throw BlipError.commandResponseToBlipError(command.uri, err)
+            }
+
+            throw err
+        }
+    }
+
+    public static check(blipClient: BlipClient): PluginSender {
+        const isPluginSender = blipClient.sender instanceof PluginSender
+        if (!isPluginSender) {
+            throw new Error('This command is only allowed for plugin senders')
+        }
+        return blipClient.sender
+    }
+
+    public static getRealm(blipClient: BlipClient): 'portal' | 'desk' {
+        const isPluginSender = blipClient.sender instanceof PluginSender
+        if (!isPluginSender) {
+            throw new Error('This command is only allowed for plugin senders')
+        }
+        return blipClient.sender.getRealm()
+    }
+
+    private getRealm(): 'portal' | 'desk' {
+        return this.channel.isDesk ? 'desk' : 'portal'
+    }
+}

package/src/sender/security.ts

@@ -0,0 +1,33 @@
+// ref: https://github.com/takenet/lime-csharp/tree/master/src/Lime.Protocol/Security
+export interface GuestAuthentication {
+    scheme: 'guest'
+}
+
+export interface KeyAuthentication {
+    scheme: 'key'
+    key: string
+}
+
+// This auth method doesn't exist in reality, it is only used to facilitate usage
+export interface TokenAuthentication {
+    scheme: 'token'
+    token: string
+}
+
+export interface ExternalAuthentication {
+    scheme: 'external'
+    issuer: string
+    token: string
+}
+
+export interface PlainAuthentication {
+    scheme: 'plain'
+    password: string
+}
+
+export type Authentication =
+    | GuestAuthentication
+    | KeyAuthentication
+    | ExternalAuthentication
+    | PlainAuthentication
+    | TokenAuthentication

package/src/sender/sender.ts

@@ -0,0 +1,145 @@
+import {
+    type BlipDomain,
+    type Command,
+    type CommandMethods,
+    type Identity,
+    type Message,
+    type MessageTypes,
+    Node,
+    type NodeLike,
+    type Notification,
+    type UnknownCommandResponse,
+} from '../types/index.ts'
+import { EnvelopeResolver, type EventMap, type Listener } from './enveloperesolver.ts'
+import type { Authentication } from './security.ts'
+import type { SessionNegotiator } from './sessionnegotiator.ts'
+
+export interface Sender {
+    sendMessage<Type extends MessageTypes>(message: Message<Type>): Promise<void>
+    sendCommand(command: Command<CommandMethods>): Promise<unknown>
+}
+
+export type ConnectionSenderConstructor<TSender = Sender> = new (options: {
+    node: NodeLike
+    authentication: Authentication
+    tenantId?: string
+}) => TSender
+
+export class ConnectionSender {
+    private readonly _domain: BlipDomain
+
+    constructor(options: ConstructorParameters<ConnectionSenderConstructor>[0]) {
+        this._domain = (Node.from(options.node).domain as BlipDomain) ?? 'msging.net'
+    }
+
+    public get domain() {
+        return this._domain
+    }
+
+    // this method is a mess but provides a good and flexible api with a single method to login
+    protected static login<S extends ConnectionSender>(bot: string | Identity, accessKey: string, tenantId?: string): S
+    protected static login<S extends ConnectionSender>(token: string, tenantId?: string): S
+    protected static login<S extends ConnectionSender>(
+        tokenOrBot: string | Identity,
+        accessKeyOrTenantId?: string,
+        tenantIdOrUndefined?: string,
+    ) {
+        let node: NodeLike
+        let accessKey: string
+        let tenantId: string | undefined
+
+        const isTokenBasedAuth = !tenantIdOrUndefined && typeof tokenOrBot === 'string'
+
+        if (isTokenBasedAuth) {
+            try {
+                const { identity, secret } = ConnectionSender.parseToken(tokenOrBot)
+                node = identity
+                accessKey = secret
+                tenantId = accessKeyOrTenantId
+            } catch {
+                if (!accessKeyOrTenantId) {
+                    throw new Error('Invalid token format and no access key provided')
+                }
+                node = Node.from(tokenOrBot, 'msging.net')
+                accessKey = accessKeyOrTenantId
+                tenantId = tenantIdOrUndefined
+            }
+        } else {
+            if (!accessKeyOrTenantId) {
+                throw new Error('Access key must be provided for bot-based authentication')
+            }
+            node = Node.from(tokenOrBot, 'msging.net')
+            accessKey = accessKeyOrTenantId
+            tenantId = tenantIdOrUndefined
+        }
+
+        // biome-ignore lint/complexity/noThisInStatic: fair use-case
+        return new this({
+            node,
+            authentication: {
+                scheme: 'key',
+                key: accessKey,
+            },
+            tenantId,
+        }) as S
+    }
+
+    public static createToken(node: NodeLike, secret: string) {
+        const identity = Node.from(node).toIdentity()
+        return btoa(`${identity}:${atob(secret)}`)
+    }
+
+    public static parseToken(token: string) {
+        let cleantoken = token.trim()
+        const parts = cleantoken.split(' ')
+        if (parts.length > 1) {
+            cleantoken = parts[1]
+        }
+
+        const [identityOrIdentifier, key] = atob(cleantoken).split(':')
+        if (!identityOrIdentifier || !key) {
+            throw new Error('Invalid token format')
+        }
+
+        const identity = Node.isValid(identityOrIdentifier)
+            ? identityOrIdentifier
+            : new Node(identityOrIdentifier, 'msging.net').toIdentity()
+
+        return {
+            identity,
+            secret: btoa(key),
+        }
+    }
+}
+
+export abstract class OpenConnectionSender extends ConnectionSender implements Sender {
+    protected readonly envelopeResolver = new EnvelopeResolver(this)
+    protected sessionNegotiator: SessionNegotiator | null = null
+
+    abstract sendMessage<Type extends MessageTypes>(message: Message<Type>): Promise<void>
+    abstract sendCommand(command: Command<CommandMethods>): Promise<unknown>
+    abstract sendNotification(notification: Notification): Promise<void>
+    abstract close(): Promise<void>
+    abstract sendCommandResponse(response: UnknownCommandResponse): Promise<void>
+
+    public on<K extends keyof EventMap>(
+        ev: K,
+        listener: Listener<K>['callback'],
+        predicate?: Listener<K>['predicate'],
+    ): this {
+        this.envelopeResolver.addListener(ev, {
+            callback: listener,
+            predicate: predicate,
+        })
+        return this
+    }
+
+    public off<K extends keyof EventMap>(ev: K, listener: Listener<K>['callback']): this {
+        this.envelopeResolver.removeListener(ev, listener)
+        return this
+    }
+
+    public get session() {
+        return this.sessionNegotiator?.session ?? null
+    }
+}

package/src/sender/sessionnegotiator.ts

@@ -0,0 +1,175 @@
+import type { Envelope } from '../types/envelope.ts'
+import { Node, type NodeLike } from '../types/node.ts'
+import type { Session } from '../types/session.ts'
+import type { Authentication } from './security.ts'
+import { OpenConnectionSender } from './sender.ts'
+
+export type ConnectionSession = {
+    id: string
+    localNode: Node
+    remoteNode: Node
+    scheme: Authentication['scheme']
+}
+
+export class SessionNegotiator {
+    public state: Session['state'] | 'present' = 'new'
+    public session: ConnectionSession | null = null
+
+    private presencePromise: Promise<void> | null = null
+    private currentSessionResolver: Pick<PromiseWithResolvers<Session>, 'reject' | 'resolve'> | null = null
+
+    constructor(
+        private readonly sender: OpenConnectionSender,
+        private readonly sendSession: (session: Session) => void,
+    ) {}
+
+    public async negotiate(options: {
+        node: NodeLike
+        authentication: Authentication
+    }): Promise<void> {
+        const timeout = setTimeout(() => {
+            if (this.negotiating) {
+                this.sender.close()
+                throw new Error('Negotiation timeout')
+            }
+        }, 60000) // 60 seconds
+
+        try {
+            this.sendSession({
+                state: 'new',
+            } as Session)
+
+            const negotiation = await this.waitForSessionResponse()
+            let authenticating: Session
+            if (negotiation.state === 'negotiating') {
+                if (!negotiation.encryptionOptions?.includes('none')) {
+                    throw new Error('Unsupported encryption options')
+                }
+
+                this.sendSession({
+                    id: negotiation.id,
+                    state: 'negotiating',
+                    encryption: 'none',
+                    compression: negotiation.compressionOptions?.at(-1),
+                })
+                await this.waitForSessionResponse()
+                authenticating = await this.waitForSessionResponse()
+            } else if (negotiation.state === 'authenticating') {
+                authenticating = negotiation
+            } else {
+                throw new Error('Unexpected session state')
+            }
+
+            if (options.authentication.scheme === 'token') {
+                const { secret } = OpenConnectionSender.parseToken(options.authentication.token)
+                options.authentication = {
+                    scheme: 'key',
+                    key: secret,
+                }
+            }
+
+            if (!authenticating.schemeOptions?.includes(options.authentication.scheme)) {
+                throw new Error(
+                    `Unsupported authentication scheme: ${options.authentication.scheme} (${authenticating.schemeOptions})`,
+                )
+            }
+
+            const { scheme, ...authenticationOptions } = options.authentication
+            this.sendSession({
+                id: authenticating.id,
+                from: options.node,
+                state: 'authenticating',
+                scheme,
+                authentication: authenticationOptions,
+            })
+            const authenticated = await this.waitForSessionResponse()
+            if (authenticated.state !== 'established') {
+                throw new Error('Authentication failed')
+            }
+
+            this.session = {
+                id: authenticated.id,
+                localNode: Node.from(authenticated.to!),
+                remoteNode: Node.from(authenticated.from!),
+                scheme,
+            }
+        } finally {
+            clearTimeout(timeout)
+        }
+    }
+
+    public handleEnvelope(envelope: Envelope) {
+        if (this.currentSessionResolver) {
+            this.currentSessionResolver.resolve(envelope as Session)
+            this.currentSessionResolver = null
+        }
+    }
+
+    public async ensurePresence(currentCommandUri = ''): Promise<void> {
+        if (!this.session) {
+            throw new Error('Session not established')
+        }
+
+        if (this.state === 'present') {
+            return
+        }
+
+        if (this.session.scheme === 'guest') {
+            return
+        }
+
+        if (currentCommandUri === '/presence') {
+            // someone is already setting the presence manually
+            if (!this.presencePromise) {
+                this.state = 'present'
+            }
+
+            // its actually setting the presence
+            return
+        }
+
+        if (this.presencePromise) {
+            return this.presencePromise
+        }
+
+        this.presencePromise = this.sender.sendCommand({
+            id: Date.now().toString(),
+            method: 'set',
+            uri: '/presence',
+            type: 'application/vnd.lime.presence+json',
+            resource: {
+                status: 'available',
+            },
+        }) as Promise<void>
+
+        await this.presencePromise
+        this.state = 'present'
+    }
+
+    public finish() {
+        if (!this.session) {
+            throw new Error('Session not established')
+        }
+
+        this.sendSession({
+            id: this.session?.id,
+            state: 'finishing',
+        })
+    }
+
+    public get negotiating(): boolean {
+        return this.state !== 'established' && this.state !== 'present'
+    }
+
+    private async waitForSessionResponse(): Promise<Session> {
+        const { promise, resolve, reject } = Promise.withResolvers<Session>()
+        this.currentSessionResolver = { resolve, reject }
+        const session = await promise
+        if (session.state === 'failed') {
+            throw new Error(`Session negotiation failed: ${session.reason?.description} (${session.reason?.code})`)
+        }
+
+        this.state = session.state
+        return session
+    }
+}