sayren 0.13.0 → 0.14.0

package/dist/boilerplate/src/lib/queries.ts

@@ -0,0 +1,61 @@
+import { productSortSchema } from "@sayren/storefront-sdk";
+import { queryOptions } from "@tanstack/react-query";
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+import { apiFor } from "./api.server";
+
+/**
+ * 기본 조회 — TanStack Query의 queryOptions 팩토리다. 라우트 loader(`ensureQueryData`)와 화면(`useSuspenseQuery`, `src/hooks`)이
+ * 같은 팩토리를 써서 queryKey가 갈라지지 않는다. 데이터는 서버 함수로 받는다(첫 요청은 서버가 받아 HTML에 싣는다).
+ * 금액·재고·주문 가능 여부는 응답 값을 그대로 보인다 — 화면에서 계산하지 않는다.
+ */
+
+const getStore = createServerFn({ method: "GET" }).handler(() => apiFor().store.get());
+
+const listCategories = createServerFn({ method: "GET" }).handler(() =>
+  apiFor().catalog.listCategories(),
+);
+
+export const productSearchSchema = z.object({
+  keyword: z.string().optional(),
+  categoryId: z.string().optional(),
+  sort: productSortSchema.optional(),
+  page: z.number().int().min(1).optional(),
+  size: z.number().int().min(1).max(60).optional(),
+});
+export type ProductSearch = z.infer<typeof productSearchSchema>;
+
+const searchProducts = createServerFn({ method: "GET" })
+  .validator(productSearchSchema)
+  .handler(({ data }) =>
+    apiFor().catalog.searchProducts({ ...data, page: data.page ?? 1, size: data.size ?? 24 }),
+  );
+
+const getProduct = createServerFn({ method: "GET" })
+  .validator(z.object({ productId: z.string().min(1) }))
+  .handler(({ data }) => apiFor().catalog.getProduct(data.productId));
+
+/** 상점 이름·로고·연락처 — 상점 플랫폼 설정 › 상점 정보 값 */
+export const storeQuery = () =>
+  queryOptions({ queryKey: ["store"], queryFn: () => getStore(), staleTime: 5 * 60_000 });
+
+/** 카테고리는 자주 바뀌지 않는다 — 5분 동안 다시 받지 않는다 */
+export const categoriesQuery = () =>
+  queryOptions({
+    queryKey: ["catalog", "categories"],
+    queryFn: () => listCategories(),
+    staleTime: 5 * 60_000,
+  });
+
+export const productsQuery = (search: ProductSearch) =>
+  queryOptions({
+    queryKey: ["catalog", "products", search],
+    queryFn: () => searchProducts({ data: search }),
+  });
+
+/** 상품 하나 — 상품 id 또는 상점별 상품번호 */
+export const productQuery = (productId: string) =>
+  queryOptions({
+    queryKey: ["catalog", "product", productId],
+    queryFn: () => getProduct({ data: { productId } }),
+  });

package/dist/boilerplate/src/routeTree.gen.ts

@@ -0,0 +1,69 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/'
+  id: '__root__' | '/'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { startInstance } from './start.ts'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+    config: Awaited<ReturnType<typeof startInstance.getOptions>>
+  }
+}

package/dist/boilerplate/src/router.tsx

@@ -0,0 +1,44 @@
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { routeTree } from "./routeTree.gen";
+
+/** 라우트 loader가 받는 문맥 — loader가 `queryClient.ensureQueryData`로 미리 받아 둔다 */
+export interface RouterContext {
+  queryClient: QueryClient;
+}
+
+export function getRouter() {
+  // 요청마다 새로 만든다 — 서버 렌더에서 다른 구매자의 캐시가 섞이지 않는다
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        // 서버가 받아 둔 데이터를 하이드레이션 직후 다시 부르지 않는다
+        staleTime: 30_000,
+        refetchOnWindowFocus: false,
+        retry: 1,
+      },
+    },
+  });
+
+  const router = createRouter({
+    routeTree,
+    context: { queryClient } satisfies RouterContext,
+    scrollRestoration: true,
+    // 링크에 마우스를 올리거나 포커스하면 다음 화면 데이터를 미리 받는다(30초 동안 다시 받지 않는다).
+    // loader가 상태를 바꾸는 화면(주문서 세션 생성·주문 완료의 바로구매 쿠키 삭제)은 라우트에서 `preload: false`로 뺀다
+    defaultPreload: "intent",
+    defaultPreloadStaleTime: 30_000,
+  });
+
+  // 서버에서 채운 쿼리 캐시를 HTML에 실어 보내고 브라우저에서 되살린다(QueryClientProvider도 여기서 감싼다)
+  setupRouterSsrQueryIntegration({ router, queryClient });
+
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}

