@teamlearners/clawops 0.34.0 → 0.36.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, VERSION, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY } from './chunk-QNWXGJTJ.js';
-export { VERSION } from './chunk-QNWXGJTJ.js';
-import { APITimeoutError, APIConnectionError, makeStatusError, APIResponseValidationError, ClawOpsError } from './chunk-36JABW7P.js';
-export { APIConnectionError, APIError, APIResponseValidationError, APIStatusError, APITimeoutError, AgentConnectionError, AgentError, AuthenticationError, BadRequestError, ClawOpsError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServiceUnavailableError, SolapiBridgeError, UnprocessableEntityError } from './chunk-36JABW7P.js';
+import { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, VERSION, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY } from './chunk-XL2VWU36.js';
+export { VERSION } from './chunk-XL2VWU36.js';
+import { APITimeoutError, APIConnectionError, makeStatusError, APIResponseValidationError, ClawOpsError } from './chunk-VYGIWHRU.js';
+export { APIConnectionError, APIError, APIResponseValidationError, APIStatusError, APITimeoutError, AgentConnectionError, AgentError, AuthenticationError, BadRequestError, ClawOpsError, ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServiceUnavailableError, SolapiBridgeError, UnprocessableEntityError } from './chunk-VYGIWHRU.js';
 import { z } from 'zod';
 import { timingSafeEqual, createHmac } from 'crypto';
 
@@ -622,10 +622,236 @@ var Calls = class extends APIResource {
     });
   }
 };
