@decocms/bindings 0.2.1 → 0.2.3

package/src/core/binder.ts

@@ -1,226 +0,0 @@
-/**
- * Core Binder Types and Utilities
- *
- * This module provides the core types and utilities for the bindings system.
- * Bindings define standardized interfaces that integrations (MCPs) can implement.
- */
-
-import type { ZodType } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
-import { diffSchemas } from "json-schema-diff";
-
-/**
- * ToolBinder defines a single tool within a binding.
- * It specifies the tool name, input/output schemas, and whether it's optional.
- *
- * @template TName - The tool name (can be a string or RegExp for pattern matching)
- * @template TInput - The input type (inferred from inputSchema)
- * @template TReturn - The return type (inferred from outputSchema)
- */
-export interface ToolBinder<
-  TName extends string | RegExp = string,
-  // biome-ignore lint/suspicious/noExplicitAny: Generic type parameter
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TInput = any,
-  TReturn extends object | null | boolean = object,
-> {
-  /** The name of the tool (e.g., "DECO_CHAT_CHANNELS_JOIN") */
-  name: TName;
-
-  /** Zod schema for validating tool input */
-  inputSchema: ZodType<TInput>;
-
-  /** Optional Zod schema for validating tool output */
-  outputSchema?: ZodType<TReturn>;
-
-  /**
-   * Whether this tool is optional in the binding.
-   * If true, an implementation doesn't need to provide this tool.
-   */
-  opt?: true;
-}
-
-/**
- * Binder represents a collection of tool definitions that form a binding.
- * A binding is like a TypeScript interface - it defines what tools must be implemented.
- *
- * @template TDefinition - Array of ToolBinder definitions
- *
- * @example
- * ```ts
- * const MY_BINDING = [{
- *   name: "MY_TOOL" as const,
- *   inputSchema: z.object({ id: z.string() }),
- *   outputSchema: z.object({ success: z.boolean() }),
- * }] as const satisfies Binder;
- * ```
- */
-export type Binder<
-  TDefinition extends readonly ToolBinder[] = readonly ToolBinder[],
-> = TDefinition;
-
-/**
- * Tool with schemas for validation
- */
-export interface ToolWithSchemas {
-  name: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  inputSchema?: ZodType<any> | Record<string, unknown>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  outputSchema?: ZodType<any> | Record<string, unknown>;
-}
-
-/**
- * Converts a schema to JSON Schema format if it's a Zod schema
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function normalizeSchema(schema: any): Record<string, unknown> | undefined {
-  if (!schema) return undefined;
-
-  // If it's a Zod schema (has _def property), convert it
-  if (schema._def) {
-    const jsonSchema = zodToJsonSchema(schema, {
-      // Don't add additionalProperties: false to allow structural compatibility
-      $refStrategy: "none",
-    }) as Record<string, unknown>;
-
-    // Remove additionalProperties constraint to allow subtyping
-    if (jsonSchema.type === "object") {
-      delete jsonSchema.additionalProperties;
-    }
-
-    return jsonSchema;
-  }
-
-  // Otherwise assume it's already a JSON Schema
-  const jsonSchema = schema as Record<string, unknown>;
-
-  // Remove additionalProperties constraint if present
-  if (jsonSchema.type === "object" && "additionalProperties" in jsonSchema) {
-    const copy = { ...jsonSchema };
-    delete copy.additionalProperties;
-    return copy;
-  }
-
-  return jsonSchema;
-}
-
-/**
- * Binding checker interface
- */
-export interface BindingChecker {
-  /**
-   * Check if a set of tools implements the binding with full schema validation.
-   *
-   * Validates:
-   * - Tool name matches (exact or regex)
-   * - Input schema: Tool accepts what binder requires (no removals from binder to tool)
-   * - Output schema: Tool provides what binder expects (no removals from tool to binder)
-   *
-   * @param tools - Array of tools with names and schemas
-   * @returns Promise<boolean> - true if all tools implement the binding correctly
-   */
-  isImplementedBy: (tools: ToolWithSchemas[]) => Promise<boolean>;
-}
-
-/**
- * Creates a binding checker with full schema validation using json-schema-diff.
- *
- * This performs strict compatibility checking:
- * - For input schemas: Validates that the tool can accept what the binder requires
- * - For output schemas: Validates that the tool provides what the binder expects
- *
- * @param binderTools - The binding definition to check against
- * @returns A binding checker with an async isImplementedBy method
- *
- * @example
- * ```ts
- * const checker = createBindingChecker(MY_BINDING);
- * const isCompatible = await checker.isImplementedBy(availableTools);
- * ```
- */
-export function createBindingChecker<TDefinition extends readonly ToolBinder[]>(
-  binderTools: TDefinition,
-): BindingChecker {
-  return {
-    isImplementedBy: async (tools: ToolWithSchemas[]) => {
-      for (const binderTool of binderTools) {
-        // Find matching tool by name (exact or regex)
-        const pattern =
-          typeof binderTool.name === "string"
-            ? new RegExp(`^${binderTool.name}$`)
-            : binderTool.name;
-
-        const matchedTool = tools.find((t) => pattern.test(t.name));
-
-        // Skip optional tools that aren't present
-        if (!matchedTool && binderTool.opt) {
-          continue;
-        }
-
-        // Required tool not found
-        if (!matchedTool) {
-          return false;
-        }
-
-        // === INPUT SCHEMA VALIDATION ===
-        // Tool must accept what binder requires
-        // Check: binder (source) -> tool (destination)
-        // If removals found, tool doesn't accept something binder requires
-        const binderInputSchema = normalizeSchema(binderTool.inputSchema);
-        const toolInputSchema = normalizeSchema(matchedTool.inputSchema);
-
-        if (binderInputSchema && toolInputSchema) {
-          try {
-            const inputDiff = await diffSchemas({
-              sourceSchema: binderInputSchema,
-              destinationSchema: toolInputSchema,
-            });
-
-            // If something was removed from binder to tool, tool can't accept it
-            if (inputDiff.removalsFound) {
-              return false;
-            }
-          } catch (error) {
-            console.error("Schema diff failed", error);
-            // Schema diff failed - consider incompatible
-            return false;
-          }
-        } else if (binderInputSchema && !toolInputSchema) {
-          // Binder requires input schema but tool doesn't have one
-          return false;
-        }
-
-        // === OUTPUT SCHEMA VALIDATION ===
-        // Tool must provide what binder expects (but can provide more)
-        // Check: binder (source) -> tool (destination)
-        // If removals found, tool doesn't provide something binder expects
-        const binderOutputSchema = normalizeSchema(binderTool.outputSchema);
-        const toolOutputSchema = normalizeSchema(matchedTool.outputSchema);
-
-        if (binderOutputSchema && toolOutputSchema) {
-          try {
-            const outputDiff = await diffSchemas({
-              sourceSchema: binderOutputSchema,
-              destinationSchema: toolOutputSchema,
-            });
-
-            // If something was removed from binder to tool, tool doesn't provide it
-            if (outputDiff.removalsFound) {
-              return false;
-            }
-          } catch (error) {
-            console.error("Schema diff failed", error);
-            // Schema diff failed - consider incompatible
-            return false;
-          }
-        } else if (binderOutputSchema && !toolOutputSchema) {
-          // Binder expects output schema but tool doesn't have one
-          return false;
-        }
-      }
-
-      return true;
-    },
-  };
-}

