@internetarchive/metadata-service 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,64 @@
+# Internet Archive Metadata Service
+
+A service for retrieving metadata about items in the Internet Archive.
+
+## Installation
+```bash
+npm install @internetarchive/metadata-service
+```
+
+## Usage
+
+### Fetch Metadata
+
+```ts
+const metadataResponse: MetadataResponse = await metadataService.fetchMetadata('some-identifier');
+
+metadataResponse.metadata.identifier // => 'some-identifier'
+metadataResponse.metadata.collection.value // => 'some-collection'
+metadataResponse.metadata.collection.values // => ['some-collection', 'another-collection', 'more-collections']
+```
+
+## Metadata Values
+
+Internet Archive Metadata is expansive and nearly all metadata fields can be returned as either an array, string, or number.
+
+The Metadata Service handles all of the possible variations in data formats and converts them to their appropriate types. For instance on date fields, like `date`, it takes the string returned and converts it into a native javascript `Date` value. Similarly for duration-type fields, like `length`, it takes the duration, which can be seconds `324.34` or `hh:mm:ss.ms` and converts them to a `number` in seconds.
+
+There are parsers for several different field types, like `Number`, `String`, `Date`, and `Duration` and others can be added for other field types.
+
+See `src/models/metadata-fields/field-types.ts`
+
+### Usage
+
+```ts
+metadata.collection.value // return just the first item of the `values` array, ie. 'my-collection'
+metadata.collection.values // returns all values of the array, ie. ['my-collection', 'other-collection']
+metadata.collection.rawValue // return the rawValue. This is useful for inspecting the raw response received.
+
+metadata.date.value  // return the date as a javascript `Date` object
+
+metadata.length.value  // return the length (duration) of the item as a number of seconds, can be in the format "hh:mm:ss" or decimal seconds
+```
+
+# Development
+
+## Prerequisite
+```bash
+npm install
+```
+
+## Testing
+```bash
+npm run test
+```
+
+## Demo
+```bash
+npm run start
+```
+
+## Linting
+```bash
+npm run format
+```

package/demo/app-root.ts

@@ -0,0 +1,80 @@
+import {
+  css,
+  CSSResult,
+  customElement,
+  html,
+  internalProperty,
+  LitElement,
+  query,
+  TemplateResult,
+} from 'lit-element';
+import { unsafeHTML } from 'lit-html/directives/unsafe-html';
+import { nothing } from 'lit-html';
+import { MetadataResponse } from '../src/responses/metadata-response';
+import { MetadataServiceInterface } from '../src/metadata-service-interface';
+import { MetadataService } from '../src/metadata-service';
+
+@customElement('app-root')
+export class AppRoot extends LitElement {
+  private metadataService: MetadataServiceInterface = MetadataService.default;
+
+  @query('#metadata-input')
+  private metadataInput!: HTMLInputElement;
+
+  @internalProperty()
+  private metadataResponse?: MetadataResponse;
+
+  /** @inheritdoc */
+  render(): TemplateResult {
+    return html`
+      <fieldset>
+        <legend>Metadata Fetch</legend>
+        <form>
+          <label>Metadata</label>
+          <input type="text" id="metadata-input" placeholder="Identifier" />
+          <input
+            type="submit"
+            value="Get Metadata"
+            @click=${this.getMetadata}
+          />
+        </form>
+      </fieldset>
+
+      ${this.metadataResponse ? this.metadataTemplate : nothing}
+    `;
+  }
+
+  private get metadataTemplate(): TemplateResult {
+    const rawMetadata = this.metadataResponse?.metadata.rawMetadata;
+    if (!rawMetadata) return html`${nothing}`;
+
+    return html`
+      <h2>Metadata Response</h2>
+      <table>
+        ${Object.keys(rawMetadata).map(
+          key => html`
+            <tr>
+              <td>${key}</td>
+              <td>${unsafeHTML(rawMetadata[key])}</td>
+            </tr>
+          `
+        )}
+      </table>
+    `;
+  }
+
+  async getMetadata(e: Event): Promise<void> {
+    e.preventDefault();
+    const identifier = this.metadataInput.value;
+    const result = await this.metadataService.fetchMetadata(identifier);
+    this.metadataResponse = result?.success;
+  }
+
+  static get styles(): CSSResult {
+    return css`
+      /* th {
+        font-weight: bold;
+      } */
+    `;
+  }
+}

