npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@molecule/api-resource-activity-feed

v1.0.7

Published

Activity feed and timeline with logging, feed queries, and unseen-count tracking for any resource

Readme

@molecule/api-resource-activity-feed

Activity feed resource for molecule.dev.

Activity timeline with logging, feed queries, resource timelines, and unseen-count tracking. Activities can reference any resource type.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { routes, requestHandlerMap } from '@molecule/api-resource-activity-feed'

// Wire routes into your Express app via mlcl inject
// POST /activities           — log an activity
// GET  /activities/feed      — paginated user feed
// GET  /activities/unseen    — unseen count
// POST /activities/seen      — mark seen up to ID
// GET  /activities/:resourceType/:resourceId — resource timeline

Type

resource

Installation

npm install @molecule/api-resource-activity-feed @molecule/api-database @molecule/api-i18n @molecule/api-logger @molecule/api-resource zod

API

Interfaces

Activity

A single activity entry in the feed.

interface Activity {
  /** Unique activity identifier. */
  id: string
  /** The ID of the user who performed the action. */
  actorId: string
  /** The action that was performed (e.g. 'created', 'updated', 'commented'). */
  action: string
  /** The type of resource the action was performed on (e.g. 'post', 'project'). */
  resourceType: string
  /** The ID of the resource the action was performed on. */
  resourceId: string
  /** Optional metadata associated with the activity. */
  metadata: Record<string, unknown> | null
  /** When the activity was created (ISO 8601). */
  createdAt: string
}

CreateActivityInput

Input for logging a new activity.

Note: this is the client-supplied payload — it deliberately omits actorId. The actor is derived from the authenticated session in the service/handler (actor = caller), never trusted from the request body, to prevent a user from forging activities that impersonate another user.

interface CreateActivityInput {
  /** The action that was performed. */
  action: string
  /** The type of resource the action was performed on. */
  resourceType: string
  /** The ID of the resource the action was performed on. */
  resourceId: string
  /** Optional metadata associated with the activity. */
  metadata?: Record<string, unknown>
}

ActivitySeenStatus

Tracks the last-seen activity position for a user.

interface ActivitySeenStatus {
  /** The user ID. */
  userId: string
  /** The ID of the last activity seen by this user. */
  lastSeenActivityId: string
  /** When this seen status was last updated (ISO 8601). */
  updatedAt: string
}

PaginationOptions

Options for paginated queries.

interface PaginationOptions {
  /** Maximum number of results to return. */
  limit?: number
  /** Number of results to skip. */
  offset?: number
}

PaginatedResult

A paginated result set.

interface PaginatedResult<T> {
  /** The result items for the current page. */
  data: T[]
  /** Total number of matching items across all pages. */
  total: number
  /** Maximum number of results per page. */
  limit: number
  /** Number of results skipped. */
  offset: number
}

FeedQuery

Options for querying a user's activity feed.

interface FeedQuery extends PaginationOptions {
  /** Filter to only activities involving this resource type. */
  resourceType?: string
  /** Filter to only activities with this action. */
  action?: string
}

Functions

feed(req, res)

Retrieves the paginated activity feed for the authenticated user.

function feed(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
  • req — The request with optional query params for filtering and pagination.
  • res — The response object.

log(req, res)

Logs a new activity to the feed.

function log(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
  • req — The request with activity creation body.
  • res — The response object.

seen(req, res)

Marks activities as seen for the authenticated user up to a given activity ID.

function seen(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
  • req — The request with upToId in body.
  • res — The response object.

timeline(req, res)

Retrieves the paginated activity timeline for a specific resource.

function timeline(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
  • req — The request with resourceType and resourceId params.
  • res — The response object.

unseen(_req, res)

Returns the number of unseen activities for the authenticated user.

function unseen(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>
  • _req — The request object (unused).
  • res — The response object.

logActivity(actorId, data)

Logs a new activity to the feed.

The actor is supplied explicitly by the caller (derived from the authenticated session in the handler), never read from the client-supplied data, so a user cannot forge activities impersonating another user.

function logActivity(actorId: string, data: CreateActivityInput): Promise<Activity>
  • actorId — The ID of the authenticated user who performed the action.
  • data — The activity creation input (client-supplied, never includes the actor).

Returns: The created activity.

getFeed(_userId, options)

Retrieves a paginated activity feed for a user. Returns activities from all actors, optionally filtered by resource type or action.

function getFeed(_userId: string, options?: FeedQuery): Promise<PaginatedResult<Activity>>
  • _userId — The user requesting the feed (reserved for future per-user filtering).
  • options — Query and pagination options.

Returns: A paginated result of activities.

getTimeline(resourceType, resourceId, options)

Retrieves a paginated timeline of activities for a specific resource.

function getTimeline(
  resourceType: string,
  resourceId: string,
  options?: PaginationOptions,
): Promise<PaginatedResult<Activity>>
  • resourceType — The resource type to get the timeline for.
  • resourceId — The resource ID to get the timeline for.
  • options — Pagination options.

Returns: A paginated result of activities.

markSeen(userId, upToId)

Marks activities as seen for a user up to a given activity ID.

function markSeen(userId: string, upToId: string): Promise<void>
  • userId — The user marking activities as seen.
  • upToId — The ID of the last activity seen.

getUnseenCount(userId)

Returns the number of unseen activities for a user. An activity is unseen if it was created after the user's last-seen position, or if the user has never marked anything as seen.

function getUnseenCount(userId: string): Promise<number>
  • userId — The user ID.

Returns: The count of unseen activities.

Constants

requestHandlerMap

Handler map for activity feed routes.

const requestHandlerMap: {
  readonly logActivity: typeof log
  readonly feed: typeof feed
  readonly unseen: typeof unseen
  readonly markSeen: typeof seen
  readonly timeline: typeof timeline
}

routes

Routes for activity feed operations.

const routes: readonly [
  {
    readonly method: 'post'
    readonly path: '/activities'
    readonly handler: 'logActivity'
    readonly middlewares: readonly ['authenticate']
  },
  {
    readonly method: 'get'
    readonly path: '/activities/feed'
    readonly handler: 'feed'
    readonly middlewares: readonly ['authenticate']
  },
  {
    readonly method: 'get'
    readonly path: '/activities/unseen'
    readonly handler: 'unseen'
    readonly middlewares: readonly ['authenticate']
  },
  {
    readonly method: 'post'
    readonly path: '/activities/seen'
    readonly handler: 'markSeen'
    readonly middlewares: readonly ['authenticate']
  },
  {
    readonly method: 'get'
    readonly path: '/activities/:resourceType/:resourceId'
    readonly handler: 'timeline'
  },
]

createActivitySchema

Schema for validating activity creation input.

Note: actorId is intentionally absent — the actor is always derived from the authenticated session in the handler (actor = caller), never accepted from the client body. Adding it here would let any user forge feed entries impersonating another user (broken access control). Mirror the comment/review/thread pattern.

const createActivitySchema: z.ZodObject<
  {
    action: z.ZodString
    resourceType: z.ZodString
    resourceId: z.ZodString
    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>
  },
  z.core.$strip
>

markSeenSchema

Schema for validating mark-seen input.

const markSeenSchema: z.ZodObject<{ upToId: z.ZodString }, z.core.$strip>

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-database ^1.0.1
  • @molecule/api-i18n ^1.0.1
  • @molecule/api-logger ^1.0.1
  • @molecule/api-resource ^1.0.1
  • zod ^4.0.0

Runtime Dependencies

  • @molecule/api-database

  • @molecule/api-i18n

  • @molecule/api-logger

  • @molecule/api-resource

  • zod

  • List endpoints return a PAGINATED envelope { data, total, limit, offset }, not a bare array — read the rows off result.data (server). On the client, unwrapList(res) from @molecule/app-http normalizes this envelope (pass it the whole HttpResponse), so the rows come back; reading the response as a bare array — or res.data alone (which is the envelope) — yields an EMPTY list.

  • Migration required. src/__setup__/activity-feeds.sql ships with this package (two tables: activities, activity_seen_status) and must exist in the target database before use (scaffolded apps apply it automatically).

  • The feed is GLOBAL, not per-user. getFeed() returns activities from ALL actors (its userId param is reserved) — right for public/social timelines. In an app with private data, do NOT mount GET /activities/feed as-is: it exposes every user's actions to any authenticated user. Filter by actor/resource in your own handler instead. Unseen counts are global too.

  • GET /activities/:resourceType/:resourceId (timeline) ships with NO auth middleware — resource timelines are public by default; add an authorizer when the underlying resources are private.

  • The actor is always the authenticated caller. POST /activities strips any client-supplied actorId (feed-entry forgery guard). Keep that property in custom paths — and prefer calling logActivity(actorId, data) directly from your server-side domain handlers over round-tripping the HTTP route.

  • resourceType/resourceId are free-form (no FK): pick canonical type slugs and reuse them across comments/bookmarks/reactions so timelines line up.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • [ ] Performing an in-app action that logs an activity (POST /activities, or a server-side logActivity() call) records ONE entry whose actorId is the session user, with the right action (verb), resourceType + resourceId (the object acted on), and a createdAt timestamp — verify by reading it back, not by trusting the 201.
  • [ ] That entry appears at the TOP of the feed (GET /activities/feed), which is strictly reverse-chronological (createdAt desc); logging a second activity pushes it above the first.
  • [ ] SCOPE — know what this feed is: getFeed() is GLOBAL, returning every actor's activity (its userId param is reserved/unused), NOT a per-user or following-based feed. Confirm that is the intent. If the app holds ANY private or per-user data, GET /activities/feed as-is leaks it (see privacy check) — replace it with an actor/resource-filtered handler.
  • [ ] Pagination is stable: page through with limit/offset back-to-back and every activity appears exactly once (none skipped, none duplicated), and total equals the real matching-row count. The resourceType/ action query filters narrow the feed to only matching entries.
  • [ ] GET /activities/:resourceType/:resourceId returns ONLY that one resource's timeline (reverse-chronological); an unrelated resource's activity is absent from it.
  • [ ] Read state (if the UI shows an unseen badge): GET /activities/unseen returns a count; POST /activities/seen { upToId } drops it to 0; a new activity logged afterward raises it again. The last-seen position is per-user (activity_seen_status keyed by userId) — mark seen as user A and user B's unseen count is unaffected.
  • [ ] PRIVACY / AUTHORIZATION — the actor cannot be forged: POST /activities with an actorId in the body still records the SESSION user as the actor (the schema strips it). Every endpoint fails closed for an anonymous caller — feed, unseen, seen, AND the timeline route (which ships with NO route middleware but 401s in-handler) all reject a sessionless request.
  • [ ] No cross-user leak: another user's activity on a PRIVATE actor or PRIVATE object must NOT surface to a viewer not allowed to see it — neither through the global feed nor by guessing a resourceId in the timeline URL. If it does, add the actor/resource filter (feed) and an authorizer (timeline) the remarks call for; the raw global endpoints are not safe over private data.