fix: handle order events correctly and reorganize tests

- Fix OpenSea order event handling (event_type='order' with order_type for specifics)
- Add escapeMarkdown for Discord usernames to prevent formatting issues
- Reorganize test folder structure by domain (opensea/, platforms/, utils/)
- Add live BAYC fixture data for comprehensive event type testing
- Update types to handle null nft/asset/criteria fields from API

Author: ryanio

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensea-activity-bot",
-  "version": "3.5.5",
+  "version": "3.5.6",
   "description": "A bot that shares new OpenSea events for a collection to Discord and Twitter.",
   "author": "Ryan Ghods <ryan@ryanio.com>",
   "license": "MIT",
@@ -20,6 +20,7 @@
   },
   "dependencies": {
     "discord.js": "^14.25.1",
+    "dotenv": "^17.2.3",
     "ethers": "^6.16.0",
     "sharp": "^0.33.5",
     "timeago.js": "^4.0.2",

src/index.ts

@@ -1,3 +1,4 @@
+import "dotenv/config";
 import { Client, Events, type TextBasedChannel } from "discord.js";
 import {
   type EventTimestampSource,

src/platforms/discord.ts

@@ -40,6 +40,13 @@ import {
 
 const log = prefixedLogger("Discord");
 
+/**
+ * Escapes Discord markdown special characters to prevent formatting issues.
+ * Characters escaped: _ * ~ ` | >
+ */
+const escapeMarkdown = (text: string): string =>
+  text.replace(/(?<special>[_*~`|>])/g, "\\$<special>");
+
 // Initialize event group manager for Discord
 const groupConfig = getDefaultEventGroupConfig("DISCORD");
 const groupManager = new EventGroupManager(groupConfig);
@@ -99,25 +106,40 @@ const buildOrderEmbed = async (
     order_type: string;
     expiration_date: number;
     maker: string;
-    criteria: { trait: { type: string; value: string } };
+    criteria: {
+      trait?: { type: string; value: string };
+      traits?: Array<{ type: string; value: string }>;
+    };
   };
   const fields: Field[] = [];
   let title = "";
-  const { quantity, decimals, symbol } = payment;
-  const inTime = format(new Date(expiration_date * MS_PER_SECOND));
+  const { quantity, decimals, symbol } = payment ?? {
+    quantity: "0",
+    decimals: 18,
+    symbol: "ETH",
+  };
+  const inTime = expiration_date
+    ? format(new Date(expiration_date * MS_PER_SECOND))
+    : "Unknown";
   if (order_type === "auction") {
     title += "Auction:";
     const price = formatAmount(quantity, decimals, symbol);
     fields.push({ name: "Starting Price", value: price });
     fields.push({ name: "Ends", value: inTime });
   } else if (order_type === "trait_offer") {
-    const traitType = criteria.trait.type;
-    const traitValue = criteria.trait.value;
+    // Get trait info from criteria - can be in trait or traits array
+    const traitInfo = criteria?.trait ?? criteria?.traits?.[0];
+    const traitType = traitInfo?.type ?? "Unknown";
+    const traitValue = traitInfo?.value ?? "Unknown";
     title += `Trait offer: ${traitType} -> ${traitValue}`;
     const price = formatAmount(quantity, decimals, symbol);
     fields.push({ name: "Price", value: price });
     fields.push({ name: "Expires", value: inTime });
-  } else if (order_type === "item_offer") {
+  } else if (
+    order_type === "item_offer" ||
+    order_type === "offer" ||
+    order_type === "criteria_offer"
+  ) {
     title += "Item offer:";
     const price = formatAmount(quantity, decimals, symbol);
     fields.push({ name: "Price", value: price });
@@ -128,12 +150,15 @@ const buildOrderEmbed = async (
     fields.push({ name: "Price", value: price });
     fields.push({ name: "Expires", value: inTime });
   } else {
+    // Default to listing
     title += "Listed for sale:";
     const price = formatAmount(quantity, decimals, symbol);
     fields.push({ name: "Price", value: price });
     fields.push({ name: "Expires", value: inTime });
   }
-  fields.push({ name: "By", value: await username(maker) });
+  if (maker) {
+    fields.push({ name: "By", value: escapeMarkdown(await username(maker)) });
+  }
   return { title, fields };
 };
 
@@ -148,7 +173,7 @@ const buildSaleEmbed = async (
   const { quantity, decimals, symbol } = payment;
   const price = formatAmount(quantity, decimals, symbol);
   fields.push({ name: "Price", value: price });
-  fields.push({ name: "By", value: await username(buyer) });
+  fields.push({ name: "By", value: escapeMarkdown(await username(buyer)) });
   return { title: "Purchased:", fields };
 };
 
@@ -174,27 +199,48 @@ const buildTransferEmbed = async (
       (event as unknown as { asset?: { token_standard?: string } })?.asset
         ?.token_standard;
 
-    const toName = await username(to_address);
+    const toName = escapeMarkdown(await username(to_address));
     const toValue = formatEditionsText(toName, tokenStandard, quantity);
     fields.push({ name: "To", value: toValue });
     return { title: "Minted:", fields };
   }
   if (kind === "burn") {
-    fields.push({ name: "From", value: await username(from_address) });
+    fields.push({
+      name: "From",
+      value: escapeMarkdown(await username(from_address)),
+    });
     return { title: "Burned:", fields };
   }
-  fields.push({ name: "From", value: await username(from_address) });
-  fields.push({ name: "To", value: await username(to_address) });
+  fields.push({
+    name: "From",
+    value: escapeMarkdown(await username(from_address)),
+  });
+  fields.push({
+    name: "To",
+    value: escapeMarkdown(await username(to_address)),
+  });
   return { title: "Transferred:", fields };
 };
 
-const isOrderLikeType = (t: unknown): boolean => {
+const isOrderLikeType = (t: unknown, orderType?: string): boolean => {
   const s = String(t);
+  // Check order_type for "order" events
+  if (s === "order" && orderType) {
+    return (
+      orderType === "listing" ||
+      orderType === "item_offer" ||
+      orderType === "trait_offer" ||
+      orderType === "collection_offer" ||
+      orderType === "auction"
+    );
+  }
+  // Legacy event_type handling
   return (
     s === BotEvent.listing ||
     s === BotEvent.offer ||
     s === "trait_offer" ||
-    s === "collection_offer"
+    s === "collection_offer" ||
+    s === "listing"
   );
 };
 
@@ -216,7 +262,7 @@ const embed = async (event: AggregatorEvent) => {
   }
   let fields: Field[] = [];
   let title = "";
-  if (isOrderLikeType(event_type)) {
+  if (isOrderLikeType(event_type, order_type)) {
     ({ title, fields } = await buildOrderEmbed(event));
   } else if (event_type === EventType.sale) {
     ({ title, fields } = await buildSaleEmbed(event));
@@ -310,7 +356,7 @@ const buildGroupEmbed = async (group: GroupedEvent): Promise<EmbedBuilder> => {
 
   if (actorAddress) {
     const label = getActorLabelForKind(kind);
-    const actorName = await username(actorAddress);
+    const actorName = escapeMarkdown(await username(actorAddress));
     fields.push({ name: label, value: actorName, inline: true });
   }
 

src/platforms/twitter.ts

@@ -1,5 +1,5 @@
 import { TwitterApi } from "twitter-api-v2";
-import { EventType, getCollectionSlug, opensea, username } from "../opensea";
+import { getCollectionSlug, opensea, username } from "../opensea";
 import type { BotEvent, OpenSeaAssetEvent, OpenSeaPayment } from "../types";
 import { txHashFor } from "../utils/aggregator";
 import { MS_PER_SECOND, SECONDS_PER_MINUTE } from "../utils/constants";
@@ -250,7 +250,11 @@ const formatOrderText = async (
   if (order_type === "listing") {
     return `listed on sale for ${price} by ${name}`;
   }
-  if (order_type === "item_offer") {
+  if (
+    order_type === "item_offer" ||
+    order_type === "offer" ||
+    order_type === "criteria_offer"
+  ) {
     return `has a new offer for ${price} by ${name}`;
   }
   if (order_type === "collection_offer") {
@@ -259,6 +263,9 @@ const formatOrderText = async (
   if (order_type === "trait_offer") {
     return `has a new trait offer for ${price} by ${name}`;
   }
+  if (order_type === "auction") {
+    return `has a new auction starting at ${price} by ${name}`;
+  }
   return "";
 };
 
@@ -345,6 +352,16 @@ const textForTransfer = async (
   return text;
 };
 
+// Helper sets for event type classification
+const ORDER_EVENT_TYPES = new Set([
+  "order",
+  "listing",
+  "offer",
+  "trait_offer",
+  "collection_offer",
+]);
+const TRANSFER_EVENT_TYPES = new Set(["transfer", "mint"]);
+
 export const textForTweet = async (event: OpenSeaAssetEvent) => {
   const ev = event;
   const {
@@ -356,32 +373,28 @@ export const textForTweet = async (event: OpenSeaAssetEvent) => {
     buyer,
     expiration_date,
   } = ev;
-  const nft = ev.nft ?? asset;
+  // Handle null asset from trait/collection offers by converting to undefined
+  const nft = ev.nft ?? (asset === null ? undefined : asset);
   let text = "";
 
-  if (
-    (event_type === "listing" ||
-      event_type === "offer" ||
-      event_type === "trait_offer" ||
-      event_type === "collection_offer") &&
-    payment &&
-    maker &&
-    order_type &&
-    typeof expiration_date === "number"
-  ) {
+  // Handle "order" event type - the API returns this for listings and offers
+  // The actual type is determined by order_type
+  const isListingOrOfferEvent = ORDER_EVENT_TYPES.has(event_type);
+  const isTransferOrMintEvent = TRANSFER_EVENT_TYPES.has(event_type);
+
+  if (isListingOrOfferEvent && payment && maker && order_type) {
+    // Use expiration_date if available, default to 0 if not
+    const expDate = typeof expiration_date === "number" ? expiration_date : 0;
     text += await textForOrder({
       nft,
       payment,
       maker,
       order_type,
-      expiration_date,
+      expiration_date: expDate,
     });
-  } else if (event_type === EventType.sale && payment && buyer) {
+  } else if (event_type === "sale" && payment && buyer) {
     text += await textForSale({ nft, payment, buyer });
-  } else if (
-    event_type === EventType.transfer ||
-    event_type === EventType.mint
-  ) {
+  } else if (isTransferOrMintEvent) {
     text += await textForTransfer(nft, ev);
   }
   if (nft?.identifier) {
@@ -407,7 +420,9 @@ const uploadImagesForGroup = async (
 
   const images: string[] = [];
   for (const e of sortedGroup) {
-    const url = imageForNFT(e.nft ?? e.asset);
+    // Handle null asset from trait/collection offers
+    const nft = e.nft ?? (e.asset === null ? undefined : e.asset);
+    const url = imageForNFT(nft);
     if (url) {
       images.push(url);
     }
@@ -479,7 +494,10 @@ const tweetSingle = async (
   await refetchMintMetadataForEvent(event);
 
   let mediaId: string | undefined;
-  const image = imageForNFT(event.nft ?? event.asset);
+  // Handle null asset from trait/collection offers
+  const nftForImage =
+    event.nft ?? (event.asset === null ? undefined : event.asset);
+  const image = imageForNFT(nftForImage);
   if (image) {
     try {
       const { buffer, mimeType } = await fetchImageBuffer(image);

src/types.ts

@@ -72,15 +72,31 @@ export type OpenSeaNFT = {
   rarity?: OpenSeaRarity;
 };
 
+// OpenSea API event_type values
+// Note: The API returns "order" for listings and all offer types
+// The actual distinction is made via the order_type field
+export type OpenSeaEventType =
+  | "sale"
+  | "transfer"
+  | "mint"
+  | "order" // Used for listings and offers - check order_type for specifics
+  // Legacy values (for backwards compatibility with existing code/tests)
+  | "listing"
+  | "offer"
+  | "trait_offer"
+  | "collection_offer";
+
+// OpenSea API order_type values (when event_type is "order")
+export type OpenSeaOrderType =
+  | "listing"
+  | "item_offer"
+  | "trait_offer"
+  | "collection_offer"
+  | "auction"
+  | "criteria_offer"; // Legacy value
+
 export type OpenSeaAssetEvent = {
-  event_type:
-    | "sale"
-    | "transfer"
-    | "mint"
-    | "listing"
-    | "offer"
-    | "trait_offer"
-    | "collection_offer";
+  event_type: OpenSeaEventType;
   event_timestamp: number;
   transaction?: string;
   order_hash?: string;
@@ -92,18 +108,27 @@ export type OpenSeaAssetEvent = {
   buyer?: string;
   quantity: number;
   nft?: OpenSeaNFT;
-  asset?: OpenSeaNFT;
-  order_type?: string;
-  start_date?: number;
+  asset?: OpenSeaNFT | null; // Can be null for trait/collection offers
+  order_type?: OpenSeaOrderType;
+  start_date?: number | null;
   expiration_date?: number;
   maker?: string;
   taker?: string;
-  criteria?: unknown;
+  criteria?: OpenSeaCriteria | null; // Can be null for collection offers and listings
   is_private_listing?: boolean;
   from_address?: string;
   to_address?: string;
 };
 
+// Criteria for trait offers
+export type OpenSeaCriteria = {
+  collection?: { slug: string };
+  contract?: { address: string };
+  trait?: { type: string; value: string };
+  traits?: Array<{ type: string; value: string }>;
+  encoded_token_ids?: string | null;
+};
+
 export type OpenSeaEventsResponse = {
   asset_events: OpenSeaAssetEvent[];
   next?: string;

src/utils/aggregator.ts

@@ -13,7 +13,7 @@ export type AggregatorEvent = {
   hash?: string;
   event_timestamp?: number | string;
   nft?: NFTLike;
-  asset?: NFTLike;
+  asset?: NFTLike | null; // Can be null for trait/collection offers
   event_type?: string;
   order_type?: string;
 };

src/utils/event-grouping.ts

@@ -397,7 +397,8 @@ export const getTopExpensiveEvents = (
     const price = payment
       ? formatAmount(payment.quantity, payment.decimals, payment.symbol)
       : null;
-    const nft = event.nft ?? event.asset;
+    // Handle null asset from trait/collection offers
+    const nft = event.nft ?? (event.asset === null ? undefined : event.asset);
 
     return {
       event,