Core API

  Backend (gencow/ folder)              Frontend (src/ folder)
  ─────────────────────────         ─────────────────────────
  Runs on the server                Runs in the browser
  ┌──────────────────────┐         ┌──────────────────────┐
  │ gencow/schema.ts     │         │                      │
  │   → pgTable + ownerRls│         │ useQuery(api.tasks.  │
  │                       │         │   list)               │
  │ gencow/tasks.ts      │  WebSocket │   → { data, total } │
  │   → createCrud(tasks)│ ←──────→│                      │
  │   → procedure.query  │  Auto-   │ useMutation(api.tasks│
  │   → procedure.mutation│ Sync    │   .create)           │
  └──────────────────────┘         └──────────────────────┘

import { pgTable, serial, text, integer } from "drizzle-orm/pg-core";
import { ownerRls } from "@gencow/core";

// Apply RLS to the table — pass the userId column reference
export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),
    title: text("title").notNull(),
    userId: text("user_id").notNull(),
}, (t) => ownerRls(t.userId));

// Public read — anyone can read, only owner can CUD
export const posts = pgTable("posts", {
    id: serial("id").primaryKey(),
    content: text("content").notNull(),
    userId: text("user_id").notNull(),
}, (t) => ownerRls(t.userId, { read: "public" }));

import { createCrud } from "./runtime";
import { tasks } from "./schema";

// Automatically registers: tasks.list, tasks.get, tasks.create, tasks.update, tasks.remove
export const { get, list, create, update, remove } = createCrud(tasks);

// ✅ Works — has id column
export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),      // serial (number) PK
    title: text("title").notNull(),
});

// ✅ Also works — UUID string id
export const users = pgTable("users", {
    id: text("id").primaryKey(),         // text/UUID PK — auto-detected
    name: text("name"),
});

// ❌ Error — no id column
export const settings = pgTable("settings", {
    key: text("key").primaryKey(),       // createCrud() requires "id", not "key"
    value: text("value"),
});
// → [createCrud] Table "settings" must have an 'id' column.
// → Use manual procedure.query / procedure.mutation instead

// Backend: list returns { data: T[], total: number }
// Frontend:
const result = useQuery(api.tasks.list);

// ✅ Access data array
result?.data.map(task => <li>{task.title}</li>)

// ✅ Access total count (for pagination)
result?.total  // e.g. 42

// ❌ Common mistake — result is NOT an array
result?.map(...)  // TypeError! Use result.data.map() instead

const [page, setPage] = useState(1);
const limit = 20;
const result = useQuery(api.tasks.list, { page, limit });

const totalPages = Math.ceil((result?.total ?? 0) / limit);

return (
    <div>
        {result?.data.map(task => <TaskCard key={task.id} task={task} />)}
        <div>Page {page} of {totalPages} ({result?.total ?? 0} items)</div>
        <button onClick={() => setPage(p => p - 1)} disabled={page <= 1}>Prev</button>
        <button onClick={() => setPage(p => p + 1)} disabled={page >= totalPages}>Next</button>
    </div>
);

export const { list, get, create, update, remove } = createCrud(tasks, {
    // Auth
    allowAnonymous: true,      // Skip auth (default: false — Secure by Default)

    // Realtime
    realtime: false,           // Disable realtime push (default: true)

    // Naming
    prefix: "myTasks",         // Override key prefix (default: table name)

    // Search — enables list({ search: "keyword" })
    searchFields: ["title", "description"],

    // Filtering — enables list({ filters: { status: "active" } })
    allowedFilters: ["status", "category"],

    // Pagination
    defaultLimit: 20,          // Default page size (default: 20)
    maxLimit: 100,             // Max page size (default: 100)

    // Soft delete — marks as deleted instead of removing
    softDelete: { field: "deletedAt" },

    // Lifecycle hooks
    hooks: {
        beforeCreate: (data) => ({ ...data, slug: slugify(data.title) }),
        beforeUpdate: (data) => ({ ...data, updatedAt: new Date() }),
    },
});

// Backend: enable filtering by status and category
export const { list } = createCrud(tasks, {
    allowedFilters: ["status", "category"],
});

