@molroo-io/sdk 0.5.2

package/dist/cjs/world/world.d.ts

@@ -0,0 +1,41 @@
+import { type ApiClient } from './client';
+import { Village } from './village';
+import type { VillageData, CreateVillageOptions, PaginationOptions } from './types';
+export interface WorldOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Entry point for the World SDK.
+ *
+ * @example
+ * ```typescript
+ * import { World } from '@molroo-io/sdk';
+ *
+ * const world = new World({ apiKey: 'mk_live_...' });
+ * const village = await world.createVillage({ name: 'My Village' });
+ * const result = await village.interact({ target: 'sera', action: 'greet' });
+ * ```
+ */
+export declare class World {
+    /** @internal — exposed for advanced use only. */
+    readonly _client: ApiClient;
+    constructor(options: WorldOptions);
+    /**
+     * Create a new village and return a {@link Village} instance.
+     */
+    createVillage(options: CreateVillageOptions): Promise<Village>;
+    /**
+     * Fetch an existing village by ID and return a {@link Village} instance.
+     */
+    getVillage(id: string): Promise<Village>;
+    /**
+     * List villages. Returns raw data objects (not Village instances) for
+     * efficiency when only metadata is needed.
+     */
+    listVillages(options?: PaginationOptions): Promise<{
+        villages: VillageData[];
+        nextCursor: string | null;
+    }>;
+}
+//# sourceMappingURL=world.d.ts.map

package/dist/cjs/world/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../src/world/world.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAiCjB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;IAChB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;gBAEhB,OAAO,EAAE,YAAY;IAOjC;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpE;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB9C;;;OAGG;IACG,YAAY,CAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CA6BnE"}

package/dist/cjs/world/world.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.World = void 0;
+// INFO: @F001 Top-level domain class — see plan step 4
+const client_1 = require("./client");
+const village_1 = require("./village");
+// ---------------------------------------------------------------------------
+// Internal helper
+// ---------------------------------------------------------------------------
+/** Map raw snake_case API village object to camelCase VillageData. */
+function toVillageData(raw) {
+    return {
+        id: raw.id,
+        tenantId: raw.tenant_id,
+        name: raw.name,
+        description: raw.description,
+        accessPolicy: raw.access_policy,
+        responseRule: raw.response_rule,
+        createdAt: raw.created_at,
+        updatedAt: raw.updated_at,
+    };
+}
+const DEFAULT_BASE_URL = 'https://api.molroo.io';
+// ---------------------------------------------------------------------------
+// World class
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for the World SDK.
+ *
+ * @example
+ * ```typescript
+ * import { World } from '@molroo-io/sdk';
+ *
+ * const world = new World({ apiKey: 'mk_live_...' });
+ * const village = await world.createVillage({ name: 'My Village' });
+ * const result = await village.interact({ target: 'sera', action: 'greet' });
+ * ```
+ */
+class World {
+    constructor(options) {
+        this._client = (0, client_1.createWorldClient)({
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: options.apiKey,
+        });
+    }
+    /**
+     * Create a new village and return a {@link Village} instance.
+     */
+    async createVillage(options) {
+        const { data } = await this._client.POST('/villages', {
+            body: {
+                name: options.name,
+                description: options.description,
+                access_policy: options.accessPolicy,
+                response_rule: options.responseRule,
+            },
+        });
+        const raw = (0, client_1.unwrap)(data);
+        return new village_1.Village(this._client, toVillageData(raw));
+    }
+    /**
+     * Fetch an existing village by ID and return a {@link Village} instance.
+     */
+    async getVillage(id) {
+        const { data } = await this._client.GET('/villages/{id}', {
+            params: { path: { id } },
+        });
+        const raw = (0, client_1.unwrap)(data);
+        return new village_1.Village(this._client, toVillageData(raw));
+    }
+    /**
+     * List villages. Returns raw data objects (not Village instances) for
+     * efficiency when only metadata is needed.
+     */
+    async listVillages(options) {
+        const { data } = await this._client.GET('/villages', {
+            params: {
+                query: {
+                    limit: options?.limit?.toString(),
+                    cursor: options?.cursor,
+                },
+            },
+        });
+        const raw = (0, client_1.unwrap)(data);
+        return {
+            villages: (raw.villages ?? []).map(toVillageData),
+            nextCursor: raw.nextCursor ?? null,
+        };
+    }
+}
+exports.World = World;

package/dist/esm/api-client.d.ts

