@internetarchive/metadata-service 0.0.1-alpha.1

package/src/models/metadata.ts

@@ -0,0 +1,457 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Memoize } from 'typescript-memoize';
+import { BooleanField } from './metadata-fields/field-types/boolean';
+import { DateField } from './metadata-fields/field-types/date';
+import { DurationField } from './metadata-fields/field-types/duration';
+import { NumberField } from './metadata-fields/field-types/number';
+import { StringField } from './metadata-fields/field-types/string';
+import { PageProgressionField } from './metadata-fields/field-types/page-progression';
+import { ByteField } from './metadata-fields/field-types/byte';
+import { MediaTypeField } from './metadata-fields/field-types/mediatype';
+import { StringListField } from './metadata-fields/field-types/list';
+
+/**
+ * Metadata is an expansive model that describes an Item.
+ *
+ * The fields in here get casted to their respective field types. See `metadata-fields/field-type`.
+ *
+ * Add additional fields as needed.
+ *
+ * @export
+ * @class Metadata
+ */
+export class Metadata {
+  /**
+   * This is the raw metadata reponse; useful for inspecting the raw data returned from the server.
+   *
+   * @type { string: any }
+   * @memberof Metadata
+   */
+  rawMetadata?: Record<string, any>;
+
+  /**
+   * The item identifier.
+   *
+   * _Note_ This is a plain string instead of a `MetadataField` since it's
+   * the primary key of the item.
+   *
+   * @type {string}
+   * @memberof Metadata
+   */
+  get identifier(): string | undefined {
+    return this.rawMetadata?.identifier;
+  }
+
+  @Memoize() get addeddate(): DateField | undefined {
+    return this.rawMetadata?.addeddate
+      ? new DateField(this.rawMetadata.addeddate)
+      : undefined;
+  }
+
+  @Memoize() get audio_codec(): StringField | undefined {
+    return this.rawMetadata?.audio_codec
+      ? new StringField(this.rawMetadata.audio_codec)
+      : undefined;
+  }
+
+  @Memoize() get audio_sample_rate(): NumberField | undefined {
+    return this.rawMetadata?.audio_sample_rate
+      ? new NumberField(this.rawMetadata.audio_sample_rate)
+      : undefined;
+  }
+
+  @Memoize() get avg_rating(): NumberField | undefined {
+    return this.rawMetadata?.avg_rating
+      ? new NumberField(this.rawMetadata.avg_rating)
+      : undefined;
+  }
+
+  /**
+   * All of the collections that an Item is in, including
+   * all of the side-loaded collections from the ListAPI
+   * and SimpleListsAPI like `fav-*`
+   *
+   * @type {StringField}
+   * @memberof Metadata
+   */
+  @Memoize() get collection(): StringField | undefined {
+    return this.rawMetadata?.collection
+      ? new StringField(this.rawMetadata.collection)
+      : undefined;
+  }
+
+  /**
+   * The "natural" collections for an item before augmentation
+   * by side-loaded collections like ListsAPI and SimpleLists
+   *
+   * The `collection` field above includes things like all of
+   * the `fav-*` collections, whereas this is only the collections
+   * that have been directly added in the hierarchy.
+   *
+   * @type {StringField}
+   * @memberof Metadata
+   */
+  @Memoize() get collections_raw(): StringField | undefined {
+    return this.rawMetadata?.collections_raw
+      ? new StringField(this.rawMetadata.collections_raw)
+      : undefined;
+  }
+
+  /**
+   * The size of a collection in bytes
+   *
+   * @type {ByteField}
+   * @memberof Metadata
+   */
+  @Memoize() get collection_size(): ByteField | undefined {
+    return this.rawMetadata?.collection_size
+      ? new ByteField(this.rawMetadata.collection_size)
+      : undefined;
+  }
+
+  @Memoize() get contributor(): StringField | undefined {
+    return this.rawMetadata?.contributor
+      ? new StringField(this.rawMetadata.contributor)
+      : undefined;
+  }
+
+  @Memoize() get coverage(): StringField | undefined {
+    return this.rawMetadata?.coverage
+      ? new StringField(this.rawMetadata.coverage)
+      : undefined;
+  }
+
+  @Memoize() get creator(): StringField | undefined {
+    return this.rawMetadata?.creator
+      ? new StringField(this.rawMetadata.creator)
+      : undefined;
+  }
+
+  @Memoize() get date(): DateField | undefined {
+    return this.rawMetadata?.date
+      ? new DateField(this.rawMetadata.date)
+      : undefined;
+  }
+
+  @Memoize() get description(): StringField | undefined {
+    return this.rawMetadata?.description
+      ? new StringField(this.rawMetadata.description)
+      : undefined;
+  }
+
+  /**
+   * All time download count
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get downloads(): NumberField | undefined {
+    return this.rawMetadata?.downloads
+      ? new NumberField(this.rawMetadata.downloads)
+      : undefined;
+  }
+
+  /**
+   * The item duration in seconds
+   *
+   * @type {DurationField}
+   * @memberof Metadata
+   */
+  @Memoize() get duration(): DurationField | undefined {
+    return this.rawMetadata?.duration
+      ? new DurationField(this.rawMetadata.duration)
+      : undefined;
+  }
+
+  @Memoize() get 'external-identifier'(): StringField | undefined {
+    return this.rawMetadata?.['external-identifier']
+      ? new StringField(this.rawMetadata?.['external-identifier'])
+      : undefined;
+  }
+
+  /**
+   * The number of files in an item
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get files_count(): NumberField | undefined {
+    return this.rawMetadata?.files_count
+      ? new NumberField(this.rawMetadata.files_count)
+      : undefined;
+  }
+
+  @Memoize() get indexdate(): DateField | undefined {
+    return this.rawMetadata?.indexdate
+      ? new DateField(this.rawMetadata.indexdate)
+      : undefined;
+  }
+
+  @Memoize() get isbn(): StringField | undefined {
+    return this.rawMetadata?.isbn
+      ? new StringField(this.rawMetadata.isbn)
+      : undefined;
+  }
+
+  @Memoize() get issue(): StringField | undefined {
+    return this.rawMetadata?.issue
+      ? new StringField(this.rawMetadata.issue)
+      : undefined;
+  }
+
+  /**
+   * For collections, the number of items in the collection
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get item_count(): NumberField | undefined {
+    return this.rawMetadata?.item_count
+      ? new NumberField(this.rawMetadata.item_count)
+      : undefined;
+  }
+
+  /**
+   * The size of the item in bytes
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get item_size(): ByteField | undefined {
+    return this.rawMetadata?.item_size
+      ? new ByteField(this.rawMetadata.item_size)
+      : undefined;
+  }
+
+  @Memoize() get language(): StringField | undefined {
+    return this.rawMetadata?.language
+      ? new StringField(this.rawMetadata.language)
+      : undefined;
+  }
+
+  @Memoize() get length(): DurationField | undefined {
+    return this.rawMetadata?.length
+      ? new DurationField(this.rawMetadata.length)
+      : undefined;
+  }
+
+  @Memoize() get lineage(): StringField | undefined {
+    return this.rawMetadata?.lineage
+      ? new StringField(this.rawMetadata.lineage)
+      : undefined;
+  }
+
+  /**
+   * The number of downloads in the last month
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get month(): NumberField | undefined {
+    return this.rawMetadata?.month
+      ? new NumberField(this.rawMetadata.month)
+      : undefined;
+  }
+
+  @Memoize() get mediatype(): MediaTypeField | undefined {
+    return this.rawMetadata?.mediatype
+      ? new MediaTypeField(this.rawMetadata.mediatype)
+      : undefined;
+  }
+
+  @Memoize() get noindex(): BooleanField | undefined {
+    return this.rawMetadata?.noindex
+      ? new BooleanField(this.rawMetadata.noindex)
+      : undefined;
+  }
+
+  @Memoize() get notes(): StringField | undefined {
+    return this.rawMetadata?.notes
+      ? new StringField(this.rawMetadata.notes)
+      : undefined;
+  }
+
+  /**
+   * The number of users that have favorited the item
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get num_favorites(): NumberField | undefined {
+    return this.rawMetadata?.num_favorites
+      ? new NumberField(this.rawMetadata.num_favorites)
+      : undefined;
+  }
+
+  @Memoize() get num_reviews(): NumberField | undefined {
+    return this.rawMetadata?.num_reviews
+      ? new NumberField(this.rawMetadata.num_reviews)
+      : undefined;
+  }
+
+  @Memoize() get openlibrary_edition(): StringField | undefined {
+    return this.rawMetadata?.openlibrary_edition
+      ? new StringField(this.rawMetadata.openlibrary_edition)
+      : undefined;
+  }
+
+  @Memoize() get openlibrary_work(): StringField | undefined {
+    return this.rawMetadata?.openlibrary_work
+      ? new StringField(this.rawMetadata.openlibrary_work)
+      : undefined;
+  }
+
+  @Memoize() get page_progression(): PageProgressionField | undefined {
+    return this.rawMetadata?.page_progression
+      ? new PageProgressionField(this.rawMetadata.page_progression)
+      : undefined;
+  }
+
+  @Memoize() get partner(): StringField | undefined {
+    return this.rawMetadata?.partner
+      ? new StringField(this.rawMetadata.partner)
+      : undefined;
+  }
+
+  @Memoize() get ppi(): NumberField | undefined {
+    return this.rawMetadata?.ppi
+      ? new NumberField(this.rawMetadata.ppi)
+      : undefined;
+  }
+
+  @Memoize() get publicdate(): DateField | undefined {
+    return this.rawMetadata?.publicdate
+      ? new DateField(this.rawMetadata.publicdate)
+      : undefined;
+  }
+
+  @Memoize() get publisher(): StringField | undefined {
+    return this.rawMetadata?.publisher
+      ? new StringField(this.rawMetadata.publisher)
+      : undefined;
+  }
+
+  @Memoize() get reviewdate(): DateField | undefined {
+    return this.rawMetadata?.reviewdate
+      ? new DateField(this.rawMetadata.reviewdate)
+      : undefined;
+  }
+
+  @Memoize() get runtime(): DurationField | undefined {
+    return this.rawMetadata?.runtime
+      ? new DurationField(this.rawMetadata.runtime)
+      : undefined;
+  }
+
+  @Memoize() get scanner(): StringField | undefined {
+    return this.rawMetadata?.scanner
+      ? new StringField(this.rawMetadata.scanner)
+      : undefined;
+  }
+
+  @Memoize() get source(): StringField | undefined {
+    return this.rawMetadata?.source
+      ? new StringField(this.rawMetadata.source)
+      : undefined;
+  }
+
+  @Memoize() get start_localtime(): DateField | undefined {
+    return this.rawMetadata?.start_localtime
+      ? new DateField(this.rawMetadata.start_localtime)
+      : undefined;
+  }
+
+  @Memoize() get start_time(): DateField | undefined {
+    return this.rawMetadata?.start_time
+      ? new DateField(this.rawMetadata.start_time)
+      : undefined;
+  }
+
+  @Memoize() get stop_time(): DateField | undefined {
+    return this.rawMetadata?.stop_time
+      ? new DateField(this.rawMetadata.stop_time)
+      : undefined;
+  }
+
+  @Memoize() get subject(): StringListField | undefined {
+    return this.rawMetadata?.subject
+      ? new StringListField(this.rawMetadata.subject)
+      : undefined;
+  }
+
+  @Memoize() get taper(): StringField | undefined {
+    return this.rawMetadata?.taper
+      ? new StringField(this.rawMetadata.taper)
+      : undefined;
+  }
+
+  @Memoize() get title(): StringField | undefined {
+    return this.rawMetadata?.title
+      ? new StringField(this.rawMetadata.title)
+      : undefined;
+  }
+
+  @Memoize() get transferer(): StringField | undefined {
+    return this.rawMetadata?.transferer
+      ? new StringField(this.rawMetadata.transferer)
+      : undefined;
+  }
+
+  @Memoize() get track(): NumberField | undefined {
+    return this.rawMetadata?.track
+      ? new NumberField(this.rawMetadata.track)
+      : undefined;
+  }
+
+  @Memoize() get type(): StringField | undefined {
+    return this.rawMetadata?.type
+      ? new StringField(this.rawMetadata.type)
+      : undefined;
+  }
+
+  @Memoize() get uploader(): StringField | undefined {
+    return this.rawMetadata?.uploader
+      ? new StringField(this.rawMetadata.uploader)
+      : undefined;
+  }
+
+  @Memoize() get utc_offset(): NumberField | undefined {
+    return this.rawMetadata?.utc_offset
+      ? new NumberField(this.rawMetadata.utc_offset)
+      : undefined;
+  }
+
+  @Memoize() get venue(): StringField | undefined {
+    return this.rawMetadata?.venue
+      ? new StringField(this.rawMetadata.venue)
+      : undefined;
+  }
+
+  @Memoize() get volume(): StringField | undefined {
+    return this.rawMetadata?.volume
+      ? new StringField(this.rawMetadata.volume)
+      : undefined;
+  }
+
+  /**
+   * The number of downloads in the last week
+   *
+   * @type {NumberField}
+   * @memberof Metadata
+   */
+  @Memoize() get week(): NumberField | undefined {
+    return this.rawMetadata?.week
+      ? new NumberField(this.rawMetadata.week)
+      : undefined;
+  }
+
+  @Memoize() get year(): DateField | undefined {
+    return this.rawMetadata?.year
+      ? new DateField(this.rawMetadata.year)
+      : undefined;
+  }
+
+  constructor(json: Record<string, any>) {
+    this.rawMetadata = json;
+  }
+}

