@walkeros/server-destination-datamanager 0.3.1 → 0.4.1

package/README.md

@@ -23,7 +23,7 @@ npm install @walkeros/server-destination-datamanager
 
 ## Quick Start
 
-### Minimal Configuration
+### Minimal Configuration (AWS Lambda / Serverless)
 
 ```typescript
 import { destinationDataManager } from '@walkeros/server-destination-datamanager';
@@ -35,8 +35,11 @@ const { collector, elb } = await startFlow({
       ...destinationDataManager,
       config: {
         settings: {
-          // OAuth 2.0 access token with datamanager scope
-          accessToken: 'ya29.c.xxx',
+          // Service account credentials from environment variables
+          credentials: {
+            client_email: process.env.GOOGLE_CLIENT_EMAIL!,
+            private_key: process.env.GOOGLE_PRIVATE_KEY!.replace(/\\n/g, '\n'),
+          },
 
           // Destination accounts
           destinations: [
@@ -62,7 +65,36 @@ await elb('order complete', {
 });
 ```
 
-### Complete Configuration
+### GCP Cloud Functions (Application Default Credentials)
+
+```typescript
+import { destinationDataManager } from '@walkeros/server-destination-datamanager';
+import { startFlow } from '@walkeros/collector';
+
+// No auth config needed - ADC works automatically on GCP!
+const { collector, elb } = await startFlow({
+  destinations: {
+    datamanager: {
+      ...destinationDataManager,
+      config: {
+        settings: {
+          destinations: [
+            {
+              operatingAccount: {
+                accountId: '123-456-7890',
+                accountType: 'GOOGLE_ADS',
+              },
+              productDestinationId: 'AW-CONVERSION-123',
+            },
+          ],
+        },
+      },
+    },
+  },
+});
+```
+
+### Local Development
 
 ```typescript
 import { destinationDataManager } from '@walkeros/server-destination-datamanager';
@@ -71,7 +103,8 @@ const config = {
   ...destinationDataManager,
   config: {
     settings: {
-      accessToken: 'ya29.c.xxx',
+      // Service account JSON file
+      keyFilename: './service-account.json',
 
       // Multiple destinations (max 10)
       destinations: [
@@ -136,34 +169,141 @@ const config = {
 
 ## Authentication
 
-### OAuth 2.0 Setup
+The Data Manager destination uses Google Cloud service accounts with automatic
+token refresh. The library handles token management automatically - you just
+provide credentials and tokens are cached and refreshed as needed.
+
+### Authentication Methods
+
+The destination supports three authentication methods (in priority order):
+
+1. **Inline Credentials** - Best for serverless (AWS Lambda, Docker, K8s)
+2. **Service Account File** - Best for local development
+3. **Application Default Credentials (ADC)** - Automatic on GCP
+
+### 1. Inline Credentials (Recommended for Serverless)
+
+Best for AWS Lambda, Docker, Kubernetes, and other containerized environments
+where you manage secrets via environment variables.
+
+```typescript
+import { destinationDataManager } from '@walkeros/server-destination-datamanager';
+
+const config = {
+  ...destinationDataManager,
+  config: {
+    settings: {
+      credentials: {
+        client_email: process.env.GOOGLE_CLIENT_EMAIL!,
+        private_key: process.env.GOOGLE_PRIVATE_KEY!.replace(/\\n/g, '\n'),
+      },
+      destinations: [
+        /* ... */
+      ],
+    },
+  },
+};
+```
+
+**Environment Variables:**
+
+```bash
+GOOGLE_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
+GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"
+```
+
+**Note:** Use `.replace(/\\n/g, '\n')` to convert escaped newlines from
+environment variables.
+
+### 2. Service Account File (Local Development)
+
+Best for local development with filesystem access.
+
+```typescript
+const config = {
+  ...destinationDataManager,
+  config: {
+    settings: {
+      keyFilename: './service-account.json',
+      destinations: [
+        /* ... */
+      ],
+    },
+  },
+};
+```
+
+### 3. Application Default Credentials (GCP)
+
+Automatic on Google Cloud Platform - no configuration needed!
 
-1. **Create a Google Cloud Project**
-   - Go to [Google Cloud Console](https://console.cloud.google.com/)
-   - Create a new project or select existing
+```typescript
+const config = {
+  ...destinationDataManager,
+  config: {
+    settings: {
+      // No auth config needed - ADC used automatically!
+      destinations: [
+        /* ... */
+      ],
+    },
+  },
+};
+```
+
+**Works automatically on:**
 
-2. **Enable Data Manager API**
-   - Navigate to APIs & Services > Library
-   - Search for "Google Data Manager API"
-   - Click Enable
+- Google Cloud Functions
+- Google Cloud Run
+- Google Compute Engine
+- Google Kubernetes Engine
+- Any GCP environment with default service account
 
-3. **Create Service Account**
-   - Go to APIs & Services > Credentials
-   - Click "Create Credentials" > "Service Account"
-   - Grant necessary permissions
-   - Download JSON key file
+**Also works with:**
 
-4. **Get Access Token**
-   ```bash
-   gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager
-   ```
+- `GOOGLE_APPLICATION_CREDENTIALS` environment variable
+- gcloud CLI: `gcloud auth application-default login`
 
-### Required Scope
+### Creating a Service Account
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Navigate to **IAM & Admin > Service Accounts**
+3. Click **Create Service Account**
+4. Name: `walkeros-datamanager` (or your choice)
+5. Grant role: **Data Manager Admin** or custom role with datamanager
+   permissions
+6. Click **Keys > Add Key > Create New Key**
+7. Select **JSON** format and download
+
+**For inline credentials:**
+
+- Extract `client_email` and `private_key` from the JSON
+- Store in environment variables or secrets manager
+
+**For keyFilename:**
+
+- Set `keyFilename: '/path/to/downloaded-key.json'`
+
+**For ADC:**
+
+- Set `GOOGLE_APPLICATION_CREDENTIALS=/path/to/downloaded-key.json`
+- Or deploy to GCP where ADC works automatically
+
+### Required OAuth Scope
 
 ```
 https://www.googleapis.com/auth/datamanager
 ```
 
+This scope is automatically applied - no configuration needed.
+
+### Token Management
+
+- **Lifetime:** 1 hour (3600 seconds)
+- **Refresh:** Automatic - library handles expiration
+- **Caching:** Tokens are cached and reused until expiration
+- **Performance:** ~10-50ms overhead per request for token validation
+
 ## Guided Mapping Helpers
 
 Define common fields once in Settings instead of repeating them in every event
@@ -172,7 +312,7 @@ mapping:
 ```typescript
 {
   settings: {
-    accessToken: 'ya29.c.xxx',
+    credentials: { /* ... */ },
     destinations: [...],
 
     // Guided helpers (apply to all events)
@@ -616,23 +756,28 @@ be rejected.
 
 ### Settings
 
-| Property                   | Type           | Required | Description                                 |
-| -------------------------- | -------------- | -------- | ------------------------------------------- |
-| `accessToken`              | string         | ✓        | OAuth 2.0 access token                      |
-| `destinations`             | Destination[]  | ✓        | Array of destination accounts (max 10)      |
-| `eventSource`              | EventSource    |          | Default event source (WEB, APP, etc.)       |
-| `batchSize`                | number         |          | Max events per batch (max 2000)             |
-| `batchInterval`            | number         |          | Batch flush interval in ms                  |
-| `validateOnly`             | boolean        |          | Validate without ingestion                  |
-| `url`                      | string         |          | Override API endpoint                       |
-| `consent`                  | Consent        |          | Request-level consent                       |
-| `testEventCode`            | string         |          | Test event code for debugging               |
-| `userData`                 | object         |          | Guided helper: User data mapping            |
-| `userId`                   | string         |          | Guided helper: First-party user ID          |
-| `clientId`                 | string         |          | Guided helper: GA4 client ID                |
-| `sessionAttributes`        | string         |          | Guided helper: Privacy-safe attribution     |
-| `consentAdUserData`        | string/boolean |          | Consent mapping: Field name or static value |
-| `consentAdPersonalization` | string/boolean |          | Consent mapping: Field name or static value |
+| Property                   | Type           | Required | Description                                  |
+| -------------------------- | -------------- | -------- | -------------------------------------------- |
+| `credentials`              | object         | \*       | Service account (client_email + private_key) |
+| `keyFilename`              | string         | \*       | Path to service account JSON file            |
+| `scopes`                   | string[]       |          | OAuth scopes (default: datamanager scope)    |
+| `destinations`             | Destination[]  | ✓        | Array of destination accounts (max 10)       |
+| `eventSource`              | EventSource    |          | Default event source (WEB, APP, etc.)        |
+| `batchSize`                | number         |          | Max events per batch (max 2000)              |
+| `batchInterval`            | number         |          | Batch flush interval in ms                   |
+| `validateOnly`             | boolean        |          | Validate without ingestion                   |
+| `url`                      | string         |          | Override API endpoint                        |
+| `consent`                  | Consent        |          | Request-level consent                        |
+| `testEventCode`            | string         |          | Test event code for debugging                |
+| `userData`                 | object         |          | Guided helper: User data mapping             |
+| `userId`                   | string         |          | Guided helper: First-party user ID           |
+| `clientId`                 | string         |          | Guided helper: GA4 client ID                 |
+| `sessionAttributes`        | string         |          | Guided helper: Privacy-safe attribution      |
+| `consentAdUserData`        | string/boolean |          | Consent mapping: Field name or static value  |
+| `consentAdPersonalization` | string/boolean |          | Consent mapping: Field name or static value  |
+
+**\* One of `credentials`, `keyFilename`, or ADC (automatic) required for
+authentication**
 
 ### Event Fields
 

package/dist/dev.d.mts

@@ -0,0 +1,235 @@
+import { JSONSchema } from '@walkeros/core/dev';
+import { Mapping as Mapping$1, Destination as Destination$1 } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { OAuth2Client } from 'google-auth-library';
+
+declare const schemas$1: Record<string, JSONSchema>;
+
+declare namespace schemas {
+  export { schemas$1 as schemas };
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+
+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[];
+    /** 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;
+    authClient?: OAuth2Client | null;
+}
+type InitSettings = Partial<Settings>;
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+type Rule = Mapping$1.Rule<Mapping>;
+/**
+ * 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';
+
+/**
+ * AWS Lambda / Serverless Configuration
+ * Uses inline credentials from environment variables
+ * Best for: AWS Lambda, Docker, Kubernetes, any serverless environment
+ */
+declare const awsLambda: Config;
+/**
+ * GCP Cloud Functions / Cloud Run Configuration
+ * Uses Application Default Credentials (ADC) - no explicit auth config needed
+ * Best for: Google Cloud Functions, Cloud Run, GCE, GKE
+ */
+declare const gcpCloudFunctions: Config;
+/**
+ * Local Development Configuration
+ * Uses service account JSON file
+ * Best for: Local development, testing
+ */
+declare const localDevelopment: Config;
+/**
+ * Docker / Kubernetes Configuration
+ * Uses ADC via GOOGLE_APPLICATION_CREDENTIALS environment variable
+ * Best for: Docker containers, Kubernetes pods
+ *
+ * Setup:
+ * 1. Mount service account JSON as secret/configmap
+ * 2. Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+ * 3. ADC will automatically use it
+ */
+declare const dockerKubernetes: Config;
+/**
+ * Custom Scopes Configuration
+ * For specific use cases requiring different OAuth scopes
+ */
+declare const customScopes: Config;
+
+declare const auth_awsLambda: typeof awsLambda;
+declare const auth_customScopes: typeof customScopes;
+declare const auth_dockerKubernetes: typeof dockerKubernetes;
+declare const auth_gcpCloudFunctions: typeof gcpCloudFunctions;
+declare const auth_localDevelopment: typeof localDevelopment;
+declare namespace auth {
+  export { auth_awsLambda as awsLambda, auth_customScopes as customScopes, auth_dockerKubernetes as dockerKubernetes, auth_gcpCloudFunctions as gcpCloudFunctions, auth_localDevelopment as localDevelopment };
+}
+
+/**
+ * Minimal configuration for Google Data Manager with inline credentials
+ */
+declare const minimal: Config;
+/**
+ * Complete configuration with all options
+ */
+declare const complete: Config;
+/**
+ * GA4-specific configuration using Application Default Credentials
+ */
+declare const ga4: Config;
+/**
+ * Debug configuration with logging enabled using keyFilename
+ */
+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 };
+}
+
+/**
+ * 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 };
+}
+
+declare const index_auth: typeof auth;
+declare const index_basic: typeof basic;
+declare namespace index {
+  export { index_auth as auth, index_basic as basic, mapping$1 as mapping };
+}
+
+export { index as examples, schemas };