@tspscale/npm-login 1.0.1 → 1.0.4

package/README.md

@@ -4,44 +4,54 @@ Official Node.js SDK for TSP Scale Authentication.
 
 🚀 Quick Start (Zero-Config)
 -----------------------------
-Verify TSP Scale JWT access tokens securely from your backend server.
+Add "Login with TSP Scale" to your server-side Node.js applications in minutes!
 
 ### Installation
 ```bash
 npm install @tspscale/npm-login
 ```
 
-🛠️ Usage
----------
-You can easily protect your Express or Next.js routes using the built-in middleware or by manually verifying tokens.
+🛠️ Usage: Full OAuth Setup (Express)
+--------------------------------------
+If you are building a traditional server-side web app without a frontend framework like React, you can use the SDK's built-in Express handlers to do the heavy lifting for you!
 
-### Express Middleware
 ```javascript
 const express = require('express');
-const { tspAuth } = require('@tspscale/npm-login');
+const { TSPClient } = require('@tspscale/npm-login');
 
 const app = express();
 
-// Protect a route - requires a Bearer token in the Authorization header
-app.get('/api/protected', tspAuth.middleware(), (req, res) => {
-  // The middleware automatically attaches the user profile to the request
-  res.json({ message: "Success!", user: req.user });
+// 1. Initialize the Client
+const tspAuth = new TSPClient({
+  clientId: process.env.TSP_CLIENT_ID,
+  clientSecret: process.env.TSP_CLIENT_SECRET,
+  redirectUri: 'http://localhost:3000/auth/callback'
 });
+
+// 2. Login Route (Automatically redirects to TSP Scale)
+app.get('/auth/login', tspAuth.loginHandler());
+
+// 3. Callback Route (Automatically exchanges the code for a token)
+app.get('/auth/callback', tspAuth.callbackHandler({
+  onSuccess: (token, req, res) => {
+    // Save the token (e.g. in a cookie) and redirect to the dashboard
+    res.cookie('auth_token', token);
+    res.redirect('/dashboard');
+  },
+  onError: (error, req, res) => {
+    res.status(500).send(`Login failed: ${error}`);
+  }
+}));
 ```
 
-### Manual Token Verification
-If you are using Next.js or a custom server, you can manually verify a token:
+🔐 Protecting API Routes
+------------------------
+If your frontend has already acquired an access token (e.g., via the React SDK), you can use the middleware to protect your backend routes.
+
 ```javascript
-const { tspAuth } = require('@tspscale/npm-login');
-
-async function checkToken(accessToken) {
-  const result = await tspAuth.verifyToken(accessToken);
-  
-  if (result.error) {
-    console.error("Verification failed:", result.error);
-    return;
-  }
-  
-  console.log("User Profile:", result.user);
-}
+// Protect a route - requires a Bearer token in the Authorization header
+app.get('/api/protected', tspAuth.middleware(), (req, res) => {
+  // The middleware automatically verifies the token and attaches the user!
+  res.json({ message: "Success!", user: req.user });
+});
 ```

package/dist/index.d.ts

