@notidotbot/noti-api-client 1.9.62 → 1.9.64

package/dist/classes/guildInfluencerPanel.d.ts

@@ -0,0 +1,266 @@
+import { WebDataManager } from '../core/manager';
+import { CancelOutWebResponses, WebResponse } from '../types';
+/**
+ * Influencer Panel - members holding a role the admin chose add THEIR OWN stream from a panel posted in
+ * Discord, and Noti posts their lives, videos and posts with the server's settings.
+ *
+ * The admin sets, per platform, the channel and ping role (and a second channel/role for videos or posts
+ * where the platform has them), the live role, a log channel, a "verified" role given while a member has an
+ * active stream, and how many accounts one member may add per platform. Influencer streams count toward the
+ * server's own per-platform limit; the per-member cap never raises it.
+ *
+ * A member who loses every required role, or leaves, has their streams PAUSED (the creator is untracked and
+ * the slot freed); getting the role back resumes them while there is room. A stream that cannot come back
+ * stays paused with reason `limit`.
+ *
+ * Tiers: free - one required role, cap 1. Premium - several roles, cap up to 3, approvals, member text.
+ * Premium Plus - the full panel editor, the Live Now board, webhook identity, cap up to 5. `data.access` from
+ * `getGuildInfluencerPanel` says what the server may set; a setting above it is refused with 403.
+ *
+ * Behind the `influencerPanel` launch flag: every method answers 403 until it is beta/public for the caller,
+ * and 403 when the server's plan lacks the Influencer Panel.
+ */
+export declare class APIGuildInfluencerPanel {
+    private web;
+    constructor(web: WebDataManager);
+    /** The setup (`panel` null = never set up), what the plan allows, the platforms on offer and entry counts. */
+    getGuildInfluencerPanel({ auth, guildId }: GuildInfluencerPanelFunctionsInput['getGuildInfluencerPanel']): Promise<WebResponse<GuildInfluencerPanelData>>;
+    /**
+     * Change the setup, field by field - omit one to leave it unchanged. `platforms` upserts the platforms
+     * listed and leaves the others alone.
+     *
+     * 400 names the problem: a bad id, a platform switched on without a channel, a setting the platform does
+     * not have, or a channel/role Noti cannot use. **403** for a setting above the plan. Turning a Premium
+     * setting OFF is always accepted.
+     *
+     * After saving, every active influencer stream is updated to the new settings (and paused where its
+     * platform went off), a posted panel and board are redrawn, and switching the panel back on resumes what
+     * switching it off paused. `applied`, `panelError` and `boardError` report that.
+     */
+    updateGuildInfluencerPanel({ auth, guildId, ...body }: GuildInfluencerPanelFunctionsInput['updateGuildInfluencerPanel']): Promise<WebResponse<GuildInfluencerPanelUpdateData>>;
+    /** Post the panel to `panelChannelId`, or redraw it where it already is. 400 with the reason when Discord or a permission refuses. */
+    createGuildInfluencerPanelMessage({ auth, guildId }: GuildInfluencerPanelFunctionsInput['createGuildInfluencerPanelMessage']): Promise<WebResponse<GuildInfluencerPanelData>>;
+    /** Delete the posted panel message. The setup and every stream stay. */
+    deleteGuildInfluencerPanelMessage({ auth, guildId }: GuildInfluencerPanelFunctionsInput['deleteGuildInfluencerPanelMessage']): Promise<WebResponse<GuildInfluencerPanelData>>;
+    /** Members' streams, newest first (at most 500). `status: 'pending'` is the approval queue. */
+    getGuildInfluencerEntries({ auth, guildId, status }: GuildInfluencerPanelFunctionsInput['getGuildInfluencerEntries']): Promise<WebResponse<{
+        entries: GuildInfluencerEntry[];
+    }>>;
+    /**
+     * Act on one stream: `pause` (active only), `resume` (paused only - goes through the server's limit
+     * again), `approve` or `deny` (pending only; `reason` is sent to the member). 404 when it is not this
+     * server's, 409 while the member's streams are being changed.
+     */
+    updateGuildInfluencerEntry({ auth, guildId, entryId, ...body }: GuildInfluencerPanelFunctionsInput['updateGuildInfluencerEntry']): Promise<WebResponse<{
+        entry: GuildInfluencerEntry;
+    }>>;
+    /** Remove a stream: the creator is untracked and the member is told in the log channel. */
+    deleteGuildInfluencerEntry({ auth, guildId, entryId }: GuildInfluencerPanelFunctionsInput['deleteGuildInfluencerEntry']): Promise<WebResponse<{
+        entryId: string;
+    }>>;
+}
+/** Platforms the panel offers. */
+export type InfluencerPlatform = 'kick' | 'twitch' | 'youtube' | 'tiktok' | 'rumble' | 'twitter' | 'club';
+/** Every `InfluencerPlatform`, in the order the API lists them. */
+export declare const INFLUENCER_PLATFORMS: readonly InfluencerPlatform[];
+export type InfluencerEntryStatus = 'pending' | 'active' | 'paused' | 'denied';
+/** Why a stream is paused: lost the role, left, panel/platform switched off, paused by an admin, server limit full on resume. */
+export type InfluencerPausedReason = 'role' | 'left' | 'panelOff' | 'manual' | 'limit';
+export type InfluencerEntryAction = 'pause' | 'resume' | 'approve' | 'deny';
+export type GuildInfluencerPlatformSettings = {
+    platform: InfluencerPlatform;
+    enabled: boolean;
+    /** Lives (posts on Club). */
+    channelId: string | null;
+    pingRoleId: string | null;
+    /** Videos (YouTube, TikTok, Rumble) or posts (X). */
+    secondaryChannelId: string | null;
+    /** YouTube, Rumble and X only - TikTok uses `pingRoleId` for both. */
+    secondaryPingRoleId: string | null;
+};
+/** The panel message's look. `title` and `description` on every plan; the rest is Premium Plus. */
+export type GuildInfluencerPanelDesign = {
+    title?: string;
+    description?: string;
+    /** 0x000000-0xFFFFFF. */
+    color?: number;
+    /** https only. */
+    imageUrl?: string;
+    footer?: string;
+    addLabel?: string;
+    mineLabel?: string;
+    addEmoji?: string;
+    mineEmoji?: string;
+};
+export type GuildInfluencerPanel = {
+    dbId: string;
+    guildId: string;
+    enabled: boolean;
+    /** Any one of them lets a member use the panel. More than one is Premium. */
+    requiredRoleIds: string[];
+    logChannelId: string | null;
+    /** Streams one member may add per platform. */
+    perMemberLimit: number;
+    liveRoleId: string | null;
+    verifiedRoleId: string | null;
+    /**
+     * Creator Managers (every plan): besides Manage Server, members with one of these roles may approve /
+     * deny requests from the log channel and use `/influencer add|remove @member` in Discord.
+     */
+    managerRoleIds: string[];
+    /** Premium. */
+    requireApproval: boolean;
+    /** Premium. The member's own line replaces the random message. */
+    allowMemberText: boolean;
+    /** Adds `{member}` (the member's mention) to their notifications. */
+    showMemberTag: boolean;
+    /**
+     * Premium Plus + CustomWebhooks. Influencer notifications (live, offline, video, posts) post through a
+     * webhook with `webhookUsername` / `webhookAvatarUrl`. A creator's own custom-message webhook still wins;
+     * this wins over the server's default. Applies only while a name or an avatar is set.
+     */
+    useWebhook: boolean;
+    /** 1-80 characters, no "discord" or "clyde". Takes placeholders, e.g. `{streamerName}`. */
+    webhookUsername: string | null;
+    /** https only. */
+    webhookAvatarUrl: string | null;
+    panelChannelId: string | null;
+    panelMessageId: string | null;
+    panelDesign: GuildInfluencerPanelDesign | null;
+    /** Premium Plus. */
+    liveBoardChannelId: string | null;
+    liveBoardMessageId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    platforms: GuildInfluencerPlatformSettings[];
+};
+/** What the server's plan allows. */
+export type GuildInfluencerPanelAccess = {
+    tier: 'free' | 'premium' | 'plus';
+    maxRequiredRoles: number;
+    maxPerMemberLimit: number;
+    approvals: boolean;
+    memberText: boolean;
+    /** The full panel editor (beyond title and description). */
+    panelDesign: boolean;
+    liveBoard: boolean;
+    /** Webhook identity: Premium Plus AND CustomWebhooks. */
+    webhook: boolean;
+};
+/** Which settings a platform has, so the page draws the right fields. */
+export type GuildInfluencerPlatformMeta = {
+    platform: InfluencerPlatform;
+    secondary: 'video' | 'post' | null;
+    secondaryRole: boolean;
+};
+export type GuildInfluencerPanelData = {
+    panel: GuildInfluencerPanel | null;
+    access: GuildInfluencerPanelAccess;
+    platforms: GuildInfluencerPlatformMeta[];
+    counts: Record<InfluencerEntryStatus, number>;
+};
+export type GuildInfluencerPanelUpdateData = GuildInfluencerPanelData & {
+    /** Active streams updated, paused (platform went off) and resumed (panel switched back on). */
+    applied: {
+        updated: number;
+        paused: number;
+        resumed: number;
+    };
+    /** Why a posted panel could not be redrawn, or null. */
+    panelError: string | null;
+    /** Why the Live Now board could not be redrawn, or null. */
+    boardError: string | null;
+};
+export type GuildInfluencerEntry = {
+    dbId: string;
+    guildId: string;
+    /** The member's Discord id. */
+    userId: string;
+    platform: InfluencerPlatform;
+    streamerUserName: string;
+    status: InfluencerEntryStatus;
+    pausedReason: InfluencerPausedReason | null;
+    deniedReason: string | null;
+    /** The member's own line (Premium). */
+    note: string | null;
+    /** Who approved or denied it. */
+    decidedBy: string | null;
+    /** Rumble only: 'channel' or 'user'. */
+    rumbleType: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** The setup's editable fields. */
+export type GuildInfluencerPanelUpdate = {
+    enabled?: boolean;
+    requiredRoleIds?: string[];
+    /** Up to 10 roles. Checked against the server: a role that no longer exists is refused. */
+    managerRoleIds?: string[];
+    logChannelId?: string | null;
+    perMemberLimit?: number;
+    liveRoleId?: string | null;
+    verifiedRoleId?: string | null;
+    requireApproval?: boolean;
+    allowMemberText?: boolean;
+    showMemberTag?: boolean;
+    panelChannelId?: string | null;
+    panelDesign?: GuildInfluencerPanelDesign | null;
+    liveBoardChannelId?: string | null;
+    useWebhook?: boolean;
+    webhookUsername?: string | null;
+    webhookAvatarUrl?: string | null;
+    platforms?: Array<{
+        platform: InfluencerPlatform;
+    } & Partial<Omit<GuildInfluencerPlatformSettings, 'platform'>>>;
+};
+export type GuildInfluencerPanelFunctionsInput = {
+    'getGuildInfluencerPanel': {
+        auth: string;
+        guildId: string;
+    };
+    'updateGuildInfluencerPanel': {
+        auth: string;
+        guildId: string;
+    } & GuildInfluencerPanelUpdate;
+    'createGuildInfluencerPanelMessage': {
+        auth: string;
+        guildId: string;
+    };
+    'deleteGuildInfluencerPanelMessage': {
+        auth: string;
+        guildId: string;
+    };
+    'getGuildInfluencerEntries': {
+        auth: string;
+        guildId: string;
+        status?: InfluencerEntryStatus;
+    };
+    'updateGuildInfluencerEntry': {
+        auth: string;
+        guildId: string;
+        entryId: string;
+        action: InfluencerEntryAction;
+        reason?: string;
+    };
+    'deleteGuildInfluencerEntry': {
+        auth: string;
+        guildId: string;
+        entryId: string;
+    };
+};
+export type GuildInfluencerPanelReturnTypes = {
+    'getGuildInfluencerPanelRaw': Awaited<ReturnType<APIGuildInfluencerPanel['getGuildInfluencerPanel']>>;
+    'getGuildInfluencerPanelSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['getGuildInfluencerPanel']>>>;
+    'updateGuildInfluencerPanelRaw': Awaited<ReturnType<APIGuildInfluencerPanel['updateGuildInfluencerPanel']>>;
+    'updateGuildInfluencerPanelSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['updateGuildInfluencerPanel']>>>;
+    'createGuildInfluencerPanelMessageRaw': Awaited<ReturnType<APIGuildInfluencerPanel['createGuildInfluencerPanelMessage']>>;
+    'createGuildInfluencerPanelMessageSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['createGuildInfluencerPanelMessage']>>>;
+    'deleteGuildInfluencerPanelMessageRaw': Awaited<ReturnType<APIGuildInfluencerPanel['deleteGuildInfluencerPanelMessage']>>;
+    'deleteGuildInfluencerPanelMessageSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['deleteGuildInfluencerPanelMessage']>>>;
+    'getGuildInfluencerEntriesRaw': Awaited<ReturnType<APIGuildInfluencerPanel['getGuildInfluencerEntries']>>;
+    'getGuildInfluencerEntriesSuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['getGuildInfluencerEntries']>>>;
+    'updateGuildInfluencerEntryRaw': Awaited<ReturnType<APIGuildInfluencerPanel['updateGuildInfluencerEntry']>>;
+    'updateGuildInfluencerEntrySuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['updateGuildInfluencerEntry']>>>;
+    'deleteGuildInfluencerEntryRaw': Awaited<ReturnType<APIGuildInfluencerPanel['deleteGuildInfluencerEntry']>>;
+    'deleteGuildInfluencerEntrySuccess': CancelOutWebResponses<Awaited<ReturnType<APIGuildInfluencerPanel['deleteGuildInfluencerEntry']>>>;
+};

package/dist/classes/guildInfluencerPanel.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INFLUENCER_PLATFORMS = exports.APIGuildInfluencerPanel = void 0;
+/**
+ * Influencer Panel - members holding a role the admin chose add THEIR OWN stream from a panel posted in
+ * Discord, and Noti posts their lives, videos and posts with the server's settings.
+ *
+ * The admin sets, per platform, the channel and ping role (and a second channel/role for videos or posts
+ * where the platform has them), the live role, a log channel, a "verified" role given while a member has an
+ * active stream, and how many accounts one member may add per platform. Influencer streams count toward the
+ * server's own per-platform limit; the per-member cap never raises it.
+ *
+ * A member who loses every required role, or leaves, has their streams PAUSED (the creator is untracked and
+ * the slot freed); getting the role back resumes them while there is room. A stream that cannot come back
+ * stays paused with reason `limit`.
+ *
+ * Tiers: free - one required role, cap 1. Premium - several roles, cap up to 3, approvals, member text.
+ * Premium Plus - the full panel editor, the Live Now board, webhook identity, cap up to 5. `data.access` from
+ * `getGuildInfluencerPanel` says what the server may set; a setting above it is refused with 403.
+ *
+ * Behind the `influencerPanel` launch flag: every method answers 403 until it is beta/public for the caller,
+ * and 403 when the server's plan lacks the Influencer Panel.
+ */
+class APIGuildInfluencerPanel {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** The setup (`panel` null = never set up), what the plan allows, the platforms on offer and entry counts. */
+    async getGuildInfluencerPanel({ auth, guildId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel`),
+        });
+    }
+    /**
+     * Change the setup, field by field - omit one to leave it unchanged. `platforms` upserts the platforms
+     * listed and leaves the others alone.
+     *
+     * 400 names the problem: a bad id, a platform switched on without a channel, a setting the platform does
+     * not have, or a channel/role Noti cannot use. **403** for a setting above the plan. Turning a Premium
+     * setting OFF is always accepted.
+     *
+     * After saving, every active influencer stream is updated to the new settings (and paused where its
+     * platform went off), a posted panel and board are redrawn, and switching the panel back on resumes what
+     * switching it off paused. `applied`, `panelError` and `boardError` report that.
+     */
+    async updateGuildInfluencerPanel({ auth, guildId, ...body }) {
+        return await this.web.request({
+            method: 'PATCH', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel`),
+            body,
+        });
+    }
+    /** Post the panel to `panelChannelId`, or redraw it where it already is. 400 with the reason when Discord or a permission refuses. */
+    async createGuildInfluencerPanelMessage({ auth, guildId }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel/message`),
+        });
+    }
+    /** Delete the posted panel message. The setup and every stream stay. */
+    async deleteGuildInfluencerPanelMessage({ auth, guildId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel/message`),
+        });
+    }
+    /** Members' streams, newest first (at most 500). `status: 'pending'` is the approval queue. */
+    async getGuildInfluencerEntries({ auth, guildId, status }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel/entries`, { status }),
+        });
+    }
+    /**
+     * Act on one stream: `pause` (active only), `resume` (paused only - goes through the server's limit
+     * again), `approve` or `deny` (pending only; `reason` is sent to the member). 404 when it is not this
+     * server's, 409 while the member's streams are being changed.
+     */
+    async updateGuildInfluencerEntry({ auth, guildId, entryId, ...body }) {
+        return await this.web.request({
+            method: 'PATCH', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel/entries/${entryId}`),
+            body,
+        });
+    }
+    /** Remove a stream: the creator is untracked and the member is told in the log channel. */
+    async deleteGuildInfluencerEntry({ auth, guildId, entryId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp(`/data/guild/${guildId}/influencer-panel/entries/${entryId}`),
+        });
+    }
+}
+exports.APIGuildInfluencerPanel = APIGuildInfluencerPanel;
+/** Every `InfluencerPlatform`, in the order the API lists them. */
+exports.INFLUENCER_PLATFORMS = ['kick', 'twitch', 'youtube', 'tiktok', 'rumble', 'twitter', 'club'];

