@fluojs/discord 1.0.2 → 1.0.4

package/README.ko.md

@@ -4,6 +4,8 @@
 
 fluo를 위한 webhook-first, transport-agnostic Discord 전달 코어 패키지입니다. Nest-like 모듈 API, standalone 사용을 위한 주입 가능한 `DiscordService`, 그리고 Node 전용 Discord SDK를 가정하지 않는 `@fluojs/notifications` 연동용 1st-party `DiscordChannel`을 제공합니다.
 
+마이그레이션 경계: 이 모듈 API는 의도적으로 Nest-like이지만 NestJS dynamic-module clone은 아닙니다. `DiscordModule`은 `global: options.global ?? true`로 기본 global이며, `forRootAsync(...)`는 `inject`와 `useFactory`만 지원하고, 내부 provider helper/token은 private으로 유지되어 애플리케이션은 module facade와 export된 service/channel token으로 Discord를 조합해야 합니다.
+
 ## 목차
 
 - [설치](#설치)
@@ -92,12 +94,17 @@ DiscordModule.forRootAsync({
 });
 ```
 
+`forRootAsync(...)`는 fluo async 형태만 받습니다. 필요한 의존성은 애플리케이션 module graph에 먼저 등록하고, token을 `inject`에 나열한 뒤, `useFactory`에서 최종 `DiscordModuleOptions`를 반환하세요. NestJS `imports`, `useClass`, `useExisting` 변형은 소비하지 않으므로 그런 패턴은 Discord에 option을 넘기기 전에 application-owned provider로 옮겨야 합니다.
+
 Behavioral contract 메모:
 
+- `DiscordModule.forRoot(...)`와 `DiscordModule.forRootAsync(...)`는 `DiscordService`, `DiscordChannel`, `DISCORD`, `DISCORD_CHANNEL`을 기본 global로 export합니다. fluo 옵션인 `global?: boolean`을 사용하고, migrated code가 Discord provider를 importing module 안에만 유지해야 할 때만 `global: false`를 설정하세요. NestJS `isGlobal`은 지원하지 않습니다.
 - `DiscordService.send(...)`는 전달 전에 `defaultThreadId`를 해석합니다.
-- 서비스는 모듈 bootstrap 시 transport를 초기화하고, factory가 소유한 리소스만 애플리케이션 shutdown 시 닫습니다.
+- `DiscordService.sendMany(...)`는 `DiscordMessage[]`를 직접 순차 전송하는 batch API이며 `continueOnError`를 지원합니다. 이는 multi-recipient `@fluojs/notifications` dispatch shortcut이 아닙니다.
+- 서비스는 모듈 bootstrap 시 transport를 초기화하고, shutdown 전에 시작된 factory 생성 transport가 아직 완료되지 않았더라도 이를 기다린 뒤 factory가 소유한 리소스를 애플리케이션 shutdown 시 닫습니다.
 - send는 bootstrap이 transport를 `ready`로 표시한 뒤에만 허용됩니다. bootstrap 전, startup 중, bootstrap 실패 후, shutdown 중, shutdown 후 시도는 전달 전에 거부됩니다.
 - 서비스가 shutdown 중이거나 이미 stopped 상태라면 cached transport를 재사용하지 않고 send를 거부합니다.
+- `DiscordService.createPlatformStatusSnapshot()`은 `createDiscordPlatformStatusSnapshot(...)`과 같은 status 계약을 노출합니다. 여기에는 lifecycle/readiness, health, transport kind와 ownership, 기본 thread 구성, bootstrap verification 상태, notifications channel dependency details가 포함되어, 호출자가 내부 옵션에 접근하지 않고도 Discord wiring을 관찰할 수 있습니다.
 - 빈 `defaultThreadId`와 `notifications.channel` 값은 trim 후 무시됩니다. notifications channel은 기본적으로 `discord`입니다.
 - 이 패키지는 절대로 `process.env`를 직접 읽지 않습니다. 모든 설정은 명시적인 옵션 또는 DI를 통해 들어와야 합니다.
 
@@ -144,7 +151,7 @@ Behavioral contract 메모:
 - 하나의 notification dispatch는 정확히 하나의 Discord thread 경로로 매핑됩니다. `payload.threadId` 또는 `recipients`의 단일 항목을 사용해야 합니다.
 - `payload.threadId`가 없으면 `DiscordService.sendNotification(...)`는 첫 번째 `recipients` 항목을 사용하고, 그것도 없으면 `defaultThreadId`로 폴백합니다.
 - notification metadata는 payload metadata, dispatch metadata, template/subject marker를 합쳐 구성됩니다. `template`은 renderer가 구성된 경우에만 렌더링됩니다.
-- 여러 Discord thread로 fan-out이 필요하다면 하나의 multi-recipient dispatch 대신 `sendMany(...)`를 사용해야 합니다.
+- 여러 Discord thread로 fan-out이 필요한 notification workflow라면 thread별 concrete Discord message를 만들어 `DiscordService.sendMany(...)`로 보내거나 별도 notification dispatch를 실행해야 합니다. 하나의 notification dispatch는 multi-recipient fan-out을 암묵적으로 확장하지 않습니다.
 
 ### 명시적 fetch 주입을 사용하는 webhook-first 전달
 
@@ -177,6 +184,7 @@ Discord 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 - 자격 증명이나 webhook URL을 `process.env`에서 직접 읽는 동작
 - 공유 루트 패키지 경계에 Node 전용 Discord SDK를 내장하는 것
 - webhook helper와 export된 transport 계약 이상으로 하나의 provider 전략을 강제하는 것
+- 애플리케이션 import용 내부 provider helper, normalized option token, 또는 NestJS-style custom provider replacement seam을 노출하는 것
 - 하나의 dispatch 호출 안에서 multi-thread fan-out을 자동 변환하는 것
 
 이 제한 사항은 런타임 선택, provider capability, rollout 전략이 애플리케이션 경계에서 명시적으로 결정되도록 하기 위한 package contract의 일부입니다.
@@ -190,12 +198,18 @@ Discord 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 - `DiscordModuleOptions`
 - `DiscordAsyncModuleOptions`
 - `DiscordService`
+- `DiscordService.send(message, options)`
+- `DiscordService.sendMany(messages, options)`
+- `DiscordService.sendNotification(notification, options)`
+- `DiscordService.createPlatformStatusSnapshot()`
 - `DiscordChannel`
 - `DISCORD`
 - `DISCORD_CHANNEL`
 
 애플리케이션 구성은 `DiscordModule`로, notifications 연동은 `DISCORD_CHANNEL`과 export된 transport 계약으로 조합합니다.
 
+이 패키지는 `createDiscordProviders(...)`, `DISCORD_OPTIONS`, `NormalizedDiscordModuleOptions`를 public root barrel에 의도적으로 노출하지 않습니다. 기존 migration이 NestJS 내부 provider token이나 custom provider seam을 바꾸고 있었다면 private helper를 import하지 말고 `DiscordModule.forRoot(...)` / `forRootAsync(...)`를 감싸는 app-owned module을 구성하세요.
+
 ### 계약과 헬퍼
 
 - `DiscordMessage`
@@ -226,6 +240,7 @@ Discord 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 
 ### 상태 및 에러
 
+- `DiscordService.createPlatformStatusSnapshot()`
 - `createDiscordPlatformStatusSnapshot(...)`
 - `DiscordLifecycleState`
 - `DiscordPlatformStatusSnapshot`

package/README.md

@@ -4,6 +4,8 @@
 
 Webhook-first, transport-agnostic Discord delivery core for fluo. It provides a Nest-like module API, an injectable `DiscordService` for standalone usage, and a first-party `DiscordChannel` for `@fluojs/notifications` integration without assuming a Node-only Discord SDK.
 
+Migration boundary: the module API is intentionally Nest-like but not a NestJS dynamic-module clone. `DiscordModule` is global by default through `global: options.global ?? true`, `forRootAsync(...)` supports only `inject` plus `useFactory`, and internal provider helpers/tokens stay private so applications compose Discord through the module facade and exported service/channel tokens.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -92,12 +94,17 @@ DiscordModule.forRootAsync({
 });
 ```
 
+`forRootAsync(...)` accepts the fluo async shape only: register dependencies elsewhere in the application graph, list their tokens in `inject`, and return final `DiscordModuleOptions` from `useFactory`. It does not consume NestJS `imports`, `useClass`, or `useExisting` variants, so migrate those patterns to application-owned providers before passing resolved options to Discord.
+
 Behavioral contract notes:
 
+- `DiscordModule.forRoot(...)` and `DiscordModule.forRootAsync(...)` export `DiscordService`, `DiscordChannel`, `DISCORD`, and `DISCORD_CHANNEL` globally by default. Use the fluo `global?: boolean` option and set `global: false` only when migrated code must keep Discord providers local to importing modules; NestJS `isGlobal` is not supported.
 - `DiscordService.send(...)` resolves `defaultThreadId` before delivery.
-- The service initializes the configured transport during module bootstrap and closes factory-owned resources during application shutdown.
+- `DiscordService.sendMany(...)` is a direct `DiscordMessage[]` batch API that sends messages sequentially and supports `continueOnError`; it is not a multi-recipient `@fluojs/notifications` dispatch shortcut.
+- The service initializes the configured transport during module bootstrap and closes factory-owned resources during application shutdown, including any in-flight factory-created transport before shutdown began.
 - Sends are accepted only after bootstrap marks the transport `ready`; attempts before bootstrap, during startup, after failed bootstrap, while shutting down, or after shutdown are rejected before delivery.
 - Sends attempted while the service is shutting down or already stopped are rejected before reusing the cached transport.
+- `DiscordService.createPlatformStatusSnapshot()` exposes the same status contract as `createDiscordPlatformStatusSnapshot(...)`: lifecycle/readiness, health, transport kind and ownership, default thread configuration, bootstrap verification state, and notifications channel dependency details, so callers can observe Discord wiring without reaching into internal options.
 - Blank `defaultThreadId` and `notifications.channel` values are trimmed and ignored; the notifications channel defaults to `discord`.
 - The package never reads `process.env` directly. All configuration must enter through explicit options or DI.
 
@@ -144,7 +151,7 @@ Behavioral contract notes:
 - One notification dispatch maps to exactly one Discord thread route. Use `payload.threadId` or a single entry in `recipients`.
 - If `payload.threadId` is omitted, `DiscordService.sendNotification(...)` uses the first `recipients` entry or falls back to `defaultThreadId`.
 - Notification metadata is merged from payload metadata, dispatch metadata, and template/subject markers. `template` is rendered only when a renderer is configured.
-- If a notification needs fan-out across multiple Discord threads, call `sendMany(...)` instead of one multi-recipient dispatch.
+- If a notification workflow needs fan-out across multiple Discord threads, create one concrete Discord message per thread with `DiscordService.sendMany(...)` or issue separate notification dispatches; a single notification dispatch never expands multi-recipient fan-out implicitly.
 
 ### Webhook-first delivery with explicit fetch injection
 
@@ -177,6 +184,7 @@ The Discord package intentionally does **not**:
 - read credentials or webhook URLs from `process.env`
 - ship a Node-only Discord SDK inside the shared root package boundary
 - force one provider strategy beyond the webhook-first helper and exported transport contract
+- expose internal provider helpers, normalized option tokens, or NestJS-style custom provider replacement seams for application imports
 - translate one notification into multi-thread fan-out inside a single dispatch call
 
 These limitations are part of the package contract so runtime choice, provider capability, and rollout strategy stay explicit at the application boundary.
@@ -190,12 +198,18 @@ These limitations are part of the package contract so runtime choice, provider c
 - `DiscordModuleOptions`
 - `DiscordAsyncModuleOptions`
 - `DiscordService`
+- `DiscordService.send(message, options)`
+- `DiscordService.sendMany(messages, options)`
+- `DiscordService.sendNotification(notification, options)`
+- `DiscordService.createPlatformStatusSnapshot()`
 - `DiscordChannel`
 - `DISCORD`
 - `DISCORD_CHANNEL`
 
 Compose applications through `DiscordModule` and integrate notifications through `DISCORD_CHANNEL` plus the exported transport contracts.
 
+The package intentionally keeps `createDiscordProviders(...)`, `DISCORD_OPTIONS`, and `NormalizedDiscordModuleOptions` out of the public root barrel. If a migration previously customized NestJS internals or provider tokens, wrap `DiscordModule.forRoot(...)` / `forRootAsync(...)` in an app-owned module instead of importing private helpers.
+
 ### Contracts and helpers
 
 - `DiscordMessage`
@@ -226,6 +240,7 @@ Compose applications through `DiscordModule` and integrate notifications through
 
 ### Status and errors
 
+- `DiscordService.createPlatformStatusSnapshot()`
 - `createDiscordPlatformStatusSnapshot(...)`
 - `DiscordLifecycleState`
 - `DiscordPlatformStatusSnapshot`

package/dist/service.d.ts

@@ -12,9 +12,11 @@ export declare class DiscordService implements Discord, OnModuleInit, OnApplicat
     private readonly options;
     private lifecycleState;
     private resolvedTransport;
+    private shutdownPromise;
     private transportPromise;
     constructor(options: NormalizedDiscordModuleOptions);
     onApplicationShutdown(): Promise<void>;
+    private closeOwnedTransport;
     onModuleInit(): Promise<void>;
     /**
      * Creates a platform status snapshot for the active Discord transport wiring.

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK3E,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,kCAAkC,EAClC,sBAAsB,EAEtB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EAIjB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAyCpB;;;;;;;GAOG;AACH,qBACa,cAAe,YAAW,OAAO,EAAE,YAAY,EAAE,qBAAqB;IAKrE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,gBAAgB,CAAwC;gBAEnC,OAAO,EAAE,8BAA8B;IAE9D,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAetC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBnC;;;;OAIG;IACH,4BAA4B;IAW5B;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyBjG;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA6B1H;;;;;;;;;;;;;;;;OAgBG;IACG,gBAAgB,CACpB,YAAY,EAAE,kCAAkC,EAChD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC;YAiCf,eAAe;IAe7B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,2BAA2B;YAkBrB,kBAAkB;CAejC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK3E,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,kCAAkC,EAClC,sBAAsB,EAEtB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EAIjB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AA+CpB;;;;;;;GAOG;AACH,qBACa,cAAe,YAAW,OAAO,EAAE,YAAY,EAAE,qBAAqB;IAMrE,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,gBAAgB,CAAwC;gBAEnC,OAAO,EAAE,8BAA8B;IAE9D,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;YAgB9B,mBAAmB;IAe3B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCnC;;;;OAIG;IACH,4BAA4B;IAW5B;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0BjG;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA6B1H;;;;;;;;;;;;;;;;OAgBG;IACG,gBAAgB,CACpB,YAAY,EAAE,kCAAkC,EAChD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC;YAiCf,eAAe;IAuB7B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,2BAA2B;YAkBrB,kBAAkB;CAejC"}

package/dist/service.js

@@ -22,6 +22,9 @@ function createLifecycleReadinessError(lifecycleState) {
   }
   return new DiscordTransportError('Discord transport is not ready for delivery.');
 }
+function isShutdownLifecycleState(state) {
+  return state === 'stopping' || state === 'stopped';
+}
 function normalizeOptionalString(value) {
   const trimmed = value?.trim();
   return trimmed && trimmed.length > 0 ? trimmed : undefined;
@@ -46,15 +49,27 @@ class DiscordService {
   }
   lifecycleState = 'created';
   resolvedTransport;
+  shutdownPromise;
   transportPromise;
   constructor(options) {
     this.options = options;
   }
   async onApplicationShutdown() {
+    if (this.lifecycleState === 'stopped') {
+      return;
+    }
+    if (this.shutdownPromise) {
+      return this.shutdownPromise;
+    }
     this.lifecycleState = 'stopping';
+    this.shutdownPromise = this.closeOwnedTransport();
+    return this.shutdownPromise;
+  }
+  async closeOwnedTransport() {
     try {
-      if (this.resolvedTransport && this.options.transport.ownsResources && this.resolvedTransport.close) {
-        await this.resolvedTransport.close();
+      const transport = this.resolvedTransport ?? (this.transportPromise ? await this.transportPromise : undefined);
+      if (transport && this.options.transport.ownsResources && transport.close) {
+        await transport.close();
       }
       this.lifecycleState = 'stopped';
     } catch (error) {
@@ -65,14 +80,26 @@ class DiscordService {
     }
   }
   async onModuleInit() {
+    if (isShutdownLifecycleState(this.lifecycleState)) {
+      return;
+    }
     this.lifecycleState = 'starting';
     try {
       const transport = await this.ensureTransport();
+      if (this.lifecycleState !== 'starting') {
+        return;
+      }
       if (this.options.verifyOnModuleInit && transport.verify) {
         await transport.verify();
       }
+      if (this.lifecycleState !== 'starting') {
+        return;
+      }
       this.lifecycleState = 'ready';
     } catch (error) {
+      if (isShutdownLifecycleState(this.lifecycleState)) {
+        throw error;
+      }
       this.lifecycleState = 'failed';
       throw new Error('Discord transport failed to initialize.', {
         cause: error
@@ -117,6 +144,7 @@ class DiscordService {
     }
     this.assertReadyForSend();
     const transport = await this.ensureTransport();
+    this.assertReadyForSend();
     const normalized = this.normalizeMessage(message);
     assertMessageContent(normalized);
     const result = await transport.send(normalized, options);
@@ -220,6 +248,12 @@ class DiscordService {
     }, options);
   }
   async ensureTransport() {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw createStoppedTransportError();
+    }
+    if (this.lifecycleState === 'failed') {
+      throw createLifecycleReadinessError(this.lifecycleState);
+    }
     if (this.resolvedTransport) {
       return this.resolvedTransport;
     }

package/package.json

@@ -9,7 +9,7 @@
     "portable",
     "fetch"
   ],
-  "version": "1.0.2",
+  "version": "1.0.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.2",
-    "@fluojs/di": "^1.0.2",
-    "@fluojs/notifications": "^1.0.0",
-    "@fluojs/runtime": "^1.1.0"
+    "@fluojs/core": "^1.0.3",
+    "@fluojs/di": "^1.1.0",
+    "@fluojs/notifications": "^1.0.2",
+    "@fluojs/runtime": "^1.1.8"
   },
   "devDependencies": {
     "vitest": "^3.2.4"