@reventlessdev/reventless-spec 3.0.0-alpha.166 → 3.0.0-alpha.167

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.167 (2026-10-16)
+
+* feat!(inbound): a translation slice can declare a signed webhook URL ([0ad6994](https://github.com/ReventlessDev/reventless-core/commit/0ad69949fcc91c2756c60ca8cb120dd468841d8b))
+
+### BREAKING CHANGES
+
+* InboundTranslationSlice.Spec requires `endpoint`. Specs under
+@@reventless.spec get it from the PPX (republish reventless-ppx with this
+release); hand-written specs add `let endpoint = None`.
+
+
+
 # 3.0.0-alpha.166 (2026-10-16)
 
 * fix(auth)!: only operators read the framework's own stores ([a2fd202](https://github.com/ReventlessDev/reventless-core/commit/a2fd2022b6876dae855b185df7f8263353fc971d))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.166",
+  "version": "3.0.0-alpha.167",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/InboundTranslationSlice.res

@@ -6,6 +6,51 @@ through `operations.receive` rather than by events.
 `Spec` holds the types, schemas and target; `Translation` the `translate` function.
 The slice moves no lifecycle of its own — its target owns that.
 */
+/**
+How a sender proves a webhook request is theirs: an HMAC-SHA256 over the raw
+body, hex-encoded, in `header` (after `prefix`, e.g. `"sha256="`). With
+`timestampHeader`, the signed text is `<timestamp>.<body>` and a timestamp more
+than `toleranceSeconds` (default 300) from now is refused, so a captured request
+cannot be replayed later. `secret` names the shared secret, never its value: the
+platform reads it from `REVENTLESS_WEBHOOK_SECRET_<SECRET>`, which may list
+several, comma-separated, while one is being rotated.
+*/
+type signature = {
+  header: string,
+  prefix?: string,
+  timestampHeader?: string,
+  toleranceSeconds?: int,
+  secret: string,
+}
+
+/** Who may call a webhook. `Open` admits anybody, as an anonymous caller. */
+type webhookAuth =
+  | Open
+  | SignedBody(signature)
+
+type webhookMethod =
+  | @as("POST") Post
+  | @as("PUT") Put
+
+/** How the URL is served. On AWS, a Lambda Function URL on the plugin's command
+    handler, every slice's webhook a path under it. */
+type webhookTransport = FunctionUrl
+
+/**
+A URL beside the slice's mutation, for a sender that only posts JSON to an
+address. `path` is the slice's segment under the plugin's webhook base URL. A
+request that passes `auth` acts as a signed-in caller holding `role` (none when
+absent); each command it translates into is checked against its own rule, as on
+the mutation.
+*/
+type endpointConfig<'role> = {
+  path: string,
+  method?: webhookMethod,
+  auth: webhookAuth,
+  role?: 'role,
+  transport?: webhookTransport,
+}
+
 module type Spec = {
   /** Logical name of this inbound translation slice (used as a component prefix). */
   let name: string
@@ -34,6 +79,10 @@ module type Spec = {
       then checked against its own, and one refused refuses the whole input.
       Defaults to `AllowAuthenticated`. */
   let authorizationOf: string => Authorization.rule<role>
+
+  /** The slice's webhook URL, if it has one. Injected as `None` by
+      `@@reventless.spec`. */
+  let endpoint: option<endpointConfig<role>>
 }
 
 /** The synchronous translate function. */