@sayren/store-sdk 0.29.7 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.29.7",
+  "version": "0.30.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -69,6 +69,23 @@ import {
   collectionProductsReplaceRequestSchema,
   collectionSchema,
 } from "./schemas/collection";
+import {
+  type CreateCommerceFlowRequest,
+  commerceFlowCheckSchema,
+  commerceFlowSchema,
+  commerceFlowSummarySchema,
+  createCommerceFlowRequestSchema,
+  flowActionRequestSchema,
+  flowActionResultSchema,
+  flowPresetSummarySchema,
+  flowSecretSchema,
+  orderItemFlowSchema,
+  resolvedFlowSchema,
+  type SaveFlowDraftRequest,
+  type SaveFlowSecretRequest,
+  saveFlowDraftRequestSchema,
+  saveFlowSecretRequestSchema,
+} from "./schemas/commerce-flow";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
   type CreateCouponRequest,
@@ -95,6 +112,11 @@ import {
   type WithdrawCustomerRequest,
   withdrawCustomerRequestSchema,
 } from "./schemas/customer";
+import {
+  type PickupLocationRequestInput,
+  pickupLocationRequestSchema,
+  pickupLocationSchema,
+} from "./schemas/fulfillment";
 import {
   type LoginProvider,
   loginProviderTestSchema,
@@ -215,6 +237,12 @@ import {
   savedOptionSetRequestSchema,
   savedOptionSetSchema,
 } from "./schemas/saved-option-set";
+import {
+  calendarDaySchema,
+  calendarQuerySchema,
+  type SetCalendarRequest,
+  setCalendarRequestSchema,
+} from "./schemas/stay";
 import {
   type AddressType,
   type Invitation,
@@ -506,6 +534,24 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       removeDiscount: (productId: string) =>
         storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
+      /** 날짜별 재고 상품(`inventoryMode: "DATED"`, 이슈 #118)의 기간(포함) 달력. 없는 날은 싣지 않는다 */
+      getCalendar: (productId: string, query: z.input<typeof calendarQuerySchema>) =>
+        storeHttp.request(
+          "GET",
+          path`/products/${productId}/calendar`,
+          z.array(calendarDaySchema),
+          {
+            query: calendarQuerySchema.parse(query) as Query,
+          },
+        ),
+      /** 기간의 날짜마다 조합별 재고·가격을 덮어쓴다. `price: null`은 조합 가격으로 되돌린다 */
+      setCalendar: (productId: string, body: SetCalendarRequest) =>
+        storeHttp.request(
+          "PUT",
+          path`/products/${productId}/calendar`,
+          z.object({ updated: z.number().int() }),
+          { body: setCalendarRequestSchema.parse(body) },
+        ),
     },
 
     /**
@@ -730,6 +776,88 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       getDelivery: (orderItemId: string) =>
         storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
+      /** `GET /order-items/{id}/flow` — 커머스 플로우의 지금 상태·할 수 있는 행동·타이머(#115). 스코프 `order:r` */
+      getFlow: (orderItemId: string) =>
+        storeHttp.request("GET", path`/order-items/${orderItemId}/flow`, orderItemFlowSchema),
+      /**
+       * `POST /order-items/{id}/actions/{key}` — `getFlow().actions`에 켜진 행동을 실행한다(#115). 묶음 진행이면
+       * `affectedOrderItemIds`에 함께 움직인 주문상품이 온다. 에러: 409 `ACTION_NOT_AVAILABLE`
+       */
+      act: (
+        orderItemId: string,
+        key: string,
+        input: Record<string, unknown> = {},
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/actions/${key}`,
+          flowActionResultSchema,
+          { body: flowActionRequestSchema.parse({ input }), headers: idempotency(idempotencyKey) },
+        ),
+      /**
+       * `POST /order-items/{id}/events/{key}` — 현장 단말·연동의 상점 사건(`custom.<이름>`)을 플로우에 넣는다(#115).
+       * 에러: 400 `FLOW_EVENT_KEY_INVALID`, 409 `FLOW_EVENT_NOT_ACCEPTED`
+       */
+      emitEvent: (
+        orderItemId: string,
+        key: `custom.${string}`,
+        input: Record<string, unknown> = {},
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/events/${key}`,
+          flowActionResultSchema,
+          { body: flowActionRequestSchema.parse({ input }), headers: idempotency(idempotencyKey) },
+        ),
+    },
+
+    /**
+     * 커머스 플로우 (이슈 #115) — 프리셋 설치·초안 저장·검사·게시와 상품 할당 규칙. 조회 `flow:r`, 쓰기 `flow:rw`.
+     * 게시한 버전은 불변이고, 진행 중 주문은 결제 때 붙은 버전으로 끝까지 간다.
+     */
+    commerceFlows: {
+      presets: () => storeHttp.request("GET", "/flow-presets", z.array(flowPresetSummarySchema)),
+      list: () => storeHttp.request("GET", "/commerce-flows", z.array(commerceFlowSummarySchema)),
+      get: (flowId: string) =>
+        storeHttp.request("GET", path`/commerce-flows/${flowId}`, commerceFlowSchema),
+      /** 프리셋 설치 또는 빈 플로우. 에러: 409 `FLOW_KEY_TAKEN`·`FLOW_PRESET_UNAVAILABLE` */
+      create: (body: CreateCommerceFlowRequest) =>
+        storeHttp.request("POST", "/commerce-flows", commerceFlowSchema, {
+          body: createCommerceFlowRequestSchema.parse(body),
+        }),
+      /** 초안 저장. `revision`을 주면 그 초안일 때만 저장한다(409 `FLOW_REVISION_CONFLICT`) */
+      saveDraft: (flowId: string, body: SaveFlowDraftRequest, revision?: number) =>
+        storeHttp.request("PUT", path`/commerce-flows/${flowId}/draft`, commerceFlowSchema, {
+          body: saveFlowDraftRequestSchema.parse(body),
+          headers: revision === undefined ? undefined : { "if-match": String(revision) },
+        }),
+      check: (flowId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/commerce-flows/${flowId}/draft/check`,
+          commerceFlowCheckSchema,
+        ),
+      /** 게시. 차단 오류가 있으면 409 `PUBLISH_BLOCKED`(`details.blocking`) */
+      publish: (flowId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/commerce-flows/${flowId}/draft/publish`,
+          commerceFlowSchema,
+        ),
+      /** 이 상품에 지금 붙을 플로우 */
+      forProduct: (productId: string) =>
+        storeHttp.request("GET", path`/products/${productId}/flow`, resolvedFlowSchema),
+      /** HTTP 노드 시크릿 목록(헤더 값 제외) */
+      secrets: () => storeHttp.request("GET", "/commerce-flows/secrets", z.array(flowSecretSchema)),
+      /** 시크릿 저장(같은 이름이면 덮어쓴다). 상점 플랫폼 OWNER·ADMIN만. 에러: 400 `FLOW_SECRET_URL_INVALID` */
+      saveSecret: (name: string, body: SaveFlowSecretRequest) =>
+        storeHttp.request("PUT", path`/commerce-flows/secrets/${name}`, flowSecretSchema, {
+          body: saveFlowSecretRequestSchema.parse(body),
+        }),
+      removeSecret: (name: string) =>
+        storeHttp.requestVoid("DELETE", path`/commerce-flows/secrets/${name}`),
     },
 
     carriers: {
@@ -1335,6 +1463,21 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("POST", path`/seller-addresses/${addressId}/default`),
     },
 
