@graffiti-garden/api 0.0.9 → 0.1.1

package/README.md

@@ -1,47 +1,7 @@
 # Graffiti API
 
-The Graffiti API makes it possible to build social applications that are flexible and interoperable.
-This repository contains the abstract API and it's documentation.
+The Graffiti API makes it possible to build many different types of social applications
+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)
-
-## 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
-```
-
-## Testing
-
-We have written a number of unit tests to verify implementations of the API with [vitest](https://vitest.dev/).
-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
-```
+[**View the Documentation**](https://api.graffiti.garden/classes/Graffiti.html)

package/dist/index.cjs.js

@@ -0,0 +1,2 @@
+"use strict";class r extends Error{constructor(t){super(t),this.name="GraffitiErrorUnauthorized",Object.setPrototypeOf(this,r.prototype)}}class t extends Error{constructor(r){super(r),this.name="GraffitiErrorForbidden",Object.setPrototypeOf(this,t.prototype)}}class o extends Error{constructor(r){super(r),this.name="GraffitiErrorNotFound",Object.setPrototypeOf(this,o.prototype)}}class e extends Error{constructor(r){super(r),this.name="GraffitiErrorInvalidSchema",Object.setPrototypeOf(this,e.prototype)}}class s extends Error{constructor(r){super(r),this.name="GraffitiErrorSchemaMismatch",Object.setPrototypeOf(this,s.prototype)}}class i extends Error{constructor(r){super(r),this.name="GraffitiErrorPatchTestFailed",Object.setPrototypeOf(this,i.prototype)}}class a extends Error{constructor(r){super(r),this.name="GraffitiErrorPatchError",Object.setPrototypeOf(this,a.prototype)}}class c extends Error{constructor(r){super(r),this.name="GraffitiErrorInvalidUri",Object.setPrototypeOf(this,c.prototype)}}exports.Graffiti=class{objectToUri(r){return this.locationToUri(r)}},exports.GraffitiErrorForbidden=t,exports.GraffitiErrorInvalidSchema=e,exports.GraffitiErrorInvalidUri=c,exports.GraffitiErrorNotFound=o,exports.GraffitiErrorPatchError=a,exports.GraffitiErrorPatchTestFailed=i,exports.GraffitiErrorSchemaMismatch=s,exports.GraffitiErrorUnauthorized=r;
+//# sourceMappingURL=index.cjs.js.map

package/package.json

@@ -1,24 +1,36 @@
 {
   "name": "@graffiti-garden/api",
-  "version": "0.0.9",
+  "version": "0.1.1",
   "description": "The heart of Graffiti",
-  "type": "module",
-  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "module": "dist/index.js",
+  "main": "dist/index.cjs.js",
   "exports": {
-    ".": "./src/index.ts",
+    ".": {
+      "import": {
+        "types": "./src/index.ts",
+        "node": "./dist/index.cjs.js",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./src/index.ts",
+        "default": "./dist/index.cjs.js"
+      }
+    },
     "./tests": "./tests/index.ts"
   },
   "files": [
     "src",
     "tests",
     "package.json",
-    "tsconfig.json"
+    "README.md"
   ],
   "author": "Theia Henderson",
   "license": "GPL-3.0-or-later",
   "scripts": {
     "docs": "typedoc --options typedoc.json",
-    "prepublishOnly": "npm install"
+    "build": "rollup -c rollup.config.ts --configPlugin rollup-plugin-typescript2",
+    "prepublishOnly": "npm install && npm run build"
   },
   "repository": {
     "type": "git",
@@ -29,6 +41,9 @@
   },
   "homepage": "https://api.graffiti.garden/classes/Graffiti.html",
   "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "rollup": "^4.31.0",
+    "rollup-plugin-typescript2": "^0.36.0",
     "tslib": "^2.8.1",
     "typedoc": "^0.26.11",
     "vitest": "^2.1.8"

package/src/1-api.ts

@@ -10,50 +10,229 @@ import type {
 import type { JSONSchema4 } from "json-schema";
 
 /**
- * This API describes a small but mighty set of methods that
+ * This API describes a small but powerful set of methods that
  * can be used to create many different kinds of social media applications,
  * all of which can interoperate.
  * These methods should satisfy all of an application's needs for
  * the communication, storage, and access management of social data.
  * The rest of the application can be built with standard client-side
- * user interface tools to present and interact with the data.
+ * user interface tools to present and interact with the data —
+ * no server code necessary.
+ * The Typescript source for this API is available at
+ * [graffiti-garden/api](https://github.com/graffiti-garden/api).
  *
  * There are several different implementations of this Graffiti API available,
  * including a [decentralized implementation](https://github.com/graffiti-garden/client-core),
  * and a [local implementation](https://github.com/graffiti-garden/implementation-pouchdb)
- * that can be used for testing. In the design of Graffiti we prioritized
- * the design of this API first as it is the layer that shapes the experience
- * of developing applications. While different implementations provide tradeoffs between
+ * that can be used for testing. In our design of Graffiti, this API is our
+ * primary focus as it is the layer that shapes the experience
+ * of developing applications. While different implementations can provide tradeoffs between
  * other important properties (e.g. privacy, security, scalability), those properties
- * are useless if the system as a whole is unusable. Build APIs before protocols!
- *
- * There is also a wrapper around this API that provides a [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)
- * that enables reactivity. Other front-end frameworks can be supported in the future.
- *
- * The first group of methods are like standard CRUD methods that
- * allow applications to {@link put}, {@link get}, {@link patch}, and {@link delete}
- * {@link GraffitiObjectBase} objects. The main difference between these
- * methods and standard database methods is that an {@link GraffitiObjectBase.actor | `actor`}
- * (essentially a user) can only modify objects that they created.
- * Applications may also specify an an array of actors that are {@link GraffitiObjectBase.allowed | `allowed`}
- * to access the object and an array of {@link GraffitiObjectBase.channels | `channels`}
- * that the object is associated with.
- *
- * The "social" part of the API is the {@link discover} method, which allows
- * an application to query for objects made by other users.
- * This function only returns objects that are associated with one or more
- * of the {@link GraffitiObjectBase.channels | `channels`}
- * provided by a querying application. This helps to prevent
- * [context collapse](https://en.wikipedia.org/wiki/Context_collapse) and
- * allows users to express their intended audience, even in an interoperable
- * environment.
- *
- * Additionally, {@link synchronize} keeps track of changes to data
- * from any of the aforementioned methods and routes these changes internally
- * to provide a consistent user experience.
- *
- * Finally, other utility functions provide simple type conversions and
- * allow users to find objects "lost" to forgotten or misspelled channels.
+ * are useless if the system as a whole doesn't expose useful functionality to developers.
+ *
+ * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)
+ * that wraps around this API to provide reactivity. Other high-level libraries
+ * will be available in the future.
+ *
+ * ## Overview
+ *
+ * This API tries to draw from well-known concepts and standards wherever possible.
+ * JSON objects, representing social artifacts (e.g. posts, profiles) and activities
+ * (e.g. likes, follows) can be interacted with through standard CRUD operations:
+ *  {@link put}, {@link get}, {@link patch}, and {@link delete}.
+ * Objects can be typed with [JSON Schema](https://json-schema.org/) and patches
+ * can be applied with [JSON Patch](https://jsonpatch.com).
+ * For interoperability between Graffiti applications, we recommend using established properties from the
+ * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available.
+ *
+ * The social aspect of Graffiti comes from the {@link discover} operation
+ * which allows applications to find objects that other users made.
+ * It is a lot like a traditional query operation, but it only
+ * returns objects that have been placed in particular
+ * {@link GraffitiObjectBase.channels | `channels`}
+ * specified by the discovering application.
+ *
+ * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts
+ * unique to Graffiti along with *interaction relativity*.
+ * Channels create boundaries between public spaces and work to prevent
+ * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)
+ * even in a highly interoperable environment.
+ * Interaction relativity means that all interactions between users are
+ * actually atomic single-user operations that can be interpreted in different ways,
+ * which also supports interoperability and pluralism.
+ *
+ * ### Channels
+ *
+ * {@link GraffitiObjectBase.channels | `channels`}
+ * are a way for the creators of social data to express the intended audience of their
+ * data. When a user creates data using the {@link put} method, they
+ * can place their data in one or more channels.
+ * Content consumers using the {@link discover} method will only see data
+ * contained in one of the channels they specify.
+ *
+ * While many channels may be public, they partition
+ * the public into different "contexts", mitigating the
+ * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the "flattening of multiple audiences."
+ * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,
+ * comment threads, topics, places (real or virtual), pieces of media, and more.
+ *
+ * For example, consider a comment on a post. If we place that comment in the channel
+ * represented by the post's URI, then only people viewing the post will know to
+ * look in that channel, giving it visibility akin to a comment on a blog post
+ * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).
+ * If we also place the comment in the channel represented by the commenter's URI (their
+ * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile
+ * will also see the comment, giving it more visibility, like a reply on Twitter.
+ * If we *only* place the comment in the channel represented by the commenter's URI, then
+ * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),
+ * where the comment is only visible to the commenter's followers but not the audience
+ * of the original post.
+ *
+ * The channel model differs from other models of communication such as the
+ * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,
+ * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)
+ * used by the AT Protocol, the protocol underlying BlueSky.
+ * The actor model is a fusion of direct messaging (like Email) and broadcasting
+ * (like RSS) and works well for follow-based communication but struggles
+ * to pass information via other rendez-vous.
+ * In the actor model, even something as simple as comments can be
+ * [very tricky and require server "side effects"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).
+ * The firehose model dumps all user data into one public database,
+ * which doesn't allow for the carving out of different contexts that we did in our comment
+ * example above. In the firehose model a comment will always be visible to *both* the original post's audience and
+ * the commenter's followers.
+ *
+ * In some sense, channels provide a sort of "social access control" by forming
+ * expectations about the audiences of different online spaces.
+ * As a real world analogy, oftentimes support groups, such as alcoholics
+ * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details
+ * because they have expectations about the other people attending.
+ * If someone malicious went to support groups just to spread people's secrets,
+ * they would be shamed for violating these norms.
+ * Similarly, in Graffiti, while you could spider public channels like a search engine
+ * to find content about a person, revealing that you've done such a thing
+ * would be shameful.
+ *
+ * Still, social access control is not perfect and so in situations where privacy is important,
+ * objects can also be given
+ * an {@link GraffitiObjectBase.allowed | `allowed`} list.
+ * For example, to send someone a direct message you should put an object representing
+ * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),
+ * so they can find it, *and* set the `allowed` field to only include the recipient,
+ * so only they can read it.
+ *
+ * ### Interaction relativity
+ *
+ * Interaction relativity posits that "interaction between two individuals only
+ * exists relative to an observer," or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).
+ * For example, if one user creates a post and another user wants to "like" that post,
+ * their like is not modifying the original post, it is simply another data object that points
+ * to the post being liked, via its {@link locationToUri | URI}.
+ *
+ * ```json
+ * {
+ *   activity: 'like',
+ *   target: 'uri-of-the-post-i-like',
+ *   actor: 'my-user-id'
+ * }
+ * ```
+ *
+ * In Graffiti, all interactions including *moderation* and *collaboration* are relative.
+ * This means that applications can freely choose which interactions
+ * they want to express to their users and how.
+ * For example, one application could have a single fixed moderator,
+ * another could allow users to choose which moderators they would like filter their content
+ * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),
+ * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).
+ * Each of these applications is one interpretation of the underlying refieid user interactions and
+ * users can freely switch between them.
+ *
+ * Interaction relativy also allows applications to introduce new sorts of interactions
+ * without having to coordinate with all the other existing applications,
+ * keeping the ecosystem flexible and interoperable.
+ * For example, an application could [add a "Trust" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)
+ * and use it assess the truthfulness of posts made on applications across Graffiti.
+ * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem
+ * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).
+ *
+ * Interactivy relativity is realized in Graffiti through two design decisions:
+ * 1. The creators of objects can only modify their own objects. It is important for
+ *    users to be able to change and delete their own content to respect their
+ *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),
+ *    but beyond self-correction and self-censorship all other interaction is reified.
+ *    Many interactions can be reified via pointers, as in the "like" example above, and collaborative
+ *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).
+ * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),
+ *    anyone can post to any channel, so long as they know the URI of that channel.
+ *    It is up to applications to hide content from channels either according to manual
+ *    filters or in response to user action.
+ *    For example, a user may create a post with the flag `disableReplies`.
+ *    Applications could then filter out any content from the replies channel
+ *    that the original poster has not specifically approved.
+ *
+ * ## 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
+ *
+ * - Test for listChannels and listOrphans,
+ * - Implement scope.
  *
  * @groupDescription CRUD Methods
  * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
@@ -238,15 +417,46 @@ export 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 synchronize}
+   * 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
-   * may return objects that have been deleted but with a
+   * will return objects that have been deleted but with a
    * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for
-   * cache invalidation purposes. Implementations must make aware when, if ever,
-   * tombstoned objects are removed.
-   *
-   * {@link discover} can be used in conjunction with {@link synchronize}
-   * to provide a responsive and consistent user experience.
+   * cache invalidation purposes.
+   * The final `return()` value of the stream includes a `tombstoneRetention`
+   * property that represents the minimum amount of time,
+   * in milliseconds, that an application will retain and return tombstones for objects that
+   * have been deleted.
+   *
+   * When repolling, the {@link GraffitiObjectBase.lastModified | `lastModified`}
+   * field can be queried via the schema to
+   * only fetch objects that have been modified since the last poll.
+   * Such queries should only be done if the time since the last poll
+   * is less than the `tombstoneRetention` value of that poll, otherwise the tombstones
+   * for objects that have been deleted may not be returned.
+   *
+   * ```json
+   * {
+   *   "properties": {
+   *     "lastModified": {
+   *       "minimum": LAST_RETRIEVED_TIME
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * `discover` needs to be polled for new data because live updates to
+   * an application can be visually distracting or lead to toxic engagement.
+   * If and when an application wants real-time updates, such as in a chat
+   * application, application authors must be intentional about their polling.
+   *
+   * Implementers should be aware that some users may applications may try to poll
+   * {@link discover} repetitively. You can deal with this by rate limiting or
+   * preemptively fetching data via a bidirectional channel, like a WebSocket.
+   * Additionally, implementers should probably index the `lastModified` field
+   * to speed up responses to schemas like the one above.
    *
    * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
    * and [JSON Schema](https://json-schema.org).
@@ -269,7 +479,12 @@ export abstract class Graffiti {
      * property will be returned.
      */
     session?: GraffitiSession,
-  ): GraffitiStream<GraffitiObject<Schema>>;
+  ): GraffitiStream<
+    GraffitiObject<Schema>,
+    {
+      tombstoneRetention: number;
+    }
+  >;
 
   /**
    * This method has the same signature as {@link discover} but listens for
@@ -336,7 +551,6 @@ export abstract class Graffiti {
     session: GraffitiSession,
   ): GraffitiStream<{
     channel: string;
-    source: string;
     lastModified: number;
     count: number;
   }>;
@@ -355,15 +569,12 @@ export abstract class Graffiti {
    * and {@link GraffitiObjectBase.source | `source`} of the orphaned objects
    * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
    * The {@link GraffitiObjectBase.lastModified | lastModified} field is the
-   * time that the user last modified the orphan and the
-   * {@link GraffitiObjectBase.tombstone | `tombstone`} field is `true`
-   * if the object has been deleted.
+   * time that the user last modified the orphan.
    */
   abstract listOrphans(session: GraffitiSession): GraffitiStream<{
     name: string;
     source: string;
     lastModified: string;
-    tombstone: boolean;
   }>;
 
   /**
@@ -378,21 +589,40 @@ export abstract class Graffiti {
    *
    * The {@link GraffitiSession | session} object is returned
    * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}
-   * as a {@link GraffitiLoginEvent}.
+   * as a {@link GraffitiLoginEvent} with event type `login`.
    *
    * @group Session Management
    */
   abstract login(
     /**
-     * An optional actor to prompt the user to login as. For example,
-     * if a session expired and the user is trying to reauthenticate,
-     * or if the user entered their username in an application-side login form.
-     *
-     * If not provided, the implementation should prompt the user to
-     * supply an actor ID along with their other login information
-     * (e.g. password).
+     * Suggestions for the permissions that the
+     * login process should grant. The login process may not
+     * provide the exact proposed permissions.
      */
-    actor?: string,
+    proposal?: {
+      /**
+       * A suggested actor to login as. For example, if a user tries to
+       * edit a post but are not logged in, the interface can infer that
+       * they might want to log in as the actor who created the post
+       * they are attempting to edit.
+       *
+       * Even if provided, the implementation should allow the user
+       * to log in as a different actor if they choose.
+       */
+      actor?: string;
+      /**
+       * A yet to be defined permissions scope. An application may use
+       * this to indicate the minimum necessary scope needed to
+       * operate. For example, it may need to be able read private
+       * messages from a certain set of channels, or write messages that
+       * follow a particular schema.
+       *
+       * The login process should make it clear what scope an application
+       * is requesting and allow the user to enhance or reduce that
+       * scope as necessary.
+       */
+      scope?: {};
+    },
     /**
      * An arbitrary string that will be returned with the
      * {@link GraffitiSession | session} object
@@ -409,7 +639,7 @@ export abstract class Graffiti {
    *
    * A confirmation will be returned asynchronously via
    * {@link Graffiti.sessionEvents | sessionEvents}
-   * as a {@link GraffitiLogoutEvent}.
+   * as a {@link GraffitiLogoutEvent} as event type `logout`.
    *
    * @group Session Management
    */
@@ -429,7 +659,7 @@ export abstract class Graffiti {
   /**
    * An event target that can be used to listen for `login`
    * and `logout` events. They are custom events of types
-   * {@link GraffitiLoginEvent`} and {@link GraffitiLogoutEvent }
+   * {@link GraffitiLoginEvent} and {@link GraffitiLogoutEvent }
    * respectively.
    *
    * @group Session Management

package/src/2-types.ts

@@ -1,4 +1,4 @@
-import { type JTDDataType } from "ajv/dist/core";
+import type { JTDDataType } from "ajv/dist/core";
 import type { Operation as JSONPatchOperation } from "fast-json-patch";
 
 /**
@@ -169,7 +169,7 @@ export type GraffitiPutObject<Schema> = Pick<
  * use to verify that a user has permission to operate a
  * particular {@link GraffitiObjectBase.actor | `actor`}.
  * This object is required of all {@link Graffiti} methods
- * that modify objects and optional for methods that read objects.
+ * that modify objects and is optional for methods that read objects.
  *
  * At a minimum the `session` object must contain the
  * {@link GraffitiSession.actor | `actor`} URI the user wants to authenticate with.
@@ -180,8 +180,20 @@ export type GraffitiPutObject<Schema> = Pick<
  * function. A distributed implementation may include
  * a cryptographic signature.
  *
- * It may also include other implementation specific properties
- * that provide hints for performance or security.
+ * As to why the `session` object is passed as an argument to every method
+ * rather than being an internal property of the {@link Graffiti} instance,
+ * this is primarily for type-checking to catch bugs related to login state.
+ * Graffiti applications can expose some functionality to users who are not logged in
+ * with {@link Graffiti.get} and {@link Graffiti.discover} but without type-checking
+ * the `session` it can be easy to forget to hide buttons that trigger
+ * other methods that require login.
+ * In the future, `session` object may be updated to include scope information
+ * and passing the `session` to each method can type-check whether the session provides the
+ * necessary permissions.
+ *
+ * Passing the `session` object per-method also allows for multiple sessions
+ * to be used within the same application, like an Email client fetching from
+ * multiple accounts.
  */
 export interface GraffitiSession {
   /**
@@ -189,9 +201,12 @@ export interface GraffitiSession {
    */
   actor: string;
   /**
-   * Other implementation-specific properties go here.
+   * A yet undefined property detailing what operations the session
+   * grants the user to perform. For example, to allow a user to
+   * read private messages from a particular set of channels or
+   * to allow the user to write object matching a particular schema.
    */
-  [key: string]: any;
+  scope?: {};
 }
 
 /**
@@ -243,16 +258,16 @@ export interface GraffitiPatch {
  * that can be iterated over using `for await` loops or calling `next` on the generator.
  * The stream can be terminated by breaking out of a loop calling `return` on the generator.
  */
-export type GraffitiStream<T> = AsyncGenerator<
+export type GraffitiStream<TValue, TReturn = void> = AsyncGenerator<
   | {
       error?: undefined;
-      value: T;
+      value: TValue;
     }
   | {
       error: Error;
       source: string;
     },
-  void
+  TReturn
 >;
 
 /**

package/tests/discover.ts

@@ -1,6 +1,11 @@
-import { it, expect, describe } from "vitest";
-import { type GraffitiFactory, type GraffitiSession } from "../src/index";
-import { randomString, randomValue, randomPutObject } from "./utils";
+import { it, expect, describe, assert } from "vitest";
+import {
+  type GraffitiFactory,
+  type GraffitiSession,
+  type GraffitiStream,
+  type JSONSchema4,
+} from "../src/index";
+import { randomString, nextStreamValue, randomPutObject } from "./utils";
 
 export const graffitiDiscoverTests = (
   useGraffiti: GraffitiFactory,
@@ -8,6 +13,12 @@ export const graffitiDiscoverTests = (
   useSession2: () => GraffitiSession,
 ) => {
   describe("discover", () => {
+    it("discover nothing", async () => {
+      const graffiti = useGraffiti();
+      const iterator = graffiti.discover([], {});
+      expect(await iterator.next()).toHaveProperty("done", true);
+    });
+
     it("discover single", async () => {
       const graffiti = useGraffiti();
       const session = useSession1();
@@ -17,16 +28,572 @@ export const graffitiDiscoverTests = (
 
       const queryChannels = [randomString(), object.channels[0]];
       const iterator = graffiti.discover(queryChannels, {});
-      const result = (await iterator.next()).value;
-      if (!result || result.error) throw new Error();
-      expect(result.value.value).toEqual(object.value);
-      expect(result.value.channels).toEqual([object.channels[0]]);
-      expect(result.value.allowed).toBeUndefined();
-      expect(result.value.actor).toEqual(session.actor);
-      expect(result.value.tombstone).toBe(false);
-      expect(result.value.lastModified).toEqual(putted.lastModified);
+      const value = await nextStreamValue(iterator);
+      expect(value.value).toEqual(object.value);
+      expect(value.channels).toEqual([object.channels[0]]);
+      expect(value.allowed).toBeUndefined();
+      expect(value.actor).toEqual(session.actor);
+      expect(value.tombstone).toBe(false);
+      expect(value.lastModified).toEqual(putted.lastModified);
       const result2 = await iterator.next();
       expect(result2.done).toBe(true);
     });
+
+    it("discover wrong channel", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const object = randomPutObject();
+      await graffiti.put(object, session);
+      const iterator = graffiti.discover([randomString()], {});
+      await expect(iterator.next()).resolves.toHaveProperty("done", true);
+    });
+
+    it("discover not allowed", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const object = randomPutObject();
+      object.allowed = [randomString(), randomString()];
+      const putted = await graffiti.put(object, session1);
+
+      const iteratorSession1 = graffiti.discover(object.channels, {}, session1);
+      const value = await nextStreamValue(iteratorSession1);
+      expect(value.value).toEqual(object.value);
+      expect(value.channels).toEqual(object.channels);
+      expect(value.allowed).toEqual(object.allowed);
+      expect(value.actor).toEqual(session1.actor);
+      expect(value.tombstone).toBe(false);
+      expect(value.lastModified).toEqual(putted.lastModified);
+
+      const iteratorSession2 = graffiti.discover(object.channels, {}, session2);
+      expect(await iteratorSession2.next()).toHaveProperty("done", true);
+
+      const iteratorNoSession = graffiti.discover(object.channels, {});
+      expect(await iteratorNoSession.next()).toHaveProperty("done", true);
+    });
+
+    it("discover allowed", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const object = randomPutObject();
+      object.allowed = [randomString(), session2.actor, randomString()];
+      const putted = await graffiti.put(object, session1);
+
+      const iteratorSession2 = graffiti.discover(object.channels, {}, session2);
+      const value = await nextStreamValue(iteratorSession2);
+      expect(value.value).toEqual(object.value);
+      expect(value.allowed).toEqual([session2.actor]);
+      expect(value.channels).toEqual(object.channels);
+      expect(value.actor).toEqual(session1.actor);
+      expect(value.tombstone).toBe(false);
+      expect(value.lastModified).toEqual(putted.lastModified);
+    });
+
+    for (const prop of ["name", "actor", "lastModified"] as const) {
+      it(`discover for ${prop}`, async () => {
+        const graffiti = useGraffiti();
+        const session1 = useSession1();
+        const session2 = useSession2();
+
+        const object1 = randomPutObject();
+        const putted1 = await graffiti.put(object1, session1);
+
+        const object2 = randomPutObject();
+        object2.channels = object1.channels;
+        // Make sure the lastModified is different for the query
+        await new Promise((r) => setTimeout(r, 20));
+        const putted2 = await graffiti.put(object2, session2);
+
+        const iterator = graffiti.discover(object1.channels, {
+          properties: {
+            [prop]: {
+              enum: [putted1[prop]],
+            },
+          },
+        });
+
+        const value = await nextStreamValue(iterator);
+        expect(value.name).toEqual(putted1.name);
+        expect(value.name).not.toEqual(putted2.name);
+        expect(value.value).toEqual(object1.value);
+        await expect(iterator.next()).resolves.toHaveProperty("done", true);
+      });
+    }
+
+    it("discover with lastModified range", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const object = randomPutObject();
+      const putted1 = await graffiti.put(object, session);
+      // Make sure the lastModified is different
+      await new Promise((r) => setTimeout(r, 20));
+      const putted2 = await graffiti.put(object, session);
+
+      expect(putted1.name).not.toEqual(putted2.name);
+      expect(putted1.lastModified).toBeLessThan(putted2.lastModified);
+
+      const gtIterator = graffiti.discover([object.channels[0]], {
+        properties: {
+          lastModified: {
+            minimum: putted2.lastModified,
+            exclusiveMinimum: true,
+          },
+        },
+      });
+      expect(await gtIterator.next()).toHaveProperty("done", true);
+      const gtIteratorEpsilon = graffiti.discover([object.channels[0]], {
+        properties: {
+          lastModified: {
+            minimum: putted2.lastModified - 0.1,
+            exclusiveMinimum: true,
+          },
+        },
+      });
+      const value1 = await nextStreamValue(gtIteratorEpsilon);
+      expect(value1.name).toEqual(putted2.name);
+      expect(await gtIteratorEpsilon.next()).toHaveProperty("done", true);
+      const gteIterator = graffiti.discover(object.channels, {
+        properties: {
+          value: {},
+          lastModified: {
+            minimum: putted2.lastModified,
+          },
+        },
+      });
+      const value = await nextStreamValue(gteIterator);
+      expect(value.name).toEqual(putted2.name);
+      expect(await gteIterator.next()).toHaveProperty("done", true);
+      const gteIteratorEpsilon = graffiti.discover(object.channels, {
+        properties: {
+          lastModified: {
+            minimum: putted2.lastModified + 0.1,
+          },
+        },
+      });
+      expect(await gteIteratorEpsilon.next()).toHaveProperty("done", true);
+
+      const ltIterator = graffiti.discover(object.channels, {
+        properties: {
+          lastModified: {
+            maximum: putted1.lastModified,
+            exclusiveMaximum: true,
+          },
+        },
+      });
+      expect(await ltIterator.next()).toHaveProperty("done", true);
+
+      const ltIteratorEpsilon = graffiti.discover(object.channels, {
+        properties: {
+          lastModified: {
+            maximum: putted1.lastModified + 0.1,
+            exclusiveMaximum: true,
+          },
+        },
+      });
+      const value3 = await nextStreamValue(ltIteratorEpsilon);
+      expect(value3.name).toEqual(putted1.name);
+      expect(await ltIteratorEpsilon.next()).toHaveProperty("done", true);
+
+      const lteIterator = graffiti.discover(object.channels, {
+        properties: {
+          lastModified: {
+            maximum: putted1.lastModified,
+          },
+        },
+      });
+      const value2 = await nextStreamValue(lteIterator);
+      expect(value2.name).toEqual(putted1.name);
+      expect(await lteIterator.next()).toHaveProperty("done", true);
+
+      const lteIteratorEpsilon = graffiti.discover(object.channels, {
+        properties: {
+          lastModified: {
+            maximum: putted1.lastModified - 0.1,
+          },
+        },
+      });
+      expect(await lteIteratorEpsilon.next()).toHaveProperty("done", true);
+    });
+
+    it("discover schema allowed, as and not as owner", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const object = randomPutObject();
+      object.allowed = [randomString(), session2.actor, randomString()];
+      await graffiti.put(object, session1);
+
+      const iteratorSession1 = graffiti.discover(
+        object.channels,
+        {
+          properties: {
+            allowed: {
+              minItems: 3,
+              // Make sure session2.actor is in the allow list
+              not: {
+                items: {
+                  not: {
+                    enum: [session2.actor],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session1,
+      );
+      const value = await nextStreamValue(iteratorSession1);
+      expect(value.value).toEqual(object.value);
+      await expect(iteratorSession1.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+
+      const iteratorSession2BigAllow = graffiti.discover(
+        object.channels,
+        {
+          properties: {
+            allowed: {
+              minItems: 3,
+            },
+          },
+        },
+        session2,
+      );
+      await expect(iteratorSession2BigAllow.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+      const iteratorSession2PeekOther = graffiti.discover(
+        object.channels,
+        {
+          properties: {
+            allowed: {
+              not: {
+                items: {
+                  not: {
+                    enum: [object.channels[0]],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session2,
+      );
+      await expect(iteratorSession2PeekOther.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+      const iteratorSession2SmallAllowPeekSelf = graffiti.discover(
+        object.channels,
+        {
+          properties: {
+            allowed: {
+              maxItems: 1,
+              not: {
+                items: {
+                  not: {
+                    enum: [session2.actor],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session2,
+      );
+      const value2 = await nextStreamValue(iteratorSession2SmallAllowPeekSelf);
+      expect(value2.value).toEqual(object.value);
+      await expect(
+        iteratorSession2SmallAllowPeekSelf.next(),
+      ).resolves.toHaveProperty("done", true);
+    });
+
+    it("discover schema channels, as and not as owner", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const object = randomPutObject();
+      object.channels = [randomString(), randomString(), randomString()];
+      await graffiti.put(object, session1);
+
+      const iteratorSession1 = graffiti.discover(
+        [object.channels[0], object.channels[2]],
+        {
+          properties: {
+            channels: {
+              minItems: 3,
+              // Make sure session2.actor is in the allow list
+              not: {
+                items: {
+                  not: {
+                    enum: [object.channels[1]],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session1,
+      );
+      const value = await nextStreamValue(iteratorSession1);
+      expect(value.value).toEqual(object.value);
+      await expect(iteratorSession1.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+
+      const iteratorSession2BigAllow = graffiti.discover(
+        [object.channels[0], object.channels[2]],
+        {
+          properties: {
+            channels: {
+              minItems: 3,
+            },
+          },
+        },
+        session2,
+      );
+      await expect(iteratorSession2BigAllow.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+      const iteratorSession2PeekOther = graffiti.discover(
+        [object.channels[0], object.channels[2]],
+        {
+          properties: {
+            channels: {
+              not: {
+                items: {
+                  not: {
+                    enum: [object.channels[1]],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session2,
+      );
+      await expect(iteratorSession2PeekOther.next()).resolves.toHaveProperty(
+        "done",
+        true,
+      );
+      const iteratorSession2SmallAllowPeekSelf = graffiti.discover(
+        [object.channels[0], object.channels[2]],
+        {
+          properties: {
+            allowed: {
+              maxItems: 2,
+              not: {
+                items: {
+                  not: {
+                    enum: [object.channels[2]],
+                  },
+                },
+              },
+            },
+          },
+        },
+        session2,
+      );
+      const value2 = await nextStreamValue(iteratorSession2SmallAllowPeekSelf);
+      expect(value2.value).toEqual(object.value);
+      await expect(
+        iteratorSession2SmallAllowPeekSelf.next(),
+      ).resolves.toHaveProperty("done", true);
+    });
+
+    it("discover query for empty allowed", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+
+      const publicO = randomPutObject();
+
+      const publicSchema = {
+        not: {
+          required: ["allowed"],
+        },
+      } satisfies JSONSchema4;
+
+      await graffiti.put(publicO, session1);
+      const iterator = graffiti.discover(
+        publicO.channels,
+        publicSchema,
+        session1,
+      );
+      const value = await nextStreamValue(iterator);
+      expect(value.value).toEqual(publicO.value);
+      expect(value.allowed).toBeUndefined();
+      await expect(iterator.next()).resolves.toHaveProperty("done", true);
+
+      const restricted = randomPutObject();
+      restricted.allowed = [];
+      await graffiti.put(restricted, session1);
+      const iterator2 = graffiti.discover(
+        restricted.channels,
+        publicSchema,
+        session1,
+      );
+      await expect(iterator2.next()).resolves.toHaveProperty("done", true);
+    });
+
+    it("discover query for values", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const object1 = randomPutObject();
+      object1.value = { test: randomString() };
+      await graffiti.put(object1, session);
+
+      const object2 = randomPutObject();
+      object2.channels = object1.channels;
+      object2.value = { test: randomString(), something: randomString() };
+      await graffiti.put(object2, session);
+
+      const object3 = randomPutObject();
+      object3.channels = object1.channels;
+      object3.value = { other: randomString(), something: randomString() };
+      await graffiti.put(object3, session);
+
+      const counts = new Map<string, number>();
+      for (const property of ["test", "something", "other"] as const) {
+        let count = 0;
+        for await (const result of graffiti.discover(object1.channels, {
+          properties: {
+            value: {
+              required: [property],
+            },
+          },
+        })) {
+          assert(!result.error, "result has error");
+          if (property in result.value.value) {
+            count++;
+          }
+        }
+        counts.set(property, count);
+      }
+
+      expect(counts.get("test")).toBe(2);
+      expect(counts.get("something")).toBe(2);
+      expect(counts.get("other")).toBe(1);
+    });
+
+    it("discover for deleted content", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const object = randomPutObject();
+      const putted = await graffiti.put(object, session);
+      const deleted = await graffiti.delete(putted, session);
+
+      const iterator = graffiti.discover(object.channels, {});
+      const value = await nextStreamValue(iterator);
+      expect(value.tombstone).toBe(true);
+      expect(value.value).toEqual(object.value);
+      expect(value.channels).toEqual(object.channels);
+      expect(value.actor).toEqual(session.actor);
+      expect(value.lastModified).toEqual(deleted.lastModified);
+      await expect(iterator.next()).resolves.toHaveProperty("done", true);
+    });
+
+    it("discover for replaced channels", async () => {
+      // Do this a bunch to check for concurrency issues
+      for (let i = 0; i < 10; i++) {
+        const graffiti = useGraffiti();
+        const session = useSession1();
+
+        const object1 = randomPutObject();
+        const putted = await graffiti.put(object1, session);
+        const object2 = randomPutObject();
+        const replaced = await graffiti.put(
+          {
+            ...putted,
+            ...object2,
+          },
+          session,
+        );
+
+        const iterator1 = graffiti.discover(object1.channels, {});
+        const value1 = await nextStreamValue(iterator1);
+        await expect(iterator1.next()).resolves.toHaveProperty("done", true);
+
+        const iterator2 = graffiti.discover(object2.channels, {});
+        const value2 = await nextStreamValue(iterator2);
+        await expect(iterator2.next()).resolves.toHaveProperty("done", true);
+
+        // If they have the same timestamp, except
+        // only one to have a tombstone
+        if (putted.lastModified === replaced.lastModified) {
+          expect(value1.tombstone || value2.tombstone).toBe(true);
+          expect(value1.tombstone && value2.tombstone).toBe(false);
+        } else {
+          expect(value1.tombstone).toBe(true);
+          expect(value1.value).toEqual(object1.value);
+          expect(value1.channels).toEqual(object1.channels);
+          expect(value1.lastModified).toEqual(replaced.lastModified);
+
+          expect(value2.tombstone).toBe(false);
+          expect(value2.value).toEqual(object2.value);
+          expect(value2.channels).toEqual(object2.channels);
+          expect(value2.lastModified).toEqual(replaced.lastModified);
+        }
+      }
+    });
+
+    it("discover for patched allowed", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const object = randomPutObject();
+      const putted = await graffiti.put(object, session);
+      await graffiti.patch(
+        {
+          allowed: [{ op: "add", path: "", value: [] }],
+        },
+        putted,
+        session,
+      );
+      const iterator = graffiti.discover(object.channels, {});
+      const value = await nextStreamValue(iterator);
+      expect(value.tombstone).toBe(true);
+      expect(value.value).toEqual(object.value);
+      expect(value.channels).toEqual(object.channels);
+      expect(value.allowed).toBeUndefined();
+      await expect(iterator.next()).resolves.toHaveProperty("done", true);
+    });
+
+    it("put concurrently and discover one", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const object = randomPutObject();
+      object.name = randomString();
+
+      const putPromises = Array(100)
+        .fill(0)
+        .map(() => graffiti.put(object, session));
+      await Promise.all(putPromises);
+
+      const iterator = graffiti.discover(object.channels, {});
+      let tombstoneCount = 0;
+      let valueCount = 0;
+      for await (const result of iterator) {
+        assert(!result.error, "result has error");
+        if (result.value.tombstone) {
+          tombstoneCount++;
+        } else {
+          valueCount++;
+        }
+      }
+      expect(tombstoneCount).toBe(99);
+      expect(valueCount).toBe(1);
+    });
   });
 };

package/tests/synchronize.ts

@@ -1,7 +1,6 @@
 import { it, expect, describe } from "vitest";
 import { type GraffitiFactory, type GraffitiSession } from "../src/index";
 import { randomPutObject, randomString } from "./utils";
-import { randomInt } from "crypto";
 
 export const graffitiSynchronizeTests = (
   useGraffiti: GraffitiFactory,

package/tests/utils.ts

@@ -1,4 +1,5 @@
-import type { GraffitiPutObject } from "../src";
+import { assert } from "vitest";
+import type { GraffitiPutObject, GraffitiStream } from "../src";
 
 export function randomString(): string {
   const array = new Uint8Array(16);
@@ -20,3 +21,9 @@ export function randomPutObject(): GraffitiPutObject<{}> {
     channels: [randomString(), randomString()],
   };
 }
+
+export async function nextStreamValue<S, T>(iterator: GraffitiStream<S, T>) {
+  const result = await iterator.next();
+  assert(!result.done && !result.value.error, "result has no value");
+  return result.value.value;
+}

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "esnext",
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "resolveJsonModule": true,
-    "verbatimModuleSyntax": true
-  },
-  "include": ["src", "tests"]
-}