@notidotbot/noti-api-client 1.6.13 → 1.7.0

package/dist/classes/adminFishing.d.ts

@@ -0,0 +1,489 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * Dev-only backend for the Fishing minigame admin dashboard.
+ *
+ * Every method here requires a developer account — the routes check the caller against the developer
+ * list and return 403 otherwise, so these are not merely "admin" in the guild-owner sense.
+ *
+ * Endpoints live under `/admin/minigames/fishing/*`. The `minigames` segment is deliberate: Fishing is
+ * the first minigame, not the only one, so a second game slots in beside it rather than replacing it.
+ */
+export declare class APIAdminFishing {
+    private web;
+    constructor(web: WebDataManager);
+    /** Rollout state, active kill switches, pending flush backlog and Redis memory. */
+    getHealth({ auth }: AdminFishingFunctionsInput['getHealth']): Promise<import("../types").WebResponse<FishingHealth>>;
+    getRollout({ auth }: AdminFishingFunctionsInput['getRollout']): Promise<import("../types").WebResponse<FishingRollout>>;
+    /** Add or remove guilds from the beta allowlist. This is what starts a beta cohort. */
+    setRolloutAllowlist({ auth, action, guildIds }: AdminFishingFunctionsInput['setRolloutAllowlist']): Promise<import("../types").WebResponse<FishingRolloutChange>>;
+    /**
+     * Set the percentage dial.
+     *
+     * **0 is the fleet-wide kill switch** — the fastest way to stop fishing everywhere without a
+     * deploy. It stops ingestion only; the flush keeps draining so nobody's unflushed progress is lost.
+     */
+    setRolloutPercent({ auth, percent }: AdminFishingFunctionsInput['setRolloutPercent']): Promise<import("../types").WebResponse<FishingRollout>>;
+    getKills({ auth }: AdminFishingFunctionsInput['getKills']): Promise<import("../types").WebResponse<FishingKills>>;
+    /**
+     * Throw or clear a kill switch.
+     *
+     * `scope` is either a subsystem (`cast`, `sell`, `boss`, …) or a single target (`guild:<id>` /
+     * `user:<id>`). A kill stops INGESTION only — the flush keeps draining, so throwing a switch mid
+     * incident does not destroy a window of every active player's progress.
+     */
+    setKill({ auth, scope, on, reason }: AdminFishingFunctionsInput['setKill']): Promise<import("../types").WebResponse<FishingKillResult>>;
+    /** Every dial with its current value and its permitted bounds. */
+    getDials({ auth }: AdminFishingFunctionsInput['getDials']): Promise<import("../types").WebResponse<FishingDial[]>>;
+    /**
+     * Set a dial, or pass `value: null` to reset it to its seeded default.
+     *
+     * Out-of-range values are **rejected with a 400, not clamped** — an operator who typed 500 should
+     * learn it did not take rather than quietly getting 3.
+     */
+    setDial({ auth, dial, value, reason }: AdminFishingFunctionsInput['setDial']): Promise<import("../types").WebResponse<FishingDialResult>>;
+    /** The editable content tables, plus the currently effective content version. */
+    getContentTables({ auth }: AdminFishingFunctionsInput['getContentTables']): Promise<import("../types").WebResponse<FishingContentIndex>>;
+    listContent<T = Record<string, unknown>>({ auth, table, limit }: AdminFishingFunctionsInput['listContent']): Promise<import("../types").WebResponse<T[]>>;
+    /**
+     * Create or update one content row (upsert — one verb, not two).
+     *
+     * For `dateDerived` tables the change does **not** apply today: `effectiveFrom` in the response is
+     * the next 00:00 UTC. Daily demand, the shop rotation and the quest board are a date-seeded shuffle
+     * over the content list, so editing it mid-day would reshuffle a day players already acted on.
+     */
+    upsertContent<T = Record<string, unknown>>({ auth, table, id, data, reason }: AdminFishingFunctionsInput['upsertContent']): Promise<import("../types").WebResponse<FishingContentWrite<T>>>;
+    /**
+     * Disable a content row. **Nothing is hard-deleted** — player rows store content ids (claimed sets,
+     * caught species, owned items), so removing a row would orphan them.
+     */
+    disableContent<T = Record<string, unknown>>({ auth, table, id }: AdminFishingFunctionsInput['disableContent']): Promise<import("../types").WebResponse<FishingContentDisable<T>>>;
+    /** Global progression, plus per-guild wallet/inventory/ledger when `guildId` is supplied. */
+    getPlayer({ auth, userId, guildId }: AdminFishingFunctionsInput['getPlayer']): Promise<import("../types").WebResponse<FishingPlayerInspect>>;
+    getGuild({ auth, guildId }: AdminFishingFunctionsInput['getGuild']): Promise<import("../types").WebResponse<FishingGuildInspect>>;
+    /**
+     * Grant (positive delta) or revoke (negative delta) coins.
+     *
+     * A revoke **clamps at zero**. A negative balance silently blocks every future purchase with no
+     * explanation the player can act on, and support would have to undo it by hand.
+     */
+    adjustPlayerCoins({ auth, userId, guildId, delta, reason }: AdminFishingFunctionsInput['adjustPlayerCoins']): Promise<import("../types").WebResponse<FishingCoinAdjustment>>;
+    /**
+     * Reset a player's server stats, their global progression, a guild's dock, or a guild's economy.
+     *
+     * `claimedSets` and `claimedMilestones` are **preserved unless `alsoClearClaims` is set**. They
+     * record what a player was already *paid* for — clearing them makes every milestone and collection
+     * pay out a second time as the counters climb back, so "please reset me" becomes a faucet. Setting
+     * the flag is audited as its own action. A dock reset likewise preserves `prestige`.
+     */
+    resetTarget({ auth, scope, userId, guildId, alsoClearClaims, reason }: AdminFishingFunctionsInput['resetTarget']): Promise<import("../types").WebResponse<FishingResetResult>>;
+    /**
+     * Subtract what a range of flush batches awarded, clamped at zero.
+     *
+     * This is **not** an undo — deltas are not invertible once superseded (earn 500, buy a 500-coin
+     * rod, undo, and the balance goes negative while they keep the rod). It reads what those batches
+     * actually applied and reverses that much.
+     *
+     * **Dry-run unless `apply` is true.** Each subtraction is idempotent per player per range, so a
+     * retried apply cannot double-charge.
+     */
+    compensateBatches({ auth, fromBatchId, toBatchId, apply, reason }: AdminFishingFunctionsInput['compensateBatches']): Promise<import("../types").WebResponse<FishingCompensation>>;
+    /** Who ran what, with before → after. Distinct from the coin ledger, which is where coins came from. */
+    getAudit({ auth, limit }: AdminFishingFunctionsInput['getAudit']): Promise<import("../types").WebResponse<FishingAuditEntry[]>>;
+    /**
+     * Abuse review queue.
+     *
+     * A queue of things for a HUMAN to look at, never a list of confirmed cheats. Detection runs
+     * against an economy with no live data, so its false positives are disproportionately legitimate
+     * heavy players — the most engaged users in the feature. Nothing here bans, and there is
+     * deliberately no bulk action: confirmed abuse is actioned through `resetTarget`,
+     * `adjustPlayerCoins` or `setKill`, each of which writes an audit row.
+     *
+     * Defaults to PENDING flags, ordered most-severe-first.
+     */
+    getAbuseQueue({ auth, status, severity, kind, userId, guildId, limit, offset }: AdminFishingFunctionsInput['getAbuseQueue']): Promise<import("../types").WebResponse<FishingAbuseQueue>>;
+    /**
+     * Mark a flag reviewed, or reopen one.
+     *
+     * Pass `reviewed: false` to reopen — a reviewer who dismisses the wrong row otherwise has no way
+     * back, because the queue's day-grained dedupe key stops the same condition re-raising it.
+     *
+     * Reviewing is also what makes retention work: reviewed flags age out after 30 days, unreviewed
+     * ones after 90.
+     */
+    updateAbuseFlag({ auth, flagId, reviewed, reason }: AdminFishingFunctionsInput['updateAbuseFlag']): Promise<import("../types").WebResponse<FishingAbuseFlag>>;
+}
+export type AdminFishingFunctionsInput = {
+    'getHealth': {
+        auth: string;
+    };
+    'getRollout': {
+        auth: string;
+    };
+    'setRolloutAllowlist': {
+        auth: string;
+        action: 'add' | 'remove';
+        guildIds: string[];
+    };
+    'setRolloutPercent': {
+        auth: string;
+        percent: number;
+    };
+    'getKills': {
+        auth: string;
+    };
+    'setKill': {
+        auth: string;
+        scope: FishingKillScope | (string & {});
+        on: boolean;
+        reason?: string;
+    };
+    'getDials': {
+        auth: string;
+    };
+    'setDial': {
+        auth: string;
+        dial: FishingDialName;
+        value: number | null;
+        reason?: string;
+    };
+    'getContentTables': {
+        auth: string;
+    };
+    'listContent': {
+        auth: string;
+        table: FishingContentTable;
+        limit?: number;
+    };
+    'upsertContent': {
+        auth: string;
+        table: FishingContentTable;
+        id: string | number;
+        data: Record<string, unknown>;
+        reason?: string;
+    };
+    'disableContent': {
+        auth: string;
+        table: FishingContentTable;
+        id: string | number;
+    };
+    'getPlayer': {
+        auth: string;
+        userId: string;
+        guildId?: string;
+    };
+    'getGuild': {
+        auth: string;
+        guildId: string;
+    };
+    'adjustPlayerCoins': {
+        auth: string;
+        userId: string;
+        guildId: string;
+        delta: number;
+        reason?: string;
+    };
+    'resetTarget': {
+        auth: string;
+        scope: FishingResetScope;
+        userId?: string;
+        guildId?: string;
+        alsoClearClaims?: boolean;
+        reason?: string;
+    };
+    'compensateBatches': {
+        auth: string;
+        fromBatchId: string;
+        toBatchId: string;
+        apply?: boolean;
+        reason?: string;
+    };
+    'getAudit': {
+        auth: string;
+        limit?: number;
+    };
+    'getAbuseQueue': {
+        auth: string;
+        status?: FishingAbuseStatus;
+        severity?: FishingAbuseSeverity;
+        kind?: FishingAbuseKind;
+        userId?: string;
+        guildId?: string;
+        limit?: number;
+        offset?: number;
+    };
+    'updateAbuseFlag': {
+        auth: string;
+        flagId: string;
+        reviewed?: boolean;
+        reason?: string;
+    };
+};
+export type AdminFishingGetReturnTypes = {
+    'getHealthRaw': Awaited<ReturnType<APIAdminFishing['getHealth']>>;
+    'getHealthSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getHealth']>>>;
+    'getRolloutRaw': Awaited<ReturnType<APIAdminFishing['getRollout']>>;
+    'getRolloutSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getRollout']>>>;
+    'setRolloutAllowlistRaw': Awaited<ReturnType<APIAdminFishing['setRolloutAllowlist']>>;
+    'setRolloutAllowlistSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['setRolloutAllowlist']>>>;
+    'setRolloutPercentRaw': Awaited<ReturnType<APIAdminFishing['setRolloutPercent']>>;
+    'setRolloutPercentSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['setRolloutPercent']>>>;
+    'getKillsRaw': Awaited<ReturnType<APIAdminFishing['getKills']>>;
+    'getKillsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getKills']>>>;
+    'setKillRaw': Awaited<ReturnType<APIAdminFishing['setKill']>>;
+    'setKillSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['setKill']>>>;
+    'getDialsRaw': Awaited<ReturnType<APIAdminFishing['getDials']>>;
+    'getDialsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getDials']>>>;
+    'setDialRaw': Awaited<ReturnType<APIAdminFishing['setDial']>>;
+    'setDialSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['setDial']>>>;
+    'getContentTablesRaw': Awaited<ReturnType<APIAdminFishing['getContentTables']>>;
+    'getContentTablesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getContentTables']>>>;
+    'listContentRaw': Awaited<ReturnType<APIAdminFishing['listContent']>>;
+    'listContentSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['listContent']>>>;
+    'upsertContentRaw': Awaited<ReturnType<APIAdminFishing['upsertContent']>>;
+    'upsertContentSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['upsertContent']>>>;
+    'disableContentRaw': Awaited<ReturnType<APIAdminFishing['disableContent']>>;
+    'disableContentSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['disableContent']>>>;
+    'getPlayerRaw': Awaited<ReturnType<APIAdminFishing['getPlayer']>>;
+    'getPlayerSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getPlayer']>>>;
+    'getGuildRaw': Awaited<ReturnType<APIAdminFishing['getGuild']>>;
+    'getGuildSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getGuild']>>>;
+    'adjustPlayerCoinsRaw': Awaited<ReturnType<APIAdminFishing['adjustPlayerCoins']>>;
+    'adjustPlayerCoinsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['adjustPlayerCoins']>>>;
+    'resetTargetRaw': Awaited<ReturnType<APIAdminFishing['resetTarget']>>;
+    'resetTargetSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['resetTarget']>>>;
+    'compensateBatchesRaw': Awaited<ReturnType<APIAdminFishing['compensateBatches']>>;
+    'compensateBatchesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['compensateBatches']>>>;
+    'getAuditRaw': Awaited<ReturnType<APIAdminFishing['getAudit']>>;
+    'getAuditSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getAudit']>>>;
+    'getAbuseQueueRaw': Awaited<ReturnType<APIAdminFishing['getAbuseQueue']>>;
+    'getAbuseQueueSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['getAbuseQueue']>>>;
+    'updateAbuseFlagRaw': Awaited<ReturnType<APIAdminFishing['updateAbuseFlag']>>;
+    'updateAbuseFlagSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminFishing['updateAbuseFlag']>>>;
+};
+export type FishingRollout = {
+    allowlist: string[];
+    percent: number;
+};
+export type FishingRolloutChange = FishingRollout & {
+    changed: number;
+};
+/** Subsystems that can be switched off independently, alongside `guild:<id>` / `user:<id>` targets. */
+export type FishingKillScope = 'cast' | 'sell' | 'shop' | 'stock' | 'dock' | 'boss' | 'quests' | 'boosters';
+export type FishingKills = {
+    /** Scopes currently switched off. */
+    active: string[];
+    scopes: readonly FishingKillScope[];
+};
+export type FishingKillResult = {
+    scope: string;
+    on: boolean;
+};
+export type FishingDialName = 'catchRateMultiplier' | 'coinRateMultiplier' | 'xpRateMultiplier' | 'scrapRateMultiplier' | 'cooldownBaseMs' | 'cooldownFloorMs' | 'demandMultiplierMax' | 'demandSpeciesPerDay' | 'demandPremiumSaleCap' | 'rarityCeiling' | 'bossConcurrentCap' | 'bossEditThrottleMs' | 'flushIntervalMs';
+export type FishingDial = {
+    name: FishingDialName;
+    value: number;
+    min: number;
+    max: number;
+    default: number;
+};
+export type FishingDialResult = {
+    dial: FishingDialName;
+    value: number;
+    reset?: boolean;
+};
+export type FishingHealth = {
+    rollout: FishingRollout;
+    kills: string[];
+    /** Players with unflushed deltas waiting in Redis. */
+    pendingPlayers: number;
+    redis: {
+        usedMemoryBytes: number | null;
+        maxMemoryBytes: number | null;
+        /** `null` when CONFIG GET is disabled on the instance. */
+        policy: string | null;
+        dbSize: number | null;
+    };
+};
+export type FishingContentTable = 'species' | 'components' | 'dockTiers' | 'shop' | 'bosses' | 'quests' | 'milestones' | 'collections' | 'badges' | 'rarityTables';
+export type FishingContentTableInfo = {
+    name: FishingContentTable;
+    key: string;
+    /**
+     * True when the table feeds a date-seeded shuffle (demand, shop rotation, quest board). Edits to
+     * these take effect at the next 00:00 UTC rather than immediately.
+     */
+    dateDerived: boolean;
+};
+export type FishingContentIndex = {
+    tables: FishingContentTableInfo[];
+    contentVersion: string;
+};
+/** `effectiveFrom` is a `YYYY-MM-DD` date for date-derived tables, or `'immediately'`. */
+export type FishingContentWrite<T = Record<string, unknown>> = {
+    row: T;
+    effectiveFrom: string;
+};
+export type FishingContentDisable<T = Record<string, unknown>> = {
+    row: T;
+    disabled: true;
+    note: string;
+    effectiveFrom: string;
+};
+export type FishingPlayerGlobal = {
+    level: number;
+    xp: bigint;
+    voteStreak: number;
+    caughtSpecies: string[];
+    personalBests: unknown;
+    claimedSets: string[];
+    claimedMilestones: string[];
+    lifetimeCasts: number;
+    lifetimeCatches: number;
+    lifetimeLegendary: number;
+    lifetimeVotes: number;
+};
+export type FishingPlayerMember = {
+    coins: bigint;
+    lifetimeCoins: bigint;
+    lifetimeCatches: number;
+    biggestCatchG: number;
+    lastActiveAt: Date;
+};
+export type FishingInventoryStack = {
+    speciesId: string;
+    count: number;
+    totalValue: bigint;
+    bestWeightG: number;
+};
+export type FishingLedgerEntry = {
+    type: string;
+    currency: string;
+    delta: bigint;
+    reason: string | null;
+    createdAt: Date;
+};
+export type FishingPlayerInspect = {
+    global: FishingPlayerGlobal | null;
+    /** `null` unless a `guildId` was supplied. */
+    member: FishingPlayerMember | null;
+    inventory: FishingInventoryStack[] | null;
+    recentLedger: FishingLedgerEntry[];
+};
+export type FishingGuildConfig = {
+    enabled: boolean;
+    allowedChannelIds: string[];
+    cooldownOverrideMs: number | null;
+    dockChannelId: string | null;
+    logChannelId: string | null;
+};
+export type FishingGuildDock = {
+    tier: number;
+    prestige: number;
+    scrapContributed: bigint;
+    buildCompletesAt: Date | null;
+};
+export type FishingGuildInspect = {
+    config: FishingGuildConfig | null;
+    dock: FishingGuildDock | null;
+    components: {
+        componentId: string;
+        quantity: number;
+    }[];
+    topMembers: {
+        userId: string;
+        coins: bigint;
+        lifetimeCatches: number;
+        lastActiveAt: Date;
+    }[];
+};
+export type FishingCoinAdjustment = {
+    userId: string;
+    guildId: string;
+    balanceAfter: number;
+};
+export type FishingResetScope = 
+/** Per-guild wallet, inventory and seasonal stats for one member. */
+'serverStats'
+/** Global XP, level, codex, records and lifetime counters for one user. */
+ | 'globalProgression'
+/** One guild's dock tier, components and contributors. Preserves `prestige`. */
+ | 'guildDock'
+/** Every member's coins and inventory in one guild. */
+ | 'guildEconomy';
+export type FishingResetResult = {
+    scope: FishingResetScope;
+    cleared: string[];
+    claimsCleared: boolean;
+    note: string;
+};
+export type FishingCompensation = {
+    batches: number;
+    players: number;
+    totalCoins: number;
+    /** Capped at the first 100 players; `players` is the true count. */
+    perPlayer: {
+        userId: string;
+        guildId: string;
+        coins: number;
+    }[];
+    applied: boolean;
+    note: string;
+};
+export type FishingAuditEntry = {
+    actorId: string;
+    action: string;
+    target: string | null;
+    before: unknown;
+    after: unknown;
+    reason: string | null;
+    createdAt: Date;
+};
+/**
+ * What a heuristic detected.
+ *
+ * Hand-copied from `FlagKind` in the server's `modules/fishing/integrity.ts`. Nothing links the two,
+ * so adding a detector server-side leaves this quietly incomplete — diff both when either changes.
+ */
+export type FishingAbuseKind = 'burst' | 'earnRate' | 'impossibleState' | 'replay';
+export type FishingAbuseSeverity = 'low' | 'medium' | 'high';
+/**
+ * The response to a flag. Note what is absent: there is no `ban`, at any layer.
+ *
+ * Enforcement is SOFT and self-expiring — a throttled player waits longer, a silenced one sees an
+ * ordinary miss. Neither is ever told they were flagged, because a message saying so is a feedback
+ * signal that lets someone A/B test their way around the detection.
+ */
+export type FishingAbuseEnforcement = 'allow' | 'throttle' | 'silentNoop';
+/** Which slice of the queue to read. `pending` is the default — the archive is not the work. */
+export type FishingAbuseStatus = 'pending' | 'reviewed' | 'all';
+export type FishingAbuseFlag = {
+    dbId: string;
+    userId: string;
+    guildId: string | null;
+    kind: FishingAbuseKind;
+    severity: FishingAbuseSeverity;
+    /** Human-readable, for the reviewer. Never shown to the flagged player. */
+    detail: string;
+    /** The observed value and what was expected, so a reviewer can judge without re-querying. */
+    observed: number;
+    expected: number;
+    enforcement: FishingAbuseEnforcement;
+    /** How many times this same condition re-raised. One row per (player, kind, day). */
+    hits: number;
+    reviewedAt: string | null;
+    reviewedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type FishingAbuseQueue = {
+    /** Ordered most-severe-first, then most recently updated. */
+    flags: FishingAbuseFlag[];
+    /** Rows matching the current filters, for paging. */
+    matching: number;
+    /** Unreviewed rows overall — the badge count, independent of the filters applied. */
+    pending: number;
+    limit: number;
+    offset: number;
+    note: string;
+};