e621 3.2.0 → 3.2.1

package/README.md

@@ -37,6 +37,21 @@ const e621 = new E621({
 // e.g. use e621.posts.METHOD(), e621.users.METHOD()
 ```
 
+### Default Post Format
+
+Post-returning methods (`posts.get()`, `posts.search()`, `favorites.search()`, `popular.get()`, `iqdbQueries.get()`/`.post()`, and convenience methods on returned post models like `post.update()`) accept per-call `v2`/`mode` options and default to the legacy format when omitted. Set `defaultPostFormat` once to change that default everywhere instead of repeating the same options on every call:
+```typescript
+const e621 = new E621({
+	defaultPostFormat: { v2: true, mode: "extended" }
+});
+
+const post = await e621.posts.get(123); // ExtendedPost, typed accurately - no cast needed
+await post?.update({ tags: "foo" }); // also resolves to ExtendedPost
+
+// a per-call option still overrides the default for that one call
+const legacy = await e621.posts.get(123, { v2: false });
+```
+
 ## Browser Usage
 
 A pre-bundled, browser-only build (no Node built-ins) is published at `e621/browser`, for use with a plain `<script type="module">` or a CDN like jsDelivr/unpkg:
@@ -62,7 +77,7 @@ import Favorites from "e621/modules/Favorites";
 import { createE621Client, createStandalone } from "e621/standalone";
 
 // same Options as `new E621()`, handles auth headers/user agent/etc. for you
-const client = createE621Client({ authUser: "", authKey: "" }).client;
+const client  = createE621Client({ authUser: "", authKey: "" });
 
 // only the modules listed here (and their own dependencies) end up in your bundle;
 // property names are each module's own `moduleKey` (matching `new E621()`'s naming, e.g. `posts`, `favorites`)
@@ -83,7 +98,8 @@ npm test
 - `test/treeshaking.test.ts` - bundles a standalone client with esbuild and asserts unrelated modules are excluded and the result is meaningfully smaller than `new E621()`.
 - `test/standalone.test.ts` / `test/client.test.ts` - verify `createE621Client`/`createStandalone` wiring and the full `E621` client's module surface (no network calls).
 - `test/browser.test.ts` - loads the browser bundle in a real headless Chromium (via [Playwright](https://playwright.dev)) and checks it works with no Node built-ins.
-- `test/operationIds.test.ts` - scans `lib/` for every `@OperationID(...)`/`@Schema(...)` and asserts the value actually exists in the OpenAPI spec (these aren't validated at runtime anymore - see the note in `lib/util.ts` - so this plus the build-time check in `scripts/replace-openapi.ts` are what catch a typo'd one).
+- `test/openapi.test.ts` - scans `lib/` for every `@OperationID(...)`/`@Schema(...)` and asserts the value actually exists in the OpenAPI spec (these aren't validated at runtime anymore - see the note in `lib/util.ts` - so this plus the build-time check in `scripts/replace-openapi.ts` are what catch a typo'd one).
+- `test/defaultPostFormat.test.ts` - mocks `fetch` to verify `defaultPostFormat` actually reaches the outgoing request's query params, that the returned model matches, that a per-call option overrides it, and that it's picked up by model convenience methods too.
 
 CI (`.github/workflows/test.yml`) runs the same on every push/PR, and gates releases (`publish.yml`) on it passing.
 

package/dist/browser/e621.js

@@ -787,7 +787,7 @@ var createClient = (config = {}) => {
 };
 
 // dist/lib/version.js
-var VERSION = "3.2.0";
+var VERSION = "3.2.1";
 
 // dist/lib/client.js
 function createE621Client(options) {
@@ -3202,10 +3202,11 @@ var Base2 = class {
         throw new UnexpectedResponseError(res.request, res.response, res.error);
       } else {
         if (klass) {
+          const e621 = this.e621;
           if (Array.isArray(res.data))
-            return res.data.map((item) => new klass(this.e621, item));
+            return res.data.map((item) => new klass(e621, item));
           else
-            return new klass(this.e621, res.data);
+            return new klass(e621, res.data);
         } else
           return res.data;
       }
@@ -5643,6 +5644,12 @@ function wrapPosts(e621, data, v2, mode) {
 var _a2;
 var Favorites = class extends Base2 {
   static moduleKey = "favorites";
+  defaultFormat;
+  /** @param defaultFormat - The v2/mode format to fall back to when `search()` is called without explicit v2/mode options. */
+  constructor(e621, client2, defaultFormat = {}) {
+    super(e621, client2);
+    this.defaultFormat = defaultFormat;
+  }
   /**
    *
    * @requiresApiKeyAuth
@@ -5678,13 +5685,15 @@ var Favorites = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Favorites-favorites\#index Documentation} for more details.
    */
   async search(options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return favorites_index({
       client: this.client,
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.posts;
-      return wrapPosts(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.posts;
+      return wrapPosts(this.e621, raw, v2, mode);
     });
   }
 };
@@ -6664,6 +6673,12 @@ var _a3;
 var _b2;
 var IqdbQueries = class extends Base2 {
   static moduleKey = "iqdb";
+  defaultFormat;
+  /** @param defaultFormat - The v2 format to fall back to when `get()`/`post()` are called without an explicit `v2` option. `mode` is ignored - IQDB only ever returns the basic v2 format. */
+  constructor(e621, client2, defaultFormat = {}) {
+    super(e621, client2);
+    this.defaultFormat = defaultFormat;
+  }
   /**
    *
    * @operationId {@link https://e621.wiki/#operations-IQDB-iqdb_queries\#show iqdb_queries#show}
@@ -6671,14 +6686,15 @@ var IqdbQueries = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-IQDB-iqdb_queries\#show Documentation} for more details.
    */
   async get(options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
     return iqdbQueries_show({
       client: this.client,
-      query: prefixKeys(options, "search", ["v2"])
+      query: { ...prefixKeys(options, "search", ["v2"]) ?? {}, v2 }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
       return data.map((d) => ({
         hash: d.hash,
-        post: options.v2 ? new BasicPost_default(this.e621, d.post) : new IqdbPost_default(this.e621, d.post.posts),
+        post: v2 ? new BasicPost_default(this.e621, d.post) : new IqdbPost_default(this.e621, d.post.posts),
         post_id: d.post_id,
         score: d.score
       }));
@@ -6691,7 +6707,8 @@ var IqdbQueries = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-IQDB-iqdb_queries\#show_post Documentation} for more details.
    */
   async post(options) {
-    const { v2, ...body } = options;
+    const { v2: rawV2, ...body } = options ?? {};
+    const v2 = rawV2 ?? this.defaultFormat.v2;
     return iqdbQueries_showPost({
       client: this.client,
       query: { v2 },
@@ -7624,6 +7641,16 @@ var _f;
 var _g;
 var Posts = class extends Base2 {
   static moduleKey = "posts";
+  defaultFormat;
+  /**
+   * @param defaultFormat - The v2/mode format to fall back to for any method here (or any convenience
+   * method on a returned post model) called without explicit v2/mode options. Defaults to the legacy
+   * format, matching `new E621()`'s behavior when {@link Options.defaultPostFormat} isn't set.
+   */
+  constructor(e621, client2, defaultFormat = {}) {
+    super(e621, client2);
+    this.defaultFormat = defaultFormat;
+  }
   /**
    *
    * You must be Janitor+.
@@ -7716,16 +7743,18 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#show Documentation} for more details.
    */
   async get(id, options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_show({
       client: this.client,
       path: { id },
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, false);
       if (data === null)
         return null;
-      const raw = options?.v2 ? data : data.post;
-      return wrapPost(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.post;
+      return wrapPost(this.e621, raw, v2, mode);
     });
   }
   /**
@@ -7739,14 +7768,16 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#mark_as_translated Documentation} for more details.
    */
   async markTranslated(id, options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_markAsTranslated({
       client: this.client,
       path: { id },
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.post;
-      return wrapPost(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.post;
+      return wrapPost(this.e621, raw, v2, mode);
     });
   }
   /**
@@ -7789,13 +7820,15 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#random Documentation} for more details.
    */
   async random(options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_random({
       client: this.client,
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.post;
-      return wrapPost(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.post;
+      return wrapPost(this.e621, raw, v2, mode);
     });
   }
   /**
@@ -7905,17 +7938,19 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#index Documentation} for more details.
    */
   async search(options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_index({
       client: this.client,
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
       if (options?.md5) {
-        const raw2 = options.v2 ? data : data.post;
-        return wrapPost(this.e621, raw2, options.v2, options.mode);
+        const raw2 = v2 ? data : data.post;
+        return wrapPost(this.e621, raw2, v2, mode);
       }
-      const raw = options?.v2 ? data : data.posts;
-      return wrapPosts(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.posts;
+      return wrapPosts(this.e621, raw, v2, mode);
     });
   }
   /**
@@ -7925,14 +7960,16 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#show_seq Documentation} for more details.
    */
   async sequence(id, options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_showSeq({
       client: this.client,
       path: { id },
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.post;
-      return wrapPost(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.post;
+      return wrapPost(this.e621, raw, v2, mode);
     });
   }
   /**
@@ -7965,7 +8002,9 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#update Documentation} for more details.
    */
   async update(id, options) {
-    const { v2, mode, ...body } = options ?? {};
+    const { v2: rawV2, mode: rawMode, ...body } = options ?? {};
+    const v2 = rawV2 ?? this.defaultFormat.v2;
+    const mode = rawMode ?? this.defaultFormat.mode;
     return posts_update({
       client: this.client,
       path: { id },
@@ -7988,14 +8027,16 @@ var Posts = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Posts-posts\#update_iqdb Documentation} for more details.
    */
   async updateIqdb(id, options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return posts_updateIqdb({
       client: this.client,
       path: { id },
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.post;
-      return wrapPost(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.post;
+      return wrapPost(this.e621, raw, v2, mode);
     });
   }
 };
@@ -11217,6 +11258,12 @@ __decorate([
 var _a5;
 var Popular = class extends Base2 {
   static moduleKey = "popular";
+  defaultFormat;
+  /** @param defaultFormat - The v2/mode format to fall back to when `get()` is called without explicit v2/mode options. */
+  constructor(e621, client2, defaultFormat = {}) {
+    super(e621, client2);
+    this.defaultFormat = defaultFormat;
+  }
   /**
    *
    * @operationId {@link https://e621.wiki/#operations-Popular-popular\#index popular#index}
@@ -11224,13 +11271,15 @@ var Popular = class extends Base2 {
    * @see {@link https://e621.wiki/#operations-Popular-popular\#index Documentation} for more details.
    */
   async get(options) {
+    const v2 = options?.v2 ?? this.defaultFormat.v2;
+    const mode = options?.mode ?? this.defaultFormat.mode;
     return popular_index({
       client: this.client,
-      query: options
+      query: { ...options, v2, mode }
     }).then((res) => {
       const data = this._handleResponse(res, 200, true);
-      const raw = options?.v2 ? data : data.posts;
-      return wrapPosts(this.e621, raw, options?.v2, options?.mode);
+      const raw = v2 ? data : data.posts;
+      return wrapPosts(this.e621, raw, v2, mode);
     });
   }
 };
@@ -13503,76 +13552,77 @@ __decorate([
 ], StaffWikiVersions.prototype, "search", null);
 
 // dist/lib/modules/index.js
-function apply(e621, client2) {
+function apply(e621, client2, defaultPostFormat = {}) {
+  const baseE621 = e621;
   const modules = {
-    appeals: new Appeals(e621, client2),
-    artistUrls: new ArtistUrls(e621, client2),
-    artistVersions: new ArtistVersions(e621, client2),
-    artists: new Artists(e621, client2),
-    avoidPostingVersions: new AvoidPostingVersions(e621, client2),
-    avoidPostings: new AvoidPostings(e621, client2),
-    bans: new Bans(e621, client2),
-    blips: new Blips(e621, client2),
-    bulkUpdateRequests: new BulkUpdateRequests(e621, client2),
-    commentVotes: new CommentVotes(e621, client2),
-    comments: new Comments(e621, client2),
-    dbExports: new DBExports(e621, client2),
-    dmails: new DMails(e621, client2),
-    dtext: new DText(e621, client2),
-    editHistories: new EditHistories(e621, client2),
-    emailBlacklists: new EmailBlacklists(e621, client2),
-    favorites: new Favorites(e621, client2),
-    forumPosts: new ForumPosts(e621, client2),
-    forumPostVotes: new ForumPostVotes(e621, client2),
-    forumTopics: new ForumTopics(e621, client2),
-    health: new Health(e621, client2),
-    helpPages: new HelpPages(e621, client2),
-    ipBans: new IpBans(e621, client2),
-    iqdb: new IqdbQueries(e621, client2),
-    mascots: new Mascots(e621, client2),
-    modActions: new ModActions(e621, client2),
-    newsUpdates: new NewsUpdates(e621, client2),
-    notes: new Notes(e621, client2),
-    noteVersions: new NoteVersions(e621, client2),
-    pools: new Pools(e621, client2),
-    popular: new Popular(e621, client2),
-    postApprovals: new PostApprovals(e621, client2),
-    postDisapprovals: new PostDisapprovals(e621, client2),
-    postEvents: new PostEvents(e621, client2),
-    postFlags: new PostFlags(e621, client2),
-    postReplacements: new PostReplacements(e621, client2),
-    poolVersions: new PoolVersions(e621, client2),
-    postSets: new PostSets(e621, client2),
-    postVersions: new PostVersions(e621, client2),
-    postVotes: new PostVotes(e621, client2),
-    posts: new Posts(e621, client2),
-    relatedTags: new RelatedTags(e621, client2),
-    searchTrendBlacklists: new SearchTrendBlacklists(e621, client2),
-    searchTrends: new SearchTrends(e621, client2),
-    staffAutomodDMails: new StaffAutomodDMails(e621, client2),
-    staffDmails: new StaffDMails(e621, client2),
-    staffExceptionLogs: new StaffExceptionLogs(e621, client2),
-    staffFiles: new StaffFiles(e621, client2),
-    staffNotes: new StaffNotes(e621, client2),
-    staffUserCleanups: new StaffUserCleanups(e621, client2),
-    staffUsers: new StaffUsers(e621, client2),
-    staffVoteTrends: new StaffVoteTrends(e621, client2),
-    staffWikis: new StaffWikis(e621, client2),
-    staffWikiVersions: new StaffWikiVersions(e621, client2),
-    tagAliases: new TagAliases(e621, client2),
-    tagCorrections: new TagCorrections(e621, client2),
-    tagImplications: new TagImplications(e621, client2),
-    tagTypeVersions: new TagTypeVersions(e621, client2),
-    tags: new Tags(e621, client2),
-    takedowns: new Takedowns(e621, client2),
-    tickets: new Tickets(e621, client2),
+    appeals: new Appeals(baseE621, client2),
+    artistUrls: new ArtistUrls(baseE621, client2),
+    artistVersions: new ArtistVersions(baseE621, client2),
+    artists: new Artists(baseE621, client2),
+    avoidPostingVersions: new AvoidPostingVersions(baseE621, client2),
+    avoidPostings: new AvoidPostings(baseE621, client2),
+    bans: new Bans(baseE621, client2),
+    blips: new Blips(baseE621, client2),
+    bulkUpdateRequests: new BulkUpdateRequests(baseE621, client2),
+    commentVotes: new CommentVotes(baseE621, client2),
+    comments: new Comments(baseE621, client2),
+    dbExports: new DBExports(baseE621, client2),
+    dmails: new DMails(baseE621, client2),
+    dtext: new DText(baseE621, client2),
+    editHistories: new EditHistories(baseE621, client2),
+    emailBlacklists: new EmailBlacklists(baseE621, client2),
+    favorites: new Favorites(e621, client2, defaultPostFormat),
+    forumPosts: new ForumPosts(baseE621, client2),
+    forumPostVotes: new ForumPostVotes(baseE621, client2),
+    forumTopics: new ForumTopics(baseE621, client2),
+    health: new Health(baseE621, client2),
+    helpPages: new HelpPages(baseE621, client2),
+    ipBans: new IpBans(baseE621, client2),
+    iqdb: new IqdbQueries(e621, client2, defaultPostFormat),
+    mascots: new Mascots(baseE621, client2),
+    modActions: new ModActions(baseE621, client2),
+    newsUpdates: new NewsUpdates(baseE621, client2),
+    notes: new Notes(baseE621, client2),
+    noteVersions: new NoteVersions(baseE621, client2),
+    pools: new Pools(baseE621, client2),
+    popular: new Popular(e621, client2, defaultPostFormat),
+    postApprovals: new PostApprovals(baseE621, client2),
+    postDisapprovals: new PostDisapprovals(baseE621, client2),
+    postEvents: new PostEvents(baseE621, client2),
+    postFlags: new PostFlags(baseE621, client2),
+    postReplacements: new PostReplacements(baseE621, client2),
+    poolVersions: new PoolVersions(baseE621, client2),
+    postSets: new PostSets(baseE621, client2),
+    postVersions: new PostVersions(baseE621, client2),
+    postVotes: new PostVotes(baseE621, client2),
+    posts: new Posts(e621, client2, defaultPostFormat),
+    relatedTags: new RelatedTags(baseE621, client2),
+    searchTrendBlacklists: new SearchTrendBlacklists(baseE621, client2),
+    searchTrends: new SearchTrends(baseE621, client2),
+    staffAutomodDMails: new StaffAutomodDMails(baseE621, client2),
+    staffDmails: new StaffDMails(baseE621, client2),
+    staffExceptionLogs: new StaffExceptionLogs(baseE621, client2),
+    staffFiles: new StaffFiles(baseE621, client2),
+    staffNotes: new StaffNotes(baseE621, client2),
+    staffUserCleanups: new StaffUserCleanups(baseE621, client2),
+    staffUsers: new StaffUsers(baseE621, client2),
+    staffVoteTrends: new StaffVoteTrends(baseE621, client2),
+    staffWikis: new StaffWikis(baseE621, client2),
+    staffWikiVersions: new StaffWikiVersions(baseE621, client2),
+    tagAliases: new TagAliases(baseE621, client2),
+    tagCorrections: new TagCorrections(baseE621, client2),
+    tagImplications: new TagImplications(baseE621, client2),
+    tagTypeVersions: new TagTypeVersions(baseE621, client2),
+    tags: new Tags(baseE621, client2),
+    takedowns: new Takedowns(baseE621, client2),
+    tickets: new Tickets(baseE621, client2),
     uploads: new Uploads(e621, client2),
-    uploadWhitelists: new UploadWhitelists(e621, client2),
-    users: new Users(e621, client2),
-    userFeedbacks: new UserFeedbacks(e621, client2),
-    userNameChangeRequests: new UserNameChangeRequests(e621, client2),
-    wikiPages: new WikiPages(e621, client2),
-    wikiPageVersions: new WikiPageVersions(e621, client2)
+    uploadWhitelists: new UploadWhitelists(baseE621, client2),
+    users: new Users(baseE621, client2),
+    userFeedbacks: new UserFeedbacks(baseE621, client2),
+    userNameChangeRequests: new UserNameChangeRequests(baseE621, client2),
+    wikiPages: new WikiPages(baseE621, client2),
+    wikiPageVersions: new WikiPageVersions(baseE621, client2)
   };
   Object.assign(e621, modules);
 }
@@ -14024,15 +14074,22 @@ var FeedbackCategoriesSchema = {
   ]
 };
 var TagRequestStatusesSchema = {
-  type: "string",
-  enum: [
-    "active",
-    "deleted",
-    "processing",
-    "queued",
-    "retired",
-    "error",
-    "pending"
+  oneOf: [
+    {
+      type: "string",
+      enum: [
+        "active",
+        "deleted",
+        "processing",
+        "queued",
+        "retired",
+        "pending"
+      ]
+    },
+    {
+      type: "string",
+      pattern: "^error: .*$"
+    }
   ]
 };
 var WarningTypesSchema = {
@@ -19209,7 +19266,7 @@ var E621 = class {
     const { client: client2, options: resolved } = createE621Client(options);
     this.client = client2;
     this.options = resolved;
-    apply(this, this.client);
+    apply(this, this.client, options?.defaultPostFormat ?? {});
   }
 };
 var index_default = E621;