@nostr-games/inventory 0.1.0

package/dist/index.js

@@ -0,0 +1,882 @@
+// src/common/constants.ts
+var KIND_GAME_ITEM_DEFINITION = 31632;
+var KIND_GAME_INVENTORY = 31633;
+
+// src/common/strings.ts
+function isBlank(value) {
+  return typeof value !== "string" || value.trim() === "";
+}
+
+// src/common/address.ts
+var HEX64 = /^[0-9a-f]{64}$/;
+function buildAddressableEventAddress(kind, pubkey, identifier) {
+  if (!Number.isInteger(kind) || kind < 0) {
+    throw new Error(`Invalid kind for address: ${String(kind)}`);
+  }
+  if (pubkey.trim() === "") {
+    throw new Error("Cannot build address with empty pubkey");
+  }
+  if (identifier.trim() === "") {
+    throw new Error("Cannot build address with empty identifier");
+  }
+  return `${kind}:${pubkey}:${identifier}`;
+}
+function parseAddressableEventAddress(address, options = {}) {
+  if (typeof address !== "string") {
+    return null;
+  }
+  const firstColon = address.indexOf(":");
+  if (firstColon <= 0) {
+    return null;
+  }
+  const secondColon = address.indexOf(":", firstColon + 1);
+  if (secondColon < 0) {
+    return null;
+  }
+  const kindStr = address.slice(0, firstColon);
+  const pubkey = address.slice(firstColon + 1, secondColon);
+  const identifier = address.slice(secondColon + 1);
+  if (!/^\d+$/.test(kindStr)) {
+    return null;
+  }
+  const kind = Number.parseInt(kindStr, 10);
+  if (!Number.isSafeInteger(kind)) {
+    return null;
+  }
+  if (isBlank(pubkey) || isBlank(identifier)) {
+    return null;
+  }
+  if (options.requireHexPubkey && !HEX64.test(pubkey)) {
+    return null;
+  }
+  return { kind, pubkey, identifier };
+}
+
+// src/common/tags.ts
+function getTagValue(tags, name) {
+  for (const tag of tags) {
+    if (tag[0] === name) {
+      return tag[1];
+    }
+  }
+  return void 0;
+}
+function getTagValues(tags, name) {
+  const values = [];
+  for (const tag of tags) {
+    if (tag[0] === name && typeof tag[1] === "string") {
+      values.push(tag[1]);
+    }
+  }
+  return values;
+}
+function getDTag(source) {
+  const tags = Array.isArray(source) ? source : source.tags;
+  return getTagValue(tags, "d");
+}
+
+// src/common/json.ts
+function parseContentJson(content) {
+  if (content === "") {
+    return { kind: "empty" };
+  }
+  try {
+    return { kind: "json", value: JSON.parse(content) };
+  } catch {
+    return { kind: "invalid", raw: content };
+  }
+}
+function serializeContent(content) {
+  if (content === void 0) {
+    return "";
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(content);
+  } catch (cause) {
+    const detail = cause instanceof Error ? `: ${cause.message}` : "";
+    throw new Error(
+      `serializeContent: value is not JSON-serializable (circular reference?)${detail}`
+    );
+  }
+  if (serialized === void 0) {
+    throw new Error(
+      "serializeContent: value is not JSON-serializable (produced `undefined`, e.g. a function or symbol)"
+    );
+  }
+  return serialized;
+}
+
+// src/kinds/game-item-definition/address.ts
+var BASED_ON_MARKER = "based_on";
+function buildGameItemAddress(pubkey, itemId) {
+  return buildAddressableEventAddress(
+    KIND_GAME_ITEM_DEFINITION,
+    pubkey,
+    itemId
+  );
+}
+function parseGameItemAddress(address, options = {}) {
+  const parsed = parseAddressableEventAddress(address, options);
+  if (parsed === null || parsed.kind !== KIND_GAME_ITEM_DEFINITION) {
+    return null;
+  }
+  return {
+    kind: KIND_GAME_ITEM_DEFINITION,
+    pubkey: parsed.pubkey,
+    itemId: parsed.identifier
+  };
+}
+
+// src/kinds/game-item-definition/validate.ts
+function isBlank2(value) {
+  return value.trim() === "";
+}
+function validateGameItemDefinition(event, options = {}) {
+  const issues = [];
+  if (event.kind !== KIND_GAME_ITEM_DEFINITION) {
+    issues.push({
+      code: "wrong-kind",
+      message: `Expected kind ${KIND_GAME_ITEM_DEFINITION}, got ${event.kind}`
+    });
+  }
+  const d = getTagValue(event.tags, "d");
+  if (d === void 0) {
+    issues.push({ code: "missing-d", message: "Missing required `d` tag" });
+  } else if (isBlank2(d)) {
+    issues.push({ code: "empty-d", message: "`d` tag value is empty" });
+  }
+  const name = getTagValue(event.tags, "name");
+  if (name === void 0) {
+    issues.push({
+      code: "missing-name",
+      message: "Missing required `name` tag"
+    });
+  } else if (isBlank2(name)) {
+    issues.push({ code: "empty-name", message: "`name` tag value is empty" });
+  }
+  const type = getTagValue(event.tags, "type");
+  if (type === void 0) {
+    issues.push({
+      code: "missing-type",
+      message: "Missing required `type` tag"
+    });
+  } else if (isBlank2(type)) {
+    issues.push({ code: "empty-type", message: "`type` tag value is empty" });
+  }
+  if (options.requireJsonContent) {
+    const parsed = parseContentJson(event.content);
+    if (parsed.kind === "invalid") {
+      issues.push({
+        code: "invalid-json-content",
+        message: "`content` is not valid JSON"
+      });
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+// src/common/result.ts
+function ok(value, warnings = []) {
+  return { ok: true, value, warnings };
+}
+function fail(error, warnings = []) {
+  return { ok: false, error, warnings };
+}
+
+// src/kinds/game-item-definition/parse.ts
+function parseGameItemDefinitionResult(event, options = {}) {
+  const mode = options.mode ?? "permissive";
+  const requireJsonContent = options.requireJsonContent ?? mode === "strict";
+  const warnings = [];
+  const validation = validateGameItemDefinition(event, {
+    requireJsonContent
+  });
+  if (!validation.valid) {
+    return fail(validation.issues.map((i) => i.message).join("; "), warnings);
+  }
+  const id = getTagValue(event.tags, "d");
+  const name = getTagValue(event.tags, "name");
+  const type = getTagValue(event.tags, "type");
+  const contentParsed = parseContentJson(event.content);
+  let contentJson;
+  if (contentParsed.kind === "json") {
+    contentJson = contentParsed.value;
+  } else if (contentParsed.kind === "invalid") {
+    warnings.push({
+      code: "invalid-json-content",
+      message: "`content` is not valid JSON; ignored"
+    });
+  }
+  const basedOn = parseBasedOnReferences(event.tags, warnings);
+  const definition = {
+    id,
+    address: buildGameItemAddress(event.pubkey, id),
+    issuer: event.pubkey,
+    kind: KIND_GAME_ITEM_DEFINITION,
+    name,
+    type,
+    contexts: getTagValues(event.tags, "context"),
+    topics: getTagValues(event.tags, "t"),
+    basedOn,
+    content: event.content,
+    event
+  };
+  assignOptional(definition, "category", getTagValue(event.tags, "category"));
+  assignOptional(definition, "image", getTagValue(event.tags, "image"));
+  assignOptional(definition, "model3d", getTagValue(event.tags, "model_3d"));
+  assignOptional(definition, "audio", getTagValue(event.tags, "audio"));
+  assignOptional(definition, "symbol", getTagValue(event.tags, "symbol"));
+  assignOptional(definition, "rarity", getTagValue(event.tags, "rarity"));
+  assignOptional(definition, "maxStack", getTagValue(event.tags, "max_stack"));
+  assignOptional(definition, "version", getTagValue(event.tags, "version"));
+  assignOptional(definition, "alt", getTagValue(event.tags, "alt"));
+  if (contentJson !== void 0) {
+    definition.contentJson = contentJson;
+  }
+  return ok(definition, warnings);
+}
+function parseGameItemDefinition(event, options = {}) {
+  const result = parseGameItemDefinitionResult(event, options);
+  return result.ok ? result.value : null;
+}
+function parseBasedOnReferences(tags, warnings) {
+  const refs = [];
+  for (const tag of tags) {
+    if (tag[0] !== "a") {
+      continue;
+    }
+    if (tag[3] !== BASED_ON_MARKER) {
+      continue;
+    }
+    const address = tag[1];
+    if (typeof address !== "string" || address === "") {
+      warnings.push({
+        code: "malformed-address",
+        message: "`based_on` `a` tag is missing an address; ignored",
+        tag
+      });
+      continue;
+    }
+    const parsed = parseGameItemAddress(address);
+    if (parsed === null) {
+      const isMalformed = address.startsWith(`${KIND_GAME_ITEM_DEFINITION}:`);
+      warnings.push({
+        code: isMalformed ? "malformed-address" : "wrong-referenced-kind",
+        message: isMalformed ? `Malformed \`based_on\` address; ignored: ${address}` : `\`based_on\` address does not reference kind ${KIND_GAME_ITEM_DEFINITION}; ignored: ${address}`,
+        tag
+      });
+      continue;
+    }
+    refs.push({ address, relay: tag[2] ?? "" });
+  }
+  return refs;
+}
+function assignOptional(target, key, value) {
+  if (value !== void 0) {
+    target[key] = value;
+  }
+}
+
+// src/kinds/game-item-definition/build.ts
+var MANAGED_TAG_NAMES = /* @__PURE__ */ new Set([
+  "d",
+  "name",
+  "type",
+  "category",
+  "image",
+  "model_3d",
+  "audio",
+  "symbol",
+  "rarity",
+  "max_stack",
+  "version",
+  "context",
+  "t",
+  "alt"
+]);
+function buildGameItemDefinitionEvent(input) {
+  const id = requireNonBlank(input.id, "id");
+  const name = requireNonBlank(input.name, "name");
+  const type = requireNonBlank(input.type, "type");
+  const tags = [
+    ["d", id],
+    ["name", name],
+    ["type", type]
+  ];
+  pushOptional(tags, "category", input.category);
+  pushOptional(tags, "image", input.image);
+  pushOptional(tags, "model_3d", input.model3d);
+  pushOptional(tags, "audio", input.audio);
+  pushOptional(tags, "symbol", input.symbol);
+  pushOptional(tags, "rarity", input.rarity);
+  pushOptional(tags, "max_stack", validateMaxStack(input.maxStack));
+  pushOptional(tags, "version", validateVersion(input.version));
+  for (const context of input.contexts ?? []) {
+    if (!isBlank3(context)) {
+      tags.push(["context", context]);
+    }
+  }
+  for (const topic of input.topics ?? []) {
+    if (!isBlank3(topic)) {
+      tags.push(["t", topic]);
+    }
+  }
+  for (const ref of input.basedOn ?? []) {
+    if (parseGameItemAddress(ref.address) === null) {
+      throw new Error(
+        `buildGameItemDefinitionEvent: invalid \`basedOn.address\` (must be a kind:${KIND_GAME_ITEM_DEFINITION} coordinate): ${String(ref.address)}`
+      );
+    }
+    tags.push(["a", ref.address, ref.relay ?? "", BASED_ON_MARKER]);
+  }
+  pushOptional(tags, "alt", input.alt);
+  for (const tag of input.extraTags ?? []) {
+    assertExtraTagAllowed(tag);
+    tags.push([...tag]);
+  }
+  return {
+    kind: KIND_GAME_ITEM_DEFINITION,
+    content: serializeContent(input.content),
+    tags
+  };
+}
+function isBlank3(value) {
+  return typeof value !== "string" || value.trim() === "";
+}
+function requireNonBlank(value, field) {
+  if (isBlank3(value)) {
+    throw new Error(
+      `buildGameItemDefinitionEvent: \`${field}\` is required and must be non-empty`
+    );
+  }
+  return value;
+}
+function pushOptional(tags, name, value) {
+  if (value !== void 0 && !isBlank3(value)) {
+    tags.push([name, value]);
+  }
+}
+function validateMaxStack(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(
+        `buildGameItemDefinitionEvent: \`maxStack\` must be a positive integer: ${String(value)}`
+      );
+    }
+    return String(value);
+  }
+  if (!/^[1-9]\d*$/.test(value)) {
+    throw new Error(
+      `buildGameItemDefinitionEvent: \`maxStack\` must be a positive integer string: ${value}`
+    );
+  }
+  return value;
+}
+function validateVersion(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `buildGameItemDefinitionEvent: numeric \`version\` must be finite: ${String(value)}`
+      );
+    }
+    return String(value);
+  }
+  return value;
+}
+function assertExtraTagAllowed(tag) {
+  const name = tag[0];
+  if (name === void 0) {
+    return;
+  }
+  if (name === "a") {
+    if (tag[3] === BASED_ON_MARKER) {
+      throw new Error(
+        "buildGameItemDefinitionEvent: `extraTags` may not contain a builder-managed `a`+`based_on` tag; pass it via `basedOn` instead"
+      );
+    }
+    return;
+  }
+  if (MANAGED_TAG_NAMES.has(name)) {
+    throw new Error(
+      `buildGameItemDefinitionEvent: \`extraTags\` may not contain the builder-managed tag \`${name}\``
+    );
+  }
+}
+
+// src/kinds/game-inventory/address.ts
+var GRANT_MARKER = "grant";
+function buildGameInventoryAddress(ownerPubkey, inventoryId) {
+  return buildAddressableEventAddress(
+    KIND_GAME_INVENTORY,
+    ownerPubkey,
+    inventoryId
+  );
+}
+function parseGameInventoryAddress(address, options = {}) {
+  const parsed = parseAddressableEventAddress(address, options);
+  if (parsed === null || parsed.kind !== KIND_GAME_INVENTORY) {
+    return null;
+  }
+  return {
+    kind: KIND_GAME_INVENTORY,
+    pubkey: parsed.pubkey,
+    inventoryId: parsed.identifier
+  };
+}
+
+// src/kinds/game-inventory/quantity.ts
+function parseInventoryQuantity(raw) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  if (!/^[1-9]\d*$/.test(raw)) {
+    return null;
+  }
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    return null;
+  }
+  return value;
+}
+function encodeInventoryQuantity(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(
+      `Cannot encode non-positive-integer quantity: ${String(value)}`
+    );
+  }
+  return String(value);
+}
+
+// src/kinds/game-inventory/validate.ts
+function validateGameInventory(event, options = {}) {
+  const issues = [];
+  if (event.kind !== KIND_GAME_INVENTORY) {
+    issues.push({
+      code: "wrong-kind",
+      message: `Expected kind ${KIND_GAME_INVENTORY}, got ${event.kind}`
+    });
+  }
+  const d = getTagValue(event.tags, "d");
+  if (d === void 0) {
+    issues.push({ code: "missing-d", message: "Missing required `d` tag" });
+  } else if (isBlank(d)) {
+    issues.push({ code: "empty-d", message: "`d` tag value is empty" });
+  }
+  if (options.requireJsonContent) {
+    const parsed = parseContentJson(event.content);
+    if (parsed.kind === "invalid") {
+      issues.push({
+        code: "invalid-json-content",
+        message: "`content` is not valid JSON"
+      });
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+// src/kinds/game-inventory/quantity.internal.ts
+var MAX_QUANTITY = Number.MAX_SAFE_INTEGER;
+function assertNonNegativeInteger(value, label) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`${label} must be a number, got: ${String(value)}`);
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`${label} must be finite, got: ${String(value)}`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${label} must be an integer, got: ${String(value)}`);
+  }
+  if (value < 0) {
+    throw new Error(`${label} must be non-negative, got: ${String(value)}`);
+  }
+  if (!Number.isSafeInteger(value)) {
+    throw new Error(
+      `${label} exceeds Number.MAX_SAFE_INTEGER, got: ${String(value)}`
+    );
+  }
+  return value;
+}
+function addQuantitiesChecked(a, b, label) {
+  const sum = a + b;
+  if (sum > MAX_QUANTITY || !Number.isSafeInteger(sum)) {
+    throw new Error(
+      `${label} overflow: ${String(a)} + ${String(b)} exceeds Number.MAX_SAFE_INTEGER`
+    );
+  }
+  return sum;
+}
+
+// src/kinds/game-inventory/parse.ts
+var HEX642 = /^[0-9a-f]{64}$/;
+function parseGameInventoryResult(event, options = {}) {
+  const mode = options.mode ?? "permissive";
+  const requireJsonContent = options.requireJsonContent ?? mode === "strict";
+  const duplicateStrategy = options.duplicateStrategy ?? (mode === "strict" ? "strict" : "last");
+  const requireHexPubkey = options.requireHexPubkey ?? false;
+  const requireHexEventId = options.requireHexEventId ?? false;
+  const warnings = [];
+  const validation = validateGameInventory(event, { requireJsonContent });
+  if (!validation.valid) {
+    return fail(validation.issues.map((i) => i.message).join("; "), warnings);
+  }
+  const id = getTagValue(event.tags, "d");
+  const collected = [];
+  for (const tag of event.tags) {
+    if (tag[0] !== "a") {
+      continue;
+    }
+    const address = tag[1];
+    if (typeof address !== "string") {
+      warnings.push({
+        code: "invalid-item-tag",
+        message: "`a` tag missing address",
+        tag
+      });
+      continue;
+    }
+    const generic = parseAddressableEventAddress(address, { requireHexPubkey });
+    if (generic === null) {
+      warnings.push({
+        code: "malformed-address",
+        message: `Malformed item address: ${address}`,
+        tag
+      });
+      continue;
+    }
+    if (generic.kind !== KIND_GAME_ITEM_DEFINITION) {
+      warnings.push({
+        code: "wrong-referenced-kind",
+        message: `Item \`a\` tag does not reference kind ${KIND_GAME_ITEM_DEFINITION}: ${address}`,
+        tag
+      });
+      continue;
+    }
+    if (parseGameItemAddress(address, { requireHexPubkey }) === null) {
+      warnings.push({
+        code: "malformed-address",
+        message: `Malformed item address: ${address}`,
+        tag
+      });
+      continue;
+    }
+    const quantity = parseInventoryQuantity(tag[3]);
+    if (quantity === null) {
+      warnings.push({
+        code: "invalid-quantity",
+        message: `Invalid or missing quantity for ${address}: ${String(tag[3])}`,
+        tag
+      });
+      continue;
+    }
+    collected.push({ address, relay: tag[2] ?? "", quantity });
+  }
+  const resolved = resolveDuplicates(collected, duplicateStrategy, warnings);
+  if (!resolved.ok) {
+    return fail(resolved.error, warnings);
+  }
+  const grants = parseGrants(event.tags, requireHexEventId, warnings);
+  const contentParsed = parseContentJson(event.content);
+  let contentJson;
+  if (contentParsed.kind === "json") {
+    contentJson = contentParsed.value;
+  } else if (contentParsed.kind === "invalid") {
+    warnings.push({
+      code: "invalid-json-content",
+      message: "`content` is not valid JSON; ignored"
+    });
+  }
+  const inventory = {
+    id,
+    address: buildGameInventoryAddress(event.pubkey, id),
+    owner: event.pubkey,
+    kind: KIND_GAME_INVENTORY,
+    contexts: getTagValues(event.tags, "context"),
+    items: resolved.value,
+    grants,
+    grantEventIds: grants.map((g) => g.eventId),
+    content: event.content,
+    event
+  };
+  const name = getTagValue(event.tags, "name");
+  if (name !== void 0) {
+    inventory.name = name;
+  }
+  const alt = getTagValue(event.tags, "alt");
+  if (alt !== void 0) {
+    inventory.alt = alt;
+  }
+  if (contentJson !== void 0) {
+    inventory.contentJson = contentJson;
+  }
+  return ok(inventory, warnings);
+}
+function parseGameInventory(event, options = {}) {
+  const result = parseGameInventoryResult(event, options);
+  return result.ok ? result.value : null;
+}
+function resolveDuplicates(items, strategy, warnings) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    counts.set(item.address, (counts.get(item.address) ?? 0) + 1);
+  }
+  const hasDuplicate = [...counts.values()].some((n) => n > 1);
+  if (!hasDuplicate) {
+    return { ok: true, value: items.map((item) => ({ ...item })) };
+  }
+  if (strategy === "strict") {
+    return {
+      ok: false,
+      error: "Duplicate item references present and duplicate strategy is `strict`"
+    };
+  }
+  for (const [address, count] of counts) {
+    if (count > 1) {
+      warnings.push({
+        code: "duplicate-item",
+        message: `Duplicate item reference (${count}x) resolved with strategy \`${strategy}\`: ${address}`
+      });
+    }
+  }
+  const order = [];
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const existing = byAddress.get(item.address);
+    if (existing === void 0) {
+      order.push(item.address);
+      byAddress.set(item.address, { ...item });
+    } else if (strategy === "sum") {
+      const sum = existing.quantity + item.quantity;
+      if (sum > MAX_QUANTITY || !Number.isSafeInteger(sum)) {
+        return {
+          ok: false,
+          error: `Summed quantity for ${item.address} exceeds Number.MAX_SAFE_INTEGER`
+        };
+      }
+      existing.quantity = sum;
+      existing.relay = item.relay;
+    } else {
+      existing.quantity = item.quantity;
+      existing.relay = item.relay;
+    }
+  }
+  return {
+    ok: true,
+    value: order.map((addr) => byAddress.get(addr))
+  };
+}
+function parseGrants(tags, requireHexEventId, warnings) {
+  const grants = [];
+  for (const tag of tags) {
+    if (tag[0] !== "e") {
+      continue;
+    }
+    if (tag[3] !== GRANT_MARKER) {
+      continue;
+    }
+    const eventId = tag[1];
+    if (typeof eventId !== "string" || isBlank(eventId)) {
+      warnings.push({
+        code: "invalid-grant-tag",
+        message: "Grant `e` tag is missing an event id; ignored",
+        tag
+      });
+      continue;
+    }
+    if (requireHexEventId && !HEX642.test(eventId)) {
+      warnings.push({
+        code: "invalid-grant-tag",
+        message: `Grant \`e\` tag event id is not canonical 64-char hex; ignored: ${eventId}`,
+        tag
+      });
+      continue;
+    }
+    grants.push({ eventId, relay: tag[2] ?? "" });
+  }
+  return grants;
+}
+
+// src/kinds/game-inventory/build.ts
+var MANAGED_TAG_NAMES2 = /* @__PURE__ */ new Set(["d", "context", "name", "alt"]);
+function buildGameInventoryEvent(input) {
+  if (isBlank(input.id)) {
+    throw new Error(
+      "buildGameInventoryEvent: `id` is required and must be non-empty"
+    );
+  }
+  const strategy = input.duplicateStrategy ?? "last";
+  const items = normalizeItems(input.items ?? [], strategy);
+  const tags = [["d", input.id]];
+  for (const context of input.contexts ?? []) {
+    if (!isBlank(context)) {
+      tags.push(["context", context]);
+    }
+  }
+  if (input.name !== void 0 && !isBlank(input.name)) {
+    tags.push(["name", input.name]);
+  }
+  for (const item of items) {
+    tags.push([
+      "a",
+      item.address,
+      item.relay,
+      encodeInventoryQuantity(item.quantity)
+    ]);
+  }
+  for (const grant of input.grants ?? []) {
+    if (isBlank(grant.eventId)) {
+      throw new Error(
+        "buildGameInventoryEvent: grant `eventId` must be non-empty"
+      );
+    }
+    tags.push(["e", grant.eventId, grant.relay ?? "", GRANT_MARKER]);
+  }
+  if (input.alt !== void 0 && !isBlank(input.alt)) {
+    tags.push(["alt", input.alt]);
+  }
+  for (const tag of input.extraTags ?? []) {
+    assertExtraTagAllowed2(tag);
+    tags.push([...tag]);
+  }
+  return {
+    kind: KIND_GAME_INVENTORY,
+    content: serializeContent(input.content),
+    tags
+  };
+}
+function normalizeItems(inputs, strategy) {
+  const order = [];
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const raw of inputs) {
+    if (parseGameItemAddress(raw.address) === null) {
+      throw new Error(
+        `buildGameInventoryEvent: invalid item address (must be a kind:${KIND_GAME_ITEM_DEFINITION} coordinate): ${String(raw.address)}`
+      );
+    }
+    const quantity = assertNonNegativeInteger(raw.quantity, "item quantity");
+    if (quantity === 0) {
+      continue;
+    }
+    const relay = raw.relay ?? "";
+    const existing = byAddress.get(raw.address);
+    if (existing === void 0) {
+      order.push(raw.address);
+      byAddress.set(raw.address, { address: raw.address, relay, quantity });
+      continue;
+    }
+    if (strategy === "strict") {
+      throw new Error(
+        `buildGameInventoryEvent: duplicate item address under strict strategy: ${raw.address}`
+      );
+    } else if (strategy === "sum") {
+      existing.quantity = addQuantitiesChecked(
+        existing.quantity,
+        quantity,
+        "summed item quantity"
+      );
+      existing.relay = relay;
+    } else {
+      existing.quantity = quantity;
+      existing.relay = relay;
+    }
+  }
+  return order.map((addr) => byAddress.get(addr));
+}
+function assertExtraTagAllowed2(tag) {
+  const name = tag[0];
+  if (name === void 0) {
+    return;
+  }
+  if (name === "a") {
+    throw new Error(
+      "buildGameInventoryEvent: `extraTags` may not contain an `a` tag; pass inventory items via `items` instead"
+    );
+  }
+  if (name === "e") {
+    if (tag[3] === GRANT_MARKER) {
+      throw new Error(
+        "buildGameInventoryEvent: `extraTags` may not contain a grant `e` tag; pass it via `grants` instead"
+      );
+    }
+    return;
+  }
+  if (MANAGED_TAG_NAMES2.has(name)) {
+    throw new Error(
+      `buildGameInventoryEvent: \`extraTags\` may not contain the builder-managed tag \`${name}\``
+    );
+  }
+}
+
+// src/kinds/game-inventory/helpers.ts
+function assertItemAddress(itemAddress) {
+  if (parseGameItemAddress(itemAddress) === null) {
+    throw new Error(
+      `itemAddress must be a valid kind:${KIND_GAME_ITEM_DEFINITION} coordinate, got: ${String(itemAddress)}`
+    );
+  }
+}
+function getInventoryItemQuantity(inventory, itemAddress) {
+  for (const item of inventory.items) {
+    if (item.address === itemAddress) {
+      return item.quantity;
+    }
+  }
+  return 0;
+}
+function setInventoryItemQuantity(inventory, itemAddress, quantity, relay) {
+  assertItemAddress(itemAddress);
+  assertNonNegativeInteger(quantity, "quantity");
+  const existing = inventory.items.find((item) => item.address === itemAddress);
+  if (quantity === 0) {
+    return {
+      ...inventory,
+      items: inventory.items.filter((item) => item.address !== itemAddress).map((item) => ({ ...item }))
+    };
+  }
+  const resolvedRelay = relay ?? existing?.relay ?? "";
+  if (existing) {
+    return {
+      ...inventory,
+      items: inventory.items.map(
+        (item) => item.address === itemAddress ? { address: itemAddress, relay: resolvedRelay, quantity } : { ...item }
+      )
+    };
+  }
+  return {
+    ...inventory,
+    items: [
+      ...inventory.items.map((item) => ({ ...item })),
+      { address: itemAddress, relay: resolvedRelay, quantity }
+    ]
+  };
+}
+function addInventoryItemQuantity(inventory, itemAddress, amount, relay) {
+  assertItemAddress(itemAddress);
+  assertNonNegativeInteger(amount, "amount");
+  const current = getInventoryItemQuantity(inventory, itemAddress);
+  const next = addQuantitiesChecked(current, amount, "quantity");
+  return setInventoryItemQuantity(inventory, itemAddress, next, relay);
+}
+function removeInventoryItemQuantity(inventory, itemAddress, amount) {
+  assertItemAddress(itemAddress);
+  assertNonNegativeInteger(amount, "amount");
+  const current = getInventoryItemQuantity(inventory, itemAddress);
+  const next = Math.max(0, current - amount);
+  return setInventoryItemQuantity(inventory, itemAddress, next);
+}
+function getInventoryItems(inventory) {
+  return inventory.items.map((item) => ({ ...item }));
+}
+
+export { BASED_ON_MARKER, GRANT_MARKER, KIND_GAME_INVENTORY, KIND_GAME_ITEM_DEFINITION, 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 };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map