package/dist/classes/guildPlatform.d.ts

@@ -132,9 +132,21 @@ type ResolvesUsersForLiveRole = 'kick' | 'twitch' | 'rumble' | 'tiktok' | 'youtu
  * `string[]`, not with `[]`. Discriminate on the element - `typeof first === 'string'` - rather than
  * on length, because an empty array is a legitimate member of both arms.
  */
-export type GuildSingleStreamerWithFormatedRole<T extends AllPlatforms> = T extends ServedPlatform ? T extends ResolvesUsersForLiveRole ? Omit<GuildSingleStreamer<T>, 'usersForLiveRole'> & {
+/**
+ * A creator a community member added from the Influencer Panel: the member, and their panel entry (for
+ * `guildInfluencerPanel.updateGuildInfluencerEntry` / `deleteGuildInfluencerEntry`). `null` on every
+ * creator an admin added. Only on the two GET routes - create/update answer with the row alone.
+ */
+export type GuildStreamerInfluencerLink = {
+    userId: string;
+    entryId: string;
+};
+type WithInfluencerLink = {
+    influencer: GuildStreamerInfluencerLink | null;
+};
+export type GuildSingleStreamerWithFormatedRole<T extends AllPlatforms> = T extends ServedPlatform ? (T extends ResolvesUsersForLiveRole ? Omit<GuildSingleStreamer<T>, 'usersForLiveRole'> & {
     usersForLiveRole: UsersForLiveRole | string[];
-} : GuildSingleStreamer<T> : never;
+} : GuildSingleStreamer<T>) & WithInfluencerLink : never;
 /**
  * The platforms `GET /data/guild/:guildId/:platform` can actually answer.
  *
@@ -191,7 +203,7 @@ export type Platformstreamers<T extends boolean, P extends AllPlatforms> = {
      * The zod type under-claims instead (it also drops the relation FK scalars), and under-claiming
      * cannot be read by accident.
      */
