@ahhaohho/event-publisher 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @ahhaohho/event-publisher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+서비스가 도메인 이벤트("무슨 일이 있었다")를 EventBridge 버스로 발행하는 SDK. 이벤트 이름과 payload 스키마(Zod) 카탈로그가 이 패키지에 있어서 발행자와 소비자(notification-server 캠페인 엔진 등)가 같은 계약을 쓴다.
+
+- 설계: 이벤트 기반 범용 메시징 서비스 설계 (Trello 상위 카드 `achs1sX1`, 이 패키지 카드 `QLvlv7As`)
+- 런타임: Node 20+, CommonJS, `zod@^4`
+
+## 발행
+
+```ts
+import { createEventPublisher } from '@ahhaohho/event-publisher';
+
+// 서버 기동 시 1회
+export const events = createEventPublisher({ source: 'ao-crew-server' });
+void events.verifyBus(); // 버스 이름이 틀리면 error 로그 (아래 ⚠️ 참고)
+
+// 사건 지점에서 — 기다리지 않고 부른다
+void events.publish('crew.featured.selected', {
+  galleryId,
+  authorUserId,
+  postType: 'challenge',
+  challengeId,
+  result: 'created',
+});
+```
+
+`publish(name, payload, options?)`
+
+- envelope(`eventId`, `occurredAt`, `source`, `version`, `actorId`, `subjectUserIds`)를 자동으로 채운다. `actorId`·`subjectUserIds`는 카탈로그가 payload에서 꺼내고, `options`로 덮어쓸 수 있다.
+- payload를 Zod로 검증하고, **스키마에 없는 필드는 버린다**(PII가 실수로 버스에 실리지 않게).
+- 보내기 직전에 envelope 전체를 소비자와 같은 스키마로 다시 검증한다. 옵션으로 덮어쓴 `eventId`(영숫자·`-_.:` 1~128자), `actorId`·`subjectUserIds`(ObjectId)가 틀리면 보내지 않는다 — "발행은 성공, 소비자에서 버려짐"을 막는다.
+- **절대 reject하지 않는다.** 결과는 `{ ok: true, eventId, attempts, skipped? }` 또는 `{ ok: false, reason, error }`로 돌려준다.
+  - `reason`: `invalid_payload` | `invalid_envelope` | `unknown_event` | `too_large`(256KB 초과) | `publish_failed`
+- 실패하면 같은 `eventId`로 지수 백오프 재시도(기본 3회, full jitter: 0~min(2s, 200ms·2ⁿ⁻¹)). 권한·설정 오류(AccessDenied, ResourceNotFound 등)는 재시도하지 않는다.
+- 로그에는 이벤트 이름·eventId·오류만 남기고 payload 값은 남기지 않는다.
+- outbox(DB 트랜잭션과 묶은 보장 발행)는 없다. 중요 이벤트에 한해 후속 작업으로 붙인다.
+
+### actorId 규칙
+
+`actorId`에는 **JWT로 검증한 사용자 id만** 넣는다. body·query·`user-id` 헤더 값을 쓰지 않는다. 어드민 id를 서비스까지 전달하지 않는 지점(피처드 지정, 어드민 숨김 등)은 `actorId: null`이 된다.
+
+### 설정
+
+| 옵션 | 환경변수 | 기본값 |
+|------|----------|--------|
+| `busName` | `EVENT_BUS_NAME` | 없음 → 발행 꺼짐 |
+| `enabled` | `EVENT_PUBLISHER_ENABLED` (`'false'`면 끔) | busName이 있으면 켜짐 |
+| `region` | `AWS_REGION` | `ap-northeast-2` |
+| `credentials` | `EVENT_PUBLISHER_CREDENTIALS` (`default`면 SDK 기본 체인) | `'instance'` — EC2 인스턴스 역할(IMDS) 명시 |
+| `client` | — | 위 자격증명으로 생성 |
+| `logger` | — | console |
+| `retry` | — | `{ maxAttempts: 3, baseDelayMs: 200, maxDelayMs: 2000, timeoutMs: 5000 }` (시도당 제한 시간 — 넘으면 실패로 보고 재시도) |
+
+꺼져 있으면 payload 검증만 하고 `{ ok: true, skipped: 'disabled' }`를 돌려준다. 버스가 만들어지기 전에 코드를 먼저 배포해도 된다. 단, `EVENT_PUBLISHER_ENABLED=false`로 명시적으로 끈 경우가 아니면 `EVENT_BUS_NAME` 누락은 생성 시 warn 로그로 남는다(env 누락으로 조용히 꺼지는 것 방지).
+
+> ⚠️ **EventBridge는 없는 버스로의 PutEvents도 성공으로 응답한다** (2026-11-09 실측). `EVENT_BUS_NAME`이 틀리면 이벤트가 조용히 사라진다. 서버 기동 시 `verifyBus()`를 호출해 로그로 확인할 것.
+
+### 자격증명 — 기본 체인을 쓰지 않는다
+
+메시징 권한(`ahhaohho-messaging-{env}-app` 정책)은 인스턴스 역할 `ssm-ec2-role`에만 붙어 있다. 서버 `.env`에는 `AWS_PROFILE=sms-sender`(notification-server staging/prod)나 S3용 `AWS_ACCESS_KEY_ID`(gallery 등)가 있어서, SDK 기본 체인을 쓰면 그 키로 발행하다 prod에서 **AccessDenied**가 난다. dev에는 프로필이 없어 역할로 떨어지므로 dev 테스트로는 잡히지 않는다. 그래서 기본값을 `fromInstanceMetadata()`로 명시한다(4PSMbfSQ 결정, 2026-11-09). EC2 밖 로컬 개발에서는 `EVENT_PUBLISHER_CREDENTIALS=default`를 쓴다.
+
+## 소비
+
+```ts
+import { parseEvent } from '@ahhaohho/event-publisher';
+
+const res = parseEvent(sqsMessage.Body); // EventBridge→SQS 본문, 또는 envelope
+if (!res.ok) {
+  // 어떤 실패든 삭제하지 말고 DLQ로 보존한다.
+  // unknown_event | unsupported_version → 발행자가 더 새 SDK. 소비자 SDK를 올린 뒤 DLQ redrive
+  return;
+}
+switch (res.event.name) {
+  case 'crew.featured.selected':
+    res.event.payload.authorUserId; // 타입이 좁혀진다
+    break;
+}
+```
+
+중복 처리는 `eventId`로 막는다(EventBridge·SQS는 최소 1회 전달).
+
+## EventBridge 매핑 (IaC 규칙 작성용)
+
+| EventBridge 필드 | 값 |
+|------------------|-----|
+| `EventBusName` | `EVENT_BUS_NAME` |
+| `Source` | `ahhaohho.{source}` (예: `ahhaohho.ao-crew-server`) |
+| `DetailType` | 이벤트 이름 (예: `crew.featured.selected`) |
+| `Time` | `occurredAt` |
+| `Detail` | envelope JSON 전체 |
+
+규칙 패턴 예: `{ "source": [{ "prefix": "ahhaohho." }], "detail-type": [{ "prefix": "crew." }] }`
+
+발행 서버 IAM 권한(인스턴스 역할): `events:PutEvents`, `events:DescribeEventBus` (버스 ARN 한정). DescribeEventBus가 없으면 `verifyBus()`가 AccessDenied로 false를 돌려준다.
+
+버스 이름(env `EVENT_BUS_NAME`)은 스택 `ahhaohho-messaging-{env}`의 output `EventBusName`이다.
+
+## Envelope
+
+```json
+{
+  "eventId": "중복 방지 키 — publish는 UUID v4, Scheduler는 execution-id (영숫자·-_.: 1~128자)",
+  "name": "gallery.post.created",
+  "version": 1,
+  "source": "ao-gallery-server",
+  "occurredAt": "2026-11-05T09:00:00.000Z",
+  "actorId": "행동한 사용자 (JWT 검증값) | null",
+  "subjectUserIds": ["영향받는 사용자"],
+  "payload": {}
+}
+```
+
+대상이 대량인 이벤트(`community.notice.published`)는 `subjectUserIds`를 비우고 소비자가 payload의 그룹 id로 수신자를 정한다.
+
+## 카탈로그
+
+payload에는 id와 작은 사실값만 싣는다. 닉네임·댓글 본문·썸네일 같은 표시용 값은 소비자가 렌더 시점에 조회한다(PII·크기·최신성).
+
+| 이벤트 | 발행 | 현재 호출 지점 | actor | subjects |
+|--------|------|----------------|-------|----------|
+| `gallery.post.created` | gallery | addGallerys.ts (보상·community webhook) | 작성자 | 작성자 |
+| `gallery.reaction.added` | gallery | galleryReaction.ts | 리액션한 사람 | 게시자 |
+| `gallery.post.hidden` | gallery | adminGallery.service.ts | 어드민(있으면) | 작성자 |
+| `gallery.post.deleted` | gallery | adminGallery.service.ts | 어드민(있으면) | 작성자 |
+| `community.comment.created` | community | galleryReply / galleryComment controller | 댓글 작성자 | 게시자 |
+| `community.comment.liked` | community | galleryReply.controller.ts | 좋아요한 사람 | 댓글 작성자 |
+| `community.reaction.added` | community | reaction.controller.ts | 리액션한 사람 | 게시자 |
+| `community.notice.published` | community | announcement.controller.ts | 작성 관리자(있으면) | (비움 — communityId로 해석) |
+| `community.message.sent` | community | message.controller.ts | 보낸 관리자(있으면) | 수신자 목록 (≤4000, 넘으면 나눠 발행) |
+| `crew.featured.selected` | crew | featured.service.ts | 어드민(있으면) | 작성자 |
+| `reward.level.up` | reward | grant.service.ts | 본인 | 본인 |
+| `membership.consent.approved` | membership | completeParentConsent.ts | null (보호자) | 아이 계정 |
+| `membership.profile.created` | membership | createUserProfileService.ts | 본인 | 본인 |
+| `ai.comment.created` | ai-chatbot | comment.service.ts | 봇 계정 | 게시자 |
+| `app.activity.challenge_viewed` | challenge | 챌린지 상세 API | 본인 | 본인 |
+| `app.activity.gallery_post_viewed` | gallery | 갤러리 상세 API | 본인 | 본인 |
+| `app.activity.post_step_viewed` | (POST /activity 수신 서버) | 앱 신호 | 본인 | 본인 |
+| `campaign.schedule.fired` | notification (Scheduler) | — | null | (비움) |
+
+정확한 필드는 `src/catalog/*.ts` 참조.
+
+### 카탈로그 변경 규칙
+
+- optional 필드 추가는 같은 이벤트·같은 `version`에서 한다.
+- 필드 삭제·이름 변경·타입 변경·required 추가처럼 호환 안 되는 변경은 `version`을 올리지 않고 **새 이벤트 이름**(예: `gallery.post.created_v2`)으로 추가한다.
+  1. 새 이름을 카탈로그에 추가하고, 소비자가 구·신 이름을 모두 받도록 먼저 배포
+  2. 발행자를 새 이름으로 전환
+  3. 구 이름 발행이 0이 되면 카탈로그에서 제거
+  - 같은 이름의 version을 올리면 롤아웃 중 구·신 발행자 이벤트를 한쪽 소비자가 읽지 못해 유실된다.
+- 닫힌 enum에 값을 추가하는 것도 호환 안 되는 변경이다(구 SDK가 거부). 발행 서비스가 자주 늘리는 값(보상 action, 숨김 사유)은 `z.string()`으로 둔다.
+- 새 이벤트는 `src/catalog/{domain}.ts`에 추가하고 SDK 버전을 올린다. 소비자가 모르는 이벤트는 `unknown_event` → DLQ로 보존된다.
+
+## 개발
+
+```bash
+npm install
+npm test          # tsx --test
+npm run typecheck
+npm run build     # dist/
+```
+
+배포: 태그 `v*` push → `.github/workflows/publish.yml` (npm Trusted Publishing). CI publish가 막혀 있으면 로컬 `npm publish --otp`. **패키지는 public이어야 한다** — 서버 CI·박스는 npm 토큰 없이 익명으로 설치한다.

