@whitewall/blip-sdk 0.0.185 → 0.0.187

package/src/namespaces/portal.ts

@@ -2,6 +2,7 @@ import type { BlipClient } from '../client.ts'
 import { BlipError } from '../sender/bliperror.ts'
 import { PluginSender } from '../sender/plugin/pluginsender.ts'
 import type { Tenant } from '../types/account.ts'
+import type { Plan } from '../types/billing.ts'
 import { type Identity, Node, type PossiblyNode } from '../types/node.ts'
 import type {
     Application,
@@ -193,6 +194,27 @@ export class PortalNamespace extends Namespace {
         })
     }
 
+    /**
+     * Creates the tenant when it doesn't exist (the caller becomes its owner and admin)
+     * or updates it when it does (requires the tenant admin role).
+     */
+    public async setTenant(
+        tenantId: string,
+        tenant: Pick<Tenant, 'name'> &
+            Partial<Pick<Tenant, 'photoUri' | 'isTestContract' | 'creationSource' | 'canViewMobileDesk'>>,
+        opts?: ConsumeOptions,
+    ): Promise<void> {
+        return await this.sendCommand(
+            {
+                method: 'set',
+                uri: uri`/tenants/${tenantId}`,
+                type: 'application/vnd.iris.portal.tenant+json',
+                resource: { id: tenantId, ...tenant },
+            },
+            opts,
+        )
+    }
+
     public async getTenantActiveMessagesMetrics(
         tenantId: string,
         interval: 'D' | 'M' | 'NI',
@@ -372,6 +394,44 @@ export class PortalNamespace extends Namespace {
         )
     }
 
