@sharpee/if-services 0.9.60-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Cornelson
+
+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,48 @@
+# @sharpee/if-services
+
+Runtime service interfaces for the Sharpee Interactive Fiction Platform.
+
+## Purpose
+
+This package provides runtime service interfaces that need access to the world model. It separates these interfaces from the pure domain package (`@sharpee/if-domain`) to maintain clean architectural boundaries.
+
+## Contents
+
+- **TextService**: Interface for text generation services that process game events and produce formatted output
+- (Future) Audio service interfaces
+- (Future) Graphics service interfaces  
+- (Future) Analytics service interfaces
+
+## Architecture
+
+The if-services package acts as a bridge between:
+- The pure domain model (`@sharpee/if-domain`)
+- The world model (`@sharpee/world-model`)
+- Runtime implementations that need both
+
+This pattern ensures that domain packages remain pure and don't have runtime dependencies, while still providing typed interfaces for runtime services.
+
+## Usage
+
+```typescript
+import { TextService, TextServiceContext } from '@sharpee/if-services';
+
+// Implement the TextService interface
+class MyTextService implements TextService {
+  initialize(context: TextServiceContext): void {
+    // Initialize with game context
+  }
+  
+  processTurn(): TextOutput {
+    // Generate output for the current turn
+  }
+  
+  // ... other methods
+}
+```
+
+## Dependencies
+
+- `@sharpee/core`: Core event system
+- `@sharpee/if-domain`: Domain types and contracts
+- `@sharpee/world-model`: World state management

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @sharpee/if-services - Runtime service interfaces for Sharpee Interactive Fiction Platform
+ *
+ * This package contains interfaces for runtime services that need access to
+ * the world model, separating them from the pure domain package.
+ */
+export * from './perception-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * @sharpee/if-services - Runtime service interfaces for Sharpee Interactive Fiction Platform
+ *
+ * This package contains interfaces for runtime services that need access to
+ * the world model, separating them from the pure domain package.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Perception service interfaces
+__exportStar(require("./perception-service"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,gCAAgC;AAChC,uDAAqC"}

package/dist/perception-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Perception service interface for Interactive Fiction
+ *
+ * Perception services filter events based on what the player can perceive.
+ * They sit between action execution and the text service, transforming
+ * events that describe things the player cannot perceive (due to darkness,
+ * blindness, etc.) into appropriate alternative events.
+ *
+ * @see ADR-069 Perception-Based Event Filtering
+ */
+import type { ISemanticEvent } from '@sharpee/core';
+import type { IFEntity, IWorldModel } from '@sharpee/world-model';
+/**
+ * Sense types for perception checks
+ */
+export type Sense = 'sight' | 'hearing' | 'smell' | 'touch';
+/**
+ * Reasons why perception might be blocked
+ */
+export type PerceptionBlockReason = 'darkness' | 'blindness' | 'blindfolded' | 'unknown';
+/**
+ * Data for a perception-blocked event
+ */
+export interface PerceptionBlockedData {
+    /** The original event type that was blocked */
+    originalType: string;
+    /** Why perception was blocked */
+    reason: PerceptionBlockReason;
+    /** Which sense was blocked */
+    sense: Sense;
+    /** Original event data (for debugging/logging) */
+    originalData?: unknown;
+}
+/**
+ * Service interface for filtering events based on player perception.
+ *
+ * The perception service determines what the player can perceive based on:
+ * - Environmental factors (darkness, noise, etc.)
+ * - Actor state (blindness, deafness, etc.)
+ * - Equipment (blindfold, earplugs, etc.)
+ *
+ * Events that describe things the player cannot perceive are transformed
+ * or removed before being sent to the text service.
+ *
+ * @see ADR-069 Perception-Based Event Filtering
+ */
+export interface IPerceptionService {
+    /**
+     * Filter events based on what the actor can perceive.
+     *
+     * @param events - Raw events from action execution
+     * @param actor - The perceiving actor (usually the player)
+     * @param world - The world model for checking environment state
+     * @returns Filtered/transformed events based on perception
+     */
+    filterEvents(events: ISemanticEvent[], actor: IFEntity, world: IWorldModel): ISemanticEvent[];
+    /**
+     * Check if an actor can perceive using a specific sense.
+     *
+     * @param actor - The perceiving actor
+     * @param location - The location being perceived
+     * @param world - The world model
+     * @param sense - Which sense to check (defaults to 'sight')
+     * @returns true if the actor can perceive, false otherwise
+     */
+    canPerceive(actor: IFEntity, location: IFEntity, world: IWorldModel, sense: Sense): boolean;
+}
+//# sourceMappingURL=perception-service.d.ts.map

package/dist/perception-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perception-service.d.ts","sourceRoot":"","sources":["../src/perception-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,WAAW,GACX,aAAa,GACb,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,kDAAkD;IAClD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,YAAY,CACV,MAAM,EAAE,cAAc,EAAE,EACxB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,WAAW,GACjB,cAAc,EAAE,CAAC;IAEpB;;;;;;;;OAQG;IACH,WAAW,CACT,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC;CACZ"}

package/dist/perception-service.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Perception service interface for Interactive Fiction
+ *
+ * Perception services filter events based on what the player can perceive.
+ * They sit between action execution and the text service, transforming
+ * events that describe things the player cannot perceive (due to darkness,
+ * blindness, etc.) into appropriate alternative events.
+ *
+ * @see ADR-069 Perception-Based Event Filtering
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=perception-service.js.map

package/dist/perception-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perception-service.js","sourceRoot":"","sources":["../src/perception-service.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/text-service.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Text service interface for Interactive Fiction
+ *
+ * Text services are responsible for generating output after each turn.
+ * They have access to the game context and can query events, entities,
+ * and spatial relationships to build appropriate output.
+ */
+import type { ISemanticEvent } from '@sharpee/core';
+import type { LanguageProvider } from '@sharpee/if-domain';
+import type { WorldModel, IFEntity } from '@sharpee/world-model';
+/**
+ * Game context provided to text service
+ */
+export interface TextServiceContext {
+    /**
+     * Current turn number
+     */
+    currentTurn: number;
+    /**
+     * Get events for the current turn
+     */
+    getCurrentTurnEvents(): ISemanticEvent[];
+    /**
+     * Get events by type for the current turn
+     */
+    getEventsByType(type: string): ISemanticEvent[];
+    /**
+     * Get all events (full history)
+     */
+    getAllEvents(): ISemanticEvent[];
+    /**
+     * Access to world model for entity queries
+     */
+    world: WorldModel;
+    /**
+     * Get the player entity
+     */
+    getPlayer(): IFEntity;
+    /**
+     * Get entities in a location
+     */
+    getContents(locationId: string): IFEntity[];
+    /**
+     * Get location of an entity
+     */
+    getLocation(entityId: string): string | null;
+    /**
+     * Get platform events for the current turn (optional)
+     * These are debug/system events from parser, world model, etc.
+     */
+    getPlatformEvents?(): ISemanticEvent[];
+}
+/**
+ * Output format for different client types
+ */
+export type TextOutput = string | TextOutputJSON | TextOutputChanneled;
+/**
+ * JSON output for web/rich clients
+ */
+export interface TextOutputJSON {
+    type: 'json';
+    main: string;
+    metadata?: {
+        turn: number;
+        location?: string;
+        score?: number;
+        moves?: number;
+    };
+    sections?: {
+        room?: string;
+        inventory?: string[];
+        exits?: string[];
+        objects?: string[];
+    };
+    styling?: {
+        roomName?: string;
+        important?: string[];
+    };
+}
+/**
+ * Multi-channel output
+ */
+export interface TextOutputChanneled {
+    type: 'channeled';
+    channels: Map<string, string>;
+}
+/**
+ * Text service interface
+ */
+export interface TextService {
+    /**
+     * Initialize with context
+     */
+    initialize(context: TextServiceContext): void;
+    /**
+     * Process the current turn and generate output
+     * @returns The formatted output
+     */
+    processTurn(): TextOutput;
+    /**
+     * Set the language provider for template resolution
+     * @param provider The language provider
+     */
+    setLanguageProvider(provider: LanguageProvider): void;
+    /**
+     * Get the current language provider
+     * @returns The language provider or null if not set
+     */
+    getLanguageProvider(): LanguageProvider | null;
+    /**
+     * Set output format preference
+     * @param format The desired output format
+     */
+    setOutputFormat?(format: 'text' | 'json' | 'channeled'): void;
+}
+/**
+ * Text service configuration
+ */
+export interface TextServiceConfig {
+    /**
+     * Output format (defaults to 'text')
+     */
+    outputFormat?: 'text' | 'json' | 'channeled';
+    /**
+     * Whether to include debug information in output
+     */
+    debug?: boolean;
+    /**
+     * Custom event processors by event type
+     */
+    processors?: Record<string, (event: ISemanticEvent, context: TextServiceContext) => string | null>;
+    /**
+     * Channels to use for channeled output
+     */
+    channels?: string[];
+}
+//# sourceMappingURL=text-service.d.ts.map

package/dist/text-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-service.d.ts","sourceRoot":"","sources":["../src/text-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,oBAAoB,IAAI,cAAc,EAAE,CAAC;IAEzC;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAEhD;;OAEG;IACH,YAAY,IAAI,cAAc,EAAE,CAAC;IAEjC;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC;IAE5C;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,iBAAiB,CAAC,IAAI,cAAc,EAAE,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,cAAc,GACd,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAE9C;;;OAGG;IACH,WAAW,IAAI,UAAU,CAAC;IAE1B;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtD;;;OAGG;IACH,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAE/C;;;OAGG;IACH,eAAe,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;IAE7C;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,kBAAkB,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnG;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/dist/text-service.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Text service interface for Interactive Fiction
+ *
+ * Text services are responsible for generating output after each turn.
+ * They have access to the game context and can query events, entities,
+ * and spatial relationships to build appropriate output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=text-service.js.map

package/dist/text-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-service.js","sourceRoot":"","sources":["../src/text-service.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sharpee/if-services",
+  "version": "0.9.60-beta",
+  "description": "Runtime service interfaces for Sharpee Interactive Fiction Platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@sharpee/world-model": "0.9.60-beta",
+    "@sharpee/core": "0.9.60-beta",
+    "@sharpee/if-domain": "0.9.60-beta"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "sharpee",
+    "interactive-fiction",
+    "if",
+    "services",
+    "runtime"
+  ],
+  "author": "Sharpee Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "jest"
+  }
+}