@venn-lang/mqtt 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,107 @@
+# @venn-lang/mqtt
+
+> The `mqtt` namespace: connect to a broker, publish, subscribe, wait for a message on a topic.
+
+Venn's grammar knows no verbs. `@venn-lang/mqtt` registers the `mqtt` namespace with the runtime, so
+`mqtt.publish` resolves to an action and `mqtt.expect` hands back a typed message. The connection and
+the subscriptions live behind the `MqttClient` port, not in a handle the flow carries around, so a
+host swaps the whole transport by binding a different implementation.
+
+## Install
+
+Nothing to install yet. The package is unpublished (version `0.0.0`) and ships inside
+`@venn-lang/stdlib`, which the `venn` CLI and the language server both load. A `.vn` file declares it:
+
+```ruby
+use "venn/mqtt"
+```
+
+## Usage
+
+```ruby
+module demo.inventory
+
+use "venn/mqtt"
+use "venn/assert"
+
+flow "Inventory" {
+  step "the broker relays the stock change" {
+    mqtt.connect "mqtt://broker.test:1883"
+    mqtt.subscribe "inventory/sku-42"
+    mqtt.publish "inventory/sku-42" { json: { delta: -1 }, qos: 1 }
+
+    const msg = mqtt.expect "inventory/sku-42"
+    expect msg topic "inventory/sku-42"
+    expect msg.payload.delta == -1
+  }
+}
+```
+
+## API
+
+Everything below is exported from the package barrel.
+
+| Export | What it is |
+| --- | --- |
+| `mqttPlugin` (also the default export) | The `PluginDefinition`: namespace `mqtt`, `requires: ["net"]`. |
+| `MqttClientPort` | `Port<MqttClient>`, id `venn.port.mqtt-client`, version 1, methods `connect`, `publish`, `subscribe`, `expect`. |
+| `createFakeMqttClient({ seed })` | The double: a topic-to-queue map that records publishes and subscriptions. |
+| `createRealMqttClient()` | The real client. Out of scope for this build: every method throws `VN8090`. |
+| `messageSchema` | The Zod schema behind the nominal `Message` type the plugin registers. |
+| `mqttTypeDefs` | What the plugin publishes to the checker, as `TypeSpec` data. |
+
+Types: `MqttClient`, `FakeMqttClient`, `MqttPublishArgs`, `MqttMessage`.
+
+## Verbs
+
+| Verb | Shape | Result |
+| --- | --- | --- |
+| `mqtt.connect` | `mqtt.connect broker` | nothing |
+| `mqtt.publish` | `mqtt.publish topic { json, qos, retain, will }` | nothing |
+| `mqtt.subscribe` | `mqtt.subscribe topic` | nothing |
+| `mqtt.expect` | `mqtt.expect topic` | `mqtt.Message` |
+
+Each verb takes one positional argument: the broker URL for `connect`, the topic (wildcards and all)
+for the other three. Only `publish` has an options map, and it carries `json` (the payload), `qos`,
+`retain` and `will`.
+
+`subscribe` hands nothing back: the subscription is the port's to remember, and `mqtt.expect` is how a
+flow reaches what arrived.
+
+## Matchers and types
+
+`topic` is the one matcher: `expect msg topic "inventory/ack"` passes when the message arrived on that
+topic.
+
+The plugin publishes one type, `mqtt.Message`, with `topic`, `payload`, and optional `qos` and
+`retain`. It is what `mqtt.expect` hands back, and what tells the checker that `msg` can carry the
+`topic` matcher.
+
+## Ports and conformance
+
+`MqttClient` has the two implementations every port has, and both run
+`src/clients/mqtt-client.suite.ts`:
+
+- `createRealMqttClient()` is a stub in this build. Every method raises `VN8090`.
+- `createFakeMqttClient({ seed })` keeps one queue per topic. A publish is recorded on `published`
+  (with its `qos`, `retain` and `will`) and enqueued, so a publish-then-expect flow resolves without a
+  broker. Subscriptions land on `subscriptions`.
+
+```ts
+import { createFakeMqttClient } from "@venn-lang/mqtt";
+
+const client = createFakeMqttClient();
+await client.subscribe({ topic: "inventory/ack" });
+await client.publish({ topic: "inventory/ack", payload: { ok: true }, qos: 1 });
+const message = await client.expect({ topic: "inventory/ack" });
+// message.payload === { ok: true }
+```
+
+`expect` on an empty topic raises `VN8091`. `@venn-lang/stdlib` binds the fake by default, so the flow in
+[Usage](#usage) runs offline with no host wiring at all.
+
+## See also
+
+- [`@venn-lang/ws`](../std-ws), the same shape over a socket rather than topics.
+- [`@venn-lang/http`](../std-http), the reference plugin, with a real client and a real server.
+- [`@venn-lang/stdlib`](../stdlib) for the plugin list and the default port bindings.

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+//#region src/types/message.d.ts
+/**
+ * Runtime validation for `mqtt.Message`, registered on the plugin.
+ *
+ * Pairs with `mqttTypeDefs.Message`, which tells the checker the same shape:
+ * this one guards a value, that one types an expression.
+ */
+declare const messageSchema: ZodType;
+//#endregion
+//#region src/types/message.types.d.ts
+/** One message delivered on a topic, and what `mqtt.expect` hands back. */
+interface MqttMessage {
+  topic: string;
+  payload: unknown;
+  qos?: number;
+  retain?: boolean;
+}
+//#endregion
+//#region src/types/type-defs.d.ts
+/**
+ * The types the plugin publishes to flows, as `mqtt.Message`.
+ *
+ * Mirrors `MqttMessage` in `message.types.ts` and the Zod schema beside it: the
+ * schema guards a value at runtime, this tells the checker what `mqtt.expect`
+ * handed back. Keep the three in step by hand.
+ */
+declare const mqttTypeDefs: Readonly<Record<string, TypeSpec>>;
+//#endregion
+//#region src/port/mqtt-client.types.d.ts
+/** What `mqtt.publish` passes on: the topic it was given, plus the opts map. */
+interface MqttPublishArgs {
+  topic: string;
+  payload: unknown;
+  qos?: number;
+  retain?: boolean;
+  /** Last-will payload, stored alongside the publish. */
+  will?: unknown;
+}
+/**
+ * One broker connection: connect, publish, subscribe, and wait for a message.
+ *
+ * The port holds the connection, which is why no method takes a handle: a flow
+ * says `mqtt.publish "topic"` and the implementation knows which broker.
+ *
+ * Two implementations: `createRealMqttClient` and `createFakeMqttClient`.
+ */
+interface MqttClient {
+  connect(args: {
+    broker: string;
+  }): Promise<void>;
+  publish(args: MqttPublishArgs): Promise<void>;
+  subscribe(args: {
+    topic: string;
+  }): Promise<void>;
+  expect(args: {
+    topic: string;
+  }): Promise<MqttMessage>;
+}
+/** An `MqttClient` that also lets a test read back what the flow asked for. */
+interface FakeMqttClient extends MqttClient {
+  /** Every publish call, in order, including qos/retain/will. */
+  readonly published: readonly MqttPublishArgs[];
+  /** Every subscribed topic, in order. */
+  readonly subscriptions: readonly string[];
+}
+//#endregion
+//#region src/port/mqtt-client.port.d.ts
+/**
+ * The port descriptor every `mqtt` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot reach a broker refuses
+ * the binding at load time with a readable diagnostic.
+ */
+declare const MqttClientPort: Port<MqttClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * The double: a queue per topic, and no broker.
+ *
+ * A publish is also a delivery, so a flow that publishes and then expects on the
+ * same topic sees its own message. Topics are matched literally, with no
+ * wildcard expansion.
+ *
+ * @param args.seed Messages already waiting, keyed by topic.
+ * @returns A client whose `published` and `subscriptions` a test can read back.
+ * @throws VN8091 from `expect` when that topic's queue is empty.
+ */
+declare function createFakeMqttClient(args?: {
+  seed?: Record<string, MqttMessage[]>;
+}): FakeMqttClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The real MQTT client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+declare function createRealMqttClient(): MqttClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `mqtt` namespace: `connect`, `publish`, `subscribe`, `expect`, the `topic`
+ * matcher and the `mqtt.Message` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+declare const mqttPlugin: PluginDefinition;
+//#endregion
+export { type FakeMqttClient, type MqttClient, MqttClientPort, type MqttMessage, type MqttPublishArgs, createFakeMqttClient, createRealMqttClient, mqttPlugin as default, mqttPlugin, messageSchema, mqttTypeDefs };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/message.ts","../src/types/message.types.ts","../src/types/type-defs.ts","../src/port/mqtt-client.types.ts","../src/port/mqtt-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts"],"mappings":";;;;;;;;;;cAQa,eAAe;;;;UCPX;EACf;EACA;EACA;EACA;;;;;;;;;;;cCIW,cAAc,SAAS,eAAe;;;;UCNlC;EACf;EACA;EACA;EACA;;EAEA;;;;;;;;;;UAWe;EACf,QAAQ;IAAQ;MAAmB;EACnC,QAAQ,MAAM,kBAAkB;EAChC,UAAU;IAAQ;MAAkB;EACpC,OAAO;IAAQ;MAAkB,QAAQ;;;UAI1B,uBAAuB;;WAE7B,oBAAoB;;WAEpB;;;;;;;;;;cCvBE,gBAAgB,KAAK;;;;;;;;;;;;;;iBCMlB,qBACd;EAAQ,OAAO,eAAe;IAC7B;;;;;;;;;;;iBCNa,wBAAwB;;;;;;;;;;cCC3B,YAAY"}

package/dist/index.js

@@ -0,0 +1,243 @@
+import { VennError } from "@venn-lang/contracts";
+import { arg, defineAction, defineMatcher, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/clients/fake-client.ts
+/**
+* The double: a queue per topic, and no broker.
+*
+* A publish is also a delivery, so a flow that publishes and then expects on the
+* same topic sees its own message. Topics are matched literally, with no
+* wildcard expansion.
+*
+* @param args.seed Messages already waiting, keyed by topic.
+* @returns A client whose `published` and `subscriptions` a test can read back.
+* @throws VN8091 from `expect` when that topic's queue is empty.
+*/
+function createFakeMqttClient(args = {}) {
+	const topics = seedTopics(args.seed);
+	const published = [];
+	const subscriptions = [];
+	return {
+		published,
+		subscriptions,
+		connect: async () => {},
+		publish: async (call) => recordPublish({
+			topics,
+			published,
+			call
+		}),
+		subscribe: async ({ topic }) => void subscriptions.push(topic),
+		expect: async ({ topic }) => dequeue(topics, topic)
+	};
+}
+function recordPublish(args) {
+	args.published.push(args.call);
+	enqueue(args.topics, toMessage(args.call));
+}
+function toMessage(call) {
+	return {
+		topic: call.topic,
+		payload: call.payload,
+		qos: call.qos,
+		retain: call.retain
+	};
+}
+function enqueue(topics, message) {
+	const queue = topics.get(message.topic) ?? [];
+	queue.push(message);
+	topics.set(message.topic, queue);
+}
+function dequeue(topics, topic) {
+	const message = topics.get(topic)?.shift();
+	if (!message) throw noMessage(topic);
+	return message;
+}
+function seedTopics(seed = {}) {
+	return new Map(Object.entries(seed).map(([topic, messages]) => [topic, [...messages]]));
+}
+function noMessage(topic) {
+	return new VennError({
+		code: "VN8091",
+		message: `No message available on topic "${topic}".`,
+		detail: { topic }
+	});
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The real MQTT client. Not implemented in this build.
+*
+* It exists so the port has its second implementation and the failure is a named
+* Venn error rather than a missing method.
+*
+* @throws VN8090 from every method.
+*/
+function createRealMqttClient() {
+	return {
+		connect: notImplemented,
+		publish: notImplemented,
+		subscribe: notImplemented,
+		expect: notImplemented
+	};
+}
+function notImplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "MQTT real client not implemented in this build"
+	});
+}
+//#endregion
+//#region src/port/mqtt-client.port.ts
+/**
+* The port descriptor every `mqtt` verb resolves through `ctx.port(...)`.
+*
+* Declares the `net` capability, so a host that cannot reach a broker refuses
+* the binding at load time with a readable diagnostic.
+*/
+const MqttClientPort = {
+	id: "venn.port.mqtt-client",
+	version: 1,
+	requires: ["net"],
+	methods: [
+		"connect",
+		"publish",
+		"subscribe",
+		"expect"
+	]
+};
+//#endregion
+//#region src/actions/connect.ts
+/**
+* `mqtt.connect "mqtt://broker.test"`: open the broker connection.
+*
+* Returns nothing, because the port owns the connection. That is what lets the
+* other verbs reach it without the flow carrying a handle.
+*/
+const mqttConnect = defineAction({
+	name: "connect",
+	doc: "Connect to an MQTT broker.",
+	args: [arg("url", t.string, "Where the broker is.")],
+	result: t.void,
+	run: (ctx, input) => ctx.port(MqttClientPort).connect({ broker: String(input.args[0] ?? "") })
+});
+//#endregion
+//#region src/actions/expect.ts
+/**
+* `mqtt.expect "inventory/ack"`: wait for the next message on a topic.
+*
+* The result is typed as `mqtt.Message`, which is what lets
+* `expect res topic "inventory/ack"` know its subject.
+*/
+const mqttExpect = defineAction({
+	name: "expect",
+	doc: "Wait for the next message on a topic.",
+	args: [arg("topic", t.string, "The topic, wildcards and all.")],
+	result: t.ref("mqtt.Message"),
+	run: (ctx, input) => ctx.port(MqttClientPort).expect({ topic: String(input.args[0] ?? "") })
+});
+//#endregion
+//#region src/actions/index.ts
+/** The mqtt namespace's verbs. Adding one is a new file plus a single line here. */
+const mqttActions = [
+	mqttConnect,
+	defineAction({
+		name: "publish",
+		doc: "Publish a message to a topic.",
+		params: z.object({
+			json: z.unknown().optional(),
+			qos: z.number().optional(),
+			retain: z.boolean().optional(),
+			will: z.unknown().optional()
+		}),
+		args: [arg("topic", t.string, "The topic, wildcards and all.")],
+		result: t.void,
+		run: (ctx, input) => ctx.port(MqttClientPort).publish({
+			topic: String(input.args[0] ?? ""),
+			payload: input.params.json,
+			qos: input.params.qos,
+			retain: input.params.retain,
+			will: input.params.will
+		})
+	}),
+	defineAction({
+		name: "subscribe",
+		doc: "Subscribe to a topic.",
+		args: [arg("topic", t.string, "The topic, wildcards and all.")],
+		result: t.void,
+		run: (ctx, input) => ctx.port(MqttClientPort).subscribe({ topic: String(input.args[0] ?? "") })
+	}),
+	mqttExpect
+];
+//#endregion
+//#region src/matchers/on-topic.ts
+/**
+* `expect res topic "inventory/ack"`: passes if the message arrived on exactly
+* that topic. The comparison is literal, so wildcards are not expanded here.
+*/
+const onTopic = defineMatcher({
+	name: "topic",
+	args: [arg("topic", t.string, "The topic the message should have arrived on.")],
+	appliesTo: "Message",
+	test: ({ subject, args }) => messageTopic(subject) === String(args[0]),
+	message: ({ args }) => `expected the message on topic "${String(args[0])}"`
+});
+function messageTopic(subject) {
+	return subject.topic;
+}
+//#endregion
+//#region src/matchers/index.ts
+const mqttMatchers = [onTopic];
+//#endregion
+//#region src/types/message.ts
+/**
+* Runtime validation for `mqtt.Message`, registered on the plugin.
+*
+* Pairs with `mqttTypeDefs.Message`, which tells the checker the same shape:
+* this one guards a value, that one types an expression.
+*/
+const messageSchema = z.object({
+	topic: z.string(),
+	payload: z.unknown(),
+	qos: z.number().optional(),
+	retain: z.boolean().optional()
+});
+//#endregion
+//#region src/types/type-defs.ts
+/**
+* The types the plugin publishes to flows, as `mqtt.Message`.
+*
+* Mirrors `MqttMessage` in `message.types.ts` and the Zod schema beside it: the
+* schema guards a value at runtime, this tells the checker what `mqtt.expect`
+* handed back. Keep the three in step by hand.
+*/
+const mqttTypeDefs = { 
+/** One message on a topic, as `mqtt.expect` gives it back. */
+Message: t.record({
+	topic: t.string,
+	payload: t.dynamic,
+	qos: t.number,
+	retain: t.bool
+}, { optional: ["qos", "retain"] }) };
+//#endregion
+//#region src/plugin.ts
+/**
+* The `mqtt` namespace: `connect`, `publish`, `subscribe`, `expect`, the `topic`
+* matcher and the `mqtt.Message` type.
+*
+* Requires the `net` capability, so a host without it refuses the plugin at load
+* time rather than failing mid-flow.
+*/
+const mqttPlugin = definePlugin({
+	name: "venn/mqtt",
+	version: "0.0.0",
+	namespace: "mqtt",
+	requires: ["net"],
+	actions: mqttActions,
+	matchers: mqttMatchers,
+	types: { Message: messageSchema },
+	typeDefs: mqttTypeDefs
+});
+//#endregion
+export { MqttClientPort, createFakeMqttClient, createRealMqttClient, mqttPlugin as default, mqttPlugin, messageSchema, mqttTypeDefs };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/port/mqtt-client.port.ts","../src/actions/connect.ts","../src/actions/expect.ts","../src/actions/publish.ts","../src/actions/subscribe.ts","../src/actions/index.ts","../src/matchers/on-topic.ts","../src/matchers/index.ts","../src/types/message.ts","../src/types/type-defs.ts","../src/plugin.ts"],"sourcesContent":["import { VennError } from \"@venn-lang/contracts\";\nimport type { FakeMqttClient, MqttPublishArgs } from \"../port/index.js\";\nimport type { MqttMessage } from \"../types/index.js\";\n\n/**\n * The double: a queue per topic, and no broker.\n *\n * A publish is also a delivery, so a flow that publishes and then expects on the\n * same topic sees its own message. Topics are matched literally, with no\n * wildcard expansion.\n *\n * @param args.seed Messages already waiting, keyed by topic.\n * @returns A client whose `published` and `subscriptions` a test can read back.\n * @throws VN8091 from `expect` when that topic's queue is empty.\n */\nexport function createFakeMqttClient(\n  args: { seed?: Record<string, MqttMessage[]> } = {},\n): FakeMqttClient {\n  const topics = seedTopics(args.seed);\n  const published: MqttPublishArgs[] = [];\n  const subscriptions: string[] = [];\n  return {\n    published,\n    subscriptions,\n    connect: async () => {},\n    publish: async (call) => recordPublish({ topics, published, call }),\n    subscribe: async ({ topic }) => void subscriptions.push(topic),\n    expect: async ({ topic }) => dequeue(topics, topic),\n  };\n}\n\nfunction recordPublish(args: {\n  topics: Map<string, MqttMessage[]>;\n  published: MqttPublishArgs[];\n  call: MqttPublishArgs;\n}): void {\n  args.published.push(args.call);\n  enqueue(args.topics, toMessage(args.call));\n}\n\nfunction toMessage(call: MqttPublishArgs): MqttMessage {\n  return { topic: call.topic, payload: call.payload, qos: call.qos, retain: call.retain };\n}\n\nfunction enqueue(topics: Map<string, MqttMessage[]>, message: MqttMessage): void {\n  const queue = topics.get(message.topic) ?? [];\n  queue.push(message);\n  topics.set(message.topic, queue);\n}\n\nfunction dequeue(topics: Map<string, MqttMessage[]>, topic: string): MqttMessage {\n  const message = topics.get(topic)?.shift();\n  if (!message) throw noMessage(topic);\n  return message;\n}\n\nfunction seedTopics(seed: Record<string, MqttMessage[]> = {}): Map<string, MqttMessage[]> {\n  return new Map(Object.entries(seed).map(([topic, messages]) => [topic, [...messages]]));\n}\n\nfunction noMessage(topic: string): VennError {\n  return new VennError({\n    code: \"VN8091\",\n    message: `No message available on topic \"${topic}\".`,\n    detail: { topic },\n  });\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { MqttClient } from \"../port/index.js\";\n\n/**\n * The real MQTT client. Not implemented in this build.\n *\n * It exists so the port has its second implementation and the failure is a named\n * Venn error rather than a missing method.\n *\n * @throws VN8090 from every method.\n */\nexport function createRealMqttClient(): MqttClient {\n  return {\n    connect: notImplemented,\n    publish: notImplemented,\n    subscribe: notImplemented,\n    expect: notImplemented,\n  };\n}\n\nfunction notImplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"MQTT real client not implemented in this build\",\n  });\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { MqttClient } from \"./mqtt-client.types.js\";\n\n/**\n * The port descriptor every `mqtt` verb resolves through `ctx.port(...)`.\n *\n * Declares the `net` capability, so a host that cannot reach a broker refuses\n * the binding at load time with a readable diagnostic.\n */\nexport const MqttClientPort: Port<MqttClient> = {\n  id: \"venn.port.mqtt-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"connect\", \"publish\", \"subscribe\", \"expect\"],\n};\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { MqttClientPort } from \"../port/index.js\";\n\n/**\n * `mqtt.connect \"mqtt://broker.test\"`: open the broker connection.\n *\n * Returns nothing, because the port owns the connection. That is what lets the\n * other verbs reach it without the flow carrying a handle.\n */\nexport const mqttConnect: ActionDefinition = defineAction({\n  name: \"connect\",\n  doc: \"Connect to an MQTT broker.\",\n  args: [arg(\"url\", t.string, \"Where the broker is.\")],\n  result: t.void,\n  run: (ctx, input) => ctx.port(MqttClientPort).connect({ broker: String(input.args[0] ?? \"\") }),\n});\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { MqttClientPort } from \"../port/index.js\";\n\n/**\n * `mqtt.expect \"inventory/ack\"`: wait for the next message on a topic.\n *\n * The result is typed as `mqtt.Message`, which is what lets\n * `expect res topic \"inventory/ack\"` know its subject.\n */\nexport const mqttExpect: ActionDefinition = defineAction({\n  name: \"expect\",\n  doc: \"Wait for the next message on a topic.\",\n  args: [arg(\"topic\", t.string, \"The topic, wildcards and all.\")],\n  result: t.ref(\"mqtt.Message\"),\n  run: (ctx, input) => ctx.port(MqttClientPort).expect({ topic: String(input.args[0] ?? \"\") }),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { MqttClientPort } from \"../port/index.js\";\n\nconst params = z.object({\n  json: z.unknown().optional(),\n  qos: z.number().optional(),\n  retain: z.boolean().optional(),\n  will: z.unknown().optional(),\n});\n\n/**\n * `mqtt.publish \"inventory/sku-42\" { json: { … }, qos: 1 }`: send one message.\n *\n * The topic is the only positional argument; the payload and the delivery\n * options ride the map, which `params` above describes.\n */\nexport const mqttPublish: ActionDefinition = defineAction({\n  name: \"publish\",\n  doc: \"Publish a message to a topic.\",\n  params,\n  args: [arg(\"topic\", t.string, \"The topic, wildcards and all.\")],\n  result: t.void,\n  run: (ctx, input) =>\n    ctx.port(MqttClientPort).publish({\n      topic: String(input.args[0] ?? \"\"),\n      payload: input.params.json,\n      qos: input.params.qos,\n      retain: input.params.retain,\n      will: input.params.will,\n    }),\n});\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { MqttClientPort } from \"../port/index.js\";\n\n/**\n * `mqtt.subscribe \"inventory/#\"`: start receiving on a topic.\n *\n * Returns nothing: the port remembers the subscription, and `mqtt.expect` is how\n * a flow reaches what arrived.\n */\nexport const mqttSubscribe: ActionDefinition = defineAction({\n  name: \"subscribe\",\n  doc: \"Subscribe to a topic.\",\n  args: [arg(\"topic\", t.string, \"The topic, wildcards and all.\")],\n  result: t.void,\n  run: (ctx, input) => ctx.port(MqttClientPort).subscribe({ topic: String(input.args[0] ?? \"\") }),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { mqttConnect } from \"./connect.js\";\nimport { mqttExpect } from \"./expect.js\";\nimport { mqttPublish } from \"./publish.js\";\nimport { mqttSubscribe } from \"./subscribe.js\";\n\n/** The mqtt namespace's verbs. Adding one is a new file plus a single line here. */\nexport const mqttActions: ActionDefinition[] = [\n  mqttConnect,\n  mqttPublish,\n  mqttSubscribe,\n  mqttExpect,\n];\n","import { arg, defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\n\n/**\n * `expect res topic \"inventory/ack\"`: passes if the message arrived on exactly\n * that topic. The comparison is literal, so wildcards are not expanded here.\n */\nexport const onTopic: MatcherDefinition = defineMatcher({\n  name: \"topic\",\n  args: [arg(\"topic\", t.string, \"The topic the message should have arrived on.\")],\n  appliesTo: \"Message\",\n  test: ({ subject, args }) => messageTopic(subject) === String(args[0]),\n  message: ({ args }) => `expected the message on topic \"${String(args[0])}\"`,\n});\n\nfunction messageTopic(subject: unknown): string | undefined {\n  return (subject as { topic?: string }).topic;\n}\n","import type { MatcherDefinition } from \"@venn-lang/sdk\";\nimport { onTopic } from \"./on-topic.js\";\n\nexport const mqttMatchers: MatcherDefinition[] = [onTopic];\n","import { type ZodType, z } from \"@venn-lang/sdk\";\n\n/**\n * Runtime validation for `mqtt.Message`, registered on the plugin.\n *\n * Pairs with `mqttTypeDefs.Message`, which tells the checker the same shape:\n * this one guards a value, that one types an expression.\n */\nexport const messageSchema: ZodType = z.object({\n  topic: z.string(),\n  payload: z.unknown(),\n  qos: z.number().optional(),\n  retain: z.boolean().optional(),\n});\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types the plugin publishes to flows, as `mqtt.Message`.\n *\n * Mirrors `MqttMessage` in `message.types.ts` and the Zod schema beside it: the\n * schema guards a value at runtime, this tells the checker what `mqtt.expect`\n * handed back. Keep the three in step by hand.\n */\nexport const mqttTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /** One message on a topic, as `mqtt.expect` gives it back. */\n  Message: t.record(\n    { topic: t.string, payload: t.dynamic, qos: t.number, retain: t.bool },\n    { optional: [\"qos\", \"retain\"] },\n  ),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { mqttActions } from \"./actions/index.js\";\nimport { mqttMatchers } from \"./matchers/index.js\";\nimport { messageSchema, mqttTypeDefs } from \"./types/index.js\";\n\n/**\n * The `mqtt` namespace: `connect`, `publish`, `subscribe`, `expect`, the `topic`\n * matcher and the `mqtt.Message` type.\n *\n * Requires the `net` capability, so a host without it refuses the plugin at load\n * time rather than failing mid-flow.\n */\nexport const mqttPlugin: PluginDefinition = definePlugin({\n  name: \"venn/mqtt\",\n  version: \"0.0.0\",\n  namespace: \"mqtt\",\n  requires: [\"net\"],\n  actions: mqttActions,\n  matchers: mqttMatchers,\n  types: { Message: messageSchema },\n  typeDefs: mqttTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/mqtt",
+  "version": "0.1.0",
+  "description": "The mqtt namespace: connect to a broker, publish, subscribe, wait for a message on a topic.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "mqtt"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-mqtt#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-mqtt"
+  },
+  "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/connect.ts

