v0.4.1 — books.create() pageCount 명시 처리

fix(books): books.create() 의 pageCount 명시 처리·검증 추가

Why

creationType=PDF_UPLOAD / MIX_COVER_TEMPLATE 시 서버가 pageCount 필수로 요구하나, 기존 SDK 는 ...extraData 로 흡수만 하고 명시적 검증/타입 힌트가 없어 누락 시 서버 400 으로 발견되던 갭 해소.

What

• books.create({ ..., pageCount }) 시그니처에서 명시적으로 분리·검증
• creationType=PDF_UPLOAD / MIX_COVER_TEMPLATE 인데 pageCount 가 number 가 아니거나 <=0 이면 즉시 SweetbookValidationError (field: pageCount)
• creationType=TEMPLATE 에서 pageCount 보내도 payload 에 포함만 함 (서버가 무시)
• TypeScript BookCreateRequest.pageCount?: number 는 이전부터 선언돼 있어 타입 변경 없음

Backward compatibility

기존 creationType=TEMPLATE 호출자는 영향 없음. extraData 로 pageCount 보내던 호출자도 그대로 동작.

Usage

```javascript
await client.books.create({
bookSpecUid: 'SQUAREBOOK_HC',
creationType: 'PDF_UPLOAD',
pageCount: 24,
});
```

테스트: 8 케이스 신규, 전체 32/32 통과.

v0.4.0 — list envelope 통일 호환 강화

photobook-api commit 6fbf346 (2026-05-11) 의 list 응답 envelope 평탄화에 대응. v0.2.1 부터 ResponseParser.toListResult 가 신·구 envelope 양쪽 분기를 지원하던 토대 위에 다음을 보강.

Changed

• ResponseParser.getList — 인식 키 19개로 확장: orders / items / books / templates / photos / keys / accounts / memos / configs / deliveries / notifications / categories / transactions / targetTypes / daily / referrers / events / logs / bookSpecs. 마지막 fallback 으로 data 객체의 첫 배열 자동 채택
• ResponseParser.getPagination — 구 photos 응답의 data.totalCount 를 pagination.total 로 자동 흡수
• ResponseParser.toListResult — 빈 pagination 일 때 응답에 포함하지 않음 (template-categories 등 pagination 없는 list 응답이 깔끔)
• client.bookSpecs.list / client.credits.transactions — toListResult 사용으로 통일

변경된 envelope

Before:
```json
{ "success": true, "data": { "books": [...], "pagination": {...} } }
```

After (commit 6fbf346 이후):
```json
{
"success": true,
"data": [...],
"pagination": { "total": 120, "limit": 20, "offset": 0, "hasNext": true }
}
```

두 envelope 모두에서 result.books (또는 toListResult key) 가 항상 배열, result.pagination 이 항상 최상위.

Tests

• tests/response_envelope.test.js 8건 추가
• npm test 24/24 통과 (helpers 16 + envelope 8)

Migration

v0.3.x → v0.4.0: 추가 호환 only. 기존 list 메서드 시그니처/리턴 shape 그대로. 의존하는 4 demo (diaryBook-demo, kidsDailyBook-demo, socialBook-demo, partner-order-demo) 도 v0.4.0 으로 갱신 완료.

이슈: #3

v0.3.0

Added — SDK 헬퍼 (다단계 플로우 한 호출)

R011-S01 (16p 책에 35+ API 호출) / C08 (다단계 실패 컨텍스트) 대응.

새 메서드

• client.helpers.createBookFromTemplate(input) — TEMPLATE 모드 책 + 표지 + 내지 N + finalize 한 호출
• client.helpers.uploadPdfAndOrder(input) — PDF_UPLOAD 모드 책 + PDF 2종 + finalize + 견적 + 주문 한 호출

새 예외 SweetbookHelperError

• stage — HelperStage 상수
• bookUid / orderUid — 부분 성공 후 cleanup 결정용
• partial — 단계별 부분 성공 정보
• contentIndex — 내지 삽입 실패 시 페이지 index
• cause — 원 SweetbookApiError
• userMessage() — cause 가 ApiError 면 위임

