LANrurugi Plugin SDK

Exact hostnames this plugin's fetch() calls are allowed to reach — verify every one against a real URL literal in the plugin's own source before shipping it; an empty array means no network access at all.

The source's own classification ("Doujinshi", "Manga"), for the excluded-category rule.

Length, so the host can show and filter on download cost before anything is spent.

When the source published it, as the listing states it.

0–5. Absent means not yet rated, which is not the same as rated zero — a work published minutes ago usually has no rating at all, and the host treats the two differently rather than judging it at the moment the answer is least knowable.

This work's source URL, already normalised through this plugin's own canonicalizeSource so the host's duplicate check is a plain comparison. An un-normalised value silently fails to match an identical work already held, with nothing reporting the mismatch.

Namespaced as the source writes them (artist:foo), not stripped — the host's tag rules compare against these verbatim.

The work's title, by language. Keys are language tags ("ja", "en", …) plus "origin" for the title as the source itself writes it.

Who posted it — what a creator-scoped subscription matches on.

A creator/uploader to follow.

A feed or index page the user supplied, for sources whose extension cannot search unaided.

How many listing pages to read at most, supplied by the host.

Tags that scope the subscription.

Load-bearing. true when this listing was read without the sign-in it needed.

Why the result is degraded, or why nothing could be read at all.

Human-readable explanation shown in the settings UI.

Maximum transfer speed (bytes/sec) permitted against a domain matching pattern. Absent = no rate limit from this rule.

Maximum simultaneous downloads permitted against a domain matching pattern. Absent = no concurrency limit from this rule.

An exact hostname ("example.com") or a wildcard covering subdomains ("*.example.com"). Case-insensitive; no port/scheme component. Omit entirely (or use "*") for a general, non-domain-specific fallback rule. An exact-hostname match always takes precedence over a wildcard match, which always takes precedence over the general fallback.

A plugin-suggested filename, used only as a fallback when the real HTTP response has no (or an unparseable) Content-Disposition header.

