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

package/package.json

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

package/src/index.ts

@@ -25,6 +25,8 @@ export {
 export {
   CloudEventSchema,
   type CloudEvent,
+  EventResultSchema,
+  type EventResult,
   OnEventsInputSchema,
   type OnEventsInput,
   OnEventsOutputSchema,
@@ -56,6 +58,14 @@ export {
   type EventAckInput,
   EventAckOutputSchema,
   type EventAckOutput,
+  SubscriptionItemSchema,
+  type SubscriptionItem,
+  SubscriptionDetailSchema,
+  type SubscriptionDetail,
+  EventSyncSubscriptionsInputSchema,
+  type EventSyncSubscriptionsInput,
+  EventSyncSubscriptionsOutputSchema,
+  type EventSyncSubscriptionsOutput,
   EVENT_BUS_BINDING,
   EventBusBinding,
   type EventBusBindingClient,

package/src/well-known/collections.ts

@@ -45,22 +45,30 @@ const ComparisonExpressionSchema = z.object({
 });
 
 /**
- * Where expression schema for filtering
- * Supports TanStack DB predicate push-down patterns
+ * Where expression type for filtering
+ * Recursive to allow nested logical operators
  */
-export const WhereExpressionSchema = z.union([
-  ComparisonExpressionSchema,
-  z.object({
-    operator: z.enum(["and", "or", "not"]),
-    conditions: z.array(ComparisonExpressionSchema),
-  }),
-]);
+export type WhereExpression =
+  | z.infer<typeof ComparisonExpressionSchema>
+  | {
+      operator: "and" | "or" | "not";
+      conditions: WhereExpression[];
+    };
 
 /**
- * Where expression type for filtering
- * Derived from WhereExpressionSchema
+ * Where expression schema for filtering
+ * Supports TanStack DB predicate push-down patterns
+ * Recursive to allow nested logical operators
  */
-export type WhereExpression = z.infer<typeof WhereExpressionSchema>;
+export const WhereExpressionSchema: z.ZodType<WhereExpression> = z.lazy(() =>
+  z.union([
+    ComparisonExpressionSchema,
+    z.object({
+      operator: z.enum(["and", "or", "not"]),
+      conditions: z.array(WhereExpressionSchema),
+    }),
+  ]),
+);
 
 /**
  * Order by expression for sorting

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

@@ -159,6 +159,119 @@ export const EventSubscribeOutputSchema = z.object({
 
 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
 // ============================================================================
@@ -259,7 +372,7 @@ export type EventAckOutput = z.infer<typeof EventAckOutputSchema>;
  * Event Bus Binding
  *
  * Defines the interface for interacting with an event bus.
- * Implementations must provide PUBLISH, SUBSCRIBE, UNSUBSCRIBE, CANCEL, and ACK tools.
+ * 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)
@@ -267,6 +380,7 @@ export type EventAckOutput = z.infer<typeof EventAckOutputSchema>;
  * - 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 = [
   {
@@ -294,6 +408,11 @@ export const EVENT_BUS_BINDING = [
     inputSchema: EventAckInputSchema,
     outputSchema: EventAckOutputSchema,
   },
+  {
+    name: "EVENT_SYNC_SUBSCRIPTIONS" as const,
+    inputSchema: EventSyncSubscriptionsInputSchema,
+    outputSchema: EventSyncSubscriptionsOutputSchema,
+  },
 ] satisfies ToolBinder[];
 
 /**

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

@@ -104,24 +104,81 @@ export const OnEventsInputSchema = z.object({
  */
 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
  *
- * Returns success status. If success=true, all events in the batch
- * are considered delivered and will be marked as such by the event bus.
+ * Two modes of operation:
+ *
+ * 1. **Batch mode** (backward compatible): Use `success`, `error`, `retryAfter`
+ *    to apply the same result to all events in the batch.
  *
- * 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.
+ * 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({
-  /** Whether all events were successfully processed */
+  /** Batch-level success (applies to events not in `results`) */
   success: z
     .boolean()
-    .describe("True if all events were successfully processed"),
+    .optional()
+    .describe("Batch success - applies to events not in results"),
 
-  /** Optional error message if success=false */
-  error: z.string().optional().describe("Error message if processing failed"),
+  /** 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
@@ -132,18 +189,24 @@ export const OnEventsOutputSchema = z.object({
     .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.
+   * Batch-level re-delivery request (applies to events not in `results`)
    */
   retryAfter: z
     .number()
     .int()
     .positive()
     .optional()
-    .describe(
-      "Request re-delivery after this many ms. Call EVENT_ACK to mark delivered.",
-    ),
+    .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"),
 });
 
 /**