@hexabot-ai/api 3.0.0-alpha.3 → 3.1.1-alpha.0

package/src/chat/services/subscriber.service.ts

@@ -4,7 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
-import { Injectable, InternalServerErrorException } from '@nestjs/common';
+import { Inject, Injectable, Optional, forwardRef } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 import mime from 'mime';
 import { In, IsNull, Not } from 'typeorm';
@@ -18,74 +18,49 @@ import {
   AttachmentResourceRef,
 } from '@/attachment/types';
 import { config } from '@/config';
-import { LoggerService } from '@/logger/logger.service';
+import { UserService } from '@/user/services/user.service';
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
-import {
-  SocketGet,
-  SocketPost,
-} from '@/websocket/decorators/socket-method.decorator';
-import { SocketReq } from '@/websocket/decorators/socket-req.decorator';
-import { SocketRes } from '@/websocket/decorators/socket-res.decorator';
-import { IOOutgoingSubscribeMessage } from '@/websocket/pipes/io-message.pipe';
-import { Room } from '@/websocket/types';
-import { SocketRequest } from '@/websocket/utils/socket-request';
-import { SocketResponse } from '@/websocket/utils/socket-response';
 import { WebsocketGateway } from '@/websocket/websocket.gateway';
 
-import {
-  Subscriber,
-  SubscriberDtoConfig,
-  SubscriberTransformerDto,
-  SubscriberUpdateDto,
-} from '../dto/subscriber.dto';
+import { Subscriber, SubscriberUpdateDto } from '../dto/subscriber.dto';
 import { SubscriberOrmEntity } from '../entities/subscriber.entity';
 import { SubscriberRepository } from '../repositories/subscriber.repository';
 
 import { LabelService } from './label.service';
 
+export const SUBSCRIBER_HANDOVER_MODES = ['specific', 'auto'] as const;
+
+export type SubscriberHandoverMode = (typeof SUBSCRIBER_HANDOVER_MODES)[number];
+
+export type SubscriberHandoverFailureReason = 'no_available_user';
+
+export type SubscriberHandoverPolicyInput = {
+  mode: SubscriberHandoverMode;
+  userId?: string;
+};
+
+export type SubscriberHandoverPolicyResult = {
+  success: boolean;
+  mode: SubscriberHandoverMode;
+  subscriber: Subscriber;
+  assignedTo: string | null;
+  reason?: SubscriberHandoverFailureReason;
+};
+
 @Injectable()