@@ -0,0 +1,23 @@
+import type { paths } from './generated/api';
+/**
+ * Create a typed openapi-fetch client for the molroo API.
+ *
+ * @param baseUrl - API base URL (e.g., 'https://api.molroo.io').
+ * @param apiKey - API key for authentication.
+ * @returns A fully-typed openapi-fetch client instance.
+ */
+export declare function createApiClient(baseUrl: string, apiKey: string): import("openapi-fetch").Client<paths, `${string}/${string}`>;
+export type ApiClient = ReturnType<typeof createApiClient>;
+/**
+ * Unwrap the `{ result: T }` envelope from API responses.
+ *
+ * Many API endpoints return `ResultWrapper` (typed as `{ result?: unknown }`)
+ * in the OpenAPI spec. This helper extracts the `result` field and casts it
+ * to the expected type.
+ *
+ * For endpoints with properly-typed response schemas, use `data.result` directly.
+ */
+export declare function unwrap<T>(data: {
+    result?: unknown;
+} | undefined): T;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/esm/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAwB7C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gEAU9D;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAAG,CAAC,CAEnE"}

package/dist/esm/api-client.js

@@ -0,0 +1,48 @@
+import createClient from 'openapi-fetch';
+import { MolrooApiError } from './errors';
+/**
+ * Middleware: throw MolrooApiError on non-OK responses.
+ *
+ * Reads the error body `{ error: { code, message } }` and converts it
+ * into a typed MolrooApiError before openapi-fetch processes the response.
+ */
+const errorMiddleware = {
+    async onResponse({ response }) {
+        if (!response.ok) {
+            const body = await response.clone().json().catch(() => ({}));
+            const err = body;
+            throw new MolrooApiError(err.error?.message ?? `API error ${response.status}`, err.error?.code ?? 'UNKNOWN', response.status);
+        }
+        // Return undefined to let openapi-fetch handle the response unchanged
+    },
+};
+/**
+ * Create a typed openapi-fetch client for the molroo API.
+ *
+ * @param baseUrl - API base URL (e.g., 'https://api.molroo.io').
+ * @param apiKey - API key for authentication.
+ * @returns A fully-typed openapi-fetch client instance.
+ */
+export function createApiClient(baseUrl, apiKey) {
+    const client = createClient({
+        baseUrl: baseUrl.replace(/\/$/, ''),
+        headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': apiKey,
+        },
+    });
+    client.use(errorMiddleware);
+    return client;
+}
+/**
+ * Unwrap the `{ result: T }` envelope from API responses.
+ *
+ * Many API endpoints return `ResultWrapper` (typed as `{ result?: unknown }`)
+ * in the OpenAPI spec. This helper extracts the `result` field and casts it
+ * to the expected type.
+ *
+ * For endpoints with properly-typed response schemas, use `data.result` directly.
+ */
+export function unwrap(data) {
+    return (data?.result ?? {});
+}

package/dist/esm/defaults/index.d.ts

@@ -0,0 +1,8 @@
+import type { PersonaConfigData } from '../types.js';
+export declare const DEFAULT_PERSONA: PersonaConfigData;
+/**
+ * Merge user-provided persona config with defaults.
+ * User values take precedence; defaults fill missing fields.
+ */
+export declare function withDefaults(config?: Partial<PersonaConfigData>): PersonaConfigData;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/defaults/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/defaults/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,eAAO,MAAM,eAAe,EAAE,iBAAkC,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAenF"}

package/dist/esm/defaults/index.js

@@ -0,0 +1,23 @@
+import defaultPersona from './persona.json';
+export const DEFAULT_PERSONA = defaultPersona;
+/**
+ * Merge user-provided persona config with defaults.
+ * User values take precedence; defaults fill missing fields.
+ */
+export function withDefaults(config) {
+    if (!config)
+        return { ...DEFAULT_PERSONA };
+    return {
+        ...DEFAULT_PERSONA,
+        ...config,
+        personality: {
+            ...DEFAULT_PERSONA.personality,
+            ...config.personality,
+        },
+        identity: {
+            ...DEFAULT_PERSONA.identity,
+            ...config.identity,
+        },
+        goals: config.goals ?? DEFAULT_PERSONA.goals,
+    };
+}

package/dist/esm/defaults/persona.json

@@ -0,0 +1,17 @@
+{
+    "personality": {
+        "O": 0.5,
+        "C": 0.5,
+        "E": 0.5,
+        "A": 0.5,
+        "N": 0.5,
+        "H": 0.5
+    },
+    "identity": {
+        "name": "Persona",
+        "role": "A person with a neutral, balanced personality.",
+        "speakingStyle": "Natural, conversational tone.",
+        "coreValues": ["honesty", "kindness"]
+    },
+    "goals": []
+}

