@seedcord/kit 0.0.1

package/dist/index.mjs

@@ -0,0 +1,77 @@
+import { a as Notice, i as NoticeCard, o as BuilderComponent, s as RowComponent, t as CustomId } from "./CustomId-5Zl_LdzZ.mjs";
+
+//#region src/stops/Fault.ts
+/**
+* A generic fault you throw after catching an error you do not have a specific message for.
+*
+* The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to
+* `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`
+* to show the generic reply without the bus publish. The original error is stored as the standard
+* `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,
+* subclass {@link Notice} and write your own `render` instead.
+*
+* The framework also renders this for an unhandled throw, where it points the user at
+* `ctx.developerUsername`.
+*
+* @example
+* ```ts
+* import { Fault } from '@seedcord/kit';
+*
+* try {
+*     await db.write(record);
+* } catch (cause) {
+*     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook
+*     throw new Fault({ cause });
+*
+*     // pass report: false to show the same reply without publishing to the handledException bus
+*     // throw new Fault({ cause, report: false });
+* }
+* ```
+*/
+var Fault = class extends Notice {
+	constructor(options) {
+		super("A fault occurred", options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.report = options?.report ?? true;
+	}
+	render(ctx) {
+		return { components: [new NoticeCard(`Something went wrong. Please reach out to ${ctx.developerUsername ?? "the developer"} with a way to reproduce the error and the following:\n### UUID: \`${ctx.uuid}\``, "Error").component] };
+	}
+};
+
+//#endregion
+//#region src/stops/Silence.ts
+/**
+* Throw to stop a handler with no reply and no report.
+*
+* The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
+* Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
+* leave the user with no reply for an interaction.
+*
+* @example
+* ```ts
+* import { Silence } from '@seedcord/kit';
+*
+* // before any reply or defer, drop the interaction with no reply and no report
+* if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');
+* ```
+*/
+var Silence = class extends Error {
+	reason;
+	/**
+	* @param reason - Optional note written only to a debug log, never shown to the user or reported.
+	*/
+	constructor(reason) {
+		super(reason ?? "Silence");
+		this.reason = reason;
+		Error.captureStackTrace(this, this.constructor);
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/** Package version */
+const version = "0.0.1";
+
+//#endregion
+export { BuilderComponent, CustomId, Fault, Notice, RowComponent, Silence, version };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/stops/Fault.ts","../src/stops/Silence.ts","../src/index.ts"],"sourcesContent":["import { Notice } from './Notice';\nimport { NoticeCard } from './NoticeCard';\n\nimport type { RenderContext, ReplyResponse } from '@seedcord/types';\n\n/**\n * A generic fault you throw after catching an error you do not have a specific message for.\n *\n * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to\n * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`\n * to show the generic reply without the bus publish. The original error is stored as the standard\n * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,\n * subclass {@link Notice} and write your own `render` instead.\n *\n * The framework also renders this for an unhandled throw, where it points the user at\n * `ctx.developerUsername`.\n *\n * @example\n * ```ts\n * import { Fault } from '@seedcord/kit';\n *\n * try {\n *     await db.write(record);\n * } catch (cause) {\n *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook\n *     throw new Fault({ cause });\n *\n *     // pass report: false to show the same reply without publishing to the handledException bus\n *     // throw new Fault({ cause, report: false });\n * }\n * ```\n */\nexport class Fault extends Notice {\n    public constructor(options?: { cause?: unknown; report?: boolean }) {\n        super('A fault occurred', options?.cause === undefined ? undefined : { cause: options.cause });\n        this.report = options?.report ?? true;\n    }\n\n    public render(ctx: RenderContext): ReplyResponse {\n        const contact = ctx.developerUsername ?? 'the developer';\n        const card = new NoticeCard(\n            `Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\\n### UUID: \\`${ctx.uuid}\\``,\n            'Error'\n        );\n        return { components: [card.component] };\n    }\n}\n","/**\n * Throw to stop a handler with no reply and no report.\n *\n * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.\n * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to\n * leave the user with no reply for an interaction.\n *\n * @example\n * ```ts\n * import { Silence } from '@seedcord/kit';\n *\n * // before any reply or defer, drop the interaction with no reply and no report\n * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');\n * ```\n */\nexport class Silence extends Error {\n    /**\n     * @param reason - Optional note written only to a debug log, never shown to the user or reported.\n     */\n    public constructor(public readonly reason?: string) {\n        super(reason ?? 'Silence');\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n","export { BuilderComponent, RowComponent } from '@components/Component';\nexport { type RowType, type BuilderType } from '@components/builderTypes';\nexport { Notice } from '@stops/Notice';\nexport { Fault } from '@stops/Fault';\nexport { Silence } from '@stops/Silence';\nexport { CustomId } from '@customId/CustomId';\n\n/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,QAAb,cAA2B,OAAO;CAC9B,AAAO,YAAY,SAAiD;EAChE,MAAM,oBAAoB,SAAS,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EAC7F,KAAK,SAAS,SAAS,UAAU;CACrC;CAEA,AAAO,OAAO,KAAmC;EAM7C,OAAO,EAAE,YAAY,CAAC,IAJL,WACb,6CAFY,IAAI,qBAAqB,gBAEgB,qEAAqE,IAAI,KAAK,KACnI,OAEqB,CAAC,CAAC,SAAS,EAAE;CAC1C;AACJ;;;;;;;;;;;;;;;;;;;AC/BA,IAAa,UAAb,cAA6B,MAAM;CAII;;;;CAAnC,AAAO,YAAY,AAAgB,QAAiB;EAChD,MAAM,UAAU,SAAS;EADM;EAG/B,MAAM,kBAAkB,MAAM,KAAK,WAAW;CAClD;AACJ;;;;;AChBA,MAAa"}

package/dist/internal.index.cjs

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_CustomId = require('./CustomId-BuIoGHXw.cjs');
+
+//#region src/customId/routing.ts
+/**
+* The route decorators store a handler's customId definitions here so the component base can decode
+* against them at runtime.
+*
+* @internal
+*/
+const ComponentDefsKey = Symbol("seedcord:customId:componentDefs");
+
+//#endregion
+exports.ComponentDefsKey = ComponentDefsKey;
+exports.NoticeCard = require_CustomId.NoticeCard;
+exports.decodeFor = require_CustomId.decodeFor;
+exports.prefixOf = require_CustomId.prefixOf;
+exports.setBotColor = require_CustomId.setBotColor;
+//# sourceMappingURL=internal.index.cjs.map

package/dist/internal.index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.index.cjs","names":[],"sources":["../src/customId/routing.ts"],"sourcesContent":["import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;;;;;;;;AAQA,MAAa,mBAAmB,OAAO,iCAAiC"}

package/dist/internal.index.d.cts

@@ -0,0 +1 @@
+export type * from './internal.index.d.mts'

package/dist/internal.index.d.mts

@@ -0,0 +1,36 @@
+import { a as DecodedParams, i as prefixOf, o as BuilderComponent, r as decodeFor, t as AnyCustomId } from "./CustomId-CbTZuUup.mjs";
+import { ColorResolvable } from "discord.js";
+
+//#region src/botColorHolder.d.ts
+/** @internal */
+declare function setBotColor(color: ColorResolvable | undefined): void;
+//#endregion
+//#region src/customId/routing.d.ts
+/**
+ * The route decorators store a handler's customId definitions here so the component base can decode
+ * against them at runtime.
+ *
+ * @internal
+ */
+declare const ComponentDefsKey: unique symbol;
+/**
+ * The phantom a component handler base carries. A route decorator constrains its argument to this, so
+ * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.
+ *
+ * @internal
+ */
+interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {
+  readonly __componentDefs?: Defs;
+}
+//#endregion
+//#region src/stops/NoticeCard.d.ts
+/**
+ * Built fresh inside a {@link Notice}'s `render` to back its ComponentsV2 reply. The title renders as
+ * an h3 line with the description on the next line.
+ */
+declare class NoticeCard extends BuilderComponent<'container'> {
+  constructor(description: string, title?: string);
+}
+//#endregion
+export { type AnyCustomId, ComponentDefsKey, type DecodedParams, type HasComponentDefs, NoticeCard, decodeFor, prefixOf, setBotColor };
+//# sourceMappingURL=internal.index.d.mts.map

package/dist/internal.index.mjs

@@ -0,0 +1,14 @@
+import { c as setBotColor, i as NoticeCard, n as decodeFor, r as prefixOf } from "./CustomId-5Zl_LdzZ.mjs";
+
+//#region src/customId/routing.ts
+/**
+* The route decorators store a handler's customId definitions here so the component base can decode
+* against them at runtime.
+*
+* @internal
+*/
+const ComponentDefsKey = Symbol("seedcord:customId:componentDefs");
+
+//#endregion
+export { ComponentDefsKey, NoticeCard, decodeFor, prefixOf, setBotColor };
+//# sourceMappingURL=internal.index.mjs.map

package/dist/internal.index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.index.mjs","names":[],"sources":["../src/customId/routing.ts"],"sourcesContent":["import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;;;;;;;AAQA,MAAa,mBAAmB,OAAO,iCAAiC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@seedcord/kit",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Reusable Seedcord building blocks: component builders, the Notice error tree, and the typed customId codec",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seedcord/seedcord.git",
+    "directory": "packages/kit"
+  },
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.index.d.mts",
+        "default": "./dist/internal.index.mjs"
+      },
+      "require": {
+        "types": "./dist/internal.index.d.cts",
+        "default": "./dist/internal.index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "discord.js": "^14.26.4",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@seedcord/errors": "0.0.1",
+    "@seedcord/types": "0.5.0"
+  },
+  "devDependencies": {
+    "discord.js": "^14.26.4",
+    "type-fest": "^5.7.0",
+    "vite": "^8.0.16",
+    "@seedcord/tsconfig": "2.0.0",
+    "@seedcord/tsdown-config": "2.0.0",
+    "@seedcord/eslint-config": "1.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "lint": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}' --cache",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}' --fix --cache",
+    "fmt": "prettier --write 'src/**/*.{ts,tsx,json,md}' 'tests/**/*.{ts,tsx,json,md}' --cache",
+    "fmt:check": "prettier --check 'src/**/*.{ts,tsx,json,md}' 'tests/**/*.{ts,tsx,json,md}' --cache",
+    "tc": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest dev",
+    "coverage": "vitest run --coverage"
+  },
+  "readme": "<p align=\"center\">\n  <img src=\"https://cdn.seedcord.org/assets/banner.webp\" alt=\"seedcord\" width=\"100%\" />\n</p>\n\n---\n\n_This repository is a work in progress._\n\n- There are no stable releases yet but changes are being made actively.\n- Till a major v1.0.0 release for seedcord, expect breaking changes in minor versions.\n- Documentation will come soon as well!\n\nIf you'd like to try it out, you can check out the code in `mock`\n"
+}