@walkeros/server-destination-datamanager 0.0.0-next-20251219153324

package/dist/index.d.mts

@@ -0,0 +1,388 @@
+import { Destination as Destination$1, Mapping as Mapping$1 } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { OAuth2Client } from 'google-auth-library';
+
+interface Settings {
+    /**
+     * Service account credentials (client_email + private_key)
+     * Recommended for serverless environments (AWS Lambda, Docker, etc.)
+     */
+    credentials?: {
+        client_email: string;
+        private_key: string;
+    };
+    /**
+     * Path to service account JSON file
+     * For local development or environments with filesystem access
+     */
+    keyFilename?: string;
+    /**
+     * OAuth scopes for Data Manager API
+     * @default ['https://www.googleapis.com/auth/datamanager']
+     */
+    scopes?: string[];
+    /** Array of destination accounts and conversion actions/user lists */
+    destinations: Destination[];
+    /** Event source for all events. Defaults to WEB if not specified */
+    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;
+    /** 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;
+    authClient?: OAuth2Client | null;
+}
+type InitSettings = Partial<Settings>;
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+interface DestinationInterface extends DestinationServer.Destination<Types> {
+    init: DestinationServer.InitFn<Types>;
+}
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+/**
+ * Config after validation - settings is guaranteed to exist with required fields
+ * Use this type after calling getConfig() to get proper type narrowing
+ * After validation, eventSource is always set (defaults to 'WEB')
+ */
+type ValidatedConfig = Omit<Config, 'settings'> & {
+    settings: Settings & {
+        eventSource: EventSource;
+    };
+};
+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 {
+    /** Reference identifier for this destination */
+    reference?: string;
+    /** Login account (account initiating the request) */
+    loginAccount?: ProductAccount;
+    /** Linked account (child account linked to login account) */
+    linkedAccount?: ProductAccount;
+    /** Operating account (account where data is sent) */
+    operatingAccount?: ProductAccount;
+    /** Product-specific destination ID (conversion action or user list) */
+    productDestinationId?: string;
+}
+/**
+ * Product account information
+ */
+interface ProductAccount {
+    /** Account ID (e.g., "123-456-7890" for Google Ads) */
+    accountId: string;
+    /** Type of account */
+    accountType: AccountType;
+}
+type AccountType = 'ACCOUNT_TYPE_UNSPECIFIED' | 'GOOGLE_ADS' | 'DISPLAY_VIDEO_ADVERTISER' | 'DISPLAY_VIDEO_PARTNER' | 'GOOGLE_ANALYTICS_PROPERTY' | 'DATA_PARTNER';
+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 {
+    /** Array of destinations for these events (max 10) */
+    destinations: Destination[];
+    /** Array of events to ingest (max 2000) */
+    events: Event[];
+    /** 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 {
+    /** Destination references for routing */
+    destinationReferences?: string[];
+    /** Transaction ID for deduplication (max 512 chars) */
+    transactionId?: string;
+    /** Event timestamp in RFC 3339 format */
+    eventTimestamp?: string;
+    /** Last updated timestamp in RFC 3339 format */
+    lastUpdatedTimestamp?: string;
+    /** User data with identifiers (max 10 identifiers) */
+    userData?: UserData;
+    /** Event-level consent (overrides request-level) */
+    consent?: Consent;
+    /** Attribution identifiers */
+    adIdentifiers?: AdIdentifiers;
+    /** Currency code (ISO 4217, 3 chars) */
+    currency?: string;
+    /** Conversion value */
+    conversionValue?: number;
+    /** Source of the event */
+    eventSource?: EventSource;
+    /** Device information for the event */
+    eventDeviceInfo?: DeviceInfo;
+    /** Shopping cart data */
+    cartData?: CartData;
+    /** Custom variables for the event */
+    customVariables?: CustomVariable[];
+    /** Experimental fields (subject to change) */
+    experimentalFields?: ExperimentalField[];
+    /** User properties */
+    userProperties?: UserProperties;
+    /** Event name for GA4 (max 40 chars, required for GA4) */
+    eventName?: string;
+    /** Google Analytics client ID (max 255 chars) */
+    clientId?: string;
+    /** First-party user ID (max 256 chars) */
+    userId?: string;
+    /** Additional event parameters */
+    additionalEventParameters?: EventParameter[];
+}
+/**
+ * Device information
+ */
+interface DeviceInfo {
+    /** User agent string */
+    userAgent?: string;
+}
+/**
+ * Custom variable
+ */
+interface CustomVariable {
+    /** Variable name */
+    name?: string;
+    /** Variable value */
+    value?: string;
+}
+/**
+ * Experimental field
+ */
+interface ExperimentalField {
+    /** Field name */
+    name?: string;
+    /** Field value */
+    value?: string;
+}
+/**
+ * User properties
+ */
+interface UserProperties {
+    /** Property values */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Event parameter
+ */
+interface EventParameter {
+    /** Parameter name */
+    name?: string;
+    /** Parameter value */
+    value?: string | number;
+}
+/**
+ * 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 {
+    /** Session attributes (privacy-safe attribution) */
+    sessionAttributes?: string;
+    /** Google Click ID (primary attribution) */
+    gclid?: string;
+    /** iOS attribution identifier (post-ATT) */
+    gbraid?: string;
+    /** Web-to-app attribution identifier */
+    wbraid?: string;
+    /** Device information for landing page */
+    landingPageDeviceInfo?: DeviceInfo;
+}
+/**
+ * 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_AccountType = AccountType;
+type index_AdIdentifiers = AdIdentifiers;
+type index_Address = Address;
+type index_CartData = CartData;
+type index_CartItem = CartItem;
+type index_Config = Config;
+type index_Consent = Consent;
+type index_ConsentStatus = ConsentStatus;
+type index_CustomVariable = CustomVariable;
+type index_Destination = Destination;
+type index_DestinationInterface = DestinationInterface;
+type index_DeviceInfo = DeviceInfo;
+type index_Env = Env;
+type index_Event = Event;
+type index_EventParameter = EventParameter;
+type index_EventSource = EventSource;
+type index_ExperimentalField = ExperimentalField;
+type index_IngestEventsRequest = IngestEventsRequest;
+type index_IngestEventsResponse = IngestEventsResponse;
+type index_InitFn = InitFn;
+type index_InitSettings = InitSettings;
+type index_Mapping = Mapping;
+type index_PartialConfig = PartialConfig;
+type index_ProductAccount = ProductAccount;
+type index_PushEvents = PushEvents;
+type index_PushFn = PushFn;
+type index_RequestError = RequestError;
+type index_RequestState = RequestState;
+type index_RequestStatusResponse = RequestStatusResponse;
+type index_Rule = Rule;
+type index_Rules = Rules;
+type index_Settings = Settings;
+type index_Types = Types;
+type index_UserData = UserData;
+type index_UserIdentifier = UserIdentifier;
+type index_UserProperties = UserProperties;
+type index_ValidatedConfig = ValidatedConfig;
+type index_ValidationError = ValidationError;
+declare namespace index {
+  export type { index_AccountType as AccountType, index_AdIdentifiers as AdIdentifiers, index_Address as Address, index_CartData as CartData, index_CartItem as CartItem, index_Config as Config, index_Consent as Consent, index_ConsentStatus as ConsentStatus, index_CustomVariable as CustomVariable, index_Destination as Destination, index_DestinationInterface as DestinationInterface, index_DeviceInfo as DeviceInfo, index_Env as Env, index_Event as Event, index_EventParameter as EventParameter, index_EventSource as EventSource, index_ExperimentalField as ExperimentalField, index_IngestEventsRequest as IngestEventsRequest, index_IngestEventsResponse as IngestEventsResponse, index_InitFn as InitFn, index_InitSettings as InitSettings, index_Mapping as Mapping, index_PartialConfig as PartialConfig, index_ProductAccount as ProductAccount, index_PushEvents as PushEvents, index_PushFn as PushFn, index_RequestError as RequestError, index_RequestState as RequestState, index_RequestStatusResponse as RequestStatusResponse, index_Rule as Rule, index_Rules as Rules, index_Settings as Settings, index_Types as Types, index_UserData as UserData, index_UserIdentifier as UserIdentifier, index_UserProperties as UserProperties, index_ValidatedConfig as ValidatedConfig, index_ValidationError as ValidationError };
+}
+
+declare const destinationDataManager: DestinationInterface;
+
+export { index as DestinationDataManager, destinationDataManager as default, destinationDataManager };