kitcn 0.12.17 → 0.12.19

package/skills/convex/SKILL.md

@@ -54,7 +54,7 @@ Only remember these non-parity deltas:
 19. On the kitcn auth client path, use `createAuthMutations(authClient)` wrappers so logout unsubscribes auth queries before sign out. Raw Convex preset keeps a smaller plain `authClient`.
 20. **NEVER** use `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` directly for module-to-module calls. Use `create<Module>Handler(ctx)` or `create<Module>Caller(ctx)` from `convex/functions/generated/<module>.runtime` instead.
 21. **`create<Module>Handler(ctx)`** — default choice for queries/mutations. Bypasses input validation, middleware, output validation → zero overhead. Query/mutation ctx only. Import from `./generated/<module>.runtime`.
-22. **`create<Module>Caller(ctx)`** — use in actions and HTTP routes (where handler is unavailable). Goes through validation + middleware. Root caller exposes query+mutation procedures. In `ActionCtx`, action procedures are under `caller.actions.*`; scheduling is under `caller.schedule.now|after|at` with `caller.schedule.cancel(id)`. If your code widened `ctx` to a union like `MutationCtx | ActionCtx`, narrow it before accessing `caller.actions.*` (for example with `requireActionCtx(ctx)`). Import from `./generated/<module>.runtime`. Each caller/handler eagerly loads every procedure in its module (no lazy loading) — split large modules to keep bundles lean.
+22. **`create<Module>Caller(ctx)`** — use in actions and HTTP routes (where handler is unavailable). Goes through validation + middleware. Root caller exposes query+mutation procedures. In `ActionCtx`, action procedures are under `caller.actions.*`; scheduling is under `caller.schedule.now|after|at` with `caller.schedule.cancel(id)`. If your code widened `ctx` to a union like `MutationCtx | ActionCtx`, narrow it before accessing `caller.actions.*` (for example with `requireActionCtx(ctx)`). For scheduling from `GenericCtx` or `MutationCtx | ActionCtx`, use `requireSchedulerCtx(ctx)` instead of pretending the path is action-only. Import from `./generated/<module>.runtime`. Each caller/handler eagerly loads every procedure in its module (no lazy loading) — split large modules to keep bundles lean.
 23. API types (`Api`, `ApiInputs`, `ApiOutputs`, `Select`, `Insert`, `TableName`) import from `@convex/api` — no manual `inferApiInputs<typeof api>`.
 24. HTTP router must export as `httpRouter` (not `appRouter`) for codegen.
 25. Server wiring imports come from `convex/functions/generated/` directory: `getAuth`, `defineAuth` from `generated/auth`; `initCRPC`, `QueryCtx`, `MutationCtx`, `OrmCtx` from `generated/server`; `create<Module>Caller`, `create<Module>Handler` from `generated/<module>.runtime`. No manual `convex/lib/orm.ts`.
@@ -226,9 +226,10 @@ Builder rules that matter:
 
 1. Build `public`, `optional`, `auth`, and `private` procedure families once in `convex/lib/crpc.ts`.
 2. `.meta(...)` is client-visible via generated API metadata. Never put secrets there.
-3. Resolve session/user once in middleware. Do not re-fetch auth state in every procedure.
-4. Shared `c.middleware()` chains preserve mutation writer types on mutation procedures. If the middleware itself performs writes, type it as mutation-only with `c.middleware<MutationCtx>(...)`.
-5. Keep deeper auth/runtime edge cases in `references/setup/server.md` and `references/features/auth*.md`.
+3. Middleware receives server-only `procedure` info. When procedures are built from your app `generated/server` helper, standard `export const` queries, mutations, and actions infer `module:function` automatically from file path + export name. Use `.name("module:function")` only to override or cover unusual export shapes.
+4. Resolve session/user once in middleware. Do not re-fetch auth state in every procedure.
+5. Shared `c.middleware()` chains preserve mutation writer types on mutation procedures. If the middleware itself performs writes, type it as mutation-only with `c.middleware<MutationCtx>(...)`.
+6. Keep deeper auth/runtime edge cases in `references/setup/server.md` and `references/features/auth*.md`.
 
 ### 3) Query + Mutation Procedure Template
 
