@bstage-sdk/bridge 0.0.0-stage → 0.9.0

package/dist/frame.d.cts

@@ -0,0 +1,72 @@
+import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-9N0GFq5b.cjs';
+
+/** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
+interface BridgeClientConfig {
+    readonly session: string;
+    readonly hostOrigin: string;
+}
+/** 이벤트 구독 해제 함수. */
+type Unsubscribe = () => void;
+/**
+ * 프레임 안 브리지 클라이언트. `globalThis.__bstage_bridge__`에 설치된다.
+ * core·react 어댑터는 이 모양을 구조적으로 읽는다(패키지 의존 없음).
+ */
+interface BridgeClient {
+    readonly version: 1;
+    readonly hostOrigin: string;
+    /** init 수신 시 resolve. reject하지 않는다(호스트가 늦게 붙으면 ready를 계속 재전송한다). */
+    readonly ready: Promise<BridgeInit>;
+    /** 지금까지 받은 init(이후 locale·member·theme·slot.context 이벤트가 반영된 값). 수신 전이면 undefined. */
+    getInit(): BridgeInit | undefined;
+    request<T extends BridgeRequestType>(type: T, payload: BridgeRequestMap[T]['req']): Promise<BridgeRequestMap[T]['res']>;
+    on<E extends keyof BridgeEventMap>(type: E, fn: (payload: BridgeEventMap[E]) => void): Unsubscribe;
+    /** 브리지 경유 fetch(`createBridgeFetch(this)`). */
+    readonly fetch: typeof globalThis.fetch;
+}
+/** 프레임 런타임이 쓰는 전역의 최소 모양 — 테스트에서 가짜 창을 넘길 수 있게 한다. */
+interface RuntimeGlobal {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    addEventListener(type: 'message', fn: (ev: {
+        source: unknown;
+        origin: string;
+        data: unknown;
+    }) => void): void;
+    crypto?: {
+        getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+    };
+    __bstage_bridge__?: BridgeClient;
+}
+/** `createBridgeFetch`가 요구하는 클라이언트 부분. */
+type BridgeRequester = Pick<BridgeClient, 'request'>;
+
+interface CreateBridgeClientOptions extends Partial<BridgeClientConfig> {
+    /** 프레임 전역. 기본 `globalThis`(테스트용). */
+    readonly global?: RuntimeGlobal;
+}
+/**
+ * 프레임 브리지 클라이언트를 만들고 `globalThis.__bstage_bridge__`에 설치한다.
+ * 이미 설치돼 있으면 그 인스턴스를 돌려준다.
+ *
+ * 세션·hostOrigin을 생략하면 srcdoc 부트스트랩이 심은 `__bstage_bridge_config__`를 읽는다.
+ * 보통은 부트스트랩이 직접 호출하므로 템플릿 코드가 부를 일은 없다.
+ */
+declare function createBridgeClient(options?: CreateBridgeClientOptions): BridgeClient;
+
+/**
+ * 브리지 경유 fetch를 만든다. 요청을 `fetch` 브리지 요청으로 바꾸고, 호스트가 돌려준
+ * `{ status, statusText, headers, bodyText }`로 `Response`를 다시 만든다.
+ *
+ * **자기완결 함수다** — `bridgeRuntime`과 함께 srcdoc에 `toString()`으로 심긴다(runtime.ts 주석 참고).
+ *
+ * 제약(호스트 fetch 정책과 프레임에서 할 수 있는 일의 경계):
+ * - body는 문자열·`URLSearchParams`·null만. FormData·Blob·스트림은 `TypeError`.
+ * - `Request` 입력은 url·method·headers만 읽는다(본문은 동기로 읽을 수 없어 `init.body`로 넘긴다).
+ * - `credentials`·`mode`·`cache` 등은 무시된다 — 호스트가 `credentials: "same-origin"`으로 보낸다.
+ * - `signal`은 프레임 쪽 대기만 끊는다(호스트 요청은 취소되지 않는다).
+ * - 응답 헤더는 content-type만 온다.
+ */
+declare function createBridgeFetch(client: BridgeRequester): typeof globalThis.fetch;
+
+export { type BridgeClient, type BridgeClientConfig, type BridgeRequester, type CreateBridgeClientOptions, type Unsubscribe, createBridgeClient, createBridgeFetch };

package/dist/frame.d.ts

