@notidotbot/noti-api-client 1.6.15 → 1.7.0

package/dist/classes/adminFishing.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIAdminFishing = void 0;
+// Data.
+/**
+ * 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.
+ */
+class APIAdminFishing {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    // ── Health & rollout ──────────────────────────────────────────────────────
+    /** Rollout state, active kill switches, pending flush backlog and Redis memory. */
+    async getHealth({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/health'),
+        });
+    }
+    async getRollout({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/rollout'),
+        });
+    }
+    /** Add or remove guilds from the beta allowlist. This is what starts a beta cohort. */
+    async setRolloutAllowlist({ auth, action, guildIds }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { action, guildIds },
+            endpoint: this.web.qp('/admin/minigames/fishing/rollout/allowlist'),
+        });
+    }
+    /**
+     * 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.
+     */
+    async setRolloutPercent({ auth, percent }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { percent },
+            endpoint: this.web.qp('/admin/minigames/fishing/rollout/percent'),
+        });
+    }
+    // ── Kill switches ─────────────────────────────────────────────────────────
+    async getKills({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/kills'),
+        });
+    }
+    /**
+     * 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.
+     */
+    async setKill({ auth, scope, on, reason }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { on, reason },
+            endpoint: this.web.qp('/admin/minigames/fishing/kills/' + scope),
+        });
+    }
+    // ── Economy dials ─────────────────────────────────────────────────────────
+    /** Every dial with its current value and its permitted bounds. */
+    async getDials({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/dials'),
+        });
+    }
+    /**
+     * 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.
+     */
+    async setDial({ auth, dial, value, reason }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { value, reason },
+            endpoint: this.web.qp('/admin/minigames/fishing/dials/' + dial),
+        });
+    }
+    // ── Content ───────────────────────────────────────────────────────────────
+    /** The editable content tables, plus the currently effective content version. */
+    async getContentTables({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/content'),
+        });
+    }
+    async listContent({ auth, table, limit }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/content/' + table, { limit }),
+        });
+    }
+    /**
+     * 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.
+     */
+    async upsertContent({ auth, table, id, data, reason }) {
+        return await this.web.request({
+            method: 'PUT', auth, body: { ...data, reason },
+            endpoint: this.web.qp(`/admin/minigames/fishing/content/${table}/${id}`),
+        });
+    }
+    /**
+     * 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.
+     */
+    async disableContent({ auth, table, id }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp(`/admin/minigames/fishing/content/${table}/${id}`),
+        });
+    }
+    // ── Player & guild operations ─────────────────────────────────────────────
+    /** Global progression, plus per-guild wallet/inventory/ledger when `guildId` is supplied. */
+    async getPlayer({ auth, userId, guildId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/players/' + userId, { guildId }),
+        });
+    }
+    async getGuild({ auth, guildId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/guilds/' + guildId),
+        });
+    }
+    /**
+     * 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.
+     */
+    async adjustPlayerCoins({ auth, userId, guildId, delta, reason }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { guildId, delta, reason },
+            endpoint: this.web.qp(`/admin/minigames/fishing/players/${userId}/coins`),
+        });
+    }
+    /**
+     * 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`.
+     */
+    async resetTarget({ auth, scope, userId, guildId, alsoClearClaims, reason }) {
+        return await this.web.request({
+            method: 'POST', auth, body: { scope, userId, guildId, alsoClearClaims, reason },
+            endpoint: this.web.qp('/admin/minigames/fishing/reset'),
+        });
+    }
+    /**
+     * 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.
+     */
+    async compensateBatches({ auth, fromBatchId, toBatchId, apply, reason }) {
+        return await this.web.request({
+            method: 'POST', auth, body: { fromBatchId, toBatchId, apply, reason },
+            endpoint: this.web.qp('/admin/minigames/fishing/compensate'),
+        });
+    }
+    // ── Audit & abuse ─────────────────────────────────────────────────────────
+    /** Who ran what, with before → after. Distinct from the coin ledger, which is where coins came from. */
+    async getAudit({ auth, limit }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/audit', { limit }),
+        });
+    }
+    /**
+     * 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.
+     */
+    async getAbuseQueue({ auth, status, severity, kind, userId, guildId, limit, offset }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/minigames/fishing/abuse', { status, severity, kind, userId, guildId, limit, offset }),
+        });
+    }
+    /**
+     * 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.
+     */
+    async updateAbuseFlag({ auth, flagId, reviewed, reason }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { reviewed, reason },
+            endpoint: this.web.qp('/admin/minigames/fishing/abuse/' + flagId),
+        });
+    }
+}
+exports.APIAdminFishing = APIAdminFishing;

