fflogsanalyzer

Query enemy cast events from FFLogs reports by ability name, with optional occurrence filtering. Works as both a CLI tool and an importable library.

Installation

npm install git+https://github.com/<you>/fflogsanalyzer.git

Setup

Create a .env file with FFLogs OAuth2 client credentials (obtain at https://www.fflogs.com/api/clients/):

FFLOGS_CLIENT_ID=your_client_id
FFLOGS_CLIENT_SECRET=your_client_secret

CLI

npx fflogsanalyzer <fflogs-url>

The URL can include a #fight=N fragment to restrict output to a single fight.

Ability filtering is configured via abilities.jsonc in the current working directory:

[
  { "name": "Light Rampant" },
  { "name": "Fulgent Blade", "occurrence": [1, 2, 3] },
  { "name": "Fall of Faith", "occurrence": 2 }
]

Omit occurrence to return all casts of that ability. If abilities.jsonc is absent, all enemy casts are returned.

Library

import { createFFLogsClient, getMatchedCasts } from "fflogsanalyzer";

const client = await createFFLogsClient();

const results = await getMatchedCasts(client, "abc123XYZ", null, [
  { name: "Light Rampant" },
  { name: "Fulgent Blade", occurrence: [1, 2] },
]);

for (const { fight, casts } of results) {
  console.log(`Fight ${fight.id}: ${casts.length} matched casts`);
}

createFFLogsClient reads FFLOGS_CLIENT_ID and FFLOGS_CLIENT_SECRET from the environment. Load them however you prefer (dotenv, process env, etc.) before calling it.

API

createFFLogsClient(): Promise<GraphQLClient>

Returns an authenticated GraphQL client for use with the functions below.

getMatchedCasts(client, code, fightIds, abilityFilters): Promise<FightCasts[]>

Fetches fights and enemy cast events from a report, filtered by the provided ability filters.

• code — alphanumeric report ID from the FFLogs URL
• fightIds — array of fight IDs to include, or null for all fights
• abilityFilters — array of { name, occurrence? } filters

getMatchedCastsMulti(client, requests, abilityFilters, options?): Promise<ReportResult[]>

The multi-report counterpart of getMatchedCasts. Fetches and matches casts for many reports in a handful of batched GraphQL requests (aliased r0: report(code:$c0){…}) instead of one request per report — the efficient path when aggregating a guild's worth of logs.

• requests — array of { code, fightIds } (fightIds: null = all fights)
• abilityFilters — shared across all reports, same semantics as getMatchedCasts
• options.batchSize — reports per batched request (default DEFAULT_MULTI_BATCH_SIZE = 10)

Each report resolves its filters against its own master data, so each ReportResult is identical to calling getMatchedCasts on that report. Results are returned in requests order; a report that fails to load (deleted/private) yields an empty result rather than throwing, so one bad report never sinks the batch.

Lower-level functions (getMasterData, getFights, getEnemyCasts, getMultiMasterData, getMultiEnemyCasts) are also exported for direct use.

parseFFLogsUrl(url): { code: string; fightIds: number[] | null }

Parses a FFLogs report URL into a report code and optional fight ID list. Throws on an invalid URL.

formatTime(ms: number): string

Formats a millisecond duration as m:ss. Useful for displaying cast timestamps relative to fight start.

loadAbilityFilters(path?: string): AbilityFilter[]

Reads ability filters from a JSONC file (default: abilities.jsonc in the current working directory). Returns [] if the file is absent.