@gallopsystems/agent-skills 1.0.0

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/deep-linking.md

@@ -0,0 +1,190 @@
+# Deep Linking (URL Params Sync)
+
+> **Example:** [deep-link-page.vue](./examples/deep-link-page.vue)
+
+Make filters bookmarkable/shareable by syncing them with URL query params.
+
+## Pattern 1: `useRouteQuery` (Recommended)
+
+From `@vueuse/router` (install: `npm install @vueuse/router`):
+
+> **Important:** Pass Nuxt's route/router composables explicitly.
+
+```typescript
+import { useRouteQuery } from "@vueuse/router";
+
+// Get Nuxt composables
+const route = useRoute();
+const router = useRouter();
+
+// Each filter synced with URL
+const search = useRouteQuery("search", "", { route, router });
+const status = useRouteQuery("status", "all", { route, router });
+const page = useRouteQuery("page", "1", {
+  route, router,
+  transform: Number,  // Parse as number
+});
+
+// Debounce search to avoid URL thrashing
+const debouncedSearch = refDebounced(search, 300);
+
+// Build query for useFetch - exclude empty/default values
+const queryParams = computed(() => ({
+  ...(debouncedSearch.value ? { search: debouncedSearch.value } : {}),
+  ...(status.value !== "all" ? { status: status.value } : {}),
+  offset: (page.value - 1) * 20,
+  limit: 20,
+}));
+
+// Auto-refetches when params change
+const { data, status: fetchStatus } = await useFetch("/api/items", {
+  query: queryParams,
+});
+
+// Reset pagination when filters change
+watch([debouncedSearch, status], () => {
+  page.value = 1;
+});
+```
+
+**Result:** URL like `/items?search=hello&status=active&page=2` loads with filters pre-applied.
+
+## Pattern 2: Manual with useRoute/useRouter
+
+For more control:
+
+```typescript
+const route = useRoute();
+const router = useRouter();
+
+// Initialize from URL (works during SSR)
+const search = ref((route.query.search as string) || "");
+const category = ref((route.query.category as string) || "");
+
+// Debounced URL update
+const updateUrl = useDebounceFn(() => {
+  router.push({
+    query: {
+      ...route.query,  // Preserve other params
+      ...(search.value ? { search: search.value } : {}),
+      ...(category.value ? { category: category.value } : {}),
+    },
+  });
+}, 300);
+
+watch([search, category], updateUrl);
+
+// useFetch with same refs
+const { data } = await useFetch("/api/items", {
+  query: computed(() => ({
+    ...(search.value ? { search: search.value } : {}),
+    ...(category.value ? { category: category.value } : {}),
+  })),
+});
+```
+
+## Pattern 3: `useUrlSearchParams` (Low-Level)
+
+Direct URL manipulation via VueUse:
+
+```typescript
+const urlParams = useUrlSearchParams("history");
+
+// Read
+const search = urlParams["search"] as string || "";
+
+// Write
+urlParams["search"] = "new value";
+
+// Delete (must use delete, not null)
+delete urlParams["search"];
+```
+
+**Best for:** Complex serialization, arrays, nested objects.
+
+## Array Values in URL
+
+For multi-select filters:
+
+```typescript
+// Serialize array to comma-separated
+const selectedStatuses = useRouteQuery("status", "", {
+  route, router,
+  transform: (val) => val ? val.split(",") : [],
+});
+
+// Manual approach
+const statuses = ref<string[]>([]);
+watch(statuses, (val) => {
+  urlParams["status"] = val.length ? val.join(",") : undefined;
+});
+```
+
+## Complete Example
+
+```typescript
+import { useRouteQuery } from "@vueuse/router";
+
+const route = useRoute();
+const router = useRouter();
+
+// All filters bound to URL
+const search = useRouteQuery("q", "", { route, router });
+const status = useRouteQuery("status", "all", { route, router });
+const sortBy = useRouteQuery("sort", "created_at", { route, router });
+const sortOrder = useRouteQuery("order", "desc", { route, router });
+const page = useRouteQuery("page", "1", { route, router, transform: Number });
+const perPage = useRouteQuery("limit", "20", { route, router, transform: Number });
+
+// Debounce search
+const debouncedSearch = refDebounced(search, 300);
+
+// Query params for API
+const queryParams = computed(() => ({
+  ...(debouncedSearch.value ? { search: debouncedSearch.value } : {}),
+  ...(status.value !== "all" ? { status: status.value } : {}),
+  sort_by: sortBy.value,
+  sort_order: sortOrder.value,
+  offset: (page.value - 1) * perPage.value,
+  limit: perPage.value,
+}));
+
+// Fetch with reactive params
+const { data, refresh } = await useFetch("/api/items", {
+  query: queryParams,
+});
+
+// Reset pagination on filter change
+watch([debouncedSearch, status, sortBy, sortOrder], () => {
+  page.value = 1;
+});
+
+// Pagination helpers
+const totalPages = computed(() =>
+  Math.ceil((data.value?.total || 0) / perPage.value)
+);
+```
+
+## SSR Considerations
+
+1. **`useRouteQuery` is SSR-safe** - reads from route during SSR
+2. **`useRoute()` works during SSR** - can initialize from URL
+3. **`useUrlSearchParams` is client-only** - guard with `import.meta.client`
+4. **`router.push()` works during SSR** - but avoid at top-level setup
+
+## Which Pattern?
+
+| Pattern | Best For | SSR-Safe |
+|---------|----------|----------|
+| `useRouteQuery` | Most cases - bidirectional sync | Yes |
+| `useRoute` + `router.push` | Custom serialization | Yes |
+| `useUrlSearchParams` | Direct param manipulation | No |
+
+## Key Gotchas
+
+1. **Debounce search inputs** - otherwise URL updates every keystroke
+2. **Reset pagination on filter change** - avoid empty page 5
+3. **Exclude default values** - cleaner URLs
+4. **Use `transform` for numbers** - URL params are strings
+5. **Arrays need serialization** - comma-separated or custom
+6. **Pass Nuxt composables** - VueUse router utils need route/router

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/auth-middleware.ts