+    /** 픽업 장소 (이슈 #115) — 방문 수령 주문의 수령 장소. 조회 `store:r`, 쓰기 `store:rw`(상점 플랫폼 OWNER·ADMIN) */
+    pickupLocations: {
+      list: () => storeHttp.request("GET", "/pickup-locations", z.array(pickupLocationSchema)),
+      create: (body: PickupLocationRequestInput) =>
+        storeHttp.request("POST", "/pickup-locations", pickupLocationSchema, {
+          body: pickupLocationRequestSchema.parse(body),
+        }),
+      update: (locationId: string, body: PickupLocationRequestInput) =>
+        storeHttp.request("PUT", path`/pickup-locations/${locationId}`, pickupLocationSchema, {
+          body: pickupLocationRequestSchema.parse(body),
+        }),
+      remove: (locationId: string) =>
+        storeHttp.requestVoid("DELETE", path`/pickup-locations/${locationId}`),
+    },
+
     /**
      * 스토어프론트 호스팅 (이슈 #53) — 조회 `storefront:r`, 쓰기 `storefront:rw`(OWNER·ADMIN).
      * 쓰기 응답은 바뀐 사이트다. Cloudflare 반영은 커밋 뒤라 `provisioning.status`가 잠시 `PENDING`일 수 있다.

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/collection";
+export * from "./schemas/commerce-flow";
 export * from "./schemas/commerce-number";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
@@ -40,6 +41,7 @@ export * from "./schemas/refund-policy";
 export * from "./schemas/saved-option-set";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
+export * from "./schemas/stay";
 export * from "./schemas/store";
 export * from "./schemas/storefront-hosting";
 export * from "./schemas/subscription";

package/src/schemas/category.ts

@@ -26,6 +26,13 @@ export const categorySchema = z.object({
   metaTitle: z.string().nullable(),
   metaDescription: z.string().nullable(),
   metaKeywords: z.string().nullable(),
+  flowId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "주문 흐름(이슈 #115) — 맨 아래 카테고리에만 있다. 흐름을 지정하지 않은 상품이 쓴다. null이면 기본 흐름",
+    ),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -89,6 +96,13 @@ export const categoryPatchRequestSchema = z.object({
   metaTitle: z.string().max(100).nullable().optional(),
   metaDescription: z.string().max(300).nullable().optional(),
   metaKeywords: z.string().max(200).nullable().optional(),
+  flowId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "주문 흐름(이슈 #115) — 게시한 흐름 id, null이면 기본 흐름. 맨 아래 카테고리에만 지정한다(400 `CATEGORY_NOT_LEAF`). 게시하지 않은 흐름은 409 `FLOW_NOT_PUBLISHED`",
+    ),
 });
 
 export type CategoryPatchRequest = z.infer<typeof categoryPatchRequestSchema>;

package/src/schemas/commerce-flow.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+import { claimStatusSchema } from "./claim";
+import { orderItemStatusSchema } from "./common";
+
+/**
+ * 커머스 플로우(이슈 #115) — 주문상품이 따르는 플로우의 지금 상태와 할 수 있는 행동. 공개 계약은 필드 추가로만 자란다.
+ * 행동 키·필드 키·꺼진 이유는 상점·앱이 늘리는 **열린 문자열**이다(모르는 값도 파싱한다). 공개 상태(`coreStatus`)만 닫힌 8개 값이다.
+ * 화면은 이 값만 그리고 상태 이름으로 분기하지 않는다 — 판정은 서버가 한다.
+ */
+
+export const flowInputFieldSchema = z.object({
+  key: z.string(),
+  type: z.string().describe("text · number · select · date · datetime · image (늘어날 수 있다)"),
+  required: z.boolean(),
+  label: z.string(),
+  maxLength: z.number().int().optional(),
+  maxFiles: z.number().int().optional(),
+  options: z.array(z.union([z.string(), z.number()])).optional(),
+});
+export type FlowInputField = z.infer<typeof flowInputFieldSchema>;
+
+export const flowActionSchema = z.object({
+  key: z.string().describe("행동 키. 플랫폼 키(예: CONFIRM_ORDER)와 상점·앱이 정한 키가 섞인다"),
+  label: z.string().describe("보여 줄 이름"),
+  mode: z
+    .enum(["INSTANT", "REQUEST", "VIEW"])
+    .describe("INSTANT 바로 실행 · REQUEST 승인 요청(클레임) · VIEW 보기"),
+  enabled: z.boolean(),
+  disabled: z
+    .object({
+      reason: z.string().describe("EXPIRED · CONDITION (늘어날 수 있다)"),
+      message: z.string().optional(),
+    })
+    .optional()
+    .describe("꺼진 이유. 켜져 있으면 없다"),
+  availableUntil: z.string().optional().describe("이 시각까지만 할 수 있다(ISO 8601)"),
+  subflow: z.string().optional().describe("이 행동이 시작하는 하위 플로우(클레임)"),
+  input: z.array(flowInputFieldSchema).optional().describe("받는 입력 폼"),
+  partialQuantity: z.union([z.boolean(), z.literal("UNIT")]).optional(),
+});
+export type FlowAction = z.infer<typeof flowActionSchema>;
+
+/** 커스텀 필드 값 — 문자열(날짜·일시는 ISO 8601)·숫자·참거짓·null, 수량 단위 필드는 문자열 배열 */
+export const flowFieldValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.string()),
+]);
+export type FlowFieldValue = z.infer<typeof flowFieldValueSchema>;
+
+export const flowStateSchema = z.object({
+  key: z.string().describe("플로우 안 상태 키(상점이 정한다). 화면 분기에 쓰지 않는다"),
+  label: z.string().describe("보는 사람(셀러·구매자)의 상태 이름"),
+  coreStatus: orderItemStatusSchema.optional().describe("공개 상태(8개)"),
+  claimStatus: claimStatusSchema.optional(),
+  message: z.string().optional().describe("보는 사람에게 보여 줄 안내문"),
+  enteredAt: z.string().describe("이 상태에 들어온 시각(ISO 8601)"),
+  deadlineAt: z.string().optional().describe("가장 가까운 기한(ISO 8601)"),
+  attachments: z
+    .array(z.string())
+    .optional()
+    .describe("가장 최근 행동이 붙인 첨부 주소(시안 등, #115). 없으면 생략"),
+  progress: z.boolean().optional().describe("진행 단계 표시에 넣는 상태인가"),
+  fields: z.record(z.string(), flowFieldValueSchema).describe("보는 사람 공개 범위의 커스텀 필드"),
+});
+export type FlowState = z.infer<typeof flowStateSchema>;
+
+export const orderItemFlowSchema = z.object({
+  orderItemId: z.string(),
+  flow: z.object({ flowId: z.string(), version: z.number().int() }),
+  flowState: flowStateSchema,
+  actions: z.array(flowActionSchema),
+  timers: z
+    .array(z.object({ key: z.string(), dueAt: z.string(), paused: z.boolean() }))
+    .describe("걸린 타이머(셀러 보기)"),
+  ended: z.boolean(),
+});
+export type OrderItemFlow = z.infer<typeof orderItemFlowSchema>;
+
+export const flowActionRequestSchema = z.object({
+  input: z.record(z.string(), z.unknown()).optional().describe("행동 입력 — 행동의 `input` 폼 키"),
+});
+export type FlowActionRequest = z.infer<typeof flowActionRequestSchema>;
+
+/**
+ * 행동 실행 결과. 지금은 동기 완료(COMPLETED)뿐이다. 외부 호출이 든 전이는 202와 함께 ACCEPTED(runId)가 온다(HTTP·앱 노드 단계에서 더한다).
+ * 동기 거절은 409(ACTION_NOT_AVAILABLE)다.
+ */
+export const flowActionResultSchema = z.object({
+  status: z.literal("COMPLETED"),
+  flowState: flowStateSchema,
+  actions: z.array(flowActionSchema),
+  /** 이 행동으로 바뀐 주문상품(주문 묶음 진행이면 여럿) */
+  affectedOrderItemIds: z.array(z.string()),
+});
+export type FlowActionResult = z.infer<typeof flowActionResultSchema>;
+
+// ── 플로우 정의 관리(이슈 #115 D3a) — `/v1/commerce-flows/**`, 스코프 `flow:r|rw` ─────────────────────
+
+/** 플로우 작성 그래프와 정의는 형태가 크고 노드 종류가 늘어나므로 여기서는 열린 객체로 싣는다(검증은 서버 `…/draft/check`) */
+const flowDocumentSchema = z.record(z.string(), z.unknown());
+
+export const flowPresetSummarySchema = z.object({
+  key: z.string(),
+  presetVersion: z.number().int(),
+  name: z.string(),
+  description: z.string(),
+  availability: z
+    .enum(["AVAILABLE", "BLOCKED"])
+    .describe("BLOCKED면 의존 이슈(dependsOn)가 끝나야 설치할 수 있다"),
+  dependsOn: z.array(z.string()),
+  requires: flowDocumentSchema.describe(
+    "프리셋이 쓰는 Core 기능(진행 단위·이행 방식·주문 입력 등)",
+  ),
+  variables: z.array(flowDocumentSchema).describe("셀러가 값만 입력하는 변수 정의"),
+});
+export type FlowPresetSummary = z.infer<typeof flowPresetSummarySchema>;
+
+export const commerceFlowSummarySchema = z.object({
+  flowId: z.string(),
+  key: z.string().describe("상점 안 유일한 키"),
+  name: z.string(),
+  progression: z.enum(["ITEM", "ORDER_GROUP"]),
+  fulfillmentMethods: z.array(z.string()),
+  presetKey: z.string().nullable().describe("설치한 프리셋(설치 뒤 연결되지 않는다)"),
+  presetVersion: z.number().int().nullable(),
+  activeVersion: z.number().int().nullable().describe("게시된 버전. 새 주문이 따른다"),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type CommerceFlowSummary = z.infer<typeof commerceFlowSummarySchema>;
+
+export const commerceFlowVersionViewSchema = z.object({
+  version: z.number().int(),
+  status: z.enum(["DRAFT", "ACTIVE", "LEGACY"]),
+  revision: z.number().int().describe("초안 저장의 If-Match 값"),
+  graph: flowDocumentSchema,
+  definition: flowDocumentSchema,
+  variables: z.record(z.string(), z.unknown()),
+  publishedAt: z.string().nullable(),
+});
+
+export const commerceFlowSchema = commerceFlowSummarySchema.extend({
+  draft: commerceFlowVersionViewSchema.nullable(),
+  active: commerceFlowVersionViewSchema.nullable(),
+  versions: z.array(
+    z.object({
+      version: z.number().int(),
+      status: z.enum(["DRAFT", "ACTIVE", "LEGACY"]),
+      publishedAt: z.string().nullable(),
+    }),
+  ),
+});
+export type CommerceFlow = z.infer<typeof commerceFlowSchema>;
+
+export const createCommerceFlowRequestSchema = z.object({
+  key: z
+    .string()
+    .regex(/^[a-z][a-z0-9-]{1,48}$/)
+    .describe("상점 안 유일한 키(소문자·숫자·하이픈)"),
+  name: z.string().min(1).max(60).optional(),
+  presetKey: z.string().optional().describe("설치할 프리셋. 없으면 빈 플로우"),
+  variables: z.record(z.string(), z.unknown()).optional().describe("프리셋 변수 값"),
+});
+export type CreateCommerceFlowRequest = z.infer<typeof createCommerceFlowRequestSchema>;
+
+export const saveFlowDraftRequestSchema = z.object({
+  graph: flowDocumentSchema,
+  definition: flowDocumentSchema.optional(),
+  variables: z.record(z.string(), z.unknown()).optional(),
+});
+export type SaveFlowDraftRequest = z.infer<typeof saveFlowDraftRequestSchema>;
+
+const flowIssueSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  nodeId: z.string().optional(),
+  edgeId: z.string().optional(),
+});
+
+export const commerceFlowCheckSchema = z.object({
+  publishable: z.boolean().describe("게시를 막는 오류(실행 불가·공개 계약·한도)가 없다"),
+  blocking: z.array(flowIssueSchema),
+  warnings: z.array(flowIssueSchema).describe("업무 논리 경고 — 게시를 막지 않는다"),
+});
+export type CommerceFlowCheck = z.infer<typeof commerceFlowCheckSchema>;
+
+// ── 흐름 해석(이슈 #115) — 상품의 흐름 → 카테고리(맨 아래)의 흐름 → 기본 흐름. 할당 규칙은 없앴다 ─────────────────
+
+export const resolvedFlowSchema = z.object({
+  flowId: z.string(),
+  version: z.number().int(),
+  source: z
+    .enum(["PRODUCT", "CATEGORY", "PLATFORM"])
+    .describe("PRODUCT 상품에 지정한 흐름 · CATEGORY 카테고리의 흐름 · PLATFORM 기본 흐름"),
+});
+export type ResolvedFlow = z.infer<typeof resolvedFlowSchema>;
+
+// ─── 플로우 시크릿(이슈 #115 E5b) ─────────────────────────────
+
+/** 시크릿 이름 — 플로우 변수 `secretRef`의 값이다 */
+export const flowSecretNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{1,39}$/)
+  .describe("시크릿 이름(소문자·숫자·하이픈 2~40자). 플로우 변수(시크릿)의 값으로 쓴다");
+
+/** HTTP 노드가 부를 셀러 API — 헤더 값은 응답에 싣지 않는다 */
+export const flowSecretSchema = z.object({
+  name: z.string(),
+  url: z.string().describe("요청 주소(https)"),
+  headerNames: z.array(z.string()).describe("저장한 헤더 이름(값은 보이지 않는다)"),
+  updatedAt: z.string(),
+});
+export type FlowSecret = z.infer<typeof flowSecretSchema>;
+
+export const saveFlowSecretRequestSchema = z.object({
+  url: z
+    .url()
+    .refine((value) => value.startsWith("https://"), { message: "https 주소만 받습니다" })
+    .describe("요청 주소. https만, 사설·루프백 주소는 400 `FLOW_SECRET_URL_INVALID`"),
+  headers: z
+    .record(z.string().regex(/^[A-Za-z0-9-]{1,64}$/), z.string().max(2000))
+    .refine((value) => Object.keys(value).length <= 10, { message: "헤더는 10개까지입니다" })
+    .default({})
+    .describe("함께 보낼 헤더(인증 등). 값은 암호화해 두고 다시 보여 주지 않는다"),
+});
+export type SaveFlowSecretRequest = z.input<typeof saveFlowSecretRequestSchema>;