The NEW ReplAPI.it Package

The NEW ReplAPI.it Package

This release has a chock load of changes, and all projects that use previous version of ReplAPI.it will break when using the latest version. When upgrading to the latest version make sure you are using ES6 (more details below).

Changes

This list is... extensive. Be sure to read through it all if you are transitioning from older versions of the package.

Initializing ReplAPI.it

The biggest change you may notice in the version 2.x line is you cannot simply require the package and then use the classes. This is to accommodate initialization variables and utilize ES6 features. The new way to use ReplAPI.it is as so:

import ReplAPI from 'replapi-it'
const replapi = ReplAPI({
  username: 'your-username-here',
});

// use similar to previous versions
const myUser = new replapi.User("an-username");

When you are running code be sure to use the --experimental-modules tag. If you use Replit it is as simple as this in your .replit file:

run = "node index.js --experimental-modules"

Initialization Variables

ReplAPI.it now has initialization variables. This is used for many things from convenience to setting preferences. When your program is run for the first time, it will create a .replapirc.json file.

In the 2.x line, versions lower than 2.0.6 attempt to use global variables instead of dot-files. Global variables are buggy and have been depreciated.

Here are all available initialization variables:

{
  username: 'Your username for Login and Mutation Interactions (no default, accepts a string)',
  captcha: {
    token: 'A hCaptcha token for login (no default, accepts a string)',
  },
  endpoints: {
    gql: "Your preferred Replit GraphQL endpoint (default value: 'https://staging.replit.com/graphql')",
    restful: "Your preferred Replit REST endpoint (default value: 'https://staging.replit.com')",
    login: "Your preferred Replit Login endpoint (default value: 'https://staging.replit.com/login')",
  },
  markdown: {
    length: 'Your preferred length of preview content markdown on posts and comments (default value: 150)',
    removeMarkdown: 'Your preference on whether to remove markdown from previews on posts and comments (default value: false)',
  },
  previewCount: {
    comments: "Your preference on how many comments should be fetched on a post for preview (default value: 10)",
  },
  experimentalFeatures: 'Your preference on whether to enable a releases experimental features, for more info see the section below (default value: false)',
}

Experimental Features

It is a pain to wait to develop something and send it in halfway when I need to patch something. I have created experimental features to solve this. By enabling experimental features you can use some exports that have been blocked off to normal users. These features are prone to break and are not recommended for production. Use at your own risk!

Query Changes

Several older queries have broken, and newer queries have come to my attention. As such, there are many new queries available. This information should not affect you too much, but there may be new information or missing information in your projects. Change your projects as necessary and check to see if data exists before using it.

Mutation Changes

Previous versions had limited, not working support for GraphQL mutations. In this version if you provide all the necessary details and have permissions you could theoretically use mutations. The amount of mutations has been stabilized and all reasonable mutations have been added to the package. This should not affect your projects since no normal user can use mutations.

Class Changes

This section will delve into the specific changes made to all the classes. Almost all classes have some changes from the 1.x line. Read this section when migrating to the 2.x versions.

Board Class

Most changes to the board class are meta and do not have major effects on projects, however it should be noted that there is more board data with Board.boardData() and Board.boardPosts() no longer returns full posts, instead returning post previewable data (see section Posts for more information on post previewable data).

Comment Class

The Comment class has been completely revamped with support for proper mutations. The important information:

• Comment.commentData() has been split into Comment.commentDataAbridged() which returns a previewable comment and Comment.commentDataFull() which returns a full comment
• New Mutations Include:
  • Comment.createCommentOnPost()
  • Comment.createCommentOnComment()
  • Comment.updateComment()
  • Comment.deleteComment()
  • Comment.createCommentVote()
  • Comment.deleteCommentVote()

Custom Classes

The Custom Classes are two new classes that will be touched on in the next section.

Database Class

The Database Class is an experimental feature that needs to be enabled using the experimentalFeatures initialization variable. It's future usage will be to provide a better interface with more features to interact with ReplDB. Currently it is not useable.

Languages Class

Previously the Languages class was the only synchronous class. That is no long the case as the KNOWN_LANGUAGES variable is dynamically retrieved from Replit. The two functions exist from before under different names:

• Languages.getLang() --> Languages.langData()
• Languages.getLangs() --> Langauges.langDataAll()

These two functions are asynchronous and now always fetching the up-to-date KNOWN_LANGUAGES variable.

Leaderboard Class

This class mainly features meta changes that should not majorly impact your project, however it should be noted that it now returns a previewable user, not a full user.

Login Class

This class has many meta changes that should make it theoretically work, such as a hCaptcha support. Previously it only had one function Login.account(). That has been scrapped and replaced with two new functions:

• Login.withCredentials which takes your password
• Login.withSID which takes your "client-sid" cookie

Notifications Class

This class has existed since previous versions, however it has not been documented. This will continue with the change that it is under the experimental features category. It is being worked on, and has no usage to normal users.

Post Class

Similar to the Comment Class, this class features many meta changes, and new methods. To make it short:

