warengonzaga / gathertown.js

Simple and lightweight community contributed unofficial JS/TS SDK for Gather Town's HTTPS and WebSocket APIs. 🌏🕹💬

GatherTownJS

Simple and lightweight community contributed unofficial JavaScript/Typescript SDK for Gather Town's HTTPS and WebSocket APIs. 🌏🕹💬

⚡ Features

Currently it supports Gather HTTP API GET and POST requests. We are currently working on Gather Websocket API.

HTTP API (100% Coverage)

• GET getMap()
• GET getEmailGuestList()
• POST createSpace()
• POST setEmailGuestlist()
• POST setMap()

NOTE: Currently working on Websocket API support as suggested by the team at Gather. Check out the discussion here: #10 and #11.

📖 Documentation

The complete documentation can be found here:

🕹️ Usage

Example usage of the GatherTownJS.

const GATHER = require('gathertown.js'); // add gather package
const access = require('./config.json'); // load your apikey
const gather = GATHER(access.key); // access keys

// some variables
const spaceId = 'space-id/space-name';
const mapId = 'map-name';

function map() {
  gather
    .getMap({ spaceId, mapId })
    .then((data) => console.log(data))
    .catch((err) => console.log(err));
}

map();

⚓ With Hooks

const { useGather } = require('gathertown.js');
const access = require('./config.json'); // load your apikey

// some variables
const spaceId = 'space-id/space-name';
const mapId = 'map-name';

function map() {
  // load only needed functions
  const { getMap } = useGather(access.key);

  getMap({ spaceId, mapId })
    .then((data) => console.log(data))
    .catch((err) => console.log(err));
}

map();

🎯 Contributing

Contributions are welcome, create a pull request to this repo and I will review your code. Please consider to submit your pull request to the dev branch. Thank you!

Read the project's contributing guide for more info.

💬 Discussions

For any questions, suggestions, ideas, or simply you want to share your experience in using this project, feel free to share and discuss it to the community!

🐛 Issues

If you're facing a problem in using GatherTownJS please let me know by creating an issue here. I'm here to help you!

🍀 Sponsors and Supporters

Love what I do? Send me some love or coffee!? 💖☕

Can't send love or coffees? 😥 Nominate me for a GitHub Star instead! Your support will help me to continue working on open-source projects like this. 🙏😇

📋 Code of Conduct

Read the project's code of conduct.

📃 License

GatherTownJS is licensed under The MIT License.

📝 Author

GatherTownJS is created by Waren Gonzaga, with the help of awesome contributors.

---

💻💖☕ by Waren Gonzaga | YHWH 🙏

gathertown.js's Issues

official documentation for GatherJS

I might need help on this but I will create a separate issue for someone interested in working on the documentation.
I'll add basic documentation for now after the pre-release of the project.

add huntr.dev badge

Add huntr.dev badge to the readme to inform the community that this project is participating to the bounty program hosted by Huntr.

use esbuild

both parcel and esbuild dont do typechecking, this has been a discussion in the community.

do we stick with this?

• implement esbuild
• let your IDE be responsible for typechecking in development stage
• will add typechecking on yarn build

automated testing with Jest

Automated testing and can be added to the GitHub actions.
Referencing discussion #33.

Add pull request template

🤔 Not Existing Feature Request?

• Yes, I'm sure, this is a new requested feature!

🤔 Not an Idea or Suggestion?

• Yes, I'm sure, this is not idea or suggestion!

📋 Request Details

Add pull request template.

Lots of template are already available, you can use any one.

📜 Code of Conduct

• I agree to follow this project's Code of Conduct.

use optional chaining

Use optional chaining for trailing objects for more secure checking

update docs for updated HTTP API support

