@notidotbot/noti-api-client 1.9.61 → 1.9.63

package/dist/classes/guildBadges.d.ts

@@ -1,5 +1,6 @@
 import { WebDataManager } from '../core/manager';
 import { CancelOutWebResponses, WebResponse } from '../types';
+import type { MissingSendData } from './guildDrops';
 /**
  * Badge Notifications - a server is pinged, once per badge, when a Kick or Twitch drops campaign offers
  * a chat badge. Separate from Drops: every badge on an enabled platform, with an optional game filter,
@@ -49,6 +50,16 @@ export declare class APIGuildBadges {
      * shape the API's catch-all guild routes cannot claim.
      */
     sendTestBadgeNotification({ auth, guildId, platform, gameId }: GuildBadgesFunctionsInput['sendTestBadgeNotification']): Promise<WebResponse<string>>;
+    /**
+     * "Force Missing Badges": sends, now, every badge still live that this server is set up for and has not
+     * been sent, rather than at the next 5-minute check. Never re-sends one already sent.
+     *
+     * 400 when badges are not set up or the platform is switched off; 403 for the launch flag; 429 within
+     * 5 minutes of the last press for this server and platform (`error.code === 'rate_limited'`, count down
+     * from `error.retryAfterSeconds`); 503 in the first minutes after the bot starts, before its first badge
+     * check (that press does not start the cooldown). `data.message` is ready to show.
+     */
+    sendMissingBadges({ auth, guildId, platform }: GuildBadgesFunctionsInput['sendMissingBadges']): Promise<WebResponse<MissingSendData>>;
     /**
      * The badge game picker's list: every game of the platform, ONE ROW PER GAME - duplicate entries for one
      * game are merged, every id in `ids`. Any game can offer a badge later, so it is not limited to games that
@@ -188,6 +199,11 @@ export type GuildBadgesFunctionsInput = {
         offset?: number;
         configuredGameIds?: string[];
     };
+    'sendMissingBadges': {
+        auth: string;
+        guildId: string;
+        platform: 'kick' | 'twitch';
+    };
 };
 export type GuildBadgesReturnTypes = {
     'getGuildBadgesRaw': Awaited<ReturnType<APIGuildBadges['getGuildBadges']>>;
@@ -198,4 +214,6 @@ export type GuildBadgesReturnTypes = {
     'sendTestBadgeNotificationSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildBadges['sendTestBadgeNotification']>>>;
     'getBadgeGamesRaw': Awaited<ReturnType<APIGuildBadges['getBadgeGames']>>;
     'getBadgeGamesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildBadges['getBadgeGames']>>>;
+    'sendMissingBadgesRaw': Awaited<ReturnType<APIGuildBadges['sendMissingBadges']>>;
+    'sendMissingBadgesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildBadges['sendMissingBadges']>>>;
 };

package/dist/classes/guildBadges.js

@@ -69,6 +69,22 @@ class APIGuildBadges {
             body: { platform, gameId },
         });
     }
+    /**
+     * "Force Missing Badges": sends, now, every badge still live that this server is set up for and has not
+     * been sent, rather than at the next 5-minute check. Never re-sends one already sent.
+     *
+     * 400 when badges are not set up or the platform is switched off; 403 for the launch flag; 429 within
+     * 5 minutes of the last press for this server and platform (`error.code === 'rate_limited'`, count down
+     * from `error.retryAfterSeconds`); 503 in the first minutes after the bot starts, before its first badge
+     * check (that press does not start the cooldown). `data.message` is ready to show.
+     */
+    async sendMissingBadges({ auth, guildId, platform }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/missing-badges`),
+            body: { platform },
+        });
+    }
     /**
      * The badge game picker's list: every game of the platform, ONE ROW PER GAME - duplicate entries for one
      * game are merged, every id in `ids`. Any game can offer a badge later, so it is not limited to games that

package/dist/classes/guildDrops.d.ts

@@ -19,7 +19,29 @@ export declare class APIGuildDrops {
      * with "Invalid platform.". One segment is the only shape they cannot claim.
      */
     sendTestDropNotification({ auth, guildId, platform, variant, dontPing }: GuildDropsFunctionsInput['sendTestDropNotification']): Promise<WebResponse<string>>;
+    /**
+     * "Force Missing Drops": sends, now, every drop still running that this server should have and has not
+     * been sent - for a server that enabled mid-campaign and does not want to wait for the next 5-minute
+     * check, or one that thinks a drop was missed. Never re-sends one already sent. Ignores the server's
+     * delivery window ("force" means now).
+     *
+     * 400 when drops are not set up or the platform is switched off; 429 within 5 minutes of the last press
+     * for this server and platform (`error.code === 'rate_limited'`, count down from `error.retryAfterSeconds`);
+     * 503 while the bot is starting. `data.sent` is how many drops were handed to the server; `data.message`
+     * is ready to show.
+     *
+     * One segment (`/missing-drops`) for the reason in `sendTestDropNotification`.
+     */
+    sendMissingDrops({ auth, guildId, platform }: GuildDropsFunctionsInput['sendMissingDrops']): Promise<WebResponse<MissingSendData>>;
 }
+/** What a "send missing drops / badges" press did. */
+export type MissingSendData = {
+    platform: 'kick' | 'twitch';
+    /** How many were handed to the server to post. 0 = nothing was missing. */
+    sent: number;
+    /** Ready to show: "Sending 3 missing Twitch drops now." or "Nothing missing - ...". */
+    message: string;
+};
 /** Which drops feed to sample: an ordinary campaign, or the exclusive/go-live variant. */
 export type DropTestVariant = 'campaign' | 'live';
 export type GuildDropsFunctionsInput = {
@@ -27,6 +49,11 @@ export type GuildDropsFunctionsInput = {
         auth: string;
         guildId: string;
     };
+    'sendMissingDrops': {
+        auth: string;
+        guildId: string;
+        platform: 'kick' | 'twitch';
+    };
     'sendTestDropNotification': {
         auth: string;
         guildId: string;
@@ -102,6 +129,8 @@ export type GuildDropsReturnTypes = {
     'updateGuildDropsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildDrops['updateGuildDrops']>>>;
     'sendTestDropNotificationRaw': Awaited<ReturnType<APIGuildDrops['sendTestDropNotification']>>;
     'sendTestDropNotificationSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildDrops['sendTestDropNotification']>>>;
+    'sendMissingDropsRaw': Awaited<ReturnType<APIGuildDrops['sendMissingDrops']>>;
+    'sendMissingDropsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildDrops['sendMissingDrops']>>>;
 };
 export type WebhookConfig = {
     avatarUrl: string | null;

package/dist/classes/guildDrops.js

@@ -70,5 +70,25 @@ class APIGuildDrops {
             body: { platform, variant },
         });
     }
+    /**
+     * "Force Missing Drops": sends, now, every drop still running that this server should have and has not
+     * been sent - for a server that enabled mid-campaign and does not want to wait for the next 5-minute
+     * check, or one that thinks a drop was missed. Never re-sends one already sent. Ignores the server's
+     * delivery window ("force" means now).
+     *
+     * 400 when drops are not set up or the platform is switched off; 429 within 5 minutes of the last press
+     * for this server and platform (`error.code === 'rate_limited'`, count down from `error.retryAfterSeconds`);
+     * 503 while the bot is starting. `data.sent` is how many drops were handed to the server; `data.message`
+     * is ready to show.
+     *
+     * One segment (`/missing-drops`) for the reason in `sendTestDropNotification`.
+     */
+    async sendMissingDrops({ auth, guildId, platform }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/missing-drops`),
+            body: { platform },
+        });
+    }
 }
 exports.APIGuildDrops = APIGuildDrops;

