@k-msg/template 0.19.1 → 0.21.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Canonical docs: [k-msg.and.guide](https://k-msg.and.guide)
 
-Template management and validation system for the K-Message platform.
+Single source of truth for K-Message template runtime lifecycle, payload validation, and personalization.
 
 ## Installation
 
@@ -12,70 +12,80 @@ npm install @k-msg/template @k-msg/core
 bun add @k-msg/template @k-msg/core
 ```
 
-## Features
+## Runtime API (`@k-msg/template`)
 
-- **Template Engine**: Comprehensive template management system
-- **Variable Parsing**: Automatic template variable extraction and validation
-- **Template Validation**: Built-in validation for template content and structure
-- **Template Registry**: Centralized template storage and retrieval
-- **Template Builder**: Dynamic template creation and modification
+Main exports focus on runtime-safe template workflows:
 
-## Runtime Compatibility
+- `TemplateLifecycleService`
+- `TemplatePersonalizer`, `defaultTemplatePersonalizer`, `TemplateVariableUtils`
+- `interpolate`
+- `validateTemplatePayload`, `parseTemplateButtons`
+- low-level parsers (`ButtonParser`, `VariableParser`, `TemplateValidator`)
 
-- Works in Edge runtimes without `nodejs_compat` (no runtime dependency on Node built-ins).
-
-## Basic Usage
+### Lifecycle Service
 
 ```typescript
-import { interpolate } from '@k-msg/template';
+import { TemplateLifecycleService } from "@k-msg/template";
+import type { TemplateProvider } from "@k-msg/core";
 
-const text = interpolate('[MyApp] Your verification code is #{code}.', {
-  code: '123456',
-});
+const provider: TemplateProvider = /* your provider */;
+const templates = new TemplateLifecycleService(provider);
 
-console.log(text); // "[MyApp] Your verification code is 123456."
+await templates.create({
+  name: "OTP Verification",
+  content: "[MyApp] Code: #{code}",
+});
 ```
 
-## Template Registry
+### Runtime Validation
 
 ```typescript
-import { TemplateRegistry } from '@k-msg/template';
+import { parseTemplateButtons, validateTemplatePayload } from "@k-msg/template";
 
-const registry = new TemplateRegistry();
+const buttons = parseTemplateButtons('[{"type":"WL","name":"Open","url_mobile":"https://example.com"}]');
+if (buttons.isFailure) throw buttons.error;
 
-// Register a template
-await registry.register({
-  id: 'otp-basic',
-  name: 'Basic OTP Template',
-  content: '[#{service}] Verification code: #{code}',
-  category: 'AUTHENTICATION'
-});
+const payload = validateTemplatePayload(
+  {
+    name: "Notice",
+    content: "Hello #{name}",
+    buttons: buttons.value,
+  },
+  { requireName: true, requireContent: true },
+);
+
+if (payload.isFailure) throw payload.error;
+```
 
-// Search templates
-const templates = await registry.search({
-  category: 'AUTHENTICATION',
-  status: 'ACTIVE'
+### Personalization
+
+```typescript
+import { TemplateVariableUtils } from "@k-msg/template";
+
+const rendered = TemplateVariableUtils.replace("Hello #{name}", {
+  name: "Jane",
 });
+// "Hello Jane"
 ```
 
-## Provider-backed TemplateService (Optional)
+## Toolkit API (`@k-msg/template/toolkit`)
 
-`TemplateService` is a small helper around the `TemplateProvider` interface from
-`@k-msg/core`.
+Builder/registry/testing helpers are exposed separately:
+
+- `TemplateBuilder`, `TemplateBuilders`
+- `TemplateRegistry`
+- `InMemoryTemplateStore`
 
 ```typescript
-import { TemplateService } from '@k-msg/template';
-import type { TemplateProvider } from '@k-msg/core';
+import { TemplateRegistry, TemplateBuilders } from "@k-msg/template/toolkit";
 
-const provider: TemplateProvider = /* your implementation */;
-const templateService = new TemplateService(provider);
+const registry = new TemplateRegistry();
+const template = TemplateBuilders.authentication("OTP", "mock")
+  .code("OTP_001")
+  .content("Code: #{code}")
+  .build();
 
-await templateService.create({
-  code: 'OTP_001',
-  name: 'OTP Verification',
-  content: '[MyApp] Your verification code is #{code}.',
-  category: 'AUTHENTICATION'
-});
+await registry.register(template);
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,14 +1,12 @@
 /**
- * Template Engine
- * 템플릿 파싱, 변수 치환, 검증 기능 제공
+ * Runtime template APIs
  */
-export { TemplateBuilder, TemplateBuilders } from "./builder/template.builder";
 export { interpolate } from "./interpolator";
 export { ButtonParser } from "./parser/button.parser";
 export { TemplateValidator, type ValidationResult } from "./parser/validator";
 export { VariableParser } from "./parser/variable.parser";
-export { type TemplateHistory, TemplateRegistry, type TemplateRegistryOptions, type TemplateSearchFilters, type TemplateSearchOptions, type TemplateSearchResult, type TemplateUsageStats, type TemplateVersion, } from "./registry/template.registry";
-export { TemplateService } from "./service";
-export { TemplateService as MockTemplateService } from "./services/template.service";
+export { type ConditionalBlock, defaultTemplatePersonalizer, type LoopBlock, type ReplacementError, type ReplacementResult, TemplatePersonalizer, type TemplatePersonalizerOptions, type TemplateVariableInfo, type TemplateVariableMap, TemplateVariableUtils, } from "./personalization/variable.replacer";
+export { type NormalizedTemplatePayload, parseTemplateButtons, type ValidateTemplatePayloadOptions, validateTemplatePayload, } from "./runtime/template-input";
+export { TemplateLifecycleService } from "./runtime/template-lifecycle.service";
 export type { AlimTalkTemplate, TemplateButton, TemplateVariable, } from "./types/template.types";
 export { TemplateCategory, TemplateStatus, TemplateType, } from "./types/template.types";