@proxima-nexus/openapi 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to the Proxima Nexus OpenAPI specification are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-03-04
+
+### Added
+
+- **Group event series**
+  - `GET /group/{groupId}/event-series`: list event series associated with a group, returned as `EventSeriesEntityConnectionDto` objects (including connection `type`, `state`, and `seriesId`).
+- **Event series batch lookup**
+  - `POST /event-series/batch`: fetch multiple event series in a single call using `GetEventSeriesDto.seriesIds`.
+- **Schemas**
+  - `EventSeriesEntityConnectionDto`: describes a user/group connection to an event series (timestamps, connection `type`/`state`, and `seriesId`).
+  - `GetEventSeriesDto`: request body for batch series lookup by IDs.
+
+## [2.2.0] - 2026-03-02
+
+### Added
+
+- **Event time range filters**
+  - `GET /event`: optional `from` / `to` query params to filter events by time window (`from` = events ending after this instant, `to` = events starting before this instant).
+  - `GET /user/{userId}/events`: optional `from` / `to` range filters with the same semantics; `from` defaults to “now” when omitted.
+  - `GET /group/{groupId}/events`: optional `from` / `to` range filters with the same semantics.
+  - `GET /events/search`: optional `from` / `to` range filters with the same semantics.
+  - `GET /event-series/{seriesId}/events`: optional `from` / `to` range filters with the same semantics.
+
+### Changed
+
+- **Event series instances**: `GET /event-series/{seriesId}/events` summary/description now clarify that the endpoint returns instances ordered by start time and **defaults to only ongoing/upcoming instances** unless a custom `from` / `to` window is provided.
+
 ## [2.1.0] - 2026-03-02
 
 ### Added

package/openapi.json

@@ -132,6 +132,26 @@
               "type": "number"
             }
           },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events ending after this time",
+            "schema": {
+              "example": "2025-01-01T00:00:00Z",
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events starting before this time",
+            "schema": {
+              "example": "2025-12-31T23:59:59Z",
+              "type": "string"
+            }
+          },
           {
             "name": "X-Proxima-Nexus-Requester-User-Id",
             "in": "header",
@@ -618,6 +638,24 @@
               "type": "string"
             }
           },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 start of range (events ending after this time). Default: NOW()",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 end of range (events starting before this time)",
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "X-Proxima-Nexus-Requester-User-Id",
             "in": "header",
@@ -799,6 +837,26 @@
               "type": "number"
             }
           },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events ending after this time",
+            "schema": {
+              "example": "2025-01-01T00:00:00Z",
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events starting before this time",
+            "schema": {
+              "example": "2025-12-31T23:59:59Z",
+              "type": "string"
+            }
+          },
           {
             "name": "X-Proxima-Nexus-Requester-User-Id",
             "in": "header",
@@ -1341,6 +1399,26 @@
               "type": "number"
             }
           },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events ending after this time",
+            "schema": {
+              "example": "2025-01-01T00:00:00Z",
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 date — filter events starting before this time",
+            "schema": {
+              "example": "2025-12-31T23:59:59Z",
+              "type": "string"
+            }
+          },
           {
             "name": "X-Proxima-Nexus-Requester-User-Id",
             "in": "header",
@@ -1736,6 +1814,24 @@
               "type": "string"
             }
           },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 start of range (events ending after this time). Default: NOW()",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 end of range (events starting before this time)",
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "X-Proxima-Nexus-Requester-User-Id",
             "in": "header",
@@ -1771,6 +1867,45 @@
         ]
       }
     },
