fix: return number from embed parser (#120)

* fix: return number from embed parser

* docs: add dev notes deny parser

* docs: update badge

* test: add test for resolveColor

Author: imranbarbhuiya

packages/tagscript-plugin-discord/README.md

@@ -4,9 +4,9 @@
 
 **A tagscript plugin to work with discord.js**
 
-[![npm](https://img.shields.io/npm/dw/tagscript)](https://www.npmjs.com/package/tagscript)
+[![npm](https://img.shields.io/npm/dw/tagscript-plugin-discord)](https://www.npmjs.com/package/tagscript-plugin-discord)
 [![codecov](https://codecov.io/gh/imranbarbhuiya/tagscript/branch/main/graph/badge.svg?precision=2&flag=tagscript-plugin-discord)](https://codecov.io/gh/imranbarbhuiya/tagscript)
-[![npm](https://img.shields.io/npm/v/tagscript?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/tagscript)
+[![npm](https://img.shields.io/npm/v/tagscript-plugin-discord?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/tagscript-plugin-discord)
 
 </div>
 

packages/tagscript-plugin-discord/src/lib/Parsers/AllowDeny.ts

@@ -6,17 +6,35 @@ import { BaseParser, type IParser, type Context } from 'tagscript';
  * it will send the response if one is given. Multiple role, user or channel
  * requirements can be given, and should be split by a `,`.
  *
+ * Aliases: allowlist, whitelist
+ *
  * @example
  * ```yaml
  * {require(user,role,channel):response}
  * ```
- * Aliases: allowlist, whitelist
  * @example
  * ```yaml
  * {require(Moderator)}
  * {require(#general, #bot-commands):This tag can only be run in #general and #bot-cmds.}
  * {require(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}
  * ```
+ *
+ * Developers need to add the check themselves.
+ * @example
+ * ```ts
+ * const { Interpreter } = require("tagscript")
+ * const { RequiredParser } = require("tagscript-plugin-discord")
+ *
+ * const ts = new Interpreter(new RequiredParser())
+ *
+ * const result = await ts.run("{require(id1, id2):You aren't allowed to use this tag.}")
+ *
+ * if (!result.actions.require.ids.includes(interaction.user.id)) {
+ * // add channel, role check here or check using name instead of id
+ * return interaction.reply(result.actions.require.message)
+ * }
+ *
+ * ```
  */
 export class RequiredParser extends BaseParser implements IParser {
 	public constructor() {
@@ -49,6 +67,22 @@ export class RequiredParser extends BaseParser implements IParser {
  * {deny(#general, #chat):This tag can't be run in #general and #chat.}
  * {deny(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}
  * ```
+ *
+ * Developers need to add the check themselves.
+ * @example
+ * ```ts
+ * const { Interpreter } = require("tagscript")
+ * const { DenyParser } = require("tagscript-plugin-discord")
+ *
+ * const ts = new Interpreter(new DenyParser())
+ *
+ * const result = await ts.run("{require(id1, id2):You aren't allowed to use this tag.}")
+ *
+ * if (result.actions.deny.ids.includes(interaction.user.id)) {
+ * // add channel, role check here or check using name instead of id
+ * return interaction.reply(result.actions.deny.message)
+ * }
+ * ```
  */
 
 export class DenyParser extends BaseParser implements IParser {

packages/tagscript-plugin-discord/src/lib/Parsers/Embed.ts

@@ -1,5 +1,7 @@
 import { BaseParser, split, type Context, type IParser, type Awaitable } from 'tagscript';
 
+import { resolveColor } from '../Utils';
+
 import type { EmbedData, APIEmbed } from 'discord.js';
 
 /**
@@ -13,12 +15,12 @@ import type { EmbedData, APIEmbed } from 'discord.js';
  * @example
  *  Using JSON
  * ```yaml
- * { embed: json }
+ * {embed: json}
  * ```
  * @example
  * ```yaml
- * { embed: { "title": "Hello!", "description": "This is a test embed." } }
- * { embed: {
+ * {embed: { "title": "Hello!", "description": "This is a test embed." } }
+ * {embed: {
  *     "title": "Here's a random duck!",
  *     "image": { "url": "https://random-d.uk/api/randomimg" },
  *     "color": 15194415
@@ -27,14 +29,26 @@ import type { EmbedData, APIEmbed } from 'discord.js';
  *  @example
  *  Using properties
  * ```yaml
- * { embed(property): value }
+ * {embed(property):value}
  * ```
  * @example
  * ```yaml
- * { embed(color): 0x37b2cb }
- * { embed(title): Rules }
- * { embed(description): Follow these rules to ensure a good experience in our server! }
- * { embed(field): Rule 1|Respect everyone you speak to.|false }
+ * {embed(color): 0x37b2cb}
+ * {embed(title): Rules}
+ * {embed(description): Follow these rules to ensure a good experience in our server!}
+ * {embed(field): Rule 1|Respect everyone you speak to.|false}
+ * ```
+ * Developers need to construct the embed builder themselves with the output of the tag.
+ * @example
+ * ```ts
+ * const { Interpreter } = require("tagscript")
+ * const { EmbedParser } = require("tagscript-plugin-discord")
+ *
+ * const ts = new Interpreter(new EmbedParser())
+ * const result = await ts.run('{embed: { "title": "Hello!", "description": "This is a test embed." }}')
+ *
+ * // You might need to change the embed object before passing to `EmbedBuilder`. Changes such as change thumbnail and image value from string to object.
+ * const embed = new EmbedBuilder(response.actions.embed);
  * ```
  * @remarks
  * The return type depends on user's input. So it might not be `EmbedData | APIEmbed`. So use a typeguard to check.
@@ -63,6 +77,13 @@ export class EmbedParser extends BaseParser implements IParser {
 			});
 		}
 
+		if (ctx.tag.parameter === 'color') {
+			return this.returnEmbed(ctx, {
+				// This can return number but it should be handled by the dev
+				color: resolveColor(ctx.tag.payload!) as number
+			});
+		}
+
 		return this.returnEmbed(ctx, { [ctx.tag.parameter]: ctx.tag.payload });
 	}
 
@@ -73,7 +94,9 @@ export class EmbedParser extends BaseParser implements IParser {
 	 * @returns
 	 */
 	protected parseEmbedJSON(payload: string): Awaitable<APIEmbed | EmbedData> {
-		return JSON.parse(payload);
+		const parsedResult = JSON.parse(payload);
+		if (parsedResult.color) parsedResult.color = resolveColor(parsedResult.color);
+		return parsedResult;
 	}
 
 	private returnEmbed(ctx: Context, data: APIEmbed | EmbedData): string {

packages/tagscript-plugin-discord/src/lib/Utils/index.ts

@@ -1 +1,2 @@
 export * from './CommandInteraction';
+export * from './resolveColor';

packages/tagscript-plugin-discord/src/lib/Utils/resolveColor.ts

@@ -0,0 +1,15 @@
+import { resolveColor as DJSResolveColor, type ColorResolvable } from 'discord.js';
+
+/**
+ * Resolves a color to a number. This function doesn't throw for invalid colors but returns the input
+ *
+ * @param color - The color to resolve
+ * @returns
+ */
+export const resolveColor = (color: string): number | string => {
+	try {
+		return Number(color) || DJSResolveColor(color as ColorResolvable);
+	} catch {
+		return color;
+	}
+};

packages/tagscript-plugin-discord/tests/Parsers/Embed.test.ts

@@ -94,4 +94,18 @@ describe('EmbedParser', () => {
 			author: { name: 'Mahir', icon_url: 'https://example.com/image.png' }
 		});
 	});
+
+	test('GIVEN color in JSON THEN resolve it to hex color', async () => {
+		const text = '{embed:{"color":"0x00ff00"}}';
+
+		expect((await ts.run(text)).actions.embed).toStrictEqual({
+			color: 65_280
+		});
+	});
+
+	test.each(['Red', '#ed4245', 0xed4245])('GIVEN color %j in property THEN resolve it to hex color', async (color) => {
+		expect((await ts.run(`{embed(color):${color}}`)).actions.embed).toStrictEqual({
+			color: 0xed4245
+		});
+	});
 });

packages/tagscript-plugin-discord/tests/Utils/resolveColor.test.ts

@@ -0,0 +1,19 @@
+import { resolveColor } from '../../src';
+
+describe('ResolveColor', () => {
+	test('GIVEN a color name THEN return valid hex code', () => {
+		expect(resolveColor('Red')).toBe(0xed4245);
+	});
+
+	test('GIVEN a hex code starts with # THEN return valid hex code', () => {
+		expect(resolveColor('#FF0000')).toBe(0xff0000);
+	});
+
+	test('GIVEN a hex code starts with 0x THEN return valid hex code', () => {
+		expect(resolveColor('0xFF0000')).toBe(0xff0000);
+	});
+
+	test('GIVEN an invalid color THEN return the input', () => {
+		expect(resolveColor('invalid')).toBe('invalid');
+	});
+});