// Frontend: pass filters
const activeTasks = useQuery(api.tasks.list, {
    filters: { status: "active" },
});

const techPosts = useQuery(api.tasks.list, {
    filters: { status: "published", category: "tech" },
});

// ⚠️ Security: filters NOT in allowedFilters are silently ignored
// filters: { userId: "hacker" }  → ignored (userId not in allowedFilters)
// ⚠️ Secure by Default: if allowedFilters is NOT set, ALL filters are ignored

// Simple equality (implicit eq — backward compatible)
useQuery(api.tasks.list, { filters: { status: "active" } });

// Explicit operator syntax
useQuery(api.tasks.list, { filters: { status: { op: "eq", value: "active" } } });
useQuery(api.tasks.list, { filters: { status: { op: "ne", value: "draft" } } });
useQuery(api.tasks.list, { filters: { priority: { op: "gte", value: 3 } } });
useQuery(api.tasks.list, { filters: { category: { op: "in", value: ["tech", "news"] } } });
useQuery(api.tasks.list, { filters: { title: { op: "ilike", value: "%meeting%" } } });

// OR — match any condition
useQuery(api.tasks.list, {
    filters: {
        OR: [
            { status: "active" },
            { status: "review" },
        ],
    },
});

// AND — match all conditions (explicit; multiple top-level keys are implicitly AND)
useQuery(api.tasks.list, {
    filters: {
        AND: [
            { status: "active" },
            { priority: { op: "gte", value: 3 } },
        ],
    },
});

// Nested — OR within AND (max 5 levels deep)
useQuery(api.tasks.list, {
    filters: {
        AND: [
            { OR: [{ category: "tech" }, { category: "news" }] },
            { status: { op: "ne", value: "archived" } },
        ],
    },
});

// gencow/runtime.ts
import {
  createCrudFactory,
  createGencowHttpRouteBuilders,
  createGencowProcedureBuilders,
} from "@gencow/core";
import type { GencowSchema } from "./generated/db-schema.gen";

export const procedure = createGencowProcedureBuilders<GencowSchema>();
export const httpRoute = createGencowHttpRouteBuilders<GencowSchema>();
export const createCrud = createCrudFactory(procedure);

// gencow/tasks.ts
import { procedure } from "./runtime";
import { v } from "@gencow/core";

export const listMine = procedure.query
    .name("tasks.listMine")
    .handler(async ({ context }) => {
        const user = context.auth.requireAuth();
        return context.db.select().from(tasks).where(eq(tasks.userId, user.id));
    });

export const createOne = procedure.mutation
    .name("tasks.createOne")
    .input(v.object({ title: v.string() }))
    .handler(async ({ context, input }) => {
        const user = context.auth.requireAuth();
        return context.db.insert(tasks).values({ title: input.title, userId: user.id });
    });

import { workflow, deriveWorkflowStatus, v } from "@gencow/core";

export const runImport = workflow("imports.run", {
    args: {
        sourceId: v.string(),
        requireApproval: v.optional(v.boolean()),
    },
    handler: async (wf, args) => {
        const prepared = await wf.step("prepare", async () => {
            return { sourceId: args.sourceId, startedAt: new Date().toISOString() };
        });

        if (args.requireApproval) {
            await wf.waitForEvent("approval", "24h");
        }

        return wf.step("finalize", async () => ({
            ok: true,
            prepared,
        }));
    },
});

const label = deriveWorkflowStatus("pending", "wait:approval");
// "waiting"

// gencow/runtime.ts
import type { GencowSchema } from "./generated/db-schema.gen";
import { createGencowHttpRouteBuilders } from "@gencow/core";

export const httpRoute = createGencowHttpRouteBuilders<GencowSchema>();

// gencow/http-routes.ts (or index.ts)
import { defineApi } from "@gencow/core";
import { httpRoute } from "./runtime";
import { z } from "zod";

// GET /api/health — public, no schema
const health = httpRoute.get
    .path("/api/health")
    .allowAnonymous()
    .handler(async () => ({ body: { status: "ok" } }));

