Oceanic.js SDK


npm install @mochi-analytics/core @mochi-analytics/oceanic

Quick start


import { Client } from "oceanic.js";
import { MochiClient } from "@mochi-analytics/core";
import { attachMochi } from "@mochi-analytics/oceanic";
 
const mochi = new MochiClient({
  url: "https://mochi.example.com",   // your Mochi instance
  apiKey: process.env.MOCHI_API_KEY!, // from the bot's settings page
});
 
const client = new Client({
  auth: `Bot ${process.env.DISCORD_TOKEN}`,
  gateway: { intents: ["GUILDS"] },
});
attachMochi(client, mochi);
 
client.connect();
 
process.on("SIGTERM", async () => {
  await mochi.shutdown(); // flush remaining events
  client.disconnect(false);
});

That’s it. Mochi now records slash/context-menu command usage, guild joins and leaves, and an hourly server-count snapshot.

Oceanic runs every shard inside one process, so Mochi sends one snapshot per shard, each carrying that shard’s own guild count and gateway latency.

Options


attachMochi(client, mochi, {
  includeGuildNames: true,        // put guild names in join/leave metadata
  ignoreCommands: ["ping"],       // skip noisy commands
  snapshotIntervalMs: 30 * 60e3,  // default 1 hour
  autoTrackCommands: false,       // see "accurate timings" below
});

Accurate duration & success

Auto-tracking records commands the moment the interaction arrives — it can’t see whether your handler succeeded or how long it took. For that, disable auto-tracking and wrap your handlers:


import { wrapHandler } from "@mochi-analytics/oceanic";
 
attachMochi(client, mochi, { autoTrackCommands: false });
 
const play = wrapHandler(mochi, async (interaction) => {
  // your command logic — duration and thrown errors are recorded
});

Custom events


mochi.track({
  type: "custom",
  name: "premium_purchased",
  userId: interaction.user.id,
  guildId: interaction.guildID ?? undefined,
  meta: { tier: "gold" },
});

Design guarantees

Events are batched (flushed every 5 s or 100 events) and sent in the background — track() never blocks or throws.
Transient failures retry with backoff; the queue is bounded (oldest dropped first), so a dead Mochi instance can never leak memory or crash the bot.
Raw user ids are hashed server-side with a per-bot salt and never stored.

Everything above is a thin wrapper over two HTTP endpoints — see the Ingest API to integrate from any other framework.