@kakao-bot/sdk 0.1.0 → 0.2.0

package/README.md

@@ -29,11 +29,38 @@ Node.js 20 이상, ESM을 지원합니다. 서비스 키는 브라우저 번들
 
 `queued: true`는 접수이며 실제 전달 성공이 아닙니다. 서버는 서비스별 `requestId`로 중복을 방지합니다. 같은 논리적 발송에는 같은 ID를 사용하세요. **SDK는 POST 또는 GET을 자동 재시도하지 않습니다.** 타임아웃은 이미 접수된 요청일 수 있으므로 새 ID로 재시도하면 중복 발송됩니다. `KakaoTransportError.requestId`로 요청을 식별하고 대시보드 로그를 확인하세요.
 
-- `KakaoApiError`: HTTP 상태·오류 코드·요청 ID. `402 plan_message_limit`은 플랜 사용량 제한, `429 rate_limited`는 단기 발송 제한입니다.
-- `KakaoTransportError`: 전송/타임아웃 실패. 발송 결과는 알 수 없습니다.
-- `KakaoProtocolError`: 예상하지 못한 서버 응답.
+## 오류 처리
+
+모든 오류는 `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`를 생성자에서 주입할 수 있습니다.
+- `fetch`와 `timeoutMs`(기본 10초)를 생성자에서 주입할 수 있습니다.
 
 ## 릴리스
 

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

@@ -1,3 +1,5 @@
+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;
@@ -42,24 +44,6 @@ export interface Room {
 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;

package/dist/index.js

@@ -1,32 +1,5 @@
-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;
-    }
-}
+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);
 }
@@ -114,15 +87,43 @@ export class KakaoBot {
             });
             data = await response.json().catch(() => null);
         }
-        catch {
-            throw new KakaoTransportError(requestId);
+        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);
+            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,6 @@
 {
   "name": "@kakao-bot/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed server-side client for the Kakao Bot Hub API",
   "license": "MIT",
   "author": "Jeongmin Lee",