package/src/models/review.ts

@@ -0,0 +1,41 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Memoize } from 'typescript-memoize';
+import { DateParser, NumberParser } from '@internetarchive/field-parsers';
+
+export class Review {
+  rawValue: Record<string, any>;
+
+  get reviewbody(): string | undefined {
+    return this.rawValue.reviewbody;
+  }
+
+  get reviewtitle(): string | undefined {
+    return this.rawValue.reviewtitle;
+  }
+
+  get reviewer(): string | undefined {
+    return this.rawValue.reviewer;
+  }
+
+  @Memoize() get reviewdate(): Date | undefined {
+    return this.rawValue.reviewdate
+      ? DateParser.shared.parseValue(this.rawValue.reviewdate)
+      : undefined;
+  }
+
+  @Memoize() get createdate(): Date | undefined {
+    return this.rawValue.createdate
+      ? DateParser.shared.parseValue(this.rawValue.createdate)
+      : undefined;
+  }
+
+  @Memoize() get stars(): number | undefined {
+    return this.rawValue.stars
+      ? NumberParser.shared.parseValue(this.rawValue.stars)
+      : undefined;
+  }
+
+  constructor(json: Record<string, any>) {
+    this.rawValue = json;
+  }
+}

package/src/models/speech-music-asr-entry.ts

@@ -0,0 +1,10 @@
+/**
+ * This is the format used for radio transcripts
+ */
+export interface SpeechMusicASREntry {
+  end: number;
+  id: number;
+  is_music: boolean;
+  start: number;
+  text: string;
+}

package/src/responses/metadata-response.ts

@@ -0,0 +1,61 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { File } from '../models/file';
+import { Metadata } from '../models/metadata';
+import { Review } from '../models/review';
+import { SpeechMusicASREntry } from '../models/speech-music-asr-entry';
+
+/**
+ * The main top-level reponse when fetching Metadata
+ *
+ * @export
+ * @class MetadataResponse
+ */
+export class MetadataResponse {
+  rawResponse: any;
+
+  created: number;
+
+  d1: string;
+
+  d2: string;
+
+  dir: string;
+
+  files: File[];
+
+  files_count: number;
+
+  item_last_updated: number;
+
+  item_size: number;
+
+  metadata: Metadata;
+
+  server: string;
+
+  uniq: number;
+
+  workable_servers: string[];
+
+  speech_vs_music_asr?: SpeechMusicASREntry[];
+
+  reviews?: Review[];
+
+  constructor(json: Record<string, any>) {
+    this.rawResponse = json;
+    this.created = json.created;
+    this.d1 = json.d1;
+    this.d2 = json.d2;
+    this.dir = json.dir;
+    this.files = json.files?.map((file: any) => new File(file));
+    this.files_count = json.files_count;
+    this.item_last_updated = json.item_last_updated;
+    this.item_size = json.item_size;
+    this.metadata = new Metadata(json.metadata);
+    this.server = json.server;
+    this.uniq = json.uniq;
+    this.workable_servers = json.workable_servers;
+    this.speech_vs_music_asr = json.speech_vs_music_asr;
+    this.reviews = json.reviews?.map((entry: any) => new Review(entry));
+  }
+}

