@character-foundry/character-foundry 0.1.3 → 0.1.5

package/dist/charx.d.ts

@@ -1,2 +1,640 @@
-export * from '@character-foundry/charx';
-//# sourceMappingURL=charx.d.ts.map
+import { z } from 'zod';
+
+/**
+ * Binary Data Utilities
+ *
+ * Universal binary data operations using Uint8Array.
+ * Works in both Node.js and browser environments.
+ */
+/**
+ * Universal binary data type (works in both environments)
+ */
+export type BinaryData = Uint8Array;
+declare const CCv3DataSchema: z.ZodObject<{
+	spec: z.ZodLiteral<"chara_card_v3">;
+	spec_version: z.ZodLiteral<"3.0">;
+	data: z.ZodObject<{
+		name: z.ZodDefault<z.ZodString>;
+		description: z.ZodDefault<z.ZodString>;
+		personality: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+		scenario: z.ZodDefault<z.ZodString>;
+		first_mes: z.ZodDefault<z.ZodString>;
+		mes_example: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+		creator: z.ZodDefault<z.ZodString>;
+		character_version: z.ZodDefault<z.ZodString>;
+		tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+		group_only_greetings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+		creator_notes: z.ZodOptional<z.ZodString>;
+		system_prompt: z.ZodOptional<z.ZodString>;
+		post_history_instructions: z.ZodOptional<z.ZodString>;
+		alternate_greetings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+		character_book: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+			name: z.ZodOptional<z.ZodString>;
+			description: z.ZodOptional<z.ZodString>;
+			scan_depth: z.ZodOptional<z.ZodNumber>;
+			token_budget: z.ZodOptional<z.ZodNumber>;
+			recursive_scanning: z.ZodOptional<z.ZodBoolean>;
+			extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+			entries: z.ZodArray<z.ZodObject<{
+				keys: z.ZodArray<z.ZodString, "many">;
+				content: z.ZodString;
+				enabled: z.ZodBoolean;
+				insertion_order: z.ZodNumber;
+				case_sensitive: z.ZodOptional<z.ZodBoolean>;
+				name: z.ZodOptional<z.ZodString>;
+				priority: z.ZodOptional<z.ZodNumber>;
+				id: z.ZodOptional<z.ZodNumber>;
+				comment: z.ZodOptional<z.ZodString>;
+				selective: z.ZodOptional<z.ZodBoolean>;
+				secondary_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+				constant: z.ZodOptional<z.ZodBoolean>;
+				position: z.ZodOptional<z.ZodEnum<[
+					"before_char",
+					"after_char"
+				]>>;
+				extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+				automation_id: z.ZodOptional<z.ZodString>;
+				role: z.ZodOptional<z.ZodEnum<[
+					"system",
+					"user",
+					"assistant"
+				]>>;
+				group: z.ZodOptional<z.ZodString>;
+				scan_frequency: z.ZodOptional<z.ZodNumber>;
+				probability: z.ZodOptional<z.ZodNumber>;
+				use_regex: z.ZodOptional<z.ZodBoolean>;
+				depth: z.ZodOptional<z.ZodNumber>;
+				selective_logic: z.ZodOptional<z.ZodEnum<[
+					"AND",
+					"NOT"
+				]>>;
+			}, "strip", z.ZodTypeAny, {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}, {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}>, "many">;
+		}, "strip", z.ZodTypeAny, {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		}, {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		}>>>;
+		extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+		assets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+			type: z.ZodEnum<[
+				"icon",
+				"background",
+				"emotion",
+				"user_icon",
+				"sound",
+				"video",
+				"custom",
+				"x-risu-asset"
+			]>;
+			uri: z.ZodString;
+			name: z.ZodString;
+			ext: z.ZodString;
+		}, "strip", z.ZodTypeAny, {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}, {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}>, "many">>;
+		nickname: z.ZodOptional<z.ZodString>;
+		creator_notes_multilingual: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+		source: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+		creation_date: z.ZodOptional<z.ZodNumber>;
+		modification_date: z.ZodOptional<z.ZodNumber>;
+	}, "strip", z.ZodTypeAny, {
+		name: string;
+		description: string;
+		personality: string | null;
+		scenario: string;
+		first_mes: string;
+		mes_example: string | null;
+		tags: string[];
+		creator: string;
+		character_version: string;
+		group_only_greetings: string[];
+		extensions?: Record<string, unknown> | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	}, {
+		name?: string | undefined;
+		description?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		personality?: string | null | undefined;
+		scenario?: string | undefined;
+		first_mes?: string | undefined;
+		mes_example?: string | null | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		tags?: string[] | undefined;
+		creator?: string | undefined;
+		character_version?: string | undefined;
+		group_only_greetings?: string[] | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	}>;
+}, "strip", z.ZodTypeAny, {
+	data: {
+		name: string;
+		description: string;
+		personality: string | null;
+		scenario: string;
+		first_mes: string;
+		mes_example: string | null;
+		tags: string[];
+		creator: string;
+		character_version: string;
+		group_only_greetings: string[];
+		extensions?: Record<string, unknown> | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	};
+	spec: "chara_card_v3";
+	spec_version: "3.0";
+}, {
+	data: {
+		name?: string | undefined;
+		description?: string | undefined;
+		extensions?: Record<string, unknown> | undefined;
+		personality?: string | null | undefined;
+		scenario?: string | undefined;
+		first_mes?: string | undefined;
+		mes_example?: string | null | undefined;
+		creator_notes?: string | undefined;
+		system_prompt?: string | undefined;
+		post_history_instructions?: string | undefined;
+		alternate_greetings?: string[] | undefined;
+		character_book?: {
+			entries: {
+				keys: string[];
+				content: string;
+				enabled: boolean;
+				insertion_order: number;
+				name?: string | undefined;
+				extensions?: Record<string, unknown> | undefined;
+				case_sensitive?: boolean | undefined;
+				priority?: number | undefined;
+				id?: number | undefined;
+				comment?: string | undefined;
+				selective?: boolean | undefined;
+				secondary_keys?: string[] | undefined;
+				constant?: boolean | undefined;
+				position?: "before_char" | "after_char" | undefined;
+				automation_id?: string | undefined;
+				role?: "system" | "user" | "assistant" | undefined;
+				group?: string | undefined;
+				scan_frequency?: number | undefined;
+				probability?: number | undefined;
+				use_regex?: boolean | undefined;
+				depth?: number | undefined;
+				selective_logic?: "AND" | "NOT" | undefined;
+			}[];
+			name?: string | undefined;
+			description?: string | undefined;
+			scan_depth?: number | undefined;
+			token_budget?: number | undefined;
+			recursive_scanning?: boolean | undefined;
+			extensions?: Record<string, unknown> | undefined;
+		} | null | undefined;
+		tags?: string[] | undefined;
+		creator?: string | undefined;
+		character_version?: string | undefined;
+		group_only_greetings?: string[] | undefined;
+		assets?: {
+			name: string;
+			type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+			uri: string;
+			ext: string;
+		}[] | undefined;
+		nickname?: string | undefined;
+		creator_notes_multilingual?: Record<string, string> | undefined;
+		source?: string[] | undefined;
+		creation_date?: number | undefined;
+		modification_date?: number | undefined;
+	};
+	spec: "chara_card_v3";
+	spec_version: "3.0";
+}>;
+/**
+ * Character Card v3 full structure
+ */
+export type CCv3Data = z.infer<typeof CCv3DataSchema>;
+declare const AssetDescriptorSchema: z.ZodObject<{
+	type: z.ZodEnum<[
+		"icon",
+		"background",
+		"emotion",
+		"user_icon",
+		"sound",
+		"video",
+		"custom",
+		"x-risu-asset"
+	]>;
+	uri: z.ZodString;
+	name: z.ZodString;
+	ext: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+	name: string;
+	type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+	uri: string;
+	ext: string;
+}, {
+	name: string;
+	type: "custom" | "icon" | "background" | "emotion" | "user_icon" | "sound" | "video" | "x-risu-asset";
+	uri: string;
+	ext: string;
+}>;
+/**
+ * Asset descriptor (v3 spec)
+ */
+export type AssetDescriptor = z.infer<typeof AssetDescriptorSchema>;
+/**
+ * Check if data is a JPEG with appended ZIP (JPEG+CharX hybrid)
+ */
+export declare function isJpegCharX(data: BinaryData): boolean;
+/**
+ * CharX Types
+ *
+ * Type definitions for CharX format handling.
+ */
+/**
+ * Valid compression levels for fflate
+ */
+export type CompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * x_meta entry (PNG chunk metadata preservation)
+ */
+export interface CharxMetaEntry {
+	type?: string;
+	[key: string]: unknown;
+}
+/**
+ * Asset info from CharX extraction
+ */
+export interface CharxAssetInfo {
+	/** Path within ZIP (e.g., 'assets/icon/image/1.png') */
+	path: string;
+	/** Corresponding asset descriptor from card.json */
+	descriptor: AssetDescriptor;
+	/** Binary data (undefined if not found in ZIP) */
+	buffer?: BinaryData;
+}
+/**
+ * Complete extracted CharX data
+ */
+export interface CharxData {
+	/** card.json content */
+	card: CCv3Data;
+	/** All assets extracted from ZIP */
+	assets: CharxAssetInfo[];
+	/** x_meta/*.json files */
+	metadata?: Map<number, CharxMetaEntry>;
+	/** module.risum binary data (preserved as opaque blob) */
+	moduleRisum?: BinaryData;
+	/** Whether this is a Risu-format CharX */
+	isRisuFormat: boolean;
+}
+/**
+ * Options for CharX extraction
+ */
+export interface CharxReadOptions {
+	/** Max size for card.json in bytes (default: 10MB) */
+	maxFileSize?: number;
+	/** Max size for individual assets (default: 50MB) */
+	maxAssetSize?: number;
+	/** Max total size of all content (default: 200MB) */
+	maxTotalSize?: number;
+	/** Preserve x_meta folder (default: true) */
+	preserveXMeta?: boolean;
+	/** Preserve module.risum (default: true) */
+	preserveModuleRisum?: boolean;
+}
+/**
+ * Asset to include in CharX export
+ */
+export interface CharxWriteAsset {
+	/** Asset type (icon, background, emotion, etc.) */
+	type: string;
+	/** Asset name (without extension) */
+	name: string;
+	/** File extension */
+	ext: string;
+	/** Binary data of the asset */
+	data: BinaryData;
+	/** Whether this is the main asset of its type */
+	isMain?: boolean;
+}
+/**
+ * Options for building CharX
+ */
+export interface CharxWriteOptions {
+	/** Target spec: 'v3' = standard, 'risu' = include x_meta */
+	spec?: "v3" | "risu";
+	/** Compression level (0-9, default: 6) */
+	compressionLevel?: CompressionLevel;
+	/** Emit x_meta for image assets (default: false, true for risu spec) */
+	emitXMeta?: boolean;
+	/** Include readme.txt (default: false) */
+	emitReadme?: boolean;
+	/** Risu module.risum binary to include (opaque, preserved from read) */
+	moduleRisum?: BinaryData;
+}
+/**
+ * Result of building a CharX file
+ */
+export interface CharxBuildResult {
+	/** The CharX ZIP buffer */
+	buffer: BinaryData;
+	/** Number of assets included */
+	assetCount: number;
+	/** Total size of the CharX */
+	totalSize: number;
+}
+/**
+ * Function to fetch remote assets
+ */
+export type AssetFetcher = (url: string) => Promise<BinaryData | undefined>;
+/**
+ * CharX Reader
+ *
+ * Extracts and parses .charx (ZIP-based character card) files.
+ * Supports standard CharX, Risu CharX, and JPEG+ZIP hybrid formats.
+ */
+/**
+ * Check if data is a CharX file (ZIP with card.json)
+ *
+ * Scans the END of the file (ZIP central directory) since JPEG+ZIP hybrids
+ * can have large JPEG data at the front. The central directory listing
+ * all filenames is always at the tail of the ZIP.
+ */
+export declare function isCharX(data: BinaryData): boolean;
+/**
+ * Extract and parse a CharX buffer
+ */
+export declare function readCharX(data: BinaryData, options?: CharxReadOptions): CharxData;
+/**
+ * Extract just the card.json from a CharX buffer (quick validation)
+ */
+export declare function readCardJsonOnly(data: BinaryData): CCv3Data;
+/**
+ * Async version of readCharX with optional remote asset fetching
+ */
+export declare function readCharXAsync(data: BinaryData, options?: CharxReadOptions & {
+	fetchRemoteAssets?: boolean;
+	assetFetcher?: AssetFetcher;
+}): Promise<CharxData>;
+/**
+ * CharX Writer
+ *
+ * Creates .charx (ZIP-based character card) files.
+ */
+/**
+ * Build a CharX ZIP from card data and assets
+ */
+export declare function writeCharX(card: CCv3Data, assets: CharxWriteAsset[], options?: CharxWriteOptions): CharxBuildResult;
+/**
+ * Async version of writeCharX
+ */
+export declare function writeCharXAsync(card: CCv3Data, assets: CharxWriteAsset[], options?: CharxWriteOptions): Promise<CharxBuildResult>;
+
+export {};