bsmnt 0.0.0

package/.cursor/rules/integrations.mdc

@@ -0,0 +1,447 @@
+---
+alwaysApply: true
+---
+---
+description: Third-party integration guidelines (Sanity, Shopify, etc.)
+globs: *.tsx, *.jsx, *.css, *.js, *.ts
+---
+
+# Third-Party Integration Guidelines
+
+## Sanity CMS Integration
+
+### Configuration & Setup
+Use CDN for performance with stega for visual editing. Store credentials securely in environment variables. All Sanity files are organized in `/lib/integrations/sanity/` directory.
+
+```typescript
+// In lib/integrations/sanity/client.ts
+export const client = createClient({
+  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID,
+  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET,
+  apiVersion: '2024-03-15',
+  useCdn: true, // Use CDN for better performance
+  token: process.env.SANITY_API_WRITE_TOKEN, // Write token for editing
+  stega: {
+    studioUrl: process.env.NEXT_PUBLIC_SANITY_STUDIO_URL || '/studio',
+  },
+})
+```
+
+### Schema Management
+
+#### Content Modelling
+- Unless explicitly modelling web pages or app views, create content models for what things are, not what they look like in a front-end
+- For example, consider the `status` of an element instead of its `color`
+
+#### Basic Schema Types
+- ALWAYS use the `defineType`, `defineField`, and `defineArrayMember` helper functions
+- ALWAYS write schema types to their own files and export a named `const` that matches the filename
+- ONLY use a `name` attribute in fields unless the `title` needs to be something other than a title-case version of the `name`
+- ANY `string` field type with an `options.list` array with fewer than 5 options must use `options.layout: "radio"`
+- ANY `image` field must include `options.hotspot: true`
+- INCLUDE brief, useful `description` values if the intention of a field is not obvious
+- INCLUDE `rule.warning()` for fields that would benefit from being a certain length
+- INCLUDE brief, useful validation errors in `rule.required().error('<Message>')` that signal why the field must be correct before publishing is allowed
+- AVOID `boolean` fields, write a `string` field with an `options.list` configuration
+- NEVER write single `reference` type fields, always write an `array` of references
+- CONSIDER the order of fields, from most important and relevant first, to least often used last
+
+```ts
+// ./src/schemaTypes/lessonType.ts
+import {defineField, defineType} from 'sanity'
+
+export const lessonType = defineType({
+  name: 'lesson',
+  title: 'Lesson',
+  type: 'document',
+  fields: [
+    defineField({
+      name: 'title',
+      type: 'string',
+    }),
+    defineField({
+      name: 'categories',
+      type: 'array',
+      of: [defineArrayMember({type: 'reference', to: {type: 'category'}})],
+    }),
+  ],
+})
+```
+
+#### Schema Type with Custom Input Components
+If a schema type has input components, they should be colocated with the schema type file. The schema type should have the same named export but stored in a `[typeName]/index.ts` file:
+
+```ts
+// ./src/schemaTypes/seoType/index.ts
+import {defineField, defineType} from 'sanity'
+import seoInput from './seoInput'
+
+export const seoType = defineType({
+  name: 'seo',
+  title: 'SEO',
+  type: 'object',
+  components: { input: seoInput }
+  // ...
+})
+```
+
+#### No Anonymous Reusable Schema Types
+ANY schema type that benefits from being reused in multiple document types should be registered as its own custom schema type.
+
+```ts
+// ./src/schemaTypes/blockContentType.ts
+import {defineField, defineType} from 'sanity'
+
+export const blockContentType = defineType({
+  name: 'blockContent',
+  title: 'Block content',
+  type: 'array',
+  of: [defineField({name: 'block',type: 'block'})],
+})
+```
+
+#### Decorating Schema Types
+Every `document` and `object` schema type should:
+
+- Have an `icon` property from `@sanity/icons`
+- Have a customized `preview` property that shows rich contextual details about the document
+- Use `groups` when the schema type has more than a few fields to collate related fields and only show the most important group by default. These `groups` should use the icon property as well.
+- Use `fieldsets` with `options: {columns: 2}` if related fields could be grouped visually together, such as `startDate` and `endDate`
+
+### Visual Editing
+Always add `data-sanity` attributes for visual editing. Use SanityContextProvider for document access. Implement proper draft mode handling. Import from `/lib/integrations/sanity` directory.
+
+```typescript
+import { RichText } from '@/integrations/sanity/components/rich-text'
+
+export function MyComponent() {
+  const { document } = useSanityContext()
+
+  return (
+    <div data-sanity={document._id}>
+      <h1 data-sanity="title">{document.title}</h1>
+      <div data-sanity="content">
+        <RichText content={document.content} />
+      </div>
+    </div>
+  )
+}
+```
+
+### Data Fetching
+Use proper perspective for draft vs published content. Implement caching strategies for performance. Handle errors gracefully with try-catch. Import from `/lib/integrations/sanity` directory. Use `@/utils/metadata` helpers for SEO optimization. All `sanityFetch` calls automatically use `cacheSignal()` for request cleanup.
+
+```typescript
+// In lib/integrations/sanity/queries/index.ts
+import { sanityFetch } from '@/integrations/sanity/live'
+import { generateSanityMetadata } from '@/utils/metadata'
+
+// Use sanityFetch (automatically includes cacheSignal)
+export async function fetchSanityPage(slug: string, isDraftMode = false) {
+  const { data, error } = await sanityFetch({
+    query: pageQuery,
+    params: { slug },
+    isDraftMode
+  })
+
+  if (error) {
+    console.error('fetchSanityPage error:', error)
+    return { data: null, error }
+  }
+
+  return { data, error: null }
+}
+
+// In page.tsx for SEO
+export async function generateMetadata({ params }) {
+  const { data } = await fetchSanityPage(params.slug)
+  return generateSanityMetadata(data)
+}
+```
+
+**Cache Components Notes:**
+- Draft mode automatically uses `cache: 'no-store'` ✅
+- Published content uses ISR with revalidation ✅
+- All queries use `cacheSignal()` for automatic cleanup ✅
+- Wrap in Suspense boundaries for proper loading states ✅
+
+### GROQ Queries
+
+- ALWAYS use SCREAMING_SNAKE_CASE for variable names, for example POSTS_QUERY
+- ALWAYS write queries to their own variables, never as a parameter in a function
+- ALWAYS import the `defineQuery` function to wrap query strings from the `groq` or `next-sanity` package
+- ALWAYS write every required attribute in a projection when writing a query
+- ALWAYS put each segment of a filter, and each attribute on its own line
+- ALWAYS use parameters for variables in a query
+- NEVER insert dynamic values using string interpolation
+
+```ts
+// In lib/integrations/sanity/queries/index.ts
+import { groq } from 'next-sanity'
+
+export const pageQuery = groq`
+  *[_type == "page" && slug.current == $slug][0] {
+    _id,
+    title,
+    slug,
+    content,
+    "imageUrl": image.asset->url,
+    _updatedAt
+  }
+`
+
+// Good query example
+import {defineQuery} from 'groq'
+
+export const POST_QUERY = defineQuery(`*[
+  _type == "post"
+  && slug.current == $slug
+][0]{
+  _id,
+  title,
+  image,
+  author->{
+    _id,
+    name
+  }
+}`)
+```
+
+### Performance Optimization
+Use ISR for static content with revalidation. Implement proper cache invalidation via webhooks. Optimize images with proper sizing. Use consolidated imports for better tree-shaking. Use metadata helpers for consistent SEO.
+
+```typescript
+import { urlForImage } from '@/integrations/sanity/utils/image'
+import { generateSanityMetadata } from '@/utils/metadata'
+
+// Use ISR for published content
+export const revalidate = 3600
+
+// Optimize images
+<SanityImage image={document.image} maxWidth={1200} />
+
+// Generate SEO metadata
+export async function generateMetadata({ params }) {
+  const page = await fetchSanityPage(params.slug)
+  return generateSanityMetadata(page, {
+    title: page.seo?.title || page.title,
+    description: page.seo?.description,
+    image: page.seo?.image || page.image,
+    noIndex: page.seo?.noIndex,
+  })
+}
+```
+
+### Project Structure
+All Sanity files are organized in `/lib/integrations/sanity/` directory
+
+```
+lib/integrations/sanity/
+├── sanity.cli.ts           # CLI configuration
+├── sanity.config.ts        # Studio configuration
+├── env.ts                  # Environment variables
+├── structure.ts            # Studio structure
+├── client.ts               # Sanity client
+├── fetch.ts                # Data fetching with cacheSignal
+├── index.ts                # Main exports
+├── README.md               # Documentation
+├── queries/
+│   └── index.ts            # GROQ queries
+├── schemaTypes/            # Content type definitions
+│   ├── documents/          # Document types (article, page, etc.)
+│   ├── objects/            # Object types (link, metadata, richText)
+│   ├── singletons/         # Singleton types (navigation)
+│   └── index.ts
+├── components/             # React components
+│   ├── context.tsx         # React context
+│   ├── rich-text.tsx       # Rich text component
+│   └── disable-draft-mode.tsx
+└── utils/
+    ├── image.ts            # Image utilities
+    └── link.ts             # Link utilities
+```
+
+### Writing Sanity Content for Importing
+
+When asked to write content:
+
+- ONLY use the existing schema types registered in the Studio configuration
+- ALWAYS write content as an `.ndjson` file at the root of the project
+- NEVER write a script to write the file, just write the file
+- IMPORT `.ndjson` files using the CLI command `npx sanity dataset import <filename.ndjson>`
+- NEVER include a `.` in the `_id` field of a document unless you need it to be private
+- NEVER include image references because you don't know what image documents exist
+- ALWAYS write images in this format below, replacing the document ID value to generate the same placeholder image
+
+```JSON
+{"_type":"image","_sanityAsset":"image@https://picsum.photos/seed/[[REPLACE_WITH_DOCUMENT_ID]]/1920/1080"}
+```
+
+### TypeScript Generation
+
+#### For the Studio
+ALWAYS re-run schema extraction after making schema file changes with `npx sanity@latest schema extract`
+
+#### For Monorepos
+ALWAYS use a simple pnpm workspace configuration to place the studio in `apps/studio`
+
+```
+your-project/
+└── apps/
+    ├── studio/ -> Sanity Studio
+    └── web/    -> Front-end
+```
+
+- ALWAYS extract the schema to the web folder with `npx sanity@latest schema extract --path=../<front-end-folder>/sanity/extract.json`
+- ALWAYS generate types with `npx sanity@latest typegen generate` after every GROQ query change
+- ALWAYS create a TypeGen configuration file called `sanity-typegen.json` at the root of the front-end code-base
+
+```json
+{
+  "path": "./**/*.{ts,tsx,js,jsx}",
+  "schema": "./<front-end-folder>/sanity/extract.json",
+  "generates": "./<web-folder>/sanity/types.ts"
+}
+```
+
+#### For the Front-end
+ONLY write Types for document types and query responses if you cannot generate them with Sanity TypeGen
+
+### Project Settings and Data
+ALWAYS check if there is a way to interact with a project via the CLI before writing custom scripts `npx sanity --help`
+
+---
+
+## Shopify Integration
+
+### API Configuration
+Use GraphQL for queries. Store credentials securely.
+
+```typescript
+const shopifyClient = createShopifyClient({
+  domain: process.env.SHOPIFY_DOMAIN,
+  storefrontAccessToken: process.env.SHOPIFY_STOREFRONT_TOKEN
+})
+```
+
+### Product Management
+Use fragments for reusable queries. Implement proper error handling.
+
+```typescript
+import { PRODUCT_FRAGMENT } from '@/lib/integrations/shopify/fragments/product'
+```
+
+### Cart Operations
+Use mutations for cart operations. Maintain cart state with Zustand.
+
+```typescript
+import { ADD_TO_CART_MUTATION } from '@/lib/integrations/shopify/mutations/cart'
+```
+
+---
+
+## General Integration Best Practices
+
+### Environment Variables
+- Never commit API keys
+- Use `.env.local` for development
+- Document required variables in `.env.example`
+- Validate environment variables are set before use
+
+```typescript
+// Check required env vars at module load
+const requiredEnvVars = ['NEXT_PUBLIC_API_KEY', 'API_SECRET'] as const
+for (const envVar of requiredEnvVars) {
+  if (!process.env[envVar]) {
+    throw new Error(`Missing required environment variable: ${envVar}`)
+  }
+}
+```
+
+### API Resilience
+**Always use `fetchWithTimeout` for external API calls**
+
+- Standard timeouts: 8-10 seconds for most integrations
+- Implement proper error handling and retry logic
+- Use `cacheSignal()` for automatic request cleanup (React 19+)
+
+```typescript
+import { fetchWithTimeout } from '@/utils/fetch'
+import { cacheSignal } from 'react'
+
+// With cacheSignal for automatic cleanup
+const signal = cacheSignal()
+const response = await fetchWithTimeout(url, {
+  timeout: 10000,
+  signal: signal as AbortSignal,
+  ...options
+})
+```
+
+### Error Handling
+Implement timeout handling for all API calls. Provide user-friendly error messages. Log errors for debugging with context.
+
+```typescript
+try {
+  const response = await fetchWithTimeout(url, options, 10000)
+  return { data: await response.json(), error: null }
+} catch (error) {
+  console.error('API call failed:', error)
+  return { data: null, error: error.message }
+}
+```
+
+### Type Safety
+Generate TypeScript types from APIs when possible. Use proper validation (e.g., Zod schemas).
+
+```typescript
+import * as z from "zod";
+
+const ProductSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  price: z.number()
+})
+```
+
+### Performance
+- Cache API responses appropriately (except user-specific data)
+- Use ISR (Incremental Static Regeneration) for dynamic content
+- Implement proper loading states with Suspense boundaries
+- Use `cacheSignal()` for automatic request cleanup
+
+**⚠️ Cache Components Gotchas:**
+- **User-specific data**: Never cache (carts, accounts, private content)
+- **Real-time data**: Use `cache: 'no-store'` for live feeds
+- **Suspense boundaries**: Required for cached data fetching
+- **Cache invalidation**: Use `revalidateTag()` or `revalidatePath()` in webhooks
+- **Testing**: Test with hard refresh AND navigation (different cache layers)
+
+### Security
+- Validate all user inputs
+- Use server-side API calls for sensitive operations
+- Implement rate limiting where necessary
+
+### Integration Management
+- Check integration usage with `@/lib/integrations/check-integration`
+- Keep only active integrations to optimize bundle size
+- Remove unused integration directories to reduce bundle size
+
+## Webhook Handling
+
+### Verification
+Always verify webhook signatures. Use proper authentication.
+
+```typescript
+export async function verifyWebhookSignature(
+  payload: string,
+  signature: string
+): Promise<boolean> {
+  // verification logic
+}
+```
+
+### Processing
+Process webhooks asynchronously. Implement idempotency. Return 200 status quickly.
+
+Last updated: 2025-12-18