Cursor AI Integration

# .cursorrules

## PostPost API Integration

This project uses PostPost API for social media scheduling.

### API Details
- Base URL: https://api.postpost.dev/api/v1
- Auth: x-api-key header with API key
- Docs: https://docs.postpost.dev

### Key Endpoints
- GET /platform-connections - List connected accounts
- POST /create-post - Create/schedule posts
- GET /get-post/{id} - Get post status
- PUT /update-post/{id} - Update scheduled post
- DELETE /delete-post/{id} - Delete post
- POST /get-upload-url - Get pre-signed upload URL
- POST /linkedin-post-statistics - Get LinkedIn analytics

### Platform IDs
Format: {platform}-{id} (e.g., twitter-123456789, linkedin-ABC123DEF)

### Supported Platforms
twitter, linkedin, instagram, threads, tiktok, youtube, facebook, bluesky, mastodon, telegram

### Request Format
- Content-Type: application/json
- scheduledTime: ISO 8601 UTC format (YYYY-MM-DDTHH:mm:ss.sssZ)
- platforms: array of platform IDs

### Common Patterns
- Always check response.ok or status code before processing
- Use 200ms delay between batch requests for rate limiting
- Handle partial failures (some platforms may fail while others succeed)

# Good prompts for Cursor

"Create a function to schedule a post to Twitter and LinkedIn using PostPost API"

"Add error handling for PostPost API responses with retry logic for 500 errors"

"Build a React component that shows connected social accounts from PostPost"

"Write a Python script to import posts from CSV and schedule them via PostPost"

"Create a Next.js API route to proxy PostPost requests with proper authentication"

// Cursor: Use this as reference for PostPost API calls

// Authentication header
const headers = {
  'Content-Type': 'application/json',
  'x-api-key': process.env.PUBLORA_API_KEY,
};

// List connections
const connections = await fetch('https://api.postpost.dev/api/v1/platform-connections', {
  headers
}).then(r => r.json());

// Create post
const post = await fetch('https://api.postpost.dev/api/v1/create-post', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    content: 'Your post content',
    platforms: ['twitter-123456789'],
    scheduledTime: '2026-03-01T14:00:00.000Z', // Optional
  })
}).then(r => r.json());

// Get post status
const status = await fetch(`https://api.postpost.dev/api/v1/get-post/${postGroupId}`, {
  headers
}).then(r => r.json());

// Delete post
await fetch(`https://api.postpost.dev/api/v1/delete-post/${postGroupId}`, {
  method: 'DELETE',
  headers
});

# Cursor: Use this as reference for PostPost API calls

import requests

BASE_URL = 'https://api.postpost.dev/api/v1'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': os.environ['PUBLORA_API_KEY']
}

# List connections
connections = requests.get(f'{BASE_URL}/platform-connections', headers=headers).json()

# Create post
post = requests.post(f'{BASE_URL}/create-post', headers=headers, json={
    'content': 'Your post content',
    'platforms': ['twitter-123456789'],
    'scheduledTime': '2026-03-01T14:00:00.000Z',  # Optional
}).json()

# Get post status
status = requests.get(f'{BASE_URL}/get-post/{post_group_id}', headers=headers).json()

# Delete post
requests.delete(f'{BASE_URL}/delete-post/{post_group_id}', headers=headers)

Build a social media scheduling feature for my app using PostPost API.

Requirements:
1. Form to compose posts with character count
2. Platform selector from connected accounts
3. Date/time picker for scheduling
4. Submit handler that calls PostPost API
5. Success/error feedback

Use: [React/Vue/Svelte] with [TypeScript/JavaScript]
API Key is in environment variable PUBLORA_API_KEY

Create a LinkedIn analytics dashboard using PostPost API.

Requirements:
1. Fetch post statistics from /linkedin-post-statistics
2. Display impressions, members reached, reactions, comments, reshares
3. Calculate engagement rate from reactions + comments + reshares
4. Show comparison between posts
5. Add date range filter

Platform connection ID: linkedin-ABC123DEF

Build a CSV import tool for scheduling posts via PostPost.

CSV format:
content,platforms,scheduled_time,media_url

Requirements:
1. File upload and CSV parsing
2. Validation before import
3. Progress indicator
4. Rate limiting (200ms between requests)
5. Summary of successful/failed imports

# Fix authentication errors
"The PostPost API returns 401. Check that x-api-key header is set correctly."

# Fix scheduling errors
"PostPost returns 'Invalid scheduled time'. Convert scheduledTime to ISO 8601 UTC format."

# Fix platform ID errors
"PostPost returns 'Invalid platform ID'. Platform IDs should be format: platform-id (e.g., twitter-123456789)"

