Dreamspace/adventures
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Start chapter expansion.

Interitio
2025-06-18 23:44:51 +10:00
parent 487b37c5a7
commit 8b988620be
2 changed files with 54 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
document.md

@@ -3,7 +3,7 @@ Represents a saved document, i.e. and image with a seal and optionally some stam
Will usually be associated with an `Event`, and event documents should generally be queried through the Event routes. Will usually be associated with an `Event`, and event documents should generally be queried through the Event routes.
However, `Document` also supports CRUD operations separately for storing arbitrary non-event documents. However, `Document` also supports CRUD operations separately for storing arbitrary non-event documents.
## Fields
| field | type | required | description | | field | type | required | description |
| --------------- | --------- | -------- | -------------------------------------------------------------- | | --------------- | --------- | -------- | -------------------------------------------------------------- |
| `document_id` | integer | - | UID for this document | | `document_id` | integer | - | UID for this document |
@@ -13,6 +13,8 @@ However, `Document` also supports CRUD operations separately for storing arbitra
| `metadata` | string? | no | Optional arbitrary associated metadata. | | `metadata` | string? | no | Optional arbitrary associated metadata. |
| `stamps` | [`Stamp`] | no | List of stamps attached to this document. | | `stamps` | [`Stamp`] | no | List of stamps attached to this document. |
## Routes
- `POST` `/documents` - `POST` `/documents`
- Create and return a `Document`. - Create and return a `Document`.
- Stamps may be added to the document by passing a list of `Stamp`s in the `stamps` field. - Stamps may be added to the document by passing a list of `Stamp`s in the `stamps` field.
@@ -40,4 +42,3 @@ However, `Document` also supports CRUD operations separately for storing arbitra
- Returns the deleted `Document`. - Returns the deleted `Document`.
- `*` `/documents/{document_id}/stamps` - `*` `/documents/{document_id}/stamps`
- Inherits all `/stamps` routes with `document_id` set. - Inherits all `/stamps` routes with `document_id` set.

89
event.md

@@ -3,6 +3,10 @@ An Event represents event data for one of the saved events.
This will typically have a `Document` attached with image data saved from the event. This will typically have a `Document` attached with image data saved from the event.
Events may also be created without documents, in which case the `document` and `document_id` fields will be `null`. Events may also be created without documents, in which case the `document` and `document_id` fields will be `null`.
There are four types of events ('PlainEvent', 'SubEvent', 'CheerEvent', 'RaidEvent'), identified by their `event_type` field.
The API will only ever accept or return these four concrete types, and never the abstract `Event` type. However, the abstraction is useful since multi-value endpoints such as `GET /events` will return a combination of these concrete types, which we shall just refer to as `Event`s.
## Fields
| field | type | required | description | | field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- | | ------------ | ------- | -------- | --------------------------------------------------------------- |
| `event_id` | integer | - | UID for this event | | `event_id` | integer | - | UID for this event |
@@ -17,16 +21,56 @@ Events may also be created without documents, in which case the `document` and `
Allowed and possible values for `EventType` are `plain`, `subscriber`, `cheer`, `raid`. Allowed and possible values for `EventType` are `plain`, `subscriber`, `cheer`, `raid`.
The `event_type` *must* be specified when creating an event. The `event_type` *must* be specified when creating an event (you cannot create a base Event, only one of the following four event types).
### `PlainEvent`
An `Event` of type `plain` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `message` | string | yes | Message for this event. |
### `SubEvent`
An `Event` of type `subscriber` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `tier` | integer | yes | Tier of the subscription. |
| `subscribed_length` | integer | yes | Subscription length (not sure what the unit is?) |
| `message` | string? | no | Subscription message. |
- [ ] What is the unit of `subscribed_length`? Is it cumulative? Does it make any sense to have `subscription_start` for the start of the current subscription?
- [ ] `message` was not in the original spec, does it make sense to add?
### `CheerEvent`
An `Event` of type `cheer` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | -------------------------------------- |
| `amount` | integer | yes | Number of bits cheered |
| `cheer_type` | string? | no | Type of cheer |
| `message` | string? | no | Message associated with the bit cheer. |
- [ ] `type` was not in the original spec, does it make sense? `message` as well.
### `RaidEvent`
An `Event` of type `raid` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `viewer_count` | integer | yes | Number of viewers who came with the raid. |
## Routes
- `POST` `/events` - `POST` `/events`
- Create a return a new `Event`. - Create a return a new `Event`.
- The `event_type` *must* be specified, and the additional fields for that event type should be considered. - The `event_type` *must* be specified, and the additional fields for that event type should be considered.
- The `document` *should* be specified in the form of a `Document` (as in `POST /documets`). - The `document` *should* be specified in the form of a `Document` (as in `POST /documents`), however, may be specified as a `document_id` instead to attach to an existing document.
- The `user` *may* be specified in the form of a `User` (as in `POST /user`), in which case `user_id` is not required and will be filled from the created `User`. - The `user` *may* be specified in the form of a `User` (as in `POST /user`), in which case `user_id` is not required and will be filled from the created `User`.
- Supplying both `user_id` and `user` is not supported. - Supplying both `user_id` and `user` is not supported.
- If a `user` already exists with the given `twitch_id`, then that `user` will instead be *updated* with the given fields, and the `user_id` of the existing user will be used to create the `Event`. This behaviour is distinct to the `POST /user` endpoint which will *error* if the user already exists. - If a `user` already exists with the given `twitch_id`, then that `user` will instead be *updated* with the given fields, and the `user_id` of the existing user will be used to create the `Event`. This behaviour is distinct to the `POST /users` endpoint which will *error* if the user already exists.
- `GET` `/events` - `GET` `/events`
- Returns `events` matching the provided filters. - Returns `events` matching the provided filters.
- Intended to be the typical way of retrieving events and documents. - Intended to be the typical way of retrieving events and documents.
@@ -59,42 +103,11 @@ The `event_type` *must* be specified when creating an event.
- [ ] It might make sense to add the subtype fields for filtering as well - [ ] It might make sense to add the subtype fields for filtering as well
#### `PlainEvent` ## Examples
An `Event` of type `plain` has the following further fields. ### Get sub events from a given user
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `message` | string | yes | Message for this event. |
#### `SubEvent` ### Create a message event, then add a stamp
An `Event` of type `subscriber` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `tier` | integer | yes | Tier of the subscription. |
| `subscribed_length` | integer | yes | Subscription length (not sure what the unit is?) |
| `message` | string? | no | Subscription message. |
- [ ] What is the unit of `subscribed_length`? Is it cumulative? Does it make any sense to have `subscription_start` for the start of the current subscription?
- [ ] `message` was not in the original spec, does it make sense to add?
#### `CheerEvent`
An `Event` of type `cheer` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | -------------------------------------- |
| `amount` | integer | yes | Number of bits cheered |
| `cheer_type` | string? | no | Type of cheer |
| `message` | string? | no | Message associated with the bit cheer. |
- [ ] `type` was not in the original spec, does it make sense? `message` as well.
#### `RaidEvent` ### Remove stamps from an event document
An `Event` of type `raid` has the following further fields.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `viewer_count` | integer | yes | Number of viewers who came with the raid. |