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

package/src/chat/dto/subscriber.dto.ts

@@ -4,8 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
+import { subscriberFullSchema, subscriberSchema } from '@hexabot-ai/types';
 import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
-import { Exclude, Expose, Type } from 'class-transformer';
 import {
   IsArray,
   IsDate,
@@ -15,75 +15,14 @@ import {
   IsString,
 } from 'class-validator';
 
-import { Attachment } from '@/attachment/dto/attachment.dto';
 import { ChannelName } from '@/channel/types';
-import { UserProfileAssignedStub } from '@/user/dto/assigned-profile.dto';
-import {
-  UserProfileCreateDto,
-  UserProfileStub,
-} from '@/user/dto/user-profile.dto';
+import { UserProfileCreateDto } from '@/user/dto/user-profile.dto';
 import { IsUUIDv4 } from '@/utils/decorators/is-uuid.decorator';
 import { Validate } from '@/utils/decorators/validate.decorator';
 import { TDto } from '@/utils/types/dto.types';
 
 import { channelDataSchema, SubscriberChannelData } from '../types/channel';
 
-import { Label } from './label.dto';
-
-@Exclude()
-export class SubscriberStub extends UserProfileStub {
-  @Expose()
-  locale: string | null;
-
-  @Expose()
-  gender: string | null;
-
-  @Expose()
-  country: string | null;
-
-  @Expose()
-  foreignId: string;
-
-  @Expose()
-  assignedAt: Date | null;
-
-  @Expose()
-  lastvisit: Date | null;
-
-  @Expose()
-  retainedFrom: Date | null;
-
-  @Expose()
-  channel!: SubscriberChannelData<ChannelName>;
-}
-
-@Exclude()
-export class Subscriber extends SubscriberStub {
-  @Expose({ name: 'labelIds' })
-  labels!: string[];
-
-  @Expose({ name: 'assignedToId' })
-  assignedTo: string | null;
-
-  @Expose({ name: 'avatarId' })
-  avatar: string | null;
-}
-
-@Exclude()
-export class SubscriberFull extends SubscriberStub {
-  @Expose()
-  @Type(() => Label)
-  labels!: Label[];
-
-  @Expose()
-  @Type(() => UserProfileAssignedStub)
-  assignedTo: UserProfileAssignedStub | null;
-
-  @Expose()
-  @Type(() => Attachment)
-  avatar: Attachment | null;
-}
-
 export class SubscriberCreateDto extends UserProfileCreateDto {
   @ApiPropertyOptional({ description: 'Subscriber locale', type: String })
   @IsOptional()
@@ -113,7 +52,7 @@ export class SubscriberCreateDto extends UserProfileCreateDto {
   @ApiPropertyOptional({ description: 'Subscriber foreign id', type: String })
   @IsOptional()
   @IsString()
-  foreignId: string;
+  foreignId: string | null;
 
   @ApiProperty({ description: 'Subscriber labels', type: Array })
   @IsArray()
@@ -172,14 +111,22 @@ export class SubscriberCreateDto extends UserProfileCreateDto {
   @IsString()
   @IsUUIDv4({ message: 'Avatar Attachment ID must be a valid UUID' })
   avatar: string | null;
+
+  @ApiProperty({
+    description: 'Subscriber source',
+    type: String,
+  })
+  @IsString()
+  @IsUUIDv4({ message: 'Source ID must be a valid UUID' })
+  source: string;
 }
 
 export class SubscriberUpdateDto extends PartialType(SubscriberCreateDto) {}
 
 export type SubscriberDto = TDto<
   {
-    plain: typeof Subscriber;
-    full: typeof SubscriberFull;
+    plain: typeof subscriberSchema;
+    full: typeof subscriberFullSchema;
   },
   {
     create: SubscriberCreateDto;

package/src/chat/dto/thread.dto.ts

@@ -4,55 +4,19 @@
  * Full terms: see LICENSE.md.
  */
 
+import { threadFullSchema, threadSchema } from '@hexabot-ai/types';
 import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
-import { Exclude, Expose, Transform, Type } from 'class-transformer';
+import { Type } from 'class-transformer';
 import { IsDate, IsIn, IsOptional, IsString } from 'class-validator';
 
 import { IsUUIDv4 } from '@/utils/decorators/is-uuid.decorator';
-import { BaseStub, TDto } from '@/utils/types/dto.types';
+import { TDto } from '@/utils/types/dto.types';
 
 import {
   THREAD_CLOSE_REASONS,
   THREAD_STATUSES,
 } from '../entities/thread.entity';
 
-import { Subscriber } from './subscriber.dto';
-
-@Exclude()
-export class ThreadStub extends BaseStub {
-  @Expose()
-  status!: 'open' | 'closed';
-
-  @Expose()
-  @Transform(({ value }) => (value == null ? undefined : value))
-  lastMessageAt?: Date | null;
-
-  @Expose()
-  @Transform(({ value }) => (value == null ? undefined : value))
-  closedAt?: Date | null;
-
-  @Expose()
-  @Transform(({ value }) => (value == null ? undefined : value))
-  closeReason?: 'manual' | 'inactivity' | null;
-
-  @Expose()
-  @Transform(({ value }) => (value == null ? undefined : value))
-  title?: string | null;
-}
-
-@Exclude()
-export class Thread extends ThreadStub {
-  @Expose({ name: 'subscriberId' })
-  subscriber!: string;
-}
-
-@Exclude()
-export class ThreadFull extends ThreadStub {
-  @Expose()
-  @Type(() => Subscriber)
-  subscriber!: Subscriber;
-}
-
 export class ThreadCreateDto {
   @ApiProperty({ description: 'Owner subscriber id', type: String })
   @IsString()
@@ -102,12 +66,21 @@ export class ThreadCreateDto {
   closeReason?: 'manual' | 'inactivity' | null;
 }
 
-export class ThreadUpdateDto extends PartialType(ThreadCreateDto) {}
+export class ThreadUpdateDto extends PartialType(ThreadCreateDto) {
+  @ApiPropertyOptional({
+    description: 'Thread source id (immutable)',
+    type: String,
+  })
+  @IsOptional()
+  @IsString()
+  @IsUUIDv4({ message: 'Source must be a valid UUID' })
+  source?: string;
+}
 
 export type ThreadDto = TDto<
   {
-    plain: typeof Thread;
-    full: typeof ThreadFull;
+    plain: typeof threadSchema;
+    full: typeof threadFullSchema;
   },
   {
     create: ThreadCreateDto;

package/src/chat/entities/label-group.entity.ts

@@ -4,25 +4,24 @@
  * Full terms: see LICENSE.md.
  */
 
+import { labelGroupSchema, labelGroupFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, Index, OneToMany } from 'typeorm';
 
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
 import { BaseOrmEntity } from '@/database/entities/base.entity';
 
-import {
-  LabelGroup,
-  LabelGroupDto,
-  LabelGroupFull,
-} from '../dto/label-group.dto';
+import { LabelGroupDto } from '../dto/label-group.dto';
 
 import { LabelOrmEntity } from './label.entity';
 
 @Entity({ name: 'label_groups' })
 @Index(['name'], { unique: true })
 export class LabelGroupOrmEntity extends BaseOrmEntity<LabelGroupDto> {
-  plainCls = LabelGroup;
+  plainCls = labelGroupSchema;
 
-  fullCls = LabelGroupFull;
+  fullCls = labelGroupFullSchema;
 
+  @AuditLabel()
   @Column()
   name!: string;
 

package/src/chat/entities/label.entity.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { labelSchema, labelFullSchema } from '@hexabot-ai/types';
 import {
   Column,
   Entity,
@@ -14,11 +15,12 @@ import {
   RelationId,
 } from 'typeorm';
 
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
 import { JsonColumn } from '@/database/decorators/json-column.decorator';
 import { BaseOrmEntity } from '@/database/entities/base.entity';
 import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
 
-import { Label, LabelDto, LabelFull } from '../dto/label.dto';
+import { LabelDto } from '../dto/label.dto';
 
 import { LabelGroupOrmEntity } from './label-group.entity';
 import { SubscriberOrmEntity } from './subscriber.entity';
@@ -27,10 +29,11 @@ import { SubscriberOrmEntity } from './subscriber.entity';
 @Index(['title'], { unique: true })
 @Index(['name'], { unique: true })
 export class LabelOrmEntity extends BaseOrmEntity<LabelDto> {
-  plainCls = Label;
+  plainCls = labelSchema;
 
-  fullCls = LabelFull;
+  fullCls = labelFullSchema;
 
+  @AuditLabel()
   @Column()
   title!: string;
 

package/src/chat/entities/message.entity.ts

@@ -4,6 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import {
+  messageSchema,
+  messageFullSchema,
+  StdIncomingMessage,
+  StdOutgoingMessage,
+} from '@hexabot-ai/types';
 import {
   Check,
   Column,
@@ -18,8 +24,7 @@ import { BaseOrmEntity } from '@/database/entities/base.entity';
 import { UserOrmEntity } from '@/user/entities/user.entity';
 import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
 
-import { Message, MessageDto, MessageFull } from '../dto/message.dto';
-import { StdIncomingMessage, StdOutgoingMessage } from '../types/message';
+import { MessageDto } from '../dto/message.dto';
 
 import { SubscriberOrmEntity } from './subscriber.entity';
 import { ThreadOrmEntity } from './thread.entity';
@@ -30,9 +35,9 @@ import { ThreadOrmEntity } from './thread.entity';
 )
 @Entity({ name: 'messages' })
 export class MessageOrmEntity extends BaseOrmEntity<MessageDto> {
-  plainCls = Message;
+  plainCls = messageSchema;
 
-  fullCls = MessageFull;
+  fullCls = messageFullSchema;
 
   @Column({ type: 'varchar', length: 255, nullable: true })
   mid?: string | null;

package/src/chat/entities/subscriber.entity.ts

@@ -4,9 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import { subscriberSchema, subscriberFullSchema } from '@hexabot-ai/types';
 import {
+  Check,
   ChildEntity,
   Column,
+  Index,
   JoinColumn,
   JoinTable,
   ManyToMany,
@@ -15,19 +18,15 @@ import {
   UpdateEvent,
 } from 'typeorm';
 
+import type { SourceOrmEntity } from '@/channel/entities/source.entity';
 import { DatetimeColumn } from '@/database/decorators/datetime-column.decorator';
 import { JsonColumn } from '@/database/decorators/json-column.decorator';
-import { UserProfileDto } from '@/user/dto/user-profile.dto';
 import { UserProfileOrmEntity } from '@/user/entities/user-profile.entity';
 import { UserOrmEntity } from '@/user/entities/user.entity';
-import { TDto } from '@/utils';
+import { TZodDto } from '@/utils';
 import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
 
-import {
-  Subscriber,
-  SubscriberDto,
-  SubscriberFull,
-} from '../dto/subscriber.dto';
+import { SubscriberDto } from '../dto/subscriber.dto';
 
 import { LabelOrmEntity } from './label.entity';
 
@@ -40,12 +39,19 @@ export class SubscriberChannel {
 }
 
 @ChildEntity()
+@Index(['source', 'foreignId'])
+@Check(
+  'CHK_SUBSCRIBER_SOURCE_REQUIRED',
+  `"type" != 'SubscriberOrmEntity' OR "source_id" IS NOT NULL`,
+)
 export class SubscriberOrmEntity<
-  Dto extends TDto = SubscriberDto,
+  Dto extends TZodDto = SubscriberDto,
 > extends UserProfileOrmEntity<Dto> {
-  plainCls = Subscriber;
+  plainCls: Dto['transformers']['plain'] =
+    subscriberSchema as Dto['transformers']['plain'];
 
-  fullCls = SubscriberFull;
+  fullCls: Dto['transformers']['full'] =
+    subscriberFullSchema as Dto['transformers']['full'];
 
   @Column({ type: 'varchar', length: 5, nullable: true })
   locale: string | null;
@@ -59,6 +65,20 @@ export class SubscriberOrmEntity<
   @Column({ type: 'varchar', length: 64 })
   foreignId: string;
 
+  @ManyToOne('SourceOrmEntity', {
+    // STI (`users` table) stores both subscribers and operators.
+    // Keep the column nullable at the DB level, and enforce non-null for
+    // Subscriber rows via `CHK_SUBSCRIBER_SOURCE_REQUIRED`.
+    nullable: true,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({ name: 'source_id' })
+  @AsRelation()
+  source: SourceOrmEntity;
+
+  @RelationId((subscriber: SubscriberOrmEntity) => subscriber.source)
+  private readonly sourceId!: string;
+
   @ManyToMany(() => LabelOrmEntity, (label) => label.users, {
     cascade: false,
   })
@@ -87,7 +107,7 @@ export class SubscriberOrmEntity<
   })
   @JoinColumn({ name: 'assigned_to_id' })
   @AsRelation()
-  assignedTo: UserProfileOrmEntity<UserProfileDto> | null;
+  assignedTo: UserProfileOrmEntity<any> | null;
 
   @RelationId((subscriber: SubscriberOrmEntity) => subscriber.assignedTo)
   private readonly assignedToId: string | null;

package/src/chat/entities/thread.entity.ts

@@ -4,14 +4,17 @@
  * Full terms: see LICENSE.md.
  */
 
+import { threadSchema, threadFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, JoinColumn, ManyToOne, RelationId } from 'typeorm';
 
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
+import { SourceOrmEntity } from '@/channel/entities/source.entity';
 import { DatetimeColumn } from '@/database/decorators/datetime-column.decorator';
 import { EnumColumn } from '@/database/decorators/enum-column.decorator';
 import { BaseOrmEntity } from '@/database/entities/base.entity';
 import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
 
-import { Thread, ThreadDto, ThreadFull } from '../dto/thread.dto';
+import { ThreadDto } from '../dto/thread.dto';
 
 import { SubscriberOrmEntity } from './subscriber.entity';
 
@@ -25,9 +28,9 @@ export type ThreadCloseReason = (typeof THREAD_CLOSE_REASONS)[number];
 
 @Entity({ name: 'threads' })
 export class ThreadOrmEntity extends BaseOrmEntity<ThreadDto> {
-  plainCls = Thread;
+  plainCls = threadSchema;
 
-  fullCls = ThreadFull;
+  fullCls = threadFullSchema;
 
   @ManyToOne(() => SubscriberOrmEntity, {
     nullable: false,
@@ -40,6 +43,17 @@ export class ThreadOrmEntity extends BaseOrmEntity<ThreadDto> {
   @RelationId((thread: ThreadOrmEntity) => thread.subscriber)
   private readonly subscriberId!: string;
 
+  @ManyToOne(() => SourceOrmEntity, {
+    nullable: false,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({ name: 'source_id' })
+  @AsRelation()
+  source!: SourceOrmEntity;
+
+  @RelationId((thread: ThreadOrmEntity) => thread.source)
+  private readonly sourceId!: string;
+
   @EnumColumn({ enum: THREAD_STATUSES, default: 'open' })
   status!: ThreadStatus;
 
@@ -52,6 +66,7 @@ export class ThreadOrmEntity extends BaseOrmEntity<ThreadDto> {
   @EnumColumn({ enum: THREAD_CLOSE_REASONS, nullable: true })
   closeReason?: ThreadCloseReason | null;
 
+  @AuditLabel()
   @Column({ name: 'title', type: 'varchar', length: 255, nullable: true })
   title?: string | null;
 }

package/src/chat/helpers/README.md

@@ -1,6 +1,6 @@
 # Envelope Helpers : Envelope Builder & Envelope Factory
 
-The envelope helpers introduce two key components to streamline outgoing message envelope creation: the **Envelope Builder** and the **Envelope Factory**. Together, they offer a comprehensive solution for constructing and validating messages in various formats with minimal boilerplate.
+The envelope helpers introduce two key components to streamline outgoing message envelope creation: the **Envelope Builder** and the **Envelope Factory**. Together, they offer a comprehensive solution for constructing and validating messages in various types with minimal boilerplate.
 
 ---
 
@@ -27,8 +27,8 @@ The envelope helpers introduce two key components to streamline outgoing message
 - **Schema Validation:**  
   Uses Zod to validate envelopes against predefined schemas, ensuring message integrity and compliance with expected formats.
 
-- **Format-Specific Construction:**  
-  Pre-configured through `getEnvelopeBuilder` to support various message formats (text, quick replies, buttons, attachment, carousel, list, and system).
+- **Type-Specific Construction:**  
+  Pre-configured through `getEnvelopeBuilder` to support various message types (text, quick reply, buttons, attachment, carousel, list, and system).
 
 ### Envelope Factory
 
@@ -52,12 +52,12 @@ The envelope helpers introduce two key components to streamline outgoing message
 
 ```typescript
 // Build a simple text envelope:
-const env1 = EnvelopeBuilder(OutgoingMessageFormat.text)
+const env1 = EnvelopeBuilder(OutgoingMessageType.text)
   .setText('Hello')
   .build();
 
 // Append multiple quick replies:
-const env2 = EnvelopeBuilder(OutgoingMessageFormat.quickReplies)
+const env2 = EnvelopeBuilder(OutgoingMessageType.quickReply)
   .setText('Are you interested?')
   .appendToQuickReplies({
     content_type: QuickReplyType.text,
@@ -98,7 +98,7 @@ const quickRepliesEnvelope = envelopeFactory.buildQuickRepliesEnvelope(
   The Envelope Builder leverages JavaScript Proxies to intercept property accesses, enabling both setter and getter behaviors, as well as dynamic array appending for enhanced flexibility.
 
 - **Type Safety with Generics:**  
-  Both components use TypeScript generics and strict typing to ensure that each envelope adheres to its specific format, reducing runtime errors and enforcing schema compliance.
+  Both components use TypeScript generics and strict typing to ensure that each envelope adheres to its specific type, reducing runtime errors and enforcing schema compliance.
 
 - **Schema Mapping:**  
-  A mapping between message formats and their corresponding Zod schemas guarantees that envelopes are built and validated against the correct structure.
+  A mapping between message types and their corresponding Zod schemas guarantees that envelopes are built and validated against the correct structure.