@k-msg/core 0.24.1 → 0.25.0

package/dist/provider.d.ts

@@ -1,56 +1,123 @@
 import type { KMsgError } from "./errors";
 import type { Result } from "./result";
 import type { BalanceQuery, BalanceResult, DeliveryStatusQuery, DeliveryStatusResult, KakaoChannel, KakaoChannelCategories, MessageType, ProviderOnboardingSpec, SendOptions, SendResult } from "./types/index";
+/**
+ * Represents an AlimTalk template registered with a provider.
+ * Templates must be approved by Kakao before use.
+ */
 export interface Template {
+    /** Unique template identifier. */
     id: string;
+    /** Template code used in send requests. */
     code: string;
+    /** Human-readable template name. */
     name: string;
+    /** Template body with #{variable} placeholders. */
     content: string;
+    /** Template category (e.g., "authentication", "promotion"). */
     category?: string;
+    /** Approval status of the template. */
     status: "APPROVED" | "REJECTED" | "PENDING" | "INSPECTION";
+    /** Button configurations attached to the template. */
     buttons?: unknown[];
+    /** Names of variables expected in the template content. */
     variables?: string[];
+    /** When the template was created. */
     createdAt: Date;
+    /** When the template was last updated. */
     updatedAt: Date;
 }
+/**
+ * Input for creating a new AlimTalk template.
+ */
 export type TemplateCreateInput = {
+    /** Human-readable template name. */
     name: string;
+    /** Template body with #{variable} placeholders. */
     content: string;
+    /** Template category. */
     category?: string;
+    /** Button configurations. */
     buttons?: unknown[];
+    /** Expected variable names in the template. */
     variables?: string[];
 };
+/**
+ * Partial input for updating an existing template.
+ */
 export type TemplateUpdateInput = Partial<TemplateCreateInput>;
+/**
+ * Context passed to template operations.
+ */
 export type TemplateContext = {
     /**
      * Provider-specific Kakao channel key (e.g. Aligo senderKey).
      */
     kakaoChannelSenderKey?: string;
 };
+/**
+ * Interface for providers that support AlimTalk template management.
+ */
 export interface TemplateProvider {
+    /**
+     * Create a new template.
+     */
     createTemplate(input: TemplateCreateInput, ctx?: TemplateContext): Promise<Result<Template, KMsgError>>;
+    /**
+     * Update an existing template by code.
+     */
     updateTemplate(code: string, patch: TemplateUpdateInput, ctx?: TemplateContext): Promise<Result<Template, KMsgError>>;
+    /**
+     * Delete a template by code.
+     */
     deleteTemplate(code: string, ctx?: TemplateContext): Promise<Result<void, KMsgError>>;
+    /**
+     * Get a template by code.
+     */
     getTemplate(code: string, ctx?: TemplateContext): Promise<Result<Template, KMsgError>>;
+    /**
+     * List templates with optional filtering and pagination.
+     */
     listTemplates(params?: {
         status?: string;
         page?: number;
         limit?: number;
     }, ctx?: TemplateContext): Promise<Result<Template[], KMsgError>>;
 }
+/**
+ * Interface for providers that support requesting template inspection.
+ */
 export interface TemplateInspectionProvider {
+    /**
+     * Request inspection for a template (submits for approval review).
+     */
     requestTemplateInspection(code: string, ctx?: TemplateContext): Promise<Result<void, KMsgError>>;
 }
