e621 1.0.9 → 2.0.0-dev.11

package/.node-version

@@ -0,0 +1 @@
+16.13.0

package/README.md

@@ -1,195 +1,124 @@
-# 621
-A module for fetching posts from e621.
+# E621
+
+The most comprehensive wrapper for e621 you'll ever find.
+
+We support almost anything normal users can do, with plans to bring everything else in, and more later in development.
+
+### Features:
+- [x] Creating Posts (Buffer & URL)
+- [x] Listing/Creating/Editing/Voting On/Favoriting Posts
+- [x] Listing/Creating/Editing/Deleting/Modifying/Adding To/Removing From Post Sets
+- [x] Listing/Creating/Editing/Deleting/Modifying/Adding To/Removing From Pools
+- [x] Listing/Creating/Deleting/Editing User Feedback
+- [x] Reverting Pool Changes
+- [x] Listing Post History
+- [x] Editing The Authenticated User (all properties minus password and email)
+- [ ] Deleting/Approving/Unapproving/Destroying Posts
+- [ ] Creating/Solving/Deleting Post Flags
+- [ ] Listing/Creating/Editing/Deleting/Modifying Wiki Pages
+- [ ] Listing/Creating/Editing/Deleting/Modifying Artists
+- [ ] Listing/Editing/Deleting/Modifying Tags
+- [ ] General Janitorial/Moderative/Admninistrative Actions
+- [ ] More Planned!
+
+### Not Planned:
+- Dmails (routes do not support json, and I'm not scraping html)
 
-[![](https://nodei.co/npm/e621.png)](https://npm.im/e621)
 <hr>
 
-## Usage
-To use this module, simply make an instance of the main class and call one of the methods. I'll be listing parameters by providing the jsdoc.
+This module is structures with submodules corresponding to separate areas of the site. All of these modules are on the primary class, which can be constructed like so:
+```typescript
+import E621 from "e621"; // or const E621 = require("e621");
 
-## Get Posts
-```ts
-// For regular javascript usage, switch out this for `const E621 = require("e621");
-import E621 from "e621";
-/**
- * Construct an instance of E621
- *
- * @param {string} [username] - your e621 username to use for requests
- * @param {string} [apiKey] - an api key to use for requests
- * @param {string[]} [blacklist=[]] - a list of tags to use to filter out posts
- * @param {string }[userAgent] - A user agent to use for requests
- * @param {boolean} [fixNullURLs=true] - If null urls should be converted to proper urls
- * @param {string} [baseDomain=this.baseDomain] - The domain to use for api requests
- * @param {boolean} [setHost=false] - If we should set the Host header on requests to e621.net (useful for proxies).
- * @example new E621();
- * @example new E621("YourUsername", "YourAPIKey");
- * @example new E621("YourUsername", "YourAPIKey", ["male/male"]);
- * @example new E621("YourUsername", "YourAPIKey", ["male/male"], "MyAwesomeProject/1.0.0");
- * @example new E621("YourUsername", "YourAPIKey", ["male/male"], "MyAwesomeProject/1.0.0", false);
- * @example new E621("YourUsername", "YourAPIKey", ["male/male"], "MyAwesomeProject/1.0.0", false, "mye621.local");
- * @example new E621("YourUsername", "YourAPIKey", ["male/male"], "MyAwesomeProject/1.0.0", false, "mye621.local", false);
- */
-const e = new E621();
+// no options are required, see below for the options
+const e621 = new E621();
 
-/**
- * Get posts from e621
- * @param {string[]} [tags=[]] - The tags to fetch posts for, 40 max
- * @param {number} [limit=25] - The, maximum amount of posts to get, 320 max 
- * @param {number} [page=1] - The page of posts to get, see {@link https://e621.net/help/api#posts_list|E621 API Posts#List}
- * @returns {Promise<(Post | NullableURLPost)[]>}
- * @example getPosts()
- * @example getPosts("male bulge");
- * @example getPosts(["male", "bulge"]);
- * @example getPosts(["male", "bulge"], 5);
- * @example getPosts(["male", "bulge"], 5, 1);
- */
-e.getPosts(["male/male"]).then(console.log) // array of posts, see Post Structure
+// the options are all an object in the first parameter, e.g.
+const e621 = new E621({
+	authUser: "",
+	authKey:  ""
+});
 
-/**
- * Get a specifc post from e621, by id
- * @param {number} id - The id of the post to get
- * @returns {Promise<(Post | NullableURLPost)>}
- * @example getPostById(1391357)
- */
-e.getPostById(1391357).then(console.log) // single post, see Post Structure
-
-/**
- * Get a specifc post from e621, by id
- * @param {number} id - The id of the post to get
- * @returns {Promise<(Post | NullableURLPost)>}
- * @example getPostById(1391357)
- */
-e.getPostByMD5("6fd0b0f2237543bfeee5ca9318a97b46").then(console.log) // single post, see Post Structure
-```
-
-## Edit Post
-This is mostly untested, but should work
-```ts
-import E621 from "e621";
-// both username & apikey are required for edits!
-const e = new E621("YourUsername", "YourAPIKey");
-
-// they all return a post, see Post Structure
-// if no reason is provided, "Edit via https://npm.im/e621" will be used.
-
-// add tag
-e.editPost(1022094, "Some Reason Here", "added_tag");
-
-// remove tag (notice the minus)
-e.editPost(1022094, "Some Reason Here", "-remove_tag");
-
-// the undefined parts are REQUIRED if you are not using the previous parameters
-
-// add source
-e.editPost(1022094, "Some Reason Here", undefined, "https://some.added/source");
-
-// remove source (notice the minus)
-e.editPost(1022094, "Some Reason Here", undefined, "-https://some.removed/source");
-
-// update parent id
-e.editPost(1022094, "Some Reason Here", undefined, undefined, 1097929);
-
-// set description
-e.editPost(1022094, "Some Reason Here", undefined, undefined, undefined, "My Amazing Post Description");
-
-// set rating - s: safe, q: questionable, e: explicit
-e.editPost(1022094, "Some Reason Here", undefined, undefined, undefined, undefined, "e");
-
-// set rating locked
-e.editPost(1022094, "Some Reason Here", undefined, undefined, undefined, undefined, undefined, true);
-
-// set note locked
-e.editPost(1022094, "Some Reason Here", undefined, undefined, undefined, undefined, undefined, undefined, false);
-
-// set has embedded notes
-e.editPost(1022094, "Some Reason Here", undefined, undefined, undefined, undefined, undefined, undefined, undefined, true);
+// all of the available modules stem from this main class,
+// e.g. use e621.posts.METHOD(), e621.users.METHOD()
 ```
 
-## Create Post
-This is mostly untested, but should work
-```ts
-import E621 from "e621";
-// both username & apikey are required for uploading!
-const e = new E621("YourUsername", "YourAPIKey");
-
-// they all return a post, see Post Structure
-
-// minimum requirements: fileURL, tags, rating
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e");
-
-// sources
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e", 
-["https://twitter.com/Gaokunx3", "https://twitter.com/Gaokunx3/status/1275559030522556417"]);
-
-// description
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e", ["https://twitter.com/Gaokunx3", "https://twitter.com/Gaokunx3/status/1275559030522556417"], "Some Description Stuff Here");
-
-// parent id
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e", ["https://twitter.com/Gaokunx3", "https://twitter.com/Gaokunx3/status/1275559030522556417"], "Some Description Stuff Here", 1234);
-
-// referer (?)
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e", ["https://twitter.com/Gaokunx3", "https://twitter.com/Gaokunx3/status/1275559030522556417"], "Some Description Stuff Here", 1234, "https://npm.im/e621");
-
-// md5 confirmation
-e.createPost("https://pbs.twimg.com/media/EbOwnXpXkAIC5ZX.jpg:orig", ["gaokun", "bulge", "penis_outline" (...)], "e", ["https://twitter.com/Gaokunx3", "https://twitter.com/Gaokunx3/status/1275559030522556417"], "Some Description Stuff Here", 1234, "https://npm.im/e621", "abcdefghijklmnopqrstuvwxyz123456");
-```
-
-## Post Structure
-Through the e621 api, some posts can have null urls. By default, we fix this by replacing it with a proper url. You can turn this off via an option in the constructor.
-```ts
-// If you haven't used typescript, pretend this is just an object, and the values after
-// the colons are the type of what should be there
-
-// Post is just a version without the null value on file.url, preview.url, and sample.url
-interface NullableURLPost {
-	id: string;
-	created_at: string;
-	updated_at: string;
-	file: {
-		width: number;
-		height: number;
-		ext: string;
-		md5: string;
-		url: string | null;
-	};
-	preview: {
-		width: number;
-		height: number;
-		url: string | null;
-	};
-	sample: {
-		has: boolean;
-		height: number;
-		width: number;
-		url: string | null;
-		alternates: {}; // @TODO
-	};
-	score: {
-		up: number;
-		down: number;
-		total: number;
-	};
-	// a record is just a key-value pair, every key here is an array of strings
-	tags: Record<"general" | "species" | "character" | "copyright" | "artist" | "invalid" | "lore" | "meta", string[]>;
-	locked_tags: string[];
-	change_seq: number;
-	flags: Record<"pending" | "flagged" | "note_locked" | "status_locked" | "rating_locked" | "deleted", boolean>;
-	rating: "s" | "q" | "e";
-	fav_count: number;
-	sources: string[];
-	pools: number[];
-	relationships: {
-		parent_id: number | null;
-		has_children: boolean;
-		has_active_children: boolean;
-		children: number[]
-	};
-	approver_id: number | null;
-	uploader_id: number | null;
-	description: string;
-	comment_count: number;
-	is_favorited: boolean;
-	has_notes: boolean;
-	duration: number | null;
-}
-```
+#### Options
+Most of these options shouldn't be used unless you know what you're doing (you probably only need `authUser` and `authKey`, and you can set `userAgent`)
+| Option | Type | Default | Description |
+|:---:|:---:|:---:|:---:|
+| `authUser` | String | None | User for authentication |
+| `authKey` | String | None | Token for authentication |
+| `userAgent` | String | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L57-L59) | UserAgent for requests |
+| `reconstructStaticURL` | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/util/RequestHandler.ts#L254-L256) | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L63-L65) | Override default url reconstruction |
+| `imageReconstructionType` | "e621" \| "yiffy" \| "local" \| null | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L39) | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L41) |
+| `instanceSSL` | Boolean | true | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L03) |
+| `instancePort` | Number | 443 | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L9) |
+| `instanceHost` | String | e621.net | [See Code](https://github.com/DonovanDMC/E621/blob/89d662f19dc76c77e28f40b18a96f9043c4e2a3a/src/types/index.d.ts#L15) |
+
+A map of features we support to their methods is listed below.
+
+## Methods
+The legend for the symbols can be found after the table.
+| Section | Description | Location |
+|:---:|:---:|:---:|
+| Pools | Get Pool | `pools.get` |
+| Pools | Get Pool By Name | `pools.getByName` |
+| Pools | Search Pools | `pools.search` |
+| Pools | Create Pool* | `pools.create` |
+| Pools | Modify Pool* | `pools.modify` |
+| Pools | Delete Pool^ | `pools.delete` |
+| Pools | Revert Pool* | `pools.revert` |
+| Pools | Search Pool History | `pools.searchHistory` |
+| Pools | Add Post To Pool | `pools.addPost` |
+| Pools | Remove Post From Pool | `pools.removePost` |
+| Type | Description | Location |
+| Posts | Get Post By ID | `posts.get` |
+| Posts | Get Post By MD5 | `posts.getByMD5` |
+| Posts | Search Posts | `posts.search` |
+| Posts | Create Post* | `posts.create` |
+| Posts | Modify Post* | `posts.modify` |
+| Posts | Vote On Post* | `posts.vote` |
+| Posts | Revert Post* | `posts.revert` |
+| Posts | Search Post History | `posts.searchHistory` |
+| Type | Description | Location |
+| Post Sets | Get Post Set | `postSets.get` |
+| Post Sets | Search Sets | `postSets.search` |
+| Post Sets | Create Post Set* | `postSets.create` |
+| Post Sets | Modify Post Set* | `postSets.modify` |
+| Post Sets | Delete Post Set* | `postSets.delete` |
+| Post Sets | Add Post To Set* | `postSets.addPost` |
+| Post Sets | Remove Post From Set* | `postSets.removePost` |
+| Type | Description | Location |
+| User Feedback | Get Feedback | `userFeedback.get` |
+| User Feedback | Search Feedback | `userFeedback.search` |
+| User Feedback | Create Feedback# | `userFeedback.create` |
+| User Feedback | Modify Feedback# | `userFeedback.modify` |
+| User Feedback | Delete Feedback# | `userFeedback.delete` |
+| Type | Description | Location |
+| Users | Get User (ID/Name) | `users.get` |
+| Users | Search Users | `users.search` |
+| Users | Get Authenticated User* | `users.getSelf` |
+| Users | Edit Authenticated User* | `users.editSelf` |
+| Users | Get Upload Limit* | `users.getUploadLimit` |
+| Users | Get Favorites | `users.getFavorites` |
+| Users | Add Favorite* | `users.addFavorite` |
+| Users | Remove Favorite* | `users.removeFavorite` |
+| Type | Description | Location |
+| Wiki Page | Get Wiki Page | `wikiPages.get` |
+| Wiki Page | Get Wiki Page (By Name) | `wikiPages.getByName` |
+| Wiki Page | Search Wiki Pages | `wikiPages.search` |
+| Wiki Page | Create Wiki Page* | `wikiPages.create` |
+| Wiki Page | Modify Wiki Page* | `wikiPages.modify` |
+| Wiki Page | Delete Wiki Page^ | `wikiPages.delete` |
+| Wiki Page | Revert Wiki Page* | `wikiPages.revert` |
+| Wiki Page | Search Wiki Page History | `wikiPages.searchHistory` |
+
+#### Method Symbol Legend
+| Symbol | Meaning                 |
+|:------:|:-----------------------:|
+| *      | Requires Authentication |
+| $      | Requires Privileged     |
+| ^      | Requires Janitor        |
+| #      | Requires Moderator      |
+| &      | Requires Admin          |

package/build/package.json

@@ -1,12 +1,12 @@
 {
     "name": "e621",
-    "version": "1.0.9",
-    "description": "A module for fetching posts from e621.",
+    "version": "2.0.0-dev.11",
+    "description": "A module for interfacing with e621.",
     "main": "build/src/index.js",
-    "types": "build/src/index.d.ts",
     "scripts": {
-        "prepare": "rm -rf build && tsc && echo Build Finished",
-        "build": "npm run prepare"
+        "build": "rm -rf build && tsc -p tsc.json && sed -i '/__exportStar(require(\".\\/types\"), exports);/d' build/src/index.js && cp -r src/types build/src",
+        "prepublishOnly": "npm run build",
+        "dev": "npm publish --tag dev"
     },
     "repository": {
         "type": "git",
@@ -14,20 +14,23 @@
     },
     "keywords": [
         "e621",
-        "api",
         "e621-api",
+        "api",
         "e926",
-        "e926-api"
+        "e926-api",
+        "e6",
+        "e9"
     ],
-    "author": "Donovan_DMC <hewwo@yiff.rocks> (https://donovan.is.gay)",
+    "author": "Donovan Daniels <hewwo@yiff.rocks>",
     "license": "MIT",
     "bugs": {
         "url": "https://github.com/DonovanDMC/E621/issues"
     },
     "homepage": "https://github.com/DonovanDMC/E621#readme",
     "devDependencies": {
-        "@types/node": "^14.14.22",
-        "@uwu-codes/eslint-config": "^1.0.8",
-        "@uwu-codes/tsconfig": "^1.0.1"
+        "@uwu-codes/eslint-config": "^1.0.25",
+        "@uwu-codes/tsconfig": "^1.0.1",
+        "ts-node": "^10.3.0",
+        "typescript": "^4.4.4"
     }
 }