+    "/group/{groupId}/event-series": {
+      "get": {
+        "operationId": "GroupController_getEventSeries",
+        "summary": "Get event series of a group",
+        "parameters": [
+          {
+            "name": "groupId",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event series returned",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/EventSeriesEntityConnectionDto"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "group"
+        ],
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
     "/group/batch": {
       "post": {
         "operationId": "GroupController_getBatch",
@@ -2017,11 +2152,51 @@
         ]
       }
     },
+    "/event-series/batch": {
+      "post": {
+        "operationId": "EventSeriesController_getBatch",
+        "summary": "Get a batch of event series by IDs",
+        "parameters": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetEventSeriesDto"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Event series returned",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/EventSeriesDto"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "event-series"
+        ],
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
     "/event-series/{seriesId}/events": {
       "get": {
         "operationId": "EventSeriesController_getInstances",
-        "summary": "List all event instances in a series",
-        "description": "Returns all event instances (past and upcoming) belonging to this series, ordered by start time.",
+        "summary": "List event instances in a series",
+        "description": "Returns event instances belonging to this series, ordered by start time. Defaults to only ongoing/upcoming instances.",
         "parameters": [
           {
             "name": "seriesId",
@@ -2030,6 +2205,24 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "from",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 start of range (events ending after this time). Default: NOW()",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "to",
+            "required": false,
+            "in": "query",
+            "description": "ISO 8601 end of range (events starting before this time)",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "responses": {
@@ -3048,6 +3241,54 @@
           "type"
         ]
       },
+      "EventSeriesEntityConnectionDto": {
+        "type": "object",
+        "properties": {
+          "createdAt": {
+            "type": "string",
+            "description": "Date/time the connection was created (ISO string)",
+            "example": "2024-05-01T12:34:56.789Z"
+          },
+          "updatedAt": {
+            "type": "string",
+            "description": "Date/time the connection was last updated (ISO string)",
+            "example": "2024-05-02T12:34:56.789Z"
+          },
+          "type": {
+            "type": "string",
+            "description": "Connection type",
+            "enum": [
+              "attendee",
+              "admin",
+              "owner",
+              "member",
+              "friend",
+              "blocked",
+              "none"
+            ]
+          },
+          "state": {
+            "type": "string",
+            "description": "Connection state",
+            "enum": [
+              "incoming_request",
+              "outgoing_request",
+              "active",
+              "requested",
+              "invited"
+            ]
+          },
+          "seriesId": {
+            "type": "string",
+            "description": "Event series ID",
+            "example": "series-123"
+          }
+        },
+        "required": [
+          "type",
+          "seriesId"
+        ]
+      },
       "GetGroupsDto": {
         "type": "object",
         "properties": {
@@ -3334,6 +3575,25 @@
             "example": 50
           }
         }
+      },
+      "GetEventSeriesDto": {
+        "type": "object",
+        "properties": {
+          "seriesIds": {
+            "description": "The IDs of the event series",
+            "example": [
+              "series-123",
+              "series-456"
+            ],
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "seriesIds"
+        ]
       }
     }
   }

package/openapi.yaml

@@ -93,6 +93,20 @@ paths:
           schema:
             example: 100
             type: number
+        - name: from
+          required: false
+          in: query
+          description: ISO 8601 date — filter events ending after this time
+          schema:
+            example: '2025-01-01T00:00:00Z'
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 date — filter events starting before this time
+          schema:
+            example: '2025-12-31T23:59:59Z'
+            type: string
         - name: X-Proxima-Nexus-Requester-User-Id
           in: header
           description: >-
@@ -411,6 +425,18 @@ paths:
           in: path
           schema:
             type: string
+        - name: from
+          required: false
+          in: query
+          description: 'ISO 8601 start of range (events ending after this time). Default: NOW()'
+          schema:
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 end of range (events starting before this time)
+          schema:
+            type: string
         - name: X-Proxima-Nexus-Requester-User-Id
           in: header
           description: >-
@@ -531,6 +557,20 @@ paths:
           schema:
             example: 100
             type: number
+        - name: from
+          required: false
+          in: query
+          description: ISO 8601 date — filter events ending after this time
+          schema:
+            example: '2025-01-01T00:00:00Z'
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 date — filter events starting before this time
+          schema:
+            example: '2025-12-31T23:59:59Z'
+            type: string
         - name: X-Proxima-Nexus-Requester-User-Id
           in: header
           description: >-
@@ -879,6 +919,20 @@ paths:
           schema:
             example: 100
             type: number
+        - name: from
+          required: false
+          in: query
+          description: ISO 8601 date — filter events ending after this time
+          schema:
+            example: '2025-01-01T00:00:00Z'
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 date — filter events starting before this time
+          schema:
+            example: '2025-12-31T23:59:59Z'
+            type: string
         - name: X-Proxima-Nexus-Requester-User-Id
           in: header
           description: >-
@@ -1129,6 +1183,18 @@ paths:
           in: path
           schema:
             type: string
+        - name: from
+          required: false
+          in: query
+          description: 'ISO 8601 start of range (events ending after this time). Default: NOW()'
+          schema:
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 end of range (events starting before this time)
+          schema:
+            type: string
         - name: X-Proxima-Nexus-Requester-User-Id
           in: header
           description: >-
@@ -1150,6 +1216,29 @@ paths:
         - group
       security:
         - api_key: []
+  /group/{groupId}/event-series:
+    get:
+      operationId: GroupController_getEventSeries
+      summary: Get event series of a group
+      parameters:
+        - name: groupId
+          required: true
+          in: path
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Event series returned
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/EventSeriesEntityConnectionDto'
+      tags:
+        - group
+      security:
+        - api_key: []
   /group/batch:
     post:
       operationId: GroupController_getBatch
@@ -1306,17 +1395,55 @@ paths:
         - event-series
       security:
         - api_key: []
+  /event-series/batch:
+    post:
+      operationId: EventSeriesController_getBatch
+      summary: Get a batch of event series by IDs
+      parameters: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GetEventSeriesDto'
+      responses:
+        '200':
+          description: Event series returned
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/EventSeriesDto'
+      tags:
+        - event-series
+      security:
+        - api_key: []
   /event-series/{seriesId}/events:
     get:
       operationId: EventSeriesController_getInstances
-      summary: List all event instances in a series
-      description: Returns all event instances (past and upcoming) belonging to this series, ordered by start time.
+      summary: List event instances in a series
+      description: >-
+        Returns event instances belonging to this series, ordered by start time. Defaults to only ongoing/upcoming
+        instances.
       parameters:
         - name: seriesId
           required: true
           in: path
           schema:
             type: string
+        - name: from
+          required: false
+          in: query
+          description: 'ISO 8601 start of range (events ending after this time). Default: NOW()'
+          schema:
+            type: string
+        - name: to
+          required: false
+          in: query
+          description: ISO 8601 end of range (events starting before this time)
+          schema:
+            type: string
       responses:
         '200':
           description: Event instances returned
@@ -2063,6 +2190,44 @@ components:
             - owner
       required:
         - type
+    EventSeriesEntityConnectionDto:
+      type: object
+      properties:
+        createdAt:
+          type: string
+          description: Date/time the connection was created (ISO string)
+          example: '2024-05-01T12:34:56.789Z'
+        updatedAt:
+          type: string
+          description: Date/time the connection was last updated (ISO string)
+          example: '2024-05-02T12:34:56.789Z'
+        type:
+          type: string
+          description: Connection type
+          enum:
+            - attendee
+            - admin
+            - owner
+            - member
+            - friend
+            - blocked
+            - none
+        state:
+          type: string
+          description: Connection state
+          enum:
+            - incoming_request
+            - outgoing_request
+            - active
+            - requested
+            - invited
+        seriesId:
+          type: string
+          description: Event series ID
+          example: series-123
+      required:
+        - type
+        - seriesId
     GetGroupsDto:
       type: object
       properties:
@@ -2277,3 +2442,16 @@ components:
           type: number
           description: Maximum number of attendees per event instance (null = unlimited)
           example: 50
+    GetEventSeriesDto:
+      type: object
+      properties:
+        seriesIds:
+          description: The IDs of the event series
+          example:
+            - series-123
+            - series-456
+          type: array
+          items:
+            type: string
+      required:
+        - seriesIds

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@proxima-nexus/openapi",
-    "version": "2.1.0",
+    "version": "2.3.0",
     "description": "OpenAPI specification for Proxima Nexus",
     "main": "openapi.json",
     "types": "openapi.json",