@clack-platform/mini-app-host-core

앱인클랙 미니앱 호스트 측 브릿지 프로토콜 SSOT(단일 진실 공급원) 패키지입니다. 순수 TypeScript로만 작성되어 있으며 React·React Native 등 네이티브 의존성이 전혀 없습니다.

목적

미니앱 브릿지 프로토콜(주입 스크립트 포맷, 메시지 파싱, 네비게이션 가드, 서빙 호스트 규약)을 구현하는 곳이 두 곳 이상이면 프로토콜 드리프트가 발생합니다(_plans/appinclack-platform/09-dev-test-app-serving-gating.md §3-3 D9-6). 이 패키지는 그 로직을 한 곳에 모아 호스트 구현체들이 공유하게 합니다.

이 패키지를 쓰는 곳

• 클랙 본앱의 MiniAppWebView (clack-app/src/pages/webview/) — 미니앱을 RN WebView에 띄우는 화면
• appinclack-dev-app (로컬 테스트 앱, 09-dev-test-app-serving-gating.md §3) — 심사 전 dev 채널 미니앱을 실기기에서 확인하는 용도

⚠️ 게스트(미니앱) 측 SDK는 별도 패키지 **@clack-platform/mini-app-sdk**입니다. 이 패키지(mini-app-host-core)는 미니앱을 띄우는 쪽(호스트) 로직이고, mini-app-sdk는 미니앱 안에서 실행되는 게스트 쪽 로직입니다. 역할이 반대이므로 서로를 대체하지 않습니다.

설치 (로컬 소비)

아직 npm 배포 전이므로 파일 경로 의존성으로 소비합니다.

{
  "dependencies": {
    "@clack-platform/mini-app-host-core": "file:../clack-mini-app-host-core"
  }
}

file: 의존성은 빌드 산출물(dist/)을 소비하므로, 소비하는 프로젝트에서 설치/빌드 전에 반드시 이 패키지를 먼저 빌드해야 합니다(dist는 .gitignore 대상이라 저장소에 커밋되지 않습니다).

cd clack-mini-app-host-core && pnpm install && pnpm build
cd ../<소비 프로젝트> && pnpm install

API

프로토콜 상수

| export | 설명 | |---|---| | MINI_APP_BRIDGE_METHODS | 호스트가 처리 가능한 브릿지 메서드 목록 ['close', 'REQUEST_TOKEN', 'share', 'openExternal'] | | MiniAppBridgeMethod | 위 목록의 유니온 타입 | | MINI_APP_BRIDGE_RESPONSE | 브릿지 응답 콜백의 responseMethod 값 — { TOKEN: 'TOKEN_RESPONSE', SHARE: 'SHARE_RESPONSE' } | | MINI_APP_SHARE_SCOPE | share 브릿지 게이트 scope 문자열('mini-app:share') — 서버 scope 카탈로그와 동일 |

타입

| export | 설명 | |---|---| | MiniAppSafeArea | 세이프 에어리어 인셋(dp) { top, bottom, left, right } | | MiniAppEnv | window.__clack_env로 주입되는 환경 정보 | | BridgeMessage | 미니앱 → 호스트 브릿지 메시지 { method, id?, params? } | | ShareParams | share 요청 페이로드 | | ShareResponse | SHARE_RESPONSE 콜백 payload | | MiniAppChannel | 배포 채널 'dev' \| 'prod' |

파싱

| export | 설명 | |---|---| | parseBridgeMessage(data) | WebView onMessage raw 문자열 → BridgeMessage \| null | | parseShareParams(params?) | share 페이로드 파싱 — message·url 둘 다 없으면 null(본앱의 invalid_payload 조건과 동일) | | parseExternalUrl(params?) | openExternal 페이로드에서 http(s) URL만 추출, 아니면 null |

주입 스크립트 빌더

RN injectJavaScript 관례대로 전부 ; true;로 끝나며, 값 이스케이프는 전부 JSON.stringify 경유입니다.

| export | 설명 | |---|---| | buildInjectedBootstrapScript(token, env) | 페이지 로드 전 토큰·환경 정보 주입 (injectedJavaScriptBeforeContentLoaded) | | buildTokenUpdateScript(token) | 토큰 재발급 후 갱신 값만 재주입 | | buildBridgeCallbackScript(responseMethod, data, requestId?) | 브릿지 요청-응답 콜백. requestId 없으면 인자 자체를 생략(구버전 SDK 폴백) | | buildEmitScript(eventName, payload) | 호스트 → 미니앱 런타임 이벤트 푸시. payload는 이중 JSON.stringify로 전달(SDK와의 현행 계약이므로 변경 금지) |

네비게이션 가드

| export | 설명 | |---|---| | parseHttpOrigin(url) | http(s) URL에서 오리진·호스트명 추출 | | isAllowedMiniAppNavigation(initialUrl, targetUrl) | 미니앱 WebView 안에서 허용되는 네비게이션인지 판정 — 최초 오리진과 동일 오리진만 허용, clack.kr 하위는 항상 차단, about:blank/data:/blob:은 허용 |

서빙 호스트

_plans/appinclack-platform/05-distribution.md §2 규약을 그대로 따릅니다. app_id 자체의 형식·예약어 검증은 서버(clack-api-v4/src/lib/mini-app-app-id.ts)가 권위를 가지며, 아래 함수들은 빈 문자열 외에는 별도 검증을 하지 않습니다.

| export | 설명 | |---|---| | buildMiniAppServingHost(appId, channel) | 예: ('foo', 'dev') → 'foo-dev.clack.page', ('foo', 'prod') → 'foo.clack.page' | | buildMiniAppServingUrl(appId, channel) | 위 호스트에 https://를 붙인 전체 URL |

로컬 개발

pnpm install
pnpm check   # typecheck + lint + test + build

License

MIT