@graffiti-garden/api 0.6.3 → 1.0.0

package/src/2-types.ts

@@ -1,23 +1,23 @@
 import type { JSONSchema, FromSchema } from "json-schema-to-ts";
-import type { Operation as JSONPatchOperation } from "fast-json-patch";
 
 /**
  * Objects are the atomic unit in Graffiti that can represent both data (*e.g.* a social media post or profile)
  * and activities (*e.g.* a like or follow).
- * Objects are created and modified by a single {@link actor | `actor`}.
  *
- * Most of an object's content is stored in its {@link value | `value`} property, which can be any JSON
- * object. However, we recommend using properties from the
+ * Each object embeds the {@link actor | `actor`} that created it.
+ * Object content and metadata are static but an object may be deleted by
+ * its creating {@link actor | `actor`}.
+ *
+ * An object's content is stored in its {@link value | `value`} property, which can be any JSON
+ * object. However, it is recommended to use properties from the
  * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
  * or properties that emerge in the Graffiti [folksonomy](https://en.wikipedia.org/wiki/Folksonomy)
  * to promote interoperability.
  *
- * The object is globally addressable via its {@link url | `url`}.
- *
- * The {@link channels | `channels`} and {@link allowed | `allowed`} properties
- * enable the object's creator to shape the visibility of and access to their object.
+ * Each object is globally addressable via its {@link url | `url`}.
  *
- * The {@link lastModified | `lastModified`} property can be used to compare object versions.
+ * An object's {@link channels | `channels`} and {@link allowed | `allowed`} properties
+ * are set by an objects creator to shape the visibility of and access to their object.
  */
 export interface GraffitiObjectBase {
   /**
@@ -34,11 +34,11 @@ export interface GraffitiObjectBase {
    * {@link Graffiti.discover} method. This allows creators to express the intended audience of their object
    * which helps to prevent [context collapse](https://en.wikipedia.org/wiki/Context_collapse) even
    * in the highly interoperable ecosystem that Graffiti envisions. For example, channel URIs may be:
-   * - A user's own {@link actor | `actor`} URI. Putting an object in this channel is a way to broadcast
-   * the object to the user's followers, like posting a tweet.
-   * - The URL of a Graffiti post. Putting an object in this channel is a way to broadcast to anyone viewing
+   * - A actor's own {@link actor | `actor`} URI. Posting an object to this channel is a way to broadcast
+   * the object to the actor's followers, like posting a tweet.
+   * - The URL of a Graffiti post. Posting an object to this channel is a way to broadcast to anyone viewing
    * the post, like commenting on a tweet.
-   * - A URI representing a topic. Putting an object in this channel is a way to broadcast to anyone interested
+   * - A URI representing a topic. Posting an object to this channel is a way to broadcast to anyone interested
    * in that topic, like posting in a subreddit.
    */
   channels: string[];
@@ -49,19 +49,20 @@ export interface GraffitiObjectBase {
    * also know the right {@link channels | `channel` } to look in). An object can always be accessed by its creator, even if
    * the `allowed` array is empty.
    *
-   * The `allowed` array is not revealed to users other than the creator, like
-   * a BCC email. A user may choose to add a `to` property to the object's {@link value | `value`} to indicate
+   * The `allowed` array is not revealed to actors other than the creator, like
+   * a BCC email. An actor may choose to add a `to` property to the object's {@link value | `value`} to indicate
    * other recipients, however this is not enforced by Graffiti and may not accurately reflect the actual `allowed` array.
    *
    * `allowed` can be combined with {@link channels | `channels`}. For example, to send someone a direct message
-   * the sender should put their object in the channel of the recipient's {@link actor | `actor`} URI to notify them of the message and also add
+   * the sender should post their object to the channel of the recipient's {@link actor | `actor`} URI to notify them of the message and also add
    * the recipient's {@link actor | `actor`} URI to the `allowed` array to prevent others from seeing the message.
    */
   allowed?: string[] | null;
 
   /**
-   * The URI of the `actor` that {@link Graffiti.put | created } the object. This `actor` also has the unique permission to
-   * {@link Graffiti.patch | modify} or {@link Graffiti.delete | delete} the object.
+   * The URI of the `actor` that {@link Graffiti.post | created } the object.
+   * This `actor`  has the unique permission to
+   * {@link Graffiti.delete | delete} the object.
    *
    * We borrow the term actor from the ActivityPub because
    * [like in ActivityPub](https://www.w3.org/TR/activitypub/#h-note-0)
@@ -77,8 +78,6 @@ export interface GraffitiObjectBase {
   /**
    * A globally unique identifier and locator for the object. It can be used to point to
    * an object or to retrieve the object directly with {@link Graffiti.get}.
-   * If an object is {@link Graffiti.put | put} with the same URL
-   * as an existing object, the existing object will be replaced with the new object.
    *
    * An object's URL is generated when the object is first created and
    * should include sufficient randomness to prevent collisions
@@ -87,25 +86,11 @@ export interface GraffitiObjectBase {
    * to pull from multiple coexisting Graffiti implementations without collision.
    * Existing schemes include `graffiti:local:` for objects stored locally
    * (see the [local implementation](https://github.com/graffiti-garden/implementation-local))
-   * and `graffiti:remote:` for objects stored on Graffiti-specific web servers (see the
-   * [remote implementation](https://github.com/graffiti-garden/implementation-remote)).
+   * and `graffiti:remote:` for objects stored on Graffiti-specific web servers (see the [remote implementation](https://github.com/graffiti-garden/implementation-remote))
    * Options available in the future might include `graffiti:solid:` for objects stored on Solid servers
    * or `graffiti:p2p:` for objects stored on a peer-to-peer network.
    */
   url: string;
-
-  /**
-   * The time the object was last modified, measured in milliseconds since January 1, 1970.
-   * It can be used to compare object versions.
-   * A number, rather than an ISO string or Date object, is used for easy comparison, sorting,
-   * and JSON Schema [range queries](https://json-schema.org/understanding-json-schema/reference/numeric#range).
-   *
-   * It is possible to use this value to sort objects in a user's interface but in many cases it would be better to
-   * use a [`published`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-published)
-   * property in the object's {@link value | `value`} to indicate when the object was created
-   * rather than when it was modified.
-   */
-  lastModified: number;
 }
 
 /**
@@ -132,61 +117,55 @@ export const GraffitiObjectJSONSchema = {
     allowed: { type: "array", items: { type: "string" }, nullable: true },
     url: { type: "string" },
     actor: { type: "string" },
-    lastModified: { type: "number" },
   },
   additionalProperties: false,
-  required: ["value", "channels", "actor", "url", "lastModified"],
+  required: ["value", "channels", "actor", "url"],
 } as const satisfies JSONSchema;
 
 /**
  * This is an object containing only the {@link GraffitiObjectBase.url | `url`}
  * property of a {@link GraffitiObjectBase | GraffitiObject}.
- * It is used as a utility type so that users can call {@link Graffiti.get},
- * {@link Graffiti.patch}, or {@link Graffiti.delete} directly on an object
+ * It is used as a utility type so that applications can call
+ * {@link Graffiti.delete} directly on an object
  * rather than on `object.url`.
  */
 export type GraffitiObjectUrl = Pick<GraffitiObjectBase, "url">;
 
 /**
- * This object is a subset of {@link GraffitiObjectBase} that a user must construct locally before calling {@link Graffiti.put}.
- * This local copy does not require system-generated properties and may be statically typed with
+ * This object is a subset of {@link GraffitiObjectBase} that must be constructed locally before calling {@link Graffiti.post}.
+ * This local copy ignores system-generated properties
+ * ({@link GraffitiObjectBase.url | `url`} and {@link GraffitiObjectBase.actor | `actor`}),
+ * and may be statically typed with
  * a [JSON schema](https://json-schema.org/) to prevent the accidental creation of erroneous objects.
  *
  * This local object must have a {@link GraffitiObjectBase.value | `value`} and {@link GraffitiObjectBase.channels | `channels`}
  * and may optionally have an {@link GraffitiObjectBase.allowed | `allowed`} property.
- *
- * It may also include a {@link GraffitiObjectBase.url | `url`} property to specify the
- * URL of an existing object to replace. If no `url` is provided, one will be generated during object creation.
- *
- * This object does not need a {@link GraffitiObjectBase.lastModified | `lastModified`}
- * property since it will be automatically generated by the Graffiti system.
  */
