birdcash-chat-sdk-alpha 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# birdcash-chat-sdk
+
+A small TypeScript SDK for sending messages through the chat API. It wraps the
+`/v1/chat/message/:msgID/reply` and `/v1/upload/*` endpoints so you can send
+text, images, files, miniapp cards, web-link previews, typing status, and
+streaming (typewriter) responses.
+
+## Install
+
+```bash
+npm install birdcash-chat-sdk-alpha
+```
+
+## Quick start
+
+```ts
+import { ChatClient } from 'birdcash-chat-sdk-alpha'
+
+const chat = new ChatClient({
+  token: '<bearer-token>',
+  // baseUrl: 'https://your-chat-api',   // optional, defaults to the hosted API
+  // logger: console,                    // optional, omit for silence
+})
+
+// …or exchange OAuth client credentials for a token automatically:
+const chat2 = await ChatClient.fromCredentials({ clientId, clientSecret })
+
+// Send text (string = one element; array = one request, one element per item)
+await chat.sendMessage(msgID, 'Hello there!')
+await chat.sendMessage(msgID, ['First line', 'Second line'])
+```
+
+## Options
+
+| Option    | Type             | Default          | Description                                  |
+| --------- | ---------------- | ---------------- | -------------------------------------------- |
+| `token`   | `string`         | — (required)     | Bearer token sent with every request.        |
+| `baseUrl` | `string`         | hosted endpoint  | Base URL of the chat API.                    |
+| `logger`  | `Logger`         | `undefined`      | Pass `console` to log; omit for no output.   |
+| `fetch`   | `typeof fetch`   | global `fetch`   | Custom fetch (Node < 18, tests, etc.).       |
+
+## Sending messages
+
+```ts
+// Images: upload first, then send by upload_id
+const { upload_id } = await chat.uploadImage(bytes, 'photo.png', 'image/png')
+await chat.sendImageMessage(msgID, [upload_id])
+
+// Files
+const file = await chat.uploadFile(bytes, 'report.pdf', 'application/pdf')
+await chat.sendFileMessage(msgID, [file.upload_id])
+
+// Sound (uploaded via uploadFile; duration in seconds)
+const audio = await chat.uploadFile(bytes, 'clip.m4a', 'audio/m4a')
+await chat.sendSoundMessage(msgID, audio.upload_id, 12)
+
+// Typing indicator (best effort — never throws)
+await chat.sendTypingStatus(msgID, true)
+
+// Miniapp card
+await chat.sendMiniAppMessage(msgID, {
+  appID: 'app123',
+  title: 'Open the app',
+  path: '/home',
+  imageURL: 'https://…/cover.png',
+})
+
+// Web link preview
+await chat.sendWebLinkMessage(msgID, 'https://example.com')
+```
+
+## Streaming (typewriter effect)
+
+```ts
+// High-level: chunk the text and stream it for you (POST first, PATCH rest)
+await chat.streamMessage(msgID, 'A long streamed reply…')
+
+// Low-level: drive the chunks yourself
+await chat.sendStreamingChunk(msgID, ['Hel'], false, true)
+await chat.sendStreamingChunk(msgID, ['Hel', 'lo'], true, false)
+```
+
+## OAuth
+
+If you don't already have a bearer token, exchange client credentials for one:
+
+```ts
+import { getAccessToken } from 'birdcash-chat-sdk-alpha'
+
+const token = await getAccessToken({
+  clientId,
+  clientSecret,
+  scope: 'chat:write uploads:write', // default
+})
+// token.access_token, token.expires_in, …
+```
+
+## Lower-level exports
+
+The element builders and helpers are also exported if you want to assemble
+requests yourself:
+
+```ts
+import { ElemType, textElem, imageElem, splitIntoChunks, toBase64 } from 'birdcash-chat-sdk-alpha'
+```

