@paulhectork/aiiinotate 0.12.0

package/src/fixtures/data/vhs_wit253_man253_anno253_anno-24.json

@@ -0,0 +1 @@
+{"@type": "sc:AnnotationList", "resources": [{"@id": "http://iscd.huma-num.fr/sas/annotation/wit253_man253_anno253_c24_b2204564e1d74023bc38cbd2906e137b", "@type": "oa:Annotation", "dcterms:created": "2025-09-09T11:42:43", "dcterms:modified": "2025-09-09T11:42:43", "resource": [{"@type": "dctypes:Text", "https://iscd.huma-num.fr/sas/full_text": "", "format": "text/html", "chars": "<p></p>"}], "on": [{"@type": "oa:SpecificResource", "within": {"@id": "https://iscd.huma-num.fr/vhs/iiif/v2/wit253_man253_anno253/manifest.json", "@type": "sc:Manifest"}, "selector": {"@type": "oa:Choice", "default": {"@type": "oa:FragmentSelector", "value": "xywh=212,381,1021,1610"}, "item": {"@type": "oa:SvgSelector", "value": "<svg xmlns=\"http://www.w3.org/2000/svg\"><path xmlns='http://www.w3.org/2000/svg' d='M212 381 h 510 v 0 h 510 v 805 v 805 h -510 h -510 v -805Z' id='rectangle_wit253_man253_anno253_c24_b2204564e1d74023bc38cbd2906e137b' data-paper-data='{&quot;strokeWidth&quot;:1,&quot;rotation&quot;:0,&quot;annotation&quot;:null,&quot;nonHoverStrokeColor&quot;:[&quot;Color&quot;,0,1,0],&quot;editable&quot;:true,&quot;deleteIcon&quot;:null,&quot;rotationIcon&quot;:null,&quot;group&quot;:null}' fill-opacity='0' fill='#00ff00' fill-rule='nonzero' stroke='#00ff00' stroke-width='1' stroke-linecap='butt' stroke-linejoin='miter' stroke-miterlimit='10' stroke-dashoffset='0' style='mix-blend-mode: normal'/></svg>"}}, "full": "https://iscd.huma-num.fr/vhs/iiif/v2/wit253_man253_anno253/canvas/c24.json"}], "motivation": ["oa:commenting", "oa:tagging"], "@context": "http://iiif.io/api/presentation/2/context.json"}]}

package/src/fixtures/generate.js

