business-as-code/src/entities/partnerships.ts

Primitives for expressing business logic and processes as code

import type { Noun } from 'ai-database'

/**
 * Partnership & Vendor Entities
 * Partner, Vendor, Affiliate, Partnership, Reseller, Integration
 */

export const Partner: Noun = {
  singular: 'partner',
  plural: 'partners',
  description: 'A business partner that collaborates with the organization',
  properties: {
    name: { type: 'string', description: 'Partner organization name' },
    type: { type: 'string', description: 'Type of partner', examples: ['strategic', 'technology', 'channel', 'solution', 'implementation', 'consulting', 'reseller', 'referral', 'OEM'] },
    tier: { type: 'string', description: 'Partner tier level', examples: ['platinum', 'gold', 'silver', 'bronze', 'registered'] },
    status: { type: 'string', description: 'Partnership status', examples: ['prospect', 'onboarding', 'active', 'inactive', 'suspended', 'terminated'] },
    description: { type: 'string', description: 'Partner description' },
    website: { type: 'string', description: 'Partner website URL' },
    logo: { type: 'string', description: 'Partner logo URL' },
    industry: { type: 'string', description: 'Partner industry' },
    size: { type: 'string', description: 'Partner company size', examples: ['startup', 'small', 'medium', 'enterprise'] },
    region: { type: 'string', description: 'Primary region of operation' },
    territories: { type: 'string[]', description: 'Geographic territories covered' },
    specializations: { type: 'string[]', description: 'Areas of specialization', examples: ['cloud', 'security', 'data', 'AI', 'mobile', 'e-commerce'] },
    certifications: { type: 'string[]', description: 'Partner certifications held' },
    primaryContact: { type: 'string', description: 'Primary contact person' },
    email: { type: 'string', description: 'Primary contact email' },
    phone: { type: 'string', description: 'Primary contact phone' },
    partnerManager: { type: 'string', description: 'Internal partner manager' },
    startDate: { type: 'date', description: 'Partnership start date' },
    renewalDate: { type: 'date', description: 'Next renewal date' },
    revenueShare: { type: 'number', description: 'Revenue share percentage' },
    referralFee: { type: 'number', description: 'Referral fee percentage' },
    totalRevenue: { type: 'number', description: 'Total revenue generated' },
    totalDeals: { type: 'number', description: 'Total deals closed' },
    lastActivityDate: { type: 'date', description: 'Date of last activity' },
    nda: { type: 'boolean', description: 'NDA in place' },
    ndaDate: { type: 'date', description: 'NDA signed date' },
    portalAccess: { type: 'boolean', description: 'Has partner portal access' },
    enablementComplete: { type: 'boolean', description: 'Enablement training completed' },
    score: { type: 'number', description: 'Partner performance score', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Partner tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    partnership: { type: 'partnership', description: 'Active partnership agreement', backref: 'partner' },
    deals: { type: 'deal[]', description: 'Deals sourced by partner', backref: 'partner' },
    leads: { type: 'lead[]', description: 'Leads referred by partner', backref: 'partner' },
    contacts: { type: 'contact[]', description: 'Partner contacts', backref: 'partner' },
    integrations: { type: 'integration[]', description: 'Technical integrations', backref: 'partner' },
  },
  actions: ['create', 'update', 'onboard', 'activate', 'deactivate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'certify', 'enable', 'review', 'renew'],
  events: ['created', 'updated', 'onboarded', 'activated', 'deactivated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'certified', 'enabled', 'reviewed', 'renewed'],
}

export const Vendor: Noun = {
  singular: 'vendor',
  plural: 'vendors',
  description: 'An external supplier or service provider',
  properties: {
    name: { type: 'string', description: 'Vendor name' },
    type: { type: 'string', description: 'Type of vendor', examples: ['supplier', 'contractor', 'consultant', 'SaaS', 'service', 'manufacturer'] },
    category: { type: 'string', description: 'Vendor category', examples: ['technology', 'operations', 'marketing', 'HR', 'legal', 'finance', 'facilities'] },
    status: { type: 'string', description: 'Vendor status', examples: ['prospect', 'evaluating', 'approved', 'active', 'preferred', 'suspended', 'terminated'] },
    website: { type: 'string', description: 'Vendor website' },
    description: { type: 'string', description: 'Vendor description' },
    primaryContact: { type: 'string', description: 'Primary contact name' },
    email: { type: 'string', description: 'Contact email' },
    phone: { type: 'string', description: 'Contact phone' },
    address: { type: 'string', description: 'Vendor address' },
    country: { type: 'string', description: 'Country of operation' },
    taxId: { type: 'string', description: 'Tax identification number' },
    paymentTerms: { type: 'string', description: 'Payment terms', examples: ['net-15', 'net-30', 'net-60', 'net-90', 'on-receipt'] },
    currency: { type: 'string', description: 'Preferred currency' },
    bankDetails: { type: 'object', description: 'Banking information', optional: true },
    contractValue: { type: 'number', description: 'Total contract value' },
    annualSpend: { type: 'number', description: 'Annual spend amount' },
    startDate: { type: 'date', description: 'Relationship start date' },
    contractEndDate: { type: 'date', description: 'Current contract end date' },
    lastOrderDate: { type: 'date', description: 'Last order date' },
    riskLevel: { type: 'string', description: 'Risk assessment', examples: ['low', 'medium', 'high', 'critical'] },
    complianceStatus: { type: 'string', description: 'Compliance status', examples: ['compliant', 'pending', 'non-compliant', 'exempt'] },
    slaScore: { type: 'number', description: 'SLA performance score' },
    qualityScore: { type: 'number', description: 'Quality rating score' },
    certifications: { type: 'string[]', description: 'Vendor certifications', examples: ['SOC2', 'ISO27001', 'GDPR', 'HIPAA'] },
    insuranceCoverage: { type: 'boolean', description: 'Has insurance coverage' },
    insuranceExpiry: { type: 'date', description: 'Insurance expiry date', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Vendor tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    contracts: { type: 'contract[]', description: 'Vendor contracts', backref: 'vendor' },
    orders: { type: 'order[]', description: 'Purchase orders', backref: 'vendor' },
    invoices: { type: 'invoice[]', description: 'Vendor invoices', backref: 'vendor' },
    contacts: { type: 'contact[]', description: 'Vendor contacts', backref: 'vendor' },
    expenses: { type: 'expense[]', description: 'Related expenses', backref: 'vendor' },
  },
  actions: ['create', 'update', 'evaluate', 'approve', 'reject', 'activate', 'suspend', 'terminate', 'review', 'audit', 'renew'],
  events: ['created', 'updated', 'evaluated', 'approved', 'rejected', 'activated', 'suspended', 'terminated', 'reviewed', 'audited', 'renewed'],
}

export const Affiliate: Noun = {
  singular: 'affiliate',
  plural: 'affiliates',
  description: 'An affiliate partner who promotes products for commission',
  properties: {
    name: { type: 'string', description: 'Affiliate name' },
    type: { type: 'string', description: 'Type of affiliate', examples: ['individual', 'company', 'influencer', 'blogger', 'publisher', 'network'] },
    status: { type: 'string', description: 'Affiliate status', examples: ['applied', 'pending', 'approved', 'active', 'suspended', 'terminated'] },
    email: { type: 'string', description: 'Contact email' },
    website: { type: 'string', description: 'Affiliate website or channel' },
    platform: { type: 'string', description: 'Primary platform', examples: ['blog', 'youtube', 'instagram', 'tiktok', 'twitter', 'podcast', 'newsletter'] },
    audienceSize: { type: 'number', description: 'Estimated audience size' },
    niche: { type: 'string', description: 'Content niche or focus area' },
    country: { type: 'string', description: 'Country of operation' },
    affiliateId: { type: 'string', description: 'Unique affiliate identifier' },
    referralCode: { type: 'string', description: 'Unique referral code' },
    trackingLink: { type: 'string', description: 'Affiliate tracking link' },
    commissionRate: { type: 'number', description: 'Commission percentage' },
    commissionType: { type: 'string', description: 'Commission type', examples: ['percentage', 'flat-rate', 'tiered', 'recurring'] },
    cookieDuration: { type: 'number', description: 'Cookie duration in days' },
    payoutThreshold: { type: 'number', description: 'Minimum payout amount' },
    payoutMethod: { type: 'string', description: 'Preferred payout method', examples: ['paypal', 'bank-transfer', 'check', 'crypto', 'gift-card'] },
    payoutDetails: { type: 'object', description: 'Payout account details', optional: true },
    totalClicks: { type: 'number', description: 'Total clicks generated' },
    totalConversions: { type: 'number', description: 'Total conversions' },
    conversionRate: { type: 'number', description: 'Conversion rate' },
    totalRevenue: { type: 'number', description: 'Total revenue generated' },
    totalCommissions: { type: 'number', description: 'Total commissions earned' },
    pendingCommissions: { type: 'number', description: 'Pending commission amount' },
    paidCommissions: { type: 'number', description: 'Total paid commissions' },
    lastReferralDate: { type: 'date', description: 'Date of last referral' },
    lastPayoutDate: { type: 'date', description: 'Date of last payout' },
    joinDate: { type: 'date', description: 'Date joined program' },
    tier: { type: 'string', description: 'Affiliate tier', examples: ['bronze', 'silver', 'gold', 'platinum', 'diamond'] },
    promotionalMaterials: { type: 'boolean', description: 'Has access to promo materials' },
    customLandingPage: { type: 'boolean', description: 'Has custom landing page' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Affiliate tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    referrals: { type: 'lead[]', description: 'Referred leads', backref: 'affiliate' },
    conversions: { type: 'deal[]', description: 'Converted deals', backref: 'affiliate' },
    payouts: { type: 'expense[]', description: 'Commission payouts', backref: 'affiliate' },
    campaigns: { type: 'campaign[]', description: 'Promotional campaigns', backref: 'affiliate' },
  },
  actions: ['create', 'update', 'approve', 'reject', 'activate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'payout', 'track'],
  events: ['created', 'updated', 'approved', 'rejected', 'activated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'paidOut', 'tracked'],
}

export const Partnership: Noun = {
  singular: 'partnership',
  plural: 'partnerships',
  description: 'A formal partnership agreement between organizations',
  properties: {
    name: { type: 'string', description: 'Partnership name' },
    type: { type: 'string', description: 'Type of partnership', examples: ['strategic', 'technology', 'channel', 'co-marketing', 'co-selling', 'integration', 'reseller', 'white-label', 'OEM'] },
    status: { type: 'string', description: 'Partnership status', examples: ['proposed', 'negotiating', 'pending-approval', 'active', 'on-hold', 'expired', 'terminated'] },
    description: { type: 'string', description: 'Partnership description' },
    objectives: { type: 'string[]', description: 'Partnership objectives' },
    startDate: { type: 'date', description: 'Partnership start date' },
    endDate: { type: 'date', description: 'Partnership end date' },
    autoRenew: { type: 'boolean', description: 'Auto-renewal enabled' },
    renewalNoticeDays: { type: 'number', description: 'Days notice required for non-renewal' },
    revenueShare: { type: 'number', description: 'Revenue share percentage' },
    referralFee: { type: 'number', description: 'Referral fee amount or percentage' },
    minimumCommitment: { type: 'number', description: 'Minimum annual commitment' },
    exclusivity: { type: 'boolean', description: 'Exclusive partnership' },
    exclusivityTerms: { type: 'string', description: 'Exclusivity terms', optional: true },
    territories: { type: 'string[]', description: 'Geographic territories' },
    products: { type: 'string[]', description: 'Products covered' },
    useCase: { type: 'string', description: 'Primary use case or focus' },
    targetRevenue: { type: 'number', description: 'Target revenue goal' },
    actualRevenue: { type: 'number', description: 'Actual revenue achieved' },
    targetDeals: { type: 'number', description: 'Target number of deals' },
    actualDeals: { type: 'number', description: 'Actual deals closed' },
    ndaRequired: { type: 'boolean', description: 'NDA required' },
    ndaSigned: { type: 'boolean', description: 'NDA signed' },
    contractSigned: { type: 'boolean', description: 'Contract signed' },
    jointMarketingBudget: { type: 'number', description: 'Joint marketing budget', optional: true },
    coMarketingApproved: { type: 'boolean', description: 'Co-marketing approved' },
    integrationRequired: { type: 'boolean', description: 'Technical integration required' },
    integrationComplete: { type: 'boolean', description: 'Integration completed' },
    internalOwner: { type: 'string', description: 'Internal partnership owner' },
    partnerOwner: { type: 'string', description: 'Partner side owner' },
    executiveSponsor: { type: 'string', description: 'Executive sponsor' },
    healthScore: { type: 'number', description: 'Partnership health score' },
    lastReviewDate: { type: 'date', description: 'Last partnership review' },
    nextReviewDate: { type: 'date', description: 'Next scheduled review' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Partnership tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    partner: { type: 'partner', description: 'Partner organization', backref: 'partnerships', required: true },
    contract: { type: 'contract', description: 'Partnership contract', backref: 'partnership' },
    deals: { type: 'deal[]', description: 'Partnership deals', backref: 'partnership' },
    campaigns: { type: 'campaign[]', description: 'Joint campaigns', backref: 'partnership' },
    integrations: { type: 'integration[]', description: 'Technical integrations', backref: 'partnership' },
    milestones: { type: 'milestone[]', description: 'Partnership milestones', backref: 'partnership' },
  },
  actions: ['create', 'update', 'propose', 'negotiate', 'approve', 'reject', 'activate', 'pause', 'resume', 'extend', 'terminate', 'renew', 'review'],
  events: ['created', 'updated', 'proposed', 'negotiated', 'approved', 'rejected', 'activated', 'paused', 'resumed', 'extended', 'terminated', 'renewed', 'reviewed'],
}

export const Integration: Noun = {
  singular: 'integration',
  plural: 'integrations',
  description: 'A technical integration with a partner or third-party system',
  properties: {
    name: { type: 'string', description: 'Integration name' },
    type: { type: 'string', description: 'Type of integration', examples: ['API', 'webhook', 'SDK', 'embed', 'SSO', 'data-sync', 'marketplace'] },
    status: { type: 'string', description: 'Integration status', examples: ['planning', 'development', 'testing', 'staging', 'live', 'deprecated', 'disabled'] },
    description: { type: 'string', description: 'Integration description' },
    direction: { type: 'string', description: 'Data flow direction', examples: ['inbound', 'outbound', 'bidirectional'] },
    category: { type: 'string', description: 'Integration category', examples: ['CRM', 'ERP', 'marketing', 'analytics', 'payment', 'communication', 'productivity'] },
    authentication: { type: 'string', description: 'Authentication method', examples: ['API-key', 'OAuth2', 'JWT', 'basic', 'certificate', 'SAML'] },
    endpoint: { type: 'string', description: 'API endpoint or URL' },
    version: { type: 'string', description: 'Integration version' },
    documentation: { type: 'string', description: 'Documentation URL' },
    syncFrequency: { type: 'string', description: 'Data sync frequency', examples: ['real-time', 'hourly', 'daily', 'weekly', 'on-demand'] },
    dataMapping: { type: 'object', description: 'Field mapping configuration', optional: true },
    rateLimits: { type: 'object', description: 'Rate limiting configuration', optional: true },
    lastSyncDate: { type: 'date', description: 'Last successful sync' },
    lastSyncStatus: { type: 'string', description: 'Last sync status', examples: ['success', 'partial', 'failed'] },
    errorCount: { type: 'number', description: 'Recent error count' },
    recordsProcessed: { type: 'number', description: 'Total records processed' },
    enabled: { type: 'boolean', description: 'Integration enabled' },
    sandboxAvailable: { type: 'boolean', description: 'Sandbox environment available' },
    productionReady: { type: 'boolean', description: 'Ready for production' },
    maintainer: { type: 'string', description: 'Internal maintainer' },
    supportContact: { type: 'string', description: 'Support contact' },
    launchDate: { type: 'date', description: 'Integration launch date' },
    deprecationDate: { type: 'date', description: 'Planned deprecation date', optional: true },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Integration tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    partner: { type: 'partner', description: 'Integration partner', backref: 'integrations' },
    partnership: { type: 'partnership', description: 'Related partnership', backref: 'integrations' },
    product: { type: 'product', description: 'Product integrated', backref: 'integrations' },
  },
  actions: ['create', 'update', 'develop', 'test', 'deploy', 'enable', 'disable', 'sync', 'debug', 'deprecate', 'version'],
  events: ['created', 'updated', 'developed', 'tested', 'deployed', 'enabled', 'disabled', 'synced', 'debugged', 'deprecated', 'versioned'],
}

export const Reseller: Noun = {
  singular: 'reseller',
  plural: 'resellers',
  description: 'A reseller partner who sells products on behalf of the organization',
  properties: {
    name: { type: 'string', description: 'Reseller name' },
    type: { type: 'string', description: 'Type of reseller', examples: ['VAR', 'distributor', 'MSP', 'SI', 'retail', 'online'] },
    tier: { type: 'string', description: 'Reseller tier', examples: ['authorized', 'premier', 'elite', 'master'] },
    status: { type: 'string', description: 'Reseller status', examples: ['prospect', 'onboarding', 'active', 'suspended', 'terminated'] },
    region: { type: 'string', description: 'Primary region' },
    territories: { type: 'string[]', description: 'Authorized territories' },
    verticals: { type: 'string[]', description: 'Industry verticals' },
    products: { type: 'string[]', description: 'Authorized products' },
    discountLevel: { type: 'number', description: 'Discount percentage from list price' },
    margin: { type: 'number', description: 'Expected margin percentage' },
    minimumOrder: { type: 'number', description: 'Minimum order value' },
    creditLimit: { type: 'number', description: 'Credit limit' },
    paymentTerms: { type: 'string', description: 'Payment terms' },
    quota: { type: 'number', description: 'Annual sales quota' },
    yearToDateSales: { type: 'number', description: 'Year to date sales' },
    totalSales: { type: 'number', description: 'Total lifetime sales' },
    dealCount: { type: 'number', description: 'Total deals closed' },
    averageDealSize: { type: 'number', description: 'Average deal size' },
    certifiedReps: { type: 'number', description: 'Number of certified sales reps' },
    technicalCerts: { type: 'number', description: 'Number of technical certifications' },
    enablementComplete: { type: 'boolean', description: 'Enablement training completed' },
    portalAccess: { type: 'boolean', description: 'Has reseller portal access' },
    dealRegistration: { type: 'boolean', description: 'Can register deals' },
    coopFunds: { type: 'number', description: 'Co-op marketing funds available' },
    mdf: { type: 'number', description: 'Market development funds' },
    lastOrderDate: { type: 'date', description: 'Last order date' },
    startDate: { type: 'date', description: 'Partnership start date' },
    renewalDate: { type: 'date', description: 'Next renewal date' },
    notes: { type: 'string', description: 'Internal notes', optional: true },
    tags: { type: 'string[]', description: 'Reseller tags' },
    metadata: { type: 'object', description: 'Additional metadata', optional: true },
  },
  relationships: {
    partner: { type: 'partner', description: 'Parent partner record', backref: 'reseller' },
    deals: { type: 'deal[]', description: 'Reseller deals', backref: 'reseller' },
    orders: { type: 'order[]', description: 'Purchase orders', backref: 'reseller' },
    customers: { type: 'customer[]', description: 'End customers', backref: 'reseller' },
    contacts: { type: 'contact[]', description: 'Reseller contacts', backref: 'reseller' },
  },
  actions: ['create', 'update', 'onboard', 'activate', 'suspend', 'terminate', 'upgrade', 'downgrade', 'certify', 'enable', 'allocateFunds'],
  events: ['created', 'updated', 'onboarded', 'activated', 'suspended', 'terminated', 'upgraded', 'downgraded', 'certified', 'enabled', 'fundsAllocated'],
}

// Export all partnership entities
export const PartnershipEntities = {
  Partner,
  Vendor,
  Affiliate,
  Partnership,
  Integration,
  Reseller,
}

export default PartnershipEntities