package/test/default-metadata-backend.test.ts

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { expect } from '@open-wc/testing';
+import { DefaultMetadataBackend } from '../src/backend/default-metadata-backend';
+import { MetadataServiceErrorType } from '../src/metadata-service-error';
+
+describe('DefaultMetadataBackend', () => {
+  it('can fetch metadata', async () => {
+    const fetchBackup = window.fetch;
+    window.fetch = (): Promise<Response> => {
+      return new Promise(resolve => {
+        const response = new Response('{ "foo": "bar" }');
+        resolve(response);
+      });
+    };
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.fetchMetadata('foo');
+    expect(result.success?.foo).to.equal('bar');
+    window.fetch = fetchBackup;
+  });
+
+  it('returns a networkError if theres a problem fetching using String type', async () => {
+    const fetchBackup = window.fetch;
+    window.fetch = (): Promise<Response> => {
+      throw 'network error';
+    };
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.fetchMetadata('foo');
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.networkError);
+    expect(result.error?.message).to.equal('network error');
+    window.fetch = fetchBackup;
+  });
+
+  it('returns a networkError if theres a problem fetching using Error type', async () => {
+    const fetchBackup = window.fetch;
+    window.fetch = (): Promise<Response> => {
+      throw new Error('network error');
+    };
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.fetchMetadata('foo');
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.networkError);
+    expect(result.error?.message).to.equal('network error');
+    window.fetch = fetchBackup;
+  });
+
+  it('returns a decodingError if theres a problem decoding the json', async () => {
+    const fetchBackup = window.fetch;
+    window.fetch = (): Promise<Response> => {
+      const response = new Response('boop');
+      return new Promise(resolve => resolve(response));
+    };
+
+    const backend = new DefaultMetadataBackend();
+    const result = await backend.fetchMetadata('foo');
+    expect(result.error?.type).to.equal(MetadataServiceErrorType.decodingError);
+    window.fetch = fetchBackup;
+  });
+
+  it('appends the scope if provided', async () => {
+    const fetchBackup = window.fetch;
+    let urlCalled = '';
+    window.fetch = (url: RequestInfo): Promise<Response> => {
+      urlCalled = url.toString();
+      const response = new Response('boop');
+      return new Promise(resolve => resolve(response));
+    };
+
+    const backend = new DefaultMetadataBackend({
+      scope: 'foo',
+    });
+    const result = await backend.fetchMetadata('foo');
+    expect(urlCalled.includes('scope=foo')).to.be.true;
+    window.fetch = fetchBackup;
+  });
+
+  it('does not credentials for metadata endpoint', async () => {
+    const fetchBackup = window.fetch;
+    let urlCalled: RequestInfo;
+    let urlConfig: RequestInit | undefined;
+    window.fetch = (
+      url: RequestInfo,
+      config?: RequestInit
+    ): Promise<Response> => {
+      urlCalled = url;
+      urlConfig = config;
+      const response = new Response('boop');
+      return new Promise(resolve => resolve(response));
+    };
+
+    const backend = new DefaultMetadataBackend({
+      scope: 'foo',
+      includeCredentials: true,
+    });
+    await backend.fetchMetadata('foo');
+    expect(urlConfig?.credentials).to.equal('omit');
+    window.fetch = fetchBackup;
+  });
+});