tbmini-sdk

v3.1.1

Published

3 months ago

태깅 기능을 지원하는 JavaScript SDK

0High
0Medium
0Low

textway

tagging tag sdk javascript

tbmini-sdk

tB-mini SDK는 태깅, 콘텐츠 관리, 챗봇, RAG 검색 등의 기능을 제공하는 tB-mini의 기능을 쉽게 사용할 수 있도록 pre-build UI와 함께 tB-mini 서비스 인증과 API method를 제공하는 JavaScript SDK입니다.

설치

npm을 통한 설치

npm install tbmini-sdk

사용 방법

JavaScript/TypeScript

import { TaggingSDK } from 'tbmini-sdk';

const sdk = new TaggingSDK();
sdk.init({
  applicationKey: 'your-application-key',
  userKey: 'user-unique-id',
  locale: 'ko' // 또는 'en'
});

sdk.createTaggingBox({
  containerId: 'tagging-container',
  width: '25rem',
  height: '600px',
  animation: 'fadeIn',
  animationDuration: '0.5s'
});

React

import React, { useEffect } from 'react';
import { TaggingSDK } from 'tbmini-sdk';

function App() {
  useEffect(() => {
    const sdk = new TaggingSDK();
    sdk.init({
      applicationKey: 'your-application-key',
      userKey: 'user-unique-id',
      locale: 'ko' // 또는 'en'
    });

    sdk.createTaggingBox({
      containerId: 'tagging-container',
      width: '25rem',
      height: '600px',
      animation: 'fadeIn',
      animationDuration: '0.5s'
    });
  }, []);

  return (
    <div className="container">
      <h1>tbmini-sdk React Example</h1>
      <div id="tagging-container"></div>
    </div>
  );
}

export default App;

Vue

<template>
  <div class="container">
    <div id="tagging-container"></div>
  </div>
</template>

<script>
import { TaggingSDK } from 'tbmini-sdk';

export default {
  name: 'App',
  mounted() {
    const sdk = new TaggingSDK();
    sdk.init({
      applicationKey: 'your-application-key',
      userKey: 'user-unique-id',
      locale: 'ko' // 또는 'en'
    });

    sdk.createTaggingBox({
      containerId: 'tagging-container',
      width: '25rem',
      height: '600px',
      animation: 'fadeIn'
    });
  }
}
</script>

CDN을 통한 사용

HTML 파일에 스크립트 태그를 추가하고 SDK를 사용합니다:

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>tbmini-sdk Example</title>
    <script src="https://unpkg.com/tbmini-sdk@latest/dist/tbmini-sdk.min.js"></script>
</head>
<body>
    <div id="tagging-container"></div>

    <script>
        window.TaggingSDK.init({
            applicationKey: 'your-application-key',
            userKey: 'user-unique-id',
            locale: 'ko'
        });

        window.TaggingSDK.createTaggingBox({
            containerId: 'tagging-container',
            width: '25rem',
            height: '600px',
            animation: 'fadeIn',
            animationDuration: '0.5s'
        });
    </script>
</body>
</html>

인증 플로우

tbmini SDK는 두 가지 인증 방식을 지원합니다: Secured On과 Secured Off.

Secured On (보안 인증 활성화)

콘솔에서 "Secured on"으로 설정한 경우, 고객사 백엔드에서 Application Secret을 사용하여 안전하게 인증을 처리해야 합니다.

방법 1: doAuth 메서드 사용 (권장)

고객사 백엔드에서 /api/v1/sdk_api/v1.1/client_auth/client_access_key API를 호출하여 access_key를 발급받고, 이를 doAuth 메서드로 전달합니다.

const sdk = new TaggingSDK();
sdk.init({
  applicationKey: 'your-application-key',
  userKey: 'user-unique-id',
  doAuth: async (userKey) => {
    // 고객사 백엔드에서 Application Secret을 사용하여 access_key 발급
    const response = await fetch('https://your-backend.com/api/get-access-key', {
      method: 'POST',
      body: JSON.stringify({ user_key: userKey })
    });
    const data = await response.json();
    return data.access_key; // access_key 반환
  }
});

고객사 백엔드에서는 다음과 같이 구현합니다:

// 고객사 백엔드 예시
app.post('/api/get-access-key', async (req, res) => {
  const { user_key } = req.body;
  
  // Application Secret을 사용하여 tbmini API 호출
  const response = await fetch(
    `https://developers.tbmini.im/api/v1/sdk_api/v1.1/client_auth/client_access_key?user_key=${user_key}`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.APPLICATION_API_KEY,
        'X-API-Secret': process.env.APPLICATION_API_SECRET
      }
    }
  );
  
  const data = await response.json();
  res.json({ access_key: data.access_key });
});