package/dist/main.cjs.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const e="https://chat-api2-3rnt.onrender.com",t="web_link";async function s(t){var s,n,r;const{clientId:o,clientSecret:i}=t;if(!o||!i)throw new Error("getAccessToken: clientId and clientSecret are required");const a=(null!==(s=t.baseUrl)&&void 0!==s?s:e).replace(/\/$/,""),l=null!==(n=t.scope)&&void 0!==n?n:"chat:write uploads:write",u=null!==(r=t.fetch)&&void 0!==r?r:"undefined"!=typeof fetch?fetch.bind(globalThis):void 0;if(!u)throw new Error("getAccessToken: no fetch implementation available; pass `fetch` in options");const p=await u(`${a}/v1/oauth/token`,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"client_credentials",client_id:o,client_secret:i,scope:l})});if(!p.ok)throw new Error(`Token request failed: ${p.status} ${p.statusText}`);return await p.json()}var n;function r(e){return{elemType:exports.ElemType.Text,priority:0,textElem:{text:e.trim()}}}function o(e){return{elemType:exports.ElemType.Image,priority:0,imageElem:{upload_ids:e}}}function i(e){return{elemType:exports.ElemType.File,priority:0,fileElem:{upload_ids:e}}}function a(e,t=0){return{elemType:exports.ElemType.Sound,priority:0,soundElem:{uploadID:e,duration:t}}}function l(e){return{elemType:exports.ElemType.Custom,priority:0,customElem:{data:e}}}function u(e){return{elemType:exports.ElemType.MiniApp,priority:0,miniAppElem:e}}function p(e){const t=new Uint8Array(e.byteLength);return t.set(e),t}function c(e){const t=(new TextEncoder).encode(e);let s="";for(const e of t)s+=String.fromCharCode(e);return btoa(s)}function d(e,t=10){if(e.length<=t)return[e];const s=[];let n="";for(const r of e.split(" "))n.length+r.length+1>t&&n.length>0?(s.push(n.trim()+" "),n=r):n+=(n?" ":"")+r;return n&&s.push(n.trim()),s.length>0?s:[e]}exports.ElemType=void 0,(n=exports.ElemType||(exports.ElemType={}))[n.None=0]="None",n[n.Text=1]="Text",n[n.Image=2]="Image",n[n.Sound=3]="Sound",n[n.Video=4]="Video",n[n.File=5]="File",n[n.Sticker=6]="Sticker",n[n.GroupTips=7]="GroupTips",n[n.Merger=8]="Merger",n[n.Custom=9]="Custom",n[n.Location=10]="Location",n[n.GroupAnnouncement=11]="GroupAnnouncement",n[n.Quote=12]="Quote",n[n.InputStatus=14]="InputStatus",n[n.TypingStatus=15]="TypingStatus",n[n.MiniApp=16]="MiniApp",n[n.Order=17]="Order",n[n.Transfer=18]="Transfer";class h{constructor(t){var s,n;if(!(null==t?void 0:t.token))throw new Error("ChatClient: token is required");this.token=t.token,this.baseUrl=(null!==(s=t.baseUrl)&&void 0!==s?s:e).replace(/\/$/,""),this.logger=t.logger;const r=null!==(n=t.fetch)&&void 0!==n?n:"undefined"!=typeof fetch?fetch:void 0;if(!r)throw new Error("ChatClient: no fetch implementation available; pass `fetch` in options");this.fetchImpl=r.bind(globalThis)}static async fromCredentials(e){const{access_token:t}=await s({clientId:e.clientId,clientSecret:e.clientSecret,scope:e.scope,baseUrl:e.baseUrl,fetch:e.fetch});return new h({token:t,baseUrl:e.baseUrl,logger:e.logger,fetch:e.fetch})}get authHeaders(){return{"Content-Type":"application/json",Authorization:`Bearer ${this.token}`}}replyUrl(e){return`${this.baseUrl}/v1/chat/message/${e}/reply`}async postElements(e,t,s="POST"){return await this.fetchImpl(this.replyUrl(e),{method:s,headers:this.authHeaders,body:JSON.stringify(t)})}async uploadImage(e,t,s="image/png"){var n;const r=new FormData;r.append("file",new Blob([p(e)],{type:s}),t);const o=await this.fetchImpl(`${this.baseUrl}/v1/upload/image`,{method:"POST",headers:{Authorization:`Bearer ${this.token}`},body:r}),i=await o.json();if(!o.ok)throw new Error(`uploadImage failed: ${o.status} ${JSON.stringify(i)}`);if(!i.upload_id)throw new Error(`uploadImage: missing upload_id: ${JSON.stringify(i)}`);return{upload_id:i.upload_id,url:null!==(n=i.url)&&void 0!==n?n:""}}async uploadFile(e,t,s="application/octet-stream"){var n;const r=new FormData;r.append("file",new Blob([p(e)],{type:s}),t);const o=await this.fetchImpl(`${this.baseUrl}/v1/upload/file`,{method:"POST",headers:{Authorization:`Bearer ${this.token}`},body:r}),i=await o.json();if(!o.ok)throw new Error(`uploadFile failed: ${o.status} ${JSON.stringify(i)}`);if(!i.upload_id)throw new Error(`uploadFile: missing upload_id: ${JSON.stringify(i)}`);return{upload_id:i.upload_id,url:null!==(n=i.url)&&void 0!==n?n:""}}async sendMessage(e,t){var s;const n=Array.isArray(t)?t.map((e=>e.trim())).filter(Boolean).map(r):[r(t)];if(0===n.length)return;const o=await this.postElements(e,n),i=await o.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] message sent",{status:o.status,elements:n.length}),!o.ok)throw new Error(`sendMessage failed: ${o.status} ${i}`)}async sendImageMessage(e,t){var s;if(!(null==t?void 0:t.length))return;const n=await this.postElements(e,[o(t)]),r=await n.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] image message sent",{status:n.status}),!n.ok)throw new Error(`sendImageMessage failed: ${n.status} ${r}`)}async sendFileMessage(e,t){var s;if(!(null==t?void 0:t.length))return;const n=await this.postElements(e,[i(t)]),r=await n.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] file message sent",{status:n.status}),!n.ok)throw new Error(`sendFileMessage failed: ${n.status} ${r}`)}async sendSoundMessage(e,t,s=0){var n;if(!(null==t?void 0:t.trim()))return;const r=await this.postElements(e,[a(t,s)]),o=await r.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] sound message sent",{status:r.status}),!r.ok)throw new Error(`sendSoundMessage failed: ${r.status} ${o.slice(0,500)}`)}async sendTypingStatus(e,t){var s,n;const r={businessID:"user_typing_status",typingStatus:t?1:0,version:1,userAction:14,actionParam:t?"EIMAMSG_InputStatus_Ing":"EIMAMSG_InputStatus_End"};try{await this.postElements(e,[l(c(JSON.stringify(r)))])}catch(e){null===(s=this.logger)||void 0===s||s.error("[chat-sdk] typing status failed",null!==(n=null==e?void 0:e.message)&&void 0!==n?n:String(e))}}async sendStreamingChunk(e,t,s,n){const r={businessID:"chatbotPlugin",src:0,chunks:t,isFinished:s,TMessageCell_Name:"ChatbotMessageCell_Minimalist",TMessageCell_Data_Name:"ChatbotMessageCellData"},o={msgID:e,...l(c(JSON.stringify(r)))},i=await this.postElements(e,[o],n?"POST":"PATCH");if(!i.ok)throw new Error(`sendStreamingChunk failed: ${i.statusText}`);await i.text()}async sendMiniAppMessage(e,t){var s;const n=await this.postElements(e,[u(t)]),r=await n.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] miniapp card sent",{status:n.status}),!n.ok)throw new Error(`sendMiniAppMessage failed: ${n.status} ${r}`)}async sendWebLinkMessage(e,s){var n;const r={businessID:t,url:s},o=await this.postElements(e,[l(c(JSON.stringify(r)))]),i=await o.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] web link sent",{status:o.status}),!o.ok)throw new Error(`sendWebLinkMessage failed: ${o.status} ${i.slice(0,500)}`)}async streamMessage(e,t,s=10){const n=d(t,s),r=[];for(let t=0;t<n.length;t++)r.push(n[t]),await this.sendStreamingChunk(e,r,t===n.length-1,0===t)}}h.ElemType=exports.ElemType,exports.ChatClient=h,exports.DEFAULT_BASE_URL=e,exports.WEB_LINK_BUSINESS_ID=t,exports.arrayBufferToBase64=function(e){let t="";const s=new Uint8Array(e),n=s.byteLength;for(let e=0;e<n;e++)t+=String.fromCharCode(s[e]);return btoa(t)},exports.base64ToArrayBuffer=function(e){const t=atob(e),s=t.length,n=new Uint8Array(s);for(let e=0;e<s;e++)n[e]=t.charCodeAt(e);return n.buffer},exports.customElem=l,exports.fileElem=i,exports.getAccessToken=s,exports.imageElem=o,exports.miniAppElem=u,exports.soundElem=a,exports.splitIntoChunks=d,exports.textElem=r,exports.toBase64=c;
+//# sourceMappingURL=main.cjs.js.map

