@graffiti-garden/api 1.0.2 → 1.0.4

package/src/1-api.ts

@@ -6,6 +6,9 @@ import type {
   GraffitiPostObject,
   GraffitiObjectStream,
   GraffitiObjectStreamContinue,
+  GraffitiMedia,
+  GraffitiPostMedia,
+  GraffitiMediaAccept,
 } from "./2-types";
 import type { JSONSchema } from "json-schema-to-ts";
 
@@ -150,6 +153,8 @@ export abstract class Graffiti {
    *
    * @throws {@link GraffitiErrorSchemaMismatch} if the retrieved object does not match the provided schema.
    *
+   * @throws {@link GraffitiErrorInvalidSchema} If an invalid schema is provided.
+   *
    * @group 1 - Single-Object Methods
    */
   abstract get<Schema extends JSONSchema>(
@@ -194,7 +199,7 @@ export abstract class Graffiti {
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session: GraffitiSession,
-  ): Promise<void>;
+  ): Promise<GraffitiObjectBase>;
 
   /**
    * Discovers objects created by any actor that are contained
@@ -223,6 +228,9 @@ export abstract class Graffiti {
    * Since different implementations may fetch data from multiple sources there is
    * no guarentee on the order that objects are returned in.
    *
+   * @throws {@link GraffitiErrorInvalidSchema} if an invalid schema is provided.
+   * Discovery is lazy and will not throw until the iterator is consumed.
+   *
    * @returns Returns a stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
    * and [JSON Schema](https://json-schema.org).
    *
@@ -263,7 +271,11 @@ export abstract class Graffiti {
    * instead, which is returned along with the `cursor` at the
    * end of the original stream.
    *
-   * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
+   * @throws {@link GraffitiErrorNotFound} upon iteration
+   * if the cursor is invalid or expired.
+   *
+   * @throws {@link GraffitiErrorForbidden} upon iteration
+   * if the {@link GraffitiObjectBase.actor | `actor`}
    * provided in the `session` is not the same as the `actor`
    * that initiated the original stream.
    *
@@ -286,24 +298,12 @@ export abstract class Graffiti {
    * @group 3 - Media Methods
    */
   abstract postMedia(
-    media: {
-      /**
-       * The binary data of the media to be uploaded,
-       * along with its [media type](https://www.iana.org/assignments/media-types/media-types.xhtml),
-       * formatted as a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
-       */
-      data: Blob;
-      /**
-       * An optional list, identical in function to an object's
-       * {@link GraffitiObjectBase.allowed | `allowed`} property,
-       * that specifies the {@link GraffitiObjectBase.actor | `actor`}s
-       * who are allowed to access the media. If the list is `undefined`
-       * or `null`, anyone with the URL can access the media. If the list
-       * is empty, only the {@link GraffitiObjectBase.actor | `actor`}
-       * who {@link postMedia | `post`ed} the media can access it.
-       */
-      allowed?: string[] | null;
-    },
+    /**
+     * The media data to upload, and optionally
+     * an {@link GraffitiObjectBase.allowed | `allowed`}
+     * list of actors that can view it.
+     */
+    media: GraffitiPostMedia,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
@@ -326,7 +326,7 @@ export abstract class Graffiti {
     /**
      * A globally unique identifier and locator for the media.
      */
-    mediaUrl: string,
+    url: string,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
@@ -355,29 +355,15 @@ export abstract class Graffiti {
      */
     mediaUrl: string,
     /**
-     * A set of requirements the retrieved media must meet.
+     * A specification for what types and sizes of media are acceptable.
      */
-    requirements: {
-      /**
-       * A list of acceptable media types for the retrieved media,
-       * formatted as like an [HTTP Accept header](https://httpwg.org/specs/rfc9110.html#field.accept)
-       */
-      accept?: string;
-      /**
-       * The maximum acceptable size, in bytes, of the media.
-       */
-      maxBytes?: number;
-    },
+    accept: GraffitiMediaAccept,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
     session?: GraffitiSession | null,
-  ): Promise<{
-    data: Blob;
-    actor: string;
-    allowed?: string[] | null;
-  }>;
+  ): Promise<GraffitiMedia>;
 
   /**
    * Begins the login process. Depending on the implementation, this may

package/src/2-types.ts

@@ -350,7 +350,7 @@ export type GraffitiObjectStreamContinue<Schema extends JSONSchema> =
 export type GraffitiLoginEvent = CustomEvent<
   | {
       error: Error;
-      session?: undefined;
+      session?: GraffitiSession;
     }
   | {
       error?: undefined;
@@ -396,3 +396,43 @@ export type GraffitiSessionInitializedEvent = CustomEvent<
   | null
   | undefined
 >;
+
+export type GraffitiMedia = {
+  /**
+   * The binary data of the media to be uploaded,
+   * along with its [media type](https://www.iana.org/assignments/media-types/media-types.xhtml),
+   * formatted as a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+   */
+  data: Blob;
+  /**
+   * The {@link GraffitiObjectBase.actor | `actor`} that
+   * {@link Graffiti.postMedia | `post`ed} the media.
+   */
+  actor: string;
+  /**
+   * An optional list, identical in function to an object's
+   * {@link GraffitiObjectBase.allowed | `allowed`} property,
+   * that specifies the {@link GraffitiObjectBase.actor | `actor`}s
+   * who are allowed to access the media. If the list is `undefined`
+   * or `null`, anyone with the URL can access the media. If the list
+   * is empty, only the {@link GraffitiObjectBase.actor | `actor`}
+   * who {@link Graffiti.postMedia | `post`ed} the media can access it.
+   */
+  allowed?: string[] | null;
+};
+
+export type GraffitiPostMedia = Pick<GraffitiMedia, "data" | "allowed">;
+
+export type GraffitiMediaAccept = {
+  /**
+   * A list of acceptable media types for the retrieved media.
+   * Each type in the list may be of the form `<type>/<subtype>`,
+   * `<type>/*`, or `&#42;/*`, just as types are formatted in
+   * an [HTTP Accept header](https://httpwg.org/specs/rfc9110.html#field.accept).
+   */
+  types?: string[];
+  /**
+   * The maximum acceptable size, in bytes, of the media.
+   */
+  maxBytes?: number;
+};

package/src/4-utilities.ts

@@ -1,9 +1,5 @@
-import type { JSONSchema } from "json-schema-to-ts";
-import type { Ajv } from "ajv";
-import { GraffitiErrorInvalidSchema } from "./3-errors";
 import type {
   GraffitiObjectBase,
-  GraffitiObject,
   GraffitiObjectUrl,
   GraffitiSession,
 } from "./2-types";
@@ -12,25 +8,6 @@ export function unpackObjectUrl(url: string | GraffitiObjectUrl) {
   return typeof url === "string" ? url : url.url;
 }
 
-export function compileGraffitiObjectSchema<Schema extends JSONSchema>(
-  ajv: Ajv,
-  schema: Schema,
-) {
-  try {
-    // Force the validation guard because
-    // it is too big for the type checker.
-    // Fortunately json-schema-to-ts is
-    // well tested against ajv.
-    return ajv.compile(schema) as (
-      data: GraffitiObjectBase,
-    ) => data is GraffitiObject<Schema>;
-  } catch (error) {
-    throw new GraffitiErrorInvalidSchema(
-      error instanceof Error ? error.message : undefined,
-    );
-  }
-}
-
 export function isActorAllowedGraffitiObject(
   object: GraffitiObjectBase,
   session?: GraffitiSession | null,
@@ -50,16 +27,43 @@ export function isActorAllowedGraffitiObject(
 export function maskGraffitiObject(
   object: GraffitiObjectBase,
   channels: string[],
-  session?: GraffitiSession | null,
-): void {
-  // If the actor is not the creator, mask the object.
-  if (object.actor !== session?.actor) {
-    // If there is an allowed list, mask it to only include the actor
-    // (This assumes the actor is already allowed to access the object)
-    object.allowed = object.allowed && session ? [session.actor] : undefined;
-    // Mask the channels to only include the channels that are being queried
-    object.channels = object.channels.filter((channel) =>
-      channels.includes(channel),
+  actor?: string | null,
+): GraffitiObjectBase {
+  // If the actor is the creator, return the object as is
+  if (actor === object.actor) return object;
+
+  // If there is an allowed list, mask it to only include the actor
+  // (This assumes the actor is already allowed to access the object)
+  const allowedMasked = object.allowed && actor ? [actor] : undefined;
+  // Mask the channels to only include the channels that are being queried
+  const channelsMasked = object.channels.filter((c) => channels.includes(c));
+
+  return {
+    ...object,
+    allowed: allowedMasked,
+    channels: channelsMasked,
+  };
+}
+
+export function isMediaAcceptable(
+  mediaType: string,
+  acceptableMediaTypes: string[],
+): boolean {
+  const [type, subtype] = mediaType.toLowerCase().split(";")[0].split("/");
+
+  if (!type || !subtype) return false;
+
+  return acceptableMediaTypes.some((acceptable) => {
+    const [accType, accSubtype] = acceptable
+      .toLowerCase()
+      .split(";")[0]
+      .split("/");
+
+    if (!accType || !accSubtype) return false;
+
+    return (
+      (accType === type || accType === "*") &&
+      (accSubtype === subtype || accSubtype === "*")
     );
-  }
+  });
 }

package/tests/crud.ts

@@ -34,6 +34,12 @@ export const graffitiCRUDTests = (
         session2 = await useSession2();
       });
 
+      it("get nonexistant object", async () => {
+        await expect(graffiti.get(randomString(), {})).rejects.toThrow(
+          GraffitiErrorNotFound,
+        );
+      });
+
       it("post, get, delete", async () => {
         const value = {
           something: "hello, world~ c:",
@@ -56,7 +62,12 @@ export const graffitiCRUDTests = (
         expect(gotten.actor).toEqual(previous.actor);
 
         // Delete it
-        await graffiti.delete(gotten, session);
+        const deleted = await graffiti.delete(gotten, session);
+        expect(deleted.value).toEqual(value);
+        expect(deleted.channels).toEqual(channels);
+        expect(deleted.allowed).toBeUndefined();
+        expect(deleted.actor).toEqual(session.actor);
+        expect(deleted.url).toEqual(previous.url);
 
         // Get is not found
         await expect(graffiti.get(gotten, {})).rejects.toBeInstanceOf(

package/tests/discover.ts

@@ -1,10 +1,14 @@
 import { it, expect, describe, assert, beforeAll } from "vitest";
 import type {
   Graffiti,
-  GraffitiObjectBase,
   GraffitiSession,
   JSONSchema,
 } from "@graffiti-garden/api";
+import {
+  GraffitiErrorForbidden,
+  GraffitiErrorInvalidSchema,
+  GraffitiErrorNotFound,
+} from "@graffiti-garden/api";
 import {
   randomString,
   nextStreamValue,
@@ -103,6 +107,19 @@ export const graffitiDiscoverTests = (
       expect(value.actor).toEqual(session1.actor);
     });
 
+    it("discover bad schema", async () => {
+      const iterator = graffiti.discover([], {
+        properties: {
+          value: {
+            //@ts-ignore
+            type: "asdf",
+          },
+        },
+      });
+
+      await expect(iterator.next()).rejects.toThrow(GraffitiErrorInvalidSchema);
+    });
+
     it("discover for actor", async () => {
       const object1 = randomPostObject();
       const posted1 = await graffiti.post<{}>(object1, session1);
@@ -396,12 +413,47 @@ export const graffitiDiscoverTests = (
           assert(!value.done && !value.value.error, "value is done");
           assert(value.value.tombstone, "value is not tombstone");
           expect(value.value.object.url).toEqual(posted.url);
-          await expect(tombIterator.next()).resolves.toHaveProperty(
+          const returnValue2 = await tombIterator.next();
+          assert(returnValue2.done, "value2 is not done");
+
+          // Post another object
+          const posted2 = await graffiti.post<{}>(object, session);
+          const doubleContinueIterator = continueStream<{}>(
+            graffiti,
+            returnValue2.value,
+            continueType,
+          );
+          const value2 = await doubleContinueIterator.next();
+          assert(!value2.done && !value2.value.error, "value2 is done");
+          assert(!value2.value.tombstone, "value2 is tombstone");
+          expect(value2.value.object.url).toEqual(posted2.url);
+          await expect(doubleContinueIterator.next()).resolves.toHaveProperty(
             "done",
             true,
           );
         });
+
+        it("continue with wrong actor", async () => {
+          const iterator = graffiti.discover<{}>([], {}, session1);
+          const result = await iterator.next();
+          assert(result.done, "iterator is not done");
+
+          const continuation = continueStream<{}>(
+            graffiti,
+            result.value,
+            continueType,
+            session2,
+          );
+          await expect(continuation.next()).rejects.toThrow(
+            GraffitiErrorForbidden,
+          );
+        });
       });
     }
+
+    it("lookup non-existant cursor", async () => {
+      const iterator = graffiti.continueDiscover(randomString());
+      await expect(iterator.next()).rejects.toThrow(GraffitiErrorNotFound);
+    });
   });
 };

package/tests/media.ts

@@ -58,7 +58,7 @@ export const graffitiMediaTests = (
         const mediaUrl = await graffiti.postMedia({ data }, session);
 
         const media = await graffiti.getMedia(mediaUrl, {
-          accept: "text/*",
+          types: ["application/json", "text/*"],
         });
         expect(await media.data.text()).toEqual(text);
         expect(media.data.type).toEqual("text/plain");
@@ -73,7 +73,7 @@ export const graffitiMediaTests = (
 
         await expect(
           graffiti.getMedia(mediaUrl, {
-            accept: "image/*",
+            types: ["image/*"],
           }),
         ).rejects.toThrow(GraffitiErrorNotAcceptable);
       });