adventures/reference.md

Models

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 in radians

• 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 Stamps.
  • Should generally not be used directly. Instead, create the Stamps with the Document or with PUT /documents/{document_id}/stamps
• 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.

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	file	yes	Image data (not sure about the encoding yet)
seal	integer	yes	Seal integer
created_at	timestamp	no	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 Stamps in the stamps field.
• GET /documents
  • Get all Documents 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.
  • To update the stamps, use /documents/{document_id}/stamps
  • Returns the updated Document.
• DELETE /documents/{document_id}
  • Delete the given document, and all associated Stamps.
  • 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.

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	no	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, bit, 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

• * /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.

---

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	no	When this user was created (internally). Automatically set on creation.

// The name is stored mainly for easy visual reference/convenience when debugging, and should not be relied on.

• POST /users
  • Create and return a User
• GET /users
  • Get all Users 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 twitch_id and name
  • Returns the updated User
• DELETE /users/{user_id}
  • Deletes the given user, and all associated data. This includes:
    • All Events associated to the user (cascading as in DELETE /events/{event_id})
    • All Specimens associated to the user.
    • All InventoryItems owned by the user.
    • All Transactions 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.

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 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 Specimens 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
• PATCH /specimens/{specimen_id}
  • Updates the given Specimen
  • Supports updating owner_id
  • I'm not sure why you would want to do this, but there you go
  • This route is intended for future updates where Specimen has more metadata.
• 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.

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

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
    • amount
    • 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.