@hexabot-ai/api 3.1.4-alpha.0 → 3.2.0-alpha.0

package/src/extensions/channels/web/services/web-history.service.ts

@@ -0,0 +1,158 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  ActionOptions,
+  AnyMessage,
+  IncomingMessage,
+  OutgoingMessage,
+  OutgoingMessageType,
+  Thread,
+} from '@hexabot-ai/types';
+import { Injectable } from '@nestjs/common';
+
+import { MessageService } from '@/chat/services/message.service';
+import { SocketRequest } from '@/websocket/utils/socket-request';
+
+import { WebInboundMessageEncoder } from '../inbound/web-inbound-message-encoder';
+import { WebOutboundMessageEncoder } from '../outbound/web-outbound-message-encoder';
+import { Web } from '../types';
+
+import { WebSessionService } from './web-session.service';
+
+/**
+ * Context bundle passed to formatting methods so they don't need the handler.
+ * Groups channel-specific pieces that vary between web and console.
+ */
+export interface WebFormatContext {
+  inboundEncoder: WebInboundMessageEncoder;
+  outboundEncoder: WebOutboundMessageEncoder;
+  generateId: () => string;
+  sourceId: string;
+}
+
+/**
+ * Handles message history fetching and all wire-format conversion for the
+ * web / console channels.
+ *
+ * Instantiated per-channel through `@ExtensionInject()` on the channel handler.
+ * The base `ChannelHandler` resolves these providers during `onModuleInit()` via
+ * `ModuleRef.create()`, so each channel gets its own DI-scoped instance.
+ */
+@Injectable()
+export class WebHistoryService {
+  constructor(private readonly messageService: MessageService) {}
+
+  /**
+   * Fetches the message history for the subscriber's thread and converts it
+   * to the web wire format.
+   *
+   * @param thread   - Resolved thread (null returns empty array).
+   * @param ctx      - Channel-specific formatting context.
+   * @param until    - Return messages older than this date (default: now).
+   * @param n        - Maximum number of messages (default: 30).
+   */
+  async fetchHistory(
+    thread: Thread | null,
+    ctx: WebFormatContext,
+    until: Date = new Date(),
+    n: number = 30,
+  ): Promise<Web.Message[]> {
+    if (!thread) return [];
+
+    const messages = await this.messageService.findHistoryUntilDate(
+      thread,
+      until,
+      n,
+    );
+
+    return this.formatMessages(messages.reverse() as AnyMessage[], ctx);
+  }
+
+  /**
+   * Resolves a thread from the request session, then fetches and formats the
+   * history. Convenience wrapper used by the subscribe/history flows.
+   */
+  async fetchHistoryForRequest(
+    req: SocketRequest,
+    sessionService: WebSessionService,
+    ctx: WebFormatContext,
+    until?: Date,
+    n?: number,
+  ): Promise<Web.Message[]> {
+    const profile = req.session.web?.profile;
+    if (!profile?.id) return [];
+
+    const thread = await sessionService.resolveThreadForHistory(
+      req,
+      profile.id,
+    );
+
+    return this.fetchHistory(thread, ctx, until, n);
+  }
+
+  /**
+   * Converts an array of persisted messages (inbound or outbound) to the web
+   * wire format, preserving chronological order.
+   */
+  async formatMessages(
+    messages: AnyMessage[],
+    ctx: WebFormatContext,
+  ): Promise<Web.Message[]> {
+    const result: Web.Message[] = [];
+
+    for (const msg of messages) {
+      const mid = msg.mid ?? ctx.generateId();
+
+      if (this.isIncomingMessage(msg)) {
+        const formatted = await ctx.inboundEncoder.encode(
+          msg.message,
+          ctx.sourceId,
+        );
+        result.push({
+          ...formatted,
+          author: msg.sender,
+          read: true,
+          mid,
+          createdAt: msg.createdAt,
+        });
+      } else {
+        const formatted = await ctx.outboundEncoder.encode(msg.message, {
+          ...this.resolveOutgoingEncodeOptions(msg),
+          sourceId: ctx.sourceId,
+        });
+        result.push({
+          ...formatted,
+          author: 'chatbot',
+          read: true,
+          mid,
+          handover: !!msg.handover,
+          createdAt: msg.createdAt,
+        });
+      }
+    }
+
+    return result;
+  }
+
+  private isIncomingMessage(msg: AnyMessage): msg is IncomingMessage {
+    return 'sender' in msg && !!msg.sender;
+  }
+
+  private resolveOutgoingEncodeOptions(
+    outgoing: OutgoingMessage,
+  ): ActionOptions {
+    const envelope = outgoing.message;
+    if (
+      envelope.type === OutgoingMessageType.list ||
+      envelope.type === OutgoingMessageType.carousel
+    ) {
+      return { content: envelope.data.options };
+    }
+
+    return {};
+  }
+}

