@ph-cms/api-contract

Shared Zod schemas and TypeScript types for PH-CMS.

This package is intended to be published to npm and consumed by servers, clients, and tooling that need a single source of truth for request and response contracts.

Installation

npm install @ph-cms/api-contract zod

Usage

import { CreateContentSchema, type CreateContentRequest } from '@ph-cms/api-contract';
import { RegisterSchema, type RegisterRequest } from '@ph-cms/api-contract';

// Create Content
const contentPayload: CreateContentRequest = {
  title: 'Hello',
  channelUid: 'news',
  type: 'post',
  status: 'published',
};

const parsedContent = CreateContentSchema.parse(contentPayload);

// Register
const registerPayload: RegisterRequest = {
  email: '[email protected]',
  password: 'password123',
  display_name: '홍길동',
  phone_number: '010-1234-5678', // 선택 사항
  channelUid: 'my-channel',
  termCodes: ['SERVICE_TERM', 'PRIVACY_TERM'],
};

const parsedRegister = RegisterSchema.parse(registerPayload);

Content Status

콘텐츠의 status 필드는 다음 세 가지 값을 가집니다:

| status | 가시성 | |---|---| | 'published' | 모든 사용자(비로그인 포함)에게 공개 | | 'draft' | 작성자 본인 및 admin/manager만 조회 가능 | | 'private' | 작성자 본인 및 admin/manager만 조회 가능 |

ListContentQuerySchema의 status 필드는 'published' | 'draft' | 'private'로 타입이 고정되어 있습니다.

Content Response Types

ContentDto

콘텐츠 목록/상세 조회 응답 타입입니다. stat.child 필드를 통해 자식 콘텐츠의 타입별 갯수를 확인할 수 있습니다.

import type { ContentDto, ContentStatDto } from '@ph-cms/api-contract';

const content: ContentDto = response.data.content[0];

// 자식 갯수 접근
const replyCount: number = content.stat.child['reply'] ?? 0;

ContentStatDto

interface ContentStatDto {
  view_count: number;
  like_count: number;
  share_count: number;
  dislike_count: number;
  child: Record<string, number>; // { [childType]: count }
}

• child는 항상 객체로 반환됩니다 (자식이 없으면 {}).
• 키는 자식 콘텐츠의 type, 값은 해당 타입의 자식 수입니다.

Place Search Contracts

장소 검색 계약이 추가되었습니다.

• PlaceSearchQuerySchema
• IntegratedPlaceSchema
• PlaceSearchResponseSchema

IntegratedPlace는 공급자 차이와 무관하게 고정된 응답 shape를 가집니다.

type IntegratedPlace = {
  id: string;
  name: string;
  address: string;
  location: { lat: number; lng: number };
  category: string;
  provider: 'google' | 'naver';
  phoneNumber: string | null;
  link: string | null;
  photos: Array<{
    url: string;
    width: number | null;
    height: number | null;
    attribution: string | null;
  }>;
  reviews: Array<{
    title: string;
    link: string;
    snippet: string;
    author: string | null;
    date: string | null;
  }>;
};

빈 값도 키가 생략되지 않고 항상 null 또는 []로 반환되도록 설계되어 있습니다.

User Contracts

사용자 프로필과 팔로우 관련 계약이 포함되어 있습니다.

UserProfileDto

공개 프로필 응답은 팔로워 수를 포함합니다.

type UserProfileDto = {
  uid: string;
  username: string | null;
  display_name: string;
  avatar_url: string | null;
  follower_count: number;
  profile_data: Record<string, any>;
};

UserDto

인증된 사용자 상세 응답도 동일하게 follower_count를 포함합니다.

Follow Contracts

아래 스키마와 타입이 추가되었습니다.

• FollowStatusResponseSchema
• FollowUserResponseSchema
• FollowStatusResponse
• FollowUserResponse

type FollowStatusResponse = {
  is_following: boolean;
};

type FollowUserResponse = {
  success: boolean;
  message: string;
  is_following: boolean;
};

Exports

• Auth, content, channel, user, hierarchy, policy, terms, geo, and common schemas
• Inferred TypeScript types derived from the shared Zod schemas

Auth Schemas

| Schema | 설명 | |---|---| | RegisterSchema | 이메일 회원가입 요청. channelUid 또는 channelSlug 중 하나 필수. phone_number 지원 | | FirebaseRegisterSchema | Firebase 서버 사이드 회원가입 요청. phone_number 지원 | | LoginSchema | 이메일/비밀번호 로그인 | | FirebaseExchangeSchema | Firebase ID 토큰 교환 | | AnonymousLoginSchema | 익명 로그인 |

License

MIT