Extra request headers for this specific resource (e.g. Pixiv's anti-hotlink Referer header) — absent means no extra headers beyond whatever the host's own downloader sends by default.

Defaults to "GET" when absent — every real corpus plugin (and legacy LANraragi's own Model::Upload.pm::download_url) only ever uses GET, but other methods remain representable for a future plugin that needs one.

The real, directly-fetchable resource URL.

One element = a single-file download (e.g. Chaika/EHentai-style plugins, which resolve one real download URL); more than one element = a multi-resource download (e.g. Pixiv's per-page images), assembled per the plugin's PluginOptionsResult.bundle_as_archive setting.

Pre-existing fallback escape hatch: a plugin that already downloaded/wrote a file itself and hands back a local path. Mutually exclusive with downloads; does not receive progress/concurrency/rate-limit treatment since the transfer already happened entirely inside the plugin process by the time this returns.

The full known version-history of this download's series, as this plugin's site exposes it — every source URL the plugin can enumerate, each with the timestamp the site reports for it.

Any header/token-based credential this login plugin wants a downstream metadata/download call to send (e.g. { "Authorization": "Key <api_key>" }, a bearer token, a custom signed-request header — whatever the target site's own auth scheme needs). Independent of cookies and of LegacyUserAgent entirely: a plugin using legacyCompat.userAgent() can hand back its own ua.headers snapshot here (see that property's own docs), but nothing requires going through userAgent() at all — a plugin that authenticates with a plain fetch() call and holds the resulting token in a local variable can just return { headers: { Authorization: Bearer ${token} } } directly. For a site authenticating via a header/token rather than a cookie, this is the only way that credential actually reaches a downstream call; cookies alone is empty for such a login plugin (issue #78/#93: nhapiauth's Authorization header used to have no way to cross this boundary at all before this field existed).

Present instead of tags/title on failure (e.g. a filename plugin whose regex didn't match) — a structured PluginError, not thrown, so the host can report it without the whole use_plugin call failing.

Interpolation params for the translated string — only strings/numbers (filenames, URLs, other messages, page counts, HTTP status codes: everything this SDK's real plugin corpus actually needs to interpolate), never a richer/nested value.

Bare domains (no scheme, no path, e.g. ["e-hentai.org", "exhentai.org"]) this plugin considers itself the owner of — only for domain-ownership lookups (Upload page's "fetch metadata" button, the AI wizard's coverage check), never for real dispatch (still PluginInfoResult.url_pattern's job — keep declaring that too, it should stay a precise trigger condition). Omit only when url_pattern is already a bare domain-level pattern; declare this explicitly whenever url_pattern is narrower than the domain itself (e.g. requires a specific path segment).

true only for a plugin whose source was produced by the AI plugin creation wizard (specs/006-ai-plugin-wizard, FR-026) — a wizard-generated draft always sets this literally in its own pluginInfo() return value (the wizard's generation prompt instructs the model to include it), so it survives independently of any wizard session once the file is saved to disk. Omit entirely for a hand-written/manually-uploaded plugin; the host never infers this from anything other than the plugin's own declared value.

Namespace of another "login"-type plugin to run fresh before every single call to this one (never a cached session) — mirrors legacy's exec_login_plugin (~/LANraragi/lib/LANraragi/Model/Plugins.pm:107-135). Omit entirely for a plugin that needs no login, or that is itself a "login"-type plugin (which never chases another login). A failed login attempt only logs a warning; this plugin's own call still goes ahead, just without hostArgs.user_agent_cookies populated.

Stable machine identifier — also this plugin's filename without the .ts extension once installed (metadata/ehentai.ts → namespace metadata/ehentai), and the Redis key suffix its one configurable arg value is stored under.

Prompt text for the single free-text value a user types into this plugin's "run once" dialog (as opposed to a saved settings-page PluginParameter) — e.g. a URL or gallery ID for a one-shot "copy tags from this other archive" action. Omit if this plugin has no such one-shot action.

Sidecar metadata filenames this plugin wants read out of the archive it's currently processing (basename suffixes, e.g. "ComicInfo.xml", "info.json") — lanrurugi- plugin-converter populates this automatically from every is_file_in_archive(...) call it finds in a converted plugin's source. The host resolves each name against the current archive before calling execMetadata and hands back whatever it found as MetadataHostArgs.sidecar_files: file content, never a path — this plugin itself never gets real filesystem access for this (constitution Principle IV).

A regex (JS RegExp source, no delimiters, e.g. "pixiv\\.net") matched case-insensitively against a full candidate URL to decide whether this plugin should handle it — the precise trigger condition for a real download/metadata fetch (the Upload page's own URL-queue grouping, the host's own find_matching_plugin). NOT what a domain-ownership lookup should match against — see PluginInfoResult.domain_match for that. Omit if this plugin has no meaningful URL-based routing (e.g. a script/login plugin, or a metadata/download plugin with no single well-known source domain).

Only meaningful for a plugin whose execDownload can return more than one DownloadResult.downloads element. Absent for a single-resource-only plugin (no such setting shown at all).

How often a subscription against this source may check (issue #55). Only meaningful for a plugin that also exports Discover.

The plugin's own declared default DomainRules for the domain(s) it targets. Absent/empty means the plugin declares no concurrency/rate-limit defaults of its own — that domain is unmanaged (unlimited) unless a user override exists (spec FR-017: the system itself imposes no default).

Whether starting a download for a URL this plugin handles should overwrite an existing archive that collides by content hash or destination filename, rather than the default safe behavior (reject the new file, keep the existing archive untouched). Omit if this plugin has no opinion — the effective value then falls back to the global replacedupe setting.

How to handle a download the host determines (via DownloadResult.version_history) is a NEWER revision of an already-catalogued archive.

How to handle a download the host determines is an OLDER revision of an already-catalogued archive. Optional on exactly the same terms as PluginOptionsResult.relative_newer_policy; defaults to DEFAULT_RELATIVE_OLDER_POLICY.

Matches legacy's own param.type (~/LANraragi/templates/plugins.html.tt2's SWITCH param.type — 'string' → a text input, 'bool' → a checkbox/switch, 'int' → a number input). Missing entirely before this — every converted plugin's parameters rendered as a plain, unstyled text input regardless of their real semantics, including boolean toggles like plugins/metadata/mems.ts's own 3 params (real legacy MEMS.pm declares all 3 as type => 'bool', rendered as ON/OFF switches — a plain blank text box here was a real, visible mismatch). Legacy's own unmatched-SWITCH fallback renders a type="color" picker (its source literally comments this default "ayy lmao" — an unintentional quirk, not a real 4th parameter kind any real plugin in this corpus uses); this SDK deliberately defaults absent type to 'string' instead, since every one of this corpus's 31 plugins with declared parameters had none of this field before now and were already correctly rendered/used as plain text inputs — matching legacy's silly color-picker default would have turned every one of those already-working parameters into a broken control instead of leaving them unaffected.

One static Category to create per discovered subfolder — the host creates each one after runScript returns, same read-compute-return-write-to-host split as updates (foldertocat).

Whether to delete every existing static (non-dynamic) category before creating the new ones — echoes back this call's own customargs[0], since the host applies the deletion itself (foldertocat).

Wall-clock milliseconds runScript itself spent walking the directory tree and computing groupings — reported back for a direct comparison against the equivalent native Rust endpoint (POST /database/scripts/subfolders-to-categories's own elapsed_ms), which does the identical job. Not a generic field every script plugin is expected to fill in (foldertocat only).

The matching archive's ID, when total is 1 (urlfinder).

Count of archives this call changed (nhsrcconv).

1 if a match was found, 0 otherwise (urlfinder).

This call's intended tag rewrites — the host applies each one (same shape as ScriptHostArgs.archives) after runScript returns; a plugin never writes storage directly (nhsrcconv).

ISO 8601 timestamp the site reports for this revision. The plugin converts from whatever the site's native format is (e-hentai's gdata reports posted as a unix-seconds string). Sole determiner of revision order: there is deliberately no separate "this one is current" flag, since a second source of truth could contradict the sort and leave the host no way to know which to believe.

This revision's source URL, already normalized through this plugin's own canonicalizeSource (see DownloadResult.version_history's docs — an un-normalized value silently fails to match a stored source: tag).

Perl's chomp($x) mutates $x in place, stripping exactly one trailing "\n" (Perl's default $/ record separator — not "\r\n"). JS can't mutate a caller's local binding through a function call, so converted code must reassign the result itself: x = legacyCompat.chomp(x), mirroring chomp $x;'s own mutating spirit as closely as a pure function can.

File::Basename::fileparse($path, $suffix_pattern) — every real call site in the legacy plugin corpus passes the same "match a trailing dot plus any run of non-dot characters" suffix pattern (i.e. "the last extension"), so the second argument is accepted but ignored rather than genuinely interpreting an arbitrary suffix pattern. Returns [name-without-extension, directory-with-trailing-slash, extension-with-leading-dot], matching Perl's own return order.

get_logger($name, $category) — see LegacyLogger's own docs for exactly what's covered.

LANraragi::Utils::Generic::get_version — legacy reads this straight out of its own package.json (version/homepage fields) once and caches it; this returns the equivalent static values for this project instead of trying to read a Rust crate's Cargo.toml from within the Deno sandbox. Update these two literals if Cargo.toml's [workspace.package] version/repository ever changes.

Mojo::Util::html_unescape — decodes HTML entities (named: &/</"/etc., and numeric: '/'). No native JS equivalent outside a real DOM (a textarea element's .value trick, unavailable in this Deno sandbox — there's no document), so reimplemented directly against the HTML5 entity table's most common names rather than pulling in a full HTML entity library for what the legacy plugin corpus only ever uses on scraped titles/summaries (a handful of the same few entities in practice).

Mojo::DOM->new(html) / Mojo::DOM->new->xml(1)->parse(xml) — parses markup and returns its root node. xml toggles case-sensitive tag matching (real XML/custom elements like <Genre> in a ComicInfo.xml file) vs HTML's traditionally case-insensitive tag names; see LegacyDomNode's own docs for what's covered.

LANraragi::Utils::Redis::redis_decode — legacy re-decodes a value read back from Redis as UTF-8, since Perl's own Redis client hands back raw bytes. Deno's Redis client (and every string this dispatcher otherwise touches) is already a proper UTF-8 JS string by the time a plugin sees it, so this is a pure pass-through.

Perl's ref($x) builtin — returns "HASH"/"ARRAY" for a hashref/arrayref, or "" for anything else (a plain scalar, undef, etc.), matching Perl's own string-truthiness rule closely enough that ref($x) used as a bare boolean condition (return if ref $x;) works unmodified once translated. Only hashref/arrayref detection — real Perl ref() also recognizes CODE/SCALAR/blessed-object-class-name, none of which the legacy plugin corpus's own use of ref() ever tests for.

Perl's reverse(@list) returns a new list; JS's Array.prototype.reverse mutates its receiver in place. Spreads into a fresh array first so converted code doesn't pick up a mutation side effect the original Perl never had.

Perl's sleep($seconds) blocks synchronously; JS has no synchronous sleep, so this is a setTimeout-backed Promise instead — every call site must await it (the converter's own sleep mapping in render.rs always emits the await, forcing the enclosing function async the same way an awaited ->get()/->post() Mojo call already does).

A minimal sprintf covering the format-spec subset actually used across the legacy plugin corpus (%s, %d, %f with optional width/precision) — not a full reimplementation of Perl's considerably larger sprintf grammar.

LANraragi::Utils::String::trim — strips leading/trailing whitespace, returning "" for null/undefined instead of throwing (unlike JS's own String.prototype.trim, which requires a real string receiver).

Mojo::UserAgent->new — see LegacyUserAgent's own docs for exactly what's covered. Every plugin using this must still declare its own real target host(s) in declared_permissions (constitution Principle IV); this shim runs inside that same already-permission-scoped process, so it's bound by whatever --allow-net grant the plugin itself was started with, same as a plugin calling fetch() directly would be.