@@ -0,0 +1,17 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { MqttClientPort } from "../port/index.js";
+
+/**
+ * `mqtt.connect "mqtt://broker.test"`: open the broker connection.
+ *
+ * Returns nothing, because the port owns the connection. That is what lets the
+ * other verbs reach it without the flow carrying a handle.
+ */
+export const mqttConnect: ActionDefinition = defineAction({
+  name: "connect",
+  doc: "Connect to an MQTT broker.",
+  args: [arg("url", t.string, "Where the broker is.")],
+  result: t.void,
+  run: (ctx, input) => ctx.port(MqttClientPort).connect({ broker: String(input.args[0] ?? "") }),
+});

package/src/actions/expect.ts

@@ -0,0 +1,17 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { MqttClientPort } from "../port/index.js";
+
+/**
+ * `mqtt.expect "inventory/ack"`: wait for the next message on a topic.
+ *
+ * The result is typed as `mqtt.Message`, which is what lets
+ * `expect res topic "inventory/ack"` know its subject.
+ */
+export const mqttExpect: ActionDefinition = defineAction({
+  name: "expect",
+  doc: "Wait for the next message on a topic.",
+  args: [arg("topic", t.string, "The topic, wildcards and all.")],
+  result: t.ref("mqtt.Message"),
+  run: (ctx, input) => ctx.port(MqttClientPort).expect({ topic: String(input.args[0] ?? "") }),
+});

