@k-msg/webhook 0.15.0 → 0.17.0

package/README.md

@@ -10,6 +10,7 @@ This package provides:
 
 Note:
 - The default `WebhookService` storage is in-memory. For persistence/advanced workflows, see the exported building blocks such as `EndpointManager` and `DeliveryStore`.
+- This package is runtime-neutral (Edge/Web/Node). Node built-ins are not required by default.
 
 ## Install
 
@@ -22,6 +23,7 @@ bun add @k-msg/webhook
 ## Quickstart (WebhookService)
 
 ```ts
+import { readRuntimeEnv } from "@k-msg/core";
 import {
   WebhookEventType,
   WebhookService,
@@ -35,7 +37,7 @@ const config: WebhookConfig = {
   timeoutMs: 30_000,
   enableSecurity: true,
   // Optional: used when an endpoint does not provide its own secret
-  secretKey: process.env.WEBHOOK_SECRET,
+  secretKey: readRuntimeEnv("WEBHOOK_SECRET"),
   // Optional: algorithm, signatureHeader, signaturePrefix
   enabledEvents: [
     WebhookEventType.MESSAGE_SENT,
@@ -53,7 +55,7 @@ const endpoint = await service.registerEndpoint({
   active: true,
   events: [WebhookEventType.MESSAGE_SENT, WebhookEventType.MESSAGE_FAILED],
   // Optional: endpoint-specific secret (preferred over config.secretKey)
-  secret: process.env.WEBHOOK_SECRET,
+  secret: readRuntimeEnv("WEBHOOK_SECRET"),
   // Optional: per-endpoint retry overrides
   retryConfig: { maxRetries: 5, retryDelayMs: 1000, backoffMultiplier: 2 },
   // Optional: metadata-based filters
@@ -109,6 +111,7 @@ To verify a webhook, you must use the exact raw request body string.
 
 ```ts
 import { Hono } from "hono";
+import { readRuntimeEnv } from "@k-msg/core";
 import { SecurityManager } from "@k-msg/webhook";
 
 const app = new Hono();
