Partner

Partner

Overview

The Partner class manages partner entities and their associated venues, documents, and contract information within the system, serving as a central registry for partner organizations and their relationships.

General Purpose:

Manages partner creation, updates, and status changes with workflow approval integration
Maintains partner types, multiple subtypes per partner, tier assignments, and social media presence
Handles venue/location management with geographic coordinates and contact information
Provides document upload, storage, and retrieval capabilities through FileManager integration
Supports activity tracking and audit logging for all partner operations
Instance-based architecture where each partner has a unique instance ID
Streams partner and venue data to MongoDB for external synchronization

Terminology Note:

Internally, partner venues are referred to as "locations" with a type field to support different location types (e.g., venue, office, warehouse)
For backward compatibility, the client-facing API endpoints continue to use "venue" terminology
The type field is system-managed and defaults to venue - it is not settable by clients
All venues/locations include geographic coordinates for location-based features

Data Structure

State Schema

interface PartnerState {
  private: {
    partner: Partner
    locations: PartnerLocation[]      // Internally called 'locations', exposed as 'venues' in API
  }
  public: object
}

interface Partner {
  id: string

  // Details Tab
  legalName: string
  brandName: string
  brandLogoPath?: string
  partnerTier?: string
  socialMediaAccounts?: SocialMediaAccount[]

  // Contact Tab
  businessAddress: string
  city: string
  country: string
  website?: string
  primaryContact: PrimaryContact

  // Contract Tab
  partnerTypeId?: string
  partnerSubtypeIds?: string[]          // Multiple subtypes supported
  tradeLicenseNumber?: string
  contractId: string
  contractStartDate: Date
  contractEndDate: Date
  accountAgent?: string

  // System Fields
  status: PartnerStatus
  statusReason?: string
  createdBy: Actor
  createdAt: Date
  updatedAt: Date
}

Enums and Types

enum PartnerStatus {
  ACTIVE = 'active',
  INACTIVE = 'inactive'
}

enum DocumentStatus {
  ACTIVE = 'active',
  ARCHIVED = 'archived'
}

enum SocialMediaPlatform {
  FACEBOOK = 'facebook',
  INSTAGRAM = 'instagram',
  LINKEDIN = 'linkedin',
  TWITTER = 'x',
  YOUTUBE = 'youtube',
  TIKTOK = 'tiktok'
}

enum PartnerEvents {
  PARTNER_CREATE = 'partner_create',
  UPDATE_PARTNER_DETAILS = 'update_partner_details',
  UPDATE_PARTNER_BRAND_LOGO = 'update_partner_brand_logo',
  UPDATE_PARTNER_CONTACT = 'update_partner_contact',
  UPDATE_PARTNER_CONTRACT = 'update_partner_contract',
  UPDATE_PARTNER_STATUS = 'update_partner_status'
}

enum VenueStatus {
  ACTIVE = 'active',
  INACTIVE = 'inactive'
}

enum LocationType {
  VENUE = 'venue'
}

enum VenueEvents {
  VENUE_CREATE = 'venue_create',
  VENUE_UPDATE = 'venue_update',
  VENUE_STATUS_UPDATE = 'venue_status_update'
}

Additional Structures

interface PrimaryContact {
  name: string
  email: string
  phone: string
}

interface SocialMediaAccount {
  platform: SocialMediaPlatform
  url: string
}

interface PartnerLocation {
  id: string
  partnerId: string
  venueName: string                  // Note: field name kept as 'venueName' for API compatibility
  address: string
  contactName: string
  contactEmail: string
  contactPhone: string
  mapCoordinates: MapCoordinates
  type: LocationType                // Location type (system-managed, not client-settable)
  status: VenueStatus
  createdBy: Actor
  createdAt: Date
  updatedAt: Date
}

interface MapCoordinates {
  latitude: number
  longitude: number
}

interface Actor {
  id: string
}

interface PartnerDocument {
  id: string
  filename: string
  originalFilename: string
  uploadedBy: Actor
  uploadedAt: Date
  status: DocumentStatus           // Document status (active/archived)
}

Core Functionality

Main Feature Groups

Partner Lifecycle Management: Create, update, and manage partner information with workflow integration across three tabs (Details, Contact, Contract)
Status Management: Control partner status transitions through approval workflows with optional status reasons
Venue Management: Create, update, and list venues associated with partners, including geographic coordinates
Document Management: Upload, list, download, archive, and unarchive documents through FileManager integration with status-based access control
Search and Filtering: List partners with filtering by status, partner type, multiple subtypes, and search query with pagination
Brand Management: Handle brand logos and social media account links for marketing purposes
Contract Tracking: Manage partner contracts with expiry dates and trade license numbers
Data Streaming: Synchronize partner and venue data to MongoDB for external system integration
Activity Logging: Track all partner-related operations through LogManager integration

Workflow Integration

The Partner class extends WorkflowCompatibleStateManager to integrate with the workflow system:

Status Transitions: Workflow rules manage partner status changes from creation to active/inactive states
Events: Partner lifecycle events trigger workflow processing (create, update details/contact/contract, status update)
Approval Integration: Uses PartnerApprovalManager for handling approval workflows
Business Rules: Workflow configuration defines approval requirements for partner operations
Venue Workflows: Separate workflow rules for venue creation, updates, and status changes

