@graffiti-garden/api 0.6.3 → 1.0.0

package/src/1-api.ts

@@ -2,250 +2,153 @@ import type {
   GraffitiObjectUrl,
   GraffitiObject,
   GraffitiObjectBase,
-  GraffitiPatch,
   GraffitiSession,
-  GraffitiPutObject,
+  GraffitiPostObject,
   GraffitiObjectStream,
-  ChannelStats,
-  GraffitiChannelStatsStream,
   GraffitiObjectStreamContinue,
 } from "./2-types";
 import type { JSONSchema } from "json-schema-to-ts";
 
 /**
  * This API describes a small but powerful set of methods that
- * can be used to create many different kinds of social media applications,
- * all of which can interoperate.
- * These methods should satisfy all of an application's needs for
+ * can be used to create many different kinds of social applications,
+ * from applications like Twitter, to Messenger, to Wikipedia, to many more new designs.
+ * See the [Graffiti project website](https://graffiti.garden)
+ * for links to example applications. Additionally, apps built on top
+ * of the API interoperate with each other so you can seamlessly switch
+ * between apps without losing your friends or data.
+ *
+ * These API methods should satisfy all of an application's needs for
  * the communication, storage, and access management of social data.
  * The rest of the application can be built with standard client-side
- * user interface tools to present and interact with the data —
- * no server code necessary.
- * The Typescript source for this API is available at
- * [graffiti-garden/api](https://github.com/graffiti-garden/api).
+ * user interface tools to present and interact with that data—no server code necessary!
+ *
+ * The Typescript code for this API is [open source on Github](https://github.com/graffiti-garden/api).
  *
  * There are several different implementations of this Graffiti API available,
- * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),
- * that lets users choose where their data is stored,
+ * including a [federated implementation](https://github.com/graffiti-garden/implementation-remote),
+ * that lets people choose where their data is stored (you do not need to host your own server)
  * and a [local implementation](https://github.com/graffiti-garden/implementation-local)
- * that can be used for testing and development. In our design of Graffiti, this API is our
- * primary focus as it is the layer that shapes the experience
- * of developing applications. While different implementations can provide tradeoffs between
- * other important properties (e.g. privacy, security, scalability), those properties
- * are useless if the system as a whole doesn't expose useful functionality to developers.
- *
- * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)
- * that wraps around this API to provide reactivity. Other high-level libraries
- * will be available in the future.
- *
- * ## Overview
- *
- * Graffiti provides applications with methods to create and store data
- * on behalf of their users using standard CRUD operations:
- *  {@link put}, {@link get}, {@link patch}, and {@link delete}.
- * This data can represent both social artifacts (e.g. posts, profiles) and
- * activities (e.g. likes, follows) and is stored as JSON.
- *
- * The social aspect of Graffiti comes from the {@link discover} method
- * which allows applications to find objects that other users made.
- * It is a lot like a traditional query operation, but it only
- * returns objects that have been placed in particular
- * {@link GraffitiObjectBase.channels | `channels`}
- * specified by the discovering application.
- *
- * Graffiti builds on well known concepts and standards wherever possible.
- * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches
- * can be applied with [JSON Patch](https://jsonpatch.com).
- * For interoperability between Graffiti applications, we recommend that
- * objects use established properties from the
- * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,
- * however it is always possible to create additional properties, contributing
- * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).
- *
- * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts
- * unique to Graffiti along with *interaction relativity*, defined below.
- * Channels create boundaries between public spaces and work to prevent
- * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)
- * even in a highly interoperable environment.
- * Interaction relativity means that all interactions between users are
- * actually atomic single-user operations that can be interpreted in different ways,
- * which also supports interoperability and pluralism.
+ * that can be used for testing and development. Different implementations can
+ * be swapped-in in the future without changing the API or any of the apps built on
+ * top of it. In fact, we're working on an end-to-end encrypted version now!
+ * [Follow Theia on BlueSky for updates](https://bsky.app/profile/theias.place).
  *
- * ### Channels
+ * On the other side of the stack, there is [Vue plugin](https://vue.graffiti.garden/variables/GraffitiPlugin.html)
+ * that wraps around this API to provide reactivity. Other plugin frameworks
+ * and high-level libraries will be available in the future.
  *
- * {@link GraffitiObjectBase.channels | `channels`}
- * are a way for the creators of social data to express the intended audience of their
- * data. When a user creates data using the {@link put} method, they
- * can place their data in one or more channels.
- * Content consumers using the {@link discover} method will only see data
- * contained in one of the channels they specify.
+ * ## API Overview
  *
- * While many channels may be public, they partition
- * the public into different "contexts", mitigating the
- * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the "flattening of multiple audiences."
- * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,
- * comment threads, topics, places (real or virtual), pieces of media, and more.
+ * The Graffiti API provides applications with methods for {@link login} and {@link logout},
+ * methods to interact with data objects using standard database operations ({@link post}, {@link get}, and {@link delete}),
+ * and a method to {@link discover} data objects created by others.
+ * These data objects have a couple structured properties:
+ * - {@link GraffitiObjectBase.url | `url`} (string): A globally unique identifier and locator for the object.
+ * - {@link GraffitiObjectBase.actor | `actor`} (string): An unforgeable identifier for the creator of the object.
+ * - {@link GraffitiObjectBase.allowed | `allowed`} (string[] | undefined): An array of the actors who are allowed to access the object (undefined for public objects).
+ * - {@link GraffitiObjectBase.channels | `channels`} (string[]): An array of the *contexts* in which the object should appear.
  *
- * For example, consider a comment on a post. If we place that comment in the channel
- * represented by the post's URL, then only people viewing the post will know to
- * look in that channel, giving it visibility akin to a comment on a blog post
- * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).
- * If we also place the comment in the channel represented by the commenter's URI (their
- * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile
- * will also see the comment, giving it more visibility, like a reply on Twitter.
- * If we *only* place the comment in the channel represented by the commenter's URI, then
- * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),
- * where the comment is only visible to the commenter's followers but not the audience
- * of the original post.
- *
- * The channel model differs from other models of communication such as the
- * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,
- * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)
- * used by the AT Protocol, the protocol underlying BlueSky.
- * The actor model is a fusion of direct messaging (like Email) and broadcasting
- * (like RSS) and works well for follow-based communication but struggles
- * to pass information via other rendez-vous.
- * In the actor model, even something as simple as comments can be
- * [very tricky and require server "side effects"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).
- * The firehose model dumps all user data into one public database,
- * which doesn't allow for the carving out of different contexts that we did in our comment
- * example above. In the firehose model a comment will always be visible to *both* the original post's audience and
- * the commenter's followers.
- *
- * In some sense, channels provide a sort of "social access control" by forming
- * expectations about the audiences of different online spaces.
- * As a real world analogy, oftentimes support groups, such as alcoholics
- * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details
- * because they have expectations about the other people attending.
- * If someone malicious went to support groups just to spread people's secrets,
- * they would be shamed for violating these norms.
- * Similarly, in Graffiti, while you could spider public channels like a search engine
- * to find content about a person, revealing that you've done such a thing
- * would be shameful.
+ * All other data is stored in the object's unstructured {@link GraffitiObjectBase.value | `value`} property.
+ * This data can be used to represent social artifacts (e.g. posts, profiles) and activities (e.g. likes, follows).
+ * For example, a post might have the value:
+
+ * ```js
+ * {
+ *   title: "My First Post",
+ *   content: "Hello, world!",
+ *   published: 1630483200000
+ * }
+ * ```
  *
- * Still, social access control is not perfect and so in situations where privacy is important,
- * objects can also be given
- * an {@link GraffitiObjectBase.allowed | `allowed`} list.
- * For example, to send someone a direct message you should put an object representing
- * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),
- * so they can find it, *and* set the `allowed` field to only include the recipient,
- * so only they can read it.
+ * a profile might have the value:
  *
- * ### Interaction relativity
+ * ```js
+ * {
+ *   name: "Theia Henderson",
+ *   pronouns: "she/her",
+ *   describes: "did:web:theias.place" // Theia's actor ID
+ * }
+ * ```
  *
- * Interaction relativity posits that "interaction between two individuals only
- * exists relative to an observer," or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).
- * For example, if one user creates a post and another user wants to "like" that post,
- * their like is not modifying the original post, it is simply another data object that points
- * to the post being liked, via its {@link GraffitiObjectBase.url | URL}.
+ * and a "Like" might have the value:
  *
- * ```json
+ * ```js
  * {
- *   activity: 'like',
- *   target: 'url-of-the-post-i-like',
- *   actor: 'my-user-id'
+ *   activity: "Like",
+ *   target: "graffiti:remote:pod.graffiti.garden/12345" // The URL of the graffiti object being liked
  * }
  * ```
  *
- * In Graffiti, all interactions including *moderation* and *collaboration* are relative.
- * This means that applications can freely choose which interactions
- * they want to express to their users and how.
- * For example, one application could have a single fixed moderator,
- * another could allow users to choose which moderators they would like filter their content
- * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),
- * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).
- * Each of these applications is one interpretation of the underlying refieid user interactions and
- * users can freely switch between them.
+ * New social artifacts and activities can be easily created, simply
+ * by creating new objects with appropriate properties. Despite the lack of
+ * structure, we expect Graffiti object properties to adhere to a "[folksonomy](https://en.wikipedia.org/wiki/Folksonomy)",
+ * similar to hashtags. Any string can be used as a hashtag on Twitter,
+ * but there is social value in using the same hashtags at other people and
+ * so a structure naturally emerges. Similarly, Graffiti objects
+ * can have arbitrary properties but if people use the same properties as each other,
+ * their apps will interoperate, which has social value.
  *
- * Interaction relativy also allows applications to introduce new sorts of interactions
- * without having to coordinate with all the other existing applications,
- * keeping the ecosystem flexible and interoperable.
- * For example, an application could [add a "Trust" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)
- * and use it assess the truthfulness of posts made on applications across Graffiti.
- * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem
- * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).
+ * For a more complete and detailed overview of Graffiti's design, please
+ * refer to [this section of the Graffiti paper](https://dl.acm.org/doi/10.1145/3746059.3747627#sec-3),
+ * published in ACM UIST 2025. The paper also overviews {@link GraffitiObjectBase.channels | `channels`},
+ * which are Graffiti's means of organizing data contextually, and a concept called "total reification",
+ * which handles explains how moderation, collaboration, and other interactions are managed.
  *
- * Interactivy relativity is realized in Graffiti through two design decisions:
- * 1. The creators of objects can only modify their own objects. It is important for
- *    users to be able to change and delete their own content to respect their
- *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),
- *    but beyond self-correction and self-censorship all other interaction is reified.
- *    Many interactions can be reified via pointers, as in the "like" example above, and collaborative
- *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).
- * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),
- *    anyone can post to any channel, so long as they know the URI of that channel.
- *    It is up to applications to hide content from channels either according to manual
- *    filters or in response to user action.
- *    For example, a user may create a post with the flag `disableReplies`.
- *    Applications could then filter out any content from the replies channel
- *    that the original poster has not specifically approved.
- *
- * @groupDescription CRUD Methods
- * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
+ * @groupDescription 1 - Single-Object Methods
+ * Methods for {@link post | creating}, {@link get | reading},
  * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.
- * @groupDescription Query Methods
+ * @groupDescription 2 - Multi-Object Methods
  * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.
- * @groupDescription Session Management
- * Methods and properties for logging in and out of a Graffiti implementation.
+ * @groupDescription 3 - Media Methods
+ * Methods for {@link postMedia | creating}, {@link getMedia | reading},
+ * and {@link deleteMedia | deleting} media data.
+ * @groupDescription 4 - Session Management
+ * Methods and properties for logging in and out.
  */
 export abstract class Graffiti {
   /**
-   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.
-   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}
-   * that created it.
-   *
-   * Replacement occurs when the {@link GraffitiObjectBase.url | `url`} of
-   * the replaced object exactly matches an existing object's URL.
-   *
-   * @throws {@link GraffitiErrorNotFound} if a {@link GraffitiObjectBase.url | `url`}
-   * is provided that has not been created yet or the {@link GraffitiObjectBase.actor | `actor`}
-   * is not {@link GraffitiObjectBase.allowed | `allowed`} to see it.
-   *
-   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
-   * is not the same `actor` as the one who created the object.
+   * Creates a new {@link GraffitiObjectBase | object}.
    *
-   * @returns The object that was replaced if one one exists, otherwise an object with
-   * with an empty {@link GraffitiObjectBase.value | `value`},
-   * {@link GraffitiObjectBase.channels | `channels`}, and {@link GraffitiObjectBase.allowed | `allowed`}
-   * list.
-   * The {@link GraffitiObjectBase.lastModified | `lastModified`} property of the returned object
-   * will be updated to the time of replacement/creation.
+   * @returns Returns the object that has been posted, complete with its
+   * assigned {@link GraffitiObjectBase.url | `url`} and
+   * {@link GraffitiObjectBase.actor | `actor`}.
    *
-   * @group CRUD Methods
+   * @group 1 - Single-Object Methods
    */
-  abstract put<Schema extends JSONSchema>(
+  abstract post<Schema extends JSONSchema>(
     /**
-     * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided
-     * as the generic type parameter. We highly recommend providing a schema to
-     * ensure that the PUT object matches subsequent {@link get} or {@link discover}
+     * An object to post. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided
+     * as the generic type parameter. It is recommended to a schema to
+     * ensure that the posted object matches subsequent {@link get} or {@link discover}
      * methods.
      */
-    object: GraffitiPutObject<Schema>,
+    object: GraffitiPostObject<Schema>,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session: GraffitiSession,
-  ): Promise<GraffitiObjectBase>;
+  ): Promise<GraffitiObject<Schema>>;
 
   /**
-   * Retrieves an object from a given {@link GraffitiObjectBase.url | `url`}.
-   *
-   * The retrieved object is type-checked against the provided [JSON schema](https://json-schema.org/)
-   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.
+   * Retrieves an object from a given {@link GraffitiObjectBase.url | `url`} matching
+   * the provided `schema`.
    *
    * If the retreiving {@link GraffitiObjectBase.actor | `actor`} is not
    * the object's `actor`,
    * the object's {@link GraffitiObjectBase.allowed | `allowed`} and
    * {@link GraffitiObjectBase.channels | `channels`} properties are
-   * not revealed, similar to a BCC.
+   * not revealed, similar to a BCC email.
+   *
+   * @returns Returns the retrieved object.
    *
-   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has been deleted, or the user is not
+   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has been deleted, or the actor is not
    * {@link GraffitiObjectBase.allowed | `allowed`} to access it.
    *
    * @throws {@link GraffitiErrorSchemaMismatch} if the retrieved object does not match the provided schema.
    *
-   * @group CRUD Methods
+   * @group 1 - Single-Object Methods
    */
   abstract get<Schema extends JSONSchema>(
     /**
@@ -266,61 +169,18 @@ export abstract class Graffiti {
   ): Promise<GraffitiObject<Schema>>;
 
   /**
-   * Patches an existing object at a given {@link GraffitiObjectBase.url | `url`}.
-   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the
-   * `actor` that created the object.
-   *
-   * @returns The original object prior to the patch with its
-   * {@link GraffitiObjectBase.lastModified | `lastModified`}
-   * property updated to the time of deletion.
-   *
-   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has already been deleted,
-   * or the user is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
-   *
-   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
-   * is not the same `actor` as the one who created the object.
-   *
-   * @group CRUD Methods
-   */
-  abstract patch(
-    /**
-     * A collection of [JSON Patch](https://jsonpatch.com) operations
-     * to apply to the object. See {@link GraffitiPatch} for more information.
-     */
-    patch: GraffitiPatch,
-    /**
-     * The location of the object to patch.
-     */
-    url: string | GraffitiObjectUrl,
-    /**
-     * An implementation-specific object with information to authenticate the
-     * {@link GraffitiObjectBase.actor | `actor`}.
-     */
-    session: GraffitiSession,
-  ): Promise<GraffitiObjectBase>;
-
-  /**
-   * Deletes an object from a given {@link GraffitiObjectBase.url | `url`}.
+   * Deletes an object from a given {@link GraffitiObjectBase.url | `url`}
+   * that had previously been {@link post | `post`ed}.
    * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the
    * `actor` that created the object.
    *
-   * It is not possible to re-{@link put} an object that has been deleted
-   * to ensure a user's [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten).
-   * In cases where deleting and restoring an object is useful, an object's
-   * {@link GraffitiObjectBase.allowed | `allowed`} property can be set to
-   * an empty list to hide it from all users except the creator.
-   *
-   * @returns The object that was deleted with its
-   * {@link GraffitiObjectBase.lastModified | `lastModified`}
-   * property updated to the time of deletion.
-   *
-   * @throws {@link GraffitiErrorNotFound} if the object does not exist,  has already been deleted,
-   * or the user is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
+   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has already been deleted,
+   * or the actor is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
    *
    * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
    * is not the same `actor` as the one who created the object.
    *
-   * @group CRUD Methods
+   * @group 1 - Single-Object Methods
    */
   abstract delete(
     /**
@@ -332,10 +192,10 @@ export abstract class Graffiti {
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session: GraffitiSession,
-  ): Promise<GraffitiObjectBase>;
+  ): Promise<void>;
 
   /**
-   * Discovers objects created by any user that are contained
+   * Discovers objects created by any actor that are contained
    * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}
    * and match the given [JSON Schema](https://json-schema.org).
    *
@@ -349,7 +209,7 @@ export abstract class Graffiti {
    * string can be serialized to continue the stream after an application is closed
    * and reopened.
    *
-   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}
+   * `discover` will not return objects that the querying {@link GraffitiObjectBase.actor | `actor`}
    * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.
    * If the `actor` is not the creator of a discovered object,
    * the allowed list will be masked to only contain the querying actor if the
@@ -360,14 +220,11 @@ export abstract class Graffiti {
    *
    * Since different implementations may fetch data from multiple sources there is
    * no guarentee on the order that objects are returned in.
-   * It is also possible that duplicate objects are returned and their
-   * {@link GraffitiObjectBase.lastModified | `lastModified`} fields must be used
-   * to determine which object is the most recent.
    *
-   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
+   * @returns Returns a stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
    * and [JSON Schema](https://json-schema.org).
    *
-   * @group Query Methods
+   * @group 2 - Multi-Object Methods
    */
   abstract discover<Schema extends JSONSchema>(
     /**
@@ -388,148 +245,156 @@ export abstract class Graffiti {
   ): GraffitiObjectStream<Schema>;
 
   /**
-   * Discovers objects **not** contained in any
-   * {@link GraffitiObjectBase.channels | `channels`}
-   * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}
-   * and match the given [JSON Schema](https://json-schema.org).
-   * Unlike {@link discover}, this method will not return objects created by other users.
+   * Continues a {@link GraffitiObjectStream} from a given
+   * {@link GraffitiObjectStreamReturn.cursor | `cursor`} string.
+   * The continuation will return new objects that have been {@link post | `post`ed}
+   * that match the original stream, and also returns the
+   * {@link GraffitiObjectBase.url | `url`}s of objects that
+   * have been {@link delete | `delete`d}, as marked by a `tombstone`.
    *
-   * This method is not useful for most applications, but necessary for
-   * getting a global view of all a user's Graffiti data or debugging
-   * channel usage.
+   * The `cursor` allows the client to
+   * serialize the state of the stream and continue it later.
+   * However this method loses any typing information that was
+   * present in the original stream. For better type safety
+   * and when serializing is not necessary, use the
+   * {@link GraffitiObjectStreamReturn.continue | `continue`} method
+   * instead, which is returned along with the `cursor` at the
+   * end of the original stream.
    *
-   * Like {@link discover}, objects are returned asynchronously as they are discovered,
-   * the stream will end once all leads have been exhausted, and the stream
-   * can be continued using the {@link GraffitiObjectStreamReturn.continue | `continue`}
-   * method or {@link GraffitiObjectStreamReturn.cursor | `cursor`} string.
+   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
+   * provided in the `session` is not the same as the `actor`
+   * that initiated the original stream.
    *
-   * @returns A stream of objects created by the querying {@link GraffitiObjectBase.actor | `actor`}
-   * that do not belong to any {@link GraffitiObjectBase.channels | `channels`}
-   * and match the given [JSON Schema](https://json-schema.org).
+   * @group 2 - Multi-Object Methods
+   */
+  abstract continueDiscover(
+    cursor: string,
+    session?: GraffitiSession | null,
+  ): GraffitiObjectStreamContinue<{}>;
+
+  /**
+   * Uploads media data, such as an image or video.
+   *
+   * Unlike structured {@link GraffitiObjectBase | objects},
+   * media is not indexed for {@link discover | `discover`y} and
+   * must be retrieved by its exact URL using {@link getMedia}
    *
-   * @group Query Methods
+   * @returns The URL that the media was posted to.
+   *
+   * @group 3 - Media Methods
    */
-  abstract recoverOrphans<Schema extends JSONSchema>(
+  abstract postMedia(
     /**
-     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.
+     * The binary data of the media to be uploaded,
+     * along with its [media type](https://www.iana.org/assignments/media-types/media-types.xhtml),
+     * formatted as a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
      */
-    schema: Schema,
+    media: Blob,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session: GraffitiSession,
-  ): GraffitiObjectStream<Schema>;
+  ): Promise<string>;
 
   /**
-   * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}
-   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.
-   * This is not very useful for most applications, but
-   * necessary for certain applications where a user wants a
-   * global view of all their Graffiti data or to debug
-   * channel usage.
+   * Deletes media previously {@link postMedia | `post`ed} to a given URL.
    *
-   * Like {@link discover}, objects are returned asynchronously as they are discovered,
-   * the stream will end once all leads have been exhausted.
+   * @throws {@link GraffitiErrorNotFound} if no media at that URL exists.
    *
-   * @group Query Methods
+   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
+   * provided in the `session` is not the same as the `actor` that {@link postMedia | `post`ed}
+   * the media.
    *
-   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}
-   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
+   * @group 3 - Media Methods
    */
-  abstract channelStats(
+  abstract deleteMedia(
+    /**
+     * A globally unique identifier and locator for the media.
+     */
+    mediaUrl: string,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session: GraffitiSession,
-  ): GraffitiChannelStatsStream;
+  ): Promise<void>;
 
   /**
-   * Continues a {@link GraffitiObjectStream} from a given
-   * {@link GraffitiObjectStreamReturn.cursor | `cursor`} string.
-   * The continuation will return new objects that have been created
-   * that match the original stream, and also returns the
-   * {@link GraffitiObjectBase.url | `url`}s of objects that
-   * have been deleted, as marked by a `tombstone`.
+   * Retrieves media from the given media URL, adhering to the given requirements.
    *
-   * The continuation may also include duplicates of objects that
-   * were already returned by the original stream. This is dependent
-   * on how much state the underlying implementation maintains.
+   * @throws {@link GraffitiErrorNotFound} if no media at that URL exists.
    *
-   * The `cursor` allows the client to
-   * serialize the state of the stream and continue it later.
-   * However this method loses any typing information that was
-   * present in the original stream. For better type safety
-   * and when serializing is not necessary, use the
-   * {@link GraffitiObjectStreamReturn.continue | `continue`} method
-   * instead, which is returned along with the `cursor` at the
-   * end of the original stream.
+   * @throws {@link GraffitiErrorTooLarge} if the media exceeds the given `maxBytes`.
    *
-   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
-   * provided in the `session` is not the same as the `actor`
-   * that initiated the original stream.
+   * @throws {@link GraffitiErrorNotAcceptable} if the media does not match the given
+   * `accept` specification.
+   *
+   * @returns The URL of the retrieved media, as a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
+   * and the {@link GraffitiObjectBase.actor | `actor`} that posted it.
    *
-   * @group Query Methods
+   * @group 3 - Media Methods
    */
-  abstract continueObjectStream(
-    cursor: string,
-    session?: GraffitiSession | null,
-  ): GraffitiObjectStreamContinue<{}>;
+  abstract getMedia(
+    /**
+     * A globally unique identifier and locator for the media.
+     */
+    mediaUrl: string,
+    /**
+     * An optional set of requirements the retrieved media must meet.
+     */
+    requirements?: {
+      /**
+       * A list of acceptable media types for the retrieved media,
+       * formatted as like an [HTTP Accept header](https://httpwg.org/specs/rfc9110.html#field.accept)
+       */
+      accept?: string;
+      /**
+       * The maximum size, in bytes, of the media.
+       */
+      maxBytes?: number;
+    },
+  ): Promise<{
+    media: Blob;
+    actor: string;
+  }>;
 
   /**
    * Begins the login process. Depending on the implementation, this may
-   * involve redirecting the user to a login page or opening a popup,
-   * so it should always be called in response to a user action.
+   * involve redirecting to a login page or opening a popup,
+   * so it should always be called in response to a gesture, such as clicking
+   * a button, due to the [feature-gating browser security feature](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation).
    *
    * The {@link GraffitiSession | session} object is returned
    * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}
    * as a {@link GraffitiLoginEvent} with event type `login`.
    *
-   * @group Session Management
+   * @group 4 - Session Management
    */
   abstract login(
     /**
-     * Suggestions for the permissions that the
-     * login process should grant. The login process may not
-     * provide the exact proposed permissions.
+     * A suggested actor to login as. For example, if a user tries to
+     * edit a post but are not logged in, the interface can infer that
+     * they might want to log in as the actor who created the post
+     * they are attempting to edit.
+     *
+     * Even if provided, the implementation should allow the user
+     * to log in as a different actor if they choose.
      */
-    proposal?: {
-      /**
-       * A suggested actor to login as. For example, if a user tries to
-       * edit a post but are not logged in, the interface can infer that
-       * they might want to log in as the actor who created the post
-       * they are attempting to edit.
-       *
-       * Even if provided, the implementation should allow the user
-       * to log in as a different actor if they choose.
-       */
-      actor?: string;
-      /**
-       * A yet to be defined permissions scope. An application may use
-       * this to indicate the minimum necessary scope needed to
-       * operate. For example, it may need to be able read private
-       * messages from a certain set of channels, or write messages that
-       * follow a particular schema.
-       *
-       * The login process should make it clear what scope an application
-       * is requesting and allow the user to enhance or reduce that
-       * scope as necessary.
-       */
-      scope?: {};
-    },
+    actor?: string,
   ): Promise<void>;
 
   /**
-   * Begins the logout process. Depending on the implementation, this may
+   * Begins the logout process for a particular {@link GraffitiSession | session}. Depending on the implementation, this may
    * involve redirecting the user to a logout page or opening a popup,
-   * so it should always be called in response to a user action.
+   * so it should always be called in response to a gesture, such as clicking
+   * a button, due to the [feature-gating browser security feature](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation).
    *
    * A confirmation will be returned asynchronously via
    * {@link Graffiti.sessionEvents | sessionEvents}
    * as a {@link GraffitiLogoutEvent} as event type `logout`.
    *
-   * @group Session Management
+   * @group 4 - Session Management
    */
   abstract logout(
     /**
@@ -540,12 +405,12 @@ export abstract class Graffiti {
 
   /**
    * An event target that can be used to listen for the following
-   * events and they're corresponding event types:
+   * events and their corresponding event types:
    * - `login` - {@link GraffitiLoginEvent}
    * - `logout` - {@link GraffitiLogoutEvent}
    * - `initialized` - {@link GraffitiSessionInitializedEvent}
    *
-   * @group Session Management
+   * @group 4 - Session Management
    */
   abstract readonly sessionEvents: EventTarget;
 }