TypeScript

• HelpersClient / CreateBookFromTemplateInput / UploadPdfAndOrderInput / BookBuildResult / PdfOrderBuildResult / SweetbookHelperError / HelperStage / HelperErrorCodes
• Photos / Credits / Webhook 도 strong-typed 인터페이스 강화

Migration

v0.2.x → v0.3.0 은 추가 only. 기존 sub-client 동작 그대로 (하위 호환).

const { SweetbookClient, SweetbookHelperError, HelperStage } = require('bookprintapi-nodejs-sdk');
const c = new SweetbookClient({ apiKey: '...' });

try {
  const result = await c.helpers.createBookFromTemplate({
    bookSpec: { uid: 'PHOTOBOOK_A4_SC' },
    cover: { templateUid: 'cv_xxx', params: { title: 'My Book' } },
    contents: [
      { templateUid: 'p_xxx', params: { ... }, bindingFiles: { mainPhoto: file1 } },
    ],
    options: { externalRef: 'ORDER-123' },
  });
} catch (e) {
  if (e instanceof SweetbookHelperError) {
    if (e.bookUid && e.stage !== HelperStage.CONTENT_INSERT) {
      await c.books.delete(e.bookUid);
    }
  }
  throw e;
}

Tests: npm test 16/16 통과

v0.2.2

multipart 파일 part 이름 회귀 정정.

Fixed

• 서버는 템플릿이 정의한 binding 이름(예: coverPhoto)을 multipart part name 으로 요구. 0.2.1 까지는 모든 파일을 files / rowPhotos 단일 필드명으로 보내 서버 거부.

Added

• client.covers.create(bookUid, templateUid, parameters, { bindingFiles: { coverPhoto: file } })
• client.contents.insert(bookUid, templateUid, parameters, { bindingFiles: { mainPhoto: f1, subPhoto: f2 } })
• _buildTemplateFormData 시그니처 객체 옵션화

Deprecated

• covers.create 4번째 인자 Array 형태, contents.insert 의 options.files — process.emitWarning 출력. 호환 보존하나 동작 보장 안 됨.

Migration

// Before (v0.2.1, 서버 거부됨)
await client.covers.create(bookUid, templateUid, parameters, [file]);

// After (v0.2.2)
await client.covers.create(bookUid, templateUid, parameters, {
  bindingFiles: { coverPhoto: file },
});

발견 경위: Java SDK sandbox 99 통합 테스트 3-시나리오 검증.

v0.2.1

v0.2.0 마이그레이션 회귀테스트 후 list 엔드포인트 본체 회귀 수정 + examples 핫픽스.

Fixed

• BooksClient.list / OrdersClient.list / PhotosClient.list / TemplatesClient.list — v1 평탄화 응답(data: [...] + 최상위 pagination)에서 getDict()가 빈 객체를 반환하던 본체 회귀
• examples/02_order.js — 책 목록 접근 폴백 패턴으로 안정화

Added

• ResponseParser.toListResult(key) — 리스트 응답을 { [key]: [...], pagination } 형태로 정규화하는 신규 헬퍼. 신/구 응답 shape 모두 호환
• index.d.ts: PhotosClient.list 반환 타입 구체화, toListResult 시그니처 추가

Migration Notes (v0.2.0 → v0.2.1)

v0.2.0에서 await client.books.list(...) 결과가 빈 객체로 보이던 사용자는 0.2.1 업그레이드 후 result.books / result.pagination 으로 접근 가능합니다.

자세한 내용: CHANGELOG

v0.2.0 — 99번 v1 마스터 변경사항 마이그레이션

Changelog

0.2.0 (2026-04-28)

서버 master 대비 develop 브랜치 변경사항(99번 v1 적용분) 반영.

Added

