@graffiti-garden/api 0.2.11 → 0.3.0

package/README.md

@@ -4,4 +4,68 @@ The Graffiti API makes it possible to build many different types of social appli
 that naturally interoperate each other, all using only standard client-side tools.
 This repository contains the abstract API and its documentation.
 
-[**View the Documentation**](https://api.graffiti.garden/classes/Graffiti.html)
+[**View the API Documentation**](https://api.graffiti.garden/classes/Graffiti.html)
+
+## Implementing the API
+
+To implement the API, first install it:
+
+```bash
+npm install @graffiti-garden/api
+```
+
+Then create a class that extends the `Graffiti` class and implement the abstract methods.
+
+```typescript
+import { Graffiti } from "@graffiti-garden/api";
+
+class MyGraffitiImplementation extends Graffiti {
+  // Implement the abstract methods here
+}
+```
+
+### Testing
+
+We have written a number of unit tests written with [vitest](https://vitest.dev/)
+that can be used to verify implementations of the API.
+To use them, create a test file in that ends in `*.spec.ts` and format it as follows:
+
+```typescript
+import { graffitiCRUDTests } from "@graffiti-garden/api/tests";
+
+const useGraffiti = () => new MyGraffitiImplementation();
+// Fill in with implementation-specific information
+// to provide to valid actor sessions for the tests
+// to use as identities.
+const useSession1 = () => ({ actor: "someone" });
+const useSession2 = () => ({ actor: "someoneelse" });
+
+// Run the tests
+graffitiCRUDTests(useGraffiti, useSession1, useSession2);
+```
+
+Then run the tests in the root of your directory with:
+
+```bash
+npx vitest
+```
+
+## Building the Documentation
+
+To build the [TypeDoc](https://typedoc.org/) documentation, run the following commands:
+
+```bash
+npm run install
+npm run build:docs
+```
+
+Then run a local server to view the documentation:
+
+```bash
+cd docs
+npx http-server
+```
+
+## TODO
+
+- Implement scope.

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";var i=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var u=(e,t)=>{for(var s in t)i(e,s,{get:t[s],enumerable:!0})},x=(e,t,s,b)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of O(t))!l.call(e,r)&&r!==s&&i(e,r,{get:()=>t[r],enumerable:!(b=G(t,r))||b.enumerable});return e};var j=e=>x(i({},"__esModule",{value:!0}),e);var y={};u(y,{Graffiti:()=>a,GraffitiErrorForbidden:()=>c,GraffitiErrorInvalidSchema:()=>f,GraffitiErrorInvalidUri:()=>S,GraffitiErrorNotFound:()=>n,GraffitiErrorPatchError:()=>p,GraffitiErrorPatchTestFailed:()=>h,GraffitiErrorSchemaMismatch:()=>m,GraffitiErrorUnauthorized:()=>o});module.exports=j(y);var a=class{objectToUri(t){return this.locationToUri(t)}};var o=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorUnauthorized",Object.setPrototypeOf(this,e.prototype)}},c=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorForbidden",Object.setPrototypeOf(this,e.prototype)}},n=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorNotFound",Object.setPrototypeOf(this,e.prototype)}},f=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidSchema",Object.setPrototypeOf(this,e.prototype)}},m=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorSchemaMismatch",Object.setPrototypeOf(this,e.prototype)}},h=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchTestFailed",Object.setPrototypeOf(this,e.prototype)}},p=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchError",Object.setPrototypeOf(this,e.prototype)}},S=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidUri",Object.setPrototypeOf(this,e.prototype)}};
+"use strict";var o=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var G=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var u=(e,t)=>{for(var s in t)o(e,s,{get:t[s],enumerable:!0})},x=(e,t,s,S)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of G(t))!l.call(e,r)&&r!==s&&o(e,r,{get:()=>t[r],enumerable:!(S=O(t,r))||S.enumerable});return e};var j=e=>x(o({},"__esModule",{value:!0}),e);var y={};u(y,{Graffiti:()=>i,GraffitiErrorForbidden:()=>c,GraffitiErrorInvalidSchema:()=>f,GraffitiErrorInvalidUri:()=>b,GraffitiErrorNotFound:()=>n,GraffitiErrorPatchError:()=>h,GraffitiErrorPatchTestFailed:()=>m,GraffitiErrorSchemaMismatch:()=>p,GraffitiErrorUnauthorized:()=>a});module.exports=j(y);var i=class{objectToUri(t){return this.locationToUri(t)}};var a=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorUnauthorized",Object.setPrototypeOf(this,e.prototype)}},c=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorForbidden",Object.setPrototypeOf(this,e.prototype)}},n=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorNotFound",Object.setPrototypeOf(this,e.prototype)}},f=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidSchema",Object.setPrototypeOf(this,e.prototype)}},p=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorSchemaMismatch",Object.setPrototypeOf(this,e.prototype)}},m=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchTestFailed",Object.setPrototypeOf(this,e.prototype)}},h=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchError",Object.setPrototypeOf(this,e.prototype)}},b=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidUri",Object.setPrototypeOf(this,e.prototype)}};
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts", "../src/1-api.ts", "../src/3-errors.ts"],
-  "sourcesContent": ["export * from \"./1-api\";\nexport * from \"./2-types\";\nexport * from \"./3-errors\";\nexport type { JSONSchema4 } from \"json-schema\";\n", "import type {\n  GraffitiLocation,\n  GraffitiObject,\n  GraffitiObjectBase,\n  GraffitiPatch,\n  GraffitiSession,\n  GraffitiPutObject,\n  GraffitiStream,\n  ChannelStats,\n} from \"./2-types\";\nimport type { JSONSchema4 } from \"json-schema\";\n\n/**\n * This API describes a small but powerful set of methods that\n * can be used to create many different kinds of social media applications,\n * all of which can interoperate.\n * These methods should satisfy all of an application's needs for\n * the communication, storage, and access management of social data.\n * The rest of the application can be built with standard client-side\n * user interface tools to present and interact with the data \u2014\n * no server code necessary.\n * The Typescript source for this API is available at\n * [graffiti-garden/api](https://github.com/graffiti-garden/api).\n *\n * There are several different implementations of this Graffiti API available,\n * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),\n * that lets users choose where their data is stored,\n * and a [local implementation](https://github.com/graffiti-garden/implementation-local)\n * that can be used for testing and development. In our design of Graffiti, this API is our\n * primary focus as it is the layer that shapes the experience\n * of developing applications. While different implementations can provide tradeoffs between\n * other important properties (e.g. privacy, security, scalability), those properties\n * are useless if the system as a whole doesn't expose useful functionality to developers.\n *\n * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)\n * that wraps around this API to provide reactivity. Other high-level libraries\n * will be available in the future.\n *\n * ## Overview\n *\n * Graffiti provides applications with methods to create and store data\n * on behalf of their users using standard CRUD operations:\n *  {@link put}, {@link get}, {@link patch}, and {@link delete}.\n * This data can represent both social artifacts (e.g. posts, profiles) and\n * activities (e.g. likes, follows) and is stored as JSON.\n *\n * The social aspect of Graffiti comes from the {@link discover} method\n * which allows applications to find objects that other users made.\n * It is a lot like a traditional query operation, but it only\n * returns objects that have been placed in particular\n * {@link GraffitiObjectBase.channels | `channels`}\n * specified by the discovering application.\n *\n * Graffiti builds on well known concepts and standards wherever possible.\n * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches\n * can be applied with [JSON Patch](https://jsonpatch.com).\n * For interoperability between Graffiti applications, we recommend that\n * objects use established properties from the\n * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,\n * however it is always possible to create additional properties, contributing\n * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts\n * unique to Graffiti along with *interaction relativity*.\n * Channels create boundaries between public spaces and work to prevent\n * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)\n * even in a highly interoperable environment.\n * Interaction relativity means that all interactions between users are\n * actually atomic single-user operations that can be interpreted in different ways,\n * which also supports interoperability and pluralism.\n *\n * ### Channels\n *\n * {@link GraffitiObjectBase.channels | `channels`}\n * are a way for the creators of social data to express the intended audience of their\n * data. When a user creates data using the {@link put} method, they\n * can place their data in one or more channels.\n * Content consumers using the {@link discover} method will only see data\n * contained in one of the channels they specify.\n *\n * While many channels may be public, they partition\n * the public into different \"contexts\", mitigating the\n * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the \"flattening of multiple audiences.\"\n * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,\n * comment threads, topics, places (real or virtual), pieces of media, and more.\n *\n * For example, consider a comment on a post. If we place that comment in the channel\n * represented by the post's URI, then only people viewing the post will know to\n * look in that channel, giving it visibility akin to a comment on a blog post\n * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).\n * If we also place the comment in the channel represented by the commenter's URI (their\n * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile\n * will also see the comment, giving it more visibility, like a reply on Twitter.\n * If we *only* place the comment in the channel represented by the commenter's URI, then\n * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),\n * where the comment is only visible to the commenter's followers but not the audience\n * of the original post.\n *\n * The channel model differs from other models of communication such as the\n * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,\n * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)\n * used by the AT Protocol, the protocol underlying BlueSky.\n * The actor model is a fusion of direct messaging (like Email) and broadcasting\n * (like RSS) and works well for follow-based communication but struggles\n * to pass information via other rendez-vous.\n * In the actor model, even something as simple as comments can be\n * [very tricky and require server \"side effects\"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).\n * The firehose model dumps all user data into one public database,\n * which doesn't allow for the carving out of different contexts that we did in our comment\n * example above. In the firehose model a comment will always be visible to *both* the original post's audience and\n * the commenter's followers.\n *\n * In some sense, channels provide a sort of \"social access control\" by forming\n * expectations about the audiences of different online spaces.\n * As a real world analogy, oftentimes support groups, such as alcoholics\n * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details\n * because they have expectations about the other people attending.\n * If someone malicious went to support groups just to spread people's secrets,\n * they would be shamed for violating these norms.\n * Similarly, in Graffiti, while you could spider public channels like a search engine\n * to find content about a person, revealing that you've done such a thing\n * would be shameful.\n *\n * Still, social access control is not perfect and so in situations where privacy is important,\n * objects can also be given\n * an {@link GraffitiObjectBase.allowed | `allowed`} list.\n * For example, to send someone a direct message you should put an object representing\n * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),\n * so they can find it, *and* set the `allowed` field to only include the recipient,\n * so only they can read it.\n *\n * ### Interaction relativity\n *\n * Interaction relativity posits that \"interaction between two individuals only\n * exists relative to an observer,\" or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).\n * For example, if one user creates a post and another user wants to \"like\" that post,\n * their like is not modifying the original post, it is simply another data object that points\n * to the post being liked, via its {@link locationToUri | URI}.\n *\n * ```json\n * {\n *   activity: 'like',\n *   target: 'uri-of-the-post-i-like',\n *   actor: 'my-user-id'\n * }\n * ```\n *\n * In Graffiti, all interactions including *moderation* and *collaboration* are relative.\n * This means that applications can freely choose which interactions\n * they want to express to their users and how.\n * For example, one application could have a single fixed moderator,\n * another could allow users to choose which moderators they would like filter their content\n * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),\n * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).\n * Each of these applications is one interpretation of the underlying refieid user interactions and\n * users can freely switch between them.\n *\n * Interaction relativy also allows applications to introduce new sorts of interactions\n * without having to coordinate with all the other existing applications,\n * keeping the ecosystem flexible and interoperable.\n * For example, an application could [add a \"Trust\" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)\n * and use it assess the truthfulness of posts made on applications across Graffiti.\n * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem\n * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * Interactivy relativity is realized in Graffiti through two design decisions:\n * 1. The creators of objects can only modify their own objects. It is important for\n *    users to be able to change and delete their own content to respect their\n *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),\n *    but beyond self-correction and self-censorship all other interaction is reified.\n *    Many interactions can be reified via pointers, as in the \"like\" example above, and collaborative\n *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).\n * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),\n *    anyone can post to any channel, so long as they know the URI of that channel.\n *    It is up to applications to hide content from channels either according to manual\n *    filters or in response to user action.\n *    For example, a user may create a post with the flag `disableReplies`.\n *    Applications could then filter out any content from the replies channel\n *    that the original poster has not specifically approved.\n *\n * ## Implementing the API\n *\n * To implement the API, first install it:\n *\n * ```bash\n * npm install @graffiti-garden/api\n * ```\n *\n * Then create a class that extends the `Graffiti` class and implement the abstract methods.\n *\n * ```typescript\n * import { Graffiti } from \"@graffiti-garden/api\";\n *\n * class MyGraffitiImplementation extends Graffiti {\n *   // Implement the abstract methods here\n * }\n * ```\n * ### Testing\n *\n * We have written a number of unit tests written with [vitest](https://vitest.dev/)\n * that can be used to verify implementations of the API.\n * To use them, create a test file in that ends in `*.spec.ts` and format it as follows:\n *\n * ```typescript\n * import { graffitiCRUDTests } from \"@graffiti-garden/api/tests\";\n *\n * const useGraffiti = () => new MyGraffitiImplementation();\n * // Fill in with implementation-specific information\n * // to provide to valid actor sessions for the tests\n * // to use as identities.\n * const useSession1 = () => ({ actor: \"someone\" });\n * const useSession2 = () => ({ actor: \"someoneelse\" });\n *\n * // Run the tests\n * graffitiCRUDTests(useGraffiti, useSession1, useSession2);\n * ```\n *\n * Then run the tests in the root of your directory with:\n *\n * ```bash\n * npx vitest\n * ```\n *\n * ## Building the Documentation\n *\n * To build the [TypeDoc](https://typedoc.org/) documentation, run the following commands:\n *\n * ```bash\n * npm run install\n * npm run docs\n * ```\n *\n * Then run a local server to view the documentation:\n *\n * ```bash\n * cd docs\n * npx http-server\n * ```\n *\n * ## TODO\n *\n * - Implement scope.\n *\n * @groupDescription CRUD Methods\n * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},\n * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.\n * @groupDescription Query Methods\n * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.\n * @groupDescription Session Management\n * Methods and properties for logging in and out of a Graffiti implementation.\n * @groupDescription Utilities\n * Methods for for converting Graffiti objects to and from URIs.\n */\nexport abstract class Graffiti {\n  /**\n   * Converts a {@link GraffitiLocation} object containing a\n   * {@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`} into a globally unique URI.\n   * The form of this URI is implementation dependent.\n   *\n   * Its exact inverse is {@link uriToLocation}.\n   *\n   * @group Utilities\n   */\n  abstract locationToUri(location: GraffitiLocation): string;\n\n  /**\n   * Parses a globally unique Graffiti URI into a {@link GraffitiLocation}\n   * object containing a {@link GraffitiObjectBase.name | `name`},\n   * {@link GraffitiObjectBase.actor | `actor`}, and {@link GraffitiObjectBase.source | `source`}.\n   *\n   * Its exact inverse is {@link locationToUri}.\n   *\n   * @group Utilities\n   */\n  abstract uriToLocation(uri: string): GraffitiLocation;\n\n  /**\n   * An alias of {@link locationToUri}\n   *\n   * @group Utilities\n   */\n  objectToUri(object: GraffitiObjectBase) {\n    return this.locationToUri(object);\n  }\n\n  /**\n   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.\n   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}\n   * that created it.\n   *\n   * Replacement occurs when the {@link GraffitiLocation} properties of the supplied object\n   * ({@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`}) exactly match the location of an existing object.\n   *\n   * @returns The object that was replaced if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} if this method\n   * created a new object.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of replacement/creation.\n   *\n   * @group CRUD Methods\n   */\n  abstract put<Schema>(\n    /**\n     * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided\n     * as the generic type parameter. We highly recommend providing a schema to\n     * ensure that the PUT object matches subsequent {@link get} or {@link discover}\n     * methods.\n     */\n    object: GraffitiPutObject<Schema>,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Retrieves an object from a given location.\n   *\n   * The retrieved object is type-checked against the provided [JSON schema](https://json-schema.org/)\n   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.\n   *\n   * If the object existed but has since been deleted,\n   * or the retrieving {@link GraffitiObjectBase.actor | `actor`}\n   * was {@link GraffitiObjectBase.allowed | `allowed`} to access\n   * the object but now isn't, this method will return the latest\n   * version of the object that the {@link GraffitiObjectBase.actor | `actor`}\n   * was allowed to access with its {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * set to `true`, so long as that version is still cached.\n   *\n   * Otherwise, if the object never existed, or the\n   * retrieving {@link GraffitiObjectBase.actor | `actor`} was never\n   * {@link GraffitiObjectBase.allowed | `allowed`} to access it, or if\n   * the object was changed long enough ago that its history has been\n   * purged from the cache, a {@link GraffitiErrorNotFound} is thrown.\n   * The rate at which the cache is purged is implementation dependent.\n   * See the `tombstoneReturn` property returned by {@link discover}.\n   *\n   * @group CRUD Methods\n   */\n  abstract get<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): Promise<GraffitiObject<Schema>>;\n\n  /**\n   * Patches an existing object at a given location.\n   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract patch(\n    /**\n     * A collection of [JSON Patch](https://jsonpatch.com) operations\n     * to apply to the object. See {@link GraffitiPatch} for more information.\n     */\n    patch: GraffitiPatch,\n    /**\n     * The location of the object to patch.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Deletes an object from a given location.\n   * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * If the object does not exist or has already been deleted,\n   * {@link GraffitiErrorNotFound} is thrown.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract delete(\n    /**\n     * The location of the object to delete.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Discovers objects created by any user that are contained\n   * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   *\n   * Objects are returned asynchronously as they are discovered but the stream\n   * will end once all leads have been exhausted.\n   * The method must be polled again for new objects.\n   *\n   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}\n   * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.\n   * If the actor is not the creator of a discovered object,\n   * the allowed list will be masked to only contain the querying actor if the\n   * allowed list is not `undefined` (public). Additionally, if the actor is not the\n   * creator of a discovered object, any {@link GraffitiObjectBase.channels | `channels`}\n   * not specified by the `discover` method will not be revealed. This masking happens\n   * before the supplied schema is applied.\n   *\n   * {@link discover} can be used in conjunction with {@link synchronizeDiscover}\n   * to provide a responsive and consistent user experience.\n   *\n   * Since different implementations may fetch data from multiple sources there is\n   * no guarentee on the order that objects are returned in. Additionally, the method\n   * will return objects that have been deleted but with a\n   * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for\n   * cache invalidation purposes.\n   * The final `return()` value of the stream includes a `tombstoneRetention`\n   * property that represents the minimum amount of time,\n   * in milliseconds, that an application will retain and return tombstones for objects that\n   * have been deleted.\n   *\n   * When repolling, the {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field can be queried via the schema to\n   * only fetch objects that have been modified since the last poll.\n   * Such queries should only be done if the time since the last poll\n   * is less than the `tombstoneRetention` value of that poll, otherwise the tombstones\n   * for objects that have been deleted may not be returned.\n   *\n   * ```json\n   * {\n   *   \"properties\": {\n   *     \"lastModified\": {\n   *       \"minimum\": LAST_RETRIEVED_TIME\n   *     }\n   *   }\n   * }\n   * ```\n   *\n   * `discover` needs to be polled for new data because live updates to\n   * an application can be visually distracting or lead to toxic engagement.\n   * If and when an application wants real-time updates, such as in a chat\n   * application, application authors must be intentional about their polling.\n   *\n   * Implementers should be aware that some users may applications may try to poll\n   * {@link discover} repetitively. You can deal with this by rate limiting or\n   * preemptively fetching data via a bidirectional channel, like a WebSocket.\n   * Additionally, implementers should probably index the `lastModified` field\n   * to speed up responses to schemas like the one above.\n   *\n   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}\n   * and [JSON Schema](https://json-schema.org).\n   *\n   * @group Query Methods\n   */\n  abstract discover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Discovers objects **not** contained in any\n   * {@link GraffitiObjectBase.channels | `channels`}\n   * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   * Unlike {@link discover}, this method will not return objects created by other users.\n   *\n   * This method is not useful for most applications, but necessary for\n   * getting a global view of all a user's Graffiti data or debugging\n   * channel usage.\n   *\n   * It's return value is the same as {@link discover}.\n   *\n   * @group Query Methods\n   */\n  abstract recoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}\n   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   * This is not very useful for most applications, but\n   * necessary for certain applications where a user wants a\n   * global view of all their Graffiti data or to debug\n   * channel usage.\n   *\n   * @group Query Methods\n   *\n   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}\n   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   */\n  abstract channelStats(\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<ChannelStats>;\n\n  /**\n   * Begins the login process. Depending on the implementation, this may\n   * involve redirecting the user to a login page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * The {@link GraffitiSession | session} object is returned\n   * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLoginEvent} with event type `login`.\n   *\n   * @group Session Management\n   */\n  abstract login(\n    /**\n     * Suggestions for the permissions that the\n     * login process should grant. The login process may not\n     * provide the exact proposed permissions.\n     */\n    proposal?: {\n      /**\n       * A suggested actor to login as. For example, if a user tries to\n       * edit a post but are not logged in, the interface can infer that\n       * they might want to log in as the actor who created the post\n       * they are attempting to edit.\n       *\n       * Even if provided, the implementation should allow the user\n       * to log in as a different actor if they choose.\n       */\n      actor?: string;\n      /**\n       * A yet to be defined permissions scope. An application may use\n       * this to indicate the minimum necessary scope needed to\n       * operate. For example, it may need to be able read private\n       * messages from a certain set of channels, or write messages that\n       * follow a particular schema.\n       *\n       * The login process should make it clear what scope an application\n       * is requesting and allow the user to enhance or reduce that\n       * scope as necessary.\n       */\n      scope?: {};\n    },\n  ): Promise<void>;\n\n  /**\n   * Begins the logout process. Depending on the implementation, this may\n   * involve redirecting the user to a logout page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * A confirmation will be returned asynchronously via\n   * {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLogoutEvent} as event type `logout`.\n   *\n   * @group Session Management\n   */\n  abstract logout(\n    /**\n     * The {@link GraffitiSession | session} object to logout.\n     */\n    session: GraffitiSession,\n  ): Promise<void>;\n\n  /**\n   * An event target that can be used to listen for the following\n   * events and they're corresponding event types:\n   * - `login` - {@link GraffitiLoginEvent}\n   * - `logout` - {@link GraffitiLogoutEvent}\n   * - `initialized` - {@link GraffitiSessionInitializedEvent}\n   *\n   * @group Session Management\n   */\n  abstract readonly sessionEvents: EventTarget;\n\n  /**\n   * This method has the same signature as {@link discover} but listens for\n   * changes made via {@link put}, {@link patch}, and {@link delete} or\n   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans}\n   * and then streams appropriate changes to provide a responsive and\n   * consistent user experience.\n   *\n   * Unlike {@link discover}, this method continuously listens for changes\n   * and will not terminate unless the user calls the `return` method on the iterator\n   * or `break`s out of the loop.\n   *\n   * Example 1: Suppose a user publishes a post using {@link put}. If the feed\n   * displaying that user's posts is using {@link synchronizeDiscover} to listen for changes,\n   * then the user's new post will instantly appear in their feed, giving the UI a\n   * responsive feel.\n   *\n   * Example 2: Suppose one of a user's friends changes their name. As soon as the\n   * user's application receives one notice of that change (using {@link get}\n   * or {@link discover}), then {@link synchronizeDiscover} listeners can be used to update\n   * all instance's of that friend's name in the user's application instantly,\n   * providing a consistent user experience.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeDiscover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that the objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n\n  /**\n   * This method has the same signature as {@link get} but, like {@link synchronizeDiscover},\n   * it listens for changes made via {@link put}, {@link patch}, and {@link delete} or\n   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then\n   * streams appropriate changes to provide a responsive and consistent user experience.\n   *\n   * Unlike {@link get}, which returns a single result, this method continuously\n   * listens for changes which are output as an asynchronous {@link GraffitiStream}.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeGet<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n\n  /**\n   * This method has the same signature as {@link recoverOrphans} but,\n   * like {@link synchronizeDiscover}, it listens for changes made via\n   * {@link put}, {@link patch}, and {@link delete} or fetched from\n   * {@link get}, {@link discover}, and {@link recoverOrphans} and then\n   * streams appropriate changes to provide a responsive and consistent user experience.\n   *\n   * Unlike {@link recoverOrphans}, this method continuously listens for changes\n   * and will not terminate unless the user calls the `return` method on the iterator\n   * or `break`s out of the loop.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeRecoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n}\n\n/**\n * This is a factory function that produces an instance of\n * the {@link Graffiti} class. Since the Graffiti class is\n * abstract, factory functions provide an easy way to\n * swap out different implementations.\n */\nexport type GraffitiFactory = () => Graffiti;\n", "export class GraffitiErrorUnauthorized extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorUnauthorized\";\n    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);\n  }\n}\n\nexport class GraffitiErrorForbidden extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorForbidden\";\n    Object.setPrototypeOf(this, GraffitiErrorForbidden.prototype);\n  }\n}\n\nexport class GraffitiErrorNotFound extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorNotFound\";\n    Object.setPrototypeOf(this, GraffitiErrorNotFound.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidSchema extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidSchema\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidSchema.prototype);\n  }\n}\n\nexport class GraffitiErrorSchemaMismatch extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorSchemaMismatch\";\n    Object.setPrototypeOf(this, GraffitiErrorSchemaMismatch.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchTestFailed extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchTestFailed\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchError extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchError\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidUri extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidUri\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);\n  }\n}\n"],
-  "mappings": "yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,cAAAE,EAAA,2BAAAC,EAAA,+BAAAC,EAAA,4BAAAC,EAAA,0BAAAC,EAAA,4BAAAC,EAAA,iCAAAC,EAAA,gCAAAC,EAAA,8BAAAC,IAAA,eAAAC,EAAAX,GC6PO,IAAeY,EAAf,KAAwB,CA6B7B,YAAYC,EAA4B,CACtC,OAAO,KAAK,cAAcA,CAAM,CAClC,CA0bF,ECttBO,IAAMC,EAAN,MAAMC,UAAkC,KAAM,CACnD,YAAYC,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,4BACZ,OAAO,eAAe,KAAMD,EAA0B,SAAS,CACjE,CACF,EAEaE,EAAN,MAAMC,UAA+B,KAAM,CAChD,YAAYF,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,yBACZ,OAAO,eAAe,KAAME,EAAuB,SAAS,CAC9D,CACF,EAEaC,EAAN,MAAMC,UAA8B,KAAM,CAC/C,YAAYJ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,wBACZ,OAAO,eAAe,KAAMI,EAAsB,SAAS,CAC7D,CACF,EAEaC,EAAN,MAAMC,UAAmC,KAAM,CACpD,YAAYN,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,6BACZ,OAAO,eAAe,KAAMM,EAA2B,SAAS,CAClE,CACF,EAEaC,EAAN,MAAMC,UAAoC,KAAM,CACrD,YAAYR,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,8BACZ,OAAO,eAAe,KAAMQ,EAA4B,SAAS,CACnE,CACF,EAEaC,EAAN,MAAMC,UAAqC,KAAM,CACtD,YAAYV,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,+BACZ,OAAO,eAAe,KAAMU,EAA6B,SAAS,CACpE,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYZ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMY,EAAwB,SAAS,CAC/D,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYd,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMc,EAAwB,SAAS,CAC/D,CACF",
+  "sourcesContent": ["export * from \"./1-api\";\nexport * from \"./2-types\";\nexport * from \"./3-errors\";\nexport type { JSONSchema4 } from \"json-schema\";\n", "import type {\n  GraffitiLocation,\n  GraffitiObject,\n  GraffitiObjectBase,\n  GraffitiPatch,\n  GraffitiSession,\n  GraffitiPutObject,\n  GraffitiStream,\n  ChannelStats,\n} from \"./2-types\";\nimport type { JSONSchema4 } from \"json-schema\";\n\n/**\n * This API describes a small but powerful set of methods that\n * can be used to create many different kinds of social media applications,\n * all of which can interoperate.\n * These methods should satisfy all of an application's needs for\n * the communication, storage, and access management of social data.\n * The rest of the application can be built with standard client-side\n * user interface tools to present and interact with the data \u2014\n * no server code necessary.\n * The Typescript source for this API is available at\n * [graffiti-garden/api](https://github.com/graffiti-garden/api).\n *\n * There are several different implementations of this Graffiti API available,\n * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),\n * that lets users choose where their data is stored,\n * and a [local implementation](https://github.com/graffiti-garden/implementation-local)\n * that can be used for testing and development. In our design of Graffiti, this API is our\n * primary focus as it is the layer that shapes the experience\n * of developing applications. While different implementations can provide tradeoffs between\n * other important properties (e.g. privacy, security, scalability), those properties\n * are useless if the system as a whole doesn't expose useful functionality to developers.\n *\n * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)\n * that wraps around this API to provide reactivity. Other high-level libraries\n * will be available in the future.\n *\n * ## Overview\n *\n * Graffiti provides applications with methods to create and store data\n * on behalf of their users using standard CRUD operations:\n *  {@link put}, {@link get}, {@link patch}, and {@link delete}.\n * This data can represent both social artifacts (e.g. posts, profiles) and\n * activities (e.g. likes, follows) and is stored as JSON.\n *\n * The social aspect of Graffiti comes from the {@link discover} method\n * which allows applications to find objects that other users made.\n * It is a lot like a traditional query operation, but it only\n * returns objects that have been placed in particular\n * {@link GraffitiObjectBase.channels | `channels`}\n * specified by the discovering application.\n *\n * Graffiti builds on well known concepts and standards wherever possible.\n * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches\n * can be applied with [JSON Patch](https://jsonpatch.com).\n * For interoperability between Graffiti applications, we recommend that\n * objects use established properties from the\n * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,\n * however it is always possible to create additional properties, contributing\n * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts\n * unique to Graffiti along with *interaction relativity*, defined below.\n * Channels create boundaries between public spaces and work to prevent\n * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)\n * even in a highly interoperable environment.\n * Interaction relativity means that all interactions between users are\n * actually atomic single-user operations that can be interpreted in different ways,\n * which also supports interoperability and pluralism.\n *\n * ### Channels\n *\n * {@link GraffitiObjectBase.channels | `channels`}\n * are a way for the creators of social data to express the intended audience of their\n * data. When a user creates data using the {@link put} method, they\n * can place their data in one or more channels.\n * Content consumers using the {@link discover} method will only see data\n * contained in one of the channels they specify.\n *\n * While many channels may be public, they partition\n * the public into different \"contexts\", mitigating the\n * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the \"flattening of multiple audiences.\"\n * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,\n * comment threads, topics, places (real or virtual), pieces of media, and more.\n *\n * For example, consider a comment on a post. If we place that comment in the channel\n * represented by the post's URI, then only people viewing the post will know to\n * look in that channel, giving it visibility akin to a comment on a blog post\n * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).\n * If we also place the comment in the channel represented by the commenter's URI (their\n * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile\n * will also see the comment, giving it more visibility, like a reply on Twitter.\n * If we *only* place the comment in the channel represented by the commenter's URI, then\n * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),\n * where the comment is only visible to the commenter's followers but not the audience\n * of the original post.\n *\n * The channel model differs from other models of communication such as the\n * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,\n * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)\n * used by the AT Protocol, the protocol underlying BlueSky.\n * The actor model is a fusion of direct messaging (like Email) and broadcasting\n * (like RSS) and works well for follow-based communication but struggles\n * to pass information via other rendez-vous.\n * In the actor model, even something as simple as comments can be\n * [very tricky and require server \"side effects\"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).\n * The firehose model dumps all user data into one public database,\n * which doesn't allow for the carving out of different contexts that we did in our comment\n * example above. In the firehose model a comment will always be visible to *both* the original post's audience and\n * the commenter's followers.\n *\n * In some sense, channels provide a sort of \"social access control\" by forming\n * expectations about the audiences of different online spaces.\n * As a real world analogy, oftentimes support groups, such as alcoholics\n * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details\n * because they have expectations about the other people attending.\n * If someone malicious went to support groups just to spread people's secrets,\n * they would be shamed for violating these norms.\n * Similarly, in Graffiti, while you could spider public channels like a search engine\n * to find content about a person, revealing that you've done such a thing\n * would be shameful.\n *\n * Still, social access control is not perfect and so in situations where privacy is important,\n * objects can also be given\n * an {@link GraffitiObjectBase.allowed | `allowed`} list.\n * For example, to send someone a direct message you should put an object representing\n * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),\n * so they can find it, *and* set the `allowed` field to only include the recipient,\n * so only they can read it.\n *\n * ### Interaction relativity\n *\n * Interaction relativity posits that \"interaction between two individuals only\n * exists relative to an observer,\" or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).\n * For example, if one user creates a post and another user wants to \"like\" that post,\n * their like is not modifying the original post, it is simply another data object that points\n * to the post being liked, via its {@link locationToUri | URI}.\n *\n * ```json\n * {\n *   activity: 'like',\n *   target: 'uri-of-the-post-i-like',\n *   actor: 'my-user-id'\n * }\n * ```\n *\n * In Graffiti, all interactions including *moderation* and *collaboration* are relative.\n * This means that applications can freely choose which interactions\n * they want to express to their users and how.\n * For example, one application could have a single fixed moderator,\n * another could allow users to choose which moderators they would like filter their content\n * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),\n * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).\n * Each of these applications is one interpretation of the underlying refieid user interactions and\n * users can freely switch between them.\n *\n * Interaction relativy also allows applications to introduce new sorts of interactions\n * without having to coordinate with all the other existing applications,\n * keeping the ecosystem flexible and interoperable.\n * For example, an application could [add a \"Trust\" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)\n * and use it assess the truthfulness of posts made on applications across Graffiti.\n * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem\n * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * Interactivy relativity is realized in Graffiti through two design decisions:\n * 1. The creators of objects can only modify their own objects. It is important for\n *    users to be able to change and delete their own content to respect their\n *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),\n *    but beyond self-correction and self-censorship all other interaction is reified.\n *    Many interactions can be reified via pointers, as in the \"like\" example above, and collaborative\n *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).\n * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),\n *    anyone can post to any channel, so long as they know the URI of that channel.\n *    It is up to applications to hide content from channels either according to manual\n *    filters or in response to user action.\n *    For example, a user may create a post with the flag `disableReplies`.\n *    Applications could then filter out any content from the replies channel\n *    that the original poster has not specifically approved.\n *\n * @groupDescription CRUD Methods\n * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},\n * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.\n * @groupDescription Query Methods\n * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.\n * @groupDescription Session Management\n * Methods and properties for logging in and out of a Graffiti implementation.\n * @groupDescription Utilities\n * Methods for for converting Graffiti objects to and from URIs.\n */\nexport abstract class Graffiti {\n  /**\n   * Converts a {@link GraffitiLocation} object containing a\n   * {@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`} into a globally unique URI.\n   * The form of this URI is implementation dependent.\n   *\n   * Its exact inverse is {@link uriToLocation}.\n   *\n   * @group Utilities\n   */\n  abstract locationToUri(location: GraffitiLocation): string;\n\n  /**\n   * Parses a globally unique Graffiti URI into a {@link GraffitiLocation}\n   * object containing a {@link GraffitiObjectBase.name | `name`},\n   * {@link GraffitiObjectBase.actor | `actor`}, and {@link GraffitiObjectBase.source | `source`}.\n   *\n   * Its exact inverse is {@link locationToUri}.\n   *\n   * @group Utilities\n   */\n  abstract uriToLocation(uri: string): GraffitiLocation;\n\n  /**\n   * An alias of {@link locationToUri}\n   *\n   * @group Utilities\n   */\n  objectToUri(object: GraffitiObjectBase) {\n    return this.locationToUri(object);\n  }\n\n  /**\n   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.\n   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}\n   * that created it.\n   *\n   * Replacement occurs when the {@link GraffitiLocation} properties of the supplied object\n   * ({@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`}) exactly match the location of an existing object.\n   *\n   * @returns The object that was replaced if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} if this method\n   * created a new object.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of replacement/creation.\n   *\n   * @group CRUD Methods\n   */\n  abstract put<Schema>(\n    /**\n     * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided\n     * as the generic type parameter. We highly recommend providing a schema to\n     * ensure that the PUT object matches subsequent {@link get} or {@link discover}\n     * methods.\n     */\n    object: GraffitiPutObject<Schema>,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Retrieves an object from a given location.\n   *\n   * The retrieved object is type-checked against the provided [JSON schema](https://json-schema.org/)\n   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.\n   *\n   * If the object existed but has since been deleted,\n   * or the retrieving {@link GraffitiObjectBase.actor | `actor`}\n   * was {@link GraffitiObjectBase.allowed | `allowed`} to access\n   * the object but now isn't, this method will return the latest\n   * version of the object that the {@link GraffitiObjectBase.actor | `actor`}\n   * was allowed to access with its {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * set to `true`, so long as that version is still cached.\n   *\n   * Otherwise, if the object never existed, or the\n   * retrieving {@link GraffitiObjectBase.actor | `actor`} was never\n   * {@link GraffitiObjectBase.allowed | `allowed`} to access it, or if\n   * the object was changed long enough ago that its history has been\n   * purged from the cache, a {@link GraffitiErrorNotFound} is thrown.\n   * The rate at which the cache is purged is implementation dependent.\n   * See the `tombstoneReturn` property returned by {@link discover}.\n   *\n   * @group CRUD Methods\n   */\n  abstract get<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): Promise<GraffitiObject<Schema>>;\n\n  /**\n   * Patches an existing object at a given location.\n   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract patch(\n    /**\n     * A collection of [JSON Patch](https://jsonpatch.com) operations\n     * to apply to the object. See {@link GraffitiPatch} for more information.\n     */\n    patch: GraffitiPatch,\n    /**\n     * The location of the object to patch.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Deletes an object from a given location.\n   * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * If the object does not exist or has already been deleted,\n   * {@link GraffitiErrorNotFound} is thrown.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract delete(\n    /**\n     * The location of the object to delete.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Discovers objects created by any user that are contained\n   * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   *\n   * Objects are returned asynchronously as they are discovered but the stream\n   * will end once all leads have been exhausted.\n   * The method must be polled again for new objects.\n   *\n   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}\n   * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.\n   * If the actor is not the creator of a discovered object,\n   * the allowed list will be masked to only contain the querying actor if the\n   * allowed list is not `undefined` (public). Additionally, if the actor is not the\n   * creator of a discovered object, any {@link GraffitiObjectBase.channels | `channels`}\n   * not specified by the `discover` method will not be revealed. This masking happens\n   * before the supplied schema is applied.\n   *\n   * Since different implementations may fetch data from multiple sources there is\n   * no guarentee on the order that objects are returned in. Additionally, the method\n   * will return objects that have been deleted but with a\n   * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for\n   * cache invalidation purposes.\n   * The final `return()` value of the stream includes a `tombstoneRetention`\n   * property that represents the minimum amount of time,\n   * in milliseconds, that an application will retain and return tombstones for objects that\n   * have been deleted.\n   *\n   * When repolling, the {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field can be queried via the schema to\n   * only fetch objects that have been modified since the last poll.\n   * Such queries should only be done if the time since the last poll\n   * is less than the `tombstoneRetention` value of that poll, otherwise the tombstones\n   * for objects that have been deleted may not be returned.\n   *\n   * ```json\n   * {\n   *   \"properties\": {\n   *     \"lastModified\": {\n   *       \"minimum\": LAST_RETRIEVED_TIME\n   *     }\n   *   }\n   * }\n   * ```\n   *\n   * `discover` needs to be polled for new data because live updates to\n   * an application can be visually distracting or lead to toxic engagement.\n   * If and when an application wants real-time updates, such as in a chat\n   * application, application authors must be intentional about their polling.\n   *\n   * Implementers should be aware that some users may applications may try to poll\n   * {@link discover} repetitively. You can deal with this by rate limiting or\n   * preemptively fetching data via a bidirectional channel, like a WebSocket.\n   * Additionally, implementers should probably index the `lastModified` field\n   * to speed up responses to schemas like the one above.\n   *\n   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}\n   * and [JSON Schema](https://json-schema.org).\n   *\n   * @group Query Methods\n   */\n  abstract discover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Discovers objects **not** contained in any\n   * {@link GraffitiObjectBase.channels | `channels`}\n   * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   * Unlike {@link discover}, this method will not return objects created by other users.\n   *\n   * This method is not useful for most applications, but necessary for\n   * getting a global view of all a user's Graffiti data or debugging\n   * channel usage.\n   *\n   * It's return value is the same as {@link discover}.\n   *\n   * @group Query Methods\n   */\n  abstract recoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}\n   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   * This is not very useful for most applications, but\n   * necessary for certain applications where a user wants a\n   * global view of all their Graffiti data or to debug\n   * channel usage.\n   *\n   * @group Query Methods\n   *\n   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}\n   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   */\n  abstract channelStats(\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<ChannelStats>;\n\n  /**\n   * Begins the login process. Depending on the implementation, this may\n   * involve redirecting the user to a login page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * The {@link GraffitiSession | session} object is returned\n   * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLoginEvent} with event type `login`.\n   *\n   * @group Session Management\n   */\n  abstract login(\n    /**\n     * Suggestions for the permissions that the\n     * login process should grant. The login process may not\n     * provide the exact proposed permissions.\n     */\n    proposal?: {\n      /**\n       * A suggested actor to login as. For example, if a user tries to\n       * edit a post but are not logged in, the interface can infer that\n       * they might want to log in as the actor who created the post\n       * they are attempting to edit.\n       *\n       * Even if provided, the implementation should allow the user\n       * to log in as a different actor if they choose.\n       */\n      actor?: string;\n      /**\n       * A yet to be defined permissions scope. An application may use\n       * this to indicate the minimum necessary scope needed to\n       * operate. For example, it may need to be able read private\n       * messages from a certain set of channels, or write messages that\n       * follow a particular schema.\n       *\n       * The login process should make it clear what scope an application\n       * is requesting and allow the user to enhance or reduce that\n       * scope as necessary.\n       */\n      scope?: {};\n    },\n  ): Promise<void>;\n\n  /**\n   * Begins the logout process. Depending on the implementation, this may\n   * involve redirecting the user to a logout page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * A confirmation will be returned asynchronously via\n   * {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLogoutEvent} as event type `logout`.\n   *\n   * @group Session Management\n   */\n  abstract logout(\n    /**\n     * The {@link GraffitiSession | session} object to logout.\n     */\n    session: GraffitiSession,\n  ): Promise<void>;\n\n  /**\n   * An event target that can be used to listen for the following\n   * events and they're corresponding event types:\n   * - `login` - {@link GraffitiLoginEvent}\n   * - `logout` - {@link GraffitiLogoutEvent}\n   * - `initialized` - {@link GraffitiSessionInitializedEvent}\n   *\n   * @group Session Management\n   */\n  abstract readonly sessionEvents: EventTarget;\n}\n", "export class GraffitiErrorUnauthorized extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorUnauthorized\";\n    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);\n  }\n}\n\nexport class GraffitiErrorForbidden extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorForbidden\";\n    Object.setPrototypeOf(this, GraffitiErrorForbidden.prototype);\n  }\n}\n\nexport class GraffitiErrorNotFound extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorNotFound\";\n    Object.setPrototypeOf(this, GraffitiErrorNotFound.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidSchema extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidSchema\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidSchema.prototype);\n  }\n}\n\nexport class GraffitiErrorSchemaMismatch extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorSchemaMismatch\";\n    Object.setPrototypeOf(this, GraffitiErrorSchemaMismatch.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchTestFailed extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchTestFailed\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchError extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchError\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidUri extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidUri\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);\n  }\n}\n"],
+  "mappings": "yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,cAAAE,EAAA,2BAAAC,EAAA,+BAAAC,EAAA,4BAAAC,EAAA,0BAAAC,EAAA,4BAAAC,EAAA,iCAAAC,EAAA,gCAAAC,EAAA,8BAAAC,IAAA,eAAAC,EAAAX,GC8LO,IAAeY,EAAf,KAAwB,CA6B7B,YAAYC,EAA4B,CACtC,OAAO,KAAK,cAAcA,CAAM,CAClC,CAuVF,ECpjBO,IAAMC,EAAN,MAAMC,UAAkC,KAAM,CACnD,YAAYC,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,4BACZ,OAAO,eAAe,KAAMD,EAA0B,SAAS,CACjE,CACF,EAEaE,EAAN,MAAMC,UAA+B,KAAM,CAChD,YAAYF,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,yBACZ,OAAO,eAAe,KAAME,EAAuB,SAAS,CAC9D,CACF,EAEaC,EAAN,MAAMC,UAA8B,KAAM,CAC/C,YAAYJ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,wBACZ,OAAO,eAAe,KAAMI,EAAsB,SAAS,CAC7D,CACF,EAEaC,EAAN,MAAMC,UAAmC,KAAM,CACpD,YAAYN,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,6BACZ,OAAO,eAAe,KAAMM,EAA2B,SAAS,CAClE,CACF,EAEaC,EAAN,MAAMC,UAAoC,KAAM,CACrD,YAAYR,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,8BACZ,OAAO,eAAe,KAAMQ,EAA4B,SAAS,CACnE,CACF,EAEaC,EAAN,MAAMC,UAAqC,KAAM,CACtD,YAAYV,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,+BACZ,OAAO,eAAe,KAAMU,EAA6B,SAAS,CACpE,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYZ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMY,EAAwB,SAAS,CAC/D,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYd,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMc,EAAwB,SAAS,CAC/D,CACF",
   "names": ["src_exports", "__export", "Graffiti", "GraffitiErrorForbidden", "GraffitiErrorInvalidSchema", "GraffitiErrorInvalidUri", "GraffitiErrorNotFound", "GraffitiErrorPatchError", "GraffitiErrorPatchTestFailed", "GraffitiErrorSchemaMismatch", "GraffitiErrorUnauthorized", "__toCommonJS", "Graffiti", "object", "GraffitiErrorUnauthorized", "_GraffitiErrorUnauthorized", "message", "GraffitiErrorForbidden", "_GraffitiErrorForbidden", "GraffitiErrorNotFound", "_GraffitiErrorNotFound", "GraffitiErrorInvalidSchema", "_GraffitiErrorInvalidSchema", "GraffitiErrorSchemaMismatch", "_GraffitiErrorSchemaMismatch", "GraffitiErrorPatchTestFailed", "_GraffitiErrorPatchTestFailed", "GraffitiErrorPatchError", "_GraffitiErrorPatchError", "GraffitiErrorInvalidUri", "_GraffitiErrorInvalidUri"]
 }