package/dist/catalog/ai.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const aiEvents: {
+    /**
+     * 현재 위치: ai-chatbot comment.service.ts postCommentAndNotify → sendNotification(ai_comment).
+     * commentId는 ai-chatbot이 알 수 없어(community ai-reply 응답을 버림) optional.
+     */
+    'ai.comment.created': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        botUserId: z.ZodString;
+        postOwnerUserId: z.ZodString;
+        commentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};

package/dist/catalog/ai.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiEvents = void 0;
+const zod_1 = require("zod");
+const envelope_1 = require("../envelope");
+exports.aiEvents = {
+    /**
+     * 현재 위치: ai-chatbot comment.service.ts postCommentAndNotify → sendNotification(ai_comment).
+     * commentId는 ai-chatbot이 알 수 없어(community ai-reply 응답을 버림) optional.
+     */
+    'ai.comment.created': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ai-chatbot'],
+        description: 'AI 봇이 게시물에 댓글 작성',
+        schema: zod_1.z.object({
+            galleryId: envelope_1.ids.objectId,
+            botUserId: envelope_1.ids.userId,
+            postOwnerUserId: envelope_1.ids.userId,
+            commentId: envelope_1.ids.objectId.optional(),
+        }),
+        actor: (p) => p.botUserId,
+        subjects: (p) => [p.postOwnerUserId],
+    }),
+};