package/dist/main.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/main.esm.js

@@ -0,0 +1,2 @@
+const t="https://chat-api2-3rnt.onrender.com",e="web_link";async function n(e){var n,s,i;const{clientId:a,clientSecret:r}=e;if(!a||!r)throw new Error("getAccessToken: clientId and clientSecret are required");const o=(null!==(n=e.baseUrl)&&void 0!==n?n:t).replace(/\/$/,""),l=null!==(s=e.scope)&&void 0!==s?s:"chat:write uploads:write",u=null!==(i=e.fetch)&&void 0!==i?i:"undefined"!=typeof fetch?fetch.bind(globalThis):void 0;if(!u)throw new Error("getAccessToken: no fetch implementation available; pass `fetch` in options");const c=await u(`${o}/v1/oauth/token`,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"client_credentials",client_id:a,client_secret:r,scope:l})});if(!c.ok)throw new Error(`Token request failed: ${c.status} ${c.statusText}`);return await c.json()}var s;function i(t){return{elemType:s.Text,priority:0,textElem:{text:t.trim()}}}function a(t){return{elemType:s.Image,priority:0,imageElem:{upload_ids:t}}}function r(t){return{elemType:s.File,priority:0,fileElem:{upload_ids:t}}}function o(t,e=0){return{elemType:s.Sound,priority:0,soundElem:{uploadID:t,duration:e}}}function l(t){return{elemType:s.Custom,priority:0,customElem:{data:t}}}function u(t){return{elemType:s.MiniApp,priority:0,miniAppElem:t}}function c(t){const e=new Uint8Array(t.byteLength);return e.set(t),e}function d(t){let e="";const n=new Uint8Array(t),s=n.byteLength;for(let t=0;t<s;t++)e+=String.fromCharCode(n[t]);return btoa(e)}function h(t){const e=atob(t),n=e.length,s=new Uint8Array(n);for(let t=0;t<n;t++)s[t]=e.charCodeAt(t);return s.buffer}function p(t){const e=(new TextEncoder).encode(t);let n="";for(const t of e)n+=String.fromCharCode(t);return btoa(n)}function g(t,e=10){if(t.length<=e)return[t];const n=[];let s="";for(const i of t.split(" "))s.length+i.length+1>e&&s.length>0?(n.push(s.trim()+" "),s=i):s+=(s?" ":"")+i;return s&&n.push(s.trim()),n.length>0?n:[t]}!function(t){t[t.None=0]="None",t[t.Text=1]="Text",t[t.Image=2]="Image",t[t.Sound=3]="Sound",t[t.Video=4]="Video",t[t.File=5]="File",t[t.Sticker=6]="Sticker",t[t.GroupTips=7]="GroupTips",t[t.Merger=8]="Merger",t[t.Custom=9]="Custom",t[t.Location=10]="Location",t[t.GroupAnnouncement=11]="GroupAnnouncement",t[t.Quote=12]="Quote",t[t.InputStatus=14]="InputStatus",t[t.TypingStatus=15]="TypingStatus",t[t.MiniApp=16]="MiniApp",t[t.Order=17]="Order",t[t.Transfer=18]="Transfer"}(s||(s={}));class f{constructor(e){var n,s;if(!(null==e?void 0:e.token))throw new Error("ChatClient: token is required");this.token=e.token,this.baseUrl=(null!==(n=e.baseUrl)&&void 0!==n?n:t).replace(/\/$/,""),this.logger=e.logger;const i=null!==(s=e.fetch)&&void 0!==s?s:"undefined"!=typeof fetch?fetch:void 0;if(!i)throw new Error("ChatClient: no fetch implementation available; pass `fetch` in options");this.fetchImpl=i.bind(globalThis)}static async fromCredentials(t){const{access_token:e}=await n({clientId:t.clientId,clientSecret:t.clientSecret,scope:t.scope,baseUrl:t.baseUrl,fetch:t.fetch});return new f({token:e,baseUrl:t.baseUrl,logger:t.logger,fetch:t.fetch})}get authHeaders(){return{"Content-Type":"application/json",Authorization:`Bearer ${this.token}`}}replyUrl(t){return`${this.baseUrl}/v1/chat/message/${t}/reply`}async postElements(t,e,n="POST"){return await this.fetchImpl(this.replyUrl(t),{method:n,headers:this.authHeaders,body:JSON.stringify(e)})}async uploadImage(t,e,n="image/png"){var s;const i=new FormData;i.append("file",new Blob([c(t)],{type:n}),e);const a=await this.fetchImpl(`${this.baseUrl}/v1/upload/image`,{method:"POST",headers:{Authorization:`Bearer ${this.token}`},body:i}),r=await a.json();if(!a.ok)throw new Error(`uploadImage failed: ${a.status} ${JSON.stringify(r)}`);if(!r.upload_id)throw new Error(`uploadImage: missing upload_id: ${JSON.stringify(r)}`);return{upload_id:r.upload_id,url:null!==(s=r.url)&&void 0!==s?s:""}}async uploadFile(t,e,n="application/octet-stream"){var s;const i=new FormData;i.append("file",new Blob([c(t)],{type:n}),e);const a=await this.fetchImpl(`${this.baseUrl}/v1/upload/file`,{method:"POST",headers:{Authorization:`Bearer ${this.token}`},body:i}),r=await a.json();if(!a.ok)throw new Error(`uploadFile failed: ${a.status} ${JSON.stringify(r)}`);if(!r.upload_id)throw new Error(`uploadFile: missing upload_id: ${JSON.stringify(r)}`);return{upload_id:r.upload_id,url:null!==(s=r.url)&&void 0!==s?s:""}}async sendMessage(t,e){var n;const s=Array.isArray(e)?e.map((t=>t.trim())).filter(Boolean).map(i):[i(e)];if(0===s.length)return;const a=await this.postElements(t,s),r=await a.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] message sent",{status:a.status,elements:s.length}),!a.ok)throw new Error(`sendMessage failed: ${a.status} ${r}`)}async sendImageMessage(t,e){var n;if(!(null==e?void 0:e.length))return;const s=await this.postElements(t,[a(e)]),i=await s.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] image message sent",{status:s.status}),!s.ok)throw new Error(`sendImageMessage failed: ${s.status} ${i}`)}async sendFileMessage(t,e){var n;if(!(null==e?void 0:e.length))return;const s=await this.postElements(t,[r(e)]),i=await s.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] file message sent",{status:s.status}),!s.ok)throw new Error(`sendFileMessage failed: ${s.status} ${i}`)}async sendSoundMessage(t,e,n=0){var s;if(!(null==e?void 0:e.trim()))return;const i=await this.postElements(t,[o(e,n)]),a=await i.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] sound message sent",{status:i.status}),!i.ok)throw new Error(`sendSoundMessage failed: ${i.status} ${a.slice(0,500)}`)}async sendTypingStatus(t,e){var n,s;const i={businessID:"user_typing_status",typingStatus:e?1:0,version:1,userAction:14,actionParam:e?"EIMAMSG_InputStatus_Ing":"EIMAMSG_InputStatus_End"};try{await this.postElements(t,[l(p(JSON.stringify(i)))])}catch(t){null===(n=this.logger)||void 0===n||n.error("[chat-sdk] typing status failed",null!==(s=null==t?void 0:t.message)&&void 0!==s?s:String(t))}}async sendStreamingChunk(t,e,n,s){const i={businessID:"chatbotPlugin",src:0,chunks:e,isFinished:n,TMessageCell_Name:"ChatbotMessageCell_Minimalist",TMessageCell_Data_Name:"ChatbotMessageCellData"},a={msgID:t,...l(p(JSON.stringify(i)))},r=await this.postElements(t,[a],s?"POST":"PATCH");if(!r.ok)throw new Error(`sendStreamingChunk failed: ${r.statusText}`);await r.text()}async sendMiniAppMessage(t,e){var n;const s=await this.postElements(t,[u(e)]),i=await s.text();if(null===(n=this.logger)||void 0===n||n.log("[chat-sdk] miniapp card sent",{status:s.status}),!s.ok)throw new Error(`sendMiniAppMessage failed: ${s.status} ${i}`)}async sendWebLinkMessage(t,n){var s;const i={businessID:e,url:n},a=await this.postElements(t,[l(p(JSON.stringify(i)))]),r=await a.text();if(null===(s=this.logger)||void 0===s||s.log("[chat-sdk] web link sent",{status:a.status}),!a.ok)throw new Error(`sendWebLinkMessage failed: ${a.status} ${r.slice(0,500)}`)}async streamMessage(t,e,n=10){const s=g(e,n),i=[];for(let e=0;e<s.length;e++)i.push(s[e]),await this.sendStreamingChunk(t,i,e===s.length-1,0===e)}}f.ElemType=s;export{f as ChatClient,t as DEFAULT_BASE_URL,s as ElemType,e as WEB_LINK_BUSINESS_ID,d as arrayBufferToBase64,h as base64ToArrayBuffer,l as customElem,r as fileElem,n as getAccessToken,a as imageElem,u as miniAppElem,o as soundElem,g as splitIntoChunks,i as textElem,p as toBase64};
+//# sourceMappingURL=main.esm.js.map

