Neutrino Packing Machine

    ib-helper
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    ib-helper

    Tests Status Downloads Version Types License

    Makes accessing the Inkbunny API just a little bit easier. Complete with TypeScript support!

    Installation

    $ npm install ib-helper
    # or
    $ yarn add ib-helper

    Prerequisites

    Make sure the account you are using has 'Enable API Access' enabled, or you won't be able to login! (https://inkbunny.net/account.php#misc)

    You can alternatively use the API as guest user (not recommended). Accessing the API in that way can be significantly slower compared to using a proper account!

    Usage

    Import

    // ES5
    var ib = require('ib-helper');
    var helper = new ib.Helper();
    
    // ES6
    import Helper from 'ib-helper';
    const helper = new Helper();

    Getting Started

    const ib = require('ib-helper');
    const helper = new ib.Helper();
    
    (async () => {
      // Login with your Inkbunny credentials
      await helper.login('<username>', '<password>');
    
      // Search submissions by tag
      const result = await helper.searchTags(['the_lion_king', 'simba']);
      const submissions = result.submissions;
    
      /* Here be Dragons */
    
      // Logout to destroy the session
      await helper.logout();
    })();

    Direct API access (not recommended)

    // ES5
    var api = require('ib-helper').api;
    
    // ES6
    import { api } from 'ib-helper';

    TypeScript

    Use with TypeScript is easy! Just import the library and start coding ^^

    import Helper from 'ib-helper';
    const helper = new Helper();

    ib-helper typescript autocomplete vscode

    Examples

    Guest user

    • log in as guest user
    • set ratings to only show sfw content
    • fetch first page of submissions
    • get second page with the nextPage() function
    • log the title of each submission

    JavaScript (guest.js) | TypeScript Version (guest.ts)

    const ib = require('ib-helper');
    
    // DISCLAIMER: Using the API as guest user can be significantly slower! Use proper credentials instead!
    
    async function main() {
      // Instantiate helper class
      const helper = new ib.Helper();
    
      // Login (left blank for guest access)
      /* SESSION MANAGEMENT included! (even refreshing) */
      await helper.login();
    
      // Adjust ratings to only show sfw content
      await helper.rating({
        nudity: false,
        violence: false,
        sexualThemes: false,
        strongViolence: false,
      });
    
      const submissions = [];
    
      /* PREWRITTEN FUNCTIONS for common use cases! */
      const firstPage = await helper.searchTags(['the_lion_king', 'simba']);
      submissions.push(...firstPage.submissions);
    
      /* PAGINATION FUNCTIONS for easier page iteration! */
      const secondPage = await firstPage.nextPage();
      submissions.push(...secondPage.submissions);
    
      // Format results
      const titles = submissions.map((s) => s.title);
    
      // Output submission titles
      titles.forEach((title) => {
        console.log(title);
      });
    
      // Logout to make sure the session gets invalidated
      await helper.logout();
    }
    main();

    Documentation

    The library only specifies what is requested by the user and doesn't set its own defaults. Always check the defaults in the Inkbunny API Documentation! (https://wiki.inkbunny.net/wiki/API)

    Helper Class

    Constructor

    Use the 'new' keyword to create a new instance of the helper class.

    const helper = new ib.Helper();

    Login

    Login using your Inkbunny credentials. The helper class will keep track of your session, so you don't have to worry about invalid tokens.

    Make sure you enabled API Access in your Inkbunny account settings!

    (LoginResponse: https://wiki.inkbunny.net/wiki/API#Response_2)

    /* REQUIRES */
    helper.login(
      // Your Inkbunny username
      username?: string,
    
      // Your Inkbunny password
      password?: string
    )
    
    /* RETURNS */
    Promise<
      LoginResponse &
      {
        // Converts the ratingsmask into a readable format
        rating: UserRating;
      }
    >
    
    /* UserRating Object */
    UserRating {
      nudity: boolean;
      violence: boolean;
      sexualThemes: boolean;
      strongViolence: boolean;
    }

    Logout

    Sign out to invalidate the current session.

    (Logout Response: https://wiki.inkbunny.net/wiki/API#Response_3)

    /* REQUIRES */
    Helper.logout()
    
    /* RETURNS */
    Promise<LogoutResponse>

    Change User Rating

    Update the user content rating (guest login only).

    (Rating Response: https://wiki.inkbunny.net/wiki/API#Response_4)

    /* REQUIRES */
    Helper.rating(
      // The new user rating
      rating: Partial<UserRating>
    )
    
    /* RETURNS */
    Promise<RatingResponse>
    
    /* UserRating Object */
    UserRating {
      nudity: boolean;
      violence: boolean;
      sexualThemes: boolean;
      strongViolence: boolean;
    }

    Search Submissions

    Search submissions based on various factors. All properties from the API are accessible. Injects helper functions to make fetching more pages easier.

    (Search Request: https://wiki.inkbunny.net/wiki/API#Parameters_4)

    (Search Response: https://wiki.inkbunny.net/wiki/API#Response_5)

    /* REQUIRES */
    Helper.search(
      params: SearchRequest
    )
    
    /* RETURNS */
    Promise<
      SearchResponse &
      {
        // Fetch the next page
        nextPage: () => Promise<SearchResponse>;
    
        // Fetch the previous page
        previousPage: () => Promise<SearchResponse>;
      }
    >

    Search Submissions By Tag

    Search submissions that contain certain tags. Injects helper functions to make fetching more pages easier.

    (Search Response: https://wiki.inkbunny.net/wiki/API#Response_5)

    /* REQUIRES */
    Helper.searchTags(
      // Required tags
      tags: string[],
    
      // Only return submission ids
      idsOnly?: boolean,
    
      // Request a certain page
      page?: number,
    
      // Amount of submissions per page
      submissionsPerPage?: number
    )
    
    /* RETURNS */
    Promise<
      SearchResponse &
      {
        // Fetch the next page
        nextPage: () => Promise<SearchResponse>;
    
        // Fetch the previous page
        previousPage: () => Promise<SearchResponse>;
      }
    >

    Submission Details

    Access the full details about specified submissions.

    (Details Response: https://wiki.inkbunny.net/wiki/API#Response_6)

    /* REQUIRES */
    Helper.details(
      // Submissions ids to fetch
      ids: string | string[],
    
      // Include the description
      includeDescription?: boolean,
    
      // Inlcude associated pools
      includePools?: boolean,
    
      // Inlcude writing (stories)
      includeWriting?: boolean
    )
    
    /* RETURNS */
    Promise<DetailsResponse>

    Install

    npm i ib-helper

    DownloadsWeekly Downloads

    1

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    37.5 kB

    Total Files

    10

    Last publish

    Collaborators

    • superscripts