Skip to content
Slingshot

Overview

@lastshotlabs/slingshot-interactions provides the dispatch layer for interactive components such as buttons, menus, and action payloads emitted from chat or community surfaces. It compiles declarative handler templates, stores interaction events, and exposes one dispatch endpoint for component actions.

When To Use It

Section titled “When To Use It”

Use this package when your app needs:

  • a single backend route for dispatching interactive component actions
  • audited interaction events stored as entities
  • declarative routing of actions to webhooks, routes, or queues
  • optional integration with Slingshot chat and community packages

Do not use it as a generic job queue. This package is specifically for user-triggered interaction dispatch.

What You Need Before Wiring It In

Section titled “What You Need Before Wiring It In”

createInteractionsPackage() depends on:

  • slingshot-auth
  • slingshot-permissions

The package throws during setup if shared permissions state is missing.

Minimum Setup

Section titled “Minimum Setup”

Defaults are:

  • mountPath: '/interactions'
  • rateLimit.windowMs: 60_000
  • rateLimit.max: 20
  • handlers: {}

The main required work is defining handlers, which map action prefixes to compiled dispatch targets.

What You Get

Section titled “What You Get”

The package mounts:

  • POST {mountPath}/dispatch
  • entity-backed read routes for interactionEvents

It also:

  • compiles declarative handler templates once at package construction time
  • publishes package state under INTERACTIONS_PLUGIN_STATE_KEY
  • registers client-safe bus events for interactions:event.dispatched and interactions:event.failed
  • probes chat and community peers when present so interactions can integrate cleanly with those packages

Common Customization

Section titled “Common Customization”

The main knobs are:

  • mountPath
  • rateLimit
  • handlers, keyed by action prefix

If you need to extend the system, start in:

  • src/config/schema.ts for config shape and defaults
  • src/handlers/ for template compilation and dispatcher behavior
  • src/routes/dispatchRoute.ts for the public dispatch endpoint
  • src/peers/ for chat and community integration points

Gotchas

Section titled “Gotchas”
  • The longest matching handler prefix wins. Action naming conventions matter because routing is prefix-based, not exact-match only.
  • The package owns an interaction-event entity surface in addition to the dispatch route. If you remove that entity layer, you also remove auditability.
  • Chat and community integrations are optional probes, not hard dependencies. Your handlers should still behave sensibly when those peers are absent.
  • Runtime handler registration overlays the compiled config. Treat that as an extension path, not a substitute for keeping createInteractionsPackage({ handlers }) accurate.

Key Files

Section titled “Key Files”
  • src/index.ts
  • src/plugin.ts
  • src/config/schema.ts
  • src/components/schema.ts
  • src/handlers/compile.ts
  • src/routes/dispatchRoute.ts
  • src/entities/interactionEvent.ts