@notidotbot/noti-api-client 1.9.63 → 1.9.64

package/dist/classes/adminAnnouncements.d.ts

@@ -0,0 +1,108 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+import type { SiteAnnouncementSeverity } from './announcements';
+/**
+ * Site announcements - the developers' side. Every method is developer-only (403 otherwise) and NOT behind the
+ * `siteAnnouncements` flag, so announcements can be drafted before launch. Every write refreshes what the
+ * site shows.
+ *
+ * Publishing with `postToDiscord` posts it to the site-updates Discord webhook ONCE (only if the server has one
+ * configured); `postedToDiscordAt` says when.
+ */
+export declare class APIAdminAnnouncements {
+    private web;
+    constructor(web: WebDataManager);
+    /** Every announcement, drafts and ended ones included, newest first. */
+    listAdminAnnouncements({ auth }: AdminAnnouncementsFunctionsInput['listAdminAnnouncements']): Promise<import("../types").WebResponse<{
+        announcements: AdminSiteAnnouncement[];
+    }>>;
+    /**
+     * Create an announcement. Rules checked on the server: in the feed, as a banner, or both; `linkUrl` and
+     * `linkLabel` together; `endsAt` after `startsAt`.
+     */
+    createAnnouncement({ auth, announcement }: AdminAnnouncementsFunctionsInput['createAnnouncement']): Promise<import("../types").WebResponse<AdminSiteAnnouncement>>;
+    /** Edit an announcement; send only what changes. The same rules apply to the result. */
+    updateAnnouncement({ auth, announcementId, announcement }: AdminAnnouncementsFunctionsInput['updateAnnouncement']): Promise<import("../types").WebResponse<AdminSiteAnnouncement>>;
+    /** Delete an announcement with its dismissals. */
+    deleteAnnouncement({ auth, announcementId }: AdminAnnouncementsFunctionsInput['deleteAnnouncement']): Promise<import("../types").WebResponse<{
+        announcementId: string;
+    }>>;
+}
+export type AdminAnnouncementsFunctionsInput = {
+    'listAdminAnnouncements': {
+        auth: string;
+    };
+    'createAnnouncement': {
+        auth: string;
+        announcement: SiteAnnouncementCreateInput;
+    };
+    'updateAnnouncement': {
+        auth: string;
+        announcementId: string;
+        announcement: SiteAnnouncementUpdateInput;
+    };
+    'deleteAnnouncement': {
+        auth: string;
+        announcementId: string;
+    };
+};
+export type AdminAnnouncementsGetReturnTypes = {
+    'listAdminAnnouncementsRaw': Awaited<ReturnType<APIAdminAnnouncements['listAdminAnnouncements']>>;
+    'listAdminAnnouncementsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminAnnouncements['listAdminAnnouncements']>>>;
+    'createAnnouncementRaw': Awaited<ReturnType<APIAdminAnnouncements['createAnnouncement']>>;
+    'createAnnouncementSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminAnnouncements['createAnnouncement']>>>;
+    'updateAnnouncementRaw': Awaited<ReturnType<APIAdminAnnouncements['updateAnnouncement']>>;
+    'updateAnnouncementSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminAnnouncements['updateAnnouncement']>>>;
+    'deleteAnnouncementRaw': Awaited<ReturnType<APIAdminAnnouncements['deleteAnnouncement']>>;
+    'deleteAnnouncementSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminAnnouncements['deleteAnnouncement']>>>;
+};
+/** The developers' view of an announcement: every field, dates as ISO. */
+export type AdminSiteAnnouncement = {
+    announcementId: string;
+    title: string;
+    body: string;
+    severity: SiteAnnouncementSeverity;
+    linkUrl: string | null;
+    linkLabel: string | null;
+    showInFeed: boolean;
+    showAsBanner: boolean;
+    dismissible: boolean;
+    pinned: boolean;
+    isPublished: boolean;
+    /** Published and inside its window right now. */
+    isActive: boolean;
+    startsAt: string | null;
+    endsAt: string | null;
+    postToDiscord: boolean;
+    postedToDiscordAt: string | null;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/** Mirrors `SiteAnnouncementCreateSchema` in Noti-v3's `src/json/zod/site.zod.ts`. Defaults are the server's. */
+export type SiteAnnouncementCreateInput = {
+    title: string;
+    /** Markdown. */
+    body: string;
+    /** Default `info`. */
+    severity?: SiteAnnouncementSeverity;
+    /** http(s) only; goes with `linkLabel`. */
+    linkUrl?: string | null;
+    linkLabel?: string | null;
+    /** Default true. */
+    showInFeed?: boolean;
+    /** Default false. */
+    showAsBanner?: boolean;
+    /** Default true. */
+    dismissible?: boolean;
+    /** Default false. */
+    pinned?: boolean;
+    /** Default false (draft). */
+    isPublished?: boolean;
+    startsAt?: Date | string | null;
+    endsAt?: Date | string | null;
+    /** Default false. */
+    postToDiscord?: boolean;
+};
+/** Mirrors `SiteAnnouncementUpdateSchema` in Noti-v3. */
+export type SiteAnnouncementUpdateInput = Partial<SiteAnnouncementCreateInput>;

package/dist/classes/adminAnnouncements.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIAdminAnnouncements = void 0;
+// Data.
+/**
+ * Site announcements - the developers' side. Every method is developer-only (403 otherwise) and NOT behind the
+ * `siteAnnouncements` flag, so announcements can be drafted before launch. Every write refreshes what the
+ * site shows.
+ *
+ * Publishing with `postToDiscord` posts it to the site-updates Discord webhook ONCE (only if the server has one
+ * configured); `postedToDiscordAt` says when.
+ */
+class APIAdminAnnouncements {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** Every announcement, drafts and ended ones included, newest first. */
+    async listAdminAnnouncements({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/announcements'),
+        });
+    }
+    /**
+     * Create an announcement. Rules checked on the server: in the feed, as a banner, or both; `linkUrl` and
+     * `linkLabel` together; `endsAt` after `startsAt`.
+     */
+    async createAnnouncement({ auth, announcement }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp('/admin/announcements'),
+            body: announcement,
+        });
+    }
+    /** Edit an announcement; send only what changes. The same rules apply to the result. */
+    async updateAnnouncement({ auth, announcementId, announcement }) {
+        return await this.web.request({
+            method: 'PATCH', auth,
+            endpoint: this.web.qp('/admin/announcements/' + announcementId),
+            body: announcement,
+        });
+    }
+    /** Delete an announcement with its dismissals. */
+    async deleteAnnouncement({ auth, announcementId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp('/admin/announcements/' + announcementId),
+        });
+    }
+}
+exports.APIAdminAnnouncements = APIAdminAnnouncements;

package/dist/classes/adminPolls.d.ts

@@ -0,0 +1,111 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+import type { SitePoll, SitePollResults, SitePollResultsVisibility } from './polls';
+/**
+ * Site polls - the developers' side. Every method is developer-only (403 otherwise) and NOT behind the
+ * `sitePolls` flag, so polls can be drafted before launch.
+ *
+ * Publishing with `postToDiscord` posts the poll to the site-updates Discord webhook ONCE (only if the
+ * server has one configured); `postedToDiscordAt` says when. Unpublishing and publishing again never posts twice.
+ */
+export declare class APIAdminPolls {
+    private web;
+    constructor(web: WebDataManager);
+    /** Every poll, drafts included, newest first, with full counts. */
+    listAdminPolls({ auth }: AdminPollsFunctionsInput['listAdminPolls']): Promise<import("../types").WebResponse<{
+        polls: AdminSitePoll[];
+    }>>;
+    /** Create a poll with 2 to 20 options. `maxChoices` cannot exceed the option count; `closesAt` must follow `opensAt`. */
+    createPoll({ auth, poll }: AdminPollsFunctionsInput['createPoll']): Promise<import("../types").WebResponse<AdminSitePoll>>;
+    /**
+     * Edit a poll; send only what changes. `options` REPLACES the list: send an existing option's `optionId`
+     * to keep it (and its votes). Removing an option that has votes is
+     * `{ status: 409, error: { code: 'option_has_votes', optionIds } }` unless `force: true`, which deletes them.
+     */
+    updatePoll({ auth, pollId, poll }: AdminPollsFunctionsInput['updatePoll']): Promise<import("../types").WebResponse<AdminSitePoll>>;
+    /** Delete a poll with its options and votes. */
+    deletePoll({ auth, pollId }: AdminPollsFunctionsInput['deletePoll']): Promise<import("../types").WebResponse<{
+        pollId: string;
+    }>>;
+    /** Full counts, whatever the poll's `resultsVisibility`. */
+    getPollResults({ auth, pollId }: AdminPollsFunctionsInput['getPollResults']): Promise<import("../types").WebResponse<SitePollResults>>;
+}
+export type AdminPollsFunctionsInput = {
+    'listAdminPolls': {
+        auth: string;
+    };
+    'createPoll': {
+        auth: string;
+        poll: SitePollCreateInput;
+    };
+    'updatePoll': {
+        auth: string;
+        pollId: string;
+        poll: SitePollUpdateInput;
+    };
+    'deletePoll': {
+        auth: string;
+        pollId: string;
+    };
+    'getPollResults': {
+        auth: string;
+        pollId: string;
+    };
+};
+export type AdminPollsGetReturnTypes = {
+    'listAdminPollsRaw': Awaited<ReturnType<APIAdminPolls['listAdminPolls']>>;
+    'listAdminPollsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminPolls['listAdminPolls']>>>;
+    'createPollRaw': Awaited<ReturnType<APIAdminPolls['createPoll']>>;
+    'createPollSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminPolls['createPoll']>>>;
+    'updatePollRaw': Awaited<ReturnType<APIAdminPolls['updatePoll']>>;
+    'updatePollSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminPolls['updatePoll']>>>;
+    'deletePollRaw': Awaited<ReturnType<APIAdminPolls['deletePoll']>>;
+    'deletePollSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminPolls['deletePoll']>>>;
+    'getPollResultsRaw': Awaited<ReturnType<APIAdminPolls['getPollResults']>>;
+    'getPollResultsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAdminPolls['getPollResults']>>>;
+};
+/** The developers' view of a poll: the public poll plus everything the public never sees. */
+export type AdminSitePoll = SitePoll & {
+    isPublished: boolean;
+    postToDiscord: boolean;
+    /** ISO; null until it has been posted. */
+    postedToDiscordAt: string | null;
+    /** Discord id of the developer who made it. */
+    createdBy: string;
+    /** ISO. */
+    createdAt: string;
+    /** ISO. */
+    updatedAt: string;
+    results: SitePollResults;
+};
+/** Mirrors `SitePollCreateSchema` in Noti-v3's `src/json/zod/site.zod.ts`. Defaults are the server's. */
+export type SitePollCreateInput = {
+    title: string;
+    description?: string | null;
+    /** Default 1 (single choice). */
+    maxChoices?: number;
+    /** Default false. */
+    allowVoteChange?: boolean;
+    /** Default `afterVote`. */
+    resultsVisibility?: SitePollResultsVisibility;
+    /** Default false (draft). */
+    isPublished?: boolean;
+    opensAt?: Date | string | null;
+    closesAt?: Date | string | null;
+    /** Default false. */
+    postToDiscord?: boolean;
+    options: Array<{
+        label: string;
+        description?: string | null;
+    }>;
+};
+/** Mirrors `SitePollUpdateSchema` in Noti-v3. */
+export type SitePollUpdateInput = Partial<Omit<SitePollCreateInput, 'options'>> & {
+    options?: Array<{
+        optionId?: string;
+        label: string;
+        description?: string | null;
+    }>;
+    /** Allow removing options that have votes (their votes are deleted). */
+    force?: boolean;
+};

package/dist/classes/adminPolls.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIAdminPolls = void 0;
+// Data.
+/**
+ * Site polls - the developers' side. Every method is developer-only (403 otherwise) and NOT behind the
+ * `sitePolls` flag, so polls can be drafted before launch.
+ *
+ * Publishing with `postToDiscord` posts the poll to the site-updates Discord webhook ONCE (only if the
+ * server has one configured); `postedToDiscordAt` says when. Unpublishing and publishing again never posts twice.
+ */
+class APIAdminPolls {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** Every poll, drafts included, newest first, with full counts. */
+    async listAdminPolls({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/polls'),
+        });
+    }
+    /** Create a poll with 2 to 20 options. `maxChoices` cannot exceed the option count; `closesAt` must follow `opensAt`. */
+    async createPoll({ auth, poll }) {
+        return await this.web.request({
+            method: 'POST', auth,
+            endpoint: this.web.qp('/admin/polls'),
+            body: poll,
+        });
+    }
+    /**
+     * Edit a poll; send only what changes. `options` REPLACES the list: send an existing option's `optionId`
+     * to keep it (and its votes). Removing an option that has votes is
+     * `{ status: 409, error: { code: 'option_has_votes', optionIds } }` unless `force: true`, which deletes them.
+     */
+    async updatePoll({ auth, pollId, poll }) {
+        return await this.web.request({
+            method: 'PATCH', auth,
+            endpoint: this.web.qp('/admin/polls/' + pollId),
+            body: poll,
+        });
+    }
+    /** Delete a poll with its options and votes. */
+    async deletePoll({ auth, pollId }) {
+        return await this.web.request({
+            method: 'DELETE', auth,
+            endpoint: this.web.qp('/admin/polls/' + pollId),
+        });
+    }
+    /** Full counts, whatever the poll's `resultsVisibility`. */
+    async getPollResults({ auth, pollId }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/admin/polls/' + pollId + '/results'),
+        });
+    }
+}
+exports.APIAdminPolls = APIAdminPolls;

package/dist/classes/announcements.d.ts

@@ -0,0 +1,68 @@
+import { CancelOutWebResponses } from '../types';
+import { WebDataManager } from '../core/manager';
+/**
+ * Site announcements - developer-posted announcements the dashboard shows, in a feed and/or as a banner.
+ *
+ * `listAnnouncements` needs no session; the rest need a logged-in user (`auth`). Behind the
+ * `siteAnnouncements` launch flag: while it is hidden for the caller the lists are EMPTY (not 403) and a
+ * dismissal 404s.
+ *
+ * Only announcements showing NOW are returned: published, and inside their start/end window. One
+ * announcement can be in both `feed` and `banners`. Pinned first, then newest. `body` is markdown.
+ */
+export declare class APIAnnouncements {
+    private web;
+    constructor(web: WebDataManager);
+    /** What is showing now: `{ feed, banners }`. No session. */
+    listAnnouncements(): Promise<import("../types").WebResponse<SiteAnnouncementList>>;
+    /** The showing, dismissible announcements the logged-in user has dismissed - hide those banners. */
+    getAnnouncementDismissals({ auth }: AnnouncementsFunctionsInput['getAnnouncementDismissals']): Promise<import("../types").WebResponse<{
+        dismissedIds: string[];
+    }>>;
+    /**
+     * Dismiss a banner for the logged-in user (remembered across devices). Dismissing twice is fine.
+     * `{ status: 400, error: { code: 'not_dismissible' } }` when it cannot be dismissed; 30/minute.
+     */
+    createAnnouncementDismissal({ auth, announcementId }: AnnouncementsFunctionsInput['createAnnouncementDismissal']): Promise<import("../types").WebResponse<{
+        announcementId: string;
+        dismissed: true;
+    }>>;
+}
+export type AnnouncementsFunctionsInput = {
+    'getAnnouncementDismissals': {
+        auth: string;
+    };
+    'createAnnouncementDismissal': {
+        auth: string;
+        announcementId: string;
+    };
+};
+export type AnnouncementsGetReturnTypes = {
+    'listAnnouncementsRaw': Awaited<ReturnType<APIAnnouncements['listAnnouncements']>>;
+    'listAnnouncementsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAnnouncements['listAnnouncements']>>>;
+    'getAnnouncementDismissalsRaw': Awaited<ReturnType<APIAnnouncements['getAnnouncementDismissals']>>;
+    'getAnnouncementDismissalsSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAnnouncements['getAnnouncementDismissals']>>>;
+    'createAnnouncementDismissalRaw': Awaited<ReturnType<APIAnnouncements['createAnnouncementDismissal']>>;
+    'createAnnouncementDismissalSuccess': CancelOutWebResponses<Awaited<ReturnType<APIAnnouncements['createAnnouncementDismissal']>>>;
+};
+export type SiteAnnouncementSeverity = 'info' | 'success' | 'warning' | 'critical';
+/** One announcement as the site shows it. Mirrors `SiteAnnouncementCard` in Noti-v3. */
+export type SiteAnnouncement = {
+    announcementId: string;
+    title: string;
+    /** Markdown. */
+    body: string;
+    severity: SiteAnnouncementSeverity;
+    linkUrl: string | null;
+    linkLabel: string | null;
+    dismissible: boolean;
+    pinned: boolean;
+    /** ISO. */
+    startsAt: string | null;
+    /** ISO. */
+    endsAt: string | null;
+};
+export type SiteAnnouncementList = {
+    feed: SiteAnnouncement[];
+    banners: SiteAnnouncement[];
+};

package/dist/classes/announcements.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIAnnouncements = void 0;
+// Data.
+/**
+ * Site announcements - developer-posted announcements the dashboard shows, in a feed and/or as a banner.
+ *
+ * `listAnnouncements` needs no session; the rest need a logged-in user (`auth`). Behind the
+ * `siteAnnouncements` launch flag: while it is hidden for the caller the lists are EMPTY (not 403) and a
+ * dismissal 404s.
+ *
+ * Only announcements showing NOW are returned: published, and inside their start/end window. One
+ * announcement can be in both `feed` and `banners`. Pinned first, then newest. `body` is markdown.
+ */
+class APIAnnouncements {
+    web;
+    constructor(web) {
+        this.web = web;
+    }
+    /** What is showing now: `{ feed, banners }`. No session. */
+    async listAnnouncements() {
+        return await this.web.request({
+            method: 'GET',
+            endpoint: this.web.qp('/public/announcements'),
+        });
+    }
+    /** The showing, dismissible announcements the logged-in user has dismissed - hide those banners. */
+    async getAnnouncementDismissals({ auth }) {
+        return await this.web.request({
+            method: 'GET', auth,
+            endpoint: this.web.qp('/public/announcements/@me'),
+        });
+    }
+    /**
+     * Dismiss a banner for the logged-in user (remembered across devices). Dismissing twice is fine.
+     * `{ status: 400, error: { code: 'not_dismissible' } }` when it cannot be dismissed; 30/minute.
+     */
+    async createAnnouncementDismissal({ auth, announcementId }) {
+        return await this.web.request({
+            method: 'PUT', auth,
+            endpoint: this.web.qp('/public/announcements/' + announcementId + '/dismissals/@me'),
+        });
+    }
+}
+exports.APIAnnouncements = APIAnnouncements;