@rtbnext/core 2.0.0-alpha.1

package/dist/job/List.js

@@ -0,0 +1,101 @@
+import { Job } from '../abstract/Job.js';
+import { Fetch } from '../core/Fetch.js';
+import { ListQueue, ProfileQueue } from '../core/Queue.js';
+import { getListConfigByUri } from '../lib/list.js';
+import { List } from '../model/List.js';
+import { Profile } from '../model/Profile.js';
+import { Parser } from '../parser/Parser.js';
+import { ProfileManager } from '../utils/ProfileManager.js';
+export class ListJob extends Job {
+  static fetch = Fetch.getInstance();
+  static profileQueue = ProfileQueue.getInstance();
+  static queue = ListQueue.getInstance();
+  constructor(options = {}) {
+    super(options, 'list');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const method = this.options.profileUpdate ? 'updateData' : 'createOnly';
+      const { uri, args } = this.options.list
+        ? { uri: this.options.list, args: this.options }
+        : ListJob.queue.next()[0];
+      // --- if no URI is provided, exit the job ---
+      if (!uri) return;
+      // --- check if the list already exists for the specified year ---
+      let list = List.get(uri);
+      if (list && args.year && !this.options.override && list.datesInYear(args.year).length)
+        throw new Error(`List with URI ${uri} already exists for year ${args.year}`);
+      // --- fetch raw list data from Forbes ---
+      const res = await ListJob.fetch.list(uri, args.year ?? '0');
+      if (!res?.success || !res.data) throw new Error('Request failed');
+      const { parser, indexItem, listItem } = getListConfigByUri(uri);
+      const th = Date.now() - Job.config.queue.tsThreshold;
+      const { entries } = parser.prepareList(res);
+      // --- determine list date ---
+      const d = new Date(entries[0].date ?? entries[0].timestamp);
+      if (Number.isNaN(d.getTime())) throw new Error(`Failed to determine date for ${uri} list`);
+      if (args.year && d.getFullYear() !== +args.year)
+        throw new Error(`List year ${args.year} does not match data year ${d.getFullYear()}`);
+      this.log(`Processing ${uri} list for year ${args.year ?? '-'} (${entries.length} items)`);
+      // --- process list data ---
+      let count = 0,
+        total = 0,
+        woman = 0,
+        { name, desc } = args;
+      const date = Parser.date(d, 'ymd');
+      const items = [];
+      const queue = [];
+      for (const raw of Object.values(entries)) {
+        name ??= Parser.string(raw.name);
+        desc ??= Parser.string(raw.listDescription);
+        const parsed = new parser(raw);
+        const uri = parsed.uri();
+        const id = parsed.id();
+        let profileData = Profile.factory({ uri, id, info: parsed.info(), bio: parsed.bio() });
+        // --- process profile using ProfileManager ---
+        const { profile, action } = ProfileManager.process(uri, id, profileData, method);
+        if (!profile) {
+          this.log(`Failed to process profile for ${uri}`);
+          continue;
+        }
+        ProfileManager.updateQueue(queue, profile, action, th);
+        profileData = profile.getData();
+        // --- push list item ---
+        items.push(listItem({ parsed, profileData }));
+        count++;
+        total += parsed.networth() ?? 0;
+        woman += +(profileData.info?.gender === 'f');
+      }
+      // --- create list (if not exists) ---
+      if (!name || !desc) throw new Error(`Failed to determine name or description for ${uri} list`);
+      list ??= List.create(uri, indexItem(uri, { name, desc }));
+      if (!list) throw new Error(`Failed to create or retrieve ${uri} list`);
+      this.log(`Saving ${uri} list for year ${args.year ?? '-'} (${count} items)`);
+      // --- create stats ---
+      const stats = parser.stats({ date, count, total, woman });
+      // --- save data ---
+      list.saveSnapshot({ date, count, items, stats }, this.options.override);
+      ListJob.profileQueue.addMany(queue);
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'list',
+    desc: 'Fetch and process Forbes lists',
+    options: [
+      { name: '-l, --list <URI>', desc: 'Specify the list URI to process' },
+      { name: '-y, --year <YYYY>', desc: 'Specify the year to process the list for' },
+      { name: '--name <NAME>', desc: 'Specify a name for the list' },
+      { name: '--desc <DESC>', desc: 'Specify a description for the list' },
+      { name: '-o, --override', desc: 'If set, existing lists will be overridden with new data' },
+      { name: '-u, --update', desc: 'If set, profile data will be updated when processing lists' }
+    ]
+  };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '*/15 1 * * *' // run every 15 minutes between 1:00 and 1:59 AM
+    }
+  ];
+}

