studex-auth

1. Getting Started

To install the SDK, choose your preferred integration method. For React, Next.js, Vue, or Svelte projects, we recommend using npm. For static web pages, use the script tag.

npm install studex-auth

import StudexOAuth from 'studex-auth';

2. Popup Authorization

Use the login method to trigger the standard Studex OAuth login popup flow. You can handle the flow using modern **Promises** or traditional **Callbacks**.

import StudexOAuth from 'studex-auth';

async function handleLogin() {
  try {
    const response = await StudexOAuth.login({
      clientId: 'YOUR_CLIENT_ID',
      redirectUri: 'YOUR_REDIRECT_URI', // Callback handler URL
      state: 'optional-custom-state',
      scope: 'profile' // default: 'profile'
    });

    console.log('Authorization successful! Code:', response.code);
    // Send response.code to your backend server for token exchange
  } catch (error) {
    console.error('Login flow failed or popup was closed:', error.message);
  }
}

3. Pre-styled Auth Buttons

To provide a native login experience, render standardized **Sign in with Studex** buttons using the renderButton helper. It injects fully responsive and high-fidelity styles.

StudexOAuth.renderButton('element-container-id', {
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'YOUR_REDIRECT_URI',
  theme: 'light',      // 'light' | 'dark'
  type: 'standard',    // 'standard' | 'icon' (only shows the logo)
  text: 'signin_with', // 'signin_with' | 'signup_with' | 'continue_with'
  pill: false          // true (rounded corners) | false (rectangular)
}, (err, response) => {
  if (err) return console.error(err);
  console.log('Auth success code:', response.code);
});

4. One-Tap Integration

One-Tap is a friction-free prompt that slides down from the top right of the user's browser, permitting instant sign-in or account creation if they are already signed into Studex.

A. Floating Card (Default)

StudexOAuth.initOneTap({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'YOUR_REDIRECT_URI'
}, (err, response) => {
  if (err) return console.error("One-tap failed:", err.message);
  console.log("One-tap code received:", response.code);
});

B. Inline Container

To render the One-Tap dialog inside a specific element in your page layout, provide the containerId option:

StudexOAuth.initOneTap({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'YOUR_REDIRECT_URI',
  containerId: 'inline-onetap-container'
}, (err, response) => {
  // ... Handle code exchange
});

5. TypeScript Support

The SDK comes bundled with type definitions. This gives your development team IDE auto-completes and static type safety out-of-the-box.

Import types alongside the default export:

import StudexOAuth, { 
  OAuthOptions, 
  OAuthResponse, 
  RenderButtonOptions, 
  OneTapOptions 
} from 'studex-auth';

6. Backend Token Exchange

After your frontend receives the authorization code, send it to your backend application. Your server must exchange this code for user profile data by making a POST request:

Node.js Backend Example

// Express.js handler
app.post('/api/auth/studex', async (req, res) => {
  const { code } = req.body;
  
  try {
    const tokenResponse = await fetch('https://studex.club/api/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: process.env.STUDEX_CLIENT_ID,
        client_secret: process.env.STUDEX_CLIENT_SECRET,
        code,
        redirect_uri: process.env.STUDEX_REDIRECT_URI,
        grant_type: 'authorization_code'
      })
    });
    
    const data = await tokenResponse.json();
    res.json(data); // Returns access token & user profile details
  } catch (err) {
    res.status(500).json({ error: 'Auth exchange failed' });
  }
});

Python Backend Example

import requests

def exchange_studex_code(auth_code):
    response = requests.post(
        "https://studex.club/api/oauth/token",
        json={
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_CLIENT_SECRET",
            "code": auth_code,
            "redirect_uri": "YOUR_REDIRECT_URI",
            "grant_type": "authorization_code"
        }
    )
    return response.json() # Returns user profile data and access token