@minesa-org/mini-interaction 0.4.16 → 0.4.17

package/README.md

@@ -139,6 +139,53 @@ try {
 
 ---
 
+## 🔗 Linked Role Metadata
+
+Register application role connection metadata with `mini.registerMetadata(...)`.
+
+```ts
+import {
+  MiniInteraction,
+  RoleConnectionMetadataTypes,
+} from '@minesa-org/mini-interaction';
+
+const mini = new MiniInteraction({
+  applicationId: process.env.DISCORD_APPLICATION_ID,
+});
+
+await mini.registerMetadata(process.env.DISCORD_BOT_TOKEN!, [
+  {
+    key: 'is_miniapp',
+    name: 'Is Mini App?',
+    description: 'Is the user an assistant?',
+    type: RoleConnectionMetadataTypes.BooleanEqual,
+  },
+]);
+```
+
+Localization maps use `locale -> string` objects for `name_localizations` and `description_localizations`.
+
+```ts
+await mini.registerMetadata(process.env.DISCORD_BOT_TOKEN!, [
+  {
+    key: 'is_miniapp',
+    name: 'Is Mini App?',
+    description: 'Is the user an assistant?',
+    type: RoleConnectionMetadataTypes.BooleanEqual,
+    name_localizations: {
+      tr: 'Mini Uygulama mi?',
+      de: 'Ist Mini-App?',
+    },
+    description_localizations: {
+      tr: 'Kullanici bir assistant mi?',
+      de: 'Benutzer ist ein Assistent?',
+    },
+  },
+]);
+```
+
+---
+
 ## 📜 License
 
 MIT © [Minesa](https://github.com/minesa-org)

package/dist/clients/MiniInteraction.d.ts

@@ -0,0 +1,14 @@
+import { type DiscordRestClientOptions } from "../core/http/DiscordRestClient.js";
+import type { RegisterMetadataResult, RoleConnectionMetadataInput } from "../types/RoleConnectionMetadata.js";
+export type MiniInteractionOptions = {
+    applicationId?: string;
+    apiBaseUrl?: DiscordRestClientOptions["apiBaseUrl"];
+    maxRetries?: DiscordRestClientOptions["maxRetries"];
+    fetchImplementation?: DiscordRestClientOptions["fetchImplementation"];
+};
+export declare class MiniInteraction {
+    private readonly options;
+    constructor(options?: MiniInteractionOptions);
+    get applicationId(): string;
+    registerMetadata(botToken: string, metadata: RoleConnectionMetadataInput[]): Promise<RegisterMetadataResult>;
+}

package/dist/clients/MiniInteraction.js

@@ -0,0 +1,41 @@
+import { DiscordRestClient } from "../core/http/DiscordRestClient.js";
+export class MiniInteraction {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        const fetchImpl = options.fetchImplementation ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("[MiniInteraction] fetch is not available. Provide a global fetch implementation.");
+        }
+    }
+    get applicationId() {
+        const resolvedApplicationId = this.options.applicationId ??
+            (typeof process !== "undefined"
+                ? process.env.DISCORD_APPLICATION_ID
+                : undefined);
+        if (!resolvedApplicationId) {
+            throw new Error("[MiniInteraction] Missing Discord application ID. Set options.applicationId or DISCORD_APPLICATION_ID.");
+        }
+        return resolvedApplicationId;
+    }
+    async registerMetadata(botToken, metadata) {
+        if (!botToken) {
+            throw new Error("[MiniInteraction] botToken is required");
+        }
+        if (!Array.isArray(metadata) || metadata.length === 0) {
+            throw new Error("[MiniInteraction] metadata must be a non-empty array payload");
+        }
+        const rest = new DiscordRestClient({
+            token: botToken,
+            applicationId: this.applicationId,
+            apiBaseUrl: this.options.apiBaseUrl,
+            maxRetries: this.options.maxRetries,
+            fetchImplementation: this.options.fetchImplementation,
+        });
+        const payload = metadata.map((field) => ({
+            ...field,
+            type: field.type,
+        }));
+        return rest.putApplicationRoleConnectionMetadata(payload);
+    }
+}

