@nodus-lib/nodus 0.0.14 → 0.0.16

package/README.md

@@ -1,11 +1,6 @@
-# next-session-inspector
+# Nodus SDK
 
-Next.js 미들웨어에서 세션 쿠키(`nodus_session`)를 발급하고 유지하는 경량 패키지입니다.
-
-## 요구 사항
-
-- Node.js `>=18.18.0`
-- Next.js `>=14` (peer dependency)
+Next.js에서 방문, 활성화, 매출 이벤트를 Nodus 서버로 전송하는 SDK입니다.
 
 ## 설치
 
@@ -13,64 +8,99 @@ Next.js 미들웨어에서 세션 쿠키(`nodus_session`)를 발급하고 유지
 npm install @nodus-lib/nodus
 ```
 
-## 사용법
+## 환경 변수
+
+```env
+NODUS_SITE_KEY=site_xxx
+```
 
-앱 루트의 `middleware.ts`에서 그대로 내보냅니다.
+브라우저 클라이언트에서 이벤트를 보낼 때는 Next.js public 환경 변수도 사용할 수 있습니다.
 
-```ts
-export { middleware, config } from "@nodus-lib/nodus";
+```env
+NEXT_PUBLIC_NODUS_SITE_KEY=site_xxx
 ```
 
-또는 한 파일에서 감싸서 추가 로직을 실행할 수 있습니다.
+## 방문 로그 설정
+
+방문 로그는 Next.js 요청 정보를 사용하므로 서버의 Proxy 또는 Middleware에서 설정합니다.
+
+### Next.js 16 이상
+
+Next.js 16부터 `middleware.ts`는 `proxy.ts`로 이름이 변경되었습니다.
 
 ```ts
+import { nodus_visit } from "@nodus-lib/nodus/server";
 import type { NextRequest } from "next/server";
-import { middleware as baseMiddleware } from "@nodus-lib/nodus";
 
-export function middleware(request: NextRequest) {
-  const response = baseMiddleware(request);
+export function proxy(request: NextRequest) {
+  return nodus_visit(request);
+}
 
-  // 추가 로직
+export const config = {
+  matcher: [
+    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+  ],
+};
+```
 
-  return response;
+### Next.js 15 이하
+
+Next.js 15 이하에서는 `middleware.ts`를 사용합니다.
+
+```ts
+import { nodus_visit } from "@nodus-lib/nodus/server";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  return nodus_visit(request);
 }
 
-export { config } from "@nodus-lib/nodus";
+export const config = {
+  matcher: [
+    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+  ],
+};
 ```
 
-## 환경 변수
+`nodus_visit`은 `nodus_session` 쿠키를 생성하거나 재사용하고, 현재 URL과 referer를 방문 이벤트로 전송합니다.
 
-방문 이벤트를 Nodus로 전송하려면 사이트 키를 설정합니다.
+## AARRR 퍼널 이벤트
 
-```env
-NODUS_SITE_KEY=site_xxx
-```
+`nodus_activation`과 `nodus_revenue`는 AARRR 퍼널 분석에서 참고한 이벤트입니다.
 
-사이트 키가 없으면 세션 쿠키만 발급하고 방문 이벤트는 전송하지 않습니다.
+- `nodus_activation`: 사용자가 핵심 기능을 경험했을 때 기록합니다.
+- `nodus_revenue`: 결제, 구매, 구독 전환처럼 매출과 관련된 행동을 기록합니다.
 
-## 동작
+이 함수들은 브라우저에서 실행되는 클라이언트 전용 함수입니다. React 컴포넌트에서 사용할 때는 `"use client"`가 필요합니다.
 
-- 쿠키 이름: `nodus_session`
-- 기존 쿠키가 있으면 재사용합니다.
-- 쿠키가 없으면 `crypto.randomUUID()`로 새 세션 ID를 생성합니다.
-- 쿠키 옵션: `httpOnly`, `sameSite: "lax"`, `secure: true`, `path: "/"`
-- 쿠키 최대 수명: 1년
+```tsx
+"use client";
 
-## config.matcher
+import { nodus_activation, nodus_revenue } from "@nodus-lib/nodus/client";
 
-기본 matcher는 정적 자산, API, favicon 등을 제외한 페이지 중심 경로에 적용됩니다.
+export function PricingActions() {
+  return (
+    <>
+      <button onClick={() => nodus_activation("무료_체험_시작_클릭")}>
+        Start
+      </button>
+      <button onClick={() => nodus_revenue("결제_완료")}>
+        Paid
+      </button>
+    </>
+  );
+}
+```
 
-제외되는 기본 경로:
+## 세션
 
-- `/api`
-- `/_next/static`
-- `/_next/image`
-- `/favicon.ico`
-- `/sitemap.xml`
-- `/robots.txt`
+- 쿠키 이름: `nodus_session`
+- 쿠키 수명: 1년
+- 쿠키 옵션: `sameSite: "lax"`, `secure: true`, `path: "/"`
+- 서버와 클라이언트는 같은 `nodus_session` 쿠키를 사용합니다.
 
-필요하면 앱의 `middleware.ts`에서 `config`를 직접 정의해 덮어쓸 수 있습니다.
+클라이언트 이벤트가 같은 세션을 읽어야 하므로 `nodus_session` 쿠키는 `httpOnly`로 설정하지 않습니다.
 
 ## 라이선스
 
-MIT. 자세한 내용은 `LICENSE` 파일을 참고하세요.
+MIT

package/dist/next/nodus_client.js

@@ -3,9 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.nodus_activation = nodus_activation;
 exports.nodus_revenue = nodus_revenue;
 const nodus_server_caller_1 = require("../logger/nodus-server-caller");
