unified-entity-card 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 Lightweight helpers for creating and validating Unified Entity Cards.
 
+npm: https://www.npmjs.com/package/unified-entity-card
+
 ## Usage
 
 ```js
@@ -20,3 +22,5 @@ if (!result.ok) {
 ```
 
 `app_specific_settings` is treated as an opaque object. Validation focuses on schema, kind, and payload structure.
+
+If `systemPrompt` is a template ID, pass `{ systemPromptIsId: true }` to `createCharacterUEC`. It will store the prompt as `_ID:<id>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-entity-card",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Unified Entity Card helpers for creating and validating UEC files.",
   "keywords": [
     "uec",

package/src/index.d.ts

@@ -37,11 +37,18 @@ export interface CharacterScene {
   content: string;
   direction?: string;
   createdAt?: number;
-  variants?: unknown[];
+  variants?: MessageVariant[];
   selectedVariantId?: string | null;
   [key: string]: unknown;
 }
 
+export interface MessageVariant {
+  id: string;
+  content: string;
+  createdAt: number;
+  [key: string]: unknown;
+}
+
 export interface VoiceConfig {
   source: string;
   providerId: string;
@@ -53,15 +60,15 @@ export interface CharacterPayload {
   id: string;
   name: string;
   description?: string;
-  avatarPath?: string | null;
-  backgroundImagePath?: string | null;
+  avatar?: string | null;
+  chatBackground?: string | null;
   definitions?: string;
   tags?: string[];
   rules?: string[];
   scenes?: CharacterScene[];
   defaultSceneId?: string | null;
   defaultModelId?: string | null;
-  promptTemplateId?: string | null;
+  systemPrompt?: string | null;
   voiceConfig?: VoiceConfig | null;
   voiceAutoplay?: boolean;
   createdAt?: number;
@@ -73,7 +80,7 @@ export interface PersonaPayload {
   id: string;
   title: string;
   description?: string;
-  avatarPath?: string | null;
+  avatar?: string | null;
   isDefault?: boolean;
   createdAt?: number;
   updatedAt?: number;
@@ -116,6 +123,7 @@ export function createUEC(input: {
   appSpecificSettings?: UecAppSpecificSettings;
   meta?: UecMeta;
   extensions?: UecExtensions;
+  systemPromptIsId?: boolean;
 }): UecUnion;
 
 export function createCharacterUEC(
@@ -125,7 +133,8 @@ export function createCharacterUEC(
     appSpecificSettings?: UecAppSpecificSettings;
     meta?: UecMeta;
     extensions?: UecExtensions;
-  }
+    systemPromptIsId?: boolean;
+  },
 ): UecCharacter;
 
 export function createPersonaUEC(
@@ -135,11 +144,17 @@ export function createPersonaUEC(
     appSpecificSettings?: UecAppSpecificSettings;
     meta?: UecMeta;
     extensions?: UecExtensions;
-  }
+  },
 ): UecPersona;
 
-export function validateUEC(value: unknown, options?: ValidateOptions): ValidationResult;
+export function validateUEC(
+  value: unknown,
+  options?: ValidateOptions,
+): ValidationResult;
 
-export function isUEC(value: unknown, options?: ValidateOptions): value is UecUnion;
+export function isUEC(
+  value: unknown,
+  options?: ValidateOptions,
+): value is UecUnion;
 
 export function assertUEC(value: unknown, options?: ValidateOptions): UecUnion;

package/src/index.js

@@ -23,15 +23,33 @@ const optionalStringArray = (value) =>
   value === undefined ||
   (Array.isArray(value) && value.every((item) => isString(item)));
 
-const optionalUnknownArray = (value) =>
-  value === undefined || (Array.isArray(value) && value.length >= 0);
-
 const optionalObject = (value) => value === undefined || isPlainObject(value);
 
 const pushError = (errors, path, message) => {
   errors.push(`${path}: ${message}`);
 };
 
+const normalizeSystemPrompt = (payload, systemPromptIsId) => {
+  if (!systemPromptIsId) {
+    return payload;
+  }
+
+  if (!isPlainObject(payload)) {
+    return payload;
+  }
+
+  const systemPrompt = payload.systemPrompt;
+  if (!isString(systemPrompt)) {
+    return payload;
+  }
+
+  if (systemPrompt.startsWith("_ID:")) {
+    return payload;
+  }
+
+  return { ...payload, systemPrompt: `_ID:${systemPrompt}` };
+};
+
 const validateSchema = (schema, errors) => {
   if (!isPlainObject(schema)) {
     pushError(errors, "schema", "must be an object");
@@ -122,8 +140,30 @@ const validateScene = (scene, path, errors, options) => {
     pushError(errors, `${path}.createdAt`, "must be a number");
   }
 
-  if (!optionalUnknownArray(scene.variants)) {
-    pushError(errors, `${path}.variants`, "must be an array");
+  if (scene.variants !== undefined) {
+    if (!Array.isArray(scene.variants)) {
+      pushError(errors, `${path}.variants`, "must be an array");
+    } else {
+      scene.variants.forEach((variant, index) => {
+        const variantPath = `${path}.variants[${index}]`;
+        if (!isPlainObject(variant)) {
+          pushError(errors, variantPath, "must be an object");
+          return;
+        }
+
+        if (!isString(variant.id)) {
+          pushError(errors, `${variantPath}.id`, "must be a string");
+        }
+
+        if (!isString(variant.content)) {
+          pushError(errors, `${variantPath}.content`, "must be a string");
+        }
+
+        if (!isNumber(variant.createdAt)) {
+          pushError(errors, `${variantPath}.createdAt`, "must be a number");
+        }
+      });
+    }
   }
 
   if (
@@ -192,16 +232,12 @@ const validateCharacterPayload = (payload, errors, options) => {
     pushError(errors, "payload.tags", "must be an array of strings");
   }
 
-  if (!optionalString(payload.avatarPath)) {
-    pushError(errors, "payload.avatarPath", "must be a string or null");
+  if (!optionalString(payload.avatar)) {
+    pushError(errors, "payload.avatar", "must be a string or null");
   }
 
-  if (!optionalString(payload.backgroundImagePath)) {
-    pushError(
-      errors,
-      "payload.backgroundImagePath",
-      "must be a string or null",
-    );
+  if (!optionalString(payload.chatBackground)) {
+    pushError(errors, "payload.chatBackground", "must be a string or null");
   }
 
   if (!optionalStringArray(payload.rules)) {
@@ -226,8 +262,8 @@ const validateCharacterPayload = (payload, errors, options) => {
     pushError(errors, "payload.defaultModelId", "must be a string or null");
   }
 
-  if (!optionalString(payload.promptTemplateId)) {
-    pushError(errors, "payload.promptTemplateId", "must be a string or null");
+  if (!optionalString(payload.systemPrompt)) {
+    pushError(errors, "payload.systemPrompt", "must be a string or null");
   }
 
   validateVoiceConfig(payload.voiceConfig, errors);
@@ -285,8 +321,8 @@ const validatePersonaPayload = (payload, errors, options) => {
     pushError(errors, "payload.description", "must be a string");
   }
 
-  if (!optionalString(payload.avatarPath)) {
-    pushError(errors, "payload.avatarPath", "must be a string or null");
+  if (!optionalString(payload.avatar)) {
+    pushError(errors, "payload.avatar", "must be a string or null");
   }
 
   if (!optionalBoolean(payload.isDefault)) {
@@ -323,6 +359,7 @@ export const createUEC = ({
   appSpecificSettings,
   meta,
   extensions,
+  systemPromptIsId,
 } = {}) => {
   if (!kind) {
     throw new Error("kind is required");
@@ -332,10 +369,15 @@ export const createUEC = ({
     throw new Error("payload must be an object");
   }
 
+  const normalizedPayload =
+    kind === "character"
+      ? normalizeSystemPrompt(payload, systemPromptIsId)
+      : payload;
+
   return {
     schema: { ...DEFAULT_SCHEMA, ...(schema || {}) },
     kind,
-    payload,
+    payload: normalizedPayload,
     app_specific_settings: appSpecificSettings || {},
     meta: meta || {},
     extensions: extensions || {},