@decocms/bindings 1.0.1-alpha.18 → 1.0.1-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.1-alpha.18",
+  "version": "1.0.1-alpha.19",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",

package/src/index.ts

@@ -20,3 +20,43 @@ export {
   type RegistryAppCollectionEntity,
   REGISTRY_APP_BINDING,
 } from "./well-known/registry";
+
+// Re-export event subscriber binding types (for connections that receive events)
+export {
+  CloudEventSchema,
+  type CloudEvent,
+  OnEventsInputSchema,
+  type OnEventsInput,
+  OnEventsOutputSchema,
+  type OnEventsOutput,
+  EVENT_SUBSCRIBER_BINDING,
+  EventSubscriberBinding,
+  type EventSubscriberBindingClient,
+} from "./well-known/event-subscriber";
+
+// Re-export event bus binding types (for interacting with an event bus)
+export {
+  EventPublishInputSchema,
+  type EventPublishInput,
+  EventPublishOutputSchema,
+  type EventPublishOutput,
+  EventSubscribeInputSchema,
+  type EventSubscribeInput,
+  EventSubscribeOutputSchema,
+  type EventSubscribeOutput,
+  EventUnsubscribeInputSchema,
+  type EventUnsubscribeInput,
+  EventUnsubscribeOutputSchema,
+  type EventUnsubscribeOutput,
+  EventCancelInputSchema,
+  type EventCancelInput,
+  EventCancelOutputSchema,
+  type EventCancelOutput,
+  EventAckInputSchema,
+  type EventAckInput,
+  EventAckOutputSchema,
+  type EventAckOutput,
+  EVENT_BUS_BINDING,
+  EventBusBinding,
+  type EventBusBindingClient,
+} from "./well-known/event-bus";

package/src/well-known/event-bus.ts

