@nostr-games/inventory 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,744 @@
+/**
+ * Minimal structural type compatible with a signed Nostr event.
+ *
+ * We intentionally define this locally instead of depending on a full Nostr
+ * library. Any object that structurally matches this shape (for example, the
+ * event type from `nostr-tools`) is accepted.
+ */
+interface NostrEvent {
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig?: string;
+    id?: string;
+}
+/**
+ * An unsigned event template as produced by the builders in this library.
+ *
+ * Builders never create `id` or `sig` and never sign anything. The template is
+ * intended to be passed to a signer / relay client by the consuming
+ * application.
+ *
+ * `pubkey` and `created_at` are intentionally omitted: they are added by the
+ * signing/publishing layer, which is out of scope for this library.
+ */
+interface UnsignedEventTemplate<K extends number = number> {
+    kind: K;
+    content: string;
+    tags: string[][];
+}
+
+/**
+ * Kind numbers defined by this library.
+ *
+ * - {@link KIND_GAME_ITEM_DEFINITION} (31632): Game Item Definition.
+ * - {@link KIND_GAME_INVENTORY} (31633): Game Inventory.
+ */
+declare const KIND_GAME_ITEM_DEFINITION: 31632;
+declare const KIND_GAME_INVENTORY: 31633;
+type KindGameItemDefinition = typeof KIND_GAME_ITEM_DEFINITION;
+type KindGameInventory = typeof KIND_GAME_INVENTORY;
+
+/**
+ * Parsing modes shared across the library.
+ *
+ * - `permissive` (default): follow the "SHOULD tolerate" rules of the specs.
+ *   Invalid tags are ignored, invalid JSON content does not block tag parsing,
+ *   duplicate inventory items resolve using the recommended default strategy.
+ * - `strict`: reject the event when the specs allow rejection (for example
+ *   duplicate inventory item references, or invalid JSON content when JSON is
+ *   required).
+ *
+ * "MUST reject" rules (wrong kind, missing/empty `d`, missing required item
+ * definition tags) apply in both modes.
+ */
+type ParseMode = "permissive" | "strict";
+/**
+ * A recoverable, non-fatal issue detected while parsing.
+ *
+ * Warnings never prevent parsing in permissive mode. They are surfaced so
+ * callers can audit what was ignored or coerced.
+ */
+interface ParseWarning {
+    /** Machine-readable warning code. */
+    code: ParseWarningCode;
+    /** Human-readable explanation. */
+    message: string;
+    /** The offending tag, when the warning relates to a specific tag. */
+    tag?: string[];
+}
+type ParseWarningCode = "invalid-json-content" | "invalid-item-tag" | "invalid-quantity" | "wrong-referenced-kind" | "malformed-address" | "duplicate-item" | "invalid-grant-tag" | "empty-required-value";
+/**
+ * Structured parse result.
+ *
+ * `ok: true` means a usable value was produced (possibly with warnings about
+ * ignored tags). `ok: false` means the event was rejected as invalid for this
+ * kind.
+ */
+type ParseResult<T> = {
+    ok: true;
+    value: T;
+    warnings: ParseWarning[];
+} | {
+    ok: false;
+    error: string;
+    warnings: ParseWarning[];
+};
+
+/**
+ * Helpers for NIP-01 addressable event coordinates of the form:
+ *
+ * ```text
+ * <kind>:<pubkey>:<d-tag>
+ * ```
+ *
+ * IMPORTANT: the `d-tag` may itself contain `:` characters. The recommended
+ * `d` format in kind:31632 is `<namespace>:<category>:<slug>` (for example
+ * `blobbi:food:carrot`), which means a full address such as
+ * `31632:pubkey123:blobbi:food:carrot` has more than three colon-separated
+ * segments. Address parsing therefore splits only on the first two colons and
+ * treats everything after the second colon as the `d-tag`.
+ */
+interface AddressableEventAddress {
+    kind: number;
+    pubkey: string;
+    identifier: string;
+}
+/**
+
+ * Options controlling how strict pubkey validation is.
+ *
+ * Placeholder pubkeys are accepted by default to support fixtures, drafts,
+ * and permissive parsing. Consumers may enable canonical 64-character hex
+ * validation.
+ *
+ * - By default, only a non-empty pubkey segment is required.
+ * - When `requireHexPubkey` is `true`, the pubkey must be a 64-character
+ *   lowercase hexadecimal string, which is the canonical Nostr pubkey form.
+ */
+interface AddressParseOptions {
+    requireHexPubkey?: boolean;
+}
+/**
+ * Build an addressable event coordinate string.
+ *
+ * @throws if any component is invalid (empty pubkey/identifier or non-integer
+ * kind). Builders in this library validate their inputs before calling this,
+ * so a throw here indicates a programming error rather than bad user data.
+ */
+declare function buildAddressableEventAddress(kind: number, pubkey: string, identifier: string): string;
+/**
+ * Parse an addressable event coordinate string.
+ *
+ * Returns `null` when the string is not a well-formed `<kind>:<pubkey>:<d>`
+ * coordinate. Everything after the second colon is treated as the identifier
+ * (`d` tag), preserving any colons it contains.
+ */
+declare function parseAddressableEventAddress(address: string, options?: AddressParseOptions): AddressableEventAddress | null;
+
+/**
+ * Return the value of the first tag with the given name, or `undefined` if no
+ * such tag exists or its value slot is missing.
+ */
+declare function getTagValue(tags: string[][], name: string): string | undefined;
+/**
+ * Return all values of tags with the given name (index 1), skipping tags whose
+ * value slot is missing.
+ */
+declare function getTagValues(tags: string[][], name: string): string[];
+/**
+ * Return the `d` tag value of an event or its raw tags.
+ *
+ * Returns `undefined` if there is no `d` tag or its value is missing. Note that
+ * an empty-string `d` value is returned as `""` (the caller decides whether an
+ * empty `d` is acceptable; per both specs it is not).
+ */
+declare function getDTag(source: NostrEvent | string[][]): string | undefined;
+
+/**
+ * Result of attempting to parse a `content` string as JSON.
+ */
+type ContentParseResult = {
+    kind: "empty";
+} | {
+    kind: "json";
+    value: unknown;
+} | {
+    kind: "invalid";
+    raw: string;
+};
+/**
+ * Attempt to parse an event `content` string as JSON without throwing.
+ *
+ * An empty string is treated as {@link ContentParseResult} `empty`, matching
+ * both specifications which allow `content` to be an empty string.
+ *
+ * This never throws: invalid JSON is reported as `invalid` so callers can
+ * decide how to react based on their parse mode.
+ */
+declare function parseContentJson(content: string): ContentParseResult;
+/**
+ * Normalize a `content` input that may be either a preserialized string or a
+ * value to be JSON-serialized.
+ *
+ * - `undefined` -> `""` (the spec default for both kinds).
+ * - `string` -> returned as-is (the caller is responsible for its validity).
+ * - anything else -> `JSON.stringify`.
+ *
+ * This function always either returns a valid string or throws; it never
+ * returns `undefined`. `JSON.stringify` returns `undefined` for values that
+ * are not JSON-serializable (for example `function`, `symbol`, or a top-level
+ * `undefined` reached via another path), and throws on circular references. In
+ * both cases a clear error is raised.
+ *
+ * @throws {Error} when the value is not JSON-serializable (including circular
+ * references).
+ */
+declare function serializeContent(content: unknown): string;
+
+/**
+ * A derivation reference declared with an `a` tag marked `based_on`.
+ */
+interface GameItemBasedOnReference {
+    /** The referenced `31632:<pubkey>:<d>` address (as written in the tag). */
+    address: string;
+    /** Relay URL hint, or `""` when unknown. */
+    relay: string;
+}
+/**
+ * A parsed kind:31632 Game Item Definition.
+ *
+ * Tags are the source of truth. `content` holds the raw content string; parsed
+ * JSON is exposed separately via {@link GameItemDefinition.contentJson}.
+ */
+interface GameItemDefinition {
+    /** The `d` tag value (item identifier). */
+    id: string;
+    /** The full addressable coordinate `31632:<pubkey>:<d>`. */
+    address: string;
+    /** The event author / item issuer. */
+    issuer: string;
+    kind: KindGameItemDefinition;
+    /** Required `name` tag. */
+    name: string;
+    /** Required `type` tag. */
+    type: string;
+    /** Optional `category` tag. */
+    category?: string;
+    /** Optional `image` tag. */
+    image?: string;
+    /** Optional `model_3d` tag. */
+    model3d?: string;
+    /** Optional `audio` tag. */
+    audio?: string;
+    /** Optional `symbol` tag. */
+    symbol?: string;
+    /** Optional `rarity` tag. */
+    rarity?: string;
+    /** Optional `max_stack` tag, kept as the raw string per the spec. */
+    maxStack?: string;
+    /** Optional `version` tag. */
+    version?: string;
+    /** Optional `alt` tag. */
+    alt?: string;
+    /** All `context` tag values (repeatable). */
+    contexts: string[];
+    /** All `t` topic tag values (repeatable). */
+    topics: string[];
+    /** All `based_on` derivation references (repeatable). */
+    basedOn: GameItemBasedOnReference[];
+    /** Raw `content` string, preserved exactly as received. */
+    content: string;
+    /**
+     * Parsed content JSON, when `content` was non-empty valid JSON. `undefined`
+     * when content is empty or (in permissive mode) invalid JSON.
+     */
+    contentJson?: unknown;
+    /** The original event this definition was parsed from. */
+    event: NostrEvent;
+}
+/**
+ * Input for building a kind:31632 event template.
+ *
+ * `content` accepts either a preserialized string or any JSON-serializable
+ * value. Tag-owned fields (name, type, etc.) MUST NOT be duplicated in content
+ * by the library; that is left to the caller's discretion per the spec.
+ */
+interface BuildGameItemDefinitionInput {
+    /** The `d` item identifier. Required, non-empty. */
+    id: string;
+    /** The `name` tag. Required, non-empty. */
+    name: string;
+    /** The `type` tag. Required, non-empty. */
+    type: string;
+    category?: string;
+    image?: string;
+    model3d?: string;
+    audio?: string;
+    symbol?: string;
+    rarity?: string;
+    /** Suggested max stack; coerced to a string if provided as a number. */
+    maxStack?: string | number;
+    version?: string | number;
+    /**
+     * Human-readable fallback. If omitted, the builder does NOT auto-generate an
+     * `alt` tag (it is only RECOMMENDED by the spec). Pass a string to include it.
+     */
+    alt?: string;
+    contexts?: string[];
+    topics?: string[];
+    basedOn?: GameItemBasedOnReference[];
+    /** Optional content; string or JSON-serializable value. Defaults to `""`. */
+    content?: unknown;
+    /**
+     * Extra tags to append verbatim after the managed tags. Use for
+     * forward-compatible or game-specific tags.
+     *
+     * Tags that conflict with builder-managed tags are REJECTED (the builder
+     * throws), not silently ignored or duplicated. Managed tags are: `d`,
+     * `name`, `type`, `category`, `image`, `model_3d`, `audio`, `symbol`,
+     * `rarity`, `max_stack`, `version`, `context`, `t`, `alt`. An `a` tag only
+     * conflicts when it carries the `based_on` marker (pass such references via
+     * `basedOn` instead); other `a` usages remain allowed.
+     */
+    extraTags?: string[][];
+}
+
+/**
+ * The marker used on an `a` tag to indicate a derivation reference.
+ */
+declare const BASED_ON_MARKER: "based_on";
+interface GameItemAddress {
+    kind: KindGameItemDefinition;
+    pubkey: string;
+    /** The item `d` tag / identifier. */
+    itemId: string;
+}
+/**
+ * Build the addressable coordinate for a game item definition:
+ * `31632:<pubkey>:<item-d-tag>`.
+ */
+declare function buildGameItemAddress(pubkey: string, itemId: string): string;
+/**
+ * Parse a `31632:<pubkey>:<item-d-tag>` coordinate.
+ *
+ * Returns `null` if the string is malformed or does not reference kind 31632.
+ */
+declare function parseGameItemAddress(address: string, options?: AddressParseOptions): GameItemAddress | null;
+
+/**
+ * A structured validation issue for a kind:31632 event.
+ */
+interface ItemDefinitionValidationIssue {
+    code: "wrong-kind" | "missing-d" | "empty-d" | "missing-name" | "empty-name" | "missing-type" | "empty-type" | "invalid-json-content";
+    message: string;
+}
+interface ItemDefinitionValidationOptions {
+    /**
+     * When `true`, `content` must be empty or valid JSON. This mirrors the spec:
+     * an item definition is rejected for invalid JSON only when the client
+     * "requires strict JSON content". Defaults to `false`.
+     */
+    requireJsonContent?: boolean;
+}
+interface ItemDefinitionValidationResult {
+    valid: boolean;
+    issues: ItemDefinitionValidationIssue[];
+}
+/**
+ * Validate that an event is a well-formed kind:31632 Game Item Definition.
+ *
+ * Per the spec, an event is rejected as an item definition if:
+ * - `kind` is not 31632
+ * - the `d` tag is missing or empty
+ * - the `name` tag is missing or empty
+ * - the `type` tag is missing or empty
+ * - (only when {@link ItemDefinitionValidationOptions.requireJsonContent})
+ *   `content` is not valid JSON
+ *
+ * A required value that contains only whitespace is treated as empty. Values
+ * are never trimmed or otherwise mutated.
+ */
+declare function validateGameItemDefinition(event: NostrEvent, options?: ItemDefinitionValidationOptions): ItemDefinitionValidationResult;
+
+interface ParseGameItemDefinitionOptions {
+    /**
+     * `permissive` (default) tolerates invalid JSON content and unknown tags.
+     * `strict` additionally rejects the event when `content` is non-empty and
+     * not valid JSON (i.e. it implies `requireJsonContent`).
+     */
+    mode?: ParseMode;
+    /**
+     * Explicitly require valid JSON content, independent of mode. When left
+     * `undefined`, this defaults to `true` in strict mode and `false` in
+     * permissive mode.
+     */
+    requireJsonContent?: boolean;
+}
+/**
+ * Parse a kind:31632 event into a {@link GameItemDefinition}, returning a
+ * structured {@link ParseResult}.
+ *
+ * The event is rejected (`ok: false`) only for the MUST-reject conditions
+ * (wrong kind, missing/empty `d`/`name`/`type`, and invalid JSON when
+ * required). Unknown tags are preserved on the event and tolerated. Invalid
+ * JSON content in permissive mode produces a warning, not a rejection. Invalid
+ * `based_on` references (malformed address or wrong referenced kind) are
+ * ignored and reported as warnings.
+ */
+declare function parseGameItemDefinitionResult(event: NostrEvent, options?: ParseGameItemDefinitionOptions): ParseResult<GameItemDefinition>;
+/**
+ * Convenience wrapper returning the parsed definition or `null`.
+ *
+ * Prefer {@link parseGameItemDefinitionResult} when you need warnings or the
+ * rejection reason.
+ */
+declare function parseGameItemDefinition(event: NostrEvent, options?: ParseGameItemDefinitionOptions): GameItemDefinition | null;
+
+/**
+ * Build an unsigned kind:31632 event template.
+ *
+ * The builder:
+ * - validates required input (`id`, `name`, `type` must be non-empty and not
+ *   whitespace-only);
+ * - validates `maxStack` (positive decimal integer) and numeric `version`
+ *   (finite);
+ * - validates every `basedOn` reference (well-formed kind:31632 coordinate);
+ * - never creates `id` or `sig`;
+ * - emits tags in a stable, deterministic order to simplify testing;
+ * - rejects `extraTags` that conflict with builder-managed tags (see
+ *   {@link MANAGED_TAG_NAMES}); an `a` tag is only treated as conflicting when
+ *   it carries the `based_on` marker, so other future `a` usages remain
+ *   possible;
+ * - appends the remaining `extraTags` verbatim after the managed tags.
+ *
+ * Valid values are never trimmed or otherwise mutated.
+ *
+ * @throws {Error} if a required field is missing/blank, an optional numeric
+ * field is invalid, a `basedOn` reference is invalid, or an `extraTags` entry
+ * conflicts with a builder-managed tag.
+ */
+declare function buildGameItemDefinitionEvent(input: BuildGameItemDefinitionInput): UnsignedEventTemplate<KindGameItemDefinition>;
+
+/**
+ * A single item reference inside an inventory.
+ */
+interface GameInventoryItem {
+    /** The referenced `31632:<issuer-pubkey>:<item-d-tag>` address. */
+    address: string;
+    /** Relay URL hint, or `""` when unknown. */
+    relay: string;
+    /** Positive integer quantity. */
+    quantity: number;
+}
+/**
+ * A grant / receipt reference declared with an `e` tag marked `grant`.
+ */
+interface GameInventoryGrantReference {
+    /** The referenced grant event id. */
+    eventId: string;
+    /** Relay URL hint, or `""` when unknown. */
+    relay: string;
+}
+/**
+ * A parsed kind:31633 Game Inventory.
+ *
+ * Tags are the source of truth. `content` holds the raw content string; parsed
+ * JSON is exposed separately via {@link GameInventory.contentJson}.
+ */
+interface GameInventory {
+    /** The `d` tag value (inventory context identifier). */
+    id: string;
+    /** The full addressable coordinate `31633:<owner>:<d>`. */
+    address: string;
+    /** The event author / inventory owner. */
+    owner: string;
+    kind: KindGameInventory;
+    /** All `context` tag values (repeatable). */
+    contexts: string[];
+    /** Optional `name` tag. */
+    name?: string;
+    /** Optional `alt` tag. */
+    alt?: string;
+    /** Valid item references, in tag order (after duplicate resolution). */
+    items: GameInventoryItem[];
+    /** Grant references from `e` tags marked `grant`. */
+    grants: GameInventoryGrantReference[];
+    /** Convenience: grant event ids only. */
+    grantEventIds: string[];
+    /** Raw `content` string, preserved exactly as received. */
+    content: string;
+    /** Parsed content JSON, when content was non-empty valid JSON. */
+    contentJson?: unknown;
+    /** The original event this inventory was parsed from. */
+    event: NostrEvent;
+}
+/**
+ * Input for a single item when building an inventory event.
+ *
+ * `quantity` must be a non-negative safe integer. `0` omits the item; negative,
+ * decimal, NaN, Infinity, and unsafe-integer values throw. Quantities are never
+ * floored, clamped, or silently dropped.
+ */
+interface BuildGameInventoryItemInput {
+    address: string;
+    relay?: string;
+    quantity: number;
+}
+interface BuildGameInventoryGrantInput {
+    eventId: string;
+    relay?: string;
+}
+/**
+ * Strategy for handling duplicate item addresses when building or parsing.
+ *
+ * - `last` (spec default): keep the last valid quantity.
+ * - `sum`: sum all valid quantities for the address.
+ * - `strict`: reject (build throws / parse returns error).
+ */
+type DuplicateStrategy = "last" | "sum" | "strict";
+/**
+ * Input for building a kind:31633 event template.
+ */
+interface BuildGameInventoryInput {
+    /** The `d` inventory identifier. Required, non-empty. */
+    id: string;
+    items?: BuildGameInventoryItemInput[];
+    contexts?: string[];
+    name?: string;
+    alt?: string;
+    grants?: BuildGameInventoryGrantInput[];
+    /** Optional content; string or JSON-serializable value. Defaults to `""`. */
+    content?: unknown;
+    /**
+     * How to handle duplicate item addresses in the input. Defaults to `last`
+     * (the spec's recommended default). `strict` throws on duplicates. `sum`
+     * throws if the summed quantity exceeds Number.MAX_SAFE_INTEGER.
+     */
+    duplicateStrategy?: DuplicateStrategy;
+    /**
+     * Extra tags appended verbatim after managed tags.
+     *
+     * Tags that conflict with builder-managed tags are REJECTED (the builder
+     * throws), not silently duplicated. Rejected: `d`, `context`, `name`, `alt`;
+     * every `a` tag (all `a` tags represent inventory items in kind:31633 — pass
+     * items via `items`); and `e` tags carrying the `grant` marker (pass grants
+     * via `grants`). Unrelated forward-compatible tags, including non-grant `e`
+     * tags, are allowed.
+     */
+    extraTags?: string[][];
+}
+
+/**
+ * The marker used on an `e` tag to indicate a grant / receipt reference.
+ */
+declare const GRANT_MARKER: "grant";
+interface GameInventoryAddress {
+    kind: KindGameInventory;
+    pubkey: string;
+    /** The inventory `d` tag / context identifier. */
+    inventoryId: string;
+}
+/**
+ * Build the addressable coordinate for a game inventory:
+ * `31633:<owner-pubkey>:<inventory-d-tag>`.
+ */
+declare function buildGameInventoryAddress(ownerPubkey: string, inventoryId: string): string;
+/**
+ * Parse a `31633:<owner-pubkey>:<inventory-d-tag>` coordinate.
+ *
+ * Returns `null` if the string is malformed or does not reference kind 31633.
+ */
+declare function parseGameInventoryAddress(address: string, options?: AddressParseOptions): GameInventoryAddress | null;
+
+/**
+ * Public quantity helpers for kind:31633 inventory `a` tags.
+ *
+ * Per the spec, quantity MUST be encoded as a decimal integer string. Parsers
+ * SHOULD ignore item references whose quantity is missing, `0`, negative,
+ * decimal, or non-numeric. A "valid" stored inventory quantity is therefore a
+ * positive integer.
+ *
+ * - {@link parseInventoryQuantity} parses an untrusted tag string, tolerantly
+ *   returning `null` for anything that is not a canonical positive decimal
+ *   integer string.
+ * - {@link encodeInventoryQuantity} encodes a positive integer back into its
+ *   canonical decimal string form.
+ *
+ * Strict validation of public numeric inputs (used by the builder and the
+ * inventory helpers) lives in `quantity.internal.ts` and is not part of the
+ * public API.
+ */
+/**
+ * Parse an inventory quantity *string* into a positive integer.
+ *
+ * Returns `null` for any value that is not a strictly positive canonical
+ * decimal integer string. This intentionally rejects:
+ * - `undefined` / `null` / missing
+ * - `"0"` and `"-1"` (not positive)
+ * - `"1.5"` (decimal)
+ * - `"abc"`, `"1e3"`, `"0x1"`, `" 1 "`, `"+1"` (not a plain decimal integer)
+ * - `"03"` (leading zeros; a well-formed publisher never emits them)
+ */
+declare function parseInventoryQuantity(raw: string | undefined | null): number | null;
+/**
+ * Encode a positive integer quantity as its canonical decimal string.
+ *
+ * @throws if the value is not a positive safe integer.
+ */
+declare function encodeInventoryQuantity(value: number): string;
+
+interface InventoryValidationIssue {
+    code: "wrong-kind" | "missing-d" | "empty-d" | "invalid-json-content";
+    message: string;
+}
+interface InventoryValidationOptions {
+    /**
+     * When `true`, non-empty invalid JSON content is treated as invalid. The
+     * spec only allows rejecting invalid JSON when NOT in permissive mode, so
+     * this defaults to `false`.
+     */
+    requireJsonContent?: boolean;
+}
+interface InventoryValidationResult {
+    valid: boolean;
+    issues: InventoryValidationIssue[];
+}
+/**
+ * Validate the MUST-reject conditions for a kind:31633 inventory.
+ *
+ * An event MUST be rejected if:
+ * - `kind` is not 31633
+ * - the `d` tag is missing
+ * - the `d` tag is empty or contains only whitespace
+ *
+ * A whitespace-only `d` value is treated as empty; values are never trimmed.
+ * Item-level problems (bad quantity, wrong referenced kind, malformed address)
+ * do NOT invalidate the inventory; those items are ignored during parsing.
+ */
+declare function validateGameInventory(event: NostrEvent, options?: InventoryValidationOptions): InventoryValidationResult;
+
+interface ParseGameInventoryOptions {
+    /**
+     * `permissive` (default) tolerates invalid JSON content and ignores invalid
+     * item tags. `strict` additionally:
+     * - rejects the event when `content` is non-empty and not valid JSON;
+     * - defaults the duplicate strategy to `strict` (reject on duplicates).
+     */
+    mode?: ParseMode;
+    /**
+     * Duplicate item address handling. When omitted, defaults to `strict` in
+     * strict mode and `last` in permissive mode (the spec's recommended
+     * default).
+     */
+    duplicateStrategy?: DuplicateStrategy;
+    /**
+     * Require valid JSON content independent of mode. Defaults to `true` in
+     * strict mode, `false` in permissive mode.
+     */
+    requireJsonContent?: boolean;
+    /**
+     * Require item addresses to use 64-char hex pubkeys. Defaults to `false`
+     * (the spec examples use placeholder pubkeys).
+     */
+    requireHexPubkey?: boolean;
+    /**
+     * Require grant `e` tag event ids to be canonical 64-char lowercase hex.
+     * Defaults to `false` so fixture placeholders remain supported.
+     */
+    requireHexEventId?: boolean;
+}
+/**
+ * Parse a kind:31633 event into a {@link GameInventory}, returning a structured
+ * {@link ParseResult}.
+ *
+ * The event is rejected (`ok: false`) only when: kind is wrong, `d` is
+ * missing/empty, JSON content is required but invalid, duplicate item
+ * references are present under the `strict` strategy, or a `sum` duplicate
+ * resolution would overflow Number.MAX_SAFE_INTEGER. Item references that are
+ * malformed, reference a non-31632 kind, or carry an invalid quantity are
+ * ignored and reported as warnings. Malformed grant tags are ignored with an
+ * `invalid-grant-tag` warning.
+ */
+declare function parseGameInventoryResult(event: NostrEvent, options?: ParseGameInventoryOptions): ParseResult<GameInventory>;
+/**
+ * Convenience wrapper returning the parsed inventory or `null`.
+ */
+declare function parseGameInventory(event: NostrEvent, options?: ParseGameInventoryOptions): GameInventory | null;
+
+/**
+ * Build an unsigned kind:31633 event template.
+ *
+ * The builder:
+ * - validates the required `d` id (non-empty, not whitespace-only);
+ * - validates each item address (must be a kind:31632 coordinate);
+ * - requires each item quantity to be a non-negative safe integer; `0` is
+ *   omitted, and negatives/decimals/NaN/Infinity/unsafe integers throw (they
+ *   are never floored, clamped, or silently dropped);
+ * - resolves duplicate addresses per `duplicateStrategy` (default `last`), and
+ *   throws if a `sum` overflows Number.MAX_SAFE_INTEGER;
+ * - rejects grants with an empty/whitespace-only event id;
+ * - emits tags in a stable, deterministic order;
+ * - never creates `id` or `sig`;
+ * - rejects `extraTags` that conflict with builder-managed tags and appends the
+ *   rest verbatim after the managed tags.
+ *
+ * Non-empty display values are never trimmed or otherwise normalized.
+ *
+ * @throws {Error} for a blank `id`, invalid item address, invalid quantity,
+ * duplicate under the `strict` strategy, `sum` overflow, a blank grant event
+ * id, or an `extraTags` entry that conflicts with a managed tag.
+ */
+declare function buildGameInventoryEvent(input: BuildGameInventoryInput): UnsignedEventTemplate<KindGameInventory>;
+
+/**
+ * Read the quantity of an item in an inventory.
+ *
+ * Returns `0` when the item is not present. This mirrors inventory semantics:
+ * a missing item is equivalent to holding zero of it.
+ */
+declare function getInventoryItemQuantity(inventory: GameInventory, itemAddress: string): number;
+/**
+ * Return a new inventory with the given item's quantity set to an exact value.
+ *
+ * - `itemAddress` must be a valid kind:31632 coordinate (throws otherwise).
+ * - `quantity` must be a non-negative safe integer (throws otherwise); it is
+ *   never floored, clamped, or silently dropped.
+ * - Setting a quantity of `0` removes the item.
+ * - The input inventory is never mutated (pure / immutable). When the
+ *   operation is rejected it throws before producing any value, so the input
+ *   is untouched.
+ */
+declare function setInventoryItemQuantity(inventory: GameInventory, itemAddress: string, quantity: number, relay?: string): GameInventory;
+/**
+ * Return a new inventory with `amount` added to the item's quantity.
+ *
+ * - `itemAddress` must be a valid kind:31632 coordinate (throws otherwise).
+ * - `amount` must be a non-negative safe integer (throws otherwise). An amount
+ *   of `0` is a no-op that still returns a fresh inventory object.
+ * - Throws if the resulting quantity would exceed Number.MAX_SAFE_INTEGER.
+ * - The input inventory is never mutated.
+ */
+declare function addInventoryItemQuantity(inventory: GameInventory, itemAddress: string, amount: number, relay?: string): GameInventory;
+/**
+ * Return a new inventory with `amount` removed from the item's quantity.
+ *
+ * - `itemAddress` must be a valid kind:31632 coordinate (throws otherwise).
+ * - `amount` must be a non-negative safe integer (throws otherwise).
+ * - The result is clamped at zero; reaching zero removes the item. (Clamping a
+ *   removal *result* to zero is allowed; the requested `amount` itself must be
+ *   valid and is never silently corrected.)
+ * - The input inventory is never mutated.
+ */
+declare function removeInventoryItemQuantity(inventory: GameInventory, itemAddress: string, amount: number): GameInventory;
+/**
+ * Return a shallow copy of the inventory's items array.
+ *
+ * Useful for callers that want the item list without exposing the internal
+ * reference.
+ */
+declare function getInventoryItems(inventory: GameInventory): GameInventoryItem[];
+
+export { type AddressParseOptions, type AddressableEventAddress, BASED_ON_MARKER, type BuildGameInventoryGrantInput, type BuildGameInventoryInput, type BuildGameInventoryItemInput, type BuildGameItemDefinitionInput, type ContentParseResult, type DuplicateStrategy, GRANT_MARKER, type GameInventory, type GameInventoryAddress, type GameInventoryGrantReference, type GameInventoryItem, type GameItemAddress, type GameItemBasedOnReference, type GameItemDefinition, type InventoryValidationIssue, type InventoryValidationOptions, type InventoryValidationResult, type ItemDefinitionValidationIssue, type ItemDefinitionValidationOptions, type ItemDefinitionValidationResult, KIND_GAME_INVENTORY, KIND_GAME_ITEM_DEFINITION, type KindGameInventory, type KindGameItemDefinition, type NostrEvent, type ParseGameInventoryOptions, type ParseGameItemDefinitionOptions, type ParseMode, type ParseResult, type ParseWarning, type ParseWarningCode, type UnsignedEventTemplate, addInventoryItemQuantity, buildAddressableEventAddress, buildGameInventoryAddress, buildGameInventoryEvent, buildGameItemAddress, buildGameItemDefinitionEvent, encodeInventoryQuantity, getDTag, getInventoryItemQuantity, getInventoryItems, getTagValue, getTagValues, parseAddressableEventAddress, parseContentJson, parseGameInventory, parseGameInventoryAddress, parseGameInventoryResult, parseGameItemAddress, parseGameItemDefinition, parseGameItemDefinitionResult, parseInventoryQuantity, removeInventoryItemQuantity, serializeContent, setInventoryItemQuantity, validateGameInventory, validateGameItemDefinition };