@onlyworlds/sdk 2.0.1 → 2.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 OnlyWorlds
-
-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.
+MIT License
+
+Copyright (c) 2024-2025 OnlyWorlds
+
+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

@@ -1,13 +1,14 @@
 # OnlyWorlds TypeScript SDK
 
-Type-safe SDK for building applications with the OnlyWorlds API. Access all 22 element types with full TypeScript support.
+[![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A type-safe TypeScript SDK for building world-building applications with the OnlyWorlds API.
 
 ## Installation
 
 ```bash
 npm install @onlyworlds/sdk
-# or
-yarn add @onlyworlds/sdk
 ```
 
 ## Quick Start
@@ -15,248 +16,239 @@ yarn add @onlyworlds/sdk
 ```typescript
 import { OnlyWorldsClient } from '@onlyworlds/sdk';
 
-// Initialize the client
 const client = new OnlyWorldsClient({
   apiKey: 'your-api-key',
-  apiPin: 'your-api-pin'
+  apiPin: '1234',
+  baseUrl: 'https://onlyworlds.com'
 });
 
-// Create a character
-const character = await client.characters.create({
-  name: 'Aragorn',
-  description: 'Heir of Isildur',
-  location_id: 'uuid-of-location',
-  abilities_ids: ['uuid1', 'uuid2']
-});
+// Get your world (API keys are world-scoped)
+const world = await client.worlds.get();
 
-// List locations with filtering
-const locations = await client.locations.list({
-  search: 'tavern',
-  ordering: '-created_at',
-  limit: 10
+// Fetch characters (paginated)
+const characters = await client.characters.list();
+
+// Create a new location
+const location = await client.locations.create({
+  name: 'Dragon Peak',
+  description: 'A treacherous mountain peak where dragons nest',
+  supertype: 'mountain'
 });
-```
 
-## Features
+// Get a specific element
+const character = await client.characters.get('element-id');
 
-- 🎯 **Full TypeScript Support** - Complete type definitions for all 22 element types
-- 🔒 **Type Safety** - Separate input/output types handle the `_id`/`_ids` pattern automatically
-- 📦 **All Element Types** - Characters, Locations, Objects, Species, Events, and more
-- 🔗 **Relationship Handling** - Properly typed single and multi-link relationships
-- 🚀 **Simple API** - Intuitive methods for CRUD operations
-- 📄 **Auto-completion** - IDE support for all fields and methods
+// Update an element
+await client.characters.update('element-id', {
+  name: 'Updated Name'
+});
 
-## Element Types
+// Delete an element
+await client.characters.delete('element-id');
+```
 
-The SDK supports all 22 OnlyWorlds element types:
+## Features
 
-- **Beings**: Character, Creature, Collective, Family, Species
-- **Places**: Location, Zone, Map, Pin, Marker
-- **Things**: Object, Construct, Phenomenon
-- **Concepts**: Ability, Event, Institution, Language, Law, Narrative, Relation, Title, Trait
+- ✅ **Full Type Safety** - Complete TypeScript definitions for all 22 OnlyWorlds element types
+- ✅ **Auto-Generated Types** - Types synchronized with the latest OnlyWorlds schema
+- ✅ **CRUD Operations** - Create, read, update, and delete operations for all elements
+- ✅ **Token Management** - Built-in support for OnlyWorlds token rating system
+- ✅ **Branded Types** - Compile-time safety for element relationships
+- ✅ **Zero Runtime Overhead** - Type system has no runtime cost
+- ✅ **Modern ESM/CJS** - Supports both ES modules and CommonJS
 
 ## API Reference
 
-### Client Initialization
+### World Endpoint
+
+The `worlds` resource is special because API keys are world-scoped (one key = one world). The endpoint returns a single `World` object directly, not a paginated list.
 
 ```typescript
-import { OnlyWorldsClient } from '@onlyworlds/sdk';
+// Get your world
+const world = await client.worlds.get();
 
-const client = new OnlyWorldsClient({
-  apiKey: 'your-api-key',    // Required
-  apiPin: 'your-api-pin',    // Required
-  baseUrl: 'custom-url'      // Optional, defaults to onlyworlds.com
+// Update your world
+const updated = await client.worlds.update({
+  description: 'A dark fantasy realm'
 });
 ```
 
-### CRUD Operations
+**Note**: The `worlds` resource only has `get()` and `update()` methods (no `list()`, `create()`, or `delete()`) because API keys are world-scoped.
+
+### Element Endpoints
 
-All element types support the same operations:
+All other element types return paginated results:
 
 ```typescript
-// List with filtering
-const items = await client.characters.list({
-  search: 'hero',
-  ordering: 'name',
-  limit: 20,
-  offset: 0
+// List with pagination
+const response = await client.characters.list({
+  limit: 10,
+  offset: 0,
+  ordering: '-created_at',
+  search: 'dragon'
 });
 
-// Get single item
-const character = await client.characters.get('uuid');
+console.log(response.count);      // Total count
+console.log(response.results);    // Array of Characters
+console.log(response.next);       // URL for next page
+console.log(response.previous);   // URL for previous page
+```
 
-// Create new item
-const newChar = await client.characters.create({
-  name: 'Gandalf',
-  description: 'A wizard'
-});
+## Type-Safe Relationships
 
-// Update existing item
-const updated = await client.characters.update('uuid', {
-  description: 'A wizard, also known as Mithrandir'
-});
+```typescript
+import { ElementId, Character, Location } from '@onlyworlds/sdk';
 
-// Delete item
-await client.characters.delete('uuid');
+// Branded types ensure you can't mix up element IDs
+const locationId: ElementId<'Location'> = 'some-location-id';
+const character: Character = {
+  name: 'Aragorn',
+  location: locationId  // Type-safe!
+};
 ```
 
-### Working with Relationships
-
-The SDK handles OnlyWorlds' `_id`/`_ids` pattern automatically:
+## Token Management
 
-```typescript
-// Creating with relationships
-const character = await client.characters.create({
-  name: 'Frodo',
-  birthplace_id: 'location-uuid',        // Single relationship
-  abilities_ids: ['uuid1', 'uuid2'],     // Multi relationship
-  friends_ids: ['sam-uuid', 'merry-uuid']
-});
+OnlyWorlds provides a token rating system for tracking API usage and enabling AI-powered features. Users get a daily token allowance (default: 10,000 tokens) that resets every day.
 
-// The response includes nested objects
-console.log(character.birthplace.name);  // "The Shire"
-console.log(character.abilities[0].name); // "Ring Bearer"
-```
+### Working Reference Implementation
 
-### Type Definitions
+See [base-tool/src/llm/token-service.ts](https://github.com/OnlyWorlds/base-tool) for the complete working implementation that this SDK enables.
 
-All types are exported for your use:
+### Check Token Status
 
 ```typescript
-import { 
-  Character, 
-  CharacterInput,
-  Location,
-  ElementType 
-} from '@onlyworlds/sdk';
-
-// Use in your functions
-function createHero(data: CharacterInput): Promise<Character> {
-  return client.characters.create(data);
-}
+// Get current token status
+const status = await client.tokens.getStatus();
 
-// Element type enum
-console.log(ElementType.Character); // 'character'
+console.log(`Available: ${status.tokens_available_today}/${status.token_rating}`);
+console.log(`Used today: ${status.tokens_used_today}`);
+console.log(`Active sessions: ${status.sessions_active}`);
+console.log(`Last reset: ${status.last_reset}`);
 ```
 
-### Advanced Examples
+### Consume Tokens
 
-#### Batch Operations
+Report token consumption when your tool uses AI features or other token-tracked services:
 
 ```typescript
-// Create multiple related elements
-async function createParty(partyData: any[]) {
-  const location = await client.locations.create({
-    name: 'Tavern',
-    description: 'Where the party meets'
-  });
-
-  const characters = await Promise.all(
-    partyData.map(data => 
-      client.characters.create({
-        ...data,
-        location_id: location.id
-      })
-    )
-  );
+// Report token usage
+const result = await client.tokens.consume({
+  amount: 500,
+  service: 'my_worldbuilding_tool',
+  metadata: {
+    feature: 'character_generation',
+    model: 'gpt-4',
+    prompt_tokens: 300,
+    completion_tokens: 200
+  }
+});
 
-  return { location, characters };
+// Check if consumption succeeded
+if (result.error) {
+  console.warn('Token warning:', result.error);
 }
-```
 
-#### Search and Filter
+console.log(`Consumed ${result.tokens_consumed} tokens`);
+console.log(`${result.tokens_remaining} tokens remaining`);
+```
 
-```typescript
-// Find all wizards in a specific location
-const wizards = await client.characters.list({
-  search: 'wizard',
-  location: 'location-uuid',
-  ordering: '-level'
-});
+**Important**: The API allows consumption even when exceeding available tokens (tracks as debt), but returns a warning in the `error` field.
 
-// Get recently updated items
-const recent = await client.events.list({
-  ordering: '-updated_at',
-  limit: 5
-});
-```
+### Advanced: Encrypted API Key Access
 
-#### Error Handling
+For tools that need direct OpenAI API access using OnlyWorlds tokens:
 
 ```typescript
-try {
-  const character = await client.characters.get('invalid-uuid');
-} catch (error) {
-  if (error.message.includes('404')) {
-    console.log('Character not found');
-  }
-}
-```
+// Get encrypted OpenAI key (requires 100+ tokens)
+const access = await client.tokens.getAccessKey();
 
-## Input vs Output Types
+console.log('Session ID:', access.session_id);
+console.log('Expires:', access.expires_at);
+console.log('Available tokens:', access.tokens_available);
 
-OnlyWorlds uses different formats for requests and responses:
+// Decrypt the key client-side (see base-tool for full implementation)
+// 1. Derive decryption key from world ID using SHA-256
+// 2. Use 'fernet' npm package to decrypt
+// 3. Use decrypted OpenAI key for direct API calls
+// 4. Report usage with session_id
 
-- **Input** (requests): Use `_id` for single relationships, `_ids` for multiple
-- **Output** (responses): Nested objects with full data
+// See base-tool/src/llm/token-service.ts:99-235 for complete example
+```
 
-The SDK provides separate types for each:
+**Full decryption implementation** (based on base-tool):
 
 ```typescript
-// CharacterInput for creating/updating
-interface CharacterInput {
-  name: string;
-  location_id?: string;      // UUID string
-  abilities_ids?: string[];  // Array of UUIDs
+import { fernet } from 'fernet';
+
+// Derive decryption key from world ID
+async function deriveKey(worldId: string): Promise<string> {
+  const salt = 'onlyworlds-token-api-2024-public-salt';
+  const keyMaterial = `${worldId}:${salt}`;
+  const encoder = new TextEncoder();
+  const data = encoder.encode(keyMaterial);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const base64 = btoa(String.fromCharCode(...hashArray));
+  return base64.replace(/\+/g, '-').replace(/\//g, '_');
 }
 
-// Character for responses
-interface Character {
-  name: string;
-  location?: Location;       // Full nested object
-  abilities?: Ability[];     // Array of full objects
+// Decrypt the API key
+async function decryptApiKey(encryptedKey: string, worldId: string): Promise<string> {
+  const derivedKey = await deriveKey(worldId);
+  const secret = new fernet.Secret(derivedKey);
+  const token = new fernet.Token({
+    secret: secret,
+    token: encryptedKey,
+    ttl: 0  // Don't enforce TTL client-side
+  });
+  return token.decode();
 }
-```
-
-## Helper Methods
 
-```typescript
-// Convert nested objects to _id/_ids format
-const input = OnlyWorldsClient.prepareInput({
-  name: 'Test',
-  location: { id: 'uuid', name: 'Place' },
-  abilities: [{ id: 'uuid1' }, { id: 'uuid2' }]
+// Usage
+const world = await client.worlds.get();
+const access = await client.tokens.getAccessKey();
+const apiKey = await decryptApiKey(access.encrypted_key, world.id);
+
+// Use apiKey for OpenAI API calls, then report usage:
+await client.tokens.consume({
+  amount: tokensUsed,
+  sessionId: access.session_id,
+  service: 'direct_openai',
+  metadata: { model: 'gpt-4', /* ... */ }
 });
-// Result: { name: 'Test', location_id: 'uuid', abilities_ids: ['uuid1', 'uuid2'] }
 ```
 
-## Requirements
+### Session Management
 
-- Node.js 18+ or modern browser with fetch API
-- TypeScript 4.5+ (for TypeScript projects)
+```typescript
+// Revoke a specific session
+await client.tokens.revokeSession(sessionId);
 
-## Browser Usage
+// Revoke all sessions (emergency cleanup)
+const result = await client.tokens.revokeAllSessions();
+console.log(`Revoked ${result.sessions_revoked} sessions`);
+```
 
-This SDK works in browsers, but you'll need to handle CORS:
+### Encryption Info
 
-```javascript
-// For development, use a proxy or CORS-enabled server
-// Never expose API credentials in client-side code!
+Get public encryption details (no auth required):
 
-// Better approach: Use a backend proxy
-const response = await fetch('/api/proxy/onlyworlds', {
-  method: 'POST',
-  body: JSON.stringify({ /* your request */ })
-});
+```typescript
+const info = await client.tokens.getEncryptionInfo();
+console.log('Algorithm:', info.algorithm);
+console.log('Key derivation:', info.key_derivation);
+console.log('Public salt:', info.salt);
+console.log(info.javascript_example);
 ```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details
 
 ## Links
 
-- [OnlyWorlds Documentation](https://onlyworlds.github.io/)
-- [API Reference](https://www.onlyworlds.com/api/docs)
+- [OnlyWorlds Website](https://onlyworlds.com)
+- [Documentation](https://onlyworlds.github.io/)
 - [NPM Package](https://www.npmjs.com/package/@onlyworlds/sdk)
-- [GitHub](https://github.com/onlyworlds/sdk)
+- [Report Issues](https://github.com/OnlyWorlds/sdk/issues)