package/dist/esm/embedding/cloudflare.d.ts

@@ -0,0 +1,15 @@
+import type { EmbeddingAdapter } from '../memory/types';
+export interface AiBinding {
+    run(model: string, input: {
+        text: string[];
+    }): Promise<{
+        data: number[][];
+    }>;
+}
+export interface CloudflareAIEmbeddingOptions {
+    ai: AiBinding;
+    model?: string;
+    dimension?: number;
+}
+export declare function cloudflareAIEmbedding(options: CloudflareAIEmbeddingOptions): EmbeddingAdapter;
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/esm/embedding/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../../src/embedding/cloudflare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,GAAG,CACD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GACxB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,gBAAgB,CAWlB"}

package/dist/esm/embedding/cloudflare.js

@@ -0,0 +1,13 @@
+const DEFAULT_MODEL = '@cf/baai/bge-base-en-v1.5';
+const DEFAULT_DIMENSION = 768;
+export function cloudflareAIEmbedding(options) {
+    const model = options.model ?? DEFAULT_MODEL;
+    const dimension = options.dimension ?? DEFAULT_DIMENSION;
+    return {
+        dimension,
+        async embed(text) {
+            const result = await options.ai.run(model, { text: [text] });
+            return result.data[0];
+        },
+    };
+}

package/dist/esm/embedding/cohere.d.ts

@@ -0,0 +1,8 @@
+import type { EmbeddingAdapter } from '../memory/types';
+export interface CohereEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    inputType?: 'search_document' | 'search_query';
+}
+export declare function cohereEmbedding(options: CohereEmbeddingOptions): EmbeddingAdapter;
+//# sourceMappingURL=cohere.d.ts.map

package/dist/esm/embedding/cohere.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere.d.ts","sourceRoot":"","sources":["../../../src/embedding/cohere.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAAC;CAChD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,gBAAgB,CA4BjF"}

package/dist/esm/embedding/cohere.js

@@ -0,0 +1,28 @@
+export function cohereEmbedding(options) {
+    const model = options.model ?? 'embed-english-v3.0';
+    const inputType = options.inputType ?? 'search_document';
+    const dimension = model.includes('v3') ? 1024 : 768;
+    return {
+        dimension,
+        embed: async (text) => {
+            const res = await fetch('https://api.cohere.com/v2/embed', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${options.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model,
+                    texts: [text],
+                    input_type: inputType,
+                    embedding_types: ['float'],
+                }),
+            });
+            if (!res.ok) {
+                throw new Error(`Cohere embedding failed: ${res.status} ${res.statusText}`);
+            }
+            const json = await res.json();
+            return json.embeddings.float[0];
+        },
+    };
+}

package/dist/esm/embedding/index.d.ts

@@ -0,0 +1,9 @@
+export { openaiEmbedding } from './openai';
+export { cohereEmbedding } from './cohere';
+export { createLocalEmbedder } from './local';
+export { cloudflareAIEmbedding } from './cloudflare';
+export type { OpenAIEmbeddingOptions } from './openai';
+export type { CohereEmbeddingOptions } from './cohere';
+export type { LocalEmbedderOptions } from './local';
+export type { CloudflareAIEmbeddingOptions, AiBinding } from './cloudflare';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/embedding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/embedding/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,YAAY,EAAE,4BAA4B,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/embedding/index.js

@@ -0,0 +1,4 @@
+export { openaiEmbedding } from './openai';
+export { cohereEmbedding } from './cohere';
+export { createLocalEmbedder } from './local';
+export { cloudflareAIEmbedding } from './cloudflare';

package/dist/esm/embedding/local.d.ts

@@ -0,0 +1,6 @@
+import type { EmbeddingAdapter } from '../memory/types';
+export interface LocalEmbedderOptions {
+    model?: string;
+}
+export declare function createLocalEmbedder(options?: LocalEmbedderOptions): Promise<EmbeddingAdapter>;
+//# sourceMappingURL=local.d.ts.map

package/dist/esm/embedding/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/embedding/local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,mBAAmB,CACvC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA4B3B"}

package/dist/esm/embedding/local.js