package/dist/job/Merge.d.ts

@@ -0,0 +1,10 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TMergeJobOptions } from '../types/job';
+export declare class MergeJob extends Job<TMergeJobOptions> {
+  constructor(options: TMergeJobOptions);
+  private listMergeable;
+  private isMergeable;
+  private merge;
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}

package/dist/job/Merge.js

@@ -0,0 +1,59 @@
+import { Job } from '../abstract/Job.js';
+import { Profile } from '../model/Profile.js';
+import { Parser } from '../parser/Parser.js';
+import { ProfileMerger } from '../utils/ProfileMerger.js';
+export class MergeJob extends Job {
+  constructor(options) {
+    super(options, 'merge');
+  }
+  // --- job runner ---
+  listMergeable(uriLike) {
+    for (const [uri, list] of Object.entries(ProfileMerger.listCandidates(...uriLike))) {
+      console.log(`Candidates for ${uri}:`);
+      if (!list.length) console.log(' - None');
+      for (const candidate of list) console.log(` - ${candidate}`);
+    }
+  }
+  isMergeable(target, source) {
+    const test = ProfileMerger.mergeableProfiles(target.getData(), source.getData());
+    if (test) console.log(`Profiles ${target.getUri()} and ${source.getUri()} are mergeable.`);
+    else console.log(`Profiles ${target.getUri()} and ${source.getUri()} are NOT mergeable.`);
+  }
+  merge(target, source, force, makeAlias) {
+    this.log(`Merging profile ${source.getUri()} into ${target.getUri()}`);
+    const res = ProfileMerger.mergeProfiles(target, source, force, makeAlias);
+    if (!res) throw new Error('Failed to merge profiles.');
+    this.log('Merge completed successfully.');
+  }
+  async run() {
+    await this.protect(async () => {
+      const { list, source, target, dryRun, force, makeAlias } = this.options;
+      if (list?.length) this.listMergeable(list);
+      else if (!source || !target) throw new Error('Invalid arguments for merge job');
+      else {
+        const src = Profile.get(source),
+          tgt = Profile.get(target);
+        if (!src || !tgt) throw new Error('One or both profiles not found');
+        if (dryRun) this.isMergeable(tgt, src);
+        else this.merge(tgt, src, Parser.boolean(force), Parser.boolean(makeAlias));
+      }
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'merge',
+    desc: 'Merge two profiles safely',
+    options: [
+      {
+        name: '-l, --list <URIs>',
+        desc: 'List merge candidates for the given profile URIs (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      { name: '-s, --source <URI>', desc: 'Source profile URI to merge from' },
+      { name: '-t, --target <URI>', desc: 'Target profile URI to merge into' },
+      { name: '--dry-run', desc: 'Perform a dry run of the merge without making any changes' },
+      { name: '--force', desc: 'Force the merge even if there are potential conflicts' },
+      { name: '-a, --make-alias', desc: 'Whether to create an alias from the old URI to the new one after merge' }
+    ]
+  };
+}

package/dist/job/Move.d.ts

@@ -0,0 +1,7 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TMoveJobOptions } from '../types/job';
+export declare class MoveJob extends Job<TMoveJobOptions> {
+  constructor(options: TMoveJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}

package/dist/job/Move.js

@@ -0,0 +1,33 @@
+import { Job } from '../abstract/Job.js';
+import { Utils } from '../core/Utils.js';
+import { Profile } from '../model/Profile.js';
+export class MoveJob extends Job {
+  constructor(options) {
+    super(options, 'move');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const makeAlias = !!this.options.makeAlias;
+      const source = Utils.sanitize(this.options.source);
+      const target = Utils.sanitize(this.options.target);
+      if (!source || !target) throw new Error('Invalid from/to profile names');
+      const profile = Profile.find(source);
+      if (!profile) throw new Error(`Profile ${source} not found`);
+      this.log(`Moving profile from ${source} to ${target} ...`);
+      const res = profile.move(target, makeAlias);
+      if (!res) throw new Error(`Failed to move profile from ${source} to ${target}`);
+      this.log(`Profile moved successfully to ${target}${makeAlias ? ' with alias' : ''}`);
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'move',
+    desc: 'Move a profile from one URI to another',
+    options: [
+      { name: '-s, --source <URI>', desc: 'Source profile URI to move from', required: true },
+      { name: '-t, --target <URI>', desc: 'Target profile URI to move to', required: true },
+      { name: '-a, --make-alias', desc: 'Whether to create an alias from the old URI to the new one' }
+    ]
+  };
+}

package/dist/job/Performance.d.ts

@@ -0,0 +1,8 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TJobClsOptions } from '../types/job';
+export declare class PerformanceJob extends Job {
+  private static readonly index;
+  constructor(options?: TJobClsOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}

package/dist/job/Performance.js

@@ -0,0 +1,27 @@
+import { Job } from '../abstract/Job.js';
+import { Profile } from '../model/Profile.js';
+import { ProfileIndex } from '../model/ProfileIndex.js';
+import { Performance } from '../utils/Performance.js';
+export class PerformanceJob extends Job {
+  static index = ProfileIndex.getInstance();
+  constructor(options = {}) {
+    super(options, 'performance');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      for (const item of PerformanceJob.index.values) {
+        const profile = Profile.getByItem(item);
+        if (!profile) {
+          this.log(`Profile not found for ${item.uri}`, undefined, 'warn');
+          continue;
+        }
+        const performance = Performance.generateProfilePerformance(profile.getHistory());
+        profile.updateData({ performance });
+        profile.save();
+      }
+    });
+  }
+  // --- command definition ---
+  static command = { id: 'performance', desc: 'Generate profile performance data' };
+}

package/dist/job/Profile.d.ts

@@ -0,0 +1,11 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TCronJob, TProfileJobOptions } from '../types/job';
+export declare class ProfileJob extends Job<TProfileJobOptions> {
+  private static readonly fetch;
+  private static readonly queue;
+  private static readonly index;
+  constructor(options?: TProfileJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob<TProfileJobOptions>;
+}

package/dist/job/Profile.js

@@ -0,0 +1,76 @@
+import { Job } from '../abstract/Job.js';
+import { Fetch } from '../core/Fetch.js';
+import { ProfileQueue } from '../core/Queue.js';
+import { Profile } from '../model/Profile.js';
+import { ProfileIndex } from '../model/ProfileIndex.js';
+import { Parser } from '../parser/Parser.js';
+import { ProfileParser } from '../parser/ProfileParser.js';
+import { ProfileManager } from '../utils/ProfileManager.js';
+import { Ranking } from '../utils/Ranking.js';
+import { Wiki } from '../utils/Wiki.js';
+export class ProfileJob extends Job {
+  static fetch = Fetch.getInstance();
+  static queue = ProfileQueue.getInstance();
+  static index = ProfileIndex.getInstance();
+  constructor(options = {}) {
+    super(options, 'profile');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const method = this.options.replace ? 'setData' : 'updateData';
+      const batch = this.options.profiles?.length
+        ? this.options.profiles
+        : ProfileJob.queue.nextUri(Job.config.fetch.rateLimit.batchSize);
+      for (const raw of await ProfileJob.fetch.profile(...batch)) {
+        if (!raw?.success || !raw.data) {
+          this.log('Request failed', raw, 'warn');
+          continue;
+        }
+        // --- parse raw profile data ---
+        const parser = new ProfileParser(raw.data);
+        const uri = parser.uri();
+        const id = parser.id();
+        const profileData = Profile.factory({
+          uri,
+          id,
+          info: parser.info(),
+          bio: parser.bio(),
+          related: parser.related(),
+          media: parser.media()
+        });
+        // --- enrich profile data with ranking and wiki ---
+        if (!Parser.boolean(this.options.skipRanking))
+          profileData.ranking = Ranking.generateProfileRanking(parser.sortedLists(), profileData.ranking);
+        if (!Parser.boolean(this.options.skipWiki)) profileData.wiki = await Wiki.fromProfileData(profileData);
+        // --- process profile using ProfileManager ---
+        const { action, success } = ProfileManager.process(uri, id, profileData, method, true, true);
+        if (!success) this.log(`Failed to process profile with uri ${uri}`, profileData, 'warn');
+        // --- add profile aliases ---
+        ProfileJob.index.addAliases(uri, ...parser.aliases());
+        this.log(`Profile with uri ${uri} processed in ${action} mode`);
+      }
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'profile',
+    desc: 'Fetch and update Forbes profiles',
+    options: [
+      {
+        name: '-p, --profiles <URIs>',
+        desc: 'Process specific profiles by URI (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      { name: '--replace', desc: 'Replace existing profile data' },
+      { name: '--skip-ranking', desc: 'Skip ranking generation' },
+      { name: '--skip-wiki', desc: 'Skip wiki data enrichment' }
+    ]
+  };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '*/5 2-23 * * *' // run every 5 minutes between 2:00 and 23:59
+    }
+  ];
+}

