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.
A link that expires
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.