package/dist/main.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/types/auth.d.ts

@@ -0,0 +1,16 @@
+import { TokenResponse } from './types';
+export interface GetAccessTokenOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Space-separated scopes. Defaults to 'chat:write uploads:write'. */
+    scope?: string;
+    /** Base URL of the chat API. Defaults to the hosted endpoint. */
+    baseUrl?: string;
+    /** Optional custom fetch implementation. */
+    fetch?: typeof fetch;
+}
+/**
+ * Exchange OAuth client credentials for an access token
+ * (POST /v1/oauth/token, grant_type=client_credentials).
+ */
+export declare function getAccessToken(options: GetAccessTokenOptions): Promise<TokenResponse>;

package/dist/types/client.d.ts

@@ -0,0 +1,69 @@
+import { ChatClientOptions, ElemType, Logger, MiniAppElem, UploadV1FileResponse, UploadV1ImageResponse } from "./types";
+/**
+ * ChatClient wraps the chat API reply/upload endpoints. Construct once with a
+ * token (and optionally a baseUrl / logger), then call the message helpers.
+ *
+ * ```ts
+ * const chat = new ChatClient({ token })
+ * await chat.sendMessage(msgID, 'Hello!')
+ * ```
+ */
+export declare class ChatClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly logger?;
+    private readonly fetchImpl;
+    constructor(options: ChatClientOptions);
+    /**
+     * Build a ChatClient by first exchanging OAuth client credentials for a token.
+     *
+     * ```ts
+     * const chat = await ChatClient.fromCredentials({ clientId, clientSecret })
+     * ```
+     */
+    static fromCredentials(options: {
+        clientId: string;
+        clientSecret: string;
+        scope?: string;
+        baseUrl?: string;
+        logger?: Logger;
+        fetch?: typeof fetch;
+    }): Promise<ChatClient>;
+    private get authHeaders();
+    private replyUrl;
+    /** POST an array of message elements to a message's reply endpoint. */
+    private postElements;
+    /** Upload a binary image (POST /v1/upload/image) and return { upload_id, url }. */
+    uploadImage(file: Uint8Array, filename: string, mimeType?: string): Promise<UploadV1ImageResponse>;
+    /** Upload a binary file (POST /v1/upload/file) and return { upload_id, url }. */
+    uploadFile(file: Uint8Array, filename: string, mimeType?: string): Promise<UploadV1FileResponse>;
+    /**
+     * Send one or more text messages as a reply. A string sends a single element;
+     * an array sends one request with multiple elements (one per line/paragraph).
+     */
+    sendMessage(msgID: string, message: string | string[]): Promise<void>;
+    /** Send an image message by upload_id(s) (use uploadImage first). */
+    sendImageMessage(msgID: string, uploadIDs: string[]): Promise<void>;
+    /** Send a file message by upload_id(s) (use uploadFile first). */
+    sendFileMessage(msgID: string, uploadIDs: string[]): Promise<void>;
+    /** Send a sound message by uploadID (duration in seconds). */
+    sendSoundMessage(msgID: string, uploadID: string, durationSec?: number): Promise<void>;
+    /** Send typing status (best effort — never throws). */
+    sendTypingStatus(msgID: string, isTyping: boolean): Promise<void>;
+    /**
+     * Send a streaming chunk (chatbotPlugin format). Use POST for the first chunk
+     * and PATCH for the rest (`isFirstChunk` controls the method).
+     */
+    sendStreamingChunk(msgID: string, chunks: string[], isFinished: boolean, isFirstChunk: boolean): Promise<void>;
+    /** Send a miniapp card message. */
+    sendMiniAppMessage(msgID: string, miniApp: MiniAppElem): Promise<void>;
+    /** Send a web link preview custom message (matches iOS `webLinkPreviewMessage`). */
+    sendWebLinkMessage(msgID: string, url: string): Promise<void>;
+    /**
+     * Stream a message in chunks for a typewriter effect. Splits `text`, then
+     * sends each chunk via sendStreamingChunk (POST first, PATCH after).
+     */
+    streamMessage(msgID: string, text: string, minChunkSize?: number): Promise<void>;
+    /** Re-export of the element types for convenience. */
+    static ElemType: typeof ElemType;
+}