package/dist/catalog/app-activity.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * 앱 활동 신호 (S3 활동 흔적 푸시 / 비활동 트리거용).
+ *
+ * - 서버가 API 호출에서 직접 아는 신호는 해당 서버가 발행한다 (challenge_viewed, gallery_post_viewed).
+ * - 서버가 모르는 화면 단계 신호(post_step_viewed)만 앱이 `POST /activity`로 보내고, 받는 서버가 발행한다.
+ * - userId는 항상 JWT 검증값이다. 요청 body/query의 userId를 쓰지 않는다.
+ * - 단순 접속(lastActiveAt)은 요청마다 이벤트를 만들지 않고 Redis → DB로 따로 반영한다.
+ */
+export declare const appActivityEvents: {
+    'app.activity.challenge_viewed': import("../envelope").EventDefinition<z.ZodObject<{
+        userId: z.ZodString;
+        challengeId: z.ZodString;
+    }, z.core.$strip>>;
+    'app.activity.gallery_post_viewed': import("../envelope").EventDefinition<z.ZodObject<{
+        userId: z.ZodString;
+        galleryId: z.ZodString;
+        communityId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    'app.activity.post_step_viewed': import("../envelope").EventDefinition<z.ZodObject<{
+        userId: z.ZodString;
+        stepId: z.ZodString;
+        flowId: z.ZodString;
+        challengeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};

package/dist/catalog/app-activity.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appActivityEvents = void 0;
+const zod_1 = require("zod");
+const envelope_1 = require("../envelope");
+/**
+ * 앱 활동 신호 (S3 활동 흔적 푸시 / 비활동 트리거용).
+ *
+ * - 서버가 API 호출에서 직접 아는 신호는 해당 서버가 발행한다 (challenge_viewed, gallery_post_viewed).
+ * - 서버가 모르는 화면 단계 신호(post_step_viewed)만 앱이 `POST /activity`로 보내고, 받는 서버가 발행한다.
+ * - userId는 항상 JWT 검증값이다. 요청 body/query의 userId를 쓰지 않는다.
+ * - 단순 접속(lastActiveAt)은 요청마다 이벤트를 만들지 않고 Redis → DB로 따로 반영한다.
+ */
+exports.appActivityEvents = {
+    'app.activity.challenge_viewed': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-challenge-server'],
+        description: '챌린지 상세 API 호출 (S3 A-2-1 흔적)',
+        schema: zod_1.z.object({
+            userId: envelope_1.ids.userId,
+            challengeId: zod_1.z.string().min(1),
+        }),
+        actor: (p) => p.userId,
+        subjects: (p) => [p.userId],
+    }),
+    'app.activity.gallery_post_viewed': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-gallery-server'],
+        description: '갤러리 게시물 상세 API 호출 (S3 A-3 흔적)',
+        schema: zod_1.z.object({
+            userId: envelope_1.ids.userId,
+            galleryId: envelope_1.ids.objectId,
+            communityId: zod_1.z.string().min(1).optional(),
+        }),
+        actor: (p) => p.userId,
+        subjects: (p) => [p.userId],
+    }),
+    'app.activity.post_step_viewed': (0, envelope_1.defineEvent)({
+        version: 1,
+        // POST /activity를 받을 서버는 S3 카드(qSPjswwl)에서 확정 — 우선 notification-server로 둔다.
+        publishers: ['notification-server'],
+        description: '기록하기 단계 화면 진입 — 앱 신호 (S3 A-2-2 흔적)',
+        schema: zod_1.z.object({
+            userId: envelope_1.ids.userId,
+            stepId: zod_1.z.string().min(1),
+            flowId: zod_1.z.string().min(1),
+            challengeId: zod_1.z.string().min(1).optional(),
+        }),
+        actor: (p) => p.userId,
+        subjects: (p) => [p.userId],
+    }),
+};