방법 2: authURL 사용

고객사 백엔드에서 access_key를 발급하는 엔드포인트를 제공하고, SDK에서 해당 URL을 사용합니다:

const sdk = new TaggingSDK();
sdk.init({
  applicationKey: 'your-application-key',
  userKey: 'user-unique-id',
  authURL: 'https://your-backend.com/api/get-access-key' // 고객사 백엔드 엔드포인트
});

고객사 백엔드는 user_key를 query parameter로 받아 access_key를 반환해야 합니다:

// 고객사 백엔드 예시
app.post('/api/get-access-key', async (req, res) => {
  const { user_key } = req.query;
  
  // Application Secret을 사용하여 tbmini API 호출
  const response = await fetch(
    `https://developers.tbmini.im/api/v1/sdk_api/v1.1/client_auth/client_access_key?user_key=${user_key}`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.APPLICATION_API_KEY,
        'X-API-Secret': process.env.APPLICATION_API_SECRET
      }
    }
  );
  
  const data = await response.json();
  res.json({ access_key: data.access_key });
});

발급받은 access_key로 SDK는 자동으로 /api/v1/sdk_api/v1.1/client_auth?access_key={access_key} GET API를 호출하여 최종 토큰을 획득합니다.

Secured Off (보안 인증 비활성화)

콘솔에서 "Secured off"로 설정한 경우, SDK가 직접 /api/v1/sdk_api/v1.1/client_auth POST API를 호출하여 토큰을 획득합니다. 이 경우 x-api-key 헤더에 Application Key를, user_key에 사용자 식별자를 넣어 간단하게 토큰을 획득할 수 있습니다.

const sdk = new TaggingSDK();
sdk.init({
  applicationKey: 'your-application-key',
  userKey: 'user-unique-id'
  // doAuth나 authURL 설정 불필요
});

주의: Secured Off 방식은 사용자 계정 유출의 위험이 있으므로, 프로덕션 환경에서는 Secured On 방식을 사용하는 것을 강력히 권장합니다.

SDK 초기화 옵션

init 메서드의 옵션 파라미터:

| 옵션 | 타입 | 필수 | 기본값 | 설명 | |------|------|------|-------|------| | applicationKey | string | 예 | - | 콘솔에서 발급받은 Application Key (공개 키, Secret 아님) | | userKey | string | 예 | - | 사용자를 식별하는 고유 키 | | locale | string | 아니오 | 'ko' | 언어 설정 ('ko' 또는 'en') | | authURL | string | 아니오 | apiBaseUrl + '/client_auth' | 엔드 유저 보안 인증용 백엔드 URL (고객사 서버). Secured On일 때 사용 | | doAuth | function | 아니오 | - | 사용자 인증 커스텀 메서드. async (user_key: string) => Promise<string> 형식으로 access_key를 반환해야 합니다. 이 옵션을 설정하면 authURL이 무시됩니다. |

TaggingBox 생성 옵션

createTaggingBox 메서드의 옵션 파라미터:

| 옵션 | 타입 | 필수 | 기본값 | 설명 | |------|------|------|-------|------| | containerId | string | 예 | - | SDK가 렌더링될 컨테이너 요소의 ID | | width | string | 아니오 | - | 전체 TaggingBox 렌더링 width (예: '25rem', '500px') | | height | string | 아니오 | - | 전체 TaggingBox 렌더링 height (예: '600px') | | animation | string | 아니오 | - | 렌더링 될 때 animation 타입 (예: 'fadeIn') | | animationDuration | string | 아니오 | - | 렌더링 될 때 animation duration (예: '0.5s') | | showIconFirst | boolean | 아니오 | - | 플로팅 아이콘(접힘) vs TaggingBox 무엇부터 보여줄 지 설정 | | logoSvg | string | 아니오 | - | TaggingBox 내 보여줄 로고 이미지 (SVG 형식) | | logoWidth | string | 아니오 | - | TaggingBox 내 보여줄 로고 width | | logoHeight | string | 아니오 | - | TaggingBox 내 보여줄 로고 height | | iconSvg | string | 아니오 | - | 플로팅 아이콘 이미지 (SVG 형식) | | iconSize | string | 아니오 | - | 플로팅 아이콘 사이즈 | | iconPosition | string | 아니오 | - | 플로팅 아이콘 위치 ('top', 'left', 'bottom', 'right') |

API 함수 사용

