Suwatte

Chapter and title files

Give a chapter or a title a file that a person can download, such as a CBZ, an EPUB or a PDF.

A source can give a chapter or a title a file. The app downloads the file and opens it in the matching reader. Use this for a site that gives files, not pages.

Files need Suwatte 7.2.1 or later. An older app does not show them.

Give a chapter a file

Put the files in acquisitions on each chapter:

import { AcquisitionFormat, ContentRating } from "@suwatte/toolchain/types";

async getChapters(contentId: string): Promise<Chapter[]> {
  return chapters.map((chapter, position) => ({
    id: chapter.id,
    index: position,
    number: chapter.number,
    acquisitions: [
      {
        id: "cbz",
        format: AcquisitionFormat.CBZ,
        title: "Digital",
        byteCount: chapter.size,
        fileName: `${chapter.title}.cbz`,
        request: { url: chapter.downloadUrl },
      },
    ],
  }));
}

Give a title a file

Put title files in acquisitions on the title. Use this for a volume or an omnibus.

async getContent(contentId: string): Promise<Content> {
  return {
    title: "Series Name",
    coverImage: "https://example.org/cover.jpg",
    rating: ContentRating.EVERYONE,
    acquisitions: [
      {
        id: "volume-3",
        format: AcquisitionFormat.EPUB,
        title: "Volume 3",
        request: { url: `https://example.org/files/${contentId}/3.epub` },
      },
    ],
  };
}

The app shows the files in the Files list of the title. A person saves a file from that list, and the file goes into their library. If byteCount is 100 MB or more, the app asks the person before it downloads the file.

The fields

Field Necessary Notes
id Yes Unique in its list. The app sends it to resolveAcquisition.
format Yes cbz, cbr, epub or pdf.
request Yes, or resolveBeforeDownload The request for the file.
resolveBeforeDownload No Set it to true for a link that expires.
title No The name in the Files list, such as “Volume 3”.
byteCount No The size. The app shows it before the download.
fileName No A file name with its extension.

The url of a request must be a full http or https address, with no user name and no password. The header values of a request are strings. The app sends them as you give them.

The app does not send the file request through the client of your source. It does not add the base address, the headers or the interceptors of that client. Put each header that the file needs in the request. The app uses the same cookies, the same user agent and the same Cloudflare handling as a page request.

Leave out acquisitions when a chapter or a title has no files. An empty array fails validation.

A source that reads from files

A source with no getChapterPages and no getChapterText reads its chapters from files. This is a download-first source.

When a person opens a chapter in a download-first source, the app downloads the file. Then it opens the file in the matching reader. Any format works.

When a chapter has more than one file, the app selects CBZ, then CBR, PDF and EPUB. For a novel, it selects EPUB, then PDF, CBZ and CBR.

A download-first source does not work on an older app. Set minSupportedAppVersion to 7.2.1. See Versions.

A source that streams pages

A source can stream pages and also give files. When a person downloads a chapter, a CBZ or CBR file replaces the page download. Reading online still streams the pages.

The app does not use an EPUB or PDF file in place of the pages. A person saves those files from the Files list.

Some sites sign their links, or the links expire. For these, do not give a request. Set resolveBeforeDownload: true and write resolveAcquisition:

async resolveAcquisition(target: AcquisitionTarget): Promise<AcquisitionRequest> {
  const link = await this.fetchSignedLink(target.contentId, target.chapterId, target.acquisitionId);
  return { url: link };
}

The app calls resolveAcquisition immediately before each download. It does not keep the result.

The target argument holds contentId and acquisitionId. It also holds chapterId for a chapter file. A title file has no chapterId.

A source that sets resolveBeforeDownload on a file must have resolveAcquisition.

The Downloads badge

The toolchain looks for acquisitions in the code of your source. If it finds them, your source gets the Downloads badge in the source list. See Source lists.