feat: add public notes caching and public count to notes endpoint

Public Notes Two-Tier Caching:
- Add Cloudflare CDN caching (24h TTL) for GET /api/public-notes/:slug
- Add Upstash Redis caching layer (24h TTL) between CDN and database
- Invalidate both caches on PUT/DELETE operations
- Add cloudflare-cache.ts helper for CDN purge via Cloudflare API

Public Count Feature:
- Add public count field to GET /api/notes/counts response
- Shows count of published notes (excludes archived/deleted)
- Joins with public_notes table to determine published status
- Update OpenAPI schemas with proper types (replaces z.any())

Environment variables required:
- CLOUDFLARE_ZONE_ID (for CDN purging)
- CLOUDFLARE_API_TOKEN (for CDN purging)
- PUBLIC_URL (for constructing purge URLs)

Author: rui-typelets

src/lib/cache-keys.ts

@@ -19,6 +19,9 @@ export const CacheKeys = {
 
   // Attachment-related
   noteAttachments: (noteId: string) => `attachments:note:${noteId}`,
+
+  // Public notes (no auth required, cached by slug)
+  publicNote: (slug: string) => `public:note:${slug}`,
 } as const;
 
 // Cache TTL values (in seconds)
@@ -34,4 +37,5 @@ export const CacheTTL = {
   notesDeleted: 300, // 5 minutes
   notesCounts: 120, // 2 minutes
   noteAttachments: 1800, // 30 minutes
+  publicNote: 86400, // 24 hours (same as Cloudflare CDN)
 } as const;

src/lib/cloudflare-cache.ts

@@ -0,0 +1,129 @@
+/**
+ * Cloudflare CDN Cache Utilities
+ * Handles cache purging for public content via Cloudflare API
+ */
+
+import { logger } from "./logger";
+
+interface CloudflarePurgeResponse {
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+  result: { id: string } | null;
+}
+
+/**
+ * Check if Cloudflare cache purging is configured
+ */
+function isCloudflareConfigured(): boolean {
+  return !!(
+    process.env.CLOUDFLARE_ZONE_ID &&
+    process.env.CLOUDFLARE_API_TOKEN &&
+    process.env.PUBLIC_URL
+  );
+}
+
+/**
+ * Purge specific URLs from Cloudflare CDN cache
+ * @param urls - Array of full URLs to purge
+ * @returns true if purge was successful (or Cloudflare not configured)
+ */
+export async function purgeCloudflareCache(urls: string[]): Promise<boolean> {
+  if (!isCloudflareConfigured()) {
+    logger.debug("[CLOUDFLARE] Cache purge skipped - not configured", {
+      urlCount: urls.length,
+    });
+    return true; // Not an error, just not configured
+  }
+
+  if (urls.length === 0) {
+    return true;
+  }
+
+  const zoneId = process.env.CLOUDFLARE_ZONE_ID!;
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN!;
+
+  try {
+    const startTime = Date.now();
+
+    const response = await fetch(
+      `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ files: urls }),
+      }
+    );
+
+    const duration = Date.now() - startTime;
+    const data: CloudflarePurgeResponse = await response.json();
+
+    if (data.success) {
+      logger.info("[CLOUDFLARE] Cache purged successfully", {
+        type: "cloudflare_cache_event",
+        event_type: "cache_purged",
+        urls: urls.join(", "),
+        urlCount: urls.length,
+        duration,
+      });
+      return true;
+    } else {
+      logger.error("[CLOUDFLARE] Cache purge failed", {
+        type: "cloudflare_cache_event",
+        event_type: "cache_purge_failed",
+        urls: urls.join(", "),
+        errors: JSON.stringify(data.errors),
+        duration,
+      });
+      return false;
+    }
+  } catch (error) {
+    logger.error(
+      "[CLOUDFLARE] Cache purge request failed",
+      {
+        type: "cloudflare_cache_event",
+        event_type: "cache_purge_error",
+        urls: urls.join(", "),
+      },
+      error instanceof Error ? error : new Error(String(error))
+    );
+    return false;
+  }
+}
+
+/**
+ * Purge a public note from Cloudflare CDN cache
+ * @param slug - The public note slug
+ */
+export async function purgePublicNoteCache(slug: string): Promise<boolean> {
+  const publicUrl = process.env.PUBLIC_URL;
+  if (!publicUrl) {
+    logger.debug("[CLOUDFLARE] PUBLIC_URL not configured, skipping cache purge");
+    return true;
+  }
+
+  // Purge both the API endpoint and any potential frontend route
+  const urls = [
+    `${publicUrl}/api/public-notes/${slug}`,
+    `${publicUrl}/p/${slug}`, // Frontend route if exists
+  ];
+
+  return purgeCloudflareCache(urls);
+}
+
+/**
+ * Get Cache-Control header value for public notes
+ * Uses stale-while-revalidate for better UX
+ */
+export function getPublicNoteCacheHeaders(): Record<string, string> {
+  // Cache for 24 hours, allow stale content for 1 hour while revalidating
+  // Long TTL is fine since we purge cache on update/unpublish
+  return {
+    "Cache-Control": "public, max-age=86400, stale-while-revalidate=3600",
+    // Vary on Accept-Encoding for proper compression handling
+    Vary: "Accept-Encoding",
+  };
+}

src/lib/openapi-schemas.ts

@@ -255,6 +255,7 @@ export const reorderFolderResponseSchema = z
 const countsObjectSchema = z.object({
   all: z.number().openapi({ example: 10, description: "Active notes count" }),
   starred: z.number().openapi({ example: 2, description: "Starred notes count" }),
+  public: z.number().openapi({ example: 1, description: "Published notes count" }),
   archived: z.number().openapi({ example: 1, description: "Archived notes count" }),
   trash: z.number().openapi({ example: 0, description: "Deleted notes count" }),
 });
@@ -263,12 +264,25 @@ export const noteCountsSchema = z
   .object({
     all: z.number().openapi({ example: 42, description: "Total active notes count" }),
     starred: z.number().openapi({ example: 5, description: "Total starred notes count" }),
+    public: z.number().openapi({ example: 3, description: "Total published notes count" }),
     archived: z.number().openapi({ example: 12, description: "Total archived notes count" }),
     trash: z.number().openapi({ example: 3, description: "Total deleted notes count" }),
     folders: z.record(z.string(), countsObjectSchema).openapi({
       example: {
-        "123e4567-e89b-12d3-a456-426614174000": { all: 10, starred: 2, archived: 1, trash: 0 },
-        "223e4567-e89b-12d3-a456-426614174001": { all: 5, starred: 1, archived: 0, trash: 0 },
+        "123e4567-e89b-12d3-a456-426614174000": {
+          all: 10,
+          starred: 2,
+          public: 1,
+          archived: 1,
+          trash: 0,
+        },
+        "223e4567-e89b-12d3-a456-426614174001": {
+          all: 5,
+          starred: 1,
+          public: 0,
+          archived: 0,
+          trash: 0,
+        },
       },
       description:
         "Counts for each root-level folder (folder IDs as keys, includes descendant notes)",