package/dist/index.mjs

@@ -1,2 +1,2 @@
-var r=class{objectToUri(t){return this.locationToUri(t)}};var s=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorUnauthorized",Object.setPrototypeOf(this,e.prototype)}},i=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorForbidden",Object.setPrototypeOf(this,e.prototype)}},a=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorNotFound",Object.setPrototypeOf(this,e.prototype)}},o=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidSchema",Object.setPrototypeOf(this,e.prototype)}},c=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorSchemaMismatch",Object.setPrototypeOf(this,e.prototype)}},n=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchTestFailed",Object.setPrototypeOf(this,e.prototype)}},f=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchError",Object.setPrototypeOf(this,e.prototype)}},m=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidUri",Object.setPrototypeOf(this,e.prototype)}};export{r as Graffiti,i as GraffitiErrorForbidden,o as GraffitiErrorInvalidSchema,m as GraffitiErrorInvalidUri,a as GraffitiErrorNotFound,f as GraffitiErrorPatchError,n as GraffitiErrorPatchTestFailed,c as GraffitiErrorSchemaMismatch,s as GraffitiErrorUnauthorized};
+var r=class{objectToUri(t){return this.locationToUri(t)}};var s=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorUnauthorized",Object.setPrototypeOf(this,e.prototype)}},o=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorForbidden",Object.setPrototypeOf(this,e.prototype)}},i=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorNotFound",Object.setPrototypeOf(this,e.prototype)}},a=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidSchema",Object.setPrototypeOf(this,e.prototype)}},c=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorSchemaMismatch",Object.setPrototypeOf(this,e.prototype)}},n=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchTestFailed",Object.setPrototypeOf(this,e.prototype)}},f=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorPatchError",Object.setPrototypeOf(this,e.prototype)}},p=class e extends Error{constructor(t){super(t),this.name="GraffitiErrorInvalidUri",Object.setPrototypeOf(this,e.prototype)}};export{r as Graffiti,o as GraffitiErrorForbidden,a as GraffitiErrorInvalidSchema,p as GraffitiErrorInvalidUri,i as GraffitiErrorNotFound,f as GraffitiErrorPatchError,n as GraffitiErrorPatchTestFailed,c as GraffitiErrorSchemaMismatch,s as GraffitiErrorUnauthorized};
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/1-api.ts", "../src/3-errors.ts"],
-  "sourcesContent": ["import type {\n  GraffitiLocation,\n  GraffitiObject,\n  GraffitiObjectBase,\n  GraffitiPatch,\n  GraffitiSession,\n  GraffitiPutObject,\n  GraffitiStream,\n  ChannelStats,\n} from \"./2-types\";\nimport type { JSONSchema4 } from \"json-schema\";\n\n/**\n * This API describes a small but powerful set of methods that\n * can be used to create many different kinds of social media applications,\n * all of which can interoperate.\n * These methods should satisfy all of an application's needs for\n * the communication, storage, and access management of social data.\n * The rest of the application can be built with standard client-side\n * user interface tools to present and interact with the data \u2014\n * no server code necessary.\n * The Typescript source for this API is available at\n * [graffiti-garden/api](https://github.com/graffiti-garden/api).\n *\n * There are several different implementations of this Graffiti API available,\n * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),\n * that lets users choose where their data is stored,\n * and a [local implementation](https://github.com/graffiti-garden/implementation-local)\n * that can be used for testing and development. In our design of Graffiti, this API is our\n * primary focus as it is the layer that shapes the experience\n * of developing applications. While different implementations can provide tradeoffs between\n * other important properties (e.g. privacy, security, scalability), those properties\n * are useless if the system as a whole doesn't expose useful functionality to developers.\n *\n * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)\n * that wraps around this API to provide reactivity. Other high-level libraries\n * will be available in the future.\n *\n * ## Overview\n *\n * Graffiti provides applications with methods to create and store data\n * on behalf of their users using standard CRUD operations:\n *  {@link put}, {@link get}, {@link patch}, and {@link delete}.\n * This data can represent both social artifacts (e.g. posts, profiles) and\n * activities (e.g. likes, follows) and is stored as JSON.\n *\n * The social aspect of Graffiti comes from the {@link discover} method\n * which allows applications to find objects that other users made.\n * It is a lot like a traditional query operation, but it only\n * returns objects that have been placed in particular\n * {@link GraffitiObjectBase.channels | `channels`}\n * specified by the discovering application.\n *\n * Graffiti builds on well known concepts and standards wherever possible.\n * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches\n * can be applied with [JSON Patch](https://jsonpatch.com).\n * For interoperability between Graffiti applications, we recommend that\n * objects use established properties from the\n * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,\n * however it is always possible to create additional properties, contributing\n * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts\n * unique to Graffiti along with *interaction relativity*.\n * Channels create boundaries between public spaces and work to prevent\n * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)\n * even in a highly interoperable environment.\n * Interaction relativity means that all interactions between users are\n * actually atomic single-user operations that can be interpreted in different ways,\n * which also supports interoperability and pluralism.\n *\n * ### Channels\n *\n * {@link GraffitiObjectBase.channels | `channels`}\n * are a way for the creators of social data to express the intended audience of their\n * data. When a user creates data using the {@link put} method, they\n * can place their data in one or more channels.\n * Content consumers using the {@link discover} method will only see data\n * contained in one of the channels they specify.\n *\n * While many channels may be public, they partition\n * the public into different \"contexts\", mitigating the\n * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the \"flattening of multiple audiences.\"\n * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,\n * comment threads, topics, places (real or virtual), pieces of media, and more.\n *\n * For example, consider a comment on a post. If we place that comment in the channel\n * represented by the post's URI, then only people viewing the post will know to\n * look in that channel, giving it visibility akin to a comment on a blog post\n * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).\n * If we also place the comment in the channel represented by the commenter's URI (their\n * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile\n * will also see the comment, giving it more visibility, like a reply on Twitter.\n * If we *only* place the comment in the channel represented by the commenter's URI, then\n * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),\n * where the comment is only visible to the commenter's followers but not the audience\n * of the original post.\n *\n * The channel model differs from other models of communication such as the\n * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,\n * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)\n * used by the AT Protocol, the protocol underlying BlueSky.\n * The actor model is a fusion of direct messaging (like Email) and broadcasting\n * (like RSS) and works well for follow-based communication but struggles\n * to pass information via other rendez-vous.\n * In the actor model, even something as simple as comments can be\n * [very tricky and require server \"side effects\"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).\n * The firehose model dumps all user data into one public database,\n * which doesn't allow for the carving out of different contexts that we did in our comment\n * example above. In the firehose model a comment will always be visible to *both* the original post's audience and\n * the commenter's followers.\n *\n * In some sense, channels provide a sort of \"social access control\" by forming\n * expectations about the audiences of different online spaces.\n * As a real world analogy, oftentimes support groups, such as alcoholics\n * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details\n * because they have expectations about the other people attending.\n * If someone malicious went to support groups just to spread people's secrets,\n * they would be shamed for violating these norms.\n * Similarly, in Graffiti, while you could spider public channels like a search engine\n * to find content about a person, revealing that you've done such a thing\n * would be shameful.\n *\n * Still, social access control is not perfect and so in situations where privacy is important,\n * objects can also be given\n * an {@link GraffitiObjectBase.allowed | `allowed`} list.\n * For example, to send someone a direct message you should put an object representing\n * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),\n * so they can find it, *and* set the `allowed` field to only include the recipient,\n * so only they can read it.\n *\n * ### Interaction relativity\n *\n * Interaction relativity posits that \"interaction between two individuals only\n * exists relative to an observer,\" or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).\n * For example, if one user creates a post and another user wants to \"like\" that post,\n * their like is not modifying the original post, it is simply another data object that points\n * to the post being liked, via its {@link locationToUri | URI}.\n *\n * ```json\n * {\n *   activity: 'like',\n *   target: 'uri-of-the-post-i-like',\n *   actor: 'my-user-id'\n * }\n * ```\n *\n * In Graffiti, all interactions including *moderation* and *collaboration* are relative.\n * This means that applications can freely choose which interactions\n * they want to express to their users and how.\n * For example, one application could have a single fixed moderator,\n * another could allow users to choose which moderators they would like filter their content\n * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),\n * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).\n * Each of these applications is one interpretation of the underlying refieid user interactions and\n * users can freely switch between them.\n *\n * Interaction relativy also allows applications to introduce new sorts of interactions\n * without having to coordinate with all the other existing applications,\n * keeping the ecosystem flexible and interoperable.\n * For example, an application could [add a \"Trust\" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)\n * and use it assess the truthfulness of posts made on applications across Graffiti.\n * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem\n * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * Interactivy relativity is realized in Graffiti through two design decisions:\n * 1. The creators of objects can only modify their own objects. It is important for\n *    users to be able to change and delete their own content to respect their\n *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),\n *    but beyond self-correction and self-censorship all other interaction is reified.\n *    Many interactions can be reified via pointers, as in the \"like\" example above, and collaborative\n *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).\n * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),\n *    anyone can post to any channel, so long as they know the URI of that channel.\n *    It is up to applications to hide content from channels either according to manual\n *    filters or in response to user action.\n *    For example, a user may create a post with the flag `disableReplies`.\n *    Applications could then filter out any content from the replies channel\n *    that the original poster has not specifically approved.\n *\n * ## Implementing the API\n *\n * To implement the API, first install it:\n *\n * ```bash\n * npm install @graffiti-garden/api\n * ```\n *\n * Then create a class that extends the `Graffiti` class and implement the abstract methods.\n *\n * ```typescript\n * import { Graffiti } from \"@graffiti-garden/api\";\n *\n * class MyGraffitiImplementation extends Graffiti {\n *   // Implement the abstract methods here\n * }\n * ```\n * ### Testing\n *\n * We have written a number of unit tests written with [vitest](https://vitest.dev/)\n * that can be used to verify implementations of the API.\n * To use them, create a test file in that ends in `*.spec.ts` and format it as follows:\n *\n * ```typescript\n * import { graffitiCRUDTests } from \"@graffiti-garden/api/tests\";\n *\n * const useGraffiti = () => new MyGraffitiImplementation();\n * // Fill in with implementation-specific information\n * // to provide to valid actor sessions for the tests\n * // to use as identities.\n * const useSession1 = () => ({ actor: \"someone\" });\n * const useSession2 = () => ({ actor: \"someoneelse\" });\n *\n * // Run the tests\n * graffitiCRUDTests(useGraffiti, useSession1, useSession2);\n * ```\n *\n * Then run the tests in the root of your directory with:\n *\n * ```bash\n * npx vitest\n * ```\n *\n * ## Building the Documentation\n *\n * To build the [TypeDoc](https://typedoc.org/) documentation, run the following commands:\n *\n * ```bash\n * npm run install\n * npm run docs\n * ```\n *\n * Then run a local server to view the documentation:\n *\n * ```bash\n * cd docs\n * npx http-server\n * ```\n *\n * ## TODO\n *\n * - Implement scope.\n *\n * @groupDescription CRUD Methods\n * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},\n * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.\n * @groupDescription Query Methods\n * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.\n * @groupDescription Session Management\n * Methods and properties for logging in and out of a Graffiti implementation.\n * @groupDescription Utilities\n * Methods for for converting Graffiti objects to and from URIs.\n */\nexport abstract class Graffiti {\n  /**\n   * Converts a {@link GraffitiLocation} object containing a\n   * {@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`} into a globally unique URI.\n   * The form of this URI is implementation dependent.\n   *\n   * Its exact inverse is {@link uriToLocation}.\n   *\n   * @group Utilities\n   */\n  abstract locationToUri(location: GraffitiLocation): string;\n\n  /**\n   * Parses a globally unique Graffiti URI into a {@link GraffitiLocation}\n   * object containing a {@link GraffitiObjectBase.name | `name`},\n   * {@link GraffitiObjectBase.actor | `actor`}, and {@link GraffitiObjectBase.source | `source`}.\n   *\n   * Its exact inverse is {@link locationToUri}.\n   *\n   * @group Utilities\n   */\n  abstract uriToLocation(uri: string): GraffitiLocation;\n\n  /**\n   * An alias of {@link locationToUri}\n   *\n   * @group Utilities\n   */\n  objectToUri(object: GraffitiObjectBase) {\n    return this.locationToUri(object);\n  }\n\n  /**\n   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.\n   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}\n   * that created it.\n   *\n   * Replacement occurs when the {@link GraffitiLocation} properties of the supplied object\n   * ({@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`}) exactly match the location of an existing object.\n   *\n   * @returns The object that was replaced if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} if this method\n   * created a new object.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of replacement/creation.\n   *\n   * @group CRUD Methods\n   */\n  abstract put<Schema>(\n    /**\n     * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided\n     * as the generic type parameter. We highly recommend providing a schema to\n     * ensure that the PUT object matches subsequent {@link get} or {@link discover}\n     * methods.\n     */\n    object: GraffitiPutObject<Schema>,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Retrieves an object from a given location.\n   *\n   * The retrieved object is type-checked against the provided [JSON schema](https://json-schema.org/)\n   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.\n   *\n   * If the object existed but has since been deleted,\n   * or the retrieving {@link GraffitiObjectBase.actor | `actor`}\n   * was {@link GraffitiObjectBase.allowed | `allowed`} to access\n   * the object but now isn't, this method will return the latest\n   * version of the object that the {@link GraffitiObjectBase.actor | `actor`}\n   * was allowed to access with its {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * set to `true`, so long as that version is still cached.\n   *\n   * Otherwise, if the object never existed, or the\n   * retrieving {@link GraffitiObjectBase.actor | `actor`} was never\n   * {@link GraffitiObjectBase.allowed | `allowed`} to access it, or if\n   * the object was changed long enough ago that its history has been\n   * purged from the cache, a {@link GraffitiErrorNotFound} is thrown.\n   * The rate at which the cache is purged is implementation dependent.\n   * See the `tombstoneReturn` property returned by {@link discover}.\n   *\n   * @group CRUD Methods\n   */\n  abstract get<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): Promise<GraffitiObject<Schema>>;\n\n  /**\n   * Patches an existing object at a given location.\n   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract patch(\n    /**\n     * A collection of [JSON Patch](https://jsonpatch.com) operations\n     * to apply to the object. See {@link GraffitiPatch} for more information.\n     */\n    patch: GraffitiPatch,\n    /**\n     * The location of the object to patch.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Deletes an object from a given location.\n   * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * If the object does not exist or has already been deleted,\n   * {@link GraffitiErrorNotFound} is thrown.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract delete(\n    /**\n     * The location of the object to delete.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Discovers objects created by any user that are contained\n   * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   *\n   * Objects are returned asynchronously as they are discovered but the stream\n   * will end once all leads have been exhausted.\n   * The method must be polled again for new objects.\n   *\n   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}\n   * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.\n   * If the actor is not the creator of a discovered object,\n   * the allowed list will be masked to only contain the querying actor if the\n   * allowed list is not `undefined` (public). Additionally, if the actor is not the\n   * creator of a discovered object, any {@link GraffitiObjectBase.channels | `channels`}\n   * not specified by the `discover` method will not be revealed. This masking happens\n   * before the supplied schema is applied.\n   *\n   * {@link discover} can be used in conjunction with {@link synchronizeDiscover}\n   * to provide a responsive and consistent user experience.\n   *\n   * Since different implementations may fetch data from multiple sources there is\n   * no guarentee on the order that objects are returned in. Additionally, the method\n   * will return objects that have been deleted but with a\n   * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for\n   * cache invalidation purposes.\n   * The final `return()` value of the stream includes a `tombstoneRetention`\n   * property that represents the minimum amount of time,\n   * in milliseconds, that an application will retain and return tombstones for objects that\n   * have been deleted.\n   *\n   * When repolling, the {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field can be queried via the schema to\n   * only fetch objects that have been modified since the last poll.\n   * Such queries should only be done if the time since the last poll\n   * is less than the `tombstoneRetention` value of that poll, otherwise the tombstones\n   * for objects that have been deleted may not be returned.\n   *\n   * ```json\n   * {\n   *   \"properties\": {\n   *     \"lastModified\": {\n   *       \"minimum\": LAST_RETRIEVED_TIME\n   *     }\n   *   }\n   * }\n   * ```\n   *\n   * `discover` needs to be polled for new data because live updates to\n   * an application can be visually distracting or lead to toxic engagement.\n   * If and when an application wants real-time updates, such as in a chat\n   * application, application authors must be intentional about their polling.\n   *\n   * Implementers should be aware that some users may applications may try to poll\n   * {@link discover} repetitively. You can deal with this by rate limiting or\n   * preemptively fetching data via a bidirectional channel, like a WebSocket.\n   * Additionally, implementers should probably index the `lastModified` field\n   * to speed up responses to schemas like the one above.\n   *\n   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}\n   * and [JSON Schema](https://json-schema.org).\n   *\n   * @group Query Methods\n   */\n  abstract discover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Discovers objects **not** contained in any\n   * {@link GraffitiObjectBase.channels | `channels`}\n   * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   * Unlike {@link discover}, this method will not return objects created by other users.\n   *\n   * This method is not useful for most applications, but necessary for\n   * getting a global view of all a user's Graffiti data or debugging\n   * channel usage.\n   *\n   * It's return value is the same as {@link discover}.\n   *\n   * @group Query Methods\n   */\n  abstract recoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}\n   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   * This is not very useful for most applications, but\n   * necessary for certain applications where a user wants a\n   * global view of all their Graffiti data or to debug\n   * channel usage.\n   *\n   * @group Query Methods\n   *\n   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}\n   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   */\n  abstract channelStats(\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<ChannelStats>;\n\n  /**\n   * Begins the login process. Depending on the implementation, this may\n   * involve redirecting the user to a login page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * The {@link GraffitiSession | session} object is returned\n   * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLoginEvent} with event type `login`.\n   *\n   * @group Session Management\n   */\n  abstract login(\n    /**\n     * Suggestions for the permissions that the\n     * login process should grant. The login process may not\n     * provide the exact proposed permissions.\n     */\n    proposal?: {\n      /**\n       * A suggested actor to login as. For example, if a user tries to\n       * edit a post but are not logged in, the interface can infer that\n       * they might want to log in as the actor who created the post\n       * they are attempting to edit.\n       *\n       * Even if provided, the implementation should allow the user\n       * to log in as a different actor if they choose.\n       */\n      actor?: string;\n      /**\n       * A yet to be defined permissions scope. An application may use\n       * this to indicate the minimum necessary scope needed to\n       * operate. For example, it may need to be able read private\n       * messages from a certain set of channels, or write messages that\n       * follow a particular schema.\n       *\n       * The login process should make it clear what scope an application\n       * is requesting and allow the user to enhance or reduce that\n       * scope as necessary.\n       */\n      scope?: {};\n    },\n  ): Promise<void>;\n\n  /**\n   * Begins the logout process. Depending on the implementation, this may\n   * involve redirecting the user to a logout page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * A confirmation will be returned asynchronously via\n   * {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLogoutEvent} as event type `logout`.\n   *\n   * @group Session Management\n   */\n  abstract logout(\n    /**\n     * The {@link GraffitiSession | session} object to logout.\n     */\n    session: GraffitiSession,\n  ): Promise<void>;\n\n  /**\n   * An event target that can be used to listen for the following\n   * events and they're corresponding event types:\n   * - `login` - {@link GraffitiLoginEvent}\n   * - `logout` - {@link GraffitiLogoutEvent}\n   * - `initialized` - {@link GraffitiSessionInitializedEvent}\n   *\n   * @group Session Management\n   */\n  abstract readonly sessionEvents: EventTarget;\n\n  /**\n   * This method has the same signature as {@link discover} but listens for\n   * changes made via {@link put}, {@link patch}, and {@link delete} or\n   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans}\n   * and then streams appropriate changes to provide a responsive and\n   * consistent user experience.\n   *\n   * Unlike {@link discover}, this method continuously listens for changes\n   * and will not terminate unless the user calls the `return` method on the iterator\n   * or `break`s out of the loop.\n   *\n   * Example 1: Suppose a user publishes a post using {@link put}. If the feed\n   * displaying that user's posts is using {@link synchronizeDiscover} to listen for changes,\n   * then the user's new post will instantly appear in their feed, giving the UI a\n   * responsive feel.\n   *\n   * Example 2: Suppose one of a user's friends changes their name. As soon as the\n   * user's application receives one notice of that change (using {@link get}\n   * or {@link discover}), then {@link synchronizeDiscover} listeners can be used to update\n   * all instance's of that friend's name in the user's application instantly,\n   * providing a consistent user experience.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeDiscover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that the objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n\n  /**\n   * This method has the same signature as {@link get} but, like {@link synchronizeDiscover},\n   * it listens for changes made via {@link put}, {@link patch}, and {@link delete} or\n   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then\n   * streams appropriate changes to provide a responsive and consistent user experience.\n   *\n   * Unlike {@link get}, which returns a single result, this method continuously\n   * listens for changes which are output as an asynchronous {@link GraffitiStream}.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeGet<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n\n  /**\n   * This method has the same signature as {@link recoverOrphans} but,\n   * like {@link synchronizeDiscover}, it listens for changes made via\n   * {@link put}, {@link patch}, and {@link delete} or fetched from\n   * {@link get}, {@link discover}, and {@link recoverOrphans} and then\n   * streams appropriate changes to provide a responsive and consistent user experience.\n   *\n   * Unlike {@link recoverOrphans}, this method continuously listens for changes\n   * and will not terminate unless the user calls the `return` method on the iterator\n   * or `break`s out of the loop.\n   *\n   * @group Synchronize Methods\n   */\n  abstract synchronizeRecoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<GraffitiObject<Schema>>;\n}\n\n/**\n * This is a factory function that produces an instance of\n * the {@link Graffiti} class. Since the Graffiti class is\n * abstract, factory functions provide an easy way to\n * swap out different implementations.\n */\nexport type GraffitiFactory = () => Graffiti;\n", "export class GraffitiErrorUnauthorized extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorUnauthorized\";\n    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);\n  }\n}\n\nexport class GraffitiErrorForbidden extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorForbidden\";\n    Object.setPrototypeOf(this, GraffitiErrorForbidden.prototype);\n  }\n}\n\nexport class GraffitiErrorNotFound extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorNotFound\";\n    Object.setPrototypeOf(this, GraffitiErrorNotFound.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidSchema extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidSchema\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidSchema.prototype);\n  }\n}\n\nexport class GraffitiErrorSchemaMismatch extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorSchemaMismatch\";\n    Object.setPrototypeOf(this, GraffitiErrorSchemaMismatch.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchTestFailed extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchTestFailed\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchError extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchError\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidUri extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidUri\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);\n  }\n}\n"],
-  "mappings": "AA6PO,IAAeA,EAAf,KAAwB,CA6B7B,YAAYC,EAA4B,CACtC,OAAO,KAAK,cAAcA,CAAM,CAClC,CA0bF,ECttBO,IAAMC,EAAN,MAAMC,UAAkC,KAAM,CACnD,YAAYC,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,4BACZ,OAAO,eAAe,KAAMD,EAA0B,SAAS,CACjE,CACF,EAEaE,EAAN,MAAMC,UAA+B,KAAM,CAChD,YAAYF,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,yBACZ,OAAO,eAAe,KAAME,EAAuB,SAAS,CAC9D,CACF,EAEaC,EAAN,MAAMC,UAA8B,KAAM,CAC/C,YAAYJ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,wBACZ,OAAO,eAAe,KAAMI,EAAsB,SAAS,CAC7D,CACF,EAEaC,EAAN,MAAMC,UAAmC,KAAM,CACpD,YAAYN,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,6BACZ,OAAO,eAAe,KAAMM,EAA2B,SAAS,CAClE,CACF,EAEaC,EAAN,MAAMC,UAAoC,KAAM,CACrD,YAAYR,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,8BACZ,OAAO,eAAe,KAAMQ,EAA4B,SAAS,CACnE,CACF,EAEaC,EAAN,MAAMC,UAAqC,KAAM,CACtD,YAAYV,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,+BACZ,OAAO,eAAe,KAAMU,EAA6B,SAAS,CACpE,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYZ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMY,EAAwB,SAAS,CAC/D,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYd,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMc,EAAwB,SAAS,CAC/D,CACF",
+  "sourcesContent": ["import type {\n  GraffitiLocation,\n  GraffitiObject,\n  GraffitiObjectBase,\n  GraffitiPatch,\n  GraffitiSession,\n  GraffitiPutObject,\n  GraffitiStream,\n  ChannelStats,\n} from \"./2-types\";\nimport type { JSONSchema4 } from \"json-schema\";\n\n/**\n * This API describes a small but powerful set of methods that\n * can be used to create many different kinds of social media applications,\n * all of which can interoperate.\n * These methods should satisfy all of an application's needs for\n * the communication, storage, and access management of social data.\n * The rest of the application can be built with standard client-side\n * user interface tools to present and interact with the data \u2014\n * no server code necessary.\n * The Typescript source for this API is available at\n * [graffiti-garden/api](https://github.com/graffiti-garden/api).\n *\n * There are several different implementations of this Graffiti API available,\n * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),\n * that lets users choose where their data is stored,\n * and a [local implementation](https://github.com/graffiti-garden/implementation-local)\n * that can be used for testing and development. In our design of Graffiti, this API is our\n * primary focus as it is the layer that shapes the experience\n * of developing applications. While different implementations can provide tradeoffs between\n * other important properties (e.g. privacy, security, scalability), those properties\n * are useless if the system as a whole doesn't expose useful functionality to developers.\n *\n * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)\n * that wraps around this API to provide reactivity. Other high-level libraries\n * will be available in the future.\n *\n * ## Overview\n *\n * Graffiti provides applications with methods to create and store data\n * on behalf of their users using standard CRUD operations:\n *  {@link put}, {@link get}, {@link patch}, and {@link delete}.\n * This data can represent both social artifacts (e.g. posts, profiles) and\n * activities (e.g. likes, follows) and is stored as JSON.\n *\n * The social aspect of Graffiti comes from the {@link discover} method\n * which allows applications to find objects that other users made.\n * It is a lot like a traditional query operation, but it only\n * returns objects that have been placed in particular\n * {@link GraffitiObjectBase.channels | `channels`}\n * specified by the discovering application.\n *\n * Graffiti builds on well known concepts and standards wherever possible.\n * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches\n * can be applied with [JSON Patch](https://jsonpatch.com).\n * For interoperability between Graffiti applications, we recommend that\n * objects use established properties from the\n * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,\n * however it is always possible to create additional properties, contributing\n * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts\n * unique to Graffiti along with *interaction relativity*, defined below.\n * Channels create boundaries between public spaces and work to prevent\n * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)\n * even in a highly interoperable environment.\n * Interaction relativity means that all interactions between users are\n * actually atomic single-user operations that can be interpreted in different ways,\n * which also supports interoperability and pluralism.\n *\n * ### Channels\n *\n * {@link GraffitiObjectBase.channels | `channels`}\n * are a way for the creators of social data to express the intended audience of their\n * data. When a user creates data using the {@link put} method, they\n * can place their data in one or more channels.\n * Content consumers using the {@link discover} method will only see data\n * contained in one of the channels they specify.\n *\n * While many channels may be public, they partition\n * the public into different \"contexts\", mitigating the\n * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the \"flattening of multiple audiences.\"\n * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,\n * comment threads, topics, places (real or virtual), pieces of media, and more.\n *\n * For example, consider a comment on a post. If we place that comment in the channel\n * represented by the post's URI, then only people viewing the post will know to\n * look in that channel, giving it visibility akin to a comment on a blog post\n * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).\n * If we also place the comment in the channel represented by the commenter's URI (their\n * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile\n * will also see the comment, giving it more visibility, like a reply on Twitter.\n * If we *only* place the comment in the channel represented by the commenter's URI, then\n * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),\n * where the comment is only visible to the commenter's followers but not the audience\n * of the original post.\n *\n * The channel model differs from other models of communication such as the\n * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,\n * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)\n * used by the AT Protocol, the protocol underlying BlueSky.\n * The actor model is a fusion of direct messaging (like Email) and broadcasting\n * (like RSS) and works well for follow-based communication but struggles\n * to pass information via other rendez-vous.\n * In the actor model, even something as simple as comments can be\n * [very tricky and require server \"side effects\"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).\n * The firehose model dumps all user data into one public database,\n * which doesn't allow for the carving out of different contexts that we did in our comment\n * example above. In the firehose model a comment will always be visible to *both* the original post's audience and\n * the commenter's followers.\n *\n * In some sense, channels provide a sort of \"social access control\" by forming\n * expectations about the audiences of different online spaces.\n * As a real world analogy, oftentimes support groups, such as alcoholics\n * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details\n * because they have expectations about the other people attending.\n * If someone malicious went to support groups just to spread people's secrets,\n * they would be shamed for violating these norms.\n * Similarly, in Graffiti, while you could spider public channels like a search engine\n * to find content about a person, revealing that you've done such a thing\n * would be shameful.\n *\n * Still, social access control is not perfect and so in situations where privacy is important,\n * objects can also be given\n * an {@link GraffitiObjectBase.allowed | `allowed`} list.\n * For example, to send someone a direct message you should put an object representing\n * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),\n * so they can find it, *and* set the `allowed` field to only include the recipient,\n * so only they can read it.\n *\n * ### Interaction relativity\n *\n * Interaction relativity posits that \"interaction between two individuals only\n * exists relative to an observer,\" or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).\n * For example, if one user creates a post and another user wants to \"like\" that post,\n * their like is not modifying the original post, it is simply another data object that points\n * to the post being liked, via its {@link locationToUri | URI}.\n *\n * ```json\n * {\n *   activity: 'like',\n *   target: 'uri-of-the-post-i-like',\n *   actor: 'my-user-id'\n * }\n * ```\n *\n * In Graffiti, all interactions including *moderation* and *collaboration* are relative.\n * This means that applications can freely choose which interactions\n * they want to express to their users and how.\n * For example, one application could have a single fixed moderator,\n * another could allow users to choose which moderators they would like filter their content\n * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),\n * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).\n * Each of these applications is one interpretation of the underlying refieid user interactions and\n * users can freely switch between them.\n *\n * Interaction relativy also allows applications to introduce new sorts of interactions\n * without having to coordinate with all the other existing applications,\n * keeping the ecosystem flexible and interoperable.\n * For example, an application could [add a \"Trust\" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)\n * and use it assess the truthfulness of posts made on applications across Graffiti.\n * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem\n * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).\n *\n * Interactivy relativity is realized in Graffiti through two design decisions:\n * 1. The creators of objects can only modify their own objects. It is important for\n *    users to be able to change and delete their own content to respect their\n *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),\n *    but beyond self-correction and self-censorship all other interaction is reified.\n *    Many interactions can be reified via pointers, as in the \"like\" example above, and collaborative\n *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).\n * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),\n *    anyone can post to any channel, so long as they know the URI of that channel.\n *    It is up to applications to hide content from channels either according to manual\n *    filters or in response to user action.\n *    For example, a user may create a post with the flag `disableReplies`.\n *    Applications could then filter out any content from the replies channel\n *    that the original poster has not specifically approved.\n *\n * @groupDescription CRUD Methods\n * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},\n * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.\n * @groupDescription Query Methods\n * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.\n * @groupDescription Session Management\n * Methods and properties for logging in and out of a Graffiti implementation.\n * @groupDescription Utilities\n * Methods for for converting Graffiti objects to and from URIs.\n */\nexport abstract class Graffiti {\n  /**\n   * Converts a {@link GraffitiLocation} object containing a\n   * {@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`} into a globally unique URI.\n   * The form of this URI is implementation dependent.\n   *\n   * Its exact inverse is {@link uriToLocation}.\n   *\n   * @group Utilities\n   */\n  abstract locationToUri(location: GraffitiLocation): string;\n\n  /**\n   * Parses a globally unique Graffiti URI into a {@link GraffitiLocation}\n   * object containing a {@link GraffitiObjectBase.name | `name`},\n   * {@link GraffitiObjectBase.actor | `actor`}, and {@link GraffitiObjectBase.source | `source`}.\n   *\n   * Its exact inverse is {@link locationToUri}.\n   *\n   * @group Utilities\n   */\n  abstract uriToLocation(uri: string): GraffitiLocation;\n\n  /**\n   * An alias of {@link locationToUri}\n   *\n   * @group Utilities\n   */\n  objectToUri(object: GraffitiObjectBase) {\n    return this.locationToUri(object);\n  }\n\n  /**\n   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.\n   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}\n   * that created it.\n   *\n   * Replacement occurs when the {@link GraffitiLocation} properties of the supplied object\n   * ({@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},\n   * and {@link GraffitiObjectBase.source | `source`}) exactly match the location of an existing object.\n   *\n   * @returns The object that was replaced if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} if this method\n   * created a new object.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of replacement/creation.\n   *\n   * @group CRUD Methods\n   */\n  abstract put<Schema>(\n    /**\n     * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided\n     * as the generic type parameter. We highly recommend providing a schema to\n     * ensure that the PUT object matches subsequent {@link get} or {@link discover}\n     * methods.\n     */\n    object: GraffitiPutObject<Schema>,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Retrieves an object from a given location.\n   *\n   * The retrieved object is type-checked against the provided [JSON schema](https://json-schema.org/)\n   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.\n   *\n   * If the object existed but has since been deleted,\n   * or the retrieving {@link GraffitiObjectBase.actor | `actor`}\n   * was {@link GraffitiObjectBase.allowed | `allowed`} to access\n   * the object but now isn't, this method will return the latest\n   * version of the object that the {@link GraffitiObjectBase.actor | `actor`}\n   * was allowed to access with its {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * set to `true`, so long as that version is still cached.\n   *\n   * Otherwise, if the object never existed, or the\n   * retrieving {@link GraffitiObjectBase.actor | `actor`} was never\n   * {@link GraffitiObjectBase.allowed | `allowed`} to access it, or if\n   * the object was changed long enough ago that its history has been\n   * purged from the cache, a {@link GraffitiErrorNotFound} is thrown.\n   * The rate at which the cache is purged is implementation dependent.\n   * See the `tombstoneReturn` property returned by {@link discover}.\n   *\n   * @group CRUD Methods\n   */\n  abstract get<Schema extends JSONSchema4>(\n    /**\n     * The location of the object to get.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * The JSON schema to validate the retrieved object against.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}\n     * property must be `undefined`.\n     */\n    session?: GraffitiSession | null,\n  ): Promise<GraffitiObject<Schema>>;\n\n  /**\n   * Patches an existing object at a given location.\n   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract patch(\n    /**\n     * A collection of [JSON Patch](https://jsonpatch.com) operations\n     * to apply to the object. See {@link GraffitiPatch} for more information.\n     */\n    patch: GraffitiPatch,\n    /**\n     * The location of the object to patch.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Deletes an object from a given location.\n   * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the\n   * `actor` that created the object.\n   *\n   * If the object does not exist or has already been deleted,\n   * {@link GraffitiErrorNotFound} is thrown.\n   *\n   * @returns The object that was deleted if one exists or an object with\n   * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.\n   * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}\n   * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field updated to the time of deletion.\n   *\n   * @group CRUD Methods\n   */\n  abstract delete(\n    /**\n     * The location of the object to delete.\n     */\n    locationOrUri: GraffitiLocation | string,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): Promise<GraffitiObjectBase>;\n\n  /**\n   * Discovers objects created by any user that are contained\n   * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   *\n   * Objects are returned asynchronously as they are discovered but the stream\n   * will end once all leads have been exhausted.\n   * The method must be polled again for new objects.\n   *\n   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}\n   * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.\n   * If the actor is not the creator of a discovered object,\n   * the allowed list will be masked to only contain the querying actor if the\n   * allowed list is not `undefined` (public). Additionally, if the actor is not the\n   * creator of a discovered object, any {@link GraffitiObjectBase.channels | `channels`}\n   * not specified by the `discover` method will not be revealed. This masking happens\n   * before the supplied schema is applied.\n   *\n   * Since different implementations may fetch data from multiple sources there is\n   * no guarentee on the order that objects are returned in. Additionally, the method\n   * will return objects that have been deleted but with a\n   * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for\n   * cache invalidation purposes.\n   * The final `return()` value of the stream includes a `tombstoneRetention`\n   * property that represents the minimum amount of time,\n   * in milliseconds, that an application will retain and return tombstones for objects that\n   * have been deleted.\n   *\n   * When repolling, the {@link GraffitiObjectBase.lastModified | `lastModified`}\n   * field can be queried via the schema to\n   * only fetch objects that have been modified since the last poll.\n   * Such queries should only be done if the time since the last poll\n   * is less than the `tombstoneRetention` value of that poll, otherwise the tombstones\n   * for objects that have been deleted may not be returned.\n   *\n   * ```json\n   * {\n   *   \"properties\": {\n   *     \"lastModified\": {\n   *       \"minimum\": LAST_RETRIEVED_TIME\n   *     }\n   *   }\n   * }\n   * ```\n   *\n   * `discover` needs to be polled for new data because live updates to\n   * an application can be visually distracting or lead to toxic engagement.\n   * If and when an application wants real-time updates, such as in a chat\n   * application, application authors must be intentional about their polling.\n   *\n   * Implementers should be aware that some users may applications may try to poll\n   * {@link discover} repetitively. You can deal with this by rate limiting or\n   * preemptively fetching data via a bidirectional channel, like a WebSocket.\n   * Additionally, implementers should probably index the `lastModified` field\n   * to speed up responses to schemas like the one above.\n   *\n   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}\n   * and [JSON Schema](https://json-schema.org).\n   *\n   * @group Query Methods\n   */\n  abstract discover<Schema extends JSONSchema4>(\n    /**\n     * The {@link GraffitiObjectBase.channels | `channels`} that objects must be associated with.\n     */\n    channels: string[],\n    /**\n     * A [JSON Schema](https://json-schema.org) that objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,\n     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}\n     * property will be returned.\n     */\n    session?: GraffitiSession | null,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Discovers objects **not** contained in any\n   * {@link GraffitiObjectBase.channels | `channels`}\n   * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}\n   * and match the given [JSON Schema](https://json-schema.org).\n   * Unlike {@link discover}, this method will not return objects created by other users.\n   *\n   * This method is not useful for most applications, but necessary for\n   * getting a global view of all a user's Graffiti data or debugging\n   * channel usage.\n   *\n   * It's return value is the same as {@link discover}.\n   *\n   * @group Query Methods\n   */\n  abstract recoverOrphans<Schema extends JSONSchema4>(\n    /**\n     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.\n     */\n    schema: Schema,\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<\n    GraffitiObject<Schema>,\n    {\n      tombstoneRetention: number;\n    }\n  >;\n\n  /**\n   * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}\n   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   * This is not very useful for most applications, but\n   * necessary for certain applications where a user wants a\n   * global view of all their Graffiti data or to debug\n   * channel usage.\n   *\n   * @group Query Methods\n   *\n   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}\n   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.\n   */\n  abstract channelStats(\n    /**\n     * An implementation-specific object with information to authenticate the\n     * {@link GraffitiObjectBase.actor | `actor`}.\n     */\n    session: GraffitiSession,\n  ): GraffitiStream<ChannelStats>;\n\n  /**\n   * Begins the login process. Depending on the implementation, this may\n   * involve redirecting the user to a login page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * The {@link GraffitiSession | session} object is returned\n   * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLoginEvent} with event type `login`.\n   *\n   * @group Session Management\n   */\n  abstract login(\n    /**\n     * Suggestions for the permissions that the\n     * login process should grant. The login process may not\n     * provide the exact proposed permissions.\n     */\n    proposal?: {\n      /**\n       * A suggested actor to login as. For example, if a user tries to\n       * edit a post but are not logged in, the interface can infer that\n       * they might want to log in as the actor who created the post\n       * they are attempting to edit.\n       *\n       * Even if provided, the implementation should allow the user\n       * to log in as a different actor if they choose.\n       */\n      actor?: string;\n      /**\n       * A yet to be defined permissions scope. An application may use\n       * this to indicate the minimum necessary scope needed to\n       * operate. For example, it may need to be able read private\n       * messages from a certain set of channels, or write messages that\n       * follow a particular schema.\n       *\n       * The login process should make it clear what scope an application\n       * is requesting and allow the user to enhance or reduce that\n       * scope as necessary.\n       */\n      scope?: {};\n    },\n  ): Promise<void>;\n\n  /**\n   * Begins the logout process. Depending on the implementation, this may\n   * involve redirecting the user to a logout page or opening a popup,\n   * so it should always be called in response to a user action.\n   *\n   * A confirmation will be returned asynchronously via\n   * {@link Graffiti.sessionEvents | sessionEvents}\n   * as a {@link GraffitiLogoutEvent} as event type `logout`.\n   *\n   * @group Session Management\n   */\n  abstract logout(\n    /**\n     * The {@link GraffitiSession | session} object to logout.\n     */\n    session: GraffitiSession,\n  ): Promise<void>;\n\n  /**\n   * An event target that can be used to listen for the following\n   * events and they're corresponding event types:\n   * - `login` - {@link GraffitiLoginEvent}\n   * - `logout` - {@link GraffitiLogoutEvent}\n   * - `initialized` - {@link GraffitiSessionInitializedEvent}\n   *\n   * @group Session Management\n   */\n  abstract readonly sessionEvents: EventTarget;\n}\n", "export class GraffitiErrorUnauthorized extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorUnauthorized\";\n    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);\n  }\n}\n\nexport class GraffitiErrorForbidden extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorForbidden\";\n    Object.setPrototypeOf(this, GraffitiErrorForbidden.prototype);\n  }\n}\n\nexport class GraffitiErrorNotFound extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorNotFound\";\n    Object.setPrototypeOf(this, GraffitiErrorNotFound.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidSchema extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidSchema\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidSchema.prototype);\n  }\n}\n\nexport class GraffitiErrorSchemaMismatch extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorSchemaMismatch\";\n    Object.setPrototypeOf(this, GraffitiErrorSchemaMismatch.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchTestFailed extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchTestFailed\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);\n  }\n}\n\nexport class GraffitiErrorPatchError extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorPatchError\";\n    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);\n  }\n}\n\nexport class GraffitiErrorInvalidUri extends Error {\n  constructor(message?: string) {\n    super(message);\n    this.name = \"GraffitiErrorInvalidUri\";\n    Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);\n  }\n}\n"],
+  "mappings": "AA8LO,IAAeA,EAAf,KAAwB,CA6B7B,YAAYC,EAA4B,CACtC,OAAO,KAAK,cAAcA,CAAM,CAClC,CAuVF,ECpjBO,IAAMC,EAAN,MAAMC,UAAkC,KAAM,CACnD,YAAYC,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,4BACZ,OAAO,eAAe,KAAMD,EAA0B,SAAS,CACjE,CACF,EAEaE,EAAN,MAAMC,UAA+B,KAAM,CAChD,YAAYF,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,yBACZ,OAAO,eAAe,KAAME,EAAuB,SAAS,CAC9D,CACF,EAEaC,EAAN,MAAMC,UAA8B,KAAM,CAC/C,YAAYJ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,wBACZ,OAAO,eAAe,KAAMI,EAAsB,SAAS,CAC7D,CACF,EAEaC,EAAN,MAAMC,UAAmC,KAAM,CACpD,YAAYN,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,6BACZ,OAAO,eAAe,KAAMM,EAA2B,SAAS,CAClE,CACF,EAEaC,EAAN,MAAMC,UAAoC,KAAM,CACrD,YAAYR,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,8BACZ,OAAO,eAAe,KAAMQ,EAA4B,SAAS,CACnE,CACF,EAEaC,EAAN,MAAMC,UAAqC,KAAM,CACtD,YAAYV,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,+BACZ,OAAO,eAAe,KAAMU,EAA6B,SAAS,CACpE,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYZ,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMY,EAAwB,SAAS,CAC/D,CACF,EAEaC,EAAN,MAAMC,UAAgC,KAAM,CACjD,YAAYd,EAAkB,CAC5B,MAAMA,CAAO,EACb,KAAK,KAAO,0BACZ,OAAO,eAAe,KAAMc,EAAwB,SAAS,CAC/D,CACF",
   "names": ["Graffiti", "object", "GraffitiErrorUnauthorized", "_GraffitiErrorUnauthorized", "message", "GraffitiErrorForbidden", "_GraffitiErrorForbidden", "GraffitiErrorNotFound", "_GraffitiErrorNotFound", "GraffitiErrorInvalidSchema", "_GraffitiErrorInvalidSchema", "GraffitiErrorSchemaMismatch", "_GraffitiErrorSchemaMismatch", "GraffitiErrorPatchTestFailed", "_GraffitiErrorPatchTestFailed", "GraffitiErrorPatchError", "_GraffitiErrorPatchError", "GraffitiErrorInvalidUri", "_GraffitiErrorInvalidUri"]
 }