package/dist/boilerplate/src/routes/__root.tsx

@@ -0,0 +1,119 @@
+import {
+  createRootRouteWithContext,
+  type ErrorComponentProps,
+  HeadContent,
+  Link,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import { createServerFn } from "@tanstack/react-start";
+import { useEffect } from "react";
+import { getLocale, m } from "../i18n";
+import { type AnalyticsConfig, startAnalytics } from "../lib/analytics";
+import { apiFor } from "../lib/api.server";
+import { ANALYTICS_DEBUG, API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import type { RouterContext } from "../router";
+import appCss from "../styles.css?url";
+
+/**
+ * 보일러플레이트의 루트 — 문서 머리, 방문 분석 시작, 오류 화면만 둔다. 헤더·푸터·메뉴는 쇼핑몰마다 새로 만든다.
+ * 화면 데이터는 `src/lib/queries.ts`의 queryOptions와 `src/hooks`의 훅으로 읽는다.
+ */
+
+/** 방문 분석 설정 — 서버 값(`process.env`)이라 서버 함수로 내려준다 */
+const getAnalyticsConfig = createServerFn({ method: "GET" }).handler(
+  (): AnalyticsConfig => ({
+    apiBaseUrl: API_BASE_URL,
+    storeCode: resolveStoreCode(),
+    debug: ANALYTICS_DEBUG,
+  }),
+);
+
+/** 상점 이름 — 문서 제목에 쓴다. 읽지 못해도 화면은 그린다 */
+const getStoreName = createServerFn({ method: "GET" }).handler(async (): Promise<string | null> => {
+  const store = await apiFor()
+    .store.get()
+    .catch(() => null);
+  return store?.name ?? null;
+});
+
+export interface RootData {
+  analytics: AnalyticsConfig;
+  storeName: string | null;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: ({ loaderData }) => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: loaderData?.storeName ?? m.site_store_fallback() },
+    ],
+    links: [
+      // 본문 서체 Pretendard(theme.css의 --font-sans). 다른 서체는 여기에 https 스타일시트로 더한다
+      {
+        rel: "stylesheet",
+        href: "https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable-dynamic-subset.min.css",
+      },
+      { rel: "stylesheet", href: appCss },
+      { rel: "icon", href: "/favicon.svg", type: "image/svg+xml" },
+    ],
+  }),
+  loader: async (): Promise<RootData> => {
+    const [analytics, storeName] = await Promise.all([getAnalyticsConfig(), getStoreName()]);
+    return { analytics, storeName };
+  },
+  staleTime: Number.POSITIVE_INFINITY,
+  shellComponent: RootDocument,
+  component: Root,
+  errorComponent: RootError,
+  notFoundComponent: NotFound,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang={getLocale()}>
+      <head>
+        <HeadContent />
+      </head>
+      <body className="min-h-screen bg-page text-ink">
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+function Root() {
+  const { analytics } = Route.useLoaderData();
+  // 방문 분석은 브라우저에서 한 번 시작한다. 이후 페이지뷰는 SDK가 History API 이동으로 센다
+  useEffect(() => {
+    startAnalytics(analytics);
+  }, [analytics]);
+  return <Outlet />;
+}
+
+function RootError({ error }: ErrorComponentProps) {
+  return (
+    <ErrorView
+      title={m.root_error_title()}
+      detail={error instanceof Error ? error.message : undefined}
+    />
+  );
+}
+
+function NotFound() {
+  return <ErrorView title={m.root_not_found_title()} />;
+}
+
+function ErrorView({ title, detail }: { title: string; detail?: string }) {
+  return (
+    <main className="space-y-3 px-4 py-16 text-center">
+      <h1 className="font-bold text-2xl">{title}</h1>
+      {detail ? <p className="text-muted">{detail}</p> : null}
+      <Link className="inline-block underline" to="/">
+        {m.root_go_home()}
+      </Link>
+    </main>
+  );
+}

