@venn-lang/notify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @venn-lang/notify
+
+> The `notify` namespace: send a Slack message, a webhook or an email from a flow.
+
+A run that fails at 3am is only useful if somebody hears about it. This plugin gives a flow three
+dispatch verbs and routes all of them through the `Notifier` port, so the transport is chosen by the
+host at startup. Under test that means a recorder you can assert against, with nothing leaving the
+machine.
+
+## Install
+
+Nothing to install. `@venn-lang/notify` is part of the standard library, and the CLI and the language
+server both load [`@venn-lang/stdlib`](../stdlib), which lists every stdlib plugin. A file reaches the
+namespace with one line.
+
+```ruby
+use "venn/notify"
+```
+
+## Usage
+
+```ruby
+module demo.checkout
+
+use "venn/notify"
+use "venn/assert"
+
+flow "Checkout" {
+  step "place the order" {
+    expect true
+  }
+
+  on failure {
+    notify.slack "#qa" { mention: "@oncall" }
+  }
+}
+```
+
+## Verbs
+
+| Verb | Call | Options |
+| --- | --- | --- |
+| `notify.slack` | `notify.slack "#qa"` | `mention` |
+| `notify.webhook` | `notify.webhook "https://hook.test/build"` | `json` |
+| `notify.email` | `notify.email "qa@example.com"` | `subject`, `body` |
+
+Each verb takes its destination as the one positional argument, the channel for Slack, the URL for a
+webhook, the recipient for an email, and everything else as options:
+
+```ruby
+const posted  = notify.slack "#builds" { mention: "@oncall" }
+const hooked  = notify.webhook "https://hook.test/build" { json: { status: "green" } }
+const mailed  = notify.email "qa@example.com" { subject: "Nightly", body: "All green." }
+
+expect posted.delivered == true
+```
+
+All three return `notify.Receipt`.
+
+## The type it publishes
+
+`notify.Receipt` is a record of `delivered: bool` and `id: string`. `delivered` is the dispatch, not
+the reading: nobody here knows whether a human saw it.
+
+## The Notifier port
+
+| | |
+| --- | --- |
+| id | `venn.port.notifier` |
+| version | 1 |
+| requires | `net` |
+| methods | `send` |
+
+Two implementations ship together, which is what makes this a port rather than a module with a good
+interface:
+
+- `createFakeNotifier()` records every notification in memory and returns
+  `{ delivered: true, id: "fake-<n>" }`. It is a `FakeNotifier`, so the recorded messages are
+  readable through `sent`. This is the one [`@venn-lang/stdlib`](../stdlib) binds.
+- `createRealNotifier()` is a stub. Every call throws a `VennError` with code `VN8090`, because this
+  repository is the language and ships no live Slack, webhook or SMTP wiring.
+
+Both run the same conformance suite, `notifierConformance` in `src/clients/notifier.suite.ts`: a
+`send` resolves a receipt with a boolean `delivered` and a string `id`.
+
+Asserting on what a flow sent, from TypeScript:
+
+```ts
+import { createFakeNotifier } from "@venn-lang/notify";
+
+const notifier = createFakeNotifier();
+await notifier.send({ kind: "slack", channel: "#qa", mention: "@vini" });
+
+expect(notifier.sent[0]).toMatchObject({ kind: "slack", channel: "#qa" });
+```
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `notifyPlugin` | The plugin definition: namespace `notify`, `requires: ["net"]`. Also the default export. |
+| `notifyActions` | The three action definitions, in order: `slack`, `webhook`, `email`. |
+| `NotifierPort` | The port descriptor. |
+| `Notifier` | The port interface: `send(message)`. |
+| `FakeNotifier` | A `Notifier` that also exposes `sent`, the notifications it recorded. |
+| `Notification` | What is handed to the port: `kind`, `channel`, and the optional `subject`, `body`, `mention`, `json`. |
+| `NotificationKind` | `"slack" \| "webhook" \| "email"`. |
+| `NotifyReceipt` | What the port returns: `{ delivered, id }`. |
+| `createFakeNotifier()` | The recording double. |
+| `createRealNotifier()` | The real notifier, stubbed to throw `VN8090`. |
+
+Binding a different notifier means one entry in the runner's port list:
+
+```ts
+import { createRunner } from "@venn-lang/runtime";
+import { createFakeNotifier, NotifierPort } from "@venn-lang/notify";
+
+const runner = createRunner({
+  host,
+  plugins,
+  sink,
+  uri,
+  ports: [{ port: NotifierPort, impl: createFakeNotifier() }],
+});
+```
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `definePlugin` and `defineAction`.
+- [`@venn-lang/contracts`](../contracts) for `Port`, `assertPortShape` and `VennError`.
+- [`@venn-lang/artifacts`](../std-artifacts) for the traces and videos a failure leaves behind.

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+import { Port } from "@venn-lang/contracts";
+//#region src/actions/index.d.ts
+/** Every verb in the `notify` namespace, in the order the plugin registers them. */
+declare const notifyActions: ActionDefinition[];
+//#endregion
+//#region src/port/notifier.types.d.ts
+/** The kind of channel a notification targets. */
+type NotificationKind = "slack" | "webhook" | "email";
+/**
+ * One message handed to the `Notifier`. `kind` picks the channel type and
+ * decides which of the optional fields carry meaning: `subject` and `body` for
+ * email, `mention` for Slack, `json` for a webhook.
+ */
+interface Notification {
+  kind: NotificationKind;
+  /** Where it goes, read in the terms of its `kind`: a Slack channel, a URL, an address. */
+  channel: string;
+  subject?: string;
+  body?: string;
+  mention?: string;
+  json?: unknown;
+}
+/** What a `Notifier` answers with once a message is on its way. */
+interface NotifyReceipt {
+  /** The dispatch succeeded. Says nothing about whether anyone read it. */
+  delivered: boolean;
+  /** The notifier's own handle for the message. */
+  id: string;
+}
+/** The contract every notification goes through, whatever the channel. */
+interface Notifier {
+  /**
+   * Dispatches one message.
+   *
+   * @returns the receipt for the dispatch.
+   * @throws {VennError} `VN8090` from an implementation that cannot deliver.
+   */
+  send(message: Notification): Promise<NotifyReceipt>;
+}
+/** A `Notifier` that keeps every sent notification in memory, for assertions. */
+interface FakeNotifier extends Notifier {
+  readonly sent: readonly Notification[];
+}
+//#endregion
+//#region src/port/notifier.port.d.ts
+/**
+ * The port every `notify` verb dispatches through. Requires the `net`
+ * capability, so a host without it fails to load the plugin rather than
+ * failing mid-run.
+ */
+declare const NotifierPort: Port<Notifier>;
+//#endregion
+//#region src/clients/fake-notifier.d.ts
+/**
+ * The in-memory `Notifier`. Records what it is handed and touches no network.
+ *
+ * @returns a fresh notifier whose `sent` array starts empty and grows in
+ * dispatch order.
+ */
+declare function createFakeNotifier(): FakeNotifier;
+//#endregion
+//#region src/clients/real-notifier.d.ts
+/**
+ * The live `Notifier`. No Slack, webhook or email wiring in this build.
+ *
+ * @returns a notifier whose `send` throws, so the gap is a legible failure
+ * rather than a silent no-op.
+ * @throws {VennError} `VN8090` on every `send`.
+ */
+declare function createRealNotifier(): Notifier;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `@venn-lang/notify` plugin. Registers the `notify` namespace: the `slack`,
+ * `webhook` and `email` verbs and the nominal `notify.Receipt` type. Requires
+ * the `net` capability, since every verb dispatches over the network.
+ */
+declare const notifyPlugin: PluginDefinition;
+//#endregion
+export { type FakeNotifier, type Notification, type NotificationKind, type Notifier, NotifierPort, type NotifyReceipt, createFakeNotifier, createRealNotifier, notifyPlugin as default, notifyPlugin, notifyActions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/index.ts","../src/port/notifier.types.ts","../src/port/notifier.port.ts","../src/clients/fake-notifier.ts","../src/clients/real-notifier.ts","../src/plugin.ts"],"mappings":";;;;cAMa,eAAe;;;;KCLhB;;;;;;UAOK;EACf,MAAM;;EAEN;EACA;EACA;EACA;EACA;;;UAIe;;EAEf;;EAEA;;;UAIe;;;;;;;EAOf,KAAK,SAAS,eAAe,QAAQ;;;UAItB,qBAAqB;WAC3B,eAAe;;;;;;;;;cC/Bb,cAAc,KAAK;;;;;;;;;iBCAhB,sBAAsB;;;;;;;;;;iBCEtB,sBAAsB;;;;;;;;cCDzB,cAAc"}

package/dist/index.js

@@ -0,0 +1,134 @@
+import { arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { VennError } from "@venn-lang/contracts";
+//#region src/port/notifier.port.ts
+/**
+* The port every `notify` verb dispatches through. Requires the `net`
+* capability, so a host without it fails to load the plugin rather than
+* failing mid-run.
+*/
+const NotifierPort = {
+	id: "venn.port.notifier",
+	version: 1,
+	requires: ["net"],
+	methods: ["send"]
+};
+/**
+* `notify.email "qa@example.com" { subject: "Nightly failed", body: report }`.
+*
+* Sends one email. Both `subject` and `body` are optional; an empty recipient
+* is passed straight through to the notifier, which decides what to do with it.
+*
+* @returns a `notify.Receipt`.
+*/
+const email = defineAction({
+	name: "email",
+	doc: "Send an email notification.",
+	params: z.object({
+		subject: z.string().optional(),
+		body: z.string().optional()
+	}).optional(),
+	args: [arg("to", t.string, "Who receives it.")],
+	result: t.ref("notify.Receipt"),
+	run: (ctx, input) => ctx.port(NotifierPort).send({
+		kind: "email",
+		channel: String(input.args[0] ?? ""),
+		subject: input.params?.subject,
+		body: input.params?.body
+	})
+});
+//#endregion
+//#region src/actions/index.ts
+/** Every verb in the `notify` namespace, in the order the plugin registers them. */
+const notifyActions = [
+	defineAction({
+		name: "slack",
+		doc: "Send a Slack notification to a channel.",
+		params: z.object({ mention: z.string().optional() }).optional(),
+		args: [arg("channel", t.string, "Where to post: `#builds`, or a user.")],
+		result: t.ref("notify.Receipt"),
+		run: (ctx, input) => ctx.port(NotifierPort).send({
+			kind: "slack",
+			channel: String(input.args[0] ?? ""),
+			mention: input.params?.mention
+		})
+	}),
+	defineAction({
+		name: "webhook",
+		doc: "Send a webhook notification with a JSON body.",
+		params: z.object({ json: z.unknown().optional() }).optional(),
+		args: [arg("url", t.string, "Where to post the JSON body.")],
+		result: t.ref("notify.Receipt"),
+		run: (ctx, input) => ctx.port(NotifierPort).send({
+			kind: "webhook",
+			channel: String(input.args[0] ?? ""),
+			json: input.params?.json
+		})
+	}),
+	email
+];
+//#endregion
+//#region src/clients/fake-notifier.ts
+/**
+* The in-memory `Notifier`. Records what it is handed and touches no network.
+*
+* @returns a fresh notifier whose `sent` array starts empty and grows in
+* dispatch order.
+*/
+function createFakeNotifier() {
+	const sent = [];
+	return {
+		sent,
+		send: async (message) => {
+			sent.push(message);
+			return {
+				delivered: true,
+				id: `fake-${sent.length}`
+			};
+		}
+	};
+}
+//#endregion
+//#region src/clients/real-notifier.ts
+/**
+* The live `Notifier`. No Slack, webhook or email wiring in this build.
+*
+* @returns a notifier whose `send` throws, so the gap is a legible failure
+* rather than a silent no-op.
+* @throws {VennError} `VN8090` on every `send`.
+*/
+function createRealNotifier() {
+	return { send: async () => {
+		throw new VennError({
+			code: "VN8090",
+			message: "Notifier real client not implemented in this build"
+		});
+	} };
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* The `@venn-lang/notify` plugin. Registers the `notify` namespace: the `slack`,
+* `webhook` and `email` verbs and the nominal `notify.Receipt` type. Requires
+* the `net` capability, since every verb dispatches over the network.
+*/
+const notifyPlugin = definePlugin({
+	name: "venn/notify",
+	version: "0.0.0",
+	namespace: "notify",
+	requires: ["net"],
+	actions: notifyActions,
+	typeDefs: { 
+	/**
+	* What the notifier answers with once a message is on its way. `delivered`
+	* reports the dispatch, not the reading: nobody here knows whether it was seen.
+	*/
+Receipt: t.record({
+		delivered: t.bool,
+		id: t.string
+	}) }
+});
+//#endregion
+export { NotifierPort, createFakeNotifier, createRealNotifier, notifyPlugin as default, notifyPlugin, notifyActions };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["params","params"],"sources":["../src/port/notifier.port.ts","../src/actions/email.ts","../src/actions/slack.ts","../src/actions/webhook.ts","../src/actions/index.ts","../src/clients/fake-notifier.ts","../src/clients/real-notifier.ts","../src/types.ts","../src/plugin.ts"],"sourcesContent":["import type { Port } from \"@venn-lang/contracts\";\nimport type { Notifier } from \"./notifier.types.js\";\n\n/**\n * The port every `notify` verb dispatches through. Requires the `net`\n * capability, so a host without it fails to load the plugin rather than\n * failing mid-run.\n */\nexport const NotifierPort: Port<Notifier> = {\n  id: \"venn.port.notifier\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"send\"],\n};\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { NotifierPort } from \"../port/index.js\";\n\nconst params = z\n  .object({\n    subject: z.string().optional(),\n    body: z.string().optional(),\n  })\n  .optional();\n\n/**\n * `notify.email \"qa@example.com\" { subject: \"Nightly failed\", body: report }`.\n *\n * Sends one email. Both `subject` and `body` are optional; an empty recipient\n * is passed straight through to the notifier, which decides what to do with it.\n *\n * @returns a `notify.Receipt`.\n */\nexport const email: ActionDefinition = defineAction({\n  name: \"email\",\n  doc: \"Send an email notification.\",\n  params,\n  args: [arg(\"to\", t.string, \"Who receives it.\")],\n  result: t.ref(\"notify.Receipt\"),\n  run: (ctx, input) =>\n    ctx.port(NotifierPort).send({\n      kind: \"email\",\n      channel: String(input.args[0] ?? \"\"),\n      subject: input.params?.subject,\n      body: input.params?.body,\n    }),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { NotifierPort } from \"../port/index.js\";\n\nconst params = z.object({ mention: z.string().optional() }).optional();\n\n/**\n * `notify.slack \"#qa\" { mention: \"@oncall\" }`.\n *\n * Posts to a Slack channel or a user. `mention` pings someone alongside the post.\n *\n * @returns a `notify.Receipt`.\n */\nexport const slack: ActionDefinition = defineAction({\n  name: \"slack\",\n  doc: \"Send a Slack notification to a channel.\",\n  params,\n  args: [arg(\"channel\", t.string, \"Where to post: `#builds`, or a user.\")],\n  result: t.ref(\"notify.Receipt\"),\n  run: (ctx, input) =>\n    ctx.port(NotifierPort).send({\n      kind: \"slack\",\n      channel: String(input.args[0] ?? \"\"),\n      mention: input.params?.mention,\n    }),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { NotifierPort } from \"../port/index.js\";\n\nconst params = z.object({ json: z.unknown().optional() }).optional();\n\n/**\n * `notify.webhook \"https://hooks.example.com/build\" { json: { status: \"red\" } }`.\n *\n * Posts a JSON payload to a URL. The payload rides in `json` and is sent as is.\n *\n * @returns a `notify.Receipt`.\n */\nexport const webhook: ActionDefinition = defineAction({\n  name: \"webhook\",\n  doc: \"Send a webhook notification with a JSON body.\",\n  params,\n  args: [arg(\"url\", t.string, \"Where to post the JSON body.\")],\n  result: t.ref(\"notify.Receipt\"),\n  run: (ctx, input) =>\n    ctx.port(NotifierPort).send({\n      kind: \"webhook\",\n      channel: String(input.args[0] ?? \"\"),\n      json: input.params?.json,\n    }),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { email } from \"./email.js\";\nimport { slack } from \"./slack.js\";\nimport { webhook } from \"./webhook.js\";\n\n/** Every verb in the `notify` namespace, in the order the plugin registers them. */\nexport const notifyActions: ActionDefinition[] = [slack, webhook, email];\n","import type { FakeNotifier, Notification } from \"../port/index.js\";\n\n/**\n * The in-memory `Notifier`. Records what it is handed and touches no network.\n *\n * @returns a fresh notifier whose `sent` array starts empty and grows in\n * dispatch order.\n */\nexport function createFakeNotifier(): FakeNotifier {\n  const sent: Notification[] = [];\n  return {\n    sent,\n    send: async (message) => {\n      sent.push(message);\n      return { delivered: true, id: `fake-${sent.length}` };\n    },\n  };\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { Notifier } from \"../port/index.js\";\n\n/**\n * The live `Notifier`. No Slack, webhook or email wiring in this build.\n *\n * @returns a notifier whose `send` throws, so the gap is a legible failure\n * rather than a silent no-op.\n * @throws {VennError} `VN8090` on every `send`.\n */\nexport function createRealNotifier(): Notifier {\n  return {\n    send: async () => {\n      throw new VennError({\n        code: \"VN8090\",\n        message: \"Notifier real client not implemented in this build\",\n      });\n    },\n  };\n}\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types `@venn-lang/notify` publishes to the checker, under the `notify`\n * namespace. Kept as data, and mirroring `NotifyReceipt` in\n * `port/notifier.types.ts` by hand, so a generator reading the emitted `.d.ts`\n * can replace this file unnoticed. The name drops its prefix on the way in\n * because the namespace already says `notify`.\n */\nexport const notifyTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /**\n   * What the notifier answers with once a message is on its way. `delivered`\n   * reports the dispatch, not the reading: nobody here knows whether it was seen.\n   */\n  Receipt: t.record({ delivered: t.bool, id: t.string }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { notifyActions } from \"./actions/index.js\";\nimport { notifyTypeDefs } from \"./types.js\";\n\n/**\n * The `@venn-lang/notify` plugin. Registers the `notify` namespace: the `slack`,\n * `webhook` and `email` verbs and the nominal `notify.Receipt` type. Requires\n * the `net` capability, since every verb dispatches over the network.\n */\nexport const notifyPlugin: PluginDefinition = definePlugin({\n  name: \"venn/notify\",\n  version: \"0.0.0\",\n  namespace: \"notify\",\n  requires: [\"net\"],\n  actions: notifyActions,\n  typeDefs: notifyTypeDefs,\n});\n\nexport { notifyPlugin as default };\n"],"mappings":";;;;;;;;;AAQA,MAAa,eAA+B;CAC1C,IAAI;CACJ,SAAS;CACT,UAAU,CAAC,KAAK;CAChB,SAAS,CAAC,MAAM;AAClB;;;;;;;;;ACMA,MAAa,QAA0B,aAAa;CAClD,MAAM;CACN,KAAK;CACL,QAlBa,EACZ,OAAO;EACN,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;EAC7B,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;CAC5B,CAAC,CAAC,CACD,SAaD;CACA,MAAM,CAAC,IAAI,MAAM,EAAE,QAAQ,kBAAkB,CAAC;CAC9C,QAAQ,EAAE,IAAI,gBAAgB;CAC9B,MAAM,KAAK,UACT,IAAI,KAAK,YAAY,CAAC,CAAC,KAAK;EAC1B,MAAM;EACN,SAAS,OAAO,MAAM,KAAK,MAAM,EAAE;EACnC,SAAS,MAAM,QAAQ;EACvB,MAAM,MAAM,QAAQ;CACtB,CAAC;AACL,CAAC;;;;AG1BD,MAAa,gBAAoC;CFOV,aAAa;EAClD,MAAM;EACN,KAAK;EACL,QAZa,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAY1D;EACA,MAAM,CAAC,IAAI,WAAW,EAAE,QAAQ,sCAAsC,CAAC;EACvE,QAAQ,EAAE,IAAI,gBAAgB;EAC9B,MAAM,KAAK,UACT,IAAI,KAAK,YAAY,CAAC,CAAC,KAAK;GAC1B,MAAM;GACN,SAAS,OAAO,MAAM,KAAK,MAAM,EAAE;GACnC,SAAS,MAAM,QAAQ;EACzB,CAAC;CACL,CEnBkD;CDOT,aAAa;EACpD,MAAM;EACN,KAAK;EACL,QAZa,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAYxD;EACA,MAAM,CAAC,IAAI,OAAO,EAAE,QAAQ,8BAA8B,CAAC;EAC3D,QAAQ,EAAE,IAAI,gBAAgB;EAC9B,MAAM,KAAK,UACT,IAAI,KAAK,YAAY,CAAC,CAAC,KAAK;GAC1B,MAAM;GACN,SAAS,OAAO,MAAM,KAAK,MAAM,EAAE;GACnC,MAAM,MAAM,QAAQ;EACtB,CAAC;CACL,CCnByD;CAAS;AAAK;;;;;;;;;ACEvE,SAAgB,qBAAmC;CACjD,MAAM,OAAuB,CAAC;CAC9B,OAAO;EACL;EACA,MAAM,OAAO,YAAY;GACvB,KAAK,KAAK,OAAO;GACjB,OAAO;IAAE,WAAW;IAAM,IAAI,QAAQ,KAAK;GAAS;EACtD;CACF;AACF;;;;;;;;;;ACPA,SAAgB,qBAA+B;CAC7C,OAAO,EACL,MAAM,YAAY;EAChB,MAAM,IAAI,UAAU;GAClB,MAAM;GACN,SAAS;EACX,CAAC;CACH,EACF;AACF;;;;;;;;AEVA,MAAa,eAAiC,aAAa;CACzD,MAAM;CACN,SAAS;CACT,WAAW;CACX,UAAU,CAAC,KAAK;CAChB,SAAS;CACT,UAAU;;;;;ADDV,SAAS,EAAE,OAAO;EAAE,WAAW,EAAE;EAAM,IAAI,EAAE;CAAO,CAAC,ECC3C;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/notify",
+  "version": "0.1.0",
+  "description": "The notify namespace: send a Slack message, a webhook or an email from a flow.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "notify"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-notify#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-notify"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/email.ts

@@ -0,0 +1,33 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { NotifierPort } from "../port/index.js";
+
+const params = z
+  .object({
+    subject: z.string().optional(),
+    body: z.string().optional(),
+  })
+  .optional();
+
+/**
+ * `notify.email "qa@example.com" { subject: "Nightly failed", body: report }`.
+ *
+ * Sends one email. Both `subject` and `body` are optional; an empty recipient
+ * is passed straight through to the notifier, which decides what to do with it.
+ *
+ * @returns a `notify.Receipt`.
+ */
+export const email: ActionDefinition = defineAction({
+  name: "email",
+  doc: "Send an email notification.",
+  params,
+  args: [arg("to", t.string, "Who receives it.")],
+  result: t.ref("notify.Receipt"),
+  run: (ctx, input) =>
+    ctx.port(NotifierPort).send({
+      kind: "email",
+      channel: String(input.args[0] ?? ""),
+      subject: input.params?.subject,
+      body: input.params?.body,
+    }),
+});

package/src/actions/index.ts

@@ -0,0 +1,7 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { email } from "./email.js";
+import { slack } from "./slack.js";
+import { webhook } from "./webhook.js";
+
+/** Every verb in the `notify` namespace, in the order the plugin registers them. */
+export const notifyActions: ActionDefinition[] = [slack, webhook, email];

package/src/actions/slack.ts

@@ -0,0 +1,26 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { NotifierPort } from "../port/index.js";
+
+const params = z.object({ mention: z.string().optional() }).optional();
+
+/**
+ * `notify.slack "#qa" { mention: "@oncall" }`.
+ *
+ * Posts to a Slack channel or a user. `mention` pings someone alongside the post.
+ *
+ * @returns a `notify.Receipt`.
+ */
+export const slack: ActionDefinition = defineAction({
+  name: "slack",
+  doc: "Send a Slack notification to a channel.",
+  params,
+  args: [arg("channel", t.string, "Where to post: `#builds`, or a user.")],
+  result: t.ref("notify.Receipt"),
+  run: (ctx, input) =>
+    ctx.port(NotifierPort).send({
+      kind: "slack",
+      channel: String(input.args[0] ?? ""),
+      mention: input.params?.mention,
+    }),
+});

package/src/actions/webhook.ts

@@ -0,0 +1,26 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { NotifierPort } from "../port/index.js";
+
+const params = z.object({ json: z.unknown().optional() }).optional();
+
+/**
+ * `notify.webhook "https://hooks.example.com/build" { json: { status: "red" } }`.
+ *
+ * Posts a JSON payload to a URL. The payload rides in `json` and is sent as is.
+ *
+ * @returns a `notify.Receipt`.
+ */
+export const webhook: ActionDefinition = defineAction({
+  name: "webhook",
+  doc: "Send a webhook notification with a JSON body.",
+  params,
+  args: [arg("url", t.string, "Where to post the JSON body.")],
+  result: t.ref("notify.Receipt"),
+  run: (ctx, input) =>
+    ctx.port(NotifierPort).send({
+      kind: "webhook",
+      channel: String(input.args[0] ?? ""),
+      json: input.params?.json,
+    }),
+});

package/src/clients/fake-notifier.ts

@@ -0,0 +1,18 @@
+import type { FakeNotifier, Notification } from "../port/index.js";
+
+/**
+ * The in-memory `Notifier`. Records what it is handed and touches no network.
+ *
+ * @returns a fresh notifier whose `sent` array starts empty and grows in
+ * dispatch order.
+ */
+export function createFakeNotifier(): FakeNotifier {
+  const sent: Notification[] = [];
+  return {
+    sent,
+    send: async (message) => {
+      sent.push(message);
+      return { delivered: true, id: `fake-${sent.length}` };
+    },
+  };
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeNotifier } from "./fake-notifier.js";
+export { createRealNotifier } from "./real-notifier.js";

package/src/clients/real-notifier.ts

@@ -0,0 +1,20 @@
+import { VennError } from "@venn-lang/contracts";
+import type { Notifier } from "../port/index.js";
+
+/**
+ * The live `Notifier`. No Slack, webhook or email wiring in this build.
+ *
+ * @returns a notifier whose `send` throws, so the gap is a legible failure
+ * rather than a silent no-op.
+ * @throws {VennError} `VN8090` on every `send`.
+ */
+export function createRealNotifier(): Notifier {
+  return {
+    send: async () => {
+      throw new VennError({
+        code: "VN8090",
+        message: "Notifier real client not implemented in this build",
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@venn-lang/notify`: the verbs that tell someone what a run did (`slack`,
+ * `webhook`, `email`) and the `Notifier` port they dispatch through.
+ */
+
+export * from "./actions/index.js";
+export * from "./clients/index.js";
+export { notifyPlugin, notifyPlugin as default } from "./plugin.js";
+export * from "./port/index.js";

package/src/plugin.ts

@@ -0,0 +1,19 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { notifyActions } from "./actions/index.js";
+import { notifyTypeDefs } from "./types.js";
+
+/**
+ * The `@venn-lang/notify` plugin. Registers the `notify` namespace: the `slack`,
+ * `webhook` and `email` verbs and the nominal `notify.Receipt` type. Requires
+ * the `net` capability, since every verb dispatches over the network.
+ */
+export const notifyPlugin: PluginDefinition = definePlugin({
+  name: "venn/notify",
+  version: "0.0.0",
+  namespace: "notify",
+  requires: ["net"],
+  actions: notifyActions,
+  typeDefs: notifyTypeDefs,
+});
+
+export { notifyPlugin as default };

package/src/port/index.ts

@@ -0,0 +1,8 @@
+export { NotifierPort } from "./notifier.port.js";
+export type {
+  FakeNotifier,
+  Notification,
+  NotificationKind,
+  Notifier,
+  NotifyReceipt,
+} from "./notifier.types.js";

package/src/port/notifier.port.ts

@@ -0,0 +1,14 @@
+import type { Port } from "@venn-lang/contracts";
+import type { Notifier } from "./notifier.types.js";
+
+/**
+ * The port every `notify` verb dispatches through. Requires the `net`
+ * capability, so a host without it fails to load the plugin rather than
+ * failing mid-run.
+ */
+export const NotifierPort: Port<Notifier> = {
+  id: "venn.port.notifier",
+  version: 1,
+  requires: ["net"],
+  methods: ["send"],
+};

package/src/port/notifier.types.ts

@@ -0,0 +1,41 @@
+/** The kind of channel a notification targets. */
+export type NotificationKind = "slack" | "webhook" | "email";
+
+/**
+ * One message handed to the `Notifier`. `kind` picks the channel type and
+ * decides which of the optional fields carry meaning: `subject` and `body` for
+ * email, `mention` for Slack, `json` for a webhook.
+ */
+export interface Notification {
+  kind: NotificationKind;
+  /** Where it goes, read in the terms of its `kind`: a Slack channel, a URL, an address. */
+  channel: string;
+  subject?: string;
+  body?: string;
+  mention?: string;
+  json?: unknown;
+}
+
+/** What a `Notifier` answers with once a message is on its way. */
+export interface NotifyReceipt {
+  /** The dispatch succeeded. Says nothing about whether anyone read it. */
+  delivered: boolean;
+  /** The notifier's own handle for the message. */
+  id: string;
+}
+
+/** The contract every notification goes through, whatever the channel. */
+export interface Notifier {
+  /**
+   * Dispatches one message.
+   *
+   * @returns the receipt for the dispatch.
+   * @throws {VennError} `VN8090` from an implementation that cannot deliver.
+   */
+  send(message: Notification): Promise<NotifyReceipt>;
+}
+
+/** A `Notifier` that keeps every sent notification in memory, for assertions. */
+export interface FakeNotifier extends Notifier {
+  readonly sent: readonly Notification[];
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types `@venn-lang/notify` publishes to the checker, under the `notify`
+ * namespace. Kept as data, and mirroring `NotifyReceipt` in
+ * `port/notifier.types.ts` by hand, so a generator reading the emitted `.d.ts`
+ * can replace this file unnoticed. The name drops its prefix on the way in
+ * because the namespace already says `notify`.
+ */
+export const notifyTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * What the notifier answers with once a message is on its way. `delivered`
+   * reports the dispatch, not the reading: nobody here knows whether it was seen.
+   */
+  Receipt: t.record({ delivered: t.bool, id: t.string }),
+};