KMsg

Defined in: packages/messaging/src/k-msg.ts:268

High-level messaging facade for sending messages through configured providers.

KMsg provides a unified API for sending various message types (SMS, LMS, MMS, ALIMTALK, FRIENDTALK, RCS, etc.) through multiple providers with automatic routing, template interpolation, and lifecycle hooks.

Key features:

• Unified send() API for all message types
• Automatic provider routing based on message type
• Template variable interpolation with #{variable} syntax
• Lifecycle hooks for monitoring and tracking
• Batch sending with concurrency control
• Optional persistence strategies

Examples

Basic usage with a single provider:

import { KMsg } from '@k-msg/messaging';
import { SolapiProvider } from '@k-msg/provider/solapi';

const kmsg = new KMsg({
  providers: [
    new SolapiProvider({
      apiKey: process.env.SOLAPI_API_KEY!,
      apiSecret: process.env.SOLAPI_API_SECRET!,
      defaultFrom: '01000000000',
    }),
  ],
});

// Send SMS (type is inferred when omitted)
const result = await kmsg.send({
  to: '01012345678',
  text: 'Hello, World!',
});

if (result.isSuccess) {
  console.log('Message sent:', result.value.messageId);
}

Multi-provider setup with routing:

import { KMsg } from '@k-msg/messaging';
import { IWINVProvider } from '@k-msg/provider';
import { SolapiProvider } from '@k-msg/provider/solapi';

const kmsg = new KMsg({
  providers: [
    new SolapiProvider({ apiKey: '...', apiSecret: '...' }),
    new IWINVProvider({ apiKey: '...' }),
  ],
  routing: {
    defaultProviderId: 'solapi',
    byType: {
      ALIMTALK: 'iwinv',
    },
  },
});

// ALIMTALK will be routed to IWINV
await kmsg.send({
  type: 'ALIMTALK',
  to: '01012345678',
  templateId: 'AUTH_OTP',
  variables: { code: '123456' },
});

Constructors

Constructor

new KMsg(config): KMsg

Defined in: packages/messaging/src/k-msg.ts:295

Creates a new KMsg instance with the specified configuration.

Parameters

config

KMsgConfig

Configuration object containing providers and optional settings

Returns

KMsg

Throws

Error if config is invalid or providers array is empty

Example

const kmsg = new KMsg({
  providers: [new SolapiProvider({ apiKey: '...', apiSecret: '...' })],
  routing: { defaultProviderId: 'solapi' },
  defaults: { sms: { autoLmsBytes: 90 } },
});

Methods

healthCheck()

healthCheck(): Promise<{ healthy: boolean; issues: string[]; providers: Record<string, ProviderHealthStatus>; }>

Defined in: packages/messaging/src/k-msg.ts:392

Performs a health check on all configured providers.

Checks the health status of each provider and aggregates the results. Useful for monitoring and determining if the messaging system is operational.

Returns

Promise<{ healthy: boolean; issues: string[]; providers: Record<string, ProviderHealthStatus>; }>

A promise resolving to health check results containing:

• healthy: true if all providers are healthy, false otherwise
• providers: Map of provider IDs to their health status
• issues: Array of error messages for any unhealthy providers

Example

const health = await kmsg.healthCheck();
if (!health.healthy) {
  console.error('Provider issues:', health.issues);
}

---

send()

Call Signature

send(input, request?): Promise<Result<SendResult, KMsgError>>

Defined in: packages/messaging/src/k-msg.ts:486

Sends a single message and returns a Result.

This method normalizes the input, selects an appropriate provider based on routing configuration, and sends the message. Template variables in the message text are interpolated if variables are provided.

Parameters

input

SendInput

The message to send. Can be a single SendInput or an array. When type is omitted, the message is treated as SMS and may be upgraded to LMS based on content length and defaults.sms.autoLmsBytes.

request?

ProviderRequestContext

Transport options forwarded to the provider for this call: a signal to cancel it and a fetch to make the request with. A batch shares them. Providers that do not support one ignore it; see provider.transportCapabilities.

Returns

Promise<Result<SendResult, KMsgError>>

A promise resolving to:

• For single input: Result<SendResult, KMsgError>
• For array input: BatchSendResult with individual results

Examples

Send an SMS:

const result = await kmsg.send({ to: '01012345678', text: 'Hello!' });
if (result.isSuccess) {
  console.log('Sent:', result.value.messageId);
} else {
  console.error('Failed:', result.error.message);
}

Send ALIMTALK with template variables:

