@unbound-app/api 0.9.0 → 1.1.0

package/src/flux.d.ts

@@ -0,0 +1,317 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { LiteralUnion } from './_types';
+import * as React$1 from 'react';
+import { DependencyList } from 'react';
+
+/**
+ * @description Sends a Flux action through Discord's dispatcher.
+ * @template A The action, whose payload is checked against {@link FluxActions} for a known type.
+ * @param action The action, with its `type` and payload.
+ * @returns A promise that settles once Discord's stores handled the action.
+ */
+export declare function dispatch<A extends FluxAction>(
+	action: A & FluxActionOf<A['type']>,
+): Promise<void>;
+/**
+ * @description Finds one of Discord's Flux stores by name. A store already loaded and cached is returned as itself; otherwise the
+ * search is lazy unless `{ lazy: false }` is passed, and runs on first access.
+ * @template K The store name, typed from {@link FluxStores}.
+ * @param name The store name without its `Store` suffix, like `'User'`.
+ * @param options Whether to search lazily, and whether to append `Store` to the name.
+ * @returns The store, typed from {@link FluxStores}, else as a base {@link FluxStore}.
+ */
+export declare function getStore<K extends FluxStoreName>(
+	name: K,
+	options?: GetStoreOptions,
+): FluxStoreOf<K>;
+/**
+ * @description Runs an interceptor before Discord handles each Flux action of one type. It may change the action, or drop it by returning `true`.
+ * @template K The action type, typed from {@link FluxActions}.
+ * @param type The action type, like `'MESSAGE_CREATE'`.
+ * @param interceptor Runs with each action. An error it throws is logged and the action goes on.
+ * @returns A function that removes the interceptor.
+ */
+export declare function interceptAction<K extends FluxActionType>(
+	type: K,
+	interceptor: FluxActionInterceptor<K>,
+): () => void;
+/**
+ * @description Runs a listener for each Flux action of one type, after Discord's stores handle it.
+ * @template K The action type, typed from {@link FluxActions}.
+ * @param type The action type, like `'MESSAGE_CREATE'`.
+ * @param listener Runs with each action. An error it throws is logged.
+ * @returns A function that removes the listener.
+ */
+export declare function onAction<K extends FluxActionType>(
+	type: K,
+	listener: FluxActionListener<K>,
+): () => void;
+/**
+ * @description Runs a listener each time a Flux store changes.
+ * @param store The store to watch.
+ * @param listener Runs after each change.
+ * @returns A function that removes the listener.
+ */
+export declare function onStoreChange(store: FluxStore, listener: FluxChangeListener): () => void;
+/**
+ * @description Selects state from Flux stores in a component, re-rendering only when the selection changes.
+ * @template S The store, or tuple of stores.
+ * @template T The value the selector returns.
+ * @param stores The store, or stores, the selector reads.
+ * @param selector Reads the value from the stores, which it receives as passed.
+ * @param options The selector's `deps`, and the `isEqual` that compares two selections.
+ * @returns The selector's latest value.
+ */
+export declare function useStore<const S extends FluxStore | readonly FluxStore[], T>(
+	stores: S,
+	selector: (stores: S) => T,
+	{ deps, isEqual }?: UseStoreOptions<T>,
+): T;
+/**
+ * The payload of each Flux action, keyed by action type. Add your own with
+ * `declare module '@unbound-app/api/flux' { interface FluxActions { MY_ACTION: { id: string } } }`.
+ */
+export interface FluxActions {
+	/** A message arrived or was sent; `optimistic` is `true` for the local copy before Discord confirms it. */
+	MESSAGE_CREATE: {
+		channelId: string;
+		guildId?: string;
+		message: FluxMessage;
+		optimistic: boolean;
+	};
+	/** A message was edited, or Discord filled in its embeds. */
+	MESSAGE_UPDATE: {
+		guildId?: string;
+		message: FluxMessage;
+	};
+	/** The message `id` in `channelId` was deleted. */
+	MESSAGE_DELETE: {
+		id: string;
+		channelId: string;
+		guildId?: string;
+	};
+	/** The user opened a channel; `messageId` is set when they jumped to a message. */
+	CHANNEL_SELECT: {
+		channelId?: string;
+		guildId?: string;
+		messageId?: string;
+	};
+	/** A user started typing in a channel. */
+	TYPING_START: {
+		channelId: string;
+		userId: string;
+	};
+	/** A user stopped typing in a channel. */
+	TYPING_STOP: {
+		channelId: string;
+		userId: string;
+	};
+	/** The gateway connection is ready; `user` is the signed-in user. */
+	CONNECTION_OPEN: {
+		user: FluxUser;
+	};
+}
+/**
+ * The Flux stores `flux.getStore` knows, keyed by name without the `Store` suffix. Add your own with
+ * `declare module '@unbound-app/api/flux' { interface FluxStores { Message: MessageStore } }`.
+ */
+export interface FluxStores {
+	/** Users Discord has loaded, including the signed-in user. */
+	User: UserStore;
+	/** Guilds the signed-in user is in. */
+	Guild: GuildStore;
+	/** Members of each guild, as far as Discord has loaded them. */
+	GuildMember: GuildMemberStore;
+	/** Channels Discord has loaded, guild channels and DMs alike. */
+	Channel: ChannelStore;
+	/** Which channel is open, per guild. */
+	SelectedChannel: SelectedChannelStore;
+	/** Who is typing in each channel. */
+	Typing: TypingStore;
+	/** Friends, blocks and friend nicknames of the signed-in user. */
+	Relationship: RelationshipStore;
+	/** Profiles of users whose profile has been opened. */
+	UserProfile: UserProfileStore;
+	/** The state of the open server settings screen. */
+	GuildSettings: GuildSettingsStore;
+}
+/** Discord's `ChannelStore`. */
+export type ChannelStore = FluxStore & {
+	getChannel(id: string): FluxChannel | undefined;
+	hasChannel(id: string): boolean;
+	getDMFromUserId(userId: string): string | undefined;
+};
+/** The base shape of every Flux action. */
+export type FluxAction<T extends string = string> = {
+	/** The action type, such as `MESSAGE_CREATE`; it picks the payload from {@link FluxActions}. */
+	type: T;
+};
+/** Runs before Discord handles an action of one type. Returning `true` drops the action. */
+export type FluxActionInterceptor<K extends string> = (action: FluxActionOf<K>) => boolean | void;
+/** Runs for each dispatched action of one type. */
+export type FluxActionListener<K extends string> = (action: FluxActionOf<K>) => void;
+/** The action Discord dispatches for type `K`: its {@link FluxActions} payload, else {@link FluxAction}. */
+export type FluxActionOf<K extends string> = K extends keyof FluxActions
+	? FluxAction<K> & FluxActions[K]
+	: FluxAction<K>;
+/** An action type: one of {@link FluxActions}, or any other string. */
+export type FluxActionType = LiteralUnion<Extract<keyof FluxActions, string>>;
+/** Runs after a Flux store's state changed. */
+export type FluxChangeListener = () => void;
+/** A Discord channel record. */
+export type FluxChannel = {
+	/** The channel's Discord snowflake id. */
+	id: string;
+	/** Discord's numeric channel type, such as `0` for a guild text channel or `1` for a DM. */
+	type: number;
+	/** The channel name; DMs may have an empty one. */
+	name: string;
+	/** The id of the guild the channel belongs to; `null` for DMs and group DMs. */
+	guild_id: string | null;
+	/** The slowmode delay in seconds; `0` when the channel has no slowmode. */
+	rateLimitPerUser?: number;
+};
+/** A Discord guild record. */
+export type FluxGuild = {
+	/** The guild's Discord snowflake id. */
+	id: string;
+	/** The guild's display name. */
+	name: string;
+	/** The guild icon's image hash; `null` when the guild has no icon. */
+	icon: string | null;
+	/** The id of the user who owns the guild. */
+	ownerId: string;
+};
+/** A guild member record. */
+export type FluxGuildMember = {
+	/** The id of the member's user. */
+	userId: string;
+	/** The id of the guild this membership is in. */
+	guildId: string;
+	/** The member's nickname in this guild; `null` when they have none. */
+	nick: string | null;
+	/** The ids of the member's roles in this guild. */
+	roles: string[];
+	/** The member's name colour as a hex string from their roles; `null` when no role gives one. */
+	colorString: string | null;
+};
+/** A Discord message record. */
+export type FluxMessage = {
+	/** The message's Discord snowflake id. */
+	id: string;
+	/** The id of the channel the message is in. */
+	channel_id: string;
+	/** The raw Markdown text of the message; empty for a message with only attachments or embeds. */
+	content: string;
+	/** The user who sent the message. */
+	author: FluxUser;
+};
+/** The members every Flux store has. A store name missing from {@link FluxStores} gets this type. */
+export type FluxStore = {
+	/** Returns the store's name, such as `UserStore`. */
+	getName(): string;
+	/** Calls `listener` after every change to the store's state, until it is removed. */
+	addChangeListener(listener: FluxChangeListener): void;
+	/** Stops calling a listener added with `addChangeListener`. */
+	removeChangeListener(listener: FluxChangeListener): void;
+	/** Calls every change listener now. Discord calls it after the store handles an action. */
+	emitChange(): void;
+};
+/** A store name: one of {@link FluxStores}, or any other string. */
+export type FluxStoreName = LiteralUnion<Extract<keyof FluxStores, string>>;
+/** The store type `flux.getStore(name)` returns: its {@link FluxStores} entry, else {@link FluxStore}. */
+export type FluxStoreOf<K extends string> = K extends keyof FluxStores ? FluxStores[K] : FluxStore;
+/** A Discord user record. */
+export type FluxUser = {
+	/** The user's Discord snowflake id. */
+	id: string;
+	/** The unique account name, without the `@`. */
+	username: string;
+	/** The display name the user set; `null` when they set none. */
+	globalName: string | null;
+	/** The legacy four-digit tag; `'0'` for accounts on unique usernames. */
+	discriminator: string;
+	/** The avatar image hash; `null` when the user has the default avatar. */
+	avatar: string | null;
+	/** `true` for bot accounts. */
+	bot: boolean;
+	/** The user's Nitro tier: `1` Nitro Classic, `2` Nitro, `3` Nitro Basic; `null` or `0` without Nitro. */
+	premiumType?: number | null;
+};
+/** A user's profile, loaded when their profile is opened. */
+export type FluxUserProfile = {
+	/** The id of the user the profile belongs to. */
+	userId: string;
+	/** The profile's About Me text, as Markdown. */
+	bio: string;
+	/** The pronouns the user set, as free text. */
+	pronouns: string;
+};
+/** Options for `flux.getStore`. */
+export type GetStoreOptions = {
+	/** Search on first property access instead of at once. Defaults to `true`. */
+	lazy?: boolean;
+	/** Append `Store` to the name before matching. Defaults to `true`. */
+	short?: boolean;
+};
+/** Discord's `GuildMemberStore`. */
+export type GuildMemberStore = FluxStore & {
+	getMember(guildId: string, userId: string): FluxGuildMember | null;
+	getMembers(guildId: string): FluxGuildMember[];
+	getNick(guildId: string, userId: string): string | null;
+	isMember(guildId: string, userId: string): boolean;
+};
+/** Discord's `GuildSettingsStore`, the state of the open server settings screen. */
+export type GuildSettingsStore = FluxStore & {
+	getGuildId(): string | undefined;
+	isOpen(): boolean;
+	hasChanges(): boolean;
+};
+/** Discord's `GuildStore`. */
+export type GuildStore = FluxStore & {
+	getGuild(id: string): FluxGuild | undefined;
+	getGuilds(): Record<string, FluxGuild>;
+	getGuildCount(): number;
+};
+/** Discord's `RelationshipStore`. */
+export type RelationshipStore = FluxStore & {
+	isFriend(userId: string): boolean;
+	isBlocked(userId: string): boolean;
+	isIgnored(userId: string): boolean;
+	getNickname(userId: string): string | undefined;
+	getRelationshipType(userId: string): number;
+	getFriendIDs(): string[];
+};
+/** Discord's `SelectedChannelStore`. */
+export type SelectedChannelStore = FluxStore & {
+	getChannelId(guildId?: string): string | undefined;
+	getLastSelectedChannelId(guildId?: string): string | undefined;
+	getVoiceChannelId(): string | null;
+};
+/** Discord's `TypingStore`. */
+export type TypingStore = FluxStore & {
+	/** Maps the id of each user typing in the channel to when they started. */
+	getTypingUsers(channelId: string): Record<string, number>;
+	isTyping(channelId: string, userId: string): boolean;
+};
+/** Options for {@link useStore}. */
+export type UseStoreOptions<T> = {
+	/** Values the selector closes over. While they stay the same, a render reuses the last value instead of re-running the selector. */
+	deps?: React$1.DependencyList;
+	/** Decides whether a new selection equals the last one, which skips the re-render. Defaults to `Object.is`. */
+	isEqual?: (previous: T, next: T) => boolean;
+};
+/** Discord's `UserProfileStore`. */
+export type UserProfileStore = FluxStore & {
+	getUserProfile(userId: string): FluxUserProfile | undefined;
+	getGuildMemberProfile(userId: string, guildId: string): FluxUserProfile | undefined;
+};
+/** Discord's `UserStore`. */
+export type UserStore = FluxStore & {
+	getCurrentUser(): FluxUser | undefined;
+	getUser(id: string): FluxUser | undefined;
+	getUsers(): Record<string, FluxUser>;
+};
+
+export {};

package/src/fonts.d.ts

@@ -0,0 +1,51 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { UnboundInstalledFont } from './_internal';
+/** Applies a saved preset, downloading the faces it lacks. */
+export declare const applyPreset: (id: string) => Promise<UnboundFontPresetResult | undefined>;
+/** Gives a Discord family, or a group, back its own font. */
+export declare const clearOverride: (key: string) => Promise<void>;
+/** Reads one installed face by id. */
+export declare const get: (id: PropertyKey) => UnboundInstalledFont | undefined;
+/** Lists every installed font face. */
+export declare const getAll: () => UnboundInstalledFont[];
+/** Lists the saved font presets. */
+export declare const getPresets: () => UnboundFontPreset[];
+/** Installs a font by family name or link, optionally only some weights and styles. */
+export declare const install: (
+	input: string,
+	variants?: UnboundFontVariant[],
+) => Promise<UnboundFontInstallResult | undefined>;
+/** Points a Discord family, or a group such as `PRIMARY`, at an installed face. */
+export declare const setOverride: (key: string, fontId: string) => Promise<void>;
+/** Removes an installed face by id. */
+export declare const uninstall: (id: string) => Promise<void>;
+/** What `fonts.install` installed, and the files it skipped and why. @internal */
+type UnboundFontInstallResult = {
+	installed: UnboundInstalledFont[];
+	errors: string[];
+};
+/**
+ * A saved snapshot of the override map, keyed by Discord family and holding sources, not files.
+ * @internal
+ */
+type UnboundFontPreset = {
+	id: string;
+	name: string;
+	overrides: Record<string, UnboundFontSource>;
+};
+/** What `fonts.applyPreset` did with each Discord family of the preset. @internal */
+type UnboundFontPresetResult = {
+	applied: string[];
+	/** Families whose face failed to install; they keep Discord's font. */
+	unavailable: string[];
+	/** Families Discord no longer has. */
+	skipped: string[];
+	errors: string[];
+};
+/** A weight and style to install. @internal */
+type UnboundFontVariant = {
+	weight: number;
+	style: UnboundFontStyle;
+};
+export {};

