@walkeros/server-destination-datamanager 0.3.1

package/dist/examples/index.mjs

@@ -0,0 +1,213 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/examples/mapping.ts
+var mapping_exports = {};
+__export(mapping_exports, {
+  Lead: () => Lead,
+  PageView: () => PageView,
+  Purchase: () => Purchase,
+  mapping: () => mapping,
+  userDataMapping: () => userDataMapping
+});
+import { isObject } from "@walkeros/core";
+var Purchase = {
+  name: "purchase",
+  data: {
+    map: {
+      // Required fields
+      transactionId: "data.id",
+      conversionValue: "data.total",
+      currency: { key: "data.currency", value: "USD" },
+      eventName: { value: "purchase" },
+      // User identification
+      userId: "user.id",
+      email: "user.id",
+      // Will be hashed automatically
+      // Attribution identifiers (captured by browser source from URL)
+      gclid: "context.gclid",
+      // Google Click ID
+      gbraid: "context.gbraid",
+      // iOS attribution
+      wbraid: "context.wbraid",
+      // Web-to-app
+      // Shopping cart data
+      cartData: {
+        map: {
+          items: {
+            loop: [
+              "nested",
+              {
+                condition: (entity) => isObject(entity) && entity.entity === "product",
+                map: {
+                  merchantProductId: "data.id",
+                  price: "data.price",
+                  quantity: { key: "data.quantity", value: 1 }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+};
+var Lead = {
+  name: "generate_lead",
+  data: {
+    map: {
+      eventName: { value: "generate_lead" },
+      conversionValue: { value: 10 },
+      currency: { value: "USD" }
+    }
+  }
+};
+var PageView = {
+  name: "page_view",
+  data: {
+    map: {
+      eventName: { value: "page_view" }
+    }
+  }
+};
+var mapping = {
+  order: {
+    complete: Purchase
+  },
+  lead: {
+    submit: Lead
+  },
+  page: {
+    view: PageView
+  }
+};
+var userDataMapping = {
+  settings: {
+    accessToken: "ya29.c.xxx",
+    destinations: [
+      {
+        operatingAccount: {
+          accountId: "123-456-7890",
+          accountType: "GOOGLE_ADS"
+        },
+        productDestinationId: "AW-CONVERSION-123"
+      }
+    ]
+  },
+  data: {
+    map: {
+      email: "user.id",
+      phone: "data.phone",
+      firstName: "data.firstName",
+      lastName: "data.lastName",
+      regionCode: "data.country",
+      postalCode: "data.zip"
+    }
+  },
+  mapping
+};
+
+// src/examples/basic.ts
+var basic_exports = {};
+__export(basic_exports, {
+  complete: () => complete,
+  debug: () => debug,
+  ga4: () => ga4,
+  minimal: () => minimal
+});
+var minimal = {
+  settings: {
+    accessToken: "ya29.c.xxx",
+    destinations: [
+      {
+        operatingAccount: {
+          accountId: "123-456-7890",
+          accountType: "GOOGLE_ADS"
+        },
+        productDestinationId: "AW-CONVERSION-123"
+      }
+    ]
+  }
+};
+var complete = {
+  settings: {
+    accessToken: "ya29.c.xxx",
+    destinations: [
+      {
+        operatingAccount: {
+          accountId: "123-456-7890",
+          accountType: "GOOGLE_ADS"
+        },
+        productDestinationId: "AW-CONVERSION-123"
+      },
+      {
+        operatingAccount: {
+          accountId: "987654321",
+          accountType: "GOOGLE_ANALYTICS_PROPERTY"
+        },
+        productDestinationId: "G-XXXXXXXXXX"
+      }
+    ],
+    eventSource: "WEB",
+    batchSize: 100,
+    batchInterval: 5e3,
+    validateOnly: false,
+    consent: {
+      adUserData: "CONSENT_GRANTED",
+      adPersonalization: "CONSENT_GRANTED"
+    },
+    // Guided helpers (apply to all events)
+    userData: {
+      email: "user.id",
+      phone: "data.phone",
+      firstName: "data.firstName",
+      lastName: "data.lastName"
+    },
+    userId: "user.id",
+    clientId: "user.device",
+    sessionAttributes: "context.sessionAttributes"
+  },
+  data: {
+    map: {
+      eventSource: { value: "WEB" }
+    }
+  }
+};
+var ga4 = {
+  settings: {
+    accessToken: "ya29.c.xxx",
+    destinations: [
+      {
+        operatingAccount: {
+          accountId: "123456789",
+          accountType: "GOOGLE_ANALYTICS_PROPERTY"
+        },
+        productDestinationId: "G-XXXXXXXXXX"
+      }
+    ],
+    eventSource: "WEB"
+  }
+};
+var debug = {
+  settings: {
+    accessToken: "ya29.c.xxx",
+    destinations: [
+      {
+        operatingAccount: {
+          accountId: "123-456-7890",
+          accountType: "GOOGLE_ADS"
+        },
+        productDestinationId: "AW-CONVERSION-123"
+      }
+    ],
+    logLevel: "debug"
+    // Shows all API calls and responses
+  }
+};
+export {
+  basic_exports as basic,
+  mapping_exports as mapping
+};

package/dist/index.d.mts

@@ -0,0 +1,372 @@
+import { Destination as Destination$1, Mapping as Mapping$1, JSONSchema } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+
+interface Settings {
+    /** OAuth 2.0 access token with datamanager scope */
+    accessToken: string;
+    /** Array of destination accounts and conversion actions/user lists */
+    destinations: Destination[];
+    /** Default event source if not specified per event */
+    eventSource?: EventSource;
+    /** Maximum number of events to batch before sending (max 2000) */
+    batchSize?: number;
+    /** Time in milliseconds to wait before auto-flushing batch */
+    batchInterval?: number;
+    /** If true, validate request without ingestion (testing mode) */
+    validateOnly?: boolean;
+    /** Override API endpoint (for testing) */
+    url?: string;
+    /** Request-level consent for all events */
+    consent?: Consent;
+    /** Test event code for debugging (optional) */
+    testEventCode?: string;
+    /** Log level for debugging (optional) */
+    logLevel?: LogLevel;
+    /** Guided helpers: User data mapping (applies to all events) */
+    userData?: Mapping$1.Map;
+    /** Guided helper: First-party user ID */
+    userId?: Mapping$1.Value;
+    /** Guided helper: GA4 client ID */
+    clientId?: Mapping$1.Value;
+    /** Guided helper: Privacy-safe attribution (Google's sessionAttributes) */
+    sessionAttributes?: Mapping$1.Value;
+    /** Consent mapping: Map consent field to adUserData (string = field name, boolean = static value) */
+    consentAdUserData?: string | boolean;
+    /** Consent mapping: Map consent field to adPersonalization (string = field name, boolean = static value) */
+    consentAdPersonalization?: string | boolean;
+}
+interface Mapping {
+    gclid?: Mapping$1.Value;
+    gbraid?: Mapping$1.Value;
+    wbraid?: Mapping$1.Value;
+    sessionAttributes?: Mapping$1.Value;
+}
+interface Env extends DestinationServer.Env {
+    fetch?: typeof fetch;
+}
+type Types = Destination$1.Types<Settings, Mapping, Env>;
+interface DestinationInterface extends DestinationServer.Destination<Types> {
+    init: DestinationServer.InitFn<Types>;
+}
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+type InitFn = DestinationServer.InitFn<Types>;
+type PushFn = DestinationServer.PushFn<Types>;
+type PartialConfig = DestinationServer.PartialConfig<Types>;
+type PushEvents = DestinationServer.PushEvents<Mapping>;
+type Rule = Mapping$1.Rule<Mapping>;
+type Rules = Mapping$1.Rules<Rule>;
+/**
+ * Destination account and product identifier
+ * https://developers.google.com/data-manager/api/reference/rest/v1/Destination
+ */
+interface Destination {
+    /** Operating account details */
+    operatingAccount: OperatingAccount;
+    /** Product-specific destination ID (conversion action or user list) */
+    productDestinationId: string;
+}
+/**
+ * Operating account information
+ */
+interface OperatingAccount {
+    /** Account ID (e.g., "123-456-7890" for Google Ads) */
+    accountId: string;
+    /** Type of account */
+    accountType: AccountType;
+}
+type AccountType = 'GOOGLE_ADS' | 'DISPLAY_VIDEO_ADVERTISER' | 'DISPLAY_VIDEO_PARTNER' | 'GOOGLE_ANALYTICS_PROPERTY';
+type EventSource = 'WEB' | 'APP' | 'IN_STORE' | 'PHONE' | 'OTHER';
+/**
+ * Consent for Digital Markets Act (DMA) compliance
+ * https://developers.google.com/data-manager/api/devguides/concepts/dma
+ */
+interface Consent {
+    /** Consent for data collection and use */
+    adUserData?: ConsentStatus;
+    /** Consent for ad personalization */
+    adPersonalization?: ConsentStatus;
+}
+type ConsentStatus = 'CONSENT_GRANTED' | 'CONSENT_DENIED';
+/**
+ * Request body for events.ingest API
+ * https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest
+ */
+interface IngestEventsRequest {
+    /** OAuth 2.0 access token */
+    access_token?: string;
+    /** Array of events to ingest (max 2000) */
+    events: Event[];
+    /** Array of destinations for these events (max 10) */
+    destinations: Destination[];
+    /** Request-level consent (overridden by event-level) */
+    consent?: Consent;
+    /** If true, validate without ingestion */
+    validateOnly?: boolean;
+    /** Test event code for debugging */
+    testEventCode?: string;
+}
+/**
+ * Single event for ingestion
+ * https://developers.google.com/data-manager/api/reference/rest/v1/Event
+ */
+interface Event {
+    /** Event timestamp in RFC 3339 format */
+    eventTimestamp: string;
+    /** Transaction ID for deduplication (max 512 chars) */
+    transactionId?: string;
+    /** Google Analytics client ID (max 255 chars) */
+    clientId?: string;
+    /** First-party user ID (max 256 chars) */
+    userId?: string;
+    /** User data with identifiers (max 10 identifiers) */
+    userData?: UserData;
+    /** Attribution identifiers */
+    adIdentifiers?: AdIdentifiers;
+    /** Conversion value */
+    conversionValue?: number;
+    /** Currency code (ISO 4217, 3 chars) */
+    currency?: string;
+    /** Shopping cart data */
+    cartData?: CartData;
+    /** Event name for GA4 (max 40 chars, required for GA4) */
+    eventName?: string;
+    /** Source of the event */
+    eventSource?: EventSource;
+    /** Event-level consent (overrides request-level) */
+    consent?: Consent;
+}
+/**
+ * User data with identifiers
+ * https://developers.google.com/data-manager/api/reference/rest/v1/UserData
+ */
+interface UserData {
+    /** Array of user identifiers (max 10) */
+    userIdentifiers: UserIdentifier[];
+}
+/**
+ * User identifier (email, phone, or address)
+ */
+type UserIdentifier = {
+    emailAddress: string;
+} | {
+    phoneNumber: string;
+} | {
+    address: Address;
+};
+/**
+ * Address for user identification
+ * https://developers.google.com/data-manager/api/reference/rest/v1/Address
+ */
+interface Address {
+    /** Given name (first name) - SHA-256 hashed */
+    givenName?: string;
+    /** Family name (last name) - SHA-256 hashed */
+    familyName?: string;
+    /** ISO-3166-1 alpha-2 country code - NOT hashed (e.g., "US", "GB") */
+    regionCode?: string;
+    /** Postal code - NOT hashed */
+    postalCode?: string;
+}
+/**
+ * Attribution identifiers
+ * https://developers.google.com/data-manager/api/reference/rest/v1/AdIdentifiers
+ */
+interface AdIdentifiers {
+    /** Google Click ID (primary attribution) */
+    gclid?: string;
+    /** iOS attribution identifier (post-ATT) */
+    gbraid?: string;
+    /** Web-to-app attribution identifier */
+    wbraid?: string;
+    /** Session attributes (privacy-safe attribution) */
+    sessionAttributes?: string;
+}
+/**
+ * Shopping cart data
+ * https://developers.google.com/data-manager/api/reference/rest/v1/CartData
+ */
+interface CartData {
+    /** Array of cart items (max 200) */
+    items: CartItem[];
+}
+/**
+ * Single cart item
+ * https://developers.google.com/data-manager/api/reference/rest/v1/CartItem
+ */
+interface CartItem {
+    /** Merchant product ID (max 127 chars) */
+    merchantProductId?: string;
+    /** Item price */
+    price?: number;
+    /** Item quantity */
+    quantity?: number;
+}
+/**
+ * Response from events.ingest API
+ * https://developers.google.com/data-manager/api/reference/rest/v1/IngestEventsResponse
+ */
+interface IngestEventsResponse {
+    /** Unique request ID for status checking */
+    requestId: string;
+    /** Validation errors (only if validateOnly=true) */
+    validationErrors?: ValidationError[];
+}
+/**
+ * Validation error
+ */
+interface ValidationError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Field path that caused the error */
+    fieldPath?: string;
+}
+/**
+ * Request status response
+ * https://developers.google.com/data-manager/api/reference/rest/v1/requestStatus/retrieve
+ */
+interface RequestStatusResponse {
+    /** Unique request ID */
+    requestId: string;
+    /** Processing state */
+    state: RequestState;
+    /** Number of events successfully ingested */
+    eventsIngested?: number;
+    /** Number of events that failed */
+    eventsFailed?: number;
+    /** Array of errors (if any) */
+    errors?: RequestError[];
+}
+type RequestState = 'STATE_UNSPECIFIED' | 'PENDING' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'PARTIALLY_SUCCEEDED';
+/**
+ * Request error
+ */
+interface RequestError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Number of events affected by this error */
+    eventCount?: number;
+}
+
+type index$1_AccountType = AccountType;
+type index$1_AdIdentifiers = AdIdentifiers;
+type index$1_Address = Address;
+type index$1_CartData = CartData;
+type index$1_CartItem = CartItem;
+type index$1_Config = Config;
+type index$1_Consent = Consent;
+type index$1_ConsentStatus = ConsentStatus;
+type index$1_Destination = Destination;
+type index$1_DestinationInterface = DestinationInterface;
+type index$1_Env = Env;
+type index$1_Event = Event;
+type index$1_EventSource = EventSource;
+type index$1_IngestEventsRequest = IngestEventsRequest;
+type index$1_IngestEventsResponse = IngestEventsResponse;
+type index$1_InitFn = InitFn;
+type index$1_Mapping = Mapping;
+type index$1_OperatingAccount = OperatingAccount;
+type index$1_PartialConfig = PartialConfig;
+type index$1_PushEvents = PushEvents;
+type index$1_PushFn = PushFn;
+type index$1_RequestError = RequestError;
+type index$1_RequestState = RequestState;
+type index$1_RequestStatusResponse = RequestStatusResponse;
+type index$1_Rule = Rule;
+type index$1_Rules = Rules;
+type index$1_Settings = Settings;
+type index$1_Types = Types;
+type index$1_UserData = UserData;
+type index$1_UserIdentifier = UserIdentifier;
+type index$1_ValidationError = ValidationError;
+declare namespace index$1 {
+  export type { index$1_AccountType as AccountType, index$1_AdIdentifiers as AdIdentifiers, index$1_Address as Address, index$1_CartData as CartData, index$1_CartItem as CartItem, index$1_Config as Config, index$1_Consent as Consent, index$1_ConsentStatus as ConsentStatus, index$1_Destination as Destination, index$1_DestinationInterface as DestinationInterface, index$1_Env as Env, index$1_Event as Event, index$1_EventSource as EventSource, index$1_IngestEventsRequest as IngestEventsRequest, index$1_IngestEventsResponse as IngestEventsResponse, index$1_InitFn as InitFn, index$1_Mapping as Mapping, index$1_OperatingAccount as OperatingAccount, index$1_PartialConfig as PartialConfig, index$1_PushEvents as PushEvents, index$1_PushFn as PushFn, index$1_RequestError as RequestError, index$1_RequestState as RequestState, index$1_RequestStatusResponse as RequestStatusResponse, index$1_Rule as Rule, index$1_Rules as Rules, index$1_Settings as Settings, index$1_Types as Types, index$1_UserData as UserData, index$1_UserIdentifier as UserIdentifier, index$1_ValidationError as ValidationError };
+}
+
+/**
+ * Purchase event mapping for Google Ads conversion
+ */
+declare const Purchase: Rule;
+/**
+ * Lead event mapping
+ */
+declare const Lead: Rule;
+/**
+ * Page view mapping for GA4
+ */
+declare const PageView: Rule;
+/**
+ * Complete mapping configuration
+ */
+declare const mapping: {
+    order: {
+        complete: Rule;
+    };
+    lead: {
+        submit: Rule;
+    };
+    page: {
+        view: Rule;
+    };
+};
+/**
+ * User data mapping configuration
+ * Maps walkerOS user properties to Data Manager user identifiers
+ */
+declare const userDataMapping: Config;
+
+declare const mapping$1_Lead: typeof Lead;
+declare const mapping$1_PageView: typeof PageView;
+declare const mapping$1_Purchase: typeof Purchase;
+declare const mapping$1_mapping: typeof mapping;
+declare const mapping$1_userDataMapping: typeof userDataMapping;
+declare namespace mapping$1 {
+  export { mapping$1_Lead as Lead, mapping$1_PageView as PageView, mapping$1_Purchase as Purchase, mapping$1_mapping as mapping, mapping$1_userDataMapping as userDataMapping };
+}
+
+/**
+ * Minimal configuration for Google Data Manager
+ */
+declare const minimal: Config;
+/**
+ * Complete configuration with all options
+ */
+declare const complete: Config;
+/**
+ * GA4-specific configuration
+ */
+declare const ga4: Config;
+/**
+ * Debug configuration with logging enabled
+ */
+declare const debug: Config;
+
+declare const basic_complete: typeof complete;
+declare const basic_debug: typeof debug;
+declare const basic_ga4: typeof ga4;
+declare const basic_minimal: typeof minimal;
+declare namespace basic {
+  export { basic_complete as complete, basic_debug as debug, basic_ga4 as ga4, basic_minimal as minimal };
+}
+
+declare const index_basic: typeof basic;
+declare namespace index {
+  export { index_basic as basic, mapping$1 as mapping };
+}
+
+declare const schemas$1: Record<string, JSONSchema>;
+
+declare namespace schemas {
+  export { schemas$1 as schemas };
+}
+
+declare const destinationDataManager: DestinationInterface;
+
+export { index$1 as DestinationDataManager, destinationDataManager as default, destinationDataManager, index as examples, schemas };