@teamlearners/clawops 0.34.0 → 0.35.0

package/README.md

@@ -493,14 +493,35 @@ const messageService = new ClawOpsMessageService({
     mode: 'sweep',                 // 리포트를 주기적으로 훑는다
     intervalMs: 5 * 60_000,        // 기본 5분
     lookbackMs: 60 * 60_000,       // 커서가 없을 때 거슬러 볼 구간. 기본 1시간
-    on: ['3104', '3107', '3102'],  // 기본값 (수신자 사유만)
+    except: RECOMMENDED_EXCLUDED_CODES,  // 기본은 3XXX 전부. 덮으면 안 되는 것만 뺀다
     types: ['ATA'],                // 훑을 타입. 친구톡까지 보려면 ['ATA','CTA','CTI']
     onFallback: (e) => logger.info({ messageId: e.messageId, statusCode: e.statusCode }, '대체발송'),
     onBlocked:  (e) => logger.warn({ messageId: e.messageId, reason: e.reason }, '대체발송 못 함'),
+    onError:    (e) => logger.error({ err: e }, '스윕 실패'),  // ← 지정하지 않으면 조용히 넘어갑니다
   },
 });
 ```
 
+⚠️ **`onError` 를 지정하지 않으면 스윕이 통째로 실패해도 아무 소리가 나지 않습니다.** 솔라피
+조회가 막히거나 자격증명이 만료되면 다음 주기에 다시 시도할 뿐이고, 그동안 대체발송은
+한 건도 나가지 않습니다. 실패가 계속되면 **문자가 안 나가는데 로그도 조용한** 상태가 되므로,
+운영에 올리실 때는 반드시 지정하십시오.
+
+`onError` 는 스윕 **전체**가 실패했을 때만 불립니다. 개별 건의 실패는 `onBlocked` 로 갑니다
+(문구를 만들지 못했거나 ClawOps 가 거절한 경우) — 한 건이 실패해도 나머지는 그대로 진행됩니다.
+
+커서를 프로세스 밖에 보관하시려면 `initialCursor` 로 넣고 `onCursor` 로 받으십시오. 재시작 후
+같은 구간을 다시 훑는 것을 줄여 줍니다(멱등키가 있어 중복 발송은 어차피 막히지만, 요청은 아낍니다).
+
+```typescript
+fallback: {
+  enabled: true,
+  mode: 'sweep',
+  initialCursor: await loadCursor(),   // 없으면 lookbackMs 만큼 거슬러 본다
+  onCursor: (cursor) => saveCursor(cursor),  // 직렬화 가능한 값만 담겨 있습니다
+}
+```
+
 **켜기만 하면 됩니다.** 커서·저장소·크론이 필요 없습니다. 발송할 때 `customFields` 에 마커를
 심어 두고, 스윕이 그 마커가 있는 실패 건만 골라 문자를 보냅니다. 고객이 솔라피로 직접 보낸
 알림톡은 마커가 없어 건드리지 않습니다.
@@ -513,10 +534,37 @@ const messageService = new ClawOpsMessageService({
 ClawOps 가 대체 문자를 거절하면 `onBlocked` 에 `reason: 'send_rejected'` 로 알리고, 다음 스윕이
 다시 시도합니다(멱등키가 같아 중복 발송은 되지 않습니다).
 
-기본 대상은 **수신자 사유만**입니다. 설정 오류(`3101` 발신프로필 무효 · `3105` 미등록 템플릿 ·
-`3106` 유효하지 않은 채널)를 문자로 덮으면 알림톡이 깨진 걸 모르게 되고, `3108`(발송 가능 시간
-아님)을 대체하면 21시 이후 발송이 되어 야간 규제에 걸립니다. 이런 건은 보내지 않고
-`onBlocked` 에 `reason: 'code_not_eligible'` 로 **알리기만** 합니다.
+##### 어떤 코드를 대체발송할지
+
+**기본은 3XXX 전부입니다.** 코드를 골라 담지 않았습니다 — 알림톡이라고 `31xx` 만 오는 게
+아니기 때문입니다. 실측에서 알림톡 건에 `3058`(전송경로 없음)이 돌아왔습니다. 목록을 추리면
+그렇게 새는 코드가 조용히 미발송이 됩니다.
+
+대신 **문자로 덮으면 안 되는 코드가 섞여 있습니다.** `RECOMMENDED_EXCLUDED_CODES` 를
+`except` 로 넘겨 빼시는 것을 권합니다.
+
+| 군 | 코드 | 덮으면 생기는 일 |
+|---|---|---|
+| 수신거부 | `3061` | 080 수신거부한 분께 문자가 나갑니다 |
+| 스팸·발신번호 변작 차단 | `3054` `3055` `3059` `3112` `3113` | 막힌 발송을 문자로 우회하는 셈이 됩니다 |
+| 설정 오류 | `3013` `3101` `3103` `3105` `3106` `3109` `3117` | 전건이 실패하는데 문자가 덮어, 알림톡이 깨진 걸 오래 모르게 됩니다. 단가도 조용히 올라갑니다 |
+| 시간 규제 | `3108` | 발송 가능 시간이 아닌데 문자로 나갑니다 |
+
+```typescript
+import { RECOMMENDED_EXCLUDED_CODES } from '@teamlearners/clawops/solapi';
+
+fallback: {
+  enabled: true,
+  mode: 'sweep',
+  except: RECOMMENDED_EXCLUDED_CODES,          // 권장 제외
+  // except: [...RECOMMENDED_EXCLUDED_CODES, '3032'],  // 더 빼려면 이어 붙이십시오
+}
+```
+
+`on` 은 반대로 **대상을 좁힙니다** — 주시면 그 코드만 나갑니다. `on` 으로 좁힌 뒤 `except` 로
+다시 뺄 수도 있습니다. `on: []` 는 아무것도 보내지 않는다는 뜻이라 기본(전부)과 구별됩니다.
+
+빠진 코드는 조용히 사라지지 않고 `onBlocked` 에 `reason: 'code_not_eligible'` 로 **알립니다.**
 
 **상주 프로세스가 없다면**(서버리스·크론) 같은 일을 하는 함수를 직접 부르십시오.
 

package/dist/agent/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk2IHVQDIP_cjs = require('../chunk-2IHVQDIP.cjs');
+var chunkNT6ZS3TQ_cjs = require('../chunk-NT6ZS3TQ.cjs');
 var chunkTVDUOKJD_cjs = require('../chunk-TVDUOKJD.cjs');
 var chunkQD2ZY4UP_cjs = require('../chunk-QD2ZY4UP.cjs');
 var fs = require('fs');
@@ -729,7 +729,7 @@ var MAX_ERROR_MESSAGE_LENGTH = 200;
 function getSdkInfo() {
   return {
     name: "clawops-node",
-    version: chunk2IHVQDIP_cjs.VERSION,
+    version: chunkNT6ZS3TQ_cjs.VERSION,
     runtime: `node/${process.versions.node}`,
     os: `${process.platform}/${os__default.default.arch()}`
   };
@@ -1474,7 +1474,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
   constructor(options) {
     this._apiKey = options.apiKey ?? process.env["CLAWOPS_API_KEY"] ?? "";
     this._accountId = options.accountId ?? process.env["CLAWOPS_ACCOUNT_ID"] ?? "";
-    this._baseUrl = options.baseUrl ?? chunk2IHVQDIP_cjs.DEFAULT_BASE_URL;
+    this._baseUrl = options.baseUrl ?? chunkNT6ZS3TQ_cjs.DEFAULT_BASE_URL;
     this._fromNumber = options.from;
     this._session = options.session;
     this._recording = options.recording ?? false;

package/dist/agent/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_URL, VERSION } from '../chunk-QNWXGJTJ.js';
+import { DEFAULT_BASE_URL, VERSION } from '../chunk-M6BYGYJO.js';
 import { AgentError, AgentConnectionError } from '../chunk-36JABW7P.js';
 import { NOOP_LOGGER, resolveBuiltinTools, createAgentLogger, createPipelineLogger, BufferingCall, attachBuffered, ulawToPcm16, resamplePcm16, getBuiltinToolSchemas, BUILTIN_TOOL_NAMES, executeBuiltinTool, CALL_NOT_READY_RESULT, pcm16ToUlaw, applyUlawGain } from '../chunk-4YLSDMLL.js';
 export { BUILTIN_TOOL_NAMES, BuiltinTool, DECODE_TABLE, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, isBuiltinTool, pcm16ToUlaw, resamplePcm16, ulawToPcm16 } from '../chunk-4YLSDMLL.js';

package/dist/{chunk-QNWXGJTJ.js → chunk-M6BYGYJO.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.34.0" ;
+var VERSION = "0.35.0" ;
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.claw-ops.com";
@@ -9,5 +9,5 @@ var INITIAL_RETRY_DELAY = 500;
 var MAX_RETRY_DELAY = 8e3;
 
 export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY, VERSION };
-//# sourceMappingURL=chunk-QNWXGJTJ.js.map
-//# sourceMappingURL=chunk-QNWXGJTJ.js.map
+//# sourceMappingURL=chunk-M6BYGYJO.js.map
+//# sourceMappingURL=chunk-M6BYGYJO.js.map

package/dist/{chunk-QNWXGJTJ.js.map → chunk-M6BYGYJO.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts","../src/constants.ts"],"names":[],"mappings":";AAEO,IAAM,OAAA,GACT,QAAA;;;ACHG,IAAM,gBAAA,GAAmB;AACzB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB;AACxB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB","file":"chunk-QNWXGJTJ.js","sourcesContent":["declare const __PKG_VERSION__: string;\n\nexport const VERSION: string = typeof __PKG_VERSION__ !== 'undefined'\n  ? __PKG_VERSION__\n  : 'dev';\n","export const DEFAULT_BASE_URL = 'https://api.claw-ops.com';\nexport const DEFAULT_MAX_RETRIES = 2;\nexport const DEFAULT_TIMEOUT = 600_000; // ms\nexport const INITIAL_RETRY_DELAY = 500; // ms\nexport const MAX_RETRY_DELAY = 8_000; // ms\n"]}
+{"version":3,"sources":["../src/version.ts","../src/constants.ts"],"names":[],"mappings":";AAEO,IAAM,OAAA,GACT,QAAA;;;ACHG,IAAM,gBAAA,GAAmB;AACzB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB;AACxB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB","file":"chunk-M6BYGYJO.js","sourcesContent":["declare const __PKG_VERSION__: string;\n\nexport const VERSION: string = typeof __PKG_VERSION__ !== 'undefined'\n  ? __PKG_VERSION__\n  : 'dev';\n","export const DEFAULT_BASE_URL = 'https://api.claw-ops.com';\nexport const DEFAULT_MAX_RETRIES = 2;\nexport const DEFAULT_TIMEOUT = 600_000; // ms\nexport const INITIAL_RETRY_DELAY = 500; // ms\nexport const MAX_RETRY_DELAY = 8_000; // ms\n"]}

package/dist/{chunk-2IHVQDIP.cjs → chunk-NT6ZS3TQ.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/version.ts
-var VERSION = "0.34.0" ;
+var VERSION = "0.35.0" ;
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.claw-ops.com";
@@ -16,5 +16,5 @@ exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
 exports.INITIAL_RETRY_DELAY = INITIAL_RETRY_DELAY;
 exports.MAX_RETRY_DELAY = MAX_RETRY_DELAY;
 exports.VERSION = VERSION;
-//# sourceMappingURL=chunk-2IHVQDIP.cjs.map
-//# sourceMappingURL=chunk-2IHVQDIP.cjs.map
+//# sourceMappingURL=chunk-NT6ZS3TQ.cjs.map
+//# sourceMappingURL=chunk-NT6ZS3TQ.cjs.map

package/dist/{chunk-2IHVQDIP.cjs.map → chunk-NT6ZS3TQ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts","../src/constants.ts"],"names":[],"mappings":";;;AAEO,IAAM,OAAA,GACT,QAAA;;;ACHG,IAAM,gBAAA,GAAmB;AACzB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB;AACxB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB","file":"chunk-2IHVQDIP.cjs","sourcesContent":["declare const __PKG_VERSION__: string;\n\nexport const VERSION: string = typeof __PKG_VERSION__ !== 'undefined'\n  ? __PKG_VERSION__\n  : 'dev';\n","export const DEFAULT_BASE_URL = 'https://api.claw-ops.com';\nexport const DEFAULT_MAX_RETRIES = 2;\nexport const DEFAULT_TIMEOUT = 600_000; // ms\nexport const INITIAL_RETRY_DELAY = 500; // ms\nexport const MAX_RETRY_DELAY = 8_000; // ms\n"]}
+{"version":3,"sources":["../src/version.ts","../src/constants.ts"],"names":[],"mappings":";;;AAEO,IAAM,OAAA,GACT,QAAA;;;ACHG,IAAM,gBAAA,GAAmB;AACzB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB;AACxB,IAAM,mBAAA,GAAsB;AAC5B,IAAM,eAAA,GAAkB","file":"chunk-NT6ZS3TQ.cjs","sourcesContent":["declare const __PKG_VERSION__: string;\n\nexport const VERSION: string = typeof __PKG_VERSION__ !== 'undefined'\n  ? __PKG_VERSION__\n  : 'dev';\n","export const DEFAULT_BASE_URL = 'https://api.claw-ops.com';\nexport const DEFAULT_MAX_RETRIES = 2;\nexport const DEFAULT_TIMEOUT = 600_000; // ms\nexport const INITIAL_RETRY_DELAY = 500; // ms\nexport const MAX_RETRY_DELAY = 8_000; // ms\n"]}

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var chunk2IHVQDIP_cjs = require('./chunk-2IHVQDIP.cjs');
+var chunkNT6ZS3TQ_cjs = require('./chunk-NT6ZS3TQ.cjs');
 var chunkTVDUOKJD_cjs = require('./chunk-TVDUOKJD.cjs');
 var zod = require('zod');
 var crypto = require('crypto');
@@ -31,9 +31,9 @@ var APIClient = class {
   _defaultHeaders;
   constructor(options) {
     this._apiKey = options.apiKey;
-    this._baseURL = validateBaseUrl((options.baseURL ?? chunk2IHVQDIP_cjs.DEFAULT_BASE_URL).replace(/\/+$/, ""));
-    this._maxRetries = options.maxRetries ?? chunk2IHVQDIP_cjs.DEFAULT_MAX_RETRIES;
-    this._timeout = options.timeout ?? chunk2IHVQDIP_cjs.DEFAULT_TIMEOUT;
+    this._baseURL = validateBaseUrl((options.baseURL ?? chunkNT6ZS3TQ_cjs.DEFAULT_BASE_URL).replace(/\/+$/, ""));
+    this._maxRetries = options.maxRetries ?? chunkNT6ZS3TQ_cjs.DEFAULT_MAX_RETRIES;
+    this._timeout = options.timeout ?? chunkNT6ZS3TQ_cjs.DEFAULT_TIMEOUT;
     this._fetch = options.fetch ?? globalThis.fetch;
     this._defaultHeaders = options.defaultHeaders ?? {};
   }
@@ -42,7 +42,7 @@ var APIClient = class {
       Authorization: `Bearer ${this._apiKey}`,
       "Content-Type": "application/json",
       Accept: "application/json",
-      "User-Agent": `claw-ops-node/${chunk2IHVQDIP_cjs.VERSION}`,
+      "User-Agent": `claw-ops-node/${chunkNT6ZS3TQ_cjs.VERSION}`,
       ...this._defaultHeaders
     };
     if (extra) Object.assign(headers, extra);
@@ -124,7 +124,7 @@ var APIClient = class {
     return status === 408 || status === 409 || status === 429 || status >= 500;
   }
   _retryDelay(retriesTaken) {
-    const delay = Math.min(chunk2IHVQDIP_cjs.INITIAL_RETRY_DELAY * 2 ** retriesTaken, chunk2IHVQDIP_cjs.MAX_RETRY_DELAY);
+    const delay = Math.min(chunkNT6ZS3TQ_cjs.INITIAL_RETRY_DELAY * 2 ** retriesTaken, chunkNT6ZS3TQ_cjs.MAX_RETRY_DELAY);
     return delay * (1 + Math.random());
   }
   _sleep(ms) {
@@ -995,7 +995,7 @@ var ClawOps = class extends APIClient {
     if (!accountId) {
       throw new chunkTVDUOKJD_cjs.ClawOpsError("accountId\uB97C \uC9C0\uC815\uD558\uAC70\uB098 CLAWOPS_ACCOUNT_ID \uD658\uACBD\uBCC0\uC218\uB97C \uC124\uC815\uD558\uC138\uC694.");
     }
-    const baseURL = options.baseURL ?? process.env.CLAWOPS_BASE_URL ?? chunk2IHVQDIP_cjs.DEFAULT_BASE_URL;
+    const baseURL = options.baseURL ?? process.env.CLAWOPS_BASE_URL ?? chunkNT6ZS3TQ_cjs.DEFAULT_BASE_URL;
     super({
       apiKey,
       baseURL,
@@ -1046,7 +1046,7 @@ var client_default_default = ClawOps;
 
 Object.defineProperty(exports, "VERSION", {
   enumerable: true,
-  get: function () { return chunk2IHVQDIP_cjs.VERSION; }
+  get: function () { return chunkNT6ZS3TQ_cjs.VERSION; }
 });
 Object.defineProperty(exports, "APIConnectionError", {
   enumerable: true,

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, VERSION, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY } from './chunk-M6BYGYJO.js';
+export { VERSION } from './chunk-M6BYGYJO.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 { z } from 'zod';

package/dist/solapi/index.cjs

@@ -128,7 +128,27 @@ async function deliverFallback(request, solapi, context) {
 // src/solapi/sweep.ts
 var FALLBACK_MARKER_FIELD = "clawopsFallback";
 var FALLBACK_MARKER_VALUE = "1";
-var DEFAULT_FALLBACK_CODES = ["3104", "3107", "3102"];
+var RECOMMENDED_EXCLUDED_CODES = [
+  // 수신거부 — 문자로 대체하면 거부한 사람에게 보내는 것이 된다
+  "3061",
+  // 스팸·발신번호 변작 차단 — 막힌 발송을 문자로 우회하는 셈이 된다
+  "3054",
+  "3055",
+  "3059",
+  "3112",
+  "3113",
+  // 설정 오류 — 전건이 실패한다. 문자가 덮으면 알림톡이 깨진 걸 몇 달간 모르고,
+  // 단가도 알림톡에서 문자로 조용히 올라간다
+  "3013",
+  "3101",
+  "3103",
+  "3105",
+  "3106",
+  "3109",
+  "3117",
+  // 발송 가능 시간이 아님 — 문자로 대체하면 야간 발송이 된다
+  "3108"
+];
 var DEFAULT_SWEEP_TYPES = ["ATA"];
 var DELIVERY_FAILURE = /^3\d{3}$/;
 var IN_FLIGHT_CODE = "3000";
@@ -138,7 +158,8 @@ var MAX_PAGES = 50;
 var firstRecipient = (to) => Array.isArray(to) ? to[0] : to;
 var timeOf = (row) => row.dateUpdated ?? row.dateCreated;
 async function sweepFailedAlimtalk(options) {
-  const targets = new Set(options.on ?? DEFAULT_FALLBACK_CODES);
+  const targets = options.on ? new Set(options.on) : null;
+  const excluded = new Set(options.except ?? []);
   const boundary = new Set(options.cursor?.seen ?? []);
   const templateCache = options.templateCache ?? /* @__PURE__ */ new Map();
   const window = options.lookbackMs ?? DEFAULT_LOOKBACK_MS;
@@ -181,7 +202,7 @@ async function sweepFailedAlimtalk(options) {
         if (row.customFields?.[FALLBACK_MARKER_FIELD] !== FALLBACK_MARKER_VALUE) continue;
         const code = String(row.statusCode ?? "");
         if (code === IN_FLIGHT_CODE || !DELIVERY_FAILURE.test(code)) continue;
-        if (!targets.has(code)) {
+        if (targets !== null && !targets.has(code) || excluded.has(code)) {
           ineligible.push(row);
           continue;
         }
@@ -583,6 +604,7 @@ function startSweepLoop(options, sweep, solapi, templateCache) {
         cursor,
         lookbackMs: sweep.lookbackMs,
         on: sweep.on,
+        except: sweep.except,
         types: sweep.types,
         fallbackField: sweep.field,
         concurrency: options.concurrency,
@@ -653,9 +675,9 @@ Object.defineProperty(exports, "SolapiBridgeError", {
 });
 exports.CLAWOPS_FAILURE_STATUS_CODE = CLAWOPS_FAILURE_STATUS_CODE;
 exports.ClawOpsMessageService = ClawOpsMessageService;
-exports.DEFAULT_FALLBACK_CODES = DEFAULT_FALLBACK_CODES;
 exports.DEFAULT_FALLBACK_FIELD = DEFAULT_FALLBACK_FIELD;
 exports.FALLBACK_MARKER_FIELD = FALLBACK_MARKER_FIELD;
+exports.RECOMMENDED_EXCLUDED_CODES = RECOMMENDED_EXCLUDED_CODES;
 exports.resolveFallbackText = resolveFallbackText;
 exports.sweepFailedAlimtalk = sweepFailedAlimtalk;
 //# sourceMappingURL=index.cjs.map