package/dist/classes/guildGiveaway.d.ts

@@ -18,6 +18,10 @@ export declare class APIGuildGiveaway {
     resendGiveawayMessage({ auth, guildId, giveawayId }: GuildGiveawayFunctionsInput['resendGiveawayMessage']): Promise<import("../types").WebResponse<string>>;
     startScheduledGiveaway({ auth, guildId, giveawayId }: GuildGiveawayFunctionsInput['startScheduledGiveaway']): Promise<import("../types").WebResponse<string>>;
     endGiveaway({ auth, guildId, giveawayId }: GuildGiveawayFunctionsInput['endGiveaway']): Promise<import("../types").WebResponse<string>>;
+    /** The server's public giveaways switches. 403 while the `publicGiveaways` flag is hidden for the caller. */
+    getPublicGiveawaySettings({ auth, guildId }: GuildGiveawayFunctionsInput['getPublicGiveawaySettings']): Promise<import("../types").WebResponse<PublicGiveawaySettings>>;
+    /** Change either switch, field by field (booleans only). Answers with both. */
+    updatePublicGiveawaySettings({ auth, guildId, ...body }: GuildGiveawayFunctionsInput['updatePublicGiveawaySettings']): Promise<import("../types").WebResponse<PublicGiveawaySettings>>;
     rerollGiveaway({ auth, guildId, giveawayId }: GuildGiveawayFunctionsInput['rerollGiveaway']): Promise<import("../types").WebResponse<string>>;
     deleteGiveaway({ auth, guildId, giveawayId, type }: GuildGiveawayFunctionsInput['deleteGiveaway']): Promise<import("../types").WebResponse<string>>;
 }