package/src/index.ts

@@ -1,15 +0,0 @@
-/**
- * @decocms/bindings
- *
- * Core type definitions for the bindings system.
- * Bindings define standardized interfaces that integrations (MCPs) can implement.
- */
-
-// Re-export core binder types and utilities
-export {
-  type ToolBinder,
-  type Binder,
-  type ToolWithSchemas,
-  type BindingChecker,
-  createBindingChecker,
-} from "./core/binder";

package/src/well-known/collections.ts

@@ -1,363 +0,0 @@
-import { z } from "zod";
-import type { ToolBinder } from "../core/binder";
-
-/**
- * Collection Bindings
- *
- * This module provides standardized tool bindings for Collections, representing
- * SQL table-like structures with CRUD + Search operations compatible with TanStack DB.
- *
- * Key Features:
- * - Generic collection bindings that work with any entity type
- * - Standardized tool naming: `COLLECTION_{COLLECTION}_*`
- * - Compatible with TanStack DB query-collection
- * - Full TypeScript support with proper type constraints
- * - Support for filtering, sorting, and pagination
- * - Simple id and title fields for human-readable identification
- */
-
-/**
- * Base schema for collection entities
- * All collection entities must have an id, title, and audit trail fields
- */
-export const BaseCollectionEntitySchema = z.object({
-  id: z.string().describe("Unique identifier for the entity"),
-  title: z.string().describe("Human-readable title for the entity"),
-  created_at: z.string().datetime(),
-  updated_at: z.string().datetime(),
-  created_by: z.string().optional(),
-  updated_by: z.string().optional(),
-});
-
-/**
- * Type helper for BaseCollectionEntitySchema
- */
-export type BaseCollectionEntitySchemaType = typeof BaseCollectionEntitySchema;
-
-/**
- * Comparison expression schema for filtering
- */
-const ComparisonExpressionSchema = z.object({
-  field: z.array(z.string()),
-  operator: z.enum(["eq", "gt", "gte", "lt", "lte", "in", "like", "contains"]),
-  value: z.unknown(),
-});
-
-/**
- * Where expression schema for filtering
- * Supports TanStack DB predicate push-down patterns
- */
-export const WhereExpressionSchema = z.union([
-  ComparisonExpressionSchema,
-  z.object({
-    operator: z.enum(["and", "or", "not"]),
-    conditions: z.array(ComparisonExpressionSchema),
-  }),
-]);
-
-/**
- * Where expression type for filtering
- * Derived from WhereExpressionSchema
- */
-export type WhereExpression = z.infer<typeof WhereExpressionSchema>;
-
-/**
- * Order by expression for sorting
- */
-export const OrderByExpressionSchema = z.object({
-  field: z.array(z.string()),
-  direction: z.enum(["asc", "desc"]),
-  nulls: z.enum(["first", "last"]).optional(),
-});
-
-/**
- * List/Query input schema for collections
- * Compatible with TanStack DB LoadSubsetOptions
- */
-export const CollectionListInputSchema = z.object({
-  where: WhereExpressionSchema.optional().describe("Filter expression"),
-  orderBy: z
-    .array(OrderByExpressionSchema)
-    .optional()
-    .describe("Sort expressions"),
-  limit: z
-    .number()
-    .int()
-    .min(1)
-    .max(1000)
-    .optional()
-    .describe("Maximum number of items to return"),
-  offset: z
-    .number()
-    .int()
-    .min(0)
-    .optional()
-    .describe("Number of items to skip"),
-});
-
-/**
- * Factory function to create list output schema for a specific collection type
- */
-export function createCollectionListOutputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    items: z.array(entitySchema).describe("Array of collection items"),
-    totalCount: z
-      .number()
-      .int()
-      .min(0)
-      .optional()
-      .describe("Total number of matching items (if available)"),
-    hasMore: z
-      .boolean()
-      .optional()
-      .describe("Whether there are more items available"),
-  });
-}
-
-/**
- * Get by ID input schema
- */
-export const CollectionGetInputSchema = z.object({
-  id: z.string().describe("ID of the entity to retrieve"),
-});
-
-/**
- * Factory function to create get output schema
- */
-export function createCollectionGetOutputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    item: entitySchema
-      .nullable()
-      .describe("The retrieved item, or null if not found"),
-  });
-}
-
-/**
- * Factory function to create insert input schema
- */
-export function createCollectionInsertInputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  // Remove id field since it may be auto-generated by the server
-  return z.object({
-    data: entitySchema.describe(
-      "Data for the new entity (id may be auto-generated)",
-    ),
-  });
-}
-
-/**
- * Factory function to create insert output schema
- */
-export function createCollectionInsertOutputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    item: entitySchema.describe("The created entity with generated id"),
-  });
-}
-
-/**
- * Factory function to create update input schema
- */
-export function createCollectionUpdateInputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    id: z.string().describe("ID of the entity to update"),
-    data: (entitySchema as unknown as z.AnyZodObject)
-      .partial()
-      .describe("Partial entity data to update"),
-  });
-}
-
-/**
- * Factory function to create update output schema
- */
-export function createCollectionUpdateOutputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    item: entitySchema.describe("The updated entity"),
-  });
-}
-
-/**
- * Delete input schema
- */
-export const CollectionDeleteInputSchema = z.object({
-  id: z.string().describe("ID of the entity to delete"),
-});
-
-/**
- * Factory function to create delete output schema
- */
-export function createCollectionDeleteOutputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
-  return z.object({
-    item: entitySchema.describe("The deleted entity"),
-  });
-}
-
-/**
- * Options for creating collection bindings
- */
-export interface CollectionBindingOptions {
-  /**
-   * If true, only LIST and GET operations will be included (read-only collection)
-   * @default false
-   */
-  readOnly?: boolean;
-}
-
-/**
- * Creates generic collection bindings for a specific entity type
- *
- * This function generates standardized tool bindings that work with any collection/table
- * by accepting a custom entity schema and collection name. The bindings provide:
- * - COLLECTION_{NAME}_LIST - Query/search entities with filtering and sorting (required)
- * - COLLECTION_{NAME}_GET - Get a single entity by ID (required)
- * - COLLECTION_{NAME}_CREATE - Create a new entity (optional, excluded if readOnly=true)
- * - COLLECTION_{NAME}_UPDATE - Update an existing entity (optional, excluded if readOnly=true)
- * - COLLECTION_{NAME}_DELETE - Delete an entity (optional, excluded if readOnly=true)
- *
- * @param collectionName - The name of the collection/table (e.g., "users", "products", "orders")
- * @param entitySchema - The Zod schema for the entity type (must extend BaseCollectionEntitySchema)
- * @param options - Optional configuration for the collection bindings
- * @returns Array of tool bindings for Collection CRUD + Query operations
- *
- * @example
- * ```typescript
- * const UserSchema = z.object({
- *   id: z.string(),
- *   title: z.string(),
- *   created_at: z.string().datetime(),
- *   updated_at: z.string().datetime(),
- *   created_by: z.string().optional(),
- *   updated_by: z.string().optional(),
- *   email: z.string().email(),
- * });
- *
- * // Full CRUD collection
- * const USER_COLLECTION_BINDING = createCollectionBindings("users", UserSchema);
- *
- * // Read-only collection (only LIST and GET)
- * const READONLY_COLLECTION_BINDING = createCollectionBindings("products", ProductSchema, { readOnly: true });
- * ```
- */
-export function createCollectionBindings<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
->(
-  collectionName: string,
-  entitySchema: TEntitySchema,
-  options?: CollectionBindingOptions,
-) {
-  const upperName = collectionName.toUpperCase();
-  const readOnly = options?.readOnly ?? false;
-
-  const bindings: ToolBinder[] = [
-    {
-      name: `COLLECTION_${upperName}_LIST` as const,
-      inputSchema: CollectionListInputSchema,
-      outputSchema: createCollectionListOutputSchema(entitySchema),
-    },
-    {
-      name: `COLLECTION_${upperName}_GET` as const,
-      inputSchema: CollectionGetInputSchema,
-      outputSchema: createCollectionGetOutputSchema(entitySchema),
-    },
-  ];
-
-  // Only include mutation operations if not read-only
-  if (!readOnly) {
-    bindings.push(
-      {
-        name: `COLLECTION_${upperName}_CREATE` as const,
-        inputSchema: createCollectionInsertInputSchema(entitySchema),
-        outputSchema: createCollectionInsertOutputSchema(entitySchema),
-        opt: true,
-      },
-      {
-        name: `COLLECTION_${upperName}_UPDATE` as const,
-        inputSchema: createCollectionUpdateInputSchema(entitySchema),
-        outputSchema: createCollectionUpdateOutputSchema(entitySchema),
-        opt: true,
-      },
-      {
-        name: `COLLECTION_${upperName}_DELETE` as const,
-        inputSchema: CollectionDeleteInputSchema,
-        outputSchema: createCollectionDeleteOutputSchema(entitySchema),
-        opt: true,
-      },
-    );
-  }
-
-  return bindings satisfies readonly ToolBinder[];
-}
-
-/**
- * Type helper to extract the collection binding type
- */
-export type CollectionBinding<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
-> = ReturnType<typeof createCollectionBindings<TEntitySchema>>;
-
-/**
- * Type helper to extract tool names from a collection binding
- */
-export type CollectionTools<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
-> = CollectionBinding<TEntitySchema>[number]["name"];
-
-// Export types for TypeScript usage
-export type CollectionListInput = z.infer<typeof CollectionListInputSchema>;
-export type CollectionGetInput = z.infer<typeof CollectionGetInputSchema>;
-export type CollectionDeleteInput = z.infer<typeof CollectionDeleteInputSchema>;
-export type OrderByExpression = z.infer<typeof OrderByExpressionSchema>;
-
-/**
- * Type helper for list output with generic item type
- */
-export type CollectionListOutput<T> = {
-  items: T[];
-  totalCount?: number;
-  hasMore?: boolean;
-};
-
-/**
- * Type helper for get output with generic item type
- */
-export type CollectionGetOutput<T> = {
-  item: T | null;
-};
-
-/**
- * Type helper for insert output with generic item type
- */
-export type CollectionInsertOutput<T> = {
-  item: T;
-};
-
-/**
- * Type helper for update output with generic item type
- */
-export type CollectionUpdateOutput<T> = {
-  item: T;
-};
-
-/**
- * Type helper for delete output with generic item type
- */
-export type CollectionDeleteOutput<T> = {
-  item: T;
-};
-
-/**
- * Base collection entity type - inferred from BaseCollectionEntitySchema
- */
-export type BaseCollectionEntity = z.infer<typeof BaseCollectionEntitySchema>;

