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

Refactor docs structure.

Interitio
2025-06-18 19:24:59 +10:00
parent 0ed37b7e1d
commit be62b21b68
12 changed files with 520 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
api/api-reference.md Normal file

@@ -0,0 +1,7 @@
## Models
---

128
api/api-tasklist.md Normal file

@@ -0,0 +1,128 @@
## API Routes to implement
- [x] `/stamps`
- [x] `POST`
- [x] `PUT`
- [x] `GET`
- [x] `/stamps/{stamp_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/documents`
- [x] `POST`
- [x] `GET`
- [x] `/documents/{document_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/documents/{document_id}/stamps` which is passed to `/stamps` with `document_id` set.
- [x] `/events`
- [x] `POST`
- [x] `GET`
- [x] `/events/{event_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/events/{event_id}/document` which is passed to `/documents/{document_id}`
- [x] `/events/{event_id}/user` which is passed to `/users/{user_id}`
- [x] `/users`
- [x] `POST`
- [x] `GET`
- [x] `/users/{user_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/users/{user_id}/events` which is passed to `/events`
- [x] `/users/{user_id}/specimen` which is passed to `/specimens/{specimen_id}`
- [x] `/users/{user_id}/specimens` which is passed to `/specimens`
- [x] `/users/{user_id}/wallet` with `GET`
- [x] `/users/{user_id}/transactions` which is passed to `/transactions`
- [x] `/specimens`
- [x] `GET`
- [x] `POST`
- [x] `/specimens/{specimen_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/specimens/{specimen_id}/owner` which is passed to `/users/{user_id}`
- [x] `/transactions`
- [x] `POST`
- [x] `GET`
- [x] `/transactions/{transaction_id}`
- [x] `GET`
- [x] `PATCH`
- [x] `DELETE`
- [x] `/transactions/{transaction_id}/user` which is passed to `/users/{user_id}`
# Notes
- Consider making `metadata` a JSONB column for storage of arbitrary metadata which can be updated over API.
- Consider suggesting storage of image name and type in the metadata column (for guidance on how to decode the image).
- For the demo, uploaded document data can be from a TTK canvas widget just for fun maybe?
- Could also straight up demo the client in godot but hmm
- Or we could demo it from Twitch redeems etc.. but tbh canvas does make sense? With simulate buttons? Hmm. Or redeems could simulate.
# Demo client plan
- For one thing we need to make sure we have documentation and examples for all the common *flows*, including the routes and payloads and replies. We want to make a simple usage guide essentially, just a few pages, with each of the key requests and how we suggest they should be used (e.g. stateless event and specimen creation vs cached user_ids, updating documents via event, or specimen via user etc.)
- It would be nice to write a bit of documentation for each route as well for a full API reference, although I think that is less required. Maybe it would even make it more confusing, not having everything in one place. Although I think it would make sense to properly index the routes in this wiki still, and add a few good examples to each route. Even a small library of examples.
- For the actual demo, we have two parts. One is the *bot* side, which will actually be the framework that Discord-side UI is built on. Need to make sure this is fairly solid. We expect that alllen will actually build new tools using the framework I put in place here.
- The other part is the *client* side which will be a throw-away client to just illustrate some of the flows I expect to be used, and how to actually interact with the API, e.g. authentication, stateless event/specimen creation, or non-stateless event/specimen creation, and editing (e.g. posting stamps).
I should make an explicit list of the flows I want to demonstrate and have available in the demo client.
- Stateless event creation
- Modification of an event (e.g. adding a stamp) after creation (and updating the document at the same time)
- User-id caching
- Stateless specimen creation
- User fetching
- User document fetching
- Fetching events with particular seal/type
- Uploading and downloading images of course
Is it worth making a python API client along the same lines as, say, the toggl HTTP client?
Could be good for API testing. Just keep each route explicit. Very explicit.
Then we can just show off test functions instead of a 'fancy' UI, and we can make a simple twitch client to demonstrate hooking it into redeems.
We can also use PIL to simulate approve and deny stamps with rotation and position.
He can possibly adapt the HTTP client I make to Godot as well, maybe, depending on how the class system works there. Or he can just bring along the routes that he needs.
Okay I think that makes sense. We have tasks.
## Documentation
- [ ] Add an authentication page to the docs
- [ ] Write suggested usage/flow documentation for each of the common flows, i.e. how I suggest the API be used.
- [ ] Move the route collections to their own docs pages and attach example requests and responses
## Local client
- [x] Write an HTTPClient class with all of the routes implemented
- [x] Write image generation functions for creating each type of card and adding stamps to a card
- [x] Write a collection of demo methods which each demonstrate a single flow or task
- [x] Test these myself
- [ ] Write a very basic twitch-capable bot which uses the client to react to a few test redeems.
## Bot client
- [x] Make the profile connection nicer, e.g. persistent view with Button -> ephemeral view with link button which updates on auth (also have the ephemeral view available by command).
- [ ] Make a simple DOM and some factory methods for the relevant objects (maybe just the events)
- [ ] Make some basic admin commands to query the objects and see e.g. matching event cards
- [ ] Make some basic user commands to view your own cards and see your specimen status and wallet
- [ ] User profile migration code to update the datamodels
## For the demo
- [ ] Show how to setup and test these locally, both running the API and the bot (needs postgres setup)
- [ ] Give ssh key to the server account
- [ ] Give key to the pgAdmin instance on the server
- [ ] Invite to postman
- [ ] Run through the demo program, and the demo client.
- [ ] Notes about sending images, sending stateless users.
- [ ] Updating stamps and documents. Want to get to the point of getting and sending some basic data from overlay side if possible.
- [ ] Viewing events on bot-side.
- [ ] Viewing specimens on bot-side.
- [ ] Emojis can be customised