The documentation should be updated based on the PR (#32).
Also, I need a sample usage based on the new implementation of the API wrapper.

concern on sqaushed commits

@warengonzaga how will i create PR to dev branch if the dev branch here is squashed?

opening a PR will include all my previous commit (unsquashed)

pulling from your repo as upstream doest squash in my fork, how will i handle this

add GET API requests

I'm currently working on the GET API request first before moving to POST API requests (#3).

• getMap 2f1ed8c ✔
• getEmailGuestlist a8475bd ✔
• code refactor b6288e1 ✔

support for Gather Websocket API

I'm now adding this to my roadmap as per Gather Team. Check below for additional details about this feature.

Discussed in #9

^{Originally posted by WarenGonzaga November 1, 2021}
The Gather team informed me about their latest API which is the Websocket. Sadly, this is not in my roadmap right now. I will consider this after building the HTTP API (#8) support.

In addition, here's the Websocket API.

Any comments on this? (updates below)

regex bug

theres a regex bug on replacing slashes in space_id for bot getMap and getEmailGuestlist

here's screenshot of me testing it:
BEFORE - formatted space_id results to four (4) backward slashes

AFTER - applied fix

this fix will be included in next PR regarding #11

use eslint

For code consistency add a linter

move the homepage to orphan branch

🤔 Not Existing Feature Request?

• Yes, I'm sure, this is a new requested feature!

🤔 Not an Idea or Suggestion?

• Yes, I'm sure, this is not idea or suggestion!

📋 Request Details

This is to completely separate the development of the homepage from the SDK.

📜 Code of Conduct

• I agree to follow this project's Code of Conduct.

add POST API request

As per issue #2, I will work on this after successfully adding the GET API requests.

• createSpace (supposed to be createRoom but Gather team prefers createSpace)
• setMap
• setEmailGuestlist

add unofficial notice to readme

🤔 Not Existing Feature Request?

• Yes, I'm sure, this is a new requested feature!

🤔 Not an Idea or Suggestion?

• Yes, I'm sure, this is not idea or suggestion!

📋 Request Details

Hey guys, Gather founder here! Love what you're doing here :)

Would you mind adding a note on the webpage and README that you're not affiliated with Gather please? Just because a few people are getting confused and asking us questions about gathertown.js haha

📜 Code of Conduct

• I agree to follow this project's Code of Conduct.

landing page for GatherTownJS

I might need help on this, basic landing is enough that can be improved later.
I will include the branding here in this issue.

bent for smaller bundle size

Refer to: https://github.com/mikeal/bent

typescript support

Any plans on converting to typescript? ill be willing to contribute.

Also can setup husky for #20 which can run test and linters before commit (pre-commit hooks)
sample of the template is with a boilerplate i made node-app-bp which has husky and eslint configured and is using esbuild to compile

-> esbuild performance <-

publish to NPM as package

adding this to the official NPM as a package.

support for Gather HTTP API

Merging these issues here: #2 and #3.

Discussed in #8

^{Originally posted by WarenGonzaga November 1, 2021}
I'm currently working with the Gather team to bring their API to the hands of developers like me in the easy way possible.

Basically, this is my roadmap right now as per these issues details (#2, #3).
My reference is this: Gather HTTP API

I want to consider this adding the Websocket API (#9).

Any insights? Feel free to submit your comment!

repo banner for GatherTownJS

I might also need help with graphic design for the repo banner. If you think you can do this let me know by leaving a comment.

setEmailGuestList giving 400

🤔 Not Existing Bug?

• Yes, I'm sure that this is a bug!

👀 Current Behavior

const Gather = gather(process.env.NEXT_PUBLIC_GATHER_API_KEY as string)
        Gather.setEmailGuestlist({
            spaceId: spaceId,
            guestlist: {
                [email]: {
                    name: name,
                    role: 'guest',
                    affiliation: 'Token Holder',
                },
            },
            overwrite: false,
        })

This is the code im using but its giving an error

       {
 "success": false,
 "message": "Some error occured",
 "error": {
   "message": "Request failed with status code 400",
   "name": "Error",
   "stack": "Error: Request failed with status code 400\n    at createError (/Users/anoushkkharangate/Documents/metapass-v2/node_modules/gathertown.js/node_modules/axios/lib/core/createError.js:16:15)\n    at settle (/Users/anoushkkharangate/Documents/metapass-v2/node_modules/gathertown.js/node_modules/axios/lib/core/settle.js:17:12)\n    at IncomingMessage.handleStreamEnd (/Users/anoushkkharangate/Documents/metapass-v2/node_modules/gathertown.js/node_modules/axios/lib/adapters/http.js:293:11)\n    at IncomingMessage.emit (node:events:549:35)\n    at IncomingMessage.emit (node:domain:482:12)\n    at endReadableNT (node:internal/streams/readable:1359:12)\n    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)",
   "config": {
     "transitional": {
       "silentJSONParsing": true,
       "forcedJSONParsing": true,
       "clarifyTimeoutError": false
     },
     "transformRequest": [
       null
     ],
     "transformResponse": [
       null
     ],
     "timeout": 0,
     "xsrfCookieName": "XSRF-TOKEN",
     "xsrfHeaderName": "X-XSRF-TOKEN",
     "maxContentLength": -1,
     "maxBodyLength": -1,
     "headers": {
       "Accept": "application/json",
       "Content-Type": "application/json",
       "Access-Control-Allow-Origin": "*",
       "User-Agent": "axios/0.24.0",
       "Content-Length": 180
     },
     "baseURL": "https://gather.town/api/",
     "responseType": "json",
     "method": "post",
     "url": "setEmailGuestlist",
     "data": "{\"apiKey\":\"apikey\",\"spaceId\":\"ev6zKLqtsrTUXck2\\\\pepeparty\",\"guestlist\":{\"[email protected]\":{\"name\":\"Test1\",\"role\":\"guest\",\"affiliation\":\"Token Holder\"}},\"overwrite\":false}"
   },
   "status": 400
 }
}

🎯 Expected Behavior

it should just work

📋 Steps To Reproduce

No response

📜 Code of Conduct

• I agree to follow this project's Code of Conduct.