@teamlearners/clawops 0.32.1 → 0.34.0

package/dist/solapi/index.d.ts

@@ -0,0 +1,269 @@
+import { RequestSendMessagesSchema, SolapiMessageService } from 'solapi';
+import { D as ClawOps } from '../client-CKaAfPlF.js';
+export { a2 as SolapiBridgeError } from '../client-CKaAfPlF.js';
+import 'zod';
+
+/** 제네릭을 거쳐야 유니온(단건 | 배열)에 분배된다 */
+type Elem<T> = T extends readonly (infer U)[] ? U : T;
+type SolapiMessage = Elem<RequestSendMessagesSchema>;
+type FallbackSource = 'customFields' | 'template' | 'text';
+/**
+ * 문구 복원에 필요한 최소 모양.
+ *
+ * 발송 요청(`SolapiMessage`)과 조회 결과(`storedMessage`)를 둘 다 받는다 —
+ * 조회 결과의 `kakaoOptions` 는 서버 정규화 포맷이라 `Record<string, unknown>` 으로 온다.
+ */
+interface FallbackInput {
+    type?: unknown;
+    text?: string | null;
+    customFields?: Record<string, string> | null;
+    kakaoOptions?: Record<string, unknown> | null;
+}
+type FallbackText = {
+    ok: true;
+    text: string;
+    source: FallbackSource;
+} | {
+    ok: false;
+    reason: 'unresolved_variables';
+    unresolved: string[];
+    source: FallbackSource;
+} | {
+    ok: false;
+    reason: 'no_template_content' | 'no_text';
+    source: FallbackSource;
+};
+interface ResolveOptions {
+    /** 대체 문구를 읽어올 customFields 키 */
+    field?: string;
+    /**
+     * 템플릿 본문 캐시. 호출자가 수명을 정한다.
+     *
+     * 값이 아니라 진행 중인 조회를 담는다 — 여러 건이 동시에 같은 템플릿을 찾을 때
+     * 완료를 기다리며 캐시가 비어 있으면 같은 요청이 그 수만큼 나간다.
+     */
+    cache?: Map<string, Promise<string | undefined>>;
+}
+declare const DEFAULT_FALLBACK_FIELD = "clawopsFallbackText";
+/**
+ * 대체발송에 쓸 문구를 만든다.
+ *
+ * 솔라피는 이 문구를 콘솔(템플릿별 대체발송 설정)에만 두고 API 로 노출하지 않는다.
+ * 알림톡은 대개 `text` 없이 `variables` 만 보내므로 템플릿 본문을 조회해 직접 치환한다.
+ */
+declare function resolveFallbackText(message: FallbackInput, solapi: SolapiMessageService, options?: ResolveOptions): Promise<FallbackText>;
+
+/** 발송 시 심는 마커. 이 값이 있는 건만 대체발송 후보다 */
+declare const FALLBACK_MARKER_FIELD = "clawopsFallback";
+/**
+ * 기본 대상 코드 — **수신자 사유만**.
+ *
+ * 설정 오류(3101 발신프로필 무효·3105 미등록 템플릿·3106 유효하지 않은 채널)를 문자로 덮으면
+ * 알림톡이 깨진 걸 고객이 몇 달간 모른다. 3108(발송 가능 시간 아님)은 문자로 대체하면
+ * 21시 이후 발송이 되어 야간 규제에 걸린다. 둘 다 `onBlocked` 로 알리기만 한다.
+ */
+declare const DEFAULT_FALLBACK_CODES: readonly ["3104", "3107", "3102"];
+/** 다음 스윕이 어디서부터 볼지. 프로세스 밖에 저장할 수 있게 직렬화 가능한 값만 담는다 */
+interface SweepCursor {
+    /** 마지막으로 본 갱신 시각 (ISO 8601) */
+    updatedAt: string;
+    /** 그 시각과 같은 messageId 들. 경계에서 같은 건을 두 번 집지 않기 위해 */
+    seen: readonly string[];
+}
+interface SweepFallbackEvent {
+    messageId: string;
+    to: string;
+    statusCode: string;
+    source: FallbackSource;
+    text: string;
+}
+type SweepBlockedEvent = {
+    messageId: string;
+    to: string;
+    statusCode: string;
+} & (Extract<FallbackText, {
+    ok: false;
+}>
+/** 실패했지만 대체발송 대상 코드가 아니다 — 설정 오류·야간 등 */
+ | {
+    ok: false;
+    reason: 'code_not_eligible';
+}
+/** 문구는 만들었는데 ClawOps 가 거절했다. 다음 스윕이 다시 시도한다 */
+ | {
+    ok: false;
+    reason: 'send_rejected';
+});
+interface SweepOptions {
+    clawops: ClawOps;
+    solapi: SolapiMessageService;
+    /** 대체발송에 쓸 기본 발신번호. 조회 결과의 from 은 솔라피 발신번호라 쓰지 않는다 */
+    from: string;
+    /** 없으면 `lookbackMs` 만큼 거슬러 본다 */
+    cursor?: SweepCursor;
+    lookbackMs?: number;
+    /** 대체발송할 상태코드. 기본 `DEFAULT_FALLBACK_CODES` */
+    on?: readonly string[];
+    /** 훑을 메시지 타입. 기본 `DEFAULT_SWEEP_TYPES` (알림톡만) */
+    types?: readonly SweepMessageType[];
+    fallbackField?: string;
+    concurrency?: number;
+    /** 이미 처리한 건을 건너뛴다. 커서가 못 막는 재갱신을 여기서 막는다 */
+    skip?: (messageId: string) => boolean;
+    /** 템플릿 본문 캐시. 스윕 간 재사용하면 조회가 줄어든다 */
+    templateCache?: Map<string, Promise<string | undefined>>;
+    onFallback?: (event: SweepFallbackEvent) => void;
+    onBlocked?: (event: SweepBlockedEvent) => void;
+}
+interface SweepResult {
+    /** 다음 호출에 그대로 넘긴다 */
+    cursor: SweepCursor;
+    /** 조회한 총 건수 */
+    scanned: number;
+    /** 대체발송한 건수 */
+    sent: number;
+    /** 문구를 만들지 못해 보내지 못한 건수 */
+    blocked: number;
+    /**
+     * 페이지 상한에 걸려 구간을 다 못 봤다. 이때는 커서를 옮기지 않아 다음 스윕이 같은 곳을
+     * 다시 본다 — 물량이 계속 상한을 넘으면 주기를 줄이거나 lookback 을 좁혀야 한다
+     */
+    truncated: boolean;
+    /** 이번에 대체발송한 messageId. 호출자가 처리 집합에 넣는다 */
+    processed: string[];
+}
+/** 조회 API 가 실제로 받는 메시지 타입. 문자열로 두면 enum 을 벗어난 값이 런타임에야 터진다 */
+type SweepMessageType = NonNullable<NonNullable<Parameters<SolapiMessageService['getMessages']>[0]>['type']>;
+/**
+ * 알림톡 발송 실패(3XXX)를 찾아 문자로 대체발송한다.
+ *
+ * 접수 실패(1XXX)는 `send()` 응답에서 바로 잡히지만, 수신자가 카카오톡을 쓰지 않거나
+ * 알림톡을 차단한 경우(3104·3107)는 접수가 성공하고 **이통사 리포트에서만 판명된다.**
+ * 그래서 주기적으로 되짚어야 한다.
+ *
+ * 발송 시 심은 마커가 있는 건만 대상이라, 고객이 솔라피로 직접 보낸 알림톡은 건드리지 않는다.
+ */
+declare function sweepFailedAlimtalk(options: SweepOptions): Promise<SweepResult>;
+
+/** 우리가 접수하지 못한 건임을 알리는 코드. 솔라피 코드 체계와 겹치지 않는다 */
+declare const CLAWOPS_FAILURE_STATUS_CODE = "CLAWOPS";
+interface FallbackEvent {
+    to: string;
+    source: FallbackSource;
+    text: string;
+    /** 스윕에서 온 경우에만 채워진다 */
+    messageId?: string;
+    statusCode?: string;
+}
+type FallbackBlockedEvent = {
+    to: string;
+    messageId?: string;
+    statusCode?: string;
+} & (Extract<FallbackText, {
+    ok: false;
+}>
+/** 스윕에서만 — 실패했지만 대체발송 대상 코드가 아니다 */
+ | {
+    ok: false;
+    reason: 'code_not_eligible';
+}
+/** 스윕에서만 — 문구는 만들었는데 ClawOps 가 거절했다 */
+ | {
+    ok: false;
+    reason: 'send_rejected';
+});
+/**
+ * 발송 실패 추적 방식.
+ *
+ * `polling`·`webhook` 은 일부러 넣지 않았다 — 유니온에 멤버를 추가하는 것은 하위호환이라
+ * 필요해지면 그때 붙이면 되고, 미리 선언하면 지키지 못할 약속이 된다.
+ */
+type FallbackTracking = 
+/**
+ * 접수 실패(1XXX)만 대체발송. `send()` 응답으로 즉시 판정된다.
+ * 추적 옵션은 받지 않는다 — `mode` 없이 `lookbackMs` 를 써 놓고 스윕이 돈다고 오해하는 것을 막는다
+ */
+{
+    mode?: undefined;
+    intervalMs?: never;
+    lookbackMs?: never;
+    on?: never;
+    initialCursor?: never;
+    onCursor?: never;
+    onError?: never;
+}
+/**
+ * 리포트를 주기적으로 훑어 발송 실패(3XXX)까지 대체발송한다.
+ * 수신자가 카카오톡을 쓰지 않거나 알림톡을 차단한 경우가 여기 해당한다.
+ */
+ | {
+    mode: 'sweep';
+    /** 스윕 주기. 기본 5분 */
+    intervalMs?: number;
+    /** 커서가 없을 때 거슬러 볼 구간. 기본 1시간 */
+    lookbackMs?: number;
+    /** 대체발송할 상태코드. 기본 3104·3107·3102 */
+    on?: readonly string[];
+    /** 훑을 메시지 타입. 기본은 알림톡만 — 친구톡까지 보려면 넓힌다 */
+    types?: SweepOptions['types'];
+    /** 프로세스 밖에 커서를 저장했다가 넘길 때 */
+    initialCursor?: SweepCursor;
+    onCursor?: (cursor: SweepCursor) => void;
+    /** 스윕 자체가 실패했을 때. 지정하지 않으면 조용히 다음 주기에 재시도한다 */
+    onError?: (error: unknown) => void;
+};
+type FallbackConfig = boolean
+/**
+ * 끈 상태. 다른 옵션은 받지 않는다 —
+ * `{ enabled: false, mode: 'sweep' }` 처럼 써 놓고 스윕이 돈다고 오해하는 것을 막는다
+ */
+ | {
+    enabled: false;
+    mode?: never;
+    field?: never;
+    onFallback?: never;
+    onBlocked?: never;
+} | ({
+    enabled: true;
+    /** 대체 문구를 읽어올 customFields 키 */
+    field?: string;
+    onFallback?: (event: FallbackEvent) => void;
+    onBlocked?: (event: FallbackBlockedEvent) => void;
+} & FallbackTracking);
+interface ClawOpsMessageServiceOptions {
+    /** ClawOps 클라이언트 */
+    clawops: ClawOps;
+    /** 문자 기본 발신번호. ClawOps 에 등록된 번호여야 한다 */
+    from: string;
+    /** 알림톡·RCS 등을 계속 쓸 때 넘긴다. 없으면 문자 전용 모드 */
+    solapi?: SolapiMessageService;
+    /**
+     * 알림톡 실패 시 문자로 대체발송.
+     * 기본은 접수 실패(1XXX)만 — 발송 실패(3XXX)까지 잡으려면 `mode: 'sweep'` 을 켠다.
+     */
+    fallback?: FallbackConfig;
+    /** 동시에 띄우는 ClawOps 요청 수. 기본 10 */
+    concurrency?: number;
+}
+/** solapi 는 send 만 노출하고 나머지는 감춘 문자 전용 서비스 */
+type ClawOpsTextOnlyService = Pick<SolapiMessageService, 'send'>;
+interface ClawOpsMessageServiceConstructor {
+    /** solapi 를 넘기면 SolapiMessageService 와 완전히 동일한 타입 */
+    new (options: ClawOpsMessageServiceOptions & {
+        solapi: SolapiMessageService;
+    }): SolapiMessageService;
+    /** 안 넘기면 문자 전용. 솔라피 기능은 타입에 나타나지 않는다 */
+    new (options: ClawOpsMessageServiceOptions & {
+        solapi?: undefined;
+    }): ClawOpsTextOnlyService;
+    /** 있는지 런타임에만 아는 경우. 두 경우 모두에서 안전한 문자 전용 타입을 준다 */
+    new (options: ClawOpsMessageServiceOptions): ClawOpsTextOnlyService;
+}
+/**
+ * 솔라피 코드를 그대로 두고 문자만 ClawOps 로 보낸다.
+ *
+ * `new` 의 결과 타입은 `SolapiMessageService` 그 자체라 기존 코드의 타입 자리에 그대로 들어간다.
+ */
+declare const ClawOpsMessageService: ClawOpsMessageServiceConstructor;
+
+export { CLAWOPS_FAILURE_STATUS_CODE, ClawOpsMessageService, type ClawOpsMessageServiceOptions, type ClawOpsTextOnlyService, DEFAULT_FALLBACK_CODES, DEFAULT_FALLBACK_FIELD, FALLBACK_MARKER_FIELD, type FallbackBlockedEvent, type FallbackConfig, type FallbackEvent, type FallbackSource, type FallbackText, type FallbackTracking, type SolapiMessage, type SweepCursor, type SweepOptions, type SweepResult, resolveFallbackText, sweepFailedAlimtalk };