@runners/pudding-js

푸딩 도구(청첩장·대본·체크리스트·예산·일정)를 제휴사 사이트에 붙이는 브라우저 SDK.

두 가지 쓰임이 있고, 둘 다 선택이다 — REST API 를 직접 불러도 되고, iframe 을 손으로 심어도 된다. SDK 는 그때 반복해서 다시 짜게 되는 부분만 대신한다.

import { Pudding } from '@runners/pudding-js';

쓰임 A · 데이터만 받아 화면은 직접 그린다

const couple = Pudding.client({ accessToken });   // 제휴사 서버가 발급한 유저 토큰

const list = await couple.checklist.create({
  weddingDate: '2027-03-20',
  budget: 50_000_000,
  onProgress: (p) => setBar(p.progress),          // 0 → 100
});

list.sections.map((s) => <MySection data={s} />); // 화면은 제휴사 디자인 그대로

create() 한 번이 네 단계를 처리한다 — 초안 요청(202) → 진행률 수신 → 완료 대기 → 확정 저장. 진행률은 WebSocket 으로 받고, 사내망이 wss:// 를 막으면 폴링으로 알아서 갈아탄다.

쓰임 B · 편집기를 iframe 으로 심는다

const editor = Pudding.mount('#pudding', { embedUrl });  // 서버가 준 주소 그대로
await editor.ready;
editor.on('error', (e) => console.warn(e.code));
editor.reload({ embedUrl: freshUrl });   // 임베드 토큰이 15분이라 만료되면
editor.destroy();                        // SPA 화면 전환 시

<iframe src={embedUrl}> 한 줄로도 뜬다. mount() 가 더 해주는 건 높이 자동 맞춤과 발신자 구분이다 — 편집기를 여러 개 심을 때 e.origin 만 보면 한쪽 높이가 다른 쪽을 덮는다.

토큰

| | 어디에 | 수명 | |---|---|---| | pk_live_ API 키 | 제휴사 서버만 | 없음 | | access_token 유저 토큰 | 브라우저 OK | 60분 | | cs_live_ 임베드 토큰 | 브라우저 OK | 15분 |

이 SDK 는 API 키를 받지 않는다. 브라우저에 두면 유출이라, 서버가 발급한 토큰만 받는다.

토큰이 만료되면 문자열 대신 함수를 넘긴다 — 호출할 때마다 물어보므로 갱신 지점이 한 곳이 된다.

Pudding.client({ accessToken: () => fetch('/my-server/pudding-token').then((r) => r.text()) });

에러

e.code 로 갈린다. 상태코드는 겹쳐서 분기에 못 쓴다 — 403 하나에 "요금제가 낮다"와 "키로는 못 부르는 기능이다"가 같이 들어온다.

try { await couple.checklist.mine(); }
catch (e) { if (e.code === 'plan_required') showUpgrade(); }

plan_required · couple_not_found · invalid_input · generation_failed · timeout · aborted · network_error 등.

구조

src/generated/paths.d.ts   서버 스펙에서 자동 생성 (27,556줄) — 손대지 않는다
src/http.ts                봉투 벗기기 · 토큰 · 재시도 · 취소
src/stream.ts              WebSocket + 폴링 폴백
src/embed.ts               iframe 헬퍼
src/index.ts               제휴사가 보는 이름들

엔드포인트는 101개지만 손으로 쓰는 건 겉의 15개뿐이다. 나머지는 스펙에서 뽑는다 — 그래서 서버가 바뀌어도 따라가기 쉽고, 나중에 Swift·Kotlin 으로 옮길 때도 15개만 다시 쓰면 된다.

node scripts/generate.mjs   # 서버 스펙 → 타입 (서버가 바뀌었을 때)
node build.mjs              # dist/ + public/sdk/v1.js

build.mjs 는 ESM·CJS·IIFE 세 벌을 낸다. IIFE 는 빌드 도구가 없는 곳(워드프레스·카페24)이 <script src="https://pudding.im/sdk/v1.js"> 한 줄로 쓸 수 있게 하려는 것이다.

버전

주소에 버전을 박는다(/sdk/v1.js). 제휴사가 붙여넣은 코드를 우리가 고칠 수 없으니, 깨지는 변경은 /sdk/v2.js 로 내고 v1 은 그대로 둔다.