@unbound-app/api 0.9.0 → 1.1.0

package/src/shims.d.ts

@@ -0,0 +1,5 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+/** Discord's copy of each library its bundle ships, by package name. A built plugin reads its library imports here. */
+export declare const libraries: Record<string, any>;
+export {};

package/src/storage.d.ts

@@ -1,253 +1,110 @@
 // Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
 
-import type { PredicateResult, Widen } from './utils';
-import type { SettingsValue } from './_internal';
-declare class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
-	events: EventCollections<EventMap>;
-	onceEvents: OnceCollections<EventMap>;
-	_symbolKeys: Set<symbol>;
-	maxListeners: number;
-	boundFuncs: undefined | Map<Listener, Listener>;
-	emit: <EventKey extends keyof EventMap>(
-		event: EventKey,
-		...args: Parameters<EventMap[EventKey]>
-	) => boolean;
-	on: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	once: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	addListener: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-		argsNum?: ArgsNum<EventMap[EventKey]>,
-	) => this;
-	removeListener: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	hasListeners: <EventKey extends keyof EventMap = string>(event: EventKey) => boolean;
-	prependListener: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	prependOnceListener: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	off: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	removeAllListeners: <EventKey extends keyof EventMap = string>(event?: EventKey) => this;
-	setMaxListeners: (n: number) => this;
-	getMaxListeners: () => number;
-	listeners: <EventKey extends keyof EventMap = string>(event: EventKey) => EventMap[EventKey][];
-	rawListeners: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-	) => EventMap[EventKey][];
-	eventNames: () => Array<string | symbol>;
-	listenerCount: <EventKey extends keyof EventMap = string>(type: EventKey) => number;
-	addListenerBound: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-		bindTo?: unknown,
-		argsNum?: ArgsNum<EventMap[EventKey]>,
-	) => this;
-	removeListenerBound: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => this;
-	/**
-	 * @description Creates an emitter with no listeners.
-	 */
-	constructor();
-	get _eventsCount(): number;
-}
-declare class TaskCollection<Func extends Listener = Listener> {
-	argsNum: number;
-	_tasks: Tasks<Func>;
-	length: number;
-	call: (...args: Parameters<Func>) => void;
-	/**
-	 * @description Creates a collection holding a single listener.
-	 * @param argsNum How many arguments each listener receives when more than one is registered.
-	 * @param task The first listener.
-	 */
-	constructor(argsNum: number, task: Func);
-	push(task: Func): void;
-	insert(index: number, task: Func): void;
-	removeLast(task: Func): void;
-	growArgsNum(argsNum: number): void;
-	rebuild(): void;
-	tasksAsArray(): Func[];
-}
-declare const _default: {
-	addListener: typeof addListener;
-	get: typeof get;
-	getStore: typeof getStore;
-	off: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => EventEmitter<EventMap>;
-	on: <EventKey extends keyof EventMap = string>(
-		event: EventKey,
-		listener: EventMap[EventKey],
-	) => EventEmitter<EventMap>;
-	persist: typeof persist;
-	remove: typeof remove;
-	removeListener: typeof removeListener;
-	set: typeof set;
-	useSettingsStore: typeof useSettingsStore;
-};
-export declare const off: <EventKey extends keyof EventMap = string>(
-	event: EventKey,
-	listener: EventMap[EventKey],
-) => EventEmitter<EventMap>;
-export declare const on: <EventKey extends keyof EventMap = string>(
-	event: EventKey,
-	listener: EventMap[EventKey],
-) => EventEmitter<EventMap>;
+export type { SettingsSchema } from './_internal';
+import type { PredicateResult, Widen } from './_types';
+import type { SettingValue, SettingsObject, SettingsSchema, SettingsValue } from './_internal';
+/**
+ * @description Binds a settings schema to a Bucket: reads apply defaults and writes are validated against the schema.
+ * Plugins reach it through `@unbound-app/settings`, which the build generates from their settings.ts.
+ * @param schema The settings schema.
+ * @param name The Bucket name. A plugin may omit it to use its own Bucket.
+ * @returns The settings, their hook and their reset.
+ * @throws When `name` is omitted outside a plugin.
+ */
+export declare function define(schema: SettingsSchema, name?: string): DefinedSettings;
+/**
+ * @description Returns the Bucket with the given name. The name is the key the Bucket is saved under on disk.
+ * @param name The Bucket name. A plugin may omit it to get its own Bucket, named after its id.
+ * @returns The Bucket, with every operation bound to `name`.
+ * @throws When `name` is omitted outside a plugin.
+ */
+export declare function getBucket(name?: string): Bucket;
 /**
  * @description Registers a callback invoked on every settings change matching the predicate.
- * @param predicate Decides whether a given change should fire the callback.
+ * @param predicate Decides whether a given change should fire the callback. The payload names the Bucket in `store`.
  * @param callback Invoked with the payload of each matching change.
  * @returns A function that removes the listener.
  */