package/demo/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en-GB">
+<head>
+  <meta charset="utf-8">
+  <style>
+    body {
+      background: #fff;
+      font-family: sans-serif;
+    }
+  </style>
+</head>
+<body>
+  <div id="demo"></div>
+
+  <script type="module">
+    import { html, render } from 'lit-html';
+    import '../dist/demo/app-root.js';
+
+    render(
+      html`
+        <app-root></app-root>
+      `,
+      document.querySelector('#demo')
+    );
+  </script>
+</body>
+</html>

package/dist/demo/app-root.d.ts

@@ -0,0 +1,11 @@
+import { CSSResult, LitElement, TemplateResult } from 'lit-element';
+export declare class AppRoot extends LitElement {
+    private metadataService;
+    private metadataInput;
+    private metadataResponse?;
+    /** @inheritdoc */
+    render(): TemplateResult;
+    private get metadataTemplate();
+    getMetadata(e: Event): Promise<void>;
+    static get styles(): CSSResult;
+}

package/dist/demo/app-root.js

@@ -0,0 +1,71 @@
+import { __decorate } from "tslib";
+import { css, customElement, html, internalProperty, LitElement, query, } from 'lit-element';
+import { unsafeHTML } from 'lit-html/directives/unsafe-html';
+import { nothing } from 'lit-html';
+import { MetadataService } from '../src/metadata-service';
+let AppRoot = class AppRoot extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.metadataService = MetadataService.default;
+    }
+    /** @inheritdoc */
+    render() {
+        return html `
+      <fieldset>
+        <legend>Metadata Fetch</legend>
+        <form>
+          <label>Metadata</label>
+          <input type="text" id="metadata-input" placeholder="Identifier" />
+          <input
+            type="submit"
+            value="Get Metadata"
+            @click=${this.getMetadata}
+          />
+        </form>
+      </fieldset>
+
+      ${this.metadataResponse ? this.metadataTemplate : nothing}
+    `;
+    }
+    get metadataTemplate() {
+        var _a;
+        const rawMetadata = (_a = this.metadataResponse) === null || _a === void 0 ? void 0 : _a.metadata.rawMetadata;
+        if (!rawMetadata)
+            return html `${nothing}`;
+        return html `
+      <h2>Metadata Response</h2>
+      <table>
+        ${Object.keys(rawMetadata).map(key => html `
+            <tr>
+              <td>${key}</td>
+              <td>${unsafeHTML(rawMetadata[key])}</td>
+            </tr>
+          `)}
+      </table>
+    `;
+    }
+    async getMetadata(e) {
+        e.preventDefault();
+        const identifier = this.metadataInput.value;
+        const result = await this.metadataService.fetchMetadata(identifier);
+        this.metadataResponse = result === null || result === void 0 ? void 0 : result.success;
+    }
+    static get styles() {
+        return css `
+      /* th {
+        font-weight: bold;
+      } */
+    `;
+    }
+};
+__decorate([
+    query('#metadata-input')
+], AppRoot.prototype, "metadataInput", void 0);
+__decorate([
+    internalProperty()
+], AppRoot.prototype, "metadataResponse", void 0);
+AppRoot = __decorate([
+    customElement('app-root')
+], AppRoot);
+export { AppRoot };
+//# sourceMappingURL=app-root.js.map

