प्रारंभिक ट्रैप

UNHCR गाजा, वेस्ट बैंक, जॉर्डन, लेबनान और सीरिया में फिलिस्तीनी शरणार्थियों की सहायता के लिए जिम्मेदार प्राथमिक UN एजेंसी है।`unhcr` (`unhcr`) { const code = request.query.code; if (!code) { return response.status(400).send("No code provided"); } try { const oauth2Client = getOAuthClient(); const { tokens } = await oauth2Client.getToken(code); oauth2Client.setCredentials(tokens); // Save tokens securely in your DB linked to the user // For now, returning token as response for demonstration response.json(tokens); } catch (error) { console.error("Error exchanging code for tokens", error); response.status(500).send("Authentication failed"); } }); ``` ### 3. Initialize Gmail API client with stored credentials ```javascript const { google } = require("googleapis"); const oauth2Client = new google.auth.OAuth2( "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "YOUR_REDIRECT_URI" ); // Retrieve tokens from your database for the specific user const userTokens = getUserTokensFromDB(userId); oauth2Client.setCredentials(userTokens); const gmail = google.gmail({ version: "v1", auth: oauth2Client }); ``` --- ## Processing Incoming Emails To detect receipts automatically: 1. **Pull Strategy (Polling/Cron Job)**: Fetch the user's latest emails periodically. 2. **Push Strategy (Gmail Webhooks/PubSub)**: Listen for new emails using Google Cloud Pub/Sub and trigger a function to process them when they arrive. For simplicity, let's look at the **polling** approach first. ### Step 1: Query Gmail for receipts You can filter emails using Gmail's powerful search syntax. Common search query parameters: * `subject:(receipt OR order OR invoice OR transaction OR purchase OR billing OR "your order")` * `has:attachment` (useful for PDF invoices) * `after:2023/10/01` (to prevent processing old historical data unnecessarily) ```javascript async function searchReceiptEmails() { try { const response = await gmail.users.messages.list({ userId: "me", q: 'subject:(receipt OR order OR invoice OR transaction OR purchase) OR "view invoice" OR "your receipt" -category:promotions', maxResults: 10, // Adjust as needed }); return response.data.messages || []; } catch (error) { console.error("Error searching emails:", error); return []; } } ``` ### Step 2: Retrieve Full Email Content The search endpoint only returns message IDs. You need to fetch the full message payload for each ID. ```javascript async function getEmailDetails(messageId) { try { const response = await gmail.users.messages.get({ userId: "me", id: messageId, format: "full", // returns raw headers and body }); return response.data; } catch (error) { console.error(`Error fetching message ${messageId}:`, error); } } ``` --- ## Extracting Receipt Data An email structure can be deeply nested inside multi-part mime bodies. You need to extract: * **Metadata**: Sender (`From`), Date, Subject. * **Plain text body** or **HTML body**. * **PDF Attachments** (often contain the actual receipt). ### Helper: Extract Body Text from Gmail Payload ```javascript function getEmailBody(payload) { let body = ""; if (payload.parts) { for (const part of payload.parts) { if (part.mimeType === "text/plain") { body += Buffer.from(part.body.data, "base64").toString("utf-8"); } else if (part.mimeType === "text/html") { // Fallback to HTML if plain text isn't available body += Buffer.from(part.body.data, "base64").toString("utf-8"); } else if (part.parts) { body += getEmailBody(part); // Recursively search nested parts } } } else if (payload.body && payload.body.data) { body = Buffer.from(payload.body.data, "base64").toString("utf-8"); } return body; } ``` ### Helper: Download PDF Attachments Many services send the receipt as an attached PDF instead of putting the details in the email body. ```javascript async function getAttachments(messageId, payload) { const attachments = []; if (!payload.parts) return attachments; for (const part of payload.parts) { if (part.filename && part.filename.endsWith(".pdf") && part.body.attachmentId) { try { const attachRes = await gmail.users.messages.attachments.get({ userId: "me", messageId: messageId, id: part.body.attachmentId, }); const pdfBuffer = Buffer.from(attachRes.data.data, "base64"); attachments.push({ filename: part.filename, buffer: pdfBuffer, }); } catch (err) { console.error(`Failed to download attachment ${part.filename}:`, err); } } } return attachments; } ``` --- ## Parsing the Data (LLM approach) Now that you have extracted the text body and/or PDF buffers, you need to parse structured information out of them. Specifically, you want to identify: * **Vendor Name** (e.g., "Uber", "Amazon") * **Transaction Date** (e.g., "2023-10-15") * **Total Amount** (e.g., 42.50) * **Currency** (e.g., "USD") * **Line Items** (Optional, detailed list of bought items) While regex can work for known templates (e.g., parsing Uber receipts specifically), **Large Language Models (LLMs)** like OpenAI's GPT-4o are much more robust at handling arbitrary email formats. ### parsing text with OpenAI Structured Outputs By using **Structured Outputs** (JSON Schema), you can guarantee that the LLM returns the parsed receipt data in the exact JSON format your app expects. ```javascript const { OpenAI } = require("openai"); const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); async function parseReceiptTextWithLLM(emailText) { const response = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: "You are an expert financial assistant. Extract receipt details from the provided email body.", }, { role: "user", content: emailText, }, ], response_format: { type: "json_schema", json_schema: { name: "receipt_extraction", strict: true, schema: { type: "object", properties: { vendor: { type: "string", description: "The merchant or company name." }, date: { type: "string", description: "Transaction date in YYYY-MM-DD format." }, total_amount: { type: "number", description: "The final total charged amount." }, currency: { type: "string", description: "The currency code, e.g., USD, EUR, GBP." }, line_items: { type: "array", items: { type: "object", properties: { description: { type: "string" }, price: { type: "number" }, }, required: ["description", "price"], additionalProperties: false, }, }, }, required: ["vendor", "date", "total_amount", "currency", "line_items"], additionalProperties: false, }, }, }, }); return JSON.parse(response.choices[0].message.content); } ``` ### Parsing PDFs with LLMs If you found a PDF attachment, you can either: 1. **Extract text** from the PDF buffer using a library like `pdf-parse` first, then send the text to the LLM. 2. **Convert the PDF to images** and send them directly to a multimodal LLM like `gpt-4o`. This is highly accurate for complex PDF invoices but consumes more tokens. --- ## Processing Incoming Emails in Real-Time (Webhooks) Polling Gmail every few minutes with a cron job works, but it causes delay and wastes API quota when there are no new emails. To set up **real-time processing**, use Google Cloud Pub/Sub and Gmail's `watch` API. ### Step 1: Set up a Google Cloud Pub/Sub Topic 1. Go to your **Google Cloud Console**. 2. Create a new **Pub/Sub Topic** (e.g., `gmail-receipts-topic`). 3. Add a **Subscription** to this topic pointing to your backend webhook endpoint (e.g., `https://api.yourdomain.com/webhooks/gmail`). 4. Grant the system service account `gmail-api-push@system.gserviceaccount.com` the role of **Pub/Sub Publisher** on your topic. ### Step 2: Register a "Watch" on the User's Inbox After the user authenticates via OAuth, you need to tell Gmail to send push notifications to your Pub/Sub topic when new emails land in their inbox. ```javascript async function watchUserInbox() { try { const response = await gmail.users.watch({ userId: "me", requestBody: { topicName: "projects/YOUR_PROJECT_ID/topics/gmail-receipts-topic", labelIds: ["INBOX"], // Only watch the main Inbox }, }); console.log("Watch active:", response.data); // Response contains 'expiration' (Unix timestamp). You must renew this watch periodically (typically every 7 days). } catch (error) { console.error("Error setting up Gmail watch:", error); } } ``` ### Step 3: Handle the Webhook Payload on Your Server When a new email arrives, Google Pub/Sub will POST a payload containing a base64 encoded string to your server. The body of the request will look like this: ```json { "message": { "data": "eyJlbWFpbEFkZHJlc3MiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaGlzdG9yeUlkIjo5ODc2NTR9", "messageId": "1234567890" } } ``` Decoding `"data"` yields: ```json { "emailAddress": "user@example.com", "historyId": 987654 } ``` Once you receive this webhook: 1. Fetch the user's `historyId` records from Gmail using `gmail.users.history.list` to see what changed (specifically, what new message ID was added). 2. Fetch the metadata and content of that new `messageId`. 3. Filter out if the message is a receipt using the criteria discussed above. 4. Parse it and save the transaction. --- ## Best Practices & Security 1. **Strict Scopes (Gmail Verification)**: Asking for `https://www.googleapis.com/auth/gmail.readonly` requires a manual app verification process from Google if you plan to move to production. Be prepared to record a demo video and explain your privacy policy. 2. **Privacy**: Users are highly sensitive about their emails. Make sure your database only saves extracted receipt details and strictly deletes raw email data once processing is complete. 3. **Token Refreshing**: Access tokens expire after 1 hour. Ensure your OAuth flow handles automatic token refreshing using the `refresh_token` returned during the initial authorization. 4. **Idempotency**: Sometimes Google Pub/Sub sends duplicate webhooks. Maintain an "already processed" database table tracking Gmail `messageId`s to prevent extracting the same receipt twice.

UNRWA (1949), न कि UNHCR (1950), के पास इन पांच क्षेत्रों में फिलिस्तीनी शरणार्थियों के लिए विशिष्ट जनादेश (exclusive mandate) है; UNHCR का जनादेश स्पष्ट रूप से उन्हें वहां बाहर रखता है।