@kakao-bot/sdk 0.0.0-stage → 0.2.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,84 @@
-# 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`로 요청을 식별하고 대시보드 로그를 확인하세요.
+
+## 오류 처리
+
+모든 오류는 `KakaoError`를 상속합니다. 한 번의 `catch`로 전부 받고, `name`이나 `instanceof`로 갈라 봅니다.
+
+```ts
+import { isKakaoError, KakaoApiError, KakaoTimeoutError } from '@kakao-bot/sdk';
+
+try {
+  await kakao.sendMessage({ roomSlug: 'deploy-alerts', text: '배포 완료', requestId: 'deploy:42' });
+} catch (error) {
+  if (!isKakaoError(error)) throw error;          // 내 코드의 버그는 그대로 올려보냅니다
+  logger.error(error.toJSON());                    // 로그 한 줄로 바로 적을 수 있는 평평한 객체
+  if (error.retryable) await scheduleRetry('deploy:42', error);  // 같은 requestId 로만
+}
+```
+
+| 클래스 | 뜻 | `retryable` |
+|---|---|---|
+| `KakaoApiError` | 허브가 응답했지만 2xx가 아님 | 429·5xx는 `true`, 그 외 4xx는 `false` |
+| `KakaoTransportError` | 허브에 닿지 못함 | `true` |
+| `KakaoTimeoutError` | 제한 시간 초과 (`KakaoTransportError`의 하위) | `true` |
+| `KakaoProtocolError` | 2xx인데 본문이 계약과 다름 | `false` |
+
+- **`retryable`은 "다시 보내도 안전한가"이지 "자동으로 재시도하라"가 아닙니다.** SDK는 어떤 경우에도 스스로 재시도하지 않습니다. 재시도할 때는 **반드시 같은 `requestId`** 를 쓰세요 — 새 ID로 바꾸면 중복 발송됩니다. `409 idempotency_conflict`만은 `retryable: false`인데, 이미 접수된 건이라 다시 보내면 방에 두 번 올라가기 때문입니다.
+- `KakaoApiError`는 `status`·`code`·`body`·`retryAfterMs`를 싣습니다. `body`에 허브의 원본 응답이 그대로 들어 있어 `402`의 `upgrade` 링크나 `429`의 `scope`(room/global/test)를 읽을 수 있습니다.
+- `code`는 알려진 코드가 자동완성되지만 임의 문자열도 허용합니다 — 허브가 코드를 추가해도 타입이 깨지지 않습니다. 목록은 `KAKAO_ERROR_CODES`.
+- `retryAfterMs`는 본문 `retry_after_ms`를 우선 쓰고, 없으면 `Retry-After` 헤더(초 또는 HTTP-date)를 읽습니다.
+- 전송 실패는 원인을 표준 `Error.cause`로 물고 옵니다.
+- **호출자가 `signal`로 취소하면 `signal.reason`이 그대로 올라옵니다** — `fetch`와 같은 동작이라 기존 `AbortError` 처리가 그대로 먹습니다. SDK 오류로 감싸지 않습니다.
+- `isKakaoError()`는 SDK가 중복 설치돼 `instanceof`가 조용히 실패하는 환경에서도 동작합니다.
+- 각 메서드의 두 번째 인자에 `{ signal }`을 넣어 취소할 수 있습니다.
+- `fetch`와 `timeoutMs`(기본 10초)를 생성자에서 주입할 수 있습니다.
+
+## 릴리스
+
+```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/errors.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 허브 호출이 실패했을 때 던지는 것들.
+ *
+ * 설계는 널리 쓰이는 SDK 들의 합의를 그대로 따른다 — 공통 베이스 클래스 하나(Stripe 의
+ * `StripeError`, AWS SDK v3 의 `ServiceException`, Octokit 의 `RequestError` 와 같은 자리),
+ * 원본 응답 보존(Stripe `.raw`), 재시도 가능 여부 표시(AWS `$retryable`),
+ * 그리고 ES2022 표준 `Error.cause` 로 원인 체인.
+ *
+ * 핵심은 **소비자가 같은 표를 각자 베껴 쓰지 않게 하는 것**이다. "409 는 다시 보내면 안 되고
+ * 429 는 보내도 된다" 는 허브 쪽 지식이라, 서비스마다 손으로 옮겨 적으면 언젠가 한 곳이 틀리고
+ * 그 대가는 단톡방에 두 번 올라간 공지다.
+ */
+/**
+ * 중복 설치된 SDK 사이에서도 에러를 식별하기 위한 브랜드.
+ *
+ * `instanceof` 는 같은 클래스의 사본이 둘 이상 로드되면(pnpm 중첩 설치, 번들러가 ESM/CJS 를
+ * 각각 끌어오는 경우) 조용히 false 가 된다. `Symbol.for` 는 realm 전역 레지스트리라 사본이
+ * 몇 개든 같은 심볼을 가리킨다. 내부용이지만 d.ts 에 이름이 필요해 export 한다.
+ */
+export declare const KAKAO_ERROR_BRAND: unique symbol;
+/** 허브가 돌려주는 오류 코드. 서버 라우트(`src/outbound/routes.ts`)가 정본이다. */
+export declare const KAKAO_ERROR_CODES: readonly ["validation_error", "invalid_room_slug", "unauthorized", "plan_message_limit", "insufficient_scope", "room_not_bound", "room_inactive", "idempotency_conflict", "rate_limited", "kill_switch", "queue_full", "request_failed"];
+export type KakaoErrorCode = (typeof KAKAO_ERROR_CODES)[number];
+/**
+ * 알려진 코드는 자동완성으로 뜨되, 허브가 새 코드를 추가해도 타입이 깨지지 않는다.
+ * `(string & {})` 는 유니온이 `string` 으로 뭉개지는 것을 막는 관용구다.
+ */
+export type KakaoErrorCodeLike = KakaoErrorCode | (string & {});
+/** 로그에 그대로 적기 좋은 평평한 모양. `toJSON()` 의 결과. */
+export interface KakaoErrorJSON {
+    name: string;
+    message: string;
+    retryable: boolean;
+    requestId?: string;
+    status?: number;
+    code?: string;
+    retryAfterMs?: number;
+    timeoutMs?: number;
+}
+/** 모든 허브 오류의 베이스. `catch` 에서 `isKakaoError(e)` 한 번으로 전부 잡는다. */
+export declare abstract class KakaoError extends Error {
+    readonly [KAKAO_ERROR_BRAND]: true;
+    /** 서브클래스를 구분하는 판별자. `instanceof` 가 막히는 환경에서도 읽을 수 있다. */
+    abstract readonly name: string;
+    /**
+     * 같은 요청을 다시 보내도 **안전한가**. 자동 재시도 지시가 아니다 —
+     * SDK 는 어떤 경우에도 스스로 재시도하지 않는다.
+     */
+    abstract readonly retryable: boolean;
+    readonly requestId?: string;
+    constructor(message: string, requestId?: string, options?: {
+        cause?: unknown;
+    });
+    toJSON(): KakaoErrorJSON;
+}
+/**
+ * 허브가 응답은 했지만 2xx 가 아니었다.
+ *
+ * 본문을 통째로 `body` 에 보관한다 — 402 는 `upgrade` 링크를, 429 는 `scope`(test/global/room)를
+ * 함께 싣는데, `error` 필드만 빼고 버리면 그 안내가 사라진다.
+ */
+export declare class KakaoApiError extends KakaoError {
+    readonly name = "KakaoApiError";
+    readonly status: number;
+    readonly code: KakaoErrorCodeLike;
+    readonly retryable: boolean;
+    /** 파싱된 응답 본문. JSON 이 아니었으면 `null`. */
+    readonly body: unknown;
+    /** `Retry-After` 또는 본문 `retry_after_ms` 에서 읽은 대기 시간. 없으면 `undefined`. */
+    readonly retryAfterMs?: number;
+    constructor(status: number, code: KakaoErrorCodeLike, requestId?: string, options?: {
+        body?: unknown;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+    toJSON(): KakaoErrorJSON;
+}
+/**
+ * 응답을 받지 못했다. 허브에 닿기 전에 끊겼다는 뜻이고, 발송 여부는 알 수 없다.
+ *
+ * 같은 `requestId` 로 다시 보내면 허브가 중복을 막아 주므로 재시도가 안전하다 —
+ * **새 id 로 바꿔 보내면 중복 발송된다.**
+ */
+export declare class KakaoTransportError extends KakaoError {
+    readonly name: "KakaoTransportError" | "KakaoTimeoutError";
+    readonly retryable = true;
+    constructor(requestId?: string, options?: {
+        cause?: unknown;
+        message?: string;
+    });
+}
+/**
+ * 제한 시간 안에 응답이 오지 않았다. `KakaoTransportError` 의 하위라
+ * 기존 `catch (e) { if (e instanceof KakaoTransportError) … }` 가 그대로 잡는다.
+ */
+export declare class KakaoTimeoutError extends KakaoTransportError {
+    readonly name = "KakaoTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, requestId?: string, options?: {
+        cause?: unknown;
+    });
+    toJSON(): KakaoErrorJSON;
+}
+/**
+ * 2xx 를 받았지만 본문이 계약과 달랐다. 허브는 받았을 가능성이 크므로 재시도하지 않는다 —
+ * 사람이 대시보드 로그를 보고 판단해야 한다.
+ */
+export declare class KakaoProtocolError extends KakaoError {
+    readonly name = "KakaoProtocolError";
+    readonly retryable = false;
+    constructor(requestId?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 허브 오류인지 판별한다. 중복 설치로 `instanceof` 가 막힌 환경에서도 동작한다.
+ */
+export declare function isKakaoError(value: unknown): value is KakaoError;

package/dist/errors.js

@@ -0,0 +1,147 @@
+/**
+ * 허브 호출이 실패했을 때 던지는 것들.
+ *
+ * 설계는 널리 쓰이는 SDK 들의 합의를 그대로 따른다 — 공통 베이스 클래스 하나(Stripe 의
+ * `StripeError`, AWS SDK v3 의 `ServiceException`, Octokit 의 `RequestError` 와 같은 자리),
+ * 원본 응답 보존(Stripe `.raw`), 재시도 가능 여부 표시(AWS `$retryable`),
+ * 그리고 ES2022 표준 `Error.cause` 로 원인 체인.
+ *
+ * 핵심은 **소비자가 같은 표를 각자 베껴 쓰지 않게 하는 것**이다. "409 는 다시 보내면 안 되고
+ * 429 는 보내도 된다" 는 허브 쪽 지식이라, 서비스마다 손으로 옮겨 적으면 언젠가 한 곳이 틀리고
+ * 그 대가는 단톡방에 두 번 올라간 공지다.
+ */
+/**
+ * 중복 설치된 SDK 사이에서도 에러를 식별하기 위한 브랜드.
+ *
+ * `instanceof` 는 같은 클래스의 사본이 둘 이상 로드되면(pnpm 중첩 설치, 번들러가 ESM/CJS 를
+ * 각각 끌어오는 경우) 조용히 false 가 된다. `Symbol.for` 는 realm 전역 레지스트리라 사본이
+ * 몇 개든 같은 심볼을 가리킨다. 내부용이지만 d.ts 에 이름이 필요해 export 한다.
+ */
+export const KAKAO_ERROR_BRAND = Symbol.for("@kakao-bot/sdk.error");
+/** 허브가 돌려주는 오류 코드. 서버 라우트(`src/outbound/routes.ts`)가 정본이다. */
+export const KAKAO_ERROR_CODES = [
+    "validation_error",
+    "invalid_room_slug",
+    "unauthorized",
+    "plan_message_limit",
+    "insufficient_scope",
+    "room_not_bound",
+    "room_inactive",
+    "idempotency_conflict",
+    "rate_limited",
+    "kill_switch",
+    "queue_full",
+    "request_failed",
+];
+/** 모든 허브 오류의 베이스. `catch` 에서 `isKakaoError(e)` 한 번으로 전부 잡는다. */
+export class KakaoError extends Error {
+    [KAKAO_ERROR_BRAND] = true;
+    requestId;
+    constructor(message, requestId, options) {
+        super(message, options);
+        this.requestId = requestId;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.requestId === undefined ? {} : { requestId: this.requestId }),
+        };
+    }
+}
+/**
+ * 허브가 응답은 했지만 2xx 가 아니었다.
+ *
+ * 본문을 통째로 `body` 에 보관한다 — 402 는 `upgrade` 링크를, 429 는 `scope`(test/global/room)를
+ * 함께 싣는데, `error` 필드만 빼고 버리면 그 안내가 사라진다.
+ */
+export class KakaoApiError extends KakaoError {
+    name = "KakaoApiError";
+    status;
+    code;
+    retryable;
+    /** 파싱된 응답 본문. JSON 이 아니었으면 `null`. */
+    body;
+    /** `Retry-After` 또는 본문 `retry_after_ms` 에서 읽은 대기 시간. 없으면 `undefined`. */
+    retryAfterMs;
+    constructor(status, code, requestId, options) {
+        super(`Kakao Bot API returned ${status} (${code})`, requestId, options);
+        this.status = status;
+        this.code = code;
+        this.body = options?.body ?? null;
+        this.retryAfterMs = options?.retryAfterMs;
+        this.retryable = isRetryableStatus(status, code);
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            status: this.status,
+            code: this.code,
+            ...(this.retryAfterMs === undefined ? {} : { retryAfterMs: this.retryAfterMs }),
+        };
+    }
+}
+/**
+ * 응답을 받지 못했다. 허브에 닿기 전에 끊겼다는 뜻이고, 발송 여부는 알 수 없다.
+ *
+ * 같은 `requestId` 로 다시 보내면 허브가 중복을 막아 주므로 재시도가 안전하다 —
+ * **새 id 로 바꿔 보내면 중복 발송된다.**
+ */
+export class KakaoTransportError extends KakaoError {
+    name = "KakaoTransportError";
+    retryable = true;
+    constructor(requestId, options) {
+        super(options?.message ??
+            "Kakao Bot request did not complete. Delivery state is unknown; retry with the same request ID.", requestId, options);
+    }
+}
+/**
+ * 제한 시간 안에 응답이 오지 않았다. `KakaoTransportError` 의 하위라
+ * 기존 `catch (e) { if (e instanceof KakaoTransportError) … }` 가 그대로 잡는다.
+ */
+export class KakaoTimeoutError extends KakaoTransportError {
+    name = "KakaoTimeoutError";
+    timeoutMs;
+    constructor(timeoutMs, requestId, options) {
+        super(requestId, {
+            ...options,
+            message: `Kakao Bot request timed out after ${timeoutMs}ms. Delivery state is unknown; retry with the same request ID.`,
+        });
+        this.timeoutMs = timeoutMs;
+    }
+    toJSON() {
+        return { ...super.toJSON(), timeoutMs: this.timeoutMs };
+    }
+}
+/**
+ * 2xx 를 받았지만 본문이 계약과 달랐다. 허브는 받았을 가능성이 크므로 재시도하지 않는다 —
+ * 사람이 대시보드 로그를 보고 판단해야 한다.
+ */
+export class KakaoProtocolError extends KakaoError {
+    name = "KakaoProtocolError";
+    retryable = false;
+    constructor(requestId, options) {
+        super("Kakao Bot returned an unexpected response.", requestId, options);
+    }
+}
+/**
+ * 응답을 받은 실패가 재시도해도 안전한지.
+ *
+ * - `idempotency_conflict` — 같은 id 가 다른 내용으로 이미 접수됐다. 다시 보내면 중복이다.
+ * - 429 / 5xx — 일시적이다(한도, `kill_switch`, `queue_full` 모두 풀린다).
+ * - 그 밖의 4xx — 권한·플랜·본문 문제라 같은 요청을 다시 보내도 같은 답이 온다.
+ */
+function isRetryableStatus(status, code) {
+    if (code === "idempotency_conflict")
+        return false;
+    return status === 429 || status >= 500;
+}
+/**
+ * 허브 오류인지 판별한다. 중복 설치로 `instanceof` 가 막힌 환경에서도 동작한다.
+ */
+export function isKakaoError(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value[KAKAO_ERROR_BRAND] === true);
+}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export type { KakaoErrorCode, KakaoErrorCodeLike, KakaoErrorJSON } from "./errors.js";
+export { isKakaoError, KAKAO_ERROR_BRAND, KAKAO_ERROR_CODES, KakaoApiError, KakaoError, KakaoProtocolError, KakaoTimeoutError, KakaoTransportError, } from "./errors.js";
+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 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,129 @@
+export { isKakaoError, KAKAO_ERROR_BRAND, KAKAO_ERROR_CODES, KakaoApiError, KakaoError, KakaoProtocolError, KakaoTimeoutError, KakaoTransportError, } from "./errors.js";
+import { KakaoApiError, KakaoProtocolError, KakaoTimeoutError, KakaoTransportError, } from "./errors.js";
+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 (cause) {
+            // The caller's own cancellation is not our failure. Rethrow their reason unchanged,
+            // the way fetch does, so `AbortError` handling upstream keeps working.
+            if (signal?.aborted)
+                throw signal.reason;
+            if (timeout.aborted)
+                throw new KakaoTimeoutError(this.timeoutMs, requestId, { cause });
+            throw new KakaoTransportError(requestId, { cause });
+        }
+        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, {
+                body: data,
+                retryAfterMs: retryAfterMs(response, data),
+            });
+        }
+        return data;
+    }
+}
+/**
+ * How long to wait before retrying, in milliseconds.
+ *
+ * The hub sends an exact `retry_after_ms` in the body; `Retry-After` (RFC 9110) is the
+ * interoperable fallback and may also arrive from a proxy in front of the hub, in either
+ * the delay-seconds or the HTTP-date form.
+ */
+function retryAfterMs(response, body) {
+    if (object(body) && typeof body.retry_after_ms === "number" && body.retry_after_ms >= 0)
+        return Math.round(body.retry_after_ms);
+    const header = response.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.round(seconds * 1000);
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}

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.2.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"
+  }
 }