package/dist/classes/guildFishing.d.ts

@@ -0,0 +1,188 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * Per-guild fishing customization (Premium) and the server-listing link.
+ *
+ * Every method here requires the caller to administer the guild AND the guild to hold the right
+ * entitlement — both enforced server-side, not merely hidden in the dashboard:
+ *
+ *   `FishingCustomization` (Premium)      — names, rarity table, catch message, shop items, listing
+ *   `FishingWebhooks`      (Premium Plus) — the webhook identity, matching every other webhook feature
+ *
+ * A Premium (non-Plus) guild gets a 403 from `setWebhook` despite passing every other check.
+ *
+ * **Customization never affects gameplay rates in a way that moves leaderboard standing.** Premium buys
+ * names, prices, messages and identity — the rarity table is the only thing touching the roll, and it
+ * is clamped to 0.5x–2x of the defaults, cannot reach `mythic`, and cannot zero a tier.
+ */
+export declare class APIGuildFishing {
+    private web;
+    constructor(web: WebDataManager);
+    /** The guild's full customization, including a member-facing summary of its rarity weighting. */
+    getCustomization({ auth, guildId }: GuildFishingFunctionsInput['getCustomization']): Promise<import("../types").WebResponse<GuildFishingCustomization>>;
+    /**
+     * Reweight the guild's rarity table, or pass `weights: null` to clear the override.
+     *
+     * **Rejects rather than clamps.** Out-of-band weights, `mythic`, and zeroing all return a 400 with
+     * per-field `issues` — an owner who typed 100 should learn it did not take, not quietly receive 2.
+     */
+    setRarityTable({ auth, guildId, weights }: GuildFishingFunctionsInput['setRarityTable']): Promise<import("../types").WebResponse<GuildFishingRarityTable>>;
+    /**
+     * Rename species and/or rarity tiers for this guild.
+     *
+     * Display only — the catalogue itself stays global, so the codex, collections and the public API
+     * remain coherent across every server. A rename changes what a server *calls* a fish, never which
+     * fish exist.
+     */
+    setNames({ auth, guildId, species, rarities }: GuildFishingFunctionsInput['setNames']): Promise<import("../types").WebResponse<GuildFishingNames>>;
+    /** Custom catch line, appended to the catch card. `null` or `''` clears it. */
+    setCatchMessage({ auth, guildId, message }: GuildFishingFunctionsInput['setCatchMessage']): Promise<import("../types").WebResponse<{
+        message?: string;
+        cleared?: boolean;
+    }>>;
+    /**
+     * Reskin and reprice a built-in shop item.
+     *
+     * NAME AND PRICE ONLY — the effect, item type and stock scope always come from the built-in item.
+     * There is deliberately no way to supply an effect, and the price is clamped to 0.5x–2x the
+     * default (a free item cannot be repriced at all).
+     */
+    setShopItem({ auth, guildId, baseItemId, name, priceCoins }: GuildFishingFunctionsInput['setShopItem']): Promise<import("../types").WebResponse<GuildFishingShopItem>>;
+    /** Hide a custom shop item. Disables rather than deletes — players may already own it. */
+    disableShopItem({ auth, guildId, baseItemId }: GuildFishingFunctionsInput['disableShopItem']): Promise<import("../types").WebResponse<{
+        baseItemId: string;
+        disabled: true;
+    }>>;
+    /**
+     * Link the guild's server listing and issue a webhook secret.
+     *
+     * **top.gg only.** No other listing site exposes a verifiable per-user server-vote webhook —
+     * discords.com lists bots only, and neither Discadia nor DISBOARD publishes a contract. Any other
+     * `site` returns a 400 saying so.
+     *
+     * The response carries the URL and secret to paste into the listing. Note the secret is held by the
+     * owner, so this is a perk an owner can self-award; it is contained because voters receive
+     * **per-server coins only** — never XP, items or global progression.
+     */
+    linkListing({ auth, guildId, site }: GuildFishingFunctionsInput['linkListing']): Promise<import("../types").WebResponse<GuildFishingListing>>;
+    unlinkListing({ auth, guildId }: GuildFishingFunctionsInput['unlinkListing']): Promise<import("../types").WebResponse<{
+        unlinked: true;
+    }>>;
+    /** Webhook identity for fishing messages. **Premium Plus only** — Premium alone gets a 403. */
+    setWebhook({ auth, guildId, enabled, username, avatarUrl }: GuildFishingFunctionsInput['setWebhook']): Promise<import("../types").WebResponse<GuildFishingWebhook>>;
+}
+export type GuildFishingFunctionsInput = {
+    'getCustomization': {
+        auth: string;
+        guildId: string;
+    };
+    'setRarityTable': {
+        auth: string;
+        guildId: string;
+        weights: Record<string, number> | null;
+    };
+    'setNames': {
+        auth: string;
+        guildId: string;
+        species?: Record<string, string> | null;
+        rarities?: Record<string, string> | null;
+    };
+    'setCatchMessage': {
+        auth: string;
+        guildId: string;
+        message: string | null;
+    };
+    'setShopItem': {
+        auth: string;
+        guildId: string;
+        baseItemId: string;
+        name?: string | null;
+        priceCoins?: number | null;
+    };
+    'disableShopItem': {
+        auth: string;
+        guildId: string;
+        baseItemId: string;
+    };
+    'linkListing': {
+        auth: string;
+        guildId: string;
+        site?: 'topgg';
+    };
+    'unlinkListing': {
+        auth: string;
+        guildId: string;
+    };
+    'setWebhook': {
+        auth: string;
+        guildId: string;
+        enabled?: boolean;
+        username?: string;
+        avatarUrl?: string;
+    };
+};
+export type GuildFishingGetReturnTypes = {
+    'getCustomizationRaw': Awaited<ReturnType<APIGuildFishing['getCustomization']>>;
+    'getCustomizationSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['getCustomization']>>>;
+    'setRarityTableRaw': Awaited<ReturnType<APIGuildFishing['setRarityTable']>>;
+    'setRarityTableSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['setRarityTable']>>>;
+    'setNamesRaw': Awaited<ReturnType<APIGuildFishing['setNames']>>;
+    'setNamesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['setNames']>>>;
+    'setCatchMessageRaw': Awaited<ReturnType<APIGuildFishing['setCatchMessage']>>;
+    'setCatchMessageSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['setCatchMessage']>>>;
+    'setShopItemRaw': Awaited<ReturnType<APIGuildFishing['setShopItem']>>;
+    'setShopItemSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['setShopItem']>>>;
+    'disableShopItemRaw': Awaited<ReturnType<APIGuildFishing['disableShopItem']>>;
+    'disableShopItemSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['disableShopItem']>>>;
+    'linkListingRaw': Awaited<ReturnType<APIGuildFishing['linkListing']>>;
+    'linkListingSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['linkListing']>>>;
+    'unlinkListingRaw': Awaited<ReturnType<APIGuildFishing['unlinkListing']>>;
+    'unlinkListingSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['unlinkListing']>>>;
+    'setWebhookRaw': Awaited<ReturnType<APIGuildFishing['setWebhook']>>;
+    'setWebhookSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildFishing['setWebhook']>>>;
+};
+/** A rarity weighting expressed as a multiplier against the default — "2x rare" reads, "0.0412" does not. */
+export type GuildFishingWeighting = {
+    rarity: string;
+    multiplier: number;
+};
+export type GuildFishingShopItem = {
+    baseItemId: string;
+    name: string | null;
+    priceCoins: number | null;
+    enabled?: boolean;
+};
+export type GuildFishingCustomization = {
+    customRarityTable: Record<string, number> | null;
+    customSpeciesNames: Record<string, string> | null;
+    customRarityNames: Record<string, string> | null;
+    customCatchMessage: string | null;
+    webhookEnabled: boolean;
+    webhookUsername: string | null;
+    webhookAvatarUrl: string | null;
+    shopItems: GuildFishingShopItem[];
+    /** Shown to members — reweighting changes the game people are playing, so it is not invisible. */
+    weighting: GuildFishingWeighting[];
+};
+export type GuildFishingRarityTable = {
+    weights?: Record<string, number>;
+    weighting?: GuildFishingWeighting[];
+    cleared?: boolean;
+};
+export type GuildFishingNames = {
+    customSpeciesNames?: Record<string, string> | null;
+    customRarityNames?: Record<string, string> | null;
+};
+export type GuildFishingListing = {
+    site: 'topgg';
+    /** Paste into the listing's webhook settings alongside `webhookUrl`. */
+    secret: string;
+    webhookUrl: string;
+    instructions: string;
+    note: string;
+};
+export type GuildFishingWebhook = {
+    webhookEnabled?: boolean;
+    webhookUsername?: string | null;
+    webhookAvatarUrl?: string | null;
+};

