@decocms/bindings 1.0.1-alpha.3 → 1.0.1

package/src/well-known/collections.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z, type ZodType } from "zod";
 import type { ToolBinder } from "../core/binder";
 
 /**
@@ -23,6 +23,7 @@ import type { ToolBinder } from "../core/binder";
 export const BaseCollectionEntitySchema = z.object({
   id: z.string().describe("Unique identifier for the entity"),
   title: z.string().describe("Human-readable title for the entity"),
+  description: z.string().nullish().describe("Description of the entity"),
   created_at: z.string().datetime(),
   updated_at: z.string().datetime(),
   created_by: z.string().optional(),
@@ -44,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
@@ -139,14 +148,14 @@ export function createCollectionGetOutputSchema<T extends z.ZodTypeAny>(
 /**
  * Factory function to create insert input schema
  */
-export function createCollectionInsertInputSchema<T extends z.ZodTypeAny>(
-  entitySchema: T,
-) {
+export function createCollectionInsertInputSchema<
+  T extends z.ZodObject<z.ZodRawShape>,
+>(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)",
-    ),
+    data: entitySchema
+      .partial()
+      .describe("Data for the new entity (id may be auto-generated)"),
   });
 }
 
@@ -251,7 +260,7 @@ export interface CollectionBindingOptions {
  * ```
  */
 export function createCollectionBindings<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema extends z.ZodObject<z.ZodRawShape>,
   TName extends string,
 >(
   collectionName: TName,
@@ -261,19 +270,18 @@ export function createCollectionBindings<
   const upperName = collectionName.toUpperCase() as Uppercase<TName>;
   const readOnly = options?.readOnly ?? false;
 
-  const bindings: CollectionBinding<TEntitySchema, Uppercase<TName>>[number][] =
-    [
-      {
-        name: `COLLECTION_${upperName}_LIST` as const,
-        inputSchema: CollectionListInputSchema,
-        outputSchema: createCollectionListOutputSchema(entitySchema),
-      },
-      {
-        name: `COLLECTION_${upperName}_GET` as const,
-        inputSchema: CollectionGetInputSchema,
-        outputSchema: createCollectionGetOutputSchema(entitySchema),
-      },
-    ];
+  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) {
@@ -299,71 +307,69 @@ export function createCollectionBindings<
     );
   }
 
-  return bindings satisfies readonly ToolBinder[];
+  return bindings as unknown as CollectionBinding<
+    TEntitySchema,
+    Uppercase<TName>
+  >;
 }
 
-export type ReadOnlyCollectionBinding<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
-  TUpperName extends Uppercase<string> = Uppercase<string>,
-> = [
-  {
-    name: `COLLECTION_${TUpperName}_LIST`;
-    inputSchema: typeof CollectionListInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionListOutputSchema<TEntitySchema>
-    >;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_GET`;
-    inputSchema: typeof CollectionGetInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionGetOutputSchema<TEntitySchema>
-    >;
-  },
-];
+// Helper type for tool definition
+type ToolBinding<
+  Name extends string,
+  Input,
+  Output,
+  Opt extends boolean = false,
+> = {
+  name: Name;
+  inputSchema: ZodType<Input>;
+  outputSchema: ZodType<Output>;
+} & (Opt extends true ? { opt: true } : unknown);
+
 /**
  * Type helper to extract the collection binding type
  */
 export type CollectionBinding<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema,
   TUpperName extends Uppercase<string> = Uppercase<string>,
+  TEntity = TEntitySchema extends z.AnyZodObject
+    ? z.infer<TEntitySchema>
+    : TEntitySchema,
 > = [
-  ...ReadOnlyCollectionBinding<TEntitySchema, TUpperName>,
-  {
-    name: `COLLECTION_${TUpperName}_CREATE`;
-    inputSchema: ReturnType<
-      typeof createCollectionInsertInputSchema<TEntitySchema>
-    >;
-    outputSchema: ReturnType<
-      typeof createCollectionInsertOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_UPDATE`;
-    inputSchema: ReturnType<
-      typeof createCollectionUpdateInputSchema<TEntitySchema>
-    >;
-    outputSchema: ReturnType<
-      typeof createCollectionUpdateOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_DELETE`;
-    inputSchema: typeof CollectionDeleteInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionDeleteOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
+  ToolBinding<
+    `COLLECTION_${TUpperName}_LIST`,
+    CollectionListInput,
+    CollectionListOutput<TEntity>
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_GET`,
+    CollectionGetInput,
+    CollectionGetOutput<TEntity>
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_CREATE`,
+    CollectionInsertInput<TEntity>,
+    CollectionInsertOutput<TEntity>,
+    true
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_UPDATE`,
+    CollectionUpdateInput<TEntity>,
+    CollectionUpdateOutput<TEntity>,
+    true
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_DELETE`,
+    CollectionDeleteInput,
+    CollectionDeleteOutput<TEntity>,
+    true
+  >,
 ];
 
 /**
  * Type helper to extract tool names from a collection binding
  */
 export type CollectionTools<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema extends z.AnyZodObject,
   TUpperName extends Uppercase<string> = Uppercase<string>,
 > = CollectionBinding<TEntitySchema, TUpperName>[number]["name"];
 
@@ -373,6 +379,21 @@ export type CollectionGetInput = z.infer<typeof CollectionGetInputSchema>;
 export type CollectionDeleteInput = z.infer<typeof CollectionDeleteInputSchema>;
 export type OrderByExpression = z.infer<typeof OrderByExpressionSchema>;
 
+/**
+ * Type helper for insert input with generic item type
+ */
+export type CollectionInsertInput<T> = {
+  data: Partial<T>;
+};
+
+/**
+ * Type helper for update input with generic item type
+ */
+export type CollectionUpdateInput<T> = {
+  id: string;
+  data: Partial<T>;
+};
+
 /**
  * Type helper for list output with generic item type
  */