package/dist/types/constants.d.ts

@@ -0,0 +1,4 @@
+/** Default hosted chat API endpoint. Override via ChatClient `baseUrl`. */
+export declare const DEFAULT_BASE_URL = "https://chat-api2-3rnt.onrender.com";
+/** Must match iOS `WebLinkMessageCellData.businessID`. */
+export declare const WEB_LINK_BUSINESS_ID = "web_link";

package/dist/types/elements.d.ts

@@ -0,0 +1,13 @@
+import { MessageElem, MiniAppElem } from './types';
+/** Single text message element for the chat API body. */
+export declare function textElem(text: string): MessageElem;
+/** Single image message element (requires upload_ids from uploadImage). */
+export declare function imageElem(uploadIDs: string[]): MessageElem;
+/** Single file message element (requires upload_ids from uploadFile). */
+export declare function fileElem(uploadIDs: string[]): MessageElem;
+/** Single sound message element (requires an uploadID; duration in seconds). */
+export declare function soundElem(uploadID: string, durationSec?: number): MessageElem;
+/** Single custom message element carrying a base64-encoded payload. */
+export declare function customElem(dataBase64: string): MessageElem;
+/** Single miniapp card message element. */
+export declare function miniAppElem(miniApp: MiniAppElem): MessageElem;

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export { ChatClient } from './client';
+export { getAccessToken } from './auth';
+export type { GetAccessTokenOptions } from './auth';
+export * from './types';
+export * from './elements';
+export * from './constants';
+export { toBase64, splitIntoChunks, arrayBufferToBase64, base64ToArrayBuffer, } from './utils';