// POST /api/echo — typed input + output
const echo = httpRoute.post
    .path("/api/echo")
    .allowAnonymous()
    .input(z.object({ message: z.string() }))
    .output(z.object({ echoed: z.string(), length: z.number() }))
    .handler(async ({ input }) => ({
        body: { echoed: input.message, length: input.message.length },
    }));

// GET /api/tasks/:id — path params, authenticated by default
const taskById = httpRoute.get
    .path("/api/tasks/:id")
    .handler(async ({ context, request }) => {
        context.auth.requireAuth();
        const id = Number(request.params.id);
        if (!Number.isFinite(id)) return { status: 400, body: { error: "id must be a number" } };
        const [row] = await context.db.select().from(tasks).where(eq(tasks.id, id));
        return row ? { body: row } : { status: 404, body: { error: "not found" } };
    });

export default defineApi({
    httpRoutes: { health, echo, taskById },
});

async ({ context, input, request }) => HttpRouteResult<TOutput>

const traced = httpRoute.post
    .path("/api/traced")
    .allowAnonymous()
    .use(async ({ request, next }) => {
        const start = Date.now();
        const traceId = request.headers["x-trace-id"] ?? crypto.randomUUID();
        const result = await next();
        return {
            ...result,
            headers: {
                ...(result.headers ?? {}),
                "x-trace-id": traceId,
                "x-duration-ms": String(Date.now() - start),
            },
        };
    })
    .input(z.object({ name: z.string() }))
    .handler(async ({ input }) => ({ body: { greeting: `hello ${input.name}` } }));

chain:    use(mwA) → use(mwB) → input(schema) → use(mwC) → handler
                                       │
                                       └─ runs HERE during execution

happy path execution flow:

  mwA.before  →  mwB.before  →  [validate input]  →  mwC.before  →  handler
                                                                       ↓
  mwA.after   ←  mwB.after   ←  ─────────────────  ←  mwC.after   ←  ─┘

failure path (input schema rejects):

  mwA.before  →  mwB.before  →  [validate input] ✗
                                       │
                                       ↓
                              400 returned to client
                              (mwC, handler, mwA.after, mwB.after are SKIPPED)

export default defineApi({
    procedures: {
        listMine,
        createOne,
        tasksList: tasksCrud.list,
        tasksGet: tasksCrud.get,
        tasksCreate: tasksCrud.create,
        tasksUpdate: tasksCrud.update,
        tasksRemove: tasksCrud.remove,
    },
    httpRoutes: { health, echo, taskById },
});

handler: async (ctx, args) => {
    // Database (RLS injected automatically)
    ctx.db                    // Drizzle ORM instance (filtered)
    ctx.unsafeDb              // Drizzle ORM instance (unfiltered, admin only)

    // Auth
    ctx.auth.requireAuth()    // Returns session (throws if not authed)
    ctx.auth.getSession()     // Returns session or null

    // Storage
    ctx.storage.store(file)   // Store file → storageId
    ctx.storage.getUrl(id)    // Get serving URL
    ctx.storage.delete(id)    // Delete file

    // Retrieval / RAG
    ctx.search("rag_chunks", query, options)       // Keyword search
    ctx.vectorSearch("rag_chunks", options)        // Vector search
    ctx.hybridSearch("rag_chunks", query, options) // Keyword + vector fusion
    ctx.grounding?.answer(input)                   // Grounded claims + citations

    // Workflow-only document conversion
    wf.services.document.convert(input)            // Only inside workflow()

    // Scheduler
    ctx.scheduler.runAfter(delayMs, "mutation.name", args)
    ctx.scheduler.runAt(timestamp, "mutation.name", args)

    // AI (generated gencow/ai.ts)
    // After: gencow add AI
    import { ai } from "./ai";
    ai.chat({ system, messages })     // → { text, usage, creditsCharged, model }
    ai.stream({ system, messages })   // → AsyncIterable<string>
    ai.embed(text)                    // → number[]

    // Realtime (custom procedures only — createCrud() handles this automatically)
    ctx.realtime.invalidate("queryKey")     // Signal subscribers to refetch with their auth/args
    ctx.realtime.refresh("queryKey")        // Re-run server-safe query + push result
    ctx.realtime.emit("queryKey", data)     // Push data directly to public/opaque subscribers

    // File Upload (in mutation with FormData)
    // File is accessed via args, NOT ctx:
    const file = args?.["file"] as File;    // from FormData upload
    await ctx.storage.store(file);          // store to disk
}

