groupme-js / node-groupme

The only GroupMe API library for NodeJS that isn't a million years old.

node-groupme

✔️ This package is in active development! If you'd like to contribute, click here 🙂

About

Inspired by discord.js, node-groupme aims to replace the obsolete groupme package with a modern, object-oriented, intuitive approach to interacting with the GroupMe API.

---

This community-led effort is made possible by the unofficial GroupMe API Community Docs. Please contribute to the development of open-source applications by contributing to the community docs.

Join the node-groupme server on Discord to discuss the API or ask any questions.

---

Getting Started

npm i node-groupme

const GroupMe = require('node-groupme');
const client = new GroupMe.Client('YOUR_TOKEN_HERE');

client.login()
    .then(client => client.groups.fetch())
    .then(groups => groups.forEach(group => console.log(group.name)))
    .then(client.logout)
    .catch(console.error);

---

Getting Started (Contributing)

git clone [email protected]:groupme-js/node-groupme.git
npm i
npm run prepare

npm run prepare sets up husky pre-commit hooks, which will auto format and run eslint on your staged files locally.

node-groupme's Issues

Disable SMS

Upload video

Get active groups

GroupManager#fetch(): Promise<Collection<string, Group>>
GroupManager#fetch(id: string): Promise<Group>
GroupManager#fetch(ids: string[]): Promise<Collection<string, Group | null>>

Fetches groups.
If called with no parameters, fetches all groups.
If a single group ID is specified, fetches only that group.
If an array of group IDs is specified, fetches those groups and returns a Collection of groups fetched.

Usage:

client.groups.fetch()
client.groups.fetch('123456789')
client.groups.fetch(['123456789', '987654321'])

Get single group by ID

see GroupManager#fetch() overloads in #4

Get messages

GroupMessageManager#fetch(): Promise<Collection<string, Message>>
GroupMessageManager#fetch(options: GroupMessageFetchOptions): Promise<Collection<string, Message>>

Fetches messages from a group.
The options parameter can be used to modify the query.
If called with no arguments, this function fetches all messages in the group.

Usage:

const group = client.groups.cache.get('12345')

group.messages.fetch()
group.messages.fetch({ limit: 50 })

A useful overload of this method would be fetch(id: string) to fetch a single message from a group.

Get poll by ID

API coverage checklist

Current state of API coverage

Groups

• #4
  • Framework
  • Implementation
  • Tests
• #5
  • Framework
  • Implementation
  • Tests
• #6
  • Framework
  • Implementation
  • Tests
• #7
  • Framework
  • Implementation
  • Tests
• #8
  • Framework
  • Implementation
  • Tests
• #9
  • Framework
  • Implementation
  • Tests
• #10
  • Framework
  • Implementation
  • Tests
• #11
  • Framework
  • Implementation
  • Tests
• #12
  • Framework
  • Implementation
  • Tests

Group Messages

• #13
  • Framework
  • Implementation
  • Tests
• #14
  • Framework
  • Implementation
  • Tests
• #15
  • Framework
  • Implementation
  • Tests

Members

• #16
  • Framework
  • Implementation
  • Tests
• #17
  • Framework
  • Implementation
  • Tests
• #18
  • Framework
  • Implementation
  • Tests
• #19
  • Framework
  • Implementation
  • Tests

Chats

• #20
  • Framework
  • Implementation
  • Tests

Chat Messages

• #21
  • Framework
  • Implementation
  • Tests
• #22
  • Framework
  • Implementation
  • Tests
• #23
  • Framework
  • Implementation
  • Tests

Users

• #24
  • Framework
  • Implementation
  • Tests
• #25
  • Framework
  • Implementation
  • Tests
• #26
  • Framework
  • Implementation
  • Tests
• #27
  • Framework
  • Implementation
  • Tests

Likes

• #28
  • Framework
  • Implementation
  • Tests
• #29
  • Framework
  • Implementation
  • Tests
• #30
  • Framework
  • Implementation
  • Tests
• #31
  • Framework
  • Implementation
  • Tests
• #32
  • Framework
  • Implementation
  • Tests

Calendar

• #33
  • Framework
  • Implementation
  • Tests
• #34
  • Framework
  • Implementation
  • Tests
• #35
  • Framework
  • Implementation
  • Tests
• #36
  • Framework
  • Implementation
  • Tests
• #37
  • Framework
  • Implementation
  • Tests
• #38
  • Framework
  • Implementation
  • Tests

Account

• #39
  • Framework
  • Implementation
  • Tests
• #40
  • Framework
  • Implementation
  • Tests
• #41
  • Framework
  • Implementation
  • Tests
• #42
  • Framework
  • Implementation
  • Tests

Polls

• #43
  • Framework
  • Implementation
  • Tests
• #44
  • Framework
  • Implementation
  • Tests
• #45
  • Framework
  • Implementation
  • Tests
• #46
  • Framework
  • Implementation
  • Tests
• #47
  • Framework
  • Implementation
  • Tests

Attachments

• #48
  • Framework
  • Implementation
  • Tests
• #49
  • Framework
  • Implementation
  • Tests
• #50
  • Framework
  • Implementation
  • Tests

Push

• Implement push events

Miscellaneous and v4 stuff

• Pending memberships
• Relationships

Bots (ignored for now)

Enable SMS

Unlike message

Rejoin former group

FormerGroup#rejoin(): Promise<Group>

Rejoins a group that had previously been left.

Usage:

const formerGroup = client.groups.former.cache.get('12345')
formerGroup.rejoin()

Subtask: Fetch results of Add members

This implementation would need to resolve the Promise returned from Group#add.

this could either be done by long-polling the API or maybe via websockets?

if the average add call doesn't take too long, maybe spamming API requests for a couple seconds would be fine?

would need to have a timeout in case the API never returns for some reason

Like message

Add members

Group#add(id): Promise<Member>
Group#add(ids: []): Promise<Collection<string, Member | null>>

Add a user (or users) to a group.

Usage:

const group = client.groups.cache.get('12345')

group.add('67890')
group.add(['67890', '24680'])

Create poll

Transfer ownership

Group#transferOwnershipTo(newOwner: string): Promise<Group>

Transfers ownership of a group to another user.

Usage:

const group = client.groups.cache.get('12345')
group.transferOwnershipTo('67890');

Apparently, the API only does change_owner requests in bulk for some reason. This is dumb, so the library will not reflect this bulk transfer operation. Instead, transfers will be done directly on Group instances and each call will only send one change_owner request, despite the API allowing for multiple to be sent at once.

Block user

Get all blocks

Delete message

Update event

Get messages

End poll

Add Resolvable types

Several methods could benefit from abstract resolvable types for parameters.

For example: Groups#add(user) could take a user ID string, a User object, or even a Member object.

Some possible resolvable types:

type UserResolvable = string | User;
type MemberResolvable = string | Member; // could User work here too?
type GroupResolvable = string | Group; // would it be a good idea to include Member here?

The corresponding class would have (static?) methods for resolving these.

Group.resolve(GroupResolvable): Group // do these need to be async...?
Member.resolve(MemberResolvable): Member
User.resolve(UserResolvable): User

Update group

Group#update(options: GroupUpdateOptions): Promise<Group>

Updates a group.

Usage:

const group = client.groups.cache.get('12345')
group.update({ name: "cool new name" })

It might be useful to split this up into multiple methods such as changeName(), changeDescription(), etc.
Each of these could still use the underlying Group#update() method, but this way users don't have to rely on knowing the GroupUpdateOptions object inside and out.

Check for block from other user

Get details

Vote

Undo RSVP

Get given likes

Get events

Create group

GroupManager#create(options: GroupCreateOptions): Promise<Group>

Creates a new group.
It would probably be worth describing the GroupCreateOptions object, but I'll decide on that later.

Usage:

client.groups.create({ name: "my awesome group" })

Remove member

Member#remove(): Promise<FormerMember> (is this a meaningful distinction?)

Removes a member from the group.

Usage:

const group = client.groups.cache.get('12345')
const member = group.members.cache.get('67890')
member.remove()

Get chats

ChatManager#fetch(): Promise<Collection<string, Chat>>
ChatManager#fetch(options: ChatFetchOptions): Promise<Collection<string, Chat>>

Fetches chats from the API. The options parameter can be used to specify pagination.

Usage:

client.chats.fetch()

Delete message

GroupMessage#delete(): Promise<void>
GroupMessage#delete(timeout: number): Promise<void>

Deletes a message from a group.

Usage:

const group = client.groups.cache.get('12345')
const message = group.messages.cache.get('67890')
message.delete()

group.send('this message will self-destruct in 5 seconds...')
    .then(message => message.delete(5000))

Add RSVP

Asynchronous client construction

Some properties on the Client object (Client.user) rely on asynchronous operations (fetching /users/me).

Perhaps making the constructor private and providing an async function that returns a new Client object would be a better idea?

This way, all properties on the Client object can be definitely assigned in the constructor. (no more unnecessary ? types)

Update details

Create event

Join group

GroupManager#join(inviteLink: string): Promise<Group>
GroupManager#join(groupID: string, shareToken: string): Promise<Group>

Joins a group.
Can take either an invite URL, or a combination of group ID and share token as parameters.

Usage:

client.groups.join('https://groupme.com/join_group/27317261/ibNNhx')
client.groups.join('27317261', 'ibNNhx')

Invite links can take a number of forms depending on the client it was created with. The inviteLink overload will need to take this into account.

Get all polls

Get leaderboard

Upload image

Delete group

Group#delete(): Promise<void>

Deletes a group.

Usage:

const group = client.groups.cache.get('12345')
group.delete()

Delete event

Upload File

Change nickname

ClientMember#setNickname(nickname: string): Promise<ClientMember>

Changes the client member's nickname in the group.

Usage:

const group = client.groups.cache.get('12345')
group.me.setNickname('Pete')

Send message

Unblock user

Get received likes

Get former groups

FormerGroupManager#fetch(): Promise<Collection<string, FormerGroup>>

Fetches all former groups.

I'm not sure whether it's possible to fetch a former group by ID, and I don't see why you would even want to, so I don't care to investigate this. Maybe it can be researched and implemented later if anyone feels like doing it.

Usage:

client.groups.former.fetch()

Send message

Polymorphic send

this is going to involve a lot of overload signatures and type checking.

Group#send(text: string): Promise<Message>
Group#send(options: GroupSendMessageOptions): Promise<Message>

Sends a message to a group.

Usage:

const group = client.groups.cache.get('12345')

group.send('hi guys')
group.send({
    text: "here's a picture of my dog",
    image: "https://i.imgur.com/NPUoRh5.png" 
})

come up with more overloads later, like sending a message with only an image or a user resolvable or something like that