SDK 초기화 후 getAPIs() 메서드를 통해 API 함수에 접근할 수 있습니다:

const sdk = new TaggingSDK();
sdk.init({
  applicationKey: 'your-application-key',
  userKey: 'user-unique-id'
});

const apis = sdk.getAPIs();

// API 함수 사용 예시
const boxes = await apis.getClientBoxes();

API 함수 목록

Client Context API

`postClientContext()`

사용자 컨텍스트 정보를 생성하고 박스 정보를 가져옵니다.

| 항목 | 설명 | |------|------| | Input Parameters | 없음 | | Output | { boxes: Array<{box_id: number, name: string}>, ... } - 사용자 박스 정보 및 컨텍스트 데이터 | | API 동작 | POST /client/context - 사용자 컨텍스트 생성 및 박스 정보 조회 |

Client Boxes API

`getClientBoxes()`

클라이언트의 박스 목록을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | 없음 | | Output | { boxes: Array<{box_id: number, name: string}>, plan_limits: {max_boxes_per_client: number, current_boxes_for_client: number} } | | API 동작 | GET /client/boxes - 클라이언트가 소유한 박스 목록 조회 |

`patchClientBoxes({box_id, name})`

박스 이름을 업데이트합니다.

| 항목 | 설명 | |------|------| | Input Parameters | box_id (number): 업데이트할 박스 IDname (string): 새로운 박스 이름 | | Output | { box_id: number, name: string, owner_public_client_id: string } | | API 동작 | PATCH /client/boxes/{box_id} - 박스 이름 수정 |

`putClientBoxesOrder(orderedList)`

박스 순서를 변경합니다.

| 항목 | 설명 | |------|------| | Input Parameters | orderedList (Array): 변경된 순서의 박스 ID 리스트 | | Output | 없음 (성공 시 알림 표시) | | API 동작 | PUT /client/boxes/order - 박스 순서 업데이트 |

Recommendations API

`postRecommendations({title, url, content, input_type, box_id, run_recommendation})`

콘텐츠를 저장하고 태그 추천을 요청합니다.

| 항목 | 설명 | |------|------| | Input Parameters | title (string): 콘텐츠 제목url (string): 원본 URLcontent (string): 콘텐츠 내용input_type (string): 입력 타입 ('DIRECT', 'PASTE', 'FILE_UPLOAD', 'API', 'UNKNOWN'), 기본값 'DIRECT'box_id (string): 저장할 박스 IDrun_recommendation (boolean): 태그 추천 여부 | | Output | { request_id: string, recommended_tags: Array<{name: string, source: string}>, ... } | | API 동작 | POST /recommendations - 콘텐츠 저장 및 태그 추천 |

Tags API

`postTags({request_id, box_id, tags})`

추천받은 태그를 저장합니다.

| 항목 | 설명 | |------|------| | Input Parameters | request_id (string): postRecommendations에서 받은 request_idbox_id (string): 저장할 박스 IDtags (Array<{name: string, source: string}>): 저장할 태그 목록 | | Output | { request_id: string, ... } | | API 동작 | POST /tags - 태그 저장 |

Chatbot API

`getChatbotMasterBoxes()`

챗봇용 마스터 박스 목록을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | 없음 | | Output | { total_count: number, items: Array<{...}>, skip: number, limit: number } | | API 동작 | GET /chatbot/master-boxes?skip=0&limit=20 - 챗봇용 마스터 박스 목록 조회 |

`postChatbotSearch({query, master_box_id, room_id})`

챗봇 검색을 수행합니다.

| 항목 | 설명 | |------|------| | Input Parameters | query (string): 사용자의 검색 질문master_box_id (number|null): 검색할 Master의 특정 Box ID (선택 사항)room_id (number|null): 기존 대화방 ID (없으면 새 방 생성) | | Output | { room_id: number, query: {id: number, user_query: string, context: Array<string>, ai_answer: string, master_box_id_used: number, sequence_number: number, created_at: string}, deducted_credits: number, message: string, context: Array<string> } | | API 동작 | POST /chatbot/search - 챗봇 검색 수행 및 대화 기록 저장 |

`getChatbotBoxContents({master_box_id})`

특정 마스터 박스의 콘텐츠 목록을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | master_box_id (number): 조회할 마스터 박스 ID | | Output | { total_count: number, items: Array<{title: string, text_content: string, master_box_id: number, is_chatbot_enabled: boolean, master_content_id: number, master_id: number, tags: Array, created_at: string, updated_at: string, request_id: string}>, skip: number, limit: number } | | API 동작 | GET /chatbot/boxes/{master_box_id}/contents?skip=0&limit=100 - 마스터 박스 콘텐츠 조회 |