package/dist/job/Queue.d.ts

@@ -0,0 +1,8 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TQueueJobOptions } from '../types/job';
+export declare class QueueJob extends Job<TQueueJobOptions> {
+  private static readonly queues;
+  constructor(options: TQueueJobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}

package/dist/job/Queue.js

@@ -0,0 +1,54 @@
+import { Job } from '../abstract/Job.js';
+import { ListQueue, ProfileQueue } from '../core/Queue.js';
+import { Parser } from '../parser/Parser.js';
+export class QueueJob extends Job {
+  static queues = { list: ListQueue.getInstance(), profile: ProfileQueue.getInstance() };
+  constructor(options) {
+    super(options, 'queue');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const { type, clear, add, remove, prio, args } = this.options;
+      const queue = QueueJob.queues[type];
+      if (!queue) throw new Error(`Unknown queue type: ${type}`);
+      if (clear) queue.clear();
+      if (add?.length) queue.addMany(add.map(uriLike => ({ uriLike, prio, args })));
+      if (remove?.length) queue.remove(...remove);
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'queue',
+    desc: 'Managing list and profile queues',
+    options: [
+      {
+        name: '-t, --type <TYPE>',
+        desc: 'Which queue to use (available: list, profile)',
+        parser: v => v.toLowerCase(),
+        required: true
+      },
+      {
+        name: '--add <URIs>',
+        desc: 'Add items to the queue (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      {
+        name: '--remove <URIs>',
+        desc: 'Remove items from the queue (comma-separated)',
+        parser: v => Parser.list(v, 'string', ',')
+      },
+      {
+        name: '--prio <NUMBER>',
+        desc: 'Set priority of added items (higher number = higher priority)',
+        parser: v => Parser.strict(v, 'number')
+      },
+      {
+        name: '--args <JSON>',
+        desc: 'Additional queue item arguments as JSON string',
+        parser: v => Parser.strict(v, 'json')
+      },
+      { name: '-c, --clear', desc: 'Clear the queue before adding new items' }
+    ]
+  };
+}

package/dist/job/RTB.d.ts

@@ -0,0 +1,12 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TCronJob, TJobClsOptions } from '../types/job';
+export declare class RTBJob extends Job {
+  private static readonly fetch;
+  private static readonly mover;
+  private static readonly queue;
+  private static readonly stats;
+  constructor(options?: TJobClsOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob;
+}

package/dist/job/RTB.js

@@ -0,0 +1,121 @@
+import { Job } from '../abstract/Job.js';
+import { Fetch } from '../core/Fetch.js';
+import { ProfileQueue } from '../core/Queue.js';
+import { LISTS } from '../lib/list.js';
+import { List } from '../model/List.js';
+import { Mover } from '../model/Mover.js';
+import { Profile } from '../model/Profile.js';
+import { ProfileIndex } from '../model/ProfileIndex.js';
+import { Stats } from '../model/Stats.js';
+import { Parser } from '../parser/Parser.js';
+import { Performance } from '../utils/Performance.js';
+import { ProfileManager } from '../utils/ProfileManager.js';
+export class RTBJob extends Job {
+  static fetch = Fetch.getInstance();
+  static mover = Mover.getInstance();
+  static queue = ProfileQueue.getInstance();
+  static stats = Stats.getInstance();
+  constructor(options = {}) {
+    super(options, 'rtb');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const res = await RTBJob.fetch.list('rtb', '0');
+      if (!res?.success || !res.data) throw new Error('Request failed');
+      const date = Parser.date(undefined, 'ymd');
+      const ts = new Date(date).getTime();
+      // --- if RTB list is already up to date, exit the job ---
+      if (RTBJob.stats.getGlobalStats().date === date) {
+        this.log('RTB list is already up to date');
+        return;
+      }
+      const { parser, indexItem, listItem } = LISTS.rtb;
+      const th = Date.now() - Job.config.queue.tsThreshold;
+      const { entries } = parser.prepareList(res);
+      this.log(`Processing RTB list dated ${date} (${entries.length} items)`);
+      // --- process list data ---
+      let count = 0,
+        total = 0,
+        woman = 0;
+      const items = [];
+      const mover = Mover.factory(date);
+      const queue = [];
+      for (const [i, raw] of Object.entries(entries)) {
+        raw.date = ts;
+        // --- parse raw list data ---
+        const parsed = new parser(raw);
+        const uri = parsed.uri();
+        const id = parsed.id();
+        const rank = parsed.rank();
+        const networth = parsed.networth();
+        if (!rank || !networth) {
+          this.log(`Skipping invalid RTB entry for ${uri}`);
+          continue;
+        }
+        let profileData = Profile.factory({ uri, id, info: parsed.info(), bio: parsed.bio(), assets: parsed.assets() });
+        // --- process profile using ProfileManager ---
+        const { profile, action } = ProfileManager.process(uri, id, profileData, 'updateData');
+        if (!profile) {
+          this.log(`Failed to process profile for ${uri}`);
+          continue;
+        }
+        ProfileManager.updateQueue(queue, profile, action, th);
+        profileData = profile.getData();
+        // --- process realtime data ---
+        const prev = entries[Number(i) - 1]?.uri;
+        const next = entries[Number(i) + 1]?.uri;
+        const realtime = parsed.realtime(profileData, prev, next);
+        const { flag, rankDiff } = parsed.rankDiff(profileData);
+        const { value = 0, percent = 0 } = realtime?.today ?? {};
+        // --- update profile data ---
+        profile.addHistory([date, rank, networth, value, percent]);
+        const performance = Performance.generateProfilePerformance(profile.getHistory());
+        profile.updateData({ realtime, performance });
+        profile.save();
+        profileData = profile.getData();
+        const name = profileData.info.name.shortName;
+        // --- skip profiles if their networth is less than $1B ---
+        if (networth < 1000 && networth - value < 1000) continue;
+        // --- aggregate mover data ---
+        Mover.aggregate(realtime, uri, name, mover, total);
+        // --- push list item ---
+        items.push(listItem({ parsed, profileData, flag, rankDiff, realtime }));
+        count++;
+        total += networth;
+        woman += +(profileData.info?.gender === 'f');
+      }
+      // --- create "rtb" list ---
+      const list = List.get('rtb') || List.create('rtb', indexItem());
+      if (!list) throw new Error('Failed to create or retrieve RTB list');
+      this.log(`Saving RTB list dated ${date} (${count} items)`);
+      // --- create stats ---
+      const stats = parser.stats({
+        date,
+        count,
+        total,
+        woman,
+        today: { value: mover.today.total.value, percent: mover.today.total.percent },
+        ytd: { value: mover.ytd.total.value, percent: mover.ytd.total.percent }
+      });
+      const globalStats = {
+        ...stats,
+        stats: { profiles: ProfileIndex.getInstance().size, days: list.getDates().length }
+      };
+      // --- save data ---
+      list.saveSnapshot({ date, count, items, stats });
+      RTBJob.mover.saveSnapshot(mover);
+      RTBJob.queue.addMany(queue);
+      RTBJob.stats.setGlobalStats(globalStats);
+      RTBJob.stats.updateHistory(globalStats);
+    });
+  }
+  // --- command definition ---
+  static command = { id: 'rtb', desc: 'Proceed daily real-time billionaires list' };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '15 0 * * *' // run at 0:15 AM on every day
+    }
+  ];
+}