package/dist/catalog/campaign.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+/**
+ * 캠페인 엔진 내부 이벤트.
+ * campaign.schedule.fired는 EventBridge Scheduler가 버스에 넣는다. notification-server가 스케줄을 만들 때
+ * Scheduler 입력(Detail)을 이 envelope 형태로 구성하고, eventId에는 `<aws.scheduler.execution-id>`(짧은 hex,
+ * UUID 아님 — envelope의 eventId 형식이 이를 허용한다)를 넣는다.
+ */
+export declare const campaignEvents: {
+    'campaign.schedule.fired': import("../envelope").EventDefinition<z.ZodObject<{
+        campaignId: z.ZodString;
+        scheduledAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+};

package/dist/catalog/campaign.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.campaignEvents = void 0;
+const zod_1 = require("zod");
+const envelope_1 = require("../envelope");
+/**
+ * 캠페인 엔진 내부 이벤트.
+ * campaign.schedule.fired는 EventBridge Scheduler가 버스에 넣는다. notification-server가 스케줄을 만들 때
+ * Scheduler 입력(Detail)을 이 envelope 형태로 구성하고, eventId에는 `<aws.scheduler.execution-id>`(짧은 hex,
+ * UUID 아님 — envelope의 eventId 형식이 이를 허용한다)를 넣는다.
+ */
+exports.campaignEvents = {
+    'campaign.schedule.fired': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['notification-server'],
+        description: 'admin-v2에서 등록한 스케줄 캠페인 발화',
+        schema: zod_1.z.object({
+            campaignId: envelope_1.ids.objectId,
+            /** 예정 발화 시각 (ISO 8601) */
+            scheduledAt: zod_1.z.iso.datetime({ offset: true }),
+        }),
+        actor: () => null,
+        subjects: () => [],
+    }),
+};