package/dist/classes/guildFishing.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIGuildFishing = void 0;
+// Data.
+/**
+ * Per-guild fishing customization (Premium) and the server-listing link.
+ *
+ * Every method here requires the caller to administer the guild AND the guild to hold the right
+ * entitlement — both enforced server-side, not merely hidden in the dashboard:
+ *
+ *   `FishingCustomization` (Premium)      — names, rarity table, catch message, shop items, listing
+ *   `FishingWebhooks`      (Premium Plus) — the webhook identity, matching every other webhook feature
+ *
+ * A Premium (non-Plus) guild gets a 403 from `setWebhook` despite passing every other check.
+ *
+ * **Customization never affects gameplay rates in a way that moves leaderboard standing.** Premium buys
+ * names, prices, messages and identity — the rarity table is the only thing touching the roll, and it
+ * is clamped to 0.5x–2x of the defaults, cannot reach `mythic`, and cannot zero a tier.
+ */
+class APIGuildFishing {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** The guild's full customization, including a member-facing summary of its rarity weighting. */
+    async getCustomization({ auth, guildId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp(`/data/fishing/${guildId}/customization`),
+        });
+    }
+    /**
+     * Reweight the guild's rarity table, or pass `weights: null` to clear the override.
+     *
+     * **Rejects rather than clamps.** Out-of-band weights, `mythic`, and zeroing all return a 400 with
+     * per-field `issues` — an owner who typed 100 should learn it did not take, not quietly receive 2.
+     */
+    async setRarityTable({ auth, guildId, weights }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { weights },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/rarity-table`),
+        });
+    }
+    /**
+     * Rename species and/or rarity tiers for this guild.
+     *
+     * Display only — the catalogue itself stays global, so the codex, collections and the public API
+     * remain coherent across every server. A rename changes what a server *calls* a fish, never which
+     * fish exist.
+     */
+    async setNames({ auth, guildId, species, rarities }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { species, rarities },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/names`),
+        });
+    }
+    /** Custom catch line, appended to the catch card. `null` or `''` clears it. */
+    async setCatchMessage({ auth, guildId, message }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { message },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/catch-message`),
+        });
+    }
+    /**
+     * Reskin and reprice a built-in shop item.
+     *
+     * NAME AND PRICE ONLY — the effect, item type and stock scope always come from the built-in item.
+     * There is deliberately no way to supply an effect, and the price is clamped to 0.5x–2x the
+     * default (a free item cannot be repriced at all).
+     */
+    async setShopItem({ auth, guildId, baseItemId, name, priceCoins }) {
+        return await this.web.request({
+            method: 'PUT', auth, body: { name, priceCoins },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/shop-items/${baseItemId}`),
+        });
+    }
+    /** Hide a custom shop item. Disables rather than deletes — players may already own it. */
+    async disableShopItem({ auth, guildId, baseItemId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp(`/data/fishing/${guildId}/shop-items/${baseItemId}`),
+        });
+    }
+    /**
+     * Link the guild's server listing and issue a webhook secret.
+     *
+     * **top.gg only.** No other listing site exposes a verifiable per-user server-vote webhook —
+     * discords.com lists bots only, and neither Discadia nor DISBOARD publishes a contract. Any other
+     * `site` returns a 400 saying so.
+     *
+     * The response carries the URL and secret to paste into the listing. Note the secret is held by the
+     * owner, so this is a perk an owner can self-award; it is contained because voters receive
+     * **per-server coins only** — never XP, items or global progression.
+     */
+    async linkListing({ auth, guildId, site }) {
+        return await this.web.request({
+            method: 'PUT', auth, body: { site: site ?? 'topgg' },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/listing`),
+        });
+    }
+    async unlinkListing({ auth, guildId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp(`/data/fishing/${guildId}/listing`),
+        });
+    }
+    /** Webhook identity for fishing messages. **Premium Plus only** — Premium alone gets a 403. */
+    async setWebhook({ auth, guildId, enabled, username, avatarUrl }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body: { enabled, username, avatarUrl },
+            endpoint: this.web.qp(`/data/fishing/${guildId}/webhook`),
+        });
+    }
+}
+exports.APIGuildFishing = APIGuildFishing;