43
api/chapters/document.md Normal file

@@ -0,0 +1,43 @@
# `Document`
Represents a saved document, i.e. and image with a seal and optionally some stamps.
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.
| field | type | required | description |
| --------------- | --------- | -------- | -------------------------------------------------------------- |
| `document_id` | integer | - | UID for this document |
| `document_data` | string | yes | Image data encoded in Base64 |
| `seal` | integer | yes | Seal integer |
| `created_at` | timestamp | - | When this document was created. Automatically set on creation. |
| `metadata` | string? | no | Optional arbitrary associated metadata. |
| `stamps` | [`Stamp`] | no | List of stamps attached to this document. |
- `POST` `/documents`
- Create and return a `Document`.
- Stamps may be added to the document by passing a list of `Stamp`s in the `stamps` field.
- These stamps should not include `document_id`, as this will be automatically added.
- `GET` `/documents`
- Get all `Document`s matching the given parameters. If no parameters are given, returns all documents.
- Supported filter parameters:
- `document_id`
- `seal`
- `created_before`
- `created_after`
- `metadata`
- `stamp_type` - Filter documents by whether they have the given stamp type.
- `GET` `/documents/{document_id}`
- Returns a `Document` with the given `document_id`.
- `PATCH` `/documents/{document_id}`
- Updates the given `Document`.
- Supports updating `document_data`, `seal`, `metadata`, and `stamps`.
- If `stamps` is provided, it must be a list of creation arguments for `Stamp`s. These will *replace* the existing document stamps.
- To update individual stamps, use `/documents/{document_id}/stamps`
- Returns the updated `Document`.
- `DELETE` `/documents/{document_id}`
- Delete the given document, and all associated `Stamp`s.
- Does not delete the associated `Event` if one exists.
- Returns the deleted `Document`.
- `*` `/documents/{document_id}/stamps`
- Inherits all `/stamps` routes with `document_id` set.

100
api/chapters/event.md Normal file

