@sayren/store-sdk 0.29.7 → 0.30.0

package/src/schemas/webhook-event.ts

@@ -380,6 +380,25 @@ export const productOutOfStockWebhookEventSchema = z.object({
   data: productOutOfStockWebhookEventDataSchema,
 });
 
+/**
+ * 플로우 알림(이슈 #115) — 상점이 플로우에 둔 알림 블록(`core.notify`, 채널 `webhook`)이 보낸다. 구매자 알림(알림톡·메일)은 이 이벤트를 받아
+ * 상점이 보낸다(플랫폼은 구매자에게 직접 보내지 않는다). 개인정보는 싣지 않는다
+ */
+export const flowNotificationWebhookEventDataSchema = z.object({
+  orderId: z.string().describe("주문 ID"),
+  orderItemIds: z.array(z.string()).describe("이 알림의 주문상품(묶음 진행이면 여럿)"),
+  event: z.string().describe("상점이 블록에 둔 알림 이름(`custom.<이름>`)"),
+  flowId: z.string(),
+  flowVersion: z.number().int(),
+  state: z.string().describe("알림을 보낸 전이의 도착 상태 키"),
+});
+
+export const flowNotificationWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("ORDER.FLOW_NOTIFICATION"),
+  data: flowNotificationWebhookEventDataSchema,
+});
+
 /** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
 export const webhookEventSchema = z
   .discriminatedUnion("type", [
@@ -390,6 +409,7 @@ export const webhookEventSchema = z
     inquiryWebhookEventSchema,
     reviewWebhookEventSchema,
     productOutOfStockWebhookEventSchema,
+    flowNotificationWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",
@@ -406,3 +426,40 @@ export type WebhookEventOf<T extends WebhookEventType> = WebhookEvent extends in
       : never
     : never
   : never;
+
+/**
+ * 알려진 웹훅 이벤트 타입 — `webhookEventSchema`의 판별 값 목록(이 SDK 버전이 아는 것).
+ * 서버는 새 타입을 구독한 엔드포인트에만 보내지만, 구독을 더 넓힌 수신자를 위해 `parseWebhookEvent`가 모르는 타입을 따로 받는다.
+ */
+export const KNOWN_WEBHOOK_EVENT_TYPES: readonly WebhookEventType[] =
+  webhookEventSchema.options.flatMap((option) => {
+    const type = option.shape.type;
+    return "options" in type
+      ? [...(type.options as WebhookEventType[])]
+      : [type.value as WebhookEventType];
+  });
+
+/** 이 SDK 버전이 모르는 이벤트 — 봉투만 검증하고 `data`는 그대로 둔다 */
+export const unknownWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.string().min(1),
+  data: z.unknown(),
+});
+export type UnknownWebhookEvent = z.infer<typeof unknownWebhookEventSchema>;
+
+export type ParsedWebhookEvent =
+  | { known: true; event: WebhookEvent }
+  | { known: false; event: UnknownWebhookEvent };
+
+/**
+ * 웹훅 본문을 `type`으로 먼저 판별해 읽는다(이슈 #115 결정 25). 알려진 타입은 그 타입의 스키마로 엄격하게 읽고 틀리면 던진다 —
+ * `z.union([known, unknown])`처럼 읽으면 알려진 타입의 파싱 실패가 `known: false`로 조용히 새어 수신자가 처리할 이벤트를 버린다.
+ * 모르는 타입은 봉투만 검증해 `known: false`로 돌려준다(새 이벤트에 옛 SDK가 깨지지 않는다).
+ */
+export function parseWebhookEvent(body: unknown): ParsedWebhookEvent {
+  const type = (body as { type?: unknown } | null)?.type;
+  if (typeof type === "string" && (KNOWN_WEBHOOK_EVENT_TYPES as readonly string[]).includes(type)) {
+    return { known: true, event: webhookEventSchema.parse(body) };
+  }
+  return { known: false, event: unknownWebhookEventSchema.parse(body) };
+}