@unbound-app/api 0.9.0 → 0.11.0

package/src/commands.d.ts

@@ -0,0 +1,255 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+declare const _default: {
+	createCommands: typeof createCommands;
+	option: OptionBuilders;
+};
+declare const valueType: unique symbol;
+/** Option builders, one per kind: `option.string({ required: true })`, `option.user()`, `option.choice([...])`. */
+export declare const option: OptionBuilders;
+/**
+ * @description Creates the commands handle for one owner, like `createPatcher` does for patches. A plugin passes
+ * its manifest id, so its commands are removed when it stops; a built-in passes `'unbound'`.
+ * @param owner The plugin id, or `'unbound'` for a built-in.
+ * @param options The owner's own picker section; omitted, the shared Unbound section.
+ * @returns The handle.
+ */
+export declare function createCommands(owner: string, options?: CommandsOptions): CommandsHandle;
+/** Suggests values for an option while the user types. At most 25 are shown. */
+export type Autocomplete<V extends string | number> = (
+	query: string,
+	context: AutocompleteContext,
+) => Awaitable<readonly Choice<V>[]>;
+/** What autocomplete sees: where it runs and the raw values of the other options filled in so far. */
+export type AutocompleteContext = CommandContext & {
+	values: Readonly<Record<string, RawOptionValue>>;
+};
+/** A value, or a promise of one. */
+export type Awaitable<T> = T | Promise<T>;
+/** Settings every builder accepts. */
+export type BuilderInput<K extends OptionKind, R extends boolean> = OptionSettings<K> & {
+	description?: string;
+	required?: R;
+};
+/** Settings of `option.channel`. */
+export type ChannelOptionSettings = {
+	/** Discord channel types the picker offers. */
+	channelTypes?: readonly number[];
+};
+/** A choice or suggestion: a bare value, shown as itself, or a value with a label. */
+export type Choice<V extends string | number> = V | ChoiceWithLabel<V>;
+/** Settings `option.choice` accepts. */
+export type ChoiceInput<R extends boolean> = {
+	description?: string;
+	required?: R;
+};
+/** The kind a choice list maps to: strings are a string option, numbers an integer or number option. */
+export type ChoiceKind<V extends string | number> = V extends string
+	? 'string'
+	: 'integer' | 'number';
+/** A value with the label the picker shows for it. */
+export type ChoiceWithLabel<V extends string | number> = {
+	label: string;
+	value: V;
+};
+/** A Discord channel, as the channel store returns it. */
+export type CommandChannel = {
+	id: string;
+	type: number;
+	name?: string;
+	guild_id?: string | null;
+};
+/** Where a command runs. Discord never runs a command without a channel. */
+export type CommandContext = {
+	channel: CommandChannel;
+	guild: CommandGuild | undefined;
+};
+/** A command that only groups subcommands: `/root sub` or `/root group sub`. */
+export type CommandGroup<S> = {
+	description: string;
+	subcommands: CommandTree<S>;
+	options?: never;
+	execute?: never;
+};
+/** A Discord guild. */
+export type CommandGuild = {
+	id: string;
+	name: string;
+};
+/** A leaf or a group. */
+export type CommandNode<T> = LeafCommand<T> | CommandGroup<T>;
+/** A Discord guild role. */
+export type CommandRole = {
+	id: string;
+	name: string;
+	color?: number;
+};
+/**
+ * Commands keyed by name, at every level. TypeScript infers `T` per key by reversing this mapped type,
+ * from `options` on a leaf and from `subcommands` on a group. A conditional type here breaks inference.
+ */
+export type CommandTree<T> = {
+	[K in keyof T]: CommandNode<T[K]>;
+};
+/** A Discord user, as the user store returns it. Only the fields commands rely on. */
+export type CommandUser = {
+	id: string;
+	username: string;
+	globalName?: string | null;
+	bot?: boolean;
+};
+/** The handle `createCommands` returns, scoped to one owner. */
+export type CommandsHandle = {
+	/**
+	 * Adds commands. Registering a root name this owner already has replaces that whole command.
+	 * Returns a function that removes this call's commands; it is safe to call twice or after a sweep.
+	 */
+	register<T>(commands: CommandTree<T>): () => void;
+	/** Removes every command of this owner. */
+	unregisterAll(): void;
+};
+/** Options of `createCommands`. */
+export type CommandsOptions = {
+	/** The owner's own picker section. Omitted, commands go in the shared Unbound section. */
+	section?: SectionInput;
+};
+/** Shown only to the user, as a bot message. */
+export type EphemeralReply = {
+	ephemeral: true;
+	content?: string;
+	embeds?: readonly ReplyEmbed[];
+};
+/** An asset id from `assets.Icons`, or a `data:` or `https:` uri. */
+export type IconSource = number | string;
+/**
+ * A command that runs. `O` is inferred from `options` and types `execute`'s args.
+ * `execute` uses method syntax so its parameter stays bivariant and the registry can hold it erased.
+ */
+export type LeafCommand<O> = {
+	description: string;
+	options?: O;
+	execute(args: OptionArgs<O>, context: CommandContext): Awaitable<Reply>;
+	subcommands?: never;
+};
+export type NoSettings = Record<never, never>;
+/** Settings of `option.integer` and `option.number`. */
+export type NumberOptionSettings = {
+	minValue?: number;
+	maxValue?: number;
+	autocomplete?: Autocomplete<number>;
+};
+/** A handler's args, derived from its options: a required option is `V`, an optional one `V | undefined`. */
+export type OptionArgs<O> = {
+	[K in keyof O]: O[K] extends OptionSpec<OptionKind, infer R, infer V>
+		? R extends true
+			? V
+			: V | undefined
+		: never;
+};
+/** One kind's builder. */
+export type OptionBuilder<K extends OptionKind> = <const R extends boolean = false>(
+	settings?: BuilderInput<K, R>,
+) => OptionSpec<K, R>;
+/** The `option` builders: one per kind, plus `choice`. */
+export type OptionBuilders = {
+	[K in OptionKind]: OptionBuilder<K>;
+} & {
+	/**
+	 * Restricts an option to listed values; the handler gets their literal union.
+	 * @param choices Values, or `{ label, value }` pairs. 1 to 25, with unique labels.
+	 * @param settings The option's description and whether it is required.
+	 */
+	choice<const V extends string | number, const R extends boolean = false>(
+		choices: readonly Choice<V>[],
+		settings?: ChoiceInput<R>,
+	): OptionSpec<ChoiceKind<V>, R, V>;
+};
+/** The option kinds: one builder each on `option`. */
+export type OptionKind = keyof OptionKindTypes;
+/** Each option kind's handler value and builder settings. The client's kind table implements every key. */
+export type OptionKindTypes = {
+	string: {
+		value: string;
+		settings: StringOptionSettings;
+	};
+	integer: {
+		value: number;
+		settings: NumberOptionSettings;
+	};
+	number: {
+		value: number;
+		settings: NumberOptionSettings;
+	};
+	boolean: {
+		value: boolean;
+		settings: NoSettings;
+	};
+	user: {
+		value: CommandUser;
+		settings: NoSettings;
+	};
+	channel: {
+		value: CommandChannel;
+		settings: ChannelOptionSettings;
+	};
+	role: {
+		value: CommandRole;
+		settings: NoSettings;
+	};
+};
+/** The settings a kind's builder accepts beyond `description` and `required`. */
+export type OptionSettings<K extends OptionKind> = OptionKindTypes[K]['settings'];
+/** One declared option, made by an `option` builder. */
+export type OptionSpec<
+	K extends OptionKind = OptionKind,
+	R extends boolean = boolean,
+	V = OptionValue<K>,
+> = {
+	readonly kind: K;
+	readonly required: R;
+	readonly description: string | undefined;
+	readonly settings: OptionSettings<K>;
+	readonly choices: readonly Choice<string | number>[] | undefined;
+	readonly [valueType]?: V;
+};
+/** The value a handler receives for a kind. */
+export type OptionValue<K extends OptionKind> = OptionKindTypes[K]['value'];
+/** Sent by Discord as a normal message from the user. */
+export type PublicReply = {
+	content: string;
+	tts?: boolean;
+	ephemeral?: false;
+};
+/** An option value as Discord passes it. User, channel and role options arrive as id strings. */
+export type RawOptionValue = string | number | boolean;
+/** What `execute` returns. A string is shorthand for `{ content }`; nothing means the command did its own work. */
+export type Reply = string | PublicReply | EphemeralReply | undefined | void;
+/** An embed in an ephemeral reply. */
+export type ReplyEmbed = {
+	title?: string;
+	description?: string;
+	url?: string;
+	color?: number;
+	fields?: readonly ReplyEmbedField[];
+};
+/** A field of an embed in an ephemeral reply. */
+export type ReplyEmbedField = {
+	name: string;
+	value: string;
+	inline?: boolean;
+};
+/** A section of the `/` picker owned by one owner. */
+export type SectionInput = {
+	name: string;
+	icon?: IconSource;
+};
+/** Settings of `option.string`. */
+export type StringOptionSettings = {
+	minLength?: number;
+	maxLength?: number;
+	autocomplete?: Autocomplete<string>;
+};
+
+export { _default as default };
+
+export {};