@@ -0,0 +1,181 @@
+import { v4 as uuid4 } from "uuid";
+
+import { getRandomItem } from "#utils/utils.js";
+import { PUBLIC_URL } from "#constants";
+
+/**
+ * generate an array of length `length` filled with values returned by `itemFunc`
+ * @param {number} length
+ * @param {Function} itemFunc
+ * @returns {Array}
+ */
+const fillArray = (length, itemFunc) =>
+  Array.from({ length: length }, itemFunc)
+
+/** @returns {string} - matches "int,int,int.int" */
+const makeXywh = () =>
+  fillArray(4, () => Math.floor(Math.random() * 1000))
+    .sort()
+    .join(",");
+
+const makeRandomNumber = (maxNum=1000) => Math.floor(Math.random() * maxNum);
+
+const makeManifestShortId = () =>
+  `wit${makeRandomNumber()}_pdf${makeRandomNumber()}_anno${makeRandomNumber()}`;
+
+const makeBaseUrl = (manifestShortId) =>
+  `${PUBLIC_URL}/data/2/${manifestShortId}`;
+
+const makeAnnotationId = (manifestShortId) =>
+  `${makeBaseUrl(manifestShortId)}/annotation/a_${uuid4()}`;
+
+const makeManifestId = (manifestShortId) =>
+  `${makeBaseUrl(manifestShortId)}/manifest.json`;
+
+const makeCanvasId = (manifestShortId) =>
+  `${makeBaseUrl(manifestShortId)}/canvas/c_${uuid4()}`;
+
+const makeAnnotationListId = (manifestShortId) =>
+  `${makeBaseUrl(manifestShortId)}/list/l_${uuid4()}`;
+
+const makeIiif2Manifest = (manifestShortId, canvasArray) => ({
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@id": makeManifestId(manifestShortId),
+  "label": "test aiiinotate manifest",
+  "attribution": "",
+  "seeAlso": [
+    "http://oai.bnf.fr/oai2/OAIHandler?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:bnf.fr:gallica/ark:/12148/btv1b8490076p"
+  ],
+  "description": "this is a test IIIF manifest for aiiinotate testing purposes",
+  "metadata": [],
+  "sequences": [
+    {
+      "canvases": canvasArray,
+      "label": "Current Page Order",
+      "@type": "sc:Sequence",
+      "@id": `${makeManifestId(manifestShortId)}/sequence/default`
+    }
+  ],
+  "thumbnail": {
+    "@id": "https://gallica.bnf.fr/ark:/12148/btv1b8490076p.thumbnail"
+  },
+  "@type": "sc:Manifest",
+})
+
+const makeIiif2Canvas = (canvasId) => ({
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@id": canvasId,
+  "label": "plat supérieur",
+  "height": 6044,
+  "width": 4768,
+  "images": [
+    {
+      "motivation": "sc:painting",
+      "on": canvasId,
+      "resource": {
+        "format": "image/jpeg",
+        "service": {
+          "profile": "http://library.stanford.edu/iiif/image-api/1.1/compliance.html#level2",
+          "@context": "http://iiif.io/api/image/1/context.json",
+          "@id": `${canvasId}_img.png`
+        },
+        "height": 6044,
+        "width": 4768,
+        "@id": `${canvasId}_img.png/full/full/0/native.jpg`,
+        "@type": "dctypes:Image"
+      },
+      "@type": "oa:Annotation"
+    }
+  ],
+  "@type": "sc:Canvas"
+})
+
+const makeIiif2AnnotationList = (manifestShortId, annotationArray) => ({
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@type": "sc:AnnotationList",
+  "@id": makeAnnotationListId(manifestShortId),
+  "resources": annotationArray
+})
+
+const makeIiif2Annotation = (annotationId, canvasId) => ({
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@id": annotationId,
+  "@type": "oa:Annotation",
+  "resource": {
+    "@type": "dctypes:Text",
+    "format": "text/html",
+    "chars": ""
+  },
+  "on": `${canvasId}#xywh=${makeXywh()}`,
+  "motivation": [
+    "oa:tagging",
+    "oa:commenting"
+  ],
+  "label": ""
+})
+
+/**
+ * @param {string} manifestShortId
+ * @param {string[]} canvasIdArray
+ * @returns {object}
+ */
+const generateIiif2AnnotationList = (manifestShortId, canvasIdArray) =>
+  makeIiif2AnnotationList(
+    canvasIdArray.map((canvasId) =>
+      makeIiif2Annotation(
+        makeAnnotationId(manifestShortId),
+        canvasId
+      )
+    )
+  );
+
+
+/**
+ * @param {number} nCanvas - integer, number of canvases in the manifest
+ * @returns {object}
+ */
+const generateIiif2Manifest = (nCanvas) => {
+  const manifestShortId = makeManifestShortId();
+  return makeIiif2Manifest(
+    manifestShortId,
+    fillArray(nCanvas, () => makeCanvasId(manifestShortId))
+      .map((canvasId) => makeIiif2Canvas(canvasId))
+  )
+}
+
+/**
+ * return an array of [manifest, annotationList].
+ * manifest has `nCanvas` canvases, `annotationList` has `nAnnotations` annotation on the canvases of the generated manifest.
+ * @param {number} nCanvas
+ * @param {number} nAnnotations
+ * @returns
+ */
+const generateIiif2ManifestAndAnnotationsList = (nCanvas, nAnnotations) => {
+  const
+    manifestShortId = makeManifestShortId(),
+    manifest = makeIiif2Manifest(
+      manifestShortId,
+      fillArray(nCanvas, () => makeCanvasId(manifestShortId))
+        .map((canvasId) => makeIiif2Canvas(canvasId))
+    ),
+    canvasArray = fillArray(
+      nAnnotations,
+      () => getRandomItem(manifest.sequences[0].canvases)
+    ).map((canvas) =>
+      makeIiif2Annotation(
+        makeAnnotationId(manifestShortId),
+        canvas["@id"]
+      )
+    ),
+    annotationList = makeIiif2AnnotationList(
+      manifestShortId, canvasArray
+    );
+
+  return [ manifest, annotationList ];
+}
+
+export {
+  generateIiif2Manifest,
+  generateIiif2AnnotationList,
+  generateIiif2ManifestAndAnnotationsList
+}

package/src/fixtures/index.js