package/dist/job/Stats.d.ts

@@ -0,0 +1,11 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TCronJob, TJobClsOptions } from '../types/job';
+export declare class StatsJob extends Job {
+  private static readonly filter;
+  private static readonly index;
+  private static readonly stats;
+  constructor(options?: TJobClsOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob;
+}

package/dist/job/Stats.js

@@ -0,0 +1,46 @@
+import { Job } from '../abstract/Job.js';
+import { StatsGroup } from '../lib/const.js';
+import { Filter } from '../model/Filter.js';
+import { Profile } from '../model/Profile.js';
+import { ProfileIndex } from '../model/ProfileIndex.js';
+import { Stats } from '../model/Stats.js';
+export class StatsJob extends Job {
+  static filter = Filter.getInstance();
+  static index = ProfileIndex.getInstance();
+  static stats = Stats.getInstance();
+  constructor(options = {}) {
+    super(options, 'stats');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const date = StatsJob.stats.getGlobalStats().date;
+      if (!date || !StatsJob.index.size) throw new Error('No data available');
+      this.log(`Generating stats for ${date} with ${StatsJob.index.size} profiles`);
+      const filter = {},
+        stats = {};
+      for (const item of StatsJob.index.values) {
+        const profile = Profile.getByItem(item);
+        if (!profile) continue;
+        const data = profile.getData();
+        Stats.aggregate(data, date, stats);
+        Filter.aggregate(data, filter);
+      }
+      this.log(`Saving stats for ${date}`);
+      StatsJob.filter.save(filter);
+      StatsJob.stats.setProfileStats(stats.profile);
+      StatsJob.stats.generateWealthStats(stats.scatter);
+      StatsGroup.forEach(g => StatsJob.stats.setGroupedStats(g, stats.groups[g]));
+      StatsJob.stats.setScatter(stats.scatter);
+      StatsJob.stats.generateDBStats();
+    });
+  }
+  // --- command definition ---
+  static command = { id: 'stats', desc: 'Generate stats and filtered lists' };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '30 0 * * *' // run at 0:30 AM on every day
+    }
+  ];
+}

