@kakao-bot/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongmin Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @kakao-bot/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Kakao Bot Hub용 서버 측 TypeScript SDK입니다. 허브 주소는 `https://kakao-api.jeongmin.dev`, 서비스 API 키는 콘솔(`https://tok.jeongmin.dev`) 개발자 메뉴에서 발급합니다.
+
+```sh
+npm install @kakao-bot/sdk
+# pnpm add @kakao-bot/sdk
+```
+
+```ts
+import { KakaoBot, KakaoApiError, KakaoTransportError } from '@kakao-bot/sdk';
+
+const kakao = new KakaoBot({
+  baseUrl: process.env.KAKAO_HUB_URL ?? 'https://kakao-api.jeongmin.dev',
+  apiKey: process.env.KAKAO_SERVICE_API_KEY!,
+});
+
+const rooms = await kakao.listRooms();
+const result = await kakao.sendMessage({
+  roomId: process.env.KAKAO_ROOM_ID!,
+  text: '배포가 완료되었습니다.',
+  requestId: 'deploy:release-2026-10-10',
+});
+```
+
+Node.js 20 이상, ESM을 지원합니다. 서비스 키는 브라우저 번들에 넣지 마세요. SDK용 서비스 키와 개인 MCP 토큰은 별도입니다.
+
+`listRooms()`에서 방의 `id`, `slug`, `canReply`를 확인합니다. `roomId` 대신 `roomSlug: 'deploy-alerts'`도 사용할 수 있습니다. slug는 워크스페이스 안에서 고유하며 변경 시 이전 주소는 사용할 수 없습니다. 고정 ID 연동은 slug 변경 후에도 유지됩니다. 두 방식 모두 해당 API 키의 서비스에 연결된 방만 허용합니다.
+
+`queued: true`는 접수이며 실제 전달 성공이 아닙니다. 서버는 서비스별 `requestId`로 중복을 방지합니다. 같은 논리적 발송에는 같은 ID를 사용하세요. **SDK는 POST 또는 GET을 자동 재시도하지 않습니다.** 타임아웃은 이미 접수된 요청일 수 있으므로 새 ID로 재시도하면 중복 발송됩니다. `KakaoTransportError.requestId`로 요청을 식별하고 대시보드 로그를 확인하세요.
+
+- `KakaoApiError`: HTTP 상태·오류 코드·요청 ID. `402 plan_message_limit`은 플랜 사용량 제한, `429 rate_limited`는 단기 발송 제한입니다.
+- `KakaoTransportError`: 전송/타임아웃 실패. 발송 결과는 알 수 없습니다.
+- `KakaoProtocolError`: 예상하지 못한 서버 응답.
+- 각 메서드의 두 번째 인자에 `{ signal }`을 넣어 취소할 수 있습니다.
+- `fetch`와 `timeoutMs`를 생성자에서 주입할 수 있습니다.
+
+## 릴리스
+
+```sh
+pnpm --filter @kakao-bot/sdk build
+pnpm --filter @kakao-bot/sdk pack --pack-destination /tmp/kakao-sdk-release
+```
+
+`packages/sdk/package.json`의 `version`을 올려 `main`에 머지하면 GitHub Actions(`publish-sdk.yml`)가 npm에 없는 버전인지 확인한 뒤 테스트하고 게시하며, `sdk-v<version>` 태그와 GitHub Release를 자동 생성합니다. 이미 게시된 버전이면 아무것도 하지 않습니다. 저장소 시크릿 `NPM_TOKEN`(Granular Access Token, `@kakao-bot` 스코프 쓰기)이 필요합니다.
+
+## 키 권한
+
+대시보드에서 키 이름과 허용 작업을 선택합니다. `listRooms()`는 `rooms:read`, `sendMessage()`는 `messages:send`가 필요하며 부족하면 `403 insufficient_scope`가 반환됩니다. 키 권한은 서비스에 연결된 방의 범위를 넓히지 않습니다. 기존 키는 두 권한을 유지합니다. 권한을 바꾸려면 새 키를 발급하고 연동을 교체한 뒤 이전 키를 폐기하세요.
+
+## 실제 발송 없는 테스트 키
+
+대시보드에서 키 환경을 **테스트**로 선택하세요. 같은 SDK·API 주소를 사용하며 서버가 키에 저장된 환경을 판별합니다. 클라이언트 요청으로 운영 키로 전환할 수 없습니다. 성공 응답은 HTTP 200, `test: true`, `queued: false`입니다. 입력값·권한·활성 방 연결을 검증하지만 폰 전달, 운영 발송 제한, 월 한도는 검증하지 않습니다. 테스트는 발송 큐·메시지 로그·과금 사용량을 생성하지 않으며 서비스당 분당 60회로 제한됩니다. 실제 방 목록과 연결 설정을 사용하는 검증 모드이며 별도 데이터 샌드박스는 아닙니다.
+
+테스트 요청 ID는 저장하지 않습니다. 같은 ID의 테스트를 반복해도 매번 검증하며, 이후 운영 키에서 같은 ID로 실제 발송할 수 있습니다. 운영 전환은 운영 키를 새로 발급해 서버 환경변수를 교체하세요. 기존 키는 운영 키로 유지됩니다.
+
+동일 서비스에서 이미 접수한 `requestId`의 방 ID 또는 본문을 바꾸면 `409 idempotency_conflict`를 반환합니다. 동일한 방·본문은 중복으로 처리하며 추가 큐/사용량을 만들지 않습니다. slug/방 표시명 변경은 고정 방 ID가 같으면 충돌로 보지 않습니다. 기존 기록 중 본문 검증값이 없는 건은 방 변경만 검출하고 재발송하지 않습니다. 검증값은 서버 비밀키로 보호하므로 비밀키 교체 후 이전 요청의 재시도는 충돌할 수 있습니다.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+export interface KakaoBotOptions {
+    /** Hub origin, e.g. https://hub.example.com. Never use the phone's private endpoint. */
+    baseUrl: string;
+    /** Service API key issued from the dashboard. Keep on your server. */
+    apiKey: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export type SendMessageInput = ({
+    room: string;
+    roomSlug?: never;
+    roomId?: never;
+} | {
+    roomSlug: string;
+    room?: never;
+    roomId?: never;
+} | {
+    roomId: string;
+    room?: never;
+    roomSlug?: never;
+}) & {
+    text: string;
+    /** Reuse this ID for the same logical send. No automatic retries are performed. */
+    requestId?: string;
+};
+export interface SendMessageResult {
+    ok: true;
+    queued: boolean;
+    duplicate?: boolean;
+    /** Validation only: no delivery, queue entry, or billable usage. */
+    test?: boolean;
+    request_id: string;
+    room?: string;
+}
+export interface Room {
+    id?: string;
+    slug?: string | null;
+    name: string;
+    status: "pending" | "active" | "suspended";
+    canReply: boolean;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export declare class KakaoApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly name = "KakaoApiError";
+    constructor(status: number, code: string, requestId?: string | undefined);
+}
+export declare class KakaoTransportError extends Error {
+    readonly requestId?: string | undefined;
+    readonly name = "KakaoTransportError";
+    /** A timed-out send may already have been queued. Never retry with a new request ID. */
+    constructor(requestId?: string | undefined);
+}
+export declare class KakaoProtocolError extends Error {
+    readonly requestId?: string | undefined;
+    readonly name = "KakaoProtocolError";
+    constructor(requestId?: string | undefined);
+}
+export declare class KakaoBot {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    constructor(options: KakaoBotOptions);
+    sendMessage(input: SendMessageInput, options?: RequestOptions): Promise<SendMessageResult>;
+    listRooms(options?: RequestOptions): Promise<Room[]>;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,128 @@
+export class KakaoApiError extends Error {
+    status;
+    code;
+    requestId;
+    name = "KakaoApiError";
+    constructor(status, code, requestId) {
+        super(`Kakao Bot API returned ${status} (${code})`);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+export class KakaoTransportError extends Error {
+    requestId;
+    name = "KakaoTransportError";
+    /** A timed-out send may already have been queued. Never retry with a new request ID. */
+    constructor(requestId) {
+        super("Kakao Bot request did not complete. Delivery state is unknown; inspect the dashboard before retrying.");
+        this.requestId = requestId;
+    }
+}
+export class KakaoProtocolError extends Error {
+    requestId;
+    name = "KakaoProtocolError";
+    constructor(requestId) {
+        super("Kakao Bot returned an unexpected response.");
+        this.requestId = requestId;
+    }
+}
+function object(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export class KakaoBot {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    fetchFn;
+    constructor(options) {
+        const url = new URL(options.baseUrl);
+        if (!["http:", "https:"].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new TypeError("baseUrl must be an HTTP(S) URL without credentials, query or fragment.");
+        if (!options.apiKey.trim() || /[\r\n]/.test(options.apiKey))
+            throw new TypeError("A non-empty service API key is required.");
+        this.baseUrl = url.toString().replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.timeoutMs = options.timeoutMs ?? 10000;
+        if (!Number.isInteger(this.timeoutMs) || this.timeoutMs < 1 || this.timeoutMs > 120000)
+            throw new TypeError("timeoutMs must be between 1 and 120000.");
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+        if (!this.fetchFn)
+            throw new TypeError("A fetch implementation is required.");
+    }
+    async sendMessage(input, options = {}) {
+        if ((input.roomId !== undefined
+            ? !input.roomId.trim()
+            : input.roomSlug !== undefined
+                ? !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(input.roomSlug)
+                : !input.room?.trim()) ||
+            !input.text.trim() ||
+            input.text.length > 4000)
+            throw new TypeError("room and text are required; text must be at most 4000 characters.");
+        const requestId = input.requestId ?? globalThis.crypto.randomUUID();
+        if (!requestId.trim() || requestId.length > 128)
+            throw new TypeError("requestId must contain 1 to 128 characters.");
+        const data = await this.request(input.roomId !== undefined
+            ? `/v1/rooms/id/${encodeURIComponent(input.roomId)}/messages`
+            : input.roomSlug !== undefined
+                ? `/v1/rooms/${encodeURIComponent(input.roomSlug)}/messages`
+                : "/v1/messages", "POST", { room: input.room, msg: input.text, request_id: requestId }, options.signal, requestId);
+        if (!object(data) ||
+            data.ok !== true ||
+            typeof data.queued !== "boolean" ||
+            data.request_id !== requestId ||
+            (data.test !== undefined && (typeof data.test !== "boolean" || (data.test && data.queued))) ||
+            (data.duplicate !== undefined && typeof data.duplicate !== "boolean") ||
+            (data.room !== undefined && typeof data.room !== "string"))
+            throw new KakaoProtocolError(requestId);
+        return data;
+    }
+    async listRooms(options = {}) {
+        const data = await this.request("/v1/rooms", "GET", undefined, options.signal);
+        if (!object(data) ||
+            !Array.isArray(data.rooms) ||
+            !data.rooms.every((room) => object(room) &&
+                (room.id === undefined || typeof room.id === "string") &&
+                (room.slug === undefined || room.slug === null || typeof room.slug === "string") &&
+                typeof room.name === "string" &&
+                ["pending", "active", "suspended"].includes(String(room.status)) &&
+                typeof room.canReply === "boolean"))
+            throw new KakaoProtocolError();
+        return data.rooms;
+    }
+    async request(path, method, body, signal, requestId) {
+        const timeout = AbortSignal.timeout(this.timeoutMs);
+        const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+        let response;
+        let data;
+        try {
+            response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: combined,
+                // Service keys must never be forwarded to a redirected origin.
+                redirect: "error",
+            });
+            data = await response.json().catch(() => null);
+        }
+        catch {
+            throw new KakaoTransportError(requestId);
+        }
+        if (!response.ok) {
+            const code = object(data) && typeof data.error === "string" && /^[a-z0-9_]{1,80}$/.test(data.error)
+                ? data.error
+                : "request_failed";
+            throw new KakaoApiError(response.status, code, requestId);
+        }
+        return data;
+    }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@kakao-bot/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Typed server-side client for the Kakao Bot Hub API",
+  "license": "MIT",
+  "author": "Jeongmin Lee",
+  "homepage": "https://github.com/froggy1014/kakao-bot/tree/main/packages/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/froggy1014/kakao-bot.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/froggy1014/kakao-bot/issues",
+  "keywords": [
+    "kakao",
+    "kakaotalk",
+    "bot",
+    "messaging",
+    "sdk",
+    "typescript"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }