@decocms/bindings 1.0.1-alpha.4 → 1.0.2

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

@@ -0,0 +1,454 @@
+/**
+ * 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>;
+
+// ============================================================================
+// Sync Subscriptions Schemas
+// ============================================================================
+
+/**
+ * Subscription item schema for sync operations
+ */
+export const SubscriptionItemSchema = 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 SubscriptionItem = z.infer<typeof SubscriptionItemSchema>;
+
+/**
+ * Subscription detail schema (returned in responses)
+ */
+export const SubscriptionDetailSchema = 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 SubscriptionDetail = z.infer<typeof SubscriptionDetailSchema>;
+
+/**
+ * EVENT_SYNC_SUBSCRIPTIONS Input Schema
+ *
+ * Input for syncing subscriptions to a desired state.
+ * The system will create new, delete removed, and update changed subscriptions.
+ * Subscriptions are identified by (eventType, publisher) - only one subscription
+ * per combination is allowed.
+ */
+export const EventSyncSubscriptionsInputSchema = z.object({
+  /** Desired subscriptions - system will create/update/delete to match */
+  subscriptions: z
+    .array(SubscriptionItemSchema)
+    .describe(
+      "Desired subscriptions - system will create/update/delete to match",
+    ),
+});
+
+export type EventSyncSubscriptionsInput = z.infer<
+  typeof EventSyncSubscriptionsInputSchema
+>;
+
+/**
+ * EVENT_SYNC_SUBSCRIPTIONS Output Schema
+ */
+export const EventSyncSubscriptionsOutputSchema = z.object({
+  /** Number of new subscriptions created */
+  created: z.number().int().min(0).describe("Number of subscriptions created"),
+
+  /** Number of subscriptions with filter updated */
+  updated: z
+    .number()
+    .int()
+    .min(0)
+    .describe("Number of subscriptions with filter updated"),
+
+  /** Number of old subscriptions removed */
+  deleted: z.number().int().min(0).describe("Number of subscriptions removed"),
+
+  /** Number of subscriptions unchanged */
+  unchanged: z
+    .number()
+    .int()
+    .min(0)
+    .describe("Number of subscriptions unchanged"),
+
+  /** Current subscriptions after sync */
+  subscriptions: z
+    .array(SubscriptionDetailSchema)
+    .describe("Current subscriptions after sync"),
+});
+
+export type EventSyncSubscriptionsOutput = z.infer<
+  typeof EventSyncSubscriptionsOutputSchema
+>;
+
+// ============================================================================
+// 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, ACK, and SYNC_SUBSCRIPTIONS 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)
+ * - EVENT_SYNC_SUBSCRIPTIONS: Sync subscriptions to desired state
+ */
+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,
+  },
+  {
+    name: "EVENT_SYNC_SUBSCRIPTIONS" as const,
+    inputSchema: EventSyncSubscriptionsInputSchema,
+    outputSchema: EventSyncSubscriptionsOutputSchema,
+  },
+] 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,259 @@
+/**
+ * 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>;
+
+/**
+ * Per-event result schema
+ * Allows granular control over each event in a batch
+ *
+ * Three modes:
+ * - `{ success: true }` - Event processed successfully
+ * - `{ success: false, error: "..." }` - Event failed permanently
+ * - `{ retryAfter: 60000 }` - Retry later (success not yet determined)
+ */
+export const EventResultSchema = z.object({
+  /** Whether this specific event was processed successfully */
+  success: z
+    .boolean()
+    .optional()
+    .describe("Whether this event was processed successfully"),
+
+  /** Error message if success=false */
+  error: z.string().optional().describe("Error message for this event"),
+
+  /**
+   * Request re-delivery of this event after this many milliseconds.
+   * Does not count toward max retry attempts.
+   * When present without success, indicates the event should be retried.
+   */
+  retryAfter: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Re-deliver this event after this many ms"),
+});
+
+/**
+ * Per-event result type
+ */
+export type EventResult = z.infer<typeof EventResultSchema>;
+
+/**
+ * ON_EVENTS Output Schema
+ *
+ * Two modes of operation:
+ *
+ * 1. **Batch mode** (backward compatible): Use `success`, `error`, `retryAfter`
+ *    to apply the same result to all events in the batch.
+ *
+ * 2. **Per-event mode**: Use `results` to specify individual outcomes for each event.
+ *    Keys are event IDs, values are per-event results.
+ *    Events not in `results` will use the batch-level fields as fallback.
+ *
+ * @example
+ * // Batch mode - all events succeeded
+ * { success: true }
+ *
+ * @example
+ * // Per-event mode - mixed results
+ * {
+ *   results: {
+ *     "event-1": { success: true },
+ *     "event-2": { success: false, error: "Validation failed" },
+ *     "event-3": { retryAfter: 60000 }
+ *   }
+ * }
+ */
+export const OnEventsOutputSchema = z.object({
+  /** Batch-level success (applies to events not in `results`) */
+  success: z
+    .boolean()
+    .optional()
+    .describe("Batch success - applies to events not in results"),
+
+  /** Batch-level error message */
+  error: z
+    .string()
+    .optional()
+    .describe("Batch error message - applies to events not in results"),
+
+  /** Optional count of successfully processed events */
+  processedCount: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Number of events successfully processed"),
+
+  /**
+   * Batch-level re-delivery request (applies to events not in `results`)
+   */
+  retryAfter: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Batch retryAfter - applies to events not in results"),
+
+  /**
+   * Per-event results, keyed by event ID.
+   * Allows different handling for each event in the batch.
+   * Events not specified here use batch-level fields as fallback.
+   */
+  results: z
+    .record(z.string(), EventResultSchema)
+    .optional()
+    .describe("Per-event results keyed by event ID"),
+});
+
+/**
+ * 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
+>;