@onlyworlds/sdk 2.0.2 → 2.1.1

package/dist/index.mjs

@@ -1,3 +1,148 @@
+// 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) {
@@ -5,20 +150,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) {
@@ -28,7 +213,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");
@@ -79,7 +265,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}`;
           }
@@ -93,13 +287,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
    */
@@ -934,6 +1121,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 || {});
 export {
   ELEMENT_ICONS,
   ELEMENT_LABELS,
@@ -941,6 +1139,7 @@ export {
   ELEMENT_UNICODE_ICONS,
   ElementType,
   FIELD_SCHEMA,
+  GameTier,
   ONLYWORLDS_VERSION,
   OnlyWorldsClient,
   createAnyElementId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "main": "dist/index.js",
   "module": "dist/index.mjs",