@onlyworlds/sdk 2.0.0 → 2.0.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 OnlyWorlds
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024-2025 OnlyWorlds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,14 @@
 # OnlyWorlds TypeScript SDK
 
-Type-safe SDK for building applications with the OnlyWorlds API. Access all 22 element types with full TypeScript support.
+[![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A type-safe TypeScript SDK for building world-building applications with the OnlyWorlds API.
 
 ## Installation
 
 ```bash
 npm install @onlyworlds/sdk
-# or
-yarn add @onlyworlds/sdk
 ```
 
 ## Quick Start
@@ -15,248 +16,109 @@ yarn add @onlyworlds/sdk
 ```typescript
 import { OnlyWorldsClient } from '@onlyworlds/sdk';
 
-// Initialize the client
 const client = new OnlyWorldsClient({
   apiKey: 'your-api-key',
-  apiPin: 'your-api-pin'
+  apiPin: '1234',
+  baseUrl: 'https://onlyworlds.com'
 });
 
-// Create a character
-const character = await client.characters.create({
-  name: 'Aragorn',
-  description: 'Heir of Isildur',
-  location_id: 'uuid-of-location',
-  abilities_ids: ['uuid1', 'uuid2']
-});
+// Fetch characters
+const characters = await client.character.list();
 
-// List locations with filtering
-const locations = await client.locations.list({
-  search: 'tavern',
-  ordering: '-created_at',
-  limit: 10
+// Create a new location
+const location = await client.location.create({
+  name: 'Dragon Peak',
+  description: 'A treacherous mountain peak where dragons nest',
+  supertype: 'mountain',
+  climate: 'cold'
 });
-```
-
-## Features
-
-- 🎯 **Full TypeScript Support** - Complete type definitions for all 22 element types
-- 🔒 **Type Safety** - Separate input/output types handle the `_id`/`_ids` pattern automatically
-- 📦 **All Element Types** - Characters, Locations, Objects, Species, Events, and more
-- 🔗 **Relationship Handling** - Properly typed single and multi-link relationships
-- 🚀 **Simple API** - Intuitive methods for CRUD operations
-- 📄 **Auto-completion** - IDE support for all fields and methods
-
-## Element Types
-
-The SDK supports all 22 OnlyWorlds element types:
-
-- **Beings**: Character, Creature, Collective, Family, Species
-- **Places**: Location, Zone, Map, Pin, Marker
-- **Things**: Object, Construct, Phenomenon
-- **Concepts**: Ability, Event, Institution, Language, Law, Narrative, Relation, Title, Trait
-
-## API Reference
-
-### Client Initialization
-
-```typescript
-import { OnlyWorldsClient } from '@onlyworlds/sdk';
-
-const client = new OnlyWorldsClient({
-  apiKey: 'your-api-key',    // Required
-  apiPin: 'your-api-pin',    // Required
-  baseUrl: 'custom-url'      // Optional, defaults to onlyworlds.com
-});
-```
-
-### CRUD Operations
-
-All element types support the same operations:
-
-```typescript
-// List with filtering
-const items = await client.characters.list({
-  search: 'hero',
-  ordering: 'name',
-  limit: 20,
-  offset: 0
-});
-
-// Get single item
-const character = await client.characters.get('uuid');
-
-// Create new item
-const newChar = await client.characters.create({
-  name: 'Gandalf',
-  description: 'A wizard'
-});
-
-// Update existing item
-const updated = await client.characters.update('uuid', {
-  description: 'A wizard, also known as Mithrandir'
-});
-
-// Delete item
-await client.characters.delete('uuid');
-```
-
-### Working with Relationships
 
-The SDK handles OnlyWorlds' `_id`/`_ids` pattern automatically:
+// Get a specific element
+const character = await client.character.get('element-id');
 
-```typescript
-// Creating with relationships
-const character = await client.characters.create({
-  name: 'Frodo',
-  birthplace_id: 'location-uuid',        // Single relationship
-  abilities_ids: ['uuid1', 'uuid2'],     // Multi relationship
-  friends_ids: ['sam-uuid', 'merry-uuid']
+// Update an element
+await client.character.update('element-id', {
+  name: 'Updated Name'
 });
 
-// The response includes nested objects
-console.log(character.birthplace.name);  // "The Shire"
-console.log(character.abilities[0].name); // "Ring Bearer"
-```
-
-### Type Definitions
-
-All types are exported for your use:
-
-```typescript
-import { 
-  Character, 
-  CharacterInput,
-  Location,
-  ElementType 
-} from '@onlyworlds/sdk';
-
-// Use in your functions
-function createHero(data: CharacterInput): Promise<Character> {
-  return client.characters.create(data);
-}
-
-// Element type enum
-console.log(ElementType.Character); // 'character'
-```
-
-### Advanced Examples
-
-#### Batch Operations
-
-```typescript
-// Create multiple related elements
-async function createParty(partyData: any[]) {
-  const location = await client.locations.create({
-    name: 'Tavern',
-    description: 'Where the party meets'
-  });
-
-  const characters = await Promise.all(
-    partyData.map(data => 
-      client.characters.create({
-        ...data,
-        location_id: location.id
-      })
-    )
-  );
-
-  return { location, characters };
-}
+// Delete an element
+await client.character.delete('element-id');
 ```
 
-#### Search and Filter
+## Features
 
-```typescript
-// Find all wizards in a specific location
-const wizards = await client.characters.list({
-  search: 'wizard',
-  location: 'location-uuid',
-  ordering: '-level'
-});
+- ✅ **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
+- ✅ **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
 
-// Get recently updated items
-const recent = await client.events.list({
-  ordering: '-updated_at',
-  limit: 5
-});
-```
+## Element Types
 
-#### Error Handling
+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
+
+## Type-Safe Relationships
 
 ```typescript
-try {
-  const character = await client.characters.get('invalid-uuid');
-} catch (error) {
-  if (error.message.includes('404')) {
-    console.log('Character not found');
-  }
-}
-```
-
-## Input vs Output Types
-
-OnlyWorlds uses different formats for requests and responses:
-
-- **Input** (requests): Use `_id` for single relationships, `_ids` for multiple
-- **Output** (responses): Nested objects with full data
-
-The SDK provides separate types for each:
+import { ElementId, Character, Location } from '@onlyworlds/sdk';
 
-```typescript
-// CharacterInput for creating/updating
-interface CharacterInput {
-  name: string;
-  location_id?: string;      // UUID string
-  abilities_ids?: string[];  // Array of UUIDs
-}
-
-// Character for responses
-interface Character {
-  name: string;
-  location?: Location;       // Full nested object
-  abilities?: Ability[];     // Array of full objects
-}
+// Branded types ensure you can't mix up element IDs
+const locationId: ElementId<'Location'> = 'some-location-id';
+const character: Character = {
+  name: 'Aragorn',
+  location: locationId  // Type-safe!
+};
 ```
 
-## Helper Methods
+## Documentation
 
-```typescript
-// Convert nested objects to _id/_ids format
-const input = OnlyWorldsClient.prepareInput({
-  name: 'Test',
-  location: { id: 'uuid', name: 'Place' },
-  abilities: [{ id: 'uuid1' }, { id: 'uuid2' }]
-});
-// Result: { name: 'Test', location_id: 'uuid', abilities_ids: ['uuid1', 'uuid2'] }
-```
+For detailed documentation, examples, and API reference, visit:
 
-## Requirements
+📚 **[https://onlyworlds.github.io/](https://onlyworlds.github.io/)**
 
-- Node.js 18+ or modern browser with fetch API
-- TypeScript 4.5+ (for TypeScript projects)
+## API Authentication
 
-## Browser Usage
+Get your API credentials from your OnlyWorlds account:
 
-This SDK works in browsers, but you'll need to handle CORS:
+1. Log in to [onlyworlds.com](https://onlyworlds.com)
+2. Go to your world settings
+3. Copy your API Key and PIN
 
-```javascript
-// For development, use a proxy or CORS-enabled server
-// Never expose API credentials in client-side code!
+## Contributing
 
-// Better approach: Use a backend proxy
-const response = await fetch('/api/proxy/onlyworlds', {
-  method: 'POST',
-  body: JSON.stringify({ /* your request */ })
-});
-```
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details
 
 ## Links
 
-- [OnlyWorlds Documentation](https://onlyworlds.github.io/)
-- [API Reference](https://www.onlyworlds.com/api/docs)
+- [OnlyWorlds Website](https://onlyworlds.com)
+- [Documentation](https://onlyworlds.github.io/)
 - [NPM Package](https://www.npmjs.com/package/@onlyworlds/sdk)
-- [GitHub](https://github.com/onlyworlds/sdk)
+- [Report Issues](https://github.com/OnlyWorlds/sdk/issues)