Skip to main content

@storyteller-platform/opds

A library for generating, validating, and parsing OPDS 2.0 catalog feeds, compatible with @readium/shared.

Installation​

npm install @storyteller-platform/opds
# yarn add @storyteller-platform/opds
# deno install npm:@storyteller-platform/opds
# pnpm add @storyteller-platform/opds
# bun add @storyteller-platform/opds

Usage​

Creating a catalog feed​

import {
  Feed,
  FeedMetadata,
  Links,
  Link,
  NavigationLinks,
  NavigationLink,
  ATOM_NAV,
  OPDS_JSON,
  toAtomXml,
} from "@storyteller-platform/opds"

const feed = new Feed({
  metadata: new FeedMetadata({
    title: "Storyteller Catalog",
    identifier: "urn:uuid:12345678-1234-1234-1234-123456789012",
  }),
  navigation: new NavigationLinks([
    new NavigationLink({
      href: "/opds/v1",
      rels: new Set(["self"]),
      type: OPDS_JSON,
    }),
  ]),
  links: new Links([
    new Link({
      href: "https://storyteller.io/opds/v1",
      rels: new Set(["alternate"]),
      type: ATOM_NAV,
      title: "Storyteller OPDS v1.2 Catalog",
    }),
  ]),
  publications: [
    new OPDSPublication({
      metadata: new Metadata({
        title: "Storyteller Book 1",
        identifier: "urn:uuid:12345678-1234-1234-1234-123456789012",
      }),
      links: new Links([
        new AcquisitionLink({
          href: "https://storyteller.io/api/v2/books/12345678-1234-1234-1234-123456789012/files?format=readaloud",
          rel: "acquisition",
          type: "application/epub+zip",
        }),
      ]),
    }),
  ],
})

// produces Result<Feed>
if (feed.ok) {
  console.log(feed.value.serialize()) // opds2 feed
  console.log(toAtomXml(feed.value)) // opds 1.2 atom xml
} else {
  console.error(feed.errors)
}

Validating a catalog feed​

This library also comes with a AJV validator for the OPDS2 schema.

The validator needs to be imported from the validate sub-package.

You can use it standalone like this

import { validateFeed } from "@storyteller-platform/opds/validate"

const result = validateFeed(feed.value.serialize())
if (result.ok) {
  console.log("feed is valid")
} else {
  console.error(result.errors)
}

or when you are consuming a feed from an external source

import { Feed } from "@storyteller-platform/opds"
import { validateFeed } from "@storyteller-platform/opds/validate"

const feed = Feed.deserialize(json, { validate: validateFeed })
if (feed.ok) {
  console.log("feed is valid")
} else {
  console.error(feed.errors)
}