···11+# Lure
22+33+Lure is a library for processing webhook events into LLM-consumable prompts. It
44+looks something like this:
55+66+1. An HTTP request is received at a path like `/webhooks/tangled`
77+2. Lure matches the path to a template file on disk, e.g.
88+ `./lures/tangled.lure`. The `.lure` file is part config, part template (more
99+ on this later).
1010+3. According to the config, Lure validates the webhook according to the
1111+ specified strategy (e.g. API key or HMAC verification)
1212+4. If validation succeeds, Lure executes some callback with the string result of
1313+ evaluating the template contents with the webhook payload.
1414+1515+The goal is to trigger LLM executions in response to webhook events, but without
1616+the requirement for Zapier/IFTTT and with as little HTTP endpoint exposure as
1717+possible. Consumers of the Lure library provide their own HTTP server--no server
1818+is provided by Lure.
1919+2020+## `.lure` file format
2121+2222+Lures are intended to be written by LLMs, so a `.lure` file is essentially a
2323+Markdown file with frontmatter. Here is a contrived example:
2424+2525+```md
2626+---
2727+register: manual
2828+verify:
2929+ hmac:
3030+ location: header
3131+ name: X-My-Header-Signature
3232+ secret: $MY_WEBHOOK_SECRET
3333+payload:
3434+ contentType: json
3535+ schema: https://example.com/schema
3636+config:
3737+ arbitrary: true
3838+ someValue: 3
3939+---
4040+4141+You have received information about a <%= it.payload.event => event on My
4242+Service. Read the following payload and respond according to your skills:
4343+4444+<%= it.payload.body %>
4545+```
4646+4747+Different registration and verification methods can be supported, for generic
4848+implementations or vendor-specific requirements. Only one verification method
4949+can be specified per lure.
5050+5151+## Usage
5252+5353+Use either the `@lure/fetch` or `@lure/express` packages to construct an
5454+endpoint handler that suits your HTTP server of choice.
5555+5656+Both handler constructors take the following parameters:
5757+5858+- `configSchema`: A Standard Schema for validating any extra config you would
5959+ like to allow in the `config` frontmatter key
6060+- `luresDir`: A path to a directory of lures
6161+- `callback`: A function that you want to run in response to incoming webhooks.
6262+ It will be called with the templated prompt `prompt` and the value of the
6363+ `config` frontmatter value.
6464+6565+## Lifecycle
6666+6767+### At Startup
6868+6969+1. The parent program creates either a fetch or an Express lure handler, as
7070+ described above.
7171+2. Lure traverses the specified directory and discovers any `.lure` files.
7272+3. Each `.lure` file has their frontmatter validated. The parsed config and
7373+ template content are cached.
7474+7575+### Per Request
7676+7777+1. The requested path is checked against registered lure paths.
7878+2. On a hit, we immediately return a 204 response, to keep the response
7979+ time as low as possible.
8080+3. Webhook requests are copied and added to a queue for processing.
8181+3. The queue processor removes requests from the queue FIFO. If verification
8282+ fails, the request is dropped.
8383+4. On successful verification, the lure template is evaluated using the
8484+ request.
8585+5. Finally, the provided `callback` is executed with the fully-formed prompt,
8686+ and the config object from the original `.lure` frontmatter.
···11+# `@lure/core`
22+33+Core implementation for working with lures. This includes:
44+55+- Frontmatter validation
66+- Verification logic
77+- Template management
88+99+Not intended to be used directly; use `@lure/fetch` or `@lure/express` instead.