API Clients Documentation

Executive Summary

In brief: How systems integrate with the portal API.

Why it matters: Transparency for future integration costs.

Cost: Only when building integrations.

Status: Reference doc.

Decision needed: None — developer reference

Executive Overview — all summaries for decision-makers.

Overview

The MQA Governance Portal provides pre-built API clients for all AI services. These clients handle SSE streaming, error handling, and type safety.

Available Clients

1. Donor & Grant Management Client

import { aiDonorClient } from '@/lib/api/ai-donor-client';

// Generate donor proposal
const proposal = await aiDonorClient.generateProposal(
  donorId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate grant application
const application = await aiDonorClient.generateGrantApplication(
  donorId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate donor report
const report = await aiDonorClient.generateReport(
  donorId,
  reportType,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Check donor compliance
const compliance = await aiDonorClient.checkCompliance(
  donorId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

2. Audit & Compliance Client

import { aiAuditClient } from '@/lib/api/ai-audit-client';

// Generate audit plan
const plan = await aiAuditClient.generatePlan(
  projectId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Analyze finding
const analysis = await aiAuditClient.analyzeFinding(
  findingId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Plan remediation
const remediation = await aiAuditClient.planRemediation(
  findingId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Analyze compliance gaps
const gaps = await aiAuditClient.analyzeGaps(
  projectId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

3. Vendor & Procurement Client

import { aiVendorClient } from '@/lib/api/ai-vendor-client';

// Evaluate vendor
const evaluation = await aiVendorClient.evaluateVendor(
  vendorId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Compare bids
const comparison = await aiVendorClient.compareBids(
  tenderIds,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate material requirements
const requirements = await aiVendorClient.generateMaterialRequirements(
  projectId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate procurement plan
const plan = await aiVendorClient.generateProcurementPlan(
  projectId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

4. Subcontractor & Quality Client

import { aiSubcontractorClient } from '@/lib/api/ai-subcontractor-client';

// Evaluate subcontractor
const evaluation = await aiSubcontractorClient.evaluateSubcontractor(
  subcontractorId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate quality plan
const plan = await aiSubcontractorClient.generateQualityPlan(
  projectId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate inspection report
const report = await aiSubcontractorClient.generateInspectionReport(
  inspectionId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Analyze non-conformance
const analysis = await aiSubcontractorClient.analyzeNonConformance(
  nonConformanceId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

5. ISO Certification Client

import { aiCertificationClient } from '@/lib/api/ai-certification-client';

// Analyze certification gaps
const gaps = await aiCertificationClient.analyzeGaps(
  certificationId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate certification roadmap
const roadmap = await aiCertificationClient.generateRoadmap(
  certificationId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Prepare for audit
const preparation = await aiCertificationClient.prepareAudit(
  certificationId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

6. Legal Entity Client

import { aiLegalEntityClient } from '@/lib/api/ai-legal-entity-client';

// Check entity compliance
const compliance = await aiLegalEntityClient.checkCompliance(
  entityId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Generate registration document
const document = await aiLegalEntityClient.generateRegistrationDocument(
  entityId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Optimize entity structure
const optimization = await aiLegalEntityClient.optimizeStructure(
  entityId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

7. Insurance Client

import { aiInsuranceClient } from '@/lib/api/ai-insurance-client';

// Analyze coverage
const analysis = await aiInsuranceClient.analyzeCoverage(
  policyId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Assess claim
const assessment = await aiInsuranceClient.assessClaim(
  policyId,
  claimDetails,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Evaluate risk transfer
const evaluation = await aiInsuranceClient.evaluateRiskTransfer(
  policyId,
  riskDescription,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

// Optimize premium
const optimization = await aiInsuranceClient.optimizePremium(
  policyId,
  prompt,
  (chunk) => console.log('Progress:', chunk)
);

Error Handling

All clients throw errors that can be caught:

try {
  const result = await aiDonorClient.generateProposal(
    donorId,
    prompt,
    (chunk) => console.log(chunk)
  );
} catch (error) {
  console.error('Failed to generate proposal:', error);
}

Progress Callbacks

All methods accept an optional progress callback:

const result = await aiDonorClient.generateProposal(
  donorId,
  prompt,
  (chunk) => {
    // Update UI with streaming content
    setStreamingContent((prev) => prev + chunk);
  }
);

Type Safety

All clients are fully typed with TypeScript:

import type { DonorProposal } from '@/types/ai-donor';

const proposal: DonorProposal = await aiDonorClient.generateProposal(
  donorId,
  prompt
);