@@ -124,7 +127,7 @@ app.post("/webhooks/k-msg", async (c) => {
 
   const signature = c.req.header("X-Webhook-Signature") ?? "";
   const timestamp = c.req.header("X-Webhook-Timestamp") ?? "";
-  const secret = process.env.WEBHOOK_SECRET ?? "";
+  const secret = readRuntimeEnv("WEBHOOK_SECRET") ?? "";
 
   if (!security.verifyTimestamp(timestamp, 300)) {
     return c.json({ error: "Request too old" }, 401);
@@ -164,6 +167,31 @@ await service.registerEndpoint({
 });
 ```
 
+## File Storage Adapter (for `type: "file"`)
+
+`EndpointManager`, `EventStore`, `DeliveryStore`, and `QueueManager` no longer import Node `fs/path` directly.
+When using file persistence, provide `fileAdapter`.
+
+```ts
+import { DeliveryStore, type FileStorageAdapter } from "@k-msg/webhook";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const nodeFileAdapter: FileStorageAdapter = {
+  appendFile: (filePath, data) => fs.appendFile(filePath, data, "utf8"),
+  readFile: (filePath) => fs.readFile(filePath, "utf8"),
+  writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
+  ensureDirForFile: (filePath) =>
+    fs.mkdir(path.dirname(filePath), { recursive: true }),
+};
+
+const store = new DeliveryStore({
+  type: "file",
+  filePath: "./data/deliveries.log",
+  fileAdapter: nodeFileAdapter,
+});
+```
+
 ## Zod Schemas
 
 This package exports Zod schemas for validation:

package/README_ko.md

@@ -10,6 +10,7 @@ HTTP 엔드포인트로 실시간 메시지 이벤트를 전달하기 위한 웹
 
 참고:
 - 기본 `WebhookService` 저장소는 in-memory입니다. 영속 저장/고급 워크플로우가 필요하면 `EndpointManager`, `DeliveryStore` 같은 빌딩 블록을 활용하세요.
+- 이 패키지는 런타임 중립(Edge/Web/Node)으로 동작하며, 기본적으로 Node 내장 모듈에 의존하지 않습니다.
 
 ## 설치
 
@@ -22,6 +23,7 @@ bun add @k-msg/webhook
 ## 빠른 시작 (WebhookService)
 
 ```ts
+import { readRuntimeEnv } from "@k-msg/core";
 import {
   WebhookEventType,
   WebhookService,
@@ -35,7 +37,7 @@ const config: WebhookConfig = {
   timeoutMs: 30_000,
   enableSecurity: true,
   // Optional: 엔드포인트에 secret이 없을 때 fallback으로 사용됩니다.
-  secretKey: process.env.WEBHOOK_SECRET,
+  secretKey: readRuntimeEnv("WEBHOOK_SECRET"),
   // Optional: algorithm, signatureHeader, signaturePrefix
   enabledEvents: [
     WebhookEventType.MESSAGE_SENT,
@@ -53,7 +55,7 @@ const endpoint = await service.registerEndpoint({
   active: true,
   events: [WebhookEventType.MESSAGE_SENT, WebhookEventType.MESSAGE_FAILED],
   // Optional: 엔드포인트별 secret (config.secretKey보다 우선)
-  secret: process.env.WEBHOOK_SECRET,
+  secret: readRuntimeEnv("WEBHOOK_SECRET"),
   // Optional: 엔드포인트별 재시도 설정
   retryConfig: { maxRetries: 5, retryDelayMs: 1000, backoffMultiplier: 2 },
   // Optional: 메타데이터 기반 필터
@@ -109,6 +111,7 @@ ${timestamp}.${rawBody}
 
 ```ts
 import { Hono } from "hono";
+import { readRuntimeEnv } from "@k-msg/core";
 import { SecurityManager } from "@k-msg/webhook";
 
 const app = new Hono();
@@ -123,7 +126,7 @@ app.post("/webhooks/k-msg", async (c) => {
 
   const signature = c.req.header("X-Webhook-Signature") ?? "";
   const timestamp = c.req.header("X-Webhook-Timestamp") ?? "";
-  const secret = process.env.WEBHOOK_SECRET ?? "";
+  const secret = readRuntimeEnv("WEBHOOK_SECRET") ?? "";
 
   if (!security.verifyTimestamp(timestamp, 300)) {
     return c.json({ error: "Request too old" }, 401);
@@ -163,6 +166,31 @@ await service.registerEndpoint({
 });
 ```
 
+## File Storage Adapter (`type: "file"` 사용 시)
+
+`EndpointManager`, `EventStore`, `DeliveryStore`, `QueueManager`는 Node `fs/path`를 직접 import하지 않습니다.
+파일 영속화를 사용하려면 `fileAdapter`를 주입해야 합니다.
+
+```ts
+import { DeliveryStore, type FileStorageAdapter } from "@k-msg/webhook";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const nodeFileAdapter: FileStorageAdapter = {
+  appendFile: (filePath, data) => fs.appendFile(filePath, data, "utf8"),
+  readFile: (filePath) => fs.readFile(filePath, "utf8"),
+  writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
+  ensureDirForFile: (filePath) =>
+    fs.mkdir(path.dirname(filePath), { recursive: true }),
+};
+
+const store = new DeliveryStore({
+  type: "file",
+  filePath: "./data/deliveries.log",
+  fileAdapter: nodeFileAdapter,
+});
+```
+
 ## Zod 스키마
 
 이 패키지는 검증용 Zod 스키마를 export 합니다.
@@ -173,4 +201,3 @@ await service.registerEndpoint({
 ## License
 
 MIT
-

package/dist/dispatcher/batch.dispatcher.d.ts

@@ -2,7 +2,7 @@
  * Batch Webhook Dispatcher
  * 대량 웹훅 요청을 효율적으로 처리하는 배치 디스패처
  */
-import { EventEmitter } from "events";
+import { EventEmitter } from "../shared/event-emitter";
 import type { WebhookBatch } from "../types/webhook.types";
 import type { BatchConfig, DispatchJob } from "./types";
 export declare class BatchDispatcher extends EventEmitter {

package/dist/dispatcher/load-balancer.d.ts

@@ -2,7 +2,7 @@
  * Load Balancer
  * 웹훅 엔드포인트 간의 부하 분산 관리
  */
-import { EventEmitter } from "events";
+import { EventEmitter } from "../shared/event-emitter";
 import type { WebhookEndpoint } from "../types/webhook.types";
 import type { LoadBalancerConfig } from "./types";
 interface EndpointHealth {

package/dist/dispatcher/queue.manager.d.ts

@@ -2,7 +2,7 @@
  * Queue Manager
  * 웹훅 작업 큐 관리 시스템
  */
-import { EventEmitter } from "events";
+import { EventEmitter } from "../shared/event-emitter";
 import type { DispatchJob, QueueConfig } from "./types";
 export declare class QueueManager extends EventEmitter {
     private config;
@@ -11,6 +11,7 @@ export declare class QueueManager extends EventEmitter {
     private mediumPriorityQueue;
     private lowPriorityQueue;
     private delayedJobs;
+    private ttlCleanupInterval;
     private totalJobs;
     private defaultConfig;
     constructor(config?: Partial<QueueConfig>);

package/dist/dispatcher/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Dispatcher Type Definitions
  */
+import type { FileStorageAdapter } from "../shared/file-storage";
 import type { WebhookEndpoint, WebhookEvent } from "../types/webhook.types";
 export interface DispatchConfig {
     maxConcurrentRequests: number;
@@ -20,6 +21,7 @@ export interface QueueConfig {
     maxQueueSize: number;
     persistToDisk: boolean;
     diskPath?: string;
+    fileAdapter?: FileStorageAdapter;
     compressionEnabled: boolean;
     ttlMs: number;
 }

package/dist/index.d.ts

@@ -15,5 +15,6 @@ export { SecurityManager } from "./security/security.manager";
 export { DefaultHttpClient, type HttpClient, MockHttpClient, WebhookDispatcher, } from "./services/webhook.dispatcher";
 export { WebhookRegistry } from "./services/webhook.registry";
 export { WebhookService } from "./services/webhook.service";
+export type { FileStorageAdapter } from "./shared/file-storage";
 export type { WebhookAttempt, WebhookBatch, WebhookConfig, WebhookDelivery, WebhookDeliveryData, WebhookEndpoint, WebhookEndpointData, WebhookEvent, WebhookEventData, WebhookSecurity, WebhookStats, WebhookTestResult, } from "./types/webhook.types";
 export { WebhookDeliverySchema, WebhookEndpointSchema, WebhookEventSchema, WebhookEventType, } from "./types/webhook.types";