+var KakaoChannelSchema = z.object({
+  /** ClawOps 채널 리소스 ID. 템플릿 조회와 알림톡 발송에 이 값을 쓴다. */
+  id: z.string(),
+  /** 카카오 채널 검색용 ID. `@` 없는 형태로 저장된다. */
+  searchId: z.string(),
+  name: z.string(),
+  categoryCode: z.string(),
+  /**
+   * `connected` = 연결 완료. `needs_attention` = 연결 기록은 있으나 카카오 채널 상태를
+   * 확인하지 못한 상태다 — 실제로 끊겼을 수도, 일시적인 조회 실패일 수도 있다.
+   * `channels.retrieve()` 를 다시 부르면 재확인한다.
+   *
+   * ⛔ **닫힌 enum 으로 두지 않는다.** 어휘는 서버가 소유하므로, 상태가 하나 늘면
+   * 닫힌 enum 은 조회를 통째로 실패시킨다(알림톡 `'ata'` 가 정확히 그렇게 터졌다).
+   * 열린 유니온이면 자동완성만 낡고 조회는 계속 산다.
+   */
+  status: z.string(),
+  /** 담당자 휴대전화번호(마스킹). 원문은 저장하지 않는다. */
+  managerPhoneMasked: z.string().nullable().optional(),
+  connectedAt: z.string(),
+  /** 카카오 채널 상태를 마지막으로 확인한 시각. null 이면 연결 이후 한 번도 확인하지 않았다. */
+  syncedAt: z.string().nullable().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+}).passthrough();
+var KakaoTemplateSchema = z.object({
+  /** ClawOps 템플릿 리소스 ID. 발송의 `kakao.templateId` 에 이 값을 쓴다. */
+  id: z.string(),
+  /** ClawOps 채널 리소스 ID. 발송의 `kakao.channelId` 와 같은 값이다. */
+  channelId: z.string(),
+  name: z.string(),
+  /** 검수를 받은 템플릿 본문. `#{변수}` 자리는 발송 시 치환된다. */
+  content: z.string(),
+  /**
+   * 카카오 검수 상태(`APPROVED`·`REJECTED` 등). **카카오 쪽 열린 집합이라 문자열이다.**
+   * 발송 가능 여부 판정은 `sendable` 이 정본이다.
+   */
+  status: z.string(),
+  /** 휴면 템플릿. `true` 면 승인 상태여도 발송할 수 없다. */
+  dormant: z.boolean(),
+  /** 지금 발송에 쓸 수 있으면 true. `status === 'APPROVED' && !dormant` 다. */
+  sendable: z.boolean(),
+  /** `CHANNEL`(채널 소유) 또는 `GROUP`(기본 제공). */
+  assignType: z.string(),
+  messageType: z.string(),
+  emphasizeType: z.string(),
+  /**
+   * 발송 시 `kakao.variables` 에 모두 채워야 하는 변수 이름.
+   * 버튼 링크·강조 문구에 들어간 변수도 이 한 목록에 모인다.
+   */
+  variables: z.array(z.string()),
+  createdAt: z.string(),
+  updatedAt: z.string()
+}).passthrough();
+var KakaoChannelCategorySchema = z.object({
+  /** 채널 연결의 `categoryCode` 에 그대로 보내는 값. */
+  code: z.string(),
+  name: z.string()
+}).passthrough();
+var KakaoChannelCategoryListSchema = z.object({
+  data: z.array(KakaoChannelCategorySchema),
+  meta: z.object({
+    /** 이 목록을 공급자에서 실제로 받아 온 시각. */
+    fetchedAt: z.string(),
+    /** 서버 캐시에서 응답했는지. 캐시는 짧고 값이 바뀌면 자동으로 따라간다. */
+    cached: z.boolean()
+  }).passthrough()
+}).passthrough();
+var KakaoTokenRequestSchema = z.object({
+  requested: z.boolean(),
+  /** 정규화된 검색용 ID. `channels.connect()` 에 이 값을 그대로 보낸다. */
+  searchId: z.string(),
+  /** 인증번호가 발송된 번호(마스킹). */
+  phoneNumberMasked: z.string(),
+  /** 재요청까지 기다릴 시간(초). */
+  retryAfterSeconds: z.number()
+}).passthrough();
+
+// src/resources/kakao.ts
+var KakaoChannels = class extends APIResource {
+  get _path() {
+    return `${this._basePath}/kakao/channels`;
+  }
+  /**
+   * 연결된 채널 목록.
+   *
+   * **카카오 쪽 상태를 확인하지 않는다** — 저장된 연결 정보를 그대로 돌려주므로 빠르다.
+   * 실제 채널 상태까지 확인하려면 `retrieve()` 를 쓴다.
+   */
+  async list(params = {}, options = {}) {
+    const query = stripNotGiven({
+      status: params.status,
+      page: params.page,
+      pageSize: params.pageSize
+    });
+    const path = this._path;
+    const raw = await this._client._get(path, {
+      castTo: PageSchema(KakaoChannelSchema),
+      query: Object.keys(query).length ? query : void 0,
+      ...options
+    });
+    const page = new Page(raw.data, raw.meta);
+    page._setClient(this._client, path, KakaoChannelSchema, query);
+    return page;
+  }
+  /**
+   * 채널 하나를 조회한다. **목록과 달리 카카오 쪽 상태를 실제로 확인하고 `status` 를 갱신한다.**
+   *
+   * `connect()` 가 타임아웃됐을 때 결과를 확정하는 경로이기도 하다 — 연결을 재호출하면 중복
+   * 등록을 시도하게 되지만 이 조회는 몇 번을 불러도 안전하다.
+   *
+   * 카카오 쪽 조회에 실패해도 `404` 가 아니다. 연결 기록은 유효하므로 `status` 가
+   * `needs_attention` 으로 온다.
+   */
+  async retrieve(channelId, options = {}) {
+    return this._client._get(`${this._path}/${channelId}`, {
+      castTo: KakaoChannelSchema,
+      ...options
+    });
+  }
+  /**
+   * 채널 권한을 증명할 인증번호를 **담당자 휴대전화로 발송**해 달라고 요청한다. 연결의 첫 단계다.
+   *
+   * 응답에 인증번호는 없다(`202`). 받은 번호는 `connect()` 의 `token` 으로 보내며, 유효 시간이
+   * 있으므로 받은 뒤 바로 진행한다. 재요청이 잦으면 `429 KAKAO_RATE_LIMITED` 이고
+   * 응답의 `retryAfterSeconds` 만큼 기다린다.
+   */
+  async requestToken(params, options = {}) {
+    return this._client._post(`${this._path}/token`, {
+      body: { searchId: params.searchId, phoneNumber: params.phoneNumber },
+      castTo: KakaoTokenRequestSchema,
+      ...options
+    });
+  }
+  /**
+   * 인증번호로 채널 연결을 완료한다. **먼저 `requestToken()` 을 불러야 한다.**
+   *
+   * **멱등이다** — 이미 이 계정에 연결된 채널이면 인증번호를 소모하지 않고 기존 연결을 돌려준다.
+   * 다른 계정에 연결된 채널은 멱등이 아니라 충돌이라 `409 KAKAO_CHANNEL_ALREADY_LINKED` 다.
+   *
+   * ⚠️ **타임아웃되면 재호출하지 말 것.** 이미 연결에 성공했을 수 있어 중복 등록을 시도하게 된다.
+   * `list()` 나 `retrieve()` 로 실제 등록 여부를 확인한 뒤 결과를 확정한다.
+   *
+   * ⚠️ **실패해도 인증번호는 소모된다**(`422 KAKAO_TOKEN_INVALID`·`KAKAO_CHANNEL_REJECTED`).
+   * 원인을 해결한 뒤 `requestToken()` 부터 다시 시작해야 한다.
+   */
+  async connect(params, options = {}) {
+    return this._client._post(this._path, {
+      body: {
+        searchId: params.searchId,
+        phoneNumber: params.phoneNumber,
+        categoryCode: params.categoryCode,
+        token: params.token
+      },
+      castTo: KakaoChannelSchema,
+      ...options
+    });
+  }
+  /**
+   * 채널 연동을 해제한다. 카카오톡 채널 자체는 지워지지 않고 ClawOps 와의 연동만 끊긴다.
+   *
+   * ⚠️ **되돌릴 수 없고, 그 채널에 등록된 알림톡 템플릿도 함께 삭제된다.** 템플릿은 카카오
+   * 검수를 다시 받아야 하므로 복구에 시간이 걸린다 — 호출 전에 사용자 확인을 받을 것.
+   *
+   * 해제 후에는 그 채널을 다시 연결할 수 있다(본인이든 다른 계정이든). `requestToken()` 부터
+   * 다시 시작하면 된다.
+   */
+  async disconnect(channelId, options = {}) {
+    return this._client._deleteWithResponse(`${this._path}/${channelId}`, {
+      castTo: KakaoChannelSchema,
+      ...options
+    });
+  }
+};
+var KakaoTemplates = class extends APIResource {
+  /**
+   * 한 채널의 알림톡 템플릿 목록.
+   *
+   * 응답의 `data[].id` 를 발송의 `kakao.templateId` 로, `data[].channelId` 를
+   * `kakao.channelId` 로 쓴다. **`sendable: true` 인 템플릿만 발송할 수 있고**,
+   * `variables` 의 모든 항목을 발송 요청의 `kakao.variables` 에 채워야 한다.
+   */
+  async list(params, options = {}) {
+    const query = stripNotGiven({
+      channelId: params.channelId,
+      page: params.page,
+      pageSize: params.pageSize
+    });
+    const path = `${this._basePath}/kakao/templates`;
+    const raw = await this._client._get(path, {
+      castTo: PageSchema(KakaoTemplateSchema),
+      query: Object.keys(query).length ? query : void 0,
+      ...options
+    });
+    const page = new Page(raw.data, raw.meta);
+    page._setClient(this._client, path, KakaoTemplateSchema, query);
+    return page;
+  }
+};
+var Kakao = class extends APIResource {
+  get channels() {
+    return new KakaoChannels(this._client, this._accountId);
+  }
+  get templates() {
+    return new KakaoTemplates(this._client, this._accountId);
+  }
+  /**
+   * 채널 연결 시 지정할 업종 카테고리 목록.
+   *
+   * **값을 코드에 하드코딩하지 말 것** — 카카오/공급자 쪽에서 늘거나 바뀌는 열린 집합이고
+   * 이 응답이 그때그때의 정본이다. 응답의 `code` 를 `channels.connect()` 의 `categoryCode`
+   * 로 그대로 보낸다.
+   *
+   * 페이지네이션이 없어 `Page` 가 아니라 `{ data, meta }` 를 그대로 돌려준다.
+   */
+  async channelCategories(options = {}) {
+    return this._client._get(`${this._basePath}/kakao/channel-categories`, {
+      castTo: KakaoChannelCategoryListSchema,
+      ...options
+    });
+  }
+};
 var MessageSchema = z.object({
   messageId: z.string(),
   status: z.enum(["queued", "sending", "sent", "failed", "received"]),
-  type: z.enum(["sms", "lms", "mms", "rcs", "kakao"]),
+  /**
+   * `'ata'` 는 카카오 알림톡이다. `body` 에는 템플릿에 변수를 치환한 결과가 담기고,
+   * 버튼·아이템 리스트·강조 문구는 템플릿에 검수된 대로 발송되어 이 값에는 담기지 않는다.
+   */
+  type: z.enum(["sms", "lms", "mms", "rcs", "ata"]),
   to: z.string(),
   from: z.string(),
   body: z.string().nullable().optional(),
@@ -640,6 +866,25 @@ var MessageSchema = z.object({
 
 // src/resources/messages.ts
 var Messages = class extends APIResource {
+  /**
+   * 문자(SMS/LMS/MMS) 또는 카카오 알림톡을 발송합니다.
+   *
+   * 둘은 배타적입니다 — `kakao` 를 실으면 알림톡이고, 이때 `body`·`subject`·`mediaUrl` 은
+   * 실을 수 없습니다(본문은 검수된 템플릿이 정합니다).
+   *
+   * ```ts
+   * // 문자
+   * await client.messages.create({ to: '010…', from: '070…', body: '안녕하세요' });
+   *
+   * // 알림톡 — 실패하면 fallback 문구가 문자로 대신 나갑니다(별도 1건으로 과금)
+   * await client.messages.create({
+   *   to: '010…',
+   *   from: '070…',
+   *   kakao: { channelId, templateId, variables: { 고객명: '홍길동' } },
+   *   fallback: { body: '주문이 접수되었습니다.' },
+   * });
+   * ```
+   */
   async create(params, options = {}) {
     const body = stripNotGiven({
       To: params.to,
@@ -648,7 +893,19 @@ var Messages = class extends APIResource {
       Type: params.type,
       Subject: params.subject,
       MediaUrl: params.mediaUrl,
-      IdempotencyKey: params.idempotencyKey
+      IdempotencyKey: params.idempotencyKey,
+      // 중첩 객체는 손으로 조립한다 — stripNotGiven 은 한 겹만 훑는다.
+      Kakao: params.kakao && stripNotGiven({
+        ChannelId: params.kakao.channelId,
+        TemplateId: params.kakao.templateId,
+        Variables: params.kakao.variables
+      }),
+      Fallback: params.fallback && stripNotGiven({
+        Type: params.fallback.type,
+        Subject: params.fallback.subject,
+        Body: params.fallback.body,
+        Disabled: params.fallback.disabled
+      })
     });
     return this._client._post(`${this._basePath}/messages`, {
       body,
@@ -660,6 +917,7 @@ var Messages = class extends APIResource {
     const query = stripNotGiven({
       type: params.type,
       status: params.status,
+      number: params.number,
       page: params.page,
       pageSize: params.pageSize
     });
@@ -956,6 +1214,9 @@ var AccountContext = class {
   get blockedRecipients() {
     return new BlockedRecipients(this._client, this._accountId);
   }
+  get kakao() {
+    return new Kakao(this._client, this._accountId);
+  }
 };
 var WebhookVerificationError = class extends ClawOpsError {
   constructor(message = "Webhook \uC11C\uBA85\uC774 \uC77C\uCE58\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.") {
@@ -1031,6 +1292,10 @@ var ClawOps = class extends APIClient {
   get blockedRecipients() {
     return new BlockedRecipients(this, this._defaultAccountId);
   }
+  /** 카카오 채널·알림톡 템플릿. 발송은 `messages.create({ kakao: … })` 다. */
+  get kakao() {
+    return new Kakao(this, this._defaultAccountId);
+  }
   get webhooks() {
     return new Webhooks();
   }
@@ -1042,6 +1307,6 @@ var ClawOps = class extends APIClient {
 // src/client-default.ts
 var client_default_default = ClawOps;
 
-export { APIClient, AccountContext, AssignmentLinks, BlockedRecipients, Calls, ClawOps, Messages, Numbers, Page, Recordings, SipCredentials, SipEndpoints, WebhookLogs, WebhookVerificationError, Webhooks, client_default_default as default };
+export { APIClient, AccountContext, AssignmentLinks, BlockedRecipients, Calls, ClawOps, Kakao, KakaoChannels, KakaoTemplates, Messages, Numbers, Page, Recordings, SipCredentials, SipEndpoints, WebhookLogs, WebhookVerificationError, Webhooks, client_default_default as default };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map