+const nodus_client_manager_1 = require("../session/nodus-client-manager");
 const nodus_manager_1 = require("../session/nodus-manager");
 function nodus_activation(feature) {
-    const sessionId = (0, nodus_manager_1.nodus_session_manager)();
+    const sessionId = (0, nodus_client_manager_1.nodus_session_manager)();
     if (nodus_manager_1.nodus_key) {
         (0, nodus_server_caller_1.nodus_server_caller)({
             data: {
@@ -19,7 +20,7 @@ function nodus_activation(feature) {
     }
 }
 function nodus_revenue(tag) {
-    const sessionId = (0, nodus_manager_1.nodus_session_manager)();
+    const sessionId = (0, nodus_client_manager_1.nodus_session_manager)();
     if (nodus_manager_1.nodus_key) {
         (0, nodus_server_caller_1.nodus_server_caller)({
             data: {

package/dist/next/nodus_server.d.ts

@@ -1,2 +1,2 @@
-import { NextRequest } from "next/server";
-export declare function nodus_visit(request: NextRequest): void;
+import { NextRequest, NextResponse } from "next/server";
+export declare function nodus_visit(request: NextRequest): NextResponse<unknown>;

package/dist/next/nodus_server.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nodus_visit = nodus_visit;
+const server_1 = require("next/server");
 const nodus_server_caller_1 = require("../logger/nodus-server-caller");
 const nodus_manager_1 = require("../session/nodus-manager");
+const nodus_server_manager_1 = require("../session/nodus-server-manager");
 function nodus_visit(request) {
-    const sessionId = (0, nodus_manager_1.nodus_session_manager)();
+    const response = server_1.NextResponse.next();
+    const sessionId = (0, nodus_server_manager_1.nodus_request_session_manager)(request, response);
     if (nodus_manager_1.nodus_key) {
         (0, nodus_server_caller_1.nodus_server_caller)({
             data: {
@@ -16,4 +19,5 @@ function nodus_visit(request) {
             key: nodus_manager_1.nodus_key,
         });
     }
+    return response;
 }

package/dist/session/nodus-client-manager.d.ts

@@ -0,0 +1 @@
+export declare function nodus_session_manager(): string;

package/dist/session/nodus-client-manager.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodus_session_manager = nodus_session_manager;
+const nodus_manager_1 = require("./nodus-manager");
+function nodus_session_manager() {
+    const existingSession = get_cookie(nodus_manager_1.COOKIE_NAME);
+    if (existingSession) {
+        return existingSession;
+    }
+    const sessionId = crypto.randomUUID() + "-" + Date.now();
+    set_cookie(nodus_manager_1.COOKIE_NAME, sessionId);
+    return sessionId;
+}
+function get_cookie(name) {
+    const cookie = document.cookie
+        .split("; ")
+        .find((row) => row.startsWith(`${name}=`));
+    return cookie ? decodeURIComponent(cookie.split("=")[1] ?? "") : null;
+}
+function set_cookie(name, value) {
+    document.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=${nodus_manager_1.COOKIE_MAX_AGE_SECONDS}; samesite=lax; secure`;
+}

package/dist/session/nodus-manager.d.ts

@@ -1,4 +1,3 @@
 export declare const COOKIE_NAME = "nodus_session";
 export declare const COOKIE_MAX_AGE_SECONDS: number;
 export declare const nodus_key: string | undefined;
-export declare function nodus_session_manager(): string;

package/dist/session/nodus-manager.js

@@ -1,25 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nodus_key = exports.COOKIE_MAX_AGE_SECONDS = exports.COOKIE_NAME = void 0;
-exports.nodus_session_manager = nodus_session_manager;
 exports.COOKIE_NAME = "nodus_session";
 exports.COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
 exports.nodus_key = process.env.NODUS_SITE_KEY ?? process.env.NEXT_PUBLIC_NODUS_SITE_KEY;
-function nodus_session_manager() {
-    const existingSession = get_cookie(exports.COOKIE_NAME);
-    if (existingSession) {
-        return existingSession;
-    }
-    const sessionId = crypto.randomUUID() + "-" + Date.now();
-    set_cookie(exports.COOKIE_NAME, sessionId);
-    return sessionId;
-}
-function get_cookie(name) {
-    const cookie = document.cookie
-        .split("; ")
-        .find((row) => row.startsWith(`${name}=`));
-    return cookie ? decodeURIComponent(cookie.split("=")[1] ?? "") : null;
-}
-function set_cookie(name, value) {
-    document.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=${exports.COOKIE_MAX_AGE_SECONDS}; samesite=lax; secure`;
-}

package/dist/session/nodus-server-manager.d.ts

@@ -0,0 +1,2 @@
+import { NextRequest, NextResponse } from "next/server";
+export declare function nodus_request_session_manager(request: NextRequest, response: NextResponse): string;

package/dist/session/nodus-server-manager.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodus_request_session_manager = nodus_request_session_manager;
+const nodus_manager_1 = require("./nodus-manager");
+function nodus_request_session_manager(request, response) {
+    const existingSession = request.cookies.get(nodus_manager_1.COOKIE_NAME)?.value;
+    if (existingSession) {
+        return existingSession;
+    }
+    const sessionId = crypto.randomUUID() + "-" + Date.now();
+    response.cookies.set(nodus_manager_1.COOKIE_NAME, sessionId, {
+        sameSite: "lax",
+        secure: true,
+        path: "/",
+        maxAge: nodus_manager_1.COOKIE_MAX_AGE_SECONDS,
+    });
+    return sessionId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodus-lib/nodus",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "publishConfig": {
     "access": "public"
   },