@onlyworlds/sdk 2.1.3 → 2.2.1

package/dist/index.d.mts

@@ -573,265 +573,266 @@ interface Pin extends BaseElement {
     z?: number;
 }
 /**
- * Input types for API requests (using _id and _ids suffixes)
+ * Input types for API requests
+ * Use field names without _id/_ids suffix - prepareRelations() handles conversion
  */
 interface AbilityInput extends Omit<Ability, 'tradition' | 'source' | 'locus' | 'effects' | 'talents' | 'requisites' | 'instruments' | 'systems'> {
-    tradition_id?: string;
-    source_id?: string;
-    locus_id?: string;
-    effects_ids?: string[];
-    talents_ids?: string[];
-    requisites_ids?: string[];
-    instruments_ids?: string[];
-    systems_ids?: string[];
+    tradition?: string;
+    source?: string;
+    locus?: string;
+    effects?: string[];
+    talents?: string[];
+    requisites?: string[];
+    instruments?: string[];
+    systems?: string[];
 }
 interface ObjectInput extends Omit<Object$1, 'parent_object' | 'location' | 'language' | 'materials' | 'technology' | 'effects' | 'abilities' | 'consumes' | 'affinities'> {
-    parent_object_id?: string;
-    location_id?: string;
-    language_id?: string;
-    materials_ids?: string[];
-    technology_ids?: string[];
-    effects_ids?: string[];
-    abilities_ids?: string[];
-    consumes_ids?: string[];
-    affinities_ids?: string[];
+    parent_object?: string;
+    location?: string;
+    language?: string;
+    materials?: string[];
+    technology?: string[];
+    effects?: string[];
+    abilities?: string[];
+    consumes?: string[];
+    affinities?: string[];
 }
 interface CharacterInput extends Omit<Character, 'birthplace' | 'location' | 'species' | 'traits' | 'abilities' | 'languages' | 'objects' | 'institutions' | 'family' | 'friends' | 'rivals'> {
-    birthplace_id?: string;
-    location_id?: string;
-    species_ids?: string[];
-    traits_ids?: string[];
-    abilities_ids?: string[];
-    languages_ids?: string[];
-    objects_ids?: string[];
-    institutions_ids?: string[];
-    family_ids?: string[];
-    friends_ids?: string[];
-    rivals_ids?: string[];
+    birthplace?: string;
+    location?: string;
+    species?: string[];
+    traits?: string[];
+    abilities?: string[];
+    languages?: string[];
+    objects?: string[];
+    institutions?: string[];
+    family?: string[];
+    friends?: string[];
+    rivals?: string[];
 }
 interface CollectiveInput extends Omit<Collective, 'operator' | 'equipment' | 'abilities' | 'symbolism' | 'species' | 'characters' | 'creatures' | 'phenomena'> {
-    operator_id?: string;
-    equipment_ids?: string[];
-    abilities_ids?: string[];
-    symbolism_ids?: string[];
-    species_ids?: string[];
-    characters_ids?: string[];
-    creatures_ids?: string[];
-    phenomena_ids?: string[];
+    operator?: string;
+    equipment?: string[];
+    abilities?: string[];
+    symbolism?: string[];
+    species?: string[];
+    characters?: string[];
+    creatures?: string[];
+    phenomena?: string[];
 }
 interface ConstructInput extends Omit<Construct, 'founder' | 'custodian' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs' | 'events' | 'narratives'> {
