@decocms/bindings 0.2.0 → 0.2.2

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;