@onlyworlds/sdk

OnlyWorlds TypeScript SDK

Type-safe SDK for building applications with the OnlyWorlds API. Access all 22 element types with full TypeScript support.

Installation

npm install @onlyworlds/sdk
# or
yarn add @onlyworlds/sdk

Quick Start

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

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:

// 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:

// 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:

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

// 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

// 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

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:

// 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

// 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:

// 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
• API Reference
• NPM Package
• GitHub