-    founder_id?: string;
-    custodian_id?: string;
-    characters_ids?: string[];
-    objects_ids?: string[];
-    locations_ids?: string[];
-    species_ids?: string[];
-    creatures_ids?: string[];
-    institutions_ids?: string[];
-    traits_ids?: string[];
-    collectives_ids?: string[];
-    zones_ids?: string[];
-    abilities_ids?: string[];
-    phenomena_ids?: string[];
-    languages_ids?: string[];
-    families_ids?: string[];
-    relations_ids?: string[];
-    titles_ids?: string[];
-    constructs_ids?: string[];
-    events_ids?: string[];
-    narratives_ids?: string[];
+    founder?: string;
+    custodian?: string;
+    characters?: string[];
+    objects?: string[];
+    locations?: string[];
+    species?: string[];
+    creatures?: string[];
+    institutions?: string[];
+    traits?: string[];
+    collectives?: string[];
+    zones?: string[];
+    abilities?: string[];
+    phenomena?: string[];
+    languages?: string[];
+    families?: string[];
+    relations?: string[];
+    titles?: string[];
+    constructs?: string[];
+    events?: string[];
+    narratives?: string[];
 }
 interface CreatureInput extends Omit<Creature, 'location' | 'zone' | 'species' | 'traits' | 'abilities' | 'languages' | 'actions'> {
-    location_id?: string;
-    zone_id?: string;
-    species_ids?: string[];
-    traits_ids?: string[];
-    abilities_ids?: string[];
-    languages_ids?: string[];
-    actions_ids?: string[];
+    location?: string;
+    zone?: string;
+    species?: string[];
+    traits?: string[];
+    abilities?: string[];
+    languages?: string[];
+    actions?: string[];
 }
 interface EventInput extends Omit<Event, 'triggers' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs'> {