package/dist/clients/__tests__/MiniInteraction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clients/__tests__/MiniInteraction.test.js

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { MiniInteraction } from "../MiniInteraction.js";
+import { RoleConnectionMetadataTypes } from "../../types/RoleConnectionMetadataTypes.js";
+test("registerMetadata sends the Discord payload and returns the response", async () => {
+    const originalAppId = process.env.DISCORD_APPLICATION_ID;
+    process.env.DISCORD_APPLICATION_ID = "app_123";
+    const calls = [];
+    const fetchImpl = (async (input, init) => {
+        calls.push({ input: String(input), init });
+        return new Response(JSON.stringify([
+            {
+                key: "is_miniapp",
+                name: "Is Mini App?",
+                description: "Is the user an assistant?",
+                type: RoleConnectionMetadataTypes.BooleanEqual,
+                name_localizations: { tr: "Mini Uygulama mi?" },
+                description_localizations: { tr: "Kullanici bir assistant mi?" },
+            },
+        ]), { status: 200 });
+    });
+    try {
+        const mini = new MiniInteraction({ fetchImplementation: fetchImpl });
+        const metadata = await mini.registerMetadata("bot-token", [
+            {
+                key: "is_miniapp",
+                name: "Is Mini App?",
+                description: "Is the user an assistant?",
+                type: RoleConnectionMetadataTypes.BooleanEqual,
+                name_localizations: { tr: "Mini Uygulama mi?" },
+                description_localizations: { tr: "Kullanici bir assistant mi?" },
+            },
+        ]);
+        assert.equal(calls.length, 1);
+        assert.equal(calls[0]?.input, "https://discord.com/api/v10/applications/app_123/role-connections/metadata");
+        assert.equal(calls[0]?.init?.method, "PUT");
+        assert.deepEqual(JSON.parse(String(calls[0]?.init?.body)), [
+            {
+                key: "is_miniapp",
+                name: "Is Mini App?",
+                description: "Is the user an assistant?",
+                type: RoleConnectionMetadataTypes.BooleanEqual,
+                name_localizations: { tr: "Mini Uygulama mi?" },
+                description_localizations: { tr: "Kullanici bir assistant mi?" },
+            },
+        ]);
+        assert.deepEqual(metadata, [
+            {
+                key: "is_miniapp",
+                name: "Is Mini App?",
+                description: "Is the user an assistant?",
+                type: RoleConnectionMetadataTypes.BooleanEqual,
+                name_localizations: { tr: "Mini Uygulama mi?" },
+                description_localizations: { tr: "Kullanici bir assistant mi?" },
+            },
+        ]);
+    }
+    finally {
+        if (originalAppId === undefined) {
+            delete process.env.DISCORD_APPLICATION_ID;
+        }
+        else {
+            process.env.DISCORD_APPLICATION_ID = originalAppId;
+        }
+    }
+});
+test("registerMetadata throws when metadata is empty", async () => {
+    const mini = new MiniInteraction({ applicationId: "app_123" });
+    await assert.rejects(() => mini.registerMetadata("bot-token", []), /\[MiniInteraction\] metadata must be a non-empty array payload/);
+});
+test("registerMetadata throws when application id cannot be resolved", async () => {
+    const originalAppId = process.env.DISCORD_APPLICATION_ID;
+    delete process.env.DISCORD_APPLICATION_ID;
+    try {
+        const mini = new MiniInteraction();
+        await assert.rejects(() => mini.registerMetadata("bot-token", [
+            {
+                key: "is_miniapp",
+                name: "Is Mini App?",
+                description: "Is the user an assistant?",
+                type: RoleConnectionMetadataTypes.BooleanEqual,
+            },
+        ]), /\[MiniInteraction\] Missing Discord application ID/);
+    }
+    finally {
+        if (originalAppId === undefined) {
+            delete process.env.DISCORD_APPLICATION_ID;
+        }
+        else {
+            process.env.DISCORD_APPLICATION_ID = originalAppId;
+        }
+    }
+});
+test("registerMetadata includes the response body in thrown errors", async () => {
+    const fetchImpl = (async () => new Response(JSON.stringify({ message: "Bad metadata" }), {
+        status: 400,
+    }));
+    const mini = new MiniInteraction({
+        applicationId: "app_123",
+        fetchImplementation: fetchImpl,
+    });
+    await assert.rejects(() => mini.registerMetadata("bot-token", [
+        {
+            key: "is_miniapp",
+            name: "Is Mini App?",
+            description: "Is the user an assistant?",
+            type: RoleConnectionMetadataTypes.BooleanEqual,
+        },
+    ]), /\[DiscordRestClient\] PUT \/applications\/app_123\/role-connections\/metadata failed: 400 {"message":"Bad metadata"}/);
+});

package/dist/core/http/DiscordRestClient.d.ts

