@onlyworlds/sdk 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -1,3 +1,26 @@
+/**
+ * Modern branded types for type-safe element relationships
+ * Provides compile-time safety while maintaining zero runtime overhead
+ */
+declare const __brand: unique symbol;
+type Brand<B> = {
+    [__brand]: B;
+};
+/**
+ * Branded type for element IDs - ensures type safety for relationships
+ * @template T The element type this ID references
+ */
+type ElementId<T extends ElementType> = string & Brand<T>;
+/**
+ * Branded type for arrays of element IDs
+ * @template T The element type these IDs reference
+ */
+type ElementIds<T extends ElementType> = ElementId<T>[];
+/**
+ * Special type for IDs that can reference ANY element type
+ * Used in cases like Pin.element_type where the target can be any OnlyWorlds element
+ */
+type AnyElementId = ElementId<ElementType>;
 /**
  * Base fields shared by all OnlyWorlds elements
  */
@@ -12,6 +35,41 @@ interface BaseElement {
     created_at?: string;
     updated_at?: string;
 }
+/**
+ * World element type
+ */
+interface World {
+    id?: string;
+    api_key: string;
+    name: string;
+    description?: string;
+    version?: string;
+    image_url?: string;
+    time_format_equivalents?: any[];
+    time_format_names?: any[];
+    time_basic_unit?: string;
+    time_range_min?: number;
+    time_range_max?: number;
+    time_current?: number;
+    user?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * World input type for creation/updates
+ */
+interface WorldInput {
+    name: string;
+    description?: string;
+    version?: string;
+    image_url?: string;
+    time_format_equivalents?: any[];
+    time_format_names?: any[];
+    time_basic_unit?: string;
+    time_range_min?: number;
+    time_range_max?: number;
+    time_current?: number;
+}
 /**
  * Ability element type
  */
@@ -22,22 +80,14 @@ interface Ability extends BaseElement {
     range?: string;
     challenges?: string;
     prevalence?: string;
-    /** Links to Construct */
-    tradition?: string;
-    /** Links to Phenomenon */
-    source?: string;
-    /** Links to Location */
-    locus?: string;
-    /** Links to Phenomenon */
-    effects?: string[];
-    /** Links to Trait */
-    talents?: string[];
-    /** Links to Construct */
-    requisites?: string[];
-    /** Links to Object */
-    instruments?: string[];
-    /** Links to Construct */
-    systems?: string[];
+    tradition?: ElementId<ElementType.Construct>;
+    source?: ElementId<ElementType.Phenomenon>;
+    locus?: ElementId<ElementType.Location>;
+    effects?: ElementIds<ElementType.Phenomenon>;
+    talents?: ElementIds<ElementType.Trait>;
+    requisites?: ElementIds<ElementType.Construct>;
+    instruments?: ElementIds<ElementType.Object>;
+    systems?: ElementIds<ElementType.Construct>;
 }
 /**
  * Object element type
@@ -46,26 +96,17 @@ interface Object$1 extends BaseElement {
     aesthetics?: string;
     weight?: string;
     amount?: string;
-    /** Links to Object */
-    parent_object?: string;
+    parent_object?: ElementId<ElementType.Object>;
     utility?: string;
     origins?: string;
-    /** Links to Location */
-    location?: string;
-    /** Links to Language */
-    language?: string;
-    /** Links to Construct */
-    materials?: string[];
-    /** Links to Construct */
-    technology?: string[];
-    /** Links to Phenomenon */
-    effects?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Construct */
-    consumes?: string[];
-    /** Links to Trait */
-    affinities?: string[];
+    location?: ElementId<ElementType.Location>;
+    language?: ElementId<ElementType.Language>;
+    materials?: ElementIds<ElementType.Construct>;
+    technology?: ElementIds<ElementType.Construct>;
+    effects?: ElementIds<ElementType.Phenomenon>;
+    abilities?: ElementIds<ElementType.Ability>;
+    consumes?: ElementIds<ElementType.Construct>;
+    affinities?: ElementIds<ElementType.Trait>;
 }
 /**
  * Character element type
@@ -78,11 +119,9 @@ interface Character extends BaseElement {
     background?: string;
     motivations?: string;
     birth_date?: string;
-    /** Links to Location */
-    birthplace?: string;
+    birthplace?: ElementId<ElementType.Location>;
     reputation?: string;
-    /** Links to Location */
-    location?: string;
+    location?: ElementId<ElementType.Location>;
     charisma?: string;
     coercion?: string;
     competence?: string;