-export class SubscriberService extends BaseOrmService<
-  SubscriberOrmEntity,
-  SubscriberTransformerDto,
-  SubscriberDtoConfig,
-  SubscriberRepository
-> {
+export class SubscriberService extends BaseOrmService<SubscriberOrmEntity> {
   constructor(
     readonly repository: SubscriberRepository,
     protected readonly attachmentService: AttachmentService,
     protected readonly labelService: LabelService,
-    private readonly gateway: WebsocketGateway,
-    private readonly logger: LoggerService,
+    protected readonly userService: UserService,
+    @Optional()
+    @Inject(forwardRef(() => WebsocketGateway))
+    protected readonly websocketGateway?: WebsocketGateway,
   ) {
     super(repository);
   }
 
-  /**
-   * Internally subscribe web-sockets to user's event
-   * For example : Notify chat if new user interacted with the chatbot
-   *
-   * @param req - The socket request object
-   * @param res - The socket response object
-   */
-  @SocketGet('/subscriber/subscribe/')
-  @SocketPost('/subscriber/subscribe/')
-  async subscribe(
-    @SocketReq() req: SocketRequest,
-    @SocketRes() res: SocketResponse,
-  ): Promise<IOOutgoingSubscribeMessage> {
-    try {
-      await this.gateway.joinNotificationSockets(req, Room.SUBSCRIBER);
-
-      return res.status(200).json({
-        success: true,
-        subscribe: Room.SUBSCRIBER,
-      });
-    } catch (e) {
-      this.logger.error('Websocket subscription', e);
-      throw new InternalServerErrorException(e);
-    }
-  }
-
   /**
    * Finds and returns a single subscriber based on a foreign ID.
    *
@@ -243,6 +218,82 @@ export class SubscriberService extends BaseOrmService<
     );
   }
 
+  /**
+   * Updates subscriber labels by applying assign/remove operations.
+   * Assign operations are applied first to preserve mutex semantics,
+   * and overlapping label ids always keep the assignment (assign wins).
+   */
+  async updateLabels(
+    subscriber: Subscriber,
+    labelsToAssign: string[] = [],
+    labelsToRemove: string[] = [],
+  ): Promise<Subscriber> {
+    const uniqueLabelsToAssign = Array.from(new Set(labelsToAssign));
+    const labelsToAssignSet = new Set(uniqueLabelsToAssign);
+    const uniqueLabelsToRemove = Array.from(new Set(labelsToRemove)).filter(
+      (labelId) => !labelsToAssignSet.has(labelId),
+    );
+
+    if (
+      uniqueLabelsToAssign.length === 0 &&
+      uniqueLabelsToRemove.length === 0
+    ) {
+      throw new Error('At least one label operation is required');
+    }
+
+    let current = subscriber;
+
+    if (uniqueLabelsToAssign.length > 0) {
+      current = await this.assignLabels(current, uniqueLabelsToAssign);
+    }
+
+    if (uniqueLabelsToRemove.length > 0) {
+      current = await this.repository.updateLabels(
+        current.id,
+        [],
+        uniqueLabelsToRemove,
+      );
+    }
+
+    return current;
+  }
+
+  /**
+   * Resolves label ids into canonical label names while preserving input order.
+   * Unknown label ids are ignored.
+   */
+  async resolveLabelNames(labelIds: string[] = []): Promise<string[]> {
+    const uniqueLabelIds = Array.from(new Set(labelIds)).filter(
+      (labelId): labelId is string =>
+        typeof labelId === 'string' && labelId.length > 0,
+    );
+    if (!uniqueLabelIds.length) {
+      return [];
+    }
+
+    const labels = await this.labelService.find({
+      where: {
+        id: In(uniqueLabelIds),
+      },
+    });
+    if (!labels.length) {
+      return [];
+    }
+
+    const labelNameById = new Map(
+      labels.map((label) => [label.id, label.name] as const),
+    );
+
+    return uniqueLabelIds.reduce<string[]>((acc, labelId) => {
+      const labelName = labelNameById.get(labelId);
+      if (labelName) {
+        acc.push(labelName);
+      }
+
+      return acc;
+    }, []);
+  }
+
   /**
    * Handover (assign) the subscriber to a specific user.
    * No-op if `assignTo` is falsy.
@@ -256,7 +307,20 @@ export class SubscriberService extends BaseOrmService<
       throw new Error('Cannot handover to undefined user!');
     }
 
-    const updated = await this.updateOne(profile.id, { assignedTo: assignTo });
+    const updated = await this.updateOne(profile.id, {
+      assignedTo: assignTo,
+      assignedAt: new Date(),
+    });
+
+    await this.eventEmitter.emitAsync(
+      'hook:subscriber:assign',
+      {
+        assignedTo: updated.assignedTo,
+        assignedAt: updated.assignedAt,
+      },
+      profile,
+    );
+
     this.logger.debug(
       `Subscriber "${profile.id}" handed over to "${assignTo}"`,
     );
@@ -264,6 +328,118 @@ export class SubscriberService extends BaseOrmService<
     return updated;
   }
 
+  /**
+   * Hand back (unassign) the subscriber from the current assignee.
+   *
+   * @param profile - The end-user (subscriber) profile
+   * @returns The updated profile with assignee fields cleared
+   */
+  async handBack(profile: Subscriber): Promise<Subscriber> {
+    const updated = await this.updateOne(profile.id, {
+      assignedTo: null,
+      assignedAt: null,
+    });
+
+    await this.eventEmitter.emitAsync(
+      'hook:subscriber:assign',
+      {
+        assignedTo: null,
+        assignedAt: null,
+      },
+      profile,
+    );
+
+    this.logger.debug(`Subscriber "${profile.id}" handed back`);
+
+    return updated;
+  }
+
+  /**
+   * Resolves the least-loaded online active assignee.
+   */
+  private async resolveAutoAssigneeId(): Promise<string | null> {
+    const onlineUserIds =
+      this.websocketGateway?.getConnectedAuthenticatedUserIds() ?? [];
+
+    if (!onlineUserIds.length) {
+      return null;
+    }
+
+    const activeUserIds =
+      await this.userService.findActiveUserIds(onlineUserIds);
+    if (!activeUserIds.length) {
+      return null;
+    }
+
+    const workloadByUser =
+      await this.repository.countAssignedSubscribersByUserIds(activeUserIds);
+    const sortedCandidates = [...activeUserIds].sort((a, b) => {
+      const aCount = workloadByUser[a] ?? 0;
+      const bCount = workloadByUser[b] ?? 0;
+
+      if (aCount !== bCount) {
+        return aCount - bCount;
+      }
+
+      return a.localeCompare(b);
+    });
+
+    return sortedCandidates[0] ?? null;
+  }
+
+  /**
+   * Performs policy-based subscriber handover for conversational workflows.
+   */
+  async handOverByPolicy(
+    profile: Subscriber,
+    input: SubscriberHandoverPolicyInput,
+  ): Promise<SubscriberHandoverPolicyResult> {
+    if (input.mode === 'specific') {
+      if (!input.userId) {
+        throw new Error('`userId` is required when handover mode is specific');
+      }
+
+      const [activeUserId] = await this.userService.findActiveUserIds([
+        input.userId,
+      ]);
+      const isActive = activeUserId === input.userId;
+      if (!isActive) {
+        throw new Error(
+          `Unable to handover to user "${input.userId}": user is inactive or does not exist`,
+        );
+      }
+
+      const updated = await this.handOver(profile, input.userId);
+
+      return {
+        success: true,
+        mode: 'specific',
+        subscriber: updated,
+        assignedTo: updated.assignedTo,
+      };
+    }
+
+    const assigneeId = await this.resolveAutoAssigneeId();
+    if (!assigneeId) {
+      return {
+        success: false,
+        mode: 'auto',
+        subscriber: profile,
+        assignedTo: profile.assignedTo ?? null,
+        reason: 'no_available_user',
+      };
+    }
+
+    const updated = await this.handOver(profile, assigneeId);
+
+    return {
+      success: true,
+      mode: 'auto',
+      subscriber: updated,
+      assignedTo: updated.assignedTo,
+    };
+  }
+
   /**
    * Apply updates on end-user such as :
    * - Assign labels to specific end-user
@@ -294,14 +470,14 @@ export class SubscriberService extends BaseOrmService<
         current = await this.handOver(current, assignTo);
       }
 
-      this.logger.debug('Block updates have been applied!', {
+      this.logger.debug('Subscriber updates have been applied!', {
         labels,
         assignTo,
       });
 
       return current;
     } catch (err) {
-      this.logger.error('Unable to perform block updates!', err);
+      this.logger.error('Unable to perform subscriber updates!', err);
       throw err;
     }
   }
@@ -336,7 +512,7 @@ export class SubscriberService extends BaseOrmService<
           JSON.stringify(user),
         );
       } catch (err) {
-        this.logger.error(err);
+        this.logger.error('Unable to log user last visit', err);
       }
     }
   }

package/src/chat/services/thread.service.ts

@@ -0,0 +1,236 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { Thread } from '../dto/thread.dto';
+import { ThreadOrmEntity } from '../entities/thread.entity';
+import { ThreadRepository } from '../repositories/thread.repository';
+
+@Injectable()
+export class ThreadService extends BaseOrmService<ThreadOrmEntity> {
+  public static readonly THREAD_TITLE_MAX_LENGTH = 96;
+
+  public static readonly THREAD_TITLE_ELLIPSIS = '...';
+
+  constructor(readonly repository: ThreadRepository) {
+    super(repository);
+  }
+
+  getDefaultInactivityHours(): number {
+    return 24;
+  }
+
+  getInactivityThresholdMs(hours?: number): number {
+    const normalizedHours = Number.isFinite(hours)
+      ? Math.max(0, Number(hours))
+      : this.getDefaultInactivityHours();
+
+    return normalizedHours * 60 * 60 * 1000;
+  }
+
+  async findThreadForSubscriber(
+    threadId: string,
+    subscriberId: string,
+  ): Promise<Thread | null> {
+    return await this.repository.findOneForSubscriber(threadId, subscriberId);
+  }
+
+  async createThread(subscriberId: string, title?: string | null) {
+    return await this.create({
+      subscriber: subscriberId,
+      title: title ?? null,
+      status: 'open',
+      lastMessageAt: new Date(),
+      closeReason: null,
+      closedAt: null,
+    });
+  }
+
+  buildThreadTitleFromIncomingText(input?: string | null): string | null {
+    if (typeof input !== 'string') {
+      return null;
+    }
+
+    const normalized = input.replace(/\s+/g, ' ').trim();
+    if (!normalized) {
+      return null;
+    }
+
+    if (normalized.length <= ThreadService.THREAD_TITLE_MAX_LENGTH) {
+      return normalized;
+    }
+
+    const trimmedMax = Math.max(
+      1,
+      ThreadService.THREAD_TITLE_MAX_LENGTH -
+        ThreadService.THREAD_TITLE_ELLIPSIS.length,
+    );
+
+    return `${normalized.slice(0, trimmedMax).trimEnd()}${ThreadService.THREAD_TITLE_ELLIPSIS}`;
+  }
+
+  async setThreadTitleIfMissing(threadId: string, title: string) {
+    return await this.repository.setTitleIfMissing(threadId, title);
+  }
+
+  async touchThread(threadId: string, at: Date = new Date()) {
+    return await this.updateOne(threadId, {
+      lastMessageAt: at,
+    });
+  }
+
+  async closeThread(
+    threadId: string,
+    reason: 'manual' | 'inactivity' = 'manual',
+    at: Date = new Date(),
+  ) {
+    return await this.updateOne(threadId, {
+      status: 'closed',
+      closeReason: reason,
+      closedAt: at,
+      lastMessageAt: at,
+    });
+  }
+
+  async reopenThread(threadId: string, at: Date = new Date()) {
+    return await this.updateOne(threadId, {
+      status: 'open',
+      closeReason: null,
+      closedAt: null,
+      lastMessageAt: at,
+    });
+  }
+
+  async resolveThreadForIncoming({
+    subscriberId,
+    explicitThreadId,
+    inactivityHours,
+  }: {
+    subscriberId: string;
+    explicitThreadId?: string;
+    inactivityHours?: number;
+  }): Promise<Thread> {
+    const now = new Date();
+
+    if (explicitThreadId) {
+      const explicit = await this.repository.findOne({
+        where: {
+          id: explicitThreadId,
+          subscriber: { id: subscriberId },
+        },
+      });
+      if (!explicit) {
+        throw new Error(
+          `Thread ${explicitThreadId} was not found for subscriber ${subscriberId}`,
+        );
+      }
+
+      if (explicit.status === 'closed') {
+        return await this.reopenThread(explicit.id, now);
+      }
+
+      await this.touchThread(explicit.id, now);
+
+      return explicit;
+    }
+
+    const latestOpen =
+      await this.repository.findLatestOpenThreadForSubscriber(subscriberId);
+
+    if (!latestOpen) {
+      return await this.createThread(subscriberId);
+    }
+
+    const anchor = latestOpen.lastMessageAt ?? latestOpen.createdAt;
+    const inactivityMs = this.getInactivityThresholdMs(inactivityHours);
+    const hasExpired = now.getTime() - anchor.getTime() > inactivityMs;
+
+    if (hasExpired) {
+      await this.closeThread(latestOpen.id, 'inactivity', now);
+
+      return await this.createThread(subscriberId);
+    }
+
+    await this.touchThread(latestOpen.id, now);
+
+    return latestOpen;
+  }
+
+  async resolveOrCreateThread({
+    subscriberId,
+    explicitThreadId,
+  }: {
+    subscriberId: string;
+    explicitThreadId?: string;
+  }): Promise<Thread> {
+    const resolved = await this.resolveThread({
+      subscriberId,
+      explicitThreadId,
+    });
+    if (resolved) {
+      return resolved;
+    }
+
+    return await this.createThread(subscriberId);
+  }
+
+  async resolveThread({
+    subscriberId,
+    explicitThreadId,
+  }: {
+    subscriberId: string;
+    explicitThreadId?: string;
+  }): Promise<Thread | null> {
+    if (explicitThreadId) {
+      const explicit = await this.findThreadForSubscriber(
+        explicitThreadId,
+        subscriberId,
+      );
+      if (!explicit) {
+        throw new Error(
+          `Thread ${explicitThreadId} was not found for subscriber ${subscriberId}`,
+        );
+      }
+
+      return explicit;
+    }
+
+    const latestOpen =
+      await this.repository.findLatestOpenThreadForSubscriber(subscriberId);
+
+    if (latestOpen) {
+      return latestOpen;
+    }
+
+    const latest =
+      await this.repository.findLatestThreadForSubscriber(subscriberId);
+
+    return latest ?? null;
+  }
+
+  /**
+   * Resolve inactivity timeout from channel settings object.
+   */
+  resolveInactivityHours(settings: unknown): number {
+    const candidate = (settings as { thread_inactivity_hours?: unknown })
+      ?.thread_inactivity_hours;
+
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+      return Math.max(0, candidate);
+    }
+    if (typeof candidate === 'string') {
+      const parsed = Number.parseInt(candidate, 10);
+      if (!Number.isNaN(parsed)) {
+        return Math.max(0, parsed);
+      }
+    }
+
+    return this.getDefaultInactivityHours();
+  }
+}