import { eq, and, desc } from "drizzle-orm";
import { tasks } from "./schema";

// SELECT — Postgres RLS automatically filters
const rows = await ctx.db.select().from(tasks); // only current user's tasks

// SELECT with additional WHERE — combined with RLS
const done = await ctx.db.select().from(tasks).where(eq(tasks.done, true));

// INSERT — passes through (no filter needed for new rows)
const [row] = await ctx.db.insert(tasks).values({ title: "..." }).returning();

// UPDATE — filter auto-applied (can only update own rows)
await ctx.db.update(tasks).set({ done: true }).where(eq(tasks.id, 1));

// DELETE — filter auto-applied
await ctx.db.delete(tasks).where(eq(tasks.id, 1));

// ❌ Blocked — raw SQL not allowed on scoped db
ctx.db.execute(sql`SELECT * FROM tasks`); // throws Error

// ⚠️ Only for intentional filter bypass — flagged in security audits
const allTasks = await ctx.unsafeDb.select().from(tasks);
ctx.unsafeDb.execute(sql`TRUNCATE tasks`); // raw SQL allowed

// Require authentication (throws 401 if not logged in)
const session = ctx.auth.requireAuth();
// session.user.id    — User ID
// session.user.email — User email
// session.user.name  — User name

// Optional authentication
const session = ctx.auth.getSession();
// null if not authenticated

// Store a file
const storageId = await ctx.storage.store(file, "optional-filename");

// Store from buffer
const storageId = await ctx.storage.storeBuffer(buffer, "name.pdf", "application/pdf");

// Get public URL
const url = ctx.storage.getUrl(storageId);
// → "/api/storage/<uuid>"

// Get metadata
const meta = await ctx.storage.getMeta(storageId);
// → { id, name, size, type, path }

// Delete (also removes all cached image transforms)
await ctx.storage.delete(storageId);

// Basic URL — Auto WebP applied if browser supports it
const url = ctx.storage.getUrl(storageId);
// → "/api/storage/<uuid>"
// Browser with WebP support → served as WebP (smaller)
// Browser without WebP     → served as original

// Transform parameters (Pro/Scale plans only)
// Append query params to the URL:
const thumb = `${url}?w=200`;              // 200px wide thumbnail
const hero  = `${url}?w=1200&q=85&f=webp`; // hero image optimized

const keyword = await ctx.search("rag_chunks", "refund policy", {
    fields: ["chunk_text", "lexical_text"],
    scope: { corpus: "manuals", visibility: "shared" },
    limit: 10,
});

const semantic = await ctx.vectorSearch("rag_chunks", {
    vector: embedding,
    vectorField: "embedding",
    scope: { corpus: "manuals", visibility: "shared" },
    limit: 10,
});

const hybrid = await ctx.hybridSearch("rag_chunks", "refund policy", {
    fields: ["chunk_text", "lexical_text"],
    vector: embedding,
    vectorField: "embedding",
    scope: { corpus: "manuals", visibility: "shared" },
    tuning: {
        keywordCandidateLimit: 40,
        vectorCandidateLimit: 40,
        fusion: { mode: "rrf" },
    },
});

const result = await ctx.grounding?.answer({
    question: "What is the refund window?",
    scope: { corpus: "manuals", visibility: "shared" },
    claims: [
        {
            claimText: "Refunds are allowed within seven days.",
            requiredTerms: ["refunds", "seven days"],
        },
    ],
    mode: "qa",
});

if (!result?.grounded) {
    // Show an insufficient-evidence state instead of a fully grounded answer.
}

import { workflow, v } from "@gencow/core";

