@saykit/carbon 0.0.0 → 0.2.0

package/README.md

@@ -0,0 +1,45 @@
+# @saykit/carbon
+
+> [Carbon](https://carbon.buape.com) Discord bot integration for [SayKit](https://saykit.js.org).
+
+Registers a shared `Say` with your Carbon client, helps command and component classes expose translated metadata, and adds locale-aware `interaction.say` and `guild.say` properties.
+
+## Install
+
+```sh
+pnpm add @saykit/carbon saykit @buape/carbon
+```
+
+## Usage
+
+```ts
+import { Client, Command, type CommandInteraction } from '@buape/carbon';
+import { SayPlugin, withSay } from '@saykit/carbon';
+import { type Say } from 'saykit';
+import say from './i18n.js';
+
+class PingCommand extends withSay(Command) {
+  constructor(say: Say) {
+    super(say, (say) => ({
+      name: say`ping`,
+      description: say`Ping the bot!`,
+    }));
+  }
+
+  async run(interaction: CommandInteraction) {
+    await interaction.reply({ content: interaction.say`Pong!` });
+  }
+}
+
+const client = new Client(
+  {
+    /* options */
+  },
+  { commands: [new PingCommand(say)] },
+  [new SayPlugin(say)],
+);
+```
+
+## Documentation
+
+[Carbon integration guide](https://saykit.js.org/integrations/carbon) at [saykit.js.org](https://saykit.js.org).

package/dist/index.d.mts

@@ -0,0 +1,65 @@
+import { APIInteraction, BaseCommand, BaseComponent, Modal, Plugin } from "@buape/carbon";
+import { Say } from "saykit";
+
+//#region src/constants.d.ts
+declare const kSay: unique symbol;
+//#endregion
+//#region src/extensions/base-interaction.d.ts
+declare module '@buape/carbon' {
+  interface BaseInteraction<T extends APIInteraction> {
+    get say(): Say;
+    [kSay]: Say;
+  }
+}
+declare function applyBaseInteractionExtension(): () => void;
+//#endregion
+//#region src/extensions/guild.d.ts
+declare module '@buape/carbon' {
+  interface Guild {
+    get say(): Say;
+    [kSay]: Say;
+  }
+}
+declare function applyGuildExtension(): () => void;
+//#endregion
+//#region src/mixers/with-say.d.ts
+type Keys = 'name' | 'description' | 'label' | 'title' | 'placeholder' | 'content' | 'options' | 'components' | 'subcommands' | 'subcommandGroups';
+type AbstractConstructor<Args extends any[] = any[], Instance extends object = object> = abstract new (...args: Args) => Instance;
+type SayProps<T> = Pick<T, Extract<keyof T, Keys>>;
+/**
+ * Enhances a {@link BaseCommand} subclass with support for localisation.
+ *
+ * @param Base Abstract command constructor to extend.
+ * @returns A new constructor that accepts a {@link Say} instance, a
+ * properties-mapping function, and the original constructor arguments.
+ */
+declare function withSay<Args extends unknown[], Instance extends BaseCommand>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[say: Say, properties: (say: Say) => SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
+/**
+ * Enhances a {@link BaseComponent} or {@link Modal} subclass with
+ * support for localisation.
+ *
+ * @param Base Abstract component or modal constructor to extend.
+ * @returns A new constructor that accepts a set of properties.
+ */
+declare function withSay<Args extends unknown[], Instance extends BaseComponent | Modal>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[properties: SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * A Carbon plugin that provides a singleton {@link Say} instance.
+ *
+ * `SayPlugin` registers a {@link Say} instance globally and
+ * applies interaction and guild-level extensions so that commands and
+ * other handlers can access localisation utilities directly.
+ *
+ * @example
+ * ```ts
+ * const say = new Say({ ... });
+ * const client = new Client({ ... }, { ... }, [new SayPlugin(say)]);
+ * ```
+ */
+declare class SayPlugin extends Plugin {
+  id: string;
+  constructor(say: Say);
+}
+//#endregion
+export { SayPlugin, applyBaseInteractionExtension, applyGuildExtension, withSay };

package/dist/index.mjs

@@ -0,0 +1,127 @@
+import { BaseCommand, BaseComponent, BaseInteraction, Guild, Locale, Modal, Plugin } from "@buape/carbon";
+//#region src/utils/combine-command-options.ts
+const ALLOWED_LOCALES = Object.values(Locale);
+function combineCommandOptions(mappedOptions, baseLocale) {
+	const options = mappedOptions[baseLocale];
+	const availableLocales = Object.keys(mappedOptions).filter((l) => l !== baseLocale && ALLOWED_LOCALES.includes(l));
+	for (const [key, value] of Object.entries(options)) if (key === "name" || key === "description") {
+		options[`${key}Localizations`] = {};
+		for (const locale of availableLocales) {
+			const other = mappedOptions[locale][key];
+			options[`${key}Localizations`][locale] = other;
+		}
+		options[`${key}_localizations`] = options[`${key}Localizations`];
+	} else if ((key === "options" || key === "choices") && Array.isArray(value)) for (const [index, option] of Object.entries(value)) {
+		const mapped = { [baseLocale]: option };
+		for (const locale of availableLocales) mapped[locale] = mappedOptions[locale][key][index];
+		const combined = combineCommandOptions(mapped, baseLocale);
+		options[key][index] = combined;
+	}
+	return options;
+}
+//#endregion
+//#region src/mixers/with-say.ts
+const ClassMap = /* @__PURE__ */ new WeakMap();
+/**
+* Factory function that creates a "withSay" wrapper around a base class.
+*
+* @param Base The base class constructor.
+* @returns A subclass of the given base class with extra for localisation.
+* @throws If the base class is neither a {@link BaseCommand} nor a
+* {@link BaseComponent}.
+*/
+function withSay(Base) {
+	if (ClassMap.has(Base)) return ClassMap.get(Base);
+	if (Base.prototype instanceof BaseCommand) {
+		const Derived = createSayCommand(Base);
+		ClassMap.set(Base, Derived);
+		return Derived;
+	}
+	if (Base.prototype instanceof BaseComponent || Base === Modal) {
+		const Derived = createSayComponent(Base);
+		ClassMap.set(Base, Derived);
+		return Derived;
+	}
+	throw new Error("Invalid base class");
+}
+function createSayCommand(Base) {
+	class SayCommand extends Base {
+		constructor(say, properties, ...args) {
+			super(...args);
+			const options = combineCommandOptions(Array.from(say).reduce((acc, [s, l]) => {
+				acc[l] = properties(s);
+				return acc;
+			}, {}), say.locale);
+			Object.assign(this, options);
+		}
+	}
+	return SayCommand;
+}
+function createSayComponent(Base) {
+	class SayComponent extends Base {
+		constructor(properties, ...args) {
+			super(...args);
+			if (properties) Object.assign(this, properties);
+		}
+	}
+	return SayComponent;
+}
+//#endregion
+//#region src/constants.ts
+const kSay = Symbol.for("saykit.say");
+//#endregion
+//#region src/extensions/base-interaction.ts
+function applyBaseInteractionExtension() {
+	Object.defineProperty(BaseInteraction.prototype, "say", { get() {
+		const say = Reflect.get(globalThis, kSay);
+		if (!say) throw new Error("No `say` instance available");
+		this[kSay] ??= say.clone();
+		const locale = this[kSay].match([this.rawData.locale]);
+		this[kSay].activate(locale);
+		return this[kSay];
+	} });
+	return () => {
+		Object.defineProperty(BaseInteraction.prototype, "say", { value: void 0 });
+	};
+}
+//#endregion
+//#region src/extensions/guild.ts
+function applyGuildExtension() {
+	Object.defineProperty(Guild.prototype, "say", { get() {
+		const say = Reflect.get(globalThis, kSay);
+		if (!say) throw new Error("No `say` instance available");
+		this[kSay] ??= say.clone();
+		const locale = this[kSay].match([this.rawData.preferred_locale]);
+		this[kSay].activate(locale);
+		return this[kSay];
+	} });
+	return () => {
+		Object.defineProperty(Guild.prototype, "say", { value: void 0 });
+	};
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* A Carbon plugin that provides a singleton {@link Say} instance.
+*
+* `SayPlugin` registers a {@link Say} instance globally and
+* applies interaction and guild-level extensions so that commands and
+* other handlers can access localisation utilities directly.
+*
+* @example
+* ```ts
+* const say = new Say({ ... });
+* const client = new Client({ ... }, { ... }, [new SayPlugin(say)]);
+* ```
+*/
+var SayPlugin = class extends Plugin {
+	id = "saykit";
+	constructor(say) {
+		super();
+		Reflect.set(globalThis, kSay, say);
+		applyBaseInteractionExtension();
+		applyGuildExtension();
+	}
+};
+//#endregion
+export { SayPlugin, withSay };

package/package.json

@@ -1,4 +1,49 @@
-{
-  "name": "@saykit/carbon",
-  "version": "0.0.0"
+{
+  "name": "@saykit/carbon",
+  "version": "0.2.0",
+  "description": "Carbon Discord framework integration for saykit",
+  "keywords": [
+    "bot",
+    "carbon",
+    "discord",
+    "i18n",
+    "saykit"
+  ],
+  "homepage": "https://github.com/k0d13/saykit#readme",
+  "bugs": {
+    "url": "https://github.com/k0d13/saykit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0d13/saykit.git",
+    "directory": "packages/integration-carbon"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@buape/carbon": "0.16.0",
+    "saykit": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@buape/carbon": "*",
+    "saykit": "*"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsdown"
+  }
 }