create-web-0to1 0.1.0

package/source/core/utils/format/text.ts

@@ -0,0 +1,15 @@
+export function truncateText(value: string, maxLength: number, suffix = '...') {
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  return `${value.slice(0, maxLength)}${suffix}`;
+}
+
+export function fallbackText(value: string | null | undefined, empty = '-') {
+  if (!value || value.trim() === '') {
+    return empty;
+  }
+
+  return value;
+}

package/source/core/utils/schema-utils.ts

@@ -0,0 +1,27 @@
+import { ApiError, APP_ERROR_CODES, getAppErrorMessage } from '../error/app-error';
+
+type SchemaLike<TOutput> = {
+  safeParse: (
+    value: unknown,
+  ) => { success: true; data: TOutput } | { success: false };
+};
+
+/**
+ * 런타임 데이터 검증 실패를 템플릿 공통 AppError로 통일합니다.
+ */
+export function parseWithSchema<TOutput>(
+  schema: SchemaLike<TOutput>,
+  payload: unknown,
+): TOutput {
+  const result = schema.safeParse(payload);
+
+  if (!result.success) {
+    throw new ApiError(
+      getAppErrorMessage(APP_ERROR_CODES.INVALID_RESPONSE),
+      500,
+      APP_ERROR_CODES.INVALID_RESPONSE,
+    );
+  }
+
+  return result.data;
+}

package/source/wrappers/monorepo/core/internal.ts

@@ -0,0 +1,21 @@
+type CoreConfig = {
+  siteId: string;
+  baseUrl: string;
+};
+
+const coreConfig: CoreConfig = {
+  siteId: '',
+  baseUrl: '',
+};
+
+export function initCore(siteId: string, baseUrl?: string) {
+  coreConfig.siteId = siteId;
+
+  if (baseUrl !== undefined) {
+    coreConfig.baseUrl = baseUrl;
+  }
+}
+
+export function getCoreConfig() {
+  return { ...coreConfig };
+}

package/source/wrappers/monorepo/core/src/index.ts

@@ -0,0 +1,4 @@
+export * from '../../../../core/error/app-error';
+export * from '../internal';
+export * from '../../request/core-request';
+export * from '../../../../core/utils/schema-utils';

package/source/wrappers/monorepo/core-next/src/auth.client.ts

@@ -0,0 +1 @@
+export { withClientAuth } from '../../core-react/src/auth';

package/source/wrappers/monorepo/core-next/src/auth.server.ts