@@ -0,0 +1,32 @@
+// server/middleware/auth.ts
+// Server middleware for protecting API routes
+
+export default defineEventHandler(async (event) => {
+  // Skip auth for public routes
+  const publicPaths = ["/api/auth", "/api/_auth", "/api/public"];
+  if (publicPaths.some((path) => event.path.startsWith(path))) {
+    return;
+  }
+
+  // Require auth for all /api/* routes
+  if (event.path.startsWith("/api")) {
+    const session = await getUserSession(event);
+
+    if (!session?.user) {
+      throw createError({
+        statusCode: 401,
+        statusMessage: "Unauthorized",
+      });
+    }
+
+    // Role-based restrictions
+    if (event.path.startsWith("/api/admin")) {
+      if (session.user.role !== "admin") {
+        throw createError({
+          statusCode: 403,
+          statusMessage: "Forbidden - Admin access required",
+        });
+      }
+    }
+  }
+});

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/auth-utils.ts

@@ -0,0 +1,51 @@
+// server/utils/auth.ts
+// Reusable auth helpers (auto-imported in /server)
+import type { H3Event } from "h3";
+
+// Type for user in session
+export interface SessionUser {
+  id: number;
+  email: string;
+  name: string;
+  role: "admin" | "user";
+}
+
+/**
+ * Get authenticated user or throw 401
+ */
+export async function getAuthenticatedUser(event: H3Event): Promise<SessionUser> {
+  const session = await getUserSession(event);
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  return session.user as SessionUser;
+}
+
+/**
+ * Require specific role(s) or throw 403
+ */
+export async function requireRole(
+  event: H3Event,
+  allowedRoles: SessionUser["role"][]
+): Promise<SessionUser> {
+  const user = await getAuthenticatedUser(event);
+  if (!allowedRoles.includes(user.role)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: `Forbidden - Requires one of: ${allowedRoles.join(", ")}`,
+    });
+  }
+  return user;
+}
+
+/**
+ * Shorthand for requiring admin role
+ */
+export async function requireAdmin(event: H3Event): Promise<SessionUser> {
+  return requireRole(event, ["admin"]);
+}
+
+// Usage in API handlers:
+// const user = await getAuthenticatedUser(event);
+// const admin = await requireAdmin(event);
+// const manager = await requireRole(event, ["admin", "manager"]);

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/deep-link-page.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+// Deep Linking: URL params → Filter state → useFetch query
+// URL: /items?search=hello&status=active&page=2
+
+import { useRouteQuery } from "@vueuse/router";
+
+// Get Nuxt composables (required for @vueuse/router)
+const route = useRoute();
+const router = useRouter();
+
+// Each param synced with URL - pass route/router explicitly
+const search = useRouteQuery("search", "", { route, router });
+const status = useRouteQuery("status", "all", { route, router });
+const page = useRouteQuery("page", "1", {
+  route,
+  router,
+  transform: Number,
+});
+
+// Debounce search to avoid thrashing
+const debouncedSearch = refDebounced(search, 300);
+
+// Build query - exclude empty/default values for clean URLs
+const queryParams = computed(() => ({
+  ...(debouncedSearch.value ? { search: debouncedSearch.value } : {}),
+  ...(status.value !== "all" ? { status: status.value } : {}),
+  offset: (page.value - 1) * 20,
+  limit: 20,
+}));
+
+// useFetch with reactive query - auto-refetches on change
+const { data, status: fetchStatus } = await useFetch("/api/items", {
+  query: queryParams,
+});
+
+// Reset pagination when filters change
+watch([debouncedSearch, status], () => {
+  page.value = 1;
+});
+</script>
+
+<template>
+  <div>
+    <h1>Items</h1>
+
+    <div class="filters">
+      <input v-model="search" placeholder="Search..." />
+      <select v-model="status">
+        <option value="all">All</option>
+        <option value="active">Active</option>
+        <option value="inactive">Inactive</option>
+      </select>
+      <input v-model.number="page" type="number" min="1" />
+    </div>
+
+    <div v-if="fetchStatus === 'pending'">Loading...</div>
+    <div v-else-if="data">
+      <pre>{{ data }}</pre>
+    </div>
+  </div>
+</template>

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/service-util.ts

