@onlyworlds/sdk 2.0.2 → 2.1.1

package/README.md

@@ -22,27 +22,29 @@ const client = new OnlyWorldsClient({
   baseUrl: 'https://onlyworlds.com'
 });
 
-// Fetch characters
-const characters = await client.character.list();
+// Get your world (API keys are world-scoped)
+const world = await client.worlds.get();
+
+// Fetch characters (paginated)
+const characters = await client.characters.list();
 
 // Create a new location
-const location = await client.location.create({
+const location = await client.locations.create({
   name: 'Dragon Peak',
   description: 'A treacherous mountain peak where dragons nest',
-  supertype: 'mountain',
-  climate: 'cold'
+  supertype: 'mountain'
 });
 
 // Get a specific element
-const character = await client.character.get('element-id');
+const character = await client.characters.get('element-id');
 
 // Update an element
-await client.character.update('element-id', {
+await client.characters.update('element-id', {
   name: 'Updated Name'
 });
 
 // Delete an element
-await client.character.delete('element-id');
+await client.characters.delete('element-id');
 ```
 
 ## Features
@@ -50,36 +52,47 @@ await client.character.delete('element-id');
 - ✅ **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
 
-## Element Types
-
-The SDK provides full support for all OnlyWorlds elements:
-
-- **Character** - People, NPCs, protagonists
-- **Location** - Places, regions, buildings
-- **Object** - Items, artifacts, tools
-- **Creature** - Animals, monsters, beasts
-- **Species** - Races, types of beings
-- **Event** - Historical events, occurrences
-- **Ability** - Skills, powers, magic
-- **Trait** - Characteristics, attributes
-- **Family** - Family groups, lineages
-- **Institution** - Organizations, governments
-- **Collective** - Groups, teams, parties
-- **Construct** - Buildings, structures, concepts
-- **Language** - Languages, dialects
-- **Law** - Rules, regulations, customs
-- **Narrative** - Stories, tales, myths
-- **Phenomenon** - Natural phenomena, effects
-- **Title** - Ranks, positions, honors
-- **Zone** - Areas, territories, districts
-- **Relation** - Relationships between elements
-- **Map** - Visual maps with pins/markers
-- **Pin** - Location markers on maps
-- **Marker** - Additional map annotations
+## API Reference
+
+### 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
+// Get your world
+const world = await client.worlds.get();
+
+// Update your world
+const updated = await client.worlds.update({
+  description: 'A dark fantasy realm'
+});
+```
+
+**Note**: The `worlds` resource only has `get()` and `update()` methods (no `list()`, `create()`, or `delete()`) because API keys are world-scoped.
+
+### Element Endpoints
+
+All other element types return paginated results:
+
+```typescript
+// List with pagination
+const response = await client.characters.list({
+  limit: 10,
+  offset: 0,
+  ordering: '-created_at',
+  search: 'dragon'
+});
+
+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
+```
 
 ## Type-Safe Relationships
 
@@ -94,23 +107,140 @@ const character: Character = {
 };
 ```
 
-## Documentation
+## Token Management
+
+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.
+
+### Working Reference Implementation
+
+See [base-tool/src/llm/token-service.ts](https://github.com/OnlyWorlds/base-tool) for the complete working implementation that this SDK enables.
 
-For detailed documentation, examples, and API reference, visit:
+### Check Token Status
 
-📚 **[https://onlyworlds.github.io/](https://onlyworlds.github.io/)**
+```typescript
+// Get current token status
+const status = await client.tokens.getStatus();
+
+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}`);
+```
 
-## API Authentication
+### Consume Tokens
 
-Get your API credentials from your OnlyWorlds account:
+Report token consumption when your tool uses AI features or other token-tracked services:
 
-1. Log in to [onlyworlds.com](https://onlyworlds.com)
-2. Go to your world settings
-3. Copy your API Key and PIN
+```typescript
+// 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
+  }
+});
 
-## Contributing
+// Check if consumption succeeded
+if (result.error) {
+  console.warn('Token warning:', result.error);
+}
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+console.log(`Consumed ${result.tokens_consumed} tokens`);
+console.log(`${result.tokens_remaining} tokens remaining`);
+```
+
+**Important**: The API allows consumption even when exceeding available tokens (tracks as debt), but returns a warning in the `error` field.
+
+### Advanced: Encrypted API Key Access
+
+For tools that need direct OpenAI API access using OnlyWorlds tokens:
+
+```typescript
+// Get encrypted OpenAI key (requires 100+ tokens)
+const access = await client.tokens.getAccessKey();
+
+console.log('Session ID:', access.session_id);
+console.log('Expires:', access.expires_at);
+console.log('Available tokens:', access.tokens_available);
+
+// 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
+
+// See base-tool/src/llm/token-service.ts:99-235 for complete example
+```
+
+**Full decryption implementation** (based on base-tool):
+
+```typescript
+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, '_');
+}
+
+// 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();
+}
+
+// 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', /* ... */ }
+});
+```
+
+### Session Management
+
+```typescript
+// Revoke a specific session
+await client.tokens.revokeSession(sessionId);
+
+// Revoke all sessions (emergency cleanup)
+const result = await client.tokens.revokeAllSessions();
+console.log(`Revoked ${result.sessions_revoked} sessions`);
+```
+
+### Encryption Info
+
+Get public encryption details (no auth required):
+
+```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
 

package/dist/index.d.mts

@@ -553,8 +553,22 @@ interface Pin extends BaseElement {
     map?: ElementId<ElementType.Map>;
     element_type?: ElementType;
     element_id?: AnyElementId;
+    /**
+     * X coordinate on map (must be integer)
+     * The API requires integer values. Float coordinates from mouse events
+     * or calculations should be rounded: Math.round(x)
+     */
     x?: number;
+    /**
+     * Y coordinate on map (must be integer)
+     * The API requires integer values. Float coordinates from mouse events
+     * or calculations should be rounded: Math.round(y)
+     */
     y?: number;
+    /**
+     * Z coordinate for 3D positioning (must be integer)
+     * The API requires integer values. Float coordinates should be rounded: Math.round(z)
+     */
     z?: number;
 }
 /**
@@ -2711,6 +2725,272 @@ declare function createElementIds<T extends ElementType>(ids: string[]): Element
  */
 declare function createAnyElementId(id: string): AnyElementId;
 
+/**
+ * OnlyWorlds Token Management API Types
+ *
+ * Types for the token rating system that provides daily token allowances
+ * for API usage and AI integration features.
+ */
+/**
+ * Current token status for the authenticated user
+ */
+interface TokenStatus {
+    /** Remaining tokens available for today */
+    tokens_available_today: number;
+    /** User's daily token allowance (default: 10000) */
+    token_rating: number;
+    /** Tokens consumed so far today */
+    tokens_used_today: number;
+    /** Date of last reset (ISO format) */
+    last_reset: string;
+    /** Number of active token sessions */
+    sessions_active: number;
+}
+/**
+ * Response from token consumption endpoint
+ */
+interface TokenConsumeResponse {
+    /** Whether the consumption was successful */
+    success: boolean;
+    /** Actual tokens consumed */
+    tokens_consumed: number;
+    /** Updated token balance */
+    tokens_remaining: number;
+    /** User's daily allowance */
+    token_rating: number;
+    /** Warning message if insufficient tokens (consumption still succeeds but tracks debt) */
+    error?: string | null;
+}
+/**
+ * Parameters for consuming tokens
+ */
+interface TokenConsumeParams {
+    /** Number of tokens to consume (required) */
+    amount: number;
+    /** Service identifier (default: "sdk_client") */
+    service?: string;
+    /** Session ID from access key response (optional) */
+    sessionId?: string | null;
+    /** Additional metadata for analytics (optional) */
+    metadata?: Record<string, any> | null;
+}
+/**
+ * Response from getting encrypted access key (advanced use case)
+ */
+interface AccessKeyResponse {
+    /** Base64 encoded encrypted OpenAI key */
+    encrypted_key: string;
+    /** Key expiration timestamp (ISO format) */
+    expires_at: string;
+    /** Session ID for tracking usage */
+    session_id: string;
+    /** Current token balance */
+    tokens_available: number;
+    /** User's token allowance */
+    token_rating: number;
+    /** Encryption algorithm used */
+    encryption_method: string;
+}
+/**
+ * Public encryption information for client-side decryption
+ */
+interface EncryptionInfo {
+    /** Encryption algorithm (e.g., "Fernet") */
+    algorithm: string;
+    /** Key derivation method (e.g., "SHA256") */
+    key_derivation: string;
+    /** Public salt used in key derivation */
+    salt: string;
+    /** Format description */
+    format: string;
+    /** Human-readable description */
+    description: string;
+    /** Example JavaScript implementation */
+    javascript_example: string;
+}
+/**
+ * Response from session revocation
+ */
+interface RevokeSessionResponse {
+    /** Whether revocation was successful */
+    success: boolean;
+    /** Status message */
+    message: string;
+}
+/**
+ * Response from revoking all sessions
+ */
+interface RevokeAllSessionsResponse {
+    /** Whether revocation was successful */
+    success: boolean;
+    /** Number of sessions revoked */
+    sessions_revoked: number;
+}
+/**
+ * Game tier / subscription level
+ * (affects future features, currently all tiers get same token rating)
+ */
+declare enum GameTier {
+    FREE = "free",
+    SILVER = "silver",
+    GOLD = "gold",
+    PLATINUM = "platinum",
+    DIAMOND = "diamond",
+    DELUXE = "deluxe"
+}
+
+/**
+ * Token Management Resource
+ *
+ * Provides access to the OnlyWorlds token rating system API.
+ * Based on the working implementation in base-tool/src/llm/token-service.ts
+ */
+
+/**
+ * Token Management Resource
+ *
+ * Handles token status checking, consumption tracking, and encrypted key access
+ * for AI integration features.
+ *
+ * All endpoints require authentication (API-Key + API-Pin headers).
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new OnlyWorldsClient({ apiKey, apiPin });
+ *
+ * // Check token status
+ * const status = await client.tokens.getStatus();
+ * console.log(`${status.tokens_available_today}/${status.token_rating} tokens available`);
+ *
+ * // Consume tokens
+ * await client.tokens.consume({
+ *   amount: 500,
+ *   service: 'my_tool',
+ *   metadata: { feature: 'chat', model: 'gpt-4' }
+ * });
+ * ```
+ */
+declare class TokenResource {
+    private client;
+    constructor(client: OnlyWorldsClient);
+    /**
+     * Get current token status for authenticated user
+     *
+     * Returns daily token allowance, usage, and availability.
+     * Matches base-tool's checkStatus() pattern.
+     *
+     * @returns Current token status
+     * @example
+     * ```typescript
+     * const status = await client.tokens.getStatus();
+     * 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}`);
+     * ```
+     */
+    getStatus(): Promise<TokenStatus>;
+    /**
+     * Consume tokens for service usage
+     *
+     * Reports token consumption to track daily usage. Allows consumption even if
+     * exceeds available tokens (tracks as debt), but warns via error field.
+     * Matches base-tool's reportUsage() pattern.
+     *
+     * @param params - Token consumption parameters
+     * @returns Consumption result with updated balance
+     * @example
+     * ```typescript
+     * const result = await client.tokens.consume({
+     *   amount: 500,
+     *   service: 'worldbuilding_tool',
+     *   metadata: {
+     *     feature: 'character_generation',
+     *     model: 'gpt-4',
+     *     prompt_tokens: 300,
+     *     completion_tokens: 200
+     *   }
+     * });
+     *
+     * if (result.error) {
+     *   console.warn('Token warning:', result.error);
+     * }
+     * console.log(`${result.tokens_remaining} tokens remaining`);
+     * ```
+     */
+    consume(params: TokenConsumeParams): Promise<TokenConsumeResponse>;
+    /**
+     * Get encrypted OpenAI API key (advanced use case)
+     *
+     * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
+     * Returns encrypted key that must be decrypted client-side using Fernet.
+     *
+     * See base-tool/src/llm/token-service.ts:99-155 for full implementation example
+     * including client-side decryption with the 'fernet' npm package.
+     *
+     * @returns Encrypted access key and session info
+     * @throws Error if insufficient tokens (< 100)
+     * @example
+     * ```typescript
+     * // Get encrypted key
+     * const access = await client.tokens.getAccessKey();
+     *
+     * // Decrypt using fernet library (see base-tool for full example)
+     * // 1. Derive 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 access.session_id
+     *
+     * console.log('Session:', access.session_id);
+     * console.log('Expires:', access.expires_at);
+     * ```
+     */
+    getAccessKey(): Promise<AccessKeyResponse>;
+    /**
+     * Revoke a specific token session
+     *
+     * Invalidates the session ID obtained from getAccessKey().
+     * Use when cleaning up or on logout.
+     *
+     * @param sessionId - Session ID to revoke
+     * @returns Revocation result
+     * @example
+     * ```typescript
+     * await client.tokens.revokeSession('session-id-here');
+     * ```
+     */
+    revokeSession(sessionId: string): Promise<RevokeSessionResponse>;
+    /**
+     * Revoke all active sessions (emergency use)
+     *
+     * Invalidates all token sessions for the authenticated user.
+     * Use for security cleanup or when sessions are stuck.
+     *
+     * @returns Revocation result with count of revoked sessions
+     * @example
+     * ```typescript
+     * const result = await client.tokens.revokeAllSessions();
+     * console.log(`Revoked ${result.sessions_revoked} sessions`);
+     * ```
+     */
+    revokeAllSessions(): Promise<RevokeAllSessionsResponse>;
+    /**
+     * Get public encryption info (no auth required)
+     *
+     * Returns algorithm details and example code for client-side decryption.
+     * Public endpoint - can be called without authentication.
+     *
+     * @returns Encryption algorithm and implementation details
+     * @example
+     * ```typescript
+     * const info = await client.tokens.getEncryptionInfo();
+     * console.log('Algorithm:', info.algorithm);
+     * console.log('Key derivation:', info.key_derivation);
+     * console.log(info.javascript_example);
+     * ```
+     */
+    getEncryptionInfo(): Promise<EncryptionInfo>;
+}
+
 interface OnlyWorldsConfig {
     apiKey: string;
     apiPin: string;
@@ -2741,6 +3021,29 @@ declare class Resource<T, TInput> {
     create(data: TInput): Promise<T>;
     update(id: string, data: Partial<TInput>): Promise<T>;
     delete(id: string): Promise<void>;
+    /**
+     * Round Pin coordinates to integers (API requirement)
+     * @private
+     */
+    private roundPinCoordinates;
+}
+/**
+ * Special resource class for World endpoint
+ * The /world/ endpoint returns a single World object directly (not paginated)
+ * because API keys are world-scoped (one key = one world)
+ */
+declare class WorldResource {
+    private client;
+    constructor(client: OnlyWorldsClient);
+    /**
+     * Get the world associated with the current API key
+     * Returns the world directly (not wrapped in pagination)
+     */
+    get(): Promise<World>;
+    /**
+     * Update the current world
+     */
+    update(data: Partial<WorldInput>): Promise<World>;
 }
 /**
  * Main OnlyWorlds API client
@@ -2748,7 +3051,8 @@ declare class Resource<T, TInput> {
 declare class OnlyWorldsClient {
     private baseUrl;
     private headers;
-    worlds: Resource<World, WorldInput>;
+    worlds: WorldResource;
+    tokens: TokenResource;
     abilities: Resource<Ability, AbilityInput>;
     characters: Resource<Character, CharacterInput>;
     collectives: Resource<Collective, CollectiveInput>;
@@ -2779,15 +3083,10 @@ declare class OnlyWorldsClient {
         params?: Record<string, any>;
         body?: any;
     }): Promise<T>;
-    /**
-     * Get all worlds accessible with current credentials
-     * @deprecated Use client.worlds.list() instead for consistent API
-     */
-    getWorlds(): Promise<ApiResponse<World>>;
     /**
      * Helper to convert nested objects to _id/_ids format
      */
     static prepareInput<T extends Record<string, any>>(data: T): any;
 }
 
-export { type Ability, type AbilityInput, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_UNICODE_ICONS, type ElementId, type ElementIds, ElementType, type Event, type EventInput, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type Trait, type TraitInput, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, getElementIcon, getElementLabel, getElementSections, getElementUnicodeIcon };
+export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_UNICODE_ICONS, type ElementId, type ElementIds, ElementType, type EncryptionInfo, type Event, type EventInput, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, getElementIcon, getElementLabel, getElementSections, getElementUnicodeIcon };