cordo 2.5.1 → 2.6.0

package/README.md

@@ -1,97 +1,23 @@
 # Cordo
 
-Cordo is a custom api wrapper built for interactions first. It functions as an addon on top of discord.js. Full documentation is yet to be written
+Cordo is a developer-experience-first Discord App and UI library for TypeScript.
 
-Originally built for the FreeStuff Bot, this codebase could find various usecases so we decided to outsource it. Here's an [Example bot](https://github.com/Maanex/cordo-example-bot) written with it.
+Cordo is built for and used in production with over 700k discord servers at https://freestuffbot.xyz/.
 
-Or if you prefer real-life examples check out [FreeStuff Bot](https://github.com/FreeStuffBot/discord/tree/master/src/bot) or [Tudebot](https://github.com/Maanex/tudebot4/tree/master/src/cordo).
 
-Use `npm i cordo` or `yarn add cordo` to install. Types are included.
+## Concepts
 
+Cordo is taking inspiration from modern web-frameworks with concepts like **File Based Routing**, **Composables**, and **Error Boundaries**.
 
-## How it works (aka quick docs / tutorial)
+Cordo is also completely stateless allowing for incredibly easy load balancing, super light ram usage, and more. (This doesn't mean your bot cannot have state. It very well can.)
 
-### Commands
+Cordo also abstracts away a lot of constraints/burdens on Discord's interactions api like completely hiding and managing *custom_id*s and automatically laying out components into rows or labels.
 
-Go in bot/commands. They export a handler function as default which gets called when the command gets run.
+Cordo can be run as a standalone web-server (recommended) or integrated into existing Discord api libraries like discord.js.
 
-### Components
 
-Go in bot/components. They too export a handler function as default which gets called when the component gets interacted with (button press or dropdown selection).
-You can create folders to build hierarchy. Each folder prefixes the resulting component id with the foldername and a _
-For instance the handler in `components/foo/bar/test.ts` gets triggered for a component with the custom_id of `foo_bar_test`
+## Quick Start
 
-### States
+That's to do lol.
 
-States are an extra layer to the Commands and Components that let you define command pages. Instead of editing or sending a response to a Command or Component Interaction, you can just ask it to take form of a state and Cordo will do the rest.
-
-## Interaction flow
-
-User presses button -> Check if this interaction has any overrides on timeout -> Check if there are global Component handlers -> Check if there is a state with the same name to take -> Error
-
-User runs command -> Check if command handler exists -> Check if there is a state with the command name and _main -> Error
-
-
-## API Coverage
-
-✔️ Slash Commands
-
-✔️ Command Groups
-
-✔️ Command Autocomplete
-
-✔️ Button Components
-
-✔️ Dropdown Components
-
-❌ Modals
-
-
-## Naming Convensions
-
-Commands may only have one word -> no CamelCase or snake_case needed
-
-Components and States must be prefixed with the command they originated from -> A button on the settings command must start with settings_ (=> be placed inside a folder called settings)
-
-Components must be named by their desired state and not how to get there. Example: Settings command has a page with general settings (settings_main), which has a button for advanced settings (settings_advanced) which has a button to destroy the world.
-Incorrect naming: settings_advanced_destroy_world
-Correct naming: settings_destroy_world
-
-States also follow this principle to not inherit the path into the name, only the destination as shown above.
-
-Components that just change state (like "open another page") or have state changing behaviour must be named like states. Example: config_page2, config_name
-Components that have side effects (like changing settings or alike) must be named with a verb. Example: config_name_change, friends_request_send
-For those verbs preferably pick:
-* _change for Select/Dropdowns
-* _toggle for Toggle Buttons
-* _enable/_disable for Single Use Buttons
-
-### Examples
-
-Component and State names correct and incorrect examples:
-
-❌ back
-
-❌ back_button
-
-❌ state_back
-
-❌ settings_back
-
-❌ settings_advanced_more
-
-❌ command_free_button_one
-
-✔️ settings_main
-
-✔️ settings_description
-
-✔️ free_show_details
-
-✔️ settings_more
-
-## Best practices
-
-While theoretically the entire system could be built on soly using states, it is recomended to use interaction.reply and interaction.edit over states in non-interactive environments to save resources. States have a larger overhead than a simply interaction reply.
-
-Cordo is best when it's used stateless. Try to reduce interactive responses to a minimum and always put as much information as possible in the custom ids. This allows for easy scaling as well as a great user experience. It might take some time to get used to but once you understand how to build on this, cordo naturally organizes your code.
+If you wanna see how it looks like using cordo, check out the `./test` folder for some almost up to date demo project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordo",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "A framework for handling complex discord api interactions",
   "exports": {
     ".": "./src/index.ts",

package/src/components/builtin/row.ts

@@ -12,8 +12,16 @@ type AllowedComponentArray
 export function row(...components: AllowedComponentArray | [ AllowedComponentArray ]) {
   if (Array.isArray(components[0]))
     components = components[0]
-  return createComponent('ActionRow', ({ hirarchy, attributes }) => ({
-    type: ComponentType.ActionRow,
-    components: renderComponentList(components as AllowedComponentArray, 'ActionRow', hirarchy, attributes)
-  }))
+
+  return createComponent('ActionRow', ({ hirarchy, attributes }) => {
+    const rendered = renderComponentList(components as AllowedComponentArray, 'ActionRow', hirarchy, attributes)
+      .filter(Boolean)
+    if (!rendered.length)
+      return null
+
+    return {
+      type: ComponentType.ActionRow,
+      components: rendered
+    }
+  })
 }

package/src/core/files/config.ts

@@ -44,7 +44,7 @@ export type CordoConfig = {
     onNetworkError: HookFor<any>,
 
     /** transforms the name of the invoked command to a file or route name */
-    transformCommandName: TransformHookFor<string>,
+    transformCommandName: TransformHookFor<string, { type: 'slash' | 'message' | 'user' }>,
     /** gets called by all cordo builtin components that render user facing text. e.g. buttons, text components, selects, etc */
     transformUserFacingText: TransformHookFor<string, { component: StringComponentType, position: null | string, interaction?: CordoInteraction }>,
   }

package/src/core/files/route.ts

@@ -89,6 +89,13 @@ type RouteRequestFromModal = {
   selected: Map<string, string>
 }
 
+type InstallContext = {
+  /** true if the bot is installed in the current guild, non-exclusive */
+  isGuildInstalled: boolean
+  /** true if the bot is installed for the current user, non-exclusive */
+  isUserInstalled: boolean
+}
+
 export type RouteRequest = {
   params: Record<string, string>
   /** route path is the path to this route you are currently in */
@@ -97,6 +104,8 @@ export type RouteRequest = {
   currentPath: string
   rawInteraction: CordoInteraction
 
+  installContext: InstallContext
+
   locals: {
     get<T = any>(key: string): T | undefined
     set(key: string, value: any): void

package/src/core/gateway.ts

@@ -1,4 +1,4 @@
-import { ApplicationCommandType, ComponentType, InteractionResponseType, InteractionType, type APIInteraction } from "discord-api-types/v10"
+import { ApplicationCommandOptionType, ApplicationCommandType, ComponentType, InteractionResponseType, InteractionType, type APIInteraction } from "discord-api-types/v10"
 import type { Method } from "axios"
 import axios from "axios"
 import { FunctCompiler } from "../functions/compiler"
@@ -133,9 +133,26 @@ export namespace CordoGateway {
   }
 
   function handleCommandInteraction(i: CordoInteraction & { type: InteractionType.ApplicationCommand }) {
+    // slash commands: need to check for subcommands
     if (i.data.type === ApplicationCommandType.ChatInput) {
-      const name = i.data.name
-      const { route, path } = RoutingResolve.getRouteForCommand(name)
+      let name = i.data.name
+      let option = i.data.options?.[0]
+      while (option?.type === ApplicationCommandOptionType.Subcommand || option?.type === ApplicationCommandOptionType.SubcommandGroup) {
+        name += ` ${option.name}`
+        option = option.options?.[0]
+      }
+
+      const { route, path } = RoutingResolve.getRouteForCommand(name, 'slash')
+      CordoMagic.setCwd(path)
+      return RoutingRespond.callRoute(route.routeId, route.args, i)
+    }
+
+    // message/user commands: go ahead
+    if (i.data.type === ApplicationCommandType.Message || i.data.type === ApplicationCommandType.User) {
+      const { route, path } = RoutingResolve.getRouteForCommand(
+        i.data.name,
+        i.data.type === ApplicationCommandType.Message ? 'message' : 'user'
+      )
       CordoMagic.setCwd(path)
       return RoutingRespond.callRoute(route.routeId, route.args, i)
     }

package/src/core/routing/resolve.ts

@@ -133,10 +133,12 @@ export namespace RoutingResolve {
     }
   }
 
-  export function getRouteForCommand(command: string) {
+  export function getRouteForCommand(command: string, type: 'slash' | 'message' | 'user') {
     const fileName = Hooks.isDefined('transformCommandName')
-      ? Hooks.callHook('transformCommandName', command)
-      : command.replaceAll(' ', '-').replace(/[^\w-]/g, '').toLowerCase()
+      ? Hooks.callHook('transformCommandName', command, { type })
+      : type === 'slash'
+        ? command.replaceAll(' ', '/').toLowerCase() // slash commands: subcommands become subfolders
+        : command.replaceAll(' ', '-').replace(/[^\w-]/g, '').toLowerCase() // message/user commands: just sanitize
     const routePath = `command/${fileName}`
     return {
       route: getRouteFromPath(routePath, false),

package/src/core/routing/respond.ts

@@ -138,6 +138,11 @@ export namespace RoutingRespond {
       rawInteraction: interaction,
       rawEntitlements: interaction.entitlements,
 
+      installContext: {
+        isGuildInstalled: Boolean(interaction.authorizing_integration_owners[0]),
+        isUserInstalled: Boolean(interaction.authorizing_integration_owners[1]),
+      },
+
       locals: {
         get: <T = any>(key: string) => interaction.locals[key] as T,
         set: (key: string, value: any) => void (interaction.locals[key] = value),