@@ -0,0 +1,63 @@
+// server/utils/stripe.ts
+// Server-side service integration pattern using Stripe
+
+import Stripe from "stripe";
+
+// Initialize at module level with runtime config
+const config = useRuntimeConfig();
+const stripe = new Stripe(config.stripe.secretKey);
+
+// Define typed methods
+interface CreatePaymentIntentOptions {
+  amount: number;
+  currency: string;
+  metadata?: Record<string, string>;
+}
+
+async function createPaymentIntent(options: CreatePaymentIntentOptions) {
+  try {
+    return await stripe.paymentIntents.create({
+      amount: options.amount,
+      currency: options.currency,
+      metadata: options.metadata,
+    });
+  } catch (error: any) {
+    // Transform SDK errors to HTTP errors
+    throw createError({
+      statusCode: error.statusCode || 500,
+      message: `Stripe error: ${error.message}`,
+    });
+  }
+}
+
+async function getCustomer(customerId: string) {
+  try {
+    return await stripe.customers.retrieve(customerId);
+  } catch (error: any) {
+    if (error.code === "resource_missing") {
+      return null;
+    }
+    throw createError({
+      statusCode: error.statusCode || 500,
+      message: `Stripe error: ${error.message}`,
+    });
+  }
+}
+
+async function createCustomer(email: string, name: string) {
+  return await stripe.customers.create({ email, name });
+}
+
+// Export as use*() function
+export function useStripe() {
+  return {
+    createPaymentIntent,
+    getCustomer,
+    createCustomer,
+    client: stripe, // Expose for advanced usage
+  };
+}
+
+// Usage in API handler:
+// const { createPaymentIntent } = useStripe();
+// const intent = await createPaymentIntent({ amount: 1000, currency: "usd" });

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/sse-endpoint.ts