`getChatbotRooms()`

챗봇 대화방 목록을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | 없음 | | Output | Array<{room_id: number, title: string, initial_master_box_id: string, created_at: string, updated_at: string, query_count: number}> | | API 동작 | GET /chatbot/rooms - 챗봇 대화방 목록 조회 |

`getChatbotRoomsDetail(room_id)`

특정 챗봇 대화방의 상세 정보(채팅 히스토리)를 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | room_id (number): 조회할 대화방 ID | | Output | { room_id: number, title: string, requesting_client_public_id: string, content_owner_master_id: number, initial_master_box_id: string, created_at: string, updated_at: string, total_queries: number, queries: Array<{id: number, user_query: string, context: Array<string>, ai_answer: string, master_box_id_used: number, sequence_number: number, created_at: string}> } | | API 동작 | GET /chatbot/rooms/{room_id} - 챗봇 대화방 상세 정보 조회 |

RAG Search API

`postRagSearch({query, box_id, room_id})`

지정된 Client Box 내의 콘텐츠를 대상으로 RAG 검색을 수행하고, 결과를 Room에 기록합니다.

| 항목 | 설명 | |------|------| | Input Parameters | query (string): RAG 검색 질문box_id (string): 검색 컨텍스트로 사용할 Client Box의 ID (선택 사항)room_id (number): 기존 검색 기록방 ID (없으면 새로 생성) | | Output | { room_id: number, query: string, answer: string, box_id_used: string, sequence_number: number, created_at: string, deducted_credits: number, context: Array<string> } | | API 동작 | POST /rag/search - 지정된 박스 내 콘텐츠 RAG 검색 |

`postRagSearchAllBoxes({query, room_id})`

Client의 모든 접근 가능한 Box 내 콘텐츠를 대상으로 RAG 검색을 수행하고, 결과를 Room에 기록합니다.

| 항목 | 설명 | |------|------| | Input Parameters | query (string): RAG 검색 질문room_id (number): 기존 검색 기록방 ID (없으면 새로 생성) | | Output | { room_id: number, query: string, answer: string, box_id_used: string, sequence_number: number, created_at: string, deducted_credits: number, context: Array<string> } | | API 동작 | POST /rag/search-all-boxes - 모든 박스 내 콘텐츠 RAG 검색 |

`getRagRooms({limit, skip})`

Client의 모든 RAG 검색 기록방 목록을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | limit (number): 조회 개수 (max 50, min 1), 기본값 20skip (number): n개 이후 검색 (pagination), 기본값 0 | | Output | Array<{room_id: number, title: string, initial_box_id: string, created_at: string, updated_at: string, query_count: number}> | | API 동작 | GET /rag/rooms?limit={limit}&skip={skip} - RAG 검색 기록방 목록 조회 |

`getRagRoomsDetail({room_id, skip, limit})`

특정 RAG 검색 기록방의 모든 질의응답을 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | room_id (number): 조회할 검색 기록방의 IDskip (number): 건너뛸 메시지 수, 기본값 0limit (number): 가져올 메시지 수, 기본값 100 | | Output | { room_id: number, title: string, initial_box_id: string, created_at: string, updated_at: string, total_queries: number, queries: Array<{sequence_number: number, user_query: string, context: Array<string>, ai_answer: string, box_id_used: number, created_at: string}> } | | API 동작 | GET /rag/rooms/{room_id}?skip={skip}&limit={limit} - RAG 검색 기록방 상세 정보 조회 |

Contents API

`getClientContents({box_id, limit, offset})`

콘텐츠 목록을 조회합니다 (Box 필터링 가능).

| 항목 | 설명 | |------|------| | Input Parameters | box_id (string|null): 필터링할 Box ID (선택 사항)limit (number): 페이지당 항목 수 (min 1, max 100), 기본값 20offset (number): 건너뛸 항목 수, 기본값 0 | | Output | { total_count: number, limit: number, offset: number, items: Array<{request_id: string, box_id: string, owner_public_client_id: string, title: string, content: string, url: string, created_dt: string, updated_dt: string, associated_tags: Array<{tag_id: number, tag_nm: string, scope: string}>}> } | | API 동작 | GET /client/contents?box_id={box_id}&limit={limit}&offset={offset} - 콘텐츠 목록 조회 |

`getContents(request_id)`

콘텐츠 상세 정보를 조회합니다.

| 항목 | 설명 | |------|------| | Input Parameters | request_id (string): 조회할 콘텐츠의 request_id (짧은 Hex) | | Output | { request_id: string, box_id: string, owner_public_client_id: string, title: string, content: string, url: string, created_dt: string, updated_dt: string, associated_tags: Array<{tag_id: number, tag_nm: string, scope: string}> } | | API 동작 | GET /contents/{request_id} - 콘텐츠 상세 정보 조회 |

`deleteContents(request_id)`

주어진 request_id에 해당하는 콘텐츠를 삭제합니다.

| 항목 | 설명 | |------|------| | Input Parameters | request_id (string): 삭제할 콘텐츠의 request_id (짧은 Hex) | | Output | 없음 (성공 시 204 응답) | | API 동작 | DELETE /contents/{request_id} - 콘텐츠 삭제 |

`patchContents({request_id, title, content, url})`

특정 콘텐츠의 제목, 내용, URL 등을 수정합니다.

| 항목 | 설명 | |------|------| | Input Parameters | request_id (string): 수정할 콘텐츠의 request_idtitle (string|null): 변경할 콘텐츠 제목 (선택 사항)content (string|null): 변경할 콘텐츠 내용 (선택 사항)url (string|null): 변경할 원본 URL (선택 사항) | | Output | { request_id: string, box_id: string, owner_public_client_id: string, title: string, content: string, url: string, created_dt: string, updated_dt: string, associated_tags: Array<{tag_id: number, tag_nm: string, scope: string}> } | | API 동작 | PATCH /contents/{request_id} - 콘텐츠 정보 수정 |

`patchContentsTags({request_id, tags_to_add, tags_to_remove})`

특정 콘텐츠에 연결된 태그를 부분적으로 수정합니다.

| 항목 | 설명 | |------|------| | Input Parameters | request_id (string): 태그를 수정할 콘텐츠의 request_idtags_to_add (Array<{name: string, source: string}>): 추가할 태그 목록tags_to_remove (Array): 제거할 태그 이름 목록 | | Output | { request_id: string, box_id: string, owner_public_client_id: string, title: string, content: string, url: string, created_dt: string, updated_dt: string, associated_tags: Array<{tag_id: number, tag_nm: string, scope: string}> } | | API 동작 | PATCH /contents/{request_id}/tags - 콘텐츠 태그 수정 (추가/제거) |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tbmini-sdk

설치

npm을 통한 설치

사용 방법

JavaScript/TypeScript

React

Vue

CDN을 통한 사용

인증 플로우

Secured On (보안 인증 활성화)

방법 1: doAuth 메서드 사용 (권장)

방법 2: authURL 사용

Secured Off (보안 인증 비활성화)

SDK 초기화 옵션

TaggingBox 생성 옵션

API 함수 사용

API 함수 목록

Client Context API

postClientContext()

Client Boxes API

getClientBoxes()

patchClientBoxes({box_id, name})

putClientBoxesOrder(orderedList)

Recommendations API

postRecommendations({title, url, content, input_type, box_id, run_recommendation})

Tags API

postTags({request_id, box_id, tags})

Chatbot API

getChatbotMasterBoxes()

postChatbotSearch({query, master_box_id, room_id})

getChatbotBoxContents({master_box_id})

getChatbotRooms()

getChatbotRoomsDetail(room_id)

RAG Search API

postRagSearch({query, box_id, room_id})

postRagSearchAllBoxes({query, room_id})

getRagRooms({limit, skip})

getRagRoomsDetail({room_id, skip, limit})

Contents API

getClientContents({box_id, limit, offset})

getContents(request_id)

deleteContents(request_id)

patchContents({request_id, title, content, url})

patchContentsTags({request_id, tags_to_add, tags_to_remove})

`postClientContext()`

`getClientBoxes()`

`patchClientBoxes({box_id, name})`

`putClientBoxesOrder(orderedList)`

`postRecommendations({title, url, content, input_type, box_id, run_recommendation})`

`postTags({request_id, box_id, tags})`

`getChatbotMasterBoxes()`

`postChatbotSearch({query, master_box_id, room_id})`

`getChatbotBoxContents({master_box_id})`

`getChatbotRooms()`

`getChatbotRoomsDetail(room_id)`

`postRagSearch({query, box_id, room_id})`

`postRagSearchAllBoxes({query, room_id})`

`getRagRooms({limit, skip})`

`getRagRoomsDetail({room_id, skip, limit})`

`getClientContents({box_id, limit, offset})`

`getContents(request_id)`

`deleteContents(request_id)`

`patchContents({request_id, title, content, url})`

`patchContentsTags({request_id, tags_to_add, tags_to_remove})`