package/dist/catalog/community.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * 한 이벤트에 직접 싣는 수신자 상한.
+ * recipientUserIds는 payload와 envelope.subjectUserIds에 두 번 직렬화된다 (id당 약 27B × 2).
+ * 256KB 한도에서 여유를 두고 4000으로 잡는다 — 테스트(catalog.test.ts)가 상한 인원으로 실제 크기를 검증한다.
+ * 더 많은 대상은 이벤트를 나눠 발행한다.
+ */
+export declare const MAX_INLINE_RECIPIENTS = 4000;
+export declare const communityEvents: {
+    /**
+     * 현재 위치: ao-community-server galleryReply.controller.ts createReply(커뮤니티 게시물),
+     * galleryComment.controller.ts(비커뮤니티 게시물). authorType 'USER' 댓글만 발행한다.
+     * postOwnerUserId는 gallery 조회 후 알 수 있으므로 그 뒤에 발행한다.
+     */
+    'community.comment.created': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        commentId: z.ZodString;
+        commenterUserId: z.ZodString;
+        postOwnerUserId: z.ZodString;
+        communityId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    /** 현재 위치: ao-community-server galleryReply.controller.ts toggleCommentLike (좋아요 켤 때만) */
+    'community.comment.liked': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        commentId: z.ZodString;
+        likerUserId: z.ZodString;
+        commentOwnerUserId: z.ZodString;
+        communityId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    /**
+     * 현재 위치: ao-community-server reaction.controller.ts toggleReaction (추가·변경 시만).
+     * ⚠️ 현재 컨트롤러는 user-id 헤더 폴백이 있다 — reactorUserId에는 JWT 검증값만 넣을 것.
+     */
+    'community.reaction.added': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        reactorUserId: z.ZodString;
+        postOwnerUserId: z.ZodString;
+        reactionType: z.ZodNumber;
+        isChange: z.ZodDefault<z.ZodBoolean>;
+        communityId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    /**
+     * 현재 위치: ao-community-server announcement.controller.ts (필독 공지 신규 작성 시).
+     * 수신자(커뮤니티 멤버 / 크루 활성 기수 멤버)는 대량이므로 싣지 않는다 — 소비자가 communityId로 해석한다.
+     */
+    'community.notice.published': import("../envelope").EventDefinition<z.ZodObject<{
+        noticeId: z.ZodString;
+        communityId: z.ZodString;
+        parentCommunityId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        isImportant: z.ZodBoolean;
+        authorUserId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    /** 현재 위치: ao-community-server message.controller.ts → notificationService.sendCommunityMessage */
+    'community.message.sent': import("../envelope").EventDefinition<z.ZodObject<{
+        communityId: z.ZodString;
+        messageType: z.ZodString;
+        recipientUserIds: z.ZodArray<z.ZodString>;
+        galleryId: z.ZodOptional<z.ZodString>;
+        senderUserId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};

package/dist/catalog/community.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.communityEvents = exports.MAX_INLINE_RECIPIENTS = void 0;
+const zod_1 = require("zod");
+const envelope_1 = require("../envelope");
+/**
+ * 한 이벤트에 직접 싣는 수신자 상한.
+ * recipientUserIds는 payload와 envelope.subjectUserIds에 두 번 직렬화된다 (id당 약 27B × 2).
+ * 256KB 한도에서 여유를 두고 4000으로 잡는다 — 테스트(catalog.test.ts)가 상한 인원으로 실제 크기를 검증한다.
+ * 더 많은 대상은 이벤트를 나눠 발행한다.
+ */
+exports.MAX_INLINE_RECIPIENTS = 4000;
+exports.communityEvents = {
+    /**
+     * 현재 위치: ao-community-server galleryReply.controller.ts createReply(커뮤니티 게시물),
+     * galleryComment.controller.ts(비커뮤니티 게시물). authorType 'USER' 댓글만 발행한다.
+     * postOwnerUserId는 gallery 조회 후 알 수 있으므로 그 뒤에 발행한다.
+     */
+    'community.comment.created': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-community-server'],
+        description: '게시물에 댓글 작성',
+        schema: zod_1.z.object({
+            galleryId: envelope_1.ids.objectId,
+            commentId: envelope_1.ids.objectId,
+            /** 댓글 작성자 (JWT 검증값) */
+            commenterUserId: envelope_1.ids.userId,
+            postOwnerUserId: envelope_1.ids.userId,
+            /** 비커뮤니티 게시물이면 null */
+            communityId: zod_1.z.string().min(1).nullable().default(null),
+        }),
+        actor: (p) => p.commenterUserId,
+        subjects: (p) => [p.postOwnerUserId],
+    }),
+    /** 현재 위치: ao-community-server galleryReply.controller.ts toggleCommentLike (좋아요 켤 때만) */
+    'community.comment.liked': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-community-server'],
+        description: '댓글 좋아요',
+        schema: zod_1.z.object({
+            galleryId: envelope_1.ids.objectId,
+            commentId: envelope_1.ids.objectId,
+            likerUserId: envelope_1.ids.userId,
+            commentOwnerUserId: envelope_1.ids.userId,
+            communityId: zod_1.z.string().min(1).nullable().default(null),
+        }),
+        actor: (p) => p.likerUserId,
+        subjects: (p) => [p.commentOwnerUserId],
+    }),
+    /**
+     * 현재 위치: ao-community-server reaction.controller.ts toggleReaction (추가·변경 시만).
+     * ⚠️ 현재 컨트롤러는 user-id 헤더 폴백이 있다 — reactorUserId에는 JWT 검증값만 넣을 것.
+     */
+    'community.reaction.added': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-community-server'],
+        description: '커뮤니티 게시물에 리액션 추가/변경',
+        schema: zod_1.z.object({
+            galleryId: envelope_1.ids.objectId,
+            reactorUserId: envelope_1.ids.userId,
+            postOwnerUserId: envelope_1.ids.userId,
+            reactionType: zod_1.z.number().int().min(1).max(5),
+            isChange: zod_1.z.boolean().default(false),
+            communityId: zod_1.z.string().min(1).nullable().default(null),
+        }),
+        actor: (p) => p.reactorUserId,
+        subjects: (p) => [p.postOwnerUserId],
+    }),
+    /**
+     * 현재 위치: ao-community-server announcement.controller.ts (필독 공지 신규 작성 시).
+     * 수신자(커뮤니티 멤버 / 크루 활성 기수 멤버)는 대량이므로 싣지 않는다 — 소비자가 communityId로 해석한다.
+     */
+    'community.notice.published': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-community-server'],
+        description: '커뮤니티 공지 게시',
+        schema: zod_1.z.object({
+            noticeId: envelope_1.ids.objectId,
+            communityId: zod_1.z.string().min(1),
+            /** 크루 기수 커뮤니티면 상위 커뮤니티 id */
+            parentCommunityId: zod_1.z.string().min(1).nullable().default(null),
+            isImportant: zod_1.z.boolean(),
+            /** 작성한 관리자 id — JWT 검증값일 때만 넣는다 (현재 컨트롤러는 body 값을 씀) */
+            authorUserId: envelope_1.ids.userId.optional(),
+        }),
+        actor: (p) => p.authorUserId ?? null,
+        subjects: () => [],
+    }),
+    /** 현재 위치: ao-community-server message.controller.ts → notificationService.sendCommunityMessage */
+    'community.message.sent': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-community-server'],
+        description: '커뮤니티 관리자가 선택 멤버에게 메시지 발송',
+        schema: zod_1.z.object({
+            communityId: zod_1.z.string().min(1),
+            messageType: zod_1.z.string().min(1),
+            recipientUserIds: zod_1.z.array(envelope_1.ids.userId).min(1).max(exports.MAX_INLINE_RECIPIENTS),
+            galleryId: envelope_1.ids.objectId.optional(),
+            /** 보낸 관리자 id — JWT 검증값일 때만 넣는다 (현재 라우트는 인증 없음) */
+            senderUserId: envelope_1.ids.userId.optional(),
+        }),
+        actor: (p) => p.senderUserId ?? null,
+        subjects: (p) => p.recipientUserIds,
+    }),
+};

package/dist/catalog/crew.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const crewEvents: {
+    /**
+     * 현재 위치: ao-crew-server featured.service.ts → notification.service.ts sendFeaturedSelectedNotification.
+     * result가 'created' | 'reactivated'일 때만 발행 ('already'는 발행하지 않음). authorUserId가 비어 있으면 발행하지 않는다.
+     * 파일럿(lMKcsXk9): 기존 HTTP 알림과 병행 발행.
+     */
+    'crew.featured.selected': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        authorUserId: z.ZodString;
+        postType: z.ZodEnum<{
+            challenge: "challenge";
+            common: "common";
+        }>;
+        challengeId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        result: z.ZodEnum<{
+            created: "created";
+            reactivated: "reactivated";
+        }>;
+        adminUserId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};

package/dist/catalog/crew.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crewEvents = void 0;
+const zod_1 = require("zod");
+const envelope_1 = require("../envelope");
+exports.crewEvents = {
+    /**
+     * 현재 위치: ao-crew-server featured.service.ts → notification.service.ts sendFeaturedSelectedNotification.
+     * result가 'created' | 'reactivated'일 때만 발행 ('already'는 발행하지 않음). authorUserId가 비어 있으면 발행하지 않는다.
+     * 파일럿(lMKcsXk9): 기존 HTTP 알림과 병행 발행.
+     */
+    'crew.featured.selected': (0, envelope_1.defineEvent)({
+        version: 1,
+        publishers: ['ao-crew-server'],
+        description: '크루 피처드(작품 선정) 지정',
+        schema: zod_1.z.object({
+            galleryId: envelope_1.ids.objectId,
+            authorUserId: envelope_1.ids.userId,
+            postType: zod_1.z.enum(['challenge', 'common']),
+            /** 챌린지 id (contentsId). ObjectId가 아닐 수 있다. common이면 null */
+            challengeId: zod_1.z.string().min(1).nullable().default(null),
+            /** 'reactivated'면 해제됐다가 다시 지정된 것 */
+            result: zod_1.z.enum(['created', 'reactivated']),
+            /** 지정한 어드민 id — 현재 서비스까지 전달되지 않음. 알 수 있을 때만 */
+            adminUserId: envelope_1.ids.userId.optional(),
+        }),
+        actor: (p) => p.adminUserId ?? null,
+        subjects: (p) => [p.authorUserId],
+    }),
+};

