@onlyworlds/sdk 2.0.1 → 2.1.0

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) {
@@ -60,6 +206,24 @@ var Resource = class {
     return this.client.request("DELETE", `/${this.elementType}/${id}/`);
   }
 };
+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) {
     this.baseUrl = config.baseUrl || "https://www.onlyworlds.com/api/worldapi";
@@ -68,7 +232,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");
@@ -133,13 +298,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 +1132,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 +1151,7 @@ function createAnyElementId(id) {
   ELEMENT_UNICODE_ICONS,
   ElementType,
   FIELD_SCHEMA,
+  GameTier,
   ONLYWORLDS_VERSION,
   OnlyWorldsClient,
   createAnyElementId,

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) {
@@ -20,6 +165,24 @@ var Resource = class {
     return this.client.request("DELETE", `/${this.elementType}/${id}/`);
   }
 };
+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) {
     this.baseUrl = config.baseUrl || "https://www.onlyworlds.com/api/worldapi";
@@ -28,7 +191,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");
@@ -93,13 +257,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 +1091,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 +1109,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.1",
+  "version": "2.1.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -28,7 +28,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/onlyworlds/sdk.git"
+    "url": "git+https://github.com/OnlyWorlds/sdk.git"
+  },
+  "homepage": "https://onlyworlds.github.io/",
+  "bugs": {
+    "url": "https://github.com/OnlyWorlds/sdk/issues"
   },
   "devDependencies": {
     "tsup": "^8.0.1",