package/dist/job/Top10.d.ts

@@ -0,0 +1,9 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TCronJob, TTop10JobOptions } from '../types/job';
+export declare class Top10Job extends Job<TTop10JobOptions> {
+  private static readonly stats;
+  constructor(options: TTop10JobOptions);
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+  static readonly cron: TCronJob<TTop10JobOptions>;
+}

package/dist/job/Top10.js

@@ -0,0 +1,48 @@
+import { Job } from '../abstract/Job.js';
+import { Utils } from '../core/Utils.js';
+import { List } from '../model/List.js';
+import { Stats } from '../model/Stats.js';
+import { Parser } from '../parser/Parser.js';
+export class Top10Job extends Job {
+  static stats = Stats.getInstance();
+  constructor(options) {
+    super(options, 'top10');
+  }
+  // --- job runner ---
+  async run() {
+    await this.protect(async () => {
+      const list = List.get('rtb');
+      if (!list) throw new Error('Real-time billionaires list not found');
+      const [year, month] = this.options.date ?? Utils.date('ym').split('-', 2);
+      const date = Parser.date(Utils.lastMonthDay(month, year), 'ymd');
+      const snapshot = list.getSnapshot(date, false);
+      if (!snapshot) throw new Error(`No snapshot found for ${month}/${year}`);
+      Top10Job.stats.generateTop10Entry(snapshot);
+    });
+  }
+  // --- command definition ---
+  static command = {
+    id: 'top10',
+    desc: 'Generate monthly top 10 ranking',
+    options: [
+      {
+        name: '-d, --date <YYYY-MM>',
+        desc: 'Specify the date for the top 10 ranking',
+        parser: v => {
+          if (!/^\d{4}-\d{2}$/.test(v)) throw new Error(`Invalid date format "${v}"; use YYYY-MM.`);
+          return v.split('-', 2).map(v => Number(v));
+        }
+      }
+    ]
+  };
+  // --- cron job definition ---
+  static cron = [
+    {
+      cronexpr: '35 0 1 * *', // run at 1:35 AM on the first day of every month
+      options: date => {
+        date.setMonth(date.getMonth() - 1);
+        return { date: [date.getFullYear(), date.getMonth() + 1] };
+      }
+    }
+  ];
+}

package/dist/job/Wiki.d.ts

@@ -0,0 +1,9 @@
+import { Job } from '../abstract/Job.js';
+import type { TCommandJob, TWikiJobOptions } from '../types/job';
+export declare class WikiJob extends Job<TWikiJobOptions> {
+  constructor(options: TWikiJobOptions);
+  private update;
+  private assign;
+  run(): Promise<void>;
+  static readonly command: TCommandJob;
+}