package/dist/catalog/gallery.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export declare const galleryEvents: {
+    /**
+     * 현재 위치: ao-gallery-server addGallerys.ts — 보상 지급(challenge_complete/retry/free_post) + community post-created webhook.
+     * E11000 중복 요청 경로에서는 발행하지 않는다 (부수효과 없는 경로).
+     */
+    'gallery.post.created': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        authorUserId: z.ZodString;
+        type: z.ZodEnum<{
+            challenge: "challenge";
+            common: "common";
+            world: "world";
+        }>;
+        challengeId: z.ZodNullable<z.ZodString>;
+        communityIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        isPrivate: z.ZodBoolean;
+        isRetry: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    /**
+     * 현재 위치: ao-gallery-server galleryReaction.ts notifyReaction (일반 피드 경로).
+     * 리액션 추가·변경 시만 발행, 제거 시 발행하지 않는다. 본인 리액션도 발행하되 소비자가 actor===owner면 알림을 건너뛴다.
+     */
+    'gallery.reaction.added': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        reactorUserId: z.ZodString;
+        postOwnerUserId: z.ZodString;
+        reactionType: z.ZodNumber;
+        isChange: z.ZodDefault<z.ZodBoolean>;
+        communityId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    /** 현재 위치: ao-gallery-server adminGallery.service.ts hideAdminPost → sendAdminNotice(post_hidden) */
+    'gallery.post.hidden': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        authorUserId: z.ZodString;
+        reason: z.ZodString;
+        adminUserId: z.ZodOptional<z.ZodString>;
+        notifyAuthor: z.ZodBoolean;
+    }, z.core.$strip>>;
+    /** 현재 위치: ao-gallery-server adminGallery.service.ts deleteAdminPost → sendAdminNotice(post_deleted) */
+    'gallery.post.deleted': import("../envelope").EventDefinition<z.ZodObject<{
+        galleryId: z.ZodString;
+        authorUserId: z.ZodString;
+        adminUserId: z.ZodOptional<z.ZodString>;
+        notifyAuthor: z.ZodBoolean;
+    }, z.core.$strip>>;
+};