@unbound-app/api 2.2.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/api",
-	"version": "2.2.0",
+	"version": "3.1.0",
 	"author": {
 		"name": "Mario P.",
 		"email": "contact@marioparaschiv.com",
@@ -45,7 +45,7 @@
 		"./storage": "./src/storage.d.ts",
 		"./sync": "./src/sync.d.ts",
 		"./testing": "./testing/index.ts",
-		"./testing/icu-parse": "./testing/icu-parse.ts",
+		"./testing/fakes": "./testing/fakes.ts",
 		"./testing/preset": "./testing/preset.ts",
 		"./themes": "./src/themes.d.ts",
 		"./toasts": "./src/toasts.d.ts",

package/src/_conventions/addon-assets.ts

@@ -0,0 +1,59 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+/** The folder, at the plugin root and beside the built bundle, that holds a plugin's images. */
+export const ASSETS_DIRECTORY = 'assets';
+
+/** The image types a plugin ships: the formats React Native's `Image` decodes. An SVG is a component, not an asset. */
+export const ASSET_TYPES = ['png', 'jpg', 'webp', 'gif'] as const;
+
+/** One of {@link ASSET_TYPES}. */
+export type AssetType = (typeof ASSET_TYPES)[number];
+
+/** The pixel densities a plugin image can ship at, as its `@2x` and `@3x` file suffixes name them. */
+export const ASSET_SCALES = ['1', '2', '3'] as const;
+
+/** Path segments joined by `/`, each starting with a letter, digit, `_` or `-`, so no name can leave its folder. */
+export const ASSET_NAME_PATTERN = '^[\\w-][\\w.-]*(?:/[\\w-][\\w.-]*)*$';
+
+const ASSET_NAME = new RegExp(ASSET_NAME_PATTERN);
+
+/**
+ * @description Tells whether `value` can name a plugin asset: path segments without `..`, at most 200 characters.
+ * @param value The untrusted value.
+ * @returns Whether it is a safe asset name.
+ */
+// UNKNOWN: a name read from a manifest or a file path.
+export function isAssetName(value: unknown): value is string {
+	return typeof value === 'string' && value.length <= 200 && ASSET_NAME.test(value);
+}
+
+/**
+ * @description Tells whether `value` is one of {@link ASSET_TYPES}.
+ * @param value The untrusted value.
+ * @returns Whether a plugin can ship an image of this type.
+ */
+// UNKNOWN: a type read from a manifest or a file extension.
+export function isAssetType(value: unknown): value is AssetType {
+	return ASSET_TYPES.some((type) => type === value);
+}
+
+/**
+ * @description Names an image file beside an addon's bundle. Files are named by content, so equal images share one.
+ * @param main The manifest's `main`, such as `index.js`.
+ * @param sha256 The file's SHA-256.
+ * @param type The file's type.
+ * @returns The file's path relative to the manifest, such as `assets/<sha256>.png`.
+ */
+export function getAssetPath(main: string, sha256: string, type: AssetType): string {
+	return `${main.slice(0, main.lastIndexOf('/') + 1)}${ASSETS_DIRECTORY}/${sha256}.${type}`;
+}
+
+export default {
+	ASSETS_DIRECTORY,
+	ASSET_TYPES,
+	ASSET_SCALES,
+	ASSET_NAME_PATTERN,
+	isAssetName,
+	isAssetType,
+	getAssetPath,
+};

package/src/_conventions/addon-locales.ts

@@ -0,0 +1,50 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+/** The Discord locale every plugin ships in its bundle, and the source of truth for its message keys. */
+export const SOURCE_LOCALE = 'en-US';
+
+/** The folder, beside a plugin's `src/` and beside its built bundle, that holds one JSON file per locale. */
+export const LOCALES_DIRECTORY = 'i18n';
+
+/** A Discord locale code, such as `de`, `en-GB` or `es-419`. It names a file, so it holds no path characters. */
+export const LOCALE_CODE_PATTERN = '^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$';
+
+const LOCALE_CODE = new RegExp(LOCALE_CODE_PATTERN);
+
+/**
+ * @description Tells whether `value` is a locale code that can name a locale file.
+ * @param value The untrusted value.
+ * @returns Whether it is a path-safe locale code.
+ */
+// UNKNOWN: a code read from a manifest or a file name.
+export function isLocaleCode(value: unknown): value is string {
+	return typeof value === 'string' && value.length <= 35 && LOCALE_CODE.test(value);
+}
+
+/**
+ * @description Names the folder of locale files beside an addon's bundle.
+ * @param main The manifest's `main`, such as `index.js`.
+ * @returns The folder's path relative to the manifest, such as `i18n`.
+ */
+export function getLocalesDirectory(main: string): string {
+	return `${main.slice(0, main.lastIndexOf('/') + 1)}${LOCALES_DIRECTORY}`;
+}
+
+/**
+ * @description Names a locale file beside an addon's bundle, as the build emits it and the client downloads it.
+ * @param main The manifest's `main`, such as `index.js`.
+ * @param code The locale code.
+ * @returns The file's path relative to the manifest, such as `i18n/de.json`.
+ */
+export function getLocalePath(main: string, code: string): string {
+	return `${getLocalesDirectory(main)}/${code}.json`;
+}
+
+export default {
+	SOURCE_LOCALE,
+	LOCALES_DIRECTORY,
+	LOCALE_CODE_PATTERN,
+	isLocaleCode,
+	getLocalesDirectory,
+	getLocalePath,
+};

package/{testing → src/_conventions}/icu-parse.ts

@@ -1,3 +1,5 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
 /** The branches of a `plural`, `selectordinal` or `select` argument, by selector, such as `one` or `=0`. */
 export type IcuBranches = Map<string, IcuNode[]>;
 

package/src/_conventions/metro.ts

@@ -0,0 +1,37 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+/** The key whose own descriptor marks a lazy metro handle, read without resolving it. */
+export const LAZY_MARKER = '__METRO_LAZY__';
+
+/** The props each `metro.common` member is found by, as the client's lookups find them. */
+export const COMMON_PROPS = {
+	Reanimated: ['useAnimatedStyle', 'useSharedValue'],
+	Gestures: ['PanGestureHandler'],
+	Clipboard: ['setString', 'getString', 'setImage', 'getImage'],
+	MarkdownParser: ['parse', 'parseToAST', 'reactParserFor'],
+	SimpleMarkdown: ['parserFor', 'outputFor', 'defaultRules'],
+	Screens: ['FullWindowOverlay'],
+	SVG: ['Svg', 'Path'],
+	Commands: ['getBuiltInCommands'],
+	Moment: ['isMoment'],
+	Util: ['inspect'],
+	Assets: ['registerAsset'],
+	ImageSources: ['getImageSourcesFromImageProps'],
+	Clyde: ['createBotMessage'],
+	Constants: ['Fonts', 'Endpoints'],
+	Radius: ['Radius'],
+	Theme: ['colors', 'internal'],
+	REST: ['getAPIBaseURL'],
+	i18n: ['getLanguages', 'getSystemLocale', 'intl'],
+} satisfies Record<string, string[]>;
+
+/** The props each `metro.api` member is found by, as the client's lookups find them. */
+export const API_PROPS = {
+	Messages: ['sendMessage', 'receiveMessage'],
+	Profiles: ['showUserProfile'],
+	AsyncUsers: ['fetchProfile'],
+	Invites: ['acceptInviteAndTransitionToInviteChannel'],
+	OAuth2: ['openOAuth2Modal'],
+	ActionSheets: ['openLazy', 'hideActionSheet'],
+	UserProfiles: ['getUserProfileActionSheetKey', 'showUserProfileActionSheetPostConnection'],
+} satisfies Record<string, string[]>;

package/src/_conventions/walk-tree.ts

@@ -0,0 +1,88 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { PredicateResult } from '../_types';
+
+/** A node in an object graph, such as a React tree. Discord's trees carry no static types, so a predicate reads them unchecked. */
+// oxlint-disable-next-line typescript/no-explicit-any -- tree nodes are whatever Discord built
+export type TreeNode = any;
+
+/** Tests one node of a tree; a truthy result is a match. */
+export type TreePredicate = (node: TreeNode) => PredicateResult;
+
+/** How a tree search descends. */
+export type TreeSearchOptions = {
+	/** The only keys descended into; every own key when omitted. Array items are always walked. */
+	walkable?: string[];
+	/** Keys never descended into. */
+	ignore?: string[];
+	/** How many levels below the root to descend. Defaults to 100. */
+	maxDepth?: number;
+};
+
+/**
+ * @description Walks an object graph depth-first from its root, testing every non-nullish value once, and collects matches.
+ * @param root The node to start from; it is tested too.
+ * @param predicate Tests each node.
+ * @param options How the search descends.
+ * @param all Whether to collect every match rather than stop at the first.
+ * @returns The matches, in visiting order.
+ */
+function walkTree(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options: TreeSearchOptions,
+	all: boolean,
+): TreeNode[] {
+	const { walkable, ignore = [], maxDepth = 100 } = options;
+	const seen = new WeakSet<object>();
+	const found: TreeNode[] = [];
+
+	// Returns `true` once the search should stop.
+	function visit(node: TreeNode, depth: number): boolean {
+		if (node === null || node === undefined) {
+			return false;
+		}
+
+		const isObject = typeof node === 'object';
+
+		if (isObject) {
+			if (seen.has(node)) {
+				return false;
+			}
+
+			seen.add(node);
+		}
+
+		if (predicate(node)) {
+			found.push(node);
+
+			if (!all) {
+				return true;
+			}
+		}
+
+		if (!isObject || depth >= maxDepth) {
+			return false;
+		}
+
+		const keys = Array.isArray(node) ? node.keys() : (walkable ?? Object.keys(node));
+
+		for (const key of keys) {
+			if (typeof key === 'string' && ignore.includes(key)) {
+				continue;
+			}
+
+			if (visit(node[key], depth + 1)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	visit(root, 0);
+
+	return found;
+}
+
+export default walkTree;