landom-sdk 0.1.0

package/dist/types/core/context.d.ts

@@ -0,0 +1,7 @@
+import type { SDKConfig } from '../types';
+import type { Logger } from '../utils/logger';
+import type { EventQueue } from './event-queue';
+export declare function setContext(q: EventQueue, c: SDKConfig, l: Logger): void;
+export declare function getQueue(): EventQueue;
+export declare function getConfig(): SDKConfig;
+export declare function getLogger(): Logger;

package/dist/types/core/event-queue.d.ts

@@ -0,0 +1,30 @@
+import type { SDKEvent } from '../types';
+import type { Transport } from '../transport/transport';
+import type { Logger } from '../utils/logger';
+/** EventQueue 생성에 필요한 설정 */
+export interface EventQueueConfig {
+    flushInterval: number;
+    flushQueueSize: number;
+    maxQueueSize: number;
+    beforeSend?: (event: SDKEvent) => SDKEvent | null;
+    transport: Transport;
+    logger: Logger;
+}
+/**
+ * 이벤트 큐 모듈
+ *
+ * 이벤트를 배열에 버퍼링하고, 조건 충족 시 배치 전송한다.
+ * - flushInterval마다 자동 flush
+ * - flushQueueSize 도달 시 즉시 flush
+ * - maxQueueSize 초과 시 오래된 이벤트 드롭
+ * - beforeSend 훅으로 이벤트 가공/필터링
+ */
+export declare function createEventQueue(config: EventQueueConfig): {
+    push: (event: SDKEvent) => void;
+    flush: () => Promise<void>;
+    flushSync: () => void;
+    start: () => void;
+    stop: () => void;
+};
+/** createEventQueue 반환 타입 */
+export type EventQueue = ReturnType<typeof createEventQueue>;

package/dist/types/core/sdk.d.ts

@@ -0,0 +1,27 @@
+import type { SDKOptions, EventType, EventPayload } from '../types';
+/** 이벤트 수집기 인터페이스 (setup/teardown) */
+export interface Collector {
+    setup(): void;
+    teardown(): void;
+}
+/**
+ * SDK 초기화
+ * 싱글턴으로 동작하며, 중복 호출 시 경고만 출력한다.
+ * 이벤트 수집기는 registerCollectors()로 별도 등록한다.
+ */
+export declare function init(options: SDKOptions): void;
+/**
+ * 이벤트 수집기 일괄 등록 및 시작
+ * init() 이후에 호출해야 한다.
+ */
+export declare function registerCollectors(items: Collector[]): void;
+/**
+ * 이벤트를 큐에 추가
+ * 외부에서 커스텀 이벤트를 보낼 때 사용
+ */
+export declare function capture(type: EventType, payload?: EventPayload): void;
+/**
+ * SDK 종료
+ * 모든 수집기 해제 + 잔여 이벤트 flush + 상태 초기화
+ */
+export declare function destroy(): void;

package/dist/types/events/click.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 클릭(click) 이벤트 수집
+ * capture: true로 문서 최상단에서 모든 클릭을 감지
+ */
+export declare function createClickCollector(): Collector;

package/dist/types/events/exit.d.ts

@@ -0,0 +1,7 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 이탈(exit) 이벤트 수집기
+ * beforeunload + visibilitychange로 이탈을 감지
+ * 이탈 직전 보이는 요소와 최대 스크롤 깊이를 기록하고 flushSync로 즉시 전송
+ */
+export declare function createExitCollector(): Collector;

package/dist/types/events/input.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 입력(input) 이벤트 수집기
+ * focus 이벤트로 입력 필드 진입만 1회 기록(  값은 수집하지 않음)
+ */
+export declare function createInputCollector(): Collector;

package/dist/types/events/ping.d.ts

@@ -0,0 +1,7 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 체류 섹션(ping) 이벤트 수집기
+ * IntersectionObserver로 현재 뷰포트에 보이는 섹션을 감지하고
+ * 5초 간격으로 현재 체류 섹션을 보고
+ */
+export declare function createPingCollector(): Collector;

package/dist/types/events/replay.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * rrweb 기반 세션 리플레이 수집기.
+ * 개인정보 보호를 위해 input 값은 기본 마스킹하고, rr-block/rr-mask 클래스를 지원한다.
+ */
+export declare function createReplayCollector(): Collector;

package/dist/types/events/scroll.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 스크롤(scroll) 이벤트 수집기
+ * 500ms trailing-edge 쓰로틀로 스크롤 위치와 비율을 기록
+ */
+export declare function createScrollCollector(): Collector;

package/dist/types/events/start.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 페이지 진입(start) 이벤트 수집
+ * init 시 즉시 start 이벤트를 발행
+ */
+export declare function createStartCollector(): Collector;

package/dist/types/events/visibility.d.ts

@@ -0,0 +1,6 @@
+import type { Collector } from '../core/sdk';
+/**
+ * 탭 전환/최소화(visibility) 이벤트 수집기
+ * visibilitychange 이벤트로 탭 활성/비활성 상태를 추적
+ */
+export declare function createVisibilityCollector(): Collector;

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { init, capture, destroy } from './core/sdk';
+export type { EventType, EventPayload, StartPayload, VisibilityPayload, ScrollPayload, ClickPayload, InputPayload, ReplayPayload, PingPayload, ExitPayload, CustomPayload, SDKEvent, TransportPayload, SDKConfig, SDKOptions, } from './types';

package/dist/types/transport/transport.d.ts

@@ -0,0 +1,23 @@
+import type { TransportPayload } from '../types';
+import type { Logger } from '../utils/logger';
+/** Transport 생성에 필요한 설정 */
+export interface TransportConfig {
+    endpoint: string;
+    apiKey: string;
+    maxRetries: number;
+    logger: Logger;
+}
+/**
+ * 이벤트 전송 모듈
+ *
+ * 두 가지 전송 방식
+ * - send(): fetch(keepalive)로 전송. 커스텀 헤더(X-Project-Key) 사용 가능.
+ * - sendSync(): navigator.sendBeacon으로 전송. 페이지 이탈 시 사용.
+ *   sendBeacon은 커스텀 헤더를 설정할 수 없으므로 body에 apiKey를 포함
+ */
+export declare function createTransport(config: TransportConfig): {
+    send: (payload: TransportPayload) => Promise<boolean>;
+    sendSync: (payload: TransportPayload) => void;
+};
+/** createTransport 반환 타입 */
+export type Transport = ReturnType<typeof createTransport>;

package/dist/types/types/index.d.ts

@@ -0,0 +1,75 @@
+export type EventType = 'start' | 'visibility' | 'scroll' | 'click' | 'input' | 'replay' | 'ping' | 'exit' | 'custom';
+export interface StartPayload {
+}
+export interface VisibilityPayload {
+    isVisible: boolean;
+}
+export interface ScrollPayload {
+    yOffset: number;
+    percentage: number;
+}
+export interface ClickPayload {
+    targetId: string;
+}
+export interface InputPayload {
+    fieldId: string;
+}
+export interface ReplayPayload {
+    event: unknown;
+    isCheckout: boolean;
+    version: 'rrweb';
+}
+export interface CompressedReplayPayload {
+    compressed: true;
+    compression: 'gzip';
+    encoding: 'base64';
+    data: string;
+    version: 'rrweb';
+}
+export interface PingPayload {
+    sectionId: string;
+}
+export interface ExitPayload {
+    lastElementId: string;
+    maxDepth: number;
+}
+export interface CustomPayload {
+    [key: string]: unknown;
+}
+export type EventPayload = StartPayload | VisibilityPayload | ScrollPayload | ClickPayload | InputPayload | ReplayPayload | CompressedReplayPayload | PingPayload | ExitPayload | CustomPayload;
+export interface SDKEvent {
+    type: EventType;
+    timestamp: number;
+    cssSelector: string | null;
+    payload: EventPayload;
+}
+export interface TransportPayload {
+    sessionId: string;
+    userAgent: string;
+    url: string;
+    events: SDKEvent[];
+}
+export interface SDKConfig {
+    apiKey: string;
+    endpoint: string;
+    flushInterval: number;
+    flushQueueSize: number;
+    maxQueueSize: number;
+    maxRetries: number;
+    enableReplay: boolean;
+    replayMaskAllInputs: boolean;
+    replayBlockClass: string;
+    replayBlockSelector?: string;
+    replayMaskTextClass: string;
+    replayMaskTextSelector?: string;
+    replayInlineStylesheet: boolean;
+    replayCheckoutEveryNms: number;
+    replayMousemoveSampling: number | false;
+    replayMousemoveCallbackSampling: number;
+    replayScrollSampling: number;
+    replayInputSampling: 'all' | 'last';
+    beforeSend?: (event: SDKEvent) => SDKEvent | null;
+    debug: boolean;
+}
+export type SDKOptions = Partial<SDKConfig> & Pick<SDKConfig, 'apiKey'>;
+export declare const DEFAULT_CONFIG: Omit<SDKConfig, 'apiKey'>;

