@ndes/iiif-images 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @ndes/iiif-images
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Enriches SCHEMA-AP-NDE works with the dimensions and sizes of the IIIF image that
+represents them, so a frontend can reserve the right aspect ratio and pick a size
+before the image loads.
+
+It is a quad transform for `@lde/search-indexer`. For each work with a IIIF
+Presentation manifest in `associatedMedia`, it reads the manifest, selects an image
+service, reads that service’s `info.json` and mints a nested `representativeImage`.
+
+## Usage
+
+Declare the fields in your schema module. The `/schema` entry point has no runtime
+dependencies, so a bundled schema module stays self-contained:
+
+```ts
+import {
+  iiifImageTypes,
+  representativeImageField,
+} from '@ndes/iiif-images/schema';
+
+const creativeWork = defineSearchType({
+  name: 'CreativeWork',
+  class: 'https://schema.org/CreativeWork',
+  fields: [representativeImageField /* … */],
+});
+```
+
+Add `iiifImageTypes` to the schema, then attach the transform after any transform
+that repairs IRIs:
+
+```ts
+import { iiifImages } from '@ndes/iiif-images';
+
+const images = iiifImages(schema, { storePath: '/provenance/iiif.sqlite' });
+await images.check();
+
+const transform = images.transformFor(creativeWork);
+const pipeline = await createSearchIndexer(config, {
+  transforms: {
+    CreativeWork: [anyUriToIri(schema), ...(transform ? [transform] : [])],
+  },
+});
+```
+
+`transformFor` answers `undefined` for a root type that does not declare
+`representativeImage` and `associatedMedia`, so a deployment on an older schema loses
+the enrichment rather than the run.
+
+| Option          | Default         | Purpose                                                  |
+| --------------- | --------------- | -------------------------------------------------------- |
+| `storePath`     | required        | SQLite file holding resolved facts between runs          |
+| `fetchesPerRun` | 500             | Manifests, and separately `info.json` documents, per run |
+| `report`        | console warning | Called for each reference whose fetch failed             |
+
+`storePath` has to be on a durable volume. The store is the only place these facts
+live between runs, and with an empty one every image is fetched from the publisher
+again.
+
+## Consuming the field
+
+```json
+{
+  "representativeImage": {
+    "width": 1335,
+    "height": 2750,
+    "sizes": [
+      {
+        "width": 83,
+        "height": 172,
+        "url": "https://example.org/iiif/image/full/83,172/0/default.jpg"
+      }
+    ],
+    "service": {
+      "url": "https://example.org/iiif/image"
+    }
+  }
+}
+```
+
+- Pick the smallest entry in `sizes` that is at least your target width. These are
+  sizes the server lists or its tiles precompute, so they are served fastest. Do not
+  rely on the array’s order.
+- Use `service` only for deep zoom or region crops.
+- Without `representativeImage`, use `associatedMedia[].thumbnailUrl`, with no
+  dimensions. That is the case for a work with no manifest, no image service in its
+  manifest, or a fetch that has not succeeded yet.
+
+## Behaviour
+
+- **Selection:** the first painted image in the manifest that has an image service,
+  found by [@lde/iiif-image](https://ldelements.org/reference/iiif-image).
+- **Freshness:** manifest facts are refetched after 30 days, because which image
+  represents a work can change. `info.json` facts are refetched after 180 days: an
+  image’s dimensions do not change, but its server’s size URLs can.
+- **Safety:** fetches go through
+  [@lde/public-fetch](https://ldelements.org/reference/public-fetch), which refuses a
+  URL, or a redirect target, that is not `http(s)` or names a private address or
+  cluster-internal host, and caps a body at 20 MiB. A refused URL or a larger body is
+  reported and counts as having no such document. It looks at URLs only, so it does not catch DNS
+  pointing inwards. Run the indexer under an egress policy as well.
+- **Failures:** a failed fetch is reported and retried on a later run, and the work
+  is indexed without an image. A 401, 403, 404 or 410 counts as having no such
+  document and is rechecked after a week, so a brief 401 or 403 can replace a stored
+  fact for that long. So does a collection, which has no image of its own, and a
+  manifest too broken to read. A 200 that is no IIIF document at all, such as an error
+  page served as JSON, counts as a failure, so it is retried every run and five in a
+  row stop that dataset’s manifests for the run.
+- **Budget:** `fetchesPerRun` covers all datasets together. What it defers is not
+  reported, and those works are indexed without an image until a later run.
+- **Later runs:** retries, deferred works and refreshes all need the dataset to be
+  reprocessed. With `PROVENANCE_FILE`, an unchanged dataset waits until it changes
+  or `PIPELINE_VERSION` is bumped, so set `fetchesPerRun` high enough to cover it in
+  one run.
+- **Limits:** manifest requests are grouped per dataset, because manifest URLs often
+  sit on a redirector such as `n2t.net`, and `info.json` requests per host. Datasets
+  on one server are limited separately, with only the overall limit across them.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { iiifImages, type IiifImages, type IiifImagesContext, type IiifImagesOptions, type IiifImagesTransform, } from './lib/iiif-images.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { iiifImages, } from './lib/iiif-images.js';

package/dist/lib/iiif-images.d.ts

@@ -0,0 +1,51 @@
+import { type ResolutionFailure } from '@lde/resolver';
+import type { RootType, SearchSchema } from '@lde/search';
+import type { Quad } from '@rdfjs/types';
+export interface IiifImagesOptions {
+    /**
+     * The SQLite file resolved facts live in between runs. It has to survive the
+     * run: the search index is rebuilt from it, and nothing else holds these facts.
+     */
+    readonly storePath: string;
+    /**
+     * Manifests, and separately `info.json` documents, this object may fetch across
+     * all datasets, so construct one per run. Defaults to the resolver’s 500.
+     *
+     * What the budget defers is not reported, and those works are indexed without an
+     * image. A cold store then warms only as datasets are reprocessed, so where
+     * unchanged datasets are skipped, set this high enough to cover them in one run.
+     */
+    readonly fetchesPerRun?: number;
+    /** Told about each reference that failed. Defaults to a console warning. */
+    readonly report?: (failure: ResolutionFailure) => void;
+}
+/** What the transform reads from the reader it is attached to. */
+export interface IiifImagesContext {
+    readonly dataset: {
+        readonly iri: URL;
+    };
+}
+/** A transform attachable to a reader as an `@lde/pipeline` `QuadTransform`. */
+export type IiifImagesTransform = (quads: AsyncIterable<Quad>, context: IiifImagesContext) => AsyncIterable<Quad>;
+export interface IiifImages {
+    /**
+     * The transform to attach to a root type’s reader, after any transform that
+     * repairs IRIs, or `undefined` where that type does not declare
+     * `representativeImage` and `associatedMedia` – so a deployment on an older
+     * schema loses the enrichment rather than the run.
+     */
+    transformFor(rootType: RootType): IiifImagesTransform | undefined;
+    /** Throws when the store cannot persist, to fail a run before it starts. */
+    check(): Promise<void>;
+}
+/**
+ * Enrich works with the image that represents them: its dimensions and a ladder
+ * of precomputed sizes, resolved from the work’s IIIF Presentation manifest and
+ * the selected image’s `info.json`.
+ *
+ * A work with no manifest, or whose resolution has not succeeded, gets no
+ * `representativeImage`; consumers then fall back to the `thumbnailUrl` already
+ * in `associatedMedia`, and a failed resolution is retried on a later run.
+ */
+export declare function iiifImages(schema: SearchSchema, options: IiifImagesOptions): IiifImages;
+//# sourceMappingURL=iiif-images.d.ts.map

package/dist/lib/iiif-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iiif-images.d.ts","sourceRoot":"","sources":["../../src/lib/iiif-images.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,QAAQ,EAER,YAAY,EAEb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,IAAI,EAA6B,MAAM,cAAc,CAAC;AASpE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACxD;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;KAAE,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,CAChC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,OAAO,EAAE,iBAAiB,KACvB,aAAa,CAAC,IAAI,CAAC,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAClE,4EAA4E;IAC5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,iBAAiB,GACzB,UAAU,CAiHZ"}

package/dist/lib/iiif-images.js

@@ -0,0 +1,290 @@
+import { imageServices, readImageService, } from '@lde/iiif-image';
+import { fetchPublic, RefusedUrlError, ResponseTooLargeError, } from '@lde/public-fetch';
+import { createResolver, sqliteFactStore, urlHost, } from '@lde/resolver';
+import { fieldNamed, irAlias, referenceTypeNamed } from '@lde/search/adapter';
+import { DataFactory } from 'rdf-data-factory';
+import { iiifImage, iiifImageService, iiifImageSize, representativeImageField, } from '../schema.js';
+/**
+ * Enrich works with the image that represents them: its dimensions and a ladder
+ * of precomputed sizes, resolved from the work’s IIIF Presentation manifest and
+ * the selected image’s `info.json`.
+ *
+ * A work with no manifest, or whose resolution has not succeeded, gets no
+ * `representativeImage`; consumers then fall back to the `thumbnailUrl` already
+ * in `associatedMedia`, and a failed resolution is retried on a later run.
+ */
+export function iiifImages(schema, options) {
+    const limits = options.fetchesPerRun === undefined
+        ? {}
+        : { fetchesPerResolver: options.fetchesPerRun };
+    const report = options.report ??
+        ((failure) => console.warn(`${failure.key}: ${failure.reason}`));
+    const manifests = createResolver({
+        key: (reference) => reference.url,
+        // Not the manifest’s own host: many are on n2t.net, which only redirects, so
+        // its limits and failure cut-off would land on the wrong server and lump
+        // publishers together. A dataset is the closest known stand-in for the server
+        // at the end of those redirects.
+        host: (reference) => reference.dataset,
+        fetch: (references, { signal }) => fetchFacts(references.map(({ url }) => url), (url) => url, (document) => {
+            try {
+                const [service] = imageServices(document);
+                return service;
+            }
+            catch (error) {
+                // A document that says it is a collection, or a manifest too broken
+                // to read, has no image to offer: a fact about that document. Anything
+                // else – an error page served as JSON – is a server misbehaving, so
+                // no absence may overwrite the stored fact.
+                if (error instanceof TypeError && declaresIiifType(document)) {
+                    return undefined;
+                }
+                throw error;
+            }
+        }, signal, report),
+        store: sqliteFactStore({
+            path: options.storePath,
+            table: 'manifests',
+        }),
+        limits: { ...limits, ttlMs: MANIFEST_TTL_MS },
+        report,
+    });
+    const images = createResolver({
+        key: (service) => service,
+        host: urlHost,
+        fetch: (services, { signal }) => fetchFacts(services, (service) => `${service}/info.json`, (info, service) => {
+            // Same reasoning, with more at stake: these facts are otherwise permanent.
+            const fact = readImageService(service, info);
+            if (fact === undefined) {
+                throw new Error(`${service}/info.json states no dimensions`);
+            }
+            return fact;
+        }, signal, report),
+        store: sqliteFactStore({
+            path: options.storePath,
+            table: 'images',
+        }),
+        limits: { ...limits, ttlMs: IMAGE_TTL_MS },
+        report,
+    });
+    return {
+        transformFor(rootType) {
+            const aliases = aliasesOf(rootType, schema);
+            return aliases === undefined
+                ? undefined
+                : async function* enrich(quads, context) {
+                    // A batch of roots is the unit of work and what bounds the memory: a
+                    // work’s manifest entry is only known once the batch is, and resolving
+                    // per batch is what lets the resolver share one store read.
+                    const batch = [];
+                    for await (const quad of quads) {
+                        batch.push(quad);
+                        yield quad;
+                    }
+                    const manifestOfWork = manifestsIn(batch, aliases);
+                    const dataset = context.dataset.iri.toString();
+                    const selected = await manifests.resolveAll([...manifestOfWork.values()].map((url) => ({ url, dataset })));
+                    const serviceOfWork = new Map();
+                    for (const [work, manifest] of manifestOfWork) {
+                        const resolution = selected.get(manifest);
+                        if (resolution?.outcome === 'resolved') {
+                            serviceOfWork.set(work, resolution.fact);
+                        }
+                    }
+                    const resolved = await images.resolveAll([
+                        ...serviceOfWork.values(),
+                    ]);
+                    for (const [work, service] of serviceOfWork) {
+                        const resolution = resolved.get(service);
+                        if (resolution?.outcome === 'resolved') {
+                            yield* mint(factory.namedNode(work), resolution.fact, aliases);
+                        }
+                    }
+                };
+        },
+        async check() {
+            await manifests.check();
+            await images.check();
+        },
+    };
+}
+const factory = new DataFactory();
+const INTEGER = factory.namedNode('http://www.w3.org/2001/XMLSchema#integer');
+/** What the profile’s `encodingFormat` for a manifest entry contains. */
+const IIIF_PRESENTATION_CONTEXT = 'iiif.io/api/presentation';
+/** A manifest’s selection can change, so it is reconsidered after 30 days. */
+const MANIFEST_TTL_MS = 30 * 24 * 3_600_000;
+/**
+ * An image’s dimensions do not change, but what its server offers does: an upgrade
+ * can change the size URLs stored with them. So these facts are reconsidered too,
+ * only rarely.
+ */
+const IMAGE_TTL_MS = 180 * 24 * 3_600_000;
+const IIIF_TYPES = new Set([
+    'Manifest',
+    'Collection',
+    'sc:Manifest',
+    'sc:Collection',
+]);
+/** Answers meaning this document is not ours to have, now or on a retry. */
+const ABSENT_STATUSES = new Set([401, 403, 404, 410]);
+function aliasesOf(rootType, schema) {
+    const media = fieldNamed(rootType, 'associatedMedia');
+    const image = fieldNamed(rootType, representativeImageField.name);
+    const mediaType = referencedType(schema, media);
+    const encodingFormat = mediaType === undefined ? undefined : aliasOf(mediaType, 'encodingFormat');
+    const imageType = referencedType(schema, image);
+    const sizeType = imageType && referencedType(schema, fieldNamed(imageType, 'sizes'));
+    const serviceType = imageType && referencedType(schema, fieldNamed(imageType, 'service'));
+    if (media === undefined ||
+        image === undefined ||
+        encodingFormat === undefined ||
+        imageType === undefined ||
+        sizeType === undefined ||
+        serviceType === undefined) {
+        return undefined;
+    }
+    const imageAliases = fieldAliases(imageType, iiifImage);
+    const sizeAliases = fieldAliases(sizeType, iiifImageSize);
+    const serviceAliases = fieldAliases(serviceType, iiifImageService);
+    return imageAliases === undefined ||
+        sizeAliases === undefined ||
+        serviceAliases === undefined
+        ? undefined
+        : {
+            associatedMedia: irAlias(rootType, media),
+            encodingFormat,
+            representativeImage: irAlias(rootType, image),
+            image: imageAliases,
+            size: sizeAliases,
+            service: serviceAliases,
+        };
+}
+/**
+ * The type a reference field nests. Read from the declaration rather than through
+ * `nestedReferenceType`, which answers only for surfaced fields: a schema may read
+ * `associatedMedia` without surfacing it, and should still be enriched.
+ */
+function referencedType(schema, field) {
+    return field?.kind === 'reference' && field.ref?.strategy === 'inline'
+        ? referenceTypeNamed(schema, field.ref.typeName)
+        : undefined;
+}
+/** Every field `declaration` names, as the schema’s own `searchType` aliases it,
+ *  or `undefined` where that type lacks one. */
+function fieldAliases(searchType, declaration) {
+    const entries = declaration.fields.map(({ name }) => [name, aliasOf(searchType, name)]);
+    return entries.every(([, alias]) => alias !== undefined)
+        ? Object.fromEntries(entries)
+        : undefined;
+}
+function aliasOf(searchType, name) {
+    const field = fieldNamed(searchType, name);
+    return field === undefined ? undefined : irAlias(searchType, field);
+}
+/**
+ * Each work’s manifest: its `associatedMedia` entry that is a named node and names
+ * the IIIF Presentation context in its `encodingFormat`. The profile allows one;
+ * where a publisher states more, the first by IRI, because quad order can change
+ * between runs and the representative image should not change with it. Only works
+ * named by an IRI, because the image is minted onto the work by its name.
+ */
+function manifestsIn(batch, aliases) {
+    const manifestEntries = new Set(batch
+        .filter((quad) => quad.predicate.value === aliases.encodingFormat &&
+        quad.subject.termType === 'NamedNode' &&
+        quad.object.value.includes(IIIF_PRESENTATION_CONTEXT))
+        .map((quad) => quad.subject.value));
+    const manifestOfWork = new Map();
+    for (const quad of batch) {
+        if (quad.predicate.value !== aliases.associatedMedia ||
+            quad.subject.termType !== 'NamedNode' ||
+            !manifestEntries.has(quad.object.value)) {
+            continue;
+        }
+        const current = manifestOfWork.get(quad.subject.value);
+        if (current === undefined || quad.object.value < current) {
+            manifestOfWork.set(quad.subject.value, quad.object.value);
+        }
+    }
+    return manifestOfWork;
+}
+/**
+ * Fetch each key’s JSON document and derive its fact. An {@link ABSENT_STATUSES}
+ * answer, or a document `derive` finds no fact in, is an absence and left out;
+ * anything else throws, so the resolver retries it and a stored fact survives a
+ * passing outage. Restricted images are absences so that they cannot write off a
+ * host whose public images are fine. So, reported, is a URL that is not a public
+ * web address – publisher data decides these URLs, and this runs inside the
+ * cluster – and a document too large to read, which a retry would not shrink.
+ */
+async function fetchFacts(keys, urlOf, derive, signal, report) {
+    const facts = [];
+    for (const key of keys) {
+        let document;
+        try {
+            document = await fetchDocument(urlOf(key), signal);
+        }
+        catch (error) {
+            if (!(error instanceof RefusedUrlError) &&
+                !(error instanceof ResponseTooLargeError)) {
+                throw error;
+            }
+            report({ key, reason: error.message, degradedToStore: false });
+            continue;
+        }
+        const fact = document === undefined ? undefined : derive(document, key);
+        if (fact !== undefined) {
+            facts.push([key, fact]);
+        }
+    }
+    return facts;
+}
+/** The JSON document at `url`, or `undefined` for an {@link ABSENT_STATUSES} answer. */
+async function fetchDocument(url, signal) {
+    // Only `*/*`: LDmaX answers 404 to any JSON media type in `Accept`, IIIF’s own
+    // included, even with `*/*` as a fallback beside it.
+    const response = await fetchPublic(url, {
+        signal,
+        headers: { Accept: '*/*' },
+    });
+    if (!response.ok) {
+        // An unread body keeps its connection until garbage collection.
+        await response.body?.cancel();
+        if (ABSENT_STATUSES.has(response.status)) {
+            return undefined;
+        }
+        throw new Error(`${url} answered ${response.status}`);
+    }
+    return response.json();
+}
+/** Whether a document says it is a IIIF manifest or collection, in Presentation 3 or 2. */
+function declaresIiifType(document) {
+    if (typeof document !== 'object' || document === null) {
+        return false;
+    }
+    const { type, '@type': legacyType } = document;
+    return IIIF_TYPES.has(String(type ?? legacyType));
+}
+function* mint(work, fact, aliases) {
+    const image = factory.blankNode();
+    yield triple(work, aliases.representativeImage, image);
+    yield triple(image, aliases.image.width, integer(fact.width));
+    yield triple(image, aliases.image.height, integer(fact.height));
+    for (const size of fact.sizes) {
+        const node = factory.blankNode();
+        yield triple(image, aliases.image.sizes, node);
+        yield triple(node, aliases.size.width, integer(size.width));
+        yield triple(node, aliases.size.height, integer(size.height));
+        yield triple(node, aliases.size.url, factory.namedNode(size.url));
+    }
+    const service = factory.blankNode();
+    yield triple(image, aliases.image.service, service);
+    yield triple(service, aliases.service.url, factory.namedNode(fact.url));
+}
+function triple(subject, predicate, object) {
+    return factory.quad(subject, factory.namedNode(predicate), object);
+}
+function integer(value) {
+    return factory.literal(String(value), INTEGER);
+}

package/dist/lib/image-service.d.ts

@@ -0,0 +1,26 @@
+/** What an image service’s `info.json` tells a consumer, in the consumer’s terms. */
+export interface ImageFact {
+    readonly width: number;
+    readonly height: number;
+    /** Renditions to pick from, smallest first. */
+    readonly sizes: readonly ImageSize[];
+    /** The service itself, for consumers doing deep zoom or region crops. */
+    readonly service: {
+        readonly url: string;
+        readonly type: string;
+        readonly profile: string;
+    };
+}
+export interface ImageSize {
+    readonly width: number;
+    readonly height: number;
+    readonly url: string;
+}
+/**
+ * An `info.json` as an {@link ImageFact}, or `undefined` where it states no
+ * dimensions. `serviceUrl` rather than the document’s own `id` names the service,
+ * because that is what the manifest resolved and what a proxied server’s
+ * self-reported `id` need not be.
+ */
+export declare function imageFactFrom(serviceUrl: string, info: unknown): ImageFact | undefined;
+//# sourceMappingURL=image-service.d.ts.map

package/dist/lib/image-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-service.d.ts","sourceRoot":"","sources":["../../src/lib/image-service.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,GACZ,SAAS,GAAG,SAAS,CA4BvB"}

package/dist/lib/image-service.js

@@ -0,0 +1,116 @@
+/**
+ * An `info.json` as an {@link ImageFact}, or `undefined` where it states no
+ * dimensions. `serviceUrl` rather than the document’s own `id` names the service,
+ * because that is what the manifest resolved and what a proxied server’s
+ * self-reported `id` need not be.
+ */
+export function imageFactFrom(serviceUrl, info) {
+    if (typeof info !== 'object' || info === null) {
+        return undefined;
+    }
+    const document = info;
+    const { width, height } = document;
+    if (!isPositive(width) || !isPositive(height)) {
+        return undefined;
+    }
+    const type = serviceTypeOf(document);
+    const profile = profileOf(document);
+    const isVersion3 = type === 'ImageService3';
+    // Image API 1.1 names its qualities differently (`native`, not `default`) and has
+    // no `sizes`, and is rare enough that its dimensions alone will do.
+    const sizes = (type === 'ImageService1' ? [] : sizesOf(document, width, height, profile))
+        .sort((left, right) => left.width - right.width)
+        .map((size) => ({
+        ...size,
+        url: `${serviceUrl}/full/${isVersion3 ? `${size.width},${size.height}` : `${size.width},`}/0/default.jpg`,
+    }));
+    return {
+        width,
+        height,
+        sizes,
+        service: { url: serviceUrl, type, profile },
+    };
+}
+/** Rungs below this width are too small to be worth a request. */
+const MINIMUM_SYNTHESISED_WIDTH = 64;
+function sizesOf(document, width, height, profile) {
+    const declared = Array.isArray(document.sizes)
+        ? document.sizes.filter((size) => isPositive(size?.width) && isPositive(size?.height))
+        : [];
+    if (declared.length > 0) {
+        return declared.map((size) => ({ width: size.width, height: size.height }));
+    }
+    // A level-0 server only serves what it lists, so nothing can be asked of it.
+    if (/level0/.test(profile)) {
+        return [];
+    }
+    const rungs = new Map();
+    for (const scaleFactor of scaleFactorsOf(document, width)) {
+        const rung = {
+            width: Math.round(width / scaleFactor),
+            height: Math.round(height / scaleFactor),
+        };
+        if (rung.width >= MINIMUM_SYNTHESISED_WIDTH &&
+            rung.height >= 1 &&
+            isWithinMaximums(rung, document)) {
+            rungs.set(rung.width, rung);
+        }
+    }
+    return [...rungs.values()];
+}
+/** The server’s own precomputed factors where it has tiles, else powers of two. */
+function scaleFactorsOf(document, width) {
+    const tiles = Array.isArray(document.tiles) ? document.tiles : [];
+    const declared = tiles
+        .flatMap((tile) => Array.isArray(tile?.scaleFactors) ? tile.scaleFactors : [])
+        .filter(isPositive);
+    if (declared.length > 0) {
+        return declared;
+    }
+    const factors = [];
+    for (let factor = 1; width / factor >= MINIMUM_SYNTHESISED_WIDTH; factor *= 2) {
+        factors.push(factor);
+    }
+    return factors;
+}
+/**
+ * Asking above a declared maximum answers 404, not 400 (Image API 3.0 § 7.3),
+ * which would read as a dead link. `maxWidth` alone also bounds the height
+ * (§ 5.3), so it is the fallback for a missing `maxHeight`.
+ */
+function isWithinMaximums(rung, document) {
+    const { maxWidth, maxHeight, maxArea } = document;
+    const heightLimit = isPositive(maxHeight) ? maxHeight : maxWidth;
+    return ((!isPositive(maxWidth) || rung.width <= maxWidth) &&
+        (!isPositive(heightLimit) || rung.height <= heightLimit) &&
+        (!isPositive(maxArea) || rung.width * rung.height <= maxArea));
+}
+function serviceTypeOf(document) {
+    // Only this family: Image API 2 documents commonly say `@type: iiif:Image`, which
+    // names what they describe and not the kind of service.
+    const type = document.type ?? document['@type'];
+    if (typeof type === 'string' && type.startsWith('ImageService')) {
+        return type;
+    }
+    const context = JSON.stringify(document['@context'] ?? '');
+    if (context.includes('image/3')) {
+        return 'ImageService3';
+    }
+    if (context.includes('image/2')) {
+        return 'ImageService2';
+    }
+    // A 1.0 document may state no context, so the profile has to answer as well.
+    return /image-api|api\/image\/1/.test(`${context} ${profileOf(document)}`)
+        ? 'ImageService1'
+        : 'ImageService2';
+}
+/** The compliance level, which Image API 2 states first in an array. */
+function profileOf(document) {
+    const profile = Array.isArray(document.profile)
+        ? document.profile[0]
+        : document.profile;
+    return typeof profile === 'string' ? profile : '';
+}
+function isPositive(value) {
+    return Number.isInteger(value) && value > 0;
+}

package/dist/lib/manifest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The image service of a manifest’s first painted image that has one, in either
+ * Presentation version.
+ *
+ * A walk over the plain JSON rather than a vault: real manifests carry shapes a
+ * normalising parser rejects outright – Deventit Atlantis writes
+ * `"annotations": [null]` – and only this path matters here. Which image
+ * represents a work is a rule that lives in this one function, so a better one
+ * can replace it without touching what it feeds.
+ */
+export declare function selectImageService(manifest: unknown): string | undefined;
+/** Whether a document has the canvases every manifest must have, in either version. */
+export declare function listsCanvases(document: unknown): boolean;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/lib/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/lib/manifest.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAcxE;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAKxD"}

package/dist/lib/manifest.js

@@ -0,0 +1,98 @@
+import { isImageService as isKnownImageService } from '@iiif/parser/image-3';
+import { convertPresentation2 } from '@iiif/parser/presentation-2';
+/**
+ * The image service of a manifest’s first painted image that has one, in either
+ * Presentation version.
+ *
+ * A walk over the plain JSON rather than a vault: real manifests carry shapes a
+ * normalising parser rejects outright – Deventit Atlantis writes
+ * `"annotations": [null]` – and only this path matters here. Which image
+ * represents a work is a rule that lives in this one function, so a better one
+ * can replace it without touching what it feeds.
+ */
+export function selectImageService(manifest) {
+    for (const canvas of arrayOf(fieldOf(upgraded(manifest), 'items'))) {
+        for (const page of arrayOf(fieldOf(canvas, 'items'))) {
+            for (const annotation of arrayOf(fieldOf(page, 'items'))) {
+                for (const body of paintedResources(fieldOf(annotation, 'body'))) {
+                    const service = imageServiceOf(body);
+                    if (service !== undefined) {
+                        return service;
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Whether a document has the canvases every manifest must have, in either version. */
+export function listsCanvases(document) {
+    return (arrayOf(fieldOf(document, 'items')).length > 0 ||
+        arrayOf(fieldOf(document, 'sequences')).length > 0);
+}
+/**
+ * The manifest in Presentation 3 terms. A Presentation 2 manifest the upgrade
+ * chokes on, such as one with `"images": [null]`, has nothing to find: retrying
+ * cannot help, and a run of them must not write off a dataset’s other manifests.
+ */
+function upgraded(manifest) {
+    if (fieldOf(manifest, 'sequences') === undefined) {
+        return manifest;
+    }
+    try {
+        return convertPresentation2(manifest);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A body’s resources in order, with each `Choice` opened up and each
+ *  `SpecificResource`, which is how a cropped painting is stated, unwrapped. */
+function paintedResources(body) {
+    return arrayOf(body).flatMap((resource) => {
+        const type = fieldOf(resource, 'type');
+        if (type === 'Choice') {
+            return paintedResources(fieldOf(resource, 'items'));
+        }
+        return type === 'SpecificResource'
+            ? paintedResources(fieldOf(resource, 'source'))
+            : [resource];
+    });
+}
+function imageServiceOf(resource) {
+    for (const service of arrayOf(fieldOf(resource, 'service'))) {
+        const id = fieldOf(service, 'id') ?? fieldOf(service, '@id');
+        if (typeof id === 'string' && isImageService(service)) {
+            return serviceBase(id);
+        }
+    }
+    return undefined;
+}
+/** The URL `/info.json` and sizes are appended to. Some manifests state the
+ *  service with a trailing slash or as the `info.json` itself. */
+function serviceBase(id) {
+    return id.replace(/\/info\.json$/, '').replace(/\/+$/, '');
+}
+/**
+ * The parser’s test, plus the two forms it misses: a `type` with no `profile`, and
+ * a profile merely naming a compliance level. Limb Gallery’s is the `https` form
+ * of the Stanford URL from Image API 1.1, which the parser’s list does not include.
+ */
+function isImageService(service) {
+    const type = fieldOf(service, 'type') ?? fieldOf(service, '@type');
+    const profile = fieldOf(service, 'profile');
+    return (isKnownImageService(service) ||
+        (typeof type === 'string' && type.startsWith('ImageService')) ||
+        (typeof profile === 'string' && /level[012]/.test(profile)));
+}
+function fieldOf(value, name) {
+    return typeof value === 'object' && value !== null
+        ? value[name]
+        : undefined;
+}
+function arrayOf(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}

package/dist/lib/public-url.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a URL taken from a publisher’s data may be fetched from inside the
+ * cluster: a web URL that does not name a private, loopback or link-local address
+ * or a cluster-internal host.
+ *
+ * This looks only at the URL, so it cannot see a public name resolving to a private
+ * address, or a redirect to one. It stops the plain case, and a cluster egress
+ * policy has to cover the rest.
+ */
+export declare function isPublicWebUrl(url: string): boolean;
+//# sourceMappingURL=public-url.d.ts.map

package/dist/lib/public-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-url.d.ts","sourceRoot":"","sources":["../../src/lib/public-url.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAoBnD"}

package/dist/lib/public-url.js

@@ -0,0 +1,53 @@
+import { BlockList, isIP } from 'node:net';
+/**
+ * Whether a URL taken from a publisher’s data may be fetched from inside the
+ * cluster: a web URL that does not name a private, loopback or link-local address
+ * or a cluster-internal host.
+ *
+ * This looks only at the URL, so it cannot see a public name resolving to a private
+ * address, or a redirect to one. It stops the plain case, and a cluster egress
+ * policy has to cover the rest.
+ */
+export function isPublicWebUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return false;
+    }
+    const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const family = isIP(host);
+    if (family === 4) {
+        return !PRIVATE_ADDRESSES.check(host, 'ipv4');
+    }
+    if (family === 6) {
+        return !PRIVATE_ADDRESSES.check(host, 'ipv6');
+    }
+    // A single label is a Kubernetes service or a machine on the local network.
+    return host.includes('.') && !INTERNAL_SUFFIX.test(host);
+}
+const INTERNAL_SUFFIX = /\.(localhost|local|internal|svc)$/;
+const PRIVATE_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.168.0.0', 16],
+]) {
+    PRIVATE_ADDRESSES.addSubnet(network, prefix, 'ipv4');
+}
+for (const [network, prefix] of [
+    ['::', 128],
+    ['::1', 128],
+    ['fc00::', 7],
+    ['fe80::', 10],
+]) {
+    PRIVATE_ADDRESSES.addSubnet(network, prefix, 'ipv6');
+}

package/dist/schema.d.ts

@@ -0,0 +1,152 @@
+/** One precomputed rendition of the image, with the URL to request it at. */
+export declare const iiifImageSize: {
+    readonly name: "IiifImageSize";
+    readonly fields: readonly [{
+        readonly name: "width";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/width>";
+    }, {
+        readonly name: "height";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/height>";
+    }, {
+        readonly name: "url";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://schema.org/contentUrl>";
+        readonly ref: {
+            readonly strategy: "idOnly";
+        };
+    }];
+};
+/** The IIIF image service itself, for consumers doing deep zoom or region crops. */
+export declare const iiifImageService: {
+    readonly name: "IiifImageService";
+    readonly fields: readonly [{
+        readonly name: "url";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://schema.org/url>";
+        readonly ref: {
+            readonly strategy: "idOnly";
+        };
+    }];
+};
+/**
+ * The image that represents a work: the full dimensions, and the renditions a
+ * consumer can pick from without knowing Image API compliance levels.
+ */
+export declare const iiifImage: {
+    readonly name: "IiifImage";
+    readonly fields: readonly [{
+        readonly name: "width";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/width>";
+    }, {
+        readonly name: "height";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/height>";
+    }, {
+        readonly name: "sizes";
+        readonly kind: "reference";
+        readonly array: true;
+        readonly output: true;
+        readonly path: "<https://def.nde.nl/iiif#size>";
+        readonly ref: {
+            readonly typeName: "IiifImageSize";
+            readonly strategy: "inline";
+        };
+    }, {
+        readonly name: "service";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://def.nde.nl/iiif#service>";
+        readonly ref: {
+            readonly typeName: "IiifImageService";
+            readonly strategy: "inline";
+        };
+    }];
+};
+/** The types {@link representativeImageField} nests, to add to the schema. */
+export declare const iiifImageTypes: ({
+    readonly name: "IiifImageSize";
+    readonly fields: readonly [{
+        readonly name: "width";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/width>";
+    }, {
+        readonly name: "height";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/height>";
+    }, {
+        readonly name: "url";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://schema.org/contentUrl>";
+        readonly ref: {
+            readonly strategy: "idOnly";
+        };
+    }];
+} | {
+    readonly name: "IiifImageService";
+    readonly fields: readonly [{
+        readonly name: "url";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://schema.org/url>";
+        readonly ref: {
+            readonly strategy: "idOnly";
+        };
+    }];
+} | {
+    readonly name: "IiifImage";
+    readonly fields: readonly [{
+        readonly name: "width";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/width>";
+    }, {
+        readonly name: "height";
+        readonly kind: "integer";
+        readonly output: true;
+        readonly path: "<https://schema.org/height>";
+    }, {
+        readonly name: "sizes";
+        readonly kind: "reference";
+        readonly array: true;
+        readonly output: true;
+        readonly path: "<https://def.nde.nl/iiif#size>";
+        readonly ref: {
+            readonly typeName: "IiifImageSize";
+            readonly strategy: "inline";
+        };
+    }, {
+        readonly name: "service";
+        readonly kind: "reference";
+        readonly output: true;
+        readonly path: "<https://def.nde.nl/iiif#service>";
+        readonly ref: {
+            readonly typeName: "IiifImageService";
+            readonly strategy: "inline";
+        };
+    }];
+})[];
+/** Add to a root type’s fields, and {@link iiifImageTypes} to the schema, to opt
+ *  that type in to enrichment. */
+export declare const representativeImageField: {
+    readonly name: "representativeImage";
+    readonly kind: "reference";
+    readonly output: true;
+    readonly path: "<https://def.nde.nl/iiif#representativeImage>";
+    readonly ref: {
+        readonly typeName: "IiifImage";
+        readonly strategy: "inline";
+    };
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAKA,6EAA6E;AAC7E,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;CAkBK,CAAC;AAEhC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAWE,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BS,CAAC;AAEhC,8EAA8E;AAC9E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA+C,CAAC;AAE3E;kCACkC;AAClC,eAAO,MAAM,wBAAwB;;;;;;;;;CAML,CAAC"}

package/dist/schema.js

@@ -0,0 +1,77 @@
+const SCHEMA = 'https://schema.org/';
+const IIIF = 'https://def.nde.nl/iiif#';
+/** One precomputed rendition of the image, with the URL to request it at. */
+export const iiifImageSize = {
+    name: 'IiifImageSize',
+    fields: [
+        { name: 'width', kind: 'integer', output: true, path: `<${SCHEMA}width>` },
+        {
+            name: 'height',
+            kind: 'integer',
+            output: true,
+            path: `<${SCHEMA}height>`,
+        },
+        {
+            name: 'url',
+            kind: 'reference',
+            output: true,
+            path: `<${SCHEMA}contentUrl>`,
+            ref: { strategy: 'idOnly' },
+        },
+    ],
+};
+/** The IIIF image service itself, for consumers doing deep zoom or region crops. */
+export const iiifImageService = {
+    name: 'IiifImageService',
+    fields: [
+        {
+            name: 'url',
+            kind: 'reference',
+            output: true,
+            path: `<${SCHEMA}url>`,
+            ref: { strategy: 'idOnly' },
+        },
+    ],
+};
+/**
+ * The image that represents a work: the full dimensions, and the renditions a
+ * consumer can pick from without knowing Image API compliance levels.
+ */
+export const iiifImage = {
+    name: 'IiifImage',
+    fields: [
+        { name: 'width', kind: 'integer', output: true, path: `<${SCHEMA}width>` },
+        {
+            name: 'height',
+            kind: 'integer',
+            output: true,
+            path: `<${SCHEMA}height>`,
+        },
+        {
+            name: 'sizes',
+            kind: 'reference',
+            array: true,
+            output: true,
+            path: `<${IIIF}size>`,
+            ref: { typeName: iiifImageSize.name, strategy: 'inline' },
+        },
+        {
+            name: 'service',
+            kind: 'reference',
+            output: true,
+            path: `<${IIIF}service>`,
+            ref: { typeName: iiifImageService.name, strategy: 'inline' },
+        },
+    ],
+};
+/** The types {@link representativeImageField} nests, to add to the schema. */
+export const iiifImageTypes = [iiifImage, iiifImageSize, iiifImageService];
+/** Add to a root type’s fields, and {@link iiifImageTypes} to the schema, to opt
+ *  that type in to enrichment. */
+export const representativeImageField = {
+    name: 'representativeImage',
+    kind: 'reference',
+    output: true,
+    path: `<${IIIF}representativeImage>`,
+    ref: { typeName: iiifImage.name, strategy: 'inline' },
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@ndes/iiif-images",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Enriches SCHEMA-AP-NDE works with the dimensions and sizes of their representative IIIF image, as a quad transform for the search indexer.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@ndes/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "@ndes/source": "./src/schema.ts",
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js",
+      "default": "./dist/schema.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@lde/iiif-image": "^0.1.0",
+    "@lde/public-fetch": "^0.1.0",
+    "@lde/resolver": "^0.2.1",
+    "@rdfjs/types": "^2.0.1",
+    "rdf-data-factory": "^2.1.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@lde/pipeline": "^0.36.7",
+    "@lde/search": "^0.34.0"
+  },
+  "peerDependencies": {
+    "@lde/search": "^0.34.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "name": "iiif-images"
+  }
+}