deevoauth 1.4.5

package/sdk/README.md

@@ -0,0 +1,216 @@
+# deevo-auth
+
+Official SDK for integrating **Deevo Account** OAuth 2.0 authentication into your applications.
+
+## Installation
+
+```bash
+npm install deevo-auth
+```
+
+## Quick Start
+
+### 1. Get your credentials
+
+Visit the [Deevo Developer Console](https://deevo.tech/developers) to register your application and get your `clientId` and `clientSecret`.
+
+### 2. Configure the SDK
+
+```javascript
+const { DeevoAuth } = require('deevo-auth');
+// or: import { DeevoAuth } from 'deevo-auth';
+
+const deevo = new DeevoAuth({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  redirectUri: 'https://yourapp.com/auth/callback',
+});
+```
+
+### 3. Redirect users to sign in
+
+```javascript
+// Express.js example
+app.get('/auth/login', (req, res) => {
+  const loginUrl = deevo.getAuthUrl();
+  res.redirect(loginUrl);
+});
+```
+
+### 4. Handle the callback
+
+```javascript
+app.get('/auth/callback', async (req, res) => {
+  try {
+    const { accessToken, user } = await deevo.handleCallback(req.query.code);
+    
+    // user = { sub: 'uid', name: 'John', email: 'john@example.com', picture: '...' }
+    req.session.user = user;
+    req.session.accessToken = accessToken;
+    
+    res.redirect('/dashboard');
+  } catch (error) {
+    console.error('Auth failed:', error);
+    res.redirect('/login?error=auth_failed');
+  }
+});
+```
+
+## API Reference
+
+### `new DeevoAuth(config)`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `clientId` | string | ✅ | OAuth client ID from Developer Console |
+| `clientSecret` | string | ✅ | OAuth client secret (keep server-side!) |
+| `redirectUri` | string | ✅ | Registered callback URL |
+| `authServerUrl` | string | ❌ | Override auth server (default: `https://deevo.tech`) |
+| `scope` | string | ❌ | Scopes (default: `'profile email'`) |
+
+### `deevo.getAuthUrl(options?)`
+
+Returns the URL to redirect users to for authentication.
+
+```javascript
+const url = deevo.getAuthUrl({ state: 'csrf-token' });
+// => https://deevo.tech/login?client_id=...&redirect_uri=...
+```
+
+### `deevo.exchangeCode(code)`
+
+Exchanges an authorization code for tokens.
+
+```javascript
+const tokens = await deevo.exchangeCode(code);
+// => { access_token: '...', token_type: 'Bearer', expires_in: 3600 }
+```
+
+### `deevo.getUserInfo(accessToken)`
+
+Fetches the authenticated user's profile.
+
+```javascript
+const user = await deevo.getUserInfo(tokens.access_token);
+// => { sub: 'uid', name: 'John Doe', email: 'john@example.com', picture: '...' }
+```
+
+### `deevo.handleCallback(code)`
+
+Convenience method: exchanges code AND fetches user info in one call.
+
+```javascript
+const { accessToken, user } = await deevo.handleCallback(code);
+```
+
+### `deevo.verifyToken(accessToken)`
+
+Verifies a token and returns user info. Useful for API middleware.
+
+```javascript
+const user = await deevo.verifyToken(req.headers.authorization.split(' ')[1]);
+```
+
+## Express Middleware
+
+Protect your API routes:
+
+```javascript
+const { DeevoAuth, deevoMiddleware } = require('deevo-auth');
+
+const deevo = new DeevoAuth({ /* config */ });
+
+app.get('/api/profile', deevoMiddleware(deevo), (req, res) => {
+  // req.deevoUser contains the authenticated user's profile
+  res.json({ user: req.deevoUser });
+});
+```
+
+## Next.js Integration
+
+```javascript
+// pages/api/auth/login.js
+import { DeevoAuth } from 'deevo-auth';
+
+const deevo = new DeevoAuth({
+  clientId: process.env.DEEVO_CLIENT_ID,
+  clientSecret: process.env.DEEVO_CLIENT_SECRET,
+  redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/callback`,
+});
+
+export default function handler(req, res) {
+  res.redirect(deevo.getAuthUrl());
+}
+```
+
+```javascript
+// pages/api/auth/callback.js
+export default async function handler(req, res) {
+  const { code } = req.query;
+  const { accessToken, user } = await deevo.handleCallback(code);
+  
+  // Set session cookie, JWT, etc.
+  res.redirect('/dashboard');
+}
+```
+
+## React Component (Client-side)
+
+```jsx
+function LoginButton() {
+  const handleLogin = () => {
+    window.location.href = '/api/auth/login';
+  };
+
+  return (
+    <button onClick={handleLogin}>
+      Sign in with Deevo
+    </button>
+  );
+}
+```
+
+## Error Handling
+
+```javascript
+const { DeevoAuthError } = require('deevo-auth');
+
+try {
+  const { user } = await deevo.handleCallback(code);
+} catch (error) {
+  if (error instanceof DeevoAuthError) {
+    console.error(`Deevo Auth Error [${error.code}]:`, error.message);
+    // error.code: 'invalid_grant', 'invalid_client', 'token_exchange_failed', etc.
+    // error.statusCode: HTTP status code
+  }
+}
+```
+
+## OAuth Flow Diagram
+
+```
+Your App                    Deevo Auth Server
+   |                              |
+   |  1. Redirect to /login       |
+   | ---------------------------→ |
+   |                              |  2. User signs in
+   |                              |     (Google or Email)
+   |  3. Redirect back with code  |
+   | ←--------------------------- |
+   |                              |
+   |  4. POST /api/oauth/token    |
+   | ---------------------------→ |
+   |                              |
+   |  5. Returns access_token     |
+   | ←--------------------------- |
+   |                              |
+   |  6. GET /api/oauth/userinfo  |
+   | ---------------------------→ |
+   |                              |
+   |  7. Returns user profile     |
+   | ←--------------------------- |
+```
+
+## License
+
+MIT © [Deevo](https://deevo.tech)

package/sdk/build.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const path = require('path');
+
+// Simple build: copy src to dist with CJS and ESM variants
+const src = fs.readFileSync(path.join(__dirname, 'src', 'index.js'), 'utf8');
+
+// Create dist directory
+const distDir = path.join(__dirname, 'dist');
+if (!fs.existsSync(distDir)) {
+  fs.mkdirSync(distDir, { recursive: true });
+}
+
+// CJS version (remove ESM export lines)
+const cjs = src
+  .replace(/^export \{.*\};?$/gm, '')
+  .replace(/^export default.*$/gm, '');
+
+fs.writeFileSync(path.join(distDir, 'index.js'), cjs);
+
+// ESM version (remove CJS export lines)
+const esm = src
+  .replace(/if \(typeof module.*\n(.*\n)*?.*module\.exports\.default.*\n\}/m, '');
+
+fs.writeFileSync(path.join(distDir, 'index.mjs'), esm);
+
+// Copy type definitions
+const types = fs.readFileSync(path.join(__dirname, 'src', 'index.d.ts'), 'utf8');
+fs.writeFileSync(path.join(distDir, 'index.d.ts'), types);
+
+console.log('✓ Built deevo-auth SDK to dist/');

package/sdk/dist/index.d.ts

@@ -0,0 +1,69 @@
+export interface DeevoAuthConfig {
+  /** Your OAuth client ID from the Deevo Developer Console */
+  clientId: string;
+  /** Your OAuth client secret (keep server-side only!) */
+  clientSecret: string;
+  /** The callback URL registered in your Deevo app */
+  redirectUri: string;
+  /** Override the auth server URL (default: https://deevo.tech) */
+  authServerUrl?: string;
+  /** Space-separated scopes (default: 'profile email') */
+  scope?: string;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  scope?: string;
+}
+
+export interface DeevoUser {
+  /** Unique user identifier */
+  sub: string;
+  /** User's full name */
+  name: string;
+  /** User's email address */
+  email: string;
+  /** URL to user's profile picture */
+  picture: string;
+}
+
+export interface CallbackResult {
+  accessToken: string;
+  tokenType: string;
+  expiresIn: number;
+  user: DeevoUser;
+}
+
+export class DeevoAuth {
+  constructor(config: DeevoAuthConfig);
+
+  /** Get the URL to redirect users to for authentication */
+  getAuthUrl(options?: { state?: string }): string;
+
+  /** Exchange an authorization code for tokens */
+  exchangeCode(code: string): Promise<TokenResponse>;
+
+  /** Get the authenticated user's profile information */
+  getUserInfo(accessToken: string): Promise<DeevoUser>;
+
+  /** Complete OAuth flow: exchange code + get user info */
+  handleCallback(code: string): Promise<CallbackResult>;
+
+  /** Verify an access token and get user info */
+  verifyToken(accessToken: string): Promise<DeevoUser>;
+}
+
+export class DeevoAuthError extends Error {
+  code: string;
+  statusCode: number;
+  constructor(message: string, code: string, statusCode: number);
+}
+
+/** Express.js middleware for protecting routes */
+export function deevoMiddleware(
+  deevoAuth: DeevoAuth
+): (req: any, res: any, next: any) => Promise<void>;
+
+export default DeevoAuth;

package/sdk/dist/index.js

@@ -0,0 +1,228 @@
+/**
+ * Deevo Auth SDK
+ * Official SDK for integrating Deevo Account OAuth 2.0 into your applications.
+ * 
+ * Usage:
+ *   import { DeevoAuth } from 'deevo-auth';
+ *   
+ *   const deevo = new DeevoAuth({
+ *     clientId: 'YOUR_CLIENT_ID',
+ *     clientSecret: 'YOUR_CLIENT_SECRET',
+ *     redirectUri: 'https://yourapp.com/auth/callback',
+ *   });
+ */
+
+const DEFAULT_AUTH_URL = 'https://deevo.tech';
+
+class DeevoAuth {
+  /**
+   * Create a new DeevoAuth instance.
+   * @param {Object} config
+   * @param {string} config.clientId - Your OAuth client ID from the Deevo Developer Console
+   * @param {string} config.clientSecret - Your OAuth client secret (keep this server-side only!)
+   * @param {string} config.redirectUri - The callback URL registered in your Deevo app
+   * @param {string} [config.authServerUrl] - Override the auth server URL (default: https://deevo.tech)
+   * @param {string} [config.scope] - Space-separated scopes (default: 'profile email')
+   */
+  constructor(config) {
+    if (!config.clientId) throw new Error('DeevoAuth: clientId is required');
+    if (!config.clientSecret) throw new Error('DeevoAuth: clientSecret is required');
+    if (!config.redirectUri) throw new Error('DeevoAuth: redirectUri is required');
+
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.redirectUri = config.redirectUri;
+    this.authServerUrl = (config.authServerUrl || DEFAULT_AUTH_URL).replace(/\/$/, '');
+    this.scope = config.scope || 'profile email';
+  }
+
+  /**
+   * Get the URL to redirect users to for authentication.
+   * Redirect the user's browser to this URL to start the OAuth flow.
+   * 
+   * @param {Object} [options]
+   * @param {string} [options.state] - Optional state parameter for CSRF protection
+   * @returns {string} The authorization URL
+   * 
+   * @example
+   *   // Express.js route
+   *   app.get('/auth/login', (req, res) => {
+   *     const url = deevo.getAuthUrl({ state: 'random-csrf-token' });
+   *     res.redirect(url);
+   *   });
+   */
+  getAuthUrl(options = {}) {
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      scope: this.scope,
+    });
+
+    if (options.state) {
+      params.set('state', options.state);
+    }
+
+    return `${this.authServerUrl}/login?${params.toString()}`;
+  }
+
+  /**
+   * Exchange an authorization code for an access token.
+   * Call this in your callback route after the user is redirected back.
+   * 
+   * @param {string} code - The authorization code from the callback URL query params
+   * @returns {Promise<Object>} Token response with access_token, token_type, expires_in
+   * 
+   * @example
+   *   // Express.js callback route
+   *   app.get('/auth/callback', async (req, res) => {
+   *     const { code } = req.query;
+   *     const tokens = await deevo.exchangeCode(code);
+   *     // tokens.access_token is your bearer token
+   *   });
+   */
+  async exchangeCode(code) {
+    const response = await fetch(`${this.authServerUrl}/api/oauth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'authorization_code',
+        code,
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
+        redirect_uri: this.redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new DeevoAuthError(
+        error.message || `Token exchange failed with status ${response.status}`,
+        error.error || 'token_exchange_failed',
+        response.status
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get the authenticated user's profile information.
+   * 
+   * @param {string} accessToken - The access token from exchangeCode()
+   * @returns {Promise<Object>} User profile { sub, name, email, picture }
+   * 
+   * @example
+   *   const user = await deevo.getUserInfo(tokens.access_token);
+   *   console.log(user.email, user.name);
+   */
+  async getUserInfo(accessToken) {
+    const response = await fetch(`${this.authServerUrl}/api/oauth/userinfo`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new DeevoAuthError(
+        error.message || `UserInfo request failed with status ${response.status}`,
+        error.error || 'userinfo_failed',
+        response.status
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Complete OAuth flow in one call: exchange code and get user info.
+   * Convenience method combining exchangeCode() + getUserInfo().
+   * 
+   * @param {string} code - The authorization code from the callback URL
+   * @returns {Promise<Object>} { accessToken, tokenType, expiresIn, user }
+   * 
+   * @example
+   *   app.get('/auth/callback', async (req, res) => {
+   *     const { accessToken, user } = await deevo.handleCallback(req.query.code);
+   *     req.session.user = user;
+   *     req.session.accessToken = accessToken;
+   *     res.redirect('/dashboard');
+   *   });
+   */
+  async handleCallback(code) {
+    const tokens = await this.exchangeCode(code);
+    const user = await this.getUserInfo(tokens.access_token);
+
+    return {
+      accessToken: tokens.access_token,
+      tokenType: tokens.token_type,
+      expiresIn: tokens.expires_in,
+      user,
+    };
+  }
+
+  /**
+   * Verify an access token and get user info (useful for API middleware).
+   * 
+   * @param {string} accessToken - The Bearer token to verify
+   * @returns {Promise<Object>} User profile if valid
+   * @throws {DeevoAuthError} If the token is invalid or expired
+   */
+  async verifyToken(accessToken) {
+    return this.getUserInfo(accessToken);
+  }
+}
+
+/**
+ * Express.js middleware for protecting routes with Deevo Auth.
+ * 
+ * @param {DeevoAuth} deevoAuth - A configured DeevoAuth instance
+ * @returns {Function} Express middleware
+ * 
+ * @example
+ *   app.get('/api/protected', deevoMiddleware(deevo), (req, res) => {
+ *     res.json({ user: req.deevoUser });
+ *   });
+ */
+function deevoMiddleware(deevoAuth) {
+  return async (req, res, next) => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'Missing or invalid authorization header' });
+    }
+
+    const token = authHeader.split(' ')[1];
+    try {
+      const user = await deevoAuth.verifyToken(token);
+      req.deevoUser = user;
+      next();
+    } catch (error) {
+      return res.status(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+}
+
+/**
+ * Custom error class for Deevo Auth errors.
+ */
+class DeevoAuthError extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.name = 'DeevoAuthError';
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+// Export for CommonJS
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { DeevoAuth, deevoMiddleware, DeevoAuthError };
+  module.exports.DeevoAuth = DeevoAuth;
+  module.exports.deevoMiddleware = deevoMiddleware;
+  module.exports.DeevoAuthError = DeevoAuthError;
+  module.exports.default = DeevoAuth;
+}
+
+// Export for ESM
+
+