@@ -53,8 +57,16 @@ export type GuildGiveawayFunctionsInput<T extends WhenCreate = never> = {
         auth: string;
         guildId: string;
         giveawayId: string;
-        body: Pick<DeepPartial<GuildGiveawayZod>, 'winnerCount' | 'durationMinutes' | 'name'>;
+        body: Pick<DeepPartial<GuildGiveawayZod>, 'winnerCount' | 'durationMinutes' | 'name' | 'publicListing'>;
     };
+    'getPublicGiveawaySettings': {
+        auth: string;
+        guildId: string;
+    };
+    'updatePublicGiveawaySettings': {
+        auth: string;
+        guildId: string;
+    } & Partial<PublicGiveawaySettings>;
     'resendGiveawayMessage': {
         auth: string;
         guildId: string;
@@ -96,9 +108,18 @@ export type GuildGiveawayReturnTypes = {
     'deleteGiveawaySuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildGiveaway['deleteGiveaway']>>>;
     'endGiveawayRaw': Awaited<ReturnType<APIGuildGiveaway['endGiveaway']>>;
     'endGiveawaySuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildGiveaway['endGiveaway']>>>;
+    'getPublicGiveawaySettingsRaw': Awaited<ReturnType<APIGuildGiveaway['getPublicGiveawaySettings']>>;
+    'getPublicGiveawaySettingsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildGiveaway['getPublicGiveawaySettings']>>>;
+    'updatePublicGiveawaySettingsRaw': Awaited<ReturnType<APIGuildGiveaway['updatePublicGiveawaySettings']>>;
+    'updatePublicGiveawaySettingsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildGiveaway['updatePublicGiveawaySettings']>>>;
     'rerollGiveawayRaw': Awaited<ReturnType<APIGuildGiveaway['rerollGiveaway']>>;
     'rerollGiveawaySuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildGiveaway['rerollGiveaway']>>>;
 };
+/** `publicGiveaways`: list this server's giveaways on noti.bot (default on). `giveawayJoinLinks`: let people join from there (default off). */
+export type PublicGiveawaySettings = {
+    publicGiveaways: boolean;
+    giveawayJoinLinks: boolean;
+};
 export type WhenCreate = 'now' | 'later';
 export type StateType = 'live' | 'scheduled';
 export type GuildGiveawaysType = {
@@ -124,6 +145,12 @@ export type GuildGiveawaysType = {
         canBonusEntries: boolean;
         canRequirements: boolean;
         canModifyWhileRunning: boolean;
+        /** Claim to win (Premium Plus). Gate the claim window control on this. */
+        canClaim: boolean;
+        /** Winner role (Premium). Gate the winner role and its removal days on this. */
+        canWinnerRole: boolean;
+        /** The claim windows the server accepts, in minutes. Same list as `GIVEAWAY_CLAIM_WINDOWS`. */
+        claimWindowChoices: number[];
     };
     /** Which tier those caps came from, so the UI can name the plan in a limit message. */
     premium: {

package/dist/classes/guildGiveaway.js

@@ -58,6 +58,20 @@ class APIGuildGiveaway {
             endpoint: this.web.qp('/data/giveaways/' + guildId + '/' + giveawayId + '/end'),
         });
     }
+    /** The server's public giveaways switches. 403 while the `publicGiveaways` flag is hidden for the caller. */
+    async getPublicGiveawaySettings({ auth, guildId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/data/guild/' + guildId + '/public-giveaways'),
+        });
+    }
+    /** Change either switch, field by field (booleans only). Answers with both. */
+    async updatePublicGiveawaySettings({ auth, guildId, ...body }) {
+        return await this.web.request({
+            method: 'PATCH', auth, body,
+            endpoint: this.web.qp('/data/guild/' + guildId + '/public-giveaways'),
+        });
+    }
     async rerollGiveaway({ auth, guildId, giveawayId }) {
         return await this.web.request({
             method: 'POST', auth,

package/dist/classes/publicDrops.d.ts

@@ -0,0 +1,147 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * The PUBLIC drops and badges pages - current and upcoming Kick and Twitch drops campaigns, and the chat
+ * badges they reward.
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPublicDrops` / `listPublicBadges` need no session: the first 12. The `*All*` methods page the rest for
+ * any logged-in user (no server permission), so pass `auth`.
+ *
+ * ── SOURCES ────────────────────────────────────────────────────────────────
+ * Every response carries `sources`: whether the Kick or Twitch drops source is failing right now. An empty list
+ * with a failing source means "unavailable", not "no drops" - show it that way.
+ *
+ * Behind the `publicDrops` launch flag: while it is hidden for the caller the lists are EMPTY (not 403).
+ * Built from the bot's last successful sync (every 5 minutes), so a new campaign can take that long to appear.
+ */
+export declare class APIPublicDrops {
+    private web;
+    constructor(web: WebDataManager);
+    /** The first 12 drops campaigns, live (ending soonest) then upcoming. No session. */
+    listPublicDrops({ platform }?: PublicDropsFunctionsInput['listPublicDrops']): Promise<import("../types").WebResponse<PublicDropList>>;
+    /** Every drops campaign, 24 per page. Pass the previous page's `nextCursor`; null = last page. */
+    listAllPublicDrops({ auth, platform, cursor }: PublicDropsFunctionsInput['listAllPublicDrops']): Promise<import("../types").WebResponse<PublicDropPage>>;
+    /** The first 12 chat badges from drops, live then upcoming. No session. */
+    listPublicBadges({ platform }?: PublicDropsFunctionsInput['listPublicBadges']): Promise<import("../types").WebResponse<PublicBadgeList>>;
+    /** Every chat badge, 24 per page. */
+    listAllPublicBadges({ auth, platform, cursor }: PublicDropsFunctionsInput['listAllPublicBadges']): Promise<import("../types").WebResponse<PublicBadgePage>>;
+}
+/** `all` (or omitted) = both platforms. */
+export type PublicDropsPlatformFilter = 'kick' | 'twitch' | 'all';
+export type PublicDropsFunctionsInput = {
+    'listPublicDrops': {
+        platform?: PublicDropsPlatformFilter;
+    };
+    'listAllPublicDrops': {
+        auth: string;
+        platform?: PublicDropsPlatformFilter;
+        cursor?: string | null;
+    };
+    'listPublicBadges': {
+        platform?: PublicDropsPlatformFilter;
+    };
+    'listAllPublicBadges': {
+        auth: string;
+        platform?: PublicDropsPlatformFilter;
+        cursor?: string | null;
+    };
+};
+export type PublicDropsGetReturnTypes = {
+    'listPublicDropsRaw': Awaited<ReturnType<APIPublicDrops['listPublicDrops']>>;
+    'listPublicDropsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicDrops['listPublicDrops']>>>;
+    'listAllPublicDropsRaw': Awaited<ReturnType<APIPublicDrops['listAllPublicDrops']>>;
+    'listAllPublicDropsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicDrops['listAllPublicDrops']>>>;
+    'listPublicBadgesRaw': Awaited<ReturnType<APIPublicDrops['listPublicBadges']>>;
+    'listPublicBadgesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicDrops['listPublicBadges']>>>;
+    'listAllPublicBadgesRaw': Awaited<ReturnType<APIPublicDrops['listAllPublicBadges']>>;
+    'listAllPublicBadgesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicDrops['listAllPublicBadges']>>>;
+};
+/** Is each drops source failing right now. `since` is ISO, set while failing. */
+export type PublicDropsSources = {
+    kick: {
+        ok: boolean;
+        since: string | null;
+    };
+    twitch: {
+        ok: boolean;
+        since: string | null;
+    };
+};
+export type PublicDropReward = {
+    name: string;
+    imageUrl: string | null;
+    requiredMinutes: number | null;
+    /** Subscriptions the reward needs (Twitch only); null when none. */
+    requiredSubs: number | null;
+    isBadge: boolean;
+};
+/** One campaign. Mirrors `PublicDropCard` in Noti-v3's `src/modules/publicDrops.ts`. */
+export type PublicDropCard = {
+    /** `<platform>:<campaignId>`. */
+    id: string;
+    platform: 'kick' | 'twitch';
+    name: string;
+    game: {
+        name: string;
+        imageUrl: string | null;
+    };
+    /** Kick only. */
+    organization: string | null;
+    /** ISO. */
+    startsAt: string;
+    /** ISO. */
+    endsAt: string;
+    status: 'live' | 'upcoming';
+    /** Where to watch: the Kick category page, or the Twitch campaign page. */
+    url: string | null;
+    rewards: PublicDropReward[];
+    /** Kick drops earned only by watching these streamers; null for everyone else. */
+    exclusive: {
+        streamers: {
+            username: string;
+            url: string;
+        }[];
+    } | null;
+};
+/** One chat badge. Mirrors `PublicBadgeCard` in Noti-v3. */
+export type PublicBadgeCard = {
+    /** `<platform>:<rewardId>`. */
+    key: string;
+    platform: 'kick' | 'twitch';
+    name: string;
+    imageUrl: string | null;
+    game: string;
+    campaign: string;
+    /** ISO. */
+    startsAt: string;
+    /** ISO. */
+    endsAt: string;
+    /** Claimable right now. */
+    active: boolean;
+    url: string | null;
+    requiredMinutes: number | null;
+    requiredSubs: number | null;
+};
+export type PublicDropList = {
+    drops: PublicDropCard[];
+    total: number;
+    sources: PublicDropsSources;
+};
+export type PublicDropPage = {
+    drops: PublicDropCard[];
+    nextCursor: string | null;
+    total: number;
+    sources: PublicDropsSources;
+};
+export type PublicBadgeList = {
+    badges: PublicBadgeCard[];
+    total: number;
+    sources: PublicDropsSources;
+};
+export type PublicBadgePage = {
+    badges: PublicBadgeCard[];
+    nextCursor: string | null;
+    total: number;
+    sources: PublicDropsSources;
+};

package/dist/classes/publicDrops.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIPublicDrops = void 0;
+// Data.
+/**
+ * The PUBLIC drops and badges pages - current and upcoming Kick and Twitch drops campaigns, and the chat
+ * badges they reward.
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPublicDrops` / `listPublicBadges` need no session: the first 12. The `*All*` methods page the rest for
+ * any logged-in user (no server permission), so pass `auth`.
+ *
+ * ── SOURCES ────────────────────────────────────────────────────────────────
+ * Every response carries `sources`: whether the Kick or Twitch drops source is failing right now. An empty list
+ * with a failing source means "unavailable", not "no drops" - show it that way.
+ *
+ * Behind the `publicDrops` launch flag: while it is hidden for the caller the lists are EMPTY (not 403).
+ * Built from the bot's last successful sync (every 5 minutes), so a new campaign can take that long to appear.
+ */
+class APIPublicDrops {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** The first 12 drops campaigns, live (ending soonest) then upcoming. No session. */
+    async listPublicDrops({ platform } = {}) {
+        return await this.web.request({
+            method: 'GET',
+            endpoint: this.web.qp('/public/drops', platform ? { platform } : {}),
+        });
+    }
+    /** Every drops campaign, 24 per page. Pass the previous page's `nextCursor`; null = last page. */
+    async listAllPublicDrops({ auth, platform, cursor }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/drops/all', { ...(platform ? { platform } : {}), ...(cursor ? { cursor } : {}) }),
+        });
+    }
+    /** The first 12 chat badges from drops, live then upcoming. No session. */
+    async listPublicBadges({ platform } = {}) {
+        return await this.web.request({
+            method: 'GET',
+            endpoint: this.web.qp('/public/badges', platform ? { platform } : {}),
+        });
+    }
+    /** Every chat badge, 24 per page. */
+    async listAllPublicBadges({ auth, platform, cursor }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/badges/all', { ...(platform ? { platform } : {}), ...(cursor ? { cursor } : {}) }),
+        });
+    }
+}
+exports.APIPublicDrops = APIPublicDrops;

