cordo 2.6.1 → 2.7.0

package/README.md

@@ -18,6 +18,281 @@ Cordo can be run as a standalone web-server (recommended) or integrated into exi
 
 ## Quick Start
 
-That's to do lol.
+### 1. Install via bun
+
+`bun add cordo`
+
+<details>
+<summary>Other runtimes</summary>
+
+Cordo should also be able to run on Deno.
+
+Cordo should also be able to run on Node with experimental native TypeScript support enabled.
+
+> [!NOTE]
+> The `plugin/hono` package uses Bun specific apis. This should not be an issue since the package must be explicitly imported but keep it in mind if you use hono in a non-bun environment.
+</details>
+
+
+### 2. Add to your project
+
+First you need to mount cordo by running `await Cordo.mountCordo()`. This step reads the cordo config and lock files and enables the file tree searching.
+
+Second you need to pass incoming events to cordo, depending on the rest of your project this might look slightly different:
+
+<details>
+<summary>Using express (http)</summary>
+
+```ts
+import { useWithExpress } from 'cordo/plugin/express'
+const app = express()
+const clientPublicKey = 'your discord public key'
+app.use(useWithExpress(clientPublicKey))
+app.listen(5058, () => console.log('Cordo is running on port 5058'))
+```
+</details>
+
+<details>
+<summary>Using hono (http)</summary>
+
+```ts
+import { useWithHono } from 'cordo/plugin/hono'
+const app = new Hono()
+const clientPublicKey = 'your discord public key'
+app.use('/cordo', useWithHono(clientPublicKey))
+return app
+```
+</details>
+
+<details>
+<summary>Using discord.js</summary>
+
+```ts
+import { useWithDiscordJs } from 'cordo/plugin/djs'
+const client = new Client({ ... })
+useWithDiscordJs(client)
+client.login()
+```
+</details>
+
+<details>
+<summary>Manually triggering (not recommended)</summary>
+
+```ts
+// Pass the raw body as a node buffer:
+Cordo.triggerInteraction(req.body, {
+  // The httpCallback, if provided, is called on the first response to the interaction. Use this if you are receiving events via http, omit otherwise.
+  httpCallback: (payload: any) => res.status(200).json(payload)
+})
+```
+</details>
+
+### 3. Create cordo.config.ts
+
+This is your primary configuration file. You can use the example from below as a starting point.
+
+```ts
+import { defineCordoConfig } from 'cordo/core'
+
+
+export default defineCordoConfig({
+  // the root directory for cordo to search through
+	rootDir: './src',
+  // the file for cordo to store the generated types
+	typeDest: './src/types/cordo.ts',
+	client: {
+    // your app's id
+		id: '123456789'
+	}
+})
+```
+
+### 4. Create your first route
+
+1. Create a folder called `routes` inside your rootDir.
+2. Create a folder called `command` inside the routes folder.
+3. Create a file named after your slash command inside the command folder.
+4. Export a cordo route handler as the default export:
+
+```ts
+
+export default defineCordoRoute((i) => {
+	i.render(
+    text('My first command')
+  )
+})
+```
+
+## Concepts
+
+### File based routing
+
+For each interaction flow cordo is keeping track of a route, the webdev equivalent of a url. This means everything you do with cordo revolves around navigating to different routes.
+
+As an entry point you will always have `command/...` routes.
+- A slash command `/foo` will have the route `command/foo` (and it's handler at `routes/command/foo.ts`)
+- A slash command with subcommand `/foo bar` will have the route `command/foo/bar`
+- Context commands are converted to lowercase, spaces replaced with `-` and all other non-word characters removed. Example: `Add user :3` will have the route `command/add-user-3`
+- Advanced: You can use the `transformCommandName` hook in your cordo.config to use custom logic
+
+You will primarily use these two situations to switch routes:
+
+#### 1. Route level redirects
+
+You can redirect directly upon calling the route like so
+
+```ts
+export default defineCordoRoute((i) => {
+	i.goto('my/route')
+})
+```
+
+Which can be useful to route commands to their proper location. You can also use this to gate specific routes to specific conditions.
+
+```ts
+export default defineCordoRoute((i) => {
+  if (!isAdmin(i.user)) {
+	  return i.goto('my/route')
+  }
+
+  // or else...
+})
+```
+
+#### 2. In response to user input
+
+For all interactable components you can define a list of "functs" - which are special micro functions - to execute when the component is interacted with.
+
+This includes buttons
+
+```ts
+i.render(
+  button()
+    .onClick(...)
+)
+```
+
+Select menus
+
+```ts
+i.render(
+  selectString()
+    .addOption({
+      label: 'test',
+      onClick: [ ... ]
+    })
+)
+```
+
+And modals:
+
+```ts
+i.prompt(
+  modal(...)
+    .onClick(...)
+)
+```
+
+The primary functs you will be using are run and goto.
+
+`goto` does a route change and will navigate the user to the specified route.
+
+```ts
+i.render(
+  button()
+    .label('See more')
+    .onClick(goto('./more'))
+)
+```
+
+This is a good moment to mention that all routes support relative paths. You can use `absolute/routes`, `./relative`, and `../upwards` like you're used to from file systems.
+
+`run` is similar to goto as it will execute the code in the location specified, yet it will not allow the route to render anything. You can use this paradigm to have purely functional routes and ones that serve ui.
+
+```ts
+i.render(
+  button()
+    .label('Save preferences')
+    .onClick(
+      run('utils/save-user-to-db', {
+        wait: true,
+        continueOnError: false
+      }),
+      goto('.')
+    )
+)
+```
+
+In this case we're running the route at `routes/utils/save-user-to-db.ts` and waiting for it to finish (this route might be async). If anything goes wrong we will abort and let the nearest error boundary handle it (we will get to this). Once done we will navigate to `.` which is the current route, forcing cordo to re-render the one we are at right now.
+
+The function at `utils/save-user-to-db` might use "locals" to attach information to the interaction such that the current route can display the successful database save.
+
+```ts
+// routes/utils/save-user-to-db.ts
+export default defineCordoRoute(await (i) => {
+  try {
+    // ... save to database ...
+
+    // set a local variable
+    i.locals.set('message', 'Successfully saved to database!')
+  } catch (ex) {
+    // this will abort the interaction and trigger an error boundary
+    throw new CordoError('Database saving failed', ex.message)
+  }
+})
+```
+
+```ts
+// current route
+export default defineCordoRoute((i) => {
+  i.render(
+    // Retreive the message from locals
+    text(`A message: ${i.locals.get('message')}`)
+      // Only show if there is a message in the locals
+      .visible(i.locals.has('message')),
+
+    // The very button to trigger it all
+    button()
+      .label('Save preferences')
+      .onClick(
+        run('utils/save-user-to-db', {
+          wait: true,
+          continueOnError: false
+        }),
+        goto('.')
+      )
+  )
+})
+```
+
+This almost recursive approach might take a second to get used to but it allows for some very powerful composability and is highly scaleable.
+
+Please note that cordo is stateless, this means the locals are only present for the single interaction they are written to and are not there once a follow up interaction happens. You can use route parameters to store dynamic information or use an external state management that works with your deployment.
+
+#### Parameters in routes
+
+You can use parameters in your routes like so:
+
+* `routes/profile/[userid]/index.ts` -> matches `profile/12345678`
+* `routes/profile/[userid]/friendlist.ts` -> matches `profile/12345678/friendlist`
+* `routes/profile/[userid]/friendlist/[friend].ts` -> matches `profile/12345678/friendlist/481279874192`
+
+You can access params using `i.params`.
+
+A single `[parameter]` only captures a single string until the end of the route string or until the next forward slash.
+
+Cordo's routing does not allow routes to have `..` for navigating up anywhere besides the beginning of the route. This means you can safely use template strings in your routes if you prefix them with something.
+- Good: `shop/category/${...}`
+- Bad: `${...}/info`
+
+`.ts` files starting with _ are ignored and can be used for hosting utilities.
+
+
+### Oh yeah, error boundaries
+
+If an error is thrown cordo will first check the folder of the file for the current route and check for a file called `error.ts` exporting `export default defineCordoErrorBoundary((error, req) => ...)`. If none is found it will go up one folder and repeat until the routes folder is left at which point cordo will use it's built-in error handler.
+
+- The search starts at the folder of the file for the current route. This means if you trigger a different route using `run` the cwd is not changed and the error handler stays the same. If you use `goto` the cwd is changed to the new route and such is the error handler.
+- An error handler can at any point `throw` the error again to escalate it to a higher up error handler.
+- An error handler can handle the interaction just like a normal route handler including: accessing locals and re-routing to non-error routes.
 
-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.6.1",
+  "version": "2.7.0",
   "description": "A framework for handling complex discord api interactions",
   "exports": {
     ".": "./src/index.ts",

package/src/components/component.ts

@@ -163,8 +163,8 @@ export function renderComponentList(
   }
 
   for (const mod of modifiers) {
-    if (mod.hooks?.preRender)
-      pipeline = mod.hooks.preRender(pipeline)
+    if (mod.hooks?.beforeRender)
+      pipeline = mod.hooks.beforeRender(pipeline)
   }
 
   let output = pipeline
@@ -172,8 +172,8 @@ export function renderComponentList(
     .filter(Boolean)
 
   for (const mod of modifiers) {
-    if (mod.hooks?.postRender)
-      output = mod.hooks.postRender(output)
+    if (mod.hooks?.afterRender)
+      output = mod.hooks.afterRender(output)
   }
 
   return output

package/src/components/index.ts

@@ -29,6 +29,7 @@ export { debugIdToLabel } from './mods/debug-id-to-label'
 export { debugPrint } from './mods/debug-print'
 export { debugRoute } from './mods/debug-route'
 export { disableAllComponents } from './mods/disable-all-components'
+export { enforcePrivateResponse } from './mods/enforce-private-response'
 
 export type { CordoComponent, StringComponentType } from './component'
 

package/src/components/modifier.ts

@@ -1,3 +1,6 @@
+import type { CordoInteraction } from "../core"
+import type { RouteResponse } from "../core/files/route"
+import type { RoutingRespond } from "../core/routing/respond"
 import type { CordoComponentPayload, renderComponentList, StringComponentType } from "./component"
 
 
@@ -8,8 +11,9 @@ export type CordoModifier = {
     name: string
     hooks?: {
       onRender?: (c: CordoComponentPayload<StringComponentType>) => CordoComponentPayload<StringComponentType>
-      preRender?: (c: Array<CordoComponentPayload<StringComponentType>>) => Array<CordoComponentPayload<StringComponentType>>
-      postRender?: (c: ReturnType<typeof renderComponentList>) => ReturnType<typeof renderComponentList>
+      beforeRender?: (c: Array<CordoComponentPayload<StringComponentType>>) => Array<CordoComponentPayload<StringComponentType>>
+      afterRender?: (c: ReturnType<typeof renderComponentList>) => ReturnType<typeof renderComponentList>
+      beforeRouteResponse?: (response: RouteResponse, i: CordoInteraction, opts: RoutingRespond.RouteOpts) => void
     }
   }
 }
@@ -18,6 +22,10 @@ export function createModifier(value: CordoModifier[typeof CordoModifierSymbol])
   return { [CordoModifierSymbol]: value }
 }
 
+export function isModifier(t: Record<string, any>): t is CordoModifier {
+  return !!t && CordoModifierSymbol in t
+}
+
 export function readModifier(mod: CordoModifier): CordoModifier[typeof CordoModifierSymbol] {
   return mod[CordoModifierSymbol]!
 }

package/src/components/mods/debug-id-to-label.ts

@@ -19,7 +19,7 @@ export function debugIdToLabel() {
   return createModifier({
     name: 'debug-id-to-label',
     hooks: {
-      postRender: (c) => {
+      afterRender: (c) => {
         searchForButton(c)
         return c
       }

package/src/components/mods/debug-print.ts

@@ -5,7 +5,7 @@ export function debugPrint() {
   return createModifier({
     name: 'debug-print',
     hooks: {
-      postRender: (c) => {
+      afterRender: (c) => {
         console.log(JSON.stringify(c, null, 2))
         return c
       }

package/src/components/mods/debug-route.ts

@@ -8,7 +8,7 @@ export function debugRoute() {
   return createModifier({
     name: 'debug-route',
     hooks: {
-      preRender: (c) => {
+      beforeRender: (c) => {
         const routeText = text(CordoMagic.getCwd()).size('small')
         return [ ...c, readComponent(routeText) ]
       },

package/src/components/mods/disable-all-components.ts

@@ -28,7 +28,7 @@ export function disableAllComponents(disable = true) {
   return createModifier({
     name: 'disable-all-components',
     hooks: {
-      postRender: (c) => {
+      afterRender: (c) => {
         if (disable)
           iterateComponents(c)
         return c

package/src/components/mods/enforce-private-response.ts

@@ -0,0 +1,13 @@
+import { createModifier } from "../modifier"
+
+
+export function enforcePrivateResponse() {
+  return createModifier({
+    name: 'enforce-private-response',
+    hooks: {
+      beforeRouteResponse: (_res, _i, opts) => {
+        opts.isPrivate = true
+      }
+    }
+  })
+}

package/src/core/routing/respond.ts

@@ -1,13 +1,13 @@
-import { ApplicationCommandType, InteractionContextType, InteractionResponseType, InteractionType, MessageFlags, type APIUser } from "discord-api-types/v10"
+import { ApplicationCommandOptionType, ApplicationCommandType, InteractionContextType, InteractionResponseType, InteractionType, MessageFlags, type APIUser } from "discord-api-types/v10"
 import { disableAllComponents } from "../../components"
-import { ComponentType, isComponent, renderComponent, renderComponentList, type CordoComponent } from "../../components/component"
+import { ComponentType, renderComponent, renderComponentList, type CordoComponent } from "../../components/component"
 import type { RouteInternals, RouteRequest, RouteResponse } from "../files/route"
 import { InteractionInternals, type CordoInteraction } from "../interaction"
 import { CordoMagic } from "../magic"
 import { CordoGateway } from "../gateway"
 import { FunctInternals } from "../../functions/funct"
 import { goto, run } from "../../functions"
-import type { CordoModifier } from "../../components/modifier"
+import { isModifier, readModifier } from "../../components/modifier"
 import { FunctCompiler } from "../../functions/compiler"
 import { RoutingResolve } from "./resolve"
 
@@ -27,16 +27,11 @@ export namespace RoutingRespond {
   //
 
   export function renderRouteResponse(response: RouteResponse, i: CordoInteraction, opts: RouteOpts = {}) {
-    const modifiers: CordoModifier[] = []
-
     for (const item of response) {
-      if (!isComponent(item)) 
-        modifiers.push(item)
+      if (isModifier(item))
+        readModifier(item).hooks?.beforeRouteResponse?.(response, i, opts)
     }
 
-    //
-    // TODO modifiers
-
     if (opts.disableComponents)
       response.push(disableAllComponents())
 
@@ -91,6 +86,16 @@ export namespace RoutingRespond {
     return out
   }
 
+  function parseCommandOptions(options: any) {
+    if (!options)
+      return {}
+
+    if (options.length === 1 && options[0].type === ApplicationCommandOptionType.SubcommandGroup)
+      return parseCommandOptions(options[0].options)
+    
+    return (options as Record<string, any>[]).reduce((out, opt) => ({ [opt.name]: opt.value, ...out }), {})
+  }
+
   export function buildRouteRequest(
     route: RouteInternals.ParsedRoute,
     args: string[],
@@ -199,7 +204,7 @@ export namespace RoutingRespond {
           // @ts-ignore
           id: interaction.data.id,
           // @ts-ignore
-          options: interaction.data.options?.reduce((out, opt) => ({ [opt.name]: opt.value, ...out }), {}) ?? {},
+          options: parseCommandOptions(interaction.data.options),
           // @ts-ignore
           type: (interaction.data.type === ApplicationCommandType.ChatInput)
             ? 'chat'