Gomining SDK

Unofficial SDK for interacting with the Gomining API. This SDK provides a TypeScript-first interface for making requests to the Gomining API endpoints.

Installation

npm install gomining-sdk

Quick Start

import { GominingSdk } from 'gomining-sdk';

// Option 1: Initialize with a refresh token (recommended)
// Get your refreshToken by logging in once in the browser (see Authentication section)
const sdk = new GominingSdk({});
const tokens = await sdk.auth.refreshToken('your-refresh-token-here');
// SDK automatically updates access token, but you can also get it:
const accessToken = sdk.getAccessToken();

// Option 2: Initialize with an existing access token
const sdk = new GominingSdk({
  accessToken: 'your-access-token-here'
});

// Check authentication
const authStatus = await sdk.auth.isAuth();
console.log('Authenticated:', authStatus.authenticated);

// Get clan information
const clan = await sdk.clan.getById(12345, { skip: 0, limit: 40 });
console.log('Clan members:', clan.data.usersForClient);

// Get all clan members (handles pagination automatically)
const allMembers = await sdk.clan.getAllMembers(12345);
console.log('Total members:', allMembers.length);

Configuration

import { GominingSdk } from 'gomining-sdk';

const sdk = new GominingSdk({
  accessToken: 'your-access-token-here',
  baseUrl: 'https://api.gomining.com/api', // Optional, defaults to this
  timeout: 30000 // Optional, defaults to 30000ms
});

API Methods

Authentication

Getting Your Refresh Token

The recommended approach is to get a refreshToken by logging in once in your browser, then use that refreshToken with the SDK. Here's how:

1. Login in your browser:

   • Navigate to: https://app.gomining.com/login
   • Login with your credentials

2. Get the refreshToken:

   • Open Browser DevTools (F12)
   • Go to the "Network" tab
   • Find the POST request to /api/auth/login
   • Check the "Response" tab - look for refreshToken in the JSON response
   • OR check localStorage: localStorage.getItem('refreshToken') (if stored)
   • Copy the refreshToken value

3. Use the refreshToken with the SDK:

   const tokens = await sdk.auth.refreshToken('your-refresh-token-here');
   // SDK automatically updates access token

Note: Refresh tokens are long-lived and can be used to get new access tokens without needing to login again.

Login Example (Alternative - Requires Browser Tokens)

If you need to login programmatically, you'll need to obtain Cloudflare Turnstile tokens from your browser:

1. Get tokens from browser:

   • Open https://app.gomining.com/login in your browser
   • Open DevTools Console (F12)
   • Get Turnstile token: document.querySelector('input[name="cf-turnstile-response"]').value
   • Get reCAPTCHA token: Check Network tab → POST to /api/auth/login → Payload → token

2. Use tokens to login:

// Login with email, password, and tokens obtained from browser
const loginResponse = await sdk.auth.login(
  '[email protected]',
  'your-password',
  {
    type: 'testnet', // or 'mainnet'
    turnstileToken: 'your-turnstile-token-from-browser', // Required
    token: 'your-recaptcha-token-from-browser', // Required
    googleClientId: '2064520565.1749046073', // Optional, default value
    appsflyerId: '', // Optional
    appStore: '' // Optional
  }
);

// SDK automatically updates access token after successful login
const accessToken = sdk.getAccessToken();
const refreshToken = loginResponse.data.refreshToken; // Store this for future use!

// Check if token is valid
const authStatus = await sdk.auth.isAuth();

// Refresh access token (use the refreshToken from login)
const tokens = await sdk.auth.refreshToken(refreshToken);
// SDK auto-updates access token, but you can also do it manually:
sdk.setAccessToken(tokens.accessToken);

Important Notes

• Tokens expire quickly - Turnstile tokens are only valid for a short time (usually a few minutes)
• Store the refreshToken - After successful login, save the refreshToken from the response. You can use it to get new access tokens without needing to login again or provide Turnstile tokens
• Use refreshToken for long-term access - Once you have a refreshToken, you can use sdk.auth.refreshToken() to get new access tokens without needing to login again

Clan

// Get clan by ID with pagination
const clan = await sdk.clan.getById(12345, { skip: 0, limit: 40 });

// Get all clan members (automatically handles pagination)
const allMembers = await sdk.clan.getAllMembers(12345);

// Get current user's clan
const myClan = await sdk.clan.getMy();

Rounds

// Get round state
const roundState = await sdk.round.getState({ roundId: 123 });

// Get last round
const lastRound = await sdk.round.getLast();

// Find rounds by cycle ID
const rounds = await sdk.round.findByCycleId(456, { skip: 0, limit: 50 });

// Get round user leaderboard
const leaderboard = await sdk.round.getUserLeaderboard(123, { skip: 0, limit: 100 });

Rewards

// Get rewards with filters and pagination
const rewards = await sdk.rewards.getByUser({
  filters: { type: 'clan', clanId: 12345 },
  pagination: { skip: 0, limit: 50 }
});

// Get all rewards (automatically handles pagination)
const allRewards = await sdk.rewards.getAll({ type: 'clan', clanId: 12345 });

Leaderboards

// Get user leaderboard
const leaderboard = await sdk.leaderboard.getUserLeaderboard({
  calculatedAt: '2025-01-01T00:00:00.000Z',
  pagination: { skip: 0, limit: 100 },
  leagueId: 4
});

Clan Invites

// Get invites where current user is inviter
const invites = await sdk.invite.getAsInviter();

// Confirm an invite
const confirmResult = await sdk.invite.confirm(inviteId);

// Cancel/deny an invite
const cancelResult = await sdk.invite.cancel(inviteId);

Actions

// Get maintenance state
const maintenance = await sdk.action.getMaintenanceState();

// Post a service action
const result = await sdk.action.postService({ action: 'some-action' });

Advanced Usage

Using the Client Directly

For endpoints not yet covered by the SDK methods, you can use the client directly:

import { GominingSdk } from 'gomining-sdk';

const sdk = new GominingSdk({ accessToken: 'your-token' });
const client = sdk.getClient();

// Make a custom request
const response = await client.post('/custom/endpoint', { custom: 'data' });

Updating Access Token

// Update the access token after refresh
sdk.setAccessToken(newAccessToken);

Error Handling

import { GominingSdk, GominingApiError } from 'gomining-sdk';

try {
  const clan = await sdk.clan.getById(12345, { skip: 0, limit: 40 });
} catch (error) {
  if (error instanceof GominingApiError) {
    console.error('API Error:', error.statusCode, error.statusText);
    console.error('Response:', error.response);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All request and response types are exported:

import {
  GetClanByIdRequest,
  GetClanByIdResponse,
  ClanMember,
  GominingReward
} from 'gomining-sdk';

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (for TypeScript projects)

License

MIT

Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by Gomining. Use at your own risk.