package/dist/src/1-api.d.ts

@@ -51,7 +51,7 @@ import type { JSONSchema4 } from "json-schema";
  * 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*.
+ * 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.
@@ -168,69 +168,6 @@ import type { JSONSchema4 } from "json-schema";
  *    Applications could then filter out any content from the replies channel
  *    that the original poster has not specifically approved.
  *
- * ## Implementing the API
- *
- * To implement the API, first install it:
- *
- * ```bash
- * npm install @graffiti-garden/api
- * ```
- *
- * Then create a class that extends the `Graffiti` class and implement the abstract methods.
- *
- * ```typescript
- * import { Graffiti } from "@graffiti-garden/api";
- *
- * class MyGraffitiImplementation extends Graffiti {
- *   // Implement the abstract methods here
- * }
- * ```
- * ### Testing
- *
- * We have written a number of unit tests written with [vitest](https://vitest.dev/)
- * that can be used to verify implementations of the API.
- * To use them, create a test file in that ends in `*.spec.ts` and format it as follows:
- *
- * ```typescript
- * import { graffitiCRUDTests } from "@graffiti-garden/api/tests";
- *
- * const useGraffiti = () => new MyGraffitiImplementation();
- * // Fill in with implementation-specific information
- * // to provide to valid actor sessions for the tests
- * // to use as identities.
- * const useSession1 = () => ({ actor: "someone" });
- * const useSession2 = () => ({ actor: "someoneelse" });
- *
- * // Run the tests
- * graffitiCRUDTests(useGraffiti, useSession1, useSession2);
- * ```
- *
- * Then run the tests in the root of your directory with:
- *
- * ```bash
- * npx vitest
- * ```
- *
- * ## Building the Documentation
- *
- * To build the [TypeDoc](https://typedoc.org/) documentation, run the following commands:
- *
- * ```bash
- * npm run install
- * npm run docs
- * ```
- *
- * Then run a local server to view the documentation:
- *
- * ```bash
- * cd docs
- * npx http-server
- * ```
- *
- * ## TODO
- *
- * - Implement scope.
- *
  * @groupDescription CRUD Methods
  * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
  * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.
@@ -412,9 +349,6 @@ export declare abstract class Graffiti {
      * not specified by the `discover` method will not be revealed. This masking happens
      * before the supplied schema is applied.
      *
-     * {@link discover} can be used in conjunction with {@link synchronizeDiscover}
-     * to provide a responsive and consistent user experience.
-     *
      * Since different implementations may fetch data from multiple sources there is
      * no guarentee on the order that objects are returned in. Additionally, the method
      * will return objects that have been deleted but with a
@@ -589,102 +523,5 @@ export declare abstract class Graffiti {
      * @group Session Management
      */
     abstract readonly sessionEvents: EventTarget;
-    /**
-     * This method has the same signature as {@link discover} but listens for
-     * changes made via {@link put}, {@link patch}, and {@link delete} or
-     * fetched from {@link get}, {@link discover}, and {@link recoverOrphans}
-     * and then streams appropriate changes to provide a responsive and
-     * consistent user experience.
-     *
-     * Unlike {@link discover}, this method continuously listens for changes
-     * and will not terminate unless the user calls the `return` method on the iterator
-     * or `break`s out of the loop.
-     *
-     * Example 1: Suppose a user publishes a post using {@link put}. If the feed
-     * displaying that user's posts is using {@link synchronizeDiscover} to listen for changes,
-     * then the user's new post will instantly appear in their feed, giving the UI a
-     * responsive feel.
-     *
-     * Example 2: Suppose one of a user's friends changes their name. As soon as the
-     * user's application receives one notice of that change (using {@link get}
-     * or {@link discover}), then {@link synchronizeDiscover} listeners can be used to update
-     * all instance's of that friend's name in the user's application instantly,
-     * providing a consistent user experience.
-     *
-     * @group Synchronize Methods
-     */
-    abstract synchronizeDiscover<Schema extends JSONSchema4>(
-    /**
-     * The {@link GraffitiObjectBase.channels | `channels`} that the objects must be associated with.
-     */
-    channels: string[], 
-    /**
-     * A [JSON Schema](https://json-schema.org) that objects must satisfy.
-     */
-    schema: Schema, 
-    /**
-     * An implementation-specific object with information to authenticate the
-     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,
-     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}
-     * property will be returned.
-     */
-    session?: GraffitiSession | null): GraffitiStream<GraffitiObject<Schema>>;
-    /**
-     * This method has the same signature as {@link get} but, like {@link synchronizeDiscover},
-     * it listens for changes made via {@link put}, {@link patch}, and {@link delete} or
-     * fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then
-     * streams appropriate changes to provide a responsive and consistent user experience.
-     *
-     * Unlike {@link get}, which returns a single result, this method continuously
-     * listens for changes which are output as an asynchronous {@link GraffitiStream}.
-     *
-     * @group Synchronize Methods
-     */
-    abstract synchronizeGet<Schema extends JSONSchema4>(
-    /**
-     * The location of the object to get.
-     */
-    locationOrUri: GraffitiLocation | string, 
-    /**
-     * The JSON schema to validate the retrieved object against.
-     */
-    schema: Schema, 
-    /**
-     * An implementation-specific object with information to authenticate the
-     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,
-     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}
-     * property must be `undefined`.
-     */
-    session?: GraffitiSession | null): GraffitiStream<GraffitiObject<Schema>>;
-    /**
-     * This method has the same signature as {@link recoverOrphans} but,
-     * like {@link synchronizeDiscover}, it listens for changes made via
-     * {@link put}, {@link patch}, and {@link delete} or fetched from
-     * {@link get}, {@link discover}, and {@link recoverOrphans} and then
-     * streams appropriate changes to provide a responsive and consistent user experience.
-     *
-     * Unlike {@link recoverOrphans}, this method continuously listens for changes
-     * and will not terminate unless the user calls the `return` method on the iterator
-     * or `break`s out of the loop.
-     *
-     * @group Synchronize Methods
-     */
-    abstract synchronizeRecoverOrphans<Schema extends JSONSchema4>(
-    /**
-     * A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.
-     */
-    schema: Schema, 
-    /**
-     * An implementation-specific object with information to authenticate the
-     * {@link GraffitiObjectBase.actor | `actor`}.
-     */
-    session: GraffitiSession): GraffitiStream<GraffitiObject<Schema>>;
 }
-/**
- * This is a factory function that produces an instance of
- * the {@link Graffiti} class. Since the Graffiti class is
- * abstract, factory functions provide an easy way to
- * swap out different implementations.
- */
-export type GraffitiFactory = () => Graffiti;
 //# sourceMappingURL=1-api.d.ts.map