@@ -0,0 +1,100 @@
# `Event`
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.
Events may also be created without documents, in which case the `document` and `document_id` fields will be `null`.
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `event_id` | integer | - | UID for this event |
| `document_id` | integer? | - | UID of the associated document, if it exists. |
| `document` | `Document`? | no | Associated `Document`, if it exists. |
| `user_id` | integer | yes | (Internal) UID of the user which triggered this event. |
| `user` | `User` | no | `User` which triggered this event. |
| `user_name` | string? | yes | Name of the user when they triggered this event. |
| `occurred_at` | timestamp | yes | When this event originally occurred. Will typically be earlier than `created_at` |
| `created_at` | timestamp | - | When this event was created. Automatically set on creation. |
| `event_type` | string in `EventType` | yes | Type of the event. Must be one of the event types. |
Allowed and possible values for `EventType` are `plain`, `subscriber`, `cheer`, `raid`.
The `event_type` *must* be specified when creating an event.
- `POST` `/events`
- Create a return a new `Event`.
- 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 `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.
- 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.
- `GET` `/events`
- Returns `events` matching the provided filters.
- Intended to be the typical way of retrieving events and documents.
- Supported filter parameters:
- `event_id`
- `document_id`
- `document_seal` - Filter by document seal
- `user_id`
- `user_name`
- `occurred_before`
- `occurred_after`
- `created_before`
- `created_after`
- `event_type`
- `GET` `/events/{event_id}`
- Returns an `Event` with the given `event_id`.
- `PATCH` `/events/{event_id}`
- Updates and returns the given `Event`.
- Supports updating all added fields in the relevant event type.
- Does not support updating any of the base event fields.
- `DELETE` `/events/{event_id}`
- Delete and return the given `Event`
- Note this will *also* delete the associated `Document`.
- `*` `/events/{event_id}/document`
- If the action is `POST`, will *create* and return a `Document` for this event.
- Otherwise inherits the `/documents/{document_id}` route with the associated `document_id`.
- If there is no `document` associated, will raise `Not Found`.
- `*` `/events/{event_id}/user`
- Inherits the `/users/{user_id}` route with the associated `user_id`.
- [ ] It might make sense to add the subtype fields for filtering as well
#### `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. |

7
api/chapters/inventory.md Normal file

@@ -0,0 +1,7 @@
# `InventoryItem`
// TODO
// Leaving this for now since I'm not sure how inventories should actually work.
// There are a few different models with significant differences.
// For example, are there any persistent items which don't need to be owned by a user? i.e. the item can be removed from a user's inventory but still exists and is now possibly useable by another user? Or are all items ephemeral and obtainable in certain quantities by users? Are items purchasable? Are there 'unique' items which can only exist once? Can users trade items or given them to the specimen (req specimen inventory).. etc.
// So leaving this for now until there is a better idea of what items and inventories are since the model would probably need a rework anyway

37
api/chapters/specimen.md Normal file

@@ -0,0 +1,37 @@
# `Specimen`
Represents a specimen, remembered or forgotten.
| field | type | required | description |
| -------------- | ---------- | -------- | -------------------------------------------------------------------------- |
| `specimen_id` | integer | - | UID of this specimen |
| `owner_id` | integer | yes | (Internal) id of the user who owns this specimen |
| `owner` | `User` | no | User who owns this specimen |
| `born_at` | timestamp | no | When this specimen came into existence. Will be set to `now` if not given. |
| `forgotten_at` | timestamp? | no | When this specimen was forgotten. |
- `POST` `/specimens`
- Create and return a new `Specimen` .
- The `owner` *may* be specified in place of the `owner_id`. In this case it should be in the form of a `User` (as in `POST /user`).
- Supplying both an `owner_id` and `owner` is not supported.
- If an `owner` object is supplied and 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 as the `owner_id` of the created `Specimen`.
- `GET` `/specimens`
- Returns `Specimen`s matching the provided filters.
- Supported filter parameters:
- `specimen_id`
- `owner_id`
- `born_after`
- `born_before`
- `forgotten` - boolean, filters by whether `forgotten_at` is set.
- `forgotten_after`
- `forgotten_before`
- `GET` `/specimens/{specimen_id}`
- Get the `Specimen` with the given id.
- `PATCH` `/specimens/{specimen_id}`
- Updates the given `Specimen`
- Supports updating `owner_id` and `forgotten_at`
- `DELETE` `/specimens/{specimen_id}`
- Deletes and returns the given `Specimen`
- `*` `/specimens/{specimen_id}/owner`
- Inherits all routes from the `/users/{user_id}` route with the associated `owner_id`.
// Notably, the inheritance allows a lot of cyclic references. You can for example do `GET /events/1/user/specimen/owner/specimen/user/...` and obtain the expected response. Each level adds the relevant filter parameter or overwrites it if the parameter is already set.

30
api/chapters/stamp.md Normal file

