node: add context, timestamp, integration options (#694)

Author: silesky

packages/node/README.md

@@ -277,3 +277,29 @@ export const lowercase: Plugin = {
 analytics.register(lowercase)
 
 ```
+
+## Selecting Destinations
+The alias, group, identify, page and track calls can all be passed an object of integrations that lets you turn certain destinations on or off. By default all destinations are enabled.
+
+Here’s an example with the integrations object shown:
+```ts
+analytics.track({
+  event: 'Membership Upgraded',
+  userId: '97234974',
+  integrations: {
+    'All': false,
+    'Vero': true,
+    'Google Analytics': false
+  }
+})
+```
+
+In this case, we’re specifying that we want this track to only go to Vero. All: false says that no destination should be enabled unless otherwise specified. Vero: true turns on Vero, etc.
+
+Destination flags are case sensitive and match the [destination’s name in the docs](https://segment.com/docs/connections/destinations) (i.e. “AdLearn Open Platform”, “awe.sm”, “MailChimp”, etc.). In some cases, there may be several names for a destination; if that happens you’ll see a “Adding (destination name) to the Integrations Object” section in the destination’s doc page with a list of valid names.
+
+Note:
+
+- Available at the business level, filtering track calls can be done right from the Segment UI on your source schema page. We recommend using the UI if possible since it’s a much simpler way of managing your filters and can be updated with no code changes on your side.
+
+- If you are on a grandfathered plan, events sent server-side that are filtered through the Segment dashboard will still count towards your API usage.

packages/node/src/app/analytics-node.ts

@@ -6,11 +6,11 @@ import {
   CorePlugin,
   EventFactory,
   EventQueue,
-  CoreOptions,
   CoreSegmentEvent,
   bindAll,
   PriorityQueue,
   pTimeout,
+  Integrations,
 } from '@segment/analytics-core'
 import { AnalyticsSettings, validateSettings } from './settings'
 import { version } from '../../package.json'
@@ -23,6 +23,7 @@ import { NodeEmitter } from './emitter'
 export class Context extends CoreContext {}
 
 export interface Plugin extends CorePlugin {}
+type Timestamp = string | Date
 
 /**
  * An ID associated with the user. Note: at least one of userId or anonymousId must be included.
@@ -31,11 +32,11 @@ type IdentityOptions =
   | { userId: string; anonymousId?: string }
   | { userId?: string; anonymousId: string }
 
-/** Events from CoreOptions */
-export interface SegmentEventOptions {
-  context?: Context
-  timestamp?: CoreOptions['timestamp']
-}
+/**
+ * A dictionary of extra context to attach to the call.
+ * Note: context differs from traits because it is not attributes of the user itself.
+ */
+type AdditionalContext = Record<string, any>
 
 class NodePriorityQueue extends PriorityQueue<Context> {
   constructor() {
@@ -55,7 +56,6 @@ type SegmentEventType = 'track' | 'page' | 'identify' | 'alias' | 'screen'
 
 export interface SegmentEvent extends CoreSegmentEvent {
   type: SegmentEventType
-  options?: SegmentEventOptions
 }
 
 export class Analytics extends NodeEmitter implements CoreAnalytics {
@@ -148,17 +148,25 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
     {
       userId,
       previousId,
-      options,
+      context,
+      timestamp,
+      integrations,
     }: {
       /* The new user id you want to associate with the user. */
       userId: string
       /* The previous id that the user was recognized by (this can be either a userId or an anonymousId). */
       previousId: string
-      options?: SegmentEventOptions
+      context?: AdditionalContext
+      timestamp?: Timestamp
+      integrations?: Integrations
     },
     callback?: Callback
   ): void {
-    const segmentEvent = this._eventFactory.alias(userId, previousId, options)
+    const segmentEvent = this._eventFactory.alias(userId, previousId, {
+      context,
+      integrations,
+      timestamp,
+    })
     this._dispatch(segmentEvent, callback)
   }
 
@@ -168,22 +176,28 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
    */
   group(
     {
+      timestamp,
       groupId,
       userId,
       anonymousId,
       traits = {},
-      options = {},
+      context,
+      integrations,
     }: IdentityOptions & {
       groupId: string
       traits?: Traits
-      options?: SegmentEventOptions
+      context?: AdditionalContext
+      timestamp?: Timestamp
+      integrations?: Integrations
     },
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.group(groupId, traits, {
-      ...options,
+      context,
       anonymousId,
       userId,
+      timestamp,
+      integrations,
     })
 
     this._dispatch(segmentEvent, callback)
@@ -198,17 +212,20 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       userId,
       anonymousId,
       traits = {},
-      options,
+      context,
+      integrations,
     }: IdentityOptions & {
       traits?: Traits
-      options?: SegmentEventOptions
+      context?: AdditionalContext
+      integrations?: Integrations
     },
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.identify(userId, traits, {
-      ...options,
+      context,
       anonymousId,
       userId,
+      integrations,
     })
     this._dispatch(segmentEvent, callback)
   }
@@ -224,25 +241,27 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       category,
       name,
       properties,
-      options,
+      context,
       timestamp,
+      integrations,
     }: IdentityOptions & {
       /*  The category of the page. Useful for cases like ecommerce where many pages might live under a single category. */
       category?: string
       /* The name of the page.*/
       name?: string
       /* A dictionary of properties of the page. */
       properties?: EventProperties
-      timestamp?: string | Date
-      options?: SegmentEventOptions
+      timestamp?: Timestamp
+      context?: AdditionalContext
+      integrations?: Integrations
     },
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.page(
       category ?? null,
       name ?? null,
       properties,
-      { ...options, anonymousId, userId, timestamp }
+      { context, anonymousId, userId, timestamp, integrations }
     )
     this._dispatch(segmentEvent, callback)
   }
@@ -260,16 +279,17 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       category,
       name,
       properties,
-      options,
+      context,
       timestamp,
+      integrations,
     }: Parameters<Analytics['page']>[0],
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.screen(
       category ?? null,
       name ?? null,
       properties,
-      { ...options, anonymousId, userId, timestamp }
+      { context, anonymousId, userId, timestamp, integrations }
     )
 
     this._dispatch(segmentEvent, callback)
@@ -285,18 +305,24 @@ export class Analytics extends NodeEmitter implements CoreAnalytics {
       anonymousId,
       event,
       properties,
-      options,
+      context,
+      timestamp,
+      integrations,
     }: IdentityOptions & {
       event: string
       properties?: EventProperties
-      options?: SegmentEventOptions
+      context?: AdditionalContext
+      timestamp?: Timestamp
+      integrations?: Integrations
     },
     callback?: Callback
   ): void {
     const segmentEvent = this._eventFactory.track(event, properties, {
-      ...options,
+      context,
       userId,
       anonymousId,
+      timestamp,
+      integrations,
     })
 
     this._dispatch(segmentEvent, callback)