package/src/actions/index.ts

@@ -0,0 +1,13 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { mqttConnect } from "./connect.js";
+import { mqttExpect } from "./expect.js";
+import { mqttPublish } from "./publish.js";
+import { mqttSubscribe } from "./subscribe.js";
+
+/** The mqtt namespace's verbs. Adding one is a new file plus a single line here. */
+export const mqttActions: ActionDefinition[] = [
+  mqttConnect,
+  mqttPublish,
+  mqttSubscribe,
+  mqttExpect,
+];

package/src/actions/publish.ts

@@ -0,0 +1,32 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { MqttClientPort } from "../port/index.js";
+
+const params = z.object({
+  json: z.unknown().optional(),
+  qos: z.number().optional(),
+  retain: z.boolean().optional(),
+  will: z.unknown().optional(),
+});
+
+/**
+ * `mqtt.publish "inventory/sku-42" { json: { … }, qos: 1 }`: send one message.
+ *
+ * The topic is the only positional argument; the payload and the delivery
+ * options ride the map, which `params` above describes.
+ */
+export const mqttPublish: ActionDefinition = defineAction({
+  name: "publish",
+  doc: "Publish a message to a topic.",
+  params,
+  args: [arg("topic", t.string, "The topic, wildcards and all.")],
+  result: t.void,
+  run: (ctx, input) =>
+    ctx.port(MqttClientPort).publish({
+      topic: String(input.args[0] ?? ""),
+      payload: input.params.json,
+      qos: input.params.qos,
+      retain: input.params.retain,
+      will: input.params.will,
+    }),
+});

package/src/actions/subscribe.ts

@@ -0,0 +1,17 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { MqttClientPort } from "../port/index.js";
+
+/**
+ * `mqtt.subscribe "inventory/#"`: start receiving on a topic.
+ *
+ * Returns nothing: the port remembers the subscription, and `mqtt.expect` is how
+ * a flow reaches what arrived.
+ */
+export const mqttSubscribe: ActionDefinition = defineAction({
+  name: "subscribe",
+  doc: "Subscribe to a topic.",
+  args: [arg("topic", t.string, "The topic, wildcards and all.")],
+  result: t.void,
+  run: (ctx, input) => ctx.port(MqttClientPort).subscribe({ topic: String(input.args[0] ?? "") }),
+});

package/src/clients/fake-client.ts

@@ -0,0 +1,67 @@
+import { VennError } from "@venn-lang/contracts";
+import type { FakeMqttClient, MqttPublishArgs } from "../port/index.js";
+import type { MqttMessage } from "../types/index.js";
+
+/**
+ * The double: a queue per topic, and no broker.
+ *
+ * A publish is also a delivery, so a flow that publishes and then expects on the
+ * same topic sees its own message. Topics are matched literally, with no
+ * wildcard expansion.
+ *
+ * @param args.seed Messages already waiting, keyed by topic.
+ * @returns A client whose `published` and `subscriptions` a test can read back.
+ * @throws VN8091 from `expect` when that topic's queue is empty.
+ */
+export function createFakeMqttClient(
+  args: { seed?: Record<string, MqttMessage[]> } = {},
+): FakeMqttClient {
+  const topics = seedTopics(args.seed);
+  const published: MqttPublishArgs[] = [];
+  const subscriptions: string[] = [];
+  return {
+    published,
+    subscriptions,
+    connect: async () => {},
+    publish: async (call) => recordPublish({ topics, published, call }),
+    subscribe: async ({ topic }) => void subscriptions.push(topic),
+    expect: async ({ topic }) => dequeue(topics, topic),
+  };
+}
+
+function recordPublish(args: {
+  topics: Map<string, MqttMessage[]>;
+  published: MqttPublishArgs[];
+  call: MqttPublishArgs;
+}): void {
+  args.published.push(args.call);
+  enqueue(args.topics, toMessage(args.call));
+}
+
+function toMessage(call: MqttPublishArgs): MqttMessage {
+  return { topic: call.topic, payload: call.payload, qos: call.qos, retain: call.retain };
+}
+
+function enqueue(topics: Map<string, MqttMessage[]>, message: MqttMessage): void {
+  const queue = topics.get(message.topic) ?? [];
+  queue.push(message);
+  topics.set(message.topic, queue);
+}
+
+function dequeue(topics: Map<string, MqttMessage[]>, topic: string): MqttMessage {
+  const message = topics.get(topic)?.shift();
+  if (!message) throw noMessage(topic);
+  return message;
+}
+
+function seedTopics(seed: Record<string, MqttMessage[]> = {}): Map<string, MqttMessage[]> {
+  return new Map(Object.entries(seed).map(([topic, messages]) => [topic, [...messages]]));
+}
+
+function noMessage(topic: string): VennError {
+  return new VennError({
+    code: "VN8091",
+    message: `No message available on topic "${topic}".`,
+    detail: { topic },
+  });
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeMqttClient } from "./fake-client.js";
+export { createRealMqttClient } from "./real-client.js";

package/src/clients/real-client.ts

@@ -0,0 +1,26 @@
+import { VennError } from "@venn-lang/contracts";
+import type { MqttClient } from "../port/index.js";
+
+/**
+ * The real MQTT client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+export function createRealMqttClient(): MqttClient {
+  return {
+    connect: notImplemented,
+    publish: notImplemented,
+    subscribe: notImplemented,
+    expect: notImplemented,
+  };
+}
+
+function notImplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "MQTT real client not implemented in this build",
+  });
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `mqtt` plugin: `connect`, `publish`, `subscribe` and `expect`.
+ *
+ * The broker connection lives behind the `MqttClient` port, so a flow never
+ * carries a handle and the same script runs against a real broker or the
+ * in-memory double.
+ */
+
+export * from "./clients/index.js";
+export { mqttPlugin, mqttPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./types/index.js";

package/src/matchers/index.ts

@@ -0,0 +1,4 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { onTopic } from "./on-topic.js";
+
+export const mqttMatchers: MatcherDefinition[] = [onTopic];

package/src/matchers/on-topic.ts

@@ -0,0 +1,18 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/**
+ * `expect res topic "inventory/ack"`: passes if the message arrived on exactly
+ * that topic. The comparison is literal, so wildcards are not expanded here.
+ */
+export const onTopic: MatcherDefinition = defineMatcher({
+  name: "topic",
+  args: [arg("topic", t.string, "The topic the message should have arrived on.")],
+  appliesTo: "Message",
+  test: ({ subject, args }) => messageTopic(subject) === String(args[0]),
+  message: ({ args }) => `expected the message on topic "${String(args[0])}"`,
+});
+
+function messageTopic(subject: unknown): string | undefined {
+  return (subject as { topic?: string }).topic;
+}

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { mqttActions } from "./actions/index.js";
+import { mqttMatchers } from "./matchers/index.js";
+import { messageSchema, mqttTypeDefs } from "./types/index.js";
+
+/**
+ * The `mqtt` namespace: `connect`, `publish`, `subscribe`, `expect`, the `topic`
+ * matcher and the `mqtt.Message` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+export const mqttPlugin: PluginDefinition = definePlugin({
+  name: "venn/mqtt",
+  version: "0.0.0",
+  namespace: "mqtt",
+  requires: ["net"],
+  actions: mqttActions,
+  matchers: mqttMatchers,
+  types: { Message: messageSchema },
+  typeDefs: mqttTypeDefs,
+});

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { MqttClientPort } from "./mqtt-client.port.js";
+export type { FakeMqttClient, MqttClient, MqttPublishArgs } from "./mqtt-client.types.js";

package/src/port/mqtt-client.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { MqttClient } from "./mqtt-client.types.js";
+
+/**
+ * The port descriptor every `mqtt` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot reach a broker refuses
+ * the binding at load time with a readable diagnostic.
+ */
+export const MqttClientPort: Port<MqttClient> = {
+  id: "venn.port.mqtt-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["connect", "publish", "subscribe", "expect"],
+};

package/src/port/mqtt-client.types.ts

@@ -0,0 +1,34 @@
+import type { MqttMessage } from "../types/index.js";
+
+/** What `mqtt.publish` passes on: the topic it was given, plus the opts map. */
+export interface MqttPublishArgs {
+  topic: string;
+  payload: unknown;
+  qos?: number;
+  retain?: boolean;
+  /** Last-will payload, stored alongside the publish. */
+  will?: unknown;
+}
+
+/**
+ * One broker connection: connect, publish, subscribe, and wait for a message.
+ *
+ * The port holds the connection, which is why no method takes a handle: a flow
+ * says `mqtt.publish "topic"` and the implementation knows which broker.
+ *
+ * Two implementations: `createRealMqttClient` and `createFakeMqttClient`.
+ */
+export interface MqttClient {
+  connect(args: { broker: string }): Promise<void>;
+  publish(args: MqttPublishArgs): Promise<void>;
+  subscribe(args: { topic: string }): Promise<void>;
+  expect(args: { topic: string }): Promise<MqttMessage>;
+}
+
+/** An `MqttClient` that also lets a test read back what the flow asked for. */
+export interface FakeMqttClient extends MqttClient {
+  /** Every publish call, in order, including qos/retain/will. */
+  readonly published: readonly MqttPublishArgs[];
+  /** Every subscribed topic, in order. */
+  readonly subscriptions: readonly string[];
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export { messageSchema } from "./message.js";
+export type { MqttMessage } from "./message.types.js";
+export { mqttTypeDefs } from "./type-defs.js";

package/src/types/message.ts

@@ -0,0 +1,14 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/**
+ * Runtime validation for `mqtt.Message`, registered on the plugin.
+ *
+ * Pairs with `mqttTypeDefs.Message`, which tells the checker the same shape:
+ * this one guards a value, that one types an expression.
+ */
+export const messageSchema: ZodType = z.object({
+  topic: z.string(),
+  payload: z.unknown(),
+  qos: z.number().optional(),
+  retain: z.boolean().optional(),
+});

package/src/types/message.types.ts

@@ -0,0 +1,7 @@
+/** One message delivered on a topic, and what `mqtt.expect` hands back. */
+export interface MqttMessage {
+  topic: string;
+  payload: unknown;
+  qos?: number;
+  retain?: boolean;
+}

package/src/types/type-defs.ts

@@ -0,0 +1,16 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types the plugin publishes to flows, as `mqtt.Message`.
+ *
+ * Mirrors `MqttMessage` in `message.types.ts` and the Zod schema beside it: the
+ * schema guards a value at runtime, this tells the checker what `mqtt.expect`
+ * handed back. Keep the three in step by hand.
+ */
+export const mqttTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** One message on a topic, as `mqtt.expect` gives it back. */
+  Message: t.record(
+    { topic: t.string, payload: t.dynamic, qos: t.number, retain: t.bool },
+    { optional: ["qos", "retain"] },
+  ),
+};