Initial draft for Activity Events

113.md

@@ -0,0 +1,139 @@
+NIP-113
+===
+Activity Events
+----------------
+`draft` `optional`
+
+This NIP defines `kind:30100`: a parameterized replaceable event to describe activities. Activities are things that one might record via a tracking watch (garmin, fitbit, apple watch, etc...) and wish to share with other.
+
+In general, activities are notes that have an activity file associated with them (gpx, tcx, fit), and a summary can be produced about this activity.
+
+The structure of an activity follows very closely with [NIP-23](23.md) long-form content events.
+### Content
+The `.content` field MAY contain a description of the activity
+### Activity Types
+Activities MUST include a `t` tag with an activity type (defined in Appendix A). e.g. `run | walk | hike`
+### Activity File
+Activities MAY include an `r` tag, which will include a URL to the location where an activity file can be found.
+### Metadata
+`t` - The activity type
+`r` - location of activity file (OPTIONAL)
+`title` - The title of the activity
+`recorded_at` - The unix timestamp (in seconds) when the activity was recorded
+`encrypted` - An indication that this event is encrypted (OPTIONAL)
+
+```json
+{
+  "kind": 30100,
+  "content": "<description-of-activity>",
+  "tags": [
+	 ['title', 'Title of Activity'],
+	 ['t', '<activity-type-from-nip>']
+	 ['d', 'UUID generated by client'],
+	 ['r', 'url to download activity file'],
+	 ['published_at', '<unix-timestamp>'],
+	 ['updated_at', '<unix-timestamp>'],
+	 ['recorded_at', '<unix-timestamp>']
+	 ['encrypted'] // Optional, activity file is encrypted
+  ],
+}
+```
+### Summaries
+`kind:30101` defines an event which is meant to summarize activities, users, places, etc...
+Summaries are intended to capture a wide range things that users may wish to summarize in relation to activities. 
+Users will likely want a summary of a specific event (e.g. milage, time, pace, etc...), a summary for a group of events (e.g. miles run this month), a summary of locations (e.g. heatmaps based on a geohash). 
+
+This NIP does not attempt to describe all the different summaries that users could want, as this list will be ever evolving. Rather this event type should facilitate clients to retrieve relevant summaries for a user.
+#### Summary Metadata
+`r` - An ID that this summary pertains to. It could be an activity ID or a user pubkey
+`t` - A summary MUST include a type which clients can specifically look for. These types must be lowercase with no spaces. e.g. `sports-lib-summary`
+`g` - Optional geohash of a summary
+`encrypted` - Optional, if summary is encrypted.
+`content` - stringified payload of the summary - the structure of which is defined by the type.
+`unit` - Optional, defines the unit types that are present in a summary. Either `imperial | metric`.
+
+```json
+{
+  kind: 30101,
+  content: "JSON.stringify(summary)", 
+  tags: [
+	 ['d', 'UUID generated by client'],
+	 ['r', '<UUID-of-activity>'],
+	 ['t', 'general-summary'],
+	 ['g', 'OPTIONAL geohash'],
+	 ['unit', 'OPTIONAL imperial | metric'],
+	 ['published_at', '<unix-timestamp>'],
+	 ['updated_at', '<unix-timestamp>']
+	 ['encrypted'] // Optional, summary content is encrypted
+  ],
+}
+```
+
+#### Summary Types
+Summary types are not meant to be standardized. Different activity types may want to look at activity files in a different way. People may create popular ways to summarize activity files (e.g. via DVMs).
+
+Examples could be:
+- `bobs-cycling-analysis` - A guy named Bob has a really good model for analyzing gpx files in a way that cyclists care about.
+- `sports-lib-summary` - A raw dump of all of the statistics produced by the [sports-lib](https://github.com/sports-alliance/sports-lib) library.
+- `year-in-review` - A summary of all your activies in the year.
+- `geojson` - A geojson representation of the activity so clients can render the activity on a map
+When creating a summary type, one SHOULD publish the schema of the content so clients can easily display the data to their users.
+#### Summary Units
+If a summary includes units, it SHOULD aim to keep things in base units. e.g. for distances, `feet` or `meters` should be used. For time, `seconds` should be used.
+### Privacy
+Activity files generally contain information that users may not want to be public. Clients SHOULD include options for users to control exactly what gets published (both to storage and to relays). 
+
+Examples:
+- Clients can include an option to "trim a route" so that the start / end of the route are hidden. This allows other users to view your routes without doxxing the exact location of where you live
+- Clients might encrypt the gpx file so only the author can view exact detail about an activity, while others are still able to view aggregate summaries about the activity.
+### Encryption
+If a user wishes to encrypt a summary or activity, they should use the [NIP-44](NIP-44.md) encryption schema to encrypt the content being uploaded. i.e. if an activity is `encrypted` and it includes a link to an activity file to download, that activity file is encrypted via NIP-44.
+
+## Appendix A - Activity Types
+run
+trail-run
+hike
+ride
+swim
+walk
+mountain-bike-ride
+gravel-ride
+e-bike-ride
+e-mountain-bike-ride
+alpine-ski
+badminton
+backcountry-ski
+canoeing
+crossfit
+elliptical
+golf
+ice-skate
+inline-skate
+handcycle
+hiit
+kayaking
+nordic-ski
+kitesurf
+stand-up-paddling
+pickleball
+pilates
+racquetball
+rock-climbing
+roller-ski
+rowing
+sail
+skateboard
+snowboard
+snowshoe
+soccer
+squash
+stair-stepper
+surfing
+table-tennis
+tennis
+velomobile
+weight-training
+windsurf
+wheelchair
+workout
+yoga