@graffiti-garden/wrapper-synchronize
    Preparing search index...

    Class GraffitiAbstract

    This API describes a small but powerful set of methods that 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 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 that data—no server code necessary!

    The Typescript code for this API is open source on Github.

    There are several different implementations of this Graffiti API available, including a federated implementation, that lets people choose where their data is stored (you do not need to host your own server) and a local implementation 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.

    On the other side of the stack, there is Vue plugin that wraps around this API to provide reactivity. Other plugin frameworks and high-level libraries will be available in the future.

    The Graffiti API provides applications with methods for login and logout, methods to interact with data objects using standard database operations (post, get, and delete), and a method to discover data objects created by others. These data objects have a couple structured properties:

    • url (string): A globally unique identifier and locator for the object.
    • actor (string): An unforgeable identifier for the creator of the object.
    • allowed (string[] | undefined): An array of the actors who are allowed to access the object (undefined for public objects).
    • channels (string[]): An array of the contexts in which the object should appear.

    All other data is stored in the object's unstructured 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:

    {
      title: "My First Post",
      content: "Hello, world!",
      published: 1630483200000
    }

    a profile might have the value:

    {
      name: "Theia Henderson",
      pronouns: "she/her",
      describes: "did:web:theias.place" // Theia's actor ID
    }

    and a "Like" might have the value:

    {
      activity: "Like",
      target: "graffiti:remote:pod.graffiti.garden/12345" // The URL of the graffiti object being liked
    }

    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", 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.

    For a more complete and detailed overview of Graffiti's design, please refer to this section of the Graffiti paper, published in ACM UIST 2025. The paper also overviews 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.

    Implemented by

    Index

    Constructors

    constructor

    1 - Single-Object Methods

    Methods for creating, reading, and deleting Graffiti objects.

    delete get post

    2 - Multi-Object Methods

    Methods that retrieve or accumulate information about multiple Graffiti objects at a time.

    continueDiscover discover

    3 - Media Methods

    Methods for creating, reading, and deleting media data.

    deleteMedia getMedia postMedia

    4 - Identity Methods

    Methods and properties for logging in and out.

    sessionEvents actorToHandle handleToActor login logout

    Constructors

    1 - Single-Object Methods

    • Deletes an object from a given url that had previously been posted. The deleting actor must be the same as the actor that created the object.

      Parameters

      Returns Promise<void>

      GraffitiErrorNotFound if the object does not exist, has already been deleted, or the actor is not allowed to access it.

      GraffitiErrorForbidden if the actor is not the same actor as the one who created the object.

    • Retrieves an object from a given url matching the provided schema.

      If the retreiving actor is not the object's actor, the object's allowed and channels properties are not revealed, similar to a BCC email.

      Type Parameters

      Parameters

      • url: string | GraffitiObjectUrl

        The location of the object to get.

      • schema: Schema

        The JSON schema to validate the retrieved object against.

      • Optionalsession: GraffitiSession | null

        An implementation-specific object with information to authenticate the actor. If no session is provided, the retrieved object's allowed property must be undefined.

      Returns Promise<GraffitiObject<Schema>>

      Returns the retrieved object.

      GraffitiErrorNotFound if the object does not exist, has been deleted, or the actor is not allowed to access it.

      GraffitiErrorSchemaMismatch if the retrieved object does not match the provided schema.

      GraffitiErrorInvalidSchema If an invalid schema is provided.

    Abstractpost

    • post<Schema extends JSONSchema>(
          partialObject: GraffitiPostObject<Schema>,
          session: GraffitiSession,
      ): Promise<GraffitiObject<Schema>>

      Creates a new object.

      Type Parameters

      Parameters

      • partialObject: GraffitiPostObject<Schema>

        An object to post, minus its url and actor, which will be assigned once posted. This object is statically type-checked against the JSON schema that can be optionally provided as the generic type parameter. It is recommended to use a schema to ensure that the posted object matches subsequent get or discover methods.

      • session: GraffitiSession

        An implementation-specific object with information to authenticate the actor.

      Returns Promise<GraffitiObject<Schema>>

      Returns the object that has been posted, complete with its assigned url and actor.

    2 - Multi-Object Methods

    • Continues a GraffitiObjectStream from a given cursor string. The continuation will return new objects that have been posted that match the original stream, and also returns the urls of objects that have been deleted, as marked by a tombstone.

      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 continue method instead, which is returned along with the cursor at the end of the original stream.

      Parameters

      Returns GraffitiObjectStreamContinue<{}>

      GraffitiErrorNotFound upon iteration if the cursor is invalid or expired.

      GraffitiErrorForbidden upon iteration if the actor provided in the session is not the same as the actor that initiated the original stream.

    • Discovers objects created by any actor that are contained in at least one of the given channels and match the given JSON Schema.

      Objects are returned asynchronously as they are discovered but the stream will end once all leads have been exhausted. The GraffitiObjectStream ends by returning a continue method and a cursor string, each of which can be be used to poll for new objects. The continue method preserves the type safety of the stream and the cursor string can be serialized to continue the stream after an application is closed and reopened.

      discover will not return objects that the querying actor is not 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 allowed list is not undefined (public). Additionally, if the actor is not the creator of a discovered object, any channels not specified by the discover method will not be revealed. This masking happens before the object is validated against the supplied schema.

      Since different implementations may fetch data from multiple sources there is no guarentee on the order that objects are returned in.

      Type Parameters

      Parameters

      • channels: string[]

        The channels that objects must be associated with.

      • schema: Schema

        A JSON Schema that objects must satisfy.

      • Optionalsession: GraffitiSession | null

        An implementation-specific object with information to authenticate the actor. If no session is provided, only objects that have no allowed property will be returned.

      Returns GraffitiObjectStream<Schema>

      Returns a stream of objects that match the given channels and JSON Schema.

      GraffitiErrorInvalidSchema if an invalid schema is provided. Discovery is lazy and will not throw until the iterator is consumed.

    3 - Media Methods

    • Deletes media previously posted to a given URL.

      Parameters

      • url: string

        A globally unique identifier and locator for the media.

      • session: GraffitiSession

        An implementation-specific object with information to authenticate the actor.

      Returns Promise<void>

      GraffitiErrorNotFound if no media at that URL exists.

      GraffitiErrorForbidden if the actor provided in the session is not the same as the actor that posted the media.

    • Uploads media data, such as an image or video.

      Unlike structured objects, media is not indexed for discovery and must be retrieved by its exact URL using getMedia

      Parameters

      Returns Promise<string>

      The URL that the media was posted to.

    4 - Identity Methods

    sessionEvents: EventTarget

    An event target that can be used to listen for the following events and their corresponding event types:

    • Retrieves the human-readable handle associated with the given actor. The handle may change over time and so it should be used for display purposes only.

      The inverse of handleToActor.

      Parameters

      • actor: string

      Returns Promise<string>

      A human-readable handle for the given actor.

      GraffitiErrorNotFound if a handle cannot be found for the given actor.

    • Retrieves the actor ID associated with the given handle.

      The inverse of actorToHandle.

      Parameters

      • handle: string

      Returns Promise<string>

      The actor ID for the given handle.

      GraffitiErrorNotFound if there is no actor with the given handle.

    • Begins the login process. Depending on the implementation, this may 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.

      The session object is returned asynchronously via sessionEvents as a GraffitiLoginEvent with event type login.

      Parameters

      • Optionalactor: string

        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.

      Returns Promise<void>

    • Begins the logout process for a particular 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 gesture, such as clicking a button, due to the feature-gating browser security feature.

      A confirmation will be returned asynchronously via sessionEvents as a GraffitiLogoutEvent as event type logout.

      Parameters

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    API Overview
    Constructors
    1 - Single-Object Methods
    2 - Multi-Object Methods
    3 - Media Methods
    4 - Identity Methods