FA-UX-05 / FW-03 Integration Contract

POST /api/v1/fw/approval-requests/submit
Authorization: Bearer {jwt_token}
Content-Type: application/json

interface SubmitPOApprovalRequest {
  organization_id: uuid;           // REQUIRED - Multi-tenant isolation
  source_type: 'purchase_order';   // REQUIRED - Identifies source entity type
  source_id: uuid;                 // REQUIRED - Purchase order ID (fa_purchase_orders.id)
  source_table: 'fa_purchase_orders'; // REQUIRED - Table name for entity type
  chain_id?: uuid;                 // OPTIONAL - Specific approval chain ID (if not provided, system selects based on rules)
  title: string;                   // REQUIRED - Approval request title (e.g., "PO-2026-001: Office Supplies")
  description?: string;            // OPTIONAL - Approval request description
  request_data: {                  // REQUIRED - Snapshot of PO data at time of submission
    po_number: string;
    vendor_id: uuid;
    vendor_name: string;
    total_amount: number;
    line_count: number;
    delivery_date?: string;        // ISO date
    ship_to_site_id?: uuid;
    department_id?: uuid;
    fund_id?: uuid;
    project_id?: uuid;
  };
  priority?: 'low' | 'normal' | 'high' | 'urgent'; // OPTIONAL - Default: 'normal'
  submitted_by: uuid;              // REQUIRED - User ID submitting the request
}

interface SubmitPOApprovalResponse {
  approval_request_id: uuid;       // Created approval request ID
  organization_id: uuid;
  chain_id: uuid;                  // Approval chain ID used
  current_step: number;            // Current approval step (starts at 1)
  status: 'pending' | 'in_progress'; // Initial status
  next_approver?: {                // Next approver (if known)
    user_id: uuid;
    user_name: string;
    role?: string;
  };
  estimated_completion?: string;   // ISO date - Estimated completion based on SLA
  submitted_at: string;           // ISO timestamp
}

interface ErrorResponse {
  error: {
    code: 'INVALID_REQUEST' | 'UNAUTHORIZED' | 'ACCESS_DENIED' | 'CHAIN_NOT_FOUND' | 'VALIDATION_ERROR' | 'SERVER_ERROR';
    message: string;                // Human-readable error message
    details?: {
      field?: string;               // Field name if validation error
      constraint?: string;          // Constraint violated
    };
  }
}

// In FA-UX-05 wizard completion handler
import { supabase } from '@/integrations/supabase/client';

async function submitPOForApproval(
  poId: string,
  organizationId: string,
  userId: string,
  poData: PurchaseOrderCreationWizardData
) {
  const { data, error } = await supabase.functions.invoke('fw-submit-approval', {
    body: {
      organization_id: organizationId,
      source_type: 'purchase_order',
      source_id: poId,
      source_table: 'fa_purchase_orders',
      title: `PO-${poData.po_number}: ${poData.vendor_name}`,
      description: `Purchase order for ${poData.line_items.length} line items`,
      request_data: {
        po_number: poData.po_number,
        vendor_id: poData.vendor_id,
        vendor_name: poData.vendor_name,
        total_amount: poData.total_amount,
        line_count: poData.line_items.length,
        delivery_date: poData.delivery_date,
        ship_to_site_id: poData.ship_to_site_id,
        department_id: poData.department_id,
        fund_id: poData.fund_id,
        project_id: poData.project_id,
      },
      priority: poData.total_amount > 10000 ? 'high' : 'normal',
      submitted_by: userId,
    },
  });

  if (error) {
    throw new Error(`Failed to submit for approval: ${error.message}`);
  }

  return data; // SubmitPOApprovalResponse
}

import { supabase } from '@/integrations/supabase/client';
import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useSubmitPurchaseOrderApproval(organizationId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (params: {
      poId: string;
      poData: PurchaseOrderCreationWizardData;
    }) => {
      const { data: user } = await supabase.auth.getUser();
      if (!user.user) throw new Error('User not authenticated');

      const { data, error } = await supabase.functions.invoke('fw-submit-approval', {
        body: {
          organization_id: organizationId,
          source_type: 'purchase_order',
          source_id: params.poId,
          source_table: 'fa_purchase_orders',
          title: `PO-${params.poData.po_number}: ${params.poData.vendor_name}`,
          request_data: {
            po_number: params.poData.po_number,
            vendor_id: params.poData.vendor_id,
            vendor_name: params.poData.vendor_name,
            total_amount: params.poData.total_amount,
            line_count: params.poData.line_items.length,
            // ... other fields
          },
          submitted_by: user.user.id,
        },
      });

      if (error) throw error;
      return data;
    },
    onSuccess: () => {
      // Invalidate PO queries to refresh status
      queryClient.invalidateQueries({ queryKey: ['purchase-orders', organizationId] });
    },
  });
}

interface ApprovalRequestCreatedPayload {
  event_type: 'approval_request_created';
  organization_id: uuid;
  timestamp: string; // ISO timestamp
  approval_request_id: uuid;
  source_type: 'purchase_order';
  source_id: uuid; // PO ID
  submitted_by: uuid;
  next_approver?: uuid;
}

interface ApprovalRequestApprovedPayload {
  event_type: 'approval_request_approved';
  organization_id: uuid;
  timestamp: string; // ISO timestamp
  approval_request_id: uuid;
  source_type: 'purchase_order';
  source_id: uuid; // PO ID
  approved_by: uuid;
  completed_at: string; // ISO timestamp
}

interface ApprovalRequestRejectedPayload {
  event_type: 'approval_request_rejected';
  organization_id: uuid;
  timestamp: string; // ISO timestamp
  approval_request_id: uuid;
  source_type: 'purchase_order';
  source_id: uuid; // PO ID
  rejected_by: uuid;
  rejection_reason?: string;
  completed_at: string; // ISO timestamp
}

// In FA-UX-05 wizard completion handler
const { mutate: submitForApproval, isLoading } = useSubmitPurchaseOrderApproval(organizationId);

// After PO creation
const poId = await createPurchaseOrder(poData);

// Submit for approval
submitForApproval(
  {
    poId,
    poData,
  },
  {
    onSuccess: (response) => {
      // Update PO with approval request ID
      updatePurchaseOrder(poId, {
        approval_request_id: response.approval_request_id,
        status: 'pending_approval',
      });
      
      // Show success message
      toast.success('Purchase order submitted for approval');
      
      // Navigate to PO detail page
      navigate(`/fa/purchase-orders/${poId}`);
    },
    onError: (error) => {
      // Show error message
      toast.error(`Failed to submit for approval: ${sanitizeErrorMessage(error)}`);
    },
  }
);

// In FA event handler (edge function or client subscription)
supabase
  .channel('approval_events')
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'fw_approval_events',
    filter: `event_type=eq.approval_request_approved,source_type=eq.purchase_order`,
  }, (payload) => {
    const event = payload.new as ApprovalRequestApprovedPayload;
    
    // Update PO status
    await supabase
      .from('fa_purchase_orders')
      .update({
        status: 'approved',
        approved_at: event.completed_at,
        approved_by: event.approved_by,
      })
      .eq('id', event.source_id)
      .eq('organization_id', event.organization_id);
    
    // Send notification to PO creator
    await sendNotification({
      user_id: poData.created_by,
      type: 'po_approved',
      title: 'Purchase Order Approved',
      message: `PO ${poData.po_number} has been approved`,
    });
  })
  .subscribe();