package/src/dialogs.d.ts

@@ -0,0 +1,69 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import * as React$1 from 'react';
+import { ComponentType } from 'react';
+
+declare const _default: {
+	showDialog: typeof showDialog;
+	confirm: typeof confirm$1;
+	dismissAll: typeof dismissAll;
+	start: typeof start;
+	stop: typeof stop$1;
+};
+/**
+ * @description Asks a yes-or-no question with a confirm and a cancel button.
+ * @param options The question and the confirm button's label.
+ * @returns Whether the user confirmed; closing the dialog any other way counts as no.
+ */
+declare function confirm$1(options: ConfirmOptions): Promise<boolean>;
+/** Closes any dialog still open. */
+declare function stop$1(): void;
+/**
+ * @description Closes every dialog this API opened.
+ */
+export declare function dismissAll(): void;
+/**
+ * @description Opens a dialog with Discord's own alert: a title, an optional body and custom component,
+ * and action buttons, each of which closes the dialog before running its handler. On a Discord build
+ * without the alert it falls back to the system alert, which shows the title, body and buttons only.
+ * @param options The dialog's content and buttons.
+ * @returns The dialog's key and a function that closes it.
+ */
+export declare function showDialog(options: AlertDialogProps): DialogHandle;
+/** Starts the dialogs API; it keeps no state until a dialog opens. */
+export declare function start(): void;
+export type AlertDialogProps = {
+	title: string;
+	body?: string;
+	/** A component rendered below the body, given a way to close the dialog. */
+	content?: React$1.ComponentType<DialogContentProps>;
+	buttons?: DialogButton[];
+	/** Adds a cancel button last; a string sets its label. */
+	cancel?: boolean | string;
+	/** Runs when the cancel button closes the dialog. */
+	onCancel?: () => void;
+};
+export type ConfirmOptions = {
+	title: string;
+	body?: string;
+	confirmLabel: string;
+	cancelLabel?: string;
+	destructive?: boolean;
+};
+export type DialogButton = {
+	label: string;
+	variant?: DialogButtonVariant;
+	onPress?: () => void;
+};
+export type DialogButtonVariant = 'primary' | 'secondary' | 'destructive';
+export type DialogContentProps = {
+	dismiss: () => void;
+};
+export type DialogHandle = {
+	key: string;
+	dismiss: () => void;
+};
+
+export { _default as default, confirm$1 as confirm, stop$1 as stop };
+
+export {};

package/src/fs.d.ts

@@ -29,9 +29,9 @@ export declare function read(
 	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 Documents}.
+ * @param path The path to remove, relative to {@link Documents}.
+ * @returns A promise resolving to whether anything was removed.
  */
 export declare function rm(path: string): Promise<boolean>;
 /**
@@ -46,7 +46,6 @@ export declare function write(
 	content: string,
 	encoding?: DCDFileManagerEncoding,
 ): Promise<string>;
-/** The text encodings accepted by the native `DCDFileManager` read/write operations. */
 export type DCDFileManagerEncoding = 'utf-8' | 'utf8' | 'base64';
 
 export { _default as default };