feat: allow sending of basic files through webhooks (#181)

.changeset/ten-steaks-doubt.md

@@ -0,0 +1,7 @@
+---
+"@guildedjs/guilded-api-typings": patch
+"@guildedjs/rest": patch
+"@guildedjs/webhook-client": minor
+---
+
+feat: allow sending of basic files through webhooks

packages/guilded-api-typings/lib/v1/rest/Webhook.ts

@@ -59,6 +59,7 @@ export interface RESTPostWebhookBody {
     embeds?: APIEmbed[];
     username?: string;
     avatar_url?: string;
+    payload_json?: Pick<RESTPostWebhookBody, "content" | "avatar_url" | "username" | "embeds">;
 }
 
 export type RESTPostWebhookResult = WebhookContentPayload;

packages/rest/lib/RestManager.ts

@@ -7,6 +7,8 @@ import EventEmitter from "events";
 import { stringify } from "qs";
 
 const packageDetails = require("../package.json");
+import FormData from "form-data";
+
 import { GuildedAPIError } from "./errors/GuildedAPIError";
 import { PermissionsError } from "./errors/PermissionsError";
 import type { RestOptions } from "./typings";
@@ -42,12 +44,22 @@ export class RestManager {
     ): Promise<[Response, Promise<T>]> {
         const headers: HeadersInit = {};
         if (authenticated) headers.Authorization = `Bearer ${this.token}`;
+
+        let body: Buffer | string | undefined = undefined;
+        if (data.body instanceof FormData) {
+            body ??= data.body.getBuffer();
+            Object.assign(headers, { ...data.body.getHeaders() });
+        } else {
+            body ??= JSON.stringify(body);
+        }
+
         const requestOptions = {
-            body: data.body ? JSON.stringify(data.body) : undefined,
+            body,
             headers: {
                 "content-type": "application/json",
                 "User-Agent": `@guildedjs-rest/${packageDetails.version} Node.js v${process.version}`,
                 ...headers,
+                ...data.headers,
             },
             method: data.method,
         };
@@ -141,7 +153,9 @@ export interface MakeOptions<B = Record<string, any>, Q = RequestBodyObject> {
     method: string;
     query?: Q;
     path: string;
-    body?: B;
+    body?: B | FormData;
+    isFormData?: boolean;
+    headers?: Record<string, string>;
 }
 export type JSONB = Record<string, any>;
 export type RequestBodyObject = JSONB | undefined;

packages/rest/package.json

@@ -20,6 +20,7 @@
         "typescript": "4.8.3"
     },
     "dependencies": {
+        "form-data": "^4.0.0",
         "node-fetch": "2.6.7",
         "qs": "^6.10.5"
     },

packages/webhook-client/__tests__/file-sending/src/index.ts

@@ -0,0 +1,8 @@
+import { readFileSync } from "fs";
+
+import { WebhookClient } from "../../../lib/index";
+const client = new WebhookClient("");
+
+void (async (): Promise<unknown> => {
+    return client.send({ files: [{ name: "bbb.png", content: readFileSync("./bbb.png") }] });
+})();

packages/webhook-client/lib/WebhookClient.ts

@@ -1,9 +1,10 @@
-import type { RESTPostWebhookBody, RESTPostWebhookResult } from "@guildedjs/guilded-api-typings";
-import type { APIContent } from "@guildedjs/guilded-api-typings/dist/v1/structs/Webhook";
+import type { APIContent, APIEmbed, RESTPostWebhookBody, RESTPostWebhookResult } from "@guildedjs/guilded-api-typings";
 import { RestManager } from "@guildedjs/rest";
+import FormData from "form-data";
 
-import type { Embed } from "./Embed";
+import { Embed } from "./Embed";
 import { type parsedMessage, parseMessage } from "./messageUtil";
+import type { MessageAttachment, MessageContent } from "./util";
 
 export class WebhookClient {
     public URL: string;
@@ -20,7 +21,7 @@ export class WebhookClient {
 
     public constructor(
         webhookConnection: string | { id: string; token: string },
-        { username, avatarURL }: { username?: string; avatarURL?: string },
+        { username, avatarURL }: { username?: string; avatarURL?: string } = {},
     ) {
         if (!webhookConnection) {
             throw new TypeError(`Must provide Webhook connection info in either string or object. Received ${webhookConnection}.`);
@@ -46,34 +47,48 @@ export class WebhookClient {
     }
 
     public send(
-        content: string | RESTPostWebhookBody,
-        embeds?: Embed[],
-        options?: { username?: string; avatarURL?: string },
+        content: MessageContent,
+        embeds?: (Embed | APIEmbed)[],
+        options?: { files?: MessageAttachment[]; username?: string; avatarURL?: string },
     ): Promise<WebhookExecuteResponse> {
-        return this.rest
-            .post<RESTPostWebhookResult, RESTPostWebhookBody>(
-                "",
-                typeof content === "object"
-                    ? content
-                    : {
-                          content,
-                          embeds: embeds?.map((x) => x.toJSON()),
-                          username: options?.username ?? this.username ?? undefined,
-                          avatar_url: options?.avatarURL ?? this.avatarURL ?? undefined,
-                      },
-            )
-            .then((data) => {
-                const parsedContent = parseMessage(data.content);
-                return {
-                    ...data,
-                    content: parsedContent.parsedText,
-                    parsedContent,
-                    rawContent: data.content,
-                } as WebhookExecuteResponse;
-            });
+        const contentIsObject = typeof content === "object";
+        const resEmbeds = transformEmbedToAPIEmbed((contentIsObject ? content.embeds : embeds) ?? []);
+        const resFiles = contentIsObject ? content.files : options?.files;
+
+        const baseBody: RESTPostWebhookBody = contentIsObject
+            ? {
+                  ...content,
+                  embeds: resEmbeds,
+              }
+            : {
+                  content,
+                  embeds: resEmbeds,
+                  username: options?.username ?? this.username ?? undefined,
+                  avatar_url: options?.avatarURL ?? this.avatarURL ?? undefined,
+              };
+
+        let body: FormData | RESTPostWebhookBody = baseBody;
+        const formData = new FormData();
+        if (resFiles?.length) {
+            resFiles.forEach((value, index) => formData.append(`files[${index}]`, value.content, { filename: value.name, filepath: value.path }));
+            formData.append("payload_json", JSON.stringify(baseBody), { contentType: "application/json" });
+            body = formData;
+        }
+
+        return this.rest.post<RESTPostWebhookResult, RESTPostWebhookBody | FormData>("", body).then((data) => {
+            const parsedContent = parseMessage(data.content);
+            return {
+                ...data,
+                content: parsedContent.parsedText,
+                parsedContent,
+                rawContent: data.content,
+            } as WebhookExecuteResponse;
+        });
     }
 }
 
+const transformEmbedToAPIEmbed = (embeds: (Embed | APIEmbed)[]): APIEmbed[] => embeds.map((x) => (x instanceof Embed ? x.toJSON() : x));
+
 export interface WebhookExecuteResponse extends Omit<RESTPostWebhookResult, "content"> {
     content: string;
     parsedContent: parsedMessage;

packages/webhook-client/lib/util.ts

@@ -1,4 +1,7 @@
+import type { APIEmbed, RESTPostWebhookBody } from "@guildedjs/guilded-api-typings";
+
 import { COLORS } from "./consts";
+import type { Embed } from "./Embed";
 
 /**
  * Copyright 2015 - 2021 Amish Shah
@@ -18,3 +21,10 @@ export function resolveColor(color: string | number | [number, number, number]):
 
     return color;
 }
+
+export interface MessageAttachment {
+    content?: Buffer;
+    name: string;
+    path?: string;
+}
+export type MessageContent = (RESTPostWebhookBody & { embeds?: (Embed | APIEmbed)[]; files?: MessageAttachment[] }) | string;

packages/webhook-client/package.json

@@ -18,7 +18,8 @@
         "typescript": "4.8.3"
     },
     "dependencies": {
-        "@guildedjs/rest": "workspace:*"
+        "@guildedjs/rest": "workspace:*",
+        "form-data": "^4.0.0"
     },
     "contributors": [
         {