@k-msg/provider

Provider implementations for k-msg (SendOptions + Result based).

Installation

npm install @k-msg/provider @k-msg/core
# or
bun add @k-msg/provider @k-msg/core

For SOLAPI provider usage, install solapi in your app as well:

npm install solapi
# or
bun add solapi

Built-in Providers

SolapiProvider (SOLAPI)
IWINVProvider (IWINV AlimTalk + optional SMS v2)
AligoProvider (Aligo)

All providers implement the Provider interface from @k-msg/core:

supportedTypes declares supported message types
send(options: SendOptions) returns Result<SendResult, KMsgError> (never throws)
some providers also implement optional capability getBalance(query?)

Import paths:

@k-msg/provider: runtime-neutral exports (IWINVProvider, AligoProvider, onboarding helpers, mock)
@k-msg/provider/aligo: Aligo provider exports
@k-msg/provider/solapi: SOLAPI provider exports

Provider Onboarding Matrix

Single source of truth: packages/provider/src/onboarding/specs.ts

Provider	Channel onboarding	Template API	plusId policy	plusId inference	Live test support
`iwinv`	manual (console)	available	optional	unsupported	supported
`aligo`	api	available	required_if_no_inference	supported	supported
`solapi`	none (vendor metadata)	unavailable	required_if_no_inference	unsupported	partial
`mock`	api (test fixture)	available	optional	supported	none

Runtime access:

Each built-in provider exposes getOnboardingSpec().
Registry helpers are exported: getProviderOnboardingSpec, listProviderOnboardingSpecs, providerOnboardingSpecs.

ALIMTALK failover responsibilities

failover on ALIMTALK is standardized in @k-msg/core, but provider-native mapping differs.

Provider	Native mapping	Warning
`iwinv`	`reSend`, `resendType`, `resendContent`, `resendTitle`	none (treated as native)
`solapi`	`kakao.disableSms`, `text`, `subject`	`FAILOVER_PARTIAL_PROVIDER`
`aligo`	`failover`, `fmessage_1`, `fsubject_1`	`FAILOVER_PARTIAL_PROVIDER`
`mock`	no native mapping	`FAILOVER_UNSUPPORTED_PROVIDER`

Boundary:

Provider package maps to vendor-native fields and returns warning metadata.
Tracking-based API-level fallback retry (delivery polling + SMS/LMS re-send) is handled by @k-msg/messaging.

Usage (with KMsg)

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: process.env.SOLAPI_API_KEY!,
      apiSecret: process.env.SOLAPI_API_SECRET!,
      defaultFrom: "01000000000",
    }),
    new IWINVProvider({
      apiKey: process.env.IWINV_API_KEY!,
      smsApiKey: process.env.IWINV_SMS_API_KEY,
      smsAuthKey: process.env.IWINV_SMS_AUTH_KEY,
      smsSenderNumber: "01000000000",
    }),
  ],
  routing: {
    defaultProviderId: "solapi",
    byType: { ALIMTALK: "iwinv" },
  },
});

await kmsg.send({ to: "01012345678", text: "hello" });

Provider README Template

When adding a new provider, start from packages/provider/PROVIDER_README_TEMPLATE.md and include official vendor doc links.

Provider Implementation Structure

For provider code organization conventions (facade + domain modules + shared utility rules), see:

packages/provider/src/PROVIDER_STRUCTURE.md