cozy-iiif 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozy-iiif",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A developer-friendly collection of abstractions and utilities built on top of @iiif/presentation-3 and @iiif/parser",
   "license": "MIT",
   "author": "Rainer Simon",
@@ -24,6 +24,7 @@
   },
   "exports": {
     ".": "./dist/index.js",
+    "./helpers": "./dist/helpers/index.js",
     "./level-0": "./dist/level-0/index.js"
   },
   "devDependencies": {
@@ -34,6 +35,7 @@
   "dependencies": {
     "@iiif/parser": "^2.1.7",
     "@iiif/presentation-3": "^2.2.3",
-    "p-throttle": "^7.0.0"
+    "p-throttle": "^7.0.0",
+    "uuid": "^11.1.0"
   }
 }

package/src/Cozy.ts

@@ -21,123 +21,121 @@ import type {
   ImageServiceResource 
 } from './types';
 
-export const Cozy = {
-  
-  parseURL: async (input: string): Promise<CozyParseResult> => {
-    try {
-      new URL(input);
-    } catch {
-      return {
-        type: 'error',
-        code: 'INVALID_URL',
-        message: 'The provided input is not a valid URL'
-      };
-    }
+const parseURL = async (input: string): Promise<CozyParseResult> => {
+  try {
+    new URL(input);
+  } catch {
+    return {
+      type: 'error',
+      code: 'INVALID_URL',
+      message: 'The provided input is not a valid URL'
+    };
+  }
 
-    let response: Response;
+  let response: Response;
 
-    try {
-      response = await fetch(input);
-      if (!response.ok) {
-        return {
-          type: 'error',
-          code: 'INVALID_HTTP_RESPONSE',
-          message: `Server responded: HTTP ${response.status} ${response.statusText ? `(${response.statusText})` : ''}`
-        }
-      }
-    } catch (error) {
+  try {
+    response = await fetch(input);
+    if (!response.ok) {
       return {
         type: 'error',
-        code: 'FETCH_ERROR',
-        message: error instanceof Error ? error.message : 'Failed to fetch resource'
-      };
+        code: 'INVALID_HTTP_RESPONSE',
+        message: `Server responded: HTTP ${response.status} ${response.statusText ? `(${response.statusText})` : ''}`
+      }
     }
+  } catch (error) {
+    return {
+      type: 'error',
+      code: 'FETCH_ERROR',
+      message: error instanceof Error ? error.message : 'Failed to fetch resource'
+    };
+  }
 
-    const contentType = response.headers.get('content-type');
-    
-    if (contentType?.startsWith('image/')) {
-      return {
-        type: 'plain-image',
-        url: input
-      };
-    }
+  const contentType = response.headers.get('content-type');
+  
+  if (contentType?.startsWith('image/')) {
+    return {
+      type: 'plain-image',
+      url: input
+    };
+  }
 
-    if (contentType?.includes('text/html')) {
-      return {
-        type: 'webpage',
-        url: input
-      };
-    }
+  if (contentType?.includes('text/html')) {
+    return {
+      type: 'webpage',
+      url: input
+    };
+  }
 
-    try {
-      const json = await response.json();
-
-      const context = Array.isArray(json['@context'])
-        ? json['@context'].find(str => str.includes('iiif.io/api/'))
-        : json['@context'];
-
-      if (!context) {
-        return {
-          type: 'error',
-          code: 'INVALID_MANIFEST', 
-          message: 'Missing @context'
-        }
-      };
-
-      const id = getPropertyValue<string>(json, 'id');
-
-      if (!id) {
-        return { 
-          type: 'error',
-          code: 'INVALID_MANIFEST', 
-          message: 'Missing id property' 
-        }
-      }
+  try {
+    const json = await response.json();
+    return parse(json, input);
+  } catch {
+    return {
+      type: 'error',
+      code: 'UNSUPPORTED_FORMAT',
+      message: 'Could not parse resource'
+    };
+  }
+}
 
-      if (context.includes('presentation/2') || context.includes('presentation/3')) {
-        const majorVersion = context.includes('presentation/2') ? 2 : 3;
+const parse = (json: any, url?: string): CozyParseResult => {
+  const context = Array.isArray(json['@context'])
+    ? json['@context'].find(str => str.includes('iiif.io/api/'))
+    : json['@context'];
 
-        const type = getPropertyValue(json, 'type');
+  if (!context) {
+    return {
+      type: 'error',
+      code: 'INVALID_MANIFEST', 
+      message: 'Missing @context'
+    }
+  };
 
-        return type.includes('Collection') ? {
-          type: 'collection',
-          url: input,
-          resource: parseCollectionResource(json, majorVersion)
-        } : {
-          type: 'manifest',
-          url: input,
-          resource: parseManifestResource(json, majorVersion)
-        };
-      }
-      
-      if (context.includes('image/2') || context.includes('image/3')) {
-        const resource = parseImageResource(json);
-        return resource ? {
-          type: 'iiif-image',
-          url: input,
-          resource
-        } : {
-          type: 'error',
-          code: 'INVALID_MANIFEST',
-          message: 'Invalid image service definition'
-        }
-      }
+  const id = getPropertyValue<string>(json, 'id');
 
-      return {
-        type: 'error',
-        code: 'INVALID_MANIFEST',
-        message: 'JSON resource is not a recognized IIIF format'
-      };
-    } catch {
-      return {
-        type: 'error',
-        code: 'UNSUPPORTED_FORMAT',
-        message: 'Could not parse resource'
-      };
+  if (!id) {
+    return { 
+      type: 'error',
+      code: 'INVALID_MANIFEST', 
+      message: 'Missing id property' 
     }
+  }
+
+  if (context.includes('presentation/2') || context.includes('presentation/3')) {
+    const majorVersion = context.includes('presentation/2') ? 2 : 3;
+
+    const type = getPropertyValue(json, 'type');
 
+    return type.includes('Collection') ? {
+      type: 'collection',
+      url: url || id,
+      resource: parseCollectionResource(json, majorVersion)
+    } : {
+      type: 'manifest',
+      url: url || id,
+      resource: parseManifestResource(json, majorVersion)
+    };
+  }
+  
+  if (context.includes('image/2') || context.includes('image/3')) {
+    const resource = parseImageResource(json);
+    return resource ? {
+      type: 'iiif-image',
+      url: url || id,
+      resource
+    } : {
+      type: 'error',
+      code: 'INVALID_MANIFEST',
+      message: 'Invalid image service definition'
+    }
   }
 
+  return {
+    type: 'error',
+    code: 'INVALID_MANIFEST',
+    message: 'JSON resource is not a recognized IIIF format'
+  };
 }
 
 const parseCollectionResource = (resource: any, majorVersion: number): CozyCollection => {
@@ -194,6 +192,7 @@ const parseManifestResource = (resource: any, majorVersion: number): CozyManifes
         width: c.width,
         height: c.height,
         images,
+        annotations: (c.annotations || []),
         getLabel: getLabel(c),
         getMetadata: getMetadata(c),
         getThumbnailURL: getThumbnailURL(c, images)
@@ -259,4 +258,6 @@ const parseImageResource = (resource: any) => {
       serviceUrl: normalizeServiceUrl(getPropertyValue<string>(resource, 'id'))
     } as ImageServiceResource;
   }
-}
+}
+
+export const Cozy = { parse, parseURL };

package/src/helpers/import-annotations.ts

@@ -0,0 +1,115 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { Annotation } from '@iiif/presentation-3';
+import type { CozyCanvas, CozyManifest } from '../types';
+
+// Helper to escape special characters in strings used in RegExp
+const escapeRegExp = (str: string) =>
+  str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const getAnnotationPageId = (canvas: CozyCanvas, namespace?: string) => {
+  if (namespace) {
+    // Use naming convention `{canvas.id}/namespace/page/p{idx}`. This means we need
+    // to find the highest index currently in use. (Index starts with 1.)
+    const pages = canvas.annotations;
+    if (pages.length > 0) {
+      const pattern = new RegExp(`${escapeRegExp(canvas.id)}/${escapeRegExp(namespace)}/page/p(\\d+)$`);
+      
+      const highestIdx = pages.reduce<number>((highest, page) => {
+        const match = page.id.match(pattern);
+        if (match && match[1]) {
+          const thisIndex = parseInt(match[1]);
+          return Math.max(highest, thisIndex);
+        } else {
+          return highest;
+        }
+      }, 1);
+
+      return `${canvas.id}/${namespace}/annotations/page/p${highestIdx}`;
+    } else {
+      return `${canvas.id}/${namespace}/annotations/page/p1`;
+    }
+  } else {
+    // Use UUIDs as a fallback naming convention
+    return `${canvas.id}/annotations/page/${uuidv4()}`;
+  }
+}
+
+/** 
+ * Will blindy attach the annotations to this canvas.
+ */
+const importAnnotationsToCanvas = (canvas: CozyCanvas, annotations: Annotation[], namespace?: string) => {
+  const page = {
+    id: getAnnotationPageId(canvas, namespace),
+    type: 'AnnotationPage',
+    items: annotations
+  }
+
+  return {
+    source: {
+      ...canvas.source,
+      annotations: [...canvas.annotations, page]
+    },
+    id: canvas.id,
+    width: canvas.width,
+    height: canvas.height,
+    images: [...canvas.images],
+    annotations: [...canvas.annotations, page],
+    getLabel: canvas.getLabel,
+    getMetadata: canvas.getMetadata,
+    getThumbnailURL: canvas.getThumbnailURL
+  } as CozyCanvas;
+}
+
+/**
+ * Will use 'source' information from the annotation targets to associate annotations with the right
+ * canvases.
+ */
+const importAnnotationsToManifest = (manifest: CozyManifest, annotations: Annotation[], namespace?: string) => {
+  const getSource = (annotation: Annotation) => {
+    const target = annotation.target;
+    if (!target) return;
+
+    if (typeof target === 'string')
+      return target.substring(0, target.indexOf('#'));
+    else
+      return (target as any).source; 
+  }
+
+  const bySource = annotations.reduce<Record<string, Annotation[]>>((acc, annotation) => {
+    const source = getSource(annotation);
+    if (!source) return acc;
+    
+    if (!acc[source]) acc[source] = [];
+    acc[source].push(annotation);
+
+    return acc;
+  }, {});
+
+  const canvases = manifest.canvases.map(canvas => {
+    const toImport = bySource[canvas.id] || [];
+    return toImport.length > 0 ? importAnnotationsToCanvas(canvas, toImport, namespace) : canvas;
+  });
+
+  return {
+    source: {
+      ...manifest.source,
+      items: canvases.map(c => c.source)
+    },
+    id: manifest.id,
+    majorVersion: manifest.majorVersion,
+    canvases,
+    structure: manifest.structure,
+    getLabel: manifest.getLabel,
+    getMetadata: manifest.getMetadata,
+    getTableOfContents: manifest.getTableOfContents
+  }
+}
+
+export const importAnnotations = <T extends CozyManifest | CozyCanvas>(
+  resource: T, 
+  annotations: Annotation[], 
+  namespace?: string
+): T extends CozyCanvas ? CozyCanvas : CozyManifest =>
+  resource.source.type === 'Canvas' 
+    ? importAnnotationsToCanvas(resource as CozyCanvas, annotations, namespace) as T extends CozyCanvas ? CozyCanvas : CozyManifest
+    : importAnnotationsToManifest(resource as CozyManifest, annotations, namespace) as T extends CozyCanvas ? CozyCanvas : CozyManifest;

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './import-annotations';

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection, Range } from '@iiif/presentation-3';
+import type { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection, Range, Annotation, AnnotationPage } from '@iiif/presentation-3';
 
 export type CozyParseResult = 
   | { type: 'collection', url: string, resource: CozyCollection }