# Handle partial failures
"The post shows 'partially_published' status. Check each platform post status individually."

// Add this to your project for easier debugging with Cursor
async function debugPostPostRequest(endpoint: string, options: RequestInit = {}) {
  console.log('PostPost Request:', {
    url: `https://api.postpost.dev/api/v1${endpoint}`,
    method: options.method || 'GET',
    body: options.body ? JSON.parse(options.body as string) : undefined,
  });

  const response = await fetch(`https://api.postpost.dev/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.PUBLORA_API_KEY!,
      ...options.headers,
    },
  });

  const data = await response.json();

  console.log('PostPost Response:', {
    status: response.status,
    ok: response.ok,
    data,
  });

  if (!response.ok) {
    throw new Error(`PostPost API error: ${data.error || data.message}`);
  }

  return data;
}

// types/postpost.d.ts
// Add to your project for Cursor autocomplete

declare namespace PostPost {
  interface PlatformConnection {
    platformId: string;
    platform: 'twitter' | 'linkedin' | 'instagram' | 'threads' | 'tiktok' | 'youtube' | 'facebook' | 'bluesky' | 'mastodon' | 'telegram';
    username: string;
    displayName: string;
    profileImageUrl?: string;
  }

  interface CreatePostRequest {
    content: string;
    platforms: string[];
    scheduledTime?: string;
    status?: 'draft' | 'scheduled';
    platformSettings?: {
      instagram?: { videoType?: 'REELS' | 'STORIES' };
      tiktok?: { disableDuet?: boolean; disableStitch?: boolean };
      telegram?: { parseMode?: 'HTML' | 'MarkdownV2' };
    };
  }

  interface Post {
    platform: string;
    platformId: string;
    status: 'draft' | 'scheduled' | 'pending' | 'processing' | 'published' | 'failed';
    publishedUrl?: string;
    error?: string;
  }

  interface PostGroup {
    postGroupId: string;
    content: string;
    status: string;
    scheduledTime?: string;
    posts: Post[];
  }

  interface CreatePostResponse {
    success: boolean;
    postGroupId: string;
    posts: Post[];
  }

  interface LinkedInStats {
    success: boolean;
    metrics: {
      IMPRESSION: number;
      MEMBERS_REACHED: number;
      RESHARE: number;
      REACTION: number;
      COMMENT: number;
    };
    cached: boolean;
  }
}

@context7 How do I schedule a post to multiple platforms with PostPost API?

@context7 Show me how to upload an image and create a post with PostPost

@context7 What are the rate limits for PostPost API?

// .cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic/context7-mcp"]
    }
  }
}

I'm building a social media scheduler using:
- Next.js 14 with App Router
- PostPost API for posting
- PostgreSQL for storing post history

My PUBLORA_API_KEY is in .env.local

Now, create an API route to schedule a post...

Step 1: "Create a function to fetch PostPost connections"
Step 2: "Add error handling to the connections function"
Step 3: "Create a React hook that uses this function"
Step 4: "Add caching to reduce API calls"

"Explain why you used a 200ms delay between API calls"
"What happens if the scheduledTime is in the past?"
"How does the partial failure handling work?"

"Create unit tests for the PostPost service class"
"Add integration tests for the create post endpoint"
"Write mocks for PostPost API responses"

// __mocks__/postpost.ts
// Use with Cursor-generated tests

export const mockConnections = [
  {
    platformId: 'twitter-123456789',
    platform: 'twitter',
    username: '@testuser',
    displayName: 'Test User',
  },
  {
    platformId: 'linkedin-ABC123DEF',
    platform: 'linkedin',
    username: 'Test User',
    displayName: 'Test User',
  },
];

export const mockCreatePostResponse = {
  success: true,
  postGroupId: 'pg_test123',
  posts: [
    { platform: 'twitter', platformId: 'twitter-123456789', status: 'scheduled' },
    { platform: 'linkedin', platformId: 'linkedin-ABC123DEF', status: 'scheduled' },
  ],
};

export const mockPostGroup = {
  postGroupId: 'pg_test123',
  content: 'Test post content',
  status: 'published',
  posts: [
    {
      platform: 'twitter',
      status: 'published',
      publishedUrl: 'https://twitter.com/testuser/status/123',
    },
    {
      platform: 'linkedin',
      status: 'published',
      publishedUrl: 'https://linkedin.com/post/123',
    },
  ],
};

export const mockLinkedInStats = {
  success: true,
  metrics: {
    IMPRESSION: 1250,
    MEMBERS_REACHED: 680,
    RESHARE: 3,
    REACTION: 28,
    COMMENT: 5,
  },
  cached: false,
};