-    streamers: P extends ServedPlatform ? (T extends true ? Pick<GuildSingleStreamer<P>, Extract<keyof GuildSingleStreamer<P>, ShortViewKeySets[P]>> : GuildSingleStreamer<P>)[] : never;
+    streamers: P extends ServedPlatform ? ((T extends true ? Pick<GuildSingleStreamer<P>, Extract<keyof GuildSingleStreamer<P>, ShortViewKeySets[P]>> : GuildSingleStreamer<P>) & WithInfluencerLink)[] : never;
     currentTotal: number;
     maxLimit: number;
     premium: {

package/dist/classes/polls.d.ts

@@ -0,0 +1,117 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * Site polls - developer-run polls on the dashboard ("which feature next?").
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPolls` needs no session. Everything else needs a logged-in user (any Discord account), so pass `auth`.
+ * Behind the `sitePolls` launch flag: while it is hidden for the caller the list is EMPTY (not 403) and a
+ * single poll 404s. Draft and scheduled polls are 404 here; developers manage them through `adminPolls`.
+ *
+ * ── RESULTS ────────────────────────────────────────────────────────────────
+ * Each poll sets `resultsVisibility`: `always`, `afterVote` (once this user has voted, or the poll closed) or
+ * `afterClose`. The server never sends counts the viewer may not see, so `results` is null until then - do
+ * not compute or guess them on the page.
+ *
+ * Percent is a share of VOTES on a single-choice poll and a share of VOTERS on a multi-choice one (so those
+ * can sum past 100). The public list is cached up to 15s, so counts there can trail by that much.
+ */
+export declare class APIPolls {
+    private web;
+    constructor(web: WebDataManager);
+    /** Open polls first, then ones closed in the last 30 days. No session. */
+    listPolls(): Promise<import("../types").WebResponse<SitePollList>>;
+    /** One poll, plus where the logged-in user stands on it. */
+    getPoll({ auth, pollId }: PollsFunctionsInput['getPoll']): Promise<import("../types").WebResponse<SitePollView>>;
+    /**
+     * Cast or change the logged-in user's vote: `optionIds` is the full pick (1 to `maxChoices`), replacing
+     * any earlier one. A refusal is `{ status: 400 | 404 | 409 | 429, error: { code } }`, `code` from
+     * `SitePollErrorCode`. Re-sending the same pick is not an error even when changes are locked. 10/minute.
+     */
+    setPollVote({ auth, pollId, optionIds }: PollsFunctionsInput['setPollVote']): Promise<import("../types").WebResponse<SitePollView>>;
+    /** Withdraw the logged-in user's vote. Only on polls with `allowVoteChange`, while open. */
+    deletePollVote({ auth, pollId }: PollsFunctionsInput['deletePollVote']): Promise<import("../types").WebResponse<SitePollView>>;
+}
+export type PollsFunctionsInput = {
+    'getPoll': {
+        auth: string;
+        pollId: string;
+    };
+    'setPollVote': {
+        auth: string;
+        pollId: string;
+        optionIds: string[];
+    };
+    'deletePollVote': {
+        auth: string;
+        pollId: string;
+    };
+};
+export type PollsGetReturnTypes = {
+    'listPollsRaw': Awaited<ReturnType<APIPolls['listPolls']>>;
+    'listPollsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPolls['listPolls']>>>;
+    'getPollRaw': Awaited<ReturnType<APIPolls['getPoll']>>;
+    'getPollSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPolls['getPoll']>>>;
+    'setPollVoteRaw': Awaited<ReturnType<APIPolls['setPollVote']>>;
+    'setPollVoteSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPolls['setPollVote']>>>;
+    'deletePollVoteRaw': Awaited<ReturnType<APIPolls['deletePollVote']>>;
+    'deletePollVoteSuccess': CancelOutWebResponses<Awaited<ReturnType<APIPolls['deletePollVote']>>>;
+};
+/** Why a vote or withdrawal was refused. Mirrors `SITE_POLL_REFUSALS` in Noti-v3's `src/modules/sitePolls.ts`. */
+export declare const SITE_POLL_REFUSALS: readonly ["not_open", "closed", "no_choice", "too_many_choices", "invalid_option", "vote_locked"];
+export type SitePollRefusal = typeof SITE_POLL_REFUSALS[number];
+/** Every `error.code` the vote routes return: the refusals, plus `busy` (a vote of theirs is still saving) and `rate_limited`. */
+export type SitePollErrorCode = SitePollRefusal | 'busy' | 'rate_limited';
+export type SitePollState = 'draft' | 'scheduled' | 'open' | 'closed';
+export type SitePollResultsVisibility = 'always' | 'afterVote' | 'afterClose';
+/** One poll as the site shows it. Mirrors `SitePollCard` in Noti-v3. */
+export type SitePoll = {
+    pollId: string;
+    title: string;
+    /** Markdown. */
+    description: string | null;
+    state: SitePollState;
+    /** 1 = single choice. */
+    maxChoices: number;
+    allowVoteChange: boolean;
+    resultsVisibility: SitePollResultsVisibility;
+    /** ISO. */
+    opensAt: string | null;
+    /** ISO. */
+    closesAt: string | null;
+    /** In display order. */
+    options: SitePollOption[];
+};
+export type SitePollOption = {
+    optionId: string;
+    label: string;
+    description: string | null;
+};
+export type SitePollResults = {
+    /** In display order. */
+    options: Array<{
+        optionId: string;
+        votes: number;
+        percent: number;
+    }>;
+    totalVotes: number;
+    totalVoters: number;
+};
+export type SitePollViewer = {
+    votedOptionIds: string[];
+    /** Can vote now (open, and not voted yet or changes allowed). */
+    canVote: boolean;
+    canChangeVote: boolean;
+    resultsVisible: boolean;
+};
+export type SitePollList = {
+    polls: Array<{
+        poll: SitePoll;
+        results: SitePollResults | null;
+    }>;
+};
+export type SitePollView = {
+    poll: SitePoll;
+    viewer: SitePollViewer;
+    results: SitePollResults | null;
+};

package/dist/classes/polls.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITE_POLL_REFUSALS = exports.APIPolls = void 0;
+// Data.
+/**
+ * Site polls - developer-run polls on the dashboard ("which feature next?").
+ *
+ * ── WHO SEES WHAT ──────────────────────────────────────────────────────────
+ * `listPolls` needs no session. Everything else needs a logged-in user (any Discord account), so pass `auth`.
+ * Behind the `sitePolls` launch flag: while it is hidden for the caller the list is EMPTY (not 403) and a
+ * single poll 404s. Draft and scheduled polls are 404 here; developers manage them through `adminPolls`.
+ *
+ * ── RESULTS ────────────────────────────────────────────────────────────────
+ * Each poll sets `resultsVisibility`: `always`, `afterVote` (once this user has voted, or the poll closed) or
+ * `afterClose`. The server never sends counts the viewer may not see, so `results` is null until then - do
+ * not compute or guess them on the page.
+ *
+ * Percent is a share of VOTES on a single-choice poll and a share of VOTERS on a multi-choice one (so those
+ * can sum past 100). The public list is cached up to 15s, so counts there can trail by that much.
+ */
+class APIPolls {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** Open polls first, then ones closed in the last 30 days. No session. */
+    async listPolls() {
+        return await this.web.request({
+            method: 'GET',
+            endpoint: this.web.qp('/public/polls'),
+        });
+    }
+    /** One poll, plus where the logged-in user stands on it. */
+    async getPoll({ auth, pollId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/polls/' + pollId),
+        });
+    }
+    /**
+     * Cast or change the logged-in user's vote: `optionIds` is the full pick (1 to `maxChoices`), replacing
+     * any earlier one. A refusal is `{ status: 400 | 404 | 409 | 429, error: { code } }`, `code` from
+     * `SitePollErrorCode`. Re-sending the same pick is not an error even when changes are locked. 10/minute.
+     */
+    async setPollVote({ auth, pollId, optionIds }) {
+        return await this.web.request({
+            method: 'PUT', auth,
+            endpoint: this.web.qp('/public/polls/' + pollId + '/votes/@me'),
+            body: { optionIds },
+        });
+    }
+    /** Withdraw the logged-in user's vote. Only on polls with `allowVoteChange`, while open. */
+    async deletePollVote({ auth, pollId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp('/public/polls/' + pollId + '/votes/@me'),
+        });
+    }
+}
+exports.APIPolls = APIPolls;
+/** Why a vote or withdrawal was refused. Mirrors `SITE_POLL_REFUSALS` in Noti-v3's `src/modules/sitePolls.ts`. */
+exports.SITE_POLL_REFUSALS = ['not_open', 'closed', 'no_choice', 'too_many_choices', 'invalid_option', 'vote_locked'];