package/dist/boilerplate/src/routes/index.tsx

@@ -0,0 +1,52 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { useProducts, useStore } from "../hooks/use-catalog";
+import { m } from "../i18n";
+import { formatMoney } from "../lib/format";
+import { productsQuery, storeQuery } from "../lib/queries";
+
+/** 홈에 보이는 상품 수 — 첫 페이지만 받는다 */
+const HOME_PRODUCTS = { page: 1, size: 24 } as const;
+
+/** 보일러플레이트의 첫 화면 — 상점 이름과 상품 목록. 쇼핑몰을 만들면 이 파일을 홈으로 바꾼다 */
+export const Route = createFileRoute("/")({
+  loader: ({ context }) =>
+    Promise.all([
+      context.queryClient.ensureQueryData(storeQuery()),
+      context.queryClient.ensureQueryData(productsQuery(HOME_PRODUCTS)),
+    ]),
+  component: Home,
+});
+
+function Home() {
+  const store = useStore();
+  const products = useProducts(HOME_PRODUCTS);
+  return (
+    <main className="mx-auto flex min-h-screen max-w-page flex-col gap-8 px-4 py-12">
+      <h1 className="font-bold text-3xl">{store.name}</h1>
+      {products.contents.length === 0 ? (
+        <p className="text-sub">{m.home_no_products()}</p>
+      ) : (
+        <ul className="grid grid-cols-2 gap-x-4 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
+          {products.contents.map((product) => (
+            <li key={product.productId} className="flex flex-col gap-2">
+              <div className="aspect-square overflow-hidden bg-chip">
+                {product.thumbnailUrl ? (
+                  <img
+                    src={product.thumbnailUrl}
+                    alt={product.name}
+                    loading="lazy"
+                    className="h-full w-full object-cover"
+                  />
+                ) : null}
+              </div>
+              <p className="text-sm">{product.name}</p>
+              <p className="font-bold text-sm">
+                {formatMoney(product.discountedPrice ?? product.salePrice, product.currency)}
+              </p>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  );
+}

package/dist/boilerplate/src/start.ts

@@ -0,0 +1,20 @@
+import { createCsrfMiddleware, createMiddleware, createStart } from "@tanstack/react-start";
+import { resolveLocale } from "./i18n";
+import { runWithLocale } from "./i18n/locale.server";
+
+/**
+ * 서버 함수 호출은 같은 사이트에서 온 것만 받는다(장바구니·결제 서버 함수를 더해도 다른 사이트가 대신 부르지 못하게).
+ * 구매자 로그인을 더하면 여기에 세션 갱신 미들웨어를 더한다(sdk-buyer-auth 스킬 참고).
+ */
+const csrf = createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === "serverFn" });
+
+/** 요청 언어 — `?lang=` → `Accept-Language` → ko. 화면 렌더가 끝날 때까지 유지한다(`src/i18n`) */
+const locale = createMiddleware().server(({ next, request }) =>
+  runWithLocale(resolveLocale(new URL(request.url), request.headers.get("accept-language")), () =>
+    next(),
+  ),
+);
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [locale, csrf],
+}));

package/dist/boilerplate/src/styles.css