-    triggers_ids?: string[];
-    characters_ids?: string[];
-    objects_ids?: string[];
-    locations_ids?: string[];
-    species_ids?: string[];
-    creatures_ids?: string[];
-    institutions_ids?: string[];
-    traits_ids?: string[];
-    collectives_ids?: string[];
-    zones_ids?: string[];
-    abilities_ids?: string[];
-    phenomena_ids?: string[];
-    languages_ids?: string[];
-    families_ids?: string[];
-    relations_ids?: string[];
-    titles_ids?: string[];
-    constructs_ids?: string[];
+    triggers?: string[];
+    characters?: string[];
+    objects?: string[];
+    locations?: string[];
+    species?: string[];
+    creatures?: string[];
+    institutions?: string[];
+    traits?: string[];
+    collectives?: string[];
+    zones?: string[];
+    abilities?: string[];
+    phenomena?: string[];
+    languages?: string[];
+    families?: string[];
+    relations?: string[];
+    titles?: string[];
+    constructs?: string[];
 }
 interface FamilyInput extends Omit<Family, 'traditions' | 'traits' | 'abilities' | 'languages' | 'ancestors' | 'estates' | 'governs' | 'heirlooms' | 'creatures'> {
-    traditions_ids?: string[];
-    traits_ids?: string[];
-    abilities_ids?: string[];
-    languages_ids?: string[];
-    ancestors_ids?: string[];
-    estates_ids?: string[];
-    governs_ids?: string[];
-    heirlooms_ids?: string[];
-    creatures_ids?: string[];
+    traditions?: string[];
+    traits?: string[];
+    abilities?: string[];
+    languages?: string[];
+    ancestors?: string[];
+    estates?: string[];
+    governs?: string[];
+    heirlooms?: string[];
+    creatures?: string[];
 }
 interface InstitutionInput extends Omit<Institution, 'parent_institution' | 'zones' | 'objects' | 'creatures' | 'allies' | 'adversaries' | 'constructs'> {
-    parent_institution_id?: string;
-    zones_ids?: string[];
-    objects_ids?: string[];
-    creatures_ids?: string[];
-    allies_ids?: string[];
-    adversaries_ids?: string[];
-    constructs_ids?: string[];
+    parent_institution?: string;
+    zones?: string[];
+    objects?: string[];
+    creatures?: string[];
+    allies?: string[];
+    adversaries?: string[];
+    constructs?: string[];
 }
 interface LanguageInput extends Omit<Language, 'classification' | 'spread' | 'dialects'> {
-    classification_id?: string;
-    spread_ids?: string[];
-    dialects_ids?: string[];
+    classification?: string;
+    spread?: string[];
+    dialects?: string[];
 }
 interface LawInput extends Omit<Law, 'parent_law' | 'author' | 'penalties' | 'locations' | 'zones' | 'prohibitions' | 'adjudicators' | 'enforcers'> {
-    parent_law_id?: string;
-    author_id?: string;
-    penalties_ids?: string[];
-    locations_ids?: string[];
-    zones_ids?: string[];
-    prohibitions_ids?: string[];
-    adjudicators_ids?: string[];
-    enforcers_ids?: string[];
+    parent_law?: string;
+    author?: string;
+    penalties?: string[];
+    locations?: string[];
+    zones?: string[];
+    prohibitions?: string[];
+    adjudicators?: string[];
+    enforcers?: string[];
 }
 interface LocationInput extends Omit<Location, 'parent_location' | 'primary_power' | 'governing_title' | 'zone' | 'rival' | 'partner' | 'populations' | 'secondary_powers' | 'founders' | 'cults' | 'delicacies' | 'extraction_methods' | 'extraction_goods' | 'industry_methods' | 'industry_goods' | 'extraction_markets' | 'industry_markets' | 'currencies' | 'buildings' | 'building_methods' | 'fighters' | 'defensive_objects'> {
-    parent_location_id?: string;
-    primary_power_id?: string;
-    governing_title_id?: string;
-    zone_id?: string;
-    rival_id?: string;
-    partner_id?: string;
-    populations_ids?: string[];
-    secondary_powers_ids?: string[];
-    founders_ids?: string[];
-    cults_ids?: string[];
-    delicacies_ids?: string[];
-    extraction_methods_ids?: string[];
-    extraction_goods_ids?: string[];
-    industry_methods_ids?: string[];
-    industry_goods_ids?: string[];
-    extraction_markets_ids?: string[];
-    industry_markets_ids?: string[];
-    currencies_ids?: string[];
-    buildings_ids?: string[];
-    building_methods_ids?: string[];
-    fighters_ids?: string[];
-    defensive_objects_ids?: string[];
+    parent_location?: string;
+    primary_power?: string;
+    governing_title?: string;
+    zone?: string;
+    rival?: string;
+    partner?: string;
+    populations?: string[];
+    secondary_powers?: string[];
+    founders?: string[];
+    cults?: string[];
+    delicacies?: string[];
+    extraction_methods?: string[];
+    extraction_goods?: string[];
+    industry_methods?: string[];
+    industry_goods?: string[];
+    extraction_markets?: string[];
+    industry_markets?: string[];
+    currencies?: string[];
+    buildings?: string[];
+    building_methods?: string[];
+    fighters?: string[];
+    defensive_objects?: string[];
 }
 interface PhenomenonInput extends Omit<Phenomenon, 'system' | 'catalysts' | 'empowerments' | 'triggers' | 'wielders' | 'environments'> {
-    system_id?: string;
-    catalysts_ids?: string[];
-    empowerments_ids?: string[];
-    triggers_ids?: string[];
-    wielders_ids?: string[];
-    environments_ids?: string[];
+    system?: string;
+    catalysts?: string[];
+    empowerments?: string[];
+    triggers?: string[];
+    wielders?: string[];
+    environments?: string[];
 }
 interface RelationInput extends Omit<Relation, 'actor' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'titles' | 'constructs' | 'events' | 'narratives'> {
-    actor_id?: string;
-    characters_ids?: string[];
-    objects_ids?: string[];
-    locations_ids?: string[];
-    species_ids?: string[];
-    creatures_ids?: string[];
-    institutions_ids?: string[];
-    traits_ids?: string[];
-    collectives_ids?: string[];
-    zones_ids?: string[];
-    abilities_ids?: string[];
-    phenomena_ids?: string[];
-    languages_ids?: string[];
-    families_ids?: string[];
-    titles_ids?: string[];
-    constructs_ids?: string[];
-    events_ids?: string[];
-    narratives_ids?: string[];
+    actor?: string;
+    characters?: string[];
+    objects?: string[];
+    locations?: string[];
+    species?: string[];
+    creatures?: string[];
+    institutions?: string[];
+    traits?: string[];
+    collectives?: string[];
+    zones?: string[];
+    abilities?: string[];
+    phenomena?: string[];
+    languages?: string[];
+    families?: string[];
+    titles?: string[];
+    constructs?: string[];
+    events?: string[];
+    narratives?: string[];
 }
 interface SpeciesInput extends Omit<Species, 'parent_species' | 'nourishment' | 'reproduction' | 'adaptations' | 'traits' | 'locations' | 'zones' | 'affinities'> {
-    parent_species_id?: string;
-    nourishment_ids?: string[];
-    reproduction_ids?: string[];
-    adaptations_ids?: string[];
-    traits_ids?: string[];
-    locations_ids?: string[];
-    zones_ids?: string[];
-    affinities_ids?: string[];
+    parent_species?: string;
+    nourishment?: string[];
+    reproduction?: string[];
+    adaptations?: string[];
+    traits?: string[];
+    locations?: string[];
+    zones?: string[];
+    affinities?: string[];
 }
 interface ZoneInput extends Omit<Zone, 'phenomena' | 'linked_zones' | 'populations' | 'titles' | 'principles'> {
-    phenomena_ids?: string[];
-    linked_zones_ids?: string[];
-    populations_ids?: string[];
-    titles_ids?: string[];
-    principles_ids?: string[];
+    phenomena?: string[];
+    linked_zones?: string[];
+    populations?: string[];
+    titles?: string[];
+    principles?: string[];
 }
 interface TitleInput extends Omit<Title, 'issuer' | 'body' | 'superior_title' | 'holders' | 'symbols' | 'characters' | 'institutions' | 'families' | 'zones' | 'locations' | 'objects' | 'constructs' | 'laws' | 'collectives' | 'creatures' | 'phenomena' | 'species' | 'languages'> {
-    issuer_id?: string;
-    body_id?: string;
-    superior_title_id?: string;
-    holders_ids?: string[];
-    symbols_ids?: string[];
-    characters_ids?: string[];
-    institutions_ids?: string[];
-    families_ids?: string[];
-    zones_ids?: string[];
-    locations_ids?: string[];
-    objects_ids?: string[];
-    constructs_ids?: string[];
-    laws_ids?: string[];
-    collectives_ids?: string[];
-    creatures_ids?: string[];
-    phenomena_ids?: string[];
-    species_ids?: string[];
-    languages_ids?: string[];
+    issuer?: string;
+    body?: string;
+    superior_title?: string;
+    holders?: string[];
+    symbols?: string[];
+    characters?: string[];
+    institutions?: string[];
+    families?: string[];
+    zones?: string[];
+    locations?: string[];
+    objects?: string[];
+    constructs?: string[];
+    laws?: string[];
+    collectives?: string[];
+    creatures?: string[];
+    phenomena?: string[];
+    species?: string[];
+    languages?: string[];
 }
 interface TraitInput extends Omit<Trait, 'anti_trait' | 'empowered_abilities'> {
-    anti_trait_id?: string;
-    empowered_abilities_ids?: string[];
+    anti_trait?: string;
+    empowered_abilities?: string[];
 }
 interface NarrativeInput extends Omit<Narrative, 'parent_narrative' | 'protagonist' | 'antagonist' | 'narrator' | 'conservator' | 'events' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs' | 'laws'> {
