@onlyworlds/sdk 2.0.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +164 -172
- package/dist/index.d.mts +287 -7
- package/dist/index.d.ts +287 -7
- package/dist/index.js +178 -8
- package/dist/index.mjs +177 -8
- package/package.json +6 -2
package/dist/index.d.mts
CHANGED
|
@@ -2711,6 +2711,272 @@ declare function createElementIds<T extends ElementType>(ids: string[]): Element
|
|
|
2711
2711
|
*/
|
|
2712
2712
|
declare function createAnyElementId(id: string): AnyElementId;
|
|
2713
2713
|
|
|
2714
|
+
/**
|
|
2715
|
+
* OnlyWorlds Token Management API Types
|
|
2716
|
+
*
|
|
2717
|
+
* Types for the token rating system that provides daily token allowances
|
|
2718
|
+
* for API usage and AI integration features.
|
|
2719
|
+
*/
|
|
2720
|
+
/**
|
|
2721
|
+
* Current token status for the authenticated user
|
|
2722
|
+
*/
|
|
2723
|
+
interface TokenStatus {
|
|
2724
|
+
/** Remaining tokens available for today */
|
|
2725
|
+
tokens_available_today: number;
|
|
2726
|
+
/** User's daily token allowance (default: 10000) */
|
|
2727
|
+
token_rating: number;
|
|
2728
|
+
/** Tokens consumed so far today */
|
|
2729
|
+
tokens_used_today: number;
|
|
2730
|
+
/** Date of last reset (ISO format) */
|
|
2731
|
+
last_reset: string;
|
|
2732
|
+
/** Number of active token sessions */
|
|
2733
|
+
sessions_active: number;
|
|
2734
|
+
}
|
|
2735
|
+
/**
|
|
2736
|
+
* Response from token consumption endpoint
|
|
2737
|
+
*/
|
|
2738
|
+
interface TokenConsumeResponse {
|
|
2739
|
+
/** Whether the consumption was successful */
|
|
2740
|
+
success: boolean;
|
|
2741
|
+
/** Actual tokens consumed */
|
|
2742
|
+
tokens_consumed: number;
|
|
2743
|
+
/** Updated token balance */
|
|
2744
|
+
tokens_remaining: number;
|
|
2745
|
+
/** User's daily allowance */
|
|
2746
|
+
token_rating: number;
|
|
2747
|
+
/** Warning message if insufficient tokens (consumption still succeeds but tracks debt) */
|
|
2748
|
+
error?: string | null;
|
|
2749
|
+
}
|
|
2750
|
+
/**
|
|
2751
|
+
* Parameters for consuming tokens
|
|
2752
|
+
*/
|
|
2753
|
+
interface TokenConsumeParams {
|
|
2754
|
+
/** Number of tokens to consume (required) */
|
|
2755
|
+
amount: number;
|
|
2756
|
+
/** Service identifier (default: "sdk_client") */
|
|
2757
|
+
service?: string;
|
|
2758
|
+
/** Session ID from access key response (optional) */
|
|
2759
|
+
sessionId?: string | null;
|
|
2760
|
+
/** Additional metadata for analytics (optional) */
|
|
2761
|
+
metadata?: Record<string, any> | null;
|
|
2762
|
+
}
|
|
2763
|
+
/**
|
|
2764
|
+
* Response from getting encrypted access key (advanced use case)
|
|
2765
|
+
*/
|
|
2766
|
+
interface AccessKeyResponse {
|
|
2767
|
+
/** Base64 encoded encrypted OpenAI key */
|
|
2768
|
+
encrypted_key: string;
|
|
2769
|
+
/** Key expiration timestamp (ISO format) */
|
|
2770
|
+
expires_at: string;
|
|
2771
|
+
/** Session ID for tracking usage */
|
|
2772
|
+
session_id: string;
|
|
2773
|
+
/** Current token balance */
|
|
2774
|
+
tokens_available: number;
|
|
2775
|
+
/** User's token allowance */
|
|
2776
|
+
token_rating: number;
|
|
2777
|
+
/** Encryption algorithm used */
|
|
2778
|
+
encryption_method: string;
|
|
2779
|
+
}
|
|
2780
|
+
/**
|
|
2781
|
+
* Public encryption information for client-side decryption
|
|
2782
|
+
*/
|
|
2783
|
+
interface EncryptionInfo {
|
|
2784
|
+
/** Encryption algorithm (e.g., "Fernet") */
|
|
2785
|
+
algorithm: string;
|
|
2786
|
+
/** Key derivation method (e.g., "SHA256") */
|
|
2787
|
+
key_derivation: string;
|
|
2788
|
+
/** Public salt used in key derivation */
|
|
2789
|
+
salt: string;
|
|
2790
|
+
/** Format description */
|
|
2791
|
+
format: string;
|
|
2792
|
+
/** Human-readable description */
|
|
2793
|
+
description: string;
|
|
2794
|
+
/** Example JavaScript implementation */
|
|
2795
|
+
javascript_example: string;
|
|
2796
|
+
}
|
|
2797
|
+
/**
|
|
2798
|
+
* Response from session revocation
|
|
2799
|
+
*/
|
|
2800
|
+
interface RevokeSessionResponse {
|
|
2801
|
+
/** Whether revocation was successful */
|
|
2802
|
+
success: boolean;
|
|
2803
|
+
/** Status message */
|
|
2804
|
+
message: string;
|
|
2805
|
+
}
|
|
2806
|
+
/**
|
|
2807
|
+
* Response from revoking all sessions
|
|
2808
|
+
*/
|
|
2809
|
+
interface RevokeAllSessionsResponse {
|
|
2810
|
+
/** Whether revocation was successful */
|
|
2811
|
+
success: boolean;
|
|
2812
|
+
/** Number of sessions revoked */
|
|
2813
|
+
sessions_revoked: number;
|
|
2814
|
+
}
|
|
2815
|
+
/**
|
|
2816
|
+
* Game tier / subscription level
|
|
2817
|
+
* (affects future features, currently all tiers get same token rating)
|
|
2818
|
+
*/
|
|
2819
|
+
declare enum GameTier {
|
|
2820
|
+
FREE = "free",
|
|
2821
|
+
SILVER = "silver",
|
|
2822
|
+
GOLD = "gold",
|
|
2823
|
+
PLATINUM = "platinum",
|
|
2824
|
+
DIAMOND = "diamond",
|
|
2825
|
+
DELUXE = "deluxe"
|
|
2826
|
+
}
|
|
2827
|
+
|
|
2828
|
+
/**
|
|
2829
|
+
* Token Management Resource
|
|
2830
|
+
*
|
|
2831
|
+
* Provides access to the OnlyWorlds token rating system API.
|
|
2832
|
+
* Based on the working implementation in base-tool/src/llm/token-service.ts
|
|
2833
|
+
*/
|
|
2834
|
+
|
|
2835
|
+
/**
|
|
2836
|
+
* Token Management Resource
|
|
2837
|
+
*
|
|
2838
|
+
* Handles token status checking, consumption tracking, and encrypted key access
|
|
2839
|
+
* for AI integration features.
|
|
2840
|
+
*
|
|
2841
|
+
* All endpoints require authentication (API-Key + API-Pin headers).
|
|
2842
|
+
*
|
|
2843
|
+
* Example usage:
|
|
2844
|
+
* ```typescript
|
|
2845
|
+
* const client = new OnlyWorldsClient({ apiKey, apiPin });
|
|
2846
|
+
*
|
|
2847
|
+
* // Check token status
|
|
2848
|
+
* const status = await client.tokens.getStatus();
|
|
2849
|
+
* console.log(`${status.tokens_available_today}/${status.token_rating} tokens available`);
|
|
2850
|
+
*
|
|
2851
|
+
* // Consume tokens
|
|
2852
|
+
* await client.tokens.consume({
|
|
2853
|
+
* amount: 500,
|
|
2854
|
+
* service: 'my_tool',
|
|
2855
|
+
* metadata: { feature: 'chat', model: 'gpt-4' }
|
|
2856
|
+
* });
|
|
2857
|
+
* ```
|
|
2858
|
+
*/
|
|
2859
|
+
declare class TokenResource {
|
|
2860
|
+
private client;
|
|
2861
|
+
constructor(client: OnlyWorldsClient);
|
|
2862
|
+
/**
|
|
2863
|
+
* Get current token status for authenticated user
|
|
2864
|
+
*
|
|
2865
|
+
* Returns daily token allowance, usage, and availability.
|
|
2866
|
+
* Matches base-tool's checkStatus() pattern.
|
|
2867
|
+
*
|
|
2868
|
+
* @returns Current token status
|
|
2869
|
+
* @example
|
|
2870
|
+
* ```typescript
|
|
2871
|
+
* const status = await client.tokens.getStatus();
|
|
2872
|
+
* console.log(`Available: ${status.tokens_available_today}/${status.token_rating}`);
|
|
2873
|
+
* console.log(`Used today: ${status.tokens_used_today}`);
|
|
2874
|
+
* console.log(`Active sessions: ${status.sessions_active}`);
|
|
2875
|
+
* ```
|
|
2876
|
+
*/
|
|
2877
|
+
getStatus(): Promise<TokenStatus>;
|
|
2878
|
+
/**
|
|
2879
|
+
* Consume tokens for service usage
|
|
2880
|
+
*
|
|
2881
|
+
* Reports token consumption to track daily usage. Allows consumption even if
|
|
2882
|
+
* exceeds available tokens (tracks as debt), but warns via error field.
|
|
2883
|
+
* Matches base-tool's reportUsage() pattern.
|
|
2884
|
+
*
|
|
2885
|
+
* @param params - Token consumption parameters
|
|
2886
|
+
* @returns Consumption result with updated balance
|
|
2887
|
+
* @example
|
|
2888
|
+
* ```typescript
|
|
2889
|
+
* const result = await client.tokens.consume({
|
|
2890
|
+
* amount: 500,
|
|
2891
|
+
* service: 'worldbuilding_tool',
|
|
2892
|
+
* metadata: {
|
|
2893
|
+
* feature: 'character_generation',
|
|
2894
|
+
* model: 'gpt-4',
|
|
2895
|
+
* prompt_tokens: 300,
|
|
2896
|
+
* completion_tokens: 200
|
|
2897
|
+
* }
|
|
2898
|
+
* });
|
|
2899
|
+
*
|
|
2900
|
+
* if (result.error) {
|
|
2901
|
+
* console.warn('Token warning:', result.error);
|
|
2902
|
+
* }
|
|
2903
|
+
* console.log(`${result.tokens_remaining} tokens remaining`);
|
|
2904
|
+
* ```
|
|
2905
|
+
*/
|
|
2906
|
+
consume(params: TokenConsumeParams): Promise<TokenConsumeResponse>;
|
|
2907
|
+
/**
|
|
2908
|
+
* Get encrypted OpenAI API key (advanced use case)
|
|
2909
|
+
*
|
|
2910
|
+
* Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
|
|
2911
|
+
* Returns encrypted key that must be decrypted client-side using Fernet.
|
|
2912
|
+
*
|
|
2913
|
+
* See base-tool/src/llm/token-service.ts:99-155 for full implementation example
|
|
2914
|
+
* including client-side decryption with the 'fernet' npm package.
|
|
2915
|
+
*
|
|
2916
|
+
* @returns Encrypted access key and session info
|
|
2917
|
+
* @throws Error if insufficient tokens (< 100)
|
|
2918
|
+
* @example
|
|
2919
|
+
* ```typescript
|
|
2920
|
+
* // Get encrypted key
|
|
2921
|
+
* const access = await client.tokens.getAccessKey();
|
|
2922
|
+
*
|
|
2923
|
+
* // Decrypt using fernet library (see base-tool for full example)
|
|
2924
|
+
* // 1. Derive key from world ID using SHA-256
|
|
2925
|
+
* // 2. Use 'fernet' npm package to decrypt
|
|
2926
|
+
* // 3. Use decrypted OpenAI key for direct API calls
|
|
2927
|
+
* // 4. Report usage with access.session_id
|
|
2928
|
+
*
|
|
2929
|
+
* console.log('Session:', access.session_id);
|
|
2930
|
+
* console.log('Expires:', access.expires_at);
|
|
2931
|
+
* ```
|
|
2932
|
+
*/
|
|
2933
|
+
getAccessKey(): Promise<AccessKeyResponse>;
|
|
2934
|
+
/**
|
|
2935
|
+
* Revoke a specific token session
|
|
2936
|
+
*
|
|
2937
|
+
* Invalidates the session ID obtained from getAccessKey().
|
|
2938
|
+
* Use when cleaning up or on logout.
|
|
2939
|
+
*
|
|
2940
|
+
* @param sessionId - Session ID to revoke
|
|
2941
|
+
* @returns Revocation result
|
|
2942
|
+
* @example
|
|
2943
|
+
* ```typescript
|
|
2944
|
+
* await client.tokens.revokeSession('session-id-here');
|
|
2945
|
+
* ```
|
|
2946
|
+
*/
|
|
2947
|
+
revokeSession(sessionId: string): Promise<RevokeSessionResponse>;
|
|
2948
|
+
/**
|
|
2949
|
+
* Revoke all active sessions (emergency use)
|
|
2950
|
+
*
|
|
2951
|
+
* Invalidates all token sessions for the authenticated user.
|
|
2952
|
+
* Use for security cleanup or when sessions are stuck.
|
|
2953
|
+
*
|
|
2954
|
+
* @returns Revocation result with count of revoked sessions
|
|
2955
|
+
* @example
|
|
2956
|
+
* ```typescript
|
|
2957
|
+
* const result = await client.tokens.revokeAllSessions();
|
|
2958
|
+
* console.log(`Revoked ${result.sessions_revoked} sessions`);
|
|
2959
|
+
* ```
|
|
2960
|
+
*/
|
|
2961
|
+
revokeAllSessions(): Promise<RevokeAllSessionsResponse>;
|
|
2962
|
+
/**
|
|
2963
|
+
* Get public encryption info (no auth required)
|
|
2964
|
+
*
|
|
2965
|
+
* Returns algorithm details and example code for client-side decryption.
|
|
2966
|
+
* Public endpoint - can be called without authentication.
|
|
2967
|
+
*
|
|
2968
|
+
* @returns Encryption algorithm and implementation details
|
|
2969
|
+
* @example
|
|
2970
|
+
* ```typescript
|
|
2971
|
+
* const info = await client.tokens.getEncryptionInfo();
|
|
2972
|
+
* console.log('Algorithm:', info.algorithm);
|
|
2973
|
+
* console.log('Key derivation:', info.key_derivation);
|
|
2974
|
+
* console.log(info.javascript_example);
|
|
2975
|
+
* ```
|
|
2976
|
+
*/
|
|
2977
|
+
getEncryptionInfo(): Promise<EncryptionInfo>;
|
|
2978
|
+
}
|
|
2979
|
+
|
|
2714
2980
|
interface OnlyWorldsConfig {
|
|
2715
2981
|
apiKey: string;
|
|
2716
2982
|
apiPin: string;
|
|
@@ -2742,13 +3008,32 @@ declare class Resource<T, TInput> {
|
|
|
2742
3008
|
update(id: string, data: Partial<TInput>): Promise<T>;
|
|
2743
3009
|
delete(id: string): Promise<void>;
|
|
2744
3010
|
}
|
|
3011
|
+
/**
|
|
3012
|
+
* Special resource class for World endpoint
|
|
3013
|
+
* The /world/ endpoint returns a single World object directly (not paginated)
|
|
3014
|
+
* because API keys are world-scoped (one key = one world)
|
|
3015
|
+
*/
|
|
3016
|
+
declare class WorldResource {
|
|
3017
|
+
private client;
|
|
3018
|
+
constructor(client: OnlyWorldsClient);
|
|
3019
|
+
/**
|
|
3020
|
+
* Get the world associated with the current API key
|
|
3021
|
+
* Returns the world directly (not wrapped in pagination)
|
|
3022
|
+
*/
|
|
3023
|
+
get(): Promise<World>;
|
|
3024
|
+
/**
|
|
3025
|
+
* Update the current world
|
|
3026
|
+
*/
|
|
3027
|
+
update(data: Partial<WorldInput>): Promise<World>;
|
|
3028
|
+
}
|
|
2745
3029
|
/**
|
|
2746
3030
|
* Main OnlyWorlds API client
|
|
2747
3031
|
*/
|
|
2748
3032
|
declare class OnlyWorldsClient {
|
|
2749
3033
|
private baseUrl;
|
|
2750
3034
|
private headers;
|
|
2751
|
-
worlds:
|
|
3035
|
+
worlds: WorldResource;
|
|
3036
|
+
tokens: TokenResource;
|
|
2752
3037
|
abilities: Resource<Ability, AbilityInput>;
|
|
2753
3038
|
characters: Resource<Character, CharacterInput>;
|
|
2754
3039
|
collectives: Resource<Collective, CollectiveInput>;
|
|
@@ -2779,15 +3064,10 @@ declare class OnlyWorldsClient {
|
|
|
2779
3064
|
params?: Record<string, any>;
|
|
2780
3065
|
body?: any;
|
|
2781
3066
|
}): Promise<T>;
|
|
2782
|
-
/**
|
|
2783
|
-
* Get all worlds accessible with current credentials
|
|
2784
|
-
* @deprecated Use client.worlds.list() instead for consistent API
|
|
2785
|
-
*/
|
|
2786
|
-
getWorlds(): Promise<ApiResponse<World>>;
|
|
2787
3067
|
/**
|
|
2788
3068
|
* Helper to convert nested objects to _id/_ids format
|
|
2789
3069
|
*/
|
|
2790
3070
|
static prepareInput<T extends Record<string, any>>(data: T): any;
|
|
2791
3071
|
}
|
|
2792
3072
|
|
|
2793
|
-
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 };
|
|
3073
|
+
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.d.ts
CHANGED
|
@@ -2711,6 +2711,272 @@ declare function createElementIds<T extends ElementType>(ids: string[]): Element
|
|
|
2711
2711
|
*/
|
|
2712
2712
|
declare function createAnyElementId(id: string): AnyElementId;
|
|
2713
2713
|
|
|
2714
|
+
/**
|
|
2715
|
+
* OnlyWorlds Token Management API Types
|
|
2716
|
+
*
|
|
2717
|
+
* Types for the token rating system that provides daily token allowances
|
|
2718
|
+
* for API usage and AI integration features.
|
|
2719
|
+
*/
|
|
2720
|
+
/**
|
|
2721
|
+
* Current token status for the authenticated user
|
|
2722
|
+
*/
|
|
2723
|
+
interface TokenStatus {
|
|
2724
|
+
/** Remaining tokens available for today */
|
|
2725
|
+
tokens_available_today: number;
|
|
2726
|
+
/** User's daily token allowance (default: 10000) */
|
|
2727
|
+
token_rating: number;
|
|
2728
|
+
/** Tokens consumed so far today */
|
|
2729
|
+
tokens_used_today: number;
|
|
2730
|
+
/** Date of last reset (ISO format) */
|
|
2731
|
+
last_reset: string;
|
|
2732
|
+
/** Number of active token sessions */
|
|
2733
|
+
sessions_active: number;
|
|
2734
|
+
}
|
|
2735
|
+
/**
|
|
2736
|
+
* Response from token consumption endpoint
|
|
2737
|
+
*/
|
|
2738
|
+
interface TokenConsumeResponse {
|
|
2739
|
+
/** Whether the consumption was successful */
|
|
2740
|
+
success: boolean;
|
|
2741
|
+
/** Actual tokens consumed */
|
|
2742
|
+
tokens_consumed: number;
|
|
2743
|
+
/** Updated token balance */
|
|
2744
|
+
tokens_remaining: number;
|
|
2745
|
+
/** User's daily allowance */
|
|
2746
|
+
token_rating: number;
|
|
2747
|
+
/** Warning message if insufficient tokens (consumption still succeeds but tracks debt) */
|
|
2748
|
+
error?: string | null;
|
|
2749
|
+
}
|
|
2750
|
+
/**
|
|
2751
|
+
* Parameters for consuming tokens
|
|
2752
|
+
*/
|
|
2753
|
+
interface TokenConsumeParams {
|
|
2754
|
+
/** Number of tokens to consume (required) */
|
|
2755
|
+
amount: number;
|
|
2756
|
+
/** Service identifier (default: "sdk_client") */
|
|
2757
|
+
service?: string;
|
|
2758
|
+
/** Session ID from access key response (optional) */
|
|
2759
|
+
sessionId?: string | null;
|
|
2760
|
+
/** Additional metadata for analytics (optional) */
|
|
2761
|
+
metadata?: Record<string, any> | null;
|
|
2762
|
+
}
|
|
2763
|
+
/**
|
|
2764
|
+
* Response from getting encrypted access key (advanced use case)
|
|
2765
|
+
*/
|
|
2766
|
+
interface AccessKeyResponse {
|
|
2767
|
+
/** Base64 encoded encrypted OpenAI key */
|
|
2768
|
+
encrypted_key: string;
|
|
2769
|
+
/** Key expiration timestamp (ISO format) */
|
|
2770
|
+
expires_at: string;
|
|
2771
|
+
/** Session ID for tracking usage */
|
|
2772
|
+
session_id: string;
|
|
2773
|
+
/** Current token balance */
|
|
2774
|
+
tokens_available: number;
|
|
2775
|
+
/** User's token allowance */
|
|
2776
|
+
token_rating: number;
|
|
2777
|
+
/** Encryption algorithm used */
|
|
2778
|
+
encryption_method: string;
|
|
2779
|
+
}
|
|
2780
|
+
/**
|
|
2781
|
+
* Public encryption information for client-side decryption
|
|
2782
|
+
*/
|
|
2783
|
+
interface EncryptionInfo {
|
|
2784
|
+
/** Encryption algorithm (e.g., "Fernet") */
|
|
2785
|
+
algorithm: string;
|
|
2786
|
+
/** Key derivation method (e.g., "SHA256") */
|
|
2787
|
+
key_derivation: string;
|
|
2788
|
+
/** Public salt used in key derivation */
|
|
2789
|
+
salt: string;
|
|
2790
|
+
/** Format description */
|
|
2791
|
+
format: string;
|
|
2792
|
+
/** Human-readable description */
|
|
2793
|
+
description: string;
|
|
2794
|
+
/** Example JavaScript implementation */
|
|
2795
|
+
javascript_example: string;
|
|
2796
|
+
}
|
|
2797
|
+
/**
|
|
2798
|
+
* Response from session revocation
|
|
2799
|
+
*/
|
|
2800
|
+
interface RevokeSessionResponse {
|
|
2801
|
+
/** Whether revocation was successful */
|
|
2802
|
+
success: boolean;
|
|
2803
|
+
/** Status message */
|
|
2804
|
+
message: string;
|
|
2805
|
+
}
|
|
2806
|
+
/**
|
|
2807
|
+
* Response from revoking all sessions
|
|
2808
|
+
*/
|
|
2809
|
+
interface RevokeAllSessionsResponse {
|
|
2810
|
+
/** Whether revocation was successful */
|
|
2811
|
+
success: boolean;
|
|
2812
|
+
/** Number of sessions revoked */
|
|
2813
|
+
sessions_revoked: number;
|
|
2814
|
+
}
|
|
2815
|
+
/**
|
|
2816
|
+
* Game tier / subscription level
|
|
2817
|
+
* (affects future features, currently all tiers get same token rating)
|
|
2818
|
+
*/
|
|
2819
|
+
declare enum GameTier {
|
|
2820
|
+
FREE = "free",
|
|
2821
|
+
SILVER = "silver",
|
|
2822
|
+
GOLD = "gold",
|
|
2823
|
+
PLATINUM = "platinum",
|
|
2824
|
+
DIAMOND = "diamond",
|
|
2825
|
+
DELUXE = "deluxe"
|
|
2826
|
+
}
|
|
2827
|
+
|
|
2828
|
+
/**
|
|
2829
|
+
* Token Management Resource
|
|
2830
|
+
*
|
|
2831
|
+
* Provides access to the OnlyWorlds token rating system API.
|
|
2832
|
+
* Based on the working implementation in base-tool/src/llm/token-service.ts
|
|
2833
|
+
*/
|
|
2834
|
+
|
|
2835
|
+
/**
|
|
2836
|
+
* Token Management Resource
|
|
2837
|
+
*
|
|
2838
|
+
* Handles token status checking, consumption tracking, and encrypted key access
|
|
2839
|
+
* for AI integration features.
|
|
2840
|
+
*
|
|
2841
|
+
* All endpoints require authentication (API-Key + API-Pin headers).
|
|
2842
|
+
*
|
|
2843
|
+
* Example usage:
|
|
2844
|
+
* ```typescript
|
|
2845
|
+
* const client = new OnlyWorldsClient({ apiKey, apiPin });
|
|
2846
|
+
*
|
|
2847
|
+
* // Check token status
|
|
2848
|
+
* const status = await client.tokens.getStatus();
|
|
2849
|
+
* console.log(`${status.tokens_available_today}/${status.token_rating} tokens available`);
|
|
2850
|
+
*
|
|
2851
|
+
* // Consume tokens
|
|
2852
|
+
* await client.tokens.consume({
|
|
2853
|
+
* amount: 500,
|
|
2854
|
+
* service: 'my_tool',
|
|
2855
|
+
* metadata: { feature: 'chat', model: 'gpt-4' }
|
|
2856
|
+
* });
|
|
2857
|
+
* ```
|
|
2858
|
+
*/
|
|
2859
|
+
declare class TokenResource {
|
|
2860
|
+
private client;
|
|
2861
|
+
constructor(client: OnlyWorldsClient);
|
|
2862
|
+
/**
|
|
2863
|
+
* Get current token status for authenticated user
|
|
2864
|
+
*
|
|
2865
|
+
* Returns daily token allowance, usage, and availability.
|
|
2866
|
+
* Matches base-tool's checkStatus() pattern.
|
|
2867
|
+
*
|
|
2868
|
+
* @returns Current token status
|
|
2869
|
+
* @example
|
|
2870
|
+
* ```typescript
|
|
2871
|
+
* const status = await client.tokens.getStatus();
|
|
2872
|
+
* console.log(`Available: ${status.tokens_available_today}/${status.token_rating}`);
|
|
2873
|
+
* console.log(`Used today: ${status.tokens_used_today}`);
|
|
2874
|
+
* console.log(`Active sessions: ${status.sessions_active}`);
|
|
2875
|
+
* ```
|
|
2876
|
+
*/
|
|
2877
|
+
getStatus(): Promise<TokenStatus>;
|
|
2878
|
+
/**
|
|
2879
|
+
* Consume tokens for service usage
|
|
2880
|
+
*
|
|
2881
|
+
* Reports token consumption to track daily usage. Allows consumption even if
|
|
2882
|
+
* exceeds available tokens (tracks as debt), but warns via error field.
|
|
2883
|
+
* Matches base-tool's reportUsage() pattern.
|
|
2884
|
+
*
|
|
2885
|
+
* @param params - Token consumption parameters
|
|
2886
|
+
* @returns Consumption result with updated balance
|
|
2887
|
+
* @example
|
|
2888
|
+
* ```typescript
|
|
2889
|
+
* const result = await client.tokens.consume({
|
|
2890
|
+
* amount: 500,
|
|
2891
|
+
* service: 'worldbuilding_tool',
|
|
2892
|
+
* metadata: {
|
|
2893
|
+
* feature: 'character_generation',
|
|
2894
|
+
* model: 'gpt-4',
|
|
2895
|
+
* prompt_tokens: 300,
|
|
2896
|
+
* completion_tokens: 200
|
|
2897
|
+
* }
|
|
2898
|
+
* });
|
|
2899
|
+
*
|
|
2900
|
+
* if (result.error) {
|
|
2901
|
+
* console.warn('Token warning:', result.error);
|
|
2902
|
+
* }
|
|
2903
|
+
* console.log(`${result.tokens_remaining} tokens remaining`);
|
|
2904
|
+
* ```
|
|
2905
|
+
*/
|
|
2906
|
+
consume(params: TokenConsumeParams): Promise<TokenConsumeResponse>;
|
|
2907
|
+
/**
|
|
2908
|
+
* Get encrypted OpenAI API key (advanced use case)
|
|
2909
|
+
*
|
|
2910
|
+
* Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
|
|
2911
|
+
* Returns encrypted key that must be decrypted client-side using Fernet.
|
|
2912
|
+
*
|
|
2913
|
+
* See base-tool/src/llm/token-service.ts:99-155 for full implementation example
|
|
2914
|
+
* including client-side decryption with the 'fernet' npm package.
|
|
2915
|
+
*
|
|
2916
|
+
* @returns Encrypted access key and session info
|
|
2917
|
+
* @throws Error if insufficient tokens (< 100)
|
|
2918
|
+
* @example
|
|
2919
|
+
* ```typescript
|
|
2920
|
+
* // Get encrypted key
|
|
2921
|
+
* const access = await client.tokens.getAccessKey();
|
|
2922
|
+
*
|
|
2923
|
+
* // Decrypt using fernet library (see base-tool for full example)
|
|
2924
|
+
* // 1. Derive key from world ID using SHA-256
|
|
2925
|
+
* // 2. Use 'fernet' npm package to decrypt
|
|
2926
|
+
* // 3. Use decrypted OpenAI key for direct API calls
|
|
2927
|
+
* // 4. Report usage with access.session_id
|
|
2928
|
+
*
|
|
2929
|
+
* console.log('Session:', access.session_id);
|
|
2930
|
+
* console.log('Expires:', access.expires_at);
|
|
2931
|
+
* ```
|
|
2932
|
+
*/
|
|
2933
|
+
getAccessKey(): Promise<AccessKeyResponse>;
|
|
2934
|
+
/**
|
|
2935
|
+
* Revoke a specific token session
|
|
2936
|
+
*
|
|
2937
|
+
* Invalidates the session ID obtained from getAccessKey().
|
|
2938
|
+
* Use when cleaning up or on logout.
|
|
2939
|
+
*
|
|
2940
|
+
* @param sessionId - Session ID to revoke
|
|
2941
|
+
* @returns Revocation result
|
|
2942
|
+
* @example
|
|
2943
|
+
* ```typescript
|
|
2944
|
+
* await client.tokens.revokeSession('session-id-here');
|
|
2945
|
+
* ```
|
|
2946
|
+
*/
|
|
2947
|
+
revokeSession(sessionId: string): Promise<RevokeSessionResponse>;
|
|
2948
|
+
/**
|
|
2949
|
+
* Revoke all active sessions (emergency use)
|
|
2950
|
+
*
|
|
2951
|
+
* Invalidates all token sessions for the authenticated user.
|
|
2952
|
+
* Use for security cleanup or when sessions are stuck.
|
|
2953
|
+
*
|
|
2954
|
+
* @returns Revocation result with count of revoked sessions
|
|
2955
|
+
* @example
|
|
2956
|
+
* ```typescript
|
|
2957
|
+
* const result = await client.tokens.revokeAllSessions();
|
|
2958
|
+
* console.log(`Revoked ${result.sessions_revoked} sessions`);
|
|
2959
|
+
* ```
|
|
2960
|
+
*/
|
|
2961
|
+
revokeAllSessions(): Promise<RevokeAllSessionsResponse>;
|
|
2962
|
+
/**
|
|
2963
|
+
* Get public encryption info (no auth required)
|
|
2964
|
+
*
|
|
2965
|
+
* Returns algorithm details and example code for client-side decryption.
|
|
2966
|
+
* Public endpoint - can be called without authentication.
|
|
2967
|
+
*
|
|
2968
|
+
* @returns Encryption algorithm and implementation details
|
|
2969
|
+
* @example
|
|
2970
|
+
* ```typescript
|
|
2971
|
+
* const info = await client.tokens.getEncryptionInfo();
|
|
2972
|
+
* console.log('Algorithm:', info.algorithm);
|
|
2973
|
+
* console.log('Key derivation:', info.key_derivation);
|
|
2974
|
+
* console.log(info.javascript_example);
|
|
2975
|
+
* ```
|
|
2976
|
+
*/
|
|
2977
|
+
getEncryptionInfo(): Promise<EncryptionInfo>;
|
|
2978
|
+
}
|
|
2979
|
+
|
|
2714
2980
|
interface OnlyWorldsConfig {
|
|
2715
2981
|
apiKey: string;
|
|
2716
2982
|
apiPin: string;
|
|
@@ -2742,13 +3008,32 @@ declare class Resource<T, TInput> {
|
|
|
2742
3008
|
update(id: string, data: Partial<TInput>): Promise<T>;
|
|
2743
3009
|
delete(id: string): Promise<void>;
|
|
2744
3010
|
}
|
|
3011
|
+
/**
|
|
3012
|
+
* Special resource class for World endpoint
|
|
3013
|
+
* The /world/ endpoint returns a single World object directly (not paginated)
|
|
3014
|
+
* because API keys are world-scoped (one key = one world)
|
|
3015
|
+
*/
|
|
3016
|
+
declare class WorldResource {
|
|
3017
|
+
private client;
|
|
3018
|
+
constructor(client: OnlyWorldsClient);
|
|
3019
|
+
/**
|
|
3020
|
+
* Get the world associated with the current API key
|
|
3021
|
+
* Returns the world directly (not wrapped in pagination)
|
|
3022
|
+
*/
|
|
3023
|
+
get(): Promise<World>;
|
|
3024
|
+
/**
|
|
3025
|
+
* Update the current world
|
|
3026
|
+
*/
|
|
3027
|
+
update(data: Partial<WorldInput>): Promise<World>;
|
|
3028
|
+
}
|
|
2745
3029
|
/**
|
|
2746
3030
|
* Main OnlyWorlds API client
|
|
2747
3031
|
*/
|
|
2748
3032
|
declare class OnlyWorldsClient {
|
|
2749
3033
|
private baseUrl;
|
|
2750
3034
|
private headers;
|
|
2751
|
-
worlds:
|
|
3035
|
+
worlds: WorldResource;
|
|
3036
|
+
tokens: TokenResource;
|
|
2752
3037
|
abilities: Resource<Ability, AbilityInput>;
|
|
2753
3038
|
characters: Resource<Character, CharacterInput>;
|
|
2754
3039
|
collectives: Resource<Collective, CollectiveInput>;
|
|
@@ -2779,15 +3064,10 @@ declare class OnlyWorldsClient {
|
|
|
2779
3064
|
params?: Record<string, any>;
|
|
2780
3065
|
body?: any;
|
|
2781
3066
|
}): Promise<T>;
|
|
2782
|
-
/**
|
|
2783
|
-
* Get all worlds accessible with current credentials
|
|
2784
|
-
* @deprecated Use client.worlds.list() instead for consistent API
|
|
2785
|
-
*/
|
|
2786
|
-
getWorlds(): Promise<ApiResponse<World>>;
|
|
2787
3067
|
/**
|
|
2788
3068
|
* Helper to convert nested objects to _id/_ids format
|
|
2789
3069
|
*/
|
|
2790
3070
|
static prepareInput<T extends Record<string, any>>(data: T): any;
|
|
2791
3071
|
}
|
|
2792
3072
|
|
|
2793
|
-
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 };
|
|
3073
|
+
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 };
|