@rempays/shared-core 1.0.2-beta.1

package/README.md

@@ -0,0 +1,346 @@
+# @rempays/shared-core
+
+Core utilities layer for RemPays platform with AWS services integration (Cognito, Auth, S3, Textract, Facebook API, HTTP Client).
+
+## Installation
+
+```bash
+npm install @rempays/shared-core
+```
+
+## Modules
+
+### 1. Cognito Service
+
+Authentication and user management with AWS Cognito.
+
+```typescript
+import { CognitoService } from '@rempays/shared-core/cognito';
+
+const cognito = new CognitoService({
+  userPoolId: 'us-east-1_xxxxx',
+  clientId: 'xxxxx',
+  region: 'us-east-1'
+});
+
+// Register user
+const result = await cognito.signUp({
+  phoneNumber: '+1234567890',
+  email: 'user@example.com',
+  password: 'SecurePass123'
+});
+
+// Confirm registration with OTP
+await cognito.confirmSignUp('+1234567890', '123456');
+
+// Sign in with custom auth
+const authResponse = await cognito.signInCustomAuth({
+  phoneNumber: '+1234567890'
+});
+
+// Verify OTP code
+const tokens = await cognito.respondToAuthChallenge({
+  phoneNumber: '+1234567890',
+  code: '123456',
+  session: authResponse.session
+});
+
+// Get user info
+const user = await cognito.getUser(tokens.accessToken!);
+
+// Refresh token
+const newTokens = await cognito.refreshToken({
+  refreshToken: tokens.refreshToken!
+});
+```
+
+### 2. JWT Validator (Auth)
+
+Validate Cognito JWT tokens for Lambda Authorizers.
+
+```typescript
+import { JwtValidator } from '@rempays/shared-core/auth';
+
+const validator = new JwtValidator({
+  region: 'us-east-1',
+  userPoolId: 'us-east-1_xxxxx'
+});
+
+// Validate token from Authorization header
+const decoded = await validator.validateFromHeader(event.headers.Authorization);
+// Returns: { sub, username, exp, iat, token_use, ... }
+
+// Or validate token directly
+const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
+const decoded = await validator.validate(token);
+
+// Use in Lambda Authorizer
+export const handler = async (event: any) => {
+  try {
+    const decoded = await validator.validateFromHeader(event.headers.Authorization);
+    return generateAllowPolicy(decoded.sub, event.methodArn, decoded);
+  } catch (error) {
+    return generateDenyPolicy('user', event.methodArn);
+  }
+};
+```
+
+### 3. HTTP Client
+
+Generic HTTP client built on axios with authentication support.
+
+```typescript
+import { createHttpClient, HttpClient } from '@rempays/shared-core/http';
+
+// Create basic client
+const client = createHttpClient();
+
+// Create client with auth token
+const authClient = createHttpClient({
+  token: 'your-bearer-token',
+  baseURL: 'https://api.example.com',
+  timeout: 5000
+});
+
+// Use convenience methods
+const data = await client.get('/users');
+await client.post('/users', { name: 'John' });
+await client.put('/users/1', { name: 'Jane' });
+await client.delete('/users/1');
+
+// Manage auth token dynamically
+authClient.setAuthToken('new-token');
+authClient.removeAuthToken();
+
+// Access underlying axios instance
+const axiosInstance = client.getInstance();
+```
+
+### 4. S3 Service
+
+File operations with AWS S3.
+
+```typescript
+import { S3Service } from '@rempays/shared-core/s3';
+
+// Upload file
+const s3Uri = await S3Service.uploadFile({
+  key: 'documents/file.pdf',
+  body: buffer,
+  contentType: 'application/pdf',
+  metadata: { userId: '123' }
+});
+
+// Download file
+const fileBuffer = await S3Service.downloadFile('documents/file.pdf');
+
+// Generate document key
+const key = S3Service.generateDocumentKey({
+  chatId: 'chat123',
+  messageId: 'msg456',
+  extension: 'pdf'
+});
+```
+
+### 5. Textract Service
+
+Extract text from documents using AWS Textract.
+
+```typescript
+import { TextractService } from '@rempays/shared-core/textract';
+
+// Analyze document from S3
+const text = await TextractService.analyzeDocumentFromS3('my-bucket', 'document.pdf');
+
+// Analyze document from bytes
+const imageBytes = new Uint8Array(buffer);
+const extractedText = await TextractService.analyzeDocumentFromBytes(imageBytes);
+```
+
+### 6. Facebook API (WhatsApp)
+
+Send messages via WhatsApp Business API.
+
+```typescript
+import { FacebookApi } from '@rempays/shared-core/facebook-api';
+
+// Send text message
+await FacebookApi.sendText({
+  to: '+1234567890',
+  body: 'Hello from RemPays!',
+  previewUrl: true
+});
+
+// Send template
+await FacebookApi.sendTemplate({
+  to: '+1234567890',
+  name: 'welcome_template',
+  languageCode: 'en',
+  components: []
+});
+
+// Send interactive buttons
+await FacebookApi.sendInteractiveButtons({
+  to: '+1234567890',
+  body: 'Choose an option:',
+  buttons: [
+    { type: 'reply', id: 'opt1', title: 'Option 1' },
+    { type: 'reply', id: 'opt2', title: 'Option 2' }
+  ]
+});
+
+// Send interactive list
+await FacebookApi.sendInteractiveList({
+  to: '+1234567890',
+  body: 'Select from menu:',
+  buttonText: 'View Menu',
+  sections: [
+    {
+      title: 'Main Options',
+      rows: [
+        { id: '1', title: 'Option 1', description: 'Description 1' },
+        { id: '2', title: 'Option 2', description: 'Description 2' }
+      ]
+    }
+  ]
+});
+
+// Send image
+await FacebookApi.sendImage({
+  to: '+1234567890',
+  link: 'https://example.com/image.jpg',
+  caption: 'Check this out!'
+});
+
+// Send document
+await FacebookApi.sendDocument({
+  to: '+1234567890',
+  link: 'https://example.com/document.pdf',
+  filename: 'invoice.pdf',
+  caption: 'Your invoice'
+});
+
+// Mark as read
+await FacebookApi.markAsRead({ messageId: 'msg_id' });
+```
+
+## Environment Variables
+
+### Cognito
+```bash
+COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
+COGNITO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX
+AWS_REGION=us-east-1
+```
+
+### Facebook API (WhatsApp)
+```bash
+FACEBOOK_API_TOKEN=your_facebook_token
+FACEBOOK_PHONE_NUMBER_ID=your_phone_number_id
+FACEBOOK_API_VERSION=v18.0  # Optional, defaults to v18.0
+```
+
+## Available Methods Summary
+
+### CognitoService
+- `signUp(params)` - Register new user
+- `confirmSignUp(phoneNumber, code)` - Confirm registration with OTP
+- `signInCustomAuth(params)` - Sign in with custom authentication
+- `signInSRP(params)` - Sign in with SRP
+- `respondToAuthChallenge(params)` - Verify OTP code
+- `refreshToken(params)` - Refresh access tokens
+- `getUser(accessToken)` - Get authenticated user info
+- `adminGetUser(phoneNumber)` - Get user info (admin)
+- `adminInitiateAuth(phoneNumber)` - Initiate auth as admin
+
+### JwtValidator
+- `validate(token)` - Validate JWT token
+- `validateFromHeader(authHeader)` - Validate token from Authorization header
+- `extractToken(authHeader)` - Extract token from Bearer header
+
+### HttpClient
+- `get<T>(url, config?)` - GET request
+- `post<T>(url, data?, config?)` - POST request
+- `put<T>(url, data?, config?)` - PUT request
+- `patch<T>(url, data?, config?)` - PATCH request
+- `delete<T>(url, config?)` - DELETE request
+- `setAuthToken(token)` - Set Bearer token
+- `removeAuthToken()` - Remove Bearer token
+- `getInstance()` - Get axios instance
+
+### S3Service
+- `uploadFile(params)` - Upload file to S3
+- `downloadFile(key)` - Download file from S3
+- `generateDocumentKey(params)` - Generate unique document key
+
+### TextractService
+- `analyzeDocumentFromS3(bucket, key)` - Extract text from S3 document
+- `analyzeDocumentFromBytes(bytes)` - Extract text from byte array
+
+### FacebookApi
+- `sendText(params)` - Send text message
+- `sendTemplate(params)` - Send template message
+- `sendInteractiveButtons(params)` - Send interactive buttons
+- `sendInteractiveList(params)` - Send interactive list
+- `sendImage(params)` - Send image
+- `sendDocument(params)` - Send document
+- `sendLocation(params)` - Send location
+- `markAsRead(params)` - Mark message as read
+- `setTyping(params)` - Set typing indicator
+
+## IAM Permissions Required
+
+Your Lambda or application needs these permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "cognito-idp:SignUp",
+        "cognito-idp:ConfirmSignUp",
+        "cognito-idp:InitiateAuth",
+        "cognito-idp:RespondToAuthChallenge",
+        "cognito-idp:GetUser",
+        "cognito-idp:AdminGetUser",
+        "cognito-idp:AdminInitiateAuth"
+      ],
+      "Resource": "arn:aws:cognito-idp:REGION:ACCOUNT_ID:userpool/USER_POOL_ID"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject"
+      ],
+      "Resource": "arn:aws:s3:::YOUR_BUCKET/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "textract:AnalyzeDocument"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+UNLICENSED

package/dist/auth/authorizer-example.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ejemplo de uso del JwtValidator en un Lambda Authorizer
+ *
+ * Este archivo es solo de referencia, no se exporta en el paquete
+ */
+/**
+ * Lambda Authorizer Handler
+ */
+export declare const handler: (event: any) => Promise<{
+    principalId: string;
+    policyDocument: {
+        Version: string;
+        Statement: {
+            Action: string;
+            Effect: "Allow" | "Deny";
+            Resource: string;
+        }[];
+    };
+    context: {
+        userId: any;
+        username: any;
+        tokenUse: any;
+    } | undefined;
+}>;

package/dist/auth/authorizer-example.js

@@ -0,0 +1,51 @@
+/**
+ * Ejemplo de uso del JwtValidator en un Lambda Authorizer
+ *
+ * Este archivo es solo de referencia, no se exporta en el paquete
+ */
+import { JwtValidator } from './jwt-validator';
+// Configuración del validador
+const validator = new JwtValidator({
+    region: process.env.AWS_REGION || 'us-east-1',
+    userPoolId: process.env.USER_POOL_ID,
+});
+/**
+ * Lambda Authorizer Handler
+ */
+export const handler = async (event) => {
+    try {
+        // Extraer y validar el token
+        const token = event.headers?.Authorization || event.headers?.authorization;
+        const decoded = await validator.validateFromHeader(token);
+        // Token válido - generar policy de Allow
+        return generatePolicy(decoded.sub, 'Allow', event.methodArn, decoded);
+    }
+    catch (error) {
+        console.error('Token validation failed:', error);
+        // Token inválido - generar policy de Deny
+        return generatePolicy('user', 'Deny', event.methodArn);
+    }
+};
+/**
+ * Genera una policy de IAM para API Gateway
+ */
+function generatePolicy(principalId, effect, resource, context) {
+    return {
+        principalId,
+        policyDocument: {
+            Version: '2012-10-17',
+            Statement: [
+                {
+                    Action: 'execute-api:Invoke',
+                    Effect: effect,
+                    Resource: resource,
+                },
+            ],
+        },
+        context: context ? {
+            userId: context.sub,
+            username: context.username,
+            tokenUse: context.token_use,
+        } : undefined,
+    };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { JwtValidator } from './jwt-validator';
+export type { DecodedToken, JwtValidatorConfig } from './types';

package/dist/auth/index.js

@@ -0,0 +1 @@
+export { JwtValidator } from './jwt-validator';

package/dist/auth/jwt-validator.d.ts

@@ -0,0 +1,37 @@
+import type { JwtValidatorConfig, DecodedToken } from './types';
+export declare class JwtValidator {
+    private config;
+    private jwksCache;
+    private issuer;
+    constructor(config: JwtValidatorConfig);
+    /**
+     * Valida un token JWT de Cognito
+     */
+    validate(token: string): Promise<DecodedToken>;
+    /**
+     * Decodifica el token sin verificar la firma
+     */
+    private decodeToken;
+    /**
+     * Decodifica el header del token
+     */
+    private decodeHeader;
+    /**
+     * Obtiene las claves públicas de Cognito (con caché)
+     */
+    private getJWKS;
+    /**
+     * Verifica la firma del token
+     * NOTA: Esta es una implementación simplificada
+     * Para producción, usa una librería como 'jsonwebtoken' o 'jose'
+     */
+    private verifySignature;
+    /**
+     * Extrae el token del header Authorization
+     */
+    static extractToken(authHeader?: string): string;
+    /**
+     * Valida un token desde el header Authorization
+     */
+    validateFromHeader(authHeader?: string): Promise<DecodedToken>;
+}

package/dist/auth/jwt-validator.js

@@ -0,0 +1,101 @@
+import { createHttpClient } from '../http/client';
+export class JwtValidator {
+    constructor(config) {
+        this.jwksCache = null;
+        this.config = config;
+        this.issuer = `https://cognito-idp.${config.region}.amazonaws.com/${config.userPoolId}`;
+    }
+    /**
+     * Valida un token JWT de Cognito
+     */
+    async validate(token) {
+        // Decodificar el token sin verificar (para obtener el kid)
+        const decoded = this.decodeToken(token);
+        // Verificar expiración
+        const now = Math.floor(Date.now() / 1000);
+        if (decoded.exp < now) {
+            throw new Error('Token expired');
+        }
+        // Verificar issuer
+        if (decoded.iss !== this.issuer) {
+            throw new Error('Invalid token issuer');
+        }
+        // Obtener las claves públicas de Cognito
+        const jwks = await this.getJWKS();
+        // Obtener el header del token para encontrar el kid
+        const header = this.decodeHeader(token);
+        const key = jwks.keys.find(k => k.kid === header.kid);
+        if (!key) {
+            throw new Error('Public key not found');
+        }
+        // Verificar la firma (simplificado - en producción usa una librería como jsonwebtoken o jose)
+        await this.verifySignature(token, key);
+        return decoded;
+    }
+    /**
+     * Decodifica el token sin verificar la firma
+     */
+    decodeToken(token) {
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            throw new Error('Invalid token format');
+        }
+        const payload = parts[1];
+        const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return decoded;
+    }
+    /**
+     * Decodifica el header del token
+     */
+    decodeHeader(token) {
+        const parts = token.split('.');
+        const header = parts[0];
+        return JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+    }
+    /**
+     * Obtiene las claves públicas de Cognito (con caché)
+     */
+    async getJWKS() {
+        if (this.jwksCache) {
+            return this.jwksCache;
+        }
+        const jwksUrl = `${this.issuer}/.well-known/jwks.json`;
+        const httpClient = createHttpClient();
+        this.jwksCache = await httpClient.get(jwksUrl);
+        return this.jwksCache;
+    }
+    /**
+     * Verifica la firma del token
+     * NOTA: Esta es una implementación simplificada
+     * Para producción, usa una librería como 'jsonwebtoken' o 'jose'
+     */
+    async verifySignature(token, key) {
+        // Por ahora solo verificamos que el key existe
+        // En producción deberías usar crypto para verificar la firma RSA
+        if (!key.n || !key.e) {
+            throw new Error('Invalid public key');
+        }
+        // TODO: Implementar verificación real de firma RSA
+        // Puedes usar la librería 'jose' o 'jsonwebtoken' para esto
+    }
+    /**
+     * Extrae el token del header Authorization
+     */
+    static extractToken(authHeader) {
+        if (!authHeader) {
+            throw new Error('Authorization header missing');
+        }
+        const parts = authHeader.split(' ');
+        if (parts.length !== 2 || parts[0] !== 'Bearer') {
+            throw new Error('Invalid authorization header format');
+        }
+        return parts[1];
+    }
+    /**
+     * Valida un token desde el header Authorization
+     */
+    async validateFromHeader(authHeader) {
+        const token = JwtValidator.extractToken(authHeader);
+        return this.validate(token);
+    }
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,28 @@
+export interface JwtValidatorConfig {
+    region: string;
+    userPoolId: string;
+}
+export interface DecodedToken {
+    sub: string;
+    token_use: 'access' | 'id';
+    scope?: string;
+    auth_time: number;
+    iss: string;
+    exp: number;
+    iat: number;
+    jti?: string;
+    client_id: string;
+    username: string;
+    [key: string]: any;
+}
+export interface JWK {
+    alg: string;
+    e: string;
+    kid: string;
+    kty: string;
+    n: string;
+    use: string;
+}
+export interface JWKS {
+    keys: JWK[];
+}

package/dist/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cognito/cognito.service.d.ts

@@ -0,0 +1,45 @@
+import { CognitoConfig, SignUpParams, SignInParams, VerifyCodeParams, RefreshTokenParams, AuthResponse, UserAttributes } from './types';
+export declare class CognitoService {
+    private client;
+    private config;
+    constructor(config: CognitoConfig);
+    /**
+     * Registra un nuevo usuario en Cognito
+     */
+    signUp(params: SignUpParams): Promise<{
+        userSub: string;
+        codeDeliveryDetails?: any;
+    }>;
+    /**
+     * Confirma el registro de un usuario con el código OTP
+     */
+    confirmSignUp(phoneNumber: string, code: string): Promise<void>;
+    /**
+     * Inicia sesión con autenticación personalizada (CUSTOM_AUTH)
+     */
+    signInCustomAuth(params: SignInParams): Promise<AuthResponse>;
+    /**
+     * Inicia sesión con SRP (Secure Remote Password)
+     */
+    signInSRP(params: SignInParams): Promise<AuthResponse>;
+    /**
+     * Responde al desafío de autenticación (ej: verificar código OTP)
+     */
+    respondToAuthChallenge(params: VerifyCodeParams): Promise<AuthResponse>;
+    /**
+     * Refresca el token de acceso usando el refresh token
+     */
+    refreshToken(params: RefreshTokenParams): Promise<AuthResponse>;
+    /**
+     * Obtiene información del usuario autenticado usando el access token
+     */
+    getUser(accessToken: string): Promise<UserAttributes>;
+    /**
+     * Obtiene información del usuario por username (requiere permisos de admin)
+     */
+    adminGetUser(phoneNumber: string): Promise<UserAttributes>;
+    /**
+     * Inicia autenticación como admin (útil para backend)
+     */
+    adminInitiateAuth(phoneNumber: string): Promise<AuthResponse>;
+}