Unable to add properties at the root level of messages in @segment/analytics-node

[lzear]

Hello

We are updating from analytics-node to @segment/analytics-node (because of segmentio/analytics-node#309), and we're facing a small issue that could be worth addressing or documenting: we're placing some custom properties at the root of the tracked events, even though I understand this is not how the API is documented (docs). It was working with analytics-node but it breaks with @segment/analytics-node.

(option 1): Would it be possible to change @segment/analytics-node and @segment/analytics-core so extra properties are placed at the root of the tracked object, so there is one less breaking change with analytics-node?

(option 2) If not, I think it would be beneficial to add warning in packages/node/README.md because it's probably not only our team that made this mistake 😄

---

If option 2 is chosen, the update in packages/node/README.md could look like this:

Differences from legacy analytics-node / Migration Guide

[...]

• Preventing custom properties to be set directly at the root of the event

  // old (this was possible even though that is not how the API is documented)
  analytics.track({
    userId,
    event: 'Bookmarked Article',
    title: 'Moby Dick',
    author: 'Herman Melville',
  })
  
  // new (custom properties placed on the root will be lost)
  analytics.track({
    userId,
    event: 'Bookmarked Article',
    properties: {
      title: 'Moby Dick',
      author: 'Herman Melville',
    }
  })

[silesky]

@lzear I really appreciate you letting us know about the legacy behavior! I think this is something we'd rather not port to the new SDK, as we'd prefer conventions / predictability in our API over saving keystrokes.

The latter "documentation" solution is the right one! Feel free to make a PR; or, I can do it after the holidays.