@@ -0,0 +1,72 @@
+import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-9N0GFq5b.js';
+
+/** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
+interface BridgeClientConfig {
+    readonly session: string;
+    readonly hostOrigin: string;
+}
+/** 이벤트 구독 해제 함수. */
+type Unsubscribe = () => void;
+/**
+ * 프레임 안 브리지 클라이언트. `globalThis.__bstage_bridge__`에 설치된다.
+ * core·react 어댑터는 이 모양을 구조적으로 읽는다(패키지 의존 없음).
+ */
+interface BridgeClient {
+    readonly version: 1;
+    readonly hostOrigin: string;
+    /** init 수신 시 resolve. reject하지 않는다(호스트가 늦게 붙으면 ready를 계속 재전송한다). */
+    readonly ready: Promise<BridgeInit>;
+    /** 지금까지 받은 init(이후 locale·member·theme·slot.context 이벤트가 반영된 값). 수신 전이면 undefined. */
+    getInit(): BridgeInit | undefined;
+    request<T extends BridgeRequestType>(type: T, payload: BridgeRequestMap[T]['req']): Promise<BridgeRequestMap[T]['res']>;
+    on<E extends keyof BridgeEventMap>(type: E, fn: (payload: BridgeEventMap[E]) => void): Unsubscribe;
+    /** 브리지 경유 fetch(`createBridgeFetch(this)`). */
+    readonly fetch: typeof globalThis.fetch;
+}
+/** 프레임 런타임이 쓰는 전역의 최소 모양 — 테스트에서 가짜 창을 넘길 수 있게 한다. */
+interface RuntimeGlobal {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    addEventListener(type: 'message', fn: (ev: {
+        source: unknown;
+        origin: string;
+        data: unknown;
+    }) => void): void;
+    crypto?: {
+        getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+    };
+    __bstage_bridge__?: BridgeClient;
+}
+/** `createBridgeFetch`가 요구하는 클라이언트 부분. */
+type BridgeRequester = Pick<BridgeClient, 'request'>;
+
+interface CreateBridgeClientOptions extends Partial<BridgeClientConfig> {
+    /** 프레임 전역. 기본 `globalThis`(테스트용). */
+    readonly global?: RuntimeGlobal;
+}
+/**
+ * 프레임 브리지 클라이언트를 만들고 `globalThis.__bstage_bridge__`에 설치한다.
+ * 이미 설치돼 있으면 그 인스턴스를 돌려준다.
+ *
+ * 세션·hostOrigin을 생략하면 srcdoc 부트스트랩이 심은 `__bstage_bridge_config__`를 읽는다.
+ * 보통은 부트스트랩이 직접 호출하므로 템플릿 코드가 부를 일은 없다.
+ */
+declare function createBridgeClient(options?: CreateBridgeClientOptions): BridgeClient;
+
+/**
+ * 브리지 경유 fetch를 만든다. 요청을 `fetch` 브리지 요청으로 바꾸고, 호스트가 돌려준
+ * `{ status, statusText, headers, bodyText }`로 `Response`를 다시 만든다.
+ *
+ * **자기완결 함수다** — `bridgeRuntime`과 함께 srcdoc에 `toString()`으로 심긴다(runtime.ts 주석 참고).
+ *
+ * 제약(호스트 fetch 정책과 프레임에서 할 수 있는 일의 경계):
+ * - body는 문자열·`URLSearchParams`·null만. FormData·Blob·스트림은 `TypeError`.
+ * - `Request` 입력은 url·method·headers만 읽는다(본문은 동기로 읽을 수 없어 `init.body`로 넘긴다).
+ * - `credentials`·`mode`·`cache` 등은 무시된다 — 호스트가 `credentials: "same-origin"`으로 보낸다.
+ * - `signal`은 프레임 쪽 대기만 끊는다(호스트 요청은 취소되지 않는다).
+ * - 응답 헤더는 content-type만 온다.
+ */
+declare function createBridgeFetch(client: BridgeRequester): typeof globalThis.fetch;
+
+export { type BridgeClient, type BridgeClientConfig, type BridgeRequester, type CreateBridgeClientOptions, type Unsubscribe, createBridgeClient, createBridgeFetch };

package/dist/frame.js

@@ -0,0 +1,21 @@
+import {
+  bridgeRuntime,
+  createBridgeFetch
+} from "./chunk-KQMJY4ZH.js";
+
+// src/frame/createBridgeClient.ts
+var BRIDGE_CONFIG_GLOBAL = "__bstage_bridge_config__";
+function createBridgeClient(options = {}) {
+  const g = options.global ?? globalThis;
+  const installed = g[BRIDGE_CONFIG_GLOBAL] ?? {};
+  const session = options.session ?? installed.session;
+  const hostOrigin = options.hostOrigin ?? installed.hostOrigin;
+  if (typeof session !== "string" || typeof hostOrigin !== "string") {
+    throw new TypeError("[bstage-bridge] session\uACFC hostOrigin\uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
+  }
+  return bridgeRuntime(g, createBridgeFetch, { session, hostOrigin });
+}
+export {
+  createBridgeClient,
+  createBridgeFetch
+};