+/**
+ * Interface for providers that support Kakao channel management.
+ */
 export interface KakaoChannelProvider {
+    /**
+     * List registered Kakao channels.
+     */
     listKakaoChannels(params?: {
         plusId?: string;
         senderKey?: string;
     }): Promise<Result<KakaoChannel[], KMsgError>>;
+    /**
+     * List available channel categories for registration.
+     */
     listKakaoChannelCategories?(): Promise<Result<KakaoChannelCategories, KMsgError>>;
+    /**
+     * Request authentication SMS for channel registration.
+     */
     requestKakaoChannelAuth?(params: {
         plusId: string;
         phoneNumber: string;
     }): Promise<Result<void, KMsgError>>;
+    /**
+     * Add a Kakao channel after authentication.
+     */
     addKakaoChannel?(params: {
         plusId: string;
         authNum: string;
@@ -58,21 +125,81 @@ export interface KakaoChannelProvider {
         categoryCode: string;
     }): Promise<Result<KakaoChannel, KMsgError>>;
 }
+/**
+ * Health check result from a provider.
+ */
 export interface ProviderHealthStatus {
+    /** Whether the provider is operational. */
     healthy: boolean;
+    /** List of issues if not healthy. */
     issues: string[];
+    /** Response latency in milliseconds. */
     latencyMs?: number;
+    /** Provider-specific health details. */
     data?: Record<string, unknown>;
 }
+/**
+ * Interface for providers that support balance queries.
+ */
 export interface BalanceProvider {
+    /**
+     * Query the remaining balance/points for the provider account.
+     */
     getBalance(query?: BalanceQuery): Promise<Result<BalanceResult, KMsgError>>;
 }
+/**
+ * Core provider interface for sending messages.
+ *
+ * All providers must implement this interface. Optional capabilities
+ * (balance, templates, delivery status) are exposed via separate interfaces.
+ *
+ * @example
+ * ```ts
+ * class MyProvider implements Provider {
+ *   readonly id = "my-provider";
+ *   readonly name = "My Provider";
+ *   readonly supportedTypes = ["SMS", "LMS"] as const;
+ *
+ *   async healthCheck() { return { healthy: true, issues: [] }; }
+ *   async send(params) { ... }
+ * }
+ * ```
+ */
 export interface Provider {
+    /**
+     * Unique identifier for this provider instance.
+     * Used for routing and logging.
+     * @example "solapi"
+     */
     readonly id: string;
+    /**
+     * Human-readable name for display purposes.
+     * @example "SOLAPI"
+     */
     readonly name: string;
+    /**
+     * Message types this provider supports.
+     * Messages of unsupported types will be rejected.
+     */
     readonly supportedTypes: readonly MessageType[];
+    /**
+     * Check if the provider is operational.
+     * Used for health monitoring and circuit breaker decisions.
+     */
     healthCheck(): Promise<ProviderHealthStatus>;
+    /**
+     * Send a message through this provider.
+     * @returns Result with SendResult on success, KMsgError on failure.
+     */
     send(params: SendOptions): Promise<Result<SendResult, KMsgError>>;
+    /**
+     * Query delivery status for a previously sent message.
+     * Optional capability - not all providers support this.
+     */
     getDeliveryStatus?(query: DeliveryStatusQuery): Promise<Result<DeliveryStatusResult | null, KMsgError>>;
+    /**
+     * Get the onboarding specification for this provider.
+     * Used by tooling to guide provider configuration.
+     */
     getOnboardingSpec?(): ProviderOnboardingSpec;
 }

package/dist/result.d.ts

@@ -1,15 +1,59 @@
+/**
+ * Represents a successful result containing a value.
+ */
 export type Ok<T> = {
+    /** Always true for successful results. */
     readonly isSuccess: true;
+    /** Always false for successful results. */
     readonly isFailure: false;
+    /** The contained success value. */
     readonly value: T;
 };
+/**
+ * Represents a failed result containing an error.
+ */
 export type Fail<E> = {
+    /** Always false for failed results. */
     readonly isSuccess: false;
+    /** Always true for failed results. */
     readonly isFailure: true;
+    /** The contained error. */
     readonly error: E;
 };
+/**
+ * A result type that represents either success (Ok) or failure (Fail).
+ * Used throughout k-msg for explicit error handling without exceptions.
+ *
+ * @template T - The type of the success value
+ * @template E - The type of the error (defaults to Error)
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return fail("division by zero");
+ *   return ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.isSuccess) {
+ *   console.log(result.value); // 5
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
 export type Result<T, E = Error> = Ok<T> | Fail<E>;
+/**
+ * Create a successful result containing the given value.
+ * @param value - The success value to wrap
+ * @returns An Ok result containing the value
+ */
 export declare const ok: <T>(value: T) => Ok<T>;
+/**
+ * Create a failed result containing the given error.
+ * @param error - The error to wrap
+ * @returns A Fail result containing the error
+ */
 export declare const fail: <E>(error: E) => Fail<E>;
 /**
  * Result utility functions for chaining and transformation
@@ -58,4 +102,63 @@ export declare const Result: {
      * Check if a Result is Fail
      */
     isFail<T, E>(result: Result<T, E>): result is Fail<E>;
+    /**
+     * Execute a side-effect without breaking the chain.
+     * Calls fn with the result (ok or fail) and returns the same result.
+     *
+     * @param result - The Result to tap
+     * @param fn - Side-effect function called with the result
+     * @returns The same Result for chaining
+     *
+     * @example
+     * ```ts
+     * const result = await provider.send(options);
+     * Result.tap(result, r => console.log('Completed:', r));
+     * ```
+     */
+    tap<T, E>(result: Result<T, E>, fn: (result: Result<T, E>) => void): Result<T, E>;
+    /**
+     * Execute a side-effect on success only.
+     * Calls fn with the value only if result is ok, returns the same result.
+     *
+     * @param result - The Result to tap
+     * @param fn - Side-effect function called with the value on success
+     * @returns The same Result for chaining
+     *
+     * @example
+     * ```ts
+     * Result.tapOk(result, value => console.log('Success:', value.messageId));
+     * ```
+     */
+    tapOk<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;
+    /**
+     * Execute a side-effect on failure only.
+     * Calls fn with the error only if result is fail, returns the same result.
+     *
+     * @param result - The Result to tap
+     * @param fn - Side-effect function called with the error on failure
+     * @returns The same Result for chaining
+     *
+     * @example
+     * ```ts
+     * Result.tapErr(result, error => console.error('Failed:', error.message));
+     * ```
+     */
+    tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
+    /**
+     * Return the value on success, or throw with a custom message on failure.
+     * Use this when you want to convert a failed Result to an exception.
+     *
+     * @param result - The Result to expect
+     * @param message - Custom error message to use if result is fail
+     * @returns The success value
+     * @throws Error with the provided message (and original error as cause)
+     *
+     * @example
+     * ```ts
+     * const value = Result.expect(result, 'Message send failed');
+     * // throws Error('Message send failed') if result is fail
+     * ```
+     */
+    expect<T, E>(result: Result<T, E>, message: string): T;
 };