package/src/well-known/models.ts

@@ -1,87 +0,0 @@
-/**
- * Models Well-Known Binding
- *
- * Defines the interface for AI model providers.
- * Any MCP that implements this binding can provide AI models and streaming endpoints.
- *
- * This binding uses collection bindings for LIST and GET operations (read-only).
- * Streaming endpoint information is included directly in the model entity schema.
- */
-
-import { z } from "zod";
-import type { Binder } from "../core/binder";
-import {
-  BaseCollectionEntitySchema,
-  createCollectionBindings,
-} from "./collections";
-
-/**
- * Model entity schema for AI models
- * Extends BaseCollectionEntitySchema with model-specific fields
- * Base schema already includes: id, title, created_at, updated_at, created_by, updated_by
- */
-export const ModelSchema = BaseCollectionEntitySchema.extend({
-  // Model-specific fields
-  logo: z.string().nullable(),
-  description: z.string().nullable(),
-  capabilities: z.array(z.string()),
-  limits: z
-    .object({
-      contextWindow: z.number(),
-      maxOutputTokens: z.number(),
-    })
-    .nullable(),
-  costs: z
-    .object({
-      input: z.number(),
-      output: z.number(),
-    })
-    .nullable(),
-  // Provider information
-  provider: z
-    .enum([
-      "openai",
-      "anthropic",
-      "google",
-      "xai",
-      "deepseek",
-      "openai-compatible",
-      "openrouter",
-    ])
-    .nullable(),
-  // Streaming endpoint information
-  endpoint: z
-    .object({
-      url: z.string().url(),
-      method: z.string().default("POST"),
-      contentType: z.string().default("application/json"),
-      stream: z.boolean().default(true),
-    })
-    .nullable(),
-});
-
-/**
- * MODELS Collection Binding
- *
- * Collection bindings for models (read-only).
- * Provides LIST and GET operations for AI models.
- */
-export const MODELS_COLLECTION_BINDING = createCollectionBindings(
-  "models",
-  ModelSchema,
-  { readOnly: true },
-);
-
-/**
- * MODELS Binding
- *
- * Defines the interface for AI model providers.
- * Any MCP that implements this binding can provide AI models and streaming endpoints.
- *
- * Required tools:
- * - COLLECTION_MODELS_LIST: List available AI models with their capabilities
- * - COLLECTION_MODELS_GET: Get a single model by ID (includes streaming endpoint info)
- */
-export const MODELS_BINDING = [
-  ...MODELS_COLLECTION_BINDING,
-] as const satisfies Binder;