@@ -0,0 +1,59 @@
+// server/api/stream/[id].get.ts
+// Server-Sent Events endpoint for real-time streaming
+
+export default defineEventHandler(async (event) => {
+  const { id } = getRouterParams(event);
+
+  // Create the event stream
+  const eventStream = createEventStream(event);
+
+  let done = false;
+
+  // Handle client disconnect
+  eventStream.onClosed(async () => {
+    console.log(`Stream ${id}: Client disconnected`);
+    done = true;
+    await eventStream.close();
+  });
+
+  // Heartbeat to keep connection alive
+  const heartbeat = setInterval(async () => {
+    if (!done) {
+      await eventStream.push(JSON.stringify({ type: "heartbeat" }));
+    }
+  }, 30000);
+
+  // Stream data
+  (async () => {
+    try {
+      while (!done) {
+        // Get next chunk of data (your logic here)
+        const data = await getNextChunk(id);
+
+        if (data) {
+          await eventStream.push(JSON.stringify(data));
+
+          if (data.type === "done" || data.type === "error") {
+            done = true;
+          }
+        } else {
+          // No data yet, wait before checking again
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+      }
+    } finally {
+      clearInterval(heartbeat);
+      await eventStream.close();
+    }
+  })();
+
+  return eventStream.send();
+});
+
+// Helper - replace with your data source
+async function getNextChunk(id: string) {
+  // Example: fetch from Redis, database, or queue
+  // return { type: "chunk", text: "Hello" }
+  // return { type: "done" }
+  return null;
+}

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts

@@ -0,0 +1,38 @@
+// server/api/validation/users.get.ts
+// API endpoint with Zod query validation
+import { z } from "zod";
+
+const querySchema = z.object({
+  search: z.string().min(1).optional(),
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  status: z.enum(["active", "inactive", "all"]).default("all"),
+});
+
+export default defineEventHandler(async (event) => {
+  // h3 v2+ - pass schema directly (Standard Schema)
+  const query = await getValidatedQuery(event, querySchema);
+
+  // query is fully typed: { search?: string, page: number, limit: number, status: "active" | "inactive" | "all" }
+
+  // Use the validated params
+  const offset = (query.page - 1) * query.limit;
+
+  // Example: Build database query (pseudo-code)
+  // const users = await db.selectFrom("user")
+  //   .where((eb) => {
+  //     const filters = [];
+  //     if (query.search) filters.push(eb("name", "ilike", `%${query.search}%`));
+  //     if (query.status !== "all") filters.push(eb("status", "=", query.status));
+  //     return eb.and(filters);
+  //   })
+  //   .limit(query.limit)
+  //   .offset(offset)
+  //   .execute();
+
+  return {
+    message: "Query validated successfully",
+    query,
+    pagination: { page: query.page, limit: query.limit, offset },
+  };
+});

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md

@@ -0,0 +1,178 @@
+# Fetch Patterns
+
+## The Three Methods
+
+| Method | SSR | When to Use |
+|--------|-----|-------------|
+| `useFetch` | Yes | Default for page data loading |
+| `$fetch` | No | Event handlers (onClick, onSubmit) |
+| `useAsyncData` + `$fetch` | Yes | Custom cache keys, combining fetches |
+
+## useFetch (Default Choice)
+
+```typescript
+// Basic - types inferred from Nitro
+const { data, status, refresh, error } = await useFetch("/api/users");
+
+// With reactive query params - auto-refetches on change
+const search = ref("");
+const page = ref(1);
+const { data } = await useFetch("/api/users", {
+  query: { search, page },  // Reactive refs
+});
+
+// Computed query for conditional params
+const queryParams = computed(() => ({
+  ...(search.value ? { search: search.value } : {}),
+  offset: page.value * 20,
+}));
+const { data } = await useFetch("/api/users", {
+  query: queryParams,
+});
+
+// Dynamic URL with getter function
+const userId = ref("123");
+const { data } = await useFetch(() => `/api/users/${userId.value}`);
+
+// Transform response before caching
+const { data } = await useFetch("/api/users", {
+  transform: (response) => response.users.map(u => u.name),
+});
+
+// Reduce SSR payload size
+const { data } = await useFetch("/api/users", {
+  pick: ["id", "name"],  // Only these fields
+});
+```
+
+### New Options (Nuxt 3.14+)
+
+```typescript
+const { data } = await useFetch("/api/data", {
+  // Retry on failure
+  retry: 3,
+  retryDelay: 1000,
+
+  // Request deduplication
+  dedupe: "cancel",   // Cancel previous (default)
+  // dedupe: "defer",  // Wait for existing
+
+  // Built-in debounce
+  delay: 300,  // Wait before making request
+});
+```
+
+## Debounced Search Pattern
+
+```typescript
+const search = ref("");
+const debouncedSearch = refDebounced(search, 300);  // Auto-imported
+
+const { data } = await useFetch("/api/search", {
+  query: computed(() => ({
+    ...(debouncedSearch.value ? { q: debouncedSearch.value } : {}),
+  })),
+});
+
+// Reset pagination when filters change
+watch([debouncedSearch, categoryFilter], () => {
+  page.value = 0;
+});
+```
+
+## useAsyncData + $fetch
+
+Use when you need:
+1. Custom cache key
+2. Combine multiple fetches
+3. Non-HTTP async operations
+
+```typescript
+// Custom cache key
+const { data } = await useAsyncData("my-key", () =>
+  $fetch("/api/users")
+);
+
+// Combining fetches
+const { data } = await useAsyncData("combined", async () => {
+  const [users, roles] = await Promise.all([
+    $fetch("/api/users"),
+    $fetch("/api/roles"),
+  ]);
+  return { users, roles };
+});
+```
+
+## $fetch (Client-Only)
+
+Only use in event handlers - never at component top level:
+
+```typescript
+const handleSubmit = async () => {
+  const result = await $fetch("/api/users", {
+    method: "POST",
+    body: { name: "Test" },
+  });
+};
+
+const handleDelete = async (id: number) => {
+  await $fetch(`/api/users/${id}`, { method: "DELETE" });
+  refresh();  // Refresh useFetch data
+};
+```
+
+## Type Inference
+
+Template literals preserve type inference (fixed late 2024):
+
+```typescript
+const userId = "123";  // Type is "123" (literal)
+const result = await $fetch(`/api/users/${userId}`);
+// result typed from handler return type
+
+// Generic string loses precision
+const userId: string = "123";  // Type is string
+const result = await $fetch(`/api/users/${userId}`);
+// result is union of all matching routes
+```
+
+### Static route shadowing a dynamic sibling
+
+Template-literal inference normally resolves a dynamic route fine. But adding a
+**static** route under an existing `[param]` directory makes a template-literal
+`$fetch` to the dynamic sibling ambiguous. E.g. adding
+`server/api/invoices/summary.get.ts` next to `server/api/invoices/[id].get.ts`:
+the typed-route map now matches both `/api/invoices/:id` and
+`/api/invoices/summary`, so inference can't tell which `$fetch(\`/api/invoices/${id}\`)`
+means — and typecheck fails on the existing callers.
+
+Disambiguate by casting the URL to the specific route id (NOT the response
+type — that still defeats response inference):
+
+```typescript
+// Ambiguous after adding the static `/api/invoices/summary` route:
+const invoice = await $fetch(`/api/invoices/${id}`);
+
+// RIGHT - name the route id; the response stays inferred
+const invoice = await $fetch(`/api/invoices/${id}` as "/api/invoices/:id");
+```
+
+Expect this side effect whenever you add a static endpoint beside a `[param]`
+one — you'll need to touch the existing dynamic-route callers.
+
+**Never add manual types:**
+```typescript
+// WRONG - defeats inference
+const result = await $fetch<User>("/api/users/123");
+
+// RIGHT - let Nitro infer
+const result = await $fetch("/api/users/123");
+```
+
+## Common Mistakes
+
+1. **Using `$fetch` in `onMounted`** - Use `useFetch` instead
+2. **Manual watchers for refetch** - Query refs are auto-watched
+3. **Adding type params** - Types are inferred from Nitro
+4. **Using `watch` option for dynamic URLs** - Use getter function
+5. **Passing null/undefined in query** - Filter them out first