+    /** Lists all available billing plans. */
+    public async getPlans(opts?: ConsumeOptions): Promise<Array<Plan>> {
+        return await this.sendCommand(
+            {
+                method: 'get',
+                uri: uri`/plans`,
+            },
+            {
+                collection: true,
+                ...opts,
+            },
+        )
+    }
+
+    /**
+     * Subscribes a payment account to a plan, replacing the account's active subscription.
+     *
+     * **Admin-only**: the server rejects any caller other than `admin@blip.ai`
+     *
+     * The subscriber is the tenant's `paymentAccount` identity, not the tenant id, see {@link getTenant}.
+     * Reads such as {@link getTenantSubscription} may briefly return the previous subscription right after this call (eventual consistency).
+     */
+    public async setPlanSubscription(
+        planId: string,
+        paymentAccount: Identity,
+        opts?: ConsumeOptions,
+    ): Promise<TenantSubscription> {
+        return await this.sendCommand(
+            {
+                method: 'set',
+                uri: uri`/plans/${planId}/subscriptions`,
+                type: 'application/vnd.lime.identity',
+                resource: paymentAccount,
+            },
+            opts,
+        )
+    }
+
     public async deleteTenantUser(tenantId: string, user: Identity, opts?: ConsumeOptions): Promise<void> {
         return await this.sendCommand(
             {

package/src/namespaces/whatsapp.ts

@@ -1,4 +1,5 @@
 import type { BlipClient } from '../client.ts'
+import type { Envelope } from '../types/envelope.ts'
 import type { Identity } from '../types/index.ts'
 import type { MessageTemplate, WhatsAppTemplateLanguage, WhatsappFlow } from '../types/whatsapp.ts'
 import { uri } from '../utils/uri.ts'
@@ -33,6 +34,65 @@ export class WhatsAppNamespace extends Namespace {
         }
     }
 
+    public getMessageMetadata(envelope: Envelope): {
+        /**
+         * Business-Scoped User ID of the user (e.g. `BR.11815799212886844830`).
+         * Unique per user ↔ business relationship: the same user has different BSUIDs across businesses.
+         */
+        bsuid?: string
+        /** Parent BSUID, correlating the user across eligible Business Accounts of the same organization */
+        parentId?: string
+        /** Username of the user, when adopted */
+        username?: string
+    } {
+        return {
+            bsuid: envelope.metadata?.['#wa.bsuid'] ?? undefined,
+            parentId: envelope.metadata?.['#wa.parentId'] ?? undefined,
+            username: envelope.metadata?.['#wa.username'] ?? undefined,
+        }
+    }
+
+    /**
+     * This does not query Meta in real time: numbers Blip hasn't seen a BSUID for are simply omitted from the result, which is not an error.
+     * Numbers must be in full form (country code + area code + number); the `+` sign is optional.
+     */
+    public async getContactsMapping(phoneNumbers: Array<string>, opts?: ConsumeOptions) {
+        const results: Array<{
+            /** Internal Blip contact id. Phone-based (e.g. `5531999999999`) or a Blip-internal GUID when the phone is not shared */
+            id: string
+            /** Business-Scoped User ID, unique per user ↔ business relationship (e.g. `BR.11815799212886844830`) */
+            bsuid: string
+            /** Phone number of the contact when available, without the `+` sign */
+            waId?: string
+            /** Correlation id between eligible Business Accounts of the same organization */
+            parentUserId?: string
+            /** Date of the most recent interaction of the contact registered by the platform */
+            lastReadDate?: string
+        }> = []
+
+        // The endpoint accepts at most 100 numbers per request and is throughput-limited,
+        // so chunks are sent sequentially instead of in parallel
+        for (let i = 0; i < phoneNumbers.length; i += 100) {
+            const chunk = phoneNumbers.slice(i, i + 100)
+            results.push(
+                ...(await this.sendCommand<'get', typeof results>(
+                    {
+                        method: 'get',
+                        uri: uri`/external-contacts-mapping?${{ phoneNumbers: chunk.join(';') }}`,
+                    },
+                    {
+                        ...opts,
+                        collection: true,
+                        // The full list is sent in a single request, there is no pagination
+                        fetchall: false,
+                    },
+                )),
+            )
+        }
+
+        return results
+    }
+
     /**
      * This is a heavily cached endpoint on Meta, so it may take a while to reflect changes
      * @param filters.status - Filter by status of the message template

package/src/sender/gateway/customgatewaysender.ts

@@ -27,7 +27,7 @@ export class CustomGatewayHttpSender extends ConnectionSender implements Sender
                 'Content-Type': 'application/json',
                 Authorization: `Basic ${this.token}`,
             },
-            body: JSON.stringify(message),
+            body: this.serializeOutboundEnvelope(message),
         })
 
         if (!response.ok) {

package/src/sender/http/httpsender.ts

@@ -52,7 +52,7 @@ export class HttpSender extends ConnectionSender implements Sender {
     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))
+            const response = await this.fetch('messages', this.serializeOutboundEnvelope(message))
 
             if (!response.ok) {
                 throw new Error(`Failed to send message: ${response.statusText} (${response.status})`)
@@ -63,7 +63,7 @@ export class HttpSender extends ConnectionSender implements Sender {
     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))
+            const response = await this.fetch('commands', this.serializeOutboundEnvelope(command))
 
             if (!response.ok) {
                 throw new Error(`Failed to send command: ${response.statusText} (${response.status})`)

package/src/sender/sender.ts

@@ -2,6 +2,7 @@ import {
     type BlipDomain,
     type Command,
     type CommandMethods,
+    type Envelope,
     type Identity,
     type Message,
     type MessageTypes,
@@ -30,17 +31,30 @@ const ROOT_AUTHORITIES: ReadonlyArray<BlipDomain> = ['msging.net', 'blip.ai', '0
 
 export class ConnectionSender {
     private readonly _domain: BlipDomain
+    private readonly _node: Node
 
     constructor(options: ConstructorParameters<ConnectionSenderConstructor>[0]) {
-        const nodeDomain = Node.from(options.node).domain ?? 'msging.net'
+        this._node = Node.from(options.node)
+        const nodeDomain = this._node.domain ?? 'msging.net'
         this._domain =
             ROOT_AUTHORITIES.find((root) => nodeDomain === root || nodeDomain.endsWith(`.${root}`)) ?? 'msging.net'
     }
 
+    public get node() {
+        return this._node
+    }
+
     public get domain() {
         return this._domain
     }
 
+    protected serializeOutboundEnvelope(envelope: Envelope): string {
+        if (envelope.from && !envelope.pp) {
+            envelope.pp = this.node
+        }
+        return JSON.stringify(envelope)
+    }
+
     // 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
@@ -146,6 +160,11 @@ export abstract class OpenConnectionSender extends ConnectionSender implements S
         return this.sessionNegotiator?.session ?? null
     }
 
+    public override get node() {
+        // the negotiated local node is authoritative: it carries the server-assigned instance
+        return this.sessionNegotiator?.session?.localNode ?? super.node
+    }
+
     public close(): Promise<void> {
         this.envelopeResolver.close()
         return Promise.resolve()

package/src/sender/tcp/tcpsender.ts

@@ -74,7 +74,7 @@ export class TCPSender extends OpenConnectionSender {
         const socket = await this.connectionHandle.get()
         await this.sessionNegotiator?.ensurePresence()
 
-        socket.write(JSON.stringify(message))
+        socket.write(this.serializeOutboundEnvelope(message))
     }
 
     public sendCommand(command: Command<CommandMethods>): Promise<unknown> {
@@ -86,7 +86,7 @@ export class TCPSender extends OpenConnectionSender {
             const socket = await this.connectionHandle.get()
             await this.sessionNegotiator?.ensurePresence(command.uri)
 
-            socket.write(JSON.stringify(command))
+            socket.write(this.serializeOutboundEnvelope(command))
 
             const response = (await envelopeResponsePromise) as CommandResponse<
                 unknown,

package/src/sender/websocket/websocketsender.ts

@@ -56,7 +56,7 @@ export class WebSocketSender extends OpenConnectionSender {
         const webSocket = await this.connectionHandle.get()
         await this.sessionNegotiator?.ensurePresence()
 
-        webSocket.send(JSON.stringify(message))
+        webSocket.send(this.serializeOutboundEnvelope(message))
     }
 
     public sendCommand(command: Command<CommandMethods>): Promise<unknown> {
@@ -67,7 +67,7 @@ export class WebSocketSender extends OpenConnectionSender {
 
             const webSocket = await this.connectionHandle.get()
             await this.sessionNegotiator?.ensurePresence(command.uri)
-            webSocket.send(JSON.stringify(command))
+            webSocket.send(this.serializeOutboundEnvelope(command))
 
             const response = (await envelopeResponsePromise) as CommandResponse<
                 unknown,

package/src/types/billing.ts

@@ -1,9 +1,10 @@
 export type Plan = {
+    id: string
     name: string
     ownerIdentity: string
-    planValue: number
-    currencyCode: string
-    extras: {
+    planValue?: number
+    currencyCode?: string
+    extras: Partial<{
         Cluster: string
         CommandThroughput: string
         DataRetentionPeriod: string
@@ -11,5 +12,5 @@ export type Plan = {
         IsDefaultPlan: string
         MessageThroughput: string
         NotificationThroughput: string
-    }
+    }>
 }