More Events for each entity

[Draykee]

Is your feature request related to a problem? Please describe.
I would like to know when a user get's verified. Currently there is no event for this. Having more events can be extremly helpful for analyzing activities.

Describe the solution you'd like
A event for each entity and every special activity (like coupon code usage, promotions, etc.)
Maybe we should make a list first, but implementing it should be easy.

Describe alternatives you've considered
Overwriting each resolver. But that's a hughe overhead

[michaelbromley]

Yes I totally agree. I've so far added events on a kinda ad-hoc basis, whenever I realized I needed one, I added it.

But now a more systematic approach makes sense, because there are infinite use-cases so we better just add all the events that could reasonably be needed. Do you want to have a go at making a list?

[Draykee]

@michaelbromley somehow like this?

So at first I think we can generalize it to this:

class EntityEvent<T> extends VendureEvent {
  type: 'created' | 'updated' | 'deleted',
  entity: T;
  input?: any; //< maybe for update event it's nice to know what changed, or the create input to react on custom fields
}

I also had the idea to add a initiator: User property. This might be obsolet if we would just add the request context used.

---

Address
Example: Maybe a plugin that groups customer by locations

• CustomerAddressEvent

Administrator
Example: Maybe to add notifications for more security

• AdministratorEvent (EntityEvent<Administrator>)

Asset
Example: Maybe the creator is important for copyrights

• AssetEvent (maybe also reword with EntityEvent and the initiator: User)

Channel
Example: For all marketplace plugins to create additional data for a newly generated channel

• ChannelEvent (EntityEvent<Channel>, initiator: User)

Collection
Example: Maybe a plugin that auto disables a collection after some time, so we need to start a cronjob when created

• CollectionEvent (EntityEvent<Collection>, initiator: User)
• CollectionModificationEvent

Country
Example: - no clue -

• CountryEvent (EntityEvent<Country>)

Customer

• CustomerEvent

CustomerGroup

• CustomerGroupEvent

Facet

• FacetEvent (EntityEvent<Facet>, initiator: User)

FacetValue

• FacetValueEvent (EntityEvent<FacetValue>, initiator: User)

Fulfillment

• FulfillmentStateTransitionEvent
• FulfillmentEvent (EntityEvent<Fulfillment>, initiator: User)

GlobalSettings

• GlobalSettingsUpdateEvent (because this is not created/deleted)

HistoryEntry

• HistoryEntryEvent (EntityEvent<HistoryEntry>, historyType: 'order' | 'customer' )
  @michaelbromley Is it possible to create more HistoryEntry types?

Order

• OrderStateTransitionEvent (will also cover "created" and "cancel")
• OrderActivity (One or multiple Event to track activities in the order entity without state transition)

OrderLine

• OrderLineEvent (EntityEvent<OrderLine>)

OrderItem

• OrderItemEvent (EntityEvent<OrderItem>)

Payment

• PaymentEvent (EntityEvent<Payment>, initiator: User)
• PaymentStateTransitionEvent

PaymentMethod
Example: Maybe it can be used to run some connection tests or something when a api key changed

• PaymentMethodEvent (EntityEvent<PaymentMethod>, initiator: User)

Product

• ProductEvent
• ProductEvent
• ProductChannelEvent
  ProductVariant
• ProductVariantChannelEvent
• ProductVariantEvent

Promotion

• PromotionEvent (EntityEvent<Promotion>)

Refund

• RefundStateTransitionEvent
• RefundEvent (EntityEvent<Refund>)

Role

• RoleEvent (EntityEvent<Role>, initiator: User)
• RoleChangeEvent (type: 'assigned | removed like CustomerGroupEvent )

Session
I'm not sure about this one...

ShippingLine

• ShippingLineEvent (EntityEvent<ShippingLine>, initiator: User)

ShippingMethod

• ShippingMethodEvent (EntityEvent<ShippingMethod>, initiator: User)

StockMovement

• StockMovementEvent

Surcharge

• SurchargeEvent (EntityEvent<Surcharge>, initiator: User)

Tag
@michaelbromley I'm not sure how this work. Maybe a TagAssignedEvent?

TaxCategory

• TaxCategoryEvent (EntityEvent<TaxCategory>, initiator: User)

TaxRate

• TaxRateModificationEvent
• TaxRateEvent (EntityEvent<TaxRate>, initiator: User)

User

• LoginEvent
• LogoutEvent
• AttemptedLoginEvent
• IdentifierChangeEvent
• IdentifierChangeRequestEvent
• PasswordResetEvent
• VerifiedEvent (when email was verified)
• UserUpdateEvent (I think create/delete doesn't need to be covered, but changes in customFields )
• RequestPasswordResetEvent

Zone
Can we create own zones?

• ZoneEvent (EntityEvent<Zone>, initiator: User)

[michaelbromley]

Yes perfect, though I don't think we need to list examples.

[Draykee]

I've updated the list. Maybe we can ask on slack if someone needs a special event. (We need a UserVerifiedEvent for example)

[Draykee]

What do you think about this:

class VendureEntityEvent<T> extends VendureEvent {
  type: 'created' | 'updated' | 'deleted',
  entity: T;
  input?: any; // the mutation input used for the event
  initiator?: User; // the user that initiated the entity operation
}

Optional properties input and initiator:
PRO: More information on the context where/how the event was published
CON: It's only optional and maybe not always present

[michaelbromley]

@Draykee yes this makes sense. We could deprecate the specific <entity type>Event events and replace them with this. For now we'd have to publish both, but remove the specific versions in v2.0.

Rather than the initiator field, why not include ctx, since it is possible to get the initiatior from that object using ctx.activeUserId already, plus RequestContext provides a whole bunch of other useful info, like which API & channel was being used etc.

[Draykee]

@michaelbromley This feature is pretty urgent for my master thesis about gamification. So maybe I'll start working on this soon.

One more question, shall I place every event inside the events directory? Or inside the related entity directory?

[michaelbromley]

Put any new events next to the existing ones in the "events" dir. If you want to work on this, make a PR against the minor branch and we can get this into the v1.4 release, which I expect to land in the next month-ish.

[Draykee]

In an type: 'update' event, is it better to store the "before" entity or the "updated" entity? I think the "before" entity might be better, because the event subscriber can still get the new updated one from database but not the one before updating it. Furthermore the input property can be used to understand what changed.

EDIT: I saw that other events are using the "before" entity in the event too. I think I will go with this approach and document that.

[Draykee]

Are ProductOptionGroups and ProductOptions never deleted? At least I couldn't find a function for that inside the services.

[Draykee]

@michaelbromley I think I've covered most of the entity events now. I just would like to ask for assitance with the Order entity.
I don't really know what operations can be executed and which one are covered by the stage transition events.

[Draykee]

Resolved with: #1222