naystack 1.1.17 → 1.2.0

package/README.md

@@ -43,6 +43,8 @@ import {
 
 Setup email-based authentication with JWT tokens and optional Turnstile captcha verification.
 
+**Basic Example:**
+
 ```typescript
 const emailAuth = getEmailAuthRoutes({
   getUser: async (email: string) => { /* fetch user by email */ },
@@ -59,6 +61,58 @@ const emailAuth = getEmailAuthRoutes({
 export const { GET, POST, PUT, DELETE, getUserIdFromRequest } = emailAuth;
 ```
 
+**Real-World Example with Drizzle ORM:**
+
+```typescript
+import { db } from "@/lib/db";
+import { UserTable, WebPushSubscriptionTable } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { getEmailAuthRoutes } from "naystack/auth";
+import { waitUntil } from "@vercel/functions";
+
+export const { GET, POST, PUT, DELETE, getUserIdFromRequest } =
+  getEmailAuthRoutes({
+    // Fetch user by email using Drizzle
+    getUser: (email: string) => 
+      db.query.UserTable.findFirst({ 
+        where: eq(UserTable.email, email) 
+      }),
+    
+    // Create new user
+    createUser: async (user) => {
+      const [newUser] = await db
+        .insert(UserTable)
+        .values(user)
+        .returning();
+      return newUser;
+    },
+    
+    signingKey: process.env.SIGNING_KEY!,
+    refreshKey: process.env.REFRESH_KEY!,
+    turnstileKey: process.env.TURNSTILE_KEY!,
+    
+    // Send welcome email on signup
+    onSignUp: ({ id, email }) =>
+      waitUntil(
+        (async () => {
+          const link = await getVerificationLink(id);
+          if (link && email) {
+            await sendTemplateEmail(email, "WelcomeUser", {
+              verifyLink: link,
+            });
+          }
+        })(),
+      ),
+    
+    // Clean up push subscriptions on logout
+    onLogout: async (endpoint: string) => {
+      await db
+        .delete(WebPushSubscriptionTable)
+        .where(eq(WebPushSubscriptionTable.endpoint, endpoint));
+    },
+  });
+```
+
 #### Options
 
 | Option         | Type                                                    | Required | Description                     |
@@ -93,20 +147,54 @@ interface UserOutput {
 
 ### Google Authentication
 
+**Real-World Example:**
+
 ```typescript
-const googleAuth = initGoogleAuth({
+import { db } from "@/lib/db";
+import { UserTable } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { initGoogleAuth } from "naystack/auth";
+
+export const { GET } = initGoogleAuth({
   clientId: process.env.GOOGLE_CLIENT_ID!,
   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-  authRoute: "/api/auth/google",
+  authRoute: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/google`,
   successRedirectURL: "/dashboard",
   errorRedirectURL: "/login?error=google",
-  refreshKey: process.env.JWT_REFRESH_KEY!,
-  getUserIdFromEmail: async (userInfo) => {
-    /* return user ID or null */
+  refreshKey: process.env.REFRESH_KEY!,
+  
+  // Find existing user or create new one
+  getUserIdFromEmail: async ({ email, name }) => {
+    if (!email) return null;
+
+    // Update existing user's email verification status
+    const [existingUser] = await db
+      .update(UserTable)
+      .set({ emailVerified: true })
+      .where(eq(UserTable.email, email))
+      .returning({ id: UserTable.id });
+    
+    if (existingUser) {
+      return existingUser.id;
+    }
+    
+    // Create new user if doesn't exist
+    if (name && email) {
+      const [newUser] = await db
+        .insert(UserTable)
+        .values({
+          email,
+          name,
+          emailVerified: true,
+        })
+        .returning({ id: UserTable.id });
+      
+      return newUser?.id || null;
+    }
+    
+    return null;
   },
 });
-
-export const { GET } = googleAuth;
 ```
 
 #### Options
@@ -125,20 +213,65 @@ export const { GET } = googleAuth;
 
 ### Instagram Authentication
 
+**Real-World Example:**
+
 ```typescript
-const instagramAuth = initInstagramAuth({
-  clientId: process.env.INSTAGRAM_CLIENT_ID!,
+import { db } from "@/lib/db";
+import { InstagramDetails, UserTable } from "@/lib/db/schema";
+import { and, eq, ne } from "drizzle-orm";
+import { initInstagramAuth } from "naystack/auth";
+
+export const { GET, getRefreshedAccessToken } = initInstagramAuth({
+  clientId: process.env.NEXT_PUBLIC_INSTAGRAM_CLIENT_ID!,
   clientSecret: process.env.INSTAGRAM_CLIENT_SECRET!,
-  authRoute: "/api/auth/instagram",
-  successRedirectURL: "/dashboard",
-  errorRedirectURL: "/login?error=instagram",
-  refreshKey: process.env.JWT_REFRESH_KEY!,
-  onUser: async (data, userId, accessToken) => {
-    /* handle Instagram user */
+  authRoute: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/instagram`,
+  successRedirectURL: "/profile",
+  errorRedirectURL: "/signup",
+  refreshKey: process.env.REFRESH_KEY!,
+  
+  // Verify and link Instagram account
+  onUser: async (instagramData, userId, accessToken) => {
+    if (!userId) return "You are not logged in";
+    
+    const user = await db.query.UserTable.findFirst({
+      where: eq(UserTable.id, userId),
+    });
+    
+    if (!user?.instagramDetails) {
+      return "Please connect Instagram first";
+    }
+
+    // Update Instagram verification status
+    const [updated] = await db
+      .update(InstagramDetails)
+      .set({ 
+        isVerified: true, 
+        accessToken: accessToken 
+      })
+      .where(
+        and(
+          eq(InstagramDetails.id, user.instagramDetails),
+          eq(InstagramDetails.username, instagramData.username),
+        ),
+      )
+      .returning({ username: InstagramDetails.username });
+
+    if (!updated) {
+      return "Please login with the same username as the connected account";
+    }
+
+    // Disconnect from other users if linked
+    await db
+      .update(UserTable)
+      .set({ instagramDetails: null })
+      .where(
+        and(
+          ne(UserTable.id, userId),
+          eq(UserTable.instagramDetails, user.instagramDetails),
+        ),
+      );
   },
 });
-
-export const { GET, getRefreshedAccessToken } = instagramAuth;
 ```
 
 #### Options
@@ -171,6 +304,8 @@ import type { Context, AuthorizedContext } from "naystack/graphql";
 
 ### Initialize GraphQL Server
 
+**Basic Example:**
+
 ```typescript
 const { GET, POST } = await initGraphQLServer({
   resolvers: [UserResolver, PostResolver],
@@ -185,6 +320,43 @@ const { GET, POST } = await initGraphQLServer({
 export { GET, POST };
 ```
 
+**Real-World Example with Advanced Context:**
+
+```typescript
+import { initGraphQLServer } from "naystack/graphql";
+import { getUserIdFromRequest } from "@/api/(auth)/email/setup";
+import { authChecker } from "@/lib/auth/context";
+
+export const { GET, POST } = await initGraphQLServer({
+  resolvers: [
+    UserResolver,
+    PostResolver,
+    ApplicationResolver,
+    ChatResolver,
+    // ... more resolvers
+  ],
+  authChecker,
+  context: async (req) => {
+    const res = getUserIdFromRequest(req);
+    if (!res) return { userId: null };
+    
+    // Handle refresh token user ID
+    if (res.refreshUserID) {
+      const isMobile = req.headers.get("x-platform-is-mobile");
+      if (isMobile) return { userId: null };
+      return { userId: res.refreshUserID, onlyQuery: true };
+    }
+    
+    // Handle access token user ID
+    if (res.accessUserId) {
+      return { userId: res.accessUserId };
+    }
+    
+    return { userId: null };
+  },
+});
+```
+
 #### Options
 
 | Option        | Type                                 | Required | Description                      |
@@ -196,6 +368,8 @@ export { GET, POST };
 
 ### Error Handling
 
+**Basic Usage:**
+
 ```typescript
 import { GQLError } from "naystack/graphql";
 
@@ -206,10 +380,64 @@ throw GQLError(400); // "Please provide all required inputs"
 throw GQLError(); // "Server Error" (500)
 ```
 
+**Real-World Example in Resolvers:**
+
+```typescript
+import { GQLError } from "naystack/graphql";
+import { db } from "@/lib/db";
+import { UserTable, PostingTable } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+
+export async function createPosting(
+  ctx: Context,
+  input: NewPostingInput,
+): Promise<number | null> {
+  // Authentication check
+  if (!ctx.userId) {
+    throw GQLError(400, "Please login to create posting");
+  }
+
+  const user = await db.query.UserTable.findFirst({
+    where: eq(UserTable.id, ctx.userId),
+  });
+
+  // Authorization check
+  if (!user || user.role === "CREATOR") {
+    throw GQLError(400, "Only onboarded users can create postings");
+  }
+
+  // Validation check
+  if (!user.emailVerified) {
+    throw GQLError(400, "Please verify email to create posting");
+  }
+
+  // Rate limiting check
+  const yesterday = new Date();
+  yesterday.setDate(yesterday.getDate() - 1);
+  const recentPostings = await db.query.PostingTable.findMany({
+    where: and(
+      eq(PostingTable.userId, ctx.userId),
+      gte(PostingTable.createdAt, yesterday),
+    ),
+  });
+
+  if (recentPostings.length >= MAXIMUM_POSTINGS_DAY) {
+    throw GQLError(
+      400,
+      `Only ${MAXIMUM_POSTINGS_DAY} allowed in 24 hours. Try again later.`,
+    );
+  }
+
+  // Create posting...
+}
+```
+
 ### Query & Field Helpers
 
 Build resolvers functionally using `query`, `field`, `QueryLibrary`, and `FieldLibrary`:
 
+**Basic Example:**
+
 ```typescript
 import { query, QueryLibrary, field, FieldLibrary } from "naystack/graphql";
 
@@ -255,6 +483,62 @@ const fields = {
 const UserFieldResolver = FieldLibrary(User, fields);
 ```
 
+**Real-World Example:**
+
+```typescript
+import { query, QueryLibrary, field, FieldLibrary } from "naystack/graphql";
+import { db } from "@/lib/db";
+import { NotificationTable } from "@/lib/db/schema";
+import { eq, lte } from "drizzle-orm";
+import { waitUntil } from "@vercel/functions";
+
+// Query with side effects
+export const getNotifications = query(
+  async (ctx) => {
+    if (!ctx.userId) return [];
+    
+    // Mark all as read
+    const notifications = await db
+      .update(NotificationTable)
+      .set({ read: true })
+      .where(eq(NotificationTable.user, ctx.userId))
+      .returning();
+    
+    // Clean up old notifications (async)
+    const weekBefore = new Date();
+    weekBefore.setDate(weekBefore.getDate() - 7);
+    waitUntil(
+      db
+        .delete(NotificationTable)
+        .where(lte(NotificationTable.createdAt, weekBefore)),
+    );
+    
+    return notifications.sort((a, b) => a.id - b.id);
+  },
+  {
+    output: [NotificationGQL!],
+  },
+);
+
+// Create resolver from queries
+export const NotificationResolver = QueryLibrary({
+  getNotifications,
+  getUnreadNotifications,
+});
+
+// Field resolver example
+export const UserFields = FieldLibrary(UserGQL, {
+  isOnboarded: field(
+    async (user) => {
+      return getIsOnboarded(user);
+    },
+    {
+      output: Boolean,
+    }
+  ),
+});
+```
+
 ### Types
 
 ```typescript
@@ -285,7 +569,9 @@ import {
 
 #### `useVisibility`
 
-Observe element visibility using Intersection Observer.
+Observe element visibility using Intersection Observer. Perfect for infinite scroll and lazy loading.
+
+**Basic Example:**
 
 ```typescript
 function Component() {
@@ -297,9 +583,38 @@ function Component() {
 }
 ```
 
+**Real-World Example - Infinite Scroll:**
+
+```typescript
+"use client";
+
+import { useVisibility } from "naystack/client";
+import { useRef } from "react";
+
+export default function PostingCard({ 
+  posting, 
+  fetchMore 
+}: { 
+  posting: Posting;
+  fetchMore?: () => void;
+}) {
+  // Trigger fetchMore when card becomes visible
+  const mainRef = useVisibility(fetchMore);
+
+  return (
+    <div ref={mainRef} className="posting-card">
+      <h3>{posting.title}</h3>
+      <p>{posting.description}</p>
+    </div>
+  );
+}
+```
+
 #### `useBreakpoint`
 
-React to media query changes.
+React to media query changes. Useful for responsive layouts and conditional rendering.
+
+**Basic Example:**
 
 ```typescript
 function Component() {
@@ -309,6 +624,35 @@ function Component() {
 }
 ```
 
+**Real-World Example - Responsive Layout:**
+
+```typescript
+"use client";
+
+import { useBreakpoint } from "naystack/client";
+
+export default function LayoutWrapper({ 
+  children 
+}: { 
+  children: React.ReactNode;
+}) {
+  const isLarge = useBreakpoint("(min-width: 1024px)");
+
+  return (
+    <div
+      style={{
+        height: isLarge 
+          ? "calc(100svh - 80px)" 
+          : "calc(100svh - 55px)",
+      }}
+      className="flex flex-col"
+    >
+      {children}
+    </div>
+  );
+}
+```
+
 ### SEO Helper
 
 ```typescript
@@ -329,14 +673,28 @@ export const metadata = getSEO(
 
 ### Instagram Authorization URL
 
+Generate Instagram OAuth authorization URLs for client-side redirects.
+
+**Example:**
+
 ```typescript
-const getInstagramAuthURL = getInstagramAuthorizationURLSetup(
-  process.env.INSTAGRAM_CLIENT_ID!,
-  "https://myapp.com/api/auth/instagram"
+import { getInstagramAuthorizationURLSetup } from "naystack/client";
+
+// Setup once
+const getInstagramAuthorizationURL = getInstagramAuthorizationURLSetup(
+  process.env.NEXT_PUBLIC_INSTAGRAM_CLIENT_ID!,
+  `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/instagram`,
 );
 
-// Usage
-const authURL = getInstagramAuthURL(userToken);
+// Usage in component
+function ConnectInstagramButton() {
+  const handleConnect = () => {
+    const authURL = getInstagramAuthorizationURL(userToken);
+    window.location.href = authURL;
+  };
+
+  return <button onClick={handleConnect}>Connect Instagram</button>;
+}
 ```
 
 ### Image Upload Client
@@ -363,6 +721,8 @@ import { setupFileUpload } from "naystack/file";
 
 ### Setup File Upload
 
+**Basic Example:**
+
 ```typescript
 const fileUpload = setupFileUpload({
   refreshKey: process.env.JWT_REFRESH_KEY!,
@@ -388,6 +748,113 @@ const { getUploadFileURL, uploadImage, deleteImage, getFileURL, uploadFile } =
   fileUpload;
 ```
 
+**Real-World Example with Multiple File Types:**
+
+```typescript
+import { setupFileUpload } from "naystack/file";
+import { db } from "@/lib/db";
+import { PortfolioTable, UserTable } from "@/lib/db/schema";
+import { and, eq } from "drizzle-orm";
+import { waitUntil } from "@vercel/functions";
+
+export const { deleteImage, getUploadFileURL, getFileURL, uploadImage, PUT } =
+  setupFileUpload({
+    region: process.env.SITE_AWS_REGION!,
+    refreshKey: process.env.REFRESH_KEY!,
+    awsSecret: process.env.SITE_AWS_SECRET_ACCESS_KEY!,
+    awsKey: process.env.SITE_AWS_ACCESS_KEY_ID!,
+    signingKey: process.env.SIGNING_KEY!,
+    bucket: process.env.SITE_AWS_BUCKET!,
+    
+    processFile: async ({ url, userId, data, type }) => {
+      switch (type) {
+        case "PORTFOLIO":
+          // Handle portfolio image upload
+          waitUntil(
+            (async () => {
+              if (!url) return {};
+              const id = (data as { id?: number }).id;
+              
+              if (id) {
+                // Update existing portfolio
+                const [existing] = await db
+                  .select()
+                  .from(PortfolioTable)
+                  .where(
+                    and(
+                      eq(PortfolioTable.id, id),
+                      eq(PortfolioTable.user, userId),
+                    ),
+                  );
+
+                if (!existing) {
+                  return { deleteURL: url };
+                }
+                
+                const oldURL = existing.imageURL;
+                await db
+                  .update(PortfolioTable)
+                  .set({ imageURL: url })
+                  .where(
+                    and(
+                      eq(PortfolioTable.id, id),
+                      eq(PortfolioTable.user, userId),
+                    ),
+                  );
+
+                return {
+                  deleteURL: oldURL,
+                  data: { id },
+                };
+              } else {
+                // Create new portfolio
+                const [portfolio] = await db
+                  .insert(PortfolioTable)
+                  .values({
+                    user: userId,
+                    imageURL: url,
+                    caption: "",
+                    link: "",
+                  })
+                  .returning({ id: PortfolioTable.id });
+                
+                return { data: { id: portfolio?.id } };
+              }
+            })(),
+          );
+          break;
+          
+        case "PROFILE_PICTURE":
+          // Handle profile picture upload
+          waitUntil(
+            (async () => {
+              const user = await db.query.UserTable.findFirst({
+                where: eq(UserTable.id, userId),
+              });
+              
+              if (!user && url) {
+                return { deleteURL: url };
+              }
+              
+              const oldPhoto = user?.photo;
+              await db
+                .update(UserTable)
+                .set({ photo: url })
+                .where(eq(UserTable.id, userId));
+
+              return {
+                deleteURL: oldPhoto || undefined,
+              };
+            })(),
+          );
+          break;
+      }
+      
+      return {};
+    },
+  });
+```
+
 #### Options
 
 | Option        | Type       | Required | Description              |
@@ -452,6 +919,8 @@ const user = await getInstagramUser(accessToken, "me", [
 
 #### Get Media
 
+**Basic Usage:**
+
 ```typescript
 const media = await getInstagramMedia(accessToken);
 const media = await getInstagramMedia(
@@ -461,6 +930,60 @@ const media = await getInstagramMedia(
 );
 ```
 
+**Real-World Example - Fetching Media with Custom Fields:**
+
+```typescript
+import { getInstagramMedia } from "naystack/socials";
+
+export async function fetchInstagramGraphMedia(
+  accessToken: string,
+  followers: number,
+  userId: number,
+) {
+  const fetchReq = await getInstagramMedia<{
+    thumbnail_url?: string;
+    id: string;
+    like_count?: number;
+    comments_count: number;
+    permalink: string;
+    caption: string;
+    media_url?: string;
+    media_type?: string;
+    timestamp: string;
+  }>(accessToken, [
+    "id",
+    "thumbnail_url",
+    "media_url",
+    "like_count",
+    "comments_count",
+    "media_type",
+    "permalink",
+    "caption",
+    "timestamp",
+  ]);
+  
+  if (fetchReq?.data) {
+    return fetchReq.data.map((media) => ({
+      isVideo: media.media_type === "VIDEO",
+      comments: media.comments_count || -1,
+      likes: media.like_count || 0,
+      link: media.permalink,
+      thumbnail: media.thumbnail_url || media.media_url,
+      mediaURL: media.media_url,
+      timestamp: media.timestamp,
+      caption: media.caption,
+      appID: media.id,
+      user: userId,
+      er: calculateEngagementRate(
+        followers,
+        media.like_count || 0,
+        media.comments_count || -1,
+      ),
+    }));
+  }
+}
+```
+
 #### Conversations
 
 ```typescript
@@ -495,6 +1018,8 @@ const result = await sendInstagramMessage(accessToken, recipientId, "Hello!");
 
 #### Webhook
 
+**Basic Example:**
+
 ```typescript
 const instagramWebhook = setupInstagramWebhook({
   secret: process.env.INSTAGRAM_WEBHOOK_SECRET!,
@@ -506,6 +1031,59 @@ const instagramWebhook = setupInstagramWebhook({
 export const { GET, POST } = instagramWebhook;
 ```
 
+**Real-World Example - Auto-Reply Bot:**
+
+```typescript
+import {
+  getInstagramConversationByUser,
+  sendInstagramMessage,
+  setupInstagramWebhook,
+} from "naystack/socials";
+
+export const { GET, POST } = setupInstagramWebhook({
+  secret: process.env.REFRESH_KEY!,
+  callback: async (
+    type,
+    value: {
+      sender: { id: string };
+      message: { text: string };
+      recipient: { id: string };
+    },
+  ) => {
+    if (
+      type === "messaging" &&
+      value.message.text &&
+      value.sender.id !== "YOUR_PAGE_ID" &&
+      value.recipient.id === "YOUR_PAGE_ID"
+    ) {
+      // Check if message is recent (within 24 hours)
+      const conversation = await getInstagramConversationByUser(
+        process.env.INSTAGRAM_ACCESS_TOKEN!,
+        value.sender.id,
+      );
+      
+      const lastMessage = conversation?.messages?.data[1]?.created_time;
+      if (lastMessage) {
+        const lastMessageDate = new Date(lastMessage);
+        if (lastMessageDate.getTime() > Date.now() - 1000 * 60 * 60 * 24) {
+          return; // Already replied recently
+        }
+      }
+      
+      // Generate reply (using your AI/LLM service)
+      const reply = await generateReply(value.message.text);
+      if (reply && reply !== '""') {
+        await sendInstagramMessage(
+          process.env.INSTAGRAM_ACCESS_TOKEN!,
+          value.sender.id,
+          reply,
+        );
+      }
+    }
+  },
+});
+```
+
 ---
 
 ### Threads API
@@ -547,6 +1125,8 @@ const firstPostId = await createThread(accessToken, [
 
 #### Webhook
 
+**Basic Example:**
+
 ```typescript
 const threadsWebhook = setupThreadsWebhook({
   secret: process.env.THREADS_WEBHOOK_SECRET!,
@@ -559,6 +1139,144 @@ const threadsWebhook = setupThreadsWebhook({
 export const { GET, POST } = threadsWebhook;
 ```
 
+**Real-World Example - Auto-Reply to Threads:**
+
+```typescript
+import {
+  createThreadsPost,
+  getThreadsReplies,
+  setupThreadsWebhook,
+} from "naystack/socials";
+import { db } from "@/lib/db";
+import { SocialPostsTable } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+
+const REPLIES = [
+  "Thanks for your interest! Check out campaign ${ID}",
+  "We'd love to work with you! See campaign ${ID}",
+];
+
+export const { GET, POST } = setupThreadsWebhook({
+  secret: process.env.REFRESH_KEY!,
+  callback: async (
+    field,
+    value: {
+      id: string;
+      username: string;
+      text: string;
+      replied_to: { id: string };
+      root_post: { id: string; username: string };
+    },
+  ) => {
+    // Skip if replying to own post
+    if (value.root_post.username === value.username) return true;
+    
+    // Only reply to direct replies to root post
+    if (value.root_post.id !== value.replied_to.id) return true;
+    
+    // Check if already replied
+    const replies = await getThreadsReplies(
+      process.env.THREADS_ACCESS_TOKEN!,
+      value.id,
+    );
+    if (replies?.length ?? 0 > 0) return true;
+    
+    // Find associated campaign
+    const [post] = await db
+      .select()
+      .from(SocialPostsTable)
+      .where(eq(SocialPostsTable.postID, value.root_post.id));
+    
+    if (!post) return true;
+    
+    // Generate reply message
+    const message = REPLIES[
+      Math.floor(Math.random() * REPLIES.length)
+    ]?.replace("${ID}", post.campaignID.toString());
+    
+    if (!message) return true;
+
+    // Send reply
+    const res = await createThreadsPost(
+      process.env.THREADS_ACCESS_TOKEN!,
+      message,
+      value.id,
+    );
+    
+    return !!res;
+  },
+});
+```
+
+---
+
+## Best Practices & Common Patterns
+
+### Authentication Flow
+
+1. **Email Auth with Database Integration:**
+   - Use Drizzle ORM queries in `getUser` and `createUser`
+   - Send verification emails in `onSignUp` callback
+   - Clean up session data in `onLogout`
+
+2. **OAuth Integration:**
+   - Always verify email/username matches existing accounts
+   - Create new users only when necessary
+   - Update verification status for existing users
+
+### GraphQL Resolver Patterns
+
+1. **Error Handling:**
+   - Use `GQLError` for all error cases
+   - Provide clear, user-friendly error messages
+   - Use appropriate HTTP status codes (400, 403, 404, 500)
+
+2. **Authorization:**
+   - Check authentication first (`if (!ctx.userId)`)
+   - Verify permissions before operations
+   - Use `authChecker` for role-based access control
+
+3. **Query Library Pattern:**
+   - Use `query()` helper for simple queries/mutations
+   - Use `QueryLibrary()` to combine multiple queries
+   - Use `field()` and `FieldLibrary()` for computed fields
+
+### File Upload Patterns
+
+1. **Multiple File Types:**
+   - Use `type` parameter to distinguish upload types
+   - Handle each type in `processFile` callback
+   - Return `deleteURL` for old files to clean up
+
+2. **Async Processing:**
+   - Use `waitUntil()` for non-blocking operations
+   - Process file metadata in background
+   - Update database after successful upload
+
+### Webhook Patterns
+
+1. **Instagram Webhooks:**
+   - Verify sender/recipient IDs
+   - Check message timestamps to avoid duplicates
+   - Use async operations for replies
+
+2. **Threads Webhooks:**
+   - Filter by reply structure (root_post vs replied_to)
+   - Check for existing replies before responding
+   - Return `true`/`false` to indicate success/failure
+
+### Client-Side Patterns
+
+1. **Infinite Scroll:**
+   - Use `useVisibility` hook with `fetchMore` callback
+   - Attach ref to last item in list
+   - Handle loading states
+
+2. **Responsive Design:**
+   - Use `useBreakpoint` for conditional rendering
+   - Adjust layout based on screen size
+   - Combine with CSS for optimal UX
+
 ---
 
 ## Environment Variables