@dalmore/api-contracts 0.0.0-dev.2cea8e5 → 0.0.0-dev.2fec89f

package/common/types/attribution.types.d.ts

@@ -0,0 +1,578 @@
+import { z } from 'zod';
+import { Request } from 'express';
+/**
+ * UTM Source enum - Common marketing sources
+ */
+export declare enum UtmSource {
+    GOOGLE = "GOOGLE",
+    FACEBOOK = "FACEBOOK",
+    TWITTER = "TWITTER",
+    LINKEDIN = "LINKEDIN",
+    INSTAGRAM = "INSTAGRAM",
+    TIKTOK = "TIKTOK",
+    EMAIL = "EMAIL",
+    DIRECT = "DIRECT",
+    ORGANIC = "ORGANIC",
+    REFERRAL = "REFERRAL",
+    OTHER = "OTHER"
+}
+/**
+ * Zod enum schema for UTM Source
+ */
+export declare const UtmSourceZod: z.ZodNativeEnum<typeof UtmSource>;
+/**
+ * Attribution Touch Data (from cookie)
+ * This represents the raw data structure stored in the cookie
+ * Platform click IDs are stored as a record: { "gclid": "abc123", "fbclid": "xyz789", "ttclid": "def456" }
+ */
+export declare const AttributionTouchDataSchema: z.ZodObject<{
+    utmSource: z.ZodNativeEnum<typeof UtmSource>;
+    utmMedium: z.ZodString;
+    utmCampaign: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    utmTerm: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    utmContent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platformClickIds: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    landingPage: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+    documentReferrer: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+}, "strip", z.ZodTypeAny, {
+    utmSource: UtmSource;
+    utmMedium: string;
+    landingPage?: string | null | undefined;
+    utmCampaign?: string | null | undefined;
+    utmTerm?: string | null | undefined;
+    utmContent?: string | null | undefined;
+    platformClickIds?: Record<string, string> | null | undefined;
+    ref?: string | null | undefined;
+    documentReferrer?: string | null | undefined;
+}, {
+    utmSource: UtmSource;
+    utmMedium: string;
+    landingPage?: string | null | undefined;
+    utmCampaign?: string | null | undefined;
+    utmTerm?: string | null | undefined;
+    utmContent?: string | null | undefined;
+    platformClickIds?: Record<string, string> | null | undefined;
+    ref?: string | null | undefined;
+    documentReferrer?: string | null | undefined;
+}>;
+export type AttributionTouchData = z.infer<typeof AttributionTouchDataSchema>;
+/**
+ * Attribution Touch Response Schema
+ * This represents the entity structure returned from the API
+ */
+export declare const AttributionTouchSchema: z.ZodObject<{
+    id: z.ZodString;
+    __entity: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+    updatedAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+    deletedAt: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodDate]>>;
+} & {
+    utmSource: z.ZodNullable<z.ZodNativeEnum<typeof UtmSource>>;
+    utmMedium: z.ZodNullable<z.ZodString>;
+    utmCampaign: z.ZodNullable<z.ZodString>;
+    utmTerm: z.ZodNullable<z.ZodString>;
+    utmContent: z.ZodNullable<z.ZodString>;
+    platformClickIds: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+    ref: z.ZodNullable<z.ZodString>;
+    landingPage: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    documentReferrer: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    isFirstTouch: z.ZodBoolean;
+    isLastTouch: z.ZodBoolean;
+    touchCount: z.ZodNumber;
+    userId: z.ZodString;
+    accountId: z.ZodString;
+    tradeId: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+    deletedAt: string | Date | null;
+    accountId: string;
+    userId: string;
+    tradeId: string | null;
+    landingPage: string | null;
+    utmSource: UtmSource | null;
+    utmMedium: string | null;
+    utmCampaign: string | null;
+    utmTerm: string | null;
+    utmContent: string | null;
+    platformClickIds: Record<string, string> | null;
+    ref: string | null;
+    documentReferrer: string | null;
+    isFirstTouch: boolean;
+    isLastTouch: boolean;
+    touchCount: number;
+    __entity?: string | undefined;
+}, {
+    id: string;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+    deletedAt: string | Date | null;
+    accountId: string;
+    userId: string;
+    tradeId: string | null;
+    landingPage: string | null;
+    utmSource: UtmSource | null;
+    utmMedium: string | null;
+    utmCampaign: string | null;
+    utmTerm: string | null;
+    utmContent: string | null;
+    platformClickIds: Record<string, string> | null;
+    ref: string | null;
+    documentReferrer: string | null;
+    isFirstTouch: boolean;
+    isLastTouch: boolean;
+    touchCount: number;
+    __entity?: string | undefined;
+}>;
+export type AttributionTouch = z.infer<typeof AttributionTouchSchema>;
+/**
+ * Cookie name constant for attribution data
+ */
+export declare const ATTRIBUTION_COOKIE_NAME = "dalmore_attribution";
+/**
+ * Cookie parsing helper type
+ */
+export type AttributionCookie = AttributionTouchData;
+/**
+ * Parse attribution cookie from request
+ *
+ * Uses Zod's safeParse to validate and parse the cookie data.
+ * Returns null if cookie is not found or validation fails.
+ *
+ * @param request - Express request object
+ * @returns Parsed and validated attribution data or null if not found/invalid
+ */
+export declare function parseAttributionCookie(request: Request): AttributionTouchData | null;
+/**
+ * Attribution Touches Include Options
+ */
+export declare const attributionTouchesInclude: z.ZodEnum<["user", "account", "trade"]>;
+/**
+ * @description Query parameters for including related entities
+ */
+export declare const AttributionTouchesIncludeQuery: z.ZodObject<{
+    include: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>;
+}, "strip", z.ZodTypeAny, {
+    include: string[];
+}, {
+    include?: string | undefined;
+}>;
+export interface AttributionTouchesIncludeQuery extends z.infer<typeof AttributionTouchesIncludeQuery> {
+}
+/**
+ * Attribution Touches Filters
+ */
+export declare const AttributionTouchesFiltersZod: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    tradeId: z.ZodOptional<z.ZodString>;
+    isFirstTouch: z.ZodOptional<z.ZodBoolean>;
+    isLastTouch: z.ZodOptional<z.ZodBoolean>;
+    utmSource: z.ZodOptional<z.ZodNativeEnum<typeof UtmSource>>;
+    utmMedium: z.ZodOptional<z.ZodString>;
+    utmCampaign: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    accountId?: string | undefined;
+    userId?: string | undefined;
+    tradeId?: string | undefined;
+    utmSource?: UtmSource | undefined;
+    utmMedium?: string | undefined;
+    utmCampaign?: string | undefined;
+    isFirstTouch?: boolean | undefined;
+    isLastTouch?: boolean | undefined;
+}, {
+    accountId?: string | undefined;
+    userId?: string | undefined;
+    tradeId?: string | undefined;
+    utmSource?: UtmSource | undefined;
+    utmMedium?: string | undefined;
+    utmCampaign?: string | undefined;
+    isFirstTouch?: boolean | undefined;
+    isLastTouch?: boolean | undefined;
+}>;
+export type AttributionTouchesFilters = z.infer<typeof AttributionTouchesFiltersZod>;
+/**
+ * Paginated Attribution Touch Response
+ */
+export declare const IPaginatedAttributionTouch: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        __entity: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        updatedAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        deletedAt: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodDate]>>;
+    } & {
+        utmSource: z.ZodNullable<z.ZodNativeEnum<typeof UtmSource>>;
+        utmMedium: z.ZodNullable<z.ZodString>;
+        utmCampaign: z.ZodNullable<z.ZodString>;
+        utmTerm: z.ZodNullable<z.ZodString>;
+        utmContent: z.ZodNullable<z.ZodString>;
+        platformClickIds: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+        ref: z.ZodNullable<z.ZodString>;
+        landingPage: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        documentReferrer: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        isFirstTouch: z.ZodBoolean;
+        isLastTouch: z.ZodBoolean;
+        touchCount: z.ZodNumber;
+        userId: z.ZodString;
+        accountId: z.ZodString;
+        tradeId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }>, "many">;
+    meta: z.ZodObject<{
+        itemCount: z.ZodNumber;
+        totalItems: z.ZodOptional<z.ZodNumber>;
+        itemsPerPage: z.ZodNumber;
+        totalPages: z.ZodOptional<z.ZodNumber>;
+        currentPage: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        itemCount: number;
+        itemsPerPage: number;
+        currentPage: number;
+        totalItems?: number | undefined;
+        totalPages?: number | undefined;
+    }, {
+        itemCount: number;
+        itemsPerPage: number;
+        currentPage: number;
+        totalItems?: number | undefined;
+        totalPages?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }[];
+    meta: {
+        itemCount: number;
+        itemsPerPage: number;
+        currentPage: number;
+        totalItems?: number | undefined;
+        totalPages?: number | undefined;
+    };
+}, {
+    items: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }[];
+    meta: {
+        itemCount: number;
+        itemsPerPage: number;
+        currentPage: number;
+        totalItems?: number | undefined;
+        totalPages?: number | undefined;
+    };
+}>;
+export type IPaginatedAttributionTouch = z.infer<typeof IPaginatedAttributionTouch>;
+/**
+ * User Attribution Touch Summary Response
+ * Contains first and last touch for a user, total touches, and conversion path
+ */
+export declare const UserAttributionTouchSummarySchema: z.ZodObject<{
+    firstTouch: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        __entity: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        updatedAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        deletedAt: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodDate]>>;
+    } & {
+        utmSource: z.ZodNullable<z.ZodNativeEnum<typeof UtmSource>>;
+        utmMedium: z.ZodNullable<z.ZodString>;
+        utmCampaign: z.ZodNullable<z.ZodString>;
+        utmTerm: z.ZodNullable<z.ZodString>;
+        utmContent: z.ZodNullable<z.ZodString>;
+        platformClickIds: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+        ref: z.ZodNullable<z.ZodString>;
+        landingPage: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        documentReferrer: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        isFirstTouch: z.ZodBoolean;
+        isLastTouch: z.ZodBoolean;
+        touchCount: z.ZodNumber;
+        userId: z.ZodString;
+        accountId: z.ZodString;
+        tradeId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }>>;
+    lastTouch: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        __entity: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        updatedAt: z.ZodUnion<[z.ZodString, z.ZodDate]>;
+        deletedAt: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodDate]>>;
+    } & {
+        utmSource: z.ZodNullable<z.ZodNativeEnum<typeof UtmSource>>;
+        utmMedium: z.ZodNullable<z.ZodString>;
+        utmCampaign: z.ZodNullable<z.ZodString>;
+        utmTerm: z.ZodNullable<z.ZodString>;
+        utmContent: z.ZodNullable<z.ZodString>;
+        platformClickIds: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+        ref: z.ZodNullable<z.ZodString>;
+        landingPage: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        documentReferrer: z.ZodNullable<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+        isFirstTouch: z.ZodBoolean;
+        isLastTouch: z.ZodBoolean;
+        touchCount: z.ZodNumber;
+        userId: z.ZodString;
+        accountId: z.ZodString;
+        tradeId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }, {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    }>>;
+    totalTouches: z.ZodNumber;
+    conversionPath: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    firstTouch: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    } | null;
+    lastTouch: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    } | null;
+    totalTouches: number;
+    conversionPath: string[];
+}, {
+    firstTouch: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    } | null;
+    lastTouch: {
+        id: string;
+        createdAt: string | Date;
+        updatedAt: string | Date;
+        deletedAt: string | Date | null;
+        accountId: string;
+        userId: string;
+        tradeId: string | null;
+        landingPage: string | null;
+        utmSource: UtmSource | null;
+        utmMedium: string | null;
+        utmCampaign: string | null;
+        utmTerm: string | null;
+        utmContent: string | null;
+        platformClickIds: Record<string, string> | null;
+        ref: string | null;
+        documentReferrer: string | null;
+        isFirstTouch: boolean;
+        isLastTouch: boolean;
+        touchCount: number;
+        __entity?: string | undefined;
+    } | null;
+    totalTouches: number;
+    conversionPath: string[];
+}>;
+export type UserAttributionTouchSummary = z.infer<typeof UserAttributionTouchSummarySchema>;