@xforge-dev/forge-kit 0.17.1 → 0.18.1

package/dist/jobs.d.ts

@@ -0,0 +1,59 @@
+export declare const JOB_CATALOG_VERSION = 1;
+export declare const JOB_CATALOG_URL = "https://cdn.xforge.dev/data/jobs.json";
+export type JobBranch = 'warrior' | 'magician' | 'bowman' | 'thief' | 'pirate';
+export type JobStat = 'STR' | 'DEX' | 'INT' | 'LUK' | 'HP' | 'ALL';
+export type JobStatus = 'released' | 'upcoming' | 'retired';
+export type LegionRank = 'B' | 'A' | 'S' | 'SS' | 'SSS';
+export declare const JOB_LEGION_RANKS: readonly ["B", "A", "S", "SS", "SSS"];
+export type RankValues<T> = [T, T, T, T, T];
+/** Numeric keys BossForge models; others are display-only. STR..LUK are Final stats. */
+export type LegionStatKey = 'STR' | 'DEX' | 'INT' | 'LUK' | 'hp' | 'hpPct' | 'mpPct' | 'critRate' | 'critDamage' | 'ied' | 'boss' | 'summonDuration' | 'buffDuration' | 'statusDamage' | 'cooldownPct' | 'mesos' | 'exp' | 'speed' | 'statusResist' | 'hpRecover' | 'mpRecover' | 'bonusDamage';
+export type JobLegionEffect = {
+    stats: Partial<Record<LegionStatKey, RankValues<number>>>;
+    text: RankValues<string>;
+};
+/** A link shared by several jobs (Explorer branch links, Cygnus, Shine) has the same `key` on each. */
+export type JobLink = {
+    key: string;
+    name: string;
+    icon: string;
+    max: number;
+    text: string[];
+};
+export type Job = {
+    name: string;
+    aliases: string[];
+    branches: JobBranch[];
+    faction: string;
+    mainStat: JobStat;
+    secondaryStats: JobStat[];
+    status: JobStatus;
+    icon: string | null;
+    nexon: {
+        jobId: number;
+        jobDetail: number;
+    } | null;
+    legionRankLevels?: RankValues<number>;
+    legion: JobLegionEffect | null;
+    link: JobLink | null;
+};
+export type JobCatalog = {
+    version: number;
+    updated: string;
+    jobs: Job[];
+};
+/** Validates the shape by hand (the kit has no schema library); throws an Error naming the first problem. */
+export declare function parseJobCatalog(data: unknown): JobCatalog;
+export declare function setJobCatalog(next: JobCatalog): void;
+export declare function getJobCatalog(): JobCatalog;
+/** Replaces the unknown-job reporter (default console.warn); each distinct trimmed name is reported once. */
+export declare function onUnknownJob(fn: (name: string) => void): void;
+/** Looks up a job by canonical name or alias, trimmed and case-insensitive. */
+export declare function job(name: string | null | undefined): Job | null;
+export declare function jobName(name: string | null | undefined): string | null;
+/** Jobs sorted by name; retired ones are left out unless asked for. */
+export declare function allJobs(opts?: {
+    includeRetired?: boolean;
+}): readonly Job[];
+/** Highest Legion rank a character of this level has reached; null below rank B's level. */
+export declare function legionRankFor(j: Job, level: number): LegionRank | null;

package/dist/jobs.js