package/dist/types/message.d.ts

@@ -1,8 +1,34 @@
+/**
+ * Supported message types in the k-msg platform.
+ *
+ * - ALIMTALK: Kakao AlimTalk (notification talk) with approved template
+ * - FRIENDTALK: Kakao FriendTalk (friend message, no template required)
+ * - SMS: Short message (up to 90 bytes, typically ~90 Korean characters)
+ * - LMS: Long message with subject line
+ * - MMS: Multimedia message with image attachment
+ * - NSA: Naver Smart Alarm (notification service)
+ * - VOICE: Voice call message
+ * - FAX: Fax transmission
+ * - RCS_SMS/LMS/MMS: Rich Communication Services text/media messages
+ * - RCS_TPL/ITPL/LTPL: RCS template-based messages
+ */
 export type MessageType = "ALIMTALK" | "FRIENDTALK" | "SMS" | "LMS" | "MMS" | "NSA" | "VOICE" | "FAX" | "RCS_SMS" | "RCS_LMS" | "RCS_MMS" | "RCS_TPL" | "RCS_ITPL" | "RCS_LTPL";
+/**
+ * Message delivery status.
+ *
+ * - PENDING: Queued or in transit
+ * - SENT: Successfully delivered to the carrier
+ * - FAILED: Delivery failed
+ */
 export type MessageStatus = "PENDING" | "SENT" | "FAILED";
 export declare const KNOWN_MESSAGE_STATUSES: MessageStatus[];
 export declare const QUEUED_MESSAGE_STATUS: MessageStatus;
 export declare const normalizeMessageStatus: (status: unknown) => MessageStatus;
+/**
+ * Variables for template interpolation.
+ * Values are substituted into #{variableName} placeholders in templates.
+ * @example { name: "John", code: "123456" }
+ */
 export type MessageVariables = Record<string, string | number | boolean | Date | null | undefined>;
 export interface MessageButton {
     name: string;
@@ -45,6 +71,10 @@ export interface CommonSendOptions {
      * Optional routing hint to force a specific provider by id.
      */
     providerId?: string;
+    /**
+     * Recipient phone number in Korean format without hyphens.
+     * @example "01012345678"
+     */
     to: string;
     /**
      * Sender number / sender id. Optional at KMsg layer; providers may require it.
@@ -202,7 +232,15 @@ export interface RcsTemplateSendOptions extends CommonSendOptions {
     variables: MessageVariables;
     rcs?: RcsSendOptions;
 }
+/**
+ * Union of all supported send option types.
+ * Use this for type narrowing based on the `type` discriminator.
+ */
 export type SendOptions = SmsSendOptions | AlimTalkSendOptions | FriendTalkSendOptions | NsaSendOptions | VoiceMessageSendOptions | FaxMessageSendOptions | RcsTextSendOptions | RcsTemplateSendOptions;
+/**
+ * Relaxed SMS input type that allows omitting `type` and using `content` as an alias for `text`.
+ * Used for developer convenience when sending simple SMS messages.
+ */
 export type SmsDefaultSendInput = Omit<SmsSendOptions, "type" | "text"> & {
     type?: undefined;
     /**
@@ -220,16 +258,41 @@ export type SmsDefaultSendInput = Omit<SmsSendOptions, "type" | "text"> & {
  * - Other channels are modeled as discriminated unions on `type`.
  */
 export type SendInput = SendOptions | SmsDefaultSendInput;
+/**
+ * Result of a message send operation.
+ * Returned by Provider.send() and KMsg.send().
+ */
 export interface SendResult {
     /**
      * Correlation id (equals the request `messageId`).
      */
     messageId: string;
+    /**
+     * Identifier of the provider that handled this message.
+     */
     providerId: string;
+    /**
+     * Provider-specific message identifier for tracking.
+     */
     providerMessageId?: string;
+    /**
+     * Current delivery status of the message.
+     */
     status: MessageStatus;
+    /**
+     * The message type that was sent.
+     */
     type: MessageType;
+    /**
+     * Recipient phone number.
+     */
     to: string;
+    /**
+     * Non-fatal warnings (e.g., failover partially applied).
+     */
     warnings?: SendWarning[];
+    /**
+     * Raw provider response for debugging (provider-specific shape).
+     */
     raw?: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-msg/core",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "packageManager": "bun@1.3.8",
   "description": "Core types and interfaces for K-Message platform",
   "type": "module",