• Post.postData() has been split into Post.postDataAbridged() which returns a previewable post and Post.postDataFull() which returns a full post
• Post.recentComments() has remained the same, however it may be worth noting that the query itself hasn't functioned like before. If it does work, it will return a full comment.
• New Mutations Include:
  • Post.createPost()
  • Post.updatePost()
  • Post.deletePost()
  • Post.createPostVote()
  • Post.deletePostVote()
• There is a new Post.posts() class which will return a list of posts on the ReplTalk Board. There is no noticeable difference between using this and Board.boardPosts() on the "all" board.

Repl Class

The Repl Class has updated query items, and will return some new data updated to reflect the new changes happening to Repls due to spotlight pages, Explore, and such. Some functions may have been renamed. Here is a list of all functions:

• Repl.replGraphQLData() ~ Returns Repl Data from the GraphQL API
• Repl.replRESTData() ~ Returns Repl Data from the Restful API
• Repl.replComments() ~ Returns Comments made on a Repl Spotlight page
• Repl.replLangs() ~ Returns statistical data from my REPLangs API
• Repl.replTitleGen() ~ A logged in function that returns the random titles that Repls use (not a joke, this was an actual query)
• Repl.recentRepls() ~ Returns recently created Repls

User Class

This is probably the most used class, so make sure your code is up to date with everything here.

• User.profileData() has been split into User.userGraphQLDataAbridged() which retuns a previewable user and User.userGraphQLDataFull() which returns a full user.
• The subscription field on full users has been removed from the GraphQL completely. The subscription query items have been preserved elsewhere in the code, but it is no longer used in the functions to reflect this change
• A new User.userRestfulData() function has been created to fetch the data from Replit's Restful user endpoint
• User.postData() has been split into User.postsDataAbridged which returns a user's posts in a previewable format and User.postsDataFull which returns a user's posts in full format
• User.commentData() has been split into User.commentsDataAbridged() which returns a user's comments in previewable format and User.commentsDataFull() which returns a user's comments in full format
• Misc.userSearch() has been moved to the User class under User.userSearch() and now it returns previewable users.

There have also been many meta changes to the User class and user query items.

Misc Class

As of the version 2.x line the Misc Class has been dissolved and any salvageable queries have been moved around and re-aliased.

The Custom Class

My main drive behind ReplAPI.it was to encourage people to use the Replit GraphQL. This has changed over the course of this refactor to making the API easy to use so that anyone can use the Replit API in their project! This is why I invented the custom query class. There are actually two parts to the Custom Query Class, replapi.CustomDataQuery and replapi.CustomRecursiveQuery. The CustomDataQuery functions like a simple request whereas the CustomRecursiveQuery acts on unpaginate pagination for items. The usage of this requires a bit more inclination towards the technical side of things, but my hope is the ReplAPI.it community will share their custom query classes for others to use. Here is a simple example of using replapi.CustomDataQuery:

import ReplAPI from 'replapi-it'
const replapi = ReplAPI({
  username: 'RayhanADev',
});

class myTestExtends extends replapi.CustomDataQuery {
  constructor(username) {
    const queryName = 'UserUsername' // Name of the query, doesn't really matter as long as it's alphanumeric and a string
    const customQuery = `
      userByUsername(username: $username) {
        username
      }` // A GraphQL query, not including the outer root of the query
    const customVariables = { username } // Variables used in the query, this will likely be passed into the constructor for your class
    super(queryName, customQuery, customVariables); // Super these three things for the class to work
  }
}

const myTestClass = new myTestExtends('RayhanADev'); // Create your custom class

async function myTestFunction() {
  const info = await myTestClass.getData(); // The .getData() function is the only one that already exists and it creates the query and sends the request
  console.log(info); // This will log my username! You can extend and change this however you like :D
}

myTestFunction(); // Call the Function

Creating custom classes is not as hard as it seems, and the new documentation will give a more in-depth tutorial on creating custom classes.

Meta Changes

Lastly, I want to touch on meta changes I made to the repository itself. As mentioned previously, I updated several GraphQL queries. I also updated the README (although it does not reflect changes made because of the version 2.x line), I added Code of Conduct and Contributing files for contributors, and I used ESLint on all files in order to make the code easier to read for contributors. This code is now completely formatted following the Airbnb style guidelines and it is expected that contributors do the same. I look forward to working with anyone brave enough to help!

Community

I have found that many more people than I thought depend on this package. Recently I even peaked at 444 downloads in a week. Some accidental changes to the main branch caused the package to go haywire for several people and resulted in some great projects breaking. I just wanted to say that I am sorry about that. I hope that no further accidents happen like this.
I wanted to take this moment to encourage people to use the Discussions section of this repository. Show off your projects, ask for help, and participate in upcoming changes to the package! Using Discussions or even Issues lets me know when a problem exists so I can address it quickly!
I also wanted to request some help on documenting these changes. I delayed documenting the version 1.x line for a long time and I do not want to delay the version 2.x line's documentation. I have all the styling and everything, the job is really simple. Contact me for more info!

Thank you for reading, and I hope you enjoy using the ReplAPI.it package in your projects.