socialdesk-node 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import { AddLabelOptions, AssignConversationOptions, DirectMessageOptions, HintCallbackOptions, HintMessageOptions, HSMMessageOptions } from './types';
+export declare class SocialdeskClient {
+    private accessToken;
+    private http;
+    constructor(accessToken: string, baseURL?: string);
+    /**
+     * Send a hint message visible only to the agent.
+     */
+    sendHintMessage(options: HintMessageOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Send a direct message to the end participant (requires "automatic replies" permission).
+     */
+    sendDirectMessage(options: DirectMessageOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Execute a hint callback action.
+     */
+    sendHintCallback(options: HintCallbackOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Send an HSM (template) message to a participant.
+     */
+    sendHSMMessage(options: HSMMessageOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Assign a conversation to an agent or team.
+     */
+    assignConversation(options: AssignConversationOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Add a label to a conversation.
+     */
+    addLabel(options: AddLabelOptions): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialdeskClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class SocialdeskClient {
+    constructor(accessToken, baseURL = 'https://api.socialdesk.com') {
+        this.accessToken = accessToken;
+        this.http = axios_1.default.create({
+            baseURL,
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Send a hint message visible only to the agent.
+     */
+    async sendHintMessage(options) {
+        const { data } = await this.http.post('/web-api/messages/reply', {
+            text: options.text,
+            attachments: options.attachments ?? [],
+            interactions: options.interactions ?? [],
+            message_id: options.message_id,
+            conversation_id: options.conversation_id,
+            callbacks: options.callbacks ?? [],
+            quick_replies: options.quick_replies ?? [],
+            send_as_direct_message: false,
+            application_context: options.application_context,
+        });
+        return data;
+    }
+    /**
+     * Send a direct message to the end participant (requires "automatic replies" permission).
+     */
+    async sendDirectMessage(options) {
+        const { data } = await this.http.post('/web-api/messages/reply', {
+            text: options.text,
+            attachments: options.attachments ?? [],
+            interactions: options.interactions ?? [],
+            message_id: options.message_id,
+            conversation_id: options.conversation_id,
+            callbacks: [],
+            quick_replies: [],
+            send_as_direct_message: true,
+            application_context: options.application_context,
+        });
+        return data;
+    }
+    /**
+     * Execute a hint callback action.
+     */
+    async sendHintCallback(options) {
+        const { data } = await this.http.post('/web-api/messages/reply/callback', {
+            callback_id: options.callback_id,
+            message_id: options.message_id,
+            reply_id: options.reply_id,
+            conversation_id: options.conversation_id,
+            app_instance: options.app_instance,
+            callback_value: options.callback_value,
+        });
+        return data;
+    }
+    /**
+     * Send an HSM (template) message to a participant.
+     */
+    async sendHSMMessage(options) {
+        const body = {
+            channel_id: options.channel_id,
+            raw_text: options.raw_text,
+        };
+        // Identificar destinatario: account_contact_id O contact, no ambos
+        if (options.account_contact_id) {
+            body.account_contact_id = options.account_contact_id;
+        }
+        else if (options.contact) {
+            body.contact = options.contact;
+        }
+        if (options.parameters)
+            body.parameters = options.parameters;
+        if (options.external_template_id)
+            body.external_template_id = options.external_template_id;
+        if (options.assign_entity)
+            body.assign_entity = options.assign_entity;
+        if (options.assign_entity_id)
+            body.assign_entity_id = options.assign_entity_id;
+        if (options.conversation_id)
+            body.conversation_id = options.conversation_id;
+        if (options.send_at)
+            body.send_at = options.send_at;
+        const { data } = await this.http.post('/web-api/messages/HSM', body);
+        return data;
+    }
+    /**
+     * Assign a conversation to an agent or team.
+     */
+    async assignConversation(options) {
+        const { data } = await this.http.post('/web-api/conversations/assign', {
+            conversation_id: options.conversation_id,
+            account_id: options.account_id ?? null,
+            entity: options.entity,
+            entity_id: options.entity_id,
+            force_assign: options.force_assign ?? false,
+        });
+        return data;
+    }
+    /**
+     * Add a label to a conversation.
+     */
+    async addLabel(options) {
+        const { data } = await this.http.post('/web-api/conversations/labels/add', {
+            conversation_id: options.conversation_id,
+            account_id: options.account_id,
+            labelKey: options.labelKey,
+        });
+        return data;
+    }
+}
+exports.SocialdeskClient = SocialdeskClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SocialdeskClient } from './client';
+export { WebhookHelper } from './webhook';
+export { EventType, MessageDirection, SenderType, AttachmentType, WebhookEvent, WebhookPayload, DirectMessagePayload, ReplyMessagePayload, ReplyMessageCallbackPayload, HSMMessagePayload, ConversationFinalizedPayload, MessageSender, Participant, Agent, Attachment, Interaction, QuickReply, Callback, HintMessageOptions, DirectMessageOptions, HintCallbackOptions, HSMMessageOptions, AssignConversationOptions, AddLabelOptions, } from './types';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentType = exports.SenderType = exports.MessageDirection = exports.EventType = exports.WebhookHelper = exports.SocialdeskClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SocialdeskClient", { enumerable: true, get: function () { return client_1.SocialdeskClient; } });
+var webhook_1 = require("./webhook");
+Object.defineProperty(exports, "WebhookHelper", { enumerable: true, get: function () { return webhook_1.WebhookHelper; } });
+var types_1 = require("./types");
+// Enums
+Object.defineProperty(exports, "EventType", { enumerable: true, get: function () { return types_1.EventType; } });
+Object.defineProperty(exports, "MessageDirection", { enumerable: true, get: function () { return types_1.MessageDirection; } });
+Object.defineProperty(exports, "SenderType", { enumerable: true, get: function () { return types_1.SenderType; } });
+Object.defineProperty(exports, "AttachmentType", { enumerable: true, get: function () { return types_1.AttachmentType; } });

package/dist/types.d.ts

@@ -0,0 +1,212 @@
+export declare enum EventType {
+    DirectMessage = "DIRECT_MESSAGE",
+    ReplyMessage = "REPLY_MESSAGE",
+    HSMMessage = "HSM_MESSAGE",
+    ReplyMessageCallback = "REPLY_MESSAGE_CALLBACK",
+    ConversationFinalized = "CONVERSATION_FINALIZED"
+}
+export declare enum MessageDirection {
+    Incoming = "INCOMING",
+    Outgoing = "OUTGOING"
+}
+export declare enum SenderType {
+    Participant = "PARTICIPANT",
+    Extension = "EXTENSION",
+    Agent = "AGENT"
+}
+export declare enum AttachmentType {
+    IMAGE = "IMAGE",
+    VIDEO = "VIDEO",
+    AUDIO = "AUDIO",
+    TEXT = "TEXT",
+    CONTACTS = "CONTACTS"
+}
+export interface MessageSender {
+    name: string;
+    profile_id: string;
+    picture: string;
+    type: SenderType;
+}
+export interface Participant {
+    id: string;
+    name: string;
+    picture: string;
+    channelInstances?: string[];
+}
+export interface Agent {
+    id: string;
+    name: string;
+    picture: string;
+}
+export interface Attachment {
+    type: AttachmentType;
+    url?: string;
+    fileName?: string;
+}
+export interface Interaction {
+    label: string;
+    config: unknown;
+}
+export interface QuickReply {
+    text: string;
+    attachments?: Attachment[];
+}
+export interface Callback {
+    id: string;
+    label: string;
+    value: string;
+}
+export interface DirectMessagePayload {
+    id: string;
+    direction: MessageDirection;
+    sender: MessageSender;
+    text: string;
+    attachments: Attachment[];
+    interactions: Interaction[];
+    send_at: string;
+    conversation: {
+        id: string;
+        topic: string;
+        participants: Participant[];
+        agents: Agent[];
+        context: any;
+    };
+}
+export interface ReplyMessagePayload {
+    id: string;
+    text: string;
+    callbacks: Callback[];
+    quick_replies: QuickReply[];
+    send_at: string;
+    conversation: {
+        id: string;
+        context: any;
+    };
+    message: {
+        id: string;
+        direction: MessageDirection;
+        text: string;
+        attachments: Attachment[];
+        send_at: string;
+    };
+    sender: MessageSender;
+}
+export interface ReplyMessageCallbackPayload {
+    id: string;
+    label: string;
+    value: any;
+    conversation: {
+        id: string;
+        context: any;
+    };
+    message: {
+        id: string;
+        direction: MessageDirection;
+        text: string;
+        attachments: Attachment[];
+        send_at: string;
+    };
+}
+export interface HSMMessagePayload {
+    id: string;
+    direction: MessageDirection;
+    text: string;
+    rawText: string;
+    to: string;
+    parameters: any;
+    externalTemplateId: string;
+    send_at: string;
+    conversation: {
+        id: string;
+        topic: string;
+        participants: Participant[];
+        agents: Agent[];
+        context: any;
+    };
+    attachments: Attachment[];
+}
+export interface ConversationFinalizedPayload {
+    id: string;
+    conversation: {
+        id: string;
+        context: any;
+        closedBySchedule?: boolean;
+    };
+    message: {
+        id: string;
+        direction: MessageDirection;
+        text: string;
+        send_at: string;
+    };
+}
+export type WebhookPayload = DirectMessagePayload | ReplyMessagePayload | ReplyMessageCallbackPayload | HSMMessagePayload | ConversationFinalizedPayload;
+export interface WebhookEvent {
+    type: EventType;
+    payload: WebhookPayload;
+    channel_instance: string;
+    instance: {
+        type: string;
+        id: string;
+        settings?: string;
+    };
+    access_token: string;
+    event_id: string;
+    event_time: string;
+}
+export interface HintMessageOptions {
+    text?: string;
+    attachments?: Attachment[];
+    interactions?: Interaction[];
+    message_id: string;
+    conversation_id: string;
+    callbacks?: Callback[];
+    quick_replies?: QuickReply[];
+    application_context?: Record<string, any>;
+}
+export interface DirectMessageOptions {
+    text?: string;
+    attachments?: Attachment[];
+    interactions?: Interaction[];
+    message_id: string;
+    conversation_id: string;
+    application_context?: Record<string, any>;
+}
+export interface HintCallbackOptions {
+    callback_id: string;
+    message_id: string;
+    reply_id: string;
+    conversation_id: string;
+    app_instance: string;
+    callback_value: any;
+}
+export interface HSMMessageOptions {
+    channel_id: string;
+    account_contact_id?: string;
+    contact?: {
+        account_id: string;
+        first_name?: string;
+        last_name?: string;
+        phone: string;
+        email?: string;
+        image_url?: string;
+    };
+    raw_text: string;
+    parameters?: any[];
+    external_template_id?: string;
+    assign_entity?: 'USER' | 'TEAM';
+    assign_entity_id?: string;
+    conversation_id?: string;
+    send_at?: string;
+}
+export interface AssignConversationOptions {
+    conversation_id: string;
+    account_id?: string;
+    entity: 'USER' | 'TEAM';
+    entity_id: string;
+    force_assign?: boolean;
+}
+export interface AddLabelOptions {
+    conversation_id: string;
+    account_id?: string;
+    labelKey: string;
+}

package/dist/types.js

@@ -0,0 +1,31 @@
+"use strict";
+// ── Event Types ──
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentType = exports.SenderType = exports.MessageDirection = exports.EventType = void 0;
+var EventType;
+(function (EventType) {
+    EventType["DirectMessage"] = "DIRECT_MESSAGE";
+    EventType["ReplyMessage"] = "REPLY_MESSAGE";
+    EventType["HSMMessage"] = "HSM_MESSAGE";
+    EventType["ReplyMessageCallback"] = "REPLY_MESSAGE_CALLBACK";
+    EventType["ConversationFinalized"] = "CONVERSATION_FINALIZED";
+})(EventType || (exports.EventType = EventType = {}));
+var MessageDirection;
+(function (MessageDirection) {
+    MessageDirection["Incoming"] = "INCOMING";
+    MessageDirection["Outgoing"] = "OUTGOING";
+})(MessageDirection || (exports.MessageDirection = MessageDirection = {}));
+var SenderType;
+(function (SenderType) {
+    SenderType["Participant"] = "PARTICIPANT";
+    SenderType["Extension"] = "EXTENSION";
+    SenderType["Agent"] = "AGENT";
+})(SenderType || (exports.SenderType = SenderType = {}));
+var AttachmentType;
+(function (AttachmentType) {
+    AttachmentType["IMAGE"] = "IMAGE";
+    AttachmentType["VIDEO"] = "VIDEO";
+    AttachmentType["AUDIO"] = "AUDIO";
+    AttachmentType["TEXT"] = "TEXT";
+    AttachmentType["CONTACTS"] = "CONTACTS";
+})(AttachmentType || (exports.AttachmentType = AttachmentType = {}));

package/dist/webhook.d.ts

@@ -0,0 +1,35 @@
+import { EventType, WebhookEvent, WebhookPayload } from './types';
+import { SocialdeskClient } from './client';
+/**
+ * Helper class to parse and extract data from Socialdesk webhook events.
+ */
+export declare class WebhookHelper {
+    private event;
+    constructor(event: WebhookEvent);
+    /** Get the event type. */
+    getEventType(): EventType;
+    /** Get the raw payload. */
+    getPayload(): WebhookPayload;
+    /** Get the access token to call the API. */
+    getAccessToken(): string;
+    /** Get the channel instance ID. */
+    getChannelInstance(): string;
+    /** Get the app instance ID. */
+    getInstanceId(): string;
+    /** Get the parsed app settings (from instance.settings JSON string). */
+    getSettings<T = any>(): T;
+    /** Get the conversation ID from any event type. */
+    getConversationId(): string;
+    /** Get the message ID from any event type. */
+    getMessageId(): string;
+    /** Get the message text from any event type. */
+    getMessageText(): string;
+    /** Get the full conversation context from any event type. */
+    getConversationContext<T = any>(): T;
+    /** Get the application_context for this app from the conversation context (assistants.{appInstanceId}). */
+    getApplicationContext<T = any>(): T;
+    /** Check if the event is a specific type. */
+    isEventType(type: EventType): boolean;
+    /** Create a SocialdeskClient pre-authenticated with the event's access token. */
+    createClient(baseURL?: string): SocialdeskClient;
+}

package/dist/webhook.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHelper = void 0;
+const types_1 = require("./types");
+const client_1 = require("./client");
+/**
+ * Helper class to parse and extract data from Socialdesk webhook events.
+ */
+class WebhookHelper {
+    constructor(event) {
+        this.event = event;
+    }
+    /** Get the event type. */
+    getEventType() {
+        return this.event.type;
+    }
+    /** Get the raw payload. */
+    getPayload() {
+        return this.event.payload;
+    }
+    /** Get the access token to call the API. */
+    getAccessToken() {
+        return this.event.access_token;
+    }
+    /** Get the channel instance ID. */
+    getChannelInstance() {
+        return this.event.channel_instance;
+    }
+    /** Get the app instance ID. */
+    getInstanceId() {
+        return this.event.instance.id;
+    }
+    /** Get the parsed app settings (from instance.settings JSON string). */
+    getSettings() {
+        try {
+            return typeof this.event.instance.settings === 'string'
+                ? JSON.parse(this.event.instance.settings)
+                : this.event.instance.settings ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Get the conversation ID from any event type. */
+    getConversationId() {
+        const payload = this.event.payload;
+        if ('conversation' in payload && payload.conversation) {
+            return payload.conversation.id;
+        }
+        return '';
+    }
+    /** Get the message ID from any event type. */
+    getMessageId() {
+        const payload = this.event.payload;
+        const type = this.event.type;
+        if (type === types_1.EventType.DirectMessage || type === types_1.EventType.HSMMessage) {
+            return payload.id;
+        }
+        if (type === types_1.EventType.ReplyMessage || type === types_1.EventType.ReplyMessageCallback) {
+            return payload.message.id;
+        }
+        if (type === types_1.EventType.ConversationFinalized) {
+            return payload.message.id;
+        }
+        return '';
+    }
+    /** Get the message text from any event type. */
+    getMessageText() {
+        const payload = this.event.payload;
+        const type = this.event.type;
+        if (type === types_1.EventType.DirectMessage) {
+            return payload.text;
+        }
+        if (type === types_1.EventType.HSMMessage) {
+            return payload.text;
+        }
+        if (type === types_1.EventType.ReplyMessage || type === types_1.EventType.ReplyMessageCallback) {
+            return payload.message.text;
+        }
+        if (type === types_1.EventType.ConversationFinalized) {
+            return payload.message.text;
+        }
+        return '';
+    }
+    /** Get the full conversation context from any event type. */
+    getConversationContext() {
+        const payload = this.event.payload;
+        if ('conversation' in payload && payload.conversation) {
+            return payload.conversation.context ?? {};
+        }
+        return {};
+    }
+    /** Get the application_context for this app from the conversation context (assistants.{appInstanceId}). */
+    getApplicationContext() {
+        const context = this.getConversationContext();
+        const appInstanceId = this.getInstanceId();
+        return (context?.assistants?.[appInstanceId] ?? {});
+    }
+    /** Check if the event is a specific type. */
+    isEventType(type) {
+        return this.event.type === type;
+    }
+    /** Create a SocialdeskClient pre-authenticated with the event's access token. */
+    createClient(baseURL) {
+        return new client_1.SocialdeskClient(this.event.access_token, baseURL);
+    }
+}
+exports.WebhookHelper = WebhookHelper;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "socialdesk-node",
+  "version": "1.0.0",
+  "description": "SDK oficial de Socialdesk para Node.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "socialdesk",
+    "sdk",
+    "node",
+    "whatsapp",
+    "chatbot",
+    "messaging"
+  ],
+  "author": "Socialdesk",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
+}