tiktok-business-messaging 0.0.1

package/README.md

@@ -0,0 +1,41 @@
+# TikTok Business Messaging SDK
+
+Lightweight **Node.js/TypeScript** wrapper for the TikTok Business Messaging API.
+
+> Unofficial SDK. Use at your own risk.
+
+## Features
+
+- Simple API client for messaging endpoints
+- Built-in auth header handling
+- Typed request/response models (TypeScript)
+- Webhook signature verification helper
+
+## Installation
+
+```bash
+npm install tiktok-business
+# or
+pnpm add tiktok-business
+```
+
+## Quick Start
+
+```ts
+import { TikTokBusiness } from "tiktok-business-messaging-sdk";
+
+const client = new TikTokBusiness({
+    appId: process.env.TT_APP_ID!,
+    appSecret: process.env.TT_APP_SECRET!,
+    accessToken: process.env.TT_ACCESS_TOKEN!,
+});
+
+await client.messages.sendText({
+    conversationId: "conv_123",
+    text: "Hello from TikTok SDK 👋",
+});
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,335 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TikTokApiError: () => TikTokApiError,
+  TikTokBusiness: () => TikTokBusiness
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var TIKTOK_API_BASE_URL = "https://business-api.tiktok.com/open_api/v1.3";
+var TIKTOK_AUTH_BASE_URL = `${TIKTOK_API_BASE_URL}/tt_user/oauth2`;
+var TIKTOK_ERROR_MESSAGES = {
+  [40001 /* NO_PERMISSION */]: "No permission to perform the related operation. Ensure you have the necessary scopes.",
+  [40002 /* PARAMETER_ERROR */]: "Parameter error. Check missing fields or incorrect formats in your request.",
+  [40007 /* OBJECT_NOT_FOUND */]: "The operation or object does not exist. Check your IDs or URLs.",
+  [40100 /* RATE_LIMIT_EXCEEDED */]: "Requests made too frequently. You are being throttled.",
+  [40105 /* INVALID_ACCESS_TOKEN */]: "Invalid or incorrect access token. Please refresh or re-authorize.",
+  [40908 /* UNSUPPORTED_FILE_TYPE */]: "The file type is unsupported. Refer to documentation for allowed formats.",
+  [40064 /* MESSAGE_BLOCKED */]: "The message is blocked due to TikTok direct message rules.",
+  [51065 /* SYSTEM_ERROR */]: "TikTok internal system error. Please retry the request.",
+  [40131 /* CODE_EXPIRED */]: "The authorization code has expired. Please re-authorize to get a new code."
+};
+
+// src/error.ts
+var TikTokApiError = class _TikTokApiError extends Error {
+  constructor(code, requestId) {
+    const friendlyMessage = TIKTOK_ERROR_MESSAGES[code] || "An unknown TikTok API error occurred.";
+    super(`TikTok API Error [${code}]: ${friendlyMessage}`);
+    this.code = code;
+    this.requestId = requestId;
+    this.name = "TikTokApiError";
+    this.message = friendlyMessage;
+    Object.setPrototypeOf(this, _TikTokApiError.prototype);
+  }
+  message;
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = config.baseUrl ?? "https://business-api.tiktok.com/open_api/v1.3";
+  }
+  baseUrl;
+  get(path, params, opts) {
+    return this.request({ method: "GET", path, params, opts });
+  }
+  post(path, body, opts) {
+    return this.request({ method: "POST", path, body, opts });
+  }
+  put(path, body, opts) {
+    return this.request({ method: "PUT", path, body, opts });
+  }
+  patch(path, body, opts) {
+    return this.request({ method: "PATCH", path, body, opts });
+  }
+  delete(path, params, opts) {
+    return this.request({ method: "DELETE", path, params, opts });
+  }
+  upload(path, form, opts) {
+    return this.request({ method: "POST", path, form, opts });
+  }
+  async request({
+    method,
+    path,
+    params,
+    body,
+    form,
+    opts
+  }) {
+    const res = await fetch(
+      this.buildUrl(path, params),
+      this.buildInit(method, body, opts, form)
+    );
+    return this.parseResponse(res);
+  }
+  buildUrl(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      Object.entries(params).forEach(([k, v]) => {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      });
+    }
+    return url.toString();
+  }
+  buildInit(method, body, opts, form) {
+    const headers = {
+      "Access-Token": opts.accessToken
+    };
+    if (!form) {
+      headers["Content-Type"] = "application/json";
+    }
+    return {
+      method,
+      signal: AbortSignal.timeout(
+        opts.timeout ?? this.config.timeout ?? 1e4
+      ),
+      headers,
+      ...form ? { body: form } : body !== void 0 ? { body: JSON.stringify(body) } : {}
+    };
+  }
+  async parseResponse(res) {
+    console.debug(`[HttpClient] Parsing response for URL: ${res.url}`);
+    console.debug(
+      `[HttpClient] Response status: ${res.status} ${res.statusText}`
+    );
+    console.debug(`[HttpClient] Response data:`, await res.clone().text());
+    const json = await res.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/services/auth.ts
+var Auth = class {
+  constructor(config) {
+    this.config = config;
+  }
+  getTokens(authCode) {
+    return this.post("/token/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      grant_type: "authorization_code",
+      auth_code: decodeURIComponent(authCode),
+      redirect_uri: this.config.redirectUri
+    });
+  }
+  refreshTokens(refreshToken) {
+    return this.post("/refresh_token/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken
+    });
+  }
+  revokeToken(accessToken) {
+    return this.post("/token/revoke/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      token: accessToken
+    });
+  }
+  // for tt_users
+  getAuthorizationUrl(state) {
+    const params = new URLSearchParams({
+      client_key: this.config.clientKey,
+      response_type: "code",
+      scope: (this.config.scopes ?? []).join(","),
+      redirect_uri: this.config.redirectUri ?? "",
+      ...state && { state }
+    });
+    return `https://www.tiktok.com/v2/auth/authorize/?${params.toString()}`;
+  }
+  async post(path, body) {
+    const response = await fetch(`${TIKTOK_AUTH_BASE_URL}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      throw new TikTokApiError(response.status, response.statusText);
+    }
+    const json = await response.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/services/media.ts
+var MediaService = class {
+  constructor(http) {
+    this.http = http;
+  }
+  upload(params, opts) {
+    const form = new FormData();
+    form.append("business_id", params.business_id);
+    form.append("file", params.file);
+    form.append("media_type", params.media_type);
+    return this.http.upload("/business/message/media/upload/", form, opts);
+  }
+};
+
+// src/services/messaging.ts
+var Messaging = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all conversations for a business account
+   */
+  listConversations(params, opts) {
+    console.debug("[Messaging] listConversations called", { params });
+    return this.http.get("/business/message/conversation/list/", params, opts).then((response) => {
+      console.debug("[Messaging] listConversations succeeded");
+      return response;
+    }).catch((error) => {
+      console.error("[Messaging] listConversations failed", error);
+      throw error;
+    });
+  }
+  /**
+   * Get messages in a specific conversation
+   */
+  listMessages(params, opts) {
+    console.log("Conversation ID:", encodeURIComponent(params.conversation_id));
+    return this.http.get(
+      "/business/message/content/list/",
+      {
+        ...params
+      },
+      opts
+    );
+  }
+  /**
+   * Send a text message to a conversation
+   */
+  sendTextMessage(body, opts) {
+    const { ...restBody } = body;
+    return this.http.post(
+      "/business/message/send/",
+      { recipient_type: "CONVERSATION", ...restBody },
+      opts
+    );
+  }
+  /**
+   * Send an image message to a conversation
+   */
+  sendImageMessage(body, opts) {
+    return this.http.post(
+      "/business/message/send/",
+      {
+        ...body
+      },
+      opts
+    );
+  }
+};
+
+// src/services/webhook.ts
+var WebhookService = class {
+  constructor(config) {
+    this.config = config;
+  }
+  create(params) {
+    return this.post("/business/webhook/update/", {
+      event_type: params.event_type,
+      callback_url: params.callback_url
+    });
+  }
+  get(params) {
+    return this.fetch("/business/webhook/list/", params.event_type);
+  }
+  delete(params) {
+    return this.post("/business/webhook/delete/", {
+      event_type: params.event_type
+    });
+  }
+  async post(path, body) {
+    console.log("called post");
+    const response = await fetch(`${TIKTOK_API_BASE_URL}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        app_id: this.config.clientKey,
+        secret: this.config.clientSecret,
+        ...body
+      })
+    });
+    console.log(response.status, await response.text());
+    return this.parseResponse(response);
+  }
+  async fetch(path, event_type) {
+    const url = new URL(`${TIKTOK_API_BASE_URL}${path}`);
+    url.searchParams.set("app_id", this.config.clientKey);
+    url.searchParams.set("secret", this.config.clientSecret);
+    url.searchParams.set("event_type", event_type);
+    const response = await globalThis.fetch(url.toString());
+    return this.parseResponse(response);
+  }
+  async parseResponse(response) {
+    if (!response.ok) {
+      throw new TikTokApiError(response.status, response.statusText);
+    }
+    const json = await response.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/client.ts
+var TikTokBusiness = class {
+  auth;
+  messaging;
+  media;
+  webhook;
+  constructor(config) {
+    const http = new HttpClient(config);
+    this.auth = new Auth(config);
+    this.messaging = new Messaging(http);
+    this.media = new MediaService(http);
+    this.webhook = new WebhookService(config);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TikTokApiError,
+  TikTokBusiness
+});

package/dist/index.d.cts

@@ -0,0 +1,263 @@
+interface TikTokTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    access_token_expire_in: number;
+    refresh_token_expire_in: number;
+    token_type: string;
+    scope: string;
+    open_id: string;
+}
+interface RefreshTokenResponse {
+    access_token: string;
+    access_token_expire_in: number;
+    refresh_token: string;
+    refresh_token_expire_in: number;
+    token_type: string;
+    scope: string;
+    open_id: string;
+}
+interface RevokeTokenResponse {
+}
+
+interface TikTokConfig {
+    clientKey: string;
+    clientSecret: string;
+    redirectUri?: string;
+    scopes?: string[];
+    baseUrl?: string;
+    timeout?: number;
+}
+
+type MediaType = "IMAGE";
+interface UploadMediaRequest {
+    business_id: string;
+    file: File | Blob;
+    media_type: MediaType;
+}
+interface MediaContent {
+    media_id: string;
+}
+type UploadMediaResponse = MediaContent;
+
+type MessageType = "TEXT" | "SENDER_ACTION";
+type SenderAction = "TYPING" | "MARK_READ";
+type RecipientType = "CONVERSATION";
+type ConversationStatus = "ACTIVE" | "ARCHIVED";
+interface ListMessagesRequest {
+    business_id: string;
+    conversation_id: string;
+}
+interface Message {
+    message_id: string;
+    conversation_id: string;
+    message_type: MessageType;
+    create_time: number;
+    direction: "INBOUND" | "OUTBOUND";
+    status: "SENT" | "DELIVERED" | "READ" | "FAILED";
+    sender: {
+        open_id: string;
+        display_name: string;
+        avatar_url: string;
+    };
+    content: {
+        body: string;
+    };
+}
+interface ListMessagesResponse {
+    messages: Message[];
+    next_cursor: string | null;
+    has_more: boolean;
+    total: number;
+}
+interface TextContent {
+    body: string;
+}
+interface SendTextMessageRequest {
+    conversation_id?: string;
+    business_id: string;
+    recipient: string;
+    message_type: MessageType;
+    recipient_type?: RecipientType;
+    text?: TextContent;
+    sender_action?: SenderAction;
+}
+interface SendTextMessageResponse {
+    message_id: string;
+    create_time: number;
+}
+type ConversationType = "STRANGER" | "SINGLE";
+interface ReferralAd {
+    advertiser_id: string;
+    ad_id: string;
+    timestamp: number;
+    ad_name: string;
+    embed_url: string;
+    message_material_id?: string;
+}
+interface ReferralShortLink {
+    ref: string;
+    prefilled_message: string;
+    prefilled_message_audit_status: "PASS" | "REJECT";
+}
+interface ConversationReferral {
+    ad?: ReferralAd[];
+    short_link?: ReferralShortLink[];
+}
+interface Conversation {
+    conversation_id: string;
+    update_time: number;
+    referral: ConversationReferral;
+}
+interface ListConversationsRequest {
+    business_id: string;
+    cursor?: number;
+    conversation_type: ConversationType;
+    limit?: number;
+}
+interface ListConversationsResponse {
+    conversations: Conversation[];
+    has_more: boolean;
+    cursor: number;
+}
+interface SendImageMessageRequest {
+    business_id: string;
+    recipient_type: RecipientType;
+    message_type: "IMAGE";
+    recipient: string;
+    image: MediaContent;
+}
+interface SendImageMessageResponse {
+    message_id: string;
+    create_time: number;
+}
+
+declare class Auth {
+    private readonly config;
+    constructor(config: TikTokConfig);
+    getTokens(authCode: string): Promise<TikTokTokenResponse>;
+    refreshTokens(refreshToken: string): Promise<RefreshTokenResponse>;
+    revokeToken(accessToken: string): Promise<RevokeTokenResponse>;
+    getAuthorizationUrl(state?: string): string;
+    private post;
+}
+
+interface RequestOptions {
+    accessToken: string;
+    advertiserIds?: string[];
+    timeout?: number;
+}
+
+declare class HttpClient {
+    private config;
+    private baseUrl;
+    constructor(config: TikTokConfig);
+    get<T>(path: string, params: object, opts: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    put<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    patch<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    delete<T>(path: string, params: object, opts: RequestOptions): Promise<T>;
+    upload<T>(path: string, form: FormData, opts: RequestOptions): Promise<T>;
+    private request;
+    private buildUrl;
+    private buildInit;
+    private parseResponse;
+}
+
+declare class MediaService {
+    private readonly http;
+    constructor(http: HttpClient);
+    upload(params: UploadMediaRequest, opts: RequestOptions): Promise<UploadMediaResponse>;
+}
+
+declare class Messaging {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all conversations for a business account
+     */
+    listConversations(params: ListConversationsRequest, opts: RequestOptions): Promise<ListConversationsResponse>;
+    /**
+     * Get messages in a specific conversation
+     */
+    listMessages(params: ListMessagesRequest, opts: RequestOptions): Promise<ListMessagesResponse>;
+    /**
+     * Send a text message to a conversation
+     */
+    sendTextMessage(body: SendTextMessageRequest, opts: RequestOptions): Promise<SendTextMessageResponse>;
+    /**
+     * Send an image message to a conversation
+     */
+    sendImageMessage(body: SendImageMessageRequest, opts: RequestOptions): Promise<SendImageMessageResponse>;
+}
+
+type WebhookEventType = "DIRECT_MESSAGE";
+interface CreateWebhookRequest {
+    callback_url: string;
+    event_type: WebhookEventType;
+}
+interface CreateWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+    callback_url: string;
+}
+interface GetWebhookRequest {
+    event_type: WebhookEventType;
+}
+interface GetWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+    callback_url?: string;
+}
+interface DeleteWebhookRequest {
+    event_type: WebhookEventType;
+}
+interface DeleteWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+}
+
+declare class WebhookService {
+    private readonly config;
+    constructor(config: TikTokConfig);
+    create(params: CreateWebhookRequest): Promise<CreateWebhookResponse>;
+    get(params: GetWebhookRequest): Promise<GetWebhookResponse>;
+    delete(params: DeleteWebhookRequest): Promise<DeleteWebhookResponse>;
+    private post;
+    private fetch;
+    private parseResponse;
+}
+
+declare class TikTokBusiness {
+    readonly auth: Auth;
+    readonly messaging: Messaging;
+    readonly media: MediaService;
+    readonly webhook: WebhookService;
+    constructor(config: TikTokConfig);
+}
+
+/**
+ * TikTok Business API Error Codes
+ */
+declare enum TikTokErrorCode {
+    NO_PERMISSION = 40001,
+    PARAMETER_ERROR = 40002,
+    OBJECT_NOT_FOUND = 40007,
+    RATE_LIMIT_EXCEEDED = 40100,
+    INVALID_ACCESS_TOKEN = 40105,
+    UNSUPPORTED_FILE_TYPE = 40908,
+    MESSAGE_BLOCKED = 40064,
+    SYSTEM_ERROR = 51065,
+    CODE_EXPIRED = 40131
+}
+
+/**
+ * TikTok API Errors
+ */
+declare class TikTokApiError extends Error {
+    readonly code: TikTokErrorCode;
+    readonly requestId?: string | undefined;
+    readonly message: string;
+    constructor(code: TikTokErrorCode, requestId?: string | undefined);
+}
+
+export { type Conversation, type ConversationReferral, type ConversationStatus, type ConversationType, type ListConversationsRequest, type ListConversationsResponse, type ListMessagesRequest, type ListMessagesResponse, type Message, type MessageType, type RecipientType, type ReferralAd, type ReferralShortLink, type RefreshTokenResponse, type RevokeTokenResponse, type SendImageMessageRequest, type SendImageMessageResponse, type SendTextMessageRequest, type SendTextMessageResponse, type SenderAction, type TextContent, TikTokApiError, TikTokBusiness, type TikTokConfig, type TikTokTokenResponse };

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+interface TikTokTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    access_token_expire_in: number;
+    refresh_token_expire_in: number;
+    token_type: string;
+    scope: string;
+    open_id: string;
+}
+interface RefreshTokenResponse {
+    access_token: string;
+    access_token_expire_in: number;
+    refresh_token: string;
+    refresh_token_expire_in: number;
+    token_type: string;
+    scope: string;
+    open_id: string;
+}
+interface RevokeTokenResponse {
+}
+
+interface TikTokConfig {
+    clientKey: string;
+    clientSecret: string;
+    redirectUri?: string;
+    scopes?: string[];
+    baseUrl?: string;
+    timeout?: number;
+}
+
+type MediaType = "IMAGE";
+interface UploadMediaRequest {
+    business_id: string;
+    file: File | Blob;
+    media_type: MediaType;
+}
+interface MediaContent {
+    media_id: string;
+}
+type UploadMediaResponse = MediaContent;
+
+type MessageType = "TEXT" | "SENDER_ACTION";
+type SenderAction = "TYPING" | "MARK_READ";
+type RecipientType = "CONVERSATION";
+type ConversationStatus = "ACTIVE" | "ARCHIVED";
+interface ListMessagesRequest {
+    business_id: string;
+    conversation_id: string;
+}
+interface Message {
+    message_id: string;
+    conversation_id: string;
+    message_type: MessageType;
+    create_time: number;
+    direction: "INBOUND" | "OUTBOUND";
+    status: "SENT" | "DELIVERED" | "READ" | "FAILED";
+    sender: {
+        open_id: string;
+        display_name: string;
+        avatar_url: string;
+    };
+    content: {
+        body: string;
+    };
+}
+interface ListMessagesResponse {
+    messages: Message[];
+    next_cursor: string | null;
+    has_more: boolean;
+    total: number;
+}
+interface TextContent {
+    body: string;
+}
+interface SendTextMessageRequest {
+    conversation_id?: string;
+    business_id: string;
+    recipient: string;
+    message_type: MessageType;
+    recipient_type?: RecipientType;
+    text?: TextContent;
+    sender_action?: SenderAction;
+}
+interface SendTextMessageResponse {
+    message_id: string;
+    create_time: number;
+}
+type ConversationType = "STRANGER" | "SINGLE";
+interface ReferralAd {
+    advertiser_id: string;
+    ad_id: string;
+    timestamp: number;
+    ad_name: string;
+    embed_url: string;
+    message_material_id?: string;
+}
+interface ReferralShortLink {
+    ref: string;
+    prefilled_message: string;
+    prefilled_message_audit_status: "PASS" | "REJECT";
+}
+interface ConversationReferral {
+    ad?: ReferralAd[];
+    short_link?: ReferralShortLink[];
+}
+interface Conversation {
+    conversation_id: string;
+    update_time: number;
+    referral: ConversationReferral;
+}
+interface ListConversationsRequest {
+    business_id: string;
+    cursor?: number;
+    conversation_type: ConversationType;
+    limit?: number;
+}
+interface ListConversationsResponse {
+    conversations: Conversation[];
+    has_more: boolean;
+    cursor: number;
+}
+interface SendImageMessageRequest {
+    business_id: string;
+    recipient_type: RecipientType;
+    message_type: "IMAGE";
+    recipient: string;
+    image: MediaContent;
+}
+interface SendImageMessageResponse {
+    message_id: string;
+    create_time: number;
+}
+
+declare class Auth {
+    private readonly config;
+    constructor(config: TikTokConfig);
+    getTokens(authCode: string): Promise<TikTokTokenResponse>;
+    refreshTokens(refreshToken: string): Promise<RefreshTokenResponse>;
+    revokeToken(accessToken: string): Promise<RevokeTokenResponse>;
+    getAuthorizationUrl(state?: string): string;
+    private post;
+}
+
+interface RequestOptions {
+    accessToken: string;
+    advertiserIds?: string[];
+    timeout?: number;
+}
+
+declare class HttpClient {
+    private config;
+    private baseUrl;
+    constructor(config: TikTokConfig);
+    get<T>(path: string, params: object, opts: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    put<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    patch<T>(path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    delete<T>(path: string, params: object, opts: RequestOptions): Promise<T>;
+    upload<T>(path: string, form: FormData, opts: RequestOptions): Promise<T>;
+    private request;
+    private buildUrl;
+    private buildInit;
+    private parseResponse;
+}
+
+declare class MediaService {
+    private readonly http;
+    constructor(http: HttpClient);
+    upload(params: UploadMediaRequest, opts: RequestOptions): Promise<UploadMediaResponse>;
+}
+
+declare class Messaging {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all conversations for a business account
+     */
+    listConversations(params: ListConversationsRequest, opts: RequestOptions): Promise<ListConversationsResponse>;
+    /**
+     * Get messages in a specific conversation
+     */
+    listMessages(params: ListMessagesRequest, opts: RequestOptions): Promise<ListMessagesResponse>;
+    /**
+     * Send a text message to a conversation
+     */
+    sendTextMessage(body: SendTextMessageRequest, opts: RequestOptions): Promise<SendTextMessageResponse>;
+    /**
+     * Send an image message to a conversation
+     */
+    sendImageMessage(body: SendImageMessageRequest, opts: RequestOptions): Promise<SendImageMessageResponse>;
+}
+
+type WebhookEventType = "DIRECT_MESSAGE";
+interface CreateWebhookRequest {
+    callback_url: string;
+    event_type: WebhookEventType;
+}
+interface CreateWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+    callback_url: string;
+}
+interface GetWebhookRequest {
+    event_type: WebhookEventType;
+}
+interface GetWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+    callback_url?: string;
+}
+interface DeleteWebhookRequest {
+    event_type: WebhookEventType;
+}
+interface DeleteWebhookResponse {
+    app_id: string;
+    event_type: WebhookEventType;
+}
+
+declare class WebhookService {
+    private readonly config;
+    constructor(config: TikTokConfig);
+    create(params: CreateWebhookRequest): Promise<CreateWebhookResponse>;
+    get(params: GetWebhookRequest): Promise<GetWebhookResponse>;
+    delete(params: DeleteWebhookRequest): Promise<DeleteWebhookResponse>;
+    private post;
+    private fetch;
+    private parseResponse;
+}
+
+declare class TikTokBusiness {
+    readonly auth: Auth;
+    readonly messaging: Messaging;
+    readonly media: MediaService;
+    readonly webhook: WebhookService;
+    constructor(config: TikTokConfig);
+}
+
+/**
+ * TikTok Business API Error Codes
+ */
+declare enum TikTokErrorCode {
+    NO_PERMISSION = 40001,
+    PARAMETER_ERROR = 40002,
+    OBJECT_NOT_FOUND = 40007,
+    RATE_LIMIT_EXCEEDED = 40100,
+    INVALID_ACCESS_TOKEN = 40105,
+    UNSUPPORTED_FILE_TYPE = 40908,
+    MESSAGE_BLOCKED = 40064,
+    SYSTEM_ERROR = 51065,
+    CODE_EXPIRED = 40131
+}
+
+/**
+ * TikTok API Errors
+ */
+declare class TikTokApiError extends Error {
+    readonly code: TikTokErrorCode;
+    readonly requestId?: string | undefined;
+    readonly message: string;
+    constructor(code: TikTokErrorCode, requestId?: string | undefined);
+}
+
+export { type Conversation, type ConversationReferral, type ConversationStatus, type ConversationType, type ListConversationsRequest, type ListConversationsResponse, type ListMessagesRequest, type ListMessagesResponse, type Message, type MessageType, type RecipientType, type ReferralAd, type ReferralShortLink, type RefreshTokenResponse, type RevokeTokenResponse, type SendImageMessageRequest, type SendImageMessageResponse, type SendTextMessageRequest, type SendTextMessageResponse, type SenderAction, type TextContent, TikTokApiError, TikTokBusiness, type TikTokConfig, type TikTokTokenResponse };