@@ -0,0 +1,69 @@
+/**
+ * the `fixtures` plugin makes test files available to the entire fastify app, mostly for testing purposes.
+ */
+import fastifyPlugin from "fastify-plugin";
+
+import { annotations2Invalid, annotations2Valid, annotations2SvgValid, annotationListUri, annotationListUriArray, annotationList, annotationListArray, annotationListUriInvalid, annotationListUriArrayInvalid } from "#src/fixtures/annotations.js";
+import { manifest2Valid, manifest2ValidUri, manifest2Invalid, manifest2InvalidUri } from "#fixtures/manifests.js";
+import { generateIiif2Manifest, generateIiif2AnnotationList, generateIiif2ManifestAndAnnotationsList } from "#fixtures/generate.js";
+import { readFileToObject } from "#fixtures/utils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+
+/**
+ * NOTE: `done` musn't be used with async plugins. it raises an error `FST_ERR_PLUGIN_INVALID_ASYNC_HANDLER`
+ * @param {FastifyInstanceType} fastify  Encapsulated Fastify Instance
+ * @param {object} options
+ */
+async function fixtures(fastify, options) {
+
+  /** route to return a file in `dataDir` */
+  fastify.get(
+    "/fixtures/:fileName",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: { fileName: { type: "string" } }
+        }
+      },
+      response: {
+        200: {
+          type: "string"
+        },
+        500: {
+          type: "object",
+          properties: {
+            error: { type: "string" }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      const { fileName } = request.params;
+      return readFileToObject(fileName);
+    }
+  )
+
+  fastify.decorate("fixtures", {
+    annotations2SvgValid: annotations2SvgValid,
+    annotationListUri: annotationListUri,
+    annotationListUriArray: annotationListUriArray,
+    annotationList: annotationList,
+    annotationListArray: annotationListArray,
+    annotationListUriArrayInvalid: annotationListUriArrayInvalid,
+    annotationListUriInvalid: annotationListUriInvalid,
+    annotations2Invalid: annotations2Invalid,
+    annotations2Valid: annotations2Valid,
+    manifest2Valid: manifest2Valid,
+    manifest2ValidUri: manifest2ValidUri,
+    manifest2Invalid: manifest2Invalid,
+    manifest2InvalidUri: manifest2InvalidUri,
+    generateIiif2Manifest: generateIiif2Manifest,
+    generateIiif2AnnotationList: generateIiif2AnnotationList,
+    generateIiif2ManifestAndAnnotationsList: generateIiif2ManifestAndAnnotationsList
+  });
+}
+
+export default fastifyPlugin(fixtures);

package/src/fixtures/manifests.js

@@ -0,0 +1,14 @@
+import { readFileToObject, toUrl } from "#fixtures/utils.js";
+
+const manifest2ValidUri = { uri: toUrl("bnf_valid_manifest.json") };
+const manifest2Valid = readFileToObject("bnf_valid_manifest.json");
+const manifest2InvalidUri = { uri: toUrl("bnf_invalid_manifest.json") };
+const manifest2Invalid = readFileToObject("bnf_invalid_manifest.json");
+
+
+export {
+  manifest2ValidUri,
+  manifest2Valid,
+  manifest2InvalidUri,
+  manifest2Invalid
+}

package/src/fixtures/utils.js

@@ -0,0 +1,37 @@
+import url from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+import { BASE_URL } from "#constants";
+
+// path to dirctory of curent file
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+// path to fixtures/data
+const dataDir = path.join(__dirname, "data");
+
+const availableFiles = fs.readdirSync(dataDir);
+
+/**
+ * for simplicity, `readFileToObject` is synchronous. given that `fixtures` should only be used in tests, there is no performance downgrade for the prod server.
+ * @param {string} fn: the filename
+ * @returns {object}
+ */
+const readFileToObject = (fn) => {
+  if (!availableFiles.includes(fn)) {
+    throw new Error(`file not found: ${fn}`);
+  }
+  return JSON.parse(fs.readFileSync(path.join(dataDir, fn), { encoding: "utf8" }));
+}
+
+/**
+ * @param {string} fn
+ * @returns {string}
+ */
+const toUrl = (fn) => `${BASE_URL}/fixtures/${fn}`;
+
+
+export {
+  dataDir,
+  readFileToObject,
+  toUrl
+}

package/src/schemas/index.js