@@ -97,24 +136,15 @@ interface Character extends BaseElement {
     INT?: string;
     WIS?: string;
     CHA?: string;
-    /** Links to Species */
-    species?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Family */
-    family?: string[];
-    /** Links to Character */
-    friends?: string[];
-    /** Links to Character */
-    rivals?: string[];
+    species?: ElementIds<ElementType.Species>;
+    traits?: ElementIds<ElementType.Trait>;
+    abilities?: ElementIds<ElementType.Ability>;
+    languages?: ElementIds<ElementType.Language>;
+    objects?: ElementIds<ElementType.Object>;
+    institutions?: ElementIds<ElementType.Institution>;
+    family?: ElementIds<ElementType.Family>;
+    friends?: ElementIds<ElementType.Character>;
+    rivals?: ElementIds<ElementType.Character>;
 }
 /**
  * Collective element type
@@ -123,25 +153,17 @@ interface Collective extends BaseElement {
     composition?: string;
     count?: string;
     formation_date?: string;
-    /** Links to Institution */
-    operator?: string;
+    operator?: ElementId<ElementType.Institution>;
     activity?: string;
     disposition?: string;
     state?: string;
-    /** Links to Construct */
-    equipment?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Construct */
-    symbolism?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
+    equipment?: ElementIds<ElementType.Construct>;
+    abilities?: ElementIds<ElementType.Ability>;
+    symbolism?: ElementIds<ElementType.Construct>;
+    species?: ElementIds<ElementType.Species>;
+    characters?: ElementIds<ElementType.Character>;
+    creatures?: ElementIds<ElementType.Creature>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
 }
 /**
  * Construct element type
@@ -153,46 +175,26 @@ interface Construct extends BaseElement {
     reach?: string;
     start_date?: string;
     end_date?: string;
-    /** Links to Character */
-    founder?: string;
-    /** Links to Institution */
-    custodian?: string;
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Collective */
-    collectives?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Family */
-    families?: string[];
-    /** Links to Relation */
-    relations?: string[];
-    /** Links to Title */
-    titles?: string[];
-    /** Links to Construct */
-    constructs?: string[];
-    /** Links to Event */
-    events?: string[];
-    /** Links to Narrative */
-    narratives?: string[];
+    founder?: ElementId<ElementType.Character>;
+    custodian?: ElementId<ElementType.Institution>;
+    characters?: ElementIds<ElementType.Character>;
+    objects?: ElementIds<ElementType.Object>;
+    locations?: ElementIds<ElementType.Location>;
+    species?: ElementIds<ElementType.Species>;
+    creatures?: ElementIds<ElementType.Creature>;
+    institutions?: ElementIds<ElementType.Institution>;
+    traits?: ElementIds<ElementType.Trait>;
+    collectives?: ElementIds<ElementType.Collective>;
+    zones?: ElementIds<ElementType.Zone>;
+    abilities?: ElementIds<ElementType.Ability>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    languages?: ElementIds<ElementType.Language>;
+    families?: ElementIds<ElementType.Family>;
+    relations?: ElementIds<ElementType.Relation>;
+    titles?: ElementIds<ElementType.Title>;
+    constructs?: ElementIds<ElementType.Construct>;
+    events?: ElementIds<ElementType.Event>;
+    narratives?: ElementIds<ElementType.Narrative>;
 }
 /**
  * Creature element type
@@ -205,24 +207,17 @@ interface Creature extends BaseElement {
     demeanor?: string;
     status?: string;
     birth_date?: string;
-    /** Links to Location */
-    location?: string;
-    /** Links to Zone */
-    zone?: string;
+    location?: ElementId<ElementType.Location>;
+    zone?: ElementId<ElementType.Zone>;
     challenge_rating?: string;
     hit_points?: string;
     armor_class?: string;
     speed?: string;