@@ -0,0 +1,25 @@
+export async function createLocalEmbedder(options) {
+    const modelId = options?.model ?? 'Xenova/all-MiniLM-L6-v2';
+    let pipeline;
+    try {
+        const transformers = await Function('return import("@huggingface/transformers")')();
+        pipeline = transformers.pipeline;
+    }
+    catch {
+        throw new Error('@huggingface/transformers is required for local embeddings. ' +
+            'Install it: npm install @huggingface/transformers');
+    }
+    const extractor = await pipeline('feature-extraction', modelId);
+    const probe = await extractor('test', { pooling: 'mean', normalize: true });
+    const dimension = probe.data.length;
+    return {
+        dimension,
+        embed: async (text) => {
+            const output = await extractor(text, {
+                pooling: 'mean',
+                normalize: true,
+            });
+            return Array.from(output.data);
+        },
+    };
+}

package/dist/esm/embedding/openai.d.ts

@@ -0,0 +1,9 @@
+import type { EmbeddingAdapter } from '../memory/types';
+export interface OpenAIEmbeddingOptions {
+    apiKey: string;
+    model?: string;
+    dimension?: number;
+    baseUrl?: string;
+}
+export declare function openaiEmbedding(options: OpenAIEmbeddingOptions): EmbeddingAdapter;
+//# sourceMappingURL=openai.d.ts.map

package/dist/esm/embedding/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/embedding/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,gBAAgB,CAuBjF"}

package/dist/esm/embedding/openai.js

@@ -0,0 +1,23 @@
+export function openaiEmbedding(options) {
+    const model = options.model ?? 'text-embedding-3-small';
+    const dimension = options.dimension ?? 1536;
+    const baseUrl = options.baseUrl ?? 'https://api.openai.com';
+    return {
+        dimension,
+        embed: async (text) => {
+            const res = await fetch(`${baseUrl}/v1/embeddings`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${options.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ model, input: text, dimensions: dimension }),
+            });
+            if (!res.ok) {
+                throw new Error(`OpenAI embedding failed: ${res.status} ${res.statusText}`);
+            }
+            const json = await res.json();
+            return json.data[0].embedding;
+        },
+    };
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error thrown when the molroo API returns a non-OK response.
+ *
+ * Contains the API error code and HTTP status for programmatic handling.
+ */
+export declare class MolrooApiError extends Error {
+    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    code: string;
+    /** HTTP status code. */
+    status: number;
+    constructor(message: string, 
+    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    code: string, 
+    /** HTTP status code. */
+    status: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAGrC,8EAA8E;IACvE,IAAI,EAAE,MAAM;IACnB,wBAAwB;IACjB,MAAM,EAAE,MAAM;gBAJrB,OAAO,EAAE,MAAM;IACf,8EAA8E;IACvE,IAAI,EAAE,MAAM;IACnB,wBAAwB;IACjB,MAAM,EAAE,MAAM;CAKxB"}

package/dist/esm/errors.js

@@ -0,0 +1,17 @@
+/**
+ * Error thrown when the molroo API returns a non-OK response.
+ *
+ * Contains the API error code and HTTP status for programmatic handling.
+ */
+export class MolrooApiError extends Error {
+    constructor(message, 
+    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    code, 
+    /** HTTP status code. */
+    status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'MolrooApiError';
+    }
+}

package/dist/esm/events/console.d.ts

@@ -0,0 +1,25 @@
+import type { EventAdapter, SDKEvent } from './types';
+export interface ConsoleEventAdapterOptions {
+    /** Prefix for log lines. Default: '[molroo]'. */
+    prefix?: string;
+    /** Only emit these event types. Empty = all. */
+    filter?: string[];
+    /** Output format. Default: 'human'. */
+    format?: 'human' | 'json';
+    /** Custom logger function. Default: console.log. */
+    logger?: (message: string) => void;
+}
+/**
+ * Console-based EventAdapter for development/debugging.
+ * Logs events to console (or a custom logger function).
+ */
+export declare class ConsoleEventAdapter implements EventAdapter {
+    private prefix;
+    private filter;
+    private format;
+    private logger;
+    constructor(options?: ConsoleEventAdapterOptions);
+    emit(event: SDKEvent): Promise<void>;
+    emitBatch(events: SDKEvent[]): Promise<void>;
+}
+//# sourceMappingURL=console.d.ts.map

package/dist/esm/events/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../src/events/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEtD,MAAM,WAAW,0BAA0B;IACzC,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,MAAM,CAA4B;gBAE9B,OAAO,CAAC,EAAE,0BAA0B;IAO1C,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAapC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAKnD"}

package/dist/esm/events/console.js

@@ -0,0 +1,37 @@
+/**
+ * Console-based EventAdapter for development/debugging.
+ * Logs events to console (or a custom logger function).
+ */
+export class ConsoleEventAdapter {
+    constructor(options) {
+        this.prefix = options?.prefix ?? '[molroo]';
+        this.filter = new Set(options?.filter ?? []);
+        this.format = options?.format ?? 'human';
+        this.logger = options?.logger ?? console.log;
+    }
+    async emit(event) {
+        if (this.filter.size > 0 && !this.filter.has(event.type)) {
+            return;
+        }
+        if (this.format === 'json') {
+            this.logger(`${this.prefix} ${JSON.stringify(event)}`);
+        }
+        else {
+            const time = new Date(event.timestamp).toISOString();
+            this.logger(`${this.prefix} ${time} ${event.type}: ${summarize(event.payload)}`);
+        }
+    }
+    async emitBatch(events) {
+        for (const event of events) {
+            await this.emit(event);
+        }
+    }
+}
+function summarize(payload) {
+    const keys = Object.keys(payload);
+    if (keys.length === 0)
+        return '{}';
+    if (keys.length <= 3)
+        return JSON.stringify(payload);
+    return `{${keys.slice(0, 3).join(', ')} + ${keys.length - 3} more}`;
+}

package/dist/esm/events/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event Adapter interface for molroo SDK.
+ *
+ * Abstracts event emission so consumers can:
+ * - Log emotion changes, relationship updates, stage transitions
+ * - Send webhooks, push notifications, analytics events
+ * - Build reactive UIs that respond to persona state changes
+ *
+ * Events are derived from API response data (AgentResponse fields).
+ * Implementations are provided by the consumer — SDK only defines the interface.
+ */
+/** Persona-scoped event types — emitted from persona state changes. */
+export type PersonaEventType = 'emotion_changed' | 'relationship_changed' | 'memory_consolidated' | 'reflection_generated' | 'stage_transition' | 'mask_exposure' | 'goal_changed';
+export type SDKEventType = PersonaEventType;
+export interface SDKEvent {
+    type: SDKEventType;
+    /** Present for persona-scoped events. Absent for world-scoped events. */
+    personaId?: string;
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+export interface EventAdapter {
+    /** Emit a single event. */
+    emit(event: SDKEvent): Promise<void>;
+    /** Emit multiple events in batch. Optional — falls back to sequential emit(). */
+    emitBatch?(events: SDKEvent[]): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,sBAAsB,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,GAClB,eAAe,GACf,cAAc,CAAC;AAEnB,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,iFAAiF;IACjF,SAAS,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C"}

package/dist/esm/events/types.js

@@ -0,0 +1,12 @@
+/**
+ * Event Adapter interface for molroo SDK.
+ *
+ * Abstracts event emission so consumers can:
+ * - Log emotion changes, relationship updates, stage transitions
+ * - Send webhooks, push notifications, analytics events
+ * - Build reactive UIs that respond to persona state changes
+ *
+ * Events are derived from API response data (AgentResponse fields).
+ * Implementations are provided by the consumer — SDK only defines the interface.
+ */
+export {};

package/dist/esm/events/webhook.d.ts

@@ -0,0 +1,30 @@
+import type { EventAdapter, SDKEvent } from './types';
+export interface WebhookEventAdapterOptions {
+    /** Webhook endpoint URL. */
+    url: string;
+    /** HMAC secret for signing payloads. Optional. */
+    secret?: string;
+    /** Max retry attempts on server errors. Default: 2. */
+    maxRetries?: number;
+    /** Request timeout in ms. Default: 5000. */
+    timeoutMs?: number;
+    /** Additional HTTP headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * Webhook-based EventAdapter for production event delivery.
+ * Sends events as POST requests with optional HMAC signing and retry.
+ */
+export declare class WebhookEventAdapter implements EventAdapter {
+    private url;
+    private secret?;
+    private maxRetries;
+    private timeoutMs;
+    private headers;
+    constructor(options: WebhookEventAdapterOptions);
+    emit(event: SDKEvent): Promise<void>;
+    emitBatch(events: SDKEvent[]): Promise<void>;
+    private post;
+    private sign;
+}
+//# sourceMappingURL=webhook.d.ts.map

package/dist/esm/events/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../../src/events/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGtD,MAAM,WAAW,0BAA0B;IACzC,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAyB;gBAE5B,OAAO,EAAE,0BAA0B;IAQzC,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAIpC,IAAI;IAwDlB,OAAO,CAAC,IAAI;CAIb"}