PenguinMod API Wrapper

A comprehensive TypeScript/JavaScript wrapper for the PenguinMod API with full type safety.

Features

• 🔷 Full TypeScript support with complete type definitions
• 🚀 Zero dependencies - No dependencies needed, how great is that?
• 🎯 Intuitive API - Clean, organized method structure

Installation

npm install pm-api-wrapper
# or
yarn add pm-api-wrapper
# or
pnpm add pm-api-wrapper
# or
bun add pm-api-wrapper

Usage

Basic Example

import { PenguinModApi } from 'pm-api-wrapper';

const api = new PenguinModApi();

// Get a user's profile
const profile = await api.users.getProfile('mubilop');
console.log(profile);

// Search for projects
const projects = await api.projects.searchProjects({ 
  query: 'platformer', 
  page: 0 
});

// Get project metadata
const project = await api.projects.getProject('projectId', 'metadata');

JavaScript (CommonJS)

const { PenguinModApi } = require('pm-api-wrapper');

const api = new PenguinModApi();

// Use async/await or promises
api.users.getProfile('username').then(profile => {
  console.log(profile);
});

Custom Base URL (For custom servers)

const api = new PenguinModApi({
  baseUrl: 'https://custom-api.example.com'
});

API Reference

Projects

// Search projects
await api.projects.searchProjects({ query: 'game', page: 0 });

// Get all projects with pagination
await api.projects.getProjects(page, reverse);

// Get specific project (metadata, thumbnail, protobuf, or assets)
await api.projects.getProject(projectId, 'metadata');
await api.projects.getProject(projectId, 'thumbnail'); // Returns Uint8Array
await api.projects.getProject(projectId, 'protobuf'); // Returns Uint8Array
await api.projects.getProject(projectId, 'assets'); // Returns asset array

// Get project wrapper (project + assets)
await api.projects.getProjectWrapper(projectId, safe);

// Get featured projects
await api.projects.getFeaturedProjects(page);

// Get front page projects
await api.projects.getFrontPage();

// Get project remixes
await api.projects.getRemixes({ projectID: 'id', page: 0 });

// Get random project
await api.projects.getRandomProject();

// Check if viewing is enabled
await api.projects.canViewProjects();

Users

// Get user profile
await api.users.getProfile('username');

// Get user ID by username
await api.users.getUserId('username');

// Get username by ID
await api.users.getUsername('userId');

// Check if user exists
await api.users.userExists('username');

// Check if user is banned
await api.users.isBanned('username');

// Get user's followers
await api.users.getFollowers('username', page);

// Get who user is following
await api.users.getFollowing('username', page);

// Get user customization (for donators)
await api.users.getCustomization('username');

// Get project count of user
await api.users.getProjectCountOfUser('username');

// Get profile picture URL
const pfpUrl = api.users.getProfilePictureUrl('username');

Interactions

// Get vote count
await api.interactions.getVotes('projectId');

// Get love count
await api.interactions.getLoves('projectId');

Miscellaneous

// Get platform statistics
await api.misc.getStats();

// Ping the API
await api.misc.ping();

// Get API metadata
await api.misc.getApiMetadata();

TypeScript Support

This package is written in TypeScript and includes complete type definitions. TypeScript users get full IntelliSense support:

import { PenguinModApi, UserProfile, Project } from 'pm-api-wrapper';

const api = new PenguinModApi();

// Full type inference
const profile: UserProfile = await api.users.getProfile('username');
const projects: Project[] = await api.projects.searchProjects({ query: 'game' });

Building from Source

# Install dependencies
npm install

# Build ESM, CommonJS, and type definitions
npm run build

# Clean build artifacts
npm run clean

Development

# Clone the repository
git clone https://github.com/yourusername/pm-api-wrapper.git
cd pm-api-wrapper

# Install dependencies
npm install

# Build the project
npm run build

API Documentation

For detailed API documentation, visit PenguinMod Backend API Repository.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• PenguinMod - The amazing Scratch mod this wrapper is built for
• PenguinMod Backend API - The API this wrapper interfaces with