@walkeros/server-destination-hubspot 3.4.0-next-1776749829492

package/dist/examples/index.d.mts

@@ -0,0 +1,185 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+/** Shape of a single custom event occurrence sent to HubSpot. */
+interface HubSpotEventRequest {
+    eventName: string;
+    email?: string;
+    objectId?: string;
+    utk?: string;
+    uuid?: string;
+    occurredAt?: Date;
+    properties?: Record<string, string>;
+}
+/**
+ * Mock-friendly interface for the HubSpot Client methods the destination
+ * actually calls. Tests provide this via env.client instead of the real SDK.
+ */
+interface HubSpotClientMock {
+    events: {
+        send: {
+            basicApi: {
+                send: (data: HubSpotEventRequest) => Promise<void>;
+            };
+            batchApi: {
+                send: (data: {
+                    inputs: HubSpotEventRequest[];
+                }) => Promise<void>;
+            };
+        };
+    };
+    crm: {
+        contacts: {
+            basicApi: {
+                update: (id: string, data: {
+                    properties: Record<string, string>;
+                }, idProperty?: string) => Promise<void>;
+            };
+        };
+    };
+}
+interface Settings {
+    /** HubSpot private app access token (required). */
+    accessToken: string;
+    /**
+     * Fully qualified event name prefix: pe{HubID}_
+     * Used to construct eventName from walkerOS event names.
+     * Example: 'pe12345678_'
+     */
+    eventNamePrefix: string;
+    /**
+     * walkerOS mapping value path to resolve contact email from events.
+     * Default: 'user.email'
+     */
+    email?: string;
+    /**
+     * walkerOS mapping value path to resolve HubSpot objectId from events.
+     * Default: undefined (use email for association)
+     */
+    objectId?: string;
+    /**
+     * Destination-level contact upsert mapping.
+     * Resolves to { email, properties } and upserts the contact on each push
+     * (with dedup via state hash).
+     */
+    identify?: Mapping.Value;
+    /**
+     * Static event properties added to every event occurrence.
+     * Useful for hs_touchpoint_source, hs_page_content_type, etc.
+     */
+    defaultProperties?: Record<string, string>;
+    /**
+     * Whether to use batch API for events (accumulate and flush).
+     * Default: false (single event sends).
+     */
+    batch?: boolean;
+    /**
+     * Batch size before auto-flush. Only used when batch: true.
+     * Default: 50. Max: 500.
+     */
+    batchSize?: number;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _client?: HubSpotClientMock;
+    _state?: RuntimeState;
+    _eventQueue?: HubSpotEventRequest[];
+}
+interface RuntimeState {
+    lastIdentity?: {
+        email?: string;
+        propertiesHash?: string;
+    };
+}
+/**
+ * Env -- optional SDK override. Production leaves this undefined and the
+ * destination creates a real Client instance. Tests provide a mock via
+ * env.client.
+ */
+interface Env extends DestinationServer.Env {
+    client?: HubSpotClientMock;
+}
+
+declare const push: Env;
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * HubSpot SDK step examples.
+ *
+ * At push time, the destination invokes the `@hubspot/api-client` SDK. The
+ * public method paths users see on the client are:
+ *
+ *   - `events.send.basicApi.send(eventRequest)` — fires an event
+ *   - `events.send.batchApi.send({ inputs: [...] })` — flushes a batch
+ *   - `crm.contacts.basicApi.update(id, data, idProperty)` — contact upsert
+ *
+ * Each `out` is therefore a list of tuples `[['method.path', ...args], ...]`
+ * matching the actual SDK call order. `identify` fires before the event.
+ * When the destination skips an event (`skip: true`, `ignore: true`, or
+ * missing identity), `out` is `[]`.
+ */
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type HubSpotStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- events.send.basicApi.send() with auto-generated
+ * event name. Email resolved from default settings.email = 'user.email'.
+ */
+declare const defaultEvent: HubSpotStepExample;
+/**
+ * Mapped event name -- mapping.settings.eventName overrides the auto-generated
+ * name. The prefix is still prepended.
+ */
+declare const mappedEventName: HubSpotStepExample;
+/**
+ * Event with defaultProperties -- settings.defaultProperties are merged
+ * into every event. Per-event properties override defaults.
+ */
+declare const defaultProperties: HubSpotStepExample;
+/**
+ * Destination-level identify -- fires crm.contacts.basicApi.update() on
+ * first push when settings.identify mapping resolves. Then fires the event.
+ */
+declare const destinationIdentify: HubSpotStepExample;
+/**
+ * Per-event identify with skip -- user login fires contact upsert only,
+ * no custom event sent.
+ */
+declare const userLoginIdentify: HubSpotStepExample;
+/**
+ * objectId association -- use objectId instead of email for contact
+ * association on the event.
+ */
+declare const objectIdAssociation: HubSpotStepExample;
+/**
+ * No identity resolved -- event is skipped with a warning. Neither email
+ * nor objectId can be resolved from the event.
+ */
+declare const noIdentity: HubSpotStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: HubSpotStepExample;
+
+type step_HubSpotStepExample = HubSpotStepExample;
+declare const step_defaultEvent: typeof defaultEvent;
+declare const step_defaultProperties: typeof defaultProperties;
+declare const step_destinationIdentify: typeof destinationIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_noIdentity: typeof noIdentity;
+declare const step_objectIdAssociation: typeof objectIdAssociation;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_HubSpotStepExample as HubSpotStepExample, step_defaultEvent as defaultEvent, step_defaultProperties as defaultProperties, step_destinationIdentify as destinationIdentify, step_mappedEventName as mappedEventName, step_noIdentity as noIdentity, step_objectIdAssociation as objectIdAssociation, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.d.ts