-export type GraffitiPutObject<Schema extends JSONSchema> = Pick<
+export type GraffitiPostObject<Schema extends JSONSchema> = Pick<
   GraffitiObjectBase,
   "value" | "channels" | "allowed"
 > &
   Partial<GraffitiObjectBase> &
-  FromSchema<Schema & typeof GraffitiPutObjectJSONSchema>;
+  FromSchema<Schema & typeof GraffitiPostObjectJSONSchema>;
 
 /**
- * A JSON Schema equivalent to the {@link GraffitiPutObject} type.
+ * A JSON Schema equivalent to the {@link GraffitiPostObject} type.
  * Needed internally for type inference of JSON Schemas, but can
  * be used by implementations to validate objects.
  */
-export const GraffitiPutObjectJSONSchema = {
+export const GraffitiPostObjectJSONSchema = {
   ...GraffitiObjectJSONSchema,
   required: ["value", "channels"],
 } as const satisfies JSONSchema;
 
 /**
  * This object contains information that the underlying implementation can
- * use to verify that a user has permission to operate a
- * particular {@link GraffitiObjectBase.actor | `actor`}.
+ * use to authenticate a particular {@link GraffitiObjectBase.actor | `actor`}.
  * This object is required of all {@link Graffiti} methods
- * that modify objects and is optional for methods that read objects.
+ * that modify objects or media 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.
+ * {@link GraffitiSession.actor | `actor`} URI to authenticate with.
  * However it is likely that the `session` object must contain other
  * implementation-specific properties.
  * For example, a Solid implementation might include a
@@ -197,13 +176,10 @@ export const GraffitiPutObjectJSONSchema = {
  * 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
+ * Graffiti applications can expose some functionality to people 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
@@ -211,61 +187,20 @@ export const GraffitiPutObjectJSONSchema = {
  */
 export interface GraffitiSession {
   /**
-   * The {@link GraffitiObjectBase.actor | `actor`} a user wants to authenticate with.
+   * The {@link GraffitiObjectBase.actor | `actor`} to authenticate with.
    */
   actor: string;
-  /**
-   * 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.
-   */
-  scope?: {};
-}
-
-/**
- * This is the format for patches that modify {@link GraffitiObjectBase} objects
- * using the {@link Graffiti.patch} method. The patches must
- * be an array of [JSON Patch](https://jsonpatch.com) operations.
- * Patches can only be applied to the
- * {@link GraffitiObjectBase.value | `value`}, {@link GraffitiObjectBase.channels | `channels`},
- * and {@link GraffitiObjectBase.allowed | `allowed`} properties since the other
- * properties either describe the object's location or are automatically generated.
- * (See also {@link GraffitiPutObject}).
- */
-export interface GraffitiPatch {
-  /**
-   * An array of [JSON Patch](https://jsonpatch.com) operations to
-   * modify the object's {@link GraffitiObjectBase.value | `value`}. The resulting
-   * `value` must still be a JSON object.
-   */
-  value?: JSONPatchOperation[];
-
-  /**
-   * An array of [JSON Patch](https://jsonpatch.com) operations to
-   * modify the object's {@link GraffitiObjectBase.channels | `channels`}. The resulting
-   * `channels` must still be an array of strings.
-   */
-  channels?: JSONPatchOperation[];
-
-  /**
-   * An array of [JSON Patch](https://jsonpatch.com) operations to
-   * modify the object's {@link GraffitiObjectBase.allowed | `allowed`} property. The resulting
-   * `allowed` property must still be an array of strings or `undefined`.
-   */
-  allowed?: JSONPatchOperation[];
 }
 
 /**
- * A stream of data that are returned by Graffiti's query-like operations
- * {@link Graffiti.discover} and {@link Graffiti.recoverOrphans}.
+ * A stream of data that are returned by {@link Graffiti.discover}.
  *
  * Errors are returned within the stream rather than as
  * exceptions that would halt the entire stream. This is because
  * some implementations may pull data from multiple sources
  * including some that may be unreliable. In many cases,
  * these errors can be safely ignored.
- * See {@link GraffitiStreamError}.
+ * See {@link GraffitiObjectStreamError}.
  *
  * The stream is an [`AsyncGenerator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
  * that can be iterated over using `for await` loops or calling `next` on the generator.
@@ -276,17 +211,16 @@ export interface GraffitiPatch {
  * each of which can be used to resume the stream from where it left off.
  */
 export type GraffitiObjectStream<Schema extends JSONSchema> = AsyncGenerator<
-  GraffitiStreamError | GraffitiObjectStreamEntry<Schema>,
+  GraffitiObjectStreamError | GraffitiObjectStreamEntry<Schema>,
   GraffitiObjectStreamReturn<Schema>
 >;
 
 /**
- * An error that can occur in either the
- * {@link GraffitiObjectStream} or {@link GraffitiChannelStatsStream}.
+ * An error that can occur in a {@link GraffitiObjectStream}.
  *
  * @internal
  */
-export interface GraffitiStreamError {
+export interface GraffitiObjectStreamError {
   /**
    * The error that occurred while streaming data.
    */
@@ -307,7 +241,7 @@ export interface GraffitiStreamError {
  */
 export interface GraffitiObjectStreamEntry<Schema extends JSONSchema> {
   /**
-   * Empty property for compatibility with {@link GraffitiStreamError}
+   * Empty property for compatibility with {@link GraffitiObjectStreamError}
    */
   error?: undefined;
   /**
@@ -324,13 +258,13 @@ export interface GraffitiObjectStreamEntry<Schema extends JSONSchema> {
  * A result from a {@link GraffitiObjectStreamContinue} that indicated
  * an object has been deleted since the original stream was run.
  * Only sparse metadata about the deleted object is returned to respect
- * the deleting user's privacy.
+ * the deleting actor's privacy.
  *
  * @internal
  */
 export interface GraffitiObjectStreamContinueTombstone {
   /**
-   * Empty property for compatibility with {@link GraffitiStreamError}
+   * Empty property for compatibility with {@link GraffitiObjectStreamError}
    */
   error?: undefined;
   /**
@@ -340,25 +274,13 @@ export interface GraffitiObjectStreamContinueTombstone {
   tombstone: true;
   /**
    * Sparse metadata about the deleted object. The full object is not returned
-   * to respect a user's privacy.
+   * to respect an actor's privacy.
    */
   object: {
     /**
      * The {@link GraffitiObjectBase.url | `url`} of the deleted object.
      */
     url: string;
-    /**
-     * The time at which the object was deleted, comparable to
-     * {@link GraffitiObjectBase.lastModified | `lastModified`}.
-     *
-     * While it is not possible to re-{@link Graffiti.put | put} objects that have been
-     * {@link Graffiti.delete | deleted}, objects may appear deleted if
-     * an {@link GraffitiObjectBase.actor | `actor`} is no longer
-     * {@link GraffitiObjectBase.allowed | `allowed`} to access them.
-     * Therefore the {@link GraffitiObjectBase.lastModified | `lastModified`} property
-     * is necessary to compare object versions.
-     */
-    lastModified: number;
   };
 }
 
@@ -377,7 +299,7 @@ export type GraffitiObjectStreamContinueEntry<Schema extends JSONSchema> =
  * that allows the stream to be continued from where it left off.
  *
  * The {@link continue} function preserves the typing of the original stream,
- * where as the {@link cursor} string can be serialized for use after a user
+ * where as the {@link cursor} string can be serialized for use after a person
  * has closed and reopened an application.
  *
  * The continued stream may include `tombstone`s of objects that have been
@@ -396,7 +318,7 @@ export interface GraffitiObjectStreamReturn<Schema extends JSONSchema> {
   continue: () => GraffitiObjectStreamContinue<Schema>;
   /**
    * A string that can be serialized and stored to resume the stream later.
-   * It must be passed to the {@link Graffiti.continueObjectStream} method
+   * It must be passed to the {@link Graffiti.continueDiscover} method
    * to resume the stream.
    */
   cursor: string;
@@ -405,7 +327,7 @@ export interface GraffitiObjectStreamReturn<Schema extends JSONSchema> {
 /**
  * A continutation of the {@link GraffitiObjectStream} type, as returned by
  * the {@link GraffitiObjectStreamReturn.continue} or by using
- * {@link GraffitiObjectStreamReturn.cursor} with {@link Graffiti.continueObjectStream}.
+ * {@link GraffitiObjectStreamReturn.cursor} with {@link Graffiti.continueDiscover}.
  *
  * The continued stream may include `tombstone`s of objects that have been
  * deleted since the original stream was run. See {@link GraffitiObjectStreamContinueTombstone}.
@@ -414,48 +336,13 @@ export interface GraffitiObjectStreamReturn<Schema extends JSONSchema> {
  */
 export type GraffitiObjectStreamContinue<Schema extends JSONSchema> =
   AsyncGenerator<
-    GraffitiStreamError | GraffitiObjectStreamContinueEntry<Schema>,
+    GraffitiObjectStreamError | GraffitiObjectStreamContinueEntry<Schema>,
     GraffitiObjectStreamReturn<Schema>
   >;
 
-/**
- * Statistic about single channel returned by {@link Graffiti.channelStats}.
- * These statistics only account for contributions made by the
- * querying actor.
- */
-export type ChannelStats = {
-  /**
-   * The URI of the channel.
-   */
-  channel: string;
-  /**
-   * The number of objects that the actor has {@link Graffiti.put | put}
-   * and not {@link Graffiti.delete | deleted} in the channel.
-   */
-  count: number;
-  /**
-   * The time that the actor {@link GraffitiObjectBase.lastModified | last modified} an object in the channel,
-   * measured in milliseconds since January 1, 1970.
-   * {@link Graffiti.delete | Deleted} objects do not effect this modification time.
-   */
-  lastModified: number;
-};
-
-/**
- * A stream of data that are returned by Graffiti's {@link Graffiti.channelStats} method.
- * See {@link GraffitiObjectStream} for more information on streams.
- */
-export type GraffitiChannelStatsStream = AsyncGenerator<
-  | GraffitiStreamError
-  | {
-      error?: undefined;
-      value: ChannelStats;
-    }
->;
-
 /**
  * The event type produced in {@link Graffiti.sessionEvents}
- * when a user logs in manually from {@link Graffiti.login}
+ * when a actor logs in manually from {@link Graffiti.login}
  * or when their session is restored from a previous login.
  * The event name to listen for is `login`.
  */
@@ -472,7 +359,7 @@ export type GraffitiLoginEvent = CustomEvent<
 
 /**
  * The event type produced in {@link Graffiti.sessionEvents}
- * when a user logs out either manually with {@link Graffiti.logout}
+ * when a actor logs out either manually with {@link Graffiti.logout}
  * or when their session times out or otherwise becomes invalid.
  * The event name to listen for is `logout`.
  */
@@ -495,8 +382,8 @@ export type GraffitiLogoutEvent = CustomEvent<
  * their own {@link GraffitiLoginEvent} events.
  *
  * This event optionally returns an `href` property
- * representing the URL the user originated a login request
- * from, which may be useful for redirecting the user back to
+ * representing the URL that originated a login request,
+ * which may be useful for redirecting the user back to
  * the page they were on after login.
  * The event name to listen for is `initialized`.
  */

package/src/3-errors.ts

@@ -38,19 +38,19 @@ export class GraffitiErrorSchemaMismatch extends Error {
   }
 }
 
-export class GraffitiErrorPatchTestFailed extends Error {
+export class GraffitiErrorTooLarge extends Error {
   constructor(message?: string) {
     super(message);
-    this.name = "GraffitiErrorPatchTestFailed";
-    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);
+    this.name = "GraffitiErrorTooLarge";
+    Object.setPrototypeOf(this, GraffitiErrorTooLarge.prototype);
   }
 }
 
-export class GraffitiErrorPatchError extends Error {
+export class GraffitiErrorNotAcceptable extends Error {
   constructor(message?: string) {
     super(message);
-    this.name = "GraffitiErrorPatchError";
-    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);
+    this.name = "GraffitiErrorNotAcceptable";
+    Object.setPrototypeOf(this, GraffitiErrorNotAcceptable.prototype);
   }
 }