gizmo-api

A minimal wrapper for interfacing with the Gizmo API.

Table of Contents

• Installation
  • Node
  • Browser
• Building
• Usage
• Example
• Documentation
  • Interfaces
    • User
    • AuthenticatedUser
  • Methods
    • getUserById
    • getAuthenticatedUser
    • searchForUser
    • login

Installation

Node

npm i gizmo-api

Browser

<script src="https://cdn.gizmo.moe/scripts/gizmo-api@1.2.7.bundle.js"></script>

<script>
    // Module will then be exposed under the variable 'gizmo'
</script>

Building

If you want to build the module and bundle from source, use the following command:

npm run build

Or alternatively, you can either build the browser bundle or node module separately.

npm run build:node

npm run build:browser

Usage

JavaScript (CommonJS)

const gizmo = require("gizmo-api");

TypeScript (ESM)

import gizmo from "gizmo-api";

Example

Simple user search:

import { searchForUser } from "gizmo-api";

searchForUser("tja").then(user => {
    console.log(user);
});

This will log the following:

{
    "id": 1,
    "username": "Tjaz",
    "badges": [ "DEVELOPER", "MODERATOR" ],
    "avatar_url": "https://cdn.gizmo.moe/uploads/avatars/...",
    "banner_url": "https://cdn.gizmo.moe/uploads/banners/...",
    "about_me": "...",
    "created_at": 1534514387
}

Documentation

You are limited to 1 request per 0.1 seconds!

Types

User

A base user.

import type { User } from "gizmo-api"

interface User {
    id: number;
    username: string;
    badges: Badge[];
    avatar_url: string | null;
    banner_url: string | null;
    about_me: string;
    created_at: number;
}

Badge

The badge union.

import type { Badge } from "gizmo-api"

type Badge = "DEVELOPER" | "MODERATOR";

To check for whether a user has a certain badge, use the provided enum and method:

import { userHasBadge, BADGES } from "gizmo-api"

const BADGES = {
    DEVELOPER: "DEVELOPER",
    MODERATOR: "MODERATOR"
};

userHasBadge(user, BADGES.DEVELOPER);

Or alternatively, you can do the checking manually:

import { BADGES } from "gizmo-api"

user.badges.includes(BADGES.DEVELOPER);

AuthenticatedUser

interface AuthenticatedUser extends User {
    token: string;
}

Methods

Fetching a specific user by their ID

function getUserById (id: number): Promise<User>;

Fetching a specific user by their token

function getAuthenticatedUser (token: string): Promise<User>;

Searching for a user

type UserID = number;
type Username = string;
type SearchQuery = UserID | Username;

function searchForUser (query: SearchQuery): Promise<User>;

Logging in and receiving the token

function login (username: string, password: string): Promise<AuthenticatedUser>;

Checking if a user has a badge

function userHasBadge (user: User | AuthenticatedUser, badge: Badge): boolean;