@@ -0,0 +1,94 @@
+import 'server-only';
+
+import { cookies } from 'next/headers';
+
+const DEFAULT_AUTH_COOKIE_NAMES = [
+  'session',
+  'access_token',
+  'refresh_token',
+] as const;
+
+export type WithServerAuthOptions = {
+  authCookieNames?: readonly string[];
+};
+
+type RequestOptionsLike = {
+  headers?: HeadersInit;
+};
+
+function isRequestOptionsLike(value: unknown): value is RequestOptionsLike {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function mergeCookieHeader(
+  headers: HeadersInit | undefined,
+  cookieHeader: string,
+) {
+  const nextHeaders = new Headers(headers);
+  const existingCookieHeader = nextHeaders.get('Cookie');
+
+  nextHeaders.set(
+    'Cookie',
+    existingCookieHeader
+      ? `${existingCookieHeader}; ${cookieHeader}`
+      : cookieHeader,
+  );
+
+  return nextHeaders;
+}
+
+function createAuthCookieHeader(
+  cookieNames: readonly string[],
+  cookieStore: Awaited<ReturnType<typeof cookies>>,
+) {
+  return cookieNames
+    .map((cookieName) => cookieStore.get(cookieName))
+    .filter((cookie) => cookie !== undefined)
+    .map((cookie) => `${cookie.name}=${cookie.value}`)
+    .join('; ');
+}
+
+function withServerAuthHeaders(args: unknown[], cookieHeader: string) {
+  if (!cookieHeader) {
+    return args;
+  }
+
+  const nextArgs = [...args];
+  const lastArg = nextArgs.at(-1);
+
+  if (!isRequestOptionsLike(lastArg)) {
+    nextArgs.push({
+      headers: mergeCookieHeader(undefined, cookieHeader),
+    });
+
+    return nextArgs;
+  }
+
+  nextArgs[nextArgs.length - 1] = {
+    ...lastArg,
+    headers: mergeCookieHeader(lastArg.headers, cookieHeader),
+  };
+
+  return nextArgs;
+}
+
+type AsyncRequestFunction = (...args: unknown[]) => Promise<unknown>;
+
+/**
+ * Next 서버에서 현재 요청 쿠키를 읽어 request 함수에 그대로 주입합니다.
+ */
+export function withServerAuth<TRequestFunction extends AsyncRequestFunction>(
+  requestFunction: TRequestFunction,
+  options: WithServerAuthOptions = {},
+): TRequestFunction {
+  const { authCookieNames = DEFAULT_AUTH_COOKIE_NAMES } = options;
+
+  return (async (...args: Parameters<TRequestFunction>) => {
+    const cookieStore = await cookies();
+    const cookieHeader = createAuthCookieHeader(authCookieNames, cookieStore);
+
+    return requestFunction(
+      ...(withServerAuthHeaders(args, cookieHeader) as Parameters<TRequestFunction>),
+    );
+  }) as TRequestFunction;
+}

package/source/wrappers/monorepo/core-next/src/bootstrap.client.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import { initCore } from '../../core/internal';
+
+export type CoreBootstrapClientProps = {
+  siteId: string;
+  baseUrl?: string;
+};
+
+/**
+ * 클라이언트에서도 동일한 core 설정을 다시 초기화해서
+ * hydration 이후 request wrapper가 같은 값을 읽도록 맞춥니다.
+ */
+export function CoreBootstrapClient({
+  siteId,
+  baseUrl,
+}: CoreBootstrapClientProps) {
+  initCore(siteId, baseUrl);
+
+  return null;
+}

package/source/wrappers/monorepo/core-next/src/bootstrap.tsx

@@ -0,0 +1,18 @@
+import type { JSX } from 'react';
+
+import { initCore } from '../../core/internal';
+import { CoreBootstrapClient } from './bootstrap.client';
+
+export type CoreBootstrapProps = {
+  siteId: string;
+  baseUrl?: string;
+};
+
+export function CoreBootstrap({
+  siteId,
+  baseUrl,
+}: CoreBootstrapProps): JSX.Element {
+  initCore(siteId, baseUrl);
+
+  return <CoreBootstrapClient siteId={siteId} baseUrl={baseUrl} />;
+}

package/source/wrappers/monorepo/core-next/src/index.ts

@@ -0,0 +1 @@
+export * from '../../core-react/src/index';

package/source/wrappers/monorepo/core-react/src/app-providers.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import type { QueryClient } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import {
+  CoreReactProvider,
+  type CoreReactProviderProps,
+} from './provider';
+import { createClientQueryErrorHandler } from './query-error-handler';
+
+export type AppProvidersProps = {
+  children: ReactNode;
+  queryClient?: QueryClient;
+  defaultOptions?: CoreReactProviderProps['defaultOptions'];
+  onGlobalError?: CoreReactProviderProps['onGlobalError'];
+};
+
+export function AppProviders({
+  children,
+  queryClient,
+  defaultOptions,
+  onGlobalError,
+}: AppProvidersProps) {
+  return (
+    <CoreReactProvider
+      queryClient={queryClient}
+      defaultOptions={defaultOptions}
+      onGlobalError={
+        onGlobalError ?? createClientQueryErrorHandler()
+      }
+    >
+      {children}
+    </CoreReactProvider>
+  );
+}

package/source/wrappers/monorepo/core-react/src/auth.ts

@@ -0,0 +1,42 @@
+type RequestOptionsLike = {
+  credentials?: RequestCredentials;
+};
+
+function isRequestOptionsLike(value: unknown): value is RequestOptionsLike {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function withClientAuthOptions(args: unknown[]) {
+  const nextArgs = [...args];
+  const lastArg = nextArgs.at(-1);
+
+  if (!isRequestOptionsLike(lastArg)) {
+    nextArgs.push({
+      credentials: 'include' satisfies RequestCredentials,
+    });
+
+    return nextArgs;
+  }
+
+  nextArgs[nextArgs.length - 1] = {
+    ...lastArg,
+    credentials: 'include' satisfies RequestCredentials,
+  };
+
+  return nextArgs;
+}
+
+type AsyncRequestFunction = (...args: unknown[]) => Promise<unknown>;
+
+/**
+ * monorepo 클라이언트 요청 함수에 credentials: include를 덧씌우는 helper입니다.
+ */
+export function withClientAuth<TRequestFunction extends AsyncRequestFunction>(
+  requestFunction: TRequestFunction,
+): TRequestFunction {
+  return ((...args: Parameters<TRequestFunction>) => {
+    return requestFunction(
+      ...(withClientAuthOptions(args) as Parameters<TRequestFunction>),
+    );
+  }) as TRequestFunction;
+}

package/source/wrappers/monorepo/core-react/src/hydration.tsx

@@ -0,0 +1,21 @@
+import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import { getCoreQueryClient } from './query-client';
+
+export type CoreQueryHydrationProps = {
+  children: ReactNode;
+  prefetch: (
+    queryClient: ReturnType<typeof getCoreQueryClient>,
+  ) => Promise<void>;
+};
+
+export async function CoreQueryHydration({
+  children,
+  prefetch,
+}: CoreQueryHydrationProps) {
+  const queryClient = getCoreQueryClient();
+  await prefetch(queryClient);
+
+  return <HydrationBoundary state={dehydrate(queryClient)}>{children}</HydrationBoundary>;
+}

package/source/wrappers/monorepo/core-react/src/index.ts

@@ -0,0 +1,7 @@
+export * from './app-providers';
+export * from './auth';
+export * from './hydration';
+export * from './provider';
+export * from './query-client';
+export * from './query-error-handler';
+export * from './query-keys';

package/source/wrappers/monorepo/core-react/src/provider.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { QueryClientProvider, type QueryClient } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import type { ReactNode } from 'react';
+
+import {
+  type CoreQueryClientOptions,
+  getCoreQueryClient,
+} from './query-client';
+
+export type CoreReactProviderProps = {
+  children: ReactNode;
+  queryClient?: QueryClient;
+  onGlobalError?: (error: unknown) => void;
+  defaultOptions?: CoreQueryClientOptions['defaultOptions'];
+};
+
+function isDevelopmentEnvironment() {
+  // Vite 앱 타입체크에서도 안전하게 동작하도록 process 전역을 직접 참조하지 않습니다.
+  const globalProcess = (globalThis as { process?: { env?: { NODE_ENV?: string } } })
+    .process;
+
+  return globalProcess?.env?.NODE_ENV === 'development';
+}
+
+export function CoreReactProvider({
+  children,
+  queryClient,
+  onGlobalError,
+  defaultOptions,
+}: CoreReactProviderProps) {
+  // 외부에서 client를 주입하지 않으면 monorepo 기본 규칙으로 생성합니다.
+  const resolvedQueryClient =
+    queryClient ??
+    getCoreQueryClient({
+      onGlobalError,
+      defaultOptions,
+    });
+
+  return (
+    <QueryClientProvider client={resolvedQueryClient}>
+      {children}
+      {isDevelopmentEnvironment() ? (
+        <ReactQueryDevtools initialIsOpen={false} />
+      ) : null}
+    </QueryClientProvider>
+  );
+}

package/source/wrappers/monorepo/core-react/src/query-client.ts

@@ -0,0 +1,48 @@
+import type { DefaultOptions } from '@tanstack/react-query';
+
+import {
+  createSharedQueryClient,
+  getSharedQueryClient,
+  mergeQueryClientDefaultOptions,
+  makeSharedQueryClient,
+  type SharedQueryClientOptions,
+} from '../../../../core/query/query-client';
+
+const monorepoDefaultOptions: DefaultOptions = {
+  queries: {
+    refetchOnWindowFocus: false,
+  },
+};
+
+export type CoreQueryClientOptions = Pick<SharedQueryClientOptions, 'onGlobalError'> & {
+  defaultOptions?: DefaultOptions;
+};
+
+function mergeMonorepoDefaultOptions(defaultOptions?: DefaultOptions): DefaultOptions {
+  return mergeQueryClientDefaultOptions(monorepoDefaultOptions, defaultOptions);
+}
+
+/**
+ * monorepo 전용 기본값을 공통 QueryClient 옵션 형태로 정규화합니다.
+ */
+function toSharedOptions({
+  onGlobalError,
+  defaultOptions,
+}: CoreQueryClientOptions = {}): SharedQueryClientOptions {
+  return {
+    onGlobalError,
+    defaultOptions: mergeMonorepoDefaultOptions(defaultOptions),
+  };
+}
+
+export function makeCoreQueryClient(options: CoreQueryClientOptions = {}) {
+  return makeSharedQueryClient(toSharedOptions(options));
+}
+
+export function getCoreQueryClient(options: CoreQueryClientOptions = {}) {
+  return getSharedQueryClient(toSharedOptions(options));
+}
+
+export function createCoreQueryClient(options: CoreQueryClientOptions = {}) {
+  return createSharedQueryClient(toSharedOptions(options));
+}

package/source/wrappers/monorepo/core-react/src/query-error-handler.ts

@@ -0,0 +1,62 @@
+import {
+  APP_ERROR_CODES,
+  type AppError,
+  isAppError,
+  normalizeAppError,
+} from '../../../../core/error/app-error';
+
+export type ClientQueryErrorHandlerOptions = {
+  logger?: (error: AppError) => void;
+  onError?: (error: AppError) => void;
+  onUnauthorized?: (error: AppError) => void;
+  onForbidden?: (error: AppError) => void;
+  onNotFound?: (error: AppError) => void;
+  onNetworkError?: (error: AppError) => void;
+  onUnknownError?: (error: AppError) => void;
+};
+
+export function handleClientQueryError(
+  error: unknown,
+  {
+    logger,
+    onError,
+    onUnauthorized,
+    onForbidden,
+    onNotFound,
+    onNetworkError,
+    onUnknownError,
+  }: ClientQueryErrorHandlerOptions = {},
+) {
+  const appError = isAppError(error) ? error : normalizeAppError(error);
+
+  logger?.(appError);
+  onError?.(appError);
+
+  switch (appError.code) {
+    case APP_ERROR_CODES.UNAUTHORIZED:
+      onUnauthorized?.(appError);
+      return;
+    case APP_ERROR_CODES.FORBIDDEN:
+      onForbidden?.(appError);
+      return;
+    case APP_ERROR_CODES.NOT_FOUND:
+      onNotFound?.(appError);
+      return;
+    case APP_ERROR_CODES.NETWORK_ERROR:
+      onNetworkError?.(appError);
+      return;
+    default:
+      onUnknownError?.(appError);
+  }
+}
+
+/**
+ * monorepo 앱은 query 전역 에러 정책을 provider에 쉽게 주입할 수 있게 helper를 유지합니다.
+ */
+export function createClientQueryErrorHandler(
+  options: ClientQueryErrorHandlerOptions = {},
+) {
+  return (error: unknown) => {
+    handleClientQueryError(error, options);
+  };
+}

package/source/wrappers/monorepo/core-react/src/query-keys.ts

@@ -0,0 +1,22 @@
+type QueryKeyValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Record<string, unknown>
+  | readonly unknown[];
+
+export function createQueryKeys<const TScope extends string>(scope: TScope) {
+  return {
+    all: [scope] as const,
+    lists: () => [scope, 'list'] as const,
+    list: <TParams extends QueryKeyValue>(params?: TParams) =>
+      params === undefined
+        ? ([scope, 'list'] as const)
+        : ([scope, 'list', params] as const),
+    details: () => [scope, 'detail'] as const,
+    detail: <TId extends QueryKeyValue>(id: TId) =>
+      [scope, 'detail', id] as const,
+  };
+}

package/source/wrappers/monorepo/request/core-fetch.ts

@@ -0,0 +1,27 @@
+import { executeRequest, type RequestOptions } from './core-request';
+
+export type CoreFetchOptions = Omit<RequestOptions, 'method' | 'url'> & {
+  method?: RequestOptions['method'];
+};
+
+export type CoreFetchFunction = <T = unknown>(
+  endpoint: string,
+  options?: CoreFetchOptions,
+) => Promise<T>;
+
+/**
+ * monorepo 패키지 공개 API는 endpoint + options 형태를 유지하고,
+ * 실제 요청 본체는 core-request wrapper로 위임합니다.
+ */
+export const coreFetch: CoreFetchFunction = async <T = unknown>(
+  endpoint: string,
+  options: CoreFetchOptions = {},
+): Promise<T> => {
+  const { method = 'GET', ...rest } = options;
+
+  return executeRequest<T>({
+    method,
+    url: endpoint,
+    ...rest,
+  });
+};

package/source/wrappers/monorepo/request/core-request.ts

@@ -0,0 +1,93 @@
+import {
+  APP_ERROR_CODES,
+  type AppError,
+  getAppErrorMessage,
+} from '../../../core/error/app-error';
+import {
+  createRequestHeaders,
+  executeRequest as executeSharedRequest,
+  type JsonObject,
+  type JsonValue,
+  type RequestData,
+  type RequestOptions as SharedRequestOptions,
+  type RequestParamValue,
+  type RequestParams,
+} from '../../../core/request/request-core';
+import { getCoreConfig } from '../core/internal';
+
+export type AuthMode = 'auto' | 'none';
+
+export type RequestOptions = SharedRequestOptions & {
+  siteId?: string;
+  auth?: AuthMode;
+};
+
+function isBrowser() {
+  return typeof window !== 'undefined';
+}
+
+function resolveSiteId(siteId?: string) {
+  const resolvedSiteId = siteId ?? getCoreConfig().siteId;
+
+  if (resolvedSiteId) {
+    return resolvedSiteId;
+  }
+
+  throw {
+    code: APP_ERROR_CODES.INVALID_CONFIGURATION,
+    message: getAppErrorMessage(APP_ERROR_CODES.INVALID_CONFIGURATION),
+    status: 500,
+  } satisfies AppError;
+}
+
+function shouldAttachAuth(
+  requestUrl: string,
+  baseUrl: string | undefined,
+  auth: AuthMode,
+) {
+  if (auth === 'none' || !baseUrl) {
+    return false;
+  }
+
+  return new URL(requestUrl).origin === new URL(baseUrl).origin;
+}
+
+export type {
+  JsonObject,
+  JsonValue,
+  RequestData,
+  RequestParamValue,
+  RequestParams,
+};
+
+/**
+ * monorepo wrapper는 siteId, X-Site-Id, same-origin auth 같은
+ * 배포 형태별 규칙만 주입합니다.
+ */
+export function executeRequest<T>({
+  siteId,
+  auth = 'auto',
+  ...options
+}: RequestOptions): Promise<T> {
+  const resolvedSiteId = resolveSiteId(siteId);
+
+  return executeSharedRequest<T>(options, {
+    resolveBaseUrl: (baseUrl) => baseUrl ?? getCoreConfig().baseUrl,
+    createHeaders: ({ data, headers }) => {
+      const nextHeaders = createRequestHeaders(data, headers);
+
+      nextHeaders.set('X-Site-Id', resolvedSiteId);
+
+      return nextHeaders;
+    },
+    resolveCredentials: ({ requestUrl, resolvedBaseUrl }) => {
+      if (!isBrowser()) {
+        return undefined;
+      }
+
+      return shouldAttachAuth(requestUrl, resolvedBaseUrl, auth)
+        ? 'include'
+        : undefined;
+    },
+  });
+}

package/source/wrappers/next/auth/auth-error-listener.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname, useRouter } from 'next/navigation';
+
+import { AUTH_UNAUTHORIZED_EVENT } from '../../../core/auth/auth-events';
+import { routePaths } from '../../../core/routes/route-paths';
+
+/**
+ * AppProviders에 렌더링해두면 unauthorized 이벤트를 받아
+ * 로그인 페이지로 이동시킬 수 있는 템플릿 예시입니다.
+ */
+export function AuthErrorListener() {
+  const pathname = usePathname();
+  const router = useRouter();
+
+  useEffect(() => {
+    function handleUnauthorized() {
+      if (pathname === routePaths.login) {
+        return;
+      }
+
+      router.replace(routePaths.login);
+    }
+
+    window.addEventListener(AUTH_UNAUTHORIZED_EVENT, handleUnauthorized);
+
+    return () => {
+      window.removeEventListener(AUTH_UNAUTHORIZED_EVENT, handleUnauthorized);
+    };
+  }, [pathname, router]);
+
+  return null;
+}