@spine-event-engine/transport 2.0.0-snapshot.2 → 2.0.0-snapshot.5

package/README.md

@@ -1,12 +1,81 @@
-# Transport
+# Local transport for Spine TS
 
-`@spine-event-engine/transport` provides process-local typed message channels
-for IntegrationBroker external-message exchange.
+`@spine-event-engine/transport` gives a Spine application typed, process-local
+message channels. It is for application and infrastructure developers who need
+to connect the external-message broker in a local or test process; it is not a
+general internet messaging client.
 
-Use `InMemoryTransportFactory` for local and test environments. The package
-exports `TransportFactory`, `MessageChannel`, `Publisher`, `Subscriber`,
-and `ConsumerHandle`; channels carry generated `ExternalMessage` values and
-canonical target type URLs.
+This is an experimental snapshot package. Use Node 24 or newer and generated
+Spine Protobuf contracts before integrating it. Start with the package
+[reference](REFERENCE.md) for the complete lifecycle and channel contract.
 
-For lifecycle and channel semantics, see the
-[REFERENCE documentation for agents](REFERENCE.md).
+## Install
+
+```sh
+pnpm add @spine-event-engine/transport@snapshot
+```
+
+The `snapshot` tag is intentionally experimental and can change before a
+stable release.
+
+## First success: create a local channel
+
+Create an `InMemoryTransportFactory`, then let the broker-facing application
+code request its typed `MessageChannel`. The channel carries generated
+`ExternalMessage` values and canonical target type URLs; it does not serialize
+them for another process.
+
+<!-- docs-snippet-path: packages/transport/test/memory/message-transport.test.ts -->
+
+```ts
+import { create, toBinary } from "@bufbuild/protobuf";
+import { AnySchema, StringValueSchema } from "@bufbuild/protobuf/wkt";
+import {
+  BoundedContextNameSchema,
+  ChannelIdSchema,
+  ExternalMessageSchema,
+} from "@spine-event-engine/proto";
+import { InMemoryTransportFactory } from "@spine-event-engine/transport";
+
+const factory = new InMemoryTransportFactory();
+const channel = create(ChannelIdSchema, { targetType: "type.spine.io/acme.tasks.Task" });
+const subscriber = await factory.createSubscriber(channel);
+const received: string[] = [];
+const consumer = await subscriber.addConsumer((message) => {
+  received.push(message.id?.typeUrl ?? "");
+});
+const publisher = await factory.createPublisher(channel);
+const id = create(AnySchema, {
+  typeUrl: "type.spine.io/google.protobuf.StringValue",
+  value: toBinary(StringValueSchema, create(StringValueSchema, { value: "task-42" })),
+});
+
+try {
+  await publisher.publish(
+    id,
+    create(ExternalMessageSchema, {
+      id,
+      originalMessage: id,
+      boundedContextName: create(BoundedContextNameSchema, { value: "tasks" }),
+    }),
+  );
+  if (received[0] !== id.typeUrl) throw new Error("The consumer did not receive the frame.");
+} finally {
+  await consumer.close();
+  await subscriber.close();
+  await publisher.close();
+  await factory.close();
+}
+```
+
+## What it does not provide
+
+This package has no network listener, persistence, cross-process delivery,
+authentication, or broker retry policy. Use it for local composition and tests;
+choose a deployment-specific transport for communication across processes.
+
+## Next steps
+
+- Read the [transport reference for coding agents](REFERENCE.md) for publisher,
+  subscriber, and `ConsumerHandle` lifecycle rules.
+- See [Protobuf contracts](https://github.com/SpineEventEngine/spine-ts/blob/main/packages/proto/README.md) for generated message types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spine-event-engine/transport",
-  "version": "2.0.0-snapshot.2",
+  "version": "2.0.0-snapshot.5",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -10,8 +10,7 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public",
-    "tag": "snapshot"
+    "access": "public"
   },
   "description": "Spine TS transport package skeleton.",
   "exports": {
@@ -27,6 +26,6 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "2.12.1",
-    "@spine-event-engine/proto": "2.0.0-snapshot.2"
+    "@spine-event-engine/proto": "2.0.0-snapshot.5"
   }
 }