@sayren/store-sdk 0.16.0 → 0.18.0

package/src/schemas/digital-asset.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * 파일 다운로드 상품의 판매 파일 (이슈 #48 단계 3).
+ *
+ * 파일은 CDN **비공개 객체**다. `POST /v1/uploads`(`purpose: "digital-asset"`)로 자리를 받아 응답의 `headers`와 함께 PUT하고,
+ * 응답의 `key`로 상품에 연결한다. 객체 키와 파일 주소는 어떤 응답에도 싣지 않는다 — 구매자는 제공된 주문상품에서
+ * 수명 300초의 서명 주소로만 받는다. 주문은 주문 시점 파일을 스냅샷하므로 파일을 바꿔도 이미 산 구매자는 옛 파일을 받는다.
+ */
+
+export const digitalAssetAttachRequestSchema = z.object({
+  key: z
+    .string()
+    .min(1)
+    .max(512)
+    .describe("업로드 자리 발급 응답의 `key`. 이 스토어의 비공개 업로드 키여야 한다"),
+  fileName: z.string().trim().min(1).max(200).describe("구매자에게 보일 파일 이름(확장자 포함)"),
+  sizeBytes: z.number().int().positive().optional().describe("파일 크기(바이트). 안내용이다"),
+  contentType: z.string().max(200).optional().describe("파일 형식(MIME). 안내용이다"),
+  variantId: z
+    .string()
+    .optional()
+    .describe("이 파일을 줄 옵션(variant). 생략하면 모든 옵션의 구매자가 받는다"),
+});
+export type DigitalAssetAttachRequest = z.infer<typeof digitalAssetAttachRequestSchema>;
+
+/** 판매 파일 — 객체 키·주소는 싣지 않는다 */
+export const digitalAssetSchema = z.object({
+  assetId: z.string(),
+  productId: z.string(),
+  variantId: z.string().nullable().describe("옵션 전용 파일이면 그 옵션, 모든 옵션 공통이면 null"),
+  fileName: z.string(),
+  contentType: z.string().nullable(),
+  sizeBytes: z.number().int().nullable(),
+  status: z
+    .string()
+    .describe(
+      "`ACTIVE`(새 주문에 제공)·`REMOVED`(해제 — 이미 산 구매자는 계속 받는다). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  createdAt: z.string(),
+});
+export type DigitalAsset = z.infer<typeof digitalAssetSchema>;
+
+/** 셀러 확인용 서명 주소 — `POST /v1/products/{productId}/digital-assets/{assetId}/preview-url` */
+export const digitalAssetPreviewSchema = z.object({
+  url: z.url().describe("수명 300초의 서명 주소"),
+  expiresAt: z.string(),
+});
+export type DigitalAssetPreview = z.infer<typeof digitalAssetPreviewSchema>;
+
+/** 주문상품의 다운로드 제공 정보 — 주문 응답의 `fulfillment.download` */
+export const orderItemDownloadSchema = z.object({
+  count: z.number().int().describe("지금까지 받은 횟수"),
+  limit: z.number().int().describe("받을 수 있는 횟수"),
+  expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
+  firstDownloadedAt: z.string().nullable().describe("처음 받은 시각 — 제공 개시 증거다"),
+  files: z.array(
+    z.object({
+      assetId: z.string(),
+      fileName: z.string(),
+      sizeBytes: z.number().int().nullable(),
+    }),
+  ),
+});
+export type OrderItemDownload = z.infer<typeof orderItemDownloadSchema>;

package/src/schemas/fulfillment-code.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { pageQueryShape, pageSchema } from "./common";
+
+/**
+ * 코드 발급 상품의 코드 풀 (이슈 #48 단계 2) — 라이선스 키·기프트 코드처럼 결제 확정과 함께 한 개씩 배정하는 코드다.
+ *
+ * **평문 코드는 두 경로로만 나간다** — 구매자 열람(`POST /storefront/v1/me/order-items/{id}/fulfillment/reveal`)과 셀러 콘솔
+ * 열람(`POST /v1/fulfillment-codes/{codeId}/reveal`, 콘솔 전용). 목록·주문·웹훅·API 로그에는 가린 값(`hint`)만 싣는다.
+ * 코드는 결제 자격 증명과 같은 키링·AES-256-GCM으로 암호화해 저장한다.
+ */
+
+/**
+ * 코드 상태.
+ * - `AVAILABLE` 판매 가능 — 재고로 센다
+ * - `ASSIGNED` 주문상품에 배정됨
+ * - `REVOKED` 환불로 회수됨(구매자 화면에서 숨긴다. 코드 자체의 무효화는 셀러 시스템 몫이다)
+ * - `EXPIRED` 유효기간이 지나 배정하지 않음
+ * - `VOID` 셀러가 폐기함
+ */
+export const fulfillmentCodeStatusSchema = z.enum([
+  "AVAILABLE",
+  "ASSIGNED",
+  "REVOKED",
+  "EXPIRED",
+  "VOID",
+]);
+export type FulfillmentCodeStatus = z.infer<typeof fulfillmentCodeStatusSchema>;
+
+/** 한 번에 올릴 수 있는 코드 수 */
+export const MAX_CODES_PER_UPLOAD = 10_000;
+/** 코드 한 개의 최대 길이 */
+export const MAX_CODE_LENGTH = 200;
+
+/**
+ * 코드 일괄 업로드 요청 — `POST /v1/products/{productId}/codes`. `codes`(배열)와 `csv`(본문) 중 하나를 보낸다.
+ * 앞뒤 공백은 지우고 빈 줄은 건너뛴다. 같은 상품에 이미 있는 코드와 요청 안의 중복은 받지 않는다(`duplicates`).
+ */
+export const fulfillmentCodeUploadRequestSchema = z
+  .object({
+    variantId: z
+      .string()
+      .optional()
+      .describe("코드를 채울 옵션(variant) ID. 옵션 없는 상품은 생략한다(기본 옵션)"),
+    codes: z
+      .array(z.string())
+      .max(MAX_CODES_PER_UPLOAD)
+      .optional()
+      .describe(`코드 목록. 한 번에 ${MAX_CODES_PER_UPLOAD}개까지. \`csv\`와 둘 중 하나만 보낸다`),
+    csv: z
+      .string()
+      .max(4_000_000)
+      .optional()
+      .describe(
+        "CSV 본문 — 줄마다 첫 칸이 코드다. 첫 줄의 첫 칸이 `code`면 머리글로 보고 건너뛴다. " +
+          `한 번에 ${MAX_CODES_PER_UPLOAD}줄까지`,
+      ),
+    expiresAt: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe("이 업로드 코드의 유효기간 (ISO 8601). 지나면 배정하지 않고 만료로 바꾼다"),
+  })
+  .refine((value) => (value.codes === undefined) !== (value.csv === undefined), {
+    message: "codes와 csv 중 하나만 보내야 합니다",
+  });
+export type FulfillmentCodeUploadRequest = z.infer<typeof fulfillmentCodeUploadRequestSchema>;
+
+/** 받지 않은 줄 */
+export const fulfillmentCodeRejectionSchema = z.object({
+  line: z.number().int().describe("요청 안의 위치 (1부터). CSV는 머리글을 포함한 줄 번호다"),
+  reason: z
+    .string()
+    .describe(
+      "사유. `DUPLICATE`(이미 있는 코드이거나 요청 안에서 겹침)·`TOO_LONG`(200자 초과)·`INVALID_CHARACTER`(제어 문자). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+});
+
+/** 업로드 결과 — 배치 요약 */
+export const fulfillmentCodeBatchSchema = z.object({
+  batchId: z.string(),
+  productId: z.string(),
+  variantId: z.string(),
+  total: z.number().int().describe("요청에서 읽은 코드 수(빈 줄·머리글 제외)"),
+  accepted: z.number().int().describe("받은 코드 수 — 재고가 이만큼 는다"),
+  duplicates: z.number().int().describe("중복이라 받지 않은 코드 수"),
+  rejected: z
+    .array(fulfillmentCodeRejectionSchema)
+    .describe("받지 않은 줄(중복 포함). 최대 1,000개까지 싣는다"),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type FulfillmentCodeBatch = z.infer<typeof fulfillmentCodeBatchSchema>;
+
+/** 코드 목록의 한 줄 — **가린 값만** 싣는다 */
+export const fulfillmentCodeSchema = z.object({
+  codeId: z.string(),
+  productId: z.string(),
+  variantId: z.string(),
+  batchId: z.string().nullable().describe("업로드 배치. 수동 제공으로 셀러가 넘긴 코드는 null"),
+  hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
+  status: z
+    .string()
+    .describe(
+      "코드 상태. `AVAILABLE`·`ASSIGNED`·`REVOKED`·`EXPIRED`·`VOID`. 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  orderItemId: z.string().nullable().describe("배정된 주문상품. 배정 전이면 null"),
+  assignedAt: z.string().nullable(),
+  revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각 — 제공 개시 증거다"),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type FulfillmentCode = z.infer<typeof fulfillmentCodeSchema>;
+
+export const fulfillmentCodePageSchema = pageSchema(fulfillmentCodeSchema).extend({
+  available: z.number().int().describe("판매 가능한 코드 수(필터와 무관한 상품 전체)"),
+});
+export type FulfillmentCodePage = z.infer<typeof fulfillmentCodePageSchema>;
+
+/** `GET /v1/products/{productId}/codes` 쿼리 */
+export const fulfillmentCodeListQuerySchema = z.object({
+  status: fulfillmentCodeStatusSchema.optional().describe("상태 필터"),
+  variantId: z.string().optional().describe("옵션 필터"),
+  batchId: z.string().optional().describe("업로드 배치 필터"),
+  orderItemId: z.string().optional().describe("주문상품 필터"),
+  ...pageQueryShape(),
+});
+
+/** 셀러 콘솔 코드 열람 응답 — `POST /v1/fulfillment-codes/{codeId}/reveal` */
+export const fulfillmentCodeRevealSchema = z.object({
+  codeId: z.string(),
+  code: z.string().describe("코드 평문. 응답은 캐시하지 않는다(`Cache-Control: no-store`)"),
+});
+export type FulfillmentCodeReveal = z.infer<typeof fulfillmentCodeRevealSchema>;
+
+/** 주문상품에 배정된 코드의 가린 값 — 주문 응답의 `fulfillment.codes` */
+export const orderItemCodeSchema = z.object({
+  codeId: z.string(),
+  hint: z.string().describe("가린 코드 — 끝 4자만 보인다"),
+  status: z
+    .string()
+    .describe("`ASSIGNED`(유효)·`REVOKED`(환불로 회수). 값이 추가될 수 있어 문자열로 받는다"),
+  revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각. 열람 전이면 null"),
+});
+export type OrderItemCode = z.infer<typeof orderItemCodeSchema>;