@salesmind-ai/design-system 0.1.7 → 0.1.9

package/dist/audit-CiyPkxk1.d.cts

@@ -0,0 +1,194 @@
+type UtmSource = 'linkedin' | 'whatsapp' | 'intercom' | 'email' | 'website' | 'app' | 'chromeStore' | 'stripe' | 'direct';
+type UtmMediumMessaging = 'dm' | 'group' | 'email' | 'inAppChat' | 'organicPost' | 'paidAd' | 'qrCode' | 'redirect' | 'storeListing';
+type UtmMediumAppPage = 'appHome' | 'appDashboard' | 'appInbox' | 'appContacts' | 'appCampaigns' | 'appSettings' | 'appBilling' | 'appCheckout' | 'appOnboarding' | 'appSupport' | 'appCalendar';
+type UtmMediumWebPage = 'webHome' | 'webDemo' | 'webPricing' | 'webFeatures' | 'webUseCase' | 'webSolution' | 'webIndustry' | 'webIntegrations' | 'webBlog' | 'webBlogPost' | 'webLanding' | 'webComparison' | 'webCaseStudy' | 'webAbout' | 'webContact' | 'webCareers' | 'webLegal' | 'webDocs' | 'webAffiliate';
+type UtmMedium = UtmMediumMessaging | UtmMediumAppPage | UtmMediumWebPage;
+type UtmCampaign = 'discoveryCall' | 'demo' | 'trial' | 'onboarding' | 'upgrade' | 'renewal' | 'retention' | 'accountSupport' | 'supportCall' | 'partnerCall' | 'hiring' | 'interviewCall';
+type UtmTerm = 'julienGadea' | 'bramSmith' | 'florentDupont' | 'sawLin' | 'evaSupport' | 'team' | 'auto';
+type UtmContent = 'ctaPrimary' | 'ctaSecondary' | 'ctaHeader' | 'ctaFooter' | 'ctaInline' | 'buttonPrimary' | 'buttonSecondary' | 'banner' | 'popup' | 'variantA' | 'variantB' | 'variantC';
+/** Core UTM parameter set. source + medium + campaign are always required. */
+interface UtmParams {
+    source: UtmSource;
+    medium: UtmMedium;
+    campaign: UtmCampaign;
+    term?: UtmTerm;
+    content?: UtmContent;
+}
+/** Partial overrides for UTM params (used when merging context). */
+type UtmOverrides = Partial<UtmParams>;
+/** Sources that require seller attribution (utm_term) for outbound manual sharing. */
+type UtmSourceRequiringSeller = 'linkedin' | 'whatsapp' | 'intercom' | 'email';
+/** CRM first-touch fields. Once set, these must never be overwritten. */
+interface FirstTouchAttribution {
+    firstTouchSource: UtmSource;
+    firstTouchMedium: UtmMedium;
+    firstTouchCampaign: UtmCampaign;
+    firstTouchSeller: UtmTerm | null;
+}
+type UrlClassification = 'internal' | 'external' | 'system' | 'asset' | 'protocol' | 'conversion';
+type UtmConfidence = 'valid' | 'corrected' | 'blocked';
+type UtmComplianceStatus = 'compliant' | 'corrected' | 'blocked';
+interface UtmAuditEntry {
+    url: string;
+    utmString: string;
+    generatorContext: string;
+    sellerAttribution: string | null;
+    timestamp: string;
+    confidence: UtmConfidence;
+}
+interface UtmComplianceResult {
+    status: UtmComplianceStatus;
+    url: string;
+    params: Partial<UtmParams> | null;
+    errors: string[];
+}
+interface UtmBlockedError {
+    status: 'UTM_COMPLIANCE_BLOCKED';
+    reason: string;
+    requiredFix: string;
+    correctedExample: string | null;
+}
+
+declare const UTM_SOURCES: readonly UtmSource[];
+declare const UTM_MEDIUMS_MESSAGING: readonly UtmMediumMessaging[];
+declare const UTM_MEDIUMS_APP: readonly UtmMediumAppPage[];
+declare const UTM_MEDIUMS_WEB: readonly UtmMediumWebPage[];
+declare const UTM_MEDIUMS_ALL: readonly UtmMedium[];
+declare const UTM_CAMPAIGNS: readonly UtmCampaign[];
+declare const UTM_TERMS: readonly UtmTerm[];
+declare const UTM_CONTENTS: readonly UtmContent[];
+declare const UTM_SOURCES_REQUIRING_SELLER: readonly UtmSourceRequiringSeller[];
+
+/**
+ * Build a URL with UTM parameters appended.
+ *
+ * - Supports both absolute and relative URLs.
+ * - Preserves existing query parameters and hash fragments.
+ * - Always emits params in canonical order: source → medium → campaign → term → content.
+ * - Omits optional params (term, content) when undefined.
+ *
+ * @example
+ * buildUtmUrl('https://app.sales-mind.ai/register', { source: 'linkedin', medium: 'dm', campaign: 'discoveryCall' })
+ * // → 'https://app.sales-mind.ai/register?utm_source=linkedin&utm_medium=dm&utm_campaign=discoveryCall'
+ *
+ * buildUtmUrl('/pricing', { source: 'website', medium: 'webHome', campaign: 'trial' })
+ * // → '/pricing?utm_source=website&utm_medium=webHome&utm_campaign=trial'
+ */
+declare function buildUtmUrl(baseUrl: string, params: UtmParams): string;
+
+/**
+ * Validate a single UTM field name + value pair against the governed enums.
+ *
+ * @param field - The UTM field name (e.g., 'source', 'medium', 'campaign', 'term', 'content')
+ * @param value - The value to validate
+ * @returns true if the value is in the corresponding enum
+ */
+declare function validateUtmField(field: string, value: string): boolean;
+/**
+ * Validate a complete or partial UtmParams object.
+ *
+ * Returns true only if:
+ * - source, medium, and campaign are all present
+ * - All present values match their respective enums
+ * - Optional fields (term, content) match their enums if provided
+ */
+declare function isValidUtmParams(params: Partial<UtmParams>): boolean;
+/**
+ * Full compliance validation for a URL + UTM params combination.
+ *
+ * Checks:
+ * 1. URL classification (does it require UTMs?)
+ * 2. All required params present
+ * 3. All values match governed enums
+ * 4. No illegal characters (spaces, underscores, hyphens, emojis, ALL CAPS)
+ * 5. camelCase format enforcement
+ */
+declare function validateCompliance(url: string, params?: Partial<UtmParams> | null): UtmComplianceResult;
+/**
+ * Classify a URL and enforce UTM compliance in a single call.
+ */
+declare function classifyAndEnforce(url: string, params?: Partial<UtmParams>): UtmComplianceResult;
+/**
+ * Build a structured blocked-error response.
+ */
+declare function buildBlockedError(reason: string, url?: string): UtmBlockedError;
+
+/**
+ * Classify a URL to determine its type.
+ *
+ * Classification order (first match wins):
+ * 1. Protocol links (mailto, tel, anchor)
+ * 2. Static assets
+ * 3. System endpoints (API, webhooks, OAuth)
+ * 4. Conversion destinations (Calendly, Stripe, Chrome Store)
+ * 5. Internal (*.sales-mind.ai)
+ * 6. External (everything else)
+ */
+declare function classifyUrl(url: string): UrlClassification;
+/**
+ * Determine whether a URL requires UTM parameters.
+ *
+ * UTMs are mandatory for:
+ * - External third-party destinations
+ * - Conversion destinations (Calendly, Stripe, Chrome Web Store)
+ *
+ * UTMs are NOT required for:
+ * - Internal navigation
+ * - System endpoints
+ * - Static assets
+ * - Protocol links
+ */
+declare function requiresUtm(url: string): boolean;
+/**
+ * Check if a URL is explicitly exempt from UTM requirements.
+ */
+declare function isUtmExempt(url: string): boolean;
+
+/**
+ * Parse UTM parameters from a URL search string.
+ *
+ * Validates each field against governed enums:
+ * - source: must be in UTM_SOURCES (invalid → excluded)
+ * - medium: accepted as-is (no enum validation — medium is loosely parsed)
+ * - campaign: must be in UTM_CAMPAIGNS (invalid → excluded)
+ * - term: must be in UTM_TERMS (invalid → excluded)
+ * - content: must be in UTM_CONTENTS (invalid → excluded)
+ *
+ * @param search - URL search string, with or without leading '?'
+ * @returns Partial<UtmParams> with only valid fields included
+ */
+declare function parseUtmParams(search: string): Partial<UtmParams>;
+/**
+ * Map UTM params to CRM first-touch attribution fields.
+ *
+ * On first lead capture:
+ * - utm_source  → firstTouchSource
+ * - utm_medium  → firstTouchMedium
+ * - utm_campaign → firstTouchCampaign
+ * - utm_term    → firstTouchSeller (null if absent)
+ *
+ * utm_content is intentionally excluded from attribution.
+ * These fields must be persisted permanently and never overwritten.
+ */
+declare function toFirstTouchAttribution(params: UtmParams): FirstTouchAttribution;
+/**
+ * Check if a source requires seller attribution (utm_term).
+ *
+ * Sources requiring seller: linkedin, whatsapp, intercom, email
+ * These are manual outbound channels where individual seller tracking matters.
+ */
+declare function requiresSellerAttribution(source: UtmSource): boolean;
+
+/**
+ * Create a structured audit log entry for a generated/validated link.
+ *
+ * Every time a link is generated, an audit entry should be logged with:
+ * - URL and full UTM string
+ * - Generator context (component, agent, or tool that created the link)
+ * - Seller attribution (from utm_term)
+ * - Timestamp
+ * - Confidence flag (valid / corrected / blocked)
+ */
+declare function createAuditEntry(url: string, params: Partial<UtmParams> | null, generatorContext: string, confidence: UtmConfidence): UtmAuditEntry;
+
+export { buildUtmUrl as A, classifyAndEnforce as B, classifyUrl as C, createAuditEntry as D, isUtmExempt as E, type FirstTouchAttribution as F, isValidUtmParams as G, parseUtmParams as H, requiresSellerAttribution as I, requiresUtm as J, toFirstTouchAttribution as K, validateCompliance as L, validateUtmField as M, type UtmParams as U, UTM_CAMPAIGNS as a, UTM_CONTENTS as b, UTM_MEDIUMS_ALL as c, UTM_MEDIUMS_APP as d, UTM_MEDIUMS_MESSAGING as e, UTM_MEDIUMS_WEB as f, UTM_SOURCES as g, UTM_SOURCES_REQUIRING_SELLER as h, UTM_TERMS as i, type UrlClassification as j, type UtmAuditEntry as k, type UtmBlockedError as l, type UtmCampaign as m, type UtmComplianceResult as n, type UtmComplianceStatus as o, type UtmConfidence as p, type UtmContent as q, type UtmMedium as r, type UtmMediumAppPage as s, type UtmMediumMessaging as t, type UtmMediumWebPage as u, type UtmOverrides as v, type UtmSource as w, type UtmSourceRequiringSeller as x, type UtmTerm as y, buildBlockedError as z };

