lewnpc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Swarmgram Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# lewnpc
+
+**NPCs that remember. Dialogue that levels up.**
+
+Drop-in persistent memory and stable personality for game characters. One NPM package. One API call. Your NPC remembers every player, evolves every session, and never breaks character.
+
+→ [lewnpc.com](https://lewnpc.com) · [Get API Key](https://lewnpc.com/#pricing) · [Docs](https://docs.lewnpc.com)
+
+---
+
+## Install
+
+```bash
+npm install lewnpc
+```
+
+## Quick start
+
+```typescript
+import { LewNPC } from 'lewnpc';
+
+const client = new LewNPC({
+  apiKey: process.env.LEWNPC_API_KEY,
+});
+
+// Create an NPC with Big Five personality traits
+const edric = await client.createNPC({
+  id: "edric_blacksmith",
+  role: "Village blacksmith and veteran of the Northern War",
+  backstory: "Lost his partner Maren to an avalanche on the northern pass. Quiet but warm once trust is earned.",
+  traits: {
+    openness: 0.3,         // Traditional, practical
+    conscientiousness: 0.8, // Meticulous craftsman
+    extraversion: 0.5,     // Opens up over time
+    agreeableness: 0.7,    // Kind but not a pushover
+    neuroticism: 0.2,      // Steady, rarely rattled
+  },
+});
+
+// Send a player message
+const response = await client.message({
+  npc_id: "edric_blacksmith",
+  player_id: "player_7f2a",
+  message: "I need a sword for the northern pass.",
+});
+
+console.log(response.text);
+// "The northern pass? That route's been closed since the avalanche took
+//  Maren's caravan. I can forge you a short blade — but you'll want a
+//  cloak more than a sword up there."
+
+console.log(response.emotion);       // "concerned"
+console.log(response.memory_delta);  // ["Player intends to travel the northern pass", ...]
+console.log(response.memory_count);  // 2
+console.log(response.latency_ms);    // 174
+```
+
+## The NPC remembers
+
+```typescript
+// Next session — same npc_id + player_id, different day
+const laterResponse = await client.message({
+  npc_id: "edric_blacksmith",
+  player_id: "player_7f2a",
+  message: "I made it back from the pass.",
+});
+
+console.log(laterResponse.text);
+// "Ha! Told you about the cloak, didn't I? Maren would've said the same —
+//  she knew those mountains better than anyone. Come, let me see that blade."
+
+console.log(laterResponse.emotion); // "warm"
+```
+
+No special setup. No session management. The NPC remembers because the API stores what it learned.
+
+---
+
+## API
+
+### `new LewNPC(config)`
+
+```typescript
+const client = new LewNPC({
+  apiKey: string,      // required — get one at lewnpc.com
+  baseUrl?: string,    // default: https://api.lewnpc.com/v1
+  timeout?: number,    // default: 30000ms
+});
+```
+
+---
+
+### `client.createNPC(params)`
+
+Create a character. Trait scores shape every response the character ever gives.
+
+```typescript
+await client.createNPC({
+  id: string,                  // unique ID — you choose it
+  role: string,                // character role/title
+  backstory?: string,          // optional backstory
+  traits: {
+    openness: number,          // 0.0–1.0
+    conscientiousness: number,
+    extraversion: number,
+    agreeableness: number,
+    neuroticism: number,
+  },
+  initial_memories?: string[], // optional seed memories
+  metadata?: object,           // arbitrary data, not used by model
+});
+```
+
+---
+
+### `client.message(params)` → `MessageResponse`
+
+Send a player message and get a response. This is the main method.
+
+```typescript
+await client.message({
+  npc_id: string,       // which NPC
+  player_id: string,    // which player — memory is per (npc, player) pair
+  message: string,      // the player's message
+  context?: string,     // optional per-turn context ("Player just defeated the boss")
+  temperature?: number, // default: 0.7
+  max_tokens?: number,  // default: 512
+});
+```
+
+**Response:**
+
+```typescript
+{
+  text: string,          // the NPC's dialogue
+  emotion: string,       // current emotional state ("warm", "concerned", "nostalgic", ...)
+  memory_delta: string[], // what the NPC learned this turn
+  memory_count: number,  // total memories held for this player
+  latency_ms: number,    // actual inference time
+  model: string,         // "lewis-2.0"
+}
+```
+
+---
+
+### `client.listMemories(params)` → `ListMemoriesResponse`
+
+Inspect everything an NPC remembers about a player.
+
+```typescript
+const { memories, total } = await client.listMemories({
+  npc_id: "edric_blacksmith",
+  player_id: "player_7f2a",
+  limit: 50,   // optional, default 50
+  offset: 0,   // optional, for pagination
+});
+
+memories.forEach(m => console.log(`[Turn ${m.turn}] ${m.content}`));
+// [Turn 1] Player intends to travel the northern pass
+// [Turn 1] Player may not know about the avalanche
+// [Turn 3] Player survived the northern pass
+// [Turn 3] Relationship: strengthening — shared experience
+```
+
+---
+
+### `client.resetMemory(params)`
+
+Reset a player's memory with an NPC. The NPC will treat their next message as a first meeting.
+
+```typescript
+await client.resetMemory({
+  npc_id: "edric_blacksmith",
+  player_id: "player_7f2a",
+});
+```
+
+---
+
+### `client.getNPC(id)` / `client.listNPCs()` / `client.deleteNPC(id)`
+
+Standard CRUD.
+
+---
+
+## Error handling
+
+```typescript
+import { LewNPC, LewNPCError, LewNPCRateLimitError, LewNPCAuthError } from 'lewnpc';
+
+try {
+  const response = await client.message({ ... });
+} catch (err) {
+  if (err instanceof LewNPCAuthError) {
+    console.error("Invalid API key — get one at lewnpc.com");
+  } else if (err instanceof LewNPCRateLimitError) {
+    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
+  } else if (err instanceof LewNPCError) {
+    console.error(`LewNPC error ${err.status}: ${err.message} (${err.code})`);
+  } else {
+    throw err;
+  }
+}
+```
+
+---
+
+## The Big Five
+
+LewNPC uses the [Big Five (OCEAN) model](https://en.wikipedia.org/wiki/Big_Five_personality_traits) for personality. All scores are floats between `0.0` and `1.0`.
+
+| Trait | Low (0.0) | High (1.0) |
+|---|---|---|
+| **Openness** | Practical, conventional, prefers routine | Curious, creative, open to new ideas |
+| **Conscientiousness** | Flexible, spontaneous, disorganized | Organized, reliable, goal-directed |
+| **Extraversion** | Reserved, solitary, quiet | Outgoing, energetic, talkative |
+| **Agreeableness** | Competitive, critical, blunt | Cooperative, warm, empathetic |
+| **Neuroticism** | Calm, stable, resilient | Anxious, moody, easily stressed |
+
+Traits are stable across the lifetime of a character. They don't drift. A blacksmith with `neuroticism: 0.2` stays steady whether it's their first interaction or their thousandth.
+
+---
+
+## Powered by Lewis
+
+LewNPC runs on [Lewis](https://lewis.works) — an 8B parameter language model fine-tuned on 1M+ behavioral interactions from [Swarmgram](https://swarmgram.com)'s 20,000-agent social simulation. Not a prompt wrapper on GPT-4. A purpose-built behavioral model.
+
+---
+
+## Pricing
+
+- **Free**: 3 NPCs, 1,000 messages/month
+- **Pro**: $29/month — unlimited NPCs, 50K messages/month
+
+[See full pricing →](https://lewnpc.com/#pricing)
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,204 @@
+/**
+ * Big Five (OCEAN) personality trait scores.
+ * All values between 0.0 and 1.0.
+ */
+interface BigFiveTraits {
+    /** Openness to experience: curiosity, creativity, novelty-seeking (0–1) */
+    openness: number;
+    /** Conscientiousness: organization, reliability, self-discipline (0–1) */
+    conscientiousness: number;
+    /** Extraversion: sociability, assertiveness, positive affect (0–1) */
+    extraversion: number;
+    /** Agreeableness: warmth, cooperation, empathy (0–1) */
+    agreeableness: number;
+    /** Neuroticism: anxiety, moodiness, emotional instability (0–1) */
+    neuroticism: number;
+}
+interface CreateNPCParams {
+    /** Unique identifier for this NPC. Must be unique within your account. */
+    id: string;
+    /** The character's role or title. Used as grounding context. */
+    role: string;
+    /** Optional backstory or character history. */
+    backstory?: string;
+    /** Big Five personality trait scores. */
+    traits: BigFiveTraits;
+    /**
+     * Optional seed memories to inject before any player interaction.
+     * Useful for characters with known history.
+     */
+    initial_memories?: string[];
+    /** Optional metadata object stored alongside the NPC. Not used by the model. */
+    metadata?: Record<string, unknown>;
+}
+interface NPC {
+    id: string;
+    role: string;
+    backstory: string | null;
+    traits: BigFiveTraits;
+    memory_count: number;
+    created_at: string;
+    updated_at: string;
+    metadata: Record<string, unknown>;
+}
+interface MessageParams {
+    /** ID of the NPC to message. */
+    npc_id: string;
+    /**
+     * Identifier for the player sending the message.
+     * The NPC maintains separate memory per player_id.
+     */
+    player_id: string;
+    /** The player's message text. */
+    message: string;
+    /**
+     * Optional context to inject for this turn only.
+     * Useful for in-game events (e.g. "The player has just defeated the boss").
+     */
+    context?: string;
+    /** Sampling temperature. Default: 0.7 */
+    temperature?: number;
+    /** Maximum tokens for the response. Default: 512 */
+    max_tokens?: number;
+}
+interface MessageResponse {
+    /** The NPC's dialogue response. */
+    text: string;
+    /**
+     * The NPC's current emotional state.
+     * Examples: "neutral", "warm", "concerned", "suspicious", "nostalgic", "amused"
+     */
+    emotion: string;
+    /**
+     * Structured list of what the NPC learned or remembered from this interaction.
+     * Returned as an array of concise memory strings.
+     * Store these if you want to render them in-game.
+     */
+    memory_delta: string[];
+    /** Total number of memories this NPC holds for this player_id. */
+    memory_count: number;
+    /** Actual inference latency in milliseconds. */
+    latency_ms: number;
+    /** Model version used for this response. */
+    model: string;
+}
+interface Memory {
+    id: string;
+    player_id: string;
+    content: string;
+    turn: number;
+    created_at: string;
+}
+interface ListMemoriesParams {
+    npc_id: string;
+    player_id: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListMemoriesResponse {
+    memories: Memory[];
+    total: number;
+    player_id: string;
+}
+interface ResetMemoryParams {
+    npc_id: string;
+    player_id: string;
+}
+interface LewNPCConfig {
+    /** Your LewNPC API key. Get one at https://lewnpc.com */
+    apiKey: string;
+    /**
+     * API base URL. Defaults to https://api.lewnpc.com/v1
+     * Override for local development or self-hosted deployments.
+     */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+}
+declare class LewNPCError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+declare class LewNPCAuthError extends LewNPCError {
+    constructor();
+}
+declare class LewNPCNotFoundError extends LewNPCError {
+    constructor(resource: string);
+}
+declare class LewNPCRateLimitError extends LewNPCError {
+    readonly retryAfter: number;
+    constructor(retryAfter?: number);
+}
+
+declare class LewNPC {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: LewNPCConfig);
+    private request;
+    /**
+     * Create a new NPC with a personality profile.
+     *
+     * @example
+     * const edric = await client.createNPC({
+     *   id: "edric_blacksmith",
+     *   role: "Village blacksmith and veteran of the Northern War",
+     *   backstory: "Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.",
+     *   traits: {
+     *     openness: 0.3,
+     *     conscientiousness: 0.8,
+     *     extraversion: 0.5,
+     *     agreeableness: 0.7,
+     *     neuroticism: 0.2,
+     *   },
+     * });
+     */
+    createNPC(params: CreateNPCParams): Promise<NPC>;
+    /**
+     * Retrieve an existing NPC by ID.
+     */
+    getNPC(npcId: string): Promise<NPC>;
+    /**
+     * List all NPCs in your account.
+     */
+    listNPCs(): Promise<NPC[]>;
+    /**
+     * Delete an NPC and all associated memories.
+     * This action is permanent.
+     */
+    deleteNPC(npcId: string): Promise<void>;
+    /**
+     * Send a message to an NPC and get a personality-consistent, memory-grounded response.
+     *
+     * The NPC remembers every interaction with each player_id across sessions.
+     *
+     * @example
+     * const response = await client.message({
+     *   npc_id: "edric_blacksmith",
+     *   player_id: "player_7f2a",
+     *   message: "I need a sword for the northern pass.",
+     * });
+     *
+     * console.log(response.text);
+     * // "The northern pass? That route's been closed since the avalanche..."
+     *
+     * console.log(response.emotion);
+     * // "concerned"
+     *
+     * console.log(response.memory_delta);
+     * // ["Player intends to travel the northern pass", "Player may not know about the avalanche"]
+     */
+    message(params: MessageParams): Promise<MessageResponse>;
+    /**
+     * List all memories an NPC holds for a specific player.
+     */
+    listMemories(params: ListMemoriesParams): Promise<ListMemoriesResponse>;
+    /**
+     * Reset all memories an NPC holds for a specific player.
+     * The NPC will treat subsequent messages from this player as a first meeting.
+     */
+    resetMemory(params: ResetMemoryParams): Promise<void>;
+}
+
+export { type BigFiveTraits, type CreateNPCParams, LewNPC, LewNPCAuthError, type LewNPCConfig, LewNPCError, LewNPCNotFoundError, LewNPCRateLimitError, type ListMemoriesParams, type ListMemoriesResponse, type Memory, type MessageParams, type MessageResponse, type NPC, type ResetMemoryParams };

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Big Five (OCEAN) personality trait scores.
+ * All values between 0.0 and 1.0.
+ */
+interface BigFiveTraits {
+    /** Openness to experience: curiosity, creativity, novelty-seeking (0–1) */
+    openness: number;
+    /** Conscientiousness: organization, reliability, self-discipline (0–1) */
+    conscientiousness: number;
+    /** Extraversion: sociability, assertiveness, positive affect (0–1) */
+    extraversion: number;
+    /** Agreeableness: warmth, cooperation, empathy (0–1) */
+    agreeableness: number;
+    /** Neuroticism: anxiety, moodiness, emotional instability (0–1) */
+    neuroticism: number;
+}
+interface CreateNPCParams {
+    /** Unique identifier for this NPC. Must be unique within your account. */
+    id: string;
+    /** The character's role or title. Used as grounding context. */
+    role: string;
+    /** Optional backstory or character history. */
+    backstory?: string;
+    /** Big Five personality trait scores. */
+    traits: BigFiveTraits;
+    /**
+     * Optional seed memories to inject before any player interaction.
+     * Useful for characters with known history.
+     */
+    initial_memories?: string[];
+    /** Optional metadata object stored alongside the NPC. Not used by the model. */
+    metadata?: Record<string, unknown>;
+}
+interface NPC {
+    id: string;
+    role: string;
+    backstory: string | null;
+    traits: BigFiveTraits;
+    memory_count: number;
+    created_at: string;
+    updated_at: string;
+    metadata: Record<string, unknown>;
+}
+interface MessageParams {
+    /** ID of the NPC to message. */
+    npc_id: string;
+    /**
+     * Identifier for the player sending the message.
+     * The NPC maintains separate memory per player_id.
+     */
+    player_id: string;
+    /** The player's message text. */
+    message: string;
+    /**
+     * Optional context to inject for this turn only.
+     * Useful for in-game events (e.g. "The player has just defeated the boss").
+     */
+    context?: string;
+    /** Sampling temperature. Default: 0.7 */
+    temperature?: number;
+    /** Maximum tokens for the response. Default: 512 */
+    max_tokens?: number;
+}
+interface MessageResponse {
+    /** The NPC's dialogue response. */
+    text: string;
+    /**
+     * The NPC's current emotional state.
+     * Examples: "neutral", "warm", "concerned", "suspicious", "nostalgic", "amused"
+     */
+    emotion: string;
+    /**
+     * Structured list of what the NPC learned or remembered from this interaction.
+     * Returned as an array of concise memory strings.
+     * Store these if you want to render them in-game.
+     */
+    memory_delta: string[];
+    /** Total number of memories this NPC holds for this player_id. */
+    memory_count: number;
+    /** Actual inference latency in milliseconds. */
+    latency_ms: number;
+    /** Model version used for this response. */
+    model: string;
+}
+interface Memory {
+    id: string;
+    player_id: string;
+    content: string;
+    turn: number;
+    created_at: string;
+}
+interface ListMemoriesParams {
+    npc_id: string;
+    player_id: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListMemoriesResponse {
+    memories: Memory[];
+    total: number;
+    player_id: string;
+}
+interface ResetMemoryParams {
+    npc_id: string;
+    player_id: string;
+}
+interface LewNPCConfig {
+    /** Your LewNPC API key. Get one at https://lewnpc.com */
+    apiKey: string;
+    /**
+     * API base URL. Defaults to https://api.lewnpc.com/v1
+     * Override for local development or self-hosted deployments.
+     */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+}
+declare class LewNPCError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+declare class LewNPCAuthError extends LewNPCError {
+    constructor();
+}
+declare class LewNPCNotFoundError extends LewNPCError {
+    constructor(resource: string);
+}
+declare class LewNPCRateLimitError extends LewNPCError {
+    readonly retryAfter: number;
+    constructor(retryAfter?: number);
+}
+
+declare class LewNPC {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: LewNPCConfig);
+    private request;
+    /**
+     * Create a new NPC with a personality profile.
+     *
+     * @example
+     * const edric = await client.createNPC({
+     *   id: "edric_blacksmith",
+     *   role: "Village blacksmith and veteran of the Northern War",
+     *   backstory: "Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.",
+     *   traits: {
+     *     openness: 0.3,
+     *     conscientiousness: 0.8,
+     *     extraversion: 0.5,
+     *     agreeableness: 0.7,
+     *     neuroticism: 0.2,
+     *   },
+     * });
+     */
+    createNPC(params: CreateNPCParams): Promise<NPC>;
+    /**
+     * Retrieve an existing NPC by ID.
+     */
+    getNPC(npcId: string): Promise<NPC>;
+    /**
+     * List all NPCs in your account.
+     */
+    listNPCs(): Promise<NPC[]>;
+    /**
+     * Delete an NPC and all associated memories.
+     * This action is permanent.
+     */
+    deleteNPC(npcId: string): Promise<void>;
+    /**
+     * Send a message to an NPC and get a personality-consistent, memory-grounded response.
+     *
+     * The NPC remembers every interaction with each player_id across sessions.
+     *
+     * @example
+     * const response = await client.message({
+     *   npc_id: "edric_blacksmith",
+     *   player_id: "player_7f2a",
+     *   message: "I need a sword for the northern pass.",
+     * });
+     *
+     * console.log(response.text);
+     * // "The northern pass? That route's been closed since the avalanche..."
+     *
+     * console.log(response.emotion);
+     * // "concerned"
+     *
+     * console.log(response.memory_delta);
+     * // ["Player intends to travel the northern pass", "Player may not know about the avalanche"]
+     */
+    message(params: MessageParams): Promise<MessageResponse>;
+    /**
+     * List all memories an NPC holds for a specific player.
+     */
+    listMemories(params: ListMemoriesParams): Promise<ListMemoriesResponse>;
+    /**
+     * Reset all memories an NPC holds for a specific player.
+     * The NPC will treat subsequent messages from this player as a first meeting.
+     */
+    resetMemory(params: ResetMemoryParams): Promise<void>;
+}
+
+export { type BigFiveTraits, type CreateNPCParams, LewNPC, LewNPCAuthError, type LewNPCConfig, LewNPCError, LewNPCNotFoundError, LewNPCRateLimitError, type ListMemoriesParams, type ListMemoriesResponse, type Memory, type MessageParams, type MessageResponse, type NPC, type ResetMemoryParams };

package/dist/index.js

@@ -0,0 +1,215 @@
+'use strict';
+
+// src/types.ts
+var LewNPCError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "LewNPCError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var LewNPCAuthError = class extends LewNPCError {
+  constructor() {
+    super("Invalid API key. Get one at https://lewnpc.com", 401, "UNAUTHORIZED");
+    this.name = "LewNPCAuthError";
+  }
+};
+var LewNPCNotFoundError = class extends LewNPCError {
+  constructor(resource) {
+    super(`${resource} not found.`, 404, "NOT_FOUND");
+    this.name = "LewNPCNotFoundError";
+  }
+};
+var LewNPCRateLimitError = class extends LewNPCError {
+  constructor(retryAfter = 60) {
+    super(
+      `Rate limit exceeded. Retry after ${retryAfter} seconds. Upgrade at https://lewnpc.com/pricing`,
+      429,
+      "RATE_LIMITED"
+    );
+    this.name = "LewNPCRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.lewnpc.com/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "0.1.0";
+var LewNPC = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new LewNPCError(
+        "apiKey is required. Get one at https://lewnpc.com",
+        400,
+        "MISSING_API_KEY"
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+  // ─── Internal fetch ───────────────────────────────────────────────────────
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `lewnpc-node/${SDK_VERSION}`,
+          "X-SDK-Version": SDK_VERSION
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new LewNPCError(
+          `Request timed out after ${this.timeout}ms`,
+          408,
+          "TIMEOUT"
+        );
+      }
+      throw new LewNPCError(
+        `Network error: ${err.message}`,
+        0,
+        "NETWORK_ERROR"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.ok) {
+      if (response.status === 204) return void 0;
+      return response.json();
+    }
+    const status = response.status;
+    if (status === 401) throw new LewNPCAuthError();
+    if (status === 429) {
+      const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60", 10);
+      throw new LewNPCRateLimitError(retryAfter);
+    }
+    let errorBody = {};
+    try {
+      errorBody = await response.json();
+    } catch {
+    }
+    if (status === 404) {
+      throw new LewNPCNotFoundError(errorBody.error ?? "Resource");
+    }
+    throw new LewNPCError(
+      errorBody.error ?? `Request failed with status ${status}`,
+      status,
+      errorBody.code ?? "API_ERROR"
+    );
+  }
+  // ─── NPCs ─────────────────────────────────────────────────────────────────
+  /**
+   * Create a new NPC with a personality profile.
+   *
+   * @example
+   * const edric = await client.createNPC({
+   *   id: "edric_blacksmith",
+   *   role: "Village blacksmith and veteran of the Northern War",
+   *   backstory: "Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.",
+   *   traits: {
+   *     openness: 0.3,
+   *     conscientiousness: 0.8,
+   *     extraversion: 0.5,
+   *     agreeableness: 0.7,
+   *     neuroticism: 0.2,
+   *   },
+   * });
+   */
+  async createNPC(params) {
+    return this.request("POST", "/npcs", params);
+  }
+  /**
+   * Retrieve an existing NPC by ID.
+   */
+  async getNPC(npcId) {
+    return this.request("GET", `/npcs/${encodeURIComponent(npcId)}`);
+  }
+  /**
+   * List all NPCs in your account.
+   */
+  async listNPCs() {
+    return this.request("GET", "/npcs");
+  }
+  /**
+   * Delete an NPC and all associated memories.
+   * This action is permanent.
+   */
+  async deleteNPC(npcId) {
+    return this.request("DELETE", `/npcs/${encodeURIComponent(npcId)}`);
+  }
+  // ─── Messages ─────────────────────────────────────────────────────────────
+  /**
+   * Send a message to an NPC and get a personality-consistent, memory-grounded response.
+   *
+   * The NPC remembers every interaction with each player_id across sessions.
+   *
+   * @example
+   * const response = await client.message({
+   *   npc_id: "edric_blacksmith",
+   *   player_id: "player_7f2a",
+   *   message: "I need a sword for the northern pass.",
+   * });
+   *
+   * console.log(response.text);
+   * // "The northern pass? That route's been closed since the avalanche..."
+   *
+   * console.log(response.emotion);
+   * // "concerned"
+   *
+   * console.log(response.memory_delta);
+   * // ["Player intends to travel the northern pass", "Player may not know about the avalanche"]
+   */
+  async message(params) {
+    const { npc_id, ...body } = params;
+    return this.request(
+      "POST",
+      `/npcs/${encodeURIComponent(npc_id)}/message`,
+      body
+    );
+  }
+  // ─── Memory ───────────────────────────────────────────────────────────────
+  /**
+   * List all memories an NPC holds for a specific player.
+   */
+  async listMemories(params) {
+    const { npc_id, player_id, limit = 50, offset = 0 } = params;
+    const qs = new URLSearchParams({
+      player_id,
+      limit: String(limit),
+      offset: String(offset)
+    });
+    return this.request(
+      "GET",
+      `/npcs/${encodeURIComponent(npc_id)}/memories?${qs}`
+    );
+  }
+  /**
+   * Reset all memories an NPC holds for a specific player.
+   * The NPC will treat subsequent messages from this player as a first meeting.
+   */
+  async resetMemory(params) {
+    const { npc_id, player_id } = params;
+    return this.request(
+      "DELETE",
+      `/npcs/${encodeURIComponent(npc_id)}/memories?player_id=${encodeURIComponent(player_id)}`
+    );
+  }
+};
+
+exports.LewNPC = LewNPC;
+exports.LewNPCAuthError = LewNPCAuthError;
+exports.LewNPCError = LewNPCError;
+exports.LewNPCNotFoundError = LewNPCNotFoundError;
+exports.LewNPCRateLimitError = LewNPCRateLimitError;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ─── Personality ─────────────────────────────────────────────────────────────\n\n/**\n * Big Five (OCEAN) personality trait scores.\n * All values between 0.0 and 1.0.\n */\nexport interface BigFiveTraits {\n  /** Openness to experience: curiosity, creativity, novelty-seeking (0–1) */\n  openness: number;\n  /** Conscientiousness: organization, reliability, self-discipline (0–1) */\n  conscientiousness: number;\n  /** Extraversion: sociability, assertiveness, positive affect (0–1) */\n  extraversion: number;\n  /** Agreeableness: warmth, cooperation, empathy (0–1) */\n  agreeableness: number;\n  /** Neuroticism: anxiety, moodiness, emotional instability (0–1) */\n  neuroticism: number;\n}\n\n// ─── NPC ─────────────────────────────────────────────────────────────────────\n\nexport interface CreateNPCParams {\n  /** Unique identifier for this NPC. Must be unique within your account. */\n  id: string;\n  /** The character's role or title. Used as grounding context. */\n  role: string;\n  /** Optional backstory or character history. */\n  backstory?: string;\n  /** Big Five personality trait scores. */\n  traits: BigFiveTraits;\n  /**\n   * Optional seed memories to inject before any player interaction.\n   * Useful for characters with known history.\n   */\n  initial_memories?: string[];\n  /** Optional metadata object stored alongside the NPC. Not used by the model. */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface NPC {\n  id: string;\n  role: string;\n  backstory: string | null;\n  traits: BigFiveTraits;\n  memory_count: number;\n  created_at: string;\n  updated_at: string;\n  metadata: Record<string, unknown>;\n}\n\n// ─── Messages ────────────────────────────────────────────────────────────────\n\nexport interface MessageParams {\n  /** ID of the NPC to message. */\n  npc_id: string;\n  /**\n   * Identifier for the player sending the message.\n   * The NPC maintains separate memory per player_id.\n   */\n  player_id: string;\n  /** The player's message text. */\n  message: string;\n  /**\n   * Optional context to inject for this turn only.\n   * Useful for in-game events (e.g. \"The player has just defeated the boss\").\n   */\n  context?: string;\n  /** Sampling temperature. Default: 0.7 */\n  temperature?: number;\n  /** Maximum tokens for the response. Default: 512 */\n  max_tokens?: number;\n}\n\nexport interface MessageResponse {\n  /** The NPC's dialogue response. */\n  text: string;\n  /**\n   * The NPC's current emotional state.\n   * Examples: \"neutral\", \"warm\", \"concerned\", \"suspicious\", \"nostalgic\", \"amused\"\n   */\n  emotion: string;\n  /**\n   * Structured list of what the NPC learned or remembered from this interaction.\n   * Returned as an array of concise memory strings.\n   * Store these if you want to render them in-game.\n   */\n  memory_delta: string[];\n  /** Total number of memories this NPC holds for this player_id. */\n  memory_count: number;\n  /** Actual inference latency in milliseconds. */\n  latency_ms: number;\n  /** Model version used for this response. */\n  model: string;\n}\n\n// ─── Memory ──────────────────────────────────────────────────────────────────\n\nexport interface Memory {\n  id: string;\n  player_id: string;\n  content: string;\n  turn: number;\n  created_at: string;\n}\n\nexport interface ListMemoriesParams {\n  npc_id: string;\n  player_id: string;\n  limit?: number;\n  offset?: number;\n}\n\nexport interface ListMemoriesResponse {\n  memories: Memory[];\n  total: number;\n  player_id: string;\n}\n\nexport interface ResetMemoryParams {\n  npc_id: string;\n  player_id: string;\n}\n\n// ─── Client Config ───────────────────────────────────────────────────────────\n\nexport interface LewNPCConfig {\n  /** Your LewNPC API key. Get one at https://lewnpc.com */\n  apiKey: string;\n  /**\n   * API base URL. Defaults to https://api.lewnpc.com/v1\n   * Override for local development or self-hosted deployments.\n   */\n  baseUrl?: string;\n  /** Request timeout in milliseconds. Default: 30000 */\n  timeout?: number;\n}\n\n// ─── Errors ──────────────────────────────────────────────────────────────────\n\nexport interface LewNPCErrorResponse {\n  error: string;\n  code: string;\n  status: number;\n}\n\nexport class LewNPCError extends Error {\n  readonly status: number;\n  readonly code: string;\n\n  constructor(message: string, status: number, code: string) {\n    super(message);\n    this.name = \"LewNPCError\";\n    this.status = status;\n    this.code = code;\n  }\n}\n\nexport class LewNPCAuthError extends LewNPCError {\n  constructor() {\n    super(\"Invalid API key. Get one at https://lewnpc.com\", 401, \"UNAUTHORIZED\");\n    this.name = \"LewNPCAuthError\";\n  }\n}\n\nexport class LewNPCNotFoundError extends LewNPCError {\n  constructor(resource: string) {\n    super(`${resource} not found.`, 404, \"NOT_FOUND\");\n    this.name = \"LewNPCNotFoundError\";\n  }\n}\n\nexport class LewNPCRateLimitError extends LewNPCError {\n  readonly retryAfter: number;\n\n  constructor(retryAfter = 60) {\n    super(\n      `Rate limit exceeded. Retry after ${retryAfter} seconds. Upgrade at https://lewnpc.com/pricing`,\n      429,\n      \"RATE_LIMITED\"\n    );\n    this.name = \"LewNPCRateLimitError\";\n    this.retryAfter = retryAfter;\n  }\n}\n","import {\n  LewNPCConfig,\n  CreateNPCParams,\n  NPC,\n  MessageParams,\n  MessageResponse,\n  ListMemoriesParams,\n  ListMemoriesResponse,\n  ResetMemoryParams,\n  LewNPCError,\n  LewNPCAuthError,\n  LewNPCNotFoundError,\n  LewNPCRateLimitError,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.lewnpc.com/v1\";\nconst DEFAULT_TIMEOUT = 30_000;\nconst SDK_VERSION = \"0.1.0\";\n\nexport class LewNPC {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly timeout: number;\n\n  constructor(config: LewNPCConfig) {\n    if (!config.apiKey) {\n      throw new LewNPCError(\n        \"apiKey is required. Get one at https://lewnpc.com\",\n        400,\n        \"MISSING_API_KEY\"\n      );\n    }\n    this.apiKey = config.apiKey;\n    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, \"\");\n    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;\n  }\n\n  // ─── Internal fetch ───────────────────────────────────────────────────────\n\n  private async request<T>(\n    method: \"GET\" | \"POST\" | \"DELETE\",\n    path: string,\n    body?: unknown\n  ): Promise<T> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    let response: Response;\n    try {\n      response = await fetch(`${this.baseUrl}${path}`, {\n        method,\n        headers: {\n          \"Authorization\": `Bearer ${this.apiKey}`,\n          \"Content-Type\": \"application/json\",\n          \"User-Agent\": `lewnpc-node/${SDK_VERSION}`,\n          \"X-SDK-Version\": SDK_VERSION,\n        },\n        body: body !== undefined ? JSON.stringify(body) : undefined,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      if ((err as Error).name === \"AbortError\") {\n        throw new LewNPCError(\n          `Request timed out after ${this.timeout}ms`,\n          408,\n          \"TIMEOUT\"\n        );\n      }\n      throw new LewNPCError(\n        `Network error: ${(err as Error).message}`,\n        0,\n        \"NETWORK_ERROR\"\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (response.ok) {\n      if (response.status === 204) return undefined as T;\n      return response.json() as Promise<T>;\n    }\n\n    // Error handling\n    const status = response.status;\n\n    if (status === 401) throw new LewNPCAuthError();\n    if (status === 429) {\n      const retryAfter = parseInt(response.headers.get(\"Retry-After\") ?? \"60\", 10);\n      throw new LewNPCRateLimitError(retryAfter);\n    }\n\n    let errorBody: { error?: string; code?: string } = {};\n    try { errorBody = await response.json() as { error?: string; code?: string }; } catch { /* ignore parse errors */ }\n\n    if (status === 404) {\n      throw new LewNPCNotFoundError(errorBody.error ?? \"Resource\");\n    }\n\n    throw new LewNPCError(\n      errorBody.error ?? `Request failed with status ${status}`,\n      status,\n      errorBody.code ?? \"API_ERROR\"\n    );\n  }\n\n  // ─── NPCs ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Create a new NPC with a personality profile.\n   *\n   * @example\n   * const edric = await client.createNPC({\n   *   id: \"edric_blacksmith\",\n   *   role: \"Village blacksmith and veteran of the Northern War\",\n   *   backstory: \"Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.\",\n   *   traits: {\n   *     openness: 0.3,\n   *     conscientiousness: 0.8,\n   *     extraversion: 0.5,\n   *     agreeableness: 0.7,\n   *     neuroticism: 0.2,\n   *   },\n   * });\n   */\n  async createNPC(params: CreateNPCParams): Promise<NPC> {\n    return this.request<NPC>(\"POST\", \"/npcs\", params);\n  }\n\n  /**\n   * Retrieve an existing NPC by ID.\n   */\n  async getNPC(npcId: string): Promise<NPC> {\n    return this.request<NPC>(\"GET\", `/npcs/${encodeURIComponent(npcId)}`);\n  }\n\n  /**\n   * List all NPCs in your account.\n   */\n  async listNPCs(): Promise<NPC[]> {\n    return this.request<NPC[]>(\"GET\", \"/npcs\");\n  }\n\n  /**\n   * Delete an NPC and all associated memories.\n   * This action is permanent.\n   */\n  async deleteNPC(npcId: string): Promise<void> {\n    return this.request<void>(\"DELETE\", `/npcs/${encodeURIComponent(npcId)}`);\n  }\n\n  // ─── Messages ─────────────────────────────────────────────────────────────\n\n  /**\n   * Send a message to an NPC and get a personality-consistent, memory-grounded response.\n   *\n   * The NPC remembers every interaction with each player_id across sessions.\n   *\n   * @example\n   * const response = await client.message({\n   *   npc_id: \"edric_blacksmith\",\n   *   player_id: \"player_7f2a\",\n   *   message: \"I need a sword for the northern pass.\",\n   * });\n   *\n   * console.log(response.text);\n   * // \"The northern pass? That route's been closed since the avalanche...\"\n   *\n   * console.log(response.emotion);\n   * // \"concerned\"\n   *\n   * console.log(response.memory_delta);\n   * // [\"Player intends to travel the northern pass\", \"Player may not know about the avalanche\"]\n   */\n  async message(params: MessageParams): Promise<MessageResponse> {\n    const { npc_id, ...body } = params;\n    return this.request<MessageResponse>(\n      \"POST\",\n      `/npcs/${encodeURIComponent(npc_id)}/message`,\n      body\n    );\n  }\n\n  // ─── Memory ───────────────────────────────────────────────────────────────\n\n  /**\n   * List all memories an NPC holds for a specific player.\n   */\n  async listMemories(params: ListMemoriesParams): Promise<ListMemoriesResponse> {\n    const { npc_id, player_id, limit = 50, offset = 0 } = params;\n    const qs = new URLSearchParams({\n      player_id,\n      limit: String(limit),\n      offset: String(offset),\n    });\n    return this.request<ListMemoriesResponse>(\n      \"GET\",\n      `/npcs/${encodeURIComponent(npc_id)}/memories?${qs}`\n    );\n  }\n\n  /**\n   * Reset all memories an NPC holds for a specific player.\n   * The NPC will treat subsequent messages from this player as a first meeting.\n   */\n  async resetMemory(params: ResetMemoryParams): Promise<void> {\n    const { npc_id, player_id } = params;\n    return this.request<void>(\n      \"DELETE\",\n      `/npcs/${encodeURIComponent(npc_id)}/memories?player_id=${encodeURIComponent(player_id)}`\n    );\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,209 @@
+// src/types.ts
+var LewNPCError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "LewNPCError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var LewNPCAuthError = class extends LewNPCError {
+  constructor() {
+    super("Invalid API key. Get one at https://lewnpc.com", 401, "UNAUTHORIZED");
+    this.name = "LewNPCAuthError";
+  }
+};
+var LewNPCNotFoundError = class extends LewNPCError {
+  constructor(resource) {
+    super(`${resource} not found.`, 404, "NOT_FOUND");
+    this.name = "LewNPCNotFoundError";
+  }
+};
+var LewNPCRateLimitError = class extends LewNPCError {
+  constructor(retryAfter = 60) {
+    super(
+      `Rate limit exceeded. Retry after ${retryAfter} seconds. Upgrade at https://lewnpc.com/pricing`,
+      429,
+      "RATE_LIMITED"
+    );
+    this.name = "LewNPCRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.lewnpc.com/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "0.1.0";
+var LewNPC = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new LewNPCError(
+        "apiKey is required. Get one at https://lewnpc.com",
+        400,
+        "MISSING_API_KEY"
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+  // ─── Internal fetch ───────────────────────────────────────────────────────
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `lewnpc-node/${SDK_VERSION}`,
+          "X-SDK-Version": SDK_VERSION
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new LewNPCError(
+          `Request timed out after ${this.timeout}ms`,
+          408,
+          "TIMEOUT"
+        );
+      }
+      throw new LewNPCError(
+        `Network error: ${err.message}`,
+        0,
+        "NETWORK_ERROR"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.ok) {
+      if (response.status === 204) return void 0;
+      return response.json();
+    }
+    const status = response.status;
+    if (status === 401) throw new LewNPCAuthError();
+    if (status === 429) {
+      const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60", 10);
+      throw new LewNPCRateLimitError(retryAfter);
+    }
+    let errorBody = {};
+    try {
+      errorBody = await response.json();
+    } catch {
+    }
+    if (status === 404) {
+      throw new LewNPCNotFoundError(errorBody.error ?? "Resource");
+    }
+    throw new LewNPCError(
+      errorBody.error ?? `Request failed with status ${status}`,
+      status,
+      errorBody.code ?? "API_ERROR"
+    );
+  }
+  // ─── NPCs ─────────────────────────────────────────────────────────────────
+  /**
+   * Create a new NPC with a personality profile.
+   *
+   * @example
+   * const edric = await client.createNPC({
+   *   id: "edric_blacksmith",
+   *   role: "Village blacksmith and veteran of the Northern War",
+   *   backstory: "Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.",
+   *   traits: {
+   *     openness: 0.3,
+   *     conscientiousness: 0.8,
+   *     extraversion: 0.5,
+   *     agreeableness: 0.7,
+   *     neuroticism: 0.2,
+   *   },
+   * });
+   */
+  async createNPC(params) {
+    return this.request("POST", "/npcs", params);
+  }
+  /**
+   * Retrieve an existing NPC by ID.
+   */
+  async getNPC(npcId) {
+    return this.request("GET", `/npcs/${encodeURIComponent(npcId)}`);
+  }
+  /**
+   * List all NPCs in your account.
+   */
+  async listNPCs() {
+    return this.request("GET", "/npcs");
+  }
+  /**
+   * Delete an NPC and all associated memories.
+   * This action is permanent.
+   */
+  async deleteNPC(npcId) {
+    return this.request("DELETE", `/npcs/${encodeURIComponent(npcId)}`);
+  }
+  // ─── Messages ─────────────────────────────────────────────────────────────
+  /**
+   * Send a message to an NPC and get a personality-consistent, memory-grounded response.
+   *
+   * The NPC remembers every interaction with each player_id across sessions.
+   *
+   * @example
+   * const response = await client.message({
+   *   npc_id: "edric_blacksmith",
+   *   player_id: "player_7f2a",
+   *   message: "I need a sword for the northern pass.",
+   * });
+   *
+   * console.log(response.text);
+   * // "The northern pass? That route's been closed since the avalanche..."
+   *
+   * console.log(response.emotion);
+   * // "concerned"
+   *
+   * console.log(response.memory_delta);
+   * // ["Player intends to travel the northern pass", "Player may not know about the avalanche"]
+   */
+  async message(params) {
+    const { npc_id, ...body } = params;
+    return this.request(
+      "POST",
+      `/npcs/${encodeURIComponent(npc_id)}/message`,
+      body
+    );
+  }
+  // ─── Memory ───────────────────────────────────────────────────────────────
+  /**
+   * List all memories an NPC holds for a specific player.
+   */
+  async listMemories(params) {
+    const { npc_id, player_id, limit = 50, offset = 0 } = params;
+    const qs = new URLSearchParams({
+      player_id,
+      limit: String(limit),
+      offset: String(offset)
+    });
+    return this.request(
+      "GET",
+      `/npcs/${encodeURIComponent(npc_id)}/memories?${qs}`
+    );
+  }
+  /**
+   * Reset all memories an NPC holds for a specific player.
+   * The NPC will treat subsequent messages from this player as a first meeting.
+   */
+  async resetMemory(params) {
+    const { npc_id, player_id } = params;
+    return this.request(
+      "DELETE",
+      `/npcs/${encodeURIComponent(npc_id)}/memories?player_id=${encodeURIComponent(player_id)}`
+    );
+  }
+};
+
+export { LewNPC, LewNPCAuthError, LewNPCError, LewNPCNotFoundError, LewNPCRateLimitError };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// ─── Personality ─────────────────────────────────────────────────────────────\n\n/**\n * Big Five (OCEAN) personality trait scores.\n * All values between 0.0 and 1.0.\n */\nexport interface BigFiveTraits {\n  /** Openness to experience: curiosity, creativity, novelty-seeking (0–1) */\n  openness: number;\n  /** Conscientiousness: organization, reliability, self-discipline (0–1) */\n  conscientiousness: number;\n  /** Extraversion: sociability, assertiveness, positive affect (0–1) */\n  extraversion: number;\n  /** Agreeableness: warmth, cooperation, empathy (0–1) */\n  agreeableness: number;\n  /** Neuroticism: anxiety, moodiness, emotional instability (0–1) */\n  neuroticism: number;\n}\n\n// ─── NPC ─────────────────────────────────────────────────────────────────────\n\nexport interface CreateNPCParams {\n  /** Unique identifier for this NPC. Must be unique within your account. */\n  id: string;\n  /** The character's role or title. Used as grounding context. */\n  role: string;\n  /** Optional backstory or character history. */\n  backstory?: string;\n  /** Big Five personality trait scores. */\n  traits: BigFiveTraits;\n  /**\n   * Optional seed memories to inject before any player interaction.\n   * Useful for characters with known history.\n   */\n  initial_memories?: string[];\n  /** Optional metadata object stored alongside the NPC. Not used by the model. */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface NPC {\n  id: string;\n  role: string;\n  backstory: string | null;\n  traits: BigFiveTraits;\n  memory_count: number;\n  created_at: string;\n  updated_at: string;\n  metadata: Record<string, unknown>;\n}\n\n// ─── Messages ────────────────────────────────────────────────────────────────\n\nexport interface MessageParams {\n  /** ID of the NPC to message. */\n  npc_id: string;\n  /**\n   * Identifier for the player sending the message.\n   * The NPC maintains separate memory per player_id.\n   */\n  player_id: string;\n  /** The player's message text. */\n  message: string;\n  /**\n   * Optional context to inject for this turn only.\n   * Useful for in-game events (e.g. \"The player has just defeated the boss\").\n   */\n  context?: string;\n  /** Sampling temperature. Default: 0.7 */\n  temperature?: number;\n  /** Maximum tokens for the response. Default: 512 */\n  max_tokens?: number;\n}\n\nexport interface MessageResponse {\n  /** The NPC's dialogue response. */\n  text: string;\n  /**\n   * The NPC's current emotional state.\n   * Examples: \"neutral\", \"warm\", \"concerned\", \"suspicious\", \"nostalgic\", \"amused\"\n   */\n  emotion: string;\n  /**\n   * Structured list of what the NPC learned or remembered from this interaction.\n   * Returned as an array of concise memory strings.\n   * Store these if you want to render them in-game.\n   */\n  memory_delta: string[];\n  /** Total number of memories this NPC holds for this player_id. */\n  memory_count: number;\n  /** Actual inference latency in milliseconds. */\n  latency_ms: number;\n  /** Model version used for this response. */\n  model: string;\n}\n\n// ─── Memory ──────────────────────────────────────────────────────────────────\n\nexport interface Memory {\n  id: string;\n  player_id: string;\n  content: string;\n  turn: number;\n  created_at: string;\n}\n\nexport interface ListMemoriesParams {\n  npc_id: string;\n  player_id: string;\n  limit?: number;\n  offset?: number;\n}\n\nexport interface ListMemoriesResponse {\n  memories: Memory[];\n  total: number;\n  player_id: string;\n}\n\nexport interface ResetMemoryParams {\n  npc_id: string;\n  player_id: string;\n}\n\n// ─── Client Config ───────────────────────────────────────────────────────────\n\nexport interface LewNPCConfig {\n  /** Your LewNPC API key. Get one at https://lewnpc.com */\n  apiKey: string;\n  /**\n   * API base URL. Defaults to https://api.lewnpc.com/v1\n   * Override for local development or self-hosted deployments.\n   */\n  baseUrl?: string;\n  /** Request timeout in milliseconds. Default: 30000 */\n  timeout?: number;\n}\n\n// ─── Errors ──────────────────────────────────────────────────────────────────\n\nexport interface LewNPCErrorResponse {\n  error: string;\n  code: string;\n  status: number;\n}\n\nexport class LewNPCError extends Error {\n  readonly status: number;\n  readonly code: string;\n\n  constructor(message: string, status: number, code: string) {\n    super(message);\n    this.name = \"LewNPCError\";\n    this.status = status;\n    this.code = code;\n  }\n}\n\nexport class LewNPCAuthError extends LewNPCError {\n  constructor() {\n    super(\"Invalid API key. Get one at https://lewnpc.com\", 401, \"UNAUTHORIZED\");\n    this.name = \"LewNPCAuthError\";\n  }\n}\n\nexport class LewNPCNotFoundError extends LewNPCError {\n  constructor(resource: string) {\n    super(`${resource} not found.`, 404, \"NOT_FOUND\");\n    this.name = \"LewNPCNotFoundError\";\n  }\n}\n\nexport class LewNPCRateLimitError extends LewNPCError {\n  readonly retryAfter: number;\n\n  constructor(retryAfter = 60) {\n    super(\n      `Rate limit exceeded. Retry after ${retryAfter} seconds. Upgrade at https://lewnpc.com/pricing`,\n      429,\n      \"RATE_LIMITED\"\n    );\n    this.name = \"LewNPCRateLimitError\";\n    this.retryAfter = retryAfter;\n  }\n}\n","import {\n  LewNPCConfig,\n  CreateNPCParams,\n  NPC,\n  MessageParams,\n  MessageResponse,\n  ListMemoriesParams,\n  ListMemoriesResponse,\n  ResetMemoryParams,\n  LewNPCError,\n  LewNPCAuthError,\n  LewNPCNotFoundError,\n  LewNPCRateLimitError,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.lewnpc.com/v1\";\nconst DEFAULT_TIMEOUT = 30_000;\nconst SDK_VERSION = \"0.1.0\";\n\nexport class LewNPC {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly timeout: number;\n\n  constructor(config: LewNPCConfig) {\n    if (!config.apiKey) {\n      throw new LewNPCError(\n        \"apiKey is required. Get one at https://lewnpc.com\",\n        400,\n        \"MISSING_API_KEY\"\n      );\n    }\n    this.apiKey = config.apiKey;\n    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, \"\");\n    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;\n  }\n\n  // ─── Internal fetch ───────────────────────────────────────────────────────\n\n  private async request<T>(\n    method: \"GET\" | \"POST\" | \"DELETE\",\n    path: string,\n    body?: unknown\n  ): Promise<T> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    let response: Response;\n    try {\n      response = await fetch(`${this.baseUrl}${path}`, {\n        method,\n        headers: {\n          \"Authorization\": `Bearer ${this.apiKey}`,\n          \"Content-Type\": \"application/json\",\n          \"User-Agent\": `lewnpc-node/${SDK_VERSION}`,\n          \"X-SDK-Version\": SDK_VERSION,\n        },\n        body: body !== undefined ? JSON.stringify(body) : undefined,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      if ((err as Error).name === \"AbortError\") {\n        throw new LewNPCError(\n          `Request timed out after ${this.timeout}ms`,\n          408,\n          \"TIMEOUT\"\n        );\n      }\n      throw new LewNPCError(\n        `Network error: ${(err as Error).message}`,\n        0,\n        \"NETWORK_ERROR\"\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (response.ok) {\n      if (response.status === 204) return undefined as T;\n      return response.json() as Promise<T>;\n    }\n\n    // Error handling\n    const status = response.status;\n\n    if (status === 401) throw new LewNPCAuthError();\n    if (status === 429) {\n      const retryAfter = parseInt(response.headers.get(\"Retry-After\") ?? \"60\", 10);\n      throw new LewNPCRateLimitError(retryAfter);\n    }\n\n    let errorBody: { error?: string; code?: string } = {};\n    try { errorBody = await response.json() as { error?: string; code?: string }; } catch { /* ignore parse errors */ }\n\n    if (status === 404) {\n      throw new LewNPCNotFoundError(errorBody.error ?? \"Resource\");\n    }\n\n    throw new LewNPCError(\n      errorBody.error ?? `Request failed with status ${status}`,\n      status,\n      errorBody.code ?? \"API_ERROR\"\n    );\n  }\n\n  // ─── NPCs ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Create a new NPC with a personality profile.\n   *\n   * @example\n   * const edric = await client.createNPC({\n   *   id: \"edric_blacksmith\",\n   *   role: \"Village blacksmith and veteran of the Northern War\",\n   *   backstory: \"Lost his partner Maren to an avalanche. Quiet but warm once trust is earned.\",\n   *   traits: {\n   *     openness: 0.3,\n   *     conscientiousness: 0.8,\n   *     extraversion: 0.5,\n   *     agreeableness: 0.7,\n   *     neuroticism: 0.2,\n   *   },\n   * });\n   */\n  async createNPC(params: CreateNPCParams): Promise<NPC> {\n    return this.request<NPC>(\"POST\", \"/npcs\", params);\n  }\n\n  /**\n   * Retrieve an existing NPC by ID.\n   */\n  async getNPC(npcId: string): Promise<NPC> {\n    return this.request<NPC>(\"GET\", `/npcs/${encodeURIComponent(npcId)}`);\n  }\n\n  /**\n   * List all NPCs in your account.\n   */\n  async listNPCs(): Promise<NPC[]> {\n    return this.request<NPC[]>(\"GET\", \"/npcs\");\n  }\n\n  /**\n   * Delete an NPC and all associated memories.\n   * This action is permanent.\n   */\n  async deleteNPC(npcId: string): Promise<void> {\n    return this.request<void>(\"DELETE\", `/npcs/${encodeURIComponent(npcId)}`);\n  }\n\n  // ─── Messages ─────────────────────────────────────────────────────────────\n\n  /**\n   * Send a message to an NPC and get a personality-consistent, memory-grounded response.\n   *\n   * The NPC remembers every interaction with each player_id across sessions.\n   *\n   * @example\n   * const response = await client.message({\n   *   npc_id: \"edric_blacksmith\",\n   *   player_id: \"player_7f2a\",\n   *   message: \"I need a sword for the northern pass.\",\n   * });\n   *\n   * console.log(response.text);\n   * // \"The northern pass? That route's been closed since the avalanche...\"\n   *\n   * console.log(response.emotion);\n   * // \"concerned\"\n   *\n   * console.log(response.memory_delta);\n   * // [\"Player intends to travel the northern pass\", \"Player may not know about the avalanche\"]\n   */\n  async message(params: MessageParams): Promise<MessageResponse> {\n    const { npc_id, ...body } = params;\n    return this.request<MessageResponse>(\n      \"POST\",\n      `/npcs/${encodeURIComponent(npc_id)}/message`,\n      body\n    );\n  }\n\n  // ─── Memory ───────────────────────────────────────────────────────────────\n\n  /**\n   * List all memories an NPC holds for a specific player.\n   */\n  async listMemories(params: ListMemoriesParams): Promise<ListMemoriesResponse> {\n    const { npc_id, player_id, limit = 50, offset = 0 } = params;\n    const qs = new URLSearchParams({\n      player_id,\n      limit: String(limit),\n      offset: String(offset),\n    });\n    return this.request<ListMemoriesResponse>(\n      \"GET\",\n      `/npcs/${encodeURIComponent(npc_id)}/memories?${qs}`\n    );\n  }\n\n  /**\n   * Reset all memories an NPC holds for a specific player.\n   * The NPC will treat subsequent messages from this player as a first meeting.\n   */\n  async resetMemory(params: ResetMemoryParams): Promise<void> {\n    const { npc_id, player_id } = params;\n    return this.request<void>(\n      \"DELETE\",\n      `/npcs/${encodeURIComponent(npc_id)}/memories?player_id=${encodeURIComponent(player_id)}`\n    );\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "lewnpc",
+  "version": "0.1.0",
+  "description": "Persistent memory and stable personality for game NPCs. One API. Lewis underneath.",
+  "keywords": ["npc", "game-development", "ai", "persistent-memory", "personality", "dialogue", "rpg"],
+  "homepage": "https://lewnpc.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swarmgram/lewnpc"
+  },
+  "license": "MIT",
+  "author": "Swarmgram <hello@lewnpc.com>",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}