-    parent_narrative_id?: string;
-    protagonist_id?: string;
-    antagonist_id?: string;
-    narrator_id?: string;
-    conservator_id?: string;
-    events_ids?: string[];
-    characters_ids?: string[];
-    objects_ids?: string[];
-    locations_ids?: string[];
-    species_ids?: string[];
-    creatures_ids?: string[];
-    institutions_ids?: string[];
-    traits_ids?: string[];
-    collectives_ids?: string[];
-    zones_ids?: string[];
-    abilities_ids?: string[];
-    phenomena_ids?: string[];
-    languages_ids?: string[];
-    families_ids?: string[];
-    relations_ids?: string[];
-    titles_ids?: string[];
-    constructs_ids?: string[];
-    laws_ids?: string[];
+    parent_narrative?: string;
+    protagonist?: string;
+    antagonist?: string;
+    narrator?: string;
+    conservator?: string;
+    events?: string[];
+    characters?: string[];
+    objects?: string[];
+    locations?: string[];
+    species?: string[];
+    creatures?: string[];
+    institutions?: string[];
+    traits?: string[];
+    collectives?: string[];
+    zones?: string[];
+    abilities?: string[];
+    phenomena?: string[];
+    languages?: string[];
+    families?: string[];
+    relations?: string[];
+    titles?: string[];
+    constructs?: string[];
+    laws?: string[];
 }
 interface MapInput extends Omit<Map, 'parent_map' | 'location'> {
-    parent_map_id?: string;
-    location_id?: string;
+    parent_map?: string;
+    location?: string;
 }
 interface MarkerInput extends Omit<Marker, 'map' | 'zone'> {
-    map_id?: string;
-    zone_id?: string;
+    map?: string;
+    zone?: string;
 }
 interface PinInput extends Omit<Pin, 'map' | 'element_id'> {
-    map_id?: string;
+    map?: string;
     element_id?: string;
 }
 /**
@@ -903,24 +904,6 @@ declare const ONLYWORLDS_VERSION: "00.30.00";
  * Compatible with Google Material Icons font
  */
 declare const ELEMENT_ICONS: Record<ElementType, string>;