@@ -317,6 +318,9 @@ Use this map consistently:
 5. `CONFLICT`: duplicate or conflicting write.
 6. `TOO_MANY_REQUESTS`: rate limit.
 7. `INTERNAL_SERVER_ERROR`: unexpected failures only.
+8. Add small custom `data` payloads on `CRPCError` when the client needs
+   domain metadata like conflicting ids. Read them on the client from
+   `error.data`.
 
 Required tests:
 

package/skills/convex/references/features/auth-organizations.md

@@ -11,7 +11,7 @@ See [Better Auth Organization Plugin](https://www.better-auth.com/docs/plugins/o
 ```ts
 // convex/functions/auth.ts
 import { organization } from "better-auth/plugins";
-import type { ActionCtx } from "./generated/server";
+import { requireSchedulerCtx } from "kitcn/server";
 import { defineAuth } from "./generated/auth";
 
 export default defineAuth((ctx) => ({
@@ -28,12 +28,13 @@ export default defineAuth((ctx) => ({
       invitationExpiresIn: 48 * 60 * 60, // 48 hours
       teams: { enabled: true, maximumTeams: 10 },
       sendInvitationEmail: async (data) => {
+        const schedulerCtx = requireSchedulerCtx(ctx);
         const inviterName = data.inviter.user.name || "Team Admin";
         const organizationName = data.organization.name;
         const roleSuffix = data.role ? ` as ${data.role}` : "";
         const acceptUrl = `${process.env.SITE_URL!}/w/${data.organization.slug}?invite=${data.id}`;
 
-        await (ctx as ActionCtx).scheduler.runAfter(
+        await schedulerCtx.scheduler.runAfter(
           0,
           internal.plugins.email.sendTemplatedEmail,
           {
@@ -51,6 +52,10 @@ export default defineAuth((ctx) => ({
 }));
 ```
 
+`sendInvitationEmail` can run from mutation-driven auth flows. Use
+`requireSchedulerCtx(ctx)` when you need scheduling. Do not narrow to
+`ActionCtx` unless the callback truly runs only inside an action.
+
 ## Client Config
 
 ```ts

package/skills/convex/references/features/react.md

@@ -418,11 +418,21 @@ Each page maintains its own WebSocket subscription. Auto-recovers on `InvalidCur
 
 ### Server Errors
 
-`CRPCError` thrown server-side → arrives as `ConvexError` on client. Access via `error.data`:
+`CRPCError` thrown server-side → arrives as `ConvexError` on client. Access
+the built-in fields and any custom payload via `error.data`:
 
 ```ts
-// Server: throw new CRPCError({ code: 'NOT_FOUND', message: 'Post not found' });
+// Server:
+throw new CRPCError({
+  code: 'CONFLICT',
+  message: 'Domain already exists',
+  data: { existingSiteId: 'site_123' },
+});
+
 // Client:
+error.data?.message; // 'Domain already exists'
+error.data?.existingSiteId; // 'site_123'
+
 const { error, isError } = useQuery(crpc.posts.get.queryOptions({ id }));
 if (isError) toast.error(error.data?.message ?? 'Something went wrong');
 
@@ -430,7 +440,12 @@ if (isError) toast.error(error.data?.message ?? 'Something went wrong');
 crpc.posts.create.mutationOptions({ onError: (error) => toast.error(error.data?.message ?? 'Failed') });
 
 // Try/catch:
-const error = err as Error & { data?: { message?: string } };
+const error = err as Error & {
+  data?: {
+    message?: string;
+    existingSiteId?: string;
+  };
+};
 ```
 
 ### Client Errors