@@ -0,0 +1,30 @@
# `Stamp`
Represents a document stamp.
| field | type | required | description |
| ------------- | ------- | -------- | --------------------------------------------------------------- |
| `stamp_id` | integer | - | UID for this stamp (unique amongst all stamps on all documents) |
| `document_id` | integer | yes | UID for the `Document` that this stamp belongs to. |
| `stamp_type` | string | yes | Stamp type, can be any string |
| `pos_x` | integer | yes | x coordinate |
| `pos_y` | integer | yes | y coordinate |
| `rotation` | float | yes | Rotation |
- `POST` `/stamps`
- Create and return a `Stamp`.
- Should generally not be used directly. Instead, create the `Stamp` with the `Document` or with `POST /documents/{document_id}/stamps`
- `PUT` `/stamps`
- Create and return a list of `Stamp`s.
- Should generally not be used directly. Instead, create the `Stamps` with the `Document` or with `PUT /documents/{document_id}/stamps`
- `GET` `/stamps`
- Get all `Stamp`s matching the given parameters.
- Supported filter parameters: `stamp_id`, `document_id`, `stamp_type`
- `GET` `/stamps/{stamp_id}`
- Returns a `Stamp` with the given `stamp_id`, or raises `Not Found` if no stamp exists.
- `PATCH` `/stamps/{stamp_id}`
- Updates the given `Stamp`.
- Supports any settable field.
- `DELETE` `/stamps/{stamp_id}`
- Delete the specified `Stamp`.

37
api/chapters/transaction.md Normal file

@@ -0,0 +1,37 @@
# `Transaction`
Represents a monetary transaction for a particular user.
| field | type | required | description |
| ---------------- | --------- | -------- | ----------------------------------------------------------------------------- |
| `transaction_id` | integer | - | UID for this transaction |
| `user_id` | integer | yes | (Internal) id of the user making the transaction. |
| `user` | `User` | - | User making the transaction. |
| `amount` | integer | yes | Amount of currency *added* to the user's account. May be negative. |
| `description` | string | yes | Description of this transaction. |
| `reference` | string? | no | Optional reference string. |
| `created_at` | timestamp | - | Timestamp at which this transaction was performed. Cannot be set or modified. |
- `POST` `/transactions`
- Create and return a new `Transaction`.
- Note that *unlike* other models containing a `User`, creation of a new `User` with a `Transaction` is not supported. Ensure the user exists before creating the transaction.
- `GET` `/transactions`
- Get all `Transactions` matching the given parameters.
- Supported filter parameters:
- `transaction_id`
- `user_id`
- `description`
- `reference`
- `created_before`
- `created_after`
- `GET` `/transactions/{transaction_id}`
- Get the `Transaction` for the given `transaction_id`
- `PATCH` `/transactions/{transaction_id}`
- Not supported, `Transactions` are considered immutable.
- `DELETE` `/transactions/{transaction_id}`
- Not supported. `Transactions` cannot be individually deleted.
- Note that if the `User` is deleted then the all their `Transactions` will also be deleted.
- To reset or set a User's balance, submit a `Transaction` which changes it to the desired value.
- `*` `/transactions/{transaction_id}/user`
- Inherits all routes from `/users/{user_id}` with the associated `user_id`.

82
api/chapters/user.md Normal file