@@ -0,0 +1,100 @@
+import fastifyPlugin from "fastify-plugin";
+
+import addSchemasBase from "#schemas/schemasBase.js";
+import addSchemasPresentation3 from "#schemas/schemasPresentation3.js";
+import addSchemasPresentation2 from "#src/schemas/schemasPresentation2.js";
+import addSchemasRoutes from "#schemas/schemasRoutes.js";
+import schemasResolver from "#schemas/schemasResolver.js";
+import { PUBLIC_URL } from "#constants";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").FastifySchemaType} FastifySchemaType */
+
+/**
+ * NOTE : how are schemas managed in aiiinotate ?
+ * we implement "namespaced schemas" (aka, schemas grouped together in a single fastify decorator).
+ *
+ * TLDR: schemas are added to the global fastify instance, but their IDs are namespaced;
+ * schemas they are then accessed through decorators, each decorator is used to resolve annotations
+ * within a namespace.
+ *
+ * @example
+ *  > fastify.schemasPresentation2.getSchema("annotations") =>
+ *  > // resolves to
+ *  > fastify.getSchema("$PUBLIC_URL/schemas/schemasPresentation2/annotation")
+ *
+ * IN MORE DETAIL:
+ * - namespacing is done through the IDs of the schemas, defined on `fastify.addSchema` and used
+ *    to retrieve a schema with `fastify.getSchema()`
+ * - the global schema ID anatomy is defined here, in `_makeSchemaUri`: it's an URI that
+ *    accepts a "namespace". each schema has a unique `slug` appended to the end of the URI.
+ * - each file in this module (appart from `schemasResolver` and this file) exports
+ *    an `addSchemas` function that adds schemas to the global fastify instance with
+ *    a specific namespace.
+ * - then, a decorator is added to the fastify instance for each namespace. it adds 2 functions
+ *    `getSchema` and `makeSchemaUri` that are used to resolve schemas names and to access
+ *    all schemas within a certain namespace.
+ * - thanks to that, schemas can be accessed by their unique slug with the pattern:
+ *   `fastify.$schemaNamespace.getSchema($schemaSlug)`.
+ * - schemas defined here are accessible in the entire fastify app.
+ */
+
+/**
+ * @type {(namespace: string) => (slug: string) => string}
+ */
+const _makeSchemaUri = (namespace) =>
+  (slug) => `${PUBLIC_URL}/schemas/${namespace}/${slug}`;
+
+/**
+ * @type {(fastify: FastifyInstanceType, namespace: string) => (slug: string) => FastifySchemaType}
+ */
+const _getSchema = (fastify, namespace) =>
+  (slug) => fastify.getSchema(_makeSchemaUri(namespace)(slug));
+
+/**
+ * decorate fastify with namespaced schemas
+ * @param {FastifyInstanceType} fastify
+ * @param {{ namespace: string, addSchemasFunc: Function }} options
+ */
+const addSchemasDecorator = (fastify, options) => {
+  if (!(options.namespace || "").length) {
+    throw new Error(`addSchemasDecorator requires options.namespace to be set ! Got '${options.namespace}'`);
+  }
+  if (!options.addSchemasFunc || typeof options.addSchemasFunc !== "function") {
+    throw new Error(`addSchemasDecorator requires options.addSchemasFunc to be a function ! Got '${options.addSchemasFunc}'`)
+  }
+
+  const
+    { namespace, addSchemasFunc } = options,
+    makeSchemaUri = _makeSchemaUri(namespace),
+    getSchema = _getSchema(fastify, namespace);
+
+  fastify = addSchemasFunc(fastify, makeSchemaUri);
+  fastify.decorate(namespace, {
+    makeSchemaUri: makeSchemaUri,
+    getSchema: getSchema
+  })
+}
+
+function schemas(fastify, options, done) {
+
+  const schemasData = [
+    [ "schemasPresentation2", addSchemasPresentation2 ],
+    [ "schemasPresentation3", addSchemasPresentation3 ],
+    [ "schemasBase", addSchemasBase ],
+    [ "schemasRoutes", addSchemasRoutes ],
+  ]
+
+  fastify.register(schemasResolver);
+
+  for (let [ schemasNamespace, addSchemasFunc ] of schemasData) {
+    addSchemasDecorator(fastify, {
+      namespace: schemasNamespace,
+      addSchemasFunc: addSchemasFunc,
+    })
+  }
+
+  done()
+}
+
+export default fastifyPlugin(schemas);

package/src/schemas/schemasBase.js

@@ -0,0 +1,19 @@
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+function addSchemas(fastify, makeSchemaUri) {
+  fastify.addSchema({
+    $id: makeSchemaUri("presentation"),
+    type: "integer",
+    enum: [ 2, 3 ],
+    description: "IIIF presentation API versions"
+  });
+  fastify.addSchema({
+    $id: makeSchemaUri("search"),
+    type: "integer",
+    enum: [ 1, 2 ],
+    description: "IIIF search API versions"
+  });
+  return fastify
+}
+
+export default addSchemas;