package/src/extensions/channels/web/services/web-session.service.ts

@@ -0,0 +1,235 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Subscriber, Thread } from '@hexabot-ai/types';
+import { Injectable } from '@nestjs/common';
+import { Response } from 'express';
+
+import { SubscriberCreateDto } from '@/chat/dto/subscriber.dto';
+import { SubscriberService } from '@/chat/services/subscriber.service';
+import { ThreadService } from '@/chat/services/thread.service';
+import { LoggerService } from '@/logger/logger.service';
+import { SocketRequest } from '@/websocket/utils/socket-request';
+import { SocketResponse } from '@/websocket/utils/socket-response';
+
+/**
+ * Handles all web-channel session and CORS concerns.
+ *
+ * Instantiated per-channel through `@ExtensionInject()` on the channel handler.
+ * The base `ChannelHandler` resolves these providers during `onModuleInit()` via
+ * `ModuleRef.create()`, so each channel gets its own DI-scoped instance.
+ */
+@Injectable()
+export class WebSessionService {
+  constructor(
+    private readonly subscriberService: SubscriberService,
+    private readonly threadService: ThreadService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  normalizeThreadId(raw: unknown): string | undefined {
+    if (typeof raw !== 'string') return undefined;
+    const v = raw.trim();
+
+    return v.length > 0 ? v : undefined;
+  }
+
+  getThreadIdFromQuery(req: SocketRequest): string | undefined {
+    const raw = req.query.thread_id;
+
+    return this.normalizeThreadId(Array.isArray(raw) ? raw[0] : raw);
+  }
+
+  getThreadIdFromBody(req: SocketRequest): string | undefined {
+    const body = req.body as { thread_id?: unknown } | undefined;
+
+    return this.normalizeThreadId(body?.thread_id);
+  }
+
+  /**
+   * Validates the request Origin against the configured allow-list and sets
+   * the appropriate CORS response headers. Throws on any violation.
+   *
+   * @param req - Socket request
+   * @param res - Socket request
+   * @param allowedDomains - Comma-separated list of allowed origins (or "*").
+   */
+  async validateCors(
+    req: SocketRequest,
+    res: Response | SocketResponse,
+    allowedDomains: string,
+  ): Promise<void> {
+    if (!req.headers?.origin) {
+      this.logger.debug('No origin ', req.headers);
+      throw new Error('CORS - No origin provided!');
+    }
+
+    const originUrl = new URL(req.headers.origin);
+    if (!['http:', 'https:'].includes(originUrl.protocol)) {
+      throw new Error('CORS - Invalid origin!');
+    }
+
+    const origins = allowedDomains.split(',');
+    const foundOrigin = origins
+      .filter((o) => o.trim() !== '*')
+      .map((o) => {
+        try {
+          return new URL(o.trim()).origin;
+        } catch {
+          this.logger.error(`Invalid URL in allowed domains: ${o}`);
+
+          return null;
+        }
+      })
+      .filter((o): o is string => o !== null)
+      .some((o) => o === originUrl.origin);
+
+    if (!foundOrigin && !origins.includes('*')) {
+      res.set('Access-Control-Allow-Origin', '');
+      this.logger.debug('No origin found ', req.headers.origin);
+      throw new Error('CORS - Domain not allowed!');
+    }
+
+    res.set('Access-Control-Allow-Origin', originUrl.origin);
+    res.set('Access-Control-Allow-Credentials', 'true');
+    res.set('Access-Control-Expose-Headers', '');
+    if (req.method === 'OPTIONS') {
+      res.set('Access-Control-Allow-Methods', 'GET, POST');
+      res.set('Access-Control-Allow-Headers', 'content-type');
+    }
+  }
+
+  /**
+   * Returns the subscriber from the active session, or attempts to recover it
+   * from the message `author` field. Writes a 403 and returns null when no
+   * valid identity can be established.
+   *
+   * @param req
+   * @param res
+   */
+  async validateSession(
+    req: SocketRequest,
+    res: Response | SocketResponse,
+    sourceId: string,
+  ): Promise<Subscriber | null> {
+    if (req.session.web?.profile?.id && req.session.web.sourceId === sourceId) {
+      return req.session.web.profile;
+    }
+
+    const body = req.body as { author?: unknown } | undefined;
+    const authorForeignId =
+      typeof body?.author === 'string' && body.author.trim().length > 0
+        ? body.author.trim()
+        : undefined;
+
+    if (authorForeignId) {
+      try {
+        const subscriber = await this.subscriberService.findOneByForeignId(
+          authorForeignId,
+          sourceId,
+        );
+        if (subscriber) {
+          const thread = await this.threadService.resolveThread({
+            subscriberId: subscriber.id,
+            explicitThreadId:
+              this.getThreadIdFromBody(req) ?? this.getThreadIdFromQuery(req),
+          });
+          req.session.web = {
+            profile: subscriber,
+            threadId: thread?.id,
+            sourceId,
+          };
+          this.logger.debug(
+            `Recovered missing web session from author ${authorForeignId}`,
+          );
+
+          return subscriber;
+        }
+      } catch (error) {
+        this.logger.warn(
+          `Unable to recover missing session from author ${authorForeignId}`,
+          error,
+        );
+      }
+    }
+
+    this.logger.warn('No session ID to be found!', req.session);
+    res.status(403).json({ err: 'Web Channel Handler : Unauthorized!' });
+
+    return null;
+  }
+
+  /**
+   * Returns the existing subscriber for this session, or creates a new one
+   * using the provided factory. Updates `req.session.web` accordingly.
+   *
+   * @param req
+   * @param buildProfile - Called only when no session exists; returns the DTO
+   *   for the new subscriber (channel name, generated ID, etc. are caller's
+   *   responsibility since they are channel-specific).
+   */
+  async getOrCreateSession(
+    req: SocketRequest,
+    sourceId: string,
+    buildProfile: () => SubscriberCreateDto,
+  ): Promise<Subscriber> {
+    const sessionProfile = req.session.web?.profile;
+
+    if (sessionProfile && req.session.web?.sourceId === sourceId) {
+      const subscriber = await this.subscriberService.findOne(
+        sessionProfile.id,
+      );
+      if (!subscriber || !req.session.web) {
+        throw new Error('Subscriber session was not persisted in DB');
+      }
+      const thread = await this.threadService.resolveThread({
+        subscriberId: subscriber.id,
+        explicitThreadId: req.session.web.threadId,
+      });
+      req.session.web.profile = subscriber;
+      req.session.web.threadId = thread?.id;
+      req.session.web.sourceId = sourceId;
+
+      return subscriber;
+    }
+
+    req.session.web = undefined;
+
+    const profile = await this.subscriberService.create(buildProfile());
+    req.session.web = { profile, sourceId };
+
+    return profile;
+  }
+
+  /**
+   * Resolves a thread for the given subscriber, optionally using an explicit
+   * thread id. Does not read from or write to the request/session.
+   */
+  async resolveThread(
+    subscriberId: string,
+    explicitThreadId?: string,
+  ): Promise<Thread | null> {
+    return this.threadService.resolveThread({ subscriberId, explicitThreadId });
+  }
+
+  /**
+   * Resolves a thread from the request query/body and writes the result back
+   * to the session. Used by the subscribe/history flows.
+   */
+  async resolveThreadForHistory(
+    req: SocketRequest,
+    subscriberId: string,
+  ): Promise<Thread | null> {
+    const explicitThreadId =
+      this.getThreadIdFromQuery(req) ?? this.getThreadIdFromBody(req);
+    const thread = await this.resolveThread(subscriberId, explicitThreadId);
+    if (req.session.web) {
+      req.session.web.threadId = thread?.id;
+    }
+
+    return thread;
+  }
+}

package/src/extensions/channels/web/{web-channel.settings.ts → settings.schema.ts}

@@ -6,17 +6,14 @@
 
 import z from 'zod';
 
-import { ChannelSetting } from '@/channel/types';
 import { config } from '@/config';
-import { createSettingGroup } from '@/setting/create-setting-group';
-import { buildSettingSeedsFromSchema } from '@/setting/runtime-settings.seed';
 
 export const WEB_CHANNEL_NAME = 'web' as const;
 
 const WEB_ALLOWED_UPLOAD_TYPES =
   'audio/mpeg,audio/x-ms-wma,audio/vnd.rn-realaudio,audio/x-wav,image/gif,image/jpeg,image/png,image/tiff,image/vnd.microsoft.icon,image/vnd.djvu,image/svg+xml,text/css,text/csv,text/html,text/plain,text/xml,video/mpeg,video/mp4,video/quicktime,video/x-ms-wmv,video/x-msvideo,video/x-flv,video/web,application/msword,application/vnd.ms-powerpoint,application/pdf,application/vnd.ms-excel,application/vnd.oasis.opendocument.presentation,application/vnd.oasis.opendocument.tex,application/vnd.oasis.opendocument.spreadsheet,application/vnd.oasis.opendocument.graphics,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.openxmlformats-officedocument.presentationml.presentation,application/vnd.openxmlformats-officedocument.wordprocessingml.document';
 
-export const WEB_CHANNEL_SETTINGS_SCHEMA = z
+export const WEB_CHANNEL_SOURCE_SETTINGS_SCHEMA = z
   .strictObject({
     allowed_domains: z
       .string()
@@ -79,27 +76,3 @@ export const WEB_CHANNEL_SETTINGS_SCHEMA = z
   .meta({
     title: 'Web Channel',
   });
-
-declare global {
-  interface RuntimeSettingRegistry {
-    [WEB_CHANNEL_NAME]: typeof WEB_CHANNEL_SETTINGS_SCHEMA;
-  }
-}
-
-export const WebChannelSettingsGroup = createSettingGroup({
-  group: WEB_CHANNEL_NAME,
-  schema: WEB_CHANNEL_SETTINGS_SCHEMA,
-  scope: 'extension',
-  extensionType: 'channel',
-  extensionName: WEB_CHANNEL_NAME,
-});
-
-export const WEB_CHANNEL_SETTINGS = buildSettingSeedsFromSchema(
-  WEB_CHANNEL_NAME,
-  WEB_CHANNEL_SETTINGS_SCHEMA,
-  {
-    subgroup: 'channel',
-  },
-) as ChannelSetting<typeof WEB_CHANNEL_NAME>[];
-
-export default WebChannelSettingsGroup;

package/src/extensions/channels/web/types.ts

@@ -4,18 +4,21 @@
  * Full terms: see LICENSE.md.
  */
 
+import {
+  SubscriberFull,
+  FileType,
+  Button,
+  WebUrlButton,
+  StdQuickReply,
+} from '@hexabot-ai/types';
 import { z } from 'zod';
 
-import { SubscriberFull } from '@/chat/dto/subscriber.dto';
-import { FileType } from '@/chat/types/attachment';
-import { Button, WebUrlButton } from '@/chat/types/button';
-import { StdQuickReply } from '@/chat/types/quick-reply';
-
 export namespace Web {
   export type RequestSession = {
     web?: {
       profile: SubscriberFull;
       threadId?: string;
+      sourceId?: string;
     };
   };
 

package/src/extensions/helpers/local-storage/index.helper.ts

@@ -9,6 +9,7 @@ import os from 'os';
 import { isAbsolute, join, relative, resolve } from 'path';
 import { Readable, Stream } from 'stream';
 
+import type { Attachment } from '@hexabot-ai/types';
 import {
   Injectable,
   NotFoundException,
@@ -18,7 +19,6 @@ import {
 import sanitizeFilename from 'sanitize-filename';
 
 import {
-  Attachment,
   AttachmentCreateDto,
   AttachmentMetadataDto,
 } from '@/attachment/dto/attachment.dto';

package/src/extensions/index.ts

@@ -6,13 +6,13 @@
 
 export * from './channels/console/index.channel';
 
-export * from './channels/console/console-channel.settings';
+export * from './channels/console/settings.schema';
 
 export * from './channels/web/base-web-channel';
 
 export * from './channels/web/index.channel';
 
-export * from './channels/web/web-channel.settings';
+export * from './channels/web/settings.schema';
 
 export * from './channels/web/types';