@@ -8,24 +8,58 @@ export interface TSPUser {
 export interface TSPAuthResult {
     user?: TSPUser;
     error?: string;
+    accessToken?: string;
+}
+export interface TSPClientConfig {
+    clientId?: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    apiUrl?: string;
+    authUrl?: string;
 }
 export declare class TSPClient {
     private apiUrl;
-    constructor(options?: {
-        apiUrl?: string;
-    });
+    private authUrl;
+    private clientId?;
+    private clientSecret?;
+    private redirectUri?;
+    constructor(options?: TSPClientConfig);
+    /**
+     * Generates the OAuth 2.0 Authorization URL to redirect the user to.
+     */
+    getAuthorizationUrl(state?: string, scope?: string): string;
+    /**
+     * Securely exchanges an authorization code for an access token.
+     */
+    exchangeToken(code: string): Promise<{
+        access_token?: string;
+        error?: string;
+    }>;
     /**
      * Verifies an access token and returns the user profile.
-     * @param accessToken The OAuth 2.0 Access Token provided by the frontend.
      */
     verifyToken(accessToken: string): Promise<TSPAuthResult>;
+    /**
+     * Express Route Handler: Automatically redirects the user to TSP Scale to log in.
+     */
+    loginHandler(options?: {
+        state?: string;
+        scope?: string;
+    }): (req: any, res: any) => void;
+    /**
+     * Express Route Handler: Intercepts the callback, exchanges the code, and provides the token.
+     */
+    callbackHandler(options: {
+        onSuccess: (token: string, req: any, res: any) => void;
+        onError: (error: string, req: any, res: any) => void;
+    }): (req: any, res: any) => Promise<void>;
     /**
      * Express middleware to protect routes.
-     * Requires the frontend to send the token in the Authorization header: `Bearer <token>`.
+     * Requires a Bearer token in the Authorization header.
      */
     middleware(): (req: any, res: any, next: any) => Promise<any>;
 }
 /**
- * Convenience default client instance
+ * Convenience default client instance (must be configured before use for full OAuth flow)
  */
 export declare const tspAuth: TSPClient;

package/dist/index.js

@@ -3,11 +3,58 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.tspAuth = exports.TSPClient = void 0;
 class TSPClient {
     constructor(options) {
-        this.apiUrl = options?.apiUrl || 'https://tspscale.in/api/v1';
+        this.apiUrl = options?.apiUrl || 'https://api.tspscale.in/api/v1';
+        this.authUrl = options?.authUrl || 'https://tspscale.in/oauth/authorize';
+        this.clientId = options?.clientId;
+        this.clientSecret = options?.clientSecret;
+        this.redirectUri = options?.redirectUri;
+    }
+    /**
+     * Generates the OAuth 2.0 Authorization URL to redirect the user to.
+     */
+    getAuthorizationUrl(state = 'tsp_auth', scope = 'read') {
+        if (!this.clientId || !this.redirectUri) {
+            throw new Error('TSPClient requires clientId and redirectUri to generate an authorization URL.');
+        }
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: scope,
+            state: state
+        });
+        return `${this.authUrl}?${params.toString()}`;
+    }
+    /**
+     * Securely exchanges an authorization code for an access token.
+     */
+    async exchangeToken(code) {
+        if (!this.clientId || !this.clientSecret || !this.redirectUri) {
+            throw new Error('TSPClient requires clientId, clientSecret, and redirectUri to exchange tokens.');
+        }
+        try {
+            const response = await fetch(`${this.apiUrl}/oauth/token`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    grant_type: 'authorization_code',
+                    client_id: this.clientId,
+                    client_secret: this.clientSecret,
+                    code: code,
+                    redirect_uri: this.redirectUri
+                })
+            });
+            const data = await response.json();
+            if (!response.ok)
+                return { error: data.error || 'Failed to exchange token' };
+            return { access_token: data.access_token };
+        }
+        catch (err) {
+            return { error: err.message || 'Network error exchanging token' };
+        }
     }
     /**
      * Verifies an access token and returns the user profile.
-     * @param accessToken The OAuth 2.0 Access Token provided by the frontend.
      */
     async verifyToken(accessToken) {
         try {
@@ -19,18 +66,47 @@ class TSPClient {
                 }
             });
             const data = await response.json();
-            if (!response.ok) {
+            if (!response.ok)
                 return { error: data.error || 'Failed to verify token' };
-            }
             return { user: data };
         }
         catch (err) {
             return { error: err.message || 'Network error verifying token' };
         }
     }
