briyah 1.0.9 → 1.1.1

package/README.md

@@ -94,7 +94,7 @@ interface BriyahConfigOptions {
 
 **Optional:**
 - `STARTING_BALANCE` - Starting balance for new users (e.g., "10.00")
-- `SERVER_DATA_PATH` - Global default data path (overridden by constructor `dataPath`)
+- `BRIYAH_DATA_PATH` - Global default data path (overridden by constructor `dataPath`)
 - `USER_SERVICE_CACHE_TIMEOUT_MINUTES` - Cache timeout (overridden by constructor option)
 
 ### Logging
@@ -205,6 +205,8 @@ The AppService provides full access to Briyah functionality.
 const agent = appService.createAgent(provider, name, nickname, description, model);
 const agents = await appService.listAgents();
 await appService.deleteAgent(agentId);
+await appService.reloadAgent(agentId);              // Clear conversation history (keeps any prior summary)
+await appService.compactAgentConversation(agentId); // Summarize history into a single message
 
 // Room Management
 const room = await appService.createRoom(name, goal, agentIds);
@@ -352,6 +354,115 @@ const messages = await appService.getRoomMessages(room.roomId);
 console.log(`Messages: ${messages.messages.length}`);
 ```
 
+### Example 6: Story Message Emitter
+
+The story message emitter delivers real-time events during gameplay. Subscribe to it after creating the story but before the first player turn, so no events are missed.
+
+```typescript
+import type {
+    StoryStateEvent,
+    StoryIntroduceCharacterEvent,
+    StoryProgressChapterEvent,
+    StoryErrorEvent,
+} from 'briyah';
+
+const app = briyah.getAppService('user-123');
+
+const story = await app.createStory(
+    'The Lost Kingdom',
+    'A medieval fantasy where ancient ruins hold a terrible secret',
+    'A disgraced knight seeking redemption'
+);
+
+const emitter = app.getStoryMessageEmitter(story.id);
+
+// Fires after every turn with the full updated game state.
+emitter.on('story-state', async (event: StoryStateEvent) => {
+    const { state } = event;
+    console.log('Latest message:', state.latestRoomMessage?.content);
+
+    // Detect the player's turn by comparing speaker names.
+    // Do NOT use state.humanPrompt for this — it is a UI display string,
+    // not a reliable turn indicator.
+    if (state.currentSpeaker === state.userAgentName) {
+        const input = await promptPlayer(state.humanPrompt);
+        await app.respondToStory(story.id, input);
+    }
+});
+
+// Fires when the narrator wants to introduce a new character.
+// The host app should present this to the player before acting.
+// Accept by calling introduceCharacterToStory, or decline with declineCharacter.
+emitter.on('suggest-introduce-character', async (event: StoryIntroduceCharacterEvent) => {
+    const accept = await askPlayer(`Add ${event.characterName} to the story?`);
+    if (accept) {
+        await app.introduceCharacterToStory(story.id, event.characterName!, '', undefined, true);
+    } else {
+        await app.declineCharacter(story.id, event.characterName!);
+    }
+});
+
+// Fires when the narrator wants to advance to the next chapter.
+// Call progressStory to accept. Ignoring the event stays in the current chapter —
+// there is no explicit rejection call.
+emitter.on('suggest-progress-chapter', async (_event: StoryProgressChapterEvent) => {
+    const accept = await askPlayer('The narrator suggests ending this chapter. Continue?');
+    if (accept) {
+        await app.progressStory(story.id);
+    }
+});
+
+// Fires on fatal errors during room processing.
+// Named 'story-error' rather than 'error' to avoid Node.js throwing when no
+// listener is attached.
+emitter.on('story-error', (event: StoryErrorEvent) => {
+    if (event.errorType === 'InsufficientBalanceError') {
+        console.error('Out of credits:', event.message);
+    } else {
+        console.error(`Story error [${event.errorType}]:`, event.message);
+    }
+});
+```
+
+### Example 7: Recording Payments and Managing Balance
+
+Briyah does not process payments itself — your application handles the payment provider interaction. Once a payment is confirmed, use `AppService` to record the transaction, credit the user's balance, and restart any stories that stalled due to insufficient funds.
+
+```typescript
+const app = briyah.getAppService(userId);
+
+// --- When your payment provider initiates a charge ---
+// Record it as pending so the transaction log stays consistent.
+await app.recordTransaction(amount, paymentIntentId, 'pending');
+
+// --- When your payment provider webhook confirms success ---
+await app.updateTransactionStatus(paymentIntentId, 'succeeded');
+await app.addBalance(amount);
+
+// Resume any stories that paused mid-turn due to InsufficientBalanceError.
+await app.resumePausedStories();
+
+// --- When a payment fails or is cancelled ---
+await app.updateTransactionStatus(paymentIntentId, 'failed');
+
+// --- Querying balance and history ---
+const balance = app.getBalance();
+
+const { transactions, total } = await app.getTransactions(50, 0);
+
+const tx = await app.getTransactionByPaymentId(paymentIntentId);
+console.log(tx?.status); // 'pending' | 'succeeded' | 'failed' | 'cancelled'
+```
+
+To push real-time balance updates to a connected client (e.g. via SSE), subscribe to the balance emitter before crediting the user:
+
+```typescript
+const emitter = app.getBalanceMessageEmitter(userId);
+emitter.on('update', (newBalance: number) => {
+    // Push newBalance to the client
+});
+```
+
 ## Data Storage
 
 Briyah stores data in the following structure:

package/data/common/config/markup

@@ -0,0 +1 @@
+1.6219859999999993