Merge pull request #1482 from nyaruka/seen_modifier

Add modifier for `last_seen_on`

Author: rowanseymour

flows/events/base_test.go

@@ -157,6 +157,12 @@ func TestEventMarshaling(t *testing.T) {
 			},
 			`contact_language_changed`,
 		},
+		{
+			func() flows.Event {
+				return events.NewContactLastSeenChanged(time.Date(2022, 2, 3, 13, 45, 30, 0, time.UTC))
+			},
+			`contact_last_seen_changed`,
+		},
 		{
 			func() flows.Event {
 				return events.NewContactNameChanged("Bryan")

flows/events/contact_last_seen_changed.go

@@ -0,0 +1,38 @@
+package events
+
+import (
+	"time"
+
+	"github.com/nyaruka/goflow/flows"
+)
+
+func init() {
+	registerType(TypeContactLastSeenChanged, func() flows.Event { return &ContactLastSeenChanged{} })
+}
+
+// TypeContactLastSeenChanged is the type of our contact last seen changed event
+const TypeContactLastSeenChanged string = "contact_last_seen_changed"
+
+// ContactLastSeenChanged events are created when the last seen on of the contact has been changed.
+//
+//	{
+//	  "uuid": "0197b335-6ded-79a4-95a6-3af85b57f108",
+//	  "type": "contact_last_seen_changed",
+//	  "created_on": "2006-01-02T15:04:05Z",
+//	  "seen_on": "2026-02-03T15:04:05Z"
+//	}
+//
+// @event contact_last_seen_changed
+type ContactLastSeenChanged struct {
+	BaseEvent
+
+	LastSeenOn time.Time `json:"last_seen_on"`
+}
+
+// NewContactLastSeenChanged returns a new contact last seen changed event
+func NewContactLastSeenChanged(seen time.Time) *ContactLastSeenChanged {
+	return &ContactLastSeenChanged{
+		BaseEvent:  NewBaseEvent(TypeContactLastSeenChanged),
+		LastSeenOn: seen,
+	}
+}

flows/modifiers/seen.go

@@ -0,0 +1,74 @@
+package modifiers
+
+import (
+	"context"
+	"time"
+
+	"github.com/nyaruka/gocommon/jsonx"
+	"github.com/nyaruka/goflow/assets"
+	"github.com/nyaruka/goflow/envs"
+	"github.com/nyaruka/goflow/flows"
+	"github.com/nyaruka/goflow/flows/events"
+	"github.com/nyaruka/goflow/utils"
+)
+
+func init() {
+	registerType(TypeSeen, readSeen)
+}
+
+// TypeSeen is the type of our seen modifier
+const TypeSeen string = "seen"
+
+// Seen modifies the last seen of a contact
+type Seen struct {
+	baseModifier
+
+	seenOn time.Time
+}
+
+// NewSeen creates a new seen modifier
+func NewSeen(seenOn time.Time) *Seen {
+	return &Seen{
+		baseModifier: newBaseModifier(TypeSeen),
+		seenOn:       seenOn,
+	}
+}
+
+// Apply applies this modification to the given contact
+func (m *Seen) Apply(ctx context.Context, eng flows.Engine, env envs.Environment, sa flows.SessionAssets, contact *flows.Contact, log flows.EventLogger) (bool, error) {
+	if contact.LastSeenOn() == nil || m.seenOn.After(*contact.LastSeenOn()) {
+		contact.SetLastSeenOn(m.seenOn)
+		log(events.NewContactLastSeenChanged(m.seenOn))
+		return true, nil
+	}
+
+	return false, nil
+}
+
+var _ flows.Modifier = (*Seen)(nil)
+
+//------------------------------------------------------------------------------------------
+// JSON Encoding / Decoding
+//------------------------------------------------------------------------------------------
+
+type seenEnvelope struct {
+	utils.TypedEnvelope
+
+	SeenOn time.Time `json:"seen_on"`
+}
+
+func readSeen(sa flows.SessionAssets, data []byte, missing assets.MissingCallback) (flows.Modifier, error) {
+	e := &seenEnvelope{}
+	if err := utils.UnmarshalAndValidate(data, e); err != nil {
+		return nil, err
+	}
+
+	return NewSeen(e.SeenOn), nil
+}
+
+func (m *Seen) MarshalJSON() ([]byte, error) {
+	return jsonx.Marshal(&seenEnvelope{
+		TypedEnvelope: utils.TypedEnvelope{Type: m.Type()},
+		SeenOn:        m.seenOn,
+	})
+}

flows/modifiers/testdata/_assets.json

@@ -96,6 +96,11 @@
             "uuid": "b4546d78-e202-4d59-9114-9bcaa2b6ee86",
             "name": "Open Tickets",
             "query": "tickets > 0"
+        },
+        {
+            "uuid": "23d0f9a4-5bb8-4577-b518-d404caef8cf3",
+            "name": "Seen In 2026",
+            "query": "last_seen_on >= 2026-01-01"
         }
     ],
     "topics": [

flows/modifiers/testdata/seen.json

@@ -0,0 +1,47 @@
+[
+    {
+        "description": "last seen changed event if changed",
+        "contact_before": {
+            "uuid": "5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f",
+            "name": "Bob",
+            "status": "active",
+            "created_on": "2018-06-20T11:40:30.123456789Z"
+        },
+        "modifier": {
+            "type": "seen",
+            "seen_on": "2026-02-03T11:40:30.123456789Z"
+        },
+        "contact_after": {
+            "uuid": "5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f",
+            "name": "Bob",
+            "status": "active",
+            "created_on": "2018-06-20T11:40:30.123456789Z",
+            "last_seen_on": "2026-02-03T11:40:30.123456789Z",
+            "groups": [
+                {
+                    "uuid": "23d0f9a4-5bb8-4577-b518-d404caef8cf3",
+                    "name": "Seen In 2026"
+                }
+            ]
+        },
+        "events": [
+            {
+                "uuid": "01969b47-0583-76f8-ae7f-f8b243c49ff5",
+                "type": "contact_last_seen_changed",
+                "created_on": "2025-05-04T12:30:46.123456789Z",
+                "last_seen_on": "2026-02-03T11:40:30.123456789Z"
+            },
+            {
+                "uuid": "01969b47-0d53-76f8-bd38-d266ec8d3716",
+                "type": "contact_groups_changed",
+                "created_on": "2025-05-04T12:30:48.123456789Z",
+                "groups_added": [
+                    {
+                        "uuid": "23d0f9a4-5bb8-4577-b518-d404caef8cf3",
+                        "name": "Seen In 2026"
+                    }
+                ]
+            }
+        ]
+    }
+]