-    /** Links to Species */
-    species?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Ability */
-    actions?: string[];
+    species?: ElementIds<ElementType.Species>;
+    traits?: ElementIds<ElementType.Trait>;
+    abilities?: ElementIds<ElementType.Ability>;
+    languages?: ElementIds<ElementType.Language>;
+    actions?: ElementIds<ElementType.Ability>;
 }
 /**
  * Event element type
@@ -233,40 +228,23 @@ interface Event extends BaseElement {
     consequences?: string;
     start_date?: string;
     end_date?: string;
-    /** Links to Event */
-    triggers?: string[];
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Collective */
-    collectives?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Family */
-    families?: string[];
-    /** Links to Relation */
-    relations?: string[];
-    /** Links to Title */
-    titles?: string[];
-    /** Links to Construct */
-    constructs?: string[];
+    triggers?: ElementIds<ElementType.Event>;
+    characters?: ElementIds<ElementType.Character>;
+    objects?: ElementIds<ElementType.Object>;
+    locations?: ElementIds<ElementType.Location>;
+    species?: ElementIds<ElementType.Species>;
+    creatures?: ElementIds<ElementType.Creature>;
+    institutions?: ElementIds<ElementType.Institution>;
+    traits?: ElementIds<ElementType.Trait>;
+    collectives?: ElementIds<ElementType.Collective>;
+    zones?: ElementIds<ElementType.Zone>;
+    abilities?: ElementIds<ElementType.Ability>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    languages?: ElementIds<ElementType.Language>;
+    families?: ElementIds<ElementType.Family>;
+    relations?: ElementIds<ElementType.Relation>;
+    titles?: ElementIds<ElementType.Title>;
+    constructs?: ElementIds<ElementType.Construct>;
 }
 /**
  * Family element type
@@ -275,24 +253,15 @@ interface Family extends BaseElement {
     spirit?: string;
     history?: string;
     reputation?: string;
-    /** Links to Construct */
-    traditions?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Character */
-    ancestors?: string[];
-    /** Links to Location */
-    estates?: string[];
-    /** Links to Institution */
-    governs?: string[];
-    /** Links to Object */
-    heirlooms?: string[];
-    /** Links to Creature */
-    creatures?: string[];
+    traditions?: ElementIds<ElementType.Construct>;
+    traits?: ElementIds<ElementType.Trait>;
+    abilities?: ElementIds<ElementType.Ability>;
+    languages?: ElementIds<ElementType.Language>;
+    ancestors?: ElementIds<ElementType.Character>;
+    estates?: ElementIds<ElementType.Location>;
+    governs?: ElementIds<ElementType.Institution>;
+    heirlooms?: ElementIds<ElementType.Object>;
+    creatures?: ElementIds<ElementType.Creature>;
 }
 /**
  * Institution element type
@@ -300,21 +269,14 @@ interface Family extends BaseElement {
 interface Institution extends BaseElement {
     doctrine?: string;
     founding_date?: string;
-    /** Links to Institution */
-    parent_institution?: string;
+    parent_institution?: ElementId<ElementType.Institution>;
     status?: string;
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Institution */
-    allies?: string[];
-    /** Links to Institution */
-    adversaries?: string[];
-    /** Links to Construct */
-    constructs?: string[];
+    zones?: ElementIds<ElementType.Zone>;
+    objects?: ElementIds<ElementType.Object>;
+    creatures?: ElementIds<ElementType.Creature>;
+    allies?: ElementIds<ElementType.Institution>;
+    adversaries?: ElementIds<ElementType.Institution>;
+    constructs?: ElementIds<ElementType.Construct>;
 }
 /**
  * Language element type
@@ -324,13 +286,10 @@ interface Language extends BaseElement {
     grammar?: string;
     lexicon?: string;
     writing?: string;
-    /** Links to Construct */
-    classification?: string;
+    classification?: ElementId<ElementType.Construct>;
     status?: string;
-    /** Links to Location */
-    spread?: string[];
-    /** Links to Language */
-    dialects?: string[];
+    spread?: ElementIds<ElementType.Location>;
+    dialects?: ElementIds<ElementType.Language>;
 }
 /**
  * Law element type
@@ -339,22 +298,14 @@ interface Law extends BaseElement {
     declaration?: string;
     purpose?: string;
     date?: string;
-    /** Links to Law */
-    parent_law?: string;
-    /** Links to Institution */
-    author?: string;
-    /** Links to Construct */
-    penalties?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Construct */
-    prohibitions?: string[];
-    /** Links to Title */
-    adjudicators?: string[];
-    /** Links to Title */
-    enforcers?: string[];
+    parent_law?: ElementId<ElementType.Law>;
+    author?: ElementId<ElementType.Institution>;
+    penalties?: ElementIds<ElementType.Construct>;
+    locations?: ElementIds<ElementType.Location>;
+    zones?: ElementIds<ElementType.Zone>;
+    prohibitions?: ElementIds<ElementType.Construct>;
+    adjudicators?: ElementIds<ElementType.Title>;
+    enforcers?: ElementIds<ElementType.Title>;
 }
 /**
  * Location element type
@@ -363,56 +314,34 @@ interface Location extends BaseElement {
     form?: string;
     function?: string;
     founding_date?: string;
-    /** Links to Location */
-    parent_location?: string;
+    parent_location?: ElementId<ElementType.Location>;
     political_climate?: string;