package/dist/index.js

@@ -0,0 +1,307 @@
+// src/constants.ts
+var TIKTOK_API_BASE_URL = "https://business-api.tiktok.com/open_api/v1.3";
+var TIKTOK_AUTH_BASE_URL = `${TIKTOK_API_BASE_URL}/tt_user/oauth2`;
+var TIKTOK_ERROR_MESSAGES = {
+  [40001 /* NO_PERMISSION */]: "No permission to perform the related operation. Ensure you have the necessary scopes.",
+  [40002 /* PARAMETER_ERROR */]: "Parameter error. Check missing fields or incorrect formats in your request.",
+  [40007 /* OBJECT_NOT_FOUND */]: "The operation or object does not exist. Check your IDs or URLs.",
+  [40100 /* RATE_LIMIT_EXCEEDED */]: "Requests made too frequently. You are being throttled.",
+  [40105 /* INVALID_ACCESS_TOKEN */]: "Invalid or incorrect access token. Please refresh or re-authorize.",
+  [40908 /* UNSUPPORTED_FILE_TYPE */]: "The file type is unsupported. Refer to documentation for allowed formats.",
+  [40064 /* MESSAGE_BLOCKED */]: "The message is blocked due to TikTok direct message rules.",
+  [51065 /* SYSTEM_ERROR */]: "TikTok internal system error. Please retry the request.",
+  [40131 /* CODE_EXPIRED */]: "The authorization code has expired. Please re-authorize to get a new code."
+};
+
+// src/error.ts
+var TikTokApiError = class _TikTokApiError extends Error {
+  constructor(code, requestId) {
+    const friendlyMessage = TIKTOK_ERROR_MESSAGES[code] || "An unknown TikTok API error occurred.";
+    super(`TikTok API Error [${code}]: ${friendlyMessage}`);
+    this.code = code;
+    this.requestId = requestId;
+    this.name = "TikTokApiError";
+    this.message = friendlyMessage;
+    Object.setPrototypeOf(this, _TikTokApiError.prototype);
+  }
+  message;
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = config.baseUrl ?? "https://business-api.tiktok.com/open_api/v1.3";
+  }
+  baseUrl;
+  get(path, params, opts) {
+    return this.request({ method: "GET", path, params, opts });
+  }
+  post(path, body, opts) {
+    return this.request({ method: "POST", path, body, opts });
+  }
+  put(path, body, opts) {
+    return this.request({ method: "PUT", path, body, opts });
+  }
+  patch(path, body, opts) {
+    return this.request({ method: "PATCH", path, body, opts });
+  }
+  delete(path, params, opts) {
+    return this.request({ method: "DELETE", path, params, opts });
+  }
+  upload(path, form, opts) {
+    return this.request({ method: "POST", path, form, opts });
+  }
+  async request({
+    method,
+    path,
+    params,
+    body,
+    form,
+    opts
+  }) {
+    const res = await fetch(
+      this.buildUrl(path, params),
+      this.buildInit(method, body, opts, form)
+    );
+    return this.parseResponse(res);
+  }
+  buildUrl(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      Object.entries(params).forEach(([k, v]) => {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      });
+    }
+    return url.toString();
+  }
+  buildInit(method, body, opts, form) {
+    const headers = {
+      "Access-Token": opts.accessToken
+    };
+    if (!form) {
+      headers["Content-Type"] = "application/json";
+    }
+    return {
+      method,
+      signal: AbortSignal.timeout(
+        opts.timeout ?? this.config.timeout ?? 1e4
+      ),
+      headers,
+      ...form ? { body: form } : body !== void 0 ? { body: JSON.stringify(body) } : {}
+    };
+  }
+  async parseResponse(res) {
+    console.debug(`[HttpClient] Parsing response for URL: ${res.url}`);
+    console.debug(
+      `[HttpClient] Response status: ${res.status} ${res.statusText}`
+    );
+    console.debug(`[HttpClient] Response data:`, await res.clone().text());
+    const json = await res.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/services/auth.ts
+var Auth = class {
+  constructor(config) {
+    this.config = config;
+  }
+  getTokens(authCode) {
+    return this.post("/token/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      grant_type: "authorization_code",
+      auth_code: decodeURIComponent(authCode),
+      redirect_uri: this.config.redirectUri
+    });
+  }
+  refreshTokens(refreshToken) {
+    return this.post("/refresh_token/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken
+    });
+  }
+  revokeToken(accessToken) {
+    return this.post("/token/revoke/", {
+      client_id: this.config.clientKey,
+      client_secret: this.config.clientSecret,
+      token: accessToken
+    });
+  }
+  // for tt_users
+  getAuthorizationUrl(state) {
+    const params = new URLSearchParams({
+      client_key: this.config.clientKey,
+      response_type: "code",
+      scope: (this.config.scopes ?? []).join(","),
+      redirect_uri: this.config.redirectUri ?? "",
+      ...state && { state }
+    });
+    return `https://www.tiktok.com/v2/auth/authorize/?${params.toString()}`;
+  }
+  async post(path, body) {
+    const response = await fetch(`${TIKTOK_AUTH_BASE_URL}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      throw new TikTokApiError(response.status, response.statusText);
+    }
+    const json = await response.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/services/media.ts
+var MediaService = class {
+  constructor(http) {
+    this.http = http;
+  }
+  upload(params, opts) {
+    const form = new FormData();
+    form.append("business_id", params.business_id);
+    form.append("file", params.file);
+    form.append("media_type", params.media_type);
+    return this.http.upload("/business/message/media/upload/", form, opts);
+  }
+};
+
+// src/services/messaging.ts
+var Messaging = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all conversations for a business account
+   */
+  listConversations(params, opts) {
+    console.debug("[Messaging] listConversations called", { params });
+    return this.http.get("/business/message/conversation/list/", params, opts).then((response) => {
+      console.debug("[Messaging] listConversations succeeded");
+      return response;
+    }).catch((error) => {
+      console.error("[Messaging] listConversations failed", error);
+      throw error;
+    });
+  }
+  /**
+   * Get messages in a specific conversation
+   */
+  listMessages(params, opts) {
+    console.log("Conversation ID:", encodeURIComponent(params.conversation_id));
+    return this.http.get(
+      "/business/message/content/list/",
+      {
+        ...params
+      },
+      opts
+    );
+  }
+  /**
+   * Send a text message to a conversation
+   */
+  sendTextMessage(body, opts) {
+    const { ...restBody } = body;
+    return this.http.post(
+      "/business/message/send/",
+      { recipient_type: "CONVERSATION", ...restBody },
+      opts
+    );
+  }
+  /**
+   * Send an image message to a conversation
+   */
+  sendImageMessage(body, opts) {
+    return this.http.post(
+      "/business/message/send/",
+      {
+        ...body
+      },
+      opts
+    );
+  }
+};
+
+// src/services/webhook.ts
+var WebhookService = class {
+  constructor(config) {
+    this.config = config;
+  }
+  create(params) {
+    return this.post("/business/webhook/update/", {
+      event_type: params.event_type,
+      callback_url: params.callback_url
+    });
+  }
+  get(params) {
+    return this.fetch("/business/webhook/list/", params.event_type);
+  }
+  delete(params) {
+    return this.post("/business/webhook/delete/", {
+      event_type: params.event_type
+    });
+  }
+  async post(path, body) {
+    console.log("called post");
+    const response = await fetch(`${TIKTOK_API_BASE_URL}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        app_id: this.config.clientKey,
+        secret: this.config.clientSecret,
+        ...body
+      })
+    });
+    console.log(response.status, await response.text());
+    return this.parseResponse(response);
+  }
+  async fetch(path, event_type) {
+    const url = new URL(`${TIKTOK_API_BASE_URL}${path}`);
+    url.searchParams.set("app_id", this.config.clientKey);
+    url.searchParams.set("secret", this.config.clientSecret);
+    url.searchParams.set("event_type", event_type);
+    const response = await globalThis.fetch(url.toString());
+    return this.parseResponse(response);
+  }
+  async parseResponse(response) {
+    if (!response.ok) {
+      throw new TikTokApiError(response.status, response.statusText);
+    }
+    const json = await response.json();
+    if (json.code !== 0) {
+      throw new TikTokApiError(json.code, json.request_id);
+    }
+    return json.data;
+  }
+};
+
+// src/client.ts
+var TikTokBusiness = class {
+  auth;
+  messaging;
+  media;
+  webhook;
+  constructor(config) {
+    const http = new HttpClient(config);
+    this.auth = new Auth(config);
+    this.messaging = new Messaging(http);
+    this.media = new MediaService(http);
+    this.webhook = new WebhookService(config);
+  }
+};
+export {
+  TikTokApiError,
+  TikTokBusiness
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "tiktok-business-messaging",
+  "version": "0.0.1",
+  "description": "TypeScript API Client for Tiktokbusiness API",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "test": "vitest run",
+    "test-watch": "vitest",
+    "lint": "tsc",
+    "ci": "pnpm run lint && pnpm run test && pnpm run build"
+  },
+  "keywords": [],
+  "author": "Pshishir",
+  "license": "MIT",
+  "packageManager": "pnpm@10.30.0",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  }
+}