@@ -0,0 +1,82 @@
# `User`
Represents a twitch user.
| field | type | required | description |
| ------------ | --------- | -------- | ----------------------------------------------------------------------- |
| `user_id` | integer | - | Internal UID of this user. (NOT the twitch userid) |
| `twitch_id` | string? | yes | Twitch user-id for this user. Stored as a string. |
| `name` | string? | yes | Twitch name for this user. May not be up to date. |
| `created_at` | timestamp | - | When this user was created (internally). Automatically set on creation. |
| `preferences` | string? | no | Arbitrary preference string, not used or read. |
// The name is stored mainly for easy visual reference/convenience when debugging, and should not be relied on.
Note that the `twitch_id` and `name` parameters are best-effort and there are some rare cases where they are unreliable:
- If a user linked their twitch account to Discord, and then unlinked the twitch account or deleted it, then `twitch_id` and `name` may be `null`.
- If a user linked *multiple* twitch accounts, then the returned `twitch_id` and `name` will only be for one account.
- In this rare case, filter parameters will still fetch the correct user. This may lead to technically unexpected behaviour, for example:
- Assume a user with `user_id` `10` has linked twitch account `1` and later twitch account `2`.
- Then both `GET /users?twitch_id=2` and `GET /users?twitch_id=1` will return `{"user_id": 10, "twitch_id": 1}`.
- Due to the general ephemeral nature of names, it is not recommended to rely on the `name` field in any way. It is included mainly for ease of debugging and reference.
- [ ] Currently there is no way of retrieving *all* the twitch accounts associated to a user. Is this needed?
- `POST` `/users`
- Create and return a `User`
- `GET` `/users`
- Get all `User`s matching the given parameters
- Supported filter parameters:
- `user_id`
- `twitch_id`
- `name` - Supported, but should not typically be used.
- `created_after`
- `created_before`
- `GET` `/users/{user_id}`
- Get the `UserDetails` for the given user.
- `PATCH` `/users/{user_id}`
- Updates the given `User`
- Supports updating `name` and `preferences`.
- Intended to be extended to update other preference fields in future.
- Returns the updated `User`
- `DELETE` `/users/{user_id}`
- Deletes the given user, and all associated data. This includes:
- All `Event`s associated to the user (cascading as in `DELETE /events/{event_id}`)
- All `Specimen`s associated to the user.
- All `InventoryItem`s owned by the user.
- All `Transaction`s made by the user.
- Returns `UserDetails` of the deleted user.
- `*` `/users/{user_id}/events`
- Inherits all `/events` routes with `user_id` set.
- `*` `/users/{user_id}/specimen`
- If the action is `POST`, will *create* and return a `Specimen` for this user.
- Note that this will error if the user already has an active specimen.
- Otherwise inherits the `/specimens/{specimen_id}` with `specimen_id` set to the user's active specimen.
- If the user does not have an active `Specimen` this will raise `NotFound`.
- `*` `/user/{user_id}/specimens`
- Inherits all `/specimens` routes with the `owner_id` set to `user_id`.
- `GET` `/users/{user_id}/wallet`
- Will return the current amount in the user's wallet.
- Not typically used and only included for route consistency.
- `*` `/users/{user_id}/transactions`
- Inherits all routes from the `/transactions` route, with `user_id` set.
# `UserDetails`
This is a convenience model presenting the current natural 'state' of the user,
including their current `Specimen`, their wallet, and their current inventory.
This is the model returned by `GET /users`.
Note that the `specimen`, `inventory`, and `wallet` fields cannot be set or updated directly,
instead use `/users/{user_id}/specimen`, `/users/{user_id}/inventory`, and `/users/{user_id}/transactions` respectively.
The wallet is viewable from `/users/{user_id}/wallet`, but does not support direct updates.
(All updates must occur through transactions.)
In *addition* to the fields from `User`, this model has the following fields
| field | type | required | description |
| ------------ | ------- | -------- | --------------------------------------------------------------- |
| `specimen` | `Specimen`? | - | Current living specimen for this user if it exists. |
| `inventory` | [`InventoryItem`] | - | List of active inventory items for this user. |
| `wallet` | integer | - | How much currency the user currently has. |

25
api/client.md Normal file

@@ -0,0 +1,25 @@
# Dreamspace API Usage Documentation
## Connection
- Mainly authentication
- Mention json
- Example of connection with curl
- Example of connection with python
- Attempted example of connection with godot
## Standard Flows
## Redundant paths
## Reference
- Links to each chapter

10
api/development.md Normal file

@@ -0,0 +1,10 @@
# Dreamspace API Developer Documentation
- The toolchain
- Installation and setup
- Configuration required
- How requests flow through the system (take an example model)
- How models are represented, in full (data, queries, and class, and argument typing)
- How errors are handled
- Some example extensions

14
api/index.md Normal file

@@ -0,0 +1,14 @@
# Dreamspace API
## Introduction
- What this API is for, and what it does
- The models it covers, and roughly what each one does
- How this API covers the original requirements
## For API clients
To learn how to connect to and use this API, with examples and a complete API model and route reference, see [[client]].
## For API developers
To learn about the development toolchain, configuration and installation instructions, and how the API parses requests or how to extend the API, see [[development]].