package/dist/classes/publicGiveaways.d.ts

@@ -0,0 +1,152 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * The PUBLIC giveaways page - running giveaways from every server that lists them on noti.bot.
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPublicGiveaways` needs no session: the latest 10. Everything else needs a logged-in user (any
+ * Discord account - no server permission), so pass `auth`.
+ *
+ * ── LISTED BY DEFAULT ──────────────────────────────────────────────────────
+ * A server's giveaways are listed unless it switched them off (`guildGiveaway.updatePublicGiveawaySettings`),
+ * and each giveaway can override that (`publicListing`). Behind the `publicGiveaways` launch flag: while it
+ * is hidden for the caller the lists are EMPTY (not 403) and single lookups 404.
+ *
+ * ── WHAT A CARD NEVER CARRIES ──────────────────────────────────────────────
+ * No host, winners, entrants or internal ids. Roles are names, dates are ISO strings, and a role deleted
+ * since the giveaway was made reads "deleted role" rather than disappearing.
+ *
+ * The lists are cached on the server for up to a minute, so an entry count can trail by that much.
+ */
+export declare class APIPublicGiveaways {
+    private web;
+    constructor(web: WebDataManager);
+    /** The latest 10 listed giveaways and how many are listed in all. No session. */
+    listPublicGiveaways(): Promise<import("../types").WebResponse<PublicGiveawayList>>;
+    /** Every listed giveaway, 24 per page, newest first. Pass the previous page's `nextCursor`; null = last page. */
+    listAllPublicGiveaways({ auth, cursor }: PublicGiveawaysFunctionsInput['listAllPublicGiveaways']): Promise<import("../types").WebResponse<PublicGiveawayPage>>;
+    /** One listed giveaway, plus where the logged-in user stands on it. 404 when it is not listed (or ended). */
+    getPublicGiveaway({ auth, giveawayId }: PublicGiveawaysFunctionsInput['getPublicGiveaway']): Promise<import("../types").WebResponse<PublicGiveawayWithViewer>>;
+    /**
+     * Enter a listed giveaway as the logged-in user - the same rules as the Discord button. A refusal is
+     * `{ status: 400 | 404 | 429, error: { code } }` with `code` from `PUBLIC_ENTRY_REFUSALS`; word it on the
+     * page (the card's `requirements` say what is required). 10 attempts per user per minute.
+     */
+    createPublicGiveawayEntry({ auth, giveawayId }: PublicGiveawaysFunctionsInput['createPublicGiveawayEntry']): Promise<import("../types").WebResponse<PublicGiveawayEntryResult>>;
+    /**
+     * A link to join the giveaway's server - only when the card's `canJoin` is true. 404 when the server does
+     * not allow it or no invite could be made. The same link is reused; do not call it per render.
+     */
+    getPublicGiveawayJoinLink({ auth, giveawayId }: PublicGiveawaysFunctionsInput['getPublicGiveawayJoinLink']): Promise<import("../types").WebResponse<{
+        url: string;
+    }>>;
+}
+export type PublicGiveawaysFunctionsInput = {
+    'listAllPublicGiveaways': {
+        auth: string;
+        cursor?: string | null;
+    };
+    'getPublicGiveaway': {
+        auth: string;
+        giveawayId: string;
+    };
+    'createPublicGiveawayEntry': {
+        auth: string;
+        giveawayId: string;
+    };
+    'getPublicGiveawayJoinLink': {
+        auth: string;
+        giveawayId: string;
+    };
+};
+export type PublicGiveawaysGetReturnTypes = {
+    'listPublicGiveawaysRaw': Awaited<ReturnType<APIPublicGiveaways['listPublicGiveaways']>>;
+    'listPublicGiveawaysSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicGiveaways['listPublicGiveaways']>>>;
+    'listAllPublicGiveawaysRaw': Awaited<ReturnType<APIPublicGiveaways['listAllPublicGiveaways']>>;
+    'listAllPublicGiveawaysSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicGiveaways['listAllPublicGiveaways']>>>;
+    'getPublicGiveawayRaw': Awaited<ReturnType<APIPublicGiveaways['getPublicGiveaway']>>;
+    'getPublicGiveawaySuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicGiveaways['getPublicGiveaway']>>>;
+    'createPublicGiveawayEntryRaw': Awaited<ReturnType<APIPublicGiveaways['createPublicGiveawayEntry']>>;
+    'createPublicGiveawayEntrySuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicGiveaways['createPublicGiveawayEntry']>>>;
+    'getPublicGiveawayJoinLinkRaw': Awaited<ReturnType<APIPublicGiveaways['getPublicGiveawayJoinLink']>>;
+    'getPublicGiveawayJoinLinkSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPublicGiveaways['getPublicGiveawayJoinLink']>>>;
+};
+/**
+ * Every reason an entry can be refused. Mirrors `PUBLIC_ENTRY_REFUSALS` in Noti-v3's
+ * `src/modules/publicGiveaways.ts`; the eligibility ones match the card's `requirements` / `entryFilter`.
+ */
+export declare const PUBLIC_ENTRY_REFUSALS: readonly ["not_listed", "ended", "full", "not_member", "already_entered", "rate_limited", "role_whitelist", "role_blacklist", "joined_server_before", "account_created_before", "min_account_age", "boosting_server", "roles", "message_count"];
+export type PublicEntryRefusal = typeof PUBLIC_ENTRY_REFUSALS[number];
+export type PublicGiveawayRole = {
+    id: string;
+    name: string;
+};
+/** One giveaway as the public page shows it. Mirrors `PublicGiveawayCard` in Noti-v3. */
+export type PublicGiveawayCard = {
+    giveawayId: string;
+    name: string;
+    emoji: string | null;
+    /** ISO. */
+    endsAt: string;
+    winnerCount: number;
+    maxEntries: number | null;
+    entryCount: number;
+    /** Minutes winners have to press Claim; null when the giveaway does not need claiming. */
+    claimWindowMinutes: number | null;
+    /** Voting for Noti counts as a second entry. */
+    doubleVoteEntry: boolean;
+    requirements: {
+        /** ISO. */
+        joinedServerBefore: string | null;
+        /** ISO. */
+        accountCreatedBefore: string | null;
+        minAccountAgeDays: number | null;
+        boostingServer: boolean;
+        messageCount: number | null;
+        roles: PublicGiveawayRole[];
+    } | null;
+    entryFilter: {
+        mode: 'whitelist' | 'blacklist';
+        roles: PublicGiveawayRole[];
+    } | null;
+    /** `stacks: false` = only the member's highest bonus role counts. */
+    bonusRoles: {
+        roles: PublicGiveawayRole[];
+        additionalEntries: number;
+        stacks: boolean;
+    }[];
+    guild: {
+        id: string;
+        name: string;
+        icon: string | null;
+        memberCount: number;
+    };
+    /** The giveaway message in Discord. */
+    messageUrl: string;
+    /** The server lets people join from noti.bot - offer `getPublicGiveawayJoinLink`. */
+    canJoin: boolean;
+};
+export type PublicGiveawayViewer = {
+    entered: boolean;
+    isMember: boolean;
+    eligible: boolean;
+    /** Why not, when `eligible` is false. */
+    reason: PublicEntryRefusal | null;
+};
+export type PublicGiveawayList = {
+    giveaways: PublicGiveawayCard[];
+    total: number;
+};
+export type PublicGiveawayPage = {
+    giveaways: PublicGiveawayCard[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicGiveawayWithViewer = {
+    giveaway: PublicGiveawayCard;
+    viewer: PublicGiveawayViewer;
+};
+export type PublicGiveawayEntryResult = {
+    entered: true;
+    entries: number;
+};

package/dist/classes/publicGiveaways.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLIC_ENTRY_REFUSALS = exports.APIPublicGiveaways = void 0;
+// Data.
+/**
+ * The PUBLIC giveaways page - running giveaways from every server that lists them on noti.bot.
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPublicGiveaways` needs no session: the latest 10. Everything else needs a logged-in user (any
+ * Discord account - no server permission), so pass `auth`.
+ *
+ * ── LISTED BY DEFAULT ──────────────────────────────────────────────────────
+ * A server's giveaways are listed unless it switched them off (`guildGiveaway.updatePublicGiveawaySettings`),
+ * and each giveaway can override that (`publicListing`). Behind the `publicGiveaways` launch flag: while it
+ * is hidden for the caller the lists are EMPTY (not 403) and single lookups 404.
+ *
+ * ── WHAT A CARD NEVER CARRIES ──────────────────────────────────────────────
+ * No host, winners, entrants or internal ids. Roles are names, dates are ISO strings, and a role deleted
+ * since the giveaway was made reads "deleted role" rather than disappearing.
+ *
+ * The lists are cached on the server for up to a minute, so an entry count can trail by that much.
+ */
+class APIPublicGiveaways {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** The latest 10 listed giveaways and how many are listed in all. No session. */
+    async listPublicGiveaways() {
+        return await this.web.request({
+            method: 'GET',
+            endpoint: this.web.qp('/public/giveaways'),
+        });
+    }
+    /** Every listed giveaway, 24 per page, newest first. Pass the previous page's `nextCursor`; null = last page. */
+    async listAllPublicGiveaways({ auth, cursor }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/giveaways/all', cursor ? { cursor } : {}),
+        });
+    }
+    /** One listed giveaway, plus where the logged-in user stands on it. 404 when it is not listed (or ended). */
+    async getPublicGiveaway({ auth, giveawayId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/giveaways/' + giveawayId),
+        });
+    }
+    /**
+     * Enter a listed giveaway as the logged-in user - the same rules as the Discord button. A refusal is
+     * `{ status: 400 | 404 | 429, error: { code } }` with `code` from `PUBLIC_ENTRY_REFUSALS`; word it on the
+     * page (the card's `requirements` say what is required). 10 attempts per user per minute.
+     */
+    async createPublicGiveawayEntry({ auth, giveawayId }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp('/public/giveaways/' + giveawayId + '/entries'),
+        });
+    }
+    /**
+     * A link to join the giveaway's server - only when the card's `canJoin` is true. 404 when the server does
+     * not allow it or no invite could be made. The same link is reused; do not call it per render.
+     */
+    async getPublicGiveawayJoinLink({ auth, giveawayId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/giveaways/' + giveawayId + '/join'),
+        });
+    }
+}
+exports.APIPublicGiveaways = APIPublicGiveaways;
+/**
+ * Every reason an entry can be refused. Mirrors `PUBLIC_ENTRY_REFUSALS` in Noti-v3's
+ * `src/modules/publicGiveaways.ts`; the eligibility ones match the card's `requirements` / `entryFilter`.
+ */
+exports.PUBLIC_ENTRY_REFUSALS = [
+    'not_listed', 'ended', 'full', 'not_member', 'already_entered', 'rate_limited',
+    'role_whitelist', 'role_blacklist', 'joined_server_before', 'account_created_before', 'min_account_age',
+    'boosting_server', 'roles', 'message_count',
+];