@iota-big3/sdk-gateway

/** * @fileoverview Comprehensive types for engagement systems (Donors, Extracurricular, Marketing) * @module @iota-big3/sdk-types/engagement * @description * Provides strictly-typed definitions for engagement management including: * - Donor Management (fundraising, campaigns, recognition) * - Extracurricular Activities (clubs, sports, arts, volunteer) * - Marketing (campaigns, outreach, communications) * * Designed for AI/debugging friendliness with descriptive names and comprehensive documentation. * * @example * ```typescript * import type { Donor, Activity, MarketingCampaign } from '@iota-big3/sdk-types'; * * // Donor Management * const donor: Donor = { * id: 'donor_123', * personalInfo: { * firstName: 'Jane', * lastName: 'Smith', * email: 'jane.smith@email.com', * phone: '+1-555-0456' * }, * donorProfile: { * type: DonorType.INDIVIDUAL, * category: DonorCategory.MAJOR_DONOR, * firstGiftDate: '2015-03-15', * lifetimeGiving: 250000n, * lastGiftDate: '2024-01-15', * communicationPreferences: { * email: true, * phone: false, * mail: true, * frequency: CommunicationFrequency.QUARTERLY * } * } * }; * ``` * * @since 1.0.0 */ import type { GradeLevel, StudentId } from './education-types'; import type { EmployeeId } from './operational-types'; import type { Brand } from './utilities'; /** * Donor identifier * @description Unique identifier for a donor in the system * @example "donor_abc123def456" */ export type DonorId = Brand<string, 'DonorId'>; /** * Campaign identifier * @description Unique identifier for a fundraising campaign * @example "campaign_annual_2024" */ export type CampaignId = Brand<string, 'CampaignId'>; /** * Activity identifier * @description Unique identifier for an extracurricular activity * @example "act_chess_club_2024" */ export type ActivityId = Brand<string, 'ActivityId'>; /** * Marketing campaign identifier * @description Unique identifier for a marketing campaign * @example "mkt_spring_enrollment_2024" */ export type MarketingCampaignId = Brand<string, 'MarketingCampaignId'>; /** * Event identifier * @description Unique identifier for an event * @example "evt_gala_2024" */ export type EventId = Brand<string, 'EventId'>; /** * Donor types * @description Categories of donors */ export declare enum DonorType { INDIVIDUAL = "INDIVIDUAL", CORPORATION = "CORPORATION", FOUNDATION = "FOUNDATION", GOVERNMENT = "GOVERNMENT", ALUMNI = "ALUMNI", PARENT = "PARENT", STAFF = "STAFF", ANONYMOUS = "ANONYMOUS" } /** * Donor categories * @description Classification levels for donors */ export declare enum DonorCategory { MAJOR_DONOR = "MAJOR_DONOR",// $10,000+ MID_LEVEL = "MID_LEVEL",// $1,000-$9,999 ANNUAL_FUND = "ANNUAL_FUND",// $100-$999 ENTRY_LEVEL = "ENTRY_LEVEL",// Under $100 PLANNED_GIVING = "PLANNED_GIVING", MONTHLY_GIVING = "MONTHLY_GIVING", LAPSED = "LAPSED",// No gift in 2+ years PROSPECT = "PROSPECT" } /** * Gift types * @description Types of donations */ export declare enum GiftType { CASH = "CASH", CHECK = "CHECK", CREDIT_CARD = "CREDIT_CARD", ACH = "ACH", STOCK = "STOCK", PROPERTY = "PROPERTY", IN_KIND = "IN_KIND", PLANNED = "PLANNED", PLEDGE = "PLEDGE", GRANT = "GRANT" } /** * Communication frequency * @description How often to communicate with donors */ export declare enum CommunicationFrequency { WEEKLY = "WEEKLY", MONTHLY = "MONTHLY", QUARTERLY = "QUARTERLY", SEMI_ANNUALLY = "SEMI_ANNUALLY", ANNUALLY = "ANNUALLY", AS_NEEDED = "AS_NEEDED", DO_NOT_CONTACT = "DO_NOT_CONTACT" } /** * Recognition level * @description Donor recognition tiers */ export declare enum RecognitionLevel { FOUNDERS_CIRCLE = "FOUNDERS_CIRCLE",// $1M+ PRESIDENTS_CIRCLE = "PRESIDENTS_CIRCLE",// $500K+ BENEFACTOR = "BENEFACTOR",// $100K+ PATRON = "PATRON",// $50K+ PARTNER = "PARTNER",// $25K+ SUPPORTER = "SUPPORTER",// $10K+ FRIEND = "FRIEND",// $1K+ MEMBER = "MEMBER" } /** * Donor personal information * @description Personal details of a donor */ export interface DonorPersonalInfo { readonly firstName: string; readonly lastName: string; readonly middleName?: string; readonly preferredName?: string; readonly title?: string; readonly suffix?: string; readonly email: string; readonly alternateEmail?: string; readonly phone: string; readonly alternatePhone?: string; readonly address?: { readonly street: string; readonly street2?: string; readonly city: string; readonly state: string; readonly postalCode: string; readonly country: string; }; readonly businessInfo?: { readonly company: string; readonly position: string; readonly industry?: string; }; } /** * Donor profile * @description Comprehensive donor information */ export interface DonorProfile { readonly type: DonorType; readonly category: DonorCategory; readonly firstGiftDate?: string; readonly lastGiftDate?: string; readonly lifetimeGiving: bigint; readonly largestGift: bigint; readonly averageGift: bigint; readonly giftCount: number; readonly pledgeBalance?: bigint; readonly recognitionLevel?: RecognitionLevel; readonly interests: string[]; readonly capacity?: { readonly rating: 'A' | 'B' | 'C' | 'D'; readonly estimatedCapacity?: bigint; readonly source?: string; }; readonly communicationPreferences: { readonly email: boolean; readonly phone: boolean; readonly mail: boolean; readonly text: boolean; readonly frequency: CommunicationFrequency; readonly doNotSolicit?: boolean; readonly anonymousGiving?: boolean; }; readonly relationships?: Array<{ readonly type: string; readonly relatedDonorId?: DonorId; readonly isPrimary: boolean; }>; } /** * Donation record * @description Individual donation information */ export interface Donation { readonly id: string; readonly donorId: DonorId; readonly date: string; readonly amount: bigint; readonly type: GiftType; readonly campaignId?: CampaignId; readonly designation: string; readonly isRecurring: boolean; readonly recurringSchedule?: { readonly frequency: 'MONTHLY' | 'QUARTERLY' | 'ANNUALLY'; readonly startDate: string; readonly endDate?: string; readonly nextDate?: string; }; readonly tribute?: { readonly type: 'IN_HONOR' | 'IN_MEMORY'; readonly honoree: string; readonly notifyName?: string; readonly notifyAddress?: string; }; readonly acknowledgment: { readonly sent: boolean; readonly sentDate?: string; readonly method?: 'EMAIL' | 'MAIL' | 'PHONE'; readonly receiptNumber?: string; }; readonly taxDeductible: boolean; readonly notes?: string; } /** * Fundraising campaign * @description Campaign for raising funds */ export interface FundraisingCampaign { readonly id: CampaignId; readonly name: string; readonly description: string; readonly type: 'ANNUAL' | 'CAPITAL' | 'SPECIAL' | 'EMERGENCY'; readonly goal: bigint; readonly raised: bigint; readonly startDate: string; readonly endDate: string; readonly status: 'PLANNING' | 'ACTIVE' | 'COMPLETED' | 'CANCELLED'; readonly theme?: string; readonly matchingGift?: { readonly donor: DonorId; readonly matchRatio: number; readonly maxMatch: bigint; readonly matched: bigint; }; readonly milestones?: Array<{ readonly amount: bigint; readonly description: string; readonly reached: boolean; readonly reachedDate?: string; }>; readonly materials?: Array<{ readonly type: string; readonly url: string; readonly version: string; }>; } /** * Complete donor record * @description Full donor information with history */ export interface Donor { readonly id: DonorId; readonly personalInfo: DonorPersonalInfo; readonly donorProfile: DonorProfile; readonly donations?: Donation[]; readonly pledges?: Array<{ readonly amount: bigint; readonly startDate: string; readonly endDate: string; readonly frequency: string; readonly fulfilled: bigint; readonly remaining: bigint; }>; readonly events?: Array<{ readonly eventId: EventId; readonly attended: boolean; readonly tableHost?: boolean; readonly guests?: number; }>; readonly stewardship?: Array<{ readonly date: string; readonly type: string; readonly contact: EmployeeId; readonly notes: string; readonly nextAction?: string; }>; readonly metadata?: { readonly createdAt: string; readonly updatedAt: string; readonly source: string; readonly tags?: string[]; }; } /** * Activity types * @description Categories of extracurricular activities */ export declare enum ActivityType { ACADEMIC = "ACADEMIC",// Math club, debate team ARTS = "ARTS",// Band, theater, art club ATHLETICS = "ATHLETICS",// Sports teams CULTURAL = "CULTURAL",// Language clubs, cultural groups SERVICE = "SERVICE",// Volunteer groups, community service LEADERSHIP = "LEADERSHIP",// Student government, honor societies STEM = "STEM",// Robotics, science clubs RECREATION = "RECREATION",// Games, hobbies PROFESSIONAL = "PROFESSIONAL",// Career-oriented clubs RELIGIOUS = "RELIGIOUS" } /** * Activity status * @description Current status of an activity */ export declare enum ActivityStatus { ACTIVE = "ACTIVE", INACTIVE = "INACTIVE", SUSPENDED = "SUSPENDED", PLANNING = "PLANNING", CANCELLED = "CANCELLED" } /** * Participation status * @description Student's participation status */ export declare enum ParticipationStatus { ACTIVE = "ACTIVE", INACTIVE = "INACTIVE", GRADUATED = "GRADUATED", WITHDRAWN = "WITHDRAWN", SUSPENDED = "SUSPENDED" } /** * Meeting schedule * @description When and where activities meet */ export interface MeetingSchedule { readonly frequency: 'DAILY' | 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'AS_NEEDED'; readonly dayOfWeek?: string[]; readonly time: string; readonly duration: number; readonly location: string; readonly virtualOption?: { readonly platform: string; readonly link: string; readonly passcode?: string; }; } /** * Activity requirements * @description Requirements for participation */ export interface ActivityRequirements { readonly minGPA?: number; readonly gradeLevel?: GradeLevel[]; readonly tryouts?: boolean; readonly applicationRequired?: boolean; readonly teacherRecommendation?: boolean; readonly parentPermission?: boolean; readonly fee?: bigint; readonly equipment?: string[]; readonly timeCommitment?: string; } /** * Extracurricular activity * @description Complete activity information */ export interface ExtracurricularActivity { readonly id: ActivityId; readonly name: string; readonly description: string; readonly type: ActivityType; readonly status: ActivityStatus; readonly sponsor: { readonly primary: EmployeeId; readonly secondary?: EmployeeId[]; }; readonly schedule: MeetingSchedule; readonly requirements: ActivityRequirements; readonly capacity?: { readonly min: number; readonly max: number; readonly current: number; readonly waitlist: number; }; readonly competitions?: Array<{ readonly name: string; readonly date: string; readonly level: 'LOCAL' | 'REGIONAL' | 'STATE' | 'NATIONAL' | 'INTERNATIONAL'; readonly result?: string; readonly participants?: StudentId[]; }>; readonly achievements?: Array<{ readonly title: string; readonly date: string; readonly description: string; readonly recognition?: 'AWARD' | 'TROPHY' | 'CERTIFICATE' | 'MEDAL'; }>; readonly budget?: { readonly annual: bigint; readonly fundraisingGoal?: bigint; readonly expenses: Array<{ readonly category: string; readonly amount: bigint; readonly description: string; }>; }; } /** * Activity participation * @description Student's participation in an activity */ export interface ActivityParticipation { readonly studentId: StudentId; readonly activityId: ActivityId; readonly joinDate: string; readonly endDate?: string; readonly status: ParticipationStatus; readonly role?: string; readonly attendance: { readonly required: number; readonly attended: number; readonly excused: number; readonly percentage: number; }; readonly contributions?: Array<{ readonly date: string; readonly type: string; readonly description: string; readonly recognition?: string; }>; readonly evaluations?: Array<{ readonly date: string; readonly evaluator: EmployeeId; readonly rating: number; readonly comments: string; readonly areasOfGrowth?: string[]; }>; } /** * Marketing channel * @description Communication channels for marketing */ export declare enum MarketingChannel { EMAIL = "EMAIL", SOCIAL_MEDIA = "SOCIAL_MEDIA", WEBSITE = "WEBSITE", PRINT = "PRINT", RADIO = "RADIO", TV = "TV", OUTDOOR = "OUTDOOR",// Billboards, etc. EVENTS = "EVENTS", DIRECT_MAIL = "DIRECT_MAIL", DIGITAL_ADS = "DIGITAL_ADS" } /** * Campaign status * @description Status of marketing campaign */ export declare enum MarketingCampaignStatus { DRAFT = "DRAFT", SCHEDULED = "SCHEDULED", ACTIVE = "ACTIVE", PAUSED = "PAUSED", COMPLETED = "COMPLETED", CANCELLED = "CANCELLED" } /** * Audience segment * @description Target audience for marketing */ export declare enum AudienceSegment { PROSPECTIVE_STUDENTS = "PROSPECTIVE_STUDENTS", CURRENT_STUDENTS = "CURRENT_STUDENTS", ALUMNI = "ALUMNI", PARENTS = "PARENTS", DONORS = "DONORS", COMMUNITY = "COMMUNITY", STAFF = "STAFF", MEDIA = "MEDIA", PARTNERS = "PARTNERS" } /** * Content type * @description Types of marketing content */ export declare enum ContentType { ARTICLE = "ARTICLE", VIDEO = "VIDEO", IMAGE = "IMAGE", INFOGRAPHIC = "INFOGRAPHIC", PODCAST = "PODCAST", NEWSLETTER = "NEWSLETTER", PRESS_RELEASE = "PRESS_RELEASE", SOCIAL_POST = "SOCIAL_POST", WEBINAR = "WEBINAR", EBOOK = "EBOOK" } /** * Marketing campaign * @description Marketing campaign details */ export interface MarketingCampaign { readonly id: MarketingCampaignId; readonly name: string; readonly description: string; readonly objective: string; readonly audience: { readonly segments: AudienceSegment[]; readonly customSegments?: string[]; readonly estimatedReach: number; }; readonly channels: MarketingChannel[]; readonly timeline: { readonly startDate: string; readonly endDate: string; readonly milestones?: Array<{ readonly date: string; readonly description: string; readonly completed: boolean; }>; }; readonly budget: { readonly total: bigint; readonly allocated: Record<MarketingChannel, bigint>; readonly spent: bigint; }; readonly content: Array<{ readonly type: ContentType; readonly title: string; readonly status: 'DRAFT' | 'REVIEW' | 'APPROVED' | 'PUBLISHED'; readonly url?: string; readonly scheduledDate?: string; }>; readonly status: MarketingCampaignStatus; readonly metrics?: { readonly impressions?: number; readonly clicks?: number; readonly conversions?: number; readonly engagement?: number; readonly roi?: number; }; readonly abTesting?: Array<{ readonly variant: string; readonly description: string; readonly percentage: number; readonly metrics: Record<string, number>; }>; } /** * Marketing event * @description Event for marketing/engagement */ export interface MarketingEvent { readonly id: EventId; readonly name: string; readonly description: string; readonly type: 'OPEN_HOUSE' | 'GALA' | 'CONFERENCE' | 'WORKSHOP' | 'CEREMONY' | 'FUNDRAISER' | 'OTHER'; readonly date: string; readonly location: { readonly venue: string; readonly address: string; readonly capacity: number; readonly virtualOption?: { readonly platform: string; readonly link: string; readonly maxAttendees?: number; }; }; readonly registration: { readonly required: boolean; readonly deadline?: string; readonly fee?: bigint; readonly currentRegistrations: number; readonly waitlist: number; }; readonly agenda?: Array<{ readonly time: string; readonly duration: number; readonly title: string; readonly speaker?: string; readonly description?: string; }>; readonly sponsors?: Array<{ readonly name: string; readonly level: 'TITLE' | 'PLATINUM' | 'GOLD' | 'SILVER' | 'BRONZE'; readonly contribution: bigint; readonly benefits: string[]; }>; readonly marketing: { readonly campaignId?: MarketingCampaignId; readonly materials: Array<{ readonly type: string; readonly url: string; }>; readonly promotionChannels: MarketingChannel[]; }; } /** * Calculate donor retention rate * @param donors - Array of donors * @param year - Year to calculate for * @returns Retention rate as percentage */ export declare function calculateDonorRetention(donors: Donor[], year: number): number; /** * Check if activity is at capacity * @param activity - Activity to check * @returns True if at or over capacity */ export declare function isActivityFull(activity: ExtracurricularActivity): boolean; /** * Calculate marketing campaign ROI * @param campaign - Marketing campaign * @returns ROI as percentage */ export declare function calculateCampaignROI(campaign: MarketingCampaign): number; /** * Get donor recognition level * @param lifetimeGiving - Total lifetime giving in cents * @returns Recognition level */ export declare function getDonorRecognitionLevel(lifetimeGiving: bigint): RecognitionLevel; export declare const engagementTypes: { readonly calculateDonorRetention: typeof calculateDonorRetention; readonly getDonorRecognitionLevel: typeof getDonorRecognitionLevel; readonly isActivityFull: typeof isActivityFull; readonly calculateCampaignROI: typeof calculateCampaignROI; }; //# sourceMappingURL=engagement-types.d.ts.map