package/dist/types/types.d.ts

@@ -0,0 +1,82 @@
+/** Mirrors datastore/database/message.go ElemType constants. */
+export declare enum ElemType {
+    None = 0,
+    Text = 1,
+    Image = 2,
+    Sound = 3,
+    Video = 4,
+    File = 5,
+    Sticker = 6,
+    GroupTips = 7,
+    Merger = 8,
+    Custom = 9,
+    Location = 10,
+    GroupAnnouncement = 11,
+    Quote = 12,
+    InputStatus = 14,
+    TypingStatus = 15,
+    MiniApp = 16,
+    Order = 17,
+    Transfer = 18
+}
+export type UploadV1ImageResponse = {
+    upload_id: string;
+    url: string;
+};
+export type UploadV1FileResponse = {
+    upload_id: string;
+    url: string;
+};
+export type MiniAppElem = {
+    appID: string;
+    title: string;
+    path: string;
+    imageURL: string;
+};
+export type SoundElem = {
+    uploadID: string;
+    duration: number;
+};
+/** OAuth client_credentials token response (POST /v1/oauth/token). */
+export type TokenResponse = {
+    access_token: string;
+    expires_in: number;
+    refresh_token: string;
+    scope: string;
+    token_type: string;
+};
+/** A single message element as accepted by the chat API reply endpoint. */
+export type MessageElem = {
+    elemType: ElemType;
+    priority: number;
+    msgID?: string;
+    textElem?: {
+        text: string;
+    };
+    imageElem?: {
+        upload_ids: string[];
+    };
+    fileElem?: {
+        upload_ids: string[];
+    };
+    soundElem?: SoundElem;
+    customElem?: {
+        data: string;
+    };
+    miniAppElem?: MiniAppElem;
+};
+/** Minimal logger interface — pass `console` to enable logging, omit for silence. */
+export interface Logger {
+    log: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+}
+export interface ChatClientOptions {
+    /** Bearer token used to authenticate every request. */
+    token: string;
+    /** Base URL of the chat API. Defaults to the hosted endpoint. */
+    baseUrl?: string;
+    /** Optional logger. Omit (or pass undefined) for no logging. */
+    logger?: Logger;
+    /** Optional custom fetch implementation (e.g. for Node < 18 or testing). */
+    fetch?: typeof fetch;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,10 @@
+/** Copy bytes into an ArrayBuffer-backed view for Blob / FormData APIs. */
+export declare function bytesToBlobPart(bytes: Uint8Array): BlobPart;
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+export declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+/** UTF-8 safe base64 encoding (browser/Workers style). */
+export declare function toBase64(str: string): string;
+/**
+ * Splits text into chunks for a streaming effect (word boundaries, min chunk size).
+ */
+export declare function splitIntoChunks(text: string, minChunkSize?: number): string[];

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "birdcash-chat-sdk-alpha",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for sending messages through the chat API (text, images, files, miniapp cards, streaming).",
+  "main": "dist/main.cjs.js",
+  "module": "dist/main.esm.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "test": "jest",
+    "build": "rm -rf dist && rollup -c",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "andy",
+  "license": "ISC",
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^26.0.1",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "rollup": "^2.79.1",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "tslib": "^2.7.0"
+  }
+}