@@ -0,0 +1,185 @@
+import { Mapping, Flow } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+/** Shape of a single custom event occurrence sent to HubSpot. */
+interface HubSpotEventRequest {
+    eventName: string;
+    email?: string;
+    objectId?: string;
+    utk?: string;
+    uuid?: string;
+    occurredAt?: Date;
+    properties?: Record<string, string>;
+}
+/**
+ * Mock-friendly interface for the HubSpot Client methods the destination
+ * actually calls. Tests provide this via env.client instead of the real SDK.
+ */
+interface HubSpotClientMock {
+    events: {
+        send: {
+            basicApi: {
+                send: (data: HubSpotEventRequest) => Promise<void>;
+            };
+            batchApi: {
+                send: (data: {
+                    inputs: HubSpotEventRequest[];
+                }) => Promise<void>;
+            };
+        };
+    };
+    crm: {
+        contacts: {
+            basicApi: {
+                update: (id: string, data: {
+                    properties: Record<string, string>;
+                }, idProperty?: string) => Promise<void>;
+            };
+        };
+    };
+}
+interface Settings {
+    /** HubSpot private app access token (required). */
+    accessToken: string;
+    /**
+     * Fully qualified event name prefix: pe{HubID}_
+     * Used to construct eventName from walkerOS event names.
+     * Example: 'pe12345678_'
+     */
+    eventNamePrefix: string;
+    /**
+     * walkerOS mapping value path to resolve contact email from events.
+     * Default: 'user.email'
+     */
+    email?: string;
+    /**
+     * walkerOS mapping value path to resolve HubSpot objectId from events.
+     * Default: undefined (use email for association)
+     */
+    objectId?: string;
+    /**
+     * Destination-level contact upsert mapping.
+     * Resolves to { email, properties } and upserts the contact on each push
+     * (with dedup via state hash).
+     */
+    identify?: Mapping.Value;
+    /**
+     * Static event properties added to every event occurrence.
+     * Useful for hs_touchpoint_source, hs_page_content_type, etc.
+     */
+    defaultProperties?: Record<string, string>;
+    /**
+     * Whether to use batch API for events (accumulate and flush).
+     * Default: false (single event sends).
+     */
+    batch?: boolean;
+    /**
+     * Batch size before auto-flush. Only used when batch: true.
+     * Default: 50. Max: 500.
+     */
+    batchSize?: number;
+    /** Runtime state -- not user-facing. Mutated by init/push. */
+    _client?: HubSpotClientMock;
+    _state?: RuntimeState;
+    _eventQueue?: HubSpotEventRequest[];
+}
+interface RuntimeState {
+    lastIdentity?: {
+        email?: string;
+        propertiesHash?: string;
+    };
+}
+/**
+ * Env -- optional SDK override. Production leaves this undefined and the
+ * destination creates a real Client instance. Tests provide a mock via
+ * env.client.
+ */
+interface Env extends DestinationServer.Env {
+    client?: HubSpotClientMock;
+}
+
+declare const push: Env;
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * HubSpot SDK step examples.
+ *
+ * At push time, the destination invokes the `@hubspot/api-client` SDK. The
+ * public method paths users see on the client are:
+ *
+ *   - `events.send.basicApi.send(eventRequest)` — fires an event
+ *   - `events.send.batchApi.send({ inputs: [...] })` — flushes a batch
+ *   - `crm.contacts.basicApi.update(id, data, idProperty)` — contact upsert
+ *
+ * Each `out` is therefore a list of tuples `[['method.path', ...args], ...]`
+ * matching the actual SDK call order. `identify` fires before the event.
+ * When the destination skips an event (`skip: true`, `ignore: true`, or
+ * missing identity), `out` is `[]`.
+ */
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type HubSpotStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Default event forwarding -- events.send.basicApi.send() with auto-generated
+ * event name. Email resolved from default settings.email = 'user.email'.
+ */
+declare const defaultEvent: HubSpotStepExample;
+/**
+ * Mapped event name -- mapping.settings.eventName overrides the auto-generated
+ * name. The prefix is still prepended.
+ */
+declare const mappedEventName: HubSpotStepExample;
+/**
+ * Event with defaultProperties -- settings.defaultProperties are merged
+ * into every event. Per-event properties override defaults.
+ */
+declare const defaultProperties: HubSpotStepExample;
+/**
+ * Destination-level identify -- fires crm.contacts.basicApi.update() on
+ * first push when settings.identify mapping resolves. Then fires the event.
+ */
+declare const destinationIdentify: HubSpotStepExample;
+/**
+ * Per-event identify with skip -- user login fires contact upsert only,
+ * no custom event sent.
+ */
+declare const userLoginIdentify: HubSpotStepExample;
+/**
+ * objectId association -- use objectId instead of email for contact
+ * association on the event.
+ */
+declare const objectIdAssociation: HubSpotStepExample;
+/**
+ * No identity resolved -- event is skipped with a warning. Neither email
+ * nor objectId can be resolved from the event.
+ */
+declare const noIdentity: HubSpotStepExample;
+/**
+ * Wildcard ignore -- the event matches a mapping rule with ignore: true.
+ * The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: HubSpotStepExample;
+
+type step_HubSpotStepExample = HubSpotStepExample;
+declare const step_defaultEvent: typeof defaultEvent;
+declare const step_defaultProperties: typeof defaultProperties;
+declare const step_destinationIdentify: typeof destinationIdentify;
+declare const step_mappedEventName: typeof mappedEventName;
+declare const step_noIdentity: typeof noIdentity;
+declare const step_objectIdAssociation: typeof objectIdAssociation;
+declare const step_userLoginIdentify: typeof userLoginIdentify;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_HubSpotStepExample as HubSpotStepExample, step_defaultEvent as defaultEvent, step_defaultProperties as defaultProperties, step_destinationIdentify as destinationIdentify, step_mappedEventName as mappedEventName, step_noIdentity as noIdentity, step_objectIdAssociation as objectIdAssociation, step_userLoginIdentify as userLoginIdentify, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.js

@@ -0,0 +1,269 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/examples/index.ts
+var examples_exports = {};
+__export(examples_exports, {
+  env: () => env_exports,
+  step: () => step_exports
+});
+module.exports = __toCommonJS(examples_exports);
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  push: () => push,
+  simulation: () => simulation
+});
+var asyncNoop = () => Promise.resolve();
+function createMockClient() {
+  return {
+    events: {
+      send: {
+        basicApi: { send: asyncNoop },
+        batchApi: { send: asyncNoop }
+      }
+    },
+    crm: {
+      contacts: {
+        basicApi: { update: asyncNoop }
+      }
+    }
+  };
+}
+var push = {
+  client: createMockClient()
+};
+var simulation = [
+  "call:events.send.basicApi.send",
+  "call:events.send.batchApi.send",
+  "call:crm.contacts.basicApi.update"
+];
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  defaultEvent: () => defaultEvent,
+  defaultProperties: () => defaultProperties,
+  destinationIdentify: () => destinationIdentify,
+  mappedEventName: () => mappedEventName,
+  noIdentity: () => noIdentity,
+  objectIdAssociation: () => objectIdAssociation,
+  userLoginIdentify: () => userLoginIdentify,
+  wildcardIgnored: () => wildcardIgnored
+});
+var import_core = require("@walkeros/core");
+var defaultEvent = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000100,
+    user: { email: "user@example.com" }
+  }),
+  out: [
+    [
+      "events.send.basicApi.send",
+      {
+        eventName: "pe12345678_product_view",
+        email: "user@example.com",
+        occurredAt: /* @__PURE__ */ new Date(1700000100),
+        properties: {}
+      }
+    ]
+  ]
+};
+var mappedEventName = {
+  in: (0, import_core.getEvent)("order complete", {
+    timestamp: 1700000101,
+    user: { email: "user@example.com" },
+    data: { total: 99.5, currency: "EUR", id: "ord-123" }
+  }),
+  mapping: {
+    name: "order complete",
+    settings: {
+      eventName: "purchase_completed",
+      properties: {
+        map: {
+          revenue: "data.total",
+          currency: "data.currency",
+          order_id: "data.id"
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "events.send.basicApi.send",
+      {
+        eventName: "pe12345678_purchase_completed",
+        email: "user@example.com",
+        occurredAt: /* @__PURE__ */ new Date(1700000101),
+        properties: {
+          revenue: "99.5",
+          currency: "EUR",
+          order_id: "ord-123"
+        }
+      }
+    ]
+  ]
+};
+var defaultProperties = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 1700000102,
+    user: { email: "user@example.com" }
+  }),
+  settings: {
+    defaultProperties: {
+      hs_touchpoint_source: "walkerOS",
+      hs_page_content_type: "STANDARD_PAGE"
+    }
+  },
+  out: [
+    [
+      "events.send.basicApi.send",
+      {
+        eventName: "pe12345678_page_view",
+        email: "user@example.com",
+        occurredAt: /* @__PURE__ */ new Date(1700000102),
+        properties: {
+          hs_touchpoint_source: "walkerOS",
+          hs_page_content_type: "STANDARD_PAGE"
+        }
+      }
+    ]
+  ]
+};
+var destinationIdentify = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 1700000103,
+    user: { email: "user@example.com", firstName: "Jane", lastName: "Doe" }
+  }),
+  settings: {
+    identify: {
+      map: {
+        email: "user.email",
+        properties: {
+          map: {
+            firstname: "user.firstName",
+            lastname: "user.lastName"
+          }
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "crm.contacts.basicApi.update",
+      "user@example.com",
+      { properties: { firstname: "Jane", lastname: "Doe" } },
+      "email"
+    ],
+    [
+      "events.send.basicApi.send",
+      {
+        eventName: "pe12345678_page_view",
+        email: "user@example.com",
+        occurredAt: /* @__PURE__ */ new Date(1700000103),
+        properties: {}
+      }
+    ]
+  ]
+};
+var userLoginIdentify = {
+  in: (0, import_core.getEvent)("user login", {
+    timestamp: 1700000104,
+    user: { email: "user@example.com" },
+    data: {
+      email: "login@acme.com",
+      first_name: "Jane",
+      last_name: "Doe",
+      lifecycle: "lead"
+    }
+  }),
+  mapping: {
+    skip: true,
+    settings: {
+      identify: {
+        map: {
+          email: "data.email",
+          properties: {
+            map: {
+              firstname: "data.first_name",
+              lastname: "data.last_name",
+              lifecyclestage: "data.lifecycle"
+            }
+          }
+        }
+      }
+    }
+  },
+  out: [
+    [
+      "crm.contacts.basicApi.update",
+      "login@acme.com",
+      {
+        properties: {
+          firstname: "Jane",
+          lastname: "Doe",
+          lifecyclestage: "lead"
+        }
+      },
+      "email"
+    ]
+  ]
+};
+var objectIdAssociation = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000105,
+    user: { id: "hs-contact-789" }
+  }),
+  settings: {
+    email: void 0,
+    objectId: "user.id"
+  },
+  out: [
+    [
+      "events.send.basicApi.send",
+      {
+        eventName: "pe12345678_product_view",
+        objectId: "hs-contact-789",
+        occurredAt: /* @__PURE__ */ new Date(1700000105),
+        properties: {}
+      }
+    ]
+  ]
+};
+var noIdentity = {
+  in: (0, import_core.getEvent)("product view", {
+    timestamp: 1700000106,
+    user: {}
+  }),
+  out: []
+};
+var wildcardIgnored = {
+  in: (0, import_core.getEvent)("debug noise", {
+    timestamp: 1700000107,
+    user: { email: "user@example.com" }
+  }),
+  mapping: { ignore: true },
+  out: []
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  env,
+  step
+});