@@ -1,4 +1,4 @@
-import type { APIChannel } from 'discord-api-types/v10';
+import type { APIChannel, RESTPutAPIApplicationRoleConnectionMetadataJSONBody, RESTPutAPIApplicationRoleConnectionMetadataResult } from 'discord-api-types/v10';
 import { DiscordSentMessage } from '../messages/DiscordSentMessage.js';
 import { type BaseDiscordMessageOptions, type DiscordReaction, type DiscordSendMessageOptions, type DiscordStartThreadOptions } from '../messages/message-payloads.js';
 import { DiscordWebhook } from '../webhooks/DiscordWebhook.js';
@@ -29,5 +29,6 @@ export declare class DiscordRestClient {
     startThread(options: DiscordStartThreadOptions): Promise<APIChannel>;
     addReaction(channelId: string, messageId: string, reaction: DiscordReaction): Promise<void>;
     webhook(id: string, token: string): DiscordWebhook;
+    putApplicationRoleConnectionMetadata(body: RESTPutAPIApplicationRoleConnectionMetadataJSONBody): Promise<RESTPutAPIApplicationRoleConnectionMetadataResult>;
 }
 export {};

package/dist/core/http/DiscordRestClient.js

@@ -48,13 +48,17 @@ export class DiscordRestClient {
             if (response.ok) {
                 if (response.status === 204)
                     return undefined;
-                return (await response.json());
+                const responseText = await response.text();
+                if (!responseText)
+                    return undefined;
+                return JSON.parse(responseText);
             }
             if (response.status >= 500 && attempt < this.maxRetries) {
                 await sleep(150 * (attempt + 1));
                 continue;
             }
-            lastError = new Error(`[DiscordRestClient] ${requestInit.method ?? 'GET'} ${path} failed: ${response.status}`);
+            const errorBody = await response.text();
+            lastError = new Error(`[DiscordRestClient] ${requestInit.method ?? 'GET'} ${path} failed: ${response.status}${errorBody ? ` ${errorBody}` : ''}`);
             break;
         }
         throw lastError instanceof Error ? lastError : new Error('[DiscordRestClient] unknown request failure');
@@ -127,6 +131,12 @@ export class DiscordRestClient {
     webhook(id, token) {
         return new DiscordWebhook(this, id, token);
     }
+    putApplicationRoleConnectionMetadata(body) {
+        return this.request(`/applications/${this.options.applicationId}/role-connections/metadata`, {
+            method: 'PUT',
+            body: JSON.stringify(body),
+        });
+    }
 }
 function getDefaultContentTypeHeader(body) {
     return body instanceof FormData ? {} : { 'Content-Type': 'application/json' };

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export { MiniDatabase } from "./database/MiniDatabase.js";
 export { generateOAuthUrl, getOAuthTokens, refreshAccessToken, getDiscordUser, ensureValidToken, } from "./oauth/DiscordOAuth.js";
 export type { OAuthConfig, OAuthTokens, DiscordUser, } from "./oauth/DiscordOAuth.js";
 export { OAuthTokenStorage } from "./oauth/OAuthTokenStorage.js";
+export type { DiscordLocale, LocalizationMap, RegisterMetadataResult, RoleConnectionMetadata, RoleConnectionMetadataInput, } from "./types/RoleConnectionMetadata.js";
 export { DiscordRestClient } from "./core/http/DiscordRestClient.js";
 export type { DiscordRestClientOptions } from "./core/http/DiscordRestClient.js";
 export { DiscordSentMessage } from "./core/messages/DiscordSentMessage.js";

package/dist/types/RoleConnectionMetadata.d.ts

@@ -0,0 +1,14 @@
+import type { APIApplicationRoleConnectionMetadata, Locale, RESTPutAPIApplicationRoleConnectionMetadataResult } from "discord-api-types/v10";
+import type { RoleConnectionMetadataTypes } from "./RoleConnectionMetadataTypes.js";
+export type DiscordLocale = `${Locale}`;
+export type LocalizationMap = Partial<Record<DiscordLocale, string>>;
+export type RoleConnectionMetadataInput = {
+    key: string;
+    name: string;
+    description: string;
+    type: RoleConnectionMetadataTypes;
+    name_localizations?: LocalizationMap;
+    description_localizations?: LocalizationMap;
+};
+export type RoleConnectionMetadata = APIApplicationRoleConnectionMetadata;
+export type RegisterMetadataResult = RESTPutAPIApplicationRoleConnectionMetadataResult;

package/dist/types/RoleConnectionMetadata.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minesa-org/mini-interaction",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).",
   "type": "module",
   "main": "dist/index.js",