@@ -0,0 +1,29 @@
+/* 클래스는 src/만 훑는다 — 빌드 산출물(dist)·설치물을 훑으면 빌드마다 CSS가 달라지고 서버·브라우저 빌드의 파일 이름이 어긋난다 */
+@import "tailwindcss" source(".");
+/* 상세설명이 에디터가 내보낸 HTML이라 그 모양 규칙이 필요하다 — 사진 줄, 재생기 틀,
+   구분선. 활자는 product-description.tsx가 정하고 이 파일은 건드리지 않는다. */
+@import "@avarlabs/editor/styles/reader.css";
+
+/*
+ * 확장 지점 — 브랜드 색·서체·폭은 theme.css의 `@theme`에서 바꾼다. 화면 코드는 토큰만 쓰므로
+ * 그 파일만 고쳐도 전체 톤이 바뀐다.
+ */
+@import "./theme.css";
+
+html {
+  font-family: var(--font-sans);
+  word-break: keep-all;
+}
+
+body {
+  /* 모바일 가로 스크롤 방지 — 화면 밖으로 밀린 요소가 있어도 페이지 전체가 옆으로 밀리지 않는다.
+     원인은 각 화면에서 min-w-0·break-words로 고친다. 이 규칙은 마지막 안전망이다 */
+  overflow-x: clip;
+  color: var(--color-ink);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* 숫자(가격·수량·날짜)는 자릿수가 흔들리지 않게 한다 */
+.tabular {
+  font-variant-numeric: tabular-nums;
+}

package/dist/boilerplate/src/theme.css

@@ -0,0 +1,38 @@
+/*
+ * 확장 지점 — 브랜드 색과 서체, 본문 폭은 여기서 바꾼다. 화면 코드는 토큰만 쓰므로
+ * 이 블록만 고쳐도 전체 톤이 바뀐다.
+ *
+ * - page: 페이지 바탕 · ink: 본문 글자·주요 버튼·판매가 · sub: 보조 본문 · muted: 캡션·정가
+ * - line: 구분선 · line-strong: 입력·보조 버튼 테두리 · chip: 옅은 면(모바일 섹션 띠·선택 행)
+ * - point: 할인율·필수 표시·오류 · point-soft: 혜택 배지 면 · info: 배송중 상태
+ * - container-page: 헤더와 본문의 최대 폭(`max-w-page`)
+ * - 글자 단차: caption 12 · meta 13 · body 14 · body-lg 15 (Tailwind 기본 xs·sm·base·lg·xl·2xl와 함께 쓴다)
+ *
+ * 기본 톤 — 흰 바탕·잉크 글자, 할인율에만 레드를 쓴다. 모서리 0
+ */
+@theme {
+  --color-page: #ffffff;
+  --color-ink: #111111;
+  --color-sub: #555555;
+  --color-muted: #767676;
+  --color-line: #e5e5e5;
+  --color-line-strong: #d4d4d4;
+  --color-chip: #f5f5f5;
+  --color-point: #e8380d;
+  --color-point-soft: #fdf0eb;
+  --color-info: #2563eb;
+  --font-sans: "Pretendard Variable", Pretendard, -apple-system, "Apple SD Gothic Neo", sans-serif;
+  --color-surface: #f7f6f3;
+  --font-display: var(--font-sans);
+  --radius-card: 0;
+  --radius-control: 0;
+  --container-page: 80rem;
+  --text-caption: 0.75rem;
+  --text-caption--line-height: 1.5;
+  --text-meta: 0.8125rem;
+  --text-meta--line-height: 1.5;
+  --text-body: 0.875rem;
+  --text-body--line-height: 1.6;
+  --text-body-lg: 0.9375rem;
+  --text-body-lg--line-height: 1.6;
+}

package/dist/boilerplate/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", ".output", ".tanstack"]
+}

package/dist/boilerplate/vite.config.ts

@@ -0,0 +1,12 @@
+import tailwindcss from "@tailwindcss/vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
+import { defineConfig, loadEnv } from "vite";
+
+export default defineConfig(({ mode }) => {
+  // .env의 SAYREN_*를 서버 코드가 읽는 process.env에 싣는다. 셸에서 준 값이 우선한다.
+  // SAYREN_TOKEN(셀러 계정 토큰)은 싣지 않는다 — 사이트 코드가 셀러 토큰을 읽지 못하게
+  const { SAYREN_TOKEN: _cliToken, ...env } = loadEnv(mode, process.cwd(), "SAYREN_");
+  Object.assign(process.env, env, { ...process.env });
+  return { plugins: [tailwindcss(), tanstackStart(), viteReact()] };
+});

package/dist/boilerplate/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { environment: "node", include: ["src/**/*.test.{ts,tsx}"] },
+});