@yanolja-next/next-hub-bo-sdk 0.0.1

package/README.md

@@ -0,0 +1,127 @@
+---
+gdrive_sync: true
+gdrive_pdf_name: "NCP Backoffice SDK"
+---
+
+# NCP Backoffice SDK (Beta)
+
+NCP Backoffice SDK는 Next Hub Console에 iframe으로 포함되는 Service Backoffice를 위한
+초기화, 등록 operation 호출, 백오피스 전용 토큰 갱신 기능을 제공한다.
+
+## 토큰 구분
+
+| Context 필드 | 용도 | 전송 대상 |
+| --- | --- | --- |
+| `token` | Next Hub에 등록된 operation 호출 | Next Hub Core |
+| `backofficeToken` | 서비스 backend 직접 호출 | 해당 서비스 backend |
+
+기존 `token`과 `projectId` 키는 변경되지 않는다. `backofficeToken`과
+`backofficeTokenExpiresAt`은 추가 필드이므로 기존 SDK 사용 코드는 그대로 동작한다.
+백오피스 전용 토큰은 SDK 메모리에만 보관하며 브라우저 영구 저장소에는 기록하지 않는다.
+
+## 초기화
+
+### `waitForContext(targetOrigin, timeoutMs?)`
+
+Console에서 context를 받을 때까지 기다린다. 다른 SDK API보다 먼저 호출해야 한다.
+
+- `targetOrigin: string | string[]`: 신뢰할 Console origin
+- `timeoutMs?: number`: 초기화 제한 시간, 기본값 10초
+- 반환값: `Promise<void>`
+
+```tsx
+import { waitForContext } from '@yanolja-next/next-hub-bo-sdk';
+
+await waitForContext('https://console.ynext.cloud');
+```
+
+초기화 시 Console이 보내는 payload는 다음과 같다.
+
+```ts
+interface InitMessage {
+  type: 'INIT';
+  token: string;
+  projectId: string;
+  backofficeToken?: string;
+  backofficeTokenExpiresAt?: string;
+}
+```
+
+## 등록 operation 호출
+
+### `getApiClient(serviceName, baseUrl, options?)`
+
+기존 세션 토큰과 프로젝트 context를 사용하는 Axios client를 생성한다.
+
+```tsx
+import { getApiClient, waitForContext } from '@yanolja-next/next-hub-bo-sdk';
+
+await waitForContext('https://console.ynext.cloud');
+const client = getApiClient('my-service', 'https://api.example.com');
+const response = await client.get('/resources');
+```
+
+이 client는 `Authorization: Bearer {token}`과
+`X-NEXTHUB-CLIENT-PROJECT-ID: {projectId}`를 Next Hub Core 요청에 추가한다. 서비스
+backend 직접 호출에는 이 client 대신 백오피스 전용 토큰을 사용한다.
+
+## 서비스 backend 직접 호출
+
+### `getBackofficeToken()`
+
+현재 백오피스 전용 토큰과 만료 시각을 읽는다. `waitForContext()`가 전용 토큰 없이
+초기화되었거나 아직 호출되지 않았다면 오류를 던진다.
+
+```tsx
+import { getBackofficeToken, waitForContext } from '@yanolja-next/next-hub-bo-sdk';
+
+await waitForContext('https://console.ynext.cloud');
+const { backofficeToken, backofficeTokenExpiresAt } = getBackofficeToken();
+
+await fetch('https://service.example.com/admin/resources', {
+  headers: { Authorization: `Bearer ${backofficeToken}` },
+});
+```
+
+### `refreshBackofficeToken()`
+
+부모 Console에 새 토큰을 요청하고 갱신된 토큰 context를 반환한다. 동시에 여러 번
+호출하면 같은 Promise를 반환해 발급 요청을 한 번만 전송한다. SDK는 만료 1분 전에도
+같은 갱신 흐름을 자동 실행한다.
+
+```tsx
+import { refreshBackofficeToken } from '@yanolja-next/next-hub-bo-sdk';
+
+const refreshed = await refreshBackofficeToken();
+```
+
+갱신 실패 시 기존 토큰을 덮어쓰지 않는다. 오류 메시지에는 토큰 값을 포함하지 않는다.
+
+## 초기화 오류 알림
+
+### `notifyInitError(message, targetOrigin)`
+
+백오피스 자체 초기화가 실패했음을 Console에 알린다.
+
+```tsx
+import { notifyInitError } from '@yanolja-next/next-hub-bo-sdk';
+
+notifyInitError('설정을 불러오지 못했습니다.', 'https://console.ynext.cloud');
+```
+
+## 서비스 backend 검증
+
+서비스 backend는 요청마다 Next Hub에 확인 요청을 보내지 않는다. Auth의
+`/.well-known/jwks.json`을 캐시해 JWT 서명을 로컬 검증하고 claim을 함께 확인해야 한다.
+구체적인 검증 절차와 예제는
+[백오피스 요청 인증 가이드](https://github.com/yanolja-org/next-hub/blob/main/docs/backoffice-authentication.md)를
+참고한다.
+
+## 템플릿
+
+백오피스 프로젝트는 템플릿 저장소에서 시작할 수 있다.
+
+```bash
+git clone https://github.com/yanolja-org/iab-ncp-service-backoffice-template.git my-backoffice
+cd my-backoffice
+```

package/dist/backoffice-token-manager.d.ts

@@ -0,0 +1,25 @@
+export interface BackofficeTokenContext {
+    backofficeToken: string;
+    backofficeTokenExpiresAt: string;
+}
+export declare class BackofficeTokenManager {
+    private context;
+    private origins;
+    private refreshPromise;
+    private resolveRefresh;
+    private rejectRefresh;
+    private refreshTimer;
+    private refreshTimeout;
+    initialize(context: BackofficeTokenContext | null, origins: string[]): void;
+    reset(): void;
+    get(): BackofficeTokenContext;
+    refresh(): Promise<BackofficeTokenContext>;
+    private readonly handleMessage;
+    private completeRefresh;
+    private failRefresh;
+    private scheduleRefresh;
+    private clearTimer;
+    private clearRefreshTimeout;
+    private clearPendingRefresh;
+}
+export declare const isBackofficeTokenContext: (value: unknown) => value is BackofficeTokenContext;

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("axios"),d="READY",R="INIT",k="INIT_ERROR",u="BACKOFFICE_TOKEN_REFRESH_REQUEST",_="BACKOFFICE_TOKEN_REFRESH_RESPONSE",f="BACKOFFICE_TOKEN_ERROR",A=6e4,g=1e4;class w{constructor(){this.context=null,this.origins=[],this.refreshPromise=null,this.resolveRefresh=null,this.rejectRefresh=null,this.refreshTimer=null,this.refreshTimeout=null,this.handleMessage=e=>{var t,s,o;if(this.origins.includes(e.origin)){if(((t=e.data)==null?void 0:t.type)===_&&h(e.data)){this.completeRefresh({backofficeToken:e.data.backofficeToken,backofficeTokenExpiresAt:e.data.backofficeTokenExpiresAt});return}if(((s=e.data)==null?void 0:s.type)===f&&((o=e.data)==null?void 0:o.phase)==="refresh"){const n=typeof e.data.code=="string"?e.data.code:"UNKNOWN";this.failRefresh(new Error(`Backoffice token refresh failed: ${n}`))}}}}initialize(e,t){this.reset(),this.context=e,this.origins=[...t],window.addEventListener("message",this.handleMessage),e&&this.scheduleRefresh(e.backofficeTokenExpiresAt)}reset(){window.removeEventListener("message",this.handleMessage),this.clearTimer(),this.clearRefreshTimeout(),this.rejectRefresh&&this.rejectRefresh(new Error("Backoffice token context was reset")),this.context=null,this.origins=[],this.clearPendingRefresh()}get(){if(!this.context)throw new Error("Backoffice token is not initialized. Call waitForContext() first.");return{...this.context}}refresh(){if(!this.context||this.origins.length===0)return Promise.reject(new Error("Backoffice token is not initialized. Call waitForContext() first."));if(this.refreshPromise)return this.refreshPromise;this.refreshPromise=new Promise((e,t)=>{this.resolveRefresh=e,this.rejectRefresh=t,this.refreshTimeout=setTimeout(()=>{this.failRefresh(new Error("Backoffice token refresh timed out"))},g)});for(const e of this.origins)window.parent.postMessage({type:u},e);return this.refreshPromise}completeRefresh(e){const t=this.resolveRefresh;this.context=e,this.clearRefreshTimeout(),this.clearPendingRefresh(),this.scheduleRefresh(e.backofficeTokenExpiresAt),t==null||t({...e})}failRefresh(e){const t=this.rejectRefresh;this.clearRefreshTimeout(),this.clearPendingRefresh(),t==null||t(e)}scheduleRefresh(e){this.clearTimer();const t=Math.max(0,Date.parse(e)-Date.now()-A);this.refreshTimer=setTimeout(()=>{this.refresh().catch(()=>{})},t)}clearTimer(){this.refreshTimer!==null&&(clearTimeout(this.refreshTimer),this.refreshTimer=null)}clearRefreshTimeout(){this.refreshTimeout!==null&&(clearTimeout(this.refreshTimeout),this.refreshTimeout=null)}clearPendingRefresh(){this.refreshPromise=null,this.resolveRefresh=null,this.rejectRefresh=null}}const h=r=>{if(typeof r!="object"||r===null)return!1;const e=r;return typeof e.backofficeToken=="string"&&typeof e.backofficeTokenExpiresAt=="string"&&!Number.isNaN(Date.parse(e.backofficeTokenExpiresAt))};class C{constructor(){this.context=null}set(e){this.context=e}get(){return this.context}}const m=new C,c=new w,I=(r,e=1e4)=>{const t=Array.isArray(r)?r:[r];return c.reset(),new Promise((s,o)=>{const n=setTimeout(()=>{window.removeEventListener("message",a),o(new Error("Timeout waiting for context"))},e),a=i=>{var E,l,T;if(t.includes(i.origin)&&((E=i.data)==null?void 0:E.type)===f&&((l=i.data)==null?void 0:l.phase)==="init"){clearTimeout(n),window.removeEventListener("message",a);const S=typeof i.data.code=="string"?i.data.code:"UNKNOWN";o(new Error(`Backoffice token initialization failed: ${S}`));return}!t.includes(i.origin)||((T=i.data)==null?void 0:T.type)!==R||typeof i.data.token!="string"||typeof i.data.projectId!="string"||!M(i.data)||(clearTimeout(n),window.removeEventListener("message",a),m.set({token:i.data.token,projectId:i.data.projectId}),c.initialize(h(i.data)?{backofficeToken:i.data.backofficeToken,backofficeTokenExpiresAt:i.data.backofficeTokenExpiresAt}:null,t),s())};window.addEventListener("message",a);for(const i of t)window.parent.postMessage({type:d},i)})},O=()=>c.get(),F=()=>c.refresh(),N=(r,e)=>{const t=Array.isArray(e)?e:[e];for(const s of t)window.parent.postMessage({type:k,message:r},s)},P="X-NEXTHUB-CLIENT-PROJECT-ID",x=(r,e,t)=>{const s=p.create({baseURL:`${e}/services/${r}`,headers:{"Content-Type":"application/json",...t==null?void 0:t.headers}});return s.interceptors.request.use(o=>{const n=m.get();if(!n)throw new Error("Context not initialized. Call waitForContext() first.");return o.headers[P]=n.projectId,o.headers.Authorization=`Bearer ${n.token}`,o}),s},M=r=>{const e=r.backofficeToken!==void 0,t=r.backofficeTokenExpiresAt!==void 0;return!e&&!t||h(r)};exports.BACKOFFICE_TOKEN_ERROR_MESSAGE_TYPE=f;exports.BACKOFFICE_TOKEN_REFRESH_REQUEST_MESSAGE_TYPE=u;exports.BACKOFFICE_TOKEN_REFRESH_RESPONSE_MESSAGE_TYPE=_;exports.INIT_ERROR_MESSAGE_TYPE=k;exports.INIT_MESSAGE_TYPE=R;exports.READY_MESSAGE_TYPE=d;exports.getApiClient=x;exports.getBackofficeToken=O;exports.notifyInitError=N;exports.refreshBackofficeToken=F;exports.waitForContext=I;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { AxiosInstance } from 'axios';
+import { BackofficeTokenContext } from './backoffice-token-manager';
+export type { BackofficeTokenContext } from './backoffice-token-manager';
+export * from './message-types';
+export declare const waitForContext: (targetOrigin: string | string[], timeoutMs?: number) => Promise<void>;
+export declare const getBackofficeToken: () => BackofficeTokenContext;
+export declare const refreshBackofficeToken: () => Promise<BackofficeTokenContext>;
+export declare const notifyInitError: (message: string, targetOrigin: string | string[]) => void;
+export declare const getApiClient: (serviceName: string, baseUrl: string, options?: ApiClientOptions) => AxiosInstance;
+interface ApiClientOptions {
+    headers?: Record<string, string>;
+}

package/dist/index.js

@@ -0,0 +1,154 @@
+import k from "axios";
+const u = "READY", m = "INIT", p = "INIT_ERROR", w = "BACKOFFICE_TOKEN_REFRESH_REQUEST", g = "BACKOFFICE_TOKEN_REFRESH_RESPONSE", d = "BACKOFFICE_TOKEN_ERROR", _ = 6e4, A = 1e4;
+class x {
+  constructor() {
+    this.context = null, this.origins = [], this.refreshPromise = null, this.resolveRefresh = null, this.rejectRefresh = null, this.refreshTimer = null, this.refreshTimeout = null, this.handleMessage = (e) => {
+      var t, i, o;
+      if (this.origins.includes(e.origin)) {
+        if (((t = e.data) == null ? void 0 : t.type) === g && f(e.data)) {
+          this.completeRefresh({
+            backofficeToken: e.data.backofficeToken,
+            backofficeTokenExpiresAt: e.data.backofficeTokenExpiresAt
+          });
+          return;
+        }
+        if (((i = e.data) == null ? void 0 : i.type) === d && ((o = e.data) == null ? void 0 : o.phase) === "refresh") {
+          const n = typeof e.data.code == "string" ? e.data.code : "UNKNOWN";
+          this.failRefresh(new Error(`Backoffice token refresh failed: ${n}`));
+        }
+      }
+    };
+  }
+  initialize(e, t) {
+    this.reset(), this.context = e, this.origins = [...t], window.addEventListener("message", this.handleMessage), e && this.scheduleRefresh(e.backofficeTokenExpiresAt);
+  }
+  reset() {
+    window.removeEventListener("message", this.handleMessage), this.clearTimer(), this.clearRefreshTimeout(), this.rejectRefresh && this.rejectRefresh(new Error("Backoffice token context was reset")), this.context = null, this.origins = [], this.clearPendingRefresh();
+  }
+  get() {
+    if (!this.context)
+      throw new Error("Backoffice token is not initialized. Call waitForContext() first.");
+    return { ...this.context };
+  }
+  refresh() {
+    if (!this.context || this.origins.length === 0)
+      return Promise.reject(
+        new Error("Backoffice token is not initialized. Call waitForContext() first.")
+      );
+    if (this.refreshPromise)
+      return this.refreshPromise;
+    this.refreshPromise = new Promise((e, t) => {
+      this.resolveRefresh = e, this.rejectRefresh = t, this.refreshTimeout = setTimeout(() => {
+        this.failRefresh(new Error("Backoffice token refresh timed out"));
+      }, A);
+    });
+    for (const e of this.origins)
+      window.parent.postMessage({ type: w }, e);
+    return this.refreshPromise;
+  }
+  completeRefresh(e) {
+    const t = this.resolveRefresh;
+    this.context = e, this.clearRefreshTimeout(), this.clearPendingRefresh(), this.scheduleRefresh(e.backofficeTokenExpiresAt), t == null || t({ ...e });
+  }
+  failRefresh(e) {
+    const t = this.rejectRefresh;
+    this.clearRefreshTimeout(), this.clearPendingRefresh(), t == null || t(e);
+  }
+  scheduleRefresh(e) {
+    this.clearTimer();
+    const t = Math.max(0, Date.parse(e) - Date.now() - _);
+    this.refreshTimer = setTimeout(() => {
+      this.refresh().catch(() => {
+      });
+    }, t);
+  }
+  clearTimer() {
+    this.refreshTimer !== null && (clearTimeout(this.refreshTimer), this.refreshTimer = null);
+  }
+  clearRefreshTimeout() {
+    this.refreshTimeout !== null && (clearTimeout(this.refreshTimeout), this.refreshTimeout = null);
+  }
+  clearPendingRefresh() {
+    this.refreshPromise = null, this.resolveRefresh = null, this.rejectRefresh = null;
+  }
+}
+const f = (r) => {
+  if (typeof r != "object" || r === null)
+    return !1;
+  const e = r;
+  return typeof e.backofficeToken == "string" && typeof e.backofficeTokenExpiresAt == "string" && !Number.isNaN(Date.parse(e.backofficeTokenExpiresAt));
+};
+class C {
+  constructor() {
+    this.context = null;
+  }
+  set(e) {
+    this.context = e;
+  }
+  get() {
+    return this.context;
+  }
+}
+const T = new C(), c = new x(), P = (r, e = 1e4) => {
+  const t = Array.isArray(r) ? r : [r];
+  return c.reset(), new Promise((i, o) => {
+    const n = setTimeout(() => {
+      window.removeEventListener("message", a), o(new Error("Timeout waiting for context"));
+    }, e), a = (s) => {
+      var h, E, l;
+      if (t.includes(s.origin) && ((h = s.data) == null ? void 0 : h.type) === d && ((E = s.data) == null ? void 0 : E.phase) === "init") {
+        clearTimeout(n), window.removeEventListener("message", a);
+        const R = typeof s.data.code == "string" ? s.data.code : "UNKNOWN";
+        o(new Error(`Backoffice token initialization failed: ${R}`));
+        return;
+      }
+      !t.includes(s.origin) || ((l = s.data) == null ? void 0 : l.type) !== m || typeof s.data.token != "string" || typeof s.data.projectId != "string" || !S(s.data) || (clearTimeout(n), window.removeEventListener("message", a), T.set({
+        token: s.data.token,
+        projectId: s.data.projectId
+      }), c.initialize(
+        f(s.data) ? {
+          backofficeToken: s.data.backofficeToken,
+          backofficeTokenExpiresAt: s.data.backofficeTokenExpiresAt
+        } : null,
+        t
+      ), i());
+    };
+    window.addEventListener("message", a);
+    for (const s of t)
+      window.parent.postMessage({ type: u }, s);
+  });
+}, F = () => c.get(), O = () => c.refresh(), y = (r, e) => {
+  const t = Array.isArray(e) ? e : [e];
+  for (const i of t)
+    window.parent.postMessage({ type: p, message: r }, i);
+}, I = "X-NEXTHUB-CLIENT-PROJECT-ID", M = (r, e, t) => {
+  const i = k.create({
+    baseURL: `${e}/services/${r}`,
+    headers: {
+      "Content-Type": "application/json",
+      ...t == null ? void 0 : t.headers
+    }
+  });
+  return i.interceptors.request.use((o) => {
+    const n = T.get();
+    if (!n)
+      throw new Error("Context not initialized. Call waitForContext() first.");
+    return o.headers[I] = n.projectId, o.headers.Authorization = `Bearer ${n.token}`, o;
+  }), i;
+}, S = (r) => {
+  const e = r.backofficeToken !== void 0, t = r.backofficeTokenExpiresAt !== void 0;
+  return !e && !t || f(r);
+};
+export {
+  d as BACKOFFICE_TOKEN_ERROR_MESSAGE_TYPE,
+  w as BACKOFFICE_TOKEN_REFRESH_REQUEST_MESSAGE_TYPE,
+  g as BACKOFFICE_TOKEN_REFRESH_RESPONSE_MESSAGE_TYPE,
+  p as INIT_ERROR_MESSAGE_TYPE,
+  m as INIT_MESSAGE_TYPE,
+  u as READY_MESSAGE_TYPE,
+  M as getApiClient,
+  F as getBackofficeToken,
+  y as notifyInitError,
+  O as refreshBackofficeToken,
+  P as waitForContext
+};

package/dist/message-types.d.ts

@@ -0,0 +1,6 @@
+export declare const READY_MESSAGE_TYPE = "READY";
+export declare const INIT_MESSAGE_TYPE = "INIT";
+export declare const INIT_ERROR_MESSAGE_TYPE = "INIT_ERROR";
+export declare const BACKOFFICE_TOKEN_REFRESH_REQUEST_MESSAGE_TYPE = "BACKOFFICE_TOKEN_REFRESH_REQUEST";
+export declare const BACKOFFICE_TOKEN_REFRESH_RESPONSE_MESSAGE_TYPE = "BACKOFFICE_TOKEN_REFRESH_RESPONSE";
+export declare const BACKOFFICE_TOKEN_ERROR_MESSAGE_TYPE = "BACKOFFICE_TOKEN_ERROR";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@yanolja-next/next-hub-bo-sdk",
+  "private": false,
+  "version": "0.0.1",
+  "description": "NCP Backoffice SDK - Build and deploy service backoffice UIs",
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanolja-org/next-hub.git",
+    "directory": "bo-sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "axios": "^1.7.2"
+  },
+  "devDependencies": {
+    "jsdom": "^26.0.0",
+    "typescript": "^5.4.4",
+    "unplugin-dts": "^1.0.3",
+    "vite": "^4.4.5",
+    "vite-plugin-externalize-deps": "^0.10.0",
+    "vitest": "^3.0.0"
+  }
+}