RankFlow AI — Backend API Test Specification

Version: 1.0.0
Date: 2026-06-13
Scope: All 14 tRPC routers (auth, practice, location, gbp, social, content, citation, site, report, lead, billing, skill, admin)
Format: Follows docs/test-plan.md Section 3 — Success Criteria Template

---

1. Test Data Factories#

1.1 Core Factories#

// src/__tests__/factories/user.ts
import { faker } from "@faker-js/faker";

export const createMockUser = (overrides?: Partial<User>) => ({
  id: `usr_${faker.string.nanoid(8)}`,
  email: faker.internet.email(),
  name: faker.person.fullName(),
  image: faker.image.avatar(),
  role: "USER",
  emailVerified: new Date(),
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockSession = (overrides?: Partial<Session>) => ({
  id: `sess_${faker.string.nanoid(8)}`,
  token: faker.string.uuid(),
  userId: `usr_${faker.string.nanoid(8)}`,
  expiresAt: new Date(Date.now() + 86400000),
  ipAddress: faker.internet.ip(),
  userAgent: faker.internet.userAgent(),
  ...overrides,
});

// src/__tests__/factories/practice.ts
export const createMockPractice = (overrides?: Partial<Practice>) => ({
  id: `prac_${faker.string.nanoid(8)}`,
  name: faker.company.name(),
  type: faker.helpers.arrayElement([
    "CLINIC", "HOSPITAL", "DIAGNOSTIC_CENTER", "DENTAL_CLINIC",
    "PHYSIOTHERAPY", "AYURVEDIC_CENTER", "HOMEOPATHY_CLINIC",
    "CA", "LAWYER", "WEDDING_PHOTOGRAPHER",
  ]),
  slug: faker.internet.domainWord(),
  logoUrl: faker.image.url(),
  primaryColor: "#3B82F6",
  settings: {},
  status: "ACTIVE",
  tier: "STANDARD",
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockPracticeMember = (overrides?: Partial<PracticeMember>) => ({
  id: `pm_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  userId: `usr_${faker.string.nanoid(8)}`,
  role: faker.helpers.arrayElement(["OWNER", "ADMIN", "EDITOR", "VIEWER"]),
  joinedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/location.ts
export const createMockLocation = (overrides?: Partial<Location>) => ({
  id: `loc_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  name: faker.location.streetAddress(),
  businessName: faker.company.name(),
  address: faker.location.streetAddress(),
  city: faker.location.city(),
  state: faker.location.state(),
  postalCode: faker.location.zipCode(),
  country: "IN",
  phone: faker.string.numeric(10),
  phoneSecondary: faker.string.numeric(10),
  email: faker.internet.email(),
  website: faker.internet.url(),
  category: "Medical Clinic",
  services: ["General Checkup", "Vaccination"],
  businessHours: { monday: "9:00-18:00" },
  targetKeywords: ["doctor near me", "best clinic"],
  serviceAreas: [faker.location.city()],
  languages: ["English", "Hindi"],
  latitude: faker.location.latitude(),
  longitude: faker.location.longitude(),
  isPrimary: false,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/content.ts
export const createMockContentPiece = (overrides?: Partial<ContentPiece>) => ({
  id: `cnt_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  locationId: `loc_${faker.string.nanoid(8)}`,
  taskType: "GBP_POST",
  title: faker.lorem.sentence(),
  content: faker.lorem.paragraphs(3),
  seoTitle: faker.lorem.sentence(5),
  seoDescription: faker.lorem.sentence(10),
  focusKeywords: ["keyword1", "keyword2"],
  status: faker.helpers.arrayElement(["DRAFT", "PENDING", "APPROVED", "REJECTED", "PUBLISHED"]),
  model: "claude-sonnet",
  costUsd: 0.002,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/gbp.ts
export const createMockGbpPost = (overrides?: Partial<GbpPost>) => ({
  id: `gbp_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  locationId: `loc_${faker.string.nanoid(8)}`,
  content: faker.lorem.paragraph(),
  mediaUrls: [faker.image.url()],
  ctaType: "BOOK",
  topicType: "STANDARD",
  status: "PUBLISHED",
  gbpPostId: faker.string.uuid(),
  scheduledFor: null,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockGbpAccount = (overrides?: Partial<GbpAccount>) => ({
  id: `gba_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  googleAccountId: faker.string.uuid(),
  email: faker.internet.email(),
  accessToken: faker.string.alphanumeric(100),
  refreshToken: faker.string.alphanumeric(100),
  expiresAt: new Date(Date.now() + 3600000),
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/social.ts
export const createMockSocialAccount = (overrides?: Partial<SocialAccount>) => ({
  id: `soc_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  platform: faker.helpers.arrayElement(["FACEBOOK", "INSTAGRAM", "LINKEDIN", "TWITTER"]),
  accountName: faker.internet.userName(),
  accountId: faker.string.uuid(),
  accessToken: faker.string.alphanumeric(100),
  refreshToken: faker.string.alphanumeric(100),
  expiresAt: new Date(Date.now() + 3600000),
  isActive: true,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockSocialPost = (overrides?: Partial<SocialPost>) => ({
  id: `sp_${faker.string.nanoid(8)}`,
  socialAccountId: `soc_${faker.string.nanoid(8)}`,
  content: faker.lorem.paragraph(),
  mediaUrls: [faker.image.url()],
  mediaType: "IMAGE",
  hashtags: ["#health", "#wellness"],
  linkUrl: faker.internet.url(),
  status: "SCHEDULED",
  scheduledFor: new Date(Date.now() + 3600000),
  publishedAt: null,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/citation.ts
export const createMockCitation = (overrides?: Partial<Citation>) => ({
  id: `cit_${faker.string.nanoid(8)}`,
  locationId: `loc_${faker.string.nanoid(8)}`,
  directoryName: faker.helpers.arrayElement(["justdial", "practo", "lybrate", "google"]),
  url: faker.internet.url(),
  status: faker.helpers.arrayElement(["PENDING", "SUBMITTED", "VERIFIED", "ERROR"]),
  napMatch: null,
  lastVerifiedAt: null,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockCitationDirectory = (overrides?: Partial<CitationDirectory>) => ({
  id: `cd_${faker.string.nanoid(8)}`,
  name: faker.helpers.arrayElement(["justdial", "practo", "lybrate", "google", "facebook", "yellowpages"]),
  category: "medical",
  domainAuthority: faker.number.int({ min: 20, max: 90 }),
  isFree: faker.datatype.boolean(),
  requiresPhoneVerification: faker.datatype.boolean(),
  createdAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/lead.ts
export const createMockLead = (overrides?: Partial<Lead>) => ({
  id: `ld_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  locationId: `loc_${faker.string.nanoid(8)}`,
  name: faker.person.fullName(),
  email: faker.internet.email(),
  phone: faker.string.numeric(10),
  source: faker.helpers.arrayElement(["GBP", "WEBSITE", "SOCIAL", "REFERRAL"]),
  status: faker.helpers.arrayElement(["NEW", "CONTACTED", "CONVERTED", "LOST"]),
  message: faker.lorem.sentence(),
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/billing.ts
export const createMockInvoice = (overrides?: Partial<Invoice>) => ({
  id: `inv_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  amount: faker.number.int({ min: 1000, max: 50000 }),
  currency: "INR",
  status: faker.helpers.arrayElement(["PENDING", "PAID", "OVERDUE", "REFUNDED"]),
  stripeInvoiceId: faker.string.uuid(),
  periodStart: new Date(),
  periodEnd: new Date(Date.now() + 2592000000),
  paidAt: null,
  createdAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/report.ts
export const createMockReport = (overrides?: Partial<Report>) => ({
  id: `rep_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  type: "MONTHLY",
  periodStart: new Date(Date.now() - 2592000000),
  periodEnd: new Date(),
  status: faker.helpers.arrayElement(["PENDING", "GENERATING", "READY", "FAILED"]),
  pdfUrl: null,
  data: {},
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

// src/__tests__/factories/admin.ts
export const createMockJob = (overrides?: Partial<Job>) => ({
  id: `job_${faker.string.nanoid(8)}`,
  practiceId: `prac_${faker.string.nanoid(8)}`,
  type: faker.helpers.arrayElement(["CONTENT_GENERATE", "CITATION_SUBMIT", "REPORT_GENERATE", "SITE_PUBLISH"]),
  status: faker.helpers.arrayElement(["PENDING", "RUNNING", "COMPLETED", "FAILED", "RETRYING"]),
  payload: {},
  result: null,
  error: null,
  attempts: 0,
  maxAttempts: 3,
  scheduledFor: new Date(),
  startedAt: null,
  completedAt: null,
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

export const createMockPromptTemplate = (overrides?: Partial<PromptTemplate>) => ({
  id: `pt_${faker.string.nanoid(8)}`,
  taskType: "GBP_POST",
  systemPrompt: faker.lorem.paragraphs(2),
  userPromptTemplate: faker.lorem.paragraphs(3),
  modelConfig: {
    provider: "anthropic",
    model: "claude-sonnet-4",
    temperature: 0.7,
    maxTokens: 2000,
  },
  createdAt: new Date(),
  updatedAt: new Date(),
  ...overrides,
});

---

2. Auth Router#

Spec Reference: docs/specs/backend-api.md Section 2
File: src/server/api/routers/auth.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• auth.me returns full user object for authenticated requests
• auth.me returns 401 for unauthenticated requests
• auth.updateProfile validates name length (1-100 chars) and image URL format
• auth.updateProfile persists changes to database
• auth.changePassword requires current password match
• auth.changePassword enforces new password length (8-100 chars)
• auth.changePassword hashes new password before storage
• auth.listSessions returns only sessions belonging to current user
• auth.revokeSession deletes target session from database
• auth.revokeSession prevents revoking the currently active session

Agent Context (Pre-conditions)#

• Required DB state: User table with at least 1 user, Session table with 3+ sessions for that user
• Required env vars: BETTER_AUTH_SECRET configured
• Required external mocks: None (pure internal auth)

Verification Commands#

# Run unit tests for auth schemas
pnpm test:unit -- src/__tests__/unit/schemas/auth.test.ts

# Run integration tests for auth router
pnpm test:integration -- src/__tests__/integration/routers/auth.test.ts

# Run auth E2E flow
pnpm test:e2e -- e2e/auth/profile.spec.ts

---

3. Practice Router#

Spec Reference: docs/specs/backend-api.md Section 3
File: src/server/api/routers/practice.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• practice.create enforces name length (2-100 chars) and valid type enum
• practice.create auto-generates slug if not provided
• practice.create validates slug format ^[a-z0-9-]+$
• practice.create returns CONFLICT on duplicate slug
• practice.create sets creator as OWNER in PracticeMember
• practice.get returns 404 for non-existent practice ID
• practice.get returns 403 for non-member users
• practice.update validates hex color format ^#[0-9A-Fa-f]{6}$
• practice.update validates logoUrl as URL
• practice.delete requires OWNER role
• practice.delete cascades or handles related locations/content
• practice.list returns only practices where user is a member
• practice.inviteMember generates valid invite URL with token
• practice.inviteMember sends email via Resend mock
• practice.removeMember prevents removing the OWNER
• practice.updateMemberRole accepts only valid roles (OWNER, ADMIN, EDITOR, VIEWER)
• practice.updateMemberRole prevents changing OWNER role

Agent Context (Pre-conditions)#

• Required DB state: User table with 2+ users, Practice table with 1+ practice, PracticeMember table with role mappings
• Required env vars: RESEND_API_KEY (for invite email mock)
• Required external mocks: Resend API mock (200 OK + messageId)

Verification Commands#

# Run unit tests for practice schemas
pnpm test:unit -- src/__tests__/unit/schemas/practice.test.ts

# Run integration tests for practice router
pnpm test:integration -- src/__tests__/integration/routers/practice.test.ts

# Run practice onboarding E2E
pnpm test:e2e -- e2e/practice/onboarding.spec.ts

---

4. Location Router#

Spec Reference: docs/specs/backend-api.md Section 4
File: src/server/api/routers/location.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• location.create validates address minimum 5 characters
• location.create validates phone as 10-15 characters
• location.create validates email format when provided
• location.create validates directory profile URL format when provided
• location.create defaults country to "IN"
• location.create defaults languages to ["English", "Hindi"]
• location.create defaults services to []
• location.create associates location with caller's practice context
• location.get returns 404 for non-existent location ID
• location.get returns 403 for location outside caller's practice
• location.update allows partial updates (all fields optional)
• location.delete removes location from database
• location.list returns only locations in caller's practice
• location.setPrimary sets isPrimary = true on target location
• location.setPrimary unsets isPrimary on all other locations in same practice
• location.setPrimary returns updated location with isPrimary = true

Agent Context (Pre-conditions)#

• Required DB state: Practice with 1+ member, Location table with 2+ locations for that practice
• Required env vars: None
• Required external mocks: None

Verification Commands#

# Run unit tests for location schemas
pnpm test:unit -- src/__tests__/unit/schemas/location.test.ts

# Run integration tests for location router
pnpm test:integration -- src/__tests__/integration/routers/location.test.ts

# Run location CRUD E2E
pnpm test:e2e -- e2e/location/crud.spec.ts

---

5. GBP Router#

Spec Reference: docs/specs/backend-api.md Section 5
File: src/server/api/routers/gbp.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• gbp.getAuthUrl returns valid Google OAuth authorization URL
• gbp.getAuthUrl includes required GBP API scopes
• gbp.listAccounts returns only accounts linked to caller's practice
• gbp.listLocations calls GBP API with stored access token
• gbp.listLocations refreshes token if expired
• gbp.createPost validates content max 1500 characters
• gbp.createPost validates max 10 media URLs
• gbp.createPost validates each media URL format
• gbp.createPost validates ctaType against allowed enum values
• gbp.createPost persists post to database before calling GBP API
• gbp.createPost calls GBP API with correct location ID and payload
• gbp.listPosts supports filtering by locationId and status
• gbp.deletePost removes post from DB and GBP API
• gbp.listReviews returns reviews from GBP API for practice locations
• gbp.replyToReview validates reply text (1-2000 chars)
• gbp.replyToReview with generateAI: true calls AI service before posting
• gbp.getInsights returns GBP insights for date range
• gbp.listQA returns Q&A for specified location
• gbp.answerQuestion posts answer to GBP and persists locally
• gbp.uploadPhoto uploads to GBP and stores reference URL

Agent Context (Pre-conditions)#

• Required DB state: Practice with GBP account connection, GbpAccount with valid tokens
• Required env vars: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GBP_API_KEY
• Required external mocks: GBP API mock (locations, posts, reviews, insights, Q&A, photos), Google OAuth mock, AI service mock for generateAI

Verification Commands#

# Run unit tests for GBP schemas
pnpm test:unit -- src/__tests__/unit/schemas/gbp.test.ts

# Run integration tests for GBP router
pnpm test:integration -- src/__tests__/integration/routers/gbp.test.ts

# Run GBP connect-and-post E2E
pnpm test:e2e -- e2e/gbp/connect-and-post.spec.ts

---

6. Social Router#

Spec Reference: docs/specs/backend-api.md Section 6
File: src/server/api/routers/social.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• social.getAuthUrl returns valid OAuth URL for requested platform
• social.getAuthUrl supports FACEBOOK, INSTAGRAM, LINKEDIN, TWITTER
• social.listAccounts returns only accounts for caller's practice
• social.disconnect revokes tokens and marks account inactive
• social.createPost validates content (1-5000 chars)
• social.createPost validates max 10 media URLs
• social.createPost validates mediaType against allowed enum
• social.createPost validates linkUrl as URL when provided
• social.listPosts supports filtering by accountId and status
• social.deletePost removes post from DB and platform API
• social.schedulePosts validates each post has valid platform enum
• social.schedulePosts validates each post has valid datetime
• social.schedulePosts creates posts with status: "SCHEDULED"
• social.schedulePosts queues BullMQ job for each scheduled post
• social.schedulePosts returns array of scheduled IDs

Agent Context (Pre-conditions)#

• Required DB state: Practice with SocialAccount records for 1+ platforms
• Required env vars: FACEBOOK_APP_ID, INSTAGRAM_APP_ID, LINKEDIN_CLIENT_ID, TWITTER_CLIENT_ID
• Required external mocks: Platform OAuth mocks (Facebook, Instagram, LinkedIn, Twitter), Platform API mocks for post creation/deletion

Verification Commands#

# Run unit tests for social schemas
pnpm test:unit -- src/__tests__/unit/schemas/social.test.ts

# Run integration tests for social router
pnpm test:integration -- src/__tests__/integration/routers/social.test.ts

# Run social connect-and-schedule E2E
pnpm test:e2e -- e2e/social/connect-and-schedule.spec.ts

---

7. Content Router#

Spec Reference: docs/specs/backend-api.md Section 7
File: src/server/api/routers/content.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• content.generate validates taskType against 10 allowed enum values
• content.generate validates model against 4 allowed enum values (claude-sonnet, claude-haiku, gpt-4o, gpt-4o-mini)
• content.generate defaults variables to {}
• content.generate calls AI service with correct prompt template for taskType
• content.generate persists ContentPiece with cost tracking
• content.generate rate limit: 5 per minute
• content.list supports filtering by status and type
• content.list returns only content for caller's practice
• content.get returns 404 for non-existent content ID
• content.get returns 403 for content outside caller's practice
• content.update allows partial updates (title, content, seoTitle, seoDescription, focusKeywords)
• content.approve changes status from PENDING → APPROVED
• content.approve triggers publish if auto-publish configured
• content.reject changes status from PENDING → REJECTED
• content.reject stores optional reason
• content.delete prevents deleting PUBLISHED content without unpublish
• content.delete removes content from database

Agent Context (Pre-conditions)#

• Required DB state: Practice with ContentPiece records, PromptTemplate for each taskType
• Required env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY
• Required external mocks: Claude API mock, GPT-4o API mock

Verification Commands#

# Run unit tests for content schemas
pnpm test:unit -- src/__tests__/unit/schemas/content.test.ts

# Run integration tests for content router
pnpm test:integration -- src/__tests__/integration/routers/content.test.ts

# Run content generate-and-approve E2E
pnpm test:e2e -- e2e/content/generate-and-approve.spec.ts

---

8. Citation Router#

Spec Reference: docs/specs/backend-api.md Section 8
File: src/server/api/routers/citation.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• citation.listDirectories returns all available citation directories
• citation.list returns citations for specified location only
• citation.list returns 403 for location outside caller's practice
• citation.submit validates at least 1 directory name
• citation.submit validates max 50 directory names
• citation.submit creates BullMQ job for each directory submission
• citation.submit returns jobId for tracking
• citation.submit handles invalid directory names gracefully
• citation.verifyNap creates NAP verification job
• citation.verifyNap updates citation status to VERIFIED on success
• citation.delete creates deletion job
• citation.delete marks citation as pending deletion
• citation.getSnapshot returns full citation with NAP snapshot data
• citation.getSnapshot returns 404 for non-existent citation ID

Agent Context (Pre-conditions)#

• Required DB state: Practice with Location, CitationDirectory seed data, Citation records
• Required env vars: FIRECRAWL_API_KEY (for NAP verification mock)
• Required external mocks: Firecrawl API mock (NAP matching), Directory submission API mocks (Justdial, Practo, etc.)

Verification Commands#

# Run unit tests for citation schemas
pnpm test:unit -- src/__tests__/unit/schemas/citation.test.ts

# Run integration tests for citation router
pnpm test:integration -- src/__tests__/integration/routers/citation.test.ts

# Run citation submit-and-verify E2E
pnpm test:e2e -- e2e/citation/submit-and-verify.spec.ts

---

9. DirectoryProfile Router#

Spec Reference: docs/specs/backend-api.md Section 9
File: src/server/api/routers/directory-profile.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• directoryProfile.get returns practice data plus all 12 profile sections
• directoryProfile.updateSection validates sectionKey against 12 allowed enum values
• directoryProfile.updateSection validates content max 50000 characters
• directoryProfile.updateSection validates max 20 media URLs
• directoryProfile.updateSection validates each media URL format
• directoryProfile.setVisibility toggles isVisible boolean on section
• directoryProfile.reorderSections validates all 12 section keys are present
• directoryProfile.reorderSections validates no duplicate section keys
• directoryProfile.reorderSections updates order index in database
• directoryProfile.setTemplate validates templateId against 5 allowed templates
• directoryProfile.publish generates static site or deploys to CDN
• directoryProfile.publish returns accessible public URL
• directoryProfile.publish includes directorySlug if no directory profile URL set
• directoryProfile.unpublish removes site from public access
• directoryProfile.setDirectoryUrl returns required directory profile paths (A, directory path)
• directoryProfile.setDirectoryUrl validates domain format
• directoryProfile.regenerate creates AI content generation job
• directoryProfile.regenerate returns jobId for tracking

Agent Context (Pre-conditions)#

• Required DB state: Practice with DirectoryProfileSection records for all 12 sections, DirectoryProfileTemplate seed data
• Required env vars: VERCEL_TOKEN or NETLIFY_TOKEN (for deploy mock), ANTHROPIC_API_KEY (for regeneration)
• Required external mocks: Vercel/Netlify deploy API mock, AI service mock for regeneration

Verification Commands#

# Run unit tests for site schemas
pnpm test:unit -- src/__tests__/unit/schemas/site.test.ts

# Run integration tests for site router
pnpm test:integration -- src/__tests__/integration/routers/directory-profile.test.ts

# Run site build-and-publish E2E
pnpm test:e2e -- e2e/profile/profile-publish.spec.ts

---

10. Report Router#

Spec Reference: docs/specs/backend-api.md Section 10
File: src/server/api/routers/report.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• report.list returns only reports for caller's practice
• report.get returns 404 for non-existent report ID
• report.get returns 403 for report outside caller's practice
• report.generate validates periodStart and periodEnd as valid ISO datetimes
• report.generate validates periodEnd is after periodStart
• report.generate creates report generation job (BullMQ)
• report.generate returns jobId for tracking
• report.downloadPdf returns accessible URL for ready reports
• report.downloadPdf returns error for reports not in READY status
• report.email validates at least 1 recipient
• report.email validates max 10 recipients
• report.email validates each recipient as email format
• report.email sends report PDF via Resend
• report.email returns { success: true } on send success
• report.email handles Resend failure gracefully

Agent Context (Pre-conditions)#

• Required DB state: Practice with Report records, Job records for report generation
• Required env vars: RESEND_API_KEY, PDF_GENERATION_SERVICE_URL
• Required external mocks: Resend API mock, PDF generation service mock, BullMQ job processor mock

Verification Commands#

# Run unit tests for report schemas
pnpm test:unit -- src/__tests__/unit/schemas/report.test.ts

# Run integration tests for report router
pnpm test:integration -- src/__tests__/integration/routers/report.test.ts

# Run report generate-and-download E2E
pnpm test:e2e -- e2e/report/generate-and-download.spec.ts

---

11. Lead Router#

Spec Reference: docs/specs/backend-api.md Section 11
File: src/server/api/routers/lead.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• lead.list returns all leads for caller's practice
• lead.list supports filtering by status (NEW, CONTACTED, CONVERTED, LOST)
• lead.get returns 404 for non-existent lead ID
• lead.get returns 403 for lead outside caller's practice
• lead.updateStatus validates status against 4 allowed enum values
• lead.updateStatus persists status change to database
• lead.updateStatus returns updated lead object
• lead.delete removes lead from database
• lead.delete returns 404 for non-existent lead
• lead.delete returns 403 for lead outside caller's practice

Agent Context (Pre-conditions)#

• Required DB state: Practice with Lead records (4+ leads with mixed statuses)
• Required env vars: None
• Required external mocks: None

Verification Commands#

# Run unit tests for lead schemas
pnpm test:unit -- src/__tests__/unit/schemas/lead.test.ts

# Run integration tests for lead router
pnpm test:integration -- src/__tests__/integration/routers/lead.test.ts

# Run lead manage-pipeline E2E
pnpm test:e2e -- e2e/lead/manage-pipeline.spec.ts

---

12. Billing Router#

Spec Reference: docs/specs/backend-api.md Section 12
File: src/server/api/routers/billing.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• billing.getPlan returns current tier and feature list for practice
• billing.getPlan returns trial information when in trial period
• billing.createSubscription validates plan against 4 enum values (STARTER, STANDARD, PREMIUM, ENTERPRISE)
• billing.createSubscription validates payment method as "stripe" or "razorpay"
• billing.createSubscription creates subscription with correct payment provider
• billing.createSubscription returns clientSecret for frontend confirmation
• billing.createSubscription handles card declined error from Stripe
• billing.createSubscription handles Razorpay payment failure
• billing.cancel sets subscription status to cancelled
• billing.cancel returns effective cancellation date
• billing.cancel handles already-cancelled subscription gracefully
• billing.listInvoices returns invoices for caller's practice only
• billing.getInvoice returns 404 for non-existent invoice
• billing.updatePaymentMethod updates payment method with provider
• billing.updatePaymentMethod returns { success: true } on success
• billing.updatePaymentMethod handles invalid payment method ID

Agent Context (Pre-conditions)#

• Required DB state: Practice with Billing record, Invoice records (3+), Subscription record
• Required env vars: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET
• Required external mocks: Stripe API mock (subscriptions, payment methods, invoices), Razorpay API mock

Verification Commands#

# Run unit tests for billing schemas
pnpm test:unit -- src/__tests__/unit/schemas/billing.test.ts

# Run integration tests for billing router
pnpm test:integration -- src/__tests__/integration/routers/billing.test.ts

# Run billing subscribe-and-cancel E2E
pnpm test:e2e -- e2e/billing/subscribe-and-cancel.spec.ts

---

13. Skill Router#

Spec Reference: docs/specs/backend-api.md Section 13
File: src/server/api/routers/skill.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• skill.list requires authentication (protectedProcedure)
• skill.list returns skill summaries for all available skills
• skill.get returns full skill definition including parameters
• skill.get returns 404 for non-existent skill ID
• skill.execute validates skillId exists
• skill.execute defaults payload to {}
• skill.execute defaults async to false
• skill.execute synchronous mode returns ExecutionResult immediately
• skill.execute async mode returns ExecutionResult with status "QUEUED" and jobId
• skill.execute rate limit: 10 per minute
• skill.execute requires practiceProcedure (practice context + CLIENT+ role)
• skill.executeAdmin requires adminProcedure (ADMIN role only)
• skill.executeAdmin validates practiceId exists
• skill.executeAdmin executes skill on behalf of specified practice
• skill.getStatus returns current execution status for jobId
• skill.getStatus returns full result data when job is complete
• skill.getStatus returns 404 for non-existent jobId
• skill.getStatus requires protectedProcedure (any authenticated user)

Agent Context (Pre-conditions)#

• Required DB state: Skill table with 5+ skill definitions, Job table with job records
• Required env vars: SKILL_EXECUTION_TIMEOUT_MS (default: 30000)
• Required external mocks: Skill execution engine mock (Composio or internal)

Verification Commands#

# Run unit tests for skill schemas
pnpm test:unit -- src/__tests__/unit/schemas/skill.test.ts

# Run integration tests for skill router
pnpm test:integration -- src/__tests__/integration/routers/skill.test.ts

# Run skill execute-and-check E2E
pnpm test:e2e -- e2e/skill/execute-and-check.spec.ts

---

14. Admin Router#

Spec Reference: docs/specs/backend-api.md Section 14
File: src/server/api/routers/admin.ts

Test Plan & Verification#

Unit Tests#

Integration Tests#

E2E Tests#

Success Criteria (Binary)#

• admin.getKPIs requires adminProcedure (ADMIN role only)
• admin.getKPIs returns aggregate counts (practices, jobs, revenue, active users)
• admin.listClients supports filtering by status (TRIAL, ACTIVE, PAST_DUE, SUSPENDED, CANCELLED, EXPIRED)
• admin.listClients supports filtering by tier (STARTER, STANDARD, PREMIUM, ENTERPRISE)
• admin.getClient returns practice with all relations (locations, members, content, jobs)
• admin.getClient returns 404 for non-existent practice ID
• admin.updateClient validates status against 6 enum values
• admin.updateClient validates tier against 4 enum values
• admin.updateClient validates trialEndsAt and subscriptionEndsAt as ISO datetime
• admin.updateClient persists changes to database
• admin.listJobs supports filtering by status and practiceId
• admin.retryJob resets FAILED job to PENDING status
• admin.retryJob resets attempt count
• admin.retryJob returns error for non-FAILED jobs
• admin.listDomains returns all directory profile URL registrations with profile status
• admin.listSocialConnections returns all social accounts across all practices
• admin.listContent supports filtering by status
• admin.approveContent changes content status to APPROVED
• admin.updatePrompt validates systemPrompt max 10000 chars
• admin.updatePrompt validates userPromptTemplate max 20000 chars
• admin.updatePrompt validates modelConfig.provider as "anthropic" or "openai"
• admin.updatePrompt validates modelConfig.temperature range 0-2
• admin.updatePrompt validates modelConfig.maxTokens range 100-8000
• admin.getRevenue returns revenue data for requested period
• admin.getSystemHealth checks DB, Redis, external APIs
• admin.getSystemHealth returns "healthy" when all checks pass
• admin.getSystemHealth returns "degraded" when any check fails

Agent Context (Pre-conditions)#

• Required DB state: Practice (10+ records), Job (20+ records), ContentPiece (50+), SocialAccount (5+), PromptTemplate (5+), Domain (3+), User with ADMIN role
• Required env vars: All service health check endpoints configured
• Required external mocks: None for admin router (internal aggregation)

Verification Commands#

# Run unit tests for admin schemas
pnpm test:unit -- src/__tests__/unit/schemas/admin.test.ts

# Run integration tests for admin router
pnpm test:integration -- src/__tests__/integration/routers/admin.test.ts

# Run admin dashboard E2E
pnpm test:e2e -- e2e/admin/dashboard.spec.ts

---

15. Procedure & Auth Tests#

Spec Reference: docs/specs/backend-api.md Section 15 — Middleware & Procedures

Test Plan & Verification#

Unit Tests#

Integration Tests#

Success Criteria (Binary)#

• publicProcedure allows requests without authentication
• protectedProcedure rejects unauthenticated requests with 401
• protectedProcedure allows authenticated requests with valid session
• practiceProcedure rejects requests without practice context (400)
• practiceProcedure rejects non-member users (403)
• practiceProcedure allows any practice member (VIEWER, EDITOR, ADMIN, OWNER)
• practiceProcedure owner-only operations reject non-OWNER members (403)
• adminProcedure rejects non-admin users (403)
• adminProcedure allows users with role = ADMIN
• requestId is injected on every request as x-request-id header
• requestId propagates to audit logs
• requestId propagates to external API calls as X-RankFlow-Request-ID
• ctx.db is available in all procedures and is a valid Prisma client
• ctx.redis is available in all procedures and is a valid Redis client
• ctx.session is populated for authenticated requests
• ctx.session is null for unauthenticated requests on public endpoints
• Zod errors are formatted with fieldErrors and formErrors structure
• Zod errors are included in tRPC response data.zodError
• Middleware executes in correct order: Rate Limit → Request ID → Auth → Practice Resolve → Role Check
• Role check middleware reads role from PracticeMember table, not User.role
• Practice resolution middleware extracts practiceId from input or headers

Agent Context (Pre-conditions)#

• Required DB state: User (regular + admin), Practice with PracticeMember records for all roles
• Required env vars: BETTER_AUTH_SECRET, REDIS_URL, DATABASE_URL
• Required external mocks: None (internal middleware)

Verification Commands#

# Run procedure unit tests
pnpm test:unit -- src/__tests__/unit/trpc/procedures.test.ts

# Run procedure integration tests
pnpm test:integration -- src/__tests__/integration/trpc/procedures.test.ts

# Run all auth/procedure tests
pnpm test:unit -- src/__tests__/unit/trpc/

---

16. Rate Limiting Tests#

Spec Reference: docs/specs/backend-api.md Section 15 — Rate Limiting

Test Plan & Verification#

Unit Tests#

Integration Tests#

Success Criteria (Binary)#

• skill.execute rate limit: 10 requests per minute per user
• content.generate rate limit: 5 requests per minute per user
• gbp.createPost rate limit: 30 requests per minute per user
• social.createPost rate limit: 30 requests per minute per user
• All other routes rate limit: 100 requests per minute per user
• Rate limit uses Redis for distributed counting
• Rate limit key includes user ID (or IP for anonymous) and route name
• Rate limit windows are sliding (60 seconds from first request in window)
• Rate limit returns 429 with Retry-After header when exceeded
• Rate limit counters reset after window expires
• Rate limits are isolated per user (User A limit does not affect User B)
• Rate limits are isolated per route (route A limit does not affect route B)
• Anonymous requests use IP address as rate limit identifier
• Rate limit middleware runs before auth middleware in the chain
• Rate limit response includes tRPC error code TOO_MANY_REQUESTS

Agent Context (Pre-conditions)#

• Required DB state: User (2+ users for isolation tests)
• Required env vars: REDIS_URL, RATE_LIMIT_ENABLED=true
• Required external mocks: Redis instance (test container or mock)

Verification Commands#

# Run rate limiting unit tests
pnpm test:unit -- src/__tests__/unit/rate-limit.test.ts

# Run rate limiting integration tests
pnpm test:integration -- src/__tests__/integration/rate-limit.test.ts

# Run rate limit stress test
pnpm test:integration -- src/__tests__/integration/rate-limit.test.ts --grep "stress"

---

17. Global Verification Commands#

Run All Backend API Tests#

# 1. Run all unit tests (schemas, utilities, procedures)
pnpm test:unit

# 2. Run all integration tests (routers, DB, middleware)
pnpm test:integration

# 3. Run all contract tests (external API mocks)
pnpm test:contract

# 4. Run all E2E tests (critical flows)
pnpm test:e2e

# 5. Run router-specific integration tests
pnpm test:integration -- src/__tests__/integration/routers/auth.test.ts
pnpm test:integration -- src/__tests__/integration/routers/practice.test.ts
pnpm test:integration -- src/__tests__/integration/routers/location.test.ts
pnpm test:integration -- src/__tests__/integration/routers/gbp.test.ts
pnpm test:integration -- src/__tests__/integration/routers/social.test.ts
pnpm test:integration -- src/__tests__/integration/routers/content.test.ts
pnpm test:integration -- src/__tests__/integration/routers/citation.test.ts
pnpm test:integration -- src/__tests__/integration/routers/directory-profile.test.ts
pnpm test:integration -- src/__tests__/integration/routers/report.test.ts
pnpm test:integration -- src/__tests__/integration/routers/lead.test.ts
pnpm test:integration -- src/__tests__/integration/routers/billing.test.ts
pnpm test:integration -- src/__tests__/integration/routers/skill.test.ts
pnpm test:integration -- src/__tests__/integration/routers/admin.test.ts

# 6. Run all schema unit tests
pnpm test:unit -- src/__tests__/unit/schemas/

# 7. Run procedure and middleware tests
pnpm test:unit -- src/__tests__/unit/trpc/
pnpm test:integration -- src/__tests__/integration/trpc/

# 8. Run rate limiting tests
pnpm test:integration -- src/__tests__/integration/rate-limit.test.ts

# 9. Full backend API test suite
pnpm test -- src/__tests__/unit/schemas/ src/__tests__/unit/trpc/ src/__tests__/integration/routers/ src/__tests__/integration/trpc/ src/__tests__/integration/rate-limit.test.ts

Coverage Requirements#

---

End of Backend API Test Specification — RankFlow AI v1.0.0