-export declare function addListener(
-	predicate: (payload: SettingsPayload) => PredicateResult,
+export declare function onChange(
+	predicate: SettingsPredicate,
 	callback: (payload: SettingsPayload) => void,
 ): () => void;
 /**
- * @description Removes an entire store and all of its keys, and emits `changed` and `cleared`.
- * @param store The store to clear.
- */
-export declare function clear(store: string): void;
-/**
- * @description Reads a value from a store by dot-separated key path, falling back to a default when absent.
- * @template T The type of the default value.
- * @param store The store to read from.
- * @param key The dot-separated key path within the store.
- * @param def The value to return when the key is not set.
- * @returns The stored value, or `def` if the key path is not present.
- */
-export declare function get<T>(store: string, key: string, def: T): Widen<T>;
-/**
- * @description Builds a store-scoped facade binding every settings operation to a single store name.
- * @param store The store name to scope every operation to.
- * @returns An object exposing `get`, `set`, `toggle`, `remove`, `clear`, `useSettingsStore`, and `addListener` bound to the store.
- */
-export declare function getStore(store: string): {
-	set: (key: string, value: SettingsValue) => void;
-	get: <T>(key: string, def: T) => Widen<T>;
-	toggle: (key: string, def: boolean) => void;
-	remove: (key: string) => void;
-	clear: () => void;
-	useSettingsStore: (predicate?: (payload: SettingsPayload) => PredicateResult) => {
-		set: (key: string, value: SettingsValue) => void;
-		get: <T>(key: string, def: T) => Widen<T>;
-		toggle: (key: string, def: boolean) => void;
-		remove: (key: string) => void;
-	};
-	addListener: (
-		predicate: (payload: SettingsPayload) => PredicateResult,
-		callback: (payload: SettingsPayload) => void,
-	) => () => EventEmitter<EventMap>;
-};
-/**
- * @description Serialises the current settings and writes them to disk.
- * @returns A promise that resolves once the settings file has been written.
+ * @description Saves the settings changed since the last call. Each change already reached the loader when it was made.
+ * @returns A promise that resolves once the loader has saved them.
  */
 export declare function persist(): Promise<void>;
 /**
- * @description Deletes a top-level key from a store, dropping the store entirely if it becomes empty, and emits `changed` and `removed`.
- * @param store The store to remove the key from.
- * @param key The key to delete.
- */
-export declare function remove(store: string, key: string): void;
-/**
- * @description Removes a previously registered settings change listener.
- * @param callback The listener to remove.
+ * @description Reads every Bucket at once. Most callers should read single keys, which stay in native code.
+ * @param options Set `includeSecrets` to read `displayAs: 'secret'` settings as they are; otherwise they are masked.
+ * @returns Every Bucket by name.
  */
-export declare function removeListener(callback: (payload: SettingsPayload) => void): void;
+export declare function snapshot({ includeSecrets }?: { includeSecrets?: boolean }): SettingsStores;
 /**
- * @description Writes a value into a store at a dot-separated key path, creating intermediate objects, and emits `changed` and `set`.
- * @param store The store to write to.
- * @param key The dot-separated key path within the store.
- * @param value The value to store.
+ * @description React hook that re-renders the component whenever a matching change occurs in the Bucket.
+ * @param name The Bucket to subscribe to.
+ * @param predicate Optional filter deciding which changes trigger a re-render.
+ * @returns The Bucket, with every operation bound to `name`.
  */
-export declare function set(store: string, key: string, value: SettingsValue): void;
+export declare function useBucket(name: string, predicate?: SettingsPredicate): Bucket;
 /**
- * @description Flips a boolean value at a key path against its current (or default) value, and emits `toggled`.
- * @param store The store to write to.
- * @param key The dot-separated key path within the store.
- * @param def The value to assume when the key is not yet set.
+ * @description React hook that selects from a Bucket, re-rendering only when the selection changes.
+ * @template T The value the selector returns.
+ * @param name The Bucket to read.
+ * @param selector Reads the value from the Bucket.
+ * @param isEqual Decides whether a new selection equals the last one, which skips the re-render. Defaults to `Object.is`.
+ * @returns The selector's latest value.
  */
-export declare function toggle(store: string, key: string, def: boolean): void;
-/**
- * @description React hook that re-renders the component whenever a matching change occurs in the store.
- * @param store The store to subscribe to.
- * @param predicate Optional filter deciding which changes trigger a re-render.
- * @returns An object exposing `get`, `set`, `toggle`, and `remove` bound to the store.
- */
-export declare function useSettingsStore(
-	store: string,
-	predicate?: (payload: SettingsPayload) => PredicateResult,
-): {
-	set: (key: string, value: SettingsValue) => void;
+export declare function useSetting<T>(
+	name: string,
+	selector: (bucket: Bucket) => T,
+	isEqual?: (previous: T, next: T) => boolean,
+): T;
+/** A Bucket: a named, persisted group of settings. Keys are dot-separated paths. */
+export type Bucket = {
+	/** Reads a value, falling back to `def` when the key is not set. */
 	get: <T>(key: string, def: T) => Widen<T>;
+	/** Writes a value, creating intermediate objects. */
+	set: (key: string, value: SettingsValue) => void;
+	/** Flips a boolean against its current value, or `def` when the key is not set. */
 	toggle: (key: string, def: boolean) => void;
+	/** Deletes a value and prunes the objects it leaves empty. */
 	remove: (key: string) => void;
+	/** Deletes every setting in the Bucket. */
+	clear: () => void;
 };
-/** The declared parameter count of a listener. */
-export type ArgsNum<T extends Listener> = Parameters<T>['length'];
-export type ClearedPayload = {
-	store: string;
-};
-/** The event map of an untyped emitter. `__proto__` is reserved, as in tseep. */
-export type DefaultEventMap = Record<string | symbol, Listener> & {
-	__proto__?: never;
-};
-export type EventCollections<EventMap extends DefaultEventMap> = {
-	[eventName in keyof EventMap]?: TaskCollection<EventMap[eventName]>;
-};
-export type EventMap = {
-	set: (payload: SetPayload) => void;
-	changed: (payload: SettingsPayload) => void;
-	cleared: (payload: ClearedPayload) => void;
-	removed: (payload: RemovedPayload) => void;
-	toggled: (payload: ToggledPayload) => void;
-};
-/** Any event listener. tseep's `any[]` parameters become `never[]`, which accepts every listener. */
-export type Listener = (...args: never[]) => Promise<unknown> | void;
-export type OnceCollections<EventMap extends DefaultEventMap> = {
-	[eventName in keyof EventMap]?: EventMap[eventName][] | EventMap[eventName];
-};
-export type RemovedPayload = {
-	store: string;
-	key: string;
-};
-export type SetPayload = {
-	store: string;
-	key: string;
-	value: SettingsValue;
+/** What `storage.define` returns: a schema's settings, bound to one Bucket. */
+export type DefinedSettings = {
+	/** The schema the settings were defined with. */
+	schema: SettingsSchema;
+	/** The settings as an object; assign a property, a section's too, to save it. */
+	values: SettingsValues;
+	/** Reads a setting by its dot-separated key; a stored value the schema rejects is logged, removed and read as the default. */
+	get: (key: string) => SettingValue;
+	/** Saves a setting by its dot-separated key; throws when the schema rejects the value. */
+	set: (key: string, value: SettingValue) => void;
+	/** Puts every setting back to its default, leaving other keys of the Bucket alone. */
+	reset: () => void;
+	/** React hook that reads a setting, or a section as an object, and re-renders when it changes. */
+	useSetting: (key: string) => SettingValue | SettingsValues;
+	/** React hook that re-renders on any change to the settings while `enabled`, and returns a number that changes with them. */
+	useVersion: (enabled?: boolean) => number;
 };
-/** Payload describing a settings change, passed to `changed` listeners and predicates. */
+/** Payload describing a settings change, passed to `onChange` listeners and predicates. */
 export type SettingsPayload = {
+	/** The name of the Bucket that changed. */
 	store: string;
+	/** The dot-separated key that changed, or `null` when the whole Bucket was cleared. */
 	key: string | null;
+	/** The new value, or `undefined` when the key was removed or the Bucket cleared. */
 	value: SettingsValue | undefined;
 };
-export type Tasks<Func> = Func[] | Func | null;
-export type ToggledPayload = {
-	store: string;
-	key: string;
-	prev: boolean;
-	value: boolean;
+/** Decides whether a settings change should reach a listener. */
+export type SettingsPredicate = (payload: SettingsPayload) => PredicateResult;
+/** Every Bucket's settings, keyed by Bucket name, as the loader persists them. */
+export type SettingsStores = Record<string, SettingsObject>;
+/** A plugin's settings as an object: reads apply defaults, writes are validated and saved. Sections are nested objects. */
+export type SettingsValues = {
+	[key: string]: SettingValue | SettingsValues;
 };
-export { _default as default };
-
 export {};

package/src/sync.d.ts

@@ -0,0 +1,51 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+/** The settings store Sync keeps its mode and last agreed document in. Never synced. */
+export declare const SYNC_STORE = 'unbound::sync';
+/**
+ * @description Deletes the stored document and turns syncing off on this device, so it is not
+ * uploaded again. Other devices keep what they have installed.
+ * @returns Whether the document was deleted. Failures are recorded as `lastError`.
+ */
+export declare function deleteData(): Promise<boolean>;
+/** @returns Which way automatic syncs move changes on this device. */
+export declare function getMode(): SyncMode;
+/**
+ * @returns Whether a sync is applying remote changes right now, so the changes it makes can be told apart.
+ */
+export declare function isApplying(): boolean;
+/** @returns Whether this device syncs automatically. */
+export declare function isEnabled(): boolean;
+/**
+ * @description Syncs now: reads the stored document, merges, applies remote changes here and saves
+ * the result. A call while a sync runs queues one more run after it, in this device's mode.
+ * @param strategy How to reconcile the two sides; this device's mode by default.
+ * @returns Whether the sync succeeded. Failures are recorded as `lastError` in {@link SYNC_STORE}.
+ */
+export declare function now(strategy?: SyncStrategy): Promise<boolean>;
+/**
+ * @description Settles how this device and an existing cloud setup combine on the first sync after
+ * signing in, then turns automatic syncing on.
+ * @param strategy `merge` keeps both, `pull` replaces this device's setup, `push` replaces the cloud's.
+ * @returns Whether the sync succeeded.
+ */
+export declare function resolveFirstSync(strategy: SyncStrategy): Promise<boolean>;
+/**
+ * @description Turns automatic syncing on or off, syncing right away when turned on.
+ * @param enabled Whether to sync automatically.
+ */
+export declare function setEnabled(enabled: boolean): void;
+/**
+ * @description Sets which way automatic syncs move changes, syncing right away when sync is on.
+ * @param mode The new mode.
+ */
+export declare function setMode(mode: SyncMode): void;
+/** Which way automatic syncs move changes on this device. */
+export type SyncMode = 'two-way' | 'download' | 'upload';
+/**
+ * How one sync reconciles the two sides: `merge` keeps changes from both, `pull` makes this device
+ * match the cloud, and `push` makes the cloud match this device.
+ */
+export type SyncStrategy = 'merge' | 'pull' | 'push';
+
+export {};

package/src/themes.d.ts

@@ -0,0 +1,43 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { AddonHandle, PushedManifest } from './_internal';
+/** Disables a theme and removes it from the app. */
+export declare const disable: (id: string) => void;
+/** Enables a theme and applies it. */
+export declare const enable: (id: string) => void | Promise<void>;
+/** Reads one installed theme by id. */
+export declare const get: (id: string) => AddonHandle | undefined;
+/** Lists every installed theme. */
+export declare const getAll: () => AddonHandle[];
+/** Installs a theme from its manifest URL. */
+export declare const install: (url: string, digest?: string) => Promise<AddonHandle | undefined>;
+/** Reports whether a theme is enabled. */
+export declare const isEnabled: (id: string) => boolean;
+/** Swaps a theme's files in place, keeping its enabled state. */
+export declare const reload: (
+	id: string,
+	bundle: string,
+	manifest: PushedManifest,
+	bytecode?: string,
+) => Promise<ReloadResult>;
+/** Enables a disabled theme, or disables an enabled one. */
+export declare const toggle: (id: string) => void;
+/** Removes an installed theme. */
+export declare const uninstall: (id: string) => Promise<void>;
+/**
+ * @description Checks for updates, then applies this theme's pending update.
+ * @param id The theme's id.
+ * @returns Whether the theme now runs a newer version.
+ */
+export declare function update(id: string): Promise<boolean>;
+/** The outcome of an addon reload: success, or failure carrying the recorded error. */
+export type ReloadResult =
+	| {
+			ok: true;
+	  }
+	| {
+			ok: false;
+			error: Error;
+	  };
+
+export {};

package/src/toasts.d.ts

@@ -1,20 +1,73 @@
 // Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
 
+import type { MessageKey, FormatVars as MessageVars } from '@unbound-app/i18n';
+
 export type { ToastHandle, ToastOptions } from './_internal';
 import type { ToastHandle, ToastOptions } from './_internal';
-import * as ReactModule from 'react';
-import { ComponentType } from 'react';
+import * as React$1 from 'react';
+import { ComponentType, ReactElement } from 'react';
 import { ImageSourcePropType } from 'react-native';
-
-declare const _default: {
-	showToast: typeof showToast;
-};
+/**
+ * @description Shows an error toast with an X icon, titled "Something went wrong" in the user's language, with the
+ * error's own message as its text, and logs the error.
+ * @param cause What was thrown or rejected: an Error, a string or anything else.
+ * @returns A {@link ToastHandle} for controlling the shown toast.
+ */
+export declare function error(cause: unknown): ToastHandle;
+/**
+ * @description Shows an error toast titled by a message key, with the error's message as its text, and logs the error.
+ * @param key The title's message key.
+ * @param args The key's placeholder values when it has placeholders, then the error, then optional `icon`, `duration` and `id`.
+ * @returns A {@link ToastHandle} for controlling the shown toast.
+ */
+export declare function error<K extends MessageKey>(
+	key: K,
+	...args: MessageArgs<K, [error: unknown, options?: ToastShorthandOptions]>
+): ToastHandle;
+/**
+ * @description Shows an info toast titled by a message key, with an info icon.
+ * @param key The message key.
+ * @param args The key's placeholder values when it has placeholders, then optional `icon`, `duration` and `id`.
+ * @returns A {@link ToastHandle} for controlling the shown toast.
+ */
+export declare function info<K extends MessageKey>(
+	key: K,
+	...args: MessageArgs<K, [options?: ToastShorthandOptions]>
+): ToastHandle;
 /**
  * @description Shows a toast, generating an id when one is not supplied.
  * @param options The toast options, optionally including a custom `id`.
  * @returns A {@link ToastHandle} for controlling the shown toast.
  */
-export declare function showToast(options: ToastOptions): ToastHandle;
-export { _default as default };
-
+export declare function show(options: ToastOptions): ToastHandle;
+/**
+ * @description Shows a success toast titled by a message key, with a check icon.
+ * @param key The message key.
+ * @param args The key's placeholder values when it has placeholders, then optional `icon`, `duration` and `id`.
+ * @returns A {@link ToastHandle} for controlling the shown toast.
+ */
+export declare function success<K extends MessageKey>(
+	key: K,
+	...args: MessageArgs<K, [options?: ToastShorthandOptions]>
+): ToastHandle;
+/**
+ * @description Shows a warning toast titled by a message key, with a warning icon.
+ * @param key The message key.
+ * @param args The key's placeholder values when it has placeholders, then optional `icon`, `duration` and `id`.
+ * @returns A {@link ToastHandle} for controlling the shown toast.
+ */
+export declare function warning<K extends MessageKey>(
+	key: K,
+	...args: MessageArgs<K, [options?: ToastShorthandOptions]>
+): ToastHandle;
+/**
+ * The arguments after a key, as `format(key, vars)` takes them: the key's placeholder values when it has
+ * placeholders, none when it has none, then `Tail`.
+ */
+export type MessageArgs<
+	K extends MessageKey,
+	Tail extends unknown[] = [],
+> = K extends keyof MessageVars ? [vars: MessageVars[K], ...Tail] : Tail;
+/** The toast options a shorthand takes after its key and vars. */
+export type ToastShorthandOptions = Pick<ToastOptions, 'icon' | 'duration' | 'id'>;
 export {};