-    /** Links to Institution */
-    primary_power?: string;
-    /** Links to Title */
-    governing_title?: string;
-    /** Links to Zone */
-    zone?: string;
-    /** Links to Location */
-    rival?: string;
-    /** Links to Location */
-    partner?: string;
+    primary_power?: ElementId<ElementType.Institution>;
+    governing_title?: ElementId<ElementType.Title>;
+    zone?: ElementId<ElementType.Zone>;
+    rival?: ElementId<ElementType.Location>;
+    partner?: ElementId<ElementType.Location>;
     customs?: string;
     infrastructure?: string;
     architecture?: string;
     defensibility?: string;
     elevation?: string;
-    /** Links to Collective */
-    populations?: string[];
-    /** Links to Institution */
-    secondary_powers?: string[];
-    /** Links to Character */
-    founders?: string[];
-    /** Links to Construct */
-    cults?: string[];
-    /** Links to Species */
-    delicacies?: string[];
-    /** Links to Construct */
-    extraction_methods?: string[];
-    /** Links to Construct */
-    extraction_goods?: string[];
-    /** Links to Construct */
-    industry_methods?: string[];
-    /** Links to Construct */
-    industry_goods?: string[];
-    /** Links to Location */
-    extraction_markets?: string[];
-    /** Links to Location */
-    industry_markets?: string[];
-    /** Links to Construct */
-    currencies?: string[];
-    /** Links to Object */
-    buildings?: string[];
-    /** Links to Construct */
-    building_methods?: string[];
-    /** Links to Construct */
-    fighters?: string[];
-    /** Links to Object */
-    defensive_objects?: string[];
+    populations?: ElementIds<ElementType.Collective>;
+    secondary_powers?: ElementIds<ElementType.Institution>;
+    founders?: ElementIds<ElementType.Character>;
+    cults?: ElementIds<ElementType.Construct>;
+    delicacies?: ElementIds<ElementType.Species>;
+    extraction_methods?: ElementIds<ElementType.Construct>;
+    extraction_goods?: ElementIds<ElementType.Construct>;
+    industry_methods?: ElementIds<ElementType.Construct>;
+    industry_goods?: ElementIds<ElementType.Construct>;
+    extraction_markets?: ElementIds<ElementType.Location>;
+    industry_markets?: ElementIds<ElementType.Location>;
+    currencies?: ElementIds<ElementType.Construct>;
+    buildings?: ElementIds<ElementType.Object>;
+    building_methods?: ElementIds<ElementType.Construct>;
+    fighters?: ElementIds<ElementType.Construct>;
+    defensive_objects?: ElementIds<ElementType.Object>;
 }
 /**
  * Phenomenon element type
@@ -422,18 +351,12 @@ interface Phenomenon extends BaseElement {
     effects?: string;
     duration?: string;
     mythology?: string;
-    /** Links to Phenomenon */
-    system?: string;
-    /** Links to Object */
-    catalysts?: string[];
-    /** Links to Ability */
-    empowerments?: string[];
-    /** Links to Construct */
-    triggers?: string[];
-    /** Links to Character */
-    wielders?: string[];
-    /** Links to Location */
-    environments?: string[];
+    system?: ElementId<ElementType.Phenomenon>;
+    catalysts?: ElementIds<ElementType.Object>;
+    empowerments?: ElementIds<ElementType.Ability>;
+    triggers?: ElementIds<ElementType.Construct>;
+    wielders?: ElementIds<ElementType.Character>;
+    environments?: ElementIds<ElementType.Location>;
 }
 /**
  * Relation element type
@@ -443,42 +366,24 @@ interface Relation extends BaseElement {
     start_date?: string;
     end_date?: string;
     intensity?: string;
-    /** Links to Character */
-    actor?: string;
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Collective */
-    collectives?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Family */
-    families?: string[];
-    /** Links to Title */
-    titles?: string[];
-    /** Links to Construct */
-    constructs?: string[];
-    /** Links to Event */
-    events?: string[];
-    /** Links to Narrative */
-    narratives?: string[];
+    actor?: ElementId<ElementType.Character>;
+    characters?: ElementIds<ElementType.Character>;
+    objects?: ElementIds<ElementType.Object>;
+    locations?: ElementIds<ElementType.Location>;
+    species?: ElementIds<ElementType.Species>;
+    creatures?: ElementIds<ElementType.Creature>;
+    institutions?: ElementIds<ElementType.Institution>;
+    traits?: ElementIds<ElementType.Trait>;
+    collectives?: ElementIds<ElementType.Collective>;
+    zones?: ElementIds<ElementType.Zone>;
+    abilities?: ElementIds<ElementType.Ability>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    languages?: ElementIds<ElementType.Language>;
+    families?: ElementIds<ElementType.Family>;
+    titles?: ElementIds<ElementType.Title>;
+    constructs?: ElementIds<ElementType.Construct>;
+    events?: ElementIds<ElementType.Event>;
+    narratives?: ElementIds<ElementType.Narrative>;
 }
 /**
  * Species element type
@@ -493,22 +398,14 @@ interface Species extends BaseElement {
     communication?: string;
     aggression?: string;
     role?: string;
-    /** Links to Species */
-    parent_species?: string;
-    /** Links to Species */
-    nourishment?: string[];
-    /** Links to Construct */
-    reproduction?: string[];
-    /** Links to Ability */
-    adaptations?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Phenomenon */
-    affinities?: string[];
+    parent_species?: ElementId<ElementType.Species>;
+    nourishment?: ElementIds<ElementType.Species>;
+    reproduction?: ElementIds<ElementType.Construct>;
+    adaptations?: ElementIds<ElementType.Ability>;
+    traits?: ElementIds<ElementType.Trait>;
+    locations?: ElementIds<ElementType.Location>;
+    zones?: ElementIds<ElementType.Zone>;
+    affinities?: ElementIds<ElementType.Phenomenon>;
 }
 /**
  * Zone element type
@@ -518,16 +415,11 @@ interface Zone extends BaseElement {
     start_date?: string;
     end_date?: string;
     context?: string;
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Zone */
-    linked_zones?: string[];
-    /** Links to Collective */
-    populations?: string[];
-    /** Links to Title */
-    titles?: string[];
-    /** Links to Construct */
-    principles?: string[];
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    linked_zones?: ElementIds<ElementType.Zone>;
+    populations?: ElementIds<ElementType.Collective>;
+    titles?: ElementIds<ElementType.Title>;
+    principles?: ElementIds<ElementType.Construct>;
 }
 /**
  * Title element type
@@ -537,44 +429,26 @@ interface Title extends BaseElement {
     eligibility?: string;
     grant_date?: string;
     revoke_date?: string;
-    /** Links to Institution */
-    issuer?: string;
-    /** Links to Institution */
-    body?: string;
-    /** Links to Title */
-    superior_title?: string;
+    issuer?: ElementId<ElementType.Institution>;
+    body?: ElementId<ElementType.Institution>;
+    superior_title?: ElementId<ElementType.Title>;
     status?: string;
     history?: string;