package/src/fs.d.ts

@@ -1,54 +1,44 @@
 // Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
 
-declare const _default: {
-	Documents: string;
-	read: typeof read;
-	write: typeof write;
-	rm: typeof rm;
-	exists: typeof exists;
-};
 /** Absolute path to the platform's documents directory. */
-export declare const Documents: string;
+export declare const documentsPath: string;
 /**
- * @description Checks whether a file exists, resolving relative paths against {@link Documents}.
- * @param path The file path to check, relative to {@link Documents} unless `inDocuments` is `false`.
- * @param inDocuments Whether to resolve `path` relative to {@link Documents}.
+ * @description Checks whether a file exists, resolving relative paths against {@link documentsPath}.
+ * @param path The file path to check, relative to {@link documentsPath} unless `inDocuments` is `false`.
+ * @param inDocuments Whether to resolve `path` relative to {@link documentsPath}.
  * @returns A promise resolving to whether the file exists.
  */
 export declare function exists(path: string, inDocuments?: boolean): Promise<boolean>;
 /**
- * @description Reads a file's contents, resolving relative paths against {@link Documents}.
- * @param path The file path to read, relative to {@link Documents} unless `inDocuments` is `false`.
+ * @description Reads a file's contents, resolving relative paths against {@link documentsPath}.
+ * @param path The file path to read, relative to {@link documentsPath} unless `inDocuments` is `false`.
  * @param encoding The encoding to read the file with.
- * @param inDocuments Whether to resolve `path` relative to {@link Documents}.
+ * @param inDocuments Whether to resolve `path` relative to {@link documentsPath}.
  * @returns A promise resolving to the file's contents.
  */
-export declare function read(
+export declare function readFile(
 	path: string,
 	encoding?: DCDFileManagerEncoding,
 	inDocuments?: boolean,
 ): Promise<string>;
 /**
- * @description Removes a file within {@link Documents}.
- * @param path The file path to remove, relative to {@link Documents}.
- * @returns A promise resolving to whether the file was removed.
+ * @description Removes a file or a whole folder within {@link documentsPath}.
+ * @param path The path to remove, relative to {@link documentsPath}.
+ * @returns A promise resolving to whether anything was removed.
  */
-export declare function rm(path: string): Promise<boolean>;
+export declare function removeFile(path: string): Promise<boolean>;
 /**
- * @description Writes content to a file within {@link Documents}.
- * @param path The file path to write to, relative to {@link Documents}.
+ * @description Writes content to a file within {@link documentsPath}.
+ * @param path The file path to write to, relative to {@link documentsPath}.
  * @param content The content to write.
  * @param encoding The encoding to write the file with.
  * @returns A promise resolving once the file is written.
  */
-export declare function write(
+export declare function writeFile(
 	path: string,
 	content: string,
 	encoding?: DCDFileManagerEncoding,
 ): Promise<string>;
-/** The text encodings accepted by the native `DCDFileManager` read/write operations. */
+/** How the native file manager encodes file contents: UTF-8 text or base64 for binary data. */
 export type DCDFileManagerEncoding = 'utf-8' | 'utf8' | 'base64';
-
-export { _default as default };
-
 export {};