@@ -88,6 +88,8 @@ export interface CozyCanvas {
 
   readonly images: CozyImageResource[];
 
+  readonly annotations: AnnotationPage[];
+
   getLabel(locale?: string): string;
 
   getMetadata(locale?: string): CozyMetadata[];

package/test/Cozy.test.ts

@@ -21,7 +21,7 @@ describe('Cozy', () => {
     const tableOfContents = manifest.getTableOfContents();
     expect(tableOfContents.length).toBe(1);
     expect(tableOfContents[0].children.length).toBe(14);
-  })
+  });
 
 });
 

package/test/annotations/fixtures.ts

@@ -0,0 +1,135 @@
+// Modified from https://iiif.io/api/cookbook/recipe/0021-tagging/
+export const ANNOTATIONS = [{
+  id: 'https://iiif.io/api/cookbook/recipe/0021-tagging/annotation/p0001',
+  type: 'Annotation',
+  motivation: 'tagging',
+  body: {
+    type: 'TextualBody',
+    value: 'Test Annotation 1',
+    format: 'text/plain'
+  },
+  target: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1#xywh=265,661,1260,1239'
+},{
+  id: 'https://iiif.io/api/cookbook/recipe/0021-tagging/annotation/p0002',
+  type: 'Annotation',
+  motivation: 'tagging',
+  body: {
+    type: 'TextualBody',
+    value: 'Test Annotation 2',
+    format: 'text/plain'
+  },
+  target: {
+    source: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p2',
+    selector: {
+      type: 'FragmentSelector',
+      value: 'xywh=265,661,1260,1239'
+    }
+  } 
+}]
+
+// https://iiif.io/api/cookbook/recipe/0001-mvm-image/
+export const SINGLE_CANVAS_NO_ANNOTATIONS = {
+  '@context': 'http://iiif.io/api/presentation/3/context.json',
+  id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json',
+  type: 'Manifest',
+  label: {
+    en: [
+      'Single Image Example'
+    ]
+  },
+  items: [
+    {
+      id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1',
+      type: 'Canvas',
+      height: 1800,
+      width: 1200,
+      items: [
+        {
+          id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/page/p1/1',
+          type: 'AnnotationPage',
+          items: [
+            {
+              id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/annotation/p0001-image',
+              type: 'Annotation',
+              motivation: 'painting',
+              body: {
+                id: 'http://iiif.io/api/presentation/2.1/example/fixtures/resources/page1-full.png',
+                type: 'Image',
+                format: 'image/png',
+                height: 1800,
+                width: 1200
+              },
+              target: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1'
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+export const TWO_CANVASES_NO_ANNOTATIONS = {
+  '@context': 'http://iiif.io/api/presentation/3/context.json',
+  id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json',
+  type: 'Manifest',
+  label: {
+    en: [
+      'Single Image Example'
+    ]
+  },
+  items: [
+    {
+      id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1',
+      type: 'Canvas',
+      height: 1800,
+      width: 1200,
+      items: [
+        {
+          id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/page/p1/1',
+          type: 'AnnotationPage',
+          items: [
+            {
+              id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/annotation/p0001-image',
+              type: 'Annotation',
+              motivation: 'painting',
+              body: {
+                id: 'http://iiif.io/api/presentation/2.1/example/fixtures/resources/page1-full.png',
+                type: 'Image',
+                format: 'image/png',
+                height: 1800,
+                width: 1200
+              },
+              target: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1'
+            }
+          ]
+        }
+      ]
+    }, {
+      id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p2',
+      type: 'Canvas',
+      height: 1800,
+      width: 1200,
+      items: [
+        {
+          id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/page/p1/1',
+          type: 'AnnotationPage',
+          items: [
+            {
+              id: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/annotation/p0001-image',
+              type: 'Annotation',
+              motivation: 'painting',
+              body: {
+                id: 'http://iiif.io/api/presentation/2.1/example/fixtures/resources/page1-full.png',
+                type: 'Image',
+                format: 'image/png',
+                height: 1800,
+                width: 1200
+              },
+              target: 'https://iiif.io/api/cookbook/recipe/0001-mvm-image/canvas/p1'
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/test/annotations/import-annotations.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { Annotation } from '@iiif/presentation-3';
+import { Cozy, CozyManifest } from '../../src';
+
+import { 
+  ANNOTATIONS, 
+  SINGLE_CANVAS_NO_ANNOTATIONS,
+  TWO_CANVASES_NO_ANNOTATIONS
+} from './fixtures';
+
+describe('import-annotations', () => {
+
+  it('should insert a new page into a canvas with no annotatinos', () => {
+    const result = Cozy.parse(SINGLE_CANVAS_NO_ANNOTATIONS);
+
+    expect(result.type).toBe('manifest');
+    const manifest = (result as any).resource as CozyManifest;
+
+    expect(manifest.canvases.length).toBe(1);
+    const firstCanvas = manifest.canvases[0];
+
+    const annotations = ANNOTATIONS as Annotation[];
+
+    const modified = Cozy.Helpers.importAnnotations(firstCanvas, annotations)
+    expect(modified.annotations.length).toBe(1);
+  });
+
+  it('should correctly insert annotation pages into the test manifest', () => {
+    const result = Cozy.parse(TWO_CANVASES_NO_ANNOTATIONS);
+
+    expect(result.type).toBe('manifest');
+    const manifest = (result as any).resource as CozyManifest;
+
+    expect(manifest.canvases.length).toBe(2);
+    expect(manifest.canvases[0].annotations.length).toBe(0);
+    expect(manifest.canvases[1].annotations.length).toBe(0);
+
+    const annotations = ANNOTATIONS as Annotation[];
+
+    const modified = Cozy.Helpers.importAnnotations(manifest, annotations, 'cozy');
+    expect(modified.canvases[0].annotations.length).toBe(1);
+    expect(modified.canvases[1].annotations.length).toBe(1);
+  });
+
+});
+

package/vite.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
     lib: {
       entry: {
         'index': resolve(__dirname, 'src/index.ts'),
+        'helpers/index': resolve(__dirname, 'src/helpers/index.ts'),
         'level-0/index': resolve(__dirname, 'src/level-0/index.ts'),
       },
       formats: ['es']