An unofficial Node.js/TypeScript client library for the Yeolpumta (YPT) study app.
Disclaimer: This is an unofficial, reverse-engineered client not affiliated with or endorsed by YPT / TGCLab. Use responsibly, respect their terms of service, keep request volume reasonable, and protect user privacy.
- Dual-Token Authentication – Modern
accessToken&refreshTokenmanagement with automatic 401 token rotation. - Social Sign-Up & OAuth – Supports Kakao, Naver, Google, Apple, and Facebook sign-up flows.
- Downstream Auth – Native support for Google Firebase Custom Tokens and device push token registration.
- Runtime Schema Validation – Powered by Zod for robust input validation and API response drift detection.
- Native fetch – Built with native
fetch(Node.js 18+ and Bun). - TypeScript ready – Full type definitions for requests, responses, and errors.
- Dual module support – Works out of the box with both ESM and CommonJS.
- Clean developer ergonomics – Replaces obfuscated upstream API keys (e.g.
dl.sm->todayStudyMs). - Live study calculations – Real-time study time computation based on ongoing sessions.
bun add ypt-js
# or: npm install ypt-jsimport { YptJs } from "ypt-js";
const ypt = new YptJs();
// Sign in with your YPT credentials
await ypt.auth.signIn({
email: process.env.YPT_EMAIL!,
password: process.env.YPT_PASSWORD!,
});
// Fetch your joined study groups
const groups = await ypt.groups.listJoined();
console.log(
"Joined groups:",
groups.map((g) => g.name),
);
// Get members of a group
const members = await ypt.groups.getMembers(groups[0].id);
for (const member of members) {
const status = member.isStudying ? `studying ${member.currentSubject ?? ""}` : "offline";
console.log(`${member.nickname} - ${member.liveStudyTime} (${status})`);
}You can pass credentials directly to the client. It will authenticate lazily on the first request and handle re-login if the session expires:
const ypt = new YptJs({
credentials: {
email: process.env.YPT_EMAIL!,
password: process.env.YPT_PASSWORD!,
},
});
// Automatically signs in before making the request
const groups = await ypt.groups.listJoined();Pass a persisted refresh token to restore sessions across restarts:
const savedRefreshToken = await loadSavedRefreshToken();
const ypt = new YptJs({
refreshToken: savedRefreshToken,
onTokenChange: async (accessToken, refreshToken) => {
await saveTokens({ accessToken, refreshToken });
},
});
// Optional explicit restore (the first request would also do this lazily)
await ypt.auth.restoreSession(savedRefreshToken);Comprehensive guides are available in the docs/ directory, and the same content is
published with VitePress at https://hyperafnan.github.io/ypt-js/.
- Documentation index: Overview, install, quick start, and the full guide map.
- Getting started: Runtime support, every client option, and the authentication strategies.
- Authentication & Session Lifecycle: Email sign-in, social OAuth (
KAKAO,NAVER,GOOGLE,APPLE,FACEBOOK), token rotation, session restore, Firebase custom tokens, push tokens, and profile management. - Groups, Discovery & Moderation: Search, creation, applications, live roster telemetry, attendance, leaderboards, strikes/kicks/blacklisting, nudges, chat, and notices.
- API Reference: Complete signatures, options, types, schemas, exports, and endpoint mapping.
- Error Handling: Error hierarchy, retry semantics, and recovery patterns.
- Architecture: Internals, request lifecycle, mapping pipeline, and design invariants.
- Cookbook: Production recipes for persistence, polling, proxying, and batch work.
- Troubleshooting: Symptom-based debugging and FAQ.
- Upstream API: Reverse-engineered wire protocol and minified-key glossary.
- Contributing: Development workflow, testing conventions, and release process.
signIn({ email, password }): Authenticates user and returns dual tokens & profile.socialSignUp({ provider, token, nickname }): Registers/authenticates via OAuth provider.splashLogin(): Sends device startup ping and rotates tokens.restoreSession(refreshToken): Restores session from stored refresh token.getFirebaseCustomToken(): Exchanges YPT token for a Google Firebase Custom Token.registerPushToken(token): Registers FCM / APNs device push token.checkUsername(nickname): Checks if a nickname is already in use.updateNickname(nickname): Changes account display nickname.updateStatusMessage(message): Changes account status message / bio.logout(): Logs out and invalidates session.
search(options): Discovers public groups with keyword, categories, and filter sorting.listJoined(): Lists all groups the authenticated user belongs to.get(groupId): Retrieves a specific joined group by ID.searchJoined(query): Client-side filter through joined groups by name, category, or owner.validateTitle(title): Verifies if a group title is valid and available.create(params): Creates a new study group with rules, join types, and study requirements.join(groupId, options?): Directly joins an open or PIN-protected study group.apply(groupId, params): Submits an application with answers to group screening questions.reviewApplicant(groupId, params): Approves or rejects incoming membership applications.leave(groupId): Leaves a joined group.warnMember(groupId, userId): Issues an official warning strike to a member.cancelWarning(groupId, userId): Revokes a previously issued warning strike.kickMember(groupId, userId): Expels a member from the group.blacklistMember(groupId, userId): Permanently bans and blacklists a member.removeBlacklist(groupId, userId): Removes a user from the group blacklist.listBlacklist(groupId): Lists all blacklisted users for a group.getMembers(groupId, options?): Retrieves members of a group with real-time live study calculations and active cams.getAttendances(groupId, startDate, endDate): Fetches attendance compliance matrix and daily study records.getLeaderboard(groupId, type?): Retrieves group study rankings ("daily" | "weekly" | "monthly", default"daily").nudge(groupId, targetUserId): Sends an in-app vibration nudge to an individual inactive student.nudgeAll(groupId): Sends a vibration nudge to all inactive members in a group.sendChatMessage(groupId, message, options?): Sends a message to the group chat room.postNotice(groupId, content, options?): Pins an official notice banner to the group home.listAllMembers(options?): Aggregates and deduplicates member telemetry across all joined groups.
avatarUrl(member, cdnUrl?): Resolves a member's avatar URL from the CDN.formatDuration(ms): Formats study duration into human-readable strings (HH:MM:SS).mergeMembers(entries): Deduplicates and merges member records across groups.validatePassword(password): Validates password against YPT's 8-character 2-category rule.
const ypt = new YptJs({
// Session (use one of token / refreshToken / credentials)
token,
refreshToken,
expiresAt,
credentials: { email, password },
// Observability / persistence hooks
onTokenChange: (accessToken, refreshToken) => {},
onSessionChange: (session) => {},
// Transport
authScheme: "JWT", // or "Bearer"
baseUrl: "https://pi.tgclab.com",
cdnUrl: "https://alicdn.tgclab.com",
userAgent: "Dart/3.11 (dart:io)",
headers: {},
timeoutMs: 15_000, // 0 disables
maxRetries: 2, // GET requests only
retryDelayMs: 500,
language: "en",
device: {}, // splash-login device overrides
// Test seams
fetch: globalThis.fetch,
now: Date.now,
});See Getting started → Complete options reference for types and defaults.
(Note: YptClient is also exported as an alias for YptJs for backward compatibility).
# Install dependencies
bun install
# Type-check
bun run typecheck
# Run the test suite (Vitest)
bun run test
# Format code
bun run format
# Build package (CJS + ESM + d.ts)
bun run build
# Docs development server (http://localhost:5173)
bun run docs:dev
# Build the static docs site
bun run docs:build
# Preview the built docs site
bun run docs:previewThis project is licensed under the MIT License.