@decocms/bindings 0.1.0

package/README.md

@@ -0,0 +1,680 @@
+# @decocms/bindings
+
+Core type definitions and utilities for the bindings system. Bindings define standardized interfaces that integrations (MCPs - Model Context Protocols) can implement, similar to TypeScript interfaces but with runtime validation.
+
+## Installation
+
+Install the package using npm or bun:
+
+```bash
+npm install @decocms/bindings
+```
+
+or with bun:
+
+```bash
+bun add @decocms/bindings
+```
+
+**Note:** This package requires `zod` as a peer dependency. If you don't already have `zod` installed in your project, you'll need to install it separately.
+
+## What are Bindings?
+
+Bindings are a core concept for defining and enforcing standardized interfaces that MCPs can implement. They provide a type-safe, declarative way to specify what tools (methods) and schemas an integration must expose to be compatible with certain parts of the system.
+
+### Key Features
+
+- **Standardization**: Define contracts (schemas and method names) that MCPs must implement
+- **Type Safety**: Leverage Zod schemas and TypeScript types for correct data structures
+- **Runtime Validation**: Check if an integration implements a binding at runtime
+- **Extensibility**: Create new bindings for any use case
+
+## Usage
+
+### 1. Defining a Binding
+
+A binding is an array of tool definitions, each specifying a name and input/output schemas:
+
+```typescript
+import { z } from "zod";
+import type { Binder } from "@decocms/bindings";
+
+// Define input/output schemas
+const joinChannelInput = z.object({
+  workspace: z.string(),
+  discriminator: z.string(),
+  agentId: z.string(),
+});
+
+const channelOutput = z.object({
+  success: z.boolean(),
+  channelId: z.string(),
+});
+
+// Define the binding
+export const CHANNEL_BINDING = [
+  {
+    name: "DECO_CHAT_CHANNELS_JOIN" as const,
+    inputSchema: joinChannelInput,
+    outputSchema: channelOutput,
+  },
+  {
+    name: "DECO_CHAT_CHANNELS_LEAVE" as const,
+    inputSchema: z.object({ channelId: z.string() }),
+    outputSchema: z.object({ success: z.boolean() }),
+  },
+  {
+    name: "DECO_CHAT_CHANNELS_LIST" as const,
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+      channels: z.array(z.object({
+        label: z.string(),
+        value: z.string(),
+      })),
+    }),
+    opt: true, // This tool is optional
+  },
+] as const satisfies Binder;
+```
+
+### 2. Checking if Tools Implement a Binding
+
+Use `createBindingChecker` to verify if a set of tools implements a binding:
+
+```typescript
+import { createBindingChecker } from "@decocms/bindings";
+
+// Create a checker for your binding
+const channelChecker = createBindingChecker(CHANNEL_BINDING);
+
+// Check if available tools implement the binding
+const availableTools = [
+  { name: "DECO_CHAT_CHANNELS_JOIN" },
+  { name: "DECO_CHAT_CHANNELS_LEAVE" },
+  { name: "DECO_CHAT_CHANNELS_LIST" },
+  { name: "OTHER_TOOL" },
+];
+
+const isImplemented = channelChecker.isImplementedBy(availableTools);
+console.log(isImplemented); // true - all required tools are present
+
+// Optional tools don't need to be present
+const minimalTools = [
+  { name: "DECO_CHAT_CHANNELS_JOIN" },
+  { name: "DECO_CHAT_CHANNELS_LEAVE" },
+];
+
+const stillValid = channelChecker.isImplementedBy(minimalTools);
+console.log(stillValid); // true - CHANNELS_LIST is optional
+```
+
+### 3. Using RegExp for Tool Names
+
+You can use RegExp patterns for flexible tool matching:
+
+```typescript
+export const RESOURCE_BINDING = [
+  {
+    name: /^DECO_RESOURCE_\w+_SEARCH$/ as RegExp,
+    inputSchema: z.object({ term: z.string() }),
+    outputSchema: z.object({ items: z.array(z.any()) }),
+  },
+] as const satisfies Binder;
+
+// This will match: DECO_RESOURCE_WORKFLOW_SEARCH, DECO_RESOURCE_USER_SEARCH, etc.
+```
+
+### 4. Type Safety with Bindings
+
+TypeScript can infer types from your binding definitions:
+
+```typescript
+import type { ToolBinder } from "@decocms/bindings";
+
+// Extract the type of a specific tool
+type JoinChannelTool = typeof CHANNEL_BINDING[0];
+
+// Get input type
+type JoinChannelInput = z.infer<JoinChannelTool["inputSchema"]>;
+
+// Get output type
+type JoinChannelOutput = z.infer<NonNullable<JoinChannelTool["outputSchema"]>>;
+```
+
+## API Reference
+
+### Types
+
+#### `ToolBinder<TName, TInput, TReturn>`
+
+Defines a single tool within a binding.
+
+- `name`: Tool name (string or RegExp)
+- `inputSchema`: Zod schema for input validation
+- `outputSchema?`: Optional Zod schema for output validation
+- `opt?`: If true, tool is optional in the binding
+
+#### `Binder<TDefinition>`
+
+Represents a collection of tool definitions that form a binding.
+
+#### `BindingChecker`
+
+Interface with an `isImplementedBy` method for checking binding implementations.
+
+### Functions
+
+#### `createBindingChecker<TDefinition>(binderTools: TDefinition): BindingChecker`
+
+Creates a binding checker that can verify if a set of tools implements the binding.
+
+**Parameters:**
+- `binderTools`: The binding definition to check against
+
+**Returns:**
+- A `BindingChecker` with an `isImplementedBy` method
+
+**Example:**
+```typescript
+const checker = createBindingChecker(MY_BINDING);
+const isValid = checker.isImplementedBy(availableTools);
+```
+
+## Common Patterns
+
+### Well-Known Bindings
+
+The package includes pre-defined bindings for common use cases. Well-known bindings are organized in the `well-known` folder and must be imported directly:
+
+- **Collections**: `@decocms/bindings/well-known/collections` - Collection bindings for SQL table-like structures
+- **Models**: `@decocms/bindings/well-known/models` - AI model providers interface
+
+See the [Collection Bindings](#collection-bindings) and [Models Bindings](#models-bindings) sections below for detailed usage examples.
+
+### Generic Bindings
+
+Create factory functions for generic bindings:
+
+```typescript
+function createResourceBinding(resourceName: string) {
+  return [
+    {
+      name: `DECO_RESOURCE_${resourceName.toUpperCase()}_SEARCH` as const,
+      inputSchema: z.object({ term: z.string() }),
+      outputSchema: z.object({ items: z.array(z.any()) }),
+    },
+    {
+      name: `DECO_RESOURCE_${resourceName.toUpperCase()}_READ` as const,
+      inputSchema: z.object({ uri: z.string() }),
+      outputSchema: z.object({ data: z.any() }),
+    },
+  ] as const satisfies Binder;
+}
+
+const workflowBinding = createResourceBinding("workflow");
+```
+
+## Collection Bindings
+
+Collection bindings provide standardized CRUD + Search operations for SQL table-like collections, compatible with TanStack DB query-collection. They are designed for database tables where each entity has a unique URI and audit trail fields.
+
+### Key Features
+
+- **SQL Table-like Structure**: Represents database tables with standardized operations
+- **URI-based Identification**: Uses collection URIs in format `rsc://{connectionid}/{collection_name}/{item_id}`
+- **Audit Trail**: All entities must include `created_at`, `updated_at`, `created_by`, and `updated_by` fields
+- **TanStack DB Compatible**: Works seamlessly with TanStack DB's query-collection LoadSubsetOptions
+- **Type-Safe**: Full TypeScript support with Zod validation
+
+### Base Entity Schema Requirements
+
+All collection entity schemas must extend `BaseCollectionEntitySchema`, which requires:
+
+- `uri`: Collection URI in format `rsc://{connectionid}/{collection_name}/{item_id}`
+- `created_at`: Creation timestamp (datetime string)
+- `updated_at`: Last update timestamp (datetime string)
+- `created_by`: User who created the entity (optional string)
+- `updated_by`: User who last updated the entity (optional string)
+
+### Using Collection Bindings
+
+Collection bindings are a well-known binding pattern for SQL table-like structures. Import them from the well-known collections module:
+
+```typescript
+import { z } from "zod";
+import { createCollectionBindings } from "@decocms/bindings/well-known/collections";
+import { createBindingChecker } from "@decocms/bindings";
+
+// Define your entity schema extending the base schema
+const TodoSchema = z.object({
+  uri: z.string(), // Collection URI: rsc://{connectionid}/todos/{item_id}
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  created_by: z.string().optional(),
+  updated_by: z.string().optional(),
+  // Your custom fields
+  title: z.string(),
+  completed: z.boolean(),
+  userId: z.number(),
+});
+
+// Create the collection binding (full CRUD)
+const TODO_COLLECTION_BINDING = createCollectionBindings("todos", TodoSchema);
+
+// Create a read-only collection binding (only LIST and GET)
+const READONLY_COLLECTION_BINDING = createCollectionBindings("products", ProductSchema, {
+  readOnly: true,
+});
+
+// Create a checker to verify if tools implement the binding
+const todoChecker = createBindingChecker(TODO_COLLECTION_BINDING);
+
+// Check if available tools implement the binding
+const availableTools = [
+  { name: "DECO_COLLECTION_TODOS_LIST" },
+  { name: "DECO_COLLECTION_TODOS_GET" },
+  { name: "DECO_COLLECTION_TODOS_INSERT" },
+  { name: "DECO_COLLECTION_TODOS_UPDATE" },
+  { name: "DECO_COLLECTION_TODOS_DELETE" },
+];
+
+const isImplemented = await todoChecker.isImplementedBy(availableTools);
+console.log(isImplemented); // true if all required tools are present
+```
+
+### Collection Operations
+
+The `createCollectionBindings` function generates tool bindings based on the `readOnly` option:
+
+**Required operations (always included):**
+
+1. **LIST** - `DECO_COLLECTION_{NAME}_LIST`
+   - Query/search entities with filtering, sorting, and pagination
+   - Input: `where?`, `orderBy?`, `limit?`, `offset?`
+   - Output: `items[]`, `totalCount?`, `hasMore?`
+
+2. **GET** - `DECO_COLLECTION_{NAME}_GET`
+   - Get a single entity by URI
+   - Input: `uri`
+   - Output: `item | null`
+
+**Optional operations (excluded if `readOnly: true`):**
+
+3. **INSERT** - `DECO_COLLECTION_{NAME}_INSERT`
+   - Create a new entity
+   - Input: `data` (without uri, which is auto-generated)
+   - Output: `item` (with generated URI)
+
+4. **UPDATE** - `DECO_COLLECTION_{NAME}_UPDATE`
+   - Update an existing entity
+   - Input: `uri`, `data` (partial)
+   - Output: `item`
+
+5. **DELETE** - `DECO_COLLECTION_{NAME}_DELETE`
+   - Delete an entity
+   - Input: `uri`
+   - Output: `success`, `uri`
+
+### Read-Only Collections
+
+To create a read-only collection (only LIST and GET operations), pass `{ readOnly: true }` as the third parameter:
+
+```typescript
+// Read-only collection - only LIST and GET operations
+const READONLY_COLLECTION_BINDING = createCollectionBindings(
+  "products",
+  ProductSchema,
+  { readOnly: true }
+);
+```
+
+This is useful for collections that are managed externally or should not be modified through the MCP interface.
+
+## Models Bindings
+
+Models bindings provide a well-known interface for AI model providers. They use collection bindings under the hood for LIST and GET operations, and add a streaming endpoint tool.
+
+### Using Models Bindings
+
+```typescript
+import { MODELS_BINDING, MODELS_COLLECTION_BINDING } from "@decocms/bindings/well-known/models";
+import { createBindingChecker } from "@decocms/bindings";
+
+// Use the pre-defined MODELS_BINDING
+const modelsChecker = createBindingChecker(MODELS_BINDING);
+
+// Check if available tools implement the binding
+const availableTools = [
+  { name: "DECO_COLLECTION_MODELS_LIST" },
+  { name: "DECO_COLLECTION_MODELS_GET" },
+  { name: "GET_STREAM_ENDPOINT" },
+];
+
+const isImplemented = await modelsChecker.isImplementedBy(availableTools);
+console.log(isImplemented); // true if all required tools are present
+```
+
+### Models Binding Tools
+
+The `MODELS_BINDING` includes:
+
+1. **DECO_COLLECTION_MODELS_LIST** (required)
+   - List available AI models with their capabilities
+   - Uses collection binding LIST operation
+   - Input: `where?`, `orderBy?`, `limit?`, `offset?`
+   - Output: `items[]` (array of model entities)
+
+2. **DECO_COLLECTION_MODELS_GET** (required)
+   - Get a single model by URI
+   - Uses collection binding GET operation
+   - Input: `uri`
+   - Output: `item | null`
+
+3. **GET_STREAM_ENDPOINT** (required)
+   - Get the streaming endpoint URL for chat completions
+   - Input: `{}` (empty object, passthrough)
+   - Output: `{ url?: string }` (optional URL)
+
+### Model Entity Schema
+
+Models follow the collection entity schema with additional model-specific fields:
+
+```typescript
+{
+  uri: string;                    // Collection URI
+  created_at: string;            // Creation timestamp
+  updated_at: string;             // Last update timestamp
+  created_by?: string;           // User who created
+  updated_by?: string;           // User who last updated
+  id: string;                    // Model ID
+  model: string;                 // Model identifier
+  name: string;                  // Display name
+  logo: string | null;           // Logo URL
+  capabilities: string[];         // Array of capabilities
+  contextWindow: number | null;   // Context window size
+  inputCost: number | null;      // Input cost per token
+  outputCost: number | null;     // Output cost per token
+  outputLimit: number | null;    // Output limit
+  description: string | null;    // Model description
+}
+```
+
+### MCP Implementation Example
+
+Here's how you would implement the models binding in an MCP server:
+
+```typescript
+import { MODELS_BINDING } from "@decocms/bindings/well-known/models";
+import { parseCollectionUri } from "@decocms/bindings/well-known/collections";
+import { impl } from "@decocms/sdk/mcp/bindings/binder";
+
+const modelTools = impl(MODELS_BINDING, [
+  {
+    description: "List available AI models",
+    handler: async ({ where, orderBy, limit, offset }) => {
+      // Query your models database
+      const items = await db.models.findMany({
+        where: convertWhereToSQL(where),
+        orderBy: convertOrderByToSQL(orderBy),
+        take: limit,
+        skip: offset,
+      });
+      
+      return { items, hasMore: items.length === limit };
+    },
+  },
+  {
+    description: "Get a model by URI",
+    handler: async ({ uri }) => {
+      const parsed = parseCollectionUri(uri);
+      const item = await db.models.findUnique({
+        where: { id: parsed.itemId },
+      });
+      return { item };
+    },
+  },
+  {
+    description: "Get streaming endpoint",
+    handler: async () => {
+      // Return your streaming endpoint URL
+      return { url: "https://api.example.com/v1/chat/completions" };
+    },
+  },
+]);
+```
+
+### Where Expression Structure
+
+The `where` parameter supports TanStack DB predicate push-down patterns:
+
+```typescript
+// Simple comparison
+{
+  field: ["category"],
+  operator: "eq",
+  value: "electronics"
+}
+
+// Logical operators
+{
+  operator: "and",
+  conditions: [
+    { field: ["category"], operator: "eq", value: "electronics" },
+    { field: ["price"], operator: "lt", value: 100 }
+  ]
+}
+```
+
+**Supported Operators:**
+- Comparison: `eq`, `gt`, `gte`, `lt`, `lte`, `in`, `like`, `contains`
+- Logical: `and`, `or`, `not`
+
+### Order By Expression Structure
+
+The `orderBy` parameter supports multi-field sorting:
+
+```typescript
+[
+  {
+    field: ["price"],
+    direction: "asc",
+    nulls: "last" // optional: "first" | "last"
+  },
+  {
+    field: ["created_at"],
+    direction: "desc"
+  }
+]
+```
+
+### Collection URI Helpers
+
+The package provides utility functions for working with collection URIs:
+
+```typescript
+import {
+  validateCollectionUri,
+  parseCollectionUri,
+  constructCollectionUri,
+} from "@decocms/bindings/well-known/collections";
+
+// Validate a URI
+const isValid = validateCollectionUri("rsc://conn-123/users/user-456");
+// true
+
+// Parse a URI into components
+const parsed = parseCollectionUri("rsc://conn-123/users/user-456");
+// { connectionId: "conn-123", collectionName: "users", itemId: "user-456" }
+
+// Construct a URI from components
+const uri = constructCollectionUri("conn-123", "users", "user-456");
+// "rsc://conn-123/users/user-456"
+```
+
+### TanStack DB Integration
+
+Collection bindings are designed to work with TanStack DB's query-collection. The `where` and `orderBy` expressions are compatible with TanStack DB's `LoadSubsetOptions`, allowing for efficient predicate push-down to your backend.
+
+### MCP Implementation Example
+
+Here's how you would implement a collection binding in an MCP server:
+
+```typescript
+import { z } from "zod";
+import { createCollectionBindings } from "@decocms/bindings/well-known/collections";
+import { parseCollectionUri, constructCollectionUri } from "@decocms/bindings/well-known/collections";
+import { impl } from "@decocms/sdk/mcp/bindings/binder";
+
+const TodoSchema = z.object({
+  uri: z.string(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  created_by: z.string().optional(),
+  updated_by: z.string().optional(),
+  title: z.string(),
+  completed: z.boolean(),
+  userId: z.number(),
+});
+
+const TODO_COLLECTION_BINDING = createCollectionBindings("todos", TodoSchema);
+
+// Implement the tools
+const todoTools = impl(TODO_COLLECTION_BINDING, [
+  {
+    description: "List todos with filtering and sorting",
+    handler: async ({ where, orderBy, limit, offset }) => {
+      // Convert where/orderBy to SQL and query database
+      const items = await db.todos.findMany({
+        where: convertWhereToSQL(where),
+        orderBy: convertOrderByToSQL(orderBy),
+        take: limit,
+        skip: offset,
+      });
+      
+      return { items, hasMore: items.length === limit };
+    },
+  },
+  {
+    description: "Get a todo by URI",
+    handler: async ({ uri }) => {
+      const parsed = parseCollectionUri(uri);
+      const item = await db.todos.findUnique({
+        where: { id: parsed.itemId },
+      });
+      return { item };
+    },
+  },
+  {
+    description: "Create a new todo",
+    handler: async ({ data }) => {
+      const item = await db.todos.create({ data });
+      const uri = constructCollectionUri(
+        connectionId,
+        "todos",
+        item.id
+      );
+      return { item: { ...item, uri } };
+    },
+  },
+  {
+    description: "Update a todo",
+    handler: async ({ uri, data }) => {
+      const parsed = parseCollectionUri(uri);
+      const item = await db.todos.update({
+        where: { id: parsed.itemId },
+        data,
+      });
+      return { item };
+    },
+  },
+  {
+    description: "Delete a todo",
+    handler: async ({ uri }) => {
+      const parsed = parseCollectionUri(uri);
+      await db.todos.delete({ where: { id: parsed.itemId } });
+      return { success: true, uri };
+    },
+  },
+]);
+```
+
+### Type Safety
+
+TypeScript can infer types from your collection binding definitions:
+
+```typescript
+import type {
+  CollectionBinding,
+  CollectionTools,
+  CollectionListInput,
+  CollectionGetInput,
+  CollectionDeleteInput,
+} from "@decocms/bindings/well-known/collections";
+
+// Extract the binding type
+type TodoBinding = typeof TODO_COLLECTION_BINDING;
+
+// Extract tool names
+type TodoTools = CollectionTools<typeof TodoSchema>;
+// "DECO_COLLECTION_TODOS_LIST" | "DECO_COLLECTION_TODOS_GET" | ...
+
+// Get input types
+type ListInput = CollectionListInput;
+type GetInput = CollectionGetInput;
+type DeleteInput = CollectionDeleteInput;
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Build the package
+bun run build
+
+# Run tests
+bun run test
+
+# Watch mode for tests
+bun run test:watch
+```
+
+### Building
+
+The package uses [tsup](https://tsup.egoist.dev/) for building:
+
+```bash
+bun run build
+```
+
+This will generate ESM output in the `dist/` directory with TypeScript declarations.
+
+### Testing
+
+Tests are written with [Vitest](https://vitest.dev/):
+
+```bash
+# Run tests once
+bun run test
+
+# Watch mode
+bun run test:watch
+```
+
+## Publishing
+
+The package is automatically published to npm when a tag matching `bindings-v*` is pushed:
+
+```bash
+# Update version in package.json, then:
+git tag bindings-v0.1.0
+git push origin bindings-v0.1.0
+```
+
+## License
+
+See the root LICENSE.md file in the repository.
+