• lib/errorcodes.js — ErrorCodes 24종 카탈로그 + ConstraintTypes 6종
• lib/order_status.js — OrderStatus 12종 + ORDER_STATUS_CODE / ORDER_STATUS_FROM_CODE 매핑
• FieldError 클래스 (core.js) — field / message / currentValue / requiredValue / constraint
• SweetbookApiError.fieldErrors (FieldError[])
• SweetbookApiError.data (일부 errorCode 진단 객체 — INSUFFICIENT_CREDIT 등)
• SweetbookApiError#fieldError(name) / userMessage() 헬퍼
• ResponseParser#success / getErrorCode() / getErrors() / getFieldErrors() / getFieldError() / getPageMeta() 신규
• TemplatesClient#getSchema(uid) — GET /templates/{uid}/schema (JSON Schema draft-07)
• TS 타입: PageMeta / FieldError / ErrorCodes / ConstraintTypes / OrderStatus / BookDetail / TemplateSchema

Changed

• SweetbookApiError.fromResponse() — errorCode (camelCase) 우선 파싱, snake_case fallback
• ResponseParser#getList() — 평탄화 응답(data: [...]) 우선, 구버전 data: {orders|items|...} 자동 흡수
• ResponseParser#getPagination() — 평탄화 응답에서 최상위 pagination 우선
• TS: OrderListItem.orderStatus / OrderItemDetail.itemStatus number → OrderStatusValue | string (Breaking 타입)
• TS: OrderListItem.orderStatusCode / OrderItemDetail.itemStatusCode 신규 (관리자 전용 옵셔널)
• TS: BookListItem.status string 유지, 신규 BookDetail (단건 응답) 분리
• TS: 응답 객체 다수에 pageMeta?: PageMeta 추가

Migration Notes (v0.1 → v0.2)

• err.error_code → err.errorCode (기존 표기도 호환되지만 문서/TS는 camelCase 통일)
• 분기는 ErrorCodes.* 상수 사용. 메시지 문자열 파싱 금지
• 주문 상태 분기는 order.orderStatus === OrderStatus.PAID (TS 에서 === 20 비교는 컴파일 에러)
• 사용자 표시 메시지는 err.userMessage() 또는 err.details[0]
• err.fieldErrors 로 폼 UI 하이라이트 자동화 가능

Compatibility

• 응답 shape 6필드 고정(success / errorCode / message / data / errors[] / fieldErrors[])
• 성공 응답은 변경 없음
• 구버전 error_code snake_case 응답도 fallback 처리

v0.1.1 — 문서/예제 개선

요약

런타임 코드 변화는 없고 문서와 예제만 개선된 패치 릴리스입니다.

변경 내역

• README 설치 가이드를 git 태그 기반으로 전환 — npm publish 불필요

  npm install github:sweet-book/bookprintapi-nodejs-sdk#v0.1.1
  

• require('bookprintapi-nodejs-sdk') → require('bookprintapi') 예시 일치 (git 설치 시 dependencies 키 이름)
• examples/README.md 신설 — 시퀀스 다이어그램 + 백엔드 전제 경고
• examples/server_pipeline.js 신설 — Python SDK 대칭 E2E 파이프라인 예제 (책 생성 → 표지 → 내지 → 발행면 → finalize → 견적 → 주문)
• examples/sample_photo.jpg 추가 (server_pipeline 실행용)
• 관련 3-tier 레퍼런스 앱으로 partner-order-demo 링크

주의

SDK를 브라우저/프론트엔드 앱에 번들하지 마세요. API Key가 노출됩니다.
권장 구조: 브라우저 → 파트너 백엔드(이 SDK 사용) → Sweetbook API

다음 버전

v0.2.0은 C04/C19 (pageMeta, orderStatus) 런타임 변경 반영 + 5번 서버 배포 완료 시점에 태그 예정.

v0.1.1-beta

• fix: books.create 기본 creationType을 TEMPLATE로 변경 (서버 필드 의미 변경 반영)

v0.1.0-beta

BookPrintAPI Node.js SDK 초기 베타

• 책 생성/조회/확정/삭제
• 사진 업로드
• 표지/내지 생성
• 주문 생성/조회/취소/배송지변경
• 충전금 잔액/거래내역/Sandbox충전
• 웹훅 서명 검증
• 예제 (create_book, order, webhook_server)