package/src/chat/types/attachment.ts

@@ -14,14 +14,14 @@ export enum FileType {
   unknown = 'unknown',
 }
 
-export const fileTypeSchema = z.nativeEnum(FileType);
+export const fileTypeSchema = z.enum(FileType);
 
 /**
  * The `AttachmentRef` type defines two possible ways to reference an attachment:
  * 1. By `id`: This is used when the attachment is uploaded and stored in the Hexabot system.
  * The `id` field represents the unique identifier of the uploaded attachment in the system.
  * 2. By `url`: This is used when the attachment is externally hosted, especially when
- * the content is generated or retrieved by a plugin that consumes a third-party API.
+ * the content is generated or retrieved by an action that consumes a third-party API.
  * In this case, the `url` field contains the direct link to the external resource.
  */
 

package/src/chat/types/button.ts

@@ -11,26 +11,69 @@ export enum ButtonType {
   web_url = 'web_url',
 }
 
-const postBackButtonSchema = z.object({
-  type: z.literal(ButtonType.postback),
-  title: z.string(),
-  payload: z.string(),
-});
-const webUrlButtonSchema = z.object({
-  type: z.literal(ButtonType.web_url),
-  title: z.string(),
-  url: z.union([z.string().url(), z.literal('')]),
-  messenger_extensions: z.boolean().optional(),
-  webview_height_ratio: z.enum(['compact', 'tall', 'full']).optional(),
-});
-
-export const buttonSchema = z.union([postBackButtonSchema, webUrlButtonSchema]);
-
-export type PostBackButton = z.infer<typeof postBackButtonSchema>;
-
-export type WebUrlButton = z.infer<typeof webUrlButtonSchema>;
-
-export type Button = z.infer<typeof buttonSchema>;
+export type PostBackButton = {
+  type: ButtonType.postback;
+  title: string;
+  payload: string;
+};
+
+export type WebUrlButton = {
+  type: ButtonType.web_url;
+  title: string;
+  url: string;
+  messenger_extensions?: boolean;
+  webview_height_ratio?: 'compact' | 'tall' | 'full';
+};
+
+export type Button = PostBackButton | WebUrlButton;
+
+export const buttonSchema = z
+  .object({
+    type: z.enum([ButtonType.postback, ButtonType.web_url]).meta({
+      title: 'Type',
+      description: 'The type of button.',
+    }),
+    title: z.string().meta({
+      title: 'Title',
+      description: 'The label shown to the user.',
+    }),
+    payload: z.string().optional().meta({
+      title: 'Payload',
+      description: 'The value sent back when the button is clicked.',
+    }),
+    url: z
+      .union([z.url(), z.literal('')])
+      .optional()
+      .meta({
+        title: 'URL',
+        description: 'The destination URL opened when the button is clicked.',
+      }),
+    messenger_extensions: z.boolean().optional().meta({
+      title: 'Messenger extensions',
+      description: 'Whether to enable Messenger Extensions for the webview.',
+    }),
+    webview_height_ratio: z.enum(['compact', 'tall', 'full']).optional().meta({
+      title: 'Webview height ratio',
+      description: 'The height of the webview.',
+    }),
+  })
+  .superRefine((button, ctx) => {
+    if (button.type === ButtonType.postback && !button.payload) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['payload'],
+        message: 'Payload is required for postback buttons.',
+      });
+    }
+
+    if (button.type === ButtonType.web_url && !button.url) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['url'],
+        message: 'URL is required for web_url buttons.',
+      });
+    }
+  }) as unknown as z.ZodType<Button>;
 
 export enum PayloadType {
   location = 'location',