@onlyworlds/sdk 2.0.2 → 2.1.1

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   ELEMENT_UNICODE_ICONS: () => ELEMENT_UNICODE_ICONS,
   ElementType: () => ElementType,
   FIELD_SCHEMA: () => FIELD_SCHEMA,
+  GameTier: () => GameTier,
   ONLYWORLDS_VERSION: () => ONLYWORLDS_VERSION,
   OnlyWorldsClient: () => OnlyWorldsClient,
   createAnyElementId: () => createAnyElementId,
@@ -38,6 +39,151 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/token-resource.ts
+var TokenResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async getStatus() {
+    return this.client.request("GET", "/tokens/status/");
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async consume(params) {
+    return this.client.request("POST", "/tokens/consume/", {
+      body: {
+        amount: params.amount,
+        service: params.service || "sdk_client",
+        session_id: params.sessionId ?? null,
+        metadata: params.metadata ?? null
+      }
+    });
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getAccessKey() {
+    return this.client.request("GET", "/tokens/access-key/");
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async revokeSession(sessionId) {
+    return this.client.request(
+      "POST",
+      `/tokens/revoke-session/?session_id=${encodeURIComponent(sessionId)}`
+    );
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async revokeAllSessions() {
+    return this.client.request("POST", "/tokens/revoke-all-sessions/");
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getEncryptionInfo() {
+    return this.client.request("GET", "/tokens/encryption-info/");
+  }
+};
+
 // src/client.ts
 var Resource = class {
   constructor(client, elementType) {
@@ -45,20 +191,60 @@ var Resource = class {
     this.elementType = elementType;
   }
   async list(options) {
-    return this.client.request("GET", `/${this.elementType}/`, { params: options });
+    const response = await this.client.request("GET", `/${this.elementType}/`, { params: options });
+    if (Array.isArray(response)) {
+      return {
+        count: response.length,
+        next: null,
+        previous: null,
+        results: response
+      };
+    }
+    return response;
   }
   async get(id) {
     return this.client.request("GET", `/${this.elementType}/${id}/`);
   }
   async create(data) {
-    return this.client.request("POST", `/${this.elementType}/`, { body: data });
+    const body = this.elementType === "pin" ? this.roundPinCoordinates(data) : data;
+    return this.client.request("POST", `/${this.elementType}/`, { body });
   }
   async update(id, data) {
-    return this.client.request("PATCH", `/${this.elementType}/${id}/`, { body: data });
+    const body = this.elementType === "pin" ? this.roundPinCoordinates(data) : data;
+    return this.client.request("PATCH", `/${this.elementType}/${id}/`, { body });
   }
   async delete(id) {
     return this.client.request("DELETE", `/${this.elementType}/${id}/`);
   }
+  /**
+   * Round Pin coordinates to integers (API requirement)
+   * @private
+   */
+  roundPinCoordinates(data) {
+    const rounded = { ...data };
+    if (typeof rounded.x === "number") rounded.x = Math.round(rounded.x);
+    if (typeof rounded.y === "number") rounded.y = Math.round(rounded.y);
+    if (typeof rounded.z === "number") rounded.z = Math.round(rounded.z);
+    return rounded;
+  }
+};
+var WorldResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the world associated with the current API key
+   * Returns the world directly (not wrapped in pagination)
+   */
+  async get() {
+    return this.client.request("GET", "/world/");
+  }
+  /**
+   * Update the current world
+   */
+  async update(data) {
+    return this.client.request("PATCH", "/world/", { body: data });
+  }
 };
 var OnlyWorldsClient = class {
   constructor(config) {
@@ -68,7 +254,8 @@ var OnlyWorldsClient = class {
       "API-Key": config.apiKey,
       "API-Pin": config.apiPin
     };
-    this.worlds = new Resource(this, "world");
+    this.worlds = new WorldResource(this);
+    this.tokens = new TokenResource(this);
     this.abilities = new Resource(this, "ability");
     this.characters = new Resource(this, "character");
     this.collectives = new Resource(this, "collective");
@@ -119,7 +306,15 @@ var OnlyWorldsClient = class {
         if (errorText) {
           try {
             const errorJson = JSON.parse(errorText);
-            errorMessage += `: ${errorJson.detail || errorJson.error || errorText}`;
+            if (Array.isArray(errorJson.detail)) {
+              const validationErrors = errorJson.detail.map((err) => {
+                const location = err.loc ? err.loc.join(".") : "unknown";
+                return `${location}: ${err.msg}`;
+              }).join("; ");
+              errorMessage += `: ${validationErrors}`;
+            } else {
+              errorMessage += `: ${errorJson.detail || errorJson.error || errorText}`;
+            }
           } catch {
             errorMessage += `: ${errorText}`;
           }
@@ -133,13 +328,6 @@ var OnlyWorldsClient = class {
     }
     return response.json();
   }
-  /**
-   * Get all worlds accessible with current credentials
-   * @deprecated Use client.worlds.list() instead for consistent API
-   */
-  async getWorlds() {
-    return this.request("GET", "/world/");
-  }
   /**
    * Helper to convert nested objects to _id/_ids format
    */
@@ -974,6 +1162,17 @@ function createElementIds(ids) {
 function createAnyElementId(id) {
   return id;
 }
+
+// src/token-types.ts
+var GameTier = /* @__PURE__ */ ((GameTier2) => {
+  GameTier2["FREE"] = "free";
+  GameTier2["SILVER"] = "silver";
+  GameTier2["GOLD"] = "gold";
+  GameTier2["PLATINUM"] = "platinum";
+  GameTier2["DIAMOND"] = "diamond";
+  GameTier2["DELUXE"] = "deluxe";
+  return GameTier2;
+})(GameTier || {});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ELEMENT_ICONS,
@@ -982,6 +1181,7 @@ function createAnyElementId(id) {
   ELEMENT_UNICODE_ICONS,
   ElementType,
   FIELD_SCHEMA,
+  GameTier,
   ONLYWORLDS_VERSION,
   OnlyWorldsClient,
   createAnyElementId,