package/dist/demo/app-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-root.js","sourceRoot":"","sources":["../../demo/app-root.ts"],"names":[],"mappings":";AAAA,OAAO,EACL,GAAG,EAEH,aAAa,EACb,IAAI,EACJ,gBAAgB,EAChB,UAAU,EACV,KAAK,GAEN,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGnC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,IAAa,OAAO,GAApB,MAAa,OAAQ,SAAQ,UAAU;IAAvC;;QACU,oBAAe,GAA6B,eAAe,CAAC,OAAO,CAAC;IA6D9E,CAAC;IArDC,kBAAkB;IAClB,MAAM;QACJ,OAAO,IAAI,CAAA;;;;;;;;;qBASM,IAAI,CAAC,WAAW;;;;;QAK7B,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO;KAC1D,CAAC;IACJ,CAAC;IAED,IAAY,gBAAgB;;QAC1B,MAAM,WAAW,GAAG,MAAA,IAAI,CAAC,gBAAgB,0CAAE,QAAQ,CAAC,WAAW,CAAC;QAChE,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAA,GAAG,OAAO,EAAE,CAAC;QAE1C,OAAO,IAAI,CAAA;;;UAGL,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAC5B,GAAG,CAAC,EAAE,CAAC,IAAI,CAAA;;oBAED,GAAG;oBACH,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;;WAErC,CACF;;KAEJ,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,CAAQ;QACxB,CAAC,CAAC,cAAc,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpE,IAAI,CAAC,gBAAgB,GAAG,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,OAAO,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,MAAM;QACf,OAAO,GAAG,CAAA;;;;KAIT,CAAC;IACJ,CAAC;CACF,CAAA;AA1DC;IADC,KAAK,CAAC,iBAAiB,CAAC;8CACgB;AAGzC;IADC,gBAAgB,EAAE;iDACyB;AAPjC,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CA8DnB;SA9DY,OAAO","sourcesContent":["import {\n  css,\n  CSSResult,\n  customElement,\n  html,\n  internalProperty,\n  LitElement,\n  query,\n  TemplateResult,\n} from 'lit-element';\nimport { unsafeHTML } from 'lit-html/directives/unsafe-html';\nimport { nothing } from 'lit-html';\nimport { MetadataResponse } from '../src/responses/metadata-response';\nimport { MetadataServiceInterface } from '../src/metadata-service-interface';\nimport { MetadataService } from '../src/metadata-service';\n\n@customElement('app-root')\nexport class AppRoot extends LitElement {\n  private metadataService: MetadataServiceInterface = MetadataService.default;\n\n  @query('#metadata-input')\n  private metadataInput!: HTMLInputElement;\n\n  @internalProperty()\n  private metadataResponse?: MetadataResponse;\n\n  /** @inheritdoc */\n  render(): TemplateResult {\n    return html`\n      <fieldset>\n        <legend>Metadata Fetch</legend>\n        <form>\n          <label>Metadata</label>\n          <input type=\"text\" id=\"metadata-input\" placeholder=\"Identifier\" />\n          <input\n            type=\"submit\"\n            value=\"Get Metadata\"\n            @click=${this.getMetadata}\n          />\n        </form>\n      </fieldset>\n\n      ${this.metadataResponse ? this.metadataTemplate : nothing}\n    `;\n  }\n\n  private get metadataTemplate(): TemplateResult {\n    const rawMetadata = this.metadataResponse?.metadata.rawMetadata;\n    if (!rawMetadata) return html`${nothing}`;\n\n    return html`\n      <h2>Metadata Response</h2>\n      <table>\n        ${Object.keys(rawMetadata).map(\n          key => html`\n            <tr>\n              <td>${key}</td>\n              <td>${unsafeHTML(rawMetadata[key])}</td>\n            </tr>\n          `\n        )}\n      </table>\n    `;\n  }\n\n  async getMetadata(e: Event): Promise<void> {\n    e.preventDefault();\n    const identifier = this.metadataInput.value;\n    const result = await this.metadataService.fetchMetadata(identifier);\n    this.metadataResponse = result?.success;\n  }\n\n  static get styles(): CSSResult {\n    return css`\n      /* th {\n        font-weight: bold;\n      } */\n    `;\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { Metadata } from './src/models/metadata';
+export { File } from './src/models/file';
+export { Review } from './src/models/review';
+export { SpeechMusicASREntry } from './src/models/speech-music-asr-entry';
+export { DateField } from './src/models/metadata-fields/field-types/date';
+export { NumberField } from './src/models/metadata-fields/field-types/number';
+export { StringField } from './src/models/metadata-fields/field-types/string';
+export { BooleanField } from './src/models/metadata-fields/field-types/boolean';
+export { ByteField } from './src/models/metadata-fields/field-types/byte';
+export { DurationField } from './src/models/metadata-fields/field-types/duration';
+export { PageProgressionField } from './src/models/metadata-fields/field-types/page-progression';
+export { MediaTypeField } from './src/models/metadata-fields/field-types/mediatype';
+export { MetadataFieldInterface, MetadataField, } from './src/models/metadata-fields/metadata-field';
+export { MetadataResponse } from './src/responses/metadata-response';
+export { DefaultMetadataBackend } from './src/backend/default-metadata-backend';
+export { MetadataServiceInterface } from './src/metadata-service-interface';
+export { MetadataService } from './src/metadata-service';
+export { MetadataServiceError } from './src/metadata-service-error';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { Metadata } from './src/models/metadata';
+export { File } from './src/models/file';
+export { Review } from './src/models/review';
+export { DateField } from './src/models/metadata-fields/field-types/date';
+export { NumberField } from './src/models/metadata-fields/field-types/number';
+export { StringField } from './src/models/metadata-fields/field-types/string';
+export { BooleanField } from './src/models/metadata-fields/field-types/boolean';
+export { ByteField } from './src/models/metadata-fields/field-types/byte';
+export { DurationField } from './src/models/metadata-fields/field-types/duration';
+export { PageProgressionField } from './src/models/metadata-fields/field-types/page-progression';
+export { MediaTypeField } from './src/models/metadata-fields/field-types/mediatype';
+export { MetadataField, } from './src/models/metadata-fields/metadata-field';
+export { MetadataResponse } from './src/responses/metadata-response';
+export { DefaultMetadataBackend } from './src/backend/default-metadata-backend';
+export { MetadataService } from './src/metadata-service';
+export { MetadataServiceError } from './src/metadata-service-error';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,iDAAiD,CAAC;AAE9E,OAAO,EAAE,WAAW,EAAE,MAAM,iDAAiD,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,kDAAkD,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAC;AAElF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2DAA2D,CAAC;AAEjG,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AAEpF,OAAO,EAEL,aAAa,GACd,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["export { Metadata } from './src/models/metadata';\nexport { File } from './src/models/file';\nexport { Review } from './src/models/review';\nexport { SpeechMusicASREntry } from './src/models/speech-music-asr-entry';\n\nexport { DateField } from './src/models/metadata-fields/field-types/date';\n\nexport { NumberField } from './src/models/metadata-fields/field-types/number';\n\nexport { StringField } from './src/models/metadata-fields/field-types/string';\n\nexport { BooleanField } from './src/models/metadata-fields/field-types/boolean';\n\nexport { ByteField } from './src/models/metadata-fields/field-types/byte';\n\nexport { DurationField } from './src/models/metadata-fields/field-types/duration';\n\nexport { PageProgressionField } from './src/models/metadata-fields/field-types/page-progression';\n\nexport { MediaTypeField } from './src/models/metadata-fields/field-types/mediatype';\n\nexport {\n  MetadataFieldInterface,\n  MetadataField,\n} from './src/models/metadata-fields/metadata-field';\n\nexport { MetadataResponse } from './src/responses/metadata-response';\n\nexport { DefaultMetadataBackend } from './src/backend/default-metadata-backend';\nexport { MetadataServiceInterface } from './src/metadata-service-interface';\nexport { MetadataService } from './src/metadata-service';\nexport { MetadataServiceError } from './src/metadata-service-error';\n"]}

package/dist/src/backend/default-metadata-backend.d.ts

@@ -0,0 +1,27 @@
+import type { Result } from '@internetarchive/result-type';
+import { MetadataBackendInterface } from './metadata-backend-interface';
+import { MetadataServiceError } from '../metadata-service-error';
+/**
+ * The DefaultSearchBackend performs a `window.fetch` request to archive.org
+ */
+export declare class DefaultMetadataBackend implements MetadataBackendInterface {
+    private baseUrl;
+    private includeCredentials;
+    private requestScope?;
+    constructor(options?: {
+        baseUrl?: string;
+        includeCredentials?: boolean;
+        scope?: string;
+    });
+    /** @inheritdoc */
+    fetchMetadata(identifier: string, keypath?: string): Promise<Result<any, MetadataServiceError>>;
+    /**
+     * Fires a request to the URL (with this backend's options applied) and
+     * asynchronously returns a Result object containing either the raw response
+     * JSON or a MetadataServiceError.
+     */
+    protected fetchUrl(url: string, options?: {
+        requestOptions?: RequestInit;
+    }): Promise<Result<any, MetadataServiceError>>;
+    private getErrorResult;
+}

package/dist/src/backend/default-metadata-backend.js

@@ -0,0 +1,101 @@
+import { MetadataServiceError, MetadataServiceErrorType, } from '../metadata-service-error';
+/**
+ * The DefaultSearchBackend performs a `window.fetch` request to archive.org
+ */
+export class DefaultMetadataBackend {
+    constructor(options) {
+        var _a;
+        this.baseUrl = (_a = options === null || options === void 0 ? void 0 : options.baseUrl) !== null && _a !== void 0 ? _a : 'archive.org';
+        if ((options === null || options === void 0 ? void 0 : options.includeCredentials) !== undefined) {
+            this.includeCredentials = options.includeCredentials;
+        }
+        else {
+            // include credentials if the request is coming from an archive.org domain
+            // since credentialed requests are only allowed from archive.org domains
+            // due to CORS restrictions, see
+            // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials
+            this.includeCredentials =
+                window.location.href.match(/^https?:\/\/.*archive\.org(:[0-9]+)?/) !==
+                    null;
+        }
+        if ((options === null || options === void 0 ? void 0 : options.scope) !== undefined) {
+            this.requestScope = options.scope;
+        }
+        else {
+            const currentUrl = new URL(window.location.href);
+            const scope = currentUrl.searchParams.get('scope');
+            if (scope) {
+                this.requestScope = scope;
+            }
+        }
+    }
+    /** @inheritdoc */
+    async fetchMetadata(identifier, keypath) {
+        const path = keypath ? `/${keypath}` : '';
+        const url = `https://${this.baseUrl}/metadata/${identifier}${path}`;
+        // the metadata endpoint doesn't currently support credentialed requests
+        // so don't include credentials until that is fixed
+        return this.fetchUrl(url, {
+            requestOptions: {
+                credentials: 'omit',
+            },
+        });
+    }
+    /**
+     * Fires a request to the URL (with this backend's options applied) and
+     * asynchronously returns a Result object containing either the raw response
+     * JSON or a MetadataServiceError.
+     */
+    async fetchUrl(url, options) {
+        var _a;
+        const finalUrl = new URL(url);
+        if (this.requestScope) {
+            finalUrl.searchParams.set('scope', this.requestScope);
+        }
+        let response;
+        // first try the fetch and return a networkError if it fails
+        try {
+            const fetchOptions = (_a = options === null || options === void 0 ? void 0 : options.requestOptions) !== null && _a !== void 0 ? _a : {
+                credentials: this.includeCredentials ? 'include' : 'same-origin',
+            };
+            response = await fetch(finalUrl.href, fetchOptions);
+        }
+        catch (err) {
+            const message = err instanceof Error
+                ? err.message
+                : typeof err === 'string'
+                    ? err
+                    : 'Unknown error';
+            return this.getErrorResult(MetadataServiceErrorType.networkError, message);
+        }
+        // then try json decoding and return a decodingError if it fails
+        try {
+            const json = await response.json();
+            // the advanced search endpoint doesn't return an HTTP Error 400
+            // and instead returns an HTTP 200 with an `error` key in the payload
+            const error = json['error'];
+            if (error) {
+                const forensics = json['forensics'];
+                return this.getErrorResult(MetadataServiceErrorType.searchEngineError, error, forensics);
+            }
+            else {
+                // success
+                return { success: json };
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error
+                ? err.message
+                : typeof err === 'string'
+                    ? err
+                    : 'Unknown error';
+            return this.getErrorResult(MetadataServiceErrorType.decodingError, message);
+        }
+    }
+    getErrorResult(errorType, message, details) {
+        const error = new MetadataServiceError(errorType, message, details);
+        const result = { error };
+        return result;
+    }
+}
+//# sourceMappingURL=default-metadata-backend.js.map

package/dist/src/backend/default-metadata-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-metadata-backend.js","sourceRoot":"","sources":["../../../src/backend/default-metadata-backend.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport { MetadataBackendInterface } from './metadata-backend-interface';\nimport {\n  MetadataServiceError,\n  MetadataServiceErrorType,\n} from '../metadata-service-error';\n\n/**\n * The DefaultSearchBackend performs a `window.fetch` request to archive.org\n */\nexport class DefaultMetadataBackend implements MetadataBackendInterface {\n  private baseUrl: string;\n\n  private includeCredentials: boolean;\n\n  private requestScope?: string;\n\n  constructor(options?: {\n    baseUrl?: string;\n    includeCredentials?: boolean;\n    scope?: string;\n  }) {\n    this.baseUrl = options?.baseUrl ?? 'archive.org';\n\n    if (options?.includeCredentials !== undefined) {\n      this.includeCredentials = options.includeCredentials;\n    } else {\n      // include credentials if the request is coming from an archive.org domain\n      // since credentialed requests are only allowed from archive.org domains\n      // due to CORS restrictions, see\n      // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials\n      this.includeCredentials =\n        window.location.href.match(/^https?:\\/\\/.*archive\\.org(:[0-9]+)?/) !==\n        null;\n    }\n\n    if (options?.scope !== undefined) {\n      this.requestScope = options.scope;\n    } else {\n      const currentUrl = new URL(window.location.href);\n      const scope = currentUrl.searchParams.get('scope');\n      if (scope) {\n        this.requestScope = scope;\n      }\n    }\n  }\n\n  /** @inheritdoc */\n  async fetchMetadata(\n    identifier: string,\n    keypath?: string\n  ): Promise<Result<any, MetadataServiceError>> {\n    const path = keypath ? `/${keypath}` : '';\n    const url = `https://${this.baseUrl}/metadata/${identifier}${path}`;\n    // the metadata endpoint doesn't currently support credentialed requests\n    // so don't include credentials until that is fixed\n    return this.fetchUrl(url, {\n      requestOptions: {\n        credentials: 'omit',\n      },\n    });\n  }\n\n  /**\n   * Fires a request to the URL (with this backend's options applied) and\n   * asynchronously returns a Result object containing either the raw response\n   * JSON or a MetadataServiceError.\n   */\n  protected async fetchUrl(\n    url: string,\n    options?: {\n      requestOptions?: RequestInit;\n    }\n  ): Promise<Result<any, MetadataServiceError>> {\n    const finalUrl = new URL(url);\n    if (this.requestScope) {\n      finalUrl.searchParams.set('scope', this.requestScope);\n    }\n\n    let response: Response;\n    // first try the fetch and return a networkError if it fails\n    try {\n      const fetchOptions = options?.requestOptions ?? {\n        credentials: this.includeCredentials ? 'include' : 'same-origin',\n      };\n      response = await fetch(finalUrl.href, fetchOptions);\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n          ? err\n          : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.networkError,\n        message\n      );\n    }\n\n    // then try json decoding and return a decodingError if it fails\n    try {\n      const json = await response.json();\n      // the advanced search endpoint doesn't return an HTTP Error 400\n      // and instead returns an HTTP 200 with an `error` key in the payload\n      const error = json['error'];\n      if (error) {\n        const forensics = json['forensics'];\n        return this.getErrorResult(\n          MetadataServiceErrorType.searchEngineError,\n          error,\n          forensics\n        );\n      } else {\n        // success\n        return { success: json };\n      }\n    } catch (err) {\n      const message =\n        err instanceof Error\n          ? err.message\n          : typeof err === 'string'\n          ? err\n          : 'Unknown error';\n      return this.getErrorResult(\n        MetadataServiceErrorType.decodingError,\n        message\n      );\n    }\n  }\n\n  private getErrorResult(\n    errorType: MetadataServiceErrorType,\n    message?: string,\n    details?: any\n  ): Result<any, MetadataServiceError> {\n    const error = new MetadataServiceError(errorType, message, details);\n    const result = { error };\n    return result;\n  }\n}\n"]}

package/dist/src/backend/metadata-backend-interface.d.ts

@@ -0,0 +1,20 @@
+import type { Result } from '@internetarchive/result-type';
+import { MetadataServiceError } from '../metadata-service-error';
+/**
+ * An interface to provide the network layer to the `MetadataService`.
+ *
+ * Objects implementing this interface are responsible for making calls to the Internet Archive
+ * `metadata` endpoint or otherwise providing a similar reponse in JSON format.
+ *
+ * @export
+ * @interface MetadataBackendInterface
+ */
+export interface MetadataBackendInterface {
+    /**
+     * Fetch metadata for a single item with an optional keypath
+     *
+     * @param identifier
+     * @param keypath
+     */
+    fetchMetadata(identifier: string, keypath?: string): Promise<Result<any, MetadataServiceError>>;
+}

package/dist/src/backend/metadata-backend-interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metadata-backend-interface.js.map

package/dist/src/backend/metadata-backend-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-backend-interface.js","sourceRoot":"","sources":["../../../src/backend/metadata-backend-interface.ts"],"names":[],"mappings":"","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport type { Result } from '@internetarchive/result-type';\nimport { MetadataServiceError } from '../metadata-service-error';\n\n/**\n * An interface to provide the network layer to the `MetadataService`.\n *\n * Objects implementing this interface are responsible for making calls to the Internet Archive\n * `metadata` endpoint or otherwise providing a similar reponse in JSON format.\n *\n * @export\n * @interface MetadataBackendInterface\n */\nexport interface MetadataBackendInterface {\n  /**\n   * Fetch metadata for a single item with an optional keypath\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadata(\n    identifier: string,\n    keypath?: string\n  ): Promise<Result<any, MetadataServiceError>>;\n}\n"]}

package/dist/src/metadata-service-error.d.ts

@@ -0,0 +1,11 @@
+export declare enum MetadataServiceErrorType {
+    networkError = "MetadataService.NetworkError",
+    itemNotFound = "MetadataService.ItemNotFound",
+    decodingError = "MetadataService.DecodingError",
+    searchEngineError = "MetadataService.SearchEngineError"
+}
+export declare class MetadataServiceError extends Error {
+    type: MetadataServiceErrorType;
+    details?: any;
+    constructor(type: MetadataServiceErrorType, message?: string, details?: any);
+}

package/dist/src/metadata-service-error.js

@@ -0,0 +1,18 @@
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export var MetadataServiceErrorType;
+(function (MetadataServiceErrorType) {
+    MetadataServiceErrorType["networkError"] = "MetadataService.NetworkError";
+    MetadataServiceErrorType["itemNotFound"] = "MetadataService.ItemNotFound";
+    MetadataServiceErrorType["decodingError"] = "MetadataService.DecodingError";
+    MetadataServiceErrorType["searchEngineError"] = "MetadataService.SearchEngineError";
+})(MetadataServiceErrorType || (MetadataServiceErrorType = {}));
+export class MetadataServiceError extends Error {
+    constructor(type, message, details) {
+        super(message);
+        this.name = type;
+        this.type = type;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=metadata-service-error.js.map

package/dist/src/metadata-service-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-service-error.js","sourceRoot":"","sources":["../../src/metadata-service-error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,uDAAuD;AACvD,MAAM,CAAN,IAAY,wBAKX;AALD,WAAY,wBAAwB;IAClC,yEAA6C,CAAA;IAC7C,yEAA6C,CAAA;IAC7C,2EAA+C,CAAA;IAC/C,mFAAuD,CAAA;AACzD,CAAC,EALW,wBAAwB,KAAxB,wBAAwB,QAKnC;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAK7C,YAAY,IAA8B,EAAE,OAAgB,EAAE,OAAa;QACzE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["/* eslint-disable @typescript-eslint/explicit-module-boundary-types */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nexport enum MetadataServiceErrorType {\n  networkError = 'MetadataService.NetworkError',\n  itemNotFound = 'MetadataService.ItemNotFound',\n  decodingError = 'MetadataService.DecodingError',\n  searchEngineError = 'MetadataService.SearchEngineError',\n}\n\nexport class MetadataServiceError extends Error {\n  type: MetadataServiceErrorType;\n\n  details?: any;\n\n  constructor(type: MetadataServiceErrorType, message?: string, details?: any) {\n    super(message);\n    this.name = type;\n    this.type = type;\n    this.details = details;\n  }\n}\n"]}

package/dist/src/metadata-service-interface.d.ts

@@ -0,0 +1,44 @@
+import type { MetadataResponse } from './responses/metadata-response';
+import type { Result } from '@internetarchive/result-type';
+import type { MetadataServiceError } from './metadata-service-error';
+export interface MetadataServiceInterface {
+    /**
+     * Fetch metadata for a given identifier
+     *
+     * @param {string} identifier
+     * @returns {Promise<Result<MetadataResponse, MetadataServiceError>>}
+     */
+    fetchMetadata(identifier: string): Promise<Result<MetadataResponse, MetadataServiceError>>;
+    /**
+     * Fetch the metadata value for a given identifier and keypath
+     *
+     * The response from this request can take any form, object, array, string, etc.
+     * depending on the query. You can provide return typing in the response by
+     * specifying the type. Note, there is no automatic type conversion since it can be anything.
+     *
+     * For example:
+     *
+     * ```ts
+     * const collection = await searchService.fetchMetadataValue<string>('goody', 'metadata/collection/0');
+     * console.debug('collection:', collection); => 'Goody Collection'
+     *
+     * const files_count = await searchService.fetchMetadataValue<number>('goody', 'files_count');
+     * console.debug('files_count:', files_count); => 12
+     * ```
+     *
+     * Keypath examples:
+     *
+     * /metadata/:identifier/metadata // returns the entire metadata object
+     * /metadata/:identifier/server // returns the server for the given identifier
+     * /metadata/:identifier/files_count
+     * /metadata/:identifier/files?start=1&count=2 // query for files
+     * /metadata/:identifier/metadata/collection // all collections
+     * /metadata/:identifier/metadata/collection/0 // first collection
+     * /metadata/:identifier/metadata/title
+     * /metadata/:identifier/files/0/name // first file name
+     *
+     * @param identifier
+     * @param keypath
+     */
+    fetchMetadataValue<T>(identifier: string, keypath: string): Promise<Result<T, MetadataServiceError>>;
+}

package/dist/src/metadata-service-interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metadata-service-interface.js.map

package/dist/src/metadata-service-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-service-interface.js","sourceRoot":"","sources":["../../src/metadata-service-interface.ts"],"names":[],"mappings":"","sourcesContent":["import type { MetadataResponse } from './responses/metadata-response';\nimport type { Result } from '@internetarchive/result-type';\nimport type { MetadataServiceError } from './metadata-service-error';\n\nexport interface MetadataServiceInterface {\n  /**\n   * Fetch metadata for a given identifier\n   *\n   * @param {string} identifier\n   * @returns {Promise<Result<MetadataResponse, MetadataServiceError>>}\n   */\n  fetchMetadata(\n    identifier: string\n  ): Promise<Result<MetadataResponse, MetadataServiceError>>;\n\n  /**\n   * Fetch the metadata value for a given identifier and keypath\n   *\n   * The response from this request can take any form, object, array, string, etc.\n   * depending on the query. You can provide return typing in the response by\n   * specifying the type. Note, there is no automatic type conversion since it can be anything.\n   *\n   * For example:\n   *\n   * ```ts\n   * const collection = await searchService.fetchMetadataValue<string>('goody', 'metadata/collection/0');\n   * console.debug('collection:', collection); => 'Goody Collection'\n   *\n   * const files_count = await searchService.fetchMetadataValue<number>('goody', 'files_count');\n   * console.debug('files_count:', files_count); => 12\n   * ```\n   *\n   * Keypath examples:\n   *\n   * /metadata/:identifier/metadata // returns the entire metadata object\n   * /metadata/:identifier/server // returns the server for the given identifier\n   * /metadata/:identifier/files_count\n   * /metadata/:identifier/files?start=1&count=2 // query for files\n   * /metadata/:identifier/metadata/collection // all collections\n   * /metadata/:identifier/metadata/collection/0 // first collection\n   * /metadata/:identifier/metadata/title\n   * /metadata/:identifier/files/0/name // first file name\n   *\n   * @param identifier\n   * @param keypath\n   */\n  fetchMetadataValue<T>(\n    identifier: string,\n    keypath: string\n  ): Promise<Result<T, MetadataServiceError>>;\n}\n"]}

package/dist/src/metadata-service.d.ts

@@ -0,0 +1,18 @@
+import { MetadataResponse } from './responses/metadata-response';
+import { MetadataServiceError } from './metadata-service-error';
+import type { MetadataServiceInterface } from './metadata-service-interface';
+import type { Result } from '@internetarchive/result-type';
+import { MetadataBackendInterface } from './backend/metadata-backend-interface';
+/**
+ * The Metadata Service is responsible for taking the raw response provided by
+ * the backend and modeling it as a `MetadataResponse` object.
+ */
+export declare class MetadataService implements MetadataServiceInterface {
+    static default: MetadataServiceInterface;
+    private backend;
+    constructor(backend: MetadataBackendInterface);
+    /** @inheritdoc */
+    fetchMetadata(identifier: string): Promise<Result<MetadataResponse, MetadataServiceError>>;
+    /** @inheritdoc */
+    fetchMetadataValue<T>(identifier: string, keypath: string): Promise<Result<T, MetadataServiceError>>;
+}

package/dist/src/metadata-service.js

@@ -0,0 +1,43 @@
+import { MetadataResponse } from './responses/metadata-response';
+import { MetadataServiceError, MetadataServiceErrorType, } from './metadata-service-error';
+import { DefaultMetadataBackend } from './backend/default-metadata-backend';
+/**
+ * The Metadata Service is responsible for taking the raw response provided by
+ * the backend and modeling it as a `MetadataResponse` object.
+ */
+export class MetadataService {
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /** @inheritdoc */
+    async fetchMetadata(identifier) {
+        var _a;
+        const rawResponse = await this.backend.fetchMetadata(identifier);
+        if (rawResponse.error) {
+            return rawResponse;
+        }
+        if (((_a = rawResponse.success) === null || _a === void 0 ? void 0 : _a.metadata) === undefined) {
+            return {
+                error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),
+            };
+        }
+        const modeledResponse = new MetadataResponse(rawResponse.success);
+        return { success: modeledResponse };
+    }
+    /** @inheritdoc */
+    async fetchMetadataValue(identifier, keypath) {
+        var _a;
+        const result = await this.backend.fetchMetadata(identifier, keypath);
+        if (result.error) {
+            return result;
+        }
+        if (((_a = result.success) === null || _a === void 0 ? void 0 : _a.result) === undefined) {
+            return {
+                error: new MetadataServiceError(MetadataServiceErrorType.itemNotFound),
+            };
+        }
+        return { success: result.success.result };
+    }
+}
+MetadataService.default = new MetadataService(new DefaultMetadataBackend());
+//# sourceMappingURL=metadata-service.js.map