+    /**
+     * Express Route Handler: Automatically redirects the user to TSP Scale to log in.
+     */
+    loginHandler(options) {
+        return (req, res) => {
+            try {
+                const url = this.getAuthorizationUrl(options?.state, options?.scope);
+                res.redirect(url);
+            }
+            catch (err) {
+                res.status(500).send(`TSP SDK Error: ${err.message}`);
+            }
+        };
+    }
+    /**
+     * Express Route Handler: Intercepts the callback, exchanges the code, and provides the token.
+     */
+    callbackHandler(options) {
+        return async (req, res) => {
+            const code = req.query.code;
+            if (!code) {
+                return options.onError('No authorization code provided in the callback', req, res);
+            }
+            const tokenResult = await this.exchangeToken(code);
+            if (tokenResult.error || !tokenResult.access_token) {
+                return options.onError(tokenResult.error || 'Token exchange failed', req, res);
+            }
+            return options.onSuccess(tokenResult.access_token, req, res);
+        };
+    }
     /**
      * Express middleware to protect routes.
-     * Requires the frontend to send the token in the Authorization header: `Bearer <token>`.
+     * Requires a Bearer token in the Authorization header.
      */
     middleware() {
         return async (req, res, next) => {
@@ -43,7 +119,6 @@ class TSPClient {
             if (result.error || !result.user) {
                 return res.status(401).json({ error: result.error || 'Unauthorized' });
             }
-            // Attach user to the request object
             req.user = result.user;
             next();
         };
@@ -51,6 +126,6 @@ class TSPClient {
 }
 exports.TSPClient = TSPClient;
 /**
- * Convenience default client instance
+ * Convenience default client instance (must be configured before use for full OAuth flow)
  */
 exports.tspAuth = new TSPClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tspscale/npm-login",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "main": "dist/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",

package/src/index.ts

@@ -9,18 +9,78 @@ export interface TSPUser {
 export interface TSPAuthResult {
   user?: TSPUser;
   error?: string;
+  accessToken?: string;
+}
+
+export interface TSPClientConfig {
+  clientId?: string;
+  clientSecret?: string;
+  redirectUri?: string;
+  apiUrl?: string;
+  authUrl?: string;
 }
 
 export class TSPClient {
   private apiUrl: string;
+  private authUrl: string;
+  private clientId?: string;
+  private clientSecret?: string;
+  private redirectUri?: string;
 
-  constructor(options?: { apiUrl?: string }) {
-    this.apiUrl = options?.apiUrl || 'https://tspscale.in/api/v1';
+  constructor(options?: TSPClientConfig) {
+    this.apiUrl = options?.apiUrl || 'https://api.tspscale.in/api/v1';
+    this.authUrl = options?.authUrl || 'https://tspscale.in/oauth/authorize';
+    this.clientId = options?.clientId;
+    this.clientSecret = options?.clientSecret;
+    this.redirectUri = options?.redirectUri;
+  }
+
+  /**
+   * Generates the OAuth 2.0 Authorization URL to redirect the user to.
+   */
+  getAuthorizationUrl(state: string = 'tsp_auth', scope: string = 'read'): string {
+    if (!this.clientId || !this.redirectUri) {
+      throw new Error('TSPClient requires clientId and redirectUri to generate an authorization URL.');
+    }
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: 'code',
+      scope: scope,
+      state: state
+    });
+    return `${this.authUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Securely exchanges an authorization code for an access token.
+   */
+  async exchangeToken(code: string): Promise<{ access_token?: string, error?: string }> {
+    if (!this.clientId || !this.clientSecret || !this.redirectUri) {
+        throw new Error('TSPClient requires clientId, clientSecret, and redirectUri to exchange tokens.');
+    }
+    try {
+      const response = await fetch(`${this.apiUrl}/oauth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          grant_type: 'authorization_code',
+          client_id: this.clientId,
+          client_secret: this.clientSecret,
+          code: code,
+          redirect_uri: this.redirectUri
+        })
+      });
+      const data = await response.json();
+      if (!response.ok) return { error: data.error || 'Failed to exchange token' };
+      return { access_token: data.access_token };
+    } catch (err: any) {
+      return { error: err.message || 'Network error exchanging token' };
+    }
   }
 
   /**
    * Verifies an access token and returns the user profile.
-   * @param accessToken The OAuth 2.0 Access Token provided by the frontend.
    */
   async verifyToken(accessToken: string): Promise<TSPAuthResult> {
     try {
@@ -31,22 +91,48 @@ export class TSPClient {
           'Content-Type': 'application/json'
         }
       });
-
       const data = await response.json();
-
-      if (!response.ok) {
-        return { error: data.error || 'Failed to verify token' };
-      }
-
+      if (!response.ok) return { error: data.error || 'Failed to verify token' };
       return { user: data };
     } catch (err: any) {
       return { error: err.message || 'Network error verifying token' };
     }
   }
 
+  /**
+   * Express Route Handler: Automatically redirects the user to TSP Scale to log in.
+   */
+  loginHandler(options?: { state?: string, scope?: string }) {
+    return (req: any, res: any) => {
+      try {
+        const url = this.getAuthorizationUrl(options?.state, options?.scope);
+        res.redirect(url);
+      } catch (err: any) {
+        res.status(500).send(`TSP SDK Error: ${err.message}`);
+      }
+    };
+  }
+
+  /**
+   * Express Route Handler: Intercepts the callback, exchanges the code, and provides the token.
+   */
+  callbackHandler(options: { onSuccess: (token: string, req: any, res: any) => void, onError: (error: string, req: any, res: any) => void }) {
+    return async (req: any, res: any) => {
+      const code = req.query.code as string;
+      if (!code) {
+        return options.onError('No authorization code provided in the callback', req, res);
+      }
+      const tokenResult = await this.exchangeToken(code);
+      if (tokenResult.error || !tokenResult.access_token) {
+        return options.onError(tokenResult.error || 'Token exchange failed', req, res);
+      }
+      return options.onSuccess(tokenResult.access_token, req, res);
+    };
+  }
+
   /**
    * Express middleware to protect routes.
-   * Requires the frontend to send the token in the Authorization header: `Bearer <token>`.
+   * Requires a Bearer token in the Authorization header.
    */
   middleware() {
     return async (req: any, res: any, next: any) => {
@@ -54,15 +140,11 @@ export class TSPClient {
       if (!authHeader || !authHeader.startsWith('Bearer ')) {
         return res.status(401).json({ error: 'Missing or invalid Bearer token' });
       }
-
       const token = authHeader.split(' ')[1];
       const result = await this.verifyToken(token);
-
       if (result.error || !result.user) {
         return res.status(401).json({ error: result.error || 'Unauthorized' });
       }
-
-      // Attach user to the request object
       req.user = result.user;
       next();
     };
@@ -70,6 +152,6 @@ export class TSPClient {
 }
 
 /**
- * Convenience default client instance
+ * Convenience default client instance (must be configured before use for full OAuth flow)
  */
 export const tspAuth = new TSPClient();