github-profile-status

github-profile-status

📖 Table of Contents

• Motivation
• Installation
• Example
• API
  • Constructor
    • new GitHubProfileStatus(options: ConstructorOptions)
    • Constructor Options
  • Methods
    • get(): Promise<UserStatus | null>
    • getForUser(username?: string): Promise<UserStatus | null>
    • set(status: ChangeUserStatusInput): Promise<UserStatus | null>
    • update(status: ChangeUserStatusInput): Promise<UserStatus | null>
    • clear(): Promise<boolean>
  • ChangeUserStatusInput
  • UserStatus
• Licence

Motivation

GitHub introduced a new feature that allows you to set your status on your profile!

This library gives you the ability to programmatically update your GitHub profile status. With this, you can do really interesting stuff, like displaying what you're listening to right on GitHub! The possibilities are endless!

Installation

This library is available on the npm registry as a node module and can be installed by running:

# via npm
npm install --save github-profile-status

# via yarn
yarn add github-profile-status

Example

import { GitHubProfileStatus } from 'github-profile-status';

async function main() {
  const profileStatus = new GitHubProfileStatus({
    token: process.env.GITHUB_ACCESS_TOKEN,
  });

  // set your the github profile status
  await profileStatus.set({
    emoji: ':wave:',
    message: 'Hello, world!',
    limitedAvailability: true,
  });

  // update your the github profile status
  await profileStatus.update({
    message: 'Howdy!',
  });

  // get your github profile status
  const status = await profileStatus.get();

  // clears your github profile status
  const success = await profileStatus.clear();
}

API

Constructor

new GitHubProfileStatus(options: ConstructorOptions)

Creates a new github profile status instance.

Constructor Options

An object with the following keys:

• token: string: a personal access token with the user scope.

Methods

Instances have the following methods:

get(): Promise<UserStatus | null>

Retrieves the status of the authenticated user.

Returns a Promise that resolves with the user status object, or null if the user does not have a status set.

getForUser(username?: string): Promise<UserStatus | null>

Retrieves the status of the provided user.

Returns a Promise that resolves with the user status object, or null if the user does not have a status set.

set(status: ChangeUserStatusInput): Promise<UserStatus | null>

Sets the user status using the provided status.

Note that attributes omitted from status will be cleared. If you only want to update the specified attributes without affecting any existing ones, consider using the update() method instead.

Returns a Promise that resolves with the user status object, or null if the status was cleared (e.g. providing an empty message).

update(status: ChangeUserStatusInput): Promise<UserStatus | null>

Partially updates the status with the provided attributes. All attributes of status are optional. Attributes omitted from the status object will remain as they are.

Returns a Promise that resolves with the user status object, or null if the status was cleared (e.g. providing empty attributes).

clear(): Promise<boolean>

Clears the user profile status.

Returns a Promise that resolves to a boolean indicating a successful operation.

ChangeUserStatusInput

interface ChangeUserStatusInput {
  /**
   * The emoji to represent your status. Can either be a native Unicode emoji or
   * an emoji name with colons, e.g., :wave:
   */
  emoji?: string | null;
  /**
   * If set, the user status will not be shown after this date. The value can be
   * either a Date object or an ISO-8601 encoded UTC date string.
   */
  expiresAt?: Date | string | null;
  /**
   * Whether this status should indicate you are not fully available on GitHub,
   * e.g., you are away.
   */
  limitedAvailability?: boolean;
  /**
   * A short description of your current status.
   */
  message?: string | null;
}

UserStatus

The status object has the following keys:

interface UserStatus {
  /**
   * An emoji summarizing the user's status.
   */
  emoji: string | null;
  /**
   * If set, the status will not be shown after this date.
   */
  expiresAt: string | null;
  /**
   * Whether this status indicates the user is not fully available on GitHub.
   */
  limitedAvailability: boolean;
  /**
   * A brief message describing what the user is doing.
   */
  message: string | null;
}

Licence

MIT