export const convertManual = workflow("manuals.convert", {
    args: {
        storageId: v.string(),
        filename: v.string(),
    },
    handler: async (wf, { storageId, filename }) => {
        return wf.services.document.convert({
            storageId,
            filename,
            mimeType: "application/pdf",
            corpus: "manuals",
            visibility: "shared",
            mode: "force-ocr",
            provider: "auto",
        });
    },
});

PDF auto:
  kordoc
  -> OpenDataLoader
  -> stop with DOCUMENT_PAID_FALLBACK_REQUIRED

HWP/HWPX/HWPML/DOCX/XLSX auto:
  kordoc
  -> OpenDataLoader
  -> stop with DOCUMENT_PAID_FALLBACK_REQUIRED

TXT/Markdown/HTML/CSV auto:
  local_text

await wf.services.document.convert({
    storageId,
    filename: "report.pdf",
    mimeType: "application/pdf",
    corpus: "manuals",
    visibility: "shared",
    provider: "auto",
    paidFallback: true,
    maxServiceCredits: 500,
});

await wf.services.document.convert({
    storageId,
    filename: "scan.pdf",
    mimeType: "application/pdf",
    corpus: "manuals",
    visibility: "shared",
    mode: "force-external",
    provider: "openai",
    maxServiceCredits: 500,
});

// Run after delay (milliseconds)
await ctx.scheduler.runAfter(0, "emails.send", { to: "[email protected]" });
await ctx.scheduler.runAfter(60_000, "tasks.cleanup", {}); // 1 minute later

// Run at specific time
await ctx.scheduler.runAt(new Date("2026-03-27T09:00:00"), "reports.generate", {});

// invalidate() — clients refetch with their own auth and query args
// Best for private/RLS lists and general CRUD-style updates
ctx.realtime.invalidate("tasks.list");

// refresh() — re-runs the query handler on the server, pushes result
// Best for public/server-safe aggregate queries
ctx.realtime.refresh("dashboard.stats");

// emit() — pushes specific data directly (skip re-query)
// Best for public or opaque-token exact channels where you already have fresh data
ctx.realtime.emit("chat.getMessages", freshMessages);

import { v } from "@gencow/core";

{
    args: {
        title: v.string(),
        count: v.number(),
        active: v.boolean(),
        tags: v.array(v.string()),
        config: v.optional(v.object({
            theme: v.string(),
            limit: v.number(),
        })),
    },
}

import { cronJobs } from "@gencow/core";

const crons = cronJobs();

crons.interval("name", { minutes: 30 }, "module.mutation");
crons.daily("name", { hour: 9 }, "module.mutation");
crons.weekly("name", { dayOfWeek: 1, hour: 10 }, "module.mutation");
crons.cron("name", "*/15 * * * *", "module.mutation");
// Or inline handler:
crons.interval("name", { minutes: 5 }, async (ctx) => { ... });

export default crons;  // Required!

import { defineAuth } from "@gencow/core";

export default defineAuth({
    emailAndPassword: { enabled: true },
    // emailVerification: { ... },
});

import { withRetry } from "@gencow/core";

const result = await withRetry(
    () => fetch("https://api.example.com/data"),
    { maxAttempts: 3, initialBackoffMs: 1000 }
);

// ❌ WRONG — no unique constraint, onConflictDoNothing is meaningless
export const articles = pgTable("articles", {
    id: serial("id").primaryKey(),
    url: text("url").notNull(),
});

await ctx.db.insert(articles)
    .values({ url: "https://..." })
    .onConflictDoNothing();          // ← silently does nothing useful!

// ✅ CORRECT — add unique() constraint on url
export const articles = pgTable("articles", {
    id: serial("id").primaryKey(),
    url: text("url").notNull().unique(),  // ← unique constraint required
});

await ctx.db.insert(articles)
    .values({ url: "https://..." })
    .onConflictDoNothing({ target: articles.url });  // ← now works correctly

// Frontend — latest 1 record
const latest = useQuery(api.logs.list, { limit: 1, orderBy: "createdAt", orderDir: "desc" });
const latestLog = latest?.data[0];  // first (and only) item

// Frontend — latest with filter
const latestActive = useQuery(api.tasks.list, {
    limit: 1,
    filters: { status: "active" },
});