const result = await kmsg.send({
  type: 'ALIMTALK',
  to: '01012345678',
  templateId: 'AUTH_OTP',
  variables: { code: '123456', name: 'John' },
});

Send multiple messages (batch):

const batchResult = await kmsg.send([
  { to: '01011112222', text: 'Hello 1' },
  { to: '01033334444', text: 'Hello 2' },
]);
console.log(`Total: ${batchResult.total}, Results: ${batchResult.results.length}`);

Give up on the provider after five seconds:

const result = await kmsg.send(
  { to: '01012345678', text: 'Hello!' },
  { signal: AbortSignal.timeout(5000) },
);

Call Signature

send(input, request?): Promise<BatchSendResult>

Defined in: packages/messaging/src/k-msg.ts:490

Sends a single message and returns a Result.

This method normalizes the input, selects an appropriate provider based on routing configuration, and sends the message. Template variables in the message text are interpolated if variables are provided.

Parameters

input

SendInput[]

The message to send. Can be a single SendInput or an array. When type is omitted, the message is treated as SMS and may be upgraded to LMS based on content length and defaults.sms.autoLmsBytes.

request?

ProviderRequestContext

Transport options forwarded to the provider for this call: a signal to cancel it and a fetch to make the request with. A batch shares them. Providers that do not support one ignore it; see provider.transportCapabilities.

Returns

Promise<BatchSendResult>

A promise resolving to:

• For single input: Result<SendResult, KMsgError>
• For array input: BatchSendResult with individual results

Examples

Send an SMS:

const result = await kmsg.send({ to: '01012345678', text: 'Hello!' });
if (result.isSuccess) {
  console.log('Sent:', result.value.messageId);
} else {
  console.error('Failed:', result.error.message);
}

Send ALIMTALK with template variables:

const result = await kmsg.send({
  type: 'ALIMTALK',
  to: '01012345678',
  templateId: 'AUTH_OTP',
  variables: { code: '123456', name: 'John' },
});

Send multiple messages (batch):

const batchResult = await kmsg.send([
  { to: '01011112222', text: 'Hello 1' },
  { to: '01033334444', text: 'Hello 2' },
]);
console.log(`Total: ${batchResult.total}, Results: ${batchResult.results.length}`);

Give up on the provider after five seconds:

const result = await kmsg.send(
  { to: '01012345678', text: 'Hello!' },
  { signal: AbortSignal.timeout(5000) },
);

---

sendOrThrow()

sendOrThrow(input, request?): Promise<SendResult>

Defined in: packages/messaging/src/k-msg.ts:531

Sends a single message and throws on failure.

This is a convenience method that unwraps the Result, returning the SendResult on success or throwing the KMsgError on failure. Useful when you want to use try/catch error handling instead of checking result.isSuccess.

Parameters

input

SendInput

The message to send (single message only, not an array)

request?

ProviderRequestContext

Transport options forwarded to the provider, as for send

Returns

Promise<SendResult>

A promise resolving to SendResult on success

Throws

KMsgError if the message fails to send

Example

try {
  const result = await kmsg.sendOrThrow({
    to: '01012345678',
    text: 'Hello!',
  });
  console.log('Sent:', result.messageId);
} catch (error) {
  console.error('Send failed:', error.message);
}

---

builder()

static builder(): KMsgBuilder

Defined in: packages/messaging/src/k-msg.ts:369

Creates a new fluent builder for constructing KMsg instances.

The builder provides a chainable API for configuring providers, routing, defaults, and hooks.

Returns

KMsgBuilder

A new KMsgBuilder instance

Example

const kmsg = KMsg.builder()
  .addProvider(new SolapiProvider({ apiKey: '...', apiSecret: '...' }))
  .withRouting({ defaultProviderId: 'solapi' })
  .withDefaults({ sms: { autoLmsBytes: 90 } })
  .build();

---

create()

static create(config): KMsg

Defined in: packages/messaging/src/k-msg.ts:348

Creates a KMsg instance with the specified configuration.

This is a factory method alias for the constructor, useful for functional-style code or when you prefer named factory methods.

Parameters

config

KMsgConfig

Configuration object containing providers and optional settings

Returns

KMsg

A new KMsg instance

Example

import { KMsg } from '@k-msg/messaging';
import { SolapiProvider } from '@k-msg/provider/solapi';

const kmsg = KMsg.create({
  providers: [
    new SolapiProvider({
      apiKey: process.env.SOLAPI_API_KEY!,
      apiSecret: process.env.SOLAPI_API_SECRET!,
      defaultFrom: '01000000000',
    }),
  ],
  routing: { defaultProviderId: 'solapi' },
});