@sayren/store-sdk 0.17.0 → 0.19.0

package/src/schemas/storefront-hosting.ts

@@ -0,0 +1,283 @@
+import { z } from "zod";
+import { RESERVED_STORE_CODES } from "./store";
+
+/**
+ * 스토어프론트 호스팅 (이슈 #53, M1: 템플릿 발행) — 관리 API `/v1/storefront/**`의 계약이다.
+ *
+ * 셀러는 템플릿을 골라 사이트를 만들고 `{slug}.{호스팅 도메인}` 주소를 받는다. 발행은 버전 단위이고,
+ * 되돌리기는 이전 버전을 다시 발행하는 것이다(재빌드 없음). 상태의 원천은 api DB이고 Cloudflare 쪽 반영
+ * (라우팅 표·사이트 Worker)은 커밋 뒤 비동기다 — 반영 상태는 `provisioning`으로 본다.
+ *
+ * 스코프는 조회 `storefront:r`, 쓰기 `storefront:rw`(역할 OWNER·ADMIN)다. 에이전트(MCP)의 발행·되돌리기·템플릿 변경·
+ * 공개 전환·슬러그 변경·호스팅 끄기는 승인(`APPROVAL_REQUIRED`)이다 — 구매자가 보는 화면을 바꾸는 쓰기다.
+ *
+ * 오류 코드:
+ * - 403 `STOREFRONT_HOSTING_DISABLED` — 플랫폼 스위치가 꺼져 새 사이트를 만들 수 없다
+ * - 404 `STOREFRONT_SITE_NOT_FOUND` · `STOREFRONT_TEMPLATE_NOT_FOUND` · `STOREFRONT_VERSION_NOT_FOUND`
+ * - 409 `STOREFRONT_SITE_EXISTS` — 이미 사이트가 있다(스토어당 1개)
+ * - 409 `STOREFRONT_SLUG_TAKEN` — 다른 사이트가 쓰거나 보류 중인 슬러그다
+ * - 409 `STOREFRONT_SLUG_CHANGE_LIMIT` — 슬러그는 스토어당 30일에 3번까지 바꾼다
+ * - 409 `STOREFRONT_SITE_CREATE_LIMIT` — 사이트는 스토어당 30일에 3번까지 만든다
+ * - 409 `STOREFRONT_SITE_CHANGED` — 읽은 상태(`expected*`)와 현재 상태가 다르다. 다시 읽고 시도한다
+ * - 409 `STOREFRONT_SITE_NOT_ACTIVE` — 정지(`SUSPENDED`)된 사이트는 바꾸거나 끌 수 없다
+ * - 409 `STOREFRONT_VERSION_NOT_READY` — 빌드가 끝나지 않았거나 실패한 버전은 발행할 수 없다
+ * - 409 `STOREFRONT_NO_ROLLBACK_TARGET` — 되돌릴 이전 발행 버전이 없다
+ * - 400 `STOREFRONT_SLUG_CONFIRM_MISMATCH` — 호스팅 끄기 확인 입력이 현재 슬러그와 다르다
+ * - 503 `STOREFRONT_PREVIEW_NOT_CONFIGURED` — 미리보기 서명 키가 설정되지 않았다
+ */
+
+// ─── 슬러그 ───────────────────────────────────────────────
+
+/**
+ * 슬러그 형식 — 스토어 코드와 같은 DNS 라벨 규칙(소문자·숫자·하이픈 3~30자, 하이픈으로 시작·끝 불가)에
+ * 연속 하이픈 금지를 더한다. `--`는 버전 미리보기 주소(`v3--{slug}`)와 punycode(`xn--`)가 쓰는 구분자다.
+ */
+export const STOREFRONT_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+
+/** 호스팅 도메인에서 플랫폼이 쓰거나 쓸 이름 — 스토어 코드 예약어에 호스팅 전용 이름을 더한다 */
+export const RESERVED_STOREFRONT_SLUGS: readonly string[] = [
+  ...RESERVED_STORE_CODES,
+  "mcp",
+  "preview",
+  "previews",
+  "sayren",
+  "shop",
+  "shops",
+  "abuse",
+  "security",
+  "closed",
+  "coming-soon",
+  "suspended",
+  "dispatch",
+  "control",
+  "outbound",
+];
+
+export function isReservedStorefrontSlug(slug: string): boolean {
+  return RESERVED_STOREFRONT_SLUGS.includes(slug.toLowerCase());
+}
+
+export const storefrontSlugSchema = z
+  .string()
+  .regex(
+    STOREFRONT_SLUG_PATTERN,
+    "소문자·숫자·하이픈 3~30자여야 하고 하이픈으로 시작하거나 끝날 수 없습니다",
+  )
+  .refine((slug) => !slug.includes("--"), "하이픈을 연달아 쓸 수 없습니다")
+  .refine((slug) => !isReservedStorefrontSlug(slug), "플랫폼이 쓰는 이름이라 쓸 수 없습니다")
+  .describe("주소 슬러그. `{slug}.{호스팅 도메인}`이 사이트 주소가 된다");
+
+/** 바꾼 슬러그를 다른 사이트가 가져가지 못하게 막는 기간(일). 보류 동안 옛 주소는 새 주소로 301한다 */
+export const STOREFRONT_SLUG_HOLD_DAYS = 90;
+/** 슬러그 변경 한도 — 이 기간(일) 안에 */
+export const STOREFRONT_SLUG_CHANGE_WINDOW_DAYS = 30;
+/** 슬러그 변경 한도 — 횟수(스토어 단위. 끄고 다시 만들어도 이어서 센다) */
+export const STOREFRONT_SLUG_CHANGE_LIMIT = 3;
+/** 사이트 만들기 한도 — 같은 창(30일) 안의 횟수(스토어 단위). 끄고 만들기를 되풀이해 이름을 묶어 두지 못하게 한다 */
+export const STOREFRONT_SITE_CREATE_LIMIT = 3;
+
+// ─── 템플릿 ───────────────────────────────────────────────
+
+export const storefrontTemplateSchema = z.object({
+  templateId: z.string().describe("템플릿 id (예: `basic`)"),
+  name: z.string().describe("템플릿 이름"),
+  industry: z.string().describe("업종 (예: `general`·`fashion`·`food`). 목록 필터에 쓴다"),
+  description: z.string().describe("템플릿 설명"),
+  thumbnailUrl: z.string().nullable().describe("썸네일 이미지 주소. 없으면 null"),
+  version: z.string().describe("현재 템플릿 버전. 새 사이트·템플릿 변경은 이 버전으로 만든다"),
+  isDefault: z.boolean().describe("기본 템플릿인가 (스토어 생성 시 자동 생성에 쓴다)"),
+});
+export type StorefrontTemplate = z.infer<typeof storefrontTemplateSchema>;
+
+// ─── 버전 ─────────────────────────────────────────────────
+
+/**
+ * 버전 상태 — M1은 템플릿 빌드 산출물을 그대로 쓰므로 만들 때 곧바로 `READY`다. `BUILDING`·`FAILED`는
+ * 셀러 편집 빌드(M2)가 쓴다. 발행 여부는 상태가 아니라 사이트의 발행 포인터가 원천이다(`published`).
+ */
+export const storefrontVersionStatusSchema = z
+  .enum(["BUILDING", "READY", "FAILED"])
+  .describe("`BUILDING` 빌드 중 · `READY` 발행 가능 · `FAILED` 빌드 실패");
+export type StorefrontVersionStatus = z.infer<typeof storefrontVersionStatusSchema>;
+
+export const storefrontVersionSchema = z.object({
+  versionId: z.string(),
+  number: z.number().int().min(1).describe("사이트 안에서 1부터 늘어나는 번호 (v1, v2…)"),
+  templateId: z.string().describe("이 버전의 기준 템플릿"),
+  templateVersion: z.string().describe("이 버전의 기준 템플릿 버전"),
+  status: storefrontVersionStatusSchema,
+  published: z.boolean().describe("지금 발행된 버전인가"),
+  publishedAt: z
+    .string()
+    .nullable()
+    .describe("마지막으로 발행한 시각 (ISO 8601). 발행한 적 없으면 null"),
+  message: z.string().nullable().describe("버전 메모"),
+  createdByType: z
+    .string()
+    .describe("만든 행위자 유형 (`USER`·`AGENT`·`APP`·`TOKEN`·`SYSTEM`). 늘어날 수 있다"),
+  createdAt: z.string().describe("만든 시각 (ISO 8601)"),
+});
+export type StorefrontVersion = z.infer<typeof storefrontVersionSchema>;
+
+// ─── 사이트 ───────────────────────────────────────────────
+
+export const storefrontSiteStatusSchema = z
+  .enum(["ACTIVE", "SUSPENDED", "CLOSED"])
+  .describe("`ACTIVE` 운영 중 · `SUSPENDED` 운영자 정지 · `CLOSED` 호스팅 끔·스토어 폐쇄");
+export type StorefrontSiteStatus = z.infer<typeof storefrontSiteStatusSchema>;
+
+export const storefrontVisibilitySchema = z
+  .enum(["COMING_SOON", "PUBLIC"])
+  .describe("`COMING_SOON` 오픈 준비 중(방문자에게 준비 중 페이지) · `PUBLIC` 공개");
+export type StorefrontVisibility = z.infer<typeof storefrontVisibilitySchema>;
+
+export const storefrontSourceModeSchema = z
+  .enum(["MANAGED", "CUSTOM"])
+  .describe("`MANAGED` 템플릿 그대로 · `CUSTOM` 한 번이라도 편집함");
+
+export const storefrontDomainSchema = z.object({
+  hostname: z.string().describe("호스트 이름 (예: `mystore.sayren.co`)"),
+  kind: z.enum(["PLATFORM", "CUSTOM"]).describe("`PLATFORM` 슬러그 주소 · `CUSTOM` 내 도메인"),
+  status: z
+    .enum(["ACTIVE", "HELD"])
+    .describe("`ACTIVE` 사용 중 · `HELD` 슬러그를 바꿔 보류 중(새 주소로 301)"),
+  isPrimary: z.boolean().describe("대표 주소인가 (`Store.storefrontUrl`)"),
+  holdUntil: z.string().nullable().describe("보류가 끝나는 시각 (ISO 8601). 보류가 아니면 null"),
+});
+export type StorefrontDomain = z.infer<typeof storefrontDomainSchema>;
+
+/**
+ * 호스팅 반영 상태 — 발행·슬러그·공개 전환은 DB에 먼저 확정되고 Cloudflare 반영은 커밋 뒤에 한다.
+ * `PENDING`이면 반영 중이거나 재시도 대기다(잡이 다시 한다). 반영 뒤에도 라우팅 전파에 최대 1분이 걸린다.
+ */
+export const storefrontProvisioningSchema = z.object({
+  status: z
+    .enum(["SYNCED", "PENDING", "FAILED"])
+    .describe(
+      "`SYNCED` 반영됨 · `PENDING` 반영 대기 · `FAILED` 반영이 여러 번 실패함(자동 재시도는 계속한다)",
+    ),
+  lastErrorCode: z.string().nullable().describe("마지막 반영 실패 코드. 없으면 null"),
+  syncedAt: z.string().nullable().describe("마지막으로 반영한 시각 (ISO 8601)"),
+});
+export type StorefrontProvisioning = z.infer<typeof storefrontProvisioningSchema>;
+
+export const storefrontSiteSchema = z.object({
+  siteId: z.string(),
+  slug: z.string().describe("주소 슬러그"),
+  hostname: z.string().describe("대표 호스트 이름"),
+  url: z.string().describe("대표 주소 (`https://{hostname}`)"),
+  domains: z.array(storefrontDomainSchema).describe("사용 중·보류 중인 호스트 이름"),
+  templateId: z.string().describe("지금 발행된 버전의 템플릿 (발행 전이면 만든 템플릿)"),
+  sourceMode: storefrontSourceModeSchema,
+  status: storefrontSiteStatusSchema,
+  visibility: storefrontVisibilitySchema,
+  publishedVersion: storefrontVersionSchema.nullable().describe("지금 발행된 버전"),
+  provisioning: storefrontProvisioningSchema,
+  slugChangesRemaining: z
+    .number()
+    .int()
+    .min(0)
+    .describe(`최근 ${STOREFRONT_SLUG_CHANGE_WINDOW_DAYS}일 기준 남은 슬러그 변경 횟수`),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type StorefrontSite = z.infer<typeof storefrontSiteSchema>;
+
+/** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 null. 끈 사이트는 싣지 않는다) */
+export const storefrontHostingSchema = z.object({
+  enabled: z.boolean().describe("새 사이트를 만들 수 있는가 (플랫폼 스위치)"),
+  domain: z.string().describe("호스팅 도메인 (예: `sayren.co`). 사이트 주소는 `{slug}.{domain}`"),
+  site: storefrontSiteSchema.nullable(),
+});
+export type StorefrontHosting = z.infer<typeof storefrontHostingSchema>;
+
+export const storefrontSlugAvailabilitySchema = z.object({
+  slug: z.string(),
+  available: z.boolean(),
+  reason: z
+    .enum(["INVALID", "RESERVED", "TAKEN", "CURRENT"])
+    .nullable()
+    .describe(
+      "쓸 수 없는 이유. `INVALID` 형식 · `RESERVED` 예약어 · `TAKEN` 사용·보류 중 · `CURRENT` 지금 내 슬러그",
+    ),
+});
+export type StorefrontSlugAvailability = z.infer<typeof storefrontSlugAvailabilitySchema>;
+
+// ─── 요청 ─────────────────────────────────────────────────
+
+export const createStorefrontSiteRequestSchema = z.object({
+  templateId: z.string().min(1).max(64).describe("템플릿 id"),
+  slug: storefrontSlugSchema.optional().describe("주소 슬러그. 생략하면 스토어 코드"),
+});
+export type CreateStorefrontSiteRequest = z.infer<typeof createStorefrontSiteRequestSchema>;
+
+export const changeStorefrontTemplateRequestSchema = z.object({
+  templateId: z.string().min(1).max(64).describe("바꿀 템플릿 id"),
+  publish: z
+    .boolean()
+    .optional()
+    .describe("새 버전을 곧바로 발행하는가 (기본 true). false면 버전만 만든다"),
+  message: z.string().max(200).optional().describe("버전 메모"),
+});
+export type ChangeStorefrontTemplateRequest = z.infer<typeof changeStorefrontTemplateRequestSchema>;
+
+/**
+ * 발행·되돌리기 — 발행은 사이트의 발행 포인터를 바꾸는 조건부 쓰기다. `expectedPublishedVersionId`를 주면
+ * 지금 발행 버전이 그 값일 때만 바꾼다(화면을 본 뒤 다른 사람이 바꿨으면 409 `STOREFRONT_SITE_CHANGED`).
+ * 이미 그 버전이 발행돼 있으면 아무것도 바꾸지 않고 200이다(같은 요청의 재실행이 안전하다).
+ */
+export const publishStorefrontVersionRequestSchema = z.object({
+  expectedPublishedVersionId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("화면에서 본 발행 버전 id (발행 전이었으면 null). 생략하면 확인하지 않는다"),
+});
+export type PublishStorefrontVersionRequest = z.infer<typeof publishStorefrontVersionRequestSchema>;
+
+export const rollbackStorefrontRequestSchema = z.object({
+  versionId: z.string().optional().describe("되돌릴 버전. 생략하면 지금 버전 직전에 발행했던 버전"),
+  expectedPublishedVersionId: z.string().nullable().optional(),
+});
+export type RollbackStorefrontRequest = z.infer<typeof rollbackStorefrontRequestSchema>;
+
+export const changeStorefrontSlugRequestSchema = z.object({
+  slug: storefrontSlugSchema,
+});
+export type ChangeStorefrontSlugRequest = z.infer<typeof changeStorefrontSlugRequestSchema>;
+
+export const setStorefrontVisibilityRequestSchema = z.object({
+  visibility: storefrontVisibilitySchema,
+  expectedVisibility: storefrontVisibilitySchema
+    .optional()
+    .describe("화면에서 본 공개 상태. 주면 지금 값이 같을 때만 바꾼다"),
+});
+export type SetStorefrontVisibilityRequest = z.infer<typeof setStorefrontVisibilityRequestSchema>;
+
+/** 호스팅 끄기 — 사이트를 닫고(`CLOSED`) 슬러그를 보류한다. 확인 입력은 현재 슬러그다 */
+export const disableStorefrontHostingRequestSchema = z.object({
+  confirmSlug: z.string().min(1).describe("확인 입력 — 현재 슬러그"),
+});
+export type DisableStorefrontHostingRequest = z.infer<typeof disableStorefrontHostingRequestSchema>;
+
+export const storefrontSlugAvailabilityQuerySchema = z.object({
+  slug: z.string().describe("확인할 슬러그"),
+});
+
+/**
+ * 오픈 준비 중 미리보기 링크 — 콘솔에서 로그인한 OWNER·ADMIN만 받는다(PAT·에이전트 불가). 링크는 5분 안에 한 번 열면
+ * 그 브라우저에 12시간짜리 미리보기 쿠키가 생기고 오픈 준비 중인 사이트의 실제 화면을 본다. 링크를 남에게 넘기면 그 사람도
+ * 볼 수 있으므로 공유하지 않는다.
+ */
+export const createStorefrontPreviewLinkRequestSchema = z.object({
+  path: z.string().max(512).optional().describe("열 경로 (`/`로 시작). 생략하면 `/`"),
+});
+export type CreateStorefrontPreviewLinkRequest = z.infer<
+  typeof createStorefrontPreviewLinkRequestSchema
+>;
+
+export const storefrontPreviewLinkSchema = z.object({
+  url: z.string().describe("미리보기 링크 — 5분 안에 연다"),
+  expiresAt: z.string().describe("링크 만료 시각 (ISO 8601)"),
+});
+export type StorefrontPreviewLink = z.infer<typeof storefrontPreviewLinkSchema>;

package/src/schemas/webhook-event.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { claimStatusSchema, claimTypeSchema } from "./claim";
 import { orderItemStatusSchema } from "./common";
+import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 
 /**
  * 웹훅 발송 형식 (공개 계약). 본문은 얇은 이벤트다. 개인정보를 싣지 않으며
@@ -59,13 +60,11 @@ export const orderWebhookEventDataSchema = z.object({
       "이벤트를 만든 주문상품 ID. 비실물 상품 제공으로 보내는 `ORDER.DELIVERED`에만 실린다. " +
         "택배 배송완료와 그 밖의 주문 이벤트에는 없다",
     ),
-  fulfillmentType: z
-    .string()
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema
     .optional()
     .describe(
-      "이벤트를 만든 주문상품의 상품 유형. 비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 이 값이 `SHIPPING`이 아니다. " +
-        "현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. " +
-        "비실물 제공이 아닌 이벤트에는 없고, 없으면 `SHIPPING`으로 읽는다",
+      "이벤트를 만든 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57). " +
+        "비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 `type`이 `SHIPPING`이 아니다. `orderItemId`가 있는 이벤트에만 실린다",
     ),
 });
 export type OrderWebhookEventData = z.infer<typeof orderWebhookEventDataSchema>;
@@ -79,15 +78,18 @@ export const orderFulfilledWebhookEventDataSchema = z.object({
   orderId: z.string().describe("주문 ID"),
   orderItemId: z.string().describe("제공한 주문상품 ID"),
   status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
-  fulfillmentType: z
-    .string()
-    .describe(
-      "상품 유형. 현재 값은 `DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다",
-    ),
-  fulfillmentMode: z
-    .string()
-    .nullable()
-    .describe("제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리)"),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
+    "제공한 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57)",
+  ),
+  fulfillment: z
+    .object({
+      mode: z
+        .string()
+        .describe(
+          "실제 제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리). 주문상품 제공 기록의 `mode`와 같다",
+        ),
+    })
+    .describe("제공 기록"),
   fulfilledAt: z.string().describe("제공 시각 (ISO 8601). 주문상품의 `deliveredAt`과 같다"),
   testPayment: z
     .boolean()