package/dist/types/utils/dom.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DOM 요소에서 식별자를 추출한다
+ * 우선순위: #id > tag.firstClass > tag
+ * 클릭, 입력, 이탈 이벤트에서 타겟 요소를 식별하는 데 사용
+ */
+export declare function getElementId(el: Element): string;

package/dist/types/utils/logger.d.ts

@@ -0,0 +1,10 @@
+/** SDK 내부 로거 인터페이스(디버깅용으로 넣음) */
+export interface Logger {
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+/**
+ * 조건부 로거 생성
+ * debug가 true일 때만 콘솔에 [LandOm] 접두사와 함께 출력
+ */
+export declare function createLogger(debug: boolean): Logger;

package/dist/types/utils/selector.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 요소의 CSS selector를 생성한다.
+ * LandOm-LLM의 html_tools/selector_lookup.py:build_css_selector와 동일한 규칙을 따른다.
+ * 규칙이 어긋나면 백엔드의 selector→funnel 매핑이 깨지므로 변경 시 LLM 쪽과 동기화 필수.
+ *
+ * 규칙:
+ *   1) id 속성이 있으면 `tag[id="..."]`를 쓰고 더 이상 위로 올라가지 않는다
+ *   2) 그 외에는 `tag:nth-of-type(N)` (같은 태그명 형제 중 1-based 위치)
+ *   3) 결합자는 ` > ` (직계 자식)
+ *   4) root까지만 올라간다 (기본값 document.body)
+ */
+export declare function buildCssSelector(node: Element, root?: Element): string;

package/dist/types/utils/session.d.ts

@@ -0,0 +1,18 @@
+/** sessionStorage에 저장되는 세션 데이터 */
+interface SessionData {
+    sessionId: string;
+    startedAt: number;
+    lastActivityAt: number;
+}
+/**
+ * UUIDv7 생성
+ * 상위 48비트에 밀리초 타임스탬프를 담아 시간순 정렬
+ */
+export declare function generateUUIDv7(): string;
+/** 기존 세션 반환, 없거나 만료되었으면 새로 생성 */
+export declare function getOrCreateSession(): SessionData;
+/** 마지막 활동 시간 갱신 */
+export declare function touchSession(): void;
+/** 현재 세션 ID 반환 (활동 시간도 갱신) */
+export declare function getSessionId(): string;
+export {};

package/dist/types/utils/throttle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Trailing-edge throttle
+ * 마지막 호출 기준으로 ms 간격마다 한 번씩 실행한다
+ * 스크롤 등 고빈도 이벤트의 호출 횟수를 제한할 때 사용
+ *
+ * 예시 (ms = 500):
+ *   0ms   → 스크롤 100px 들어옴 → lastArgs = 100, 타이머 시작
+ *   50ms  → 스크롤 200px 들어옴 → lastArgs = 200, 타이머 있으니 무시
+ *   100ms → 스크롤 350px 들어옴 → lastArgs = 350, 타이머 있으니 무시
+ *   500ms → 타이머 만료 → fn(350) 실행 (마지막 값만 사용됨)
+ */
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, ms: number): T;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "landom-sdk",
+  "version": "0.1.0",
+  "description": "Lightweight SDK that auto-captures landing page user behavior (clicks, scrolls, inputs, exits, rrweb session replay) and ships it to your analytics backend.",
+  "main": "dist/landom-sdk.cjs.js",
+  "module": "dist/landom-sdk.esm.js",
+  "browser": "dist/landom-sdk.umd.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/landom-sdk.esm.js",
+      "require": "./dist/landom-sdk.cjs.js",
+      "default": "./dist/landom-sdk.umd.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c && tsc -p tsconfig.json",
+    "dev": "rollup -c -w",
+    "test": "jest --passWithNoTests",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DontYouKnowFunnel/LandOm-SDK.git"
+  },
+  "keywords": [
+    "analytics",
+    "landing-page",
+    "user-behavior",
+    "sdk",
+    "event-tracking"
+  ],
+  "author": "Kim Seongmin",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/DontYouKnowFunnel/LandOm-SDK/issues"
+  },
+  "homepage": "https://github.com/DontYouKnowFunnel/LandOm-SDK#readme",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "rollup": "^4.60.0",
+    "rollup-plugin-esbuild": "^6.2.1",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "rrweb": "^2.0.0-alpha.4"
+  }
+}