API Methods

Partner Management

init (WRITE) - Initialize a new partner with details, contact, and contract information
- Uploads brand logo to FileManager if provided
- Triggers workflow approval process
- Streams partner data to MongoDB
listPartners (STATIC) - List partners with filtering and pagination
- Filter by status, partner type, multiple subtypes, and search query
- Subtype filtering returns partners that have any of the specified subtypes
- Returns paginated results with total count

Partner Information

getPartnerDetails (READ) - Get partner details tab information
- Returns legal name, brand name, logo path, tier, and social media accounts
getPartnerContact (READ) - Get partner contact tab information
- Returns business address, city, country, website, and primary contact
getPartnerContract (READ) - Get partner contract tab information
- Returns partner type, subtypes (array), trade license, contract ID, and expiry date
updatePartnerDetails (WRITE) - Update partner details tab
- Updates legal name, brand information, tier, and social media
- Triggers workflow event for approval
updatePartnerBrandLogo (WRITE) - Update partner brand logo
- Uploads new brand logo to FileManager
- Updates brandLogoPath in partner state
- Triggers workflow event for approval
updatePartnerContact (WRITE) - Update partner contact tab
- Updates address, city, country, website, and primary contact
- Triggers workflow event for approval
updatePartnerContract (WRITE) - Update partner contract tab
- Updates partner type, subtypes (array), trade license, contract ID, and expiry date
- Supports multiple subtypes per partner for flexible categorization
- Triggers workflow event for approval
updatePartnerStatus (WRITE) - Update partner status
- Changes partner status (active/inactive) with optional reason
- Triggers workflow event for approval

Venue Management

createVenue (WRITE) - Create a new venue for the partner
- Includes venue name, address, contact info, and map coordinates
- Streams venue data to MongoDB
getVenue (READ) - Get a specific venue by ID
- Retrieves venue details from MongoDB
listVenues (READ) - List venues for the partner
- Filter by status and search query with pagination
- Returns venues associated with the partner instance
updateVenue (WRITE) - Update an existing venue
- Updates venue name, address, contact info, and coordinates
- Streams updated data to MongoDB
updateVenueStatus (WRITE) - Update venue status
- Changes venue status (active/inactive)

Document Management

uploadDocument (WRITE) - Upload a document or image
- Supports IMAGE (max 5MB) and DOCUMENT (max 10MB) file types
- Accepts images (jpeg, png, gif, webp) and documents (pdf, doc, docx, xls, xlsx, txt, csv)
- Stores documents through FileManager integration
- Documents are created with ACTIVE status by default
- Returns document ID and filename
listDocuments (READ) - List documents with pagination
- Returns all documents (both active and archived) associated with the partner
- Documents are sorted by uploadedAt in descending order (newest first)
- Includes document status and status label (Active/Archived) for each document
- Includes pagination support
downloadDocument (READ) - Download an active document
- Retrieves active documents from FileManager by document ID
- Prevents access to archived documents (returns error code 14008)
- Use downloadArchivedDocument endpoint for archived documents
archiveDocument (WRITE) - Archive a document
- Changes document status to ARCHIVED
- Archived documents cannot be accessed via regular downloadDocument endpoint
- Document remains in storage but requires special permissions to access
unarchiveDocument (WRITE) - Unarchive a document
- Changes document status back to ACTIVE
- Makes document accessible through regular downloadDocument endpoint
downloadArchivedDocument (READ) - Download an archived document
- Retrieves archived documents from FileManager by document ID
- Separate endpoint with dedicated permissions for accessing archived documents
- Enables permission separation between active and archived document access

Approval Operations

approvePartner (QUEUED_WRITE) - Approve partner operations
- Processes approval/rejection for partner workflows
- Uses CommonApprovalInput pattern

History Operations

getLogEntries (STATIC) - Get log entries for a specific partner
- Returns paginated log entries with filtering by date range and search
- Retrieves activity history from LogManager
getLog (STATIC) - Get a specific log entry with complete details
- Returns full details of a single log entry by log ID

Key Features

Architecture Pattern: Instance-based architecture where each partner has a unique instance ID generated via getInstanceId()
Integration Points: Integrates with FileManager for document storage, LogManager for activity tracking, MongoDB for data persistence, and Workflow/ApprovalManager for approval processes
Workflow Support: Extends WorkflowCompatibleStateManager with separate workflow configurations for partner and venue operations
Tabbed Data Model: Organizes partner information into three logical tabs (Details, Contact, Contract) for better UX and granular updates
Venue Management: Supports multiple venues per partner with geographic coordinates for location-based features
Document Storage: Leverages FileManager for secure document upload, storage, and retrieval with status-based archiving (active/archived) for access control and permission separation
Data Streaming: Automatically streams partner and venue data to MongoDB for external system synchronization
Audit Logging: Tracks all operations through LogManager with comprehensive history retrieval
Brand Assets: Handles brand logos via FileManager and manages social media presence
Contract Management: Tracks contract expiry dates and trade licenses for compliance

Keyboard shortcuts

Platinum