@lemoncloud/chatic-sockets-api 0.26.403 → 0.26.517

package/dist/generated/field-registry.d.ts

@@ -0,0 +1,38 @@
+export declare const fieldKeys: {
+    readonly authHead: <T extends object>() => Extract<keyof T, string>[];
+    readonly authModel: <T_1 extends object>() => Extract<keyof T_1, string>[];
+    readonly authTransformerModel: <T_2 extends object>() => Extract<keyof T_2, string>[];
+    readonly callbackHead: <T_3 extends object>() => Extract<keyof T_3, string>[];
+    readonly callbackModel: <T_4 extends object>() => Extract<keyof T_4, string>[];
+    readonly callbackServiceModel: <T_5 extends object>() => Extract<keyof T_5, string>[];
+    readonly callbackTransformerModel: <T_6 extends object>() => Extract<keyof T_6, string>[];
+    readonly channelHead: <T_7 extends object>() => Extract<keyof T_7, string>[];
+    readonly channelModel: <T_8 extends object>() => Extract<keyof T_8, string>[];
+    readonly chatModel: <T_9 extends object>() => Extract<keyof T_9, string>[];
+    readonly connectionModel: <T_10 extends object>() => Extract<keyof T_10, string>[];
+    readonly coreModel: <T_11 extends object>() => Extract<keyof T_11, string>[];
+    readonly deviceHead: <T_12 extends object>() => Extract<keyof T_12, string>[];
+    readonly deviceModel: <T_13 extends object>() => Extract<keyof T_13, string>[];
+    readonly joinModel: <T_14 extends object>() => Extract<keyof T_14, string>[];
+    readonly mockHead: <T_15 extends object>() => Extract<keyof T_15, string>[];
+    readonly mockModel: <T_16 extends object>() => Extract<keyof T_16, string>[];
+    readonly mockTestModel: <T_17 extends object>() => Extract<keyof T_17, string>[];
+    readonly mockTransformerModel: <T_18 extends object>() => Extract<keyof T_18, string>[];
+    readonly searchBatchModel: <T_19 extends object>() => Extract<keyof T_19, string>[];
+    readonly searchModel: <T_20 extends object>() => Extract<keyof T_20, string>[];
+    readonly searchQueryModel: <T_21 extends object>() => Extract<keyof T_21, string>[];
+    readonly socketModel: <T_22 extends object>() => Extract<keyof T_22, string>[];
+    readonly socketsTransformerModel: <T_23 extends object>() => Extract<keyof T_23, string>[];
+    readonly testHead: <T_24 extends object>() => Extract<keyof T_24, string>[];
+    readonly testModel: <T_25 extends object>() => Extract<keyof T_25, string>[];
+    readonly userHead: <T_26 extends object>() => Extract<keyof T_26, string>[];
+    readonly userModel: <T_27 extends object>() => Extract<keyof T_27, string>[];
+    readonly viewTransformerModel: <T_28 extends object>() => Extract<keyof T_28, string>[];
+};
+export declare const fieldRegistryMeta: {
+    readonly kind: "concrete";
+    readonly schemaVersion: 1;
+    readonly entryCount: 29;
+    readonly checksum: "cfe99591dae6d229";
+    readonly generatedBy: "lemon-fields";
+};

package/dist/lib/broadcast/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `lib/broadcast/types.ts`
+ * - broadcast engine 공개 계약 — `DomainEvent` 와 내부 전달 타입.
+ */
+import type { ConnectionModel, DeviceModel } from '../../modules/sockets/model';
+/**
+ * interface: `DomainEvent`
+ * - CDC가 감지한 도메인 사실 1건 — 분류·렌더가 끝난 상태로 발행됨.
+ */
+export interface DomainEvent<T = unknown> {
+    /** 멱등성 키 — Producer가 결정적으로 파생(재시도마다 동일). 생략 시 ingress가 생성 → 재시도 dedupe 불가 */
+    id?: string;
+    /** 계층형 시맨틱 타입 — 클라 핸들러 라우팅 키 (`chat.message.created` ...) */
+    type: string;
+    /** 발생 출처 서비스 */
+    source: string;
+    /** 이벤트 발생 시각 (epoch ms) — 메타데이터, 순서 보장 기준 아님 */
+    ts: number;
+    /** data 스키마 버전 */
+    version: number;
+    /** 행위자 */
+    actor?: string;
+    /** 관련 리소스 (`channel:C1`) */
+    subject: string;
+    /** ── the WHAT ── 일어난 일의 데이터, 클라에 그대로 전달됨 */
+    data: T;
+    /** ── the HOW ── 전달 지시 (producer가 덧붙인 라우팅 메타데이터, Engine 대상) */
+    broadcast: BroadcastDirective;
+}
+/** producer가 덧붙이는 전달 지시 */
+export interface BroadcastDirective {
+    /** 수신 대상 — 도메인 식별자, 해석은 Engine */
+    audience: BroadcastAudience;
+    /** push 알림 — 있으면 push leg 실행. 엔진은 `data`를 해석하지 않고 push 서비스로 verbatim 전달 */
+    push?: PushPayload;
+    /** 제외 대상 */
+    exclude?: BroadcastExclude;
+}
+export declare type BroadcastAudience = {
+    type: 'channel';
+    channelId: string;
+} | {
+    type: 'users';
+    userIds: string[];
+}
+/** 저수준 — deviceIds 직접 지정 (channel/users 해석 생략) */
+ | {
+    type: 'devices';
+    deviceIds: string[];
+};
+/**
+ * push 알림 payload.
+ * - localization 봉투(`*_loc_key`/`loc_args`/`link`/`type`/`silent`)는 APNs·FCM 표준 기반 **푸시 공용 인터페이스** — 엔진이 타입으로 안다.
+ * - `data`만 도메인별이라 `TData` 제네릭으로 열어 둔다 — 엔진은 `data`를 해석하지 않고 verbatim 전달.
+ * - 실제 발송 계약은 push 서비스(`chatic-pushes-api`)의 `ChaticPushPayload`. 의존성 결합을 피하려 엔진이 별도 선언한다.
+ */
+export interface PushPayload<TData = any> {
+    /** notification title localization key */
+    title_loc_key?: string;
+    /** title localization arguments */
+    title_loc_args?: string[];
+    /** notification body localization key */
+    loc_key?: string;
+    /** body localization arguments */
+    loc_args?: string[];
+    /** app deep link (e.g. `channel?channelId=<channelId>`) */
+    link?: string;
+    /** domain event type — required */
+    type: string;
+    /** silent/background notification flag */
+    silent?: boolean;
+    /** custom app data — 도메인별, 엔진은 해석하지 않음 */
+    data: TData;
+}
+export interface BroadcastExclude {
+    userIds?: string[];
+    deviceIds?: string[];
+    connIds?: string[];
+}
+/** 클라이언트가 WS로 받는 공개 페이로드 — `broadcast` 메타데이터 제외 */
+export declare type PublicEvent<T = unknown> = Omit<DomainEvent<T>, 'broadcast'>;
+/** audience 해석 결과 1건 — device + (활성일 때만) connection */
+export interface BroadcastRecipient {
+    device: DeviceModel;
+    /** 활성 커넥션 — 없으면 offline (WS 불가) */
+    connection?: ConnectionModel;
+}
+export interface BroadcastPushResult {
+    sent: number;
+    failed: number;
+    skipped: number;
+}
+/**
+ * interface: `BroadcastResult`
+ * - fan-out 결과 집계.
+ */
+export interface BroadcastResult {
+    /** audience 해석된 대상 device 총수 */
+    total: number;
+    /** 등록 정보를 못 찾아 제외된 device 수 */
+    missing: number;
+    ws: {
+        sent: number;
+        failed: number;
+    };
+    push: BroadcastPushResult;
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `lib/types.ts`
+ * - shared socket packet contracts for both server and client.
+ *
+ * RULES
+ * - every new socket packet type must be registered here first.
+ * - `SocketMessage<T>` payload usage must be derived from this file.
+ * - server/client code should treat this file as the source of truth for packet shapes.
+ */
+/**
+ * common socket message metadata.
+ */
+export interface SocketMessageMeta {
+    /** timestamp (ms) */
+    ts: number;
+    /** extensible metadata bag */
+    [key: string]: unknown;
+}
+/**
+ * base socket message envelope.
+ */
+export interface SocketMessage<T = any, TType extends string = string> {
+    /** message type like `system.ping`, `system.ping:ok`, `system.ping:error` */
+    type: TType;
+    /** payload data */
+    data: T | null;
+    /** request-response correlation id */
+    mid?: string;
+    /** optional metadata */
+    meta?: SocketMessageMeta;
+    /** optional error message */
+    error?: string;
+}
+/**
+ * shared packet registry extension point.
+ *
+ * NOTE
+ * - keep only the base contract here.
+ * - each `src/lib/<domain>/types.ts` can extend this registry via module augmentation.
+ * - response types `:ok` / `:error` are derived from the merged registry.
+ */
+export interface SocketPacketRegistry {
+}
+/**
+ * shorthand alias extension point.
+ * - domain folders can add aliases via module augmentation.
+ */
+export interface SocketPacketAliasRegistry {
+}
+/**
+ * registered request packet type.
+ */
+export declare type SocketPacketType = Extract<keyof SocketPacketRegistry, string>;
+/**
+ * request input type before canonical normalization.
+ */
+export declare type SocketPacketInputType = SocketPacketType | Extract<keyof SocketPacketAliasRegistry, string>;
+/**
+ * resolve shorthand input into canonical packet type.
+ */
+export declare type ResolveSocketPacketType<TType extends SocketPacketInputType> = TType extends keyof SocketPacketAliasRegistry ? SocketPacketAliasRegistry[TType] : TType;
+/**
+ * packet status suffix.
+ */
+export declare type SocketPacketStatus = 'request' | 'ok' | 'error';
+/**
+ * derived success response type.
+ */
+export declare type SocketPacketOkType<TType extends SocketPacketType = SocketPacketType> = `${TType}:ok`;
+/**
+ * derived error response type.
+ */
+export declare type SocketPacketErrorType<TType extends SocketPacketType = SocketPacketType> = `${TType}:error`;
+/**
+ * union of all request/response packet type strings.
+ */
+export declare type SocketMessageType<TType extends SocketPacketType = SocketPacketType> = TType | SocketPacketOkType<TType> | SocketPacketErrorType<TType>;
+/**
+ * request payload of a registered packet.
+ */
+export declare type SocketPacketRequestData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['request'];
+/**
+ * success payload of a registered packet.
+ */
+export declare type SocketPacketResponseData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['response'];
+/**
+ * error payload of a registered packet.
+ */
+export declare type SocketPacketErrorData<TType extends SocketPacketType> = SocketPacketRegistry[TType]['error'];
+/**
+ * typed request message.
+ */
+export declare type SocketRequestMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketRequestData<TType>, TType>;
+/**
+ * typed success message.
+ */
+export declare type SocketResponseMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketResponseData<TType>, SocketPacketOkType<TType>>;
+/**
+ * typed error message.
+ */
+export declare type SocketErrorMessage<TType extends SocketPacketType = SocketPacketType> = SocketMessage<SocketPacketErrorData<TType>, SocketPacketErrorType<TType>>;
+/**
+ * helper to infer request payload from packet type.
+ */
+export declare type InferSocketRequest<TType extends SocketPacketType> = SocketPacketRequestData<TType>;
+/**
+ * helper to infer success payload from packet type.
+ */
+export declare type InferSocketResponse<TType extends SocketPacketType> = SocketPacketResponseData<TType>;
+/**
+ * helper to infer error payload from packet type.
+ */
+export declare type InferSocketError<TType extends SocketPacketType> = SocketPacketErrorData<TType>;
+/**
+ * optional normalized error shape for higher-level usage.
+ * - transport still uses `SocketMessage.error` as the primary field.
+ */
+export interface SocketErrorShape {
+    message: string;
+    code?: string;
+    retryable?: boolean;
+}

package/dist/libs/sockets.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `sockets.ts`
+ * - basic definitions for supporting web-socket w/ AWS API Gateway + Lambda.
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2026-05-06 refactoring for v2 support.
+ *
+ * @copyright   (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NextContext, NextIdentity } from 'lemon-model';
+export type { NextContext };
+export * from '../lib/types';
+/**
+ * interface: `ConnectionInfo`
+ * - 연결 정보 공통 모델
+ */
+export interface ConnectionInfo {
+    /** stage of api-gateway */
+    stage?: string;
+    /** connected domain */
+    domain?: string;
+    /** api-gateway id */
+    apiId?: string;
+    /** (optional) id as decoded from `connectionId` */
+    conId?: string;
+    /** (original) connection-id */
+    connectionId?: string;
+    /** (optional) user-agent */
+    userAgent?: string;
+}
+/**
+ * interface: `ConnectionIdentity`
+ * - common idenity with socket event.
+ */
+export interface ConnectionIdentity extends NextIdentity, ConnectionInfo {
+}
+/**
+ * type: `WSSEventType
+ */
+export declare type SocketEventType = '' | 'CONNECT' | 'DISCONNECT' | 'MESSAGE';
+/**
+ * type: `SocketRouteKeyType`
+ * - must be matched with `sls/functions.socket.events.websocket.route`
+ */
+export declare type SocketRouteKeyType = '$connect' | '$disconnect' | '$default' | 'echo';
+/**
+ * type: `SocketStageType`
+ * - stage in API GW
+ */
+export declare type SocketStageType = '' | 'dev' | 'prod' | 'local';
+export declare type SocketDirectionType = '' | 'IN' | 'OUT';
+/**
+ * interface: `SocketEvent`
+ * - Lambda에서 수신하는 WebSocket 이벤트 (Raw Level)
+ */
+export interface SocketEvent<TBody = any> extends ConnectionInfo {
+    /** request-id */
+    id: string;
+    /** major type of event */
+    type: SocketEventType;
+    /** router-key from api-gateway */
+    route: SocketRouteKeyType;
+    /** known as Headr[Authorization] */
+    authorization?: string;
+    /** stage in api-gw */
+    stage: SocketStageType;
+    /** socket direction */
+    direction: SocketDirectionType;
+    /** code of disconnection */
+    disconnectCode?: number;
+    /** known as disconnectReason */
+    reason?: string;
+    /** known as Header[Origin] */
+    origin?: string;
+    /** known as Header[User-Agent] */
+    agent: string;
+    /** socket message-id */
+    messageId: string;
+    /**
+     * the original base64-encoded string (ex: c8OGXcpSIE0CJuQ=)
+     */
+    connectionId: string;
+    /** connectedAt (ts) */
+    connectedAt: number;
+    /** known as ClientIp */
+    remote: string;
+    /** query parameters */
+    param: {
+        [key: string]: string;
+    };
+    /** body payload in string */
+    body?: TBody;
+}
+/**
+ * type: `SocketEventAgent`
+ * - interface for handling WebSocket events.
+ */
+export interface SocketEventAgent<T = ConnectionIdentity> {
+    /**
+     * Handle incoming WebSocket events.
+     *
+     * @param event SocketEvent - the socket event in lambda
+     * @param context NextContext - the current request's context.
+     * */
+    onSocketEvent(event: SocketEvent, context: NextContext<T>): Promise<any>;
+}

package/dist/modules/chat/model.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `model.ts`
+ * - model definitions for chat module.
+ */
+import { CoreModel } from 'lemon-model';
+import $LUT, { ChannelStereo, ChatStereo, JoinStereo } from './types';
+/**
+ * type: `ModelType`
+ */
+export declare type ModelType = keyof typeof $LUT.ModelType;
+/**
+ * type: `Model`: common model
+ */
+export declare type Model = CoreModel<ModelType>;
+/**
+ * interface: `ChannelHead`
+ */
+export interface ChannelHead {
+    /** id of channel */
+    id?: string;
+    /** name of channel */
+    name?: string;
+}
+/**
+ * interface: `ChannelModel`
+ * - chat room state.
+ */
+export interface ChannelModel extends Model, ChannelHead {
+    /** id of model */
+    id?: string;
+    /** name of channel */
+    name?: string;
+    /** channel stereo */
+    stereo?: ChannelStereo;
+    /** optional description */
+    desc?: string;
+    /** owner id (P1 uses deviceId) */
+    ownerId?: string;
+    /** last chat sequence in this channel */
+    chatNo?: number;
+    /** joined device ids */
+    memberIds?: string[];
+}
+/**
+ * interface: `ChatModel`
+ * - message or channel event.
+ */
+export interface ChatModel extends Model {
+    /** id = `${channelId}:${chatNo}` */
+    id?: string;
+    /** chat event kind */
+    stereo?: ChatStereo;
+    /** channel-local sequence */
+    chatNo?: number;
+    /** message content */
+    content?: string;
+    /** message content type. v1 only uses text. */
+    contentType?: string;
+    /** parent channel id */
+    channelId?: string;
+    /** owner id. v1 uses deviceId. */
+    ownerId?: string;
+}
+/**
+ * interface: `JoinModel`
+ * - channel membership and read cursor.
+ */
+export interface JoinModel extends Model {
+    /** id = `${channelId}:${ownerId}` */
+    id?: string;
+    /** join stereo. v1 only uses empty string. */
+    stereo?: JoinStereo;
+    /** joined channel id */
+    channelId?: string;
+    /** owner id. v1 uses deviceId. */
+    ownerId?: string;
+    /** last read chat sequence */
+    chatNo?: number;
+    /** current joined state. 1 = joined, 0 = left. */
+    joined?: number;
+}
+/**
+ * extract field names from models
+ * - only fields start with lowercase, or all upper.
+ */
+export declare const filterFields: (fields: string[], base?: string[]) => string[];
+/** field names from head */
+export declare const $HEAD: {
+    channel: string[];
+};
+export declare const $FIELD: {
+    channel: string[];
+    chat: string[];
+    join: string[];
+};
+/** must export default as below */
+declare const _default: {
+    $HEAD: {
+        channel: string[];
+    };
+    $FIELD: {
+        channel: string[];
+        chat: string[];
+        join: string[];
+    };
+};
+export default _default;

package/dist/modules/chat/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `types.ts`
+ * - basic types for chat module.
+ */
+/**
+ * Lookup Table
+ *
+ * WARN! DO NOT EXPORT AS `$LUT`. use default export instead.
+ */
+declare const $LUT: {
+    /**
+     * Possible type of model.
+     */
+    ModelType: {
+        /** channel model */
+        channel: string;
+        /** chat model */
+        chat: string;
+        /** join model */
+        join: string;
+    };
+    /**
+     * ChannelStereo
+     */
+    ChannelStereo: {
+        '': string;
+        /** direct message (1:1) */
+        dm: string;
+        /** self memo channel */
+        self: string;
+        /** open channel */
+        public: string;
+        /** invite-only channel */
+        private: string;
+    };
+    /**
+     * ChatStereo
+     */
+    ChatStereo: {
+        text: string;
+        join: string;
+        leave: string;
+        system: string;
+    };
+    /**
+     * JoinStereo
+     */
+    JoinStereo: {
+        '': string;
+    };
+};
+/**
+ * type: `ChannelStereo`
+ */
+export declare type ChannelStereo = keyof typeof $LUT.ChannelStereo;
+/**
+ * type: `ChatStereo`
+ */
+export declare type ChatStereo = keyof typeof $LUT.ChatStereo;
+/**
+ * type: `JoinStereo`
+ */
+export declare type JoinStereo = keyof typeof $LUT.JoinStereo;
+/** must export $LUT as default */
+export default $LUT;

package/dist/modules/mock/model.d.ts

@@ -63,6 +63,11 @@ export interface TestModel extends Model, TestHead {
     count?: number;
     /** (optional) extra */
     extra?: SimpleSet;
+    /**
+     * string array for test of array set
+     * test for inc() method.
+     */
+    strings?: string[];
     /**
      * inner Object.
      */

package/dist/modules/sockets/model.d.ts

@@ -10,7 +10,8 @@
  * Copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
  */
 import { CoreModel } from 'lemon-model';
-import $LUT, { ChannelStereo, DevicePlatform, DeviceStatus } from './types';
+import $LUT, { DevicePlatform, DeviceStatus } from './types';
+import type { ChannelHead } from '../chat/model';
 /**
  * type: `ModelType`
  */
@@ -64,6 +65,10 @@ export interface ConnectionModel extends Model {
     connectedAt?: number;
     /** (internal) Timestamp when the connection was terminated. */
     disConnectedAt?: number;
+    /** (internal) version no */
+    versionNo?: number;
+    /** (internal) tracking no */
+    no?: number;
     /**
      * (extended) The origin of the request.
      */
@@ -94,6 +99,8 @@ export interface ConnectionModel extends Model {
     readonly count?: number;
     /**
      * (linked) 현재 연결이 구독 중인 채널(토픽) ID 목록
+     *
+     * @deprecated no more supported (see `chatic-socials-api`)
      */
     channels?: string[];
     /**
@@ -102,6 +109,9 @@ export interface ConnectionModel extends Model {
     channel$$?: ChannelHead[];
     /**
      * (linked) device id for state sync
+     * NOTE it must be 1:1 matching with device.
+     * - `Device` has the major one connection.
+     * - `Connection` is belong to single `Device`.
      */
     deviceId?: string;
     /** (internal) identity-id */
@@ -115,35 +125,6 @@ export interface ConnectionModel extends Model {
      */
     readonly $device?: DeviceModel;
 }
-/**
- * interface: `ChannelHead`
- * - common head of `ChannelModel`
- */
-export interface ChannelHead {
-    /** id of channel */
-    id?: string;
-    /** name of channel */
-    name?: string;
-}
-/**
- * interface: `ChannelModel`
- * - 웹소켓 접속 채널(room) 관리
- * @deprecated  no longer in use (Channel management has been delegated to chatic-socials-api)
- */
-export interface ChannelModel extends Model, ChannelHead {
-    /** stereo */
-    stereo?: ChannelStereo;
-    /** (internal) alised router-id if stereo=alias */
-    aliasId?: string;
-    /** (internal) the linked router */
-    alias$?: ChannelHead;
-    /** (optional) description of this channel */
-    desc?: string;
-    /** (internal) count of subscribers */
-    subscribed?: number;
-    /** (internal) the linked alias for detailed */
-    readonly $alias?: ChannelModel;
-}
 /**
  * interface: `DeviceHead`
  */
@@ -154,8 +135,11 @@ export interface DeviceHead {
     name?: string;
 }
 /**
- * interface: `DeviceModel`
+ * interface: `DeviceModel` (종단 기기)ㅊ
  * - 디바이스 정보 관리 모델
+ * - 그럼, 여기에서는 ENDPOINT 간의 상태 동기화
+ *
+ * ex) 브라우저 창, 네이티브 앱, 노드기반 클라이언트.
  */
 export interface DeviceModel extends Model, DeviceHead {
     /** device-id (클라이언트에서 생성된 UUID) */
@@ -180,6 +164,13 @@ export interface DeviceModel extends Model, DeviceHead {
     disconnectedAt?: number;
     /** (internal) connection-id */
     connId?: string;
+    /** joined channel ids */
+    channelIds?: string[];
+    /**
+     * (internal) owner user-id
+     * - 푸시 전송 시, 타겟 유저 ID 매핑을 위해 이용됨.
+     * */
+    readonly userId?: string;
 }
 /**
  * extract field names from models
@@ -188,25 +179,21 @@ export interface DeviceModel extends Model, DeviceHead {
 export declare const filterFields: (fields: string[], base?: string[]) => string[];
 /** field names from head */
 export declare const $HEAD: {
-    channel: string[];
     device: string[];
 };
 export declare const $FIELD: {
     socket: string[];
     connection: string[];
-    channel: string[];
     device: string[];
 };
 /** must export default as below */
 declare const _default: {
     $HEAD: {
-        channel: string[];
         device: string[];
     };
     $FIELD: {
         socket: string[];
         connection: string[];
-        channel: string[];
         device: string[];
     };
 };