@@ -0,0 +1,127 @@
+import { JOBS_SNAPSHOT } from './jobs-snapshot.js';
+export const JOB_CATALOG_VERSION = 1;
+export const JOB_CATALOG_URL = 'https://cdn.xforge.dev/data/jobs.json';
+export const JOB_LEGION_RANKS = ['B', 'A', 'S', 'SS', 'SSS'];
+/** Standard level needed for each rank (B..SSS); a job may override via `legionRankLevels`. */
+const STANDARD_RANK_LEVELS = [60, 100, 140, 200, 250];
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isRank5 = (v, type) => Array.isArray(v) && v.length === 5 && v.every((x) => typeof x === type);
+const BRANCHES = ['warrior', 'magician', 'bowman', 'thief', 'pirate'];
+const STATS = ['STR', 'DEX', 'INT', 'LUK', 'HP', 'ALL'];
+const isOneOf = (list, v) => list.includes(v);
+const isListOf = (list, v) => Array.isArray(v) && v.every((x) => isOneOf(list, x));
+/** Validates the shape by hand (the kit has no schema library); throws an Error naming the first problem. */
+export function parseJobCatalog(data) {
+    if (!isObj(data))
+        throw new Error('job catalog: not an object');
+    if (data.version !== JOB_CATALOG_VERSION)
+        throw new Error(`job catalog: unsupported version ${String(data.version)}`);
+    if (typeof data.updated !== 'string')
+        throw new Error('job catalog: updated must be a string');
+    if (!Array.isArray(data.jobs))
+        throw new Error('job catalog: jobs must be an array');
+    const owner = new Map();
+    const claim = (key, name) => {
+        const k = key.trim().toLowerCase();
+        const prev = owner.get(k);
+        if (prev !== undefined)
+            throw new Error(`job "${name}": name or alias "${key}" already used by "${prev}"`);
+        owner.set(k, name);
+    };
+    for (const raw of data.jobs) {
+        if (!isObj(raw) || typeof raw.name !== 'string' || !raw.name.trim())
+            throw new Error('job catalog: a job has no name');
+        const name = raw.name;
+        const bad = (why) => new Error(`job "${name}": ${why}`);
+        if (!Array.isArray(raw.aliases) || !raw.aliases.every((a) => typeof a === 'string'))
+            throw bad('aliases must be strings');
+        if (raw.aliases.some((a) => !a.trim()))
+            throw bad('an alias is empty');
+        if (!isListOf(BRANCHES, raw.branches))
+            throw bad(`branches must be from ${BRANCHES.join(', ')}`);
+        if (typeof raw.faction !== 'string')
+            throw bad('faction must be a string');
+        if (!isOneOf(STATS, raw.mainStat))
+            throw bad(`mainStat must be one of ${STATS.join(', ')}`);
+        if (!isListOf(STATS, raw.secondaryStats))
+            throw bad(`secondaryStats must be from ${STATS.join(', ')}`);
+        if (raw.status !== 'released' && raw.status !== 'upcoming' && raw.status !== 'retired')
+            throw bad('bad status');
+        if (raw.icon !== null && typeof raw.icon !== 'string')
+            throw bad('icon must be a string or null');
+        if (raw.nexon !== null && !(isObj(raw.nexon) && typeof raw.nexon.jobId === 'number' && typeof raw.nexon.jobDetail === 'number')) {
+            throw bad('nexon must be { jobId, jobDetail } numbers or null');
+        }
+        if (raw.legionRankLevels !== undefined && !isRank5(raw.legionRankLevels, 'number'))
+            throw bad('legionRankLevels needs 5 numbers');
+        if (raw.legion !== null) {
+            if (!isObj(raw.legion) || !isObj(raw.legion.stats))
+                throw bad('legion.stats missing');
+            if (!isRank5(raw.legion.text, 'string'))
+                throw bad('legion.text needs 5 entries');
+            for (const [k, v] of Object.entries(raw.legion.stats))
+                if (!isRank5(v, 'number'))
+                    throw bad(`legion.stats.${k} needs 5 numbers`);
+        }
+        if (raw.link !== null) {
+            const l = raw.link;
+            if (!isObj(l) || typeof l.key !== 'string' || typeof l.name !== 'string' || typeof l.icon !== 'string'
+                || typeof l.max !== 'number' || !Array.isArray(l.text))
+                throw bad('malformed link');
+            if (l.text.length !== l.max || !l.text.every((t) => typeof t === 'string'))
+                throw bad('link.text needs one string per level up to max');
+        }
+        claim(name, name);
+        for (const a of raw.aliases)
+            claim(a, name);
+    }
+    return data;
+}
+let catalog = JOBS_SNAPSHOT;
+let byName = new Map();
+const norm = (s) => s.trim().toLowerCase();
+export function setJobCatalog(next) {
+    catalog = next;
+    byName = new Map();
+    for (const j of next.jobs) {
+        byName.set(norm(j.name), j);
+        for (const a of j.aliases)
+            byName.set(norm(a), j);
+    }
+}
+/** The registry starts as the built-in copy taken from data/jobs.json when the kit was built. */
+setJobCatalog(JOBS_SNAPSHOT);
+export function getJobCatalog() { return catalog; }
+let report = (name) => console.warn(`[forge-kit] unknown job: ${name}`);
+const reported = new Set();
+/** Replaces the unknown-job reporter (default console.warn); each distinct trimmed name is reported once. */
+export function onUnknownJob(fn) { report = fn; }
+/** Looks up a job by canonical name or alias, trimmed and case-insensitive. */
+export function job(name) {
+    const t = name?.trim();
+    if (!t)
+        return null;
+    const found = byName.get(t.toLowerCase());
+    if (found)
+        return found;
+    if (!reported.has(t)) {
+        reported.add(t);
+        report(t);
+    }
+    return null;
+}
+export function jobName(name) { return job(name)?.name ?? null; }
+/** Jobs sorted by name; retired ones are left out unless asked for. */
+export function allJobs(opts = {}) {
+    return catalog.jobs
+        .filter((j) => opts.includeRetired || j.status !== 'retired')
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Highest Legion rank a character of this level has reached; null below rank B's level. */
+export function legionRankFor(j, level) {
+    const levels = j.legionRankLevels ?? STANDARD_RANK_LEVELS;
+    let rank = null;
+    levels.forEach((min, i) => { if (level >= min)
+        rank = JOB_LEGION_RANKS[i]; });
+    return rank;
+}

package/dist/server.d.ts

@@ -24,3 +24,4 @@ export declare function updateForgeSession(request: NextRequest): Promise<{
  * receiving page; null everywhere else.
  */
 export declare function forgeLegacyResponse(request: NextRequest): NextResponse | null;
+export { refreshJobCatalog } from './jobs-server.js';

package/dist/server.js

@@ -76,3 +76,4 @@ export function forgeLegacyResponse(request) {
         },
     });
 }
+export { refreshJobCatalog } from './jobs-server.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xforge-dev/forge-kit",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Shared auth, app registry and UI for xForge apps",
   "license": "MIT",
   "repository": {
@@ -31,8 +31,9 @@
     "./tokens.css": "./dist/tokens.css"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && cp src/tokens.css dist/tokens.css",
+    "build": "npm run snapshot-jobs && rm -rf dist && tsc -p tsconfig.json && cp src/tokens.css dist/tokens.css",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "snapshot-jobs": "node scripts/snapshot-jobs.mjs",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },