Events API

Planned

This module is not yet shipped. The shape below describes the intended endpoints on the new Hono + Supabase + Drizzle stack. Geo queries depend on enabling PostGIS on the Supabase Postgres (already documented in api/docs/DATABASE.md).

Create and manage events. Events are the primary social object: users create them, invite friends as co-authors, and other users form like groups to apply.

See also: Event lifecycle, Feed algorithm, Events model.

All endpoints require Authorization: Bearer <supabase-access-token>.

Endpoints

Method	Path	Description
POST	/events	Create event (in draft)
GET	/events	Browse events feed
GET	/events/:id	Get event details
PATCH	/events/:id	Update event (before start_at)
DELETE	/events/:id	Soft-delete
POST	/events/:id/restore	Restore a soft-deleted event
POST	/events/:id/publish	draft → published
POST	/events/:id/cancel	published | started → cancelled
POST	/events/:id/authors	Invite a friend as co-author
GET	/events/:id/authors	List authors
DELETE	/events/:id/authors/:userId	Remove a co-author (creator only)
POST	/events/:id/like	Create a solo or group like
GET	/events/:id/likes	List like groups for the event

Create event

POST /events
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Saturday Night Party",
  "description": "Join us for drinks!",
  "type": "party",
  "visibility": "public",
  "startAt": "2026-05-15T20:00:00Z",
  "endAt": "2026-05-16T02:00:00Z",
  "latitude": 40.7128,
  "longitude": -74.006,
  "capacity": 50
}

Field	Type	Required	Notes
title	string	✅
description	string
type	enum	✅	party, dinner, outdoor, sports
visibility	enum	✅	public, private
startAt	ISO8601	✅
endAt	ISO8601
latitude	number	✅	WGS84
longitude	number	✅	WGS84
capacity	int		Default 200; creator + authors don't count

Response

{
  "id": "uuid",
  "creatorId": "uuid",
  "status": "draft",
  "...": "..."
}

Feed

GET /events?lat=40.7128&lng=-74.006&radius=5000
Authorization: Bearer <token>

Query	Description
lat, lng	Required when filtering by location
radius	Metres (default 5000) — uses ST_DWithin on geography(Point, 4326)
type	Filter by event type
friendsOnly	Only events created by friends
cursor, limit	Pagination
startDate, endDate	ISO date range filter

Visibility rule:

visible = event.visibility = 'public' OR is_friend(viewer, event.creator)

Sort order: distance ASC, then start_at ASC. See Feed algorithm for the full details and boost-by-preferences design.

Update / cancel / delete

PATCH /events/:id     # only while now() < startAt
POST /events/:id/cancel   # any time, by creator or any author
DELETE /events/:id    # soft delete (sets deleted_at)
POST /events/:id/restore  # before status='finished'

After start_at the event becomes immutable for content fields. See Event lifecycle for the locked-fields list and state machine.

Authors

Only friends of the creator can be invited as authors.

POST /events/:id/authors
{ "userId": "friend-uuid" }

Limit	Value
Authors per event	10

Like an event

Solo or group like.

POST /events/:id/like
{ "memberIds": ["friend-1", "friend-2"] }   // optional

• Without memberIds → solo like (group of size 1).
• All memberIds must be friends of the caller.
• A user can only be in one pending like group per event.

{
  "id": "group-uuid",
  "eventId": "event-uuid",
  "status": "pending",
  "memberIds": ["caller-uuid", "friend-1", "friend-2"]
}

See the Like Groups API for approval, removal and chat-creation side effects.

Implementation notes

• Geo: events store geography(Point, 4326). PostGIS is required; see api/docs/DATABASE.md for the existing setup of geography columns on cities and profiles.
• Soft delete: deleted_at is partial-indexed for fast feed queries (WHERE deleted_at IS NULL).
• Realtime: clients can subscribe to event:{eventId} via Supabase Realtime to receive event.updated notifications.
• Module layout will follow the shipped pattern: src/feats/events/{router,service,schemas,constants}.ts.