@onlyworlds/sdk 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,262 @@
+# OnlyWorlds TypeScript SDK
+
+Type-safe SDK for building applications with the OnlyWorlds API. Access all 22 element types with full TypeScript support.
+
+## Installation
+
+```bash
+npm install @onlyworlds/sdk
+# or
+yarn add @onlyworlds/sdk
+```
+
+## Quick Start
+
+```typescript
+import { OnlyWorldsClient } from '@onlyworlds/sdk';
+
+// Initialize the client
+const client = new OnlyWorldsClient({
+  apiKey: 'your-api-key',
+  apiPin: 'your-api-pin'
+});
+
+// Create a character
+const character = await client.characters.create({
+  name: 'Aragorn',
+  description: 'Heir of Isildur',
+  location_id: 'uuid-of-location',
+  abilities_ids: ['uuid1', 'uuid2']
+});
+
+// List locations with filtering
+const locations = await client.locations.list({
+  search: 'tavern',
+  ordering: '-created_at',
+  limit: 10
+});
+```
+
+## 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:
+
+```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']
+});
+
+// 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 };
+}
+```
+
+#### Search and Filter
+
+```typescript
+// Find all wizards in a specific location
+const wizards = await client.characters.list({
+  search: 'wizard',
+  location: 'location-uuid',
+  ordering: '-level'
+});
+
+// Get recently updated items
+const recent = await client.events.list({
+  ordering: '-updated_at',
+  limit: 5
+});
+```
+
+#### Error Handling
+
+```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:
+
+```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
+}
+```
+
+## Helper Methods
+
+```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'] }
+```
+
+## Requirements
+
+- Node.js 18+ or modern browser with fetch API
+- TypeScript 4.5+ (for TypeScript projects)
+
+## Browser Usage
+
+This SDK works in browsers, but you'll need to handle CORS:
+
+```javascript
+// For development, use a proxy or CORS-enabled server
+// Never expose API credentials in client-side code!
+
+// Better approach: Use a backend proxy
+const response = await fetch('/api/proxy/onlyworlds', {
+  method: 'POST',
+  body: JSON.stringify({ /* your request */ })
+});
+```
+
+## License
+
+MIT
+
+## Links
+
+- [OnlyWorlds Documentation](https://onlyworlds.github.io/)
+- [API Reference](https://www.onlyworlds.com/api/docs)
+- [NPM Package](https://www.npmjs.com/package/@onlyworlds/sdk)
+- [GitHub](https://github.com/onlyworlds/sdk)