-/**
- * Simple Unicode icons for element types
- * Minimalist symbols used as fallbacks
- */
-declare const ELEMENT_UNICODE_ICONS: Record<ElementType, string>;
-/**
- * Get Material Design icon for an element type
- * Returns the uniform monochrome icon used in OnlyWorlds frontend
- * @param elementType The element type
- * @returns Material icon name
- */
-declare function getElementIcon(elementType: ElementType): string;
-/**
- * Get Unicode icon for an element type
- * @param elementType The element type
- * @returns Unicode symbol string
- */
-declare function getElementUnicodeIcon(elementType: ElementType): string;
 /**
  * Field type definitions for OnlyWorlds elements
  */
@@ -3088,9 +3071,40 @@ declare class OnlyWorldsClient {
         body?: any;
     }): Promise<T>;
     /**
-     * Helper to convert nested objects to _id/_ids format
+     * Helper to convert nested objects to _id/_ids format (legacy method)
+     * @deprecated Use prepareRelations instead - it's called automatically in create/update
      */
     static prepareInput<T extends Record<string, any>>(data: T): any;
+    /**
+     * Convert relation fields to API format (_id/_ids suffix)
+     *
+     * The OnlyWorlds API expects:
+     * - single_link fields: fieldname_id (e.g., birthplace_id)
+     * - multi_link fields: fieldname_ids (e.g., species_ids)
+     *
+     * This method auto-converts based on FIELD_SCHEMA:
+     * - { species: ["id1", "id2"] } → { species_ids: ["id1", "id2"] }
+     * - { birthplace: "location-id" } → { birthplace_id: "location-id" }
+     * - { species: [{id: "id1", name: "X"}] } → { species_ids: ["id1"] }
+     *
+     * Called automatically by create() and update() methods.
+     */
+    static prepareRelations<T extends Record<string, any>>(data: T, elementType: string): any;
 }
 
-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 };
+/**
+ * Get Material Design icon name for an element type
+ * Accepts multiple formats: 'character', 'characters', 'Character', etc.
+ *
+ * @param type - Element type in any format (singular, plural, any case)
+ * @returns Material icon name (e.g., 'person', 'castle', 'thunderstorm')
+ *
+ * @example
+ * getElementIcon('character')   // 'person'
+ * getElementIcon('characters')  // 'person'
+ * getElementIcon('Character')   // 'person'
+ * getElementIcon('phenomena')   // 'thunderstorm'
+ */
+declare function getElementIcon(type: string): string;
+
+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, 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 };