-    /** Links to Character */
-    holders?: string[];
-    /** Links to Object */
-    symbols?: string[];
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Family */
-    families?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Construct */
-    constructs?: string[];
-    /** Links to Law */
-    laws?: string[];
-    /** Links to Collective */
-    collectives?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Language */
-    languages?: string[];
+    holders?: ElementIds<ElementType.Character>;
+    symbols?: ElementIds<ElementType.Object>;
+    characters?: ElementIds<ElementType.Character>;
+    institutions?: ElementIds<ElementType.Institution>;
+    families?: ElementIds<ElementType.Family>;
+    zones?: ElementIds<ElementType.Zone>;
+    locations?: ElementIds<ElementType.Location>;
+    objects?: ElementIds<ElementType.Object>;
+    constructs?: ElementIds<ElementType.Construct>;
+    laws?: ElementIds<ElementType.Law>;
+    collectives?: ElementIds<ElementType.Collective>;
+    creatures?: ElementIds<ElementType.Creature>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    species?: ElementIds<ElementType.Species>;
+    languages?: ElementIds<ElementType.Language>;
 }
 /**
  * Trait element type
@@ -592,10 +466,8 @@ interface Trait extends BaseElement {
     creativity?: string;
     courage?: string;
     significance?: string;
-    /** Links to Trait */
-    anti_trait?: string;
-    /** Links to Ability */
-    empowered_abilities?: string[];
+    anti_trait?: ElementId<ElementType.Trait>;
+    empowered_abilities?: ElementIds<ElementType.Ability>;
 }
 /**
  * Narrative element type
@@ -606,52 +478,29 @@ interface Narrative extends BaseElement {
     start_date?: string;
     end_date?: string;
     order?: string;
-    /** Links to Narrative */
-    parent_narrative?: string;
-    /** Links to Character */
-    protagonist?: string;
-    /** Links to Character */
-    antagonist?: string;
-    /** Links to Character */
-    narrator?: string;
-    /** Links to Institution */
-    conservator?: string;
-    /** Links to Event */
-    events?: string[];
-    /** Links to Character */
-    characters?: string[];
-    /** Links to Object */
-    objects?: string[];
-    /** Links to Location */
-    locations?: string[];
-    /** Links to Species */
-    species?: string[];
-    /** Links to Creature */
-    creatures?: string[];
-    /** Links to Institution */
-    institutions?: string[];
-    /** Links to Trait */
-    traits?: string[];
-    /** Links to Collective */
-    collectives?: string[];
-    /** Links to Zone */
-    zones?: string[];
-    /** Links to Ability */
-    abilities?: string[];
-    /** Links to Phenomenon */
-    phenomena?: string[];
-    /** Links to Language */
-    languages?: string[];
-    /** Links to Family */
-    families?: string[];
-    /** Links to Relation */
-    relations?: string[];
-    /** Links to Title */
-    titles?: string[];
-    /** Links to Construct */
-    constructs?: string[];
-    /** Links to Law */
-    laws?: string[];
+    parent_narrative?: ElementId<ElementType.Narrative>;
+    protagonist?: ElementId<ElementType.Character>;
+    antagonist?: ElementId<ElementType.Character>;
+    narrator?: ElementId<ElementType.Character>;
+    conservator?: ElementId<ElementType.Institution>;
+    events?: ElementIds<ElementType.Event>;
+    characters?: ElementIds<ElementType.Character>;
+    objects?: ElementIds<ElementType.Object>;
+    locations?: ElementIds<ElementType.Location>;
+    species?: ElementIds<ElementType.Species>;
+    creatures?: ElementIds<ElementType.Creature>;
+    institutions?: ElementIds<ElementType.Institution>;
+    traits?: ElementIds<ElementType.Trait>;
+    collectives?: ElementIds<ElementType.Collective>;
+    zones?: ElementIds<ElementType.Zone>;
+    abilities?: ElementIds<ElementType.Ability>;
+    phenomena?: ElementIds<ElementType.Phenomenon>;
+    languages?: ElementIds<ElementType.Language>;
+    families?: ElementIds<ElementType.Family>;
+    relations?: ElementIds<ElementType.Relation>;
+    titles?: ElementIds<ElementType.Title>;
+    constructs?: ElementIds<ElementType.Construct>;
+    laws?: ElementIds<ElementType.Law>;
 }
 /**
  * Map element type
@@ -662,19 +511,15 @@ interface Map extends BaseElement {
     width?: string;
     height?: string;
     depth?: string;
-    /** Links to Map */
-    parent_map?: string;
-    /** Links to Location */
-    location?: string;
+    parent_map?: ElementId<ElementType.Map>;
+    location?: ElementId<ElementType.Location>;
 }
 /**
  * Marker element type
  */
 interface Marker extends BaseElement {
-    /** Links to Map */
-    map?: string;
-    /** Links to Zone */
-    zone?: string;
+    map?: ElementId<ElementType.Map>;
+    zone?: ElementId<ElementType.Zone>;
     x?: string;
     y?: string;
     z?: string;
@@ -683,10 +528,9 @@ interface Marker extends BaseElement {
  * Pin element type
  */
 interface Pin extends BaseElement {
-    /** Links to Map */
-    map?: string;
-    /** Links to ContentType */
-    element_type?: string;
+    map?: ElementId<ElementType.Map>;
+    element_type?: ElementType;
+    element_id?: AnyElementId;
     x?: string;
     y?: string;
     z?: string;
@@ -949,9 +793,9 @@ interface MarkerInput extends Omit<Marker, 'map' | 'zone'> {
     map_id?: string;
     zone_id?: string;
 }
-interface PinInput extends Omit<Pin, 'map' | 'element_type'> {
+interface PinInput extends Omit<Pin, 'map' | 'element_id'> {
     map_id?: string;
-    element_type_id?: string;
+    element_id?: string;
 }
 /**
  * All available element types in OnlyWorlds
@@ -980,6 +824,293 @@ declare enum ElementType {
     Trait = "trait",
     Zone = "zone"
 }
+/**
+ * Runtime metadata for field relationships - enables tooling and dynamic processing
+ * Maps element types to their field relationships for runtime introspection
+ */
+declare const FIELD_MAPPINGS: {
+    readonly ability: {
+        readonly tradition: "construct";
+        readonly source: "phenomenon";
+        readonly locus: "location";
+        readonly effects: "phenomenon";
+        readonly talents: "trait";
+        readonly requisites: "construct";
+        readonly instruments: "object";
+        readonly systems: "construct";
+    };
+    readonly character: {
+        readonly birthplace: "location";
+        readonly location: "location";
+        readonly species: "species";
+        readonly traits: "trait";
+        readonly abilities: "ability";
+        readonly languages: "language";
+        readonly objects: "object";
+        readonly institutions: "institution";
+        readonly family: "family";
+        readonly friends: "character";
+        readonly rivals: "character";
+    };
+    readonly collective: {
+        readonly operator: "institution";
+        readonly equipment: "construct";
+        readonly abilities: "ability";
+        readonly symbolism: "construct";
+        readonly species: "species";
+        readonly characters: "character";
+        readonly creatures: "creature";
+        readonly phenomena: "phenomenon";
+    };
+    readonly construct: {
+        readonly founder: "character";
+        readonly custodian: "institution";
+        readonly characters: "character";
+        readonly objects: "object";
+        readonly locations: "location";
+        readonly species: "species";
+        readonly creatures: "creature";
+        readonly institutions: "institution";
+        readonly traits: "trait";
+        readonly collectives: "collective";
+        readonly zones: "zone";
+        readonly abilities: "ability";
+        readonly phenomena: "phenomenon";
+        readonly languages: "language";
+        readonly families: "family";
+        readonly relations: "relation";
+        readonly titles: "title";
+        readonly constructs: "construct";
+        readonly events: "event";
+        readonly narratives: "narrative";
+    };
+    readonly creature: {
+        readonly location: "location";
+        readonly zone: "zone";
+        readonly species: "species";
+        readonly traits: "trait";
+        readonly abilities: "ability";
+        readonly languages: "language";
+        readonly actions: "ability";
+    };
+    readonly event: {
+        readonly triggers: "event";
+        readonly characters: "character";
+        readonly objects: "object";
+        readonly locations: "location";
+        readonly species: "species";
+        readonly creatures: "creature";
+        readonly institutions: "institution";
+        readonly traits: "trait";
+        readonly collectives: "collective";
+        readonly zones: "zone";
+        readonly abilities: "ability";
+        readonly phenomena: "phenomenon";
+        readonly languages: "language";
+        readonly families: "family";
+        readonly relations: "relation";
+        readonly titles: "title";
+        readonly constructs: "construct";
+    };
+    readonly family: {
+        readonly traditions: "construct";
+        readonly traits: "trait";
+        readonly abilities: "ability";
+        readonly languages: "language";
+        readonly ancestors: "character";
+        readonly estates: "location";
+        readonly governs: "institution";
+        readonly heirlooms: "object";
+        readonly creatures: "creature";
+    };
+    readonly institution: {
+        readonly parent_institution: "institution";
+        readonly zones: "zone";
+        readonly objects: "object";
+        readonly creatures: "creature";
+        readonly allies: "institution";
+        readonly adversaries: "institution";
+        readonly constructs: "construct";
+    };
+    readonly language: {
+        readonly classification: "construct";
+        readonly spread: "location";
+        readonly dialects: "language";
+    };
+    readonly law: {
+        readonly parent_law: "law";
+        readonly author: "institution";
+        readonly penalties: "construct";
+        readonly locations: "location";
+        readonly zones: "zone";
+        readonly prohibitions: "construct";
+        readonly adjudicators: "title";
+        readonly enforcers: "title";
+    };
+    readonly location: {
+        readonly parent_location: "location";
+        readonly primary_power: "institution";
+        readonly governing_title: "title";
+        readonly zone: "zone";
+        readonly rival: "location";
+        readonly partner: "location";
+        readonly populations: "collective";
+        readonly secondary_powers: "institution";
+        readonly founders: "character";
+        readonly cults: "construct";
+        readonly delicacies: "species";
+        readonly extraction_methods: "construct";
+        readonly extraction_goods: "construct";
+        readonly industry_methods: "construct";
+        readonly industry_goods: "construct";
+        readonly extraction_markets: "location";
+        readonly industry_markets: "location";
+        readonly currencies: "construct";
+        readonly buildings: "object";
+        readonly building_methods: "construct";
+        readonly fighters: "construct";
+        readonly defensive_objects: "object";
+    };
+    readonly map: {
+        readonly parent_map: "map";
+        readonly location: "location";
+    };
+    readonly marker: {
+        readonly map: "map";
+        readonly zone: "zone";
+    };
+    readonly narrative: {
+        readonly parent_narrative: "narrative";
+        readonly protagonist: "character";
+        readonly antagonist: "character";
+        readonly narrator: "character";
+        readonly conservator: "institution";
+        readonly events: "event";
+        readonly characters: "character";
+        readonly objects: "object";
+        readonly locations: "location";
+        readonly species: "species";
+        readonly creatures: "creature";
+        readonly institutions: "institution";
+        readonly traits: "trait";
+        readonly collectives: "collective";
+        readonly zones: "zone";
+        readonly abilities: "ability";
+        readonly phenomena: "phenomenon";
+        readonly languages: "language";
+        readonly families: "family";
+        readonly relations: "relation";
+        readonly titles: "title";
+        readonly constructs: "construct";
+        readonly laws: "law";
+    };
+    readonly object: {
+        readonly parent_object: "object";
+        readonly location: "location";
+        readonly language: "language";
+        readonly materials: "construct";
+        readonly technology: "construct";
+        readonly effects: "phenomenon";
+        readonly abilities: "ability";
+        readonly consumes: "construct";
+        readonly affinities: "trait";
+    };
+    readonly phenomenon: {
+        readonly system: "phenomenon";
+        readonly catalysts: "object";
+        readonly empowerments: "ability";
+        readonly triggers: "construct";
+        readonly wielders: "character";
+        readonly environments: "location";
+    };
+    readonly pin: {
+        readonly map: "map";
+        readonly element_id: "any_element";
+    };
+    readonly relation: {
+        readonly actor: "character";
+        readonly characters: "character";
+        readonly objects: "object";
+        readonly locations: "location";
+        readonly species: "species";
+        readonly creatures: "creature";
+        readonly institutions: "institution";
+        readonly traits: "trait";
+        readonly collectives: "collective";
+        readonly zones: "zone";
+        readonly abilities: "ability";
+        readonly phenomena: "phenomenon";
+        readonly languages: "language";
+        readonly families: "family";
+        readonly titles: "title";
+        readonly constructs: "construct";
+        readonly events: "event";
+        readonly narratives: "narrative";
+    };
+    readonly species: {
+        readonly parent_species: "species";
+        readonly nourishment: "species";
+        readonly reproduction: "construct";
+        readonly adaptations: "ability";
+        readonly traits: "trait";
+        readonly locations: "location";
+        readonly zones: "zone";
+        readonly affinities: "phenomenon";
+    };
+    readonly title: {
+        readonly issuer: "institution";
+        readonly body: "institution";
+        readonly superior_title: "title";
+        readonly holders: "character";
+        readonly symbols: "object";
+        readonly characters: "character";
+        readonly institutions: "institution";
+        readonly families: "family";
+        readonly zones: "zone";
+        readonly locations: "location";
+        readonly objects: "object";
+        readonly constructs: "construct";
+        readonly laws: "law";
+        readonly collectives: "collective";
+        readonly creatures: "creature";
+        readonly phenomena: "phenomenon";
+        readonly species: "species";
+        readonly languages: "language";
+    };
+    readonly trait: {
+        readonly anti_trait: "trait";
+        readonly empowered_abilities: "ability";
+    };
+    readonly zone: {
+        readonly phenomena: "phenomenon";
+        readonly linked_zones: "zone";
+        readonly populations: "collective";
+        readonly titles: "title";
+        readonly principles: "construct";
+    };
+};
+/**
+ * Type for the field mappings - enables type-safe access to relationship metadata
+ */
+type FieldMappingsType = typeof FIELD_MAPPINGS;
+/**
+ * Creates a typed element ID from a string
+ * @param id The string ID to brand
+ * @returns Branded ElementId
+ */
+declare function createElementId<T extends ElementType>(id: string): ElementId<T>;
+/**
+ * Creates typed element IDs array from string array
+ * @param ids The string IDs to brand
+ * @returns Branded ElementIds array
+ */
+declare function createElementIds<T extends ElementType>(ids: string[]): ElementIds<T>;
+/**
+ * Creates an AnyElementId that can reference any element type
+ * @param id The string ID to brand
+ * @returns AnyElementId
+ */
+declare function createAnyElementId(id: string): AnyElementId;
 
 interface OnlyWorldsConfig {
     apiKey: string;
@@ -1018,6 +1149,7 @@ declare class Resource<T, TInput> {
 declare class OnlyWorldsClient {
     private baseUrl;
     private headers;
+    worlds: Resource<World, WorldInput>;
     abilities: Resource<Ability, AbilityInput>;
     characters: Resource<Character, CharacterInput>;
     collectives: Resource<Collective, CollectiveInput>;
@@ -1050,12 +1182,13 @@ declare class OnlyWorldsClient {
     }): Promise<T>;
     /**
      * Get all worlds accessible with current credentials
+     * @deprecated Use client.worlds.list() instead for consistent API
      */
-    getWorlds(): Promise<any>;
+    getWorlds(): Promise<ApiResponse<World>>;
     /**
      * Helper to convert nested objects to _id/_ids format
      */
     static prepareInput<T extends Record<string, any>>(data: T): any;
 }
 
-export { type Ability, type AbilityInput, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ElementType, type Event, type EventInput, type Family, type FamilyInput, 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, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type Species, type SpeciesInput, type Title, type TitleInput, type Trait, type TraitInput, type Zone, type ZoneInput };
+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, type ElementId, type ElementIds, ElementType, type Event, type EventInput, FIELD_MAPPINGS, type Family, type FamilyInput, type FieldMappingsType, 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, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type Species, type SpeciesInput, type Title, type TitleInput, type Trait, type TraitInput, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds };