exguard-backend 1.0.1

package/README.md

@@ -0,0 +1,201 @@
+# ExGuard Backend SDK
+
+A simple and lightweight backend SDK for integrating with EmpowerX Guard API to validate user roles and permissions.
+
+## Installation
+
+```bash
+npm install exguard-backend
+# or
+yarn add exguard-backend
+# or
+pnpm add exguard-backend
+```
+
+## Quick Start
+
+```typescript
+import { ExGuardBackend } from 'exguard-backend';
+
+// Initialize the SDK
+const exGuard = new ExGuardBackend({
+  apiUrl: 'https://your-guard-api-url.com'
+});
+
+// Get user access information
+async function checkUserAccess(token: string) {
+  try {
+    const userAccess = await exGuard.getUserAccess(token);
+    console.log('User roles:', userAccess.roles);
+    console.log('User permissions:', userAccess.modules);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new ExGuardBackend(config: ExGuardConfig)
+```
+
+**Config:**
+- `apiUrl` (string): Base URL of your Guard API
+- `timeout` (number, optional): Request timeout in milliseconds (default: 10000)
+
+### Methods
+
+#### `getUserAccess(token: string): Promise<UserAccessResponse>`
+
+Get complete user access information including roles, permissions, and field offices.
+
+**Returns:**
+```typescript
+{
+  user: User,
+  groups: string[],
+  roles: string[],
+  module: string[],
+  modules: ModulePermission[],
+  fieldOffices: string[]
+}
+```
+
+#### `hasPermission(token: string, permission: string): Promise<boolean>`
+
+Check if user has a specific permission.
+
+**Example:**
+```typescript
+const canCreateEvent = await exGuard.hasPermission(token, 'events:create');
+```
+
+#### `hasRole(token: string, role: string): Promise<boolean>`
+
+Check if user has a specific role.
+
+**Example:**
+```typescript
+const isEventManager = await exGuard.hasRole(token, 'Event Manager');
+```
+
+#### `getModulePermissions(token: string, moduleKey: string): Promise<string[]>`
+
+Get all permissions for a specific module.
+
+**Example:**
+```typescript
+const eventPermissions = await exGuard.getModulePermissions(token, 'events');
+// Returns: ['events:create', 'events:read', 'events:update', 'events:delete']
+```
+
+#### `getUserRoles(token: string): Promise<string[]>`
+
+Get all user roles.
+
+**Example:**
+```typescript
+const roles = await exGuard.getUserRoles(token);
+// Returns: ['Event Manager', 'Viewer']
+```
+
+#### `getUserFieldOffices(token: string): Promise<string[]>`
+
+Get all user field offices.
+
+**Example:**
+```typescript
+const fieldOffices = await exGuard.getUserFieldOffices(token);
+// Returns: ['FO-MIMAROPA', 'FO-NCR']
+```
+
+## Usage Examples
+
+### Express.js Middleware
+
+```typescript
+import express from 'express';
+import { ExGuardBackend } from 'exguard-backend';
+
+const app = express();
+const exGuard = new ExGuardBackend({
+  apiUrl: process.env.GUARD_API_URL || 'http://localhost:3001'
+});
+
+// Middleware to check permissions
+const requirePermission = (permission: string) => {
+  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    
+    if (!token) {
+      return res.status(401).json({ error: 'No token provided' });
+    }
+
+    try {
+      const hasPermission = await exGuard.hasPermission(token, permission);
+      if (!hasPermission) {
+        return res.status(403).json({ error: 'Insufficient permissions' });
+      }
+      next();
+    } catch (error) {
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+  };
+};
+
+// Use in routes
+app.post('/events', requirePermission('events:create'), (req, res) => {
+  // Your route logic here
+});
+```
+
+### NestJS Guard
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { ExGuardBackend } from 'exguard-backend';
+
+@Injectable()
+export class PermissionGuard implements CanActivate {
+  private exGuard = new ExGuardBackend({
+    apiUrl: process.env.GUARD_API_URL
+  });
+
+  constructor(private requiredPermission: string) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest();
+    const token = request.headers.authorization?.replace('Bearer ', '');
+    
+    if (!token) {
+      return false;
+    }
+
+    return await this.exGuard.hasPermission(token, this.requiredPermission);
+  }
+}
+
+// Usage in controller
+@Get('events')
+@UseGuards(new PermissionGuard('events:read'))
+async getEvents() {
+  // Your logic here
+}
+```
+
+## Error Handling
+
+The SDK throws specific errors for different scenarios:
+
+- **Unauthorized**: Invalid or expired token (401)
+- **API Error**: General API errors with detailed messages
+- **Network Error**: Connection issues
+
+Always wrap SDK calls in try-catch blocks for proper error handling.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ExGuardBackend: () => ExGuardBackend
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/exguard-backend.ts
+var import_axios = __toESM(require("axios"), 1);
+var ExGuardBackend = class {
+  constructor(config) {
+    this.config = {
+      timeout: 1e4,
+      ...config
+    };
+    this.client = import_axios.default.create({
+      baseURL: this.config.apiUrl,
+      timeout: this.config.timeout,
+      headers: {
+        "Content-Type": "application/json"
+      }
+    });
+  }
+  /**
+   * Get user roles and permissions from the /guard/me endpoint
+   * @param token - JWT access token
+   * @returns Promise<UserAccessResponse>
+   */
+  async getUserAccess(token) {
+    try {
+      const response = await this.client.get("/guard/me", {
+        headers: {
+          "Authorization": `Bearer ${token}`
+        }
+      });
+      if (!response.data.success) {
+        throw new Error("Failed to fetch user access information");
+      }
+      return response.data.data;
+    } catch (error) {
+      if (import_axios.default.isAxiosError(error)) {
+        if (error.response?.status === 401) {
+          throw new Error("Unauthorized: Invalid or expired token");
+        }
+        throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Check if user has specific permission
+   * @param token - JWT access token
+   * @param permission - Permission to check (e.g., 'events:create')
+   * @returns Promise<boolean>
+   */
+  async hasPermission(token, permission) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.modules.some(
+        (module2) => module2.permissions.includes(permission)
+      );
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Check if user has specific role
+   * @param token - JWT access token
+   * @param role - Role to check (e.g., 'Event Manager')
+   * @returns Promise<boolean>
+   */
+  async hasRole(token, role) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.roles.includes(role);
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Get all permissions for a specific module
+   * @param token - JWT access token
+   * @param moduleKey - Module key (e.g., 'events')
+   * @returns Promise<string[]>
+   */
+  async getModulePermissions(token, moduleKey) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      const module2 = userAccess.modules.find((m) => m.key === moduleKey);
+      return module2?.permissions || [];
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get user roles
+   * @param token - JWT access token
+   * @returns Promise<string[]>
+   */
+  async getUserRoles(token) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.roles;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get user field offices
+   * @param token - JWT access token
+   * @returns Promise<string[]>
+   */
+  async getUserFieldOffices(token) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.fieldOffices;
+    } catch (error) {
+      return [];
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExGuardBackend
+});

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+interface User {
+    id: string;
+    cognitoSubId: string;
+    username: string;
+    email: string;
+    emailVerified: boolean;
+    givenName: string;
+    familyName: string;
+    employeeNumber: string;
+    regionId: string;
+    createdAt: string;
+    updatedAt: string;
+    lastLoginAt: string;
+    fieldOffice: {
+        id: string;
+        code: string;
+        name: string;
+    };
+}
+interface ModulePermission {
+    key: string;
+    name: string;
+    permissions: string[];
+}
+interface UserAccessResponse {
+    user: User;
+    groups: string[];
+    roles: string[];
+    module: string[];
+    modules: ModulePermission[];
+    fieldOffices: string[];
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+}
+interface ExGuardConfig {
+    apiUrl: string;
+    timeout?: number;
+}
+
+declare class ExGuardBackend {
+    private client;
+    private config;
+    constructor(config: ExGuardConfig);
+    /**
+     * Get user roles and permissions from the /guard/me endpoint
+     * @param token - JWT access token
+     * @returns Promise<UserAccessResponse>
+     */
+    getUserAccess(token: string): Promise<UserAccessResponse>;
+    /**
+     * Check if user has specific permission
+     * @param token - JWT access token
+     * @param permission - Permission to check (e.g., 'events:create')
+     * @returns Promise<boolean>
+     */
+    hasPermission(token: string, permission: string): Promise<boolean>;
+    /**
+     * Check if user has specific role
+     * @param token - JWT access token
+     * @param role - Role to check (e.g., 'Event Manager')
+     * @returns Promise<boolean>
+     */
+    hasRole(token: string, role: string): Promise<boolean>;
+    /**
+     * Get all permissions for a specific module
+     * @param token - JWT access token
+     * @param moduleKey - Module key (e.g., 'events')
+     * @returns Promise<string[]>
+     */
+    getModulePermissions(token: string, moduleKey: string): Promise<string[]>;
+    /**
+     * Get user roles
+     * @param token - JWT access token
+     * @returns Promise<string[]>
+     */
+    getUserRoles(token: string): Promise<string[]>;
+    /**
+     * Get user field offices
+     * @param token - JWT access token
+     * @returns Promise<string[]>
+     */
+    getUserFieldOffices(token: string): Promise<string[]>;
+}
+
+export { type ApiResponse, ExGuardBackend, type ExGuardConfig, type ModulePermission, type User, type UserAccessResponse };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+interface User {
+    id: string;
+    cognitoSubId: string;
+    username: string;
+    email: string;
+    emailVerified: boolean;
+    givenName: string;
+    familyName: string;
+    employeeNumber: string;
+    regionId: string;
+    createdAt: string;
+    updatedAt: string;
+    lastLoginAt: string;
+    fieldOffice: {
+        id: string;
+        code: string;
+        name: string;
+    };
+}
+interface ModulePermission {
+    key: string;
+    name: string;
+    permissions: string[];
+}
+interface UserAccessResponse {
+    user: User;
+    groups: string[];
+    roles: string[];
+    module: string[];
+    modules: ModulePermission[];
+    fieldOffices: string[];
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+}
+interface ExGuardConfig {
+    apiUrl: string;
+    timeout?: number;
+}
+
+declare class ExGuardBackend {
+    private client;
+    private config;
+    constructor(config: ExGuardConfig);
+    /**
+     * Get user roles and permissions from the /guard/me endpoint
+     * @param token - JWT access token
+     * @returns Promise<UserAccessResponse>
+     */
+    getUserAccess(token: string): Promise<UserAccessResponse>;
+    /**
+     * Check if user has specific permission
+     * @param token - JWT access token
+     * @param permission - Permission to check (e.g., 'events:create')
+     * @returns Promise<boolean>
+     */
+    hasPermission(token: string, permission: string): Promise<boolean>;
+    /**
+     * Check if user has specific role
+     * @param token - JWT access token
+     * @param role - Role to check (e.g., 'Event Manager')
+     * @returns Promise<boolean>
+     */
+    hasRole(token: string, role: string): Promise<boolean>;
+    /**
+     * Get all permissions for a specific module
+     * @param token - JWT access token
+     * @param moduleKey - Module key (e.g., 'events')
+     * @returns Promise<string[]>
+     */
+    getModulePermissions(token: string, moduleKey: string): Promise<string[]>;
+    /**
+     * Get user roles
+     * @param token - JWT access token
+     * @returns Promise<string[]>
+     */
+    getUserRoles(token: string): Promise<string[]>;
+    /**
+     * Get user field offices
+     * @param token - JWT access token
+     * @returns Promise<string[]>
+     */
+    getUserFieldOffices(token: string): Promise<string[]>;
+}
+
+export { type ApiResponse, ExGuardBackend, type ExGuardConfig, type ModulePermission, type User, type UserAccessResponse };

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/exguard-backend.ts
+import axios from "axios";
+var ExGuardBackend = class {
+  constructor(config) {
+    this.config = {
+      timeout: 1e4,
+      ...config
+    };
+    this.client = axios.create({
+      baseURL: this.config.apiUrl,
+      timeout: this.config.timeout,
+      headers: {
+        "Content-Type": "application/json"
+      }
+    });
+  }
+  /**
+   * Get user roles and permissions from the /guard/me endpoint
+   * @param token - JWT access token
+   * @returns Promise<UserAccessResponse>
+   */
+  async getUserAccess(token) {
+    try {
+      const response = await this.client.get("/guard/me", {
+        headers: {
+          "Authorization": `Bearer ${token}`
+        }
+      });
+      if (!response.data.success) {
+        throw new Error("Failed to fetch user access information");
+      }
+      return response.data.data;
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        if (error.response?.status === 401) {
+          throw new Error("Unauthorized: Invalid or expired token");
+        }
+        throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Check if user has specific permission
+   * @param token - JWT access token
+   * @param permission - Permission to check (e.g., 'events:create')
+   * @returns Promise<boolean>
+   */
+  async hasPermission(token, permission) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.modules.some(
+        (module) => module.permissions.includes(permission)
+      );
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Check if user has specific role
+   * @param token - JWT access token
+   * @param role - Role to check (e.g., 'Event Manager')
+   * @returns Promise<boolean>
+   */
+  async hasRole(token, role) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.roles.includes(role);
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Get all permissions for a specific module
+   * @param token - JWT access token
+   * @param moduleKey - Module key (e.g., 'events')
+   * @returns Promise<string[]>
+   */
+  async getModulePermissions(token, moduleKey) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      const module = userAccess.modules.find((m) => m.key === moduleKey);
+      return module?.permissions || [];
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get user roles
+   * @param token - JWT access token
+   * @returns Promise<string[]>
+   */
+  async getUserRoles(token) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.roles;
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get user field offices
+   * @param token - JWT access token
+   * @returns Promise<string[]>
+   */
+  async getUserFieldOffices(token) {
+    try {
+      const userAccess = await this.getUserAccess(token);
+      return userAccess.fieldOffices;
+    } catch (error) {
+      return [];
+    }
+  }
+};
+export {
+  ExGuardBackend
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "exguard-backend",
+  "version": "1.0.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "ExGuard backend SDK for user role and permission validation",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "exguard",
+    "rbac",
+    "backend",
+    "typescript",
+    "permissions",
+    "roles"
+  ],
+  "author": "EmpowerX",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  }
+}