package/dist/audit-CiyPkxk1.d.ts

@@ -0,0 +1,194 @@
+type UtmSource = 'linkedin' | 'whatsapp' | 'intercom' | 'email' | 'website' | 'app' | 'chromeStore' | 'stripe' | 'direct';
+type UtmMediumMessaging = 'dm' | 'group' | 'email' | 'inAppChat' | 'organicPost' | 'paidAd' | 'qrCode' | 'redirect' | 'storeListing';
+type UtmMediumAppPage = 'appHome' | 'appDashboard' | 'appInbox' | 'appContacts' | 'appCampaigns' | 'appSettings' | 'appBilling' | 'appCheckout' | 'appOnboarding' | 'appSupport' | 'appCalendar';
+type UtmMediumWebPage = 'webHome' | 'webDemo' | 'webPricing' | 'webFeatures' | 'webUseCase' | 'webSolution' | 'webIndustry' | 'webIntegrations' | 'webBlog' | 'webBlogPost' | 'webLanding' | 'webComparison' | 'webCaseStudy' | 'webAbout' | 'webContact' | 'webCareers' | 'webLegal' | 'webDocs' | 'webAffiliate';
+type UtmMedium = UtmMediumMessaging | UtmMediumAppPage | UtmMediumWebPage;
+type UtmCampaign = 'discoveryCall' | 'demo' | 'trial' | 'onboarding' | 'upgrade' | 'renewal' | 'retention' | 'accountSupport' | 'supportCall' | 'partnerCall' | 'hiring' | 'interviewCall';
+type UtmTerm = 'julienGadea' | 'bramSmith' | 'florentDupont' | 'sawLin' | 'evaSupport' | 'team' | 'auto';
+type UtmContent = 'ctaPrimary' | 'ctaSecondary' | 'ctaHeader' | 'ctaFooter' | 'ctaInline' | 'buttonPrimary' | 'buttonSecondary' | 'banner' | 'popup' | 'variantA' | 'variantB' | 'variantC';
+/** Core UTM parameter set. source + medium + campaign are always required. */
+interface UtmParams {
+    source: UtmSource;
+    medium: UtmMedium;
+    campaign: UtmCampaign;
+    term?: UtmTerm;
+    content?: UtmContent;
+}
+/** Partial overrides for UTM params (used when merging context). */
+type UtmOverrides = Partial<UtmParams>;
+/** Sources that require seller attribution (utm_term) for outbound manual sharing. */
+type UtmSourceRequiringSeller = 'linkedin' | 'whatsapp' | 'intercom' | 'email';
+/** CRM first-touch fields. Once set, these must never be overwritten. */
+interface FirstTouchAttribution {
+    firstTouchSource: UtmSource;
+    firstTouchMedium: UtmMedium;
+    firstTouchCampaign: UtmCampaign;
+    firstTouchSeller: UtmTerm | null;
+}
+type UrlClassification = 'internal' | 'external' | 'system' | 'asset' | 'protocol' | 'conversion';
+type UtmConfidence = 'valid' | 'corrected' | 'blocked';
+type UtmComplianceStatus = 'compliant' | 'corrected' | 'blocked';
+interface UtmAuditEntry {
+    url: string;
+    utmString: string;
+    generatorContext: string;
+    sellerAttribution: string | null;
+    timestamp: string;
+    confidence: UtmConfidence;
+}
+interface UtmComplianceResult {
+    status: UtmComplianceStatus;
+    url: string;
+    params: Partial<UtmParams> | null;
+    errors: string[];
+}
+interface UtmBlockedError {
+    status: 'UTM_COMPLIANCE_BLOCKED';
+    reason: string;
+    requiredFix: string;
+    correctedExample: string | null;
+}
+
+declare const UTM_SOURCES: readonly UtmSource[];
+declare const UTM_MEDIUMS_MESSAGING: readonly UtmMediumMessaging[];
+declare const UTM_MEDIUMS_APP: readonly UtmMediumAppPage[];
+declare const UTM_MEDIUMS_WEB: readonly UtmMediumWebPage[];
+declare const UTM_MEDIUMS_ALL: readonly UtmMedium[];
+declare const UTM_CAMPAIGNS: readonly UtmCampaign[];
+declare const UTM_TERMS: readonly UtmTerm[];
+declare const UTM_CONTENTS: readonly UtmContent[];
+declare const UTM_SOURCES_REQUIRING_SELLER: readonly UtmSourceRequiringSeller[];
+
+/**
+ * Build a URL with UTM parameters appended.
+ *
+ * - Supports both absolute and relative URLs.
+ * - Preserves existing query parameters and hash fragments.
+ * - Always emits params in canonical order: source → medium → campaign → term → content.
+ * - Omits optional params (term, content) when undefined.
+ *
+ * @example
+ * buildUtmUrl('https://app.sales-mind.ai/register', { source: 'linkedin', medium: 'dm', campaign: 'discoveryCall' })
+ * // → 'https://app.sales-mind.ai/register?utm_source=linkedin&utm_medium=dm&utm_campaign=discoveryCall'
+ *
+ * buildUtmUrl('/pricing', { source: 'website', medium: 'webHome', campaign: 'trial' })
+ * // → '/pricing?utm_source=website&utm_medium=webHome&utm_campaign=trial'
+ */
+declare function buildUtmUrl(baseUrl: string, params: UtmParams): string;
+
+/**
+ * Validate a single UTM field name + value pair against the governed enums.
+ *
+ * @param field - The UTM field name (e.g., 'source', 'medium', 'campaign', 'term', 'content')
+ * @param value - The value to validate
+ * @returns true if the value is in the corresponding enum
+ */
+declare function validateUtmField(field: string, value: string): boolean;
+/**
+ * Validate a complete or partial UtmParams object.
+ *
+ * Returns true only if:
+ * - source, medium, and campaign are all present
+ * - All present values match their respective enums
+ * - Optional fields (term, content) match their enums if provided
+ */
+declare function isValidUtmParams(params: Partial<UtmParams>): boolean;
+/**
+ * Full compliance validation for a URL + UTM params combination.
+ *
+ * Checks:
+ * 1. URL classification (does it require UTMs?)
+ * 2. All required params present
+ * 3. All values match governed enums
+ * 4. No illegal characters (spaces, underscores, hyphens, emojis, ALL CAPS)
+ * 5. camelCase format enforcement
+ */
+declare function validateCompliance(url: string, params?: Partial<UtmParams> | null): UtmComplianceResult;
+/**
+ * Classify a URL and enforce UTM compliance in a single call.
+ */
+declare function classifyAndEnforce(url: string, params?: Partial<UtmParams>): UtmComplianceResult;
+/**
+ * Build a structured blocked-error response.
+ */
+declare function buildBlockedError(reason: string, url?: string): UtmBlockedError;
+
+/**
+ * Classify a URL to determine its type.
+ *
+ * Classification order (first match wins):
+ * 1. Protocol links (mailto, tel, anchor)
+ * 2. Static assets
+ * 3. System endpoints (API, webhooks, OAuth)
+ * 4. Conversion destinations (Calendly, Stripe, Chrome Store)
+ * 5. Internal (*.sales-mind.ai)
+ * 6. External (everything else)
+ */
+declare function classifyUrl(url: string): UrlClassification;
+/**
+ * Determine whether a URL requires UTM parameters.
+ *
+ * UTMs are mandatory for:
+ * - External third-party destinations
+ * - Conversion destinations (Calendly, Stripe, Chrome Web Store)
+ *
+ * UTMs are NOT required for:
+ * - Internal navigation
+ * - System endpoints
+ * - Static assets
+ * - Protocol links
+ */
+declare function requiresUtm(url: string): boolean;
+/**
+ * Check if a URL is explicitly exempt from UTM requirements.
+ */
+declare function isUtmExempt(url: string): boolean;
+
+/**
+ * Parse UTM parameters from a URL search string.
+ *
+ * Validates each field against governed enums:
+ * - source: must be in UTM_SOURCES (invalid → excluded)
+ * - medium: accepted as-is (no enum validation — medium is loosely parsed)
+ * - campaign: must be in UTM_CAMPAIGNS (invalid → excluded)
+ * - term: must be in UTM_TERMS (invalid → excluded)
+ * - content: must be in UTM_CONTENTS (invalid → excluded)
+ *
+ * @param search - URL search string, with or without leading '?'
+ * @returns Partial<UtmParams> with only valid fields included
+ */
+declare function parseUtmParams(search: string): Partial<UtmParams>;
+/**
+ * Map UTM params to CRM first-touch attribution fields.
+ *
+ * On first lead capture:
+ * - utm_source  → firstTouchSource
+ * - utm_medium  → firstTouchMedium
+ * - utm_campaign → firstTouchCampaign
+ * - utm_term    → firstTouchSeller (null if absent)
+ *
+ * utm_content is intentionally excluded from attribution.
+ * These fields must be persisted permanently and never overwritten.
+ */
+declare function toFirstTouchAttribution(params: UtmParams): FirstTouchAttribution;
+/**
+ * Check if a source requires seller attribution (utm_term).
+ *
+ * Sources requiring seller: linkedin, whatsapp, intercom, email
+ * These are manual outbound channels where individual seller tracking matters.
+ */
+declare function requiresSellerAttribution(source: UtmSource): boolean;
+
+/**
+ * Create a structured audit log entry for a generated/validated link.
+ *
+ * Every time a link is generated, an audit entry should be logged with:
+ * - URL and full UTM string
+ * - Generator context (component, agent, or tool that created the link)
+ * - Seller attribution (from utm_term)
+ * - Timestamp
+ * - Confidence flag (valid / corrected / blocked)
+ */
+declare function createAuditEntry(url: string, params: Partial<UtmParams> | null, generatorContext: string, confidence: UtmConfidence): UtmAuditEntry;
+
+export { buildUtmUrl as A, classifyAndEnforce as B, classifyUrl as C, createAuditEntry as D, isUtmExempt as E, type FirstTouchAttribution as F, isValidUtmParams as G, parseUtmParams as H, requiresSellerAttribution as I, requiresUtm as J, toFirstTouchAttribution as K, validateCompliance as L, validateUtmField as M, type UtmParams as U, UTM_CAMPAIGNS as a, UTM_CONTENTS as b, UTM_MEDIUMS_ALL as c, UTM_MEDIUMS_APP as d, UTM_MEDIUMS_MESSAGING as e, UTM_MEDIUMS_WEB as f, UTM_SOURCES as g, UTM_SOURCES_REQUIRING_SELLER as h, UTM_TERMS as i, type UrlClassification as j, type UtmAuditEntry as k, type UtmBlockedError as l, type UtmCampaign as m, type UtmComplianceResult as n, type UtmComplianceStatus as o, type UtmConfidence as p, type UtmContent as q, type UtmMedium as r, type UtmMediumAppPage as s, type UtmMediumMessaging as t, type UtmMediumWebPage as u, type UtmOverrides as v, type UtmSource as w, type UtmSourceRequiringSeller as x, type UtmTerm as y, buildBlockedError as z };

package/dist/core/index.cjs

@@ -4199,5 +4199,5 @@ exports.useNumberFormat = useNumberFormat;
 exports.useRelativeTime = useRelativeTime;
 exports.useTextDirection = useTextDirection;
 exports.useToast = useToast;
-//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.cjs.map