@@ -0,0 +1,335 @@
+/**
+ * Event Bus Well-Known Binding
+ *
+ * Defines the interface for interacting with an event bus via MCP.
+ * Any MCP that implements this binding can publish events and manage subscriptions.
+ *
+ * This binding includes:
+ * - EVENT_PUBLISH: Publish an event to the bus
+ * - EVENT_SUBSCRIBE: Subscribe to events of a specific type
+ * - EVENT_UNSUBSCRIBE: Remove a subscription
+ *
+ * Events follow the CloudEvents v1.0 specification.
+ * @see https://cloudevents.io/
+ */
+
+import { z } from "zod";
+import { bindingClient, type ToolBinder } from "../core/binder";
+
+// ============================================================================
+// Publish Schemas
+// ============================================================================
+
+/**
+ * EVENT_PUBLISH Input Schema
+ *
+ * Input for publishing an event.
+ * Note: `source` is automatically set by the event bus from the caller's connection ID.
+ */
+export const EventPublishInputSchema = z.object({
+  /** Event type (e.g., "order.created", "user.signup") */
+  type: z.string().min(1).max(255).describe("Event type identifier"),
+
+  /** Optional subject/resource identifier */
+  subject: z
+    .string()
+    .max(255)
+    .optional()
+    .describe("Subject/resource identifier (e.g., order ID)"),
+
+  /** Event payload (any JSON value) */
+  data: z.unknown().optional().describe("Event payload"),
+
+  /**
+   * Optional scheduled delivery time (ISO 8601 timestamp).
+   * If provided, the event will not be delivered until this time.
+   * If omitted, the event is delivered immediately.
+   * Cannot be used together with `cron`.
+   */
+  deliverAt: z
+    .string()
+    .datetime()
+    .optional()
+    .describe(
+      "Scheduled delivery time (ISO 8601). Omit for immediate delivery.",
+    ),
+
+  /**
+   * Optional cron expression for recurring events.
+   * If provided, the event will be delivered repeatedly according to the schedule.
+   * Uses standard cron syntax (5 or 6 fields).
+   * Cannot be used together with `deliverAt`.
+   *
+   * Examples:
+   * - "0 9 * * 1" - Every Monday at 9:00 AM
+   * - "0 0 1 * *" - First day of every month at midnight
+   * - "0/15 * * * *" - Every 15 minutes
+   */
+  cron: z
+    .string()
+    .max(100)
+    .optional()
+    .describe(
+      "Cron expression for recurring delivery. Use EVENT_CANCEL to stop.",
+    ),
+});
+
+export type EventPublishInput = z.infer<typeof EventPublishInputSchema>;
+
+/**
+ * EVENT_PUBLISH Output Schema
+ */
+export const EventPublishOutputSchema = z.object({
+  /** Created event ID */
+  id: z.string().describe("Unique event ID"),
+
+  /** Event type */
+  type: z.string().describe("Event type"),
+
+  /** Source connection ID */
+  source: z.string().describe("Source connection ID"),
+
+  /** Event timestamp (ISO 8601) */
+  time: z.string().describe("Event timestamp"),
+});
+
+export type EventPublishOutput = z.infer<typeof EventPublishOutputSchema>;
+
+// ============================================================================
+// Subscribe Schemas
+// ============================================================================
+
+/**
+ * EVENT_SUBSCRIBE Input Schema
+ *
+ * Input for subscribing to events.
+ * The subscriber connection ID is automatically set from the caller's token.
+ */
+export const EventSubscribeInputSchema = z.object({
+  /** Event type pattern to match */
+  eventType: z.string().min(1).max(255).describe("Event type to subscribe to"),
+
+  /** Optional: Only receive events from this publisher connection */
+  publisher: z
+    .string()
+    .optional()
+    .describe("Filter events by publisher connection ID"),
+
+  /** Optional: JSONPath filter expression on event data */
+  filter: z
+    .string()
+    .max(1000)
+    .optional()
+    .describe("JSONPath filter expression on event data"),
+});
+
+export type EventSubscribeInput = z.infer<typeof EventSubscribeInputSchema>;
+
+/**
+ * EVENT_SUBSCRIBE Output Schema
+ */
+export const EventSubscribeOutputSchema = z.object({
+  /** Created subscription */
+  subscription: z.object({
+    /** Subscription ID */
+    id: z.string().describe("Subscription ID"),
+
+    /** Subscriber connection ID */
+    connectionId: z.string().describe("Subscriber connection ID"),
+
+    /** Event type pattern */
+    eventType: z.string().describe("Event type pattern"),
+
+    /** Publisher connection filter */
+    publisher: z.string().nullable().describe("Publisher connection filter"),
+
+    /** JSONPath filter */
+    filter: z.string().nullable().describe("JSONPath filter expression"),
+
+    /** Whether subscription is enabled */
+    enabled: z.boolean().describe("Whether subscription is enabled"),
+
+    /** Created timestamp */
+    createdAt: z.union([z.string(), z.date()]).describe("Created timestamp"),
+
+    /** Updated timestamp */
+    updatedAt: z.union([z.string(), z.date()]).describe("Updated timestamp"),
+  }),
+});
+
+export type EventSubscribeOutput = z.infer<typeof EventSubscribeOutputSchema>;
+
+// ============================================================================
+// Unsubscribe Schemas
+// ============================================================================
+
+/**
+ * EVENT_UNSUBSCRIBE Input Schema
+ */
+export const EventUnsubscribeInputSchema = z.object({
+  /** Subscription ID to remove */
+  subscriptionId: z.string().describe("Subscription ID to remove"),
+});
+
+export type EventUnsubscribeInput = z.infer<typeof EventUnsubscribeInputSchema>;
+
+/**
+ * EVENT_UNSUBSCRIBE Output Schema
+ */
+export const EventUnsubscribeOutputSchema = z.object({
+  /** Success status */
+  success: z.boolean().describe("Whether unsubscribe was successful"),
+
+  /** Subscription ID that was removed */
+  subscriptionId: z.string().describe("Subscription ID that was removed"),
+});
+
+export type EventUnsubscribeOutput = z.infer<
+  typeof EventUnsubscribeOutputSchema
+>;
+
+// ============================================================================
+// Cancel Schemas (for stopping recurring events)
+// ============================================================================
+
+/**
+ * EVENT_CANCEL Input Schema
+ *
+ * Input for cancelling a recurring event.
+ * Only the publisher connection can cancel its own events.
+ */
+export const EventCancelInputSchema = z.object({
+  /** Event ID to cancel */
+  eventId: z.string().describe("Event ID to cancel"),
+});
+
+export type EventCancelInput = z.infer<typeof EventCancelInputSchema>;
+
+/**
+ * EVENT_CANCEL Output Schema
+ */
+export const EventCancelOutputSchema = z.object({
+  /** Success status */
+  success: z.boolean().describe("Whether cancellation was successful"),
+
+  /** Event ID that was cancelled */
+  eventId: z.string().describe("Event ID that was cancelled"),
+});
+
+export type EventCancelOutput = z.infer<typeof EventCancelOutputSchema>;
+
+// ============================================================================
+// Ack Schemas (for acknowledging async event processing)
+// ============================================================================
+
+/**
+ * EVENT_ACK Input Schema
+ *
+ * Input for acknowledging an event delivery.
+ * Used when ON_EVENTS returns retryAfter - the subscriber must call EVENT_ACK
+ * to confirm successful processing, otherwise the event will be re-delivered.
+ *
+ * The subscriber connection ID is determined from the caller's token.
+ */
+export const EventAckInputSchema = z.object({
+  /** Event ID to acknowledge */
+  eventId: z.string().describe("Event ID to acknowledge"),
+});
+
+export type EventAckInput = z.infer<typeof EventAckInputSchema>;
+
+/**
+ * EVENT_ACK Output Schema
+ */
+export const EventAckOutputSchema = z.object({
+  /** Success status */
+  success: z.boolean().describe("Whether ACK was successful"),
+
+  /** Event ID that was acknowledged */
+  eventId: z.string().describe("Event ID that was acknowledged"),
+});
+
+export type EventAckOutput = z.infer<typeof EventAckOutputSchema>;
+
+// ============================================================================
+// Event Bus Binding
+// ============================================================================
+
+/**
+ * Event Bus Binding
+ *
+ * Defines the interface for interacting with an event bus.
+ * Implementations must provide PUBLISH, SUBSCRIBE, UNSUBSCRIBE, CANCEL, and ACK tools.
+ *
+ * Required tools:
+ * - EVENT_PUBLISH: Publish an event (supports one-time, scheduled, and recurring via cron)
+ * - EVENT_SUBSCRIBE: Subscribe to events
+ * - EVENT_UNSUBSCRIBE: Remove a subscription
+ * - EVENT_CANCEL: Cancel a recurring event (stops future deliveries)
+ * - EVENT_ACK: Acknowledge event delivery (for async processing with retryAfter)
+ */
+export const EVENT_BUS_BINDING = [
+  {
+    name: "EVENT_PUBLISH" as const,
+    inputSchema: EventPublishInputSchema,
+    outputSchema: EventPublishOutputSchema,
+  },
+  {
+    name: "EVENT_SUBSCRIBE" as const,
+    inputSchema: EventSubscribeInputSchema,
+    outputSchema: EventSubscribeOutputSchema,
+  },
+  {
+    name: "EVENT_UNSUBSCRIBE" as const,
+    inputSchema: EventUnsubscribeInputSchema,
+    outputSchema: EventUnsubscribeOutputSchema,
+  },
+  {
+    name: "EVENT_CANCEL" as const,
+    inputSchema: EventCancelInputSchema,
+    outputSchema: EventCancelOutputSchema,
+  },
+  {
+    name: "EVENT_ACK" as const,
+    inputSchema: EventAckInputSchema,
+    outputSchema: EventAckOutputSchema,
+  },
+] satisfies ToolBinder[];
+
+/**
+ * Event Bus Binding Client
+ *
+ * Use this to create a client for interacting with an event bus.
+ *
+ * @example
+ * ```typescript
+ * import { EventBusBinding } from "@decocms/bindings/event-bus";
+ *
+ * // For a connection
+ * const client = EventBusBinding.forConnection(connection);
+ *
+ * // Publish an event
+ * const event = await client.EVENT_PUBLISH({
+ *   type: "order.created",
+ *   data: { orderId: "123" }
+ * });
+ *
+ * // Subscribe to events
+ * const sub = await client.EVENT_SUBSCRIBE({
+ *   eventType: "order.created"
+ * });
+ *
+ * // Unsubscribe
+ * await client.EVENT_UNSUBSCRIBE({
+ *   subscriptionId: sub.subscription.id
+ * });
+ * ```
+ */
+export const EventBusBinding = bindingClient(EVENT_BUS_BINDING);
+
+/**
+ * Type helper for the Event Bus binding client
+ */
+export type EventBusBindingClient = ReturnType<
+  typeof EventBusBinding.forConnection
+>;

package/src/well-known/event-subscriber.ts

@@ -0,0 +1,196 @@
+/**
+ * Event Subscriber Well-Known Binding
+ *
+ * Defines the interface for MCP connections that can receive events.
+ * Any MCP that implements this binding can receive batched CloudEvents
+ * from the MCP Mesh event bus.
+ *
+ * This binding includes:
+ * - ON_EVENTS: Receive a batch of CloudEvents
+ *
+ * Events follow the CloudEvents v1.0 specification.
+ * @see https://cloudevents.io/
+ */
+
+import { z } from "zod";
+import { bindingClient, type ToolBinder } from "../core/binder";
+
+/**
+ * CloudEvent Schema
+ *
+ * Follows CloudEvents v1.0 specification.
+ * Required attributes: id, source, type, specversion
+ * Optional attributes: time, subject, datacontenttype, dataschema, data
+ *
+ * @see https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
+ */
+export const CloudEventSchema = z.object({
+  /** CloudEvents specification version (always "1.0") */
+  specversion: z.literal("1.0").describe("CloudEvents specification version"),
+
+  /** Unique identifier for this event */
+  id: z
+    .string()
+    .describe("Unique identifier for this event (UUID recommended)"),
+
+  /**
+   * Source of the event - in MCP Mesh, this is the connection ID of the publisher.
+   * Format: URI-reference identifying the context in which an event happened.
+   */
+  source: z.string().describe("Connection ID of the event publisher"),
+
+  /**
+   * Event type identifier.
+   * Should be a reverse-DNS name like "com.example.order.created"
+   */
+  type: z
+    .string()
+    .describe("Event type (e.g., 'order.created', 'user.signup')"),
+
+  /** Timestamp of when the event occurred (ISO 8601 format) */
+  time: z
+    .string()
+    .datetime()
+    .optional()
+    .describe("Timestamp of when the event occurred (ISO 8601)"),
+
+  /**
+   * Subject of the event in the context of the event producer.
+   * Can be used to identify the resource the event is about.
+   */
+  subject: z
+    .string()
+    .optional()
+    .describe("Subject/resource identifier (e.g., order ID, user ID)"),
+
+  /** Content type of the data attribute (e.g., "application/json") */
+  datacontenttype: z
+    .string()
+    .optional()
+    .default("application/json")
+    .describe("Content type of the data attribute"),
+
+  /** Schema URI for the data attribute */
+  dataschema: z
+    .string()
+    .url()
+    .optional()
+    .describe("URI to the schema for the data attribute"),
+
+  /** Event payload - can be any JSON value */
+  data: z.unknown().optional().describe("Event payload (any JSON value)"),
+});
+
+/**
+ * CloudEvent type - inferred from schema
+ */
+export type CloudEvent = z.infer<typeof CloudEventSchema>;
+
+/**
+ * ON_EVENTS Input Schema
+ *
+ * Accepts a batch of CloudEvents for processing.
+ */
+export const OnEventsInputSchema = z.object({
+  /** Array of CloudEvents to process */
+  events: z
+    .array(CloudEventSchema)
+    .min(1)
+    .describe("Batch of CloudEvents to process"),
+});
+
+/**
+ * ON_EVENTS Input type
+ */
+export type OnEventsInput = z.infer<typeof OnEventsInputSchema>;
+
+/**
+ * ON_EVENTS Output Schema
+ *
+ * Returns success status. If success=true, all events in the batch
+ * are considered delivered and will be marked as such by the event bus.
+ *
+ * Alternatively, return retryAfter (ms) to request re-delivery after a delay.
+ * Events with retryAfter stay pending until explicitly ACKed via EVENT_ACK.
+ * This enables async processing patterns where the subscriber needs time to process.
+ */
+export const OnEventsOutputSchema = z.object({
+  /** Whether all events were successfully processed */
+  success: z
+    .boolean()
+    .describe("True if all events were successfully processed"),
+
+  /** Optional error message if success=false */
+  error: z.string().optional().describe("Error message if processing failed"),
+
+  /** Optional count of successfully processed events */
+  processedCount: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Number of events successfully processed"),
+
+  /**
+   * Request re-delivery after this many milliseconds.
+   * Events remain pending until explicitly ACKed via EVENT_ACK.
+   * Does not count toward max retry attempts.
+   */
+  retryAfter: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Request re-delivery after this many ms. Call EVENT_ACK to mark delivered.",
+    ),
+});
+
+/**
+ * ON_EVENTS Output type
+ */
+export type OnEventsOutput = z.infer<typeof OnEventsOutputSchema>;
+
+/**
+ * Event Subscriber Binding
+ *
+ * Defines the interface for MCP connections that can receive events.
+ * Implementations must provide the ON_EVENTS tool to receive batched CloudEvents.
+ *
+ * Required tools:
+ * - ON_EVENTS: Receive and process a batch of CloudEvents
+ */
+export const EVENT_SUBSCRIBER_BINDING = [
+  {
+    name: "ON_EVENTS" as const,
+    inputSchema: OnEventsInputSchema,
+    outputSchema: OnEventsOutputSchema,
+  },
+] satisfies ToolBinder[];
+
+/**
+ * Event Subscriber Binding Client
+ *
+ * Use this to create a client for calling ON_EVENTS on subscriber connections.
+ *
+ * @example
+ * ```typescript
+ * import { EventSubscriberBinding } from "@decocms/bindings/event-subscriber";
+ *
+ * // For a connection
+ * const client = EventSubscriberBinding.forConnection(connection);
+ * const result = await client.ON_EVENTS({ events: [...] });
+ *
+ * // For an MCP client
+ * const client = EventSubscriberBinding.forClient(mcpClient);
+ * const result = await client.ON_EVENTS({ events: [...] });
+ * ```
+ */
+export const EventSubscriberBinding = bindingClient(EVENT_SUBSCRIBER_BINDING);
+
+/**
+ * Type helper for the Event Subscriber binding client
+ */
+export type EventSubscriberBindingClient = ReturnType<
+  typeof EventSubscriberBinding.forConnection
+>;