promiscuity/microservices/InventoryApi/README.md

InventoryApi

Purpose

Owns item-instance state.

This service should answer:

• what item records currently belong to a character, location, or other container owner
• where each item currently is
• whether an item move, split, merge, equip, or consume action is valid
• which specific item instance is being traded, auctioned, or transferred

This service should not own:

• auth/token issuance
• character identity creation
• location generation
• auction bidding logic

Ownership model

• every inventory record has an ownerType and ownerId
• USER can read and mutate items owned by their own characters
• USER can read and mutate location/container items only when gameplay rules allow it
• SUPER can read and mutate any inventory item
• access should be resolved through the current owner, not from the item id alone

Initial design

Use one MongoDB document per inventory item record.

Practical interpretation:

• non-stackable items: one document per item instance
• stackable items: one document per stack

Reasons:

• every item or stack gets a stable UUID, which is useful for auctions, trade, mail, and auditing
• ownership transfer is explicit and cheap: update ownerType, ownerId, and slot fields
• future item metadata like durability, rarity rolls, or provenance can live on the item document
• auction listings can point to specific item ids instead of vague stack descriptions

Tradeoffs:

• inventory reads are queries over many documents instead of one aggregate read
• stack merging and slot enforcement need careful indexes and mutation logic
• transfers should use transactions when they touch multiple item documents

Suggested endpoints

• GET /api/inventory/by-owner/{ownerType}/{ownerId} Return all item records currently owned by that container owner.
• POST /api/inventory/by-owner/{ownerType}/{ownerId}/grant Create a new item record or add quantity into an existing compatible stack.
• POST /api/inventory/by-owner/{ownerType}/{ownerId}/move Move an item or stack within the same owner inventory.
• POST /api/inventory/transfer Move quantity from one owner inventory to another.
• POST /api/inventory/items/{itemId}/consume Consume quantity from a specific item record.
• POST /api/inventory/items/{itemId}/equip Equip a specific item into a character equipment slot.
• POST /api/inventory/items/{itemId}/unequip Return an equipped item to a character inventory slot.

Notes:

• equip and unequip only make sense for character-owned items
• transfer is the core world interaction primitive for looting, dropping, trading, chest interaction, and auction handoff
• a future AuctionApi can reserve or re-own specific item ids without redesigning InventoryApi

Item identity

Every inventory record should have a stable UUID string such as:

• a8d4218b-5e20-4e47-8b5f-0f0f0b9d7e10

Each record also carries an itemKey such as:

• wood
• stone
• pistol
• small_health_potion

Recommended distinction:

• id: unique item-record identifier used for ownership changes, auctions, and references
• itemKey: item definition identifier used to decide stackability and gameplay behavior

Recommended stored shape

Each item document should include:

• id
• itemKey
• quantity
• ownerType
• ownerId
• slot
• equippedSlot
• ownerUserId when applicable
• createdUtc
• updatedUtc

Optional future fields:

• durability
• rarity
• instanceData
• listingId
• reservedUntilUtc

MVP rules

• an item record must belong to exactly one owner at a time
• stackable items may share itemKey but should still be represented by one stack record per occupied slot
• non-stackable items must always have quantity = 1
• equipped items should set equippedSlot and clear slot
• unequipped bag items should set slot and clear equippedSlot
• slot occupancy must be unique per (ownerType, ownerId, slot)
• all mutating endpoints should be idempotent where practical

Client shape

The Godot client should fetch all items for the currently relevant owner and group them into a bag view locally.

Good pattern:

• login/select character
• GET /api/inventory/by-owner/character/{characterId}
• when opening a stash or world container: GET /api/inventory/by-owner/location/{locationId}
• cache the returned item records locally
• call transfer/equip/consume endpoints using specific itemId values
• replace local state with the server response after each mutation