Purpose

The Activity Feed service provides a unified interface to access recent activity events in the Seed system. It enables clients to list, filter, and paginate events, ensuring that product, design, and technical teams have a consistent foundation for building feeds, notifications, and collaborative views.

Status

This is a v1alpha specification. Breaking changes may occur as we validate the design and gather feedback.

Protobuf Definition

syntax = "proto3";

package com.seed.activity.v1alpha;

import "google/protobuf/timestamp.proto";

option go_package = "seed/backend/genproto/activity/v1alpha;activity";

// ActivityFeed service provides information about the recent activity events happened in the system.
service ActivityFeed {
  // Lists the recent activity events,
  // sorted by locally observed time (newest first).
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse);
}

// The request to list the events.
message ListEventsRequest {
  // Optional. The size of the page. The default is defined by the server.
  int32 page_size = 1;

  // Optional. The page token for requesting next pages.
  string page_token = 2;

  // Optional. If we want events from trusted peers only. All peers by default.
  bool trusted_only = 3;

  // Optional. If we want events only from specific user accounts. Multiple 
  // authors are filtered following OR logic.
  repeated string filter_authors = 4;

  // Optional. If we want certain types of events.
  // Currently supported event types are:
  //   - Ref: any document change
  //   - Capability: obvious
  //   - Comment: obvious
  //   - DagPB: 
  //   - Profile: 
  //   - Contact: create a contact for a specific resource
  // Multiple types are filtered following OR logic.
  repeated string filter_event_type = 5;

  // Optional. If we want events only from specific resource IDs.
  // It admits wildards, i.e. we can filter by path prefixes.
  string filter_resource = 6;

  // Optional. If we want to include link events. These blobs (usually documents
  // or comments), link (mention) to another resource (currently only account
  // mentions supported). We can add these blobs to the feed result by providing a 
  // list of resources iris we want links to aggregated as a logical OR. 
  // These link events are also treated as logical OR when grouped with other filters,
  // unlike other filters (authors, event_types) that are grouped under a logic AND. 
  // Example: filter_authors(u+a1 OR a2 ...) AND filter_event_type(et1 OR et2 ...) OR 
  // add_linked_resource(lr1 OR lr2 ...)
  repeated string add_linked_resource = 7;
}

// The response with the list of events.
message ListEventsResponse {
  // The list of events.
  repeated Event events = 1;

  // The token to request the next page.
  string next_page_token = 2;
}

// Description of the event occurred in the system.
message Event {
  // Union type of different event types.
  // Eventually we'll have more event types.
  oneof data {
    // Event type describing the appearance of a new blob in the system.
    NewBlobEvent new_blob = 1;
  }

  // The ID of the user account that has caused the event.
  string account = 2;

  // Timestamp of the event as per the event itself.
  google.protobuf.Timestamp event_time = 3;

  // Locally perceived time of the event.
  // I.e. time when we have received the event on our machine.
  google.protobuf.Timestamp observe_time = 4;
}

// The event describing the
message NewBlobEvent {
  // The CID of the blob that was created.
  string cid = 1;

  // The type of the blob that was created.
  // Defined as string for extensibility.
  // Some of the currently supported blob types are:
  //   - KeyDelegation
  //   - Change
  //   - Comment
  //   - DagPB
  string blob_type = 2;

  // The user account ID that has created the blob.
  string author = 3;

  // The resource ID that the blob is related to.
  string resource = 4;

  // Extra attributes of the blob.
  string extra_attrs = 5;

  int64 blob_id = 6;

  // Only relevant for ling events
  bool is_pinned = 7;
}