DEV Community: Brian Baliach

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript

Brian Baliach — Tue, 10 Feb 2026 11:00:29 +0000

Building production-grade AI agents is tricky. In a landscape shifting rapidly, betting your entire architecture on a single provider's raw SDK allows for quick starts but leads to brittle vendor lock-in. This is where Google’s Agent Development Kit (ADK) shines. It acts as a crucial abstraction layer, providing a standardized common interface for defining tools (similar to LiteLLM which Google ADK actually uses internally), events, and agent orchestration. This means you aren't locked solely into Gemini; you can design systems that utilize different models from various providers — even using them as fallbacks for one another — without rewriting your core business logic.

However, if you’ve tried taking the ADK into production with TypeScript, you’ve likely hit a significant reality gap. While the Python documentation is comprehensive, the TypeScript side is remarkably thin, steering devs toward "ADK Devtools" which, while fine for local prototyping, simply don't cut it for a hardened production stack.

Before we fix that, let's briefly strip away the jargon and define how the ADK actually works under the hood. It relies on three core concepts:

The Runner (Event Loop): Think of this as the engine room. It’s an asynchronous loop that takes an incoming signal (an event), processes it through your agent’s logic (calling the LLM, executing tools), and determines the next step (updating state in the process).
State: This is the "short-term memory" of the active conversation. It’s mutable data representing where the user is right now in a flow (e.g., { step: 'collecting_address', attempt: 2 }).
Context: The environment the runner operates in. This is the static stuff the agent needs to do its job but doesn't change turn-by-turn. Think database connections, user IDs, or API keys.

Here is the crucial part for production: Events in the ADK aren't just passive text messages. They carry their own state payload representing a "delta" or in simple layman terms, change. The Runner uses this specific event state to update the overall session state before beginning the next turn (handled by the session service).

You can read more about the Google ADK architecture here: https://google.github.io/adk-docs/get-started/about/

In a real-world environment, you can't let that critical state live in volatile, in-memory storage. You need true persistence so agents retain context across server restarts and container scaling. Furthermore, if you’re running a modern TypeScript stack with ESM, the currently shipped @google/adk package suffers from dependency conflicts that break standard builds.

Today, we’re going to fix this. We'll walk through patching the ADK to bridge the ESM/CommonJS gap and implementing custom PostgreSQL-backed session and memory services to ensure that state is saved durably. It’s a deep dive, but essential for anyone moving beyond the "Hello World" phase.

Here's the GitHub repo with complete code examples you can refer from: tutorial repository

The Current Limitations

For production TypeScript applications, the current ADK falls short in three key areas:

Lack of Persistence: The provided examples use in-memory services. Server restarts mean lost user context.
ESM/CJS Conflicts: The published package's CommonJS build incorrectly imports the ESM-only lodash-es package, rather than standard lodash, breaking many build pipelines.
Missing Infrastructure: Unlike the Python SDK, the TypeScript version lacks built-in persistent session services (like VertexAI) out of the box.

We will resolve these issues using NestJS, TypeORM (PostgreSQL), and pnpm package manager for patching.

Hands-On: Building a Persistent ADK Agent

We are going to implement a CloudSqlSessionService and a CloudSqlMemoryService. This ensures your agent's state and long-term memories live safely in your Postgres database rather than ephemeral RAM.

1. Patching @google/adk

The first step is stabilizing the dependency tree. As mentioned, the @google/adk package currently ships a CommonJS build that incorrectly imports lodash-es. We need to patch this to get it running in a modern environment.

Ensure you have pnpm installed, then run (I assume here that you already have this dependency included in your project):
pnpm patch @google/adk

Open the temporary directory pnpm provides (it'll be printed out in your terminal) and make two changes:

In package.json, add the standard lodash (CommonJS) to dependencies, matching the version of the existing lodash-es entry.
In dist/cjs/index.js, do a find-and-replace: change all instances of 'lodash-es' to 'lodash'.

Here's my package.json example:

{
  "dependencies": {
    "@google/genai": "^1.37.0",
    "@modelcontextprotocol/sdk": "^1.24.0",
    "google-auth-library": "^10.3.0",
    "lodash-es": "^4.17.22",
    "lodash": "^4.17.22", <----- This change here. Also ensure version numbers match for lodash-es (above) and lodash.
    "zod": "3.25.76"
  }

Apply the fix:
pnpm patch-commit <path-to-temp-dir>

Note: You can find the already-patched version in the tutorial repository if you want to skip this step.

2. The Webpack Shim (For NX/Webpack users)

If you are using Webpack (or NX), you need to configure it to handle mixed module types. Since your project is likely ESM, but the patched ADK package is CJS, your webpack.config.cjs (you should have a webpack.config.js file if your project is commonjs) needs explicit handling for output formatting to ensure Node runs it correctly.

// Key configuration: Save output as .cjs to run as a CommonJS module while maintaining TS paths (if your project is esm), otherwise, use .js
config.output = {
  ...config.output,
  // ensure the output is treated as commonjs
  filename: '[name].cjs',
  chunkFilename: '[name].chunk.cjs',
};

3. Implementing Persistent Sessions

Before we go to the actual meat of the implementation, I'll briefly explain the database entities and how they map to Google ADK types (feel free to skip this section if this is of no interest to you).

The Persistence Schema: Mapping ADK to PostgreSQL

You'll need a database schema that mirrors the ADK's internal logic. Using TypeORM, we define three primary entities: Sessions, Events, and Memories.

The Session Entity

The SessionEntity acts as the root. It tracks the overall state (the short-term memory) and metadata like appName and userId. This ensures that even if your server instances cycle, the agent knows exactly where it left off with a specific user.

import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';
import { Column, Entity, OneToMany, Index } from 'typeorm';
import { EventEntity } from './event.entity.mjs';

@Entity('adk_sessions')
export class SessionEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 100 })
  @Index({ unique: true })
  sessionId: string; // The ADK session identifier (e.g. phone_YYYY-MM-DD)

  @Column({ type: 'varchar', length: 255 })
  appName: string;

  @Column({ type: 'varchar', length: 255 })
  userId: string; // The phone number identifier

  @Column({ type: 'jsonb', default: {} })
  state: Record<string, unknown>;

  @Column({ type: 'bigint' })
  lastUpdateTime: number;

  @Column({ type: 'boolean', default: false })
  isSummarized: boolean; // To avoid re-summarizing already summarized sessions.

  @OneToMany(() => EventEntity, (event: EventEntity) => event.session, { cascade: true })
  events: EventEntity[];
}

The Event Entity

Every interaction, whether it’s a user message, an agent response, or a tool execution, is an event. Notice the actions and content columns are jsonb. This is because ADK events are complex objects; storing them as JSON allows us to preserve the full payload without creating dozens of narrow columns.

import { Column, Entity, JoinColumn, ManyToOne, type Relation } from 'typeorm';
import { SessionEntity } from './session.entity.mjs';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_events')
export class EventEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 150, unique: true })
  eventId: string; // Global Event ID provided by ADK

  @ManyToOne(() => SessionEntity, (session) => session.events, { onDelete: 'CASCADE' })
  @JoinColumn()
  session: Relation<SessionEntity>;

  @Column({ type: 'jsonb' })
  actions: Record<string, unknown>; // Stores the full ADK Event object

  @Column({ type: 'varchar', length: 255 })
  invocationId: string;

  /**
   * Represents the entity that generated the event.
   * "user" - for input from the human user
   * "Agent Name" - (e.g. "General Agent") for output from a specific AI agent
   */
  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'varchar', length: 255, nullable: true })
  branch: string;

  @Column({ type: 'jsonb' })
  content: Record<string, unknown>; // Stores the full ADK Event object
}

The Memory Entity

Finally, the MemoryEntity handles long-term persistence. The key column here is embedding, which uses the vector type. This is what allows your agent to perform semantic searches over thousands of past interactions to find relevant historical context.

import { Column, Entity, Index } from 'typeorm';
import type { Content } from '@google/genai';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_memories')
export class MemoryEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 255 })
  @Index()
  userId: string;

  @Column({ type: 'varchar', length: 255 })
  @Index()
  appName: string;

  @Column({ type: 'jsonb' })
  content: Content;

  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'vector', length: 768, nullable: true })
  embedding: number[];
}

Actual Implementation: The Services Layer

We need a custom SessionService that persists state to PostgreSQL via TypeORM.

Critical Implementation Detail: When overriding the appendEvent method in your custom service, you must call super.appendEvent({ session, event }) first.
This call registers the incoming event with the ADK framework's current in-memory execution context for the active "turn." If you omit this, the framework won't recognize that an event occurred, even if you successfully save it to your database.

Here's a code snippet of my implementation (you can find the full code example in the project repo):

export class CloudSqlSessionService extends BaseSessionService {
  override async appendEvent({ session, event }: AppendEventRequest): Promise<Event> {
    // 1. Essential: Tell the ADK framework something happened in this turn
    await super.appendEvent({ session, event });

    // 2. Fetch current session state from DB
    const sessionEntity = await this.sessionsRepository.findOne({
      where: { sessionId: session.id },
    });

    // 3. Create event entity
    const eventEntity = this.eventsRepository.create({
      /* ... mapping logic ... */
    });

    await this.eventsRepository.save(eventEntity);

    // 4. Persist the updated state delta to Postgres
    await this.sessionsRepository.update(sessionEntity.id, {
      state: updatedState,
      lastUpdateTime: Date.now(),
    });

    return event;
  }
}

4. Long-Term Memory (Vector Search)

For long-term recall across different sessions, we implement a CloudSqlMemoryService. This utilizes pgvector within PostgreSQL for similarity search and Gemini’s text-embedding-004 model for generating embeddings.
Important: You MUST enable the pgvector extension in postgres. Refer to this link on how to install this extension: installation instructions, then enable it by running this command:

CREATE EXTENSION IF NOT EXISTS vector;

Here's the code example for saving and searching your long term memory (again, the full code example is available in the project repo):

export class CloudSqlSessionService extends BaseSessionService {
  async addSessionToMemory(session: Session): Promise<void> {
    console.info(`------------- Adding session ${session.id} events (total events: ${session.events.length}) to memory for user ${session.userId} -------------`);

    for (const event of session.events) {
      console.log('event: ', event);
      console.log('event.content: ', event.content);
      const textContent = stringifyContent(event).trim();
      console.log('textContent: ', textContent, '\n\n');
      if (!textContent) {
        continue;
      }

      try {
        const embedding = await this.generateEmbedding(textContent);

        const memory = this.memoryRepository.create({
          userId: session.userId,
          appName: session.appName,
          content: event.content,
          author: event.author || 'unknown',
          timestamp: event.timestamp,
          embedding: embedding,
        });

        await this.memoryRepository.save(memory);
      } catch (e) {
        console.error(`Failed to generate embedding for event in session ${session.id}: ${e.message}`, e);
      }
    }
  }

  /**
   * Searches for relevant memories using vector similarity.
   */
  async searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse> {
    const { appName, userId, query } = request;

    try {
      const queryEmbedding = await this.generateEmbedding(query);
      const vectorStr = `[${queryEmbedding.join(',')}]`;

      // Use pgvector's cosine distance operator <=>
      const results = await this.dataSource.query(
        `SELECT id, content, author, timestamp
         FROM adk_memories
         WHERE "userId" = $1
           AND "appName" = $2
         ORDER BY embedding <=> $3
           LIMIT 5`,
        [userId, appName, vectorStr],
      );

      const memories: MemoryEntry[] = results.map(r => ({
        content: r.content,
        author: r.author,
        timestamp: r.timestamp,
      }));

      return { memories };
    } catch (error) {
      console.error(`Failed to search memory: ${error.message}`, error);
      return { memories: [] };
    }
  }

  /**
   * Generates an embedding for the given text.
   */
  private async generateEmbedding(text: string): Promise<number[]> {
    const response = await this._genAI.models.embedContent({
      model: 'text-embedding-004',
      contents: [text],
    });
    if (!response.embeddings || response.embeddings.length === 0) {
      throw new Error('No embeddings returned from API');
    }
    return response.embeddings[0].values!;
  }
}

5) Giving the Agent a "Memory" Tool

With your CloudSqlMemoryService in place, you need a way for the agent to actually trigger a search. In the ADK, this is done by defining a FunctionTool. This tool acts as the bridge between the LLM’s reasoning and your vector database.

When the agent realizes it lacks specific historical context (e.g., "What did we discuss about the project architecture last month?"), it will call this load_memory tool.

import { FunctionTool } from '@google/adk';
import { z } from 'zod';

/**
 * A built-in tool that allows agents to load relevant long-term memories.
 */
const loadMemoryTool = new FunctionTool({
  name: 'load_memory',
  description: 'Loads relevant long-term memories for the current user based on a query.',
  parameters: z.object({
    query: z.string().describe('The search query for memory.'),
  }),
  execute: async ({ query }, toolContext) => {
    if (!toolContext) {
      throw new Error('Tool context is missing');
    }
    // The ADK passes the active MemoryService via toolContext
    return await toolContext.searchMemory(query);
  },
});

export default loadMemoryTool;

Why `toolContext` is Key

Notice that we don't import the memory service directly into the tool. Instead, we pull it from the toolContext. This is an architectural win: it keeps your tools decoupled from specific database implementations and ensures that the search is automatically scoped to the correct userId and appName currently active in the session.

6) Orchestrating the Agent (The "General Agent" Factory)

Now that we have our persistent services and our load_memory tool, we need to wire them into the agent. In a production NestJS or Express environment, you’ll often want to pass external dependencies (like database connections or configurations) into your agent definition.

A clean way to do this is by using a factory function. This allows you to inject your MainContext directly into the agent and its sub-agents.

import { LlmAgent } from '@google/adk';
import loadMemoryTool from '../load-memory.tool.mjs';

// Factory function to inject context and dependencies
export default function generalAgent(context: MainContext) {
  return new LlmAgent({
    name: 'general_agent',
    model: 'gemini-1.5-pro', // Use your preferred model constant
    instruction: `
  **Identity:**
  You are SkyCast, a helpful weather assistant. 
  **Current Date and Time:** {current_datetime}

  **Long-term Memory:** You can access the user's favorite locations and past queries by calling the \`load_memory\` tool.

  **User profile:** {user:profile?} 
  Use this to identify the user's home city or preferred units.

  **Core Responsibilities:**
  1. **Triage & Routing:** Route users to specific sub-agents (user, forecast, or alerts).
  2. **Memory Retrieval:** Proactively check memory for saved preferences if the user is vague.
  `,
    tools: [loadMemoryTool],
    // Sub-agents receive the same context for consistent behavior
    subAgents: [userAgent(context), forecastAgent(context), alertsAgent(context)],
  });
}

Why This Structure Wins

Recursive Context: By passing context into subAgents, every agent in the hierarchy shares the same understanding of the user's session and database connection.
Dynamic Instructions: Notice the placeholders like {current_datetime} and {user:profile?}. The ADK fills these in at runtime, giving the LLM immediate "short-term" context before it even decides to call the "long-term" load_memory tool.
Agent Handoffs: The subAgents array defines the "routing" capabilities. If the user asks to register, the General Agent handles the handoff to the user_agent automatically based on your routing rules.

Architectural Benefits

By moving off the default in-memory implementations and using a factory pattern for orchestration, we gain several production advantages:

Stateless Application Tier: Offloading state to PostgreSQL means your application containers can scale horizontally without losing track of a user's progress.
Session Durability: User context survives deployments, crashes, or server restarts.
Complex Multi-Agent Logic: The factory pattern allows you to build a sophisticated "brain" that delegates specialized tasks (like weather alerts or billing) while maintaining a single source of truth for user memory.

Wrapping Up

By patching the ADK's module issues, implementing database-backed services, and orchestrating your agents through a clean factory pattern, you move from a prototype to a production-ready system. The result is a robust backend that handles state correctly, regardless of infrastructure churn.

AI Agents, Not If-Else: A Friendly Intro to Tool-Calling with CSVs

Brian Baliach — Fri, 24 Oct 2025 14:28:37 +0000

Imagine this: You have an Excel or CSV (or any other) dataset, and you want quick, clear answers from it. Maybe something simple on the lines of: "What’s the average price by country?".
Also, you do not use Excel (or you just hate Microsoft and are an apple junkie, despite their recent uninspired "innovations" like re-arranging cameras and renaming abbreviations like AI), and you definitely do not have a data science degree and aren't planning on getting one.

With AI (or AGI, or ASI, or whichever new acronym the industry comes up with tomorrow), you probably don’t have to. Upload your file, ask your question, and the assistant will inspect the columns, validate types, choose the right calculation, and deliver a crisp summary. No data science degree and no big budgets on Microsoft software - just useful insights from your data.

That is the magic of agentic AI and tool-calling.

How Agentic AI Solves the Spreadsheet Sweat

Think of an "agent" as a seasoned analyst who:

Understands your question in plain language.
Chooses the right tools (average, sum, min, max).
Validates the data and asks clarifying questions when things are ambiguous.
Returns a concise answer with just the essentials.

Tool-calling is simply how the agent gets real work done: it calls small, well-defined functions (tools) to compute things accurately. If you say "average price," the agent picks the average tool, ensures "price" exists and is numeric, and then computes it.

No more trying to predict every user action with a jungle of if-else branches. People are gloriously unpredictable - remember all that blockchain hype? Door locks on the blockchain, toasters on the blockchain... in what world would your smart bed need blockchain?
Instead, define small, composable tools with clear contracts, and let the agent do the orchestration, validation and computation:

Infer intent from natural language
Inspect schema or preview to confirm columns and types
Select the right tool (average, sum, min, max)
Supply the correct parameters
Catch and explain errors in plain English
Ask clarifying questions when things are ambiguous

Even your grandpa or grandma does not need to video call you to ask how to answer a call on Skype (also, who uses Skype nowadays). The AI handles everything and picks the correct inputs for your tools so that users can just ask, and they get answers.

What Is Tool-Calling, Really?

If LLMs are your conversational layer, tools are your calculators, databases, and business logic. The LLM doesn’t need to "guess" results - it orchestrates:

Which tool to call
With which parameters
In what order
And how to present the answer back to you

This is how LLMs stop hallucinating numbers and start doing grounded, verifiable work.

A Friendly Real-World Aside

This shift is already happening in the industry — and at my workplace, farmbetter — where we’re equipping our WhatsApp bot with AI. Instead of hardcoding every flow and error message, we let an agent validate inputs, ask follow-up questions, and run the right tools. The result: more natural conversations and fewer dead ends.

Also: the UI for this demo is AI-generated. Because of course it is.

Try It Yourself

Upload a CSV and chat with it like a human. Ask "Total revenue by country" or "Average price." The agent will do the rest.

Live demo: [https://ask-your-csv-agent.vercel.app]

GitHub: [https://github.com/TylerMutai/ask-your-csv-agent.git]

If you just want the big picture, you can stop here. For devs who want to see how the sausage is made, do read on.

Hands-On: Building a CSV Agent with Next.js and TypeScript

We’ll build a simple analysis agent with four tools: average, sum, min, and max. The agent:

Works only with the loaded CSV
Never guesses column names or types
Validates numeric columns before computing
Stays concise and helpful (no words of affirmation like: Spectacularly superb question)

1) Define the Agent

Before we begin: This guide uses OpenAI’s Agent SDK in a Next.js app with TypeScript (@openai/agents).
If you prefer Python, there's a Python SDK with the same a very similar API.
On another stack? The patterns and concepts highlighted in this guide map cleanly to other AI providers (e.g., Google Gemini - I have another blog on this focused also on AI and tool calling that you can check out (here)[https://www.balysnotes.com/integrating-model-context-protocol-with-gemini].

Also, here's the entire project codebase: [https://github.com/TylerMutai/ask-your-csv-agent.git]

Moving on...

We’ll give the agent clear instructions and register our tools. The agent decides when to call them.

import {Agent} from "@openai/agents";
import averageTool from "@/tools/average";
import minTool from "@/tools/min";
import maxTool from "@/tools/max";
import sumTool from "@/tools/sum";

const mainAgent = new Agent({
  name: 'Assistant',
  instructions: `
You are a data analysis agent that answers questions about a CSV file. Your job is to compute accurate summaries (e.g., average, sum, count, min, max), optionally grouped by one or more columns, and return concise, helpful answers.

Behavior
- Work only with the currently loaded CSV. If no file is loaded, ask the user to upload one.
- Never guess column names or types. When unsure, inspect the schema or preview a few rows first.
- Validate that target columns exist and are numeric before computing numeric metrics; if not, ask a clarifying question or suggest valid columns.
- Prefer aggregated results over raw row dumps. If a result set would be large, summarize and show only the top 10 groups.
- Be concise: provide a one-sentence conclusion followed by a small, readable table of results (if applicable). Include units and time ranges when known.
- For ambiguous requests (e.g., "average price"), ask which column to use or propose likely matches.
- If grouping is requested (e.g., "by country" or "per month"), perform a grouped aggregation and sort results sensibly.
- If an operation is not possible (missing column, wrong type), explain the issue and propose alternatives.

Tool use
- Use schema/columns tools before calculations if uncertain.
- Use preview to verify formatting (e.g., dates).
- Use aggregate tools for grouped metrics.
- Use filter/query tools for conditions.
- Use a plotting tool when asked or when trends are natural.

Constraints and formatting
- Limit previews to ≤20 rows.
- Limit output tables to ≤10 rows.
- Do not fabricate values or columns.
- Return answers in this order:
  1) Short conclusion (one or two sentences).
  2) Compact table with clear headers.
  3) Notes about assumptions or limitations (only if relevant).
`,
  tools: [averageTool, minTool, maxTool, sumTool],
});

export default mainAgent;

Key idea: the LLM doesn’t compute - your tools do. The agent just decides which tool to call and how.

2) Create a Tool: Average

We’ll parse the CSV safely, validate columns, and compute the mean. If something’s off, we throw precise errors that the agent turns into friendly explanations.

import {tool} from "@openai/agents";
import {z} from "zod/v3";
import parseAndFormatCsvData from "@/utils/parseAndFormatCsvData";

const averageTool = tool({
  name: 'average_tool',
  description: "'Finds the average of a given set of data.',"
  parameters: z.object({
    data: z.string(),
    columns: z.array(z.string()),
  }),
  execute: async ({data, columns}) => {
    const records = parseAndFormatCsvData({data, columns});
    const averages: { [key: string]: number } = {};

    for (const column of columns) {
      const sum = records.reduce((acc: number, row: { [key: string]: unknown }) => acc + Number(row[column]), 0);
      averages[column] = sum / records.length;
    }

    return `averages according to columns: ${JSON.stringify(averages)}`;
  },
});

export default averageTool;

And here’s our CSV parser and validator:

import {parse} from "csv-parse/sync";

const parseAndFormatCsvData = ({data, columns}: { data: string, columns: string[] }) => {
  const records: { [key: string]: unknown }[] = parse(data, {
    columns: true,
    skipEmptyLines: true,
    skipRecordsWithError: true,
  });

  for (const record of records) {
    for (const column of columns) {
      if (!record[column]) {
        throw new Error(`Column ${column} not found in data`);
      }
      if (isNaN(Number(record[column]))) {
        throw new Error(`Column ${column} contains non-numeric values`);
      }
    }
  }

  return records;
};

export default parseAndFormatCsvData;

Why this matters: instead of a generic "Something went wrong," the agent can say "Column price contains non-numeric values; try unit_price instead?" That’s kinder UX and better debugging.

3) Run the Agent on an API Route

We’ll post chat messages plus the CSV to an API route. The agent gets the CSV as context and replies with a concise answer.

import {AgentInputItem, run} from "@openai/agents";
import mainAgent from "@/agents/mainAgent";

export async function POST(req: Request) {
  try {
    const {csvData, messages} = await req.json();

    const conversationMessages: AgentInputItem[] = messages.map((msg: { role: string; content: string }) => ({
      role: msg.role,
      content: [{type: msg.role === 'assistant' ? 'output_text' : 'input_text', text: msg.content}],
    }));

    const result = await run(mainAgent, conversationMessages, {
      context: csvData,
    });

    return Response.json({response: result.finalOutput});
  } catch (error) {
    console.error("Chat API error:", error);
    return Response.json({error: "Failed to process request"}, {status: 500});
  }
}

Note: You can also inject the CSV as the first user message if you prefer; passing it as context keeps prompts tidy.

4) A Minimal Frontend Chat

A simple chat interface in Next.js. Paste this into a client component and wire it to your API route.

"use client";

import {useEffect, useRef, useState} from "react";

interface Message {
  id: string;
  role: "user" | "assistant";
  content: string;
  timestamp: Date;
}

export default function ChatInterface({csvData, fileName, onReset}: {csvData: string; fileName: string; onReset: () => void;}) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const messagesEndRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({behavior: "smooth"});
  }, [messages]);

  const handleSendMessage = async (userMessage: string) => {
    if (!userMessage.trim()) return;

    const newUserMessage: Message = {
      id: Date.now().toString(),
      role: "user",
      content: userMessage,
      timestamp: new Date(),
    };

    setMessages((prev) => [...prev, newUserMessage]);
    setIsLoading(true);

    try {
      const response = await fetch("/api/chat", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify({
          csvData,
          messages: [...messages, newUserMessage].map((m) => ({role: m.role, content: m.content})),
        }),
      });

      const data = await response.json();
      const assistantMessage: Message = {
        id: (Date.now() + 1).toString(),
        role: "assistant",
        content: data.response ?? "No response",
        timestamp: new Date(),
      };
      setMessages((prev) => [...prev, assistantMessage]);
    } catch (e) {
      setMessages((prev) => [...prev, {
        id: (Date.now() + 2).toString(),
        role: "assistant",
        content: "Sorry, I encountered an error. Please try again.",
        timestamp: new Date(),
      }]);
    } finally {
      setIsLoading(false);
    }
  };

  // Render your message list and input here
  return <div>
    {/* Message list */}
    <div ref={messagesEndRef} />
  </div>;
}

Why Tool-Calling Changes the UX (and Programming)

Natural interaction: Users ask for outcomes, not functions. "Top 10 customers by spend" beats "Click Reports → Pivot...".
Better error handling: Instead of 400 Bad Request, the agent explains what went wrong and suggests fixes.
Fewer edge-case branches: Devs define tools and constraints; the agent orchestrates logic paths on the fly.
Maintainability: Add or swap tools without rewriting flows.
Safer by design: Validation happens before computation; the agent refuses to guess.

What’s Next

Add group-by and filter tools, and a simple plotting tool for trends.
Stream results and clarifying questions.
Integrate with WhatsApp (hello, farmbetter -)), Slack, or internal dashboards.
Keep the UI simple - let the agent handle the complexity.

Wrapping Up

We’re moving from "write all the if-else" to "define good tools, then let agents orchestrate." Users win with clearer answers and fewer roadblocks. Developers win with cleaner boundaries and reusable logic.

How might agentic AI simplify your next product? Try the demo, peek at the code, and tell me what you build next!

Weekly Coding Challenge #2: Generating Parentheses with Backtracking and Recursion

Brian Baliach — Thu, 14 Aug 2025 09:40:57 +0000

I’m continuing the weekly challenge series, and this time we’re tackling a foundational favorite: Generate Parentheses. The goal is to produce all well-formed strings of parentheses for a given n pairs of parenthesis, and it’s a perfect showcase for two core ideas in algorithm design: backtracking and recursion. I’ll walk through the problem, explain why these techniques fit, and then break down the TypeScript implementation line by line.

Problem Overview

Here’s the problem statement:

You are given an integer n. Return all well-formed parentheses strings that you can generate with n pairs of parentheses.

You can also find a detailed problem statement here:
https://neetcode.io/problems/generate-parentheses?list=neetcode150

Also, here's my public GitHub repo that has all these coding solutions implemented:
https://github.com/TylerMutai/coding-challenges-solutions/tree/main/ts-coding-challenges-solutions

The task is to enumerate every valid combination, ensuring each string is balanced (every opening parenthesis has a matching closing one, and order is correct).

1. Understanding Backtracking and Recursion

Before diving into code, let’s clarify the two techniques driving the solution.

Backtracking is a systematic way to explore all possible configurations by making a sequence of choices, recursing deeper when a choice looks promising, and undoing it (“backtracking”) when it doesn’t. It shines when we need to generate combinations under constraints, which is exactly our situation.

Recursion is a function calling itself with smaller subproblems. Here, it naturally models "build the string one character at a time", carrying the current state along (how many open/closed parenthesis we’ve used) until we reach a complete, valid result. Together, recursion provides the structure of exploration, and backtracking provides the discipline to try, revert, and try again.

2. TypeScript Solution

Let’s look at the core implementation:

/**
 * You are given an integer n.
 * Return all well-formed parentheses strings that you can generate with n pairs of parentheses.
 */

const generateParenthesis = (n: number) => {

  const result: string[] = [];
  const stack: string[] = [];

  const backtrack = (openN: number, closeN: number) => {
    if (openN === closeN && openN === n && closeN === n) {
      result.push(stack.join(""));
    }

    if (openN < n) {
      stack.push("(");
      backtrack(openN + 1, closeN);
      stack.pop();
    }

    if (closeN < openN) {
      stack.push(")");
      backtrack(openN, closeN + 1);
      stack.pop();
    }
  };

  backtrack(0, 0);
  return result;
};

console.log(generateParenthesis(3));

3. Step-By-Step Explanation

Let’s unpack the key decisions and constraints inside the algorithm.

a) State and Constraints

We track two counters:

openN: how many "(" we’ve used so far.
closeN: how many ")" we’ve used so far.

The constraints that keep the string valid:

We can’t use more than n opening parentheses:

  if (openN < n) { ... }

We can only close if we have an unmatched "(" available, which basically means we can't use a closing parenthesis if the currently open parenthesis are less than the closing parenthesis:

  if (closeN < openN) { ... }

These checks prevent invalid prefixes from ever forming.

b) The Backtracking Function

const backtrack = (openN: number, closeN: number) => { ... }

This function builds strings incrementally using a stack (array of characters) as our current path. At each call:

If we’ve placed n open parentheses and n closed parentheses, we have a complete, valid string and add it to our results array:

  if (openN === closeN && openN === n && closeN === n) {
    result.push(stack.join(""));
  }

Otherwise, we branch by choosing a "(" if allowed, or a ")" if it keeps the string valid. After exploring a branch, we pop to revert the choice and try the next option: this is the essence of backtracking.

c) Choosing "("

if (openN < n) {
  stack.push("(");
  backtrack(openN + 1, closeN);
  stack.pop();
}

We can always add another "(" as long as we haven’t used n of them. Push, explore deeper, then undo.

d) Choosing ")"

if (closeN < openN) {
  stack.push(")");
  backtrack(openN, closeN + 1);
  stack.pop();
}

We only add ")" if there are more opens than closed so far. This preserves balance at every prefix.

e) Building Results

The recursion starts at:

backtrack(0, 0);

The result array accumulates every well-formed string. Because we never create invalid prefixes, we don’t need to filter later. Every terminal path is valid by construction.

4. Example

Given this input:

generateParenthesis(3);

A valid output is:

[
  "((()))",
  "(()())",
  "(())()",
  "()(())",
  "()()()"
]

All strings are balanced, and every unique combination is present.

Conclusion

By combining recursion’s natural tree structure with backtracking’s disciplined choice-and-revert strategy, we can generate all well-formed parentheses efficiently. The constraints (limit opens to n, never let closed exceed opens) ensure correctness without post-processing. It’s a clean and scalable pattern you’ll reuse across many combinatorial problems.

If you have questions or ideas for variations (like adding brackets or braces), drop a comment below.
See you in next week’s challenge!

Weekly Coding Challenge #1: Solving Subsets II with Backtracking

Brian Baliach — Thu, 24 Jul 2025 11:24:09 +0000

I've decided to do a new blog series where I’ll be sharing coding challenges I’ve solved each week. For our first entry, I’ll walk through the classic Subsets II problem, which involves returning all possible unique subsets in an integer array that may contain duplicates, demonstrating how to approach it, step by step, using one of the most fundamental algorithmic techniques: backtracking.

Problem Overview

Here’s the problem statement:

You are given an array nums of integers, which may contain duplicates. Return all possible subsets.

The solution must not contain duplicate subsets. You may return the solution in any order.

You can also find a more detailed problem statement here.

The goal is to produce every possible subset from the input array, while ensuring that no duplicate subsets are included in the output. This is a common scenario when dealing with arrays that can have repeated elements.

1. Understanding Backtracking

Before diving into the implementation, it’s important to clarify what backtracking is and why it fits this problem.

Backtracking is an algorithmic approach often used for searching through all possible decisions in a sequence, systematically exploring all configurations and undoing ('backtracking') steps as necessary. It’s particularly effective for generating all possible combinations or permutations.

In the context of Subsets II, backtracking enables us to explore every possible way to build a subset, one element at a time, and carefully manage the inclusion of duplicates.

2. TypeScript Solution

Let’s look at the core implementation:

/**
 * Given an integer array nums that may contain duplicates, return all possible subsets (the power set).
 * The solution set must not contain duplicate subsets. Return the solution in any order.
 */

const subsetsWithDup = (nums: number[]) => {

  const backtrack = (start: number, subset: number[], nums: number[], res: number[][]) => {
    res.push([...subset]);
    for (let i = start; i < nums.length; i++) {
      // Skip duplicates
      if (i > start && nums[i] === nums[i - 1]) {
        continue;
      }
      subset.push(nums[i]);
      backtrack(i + 1, subset, nums, res);
      subset.pop();
    }
  };

  const res: number[][] = [];
  nums.sort((a: number, b: number) => a - b);
  backtrack(0, [], nums, res);
  return res;
};

console.log(subsetsWithDup([1, 2, 2]));

3. Step-By-Step Explanation

Let’s break down the solution, focusing on each step and decision.

a) Sorting the Input

nums.sort((a: number, b: number) => a - b);

The array is sorted first. This is essential for detecting duplicates efficiently. If duplicate numbers are adjacent, it’s much easier to skip them during subset generation.

b) The Backtracking Function

const backtrack = (start: number, subset: number[], nums: number[], res: number[][]) => { ... }

This function explores all possible subset combinations from a given start index in nums. Here’s what happens inside:

Add Current Subset: At each stage, add a copy of the current subset to the result list:

  res.push([...subset]);

Iterate From Start Index:

For each possible next element (starting from the current index), we consider two options: include or skip.
Skip Duplicates:

The key line that avoids duplicate subsets:

  if (i > start && nums[i] === nums[i - 1]) {
    continue;
  }

This ensures that, from the same decision point, we don’t select the same value twice.

Include Element, Explore Further: We add the current element, proceed to the next index, and then remove the element ('backtrack') for subsequent branches:

  subset.push(nums[i]);
  backtrack(i + 1, subset, nums, res);
  subset.pop();

c) Generating Results

The process starts with an empty subset and fills the res array with every unique subset generated through the backtracking process.

4. Example

Given this input:

subsetsWithDup([1, 2, 2]);

The output will be:

[
  [],
  [1],
  [1, 2],
  [1, 2, 2],
  [2],
  [2, 2]
]

Each subset is unique, and all possible combinations are present.

Conclusion

By applying backtracking and carefully managing duplicate handling using sorting and an early-skip condition, we can efficiently generate all unique subsets of an array with duplicates. This approach is both scalable and easy to implement, making it a strong fit for this class of problems.

If you have any questions, suggestions, or feedback, feel free to leave a comment.
Stay tuned for next week’s challenge!

End-to-End GraphQL File Uploads with Apollo Server and Apollo Client: A Comprehensive Guide

Brian Baliach — Tue, 22 Jul 2025 11:34:47 +0000

We recently started partnering (where I currently work) with some of our customers to co-create content, and as a result we needed a way to stream files from the client to the server, through GraphQL. This added an extra layer of complexity, which took us some time to effectively hash-out, and hence the inspiration for this blog.

In this blog, I'll be walking you through (with code snippets included) how to enhance your GraphQL set up, to allow for file uploads. I intend this tutorial to be an in-depth one, that goes full circle starting with the server set up, and implementation (using Apollo Server), and going all the way to the client set up and implementation (using Apollo Client).
The tech-stack specifications for the client will be Apollo client (and I'll try and generalize the config as much as possible since there's a gazillion javascript frontend frameworks and I can't possibly touch on all of them. There'll be probably another new javascript frontend framework by the time you are reading this lol).
For the server, the set-up is mostly inclined towards NestJS, but can be co-adopted to other frameworks as well.

1. Spinning Up the Backend: Dependencies & Configuration

So for starters, create a nestjs project (if you don't have one already). You can skip this step if you have your own set-up that isn't nestjs-related.

nest new project-name

Secondly, install necessary dependencies (I'm using TypeScript, which should - at the risk of breaking the one forbidden software rule of having an opinion - be your default at this point. If you are writing server-side code without static types, then you must be the one-true master, and I'd love to learn your ways). Skip the nestjs apollo dependencies if you have a different backend set up:

npm i @nestjs/graphql @nestjs/apollo @apollo/server@^4.11.2 graphql graphql-upload-ts

Next, we need to configure our graphql set-up.

For the nestjs category:

Open app.module.ts and make sure your graphql config matches mine (especially since v10 of Apollo Server removed it's built-in upload handler):

// ...other imports
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';
// ...other imports
GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  playground: false, // Let's get fancy with an alternative playground.
  plugins: [
    ApolloServerPluginLandingPageLocalDefault({
      embed: true,
    }),
  ],
  uploads: false, // Disable Apollo’s default upload handling if on NestJS 9+ (and Apollo Server version 10 and above).
  autoSchemaFile: 'src/schema.gql', // Adjust if your path differs!
  sortSchema: true,
  introspection: true,
  context: ({ req, res }) => ({ req, res }),
})
// ...other imports

Then configure the graphqlUploadExpress middleware within the same app.module.ts file:

export class GraphQLAppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(
      // apply the upload middleware, setting reasonable defaults.
        graphqlUploadExpress({
          maxFieldSize:100 * 1024 * 1024, // 100MB
          maxFileSize: 100 * 1024 * 1024, // 100MB
          maxFiles: 10, // 10 files per request
        })
      )
      .forRoutes('graphql');
  }
}

for the bare-metal express server category:

const express = require('express');
const expressGraphql = require('express-graphql');
const { graphqlUploadExpress } = require('graphql-upload-ts');

express()
  .use(
    '/graphql',
    // apply the upload middleware, setting reasonable defaults.
    graphqlUploadExpress({
      maxFieldSize:100 * 1024 * 1024, // 100MB
      maxFileSize: 100 * 1024 * 1024, // 100MB
      maxFiles: 10, // 10 files per request
    }),
    // Replace with your schema path
    expressGraphql({ schema: require('./schema.gql') })
  )
  .listen(3000);

2. Server Models, DTOs, & Resolvers: Building Your Upload Endpoint

Next, we'll define our model, which we'll call BigFileDataModel.
For nestjs users, I'm using the code-first approach. For the rest of the readers, I'll also include a snippet of the resulting schema to include in your schema files.

The typescript definition:

import { Field, InputType } from '@nestjs/graphql';
import { FileUpload, GraphQLUpload } from 'graphql-upload-ts';
import { IsIn, IsNotEmpty } from 'class-validator';

@InputType()
export class BigFileDataModel {
  @Field()
  @IsNotEmpty()
  @IsIn(['mp4', 'mov', 'avi', 'mkv', 'webp', 'jpeg', 'jpg', 'png'])
  fileType: string;

  @Field(() => GraphQLUpload)
  contents: Promise<FileUpload>;
}

The equivalent schema:

"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}

Our BigFileDataModel has a file type and contents. The fileType is the file extension (so .png, .jpg and so on), and the contents is the binary file itself.

A quick thing to note: Make sure the data types match the typescript example if you are using schema-first approach, specifically the contents (which will be the file being streamed), which returns a promise when all the file bytes have finished transmitting.

Request & Response DTOs

Next, we'll create our DTOs that will be used by a resolver (which we'll create in a future step).
The DTOs will be basically a request and response DTO (Data Transfer Object).
For nestjs readers using the code-first approach, here's the TypeScript definitions.

Our Request DTO:
Request DTO:

import { ArgsType, Field } from '@nestjs/graphql';

@ArgsType()
export class UploadFileRequest {
  @Field(() => BigFileDataModel)
  file: BigFileDataModel;
}

Response DTO:

import { Field, ObjectType } from '@nestjs/graphql';

@ObjectType()
export class _UploadFileResponse {
  @Field({ nullable: true })
  file: string;
}

// Use your preferred base response structure, here I'm assuming inheritance/mixins:
@ObjectType()
export class UploadFileResponse extends StandardGraphQLResponse(_UploadFileResponse) {}

For our schema-first readers, here's the equivalent schema:

"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}

"""The section above has been included from a previous step for consistency """

type UploadFileResponse {
  file: String!
}

type Mutation {
  uploadFile(file: BigFileDataModel!): UploadFileResponse!
}

The request DTO basically takes an argument file which specifies the file properties we are sending from the client.

Our Resolver and FileUploadService class

At this point I don't think I need a 'nestjs code-first approach users' and 'schema-first users'. I assume you'll be smart enough to deduce which code snippet is for you moving forward.

Our typescript resolver (feel free to adapt this without the annotations to your resolver definition):

import { Resolver, Mutation, Args } from '@nestjs/graphql';

@Resolver('FileUploadResolver')
export class FileUploadResolver {
  constructor(private readonly fileUploadService: FileUploadService) {}

  @Mutation(() => UploadFileResponse)
  async uploadFile(@Args() req: UploadFileRequest) {
    const res = await this.fileUploadService.uploadToFirebase({
      file: req.file.contents,
      fileType: req.file.fileType,
    });
    return { file: res };
  }
}

The resolver basically calls our file upload service (which uploads the binary file to Google Storage, and returns a string representing the public url).

Here's the definition of our FileUploadService.ts, which you can feel free to re-use in your personal services requiring file upload.

import { Injectable } from '@nestjs/common';
import { Readable } from 'stream';
import { FileUpload } from 'graphql-upload-ts';

@Injectable()
export class FileUploadService {
  constructor(private readonly folderName: string) {}

  async uploadToFirebase({
    file,
    fileType,
  }: {
    file: Promise<FileUpload>;
    fileType?: string;
  }): Promise<string> {
    const buffer = await this.streamToBuffer((await file).createReadStream());
    const _fileName = `${Date.now()}-${Math.round(Math.random() * 1e9)}.${fileType}`;

    // Check the definition for this method below
    return await this.saveFileToStorage(this.folderName, _fileName, buffer);
  }

  private async streamToBuffer(readableStream: Readable): Promise<Buffer> {
    return new Promise((resolve, reject) => {
      const chunks: Buffer[] = [];
      readableStream.on('data', (data) => {
        if (typeof data === 'string') {
          chunks.push(Buffer.from(data, 'utf-8'));
        } else {
          chunks.push(data);
        }
      });
      readableStream.on('end', () => resolve(Buffer.concat(chunks)));
      readableStream.on('error', reject);
    });
  }

  // Stub: wire this up to your favorite storage backend
  private async saveFileToStorage(folder: string, fileName: string, buffer: Buffer): Promise<string> {
    // Implementation left as an exercise for the reader. Feel free to user Google storage/S3/local-fs or your own implementation for this.
    return `https://storage.example.com/${folder}/${fileName}`;
  }
}

There you have it - we have our server set up and ready to receive graphql file uploads. You can stop here if you're a just-backend engineer and hate anything to do with HTML/CSS/JavaScript.

For our full-stack engineers (yes, you rank higher than the just-backend engineers) who also want to set up a client, read on.

3. Client-Side Wizardry: Uploading Files with Apollo Client

Let's face it: JavaScript frontend frameworks multiply like rabbits. As a result, I'll try my best to keep the client implementation as framework-agnostic as possible. I'll use Apollo Client as an agnostic toolkit (since it's a separate implementation that does not depend on any frameworks, and is in the blog title).

Install necessary dependencies:

npm install @apollo/client apollo-upload-client

Setup Apollo Client Setup (with Upload)

Set up your Apollo Client (which you can use in your ApolloProvider in the case of Next.js. For other frameworks, you're on your own here):

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createUploadLink } from 'apollo-upload-client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createUploadLink({
  uri: 'http://localhost:4000/graphql', // Plug in your server URL!
});

const headersLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    'Apollo-Require-Preflight': 'true', // Enable CORS for file uploads
  },
}));

const apolloClient = new ApolloClient({
  cache: new InMemoryCache(),
  link: headersLink.concat(httpLink),
  ssrMode: typeof window === 'undefined', // Server-side support, if needed
});

export default apolloClient;

In the example above, we create two links: one for injecting headers, and the other, a http terminating link for file upload, provided by the apollo-upload-client package.
Then we include the 'Apollo-Require-Preflight': 'true' header, which is needed for enabling cors. This is outside the scope of this tutorial, but if you'd like to find out more, you can here;

The GraphQL Mutation

mutation uploadFile($file: BigFileDataModel!) {
  uploadFile(file: $file) {
    file
  }
}

File Input and Upload Logic

Here’s a barebones React-flavored file uploader. You can adapt this for your front-end framework of choice.

import { useMutation } from '@apollo/client';
const MUTATION = /* see mutation above */;

function UploadFile() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="file"
      required
      onChange={({
        target: {
          validity,
          files: [file],
        },
      }) => {
        if (validity.valid)
          mutate({
            variables: {
              file,
            },
          });
      }}
    />
  );
}

I hope the code snippets above are self-explanatory (considering this is applicable to all frontend frameworks). If you run into any issues, always feel free to tag me in the comment section, and I'll respond as soon as I can!

Wrapping Up...

You should now have a working, end-to-end GraphQL file upload system, complete with server, DTOs, middleware, resolvers, upload streaming, Apollo Client, and a front-end implementation.
If there's a framework or storage backend I missed, or you have a better implementation, drop your thoughts in the comments!
Until next time, happy hacking!

Integrating Model Context Protocol with Gemini: The Definitive Guide to Modern Tool Calling (Agentic-AI)

Brian Baliach — Sat, 19 Jul 2025 19:54:38 +0000

When it comes to tool-calling and agentic AI, the internet seems awash with tutorials for Anthropic’s Claude or the latest from OpenAI’s GPTs. But what if you want to ride the (less-documented) Gemini wave? If you’ve searched far and wide for a comprehensive guide on integrating the Model Context Protocol (MCP), Gemini, and modern tool schemas, only to find sparse blog posts tailored for other ecosystems, you’re not alone.

This tutorial fills that void, focusing on practical integration of Gemini and Model Context Protocol, from both server and client perspectives. We’ll draw on Node.js with TypeScript, @google/genai for Gemini and schema definition, and @modelcontextprotocol/sdk as our primary toolkit. By the end, you should be able registering tools server-side, and activate them client-side, all via MCP.

You can find the original blog post here..

But before diving into code, let’s clarify a crucial foundation: what is Model Context Protocol?
MCP is an emerging open protocol standard for AI tool-calling, defining how AI models (clients) can discover and call arbitrary server-side tools, in a language and vendor-agnostic way (basically not dependent on the language used to develop server-side tools, or the AI model vendor). Think of it as the universal handshake between advanced AI clients and your server’s unique APIs or business logic. By using MCP, you unlock true interoperability: write a tool once, and access it from any AI that speaks the protocol.

Ready? Let’s dive in!

Setting Up Your AI Tooling Playground

Before we start, we need the 'ol 'getting started boilerplate'. This phase is all about laying down some groundwork, and covers initializing a project and installing the bare-metal essentials.

Step 1: Initialize Your Node.js Project

Crack open a terminal and create a fresh directory:

mkdir gemini-mcp-tutorial && cd gemini-mcp-tutorial
npm init -y

Step 2: Install Required Dependencies

You’ll need just four core libraries:

@google/genai: Official Google AI SDK (includes gemini, and other handy features like schema definitions for tool-calling).
@modelcontextprotocol/sdk: The heart of MCP communication (both server and client).
(Optionally) google-libphonenumber, if you want to parse phone numbers as we will in our example tool.

Install them in a single swing:

npm install @google/genai @modelcontextprotocol/sdk google-libphonenumber

If you’re using TypeScript (recommended), also install typing essentials:

npm install -D typescript ts-node @types/node

And, as with any journey, don’t forget to wire up your favorite Node.js (tsconfig.json and so forth).

Defining MCP Servers and Tools

With dependencies squared away, let’s architect both the server (which hosts our tools) and the client (which acts as a Gemini-empowered AI agent that calls them).

(A) Creating an MCP Server

Your MCP server will describe its tools and listen for tool-calling requests from clients. Let’s work from the skeleton up.

Start by defining the MCP server itself:

// src/mcp/server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const mcpServer = new McpServer({
  name: 'music-guys-mcp',
  version: '1.0.0',
  capabilities: {
    resources: {},
    tools: {},
  },
});

export default mcpServer;

Next, you’ll want to actually run this server and choose how it listens for requests. Here, we’ll use a simple stdio (Standard Input/Output) transport, which works beautifully for testing and local development:

// src/mcp/serverMain.ts
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import mcpServer from './server';

export const createServer = async () => {
  const transport = new StdioServerTransport();
  await mcpServer.connect(transport);
  console.info('MCP Server running on stdio');
};

createServer().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});

Just like that, you’ve spun up an MCP-compliant tool server, ready for calls.

(B) Defining and Registering a Tool

Let’s register a real tool. Here’s a genuinely practical example: a tool that fetches user details by phone number. (We’ve stripped out some internal details, but you’re welcome to adapt as needed.)

// src/mcp/tools/getUser.ts
import mcpServer from '../server';
import { PhoneNumberUtil } from 'google-libphonenumber';

mcpServer.tool(
  'get-user-details',
  "Returns user details according to their phone number, or 'undefined' if user doesn't exist.",
  {
    phoneNumber: {
      type: 'string',
      description: "'User phone number including country code as registered.',"
      required: true,
    },
  },
  async (args) => {
    const phoneNumber = args.phoneNumber;
    try {
      let formattedPhone = phoneNumber.startsWith('+')
        ? phoneNumber
        : `+${phoneNumber}`;
      const phoneUtil = PhoneNumberUtil.getInstance();
      const parsedNum = phoneUtil.parse(formattedPhone);

      // Here you'll implement your user lookup logic (e.g., using your database)
      // const user = ...;

      // For demonstration:
      if (parsedNum.getNationalNumber() === 1234567890) {
        // Mocked user:
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                id: 'user-id',
                name: 'Jane Doe',
                phone: formattedPhone,
              }),
            },
          ],
        };
      }
      return {
        content: [
          {
            type: 'text',
            text: 'User not found',
          },
        ],
      };
    } catch (e) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to parse phone number: ${phoneNumber}: ${e}`,
          },
        ],
      };
    }
  }
);

And wire up your tool handler so it loads when the server starts (add this to the serverMain.ts file we've just defined above):

// src/mcp/serverMain.ts (add at the top)
import './tools/getUser';

Now, run your server with ts-node src/mcp/serverMain.ts, and it will listen for tool calls from any MCP-compatible client!

Implementing the MCP Client

At this point, we're half-way there. In this section, I'll walk you through on how to connect Gemini (or any MCP-aware model) to your server.

(A) MCP Client Bootstrap

First, let’s lay down the scaffolding for establishing the connection to the server (and to Gemini itself):

// src/mcp/client.ts
import { Client, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { GoogleGenAI } from '@google/genai';

export class MCPClient {
  private mcp: Client;
  private googleGenAI: GoogleGenAI;
  private tools: any[] = [];
  private transport: StdioClientTransport | null = null;

  constructor(apiKey: string) {
    this.googleGenAI = new GoogleGenAI({ apiKey });
    this.mcp = new Client({
      name: 'music-guys-mcp-client-cli',
      version: '1.0.0',
    });
  }

  // Connect through stdio to our running mcp server.
  async connectToServer(serverScriptPath: string) {
    const command = process.execPath;
    this.transport = new StdioClientTransport({
      command,
      args: [serverScriptPath],
    });
    await this.mcp.connect(this.transport);

    // Fetch available tools
    const toolsResult = await this.mcp.listTools();
    this.tools = toolsResult.tools.map(tool => ({
      functionDeclarations: [{
        name: tool.name,
        description: tool.description,
        parameters: tool.inputSchema,
      }],
    }));
    console.log('Available tools:', this.tools.map(t => t.functionDeclarations[0].name));
  }

  // Called via our chat loop, and is the main function that interfaces between tools and the Gemini model.
  async processQuery(query: string) {
    const response = await this.googleGenAI.models.generateContent({
      model: 'gemini-2.5-pro',
      contents: [
        {role: 'user', parts: [{text: query}]},
      ],
      // We've defined the list of tools that we have available and sent them as part of the request.
      config: {tools: this.tools, maxOutputTokens: 1024},
    });

    // Handle and display response, including any tool calls (see full method below for more)
    response.candidates?.forEach(cand =>
      cand.content?.parts?.forEach( async part => {
        const toolName = part.functionCall.name;
        const toolArgs = part.functionCall.args as
          | { [x: string]: unknown }
          | undefined;
        console.log('toolName', toolName);
        console.log('toolArgs: ', toolArgs);

        const tool = serverTools[toolName];
        if (tool) {
          const result = await tool.callback(toolArgs || {});

          contents.push({
            role: 'model',
            parts: [{text: (result.content as any)?.[0]?.text}],
          });

          if ((result.content as any)?.[0]?.text) {
            finalText.push((result.content as any)?.[0]?.text);
          }

          // call LLM to also get additional responses.
          const response = await this.googleGenAI.models.generateContent({
            model: this.modelName,
            contents: contents,
            config: {tools: this.tools, maxOutputTokens: 1024},
          });

          for (const candidate of response.candidates || []) {
            const content = candidate.content;
            for (const part of content?.parts || []) {
              if (part.text) {
                finalText.push(part.text);
              }
            }
          }
        }
      }));
  }
}

What is processQuery Doing?

This function is the heart of the Gemini+MCP client:

It orchestrates a conversation between the user, the Gemini model, and your set of tools (accessible via the Model Context Protocol).

The function does several key things:
TLDR;

Submits a user query to Gemini (with a list of available tools).
Inspects Gemini’s response to determine if a tool function needs to be called.
Invokes local/server tools when Gemini requests it (via a functionCall).
Feeds the tool results back into Gemini for a more complete or grounded answer.
Displays the final answer(s) to the user.

Here's a step by step breakdown for a clearer understanding

Sending the User Query to Gemini

const response = await this.googleGenAI.models.generateContent({
  model: 'gemini-2.5-pro',
  contents: [
    {role: 'user', parts: [{text: query}]},
  ],
  config: {tools: this.tools, maxOutputTokens: 1024},
});

What’s happening here? You’re sending the user's question to Gemini’s generateContent() API.
Why the tools in config? This tells Gemini, “Hey, here are the functions (‘tools’) I can call if you need them.”
What does this let Gemini do? Gemini can, instead of answering directly, choose to call one of your tools if it thinks that’s appropriate (e.g. “get-user-details”).

Handling the Gemini Response (Including Tool Calls)

response.candidates?.forEach(cand =>
  cand.content?.parts?.forEach( async part => {
    ...
  })
);

What’s happening here? Gemini may return several “candidates” (possible responses). Each candidate has “parts” which are chunks of its response, which could be text, images, or function calls.
Why multiple loops? To handle all possible parts of all possible responses.

Detecting Function Calls (Tool Requests)

const toolName = part.functionCall.name;
const toolArgs = part.functionCall.args as { [x: string]: unknown } | undefined;

What’s happening here? If Gemini thinks the answer requires calling a tool, it will return a functionCall instead of just text.
toolName/toolArgs: These are the name and arguments for the requested tool.

Calling the Local/Server Tool with Those Arguments

const tool = serverTools[toolName];
if (tool) {
  const result = await tool.callback(toolArgs || {});

What’s happening here? You look up (from your list of registered server tools) the one Gemini wants to call.
- If it exists, you run it, passing the parsed arguments.
This is where your server, database, or API logic runs.

Feeding the Tool Result Back to Gemini

contents.push({
  role: 'model',
  parts: [{text: (result.content as any)?.[0]?.text}],
});

What’s happening here? After getting the tool’s output, you add it to the contents. This simulates Gemini’s internal dialogue and gives it the additional “real” data it just requested.

Asking Gemini for a Final Answer (Now Informed by the Tool Output)

const response = await this.googleGenAI.models.generateContent({
  model: this.modelName,
  contents: contents,
  config: {tools: this.tools, maxOutputTokens: 1024},
});

What’s happening here? Now that Gemini has the tool output, you ask for another response. Gemini can now integrate that tool data and produce a final, well-informed answer.

Output the Final Result(s)

for (const candidate of response.candidates || []) {
  const content = candidate.content;
  for (const part of content?.parts || []) {
    if (part.text) {
      finalText.push(part.text);
    }
  }
}

What’s happening here? Finally, you extract and print/return all the textual answers Gemini crafts after seeing the real data from your tool.

Why This Structure?

Two calls to Gemini: First, to see if a tool call is requested; second, to let Gemini integrate the tool output into its answer.
MCP Tool Calling: The magic of MCP+Gemini is this “AI calls your tools, you execute, and AI incorporates the result into its reasoning.”

(B) Running the Client Loop

Welcome to the interactive part. The chatLoop lets you query our Gemini model, who'll make the administrative decision on whether to call your MCP server’s tool as needed.

// src/mcp/runClient.ts
import { MCPClient } from './client';
// Ensure you have your Google API key ready
const API_KEY = process.env.GEMINI_API_KEY;

async function main() {
  const mcpClient = new MCPClient(API_KEY);
  await mcpClient.connectToServer(__dirname + '/serverMain.js');
  // Minimal chat/question loop
  process.stdin.setEncoding('utf-8');
  process.stdout.write("Ask your query or type 'quit':\n");

  process.stdin.on('data', async (input) => {
    const query = input.trim();
    if (query.toLowerCase() === 'quit') {
      process.exit(0);
    }
    await mcpClient.processQuery(query);
    process.stdout.write("\nAsk next query or 'quit':\n");
  });
}
main();

Now, simply run your client (ts-node src/mcp/runClient.ts), type in a phone number, or ask it to give you your details (as the get-user-details tool expects), and watch as Gemini seamlessly calls your custom tool!

Wrapping Up: What We’ve Built and Where You Can Go Next

Congratulations! You’ve now experienced end-to-end Model Context Protocol integration tailored to Gemini, spanning both a tool-hosting server and a tool-calling client.
Feel free to expand your tool arsenal by adding more business logic and tool endpoints (CRUD ops, APIs, complex workflows).
Have thoughts, questions, or wild new use cases? Drop a comment or issue below!
Happy contextual hacking!

Permit IO Auth Challenge: Document and Team Management API with Fine-Grained Access Control

Brian Baliach — Wed, 30 Apr 2025 09:07:46 +0000

This is a submission for the Permit.io Authorization Challenge: API-First Authorization Reimagined

What I Built

I built a Document and Team Management API using NestJS that elegantly implements API-first authorization using Permit.io. This application goes beyond basic CRUD operations by demonstrating real-world access control scenarios for documents (viewing, editing, owning) and teams (viewing, creating, managing members). The core problem it solves is providing a secure and flexible way to manage access to sensitive resources in a multi-user environment, where permissions are not hardcoded but dynamically enforced based on external policies and attributes managed by Permit.io. This allows for a more scalable, auditable, and maintainable authorization system.

Demo

While a live deployment isn't currently available for this challenge submission, I have created a comprehensive Postman collection (permit.io.postman_collection.json in the project repository) that demonstrates the functionality of all API endpoints and the enforced authorization rules. Additionally, the detailed API documentation in the README provides clear request/response examples showcasing the different access control scenarios.

Login as an admin

Login as an editor

Login as a viewer

Get all documents (allowed access)

ABAC - Get specific document (allowed access)

ABAC - Get specific document (disallowed access)

RBAC - Create team (allowed access)

RBAC - Create team (disallowed access)

Project Repo

https://github.com/TylerMutai/permit.io-auth-challenge

Be sure to check out the README.md file in the repository for detailed installation instructions, environment variable setup, architectural overview, a comprehensive guide to implementing RBAC and ABAC using permit.io and a description of the API endpoints and their authorization mechanisms.

My Journey

My journey involved several key steps:

Understanding the Challenge and Permit.io: I first thoroughly reviewed the challenge requirements and the Permit.io documentation, focusing on API-first authorization principles. Considering I wanted to also implement Attribute-Bases Access Control, I had to recognize the capabilities of both the Cloud and Container PDP, which pushed me to opt for the Container PDP route since the Cloud PDP doesn't yet support ABAC.
Choosing the Domain: I selected document and team management as a practical domain with clear authorization needs. Documents can have different access levels (inspired by how Google Docs works): view, edit and ownership, which was a perfect attack vector for showcasing ABAC, and teams which would help showcase traditional Role-Based Access Control.
Setting up the NestJS API: I scaffolded a NestJS application, implementing user authentication, which involved setting up necessary mechanisms for securing endpoints and obtaining the logged-in user, and designed the API endpoints for documents and teams, focusing on clear REST conventions.
Integrating Permit.io: This was the core of the challenge. I implemented the Permit.io client within the NestJS application to communicate with the PDP. I focused on:
- Resource and Action Definitions: Defining the resource types (document, team) and the actions that can be performed on them (view, create, update, delete, readone).
- Attribute Handling: Implementing logic to fetch relevant user and resource attributes to be passed to Permit.io for ABAC. For example, implementing role-based access for certain document endpoints, and all teams endpoints, and attribute-based access for fetching a single document. This also involved implementing helper guards and decorators (in cases for permissions and authorization) that allowed me to easily obtain the logged-in user object and do permission validation and access control in a maintainable and re-usable way.
- Authorization Checks: Integrating Permit.io's check function within my API endpoint controllers to verify if the authenticated user has the required permission for the requested action on the specific resource.
- Error Handling: Ensuring that all responses are standardized (by using http exception filters), even when errors are thrown.
Implementing Attribute-Based Access Control (ABAC): I specifically chose to use the Container PDP to demonstrate ABAC (again, since the cloud PDP doesn't support this). This involved an additional challenge (which I really didn't mind), of deploying their docker container onto cloud run. This journey helped me learn additional concepts on how cloud run works (and min-max instances importance, and what and OPA is -)). This also involved thinking about how attributes of users (e.g., roles), resources (e.g., documents and teams), and the relationships between them could influence authorization decisions defined in Permit.io policies.
Documentation: Throughout the development process, I prioritized clear and comprehensive documentation in the README. This included setup instructions, environment variable explanations, the architectural overview of the API, a comprehensive guide to implementing RBAC and ABAC using permit.io, and detailed API endpoint descriptions with request/response examples.

Challenges and Overcoming Them:

Deploying the Container PDP: Initially, grasping the nuances of setting up and querying the Container PDP required in-depth digging into the permit.io documentation on how to do this. Considering that I was also deploying this to Google Cloud (using Cloud Run), this involved looking up more documentation on defining ports correctly, environment variables etc. I was then eventually able to deploy the Container PDP to cloud run.
Understanding ABAC: Initially, grasping the nuances of setting up and querying ABAC required careful review of the Permit.io documentation. I spent time understanding how to structure attributes and policies on the permit.io dashboard, how to sync users (and what their unique identifier is), and lastly, I had to experiment (and comb the documentation) on how to pass attributes as request parameters onto permit.io.
Designing Meaningful Policies: Crafting Permit.io policies that accurately reflected the desired access control logic for documents and teams required some iteration. I focused on creating policies that were both functional and easy to understand.
Integrating Permit.io Client: Ensuring the Permit.io client was correctly initialized and used within the NestJS controllers to perform authorization checks required careful attention to the SDK documentation and examples. I also preferred deploying the permit.io pdp on Cloud Run, which involved combing in deeper into the documentation to further understand how to set up the client (part of the SDK) to point to the correct PDP url.

What I Learned:

The power and elegance of externalized authorization using tools like Permit.io. It significantly decouples authorization logic from the core application, making it more maintainable and scalable. I didn't have to implement RBAC logic in code, hard-code new permissions in my codebase (which really saved on time, allowing me to focus on logic, and also new deployments everytime a new feature, hence a new permission, is introduced!), and therefore iterations were instant, rather than having to wait for a new deployment to have the changes effected (similar to how feature flags work, which was quite neat-)).
The benefits of API-first thinking in designing authorization systems. By treating authorization as a fundamental aspect of the API design, it ensures security is baked in from the start.
The concepts and practical implementation of Attribute-Based Access Control (ABAC) and its potential for fine-grained access control (this was a new concept for me, which took sometime understanding, but was quite fascinating to see in action).

API-First Authorization

Permit.io was central to building an API-first authorization system in this project. Here's how it was implemented:

External Decision Point: Instead of embedding authorization logic within the NestJS application code (e.g., handling roles and permissions logic within the backend code), all authorization decisions are delegated to the external Permit.io Policy Decision Point (PDP). The API acts as a Policy Enforcement Point (PEP), querying the PDP to determine if a user is authorized to perform a specific action on a resource.
Declarative Policies: The access control rules for documents and teams are defined declaratively as policies within the Permit.io platform (or would be in a real-world scenario connected to the cloud or a configured Container PDP). These policies specify who can perform which actions on which resources, often based on roles, attributes, and relationships.
Centralized Management: Permit.io provides a centralized platform for managing and auditing authorization policies. This allows for easier updates to access control rules without requiring code changes in the API.
Abstraction of Authorization Logic: The API code remains focused on its core business logic (managing documents and teams). The complexities of authorization are abstracted away and handled by Permit.io. The API simply needs to make authorization requests and enforce the PDP's decisions.
Attribute-Based Access Control (ABAC) Implementation: By utilizing the Container PDP (since ABAC is not supported by the cloud PDP), the project demonstrates ABAC. When an API request is made, the application gathers relevant attributes of the user making the request and the resource being accessed (e.g., the user's ID, the document's owner, editor and viewer IDs). These attributes are then sent to Permit.io, which evaluates them against the defined ABAC policies to make an authorization decision. For example, I implemented a policy which stated that a user can edit a document if their ID is present in the document's editors or owners attribute.

In essence, this project treats authorization as a distinct layer that the API interacts with. The API doesn't know nor handle the specific rules and authorization logic; it only knows how to ask Permit.io (which handles the rules and auth logic) if an action is allowed. This aligns perfectly with the principles of API-first authorization, where security is handled through a dedicated and externalized system.

Mastering Facebook APIs: A Guide to Media Handling, Encryption, and Messaging

Brian Baliach — Tue, 01 Apr 2025 15:47:53 +0000

Facebook's documentation is all over the place. It's quite difficult to specifically find what you're looking for, considering they have multiple pages that seem to leapfrog one another in delightful disarray. Whether it's sending messages, assembling message components, or mastering webhook APIs, the rabbit holes are plentiful. Feel like you’re running in circles? You're not alone.

This guide aims to present a clear path through this jungle of information, focusing specifically on handling media, encryption, and integrating WhatsApp flows. The documentation you need is within one place here, so go on—breathe easy, savor those extra years you’ve gotten back. You’re welcome!

Downloading and Handling Media

There's two ways to handle media when navigating the labyrinth of Facebook APIs: under WhatsApp flows and using the webhook API. We'll start off by easing into the mystical world of the webhook API, and then gradually move towards the more complicated WhatsApp flows.

1. Downloading and Handling Media (webhook API)

This is as simple as the code snippet below.
If you'd like to explore further, here's the documentation.

protected async downloadMedia(mediaId: string) {
  const env = getEnvs();
  const headers = { Authorization: `Bearer ${this.accessToken}` };
  const mediaUrl = await lastValueFrom(this.httpService.get(`https://graph.facebook.com/${env.env.whatsappConfig.version}/${mediaId}`, { headers }));

  if (mediaUrl?.data?.['url']) {
    const response = await lastValueFrom(this.httpService.get(mediaUrl?.data?.['url'], {
      headers,
      responseType: 'arraybuffer',
    }));
    const file: Buffer = response.data;
    return Buffer.from(file).toString('base64');
  }
  return undefined;
}

This block of code directly accesses and downloads media files, transforming them into base64 format for easy handling.

2. Downloading and Handling Media (WhatsApp Flows)

Now, let's talk about handling media in WhatsApp flows. This method involves making sure the media is securely encrypted and checked for integrity. Here’s a quick overview of the process:

Download the media from the CDN using the URL provided.
Verify the media hash to confirm it hasn't been tampered with.
Validate the HMAC to further ensure the integrity of the media content.
Decrypt the media file using AES-256-CBC, and verify its hash matches the expected hash.

You first need to generate a private-public key pair as explained here.
You also need to set up the necessary callbacks as described in this documentation.

For set up, here's an example snippet that should provide you with a blueprint/framework of the process.

@Injectable()
export class WhatsappBotUtilsService extends BaseService {
  protected readonly whatsappApi: string;
  protected readonly accessToken: string;
  private readonly verificationToken: string;
  private readonly whatsappMessagingApi: string;

  constructor(
    protected readonly httpService: HttpService,
    ) {
    super();
    const { env } = getEnvs();
    this.verificationToken = env.whatsappConfig.verificationToken;
    this.accessToken = env.whatsappConfig.accessToken;
    this.whatsappApi = `https://graph.facebook.com/${env.whatsappConfig.version}/${env.whatsappConfig.phoneNumberId}`;
    this.whatsappMessagingApi = `${this.whatsappApi}/messages`;
  }

  async verify(token: string, challenge: string): Promise<string> {
    if (token === this.verificationToken) {
      return challenge;
    }
    return 'error';
  }

  public async sendMessage(message: WhatsAppOutgoingMessage, apiOpts?: {
    phoneNumberId?: string,
    accessToken?: string
  }): Promise<void> {
    if (message.to.includes('+')) {
      message.to = message.to.replace('+', '');
    }
    const { env } = getEnvs();

    const api = apiOpts?.phoneNumberId ? `https://graph.facebook.com/${env.whatsappConfig.version}/${apiOpts.phoneNumberId}/messages` : this.whatsappMessagingApi;
    console.info('api: ', api);
    console.info('API Opts: ', apiOpts);
    console.info('outgoing message: ', message);

    await firstValueFrom(
      this.httpService.post(
        api,
        message,
        {
          headers: {
            Authorization: `Bearer ${apiOpts?.accessToken || this.accessToken}`,
            'Content-Type': 'application/json',
          },
        },
      ).pipe(
        catchError((error: AxiosError) => {
          throw error;
        }),
      ),
    ).catch((error: AxiosError) => {
      console.log('error: ', error.message, error.response?.data);
    });
  }

  protected async downloadMedia(mediaId: string) {
    const env = getEnvs();
    const headers = {
      Authorization: `Bearer ${this.accessToken}`,
    };
    const mediaUrl = await lastValueFrom(this.httpService.get(`https://graph.facebook.com/${env.env.whatsappConfig.version}/${mediaId}`, { headers }));
    if (mediaUrl?.data?.['url']) {
      const response = await lastValueFrom(this.httpService.get(mediaUrl?.data?.['url'], {
        headers,
        responseType: 'arraybuffer',
      }));
      const file: Buffer = response.data;
      return Buffer.from(file).toString('base64');
    }
    return undefined;
  }

}

Lastly, for actual media encryption and decription, here's a code snippet that does all of this for you (powered by nestjs), but again, feel free to read more here.

@Injectable()
export class WhatsappFlowEncryptionService {
  private readonly appSecret;
  private readonly privateKey;
  private readonly passphrase;

  constructor(protected readonly httpService: HttpService) {
    const { env } = getEnvs();
    this.appSecret = env.whatsappConfig.secret;
    this.privateKey = env.whatsappConfig.privateKey;
    this.passphrase = env.whatsappConfig.passphrase;
  }


  public decryptRequest = (req: RawBodyRequest<Request>): WhatsAppFlowDecryptedRequest => {
    if (!this.isRequestSignatureValid(req)) {
      throw new WhatsAppFlowException('The request signature is invalid', 432);
    }
    if (!this.privateKey) {
      throw new WhatsAppFlowException('No private key defined.', 421);
    }

    const { encrypted_aes_key, encrypted_flow_data, initial_vector } = req.body;

    let decryptedAesKey = null;
    try {
      const privateKey = crypto.createPrivateKey({
        key: this.privateKey || '',
        passphrase: this.passphrase,
      });

      // decrypt AES key created by client
      decryptedAesKey = crypto.privateDecrypt(
        {
          key: privateKey,
          padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
          oaepHash: 'sha256',
        },
        Buffer.from(encrypted_aes_key, 'base64'),
      );
    } catch (error) {
      console.error('DECRYPT AES KEY ERROR:', error, '\n', '\n');
      /*
      Failed to decrypt. Please verify your private key.
      If you change your public key. You need to return HTTP status code 421 to refresh the public key on the client
      */
      throw new WhatsAppFlowException(
        'Failed to decrypt the request. Please verify your private key.',
        421,
      );
    }

    // decrypt flow data
    const flowDataBuffer = Buffer.from(encrypted_flow_data, 'base64');
    const initialVectorBuffer = Buffer.from(initial_vector, 'base64');

    const TAG_LENGTH = 16;
    const encrypted_flow_data_body = flowDataBuffer.subarray(0, -TAG_LENGTH);
    const encrypted_flow_data_tag = flowDataBuffer.subarray(-TAG_LENGTH);


    let decryptedJSONString = '{}';
    try {
      const decipher = crypto.createDecipheriv(
        'aes-128-gcm',
        decryptedAesKey,
        initialVectorBuffer,
      );
      decipher.setAuthTag(encrypted_flow_data_tag);

      decryptedJSONString = Buffer.concat([
        decipher.update(encrypted_flow_data_body),
        decipher.final(),
      ]).toString('utf-8');
    } catch (error) {
      console.error('DECRYPT AES KEY ERROR:', error, '\n');
      /*
      Failed to decrypt. Please verify your private key.
      If you change your public key. You need to return HTTP status code 421 to refresh the public key on the client
      */
      throw new WhatsAppFlowException(
        'Failed to decrypt the request. Please verify your private key.',
        421,
      );
    }

    return {
      decryptedBody: JSON.parse(decryptedJSONString),
      aesKeyBase64: decryptedAesKey.toString('base64'),
      initialVectorBase64: initialVectorBuffer.toString('base64'),
    };
  };

  public encryptResponse = (
    response: WhatsAppFlowDecryptedResponse,
  ) => {
    const { aesKeyBase64, initialVectorBase64, decryptedBody } = response;

    // flip initial vector
    const flipped_iv = [];
    for (const pair of Buffer.from(initialVectorBase64, 'base64').entries()) {
      flipped_iv.push(~pair[1]);
    }

    // encrypt response data
    const cipher = crypto.createCipheriv(
      'aes-128-gcm',
      Buffer.from(aesKeyBase64, 'base64'),
      Buffer.from(flipped_iv),
    );
    return Buffer.concat([
      cipher.update(JSON.stringify(decryptedBody), 'utf-8'),
      cipher.final(),
      cipher.getAuthTag(),
    ]).toString('base64');
  };

  public async decryptMedia(jsonPayload: WhatsAppResponseMedia) {
    const {
      cdn_url,
      encryption_metadata: {
        encrypted_hash,
        iv,
        encryption_key,
        hmac_key,
        plaintext_hash,
      },
    } = jsonPayload;

    // Step 1: Download cdn_file from cdn_url
    const response = await lastValueFrom(this.httpService.get(cdn_url, { responseType: 'arraybuffer' }));
    const cdn_file: Buffer = response.data;

    // Step 2: Make sure SHA256(cdn_file) == enc_hash
    const cdn_file_hash = crypto.createHash('sha256').update(cdn_file).digest('base64');
    if (cdn_file_hash !== encrypted_hash) {
      console.error('CDN file hash mismatch', '\n');
      throw new WhatsAppFlowException('CDN file hash mismatch', 500);
    }

    // Step 3: Validate HMAC-SHA256
    const threshold = cdn_file.length - 10;

    // since file structure = cipherText + hmac10
    const _hmac10 = Buffer.from(cdn_file);
    const hmac10 = _hmac10.subarray(threshold);

    const _cipherText = Buffer.from(cdn_file);
    const cipherText = _cipherText.subarray(0, threshold);

    // Calculate HMAC with hmac_key, initialization vector (encryption_metadata.iv) and cipherText
    const hmac = crypto.createHmac('sha256', Buffer.from(hmac_key, 'base64'));
    hmac.update(Buffer.from(iv, 'base64'));
    hmac.update(cipherText);

    const calculated_hmac = hmac.digest();

    // Make sure first 10 bytes == hmac10
    const first10Bytes = Buffer.from(calculated_hmac.subarray(0, 10)); // From the calculated hmac.

    if (Buffer.compare(hmac10, first10Bytes) !== 0) {
      console.error('HMAC validation failed', '\n');
      throw new WhatsAppFlowException('HMAC validation failed', 500);
    }

    // Step 4: Decrypt media content:

    // Run AES with CBC mode and initialization vector (encryption_metadata.iv) on cipherText
    const decipher = crypto.createDecipheriv(
      'aes-256-cbc',
      Buffer.from(encryption_key, 'base64'),
      Buffer.from(iv, 'base64'),
    );

    // Remove padding (AES256 uses blocks of 16 bytes, padding algorithm is pkcs7) - ode.js does this automatically
    const decrypted_media = Buffer.concat([decipher.update(cipherText), decipher.final()]);

    // Step 5: Validate the decrypted media

    // Make sure SHA256(decrypted_media) = plaintext_hash
    const decrypted_media_hash = crypto.createHash('sha256').update(decrypted_media).digest('base64');
    if (decrypted_media_hash !== plaintext_hash) {
      console.error('Decrypted media hash mismatch');
      throw new Error('Decrypted media hash mismatch');
    }

    return decrypted_media.toString('base64');
  }

  private isRequestSignatureValid(req: RawBodyRequest<Request>) {
    if (!this.appSecret) {
      console.warn('App Secret is not set up. Please Add your app secret in /.env file to check for request validation', '\n');
      return true;
    }

    const signatureHeader = req.get('x-hub-signature-256');
    if (!signatureHeader) {
      console.warn('No x-hub-signature-256 header', '\n');
      return false;
    }
    const signatureBuffer = Buffer.from(signatureHeader.replace('sha256=', ''), 'utf-8');

    const hmac = crypto.createHmac('sha256', this.appSecret);
    const digestString = hmac.update(req.rawBody?.toString() || '').digest('hex');
    const digestBuffer = Buffer.from(digestString, 'utf-8');

    if (!crypto.timingSafeEqual(digestBuffer, signatureBuffer)) {
      console.error('Error: Request Signature did not match', '\n');
      return false;
    }
    return true;
  }
}

By employing both of these methods, you'll be well-equipped to manage media efficiently across different platforms.

Messaging and Error Handling

Managing messages and handling errors effectively is crucial in working with Facebook APIs. You've already seen some of this in the previous code snippets, so I'll break this down here to it's constituent methods for a better look at how to handle incoming messages and address errors.

Handling Incoming Messages

When a new WhatsApp message comes in, it’s important to process it efficiently. Below is a simple process to manage this:

async handleIncomingWhatsAppMessage(message: WhatsAppIncomingMessage) {
  console.log('Handling incoming WhatsApp message', JSON.stringify(message), '\n\n');

  const entry = message.entry[0];
  const messages = entry.changes.find(entry => entry.field === 'messages')?.value?.messages || [];

  if (await this.farmerOnboardingStoryService.canHandleMessage({ message, actualMessage: messages })) {
    return this.farmerOnboardingStoryService.handleMessage({ message, actualMessage: messages });
  }
  // Further checks and error handling...
}

async verify(token: string, challenge: string): Promise<string> {
    if (token === this.verificationToken) {
      return challenge;
    }
    return 'error';
  }

  public async sendMessage(message: WhatsAppOutgoingMessage, apiOpts?: {
    phoneNumberId?: string,
    accessToken?: string
  }): Promise<void> {
    if (message.to.includes('+')) {
      message.to = message.to.replace('+', '');
    }
    const { env } = getEnvs();

    const api = apiOpts?.phoneNumberId ? `https://graph.facebook.com/${env.whatsappConfig.version}/${apiOpts.phoneNumberId}/messages` : this.whatsappMessagingApi;
    console.info('api: ', api);
    console.info('API Opts: ', apiOpts);
    console.info('outgoing message: ', message);

    await firstValueFrom(
      this.httpService.post(
        api,
        message,
        {
          headers: {
            Authorization: `Bearer ${apiOpts?.accessToken || this.accessToken}`,
            'Content-Type': 'application/json',
          },
        },
      ).pipe(
        catchError((error: AxiosError) => {
          throw error;
        }),
      ),
    ).catch((error: AxiosError) => {
      console.log('error: ', error.message, error.response?.data);
    });
  }

The verify method
This method ensures that the incoming requests are valid and originate from a trusted source, protecting your application from potential spoofing or unauthorized access.
token: This is the token that you've configured with WhatsApp to ensure that your app is what it claims to be. It acts as a shared secret between WhatsApp and your application.
challenge: A unique string sent by WhatsApp, which you must return to validate the request. This is unique for each request sent.
The handleIncomingWhatsAppMessage method
This method acts as a traffic controller for incoming messages, deciding which service should handle each message based on predefined conditions.
Logging: It starts by logging the entire message for debugging and auditing purposes.
Extracting Entries: The method retrieves the entry array from the message, isolating the changes related to incoming messages.
Message Filtering: It looks for changes that are specifically concerned with messages using the entry field messages.
Routing Logic: It checks each message against various conditions using different services designed to handle specific types of messages. For instance, if a message can be processed by the farmerOnboardingStoryService, the method routes the message to this service. Add more conditions as required by your application's logic to handle other story services.

Handling Errors

Handling errors is essential to ensure robust and resilient application behavior.

NB: Always make sure to catch all errors, and respond with a 200 OK response to WhatsApp, otherwise the messages will be considered failed, and will continously retry until WA servers get a 200 OK response. This is a bad experience for your users if a lot of messages have been queued since they will all be sent once the error is resolved, and will lower the quality rating of your account. Yes, I had to learn this the hard way unfortunately.

Here's how you can catch and manage errors:

@Catch(HttpException)
export class RESTHttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const res = new GqStandardEmptyResponse();
    res.status = exception.getStatus();
    console.error('HTTPExceptionFilter exception: ', exception);

    if (exception instanceof WhatsAppHandleMessageException) {

      // Here, we always return a 200 response to prevent WA servers from queing these messages to improve user experience.
      return response.status(200);
    }

    switch (res.status) {
      case 401:
        res.message = getTranslations(request.body.preferredLanguage)['not_authorized'];
        break;

      default:
        res.message = getTranslations(request.body.preferredLanguage)['server_error'];
        break;
    }

    return response.status(res.status).json(res);
  }
}

Use Cases: Where Our Integration Shines

With your newfound knowledge of Facebook API integration, let's explore some practical scenarios where these techniques can truly make an impact:

Enhanced Customer Support: By efficiently handling incoming WhatsApp messages, businesses can provide timely and personalized support to their customers. This ensures happier customers and improved service ratings.
Automated Notifications: Automate sending out notifications for order confirmations, shipping updates, or appointment reminders—saving time and ensuring your customers are always informed.
Secure Media Handling: Utilize secure methods for downloading and encrypting media through WhatsApp flows to protect sensitive information and maintain customer trust.
Dynamic Content Distribution: Distribute personalized offers or targeted messages at scale using the flexibility provided by WhatsApp and Facebook integrations.

Conclusion

Congratulations, you've turned a potentially overwhelming task into a suite of manageable, actionable components. By effectively handling media, ensuring secure message exchanges through encryption, and competently managing incoming messages, you’ve enhanced your app's interactions and data security.

Whether you're building sophisticated chatbots or simply improving customer communication, these tools and techniques empower you to leverage Facebook's rich API offerings fully. Now, it's time to put this knowledge into practice. How will you implement these methods in your project? Share your thoughts and questions in the comments below—we’re all here to learn and grow together!

A Personal Tutor (Powered by AI)

Brian Baliach — Sat, 22 Mar 2025 19:59:59 +0000

This is a submission for the KendoReact Free Components Challenge.

What I Built

I've developed a personal learning assistant focused on improving various aspects of the English language. This tool helps users enhance their pronunciation, grammar, vocabulary, and fluency.

Demo

You can check out the app source code here.
Here's a deployed demo (courtesy of vercel).
Below is a drive with screenshots showcasing the UI:

KendoReact Experience

In this project, I've utilized KendoReact Free Components to create a responsive and intuitive user interface. The components have streamlined the development process, allowing me to focus more on functionality.

AIm to Impress

I integrated GenAI technology to offer personalized learning experiences. This includes adaptive content recommendations based on user performance and progress tracking.

Delightfully Designed

I integrated GenAI technology to offer personalized learning experiences. This includes adaptive content recommendations based on user performance and progress tracking.

Thank you for the opportunity to participate in the challenge!

A Journey of Learning: From Software Engineer to Team Leader

Brian Baliach — Thu, 07 Nov 2024 07:12:50 +0000

Transitioning from a senior software engineer to building and leading an internal team at Farmbetter marks a significant shift not only in my professional journey but also in the way I communicate my experiences. Unlike my usual technical software engineering blogs, this post delves into the broader scope of leadership, communication, and personal growth.

You can find the original blog here.

Moving from a focus on code to leading a diverse team has expanded my perspective and sharpened my skills. Here, I share insights from this transformative journey, emphasizing the critical areas of communication and leadership that have been pivotal in navigating this new role.

The Art of Over-communication

In a diverse environment with team members spread across various countries, efficient communication emerges as a key growth area. Over-communication has become not just a best practice but a necessity. Ensuring everyone is on the same page regardless of time zones enhances cooperation and prevents misunderstandings.

Regular updates, setting clear expectations, and creating open channels for feedback are crucial. These lessons were particularly evident during my involvement in the #AgriPath project.

The Importance of Mentorship

Navigating the complexities of corporate culture and managing human relationships can be challenging, especially when transitioning into a leadership role. Having a mentor has been invaluable in guiding me through these nuances. A mentor provides insights and advice, helping to navigate difficult situations and offering perspectives that I might not have considered. They serve as a sounding board for ideas and challenges, helping to refine leadership skills and improve interpersonal interactions.

Having someone to share their experiences and wisdom makes the process less daunting and more structured, ultimately contributing to personal and professional growth.
For anyone stepping into a new role or looking to excel in their current position, seeking a mentor can be a game-changer in understanding and thriving within a corporate environment.

Embracing New Challenges

One of the most pivotal moments in my journey with Farmbetter came during the AgriPath workshop, where I faced the daunting task of presenting to high-ranking representatives. At that time, the technological aspects of the project, which Farmbetter leads, were in a challenging state, and our partners were understandably disappointed. Having just joined the team as the lead of tech, I was thrust into a situation that required not only a technical turnaround but also a strong reassurance to our partners.

This experience pushed me far out of my comfort zone, compelling me to hone my public speaking skills and become adept at handling pressure. While the static from the microphone might have been a re-occurring nemesis every time I spoke, it also taught me the importance of perseverance and adaptability in stressful situations. This challenge not only promoted my growth as a communicator but also strengthened my ability to engage meaningfully with diverse stakeholders.

The experience proved that embracing new challenges, even uncomfortable ones, is essential for personal development. Today, I'm not only a better speaker but also more confident in my ability to lead through adversity — static and all :-).

Looking Forward

In summary, this transition has taught me that effective leadership lies in good communication, empathy, and the ability to adapt. It's the human connections and shared goals that truly drive a project's success. For those considering a similar leap, remember that growth often lies beyond the comfort zone.

A side note: Interested in diving deeper into our work and seeing some of our research outcomes, do check out AgriPath's website and Farmbetter's website. The journey towards impactful agricultural development is one worth following!

Stay Curious and 'Lettuce' Grow Together!

TypeScript Stage 3 Decorators: A Journey Through Setup and Usage

Brian Baliach — Wed, 24 Jul 2024 09:06:50 +0000

So, What Are TypeScript Decorators?

In the simplest of terms, a decorator in TypeScript is like a wrapping paper. You take a function or a class and wrap it with another function that adds some extra features.

You can read the original blog here.

Decorators provide a way to add both meta-programming annotations and a declarative syntax for applying those annotations, making TypeScript more powerful and expressive. For instance, if you want a function that performs image compression and can be reused across various other functions, you can create an ImageCompression decorator. This decorator will wrap whichever function it is applied to, adding image compression capabilities.

To really get a grasp of this, consider an example in managing roles and permissions.

(as Billy Butcher) So for the deep-dive then, pay attention, because this is where it gets bloody interesting, mate.

Let's Get Technical

Defining a Permission Decorator

Here’s a simple example: a decorator that takes in a permission string and checks if the user has that specific permission. If the user lacks the required permission, the function returns with an unauthorized error. Note that we expect the class containing the calling function (the function what will be wrapped with this decorator) to have both a getLoggedInUser and handleUnauthorizedUser method (which is public since we can't decorate private properties) since implementations of both these methods may defer from architecture to architecture.

It is also worth noting that in this example, our decorator first runs (since it wraps the calling function) then depending on whether the user has permissions, either returns the call to this.handleUnauthorizedUser or the call to the calling function itself. So basically two steps, first our decorator function runs, then it returns the result of the calling function if the permission check passes.

export interface Caller {
  getLoggedInUser: () => Promise<{ permissions: Array<{ id: string }> }>;
  handleUnauthorizedUser: () => any;
}

export type Union<T> = Caller & T;

export function requiresPermission(permission: string) {
  function actualDecorator<This>(
    target: (this: This, ...args: any) => any,
    context: ClassMethodDecoratorContext<Union<This>, any>
  ) {
    const methodName = context.name;
    if (context.private) {
      throw new Error(
        `'requiresPermission' cannot decorate private properties like ${
          methodName as string
        }.`
      );
    }

    // Bind the method to the context
    context.addInitializer(function () {
      this[methodName] = this[methodName].bind(this);
    });

    async function replacementMethod(
      this: Union<This>,
      ...args: any
    ): Promise<any> {
      const user = await this.getLoggedInUser();
      let hasPermission = false;

      try {
        user?.permissions?.forEach((p) => {
          if (p?.id === permission) {
            hasPermission = true;
            throw Error("Match found.");
          }
        });
      } catch (e) {
        // Intended to break the loop
      }

      if (!hasPermission) {
        return this.handleUnauthorizedUser();
      }
      return target.call(this, ...args);
    }

    return replacementMethod;
  }

  return actualDecorator;
}

Implementing the Decorator

We’ll use the requiresPermission decorator in a class to manage function calls to a REST API that manages roles.

class RESTInternalInternalRoleDataSource {

    public handleUnauthorizedUser(){
        return false; // Handle single source of unauthorized user
    }

    public getLoggedInUser() {
        return {
            id: 1,
            name: "Test User",
            permissions: [
                {
                    id: "Manage Roles",
                    name: "Manage Roles"
                },
                {
                    id: "Manage Permissions",
                    name: "Manage Permissions"
                }
            ]
        }
    }

    @requiresPermission("Manage Permissions")
    getInternalPermissions(): Array<{id: string; name: string}> {
        return [
            { id: "Manage Permissions", name: "Manage Permissions" },
            { id: "Create Permissions", name: "Create Permissions" },
            { id: "Delete Permissions", name: "Delete Permissions" }
        ];
    }

    @requiresPermission("Manage Roles")
    getInternalRoles(): Array<{id: string; name: string}> {
        return [
            { id: "1", name: "Super Admin" },
            { id: "2", name: "Admin" },
            { id: "3", name: "Finance" }
        ];
    }

    @requiresPermission("Delete Roles")
    deleteInternalRole(): boolean {
        return true; // Handle role deletion
    }
}

export default RESTInternalInternalRoleDataSource;

Here, each method checks the user's permissions before proceeding with its logic using the requiresPermission decorator. If the user doesn't have the required permission, the method handles it appropriately.

That's basically it in using Stage 3 decorators. Here's a link to their documentation if you'd like an even deeper dive into stage 3 decorators.

For the next section, I'll be talking about how to integrate Stage 3 decorators with Next.js (App Router) since as of version 14.2.4 - currently the latest as I write this blog - doesn't offer support for Stage 3 decorators out of the box.

The Next.js Side of Things: Adding Support for Stage 3 Decorators

Next.js v14.2.4 is a robust framework with a massive community, but unfortunately, doesn’t support TypeScript Stage 3 decorators out of the box just yet. Luckily, there's a workaround. This workaround however, isn't for the faint-hearted as it involves patching Next.js' source code.
Don't worry though as I'll try to explain the process as clearly as I can, but feel free to comment if you still have questions!

Setting Up with `pnpm`

First things first. You'll have to ditch yarn (or maybe don't if Yarn supports patching of npm packages, but you'll most definitely need to ditch npm.). Then download pnpm an efficient package manager (which also doesn't duplicate your node_modules folders by providing a central repo locally, so no more running out of storage). We’ll use pnpm to patch our Next.js setup.

Step 1: Install `pnpm`

First, let’s install pnpm. You can install it via npm:

npm install -g pnpm

Or via homebrew:

brew install pnpm

For more installation options, you can refer to the official documentation.

Step 2: Patch Next.js

Next, patch your Next.js setup/project to support decorators. Navigate to your Next.js project directory and run:

pnpm patch next@14.2.4

Remember to edit the version number (the part after @) with the version you're currently using.
To check nextjs version, run:

next --version

pnpm will create a copy of next and output the location of this copy inside your terminal. The output should look roughly as follows:

Patch: You can now edit the package at:

  /private/var/folders/lh/jm0gx9n97ljf1hr66rbxclyh0000gn/T/1e5dc394b869fc2b77f7e91e57448382 (file:///private/var/folders/lh/jm0gx9n97ljf1hr66rbxclyh0000gn/T/1e5dc394b869fc2b77f7e91e57448382)

To commit your changes, run:

  pnpm patch-commit '/private/var/folders/lh/jm0gx9n97ljf1hr66rbxclyh0000gn/T/1e5dc394b869fc2b77f7e91e57448382'

Take not of the patch-commit command as you'll use it in the next steps.

Open the project in your favourite IDE (I prefer vi cause I'm 10X 😎) and edit the following file:
dist/build/swc/options.js

Find these entries (or similar ones):
enableDecorators - set this to true,
decoratorVersion - set this to '2022-03',
legacyDecorator - set this to false,

Finally, go back to your Next.js project and run patch-commit (you should have this when you ran pnpm patch):

pnpm patch-commit '/your/folder/with/next.js/copy/that/you/edited/here'

pnpm will add an entry automatically to your package.json that will resolve to a patch folder created in your project that contains the edits you just made.

(as Billy Butcher) Now Go wild with decorators in your Next.js project, and maybe, just maybe, those sods will drop an update soon that sorts this mess out.

Conclusion

Alright, that was definitely a mouthful. Let's wrap things up: You've had an introduction to TypeScript decorators, specifically Stage 3 decorators, and you've gotten a glimpse of a new package manager, pnpm, which you've used to skillfully patch Next.js. Now, if you're feeling adventurous, dive into the source code yourself and maybe even contribute to the Next.js repo with this patch. Maybe that long awaited update will be from you :-) The sky's the limit.

Go on, integrate those decorators in your Next.js projects and create something truly remarkable.

JavaScript Equality Under the Lens: Enhancing React’s Dependency Checks - Part 2

Brian Baliach — Thu, 04 Jul 2024 03:21:24 +0000

In a previous blog, JavaScript Equality Under the Lens: Enhancing React’s Dependency Checks, we delved into the nuances of JavaScript data types and their equality checks. We explored values with identity and those without, examining how JavaScript stores objects by reference rather than by value. To address object comparison within React's dependency checks, we devised a method to fetch keys from an object and compare their values, though this method was limited to one level deep.
You can find this original blog post here.

In this blog, we'll talk about a new way to do equality checks that will allow us to go n levels deep (rather than just one level) and will still be applicable not only to simple data types like numbers and strings, but also complex structures like objects and arrays. For this approach, we'll rely on an advanced but straightforward technique for value-based comparison of objects using JSON.stringify and JSON.parse.

Revisiting Object Equality: The Challenge

JavaScript’s intrinsic method of object comparison works by comparing memory references. This means two distinct objects with identical properties and values are considered unequal:

const objectOne = { key: "value" };
const objectTwo = { key: "value" };

console.log(objectOne === objectTwo);  // returns 'false'

In our previous blog, we created a function to check equality by manually comparing object keys and values. However, this function was limited to a shallow comparison:

function shallowEqual(obj1, obj2) {
  const keys1 = Object.keys(obj1);
  const keys2 = Object.keys(obj2);

  if (keys1.length !== keys2.length) return false;

  for (let key of keys1) {
    if (obj1[key] !== obj2[key]) return false;
  }

  return true;
}

While this approach was somewhat effective, it fell short when dealing with nested objects and arrays. This is where JSON.stringify and JSON.parse come into play.

The Magic of `JSON.stringify` and `JSON.parse`

In JavaScript, JSON.stringify converts a JavaScript object to a JSON string, while JSON.parse parses a JSON string to construct the JavaScript object. By converting objects into strings and comparing these string representations, we can bypass the idiosyncrasies of object reference comparison and handle nested structures efficiently:

const objectOne = { key: "value" };
const objectTwo = { key: "value" };

console.log(JSON.stringify(objectOne) === JSON.stringify(objectTwo)); // returns 'true'

And at the same time still return the original object using JSON.parse (if there's this use case).

Applying JSON Techniques in React

This approach is pivotal for React components' dependency checks. Let’s consider an advanced example where we use this technique in a custom hook:

import { useCallback, useEffect, useMemo, useRef, useState } from "react";

export type ObjType = {
  [key: string | number | symbol]: any;
};

/**
 * This hook checks for equality even for nested objects or arrays. Only causes a re-render if the [obj] param changes.
 */
const useObjectEqualityChecker = (obj: ObjType) => {
  const renders = useRef(0);
  if (renders.current >= 10) {
    throw new Error(
      `Total Renders: ${renders.current}. A tad bit too much ey?`
    );
  }
  const _internalStringify = useCallback((o: any) => {
    return JSON.stringify(o);
  }, []);

  const _objString = _internalStringify(obj);
  const currentObjRef = useRef(_internalStringify(obj));
  const [currentObj, setCurrentObj] = useState<string>(_internalStringify(obj));

  useEffect(() => {
    if (_objString) {
      try {
        if (currentObjRef.current !== _objString) {
          renders.current += 1;
          currentObjRef.current = _objString;
          setCurrentObj(_objString);
        }
      } catch (e) {
        // left blank intentionally. No need for any re-render.
      }
    }
  }, [_objString]);

  return useMemo(() => {
    return JSON.parse(currentObj);
  }, [currentObj]);
};

export default useObjectEqualityChecker;

This hook can come in handy when building components that take arrays or objects as props, where a developer might have forgotten to use useCallback or useMemo therefore returning different memory references every render.

Why This Approach is Better

Value-Based Comparison:
- Unlike reference-based comparison, the JSON-based approach guarantees that objects with the same properties and values will be considered equal, thereby avoiding unexpected re-renders in React.
Depth Coverage:
- This method seamlessly handles nested objects and arrays, ensuring accurate and deep comparisons without the need for custom deep equality functions.
Simplicity and Clarity:
- The technique is straightforward to implement, making your code more readable and less error-prone. It reduces the cognitive load for developers trying to understand object equality logic.
Consistency:
- Standardized behavior of JSON.stringify ensures consistency across different environments and usages, avoiding potential pitfalls of manually deep-checking objects or relying on third-party libraries.

Performance Implications

Though the JSON approach is powerful, it comes with performance trade-offs, especially for larger objects or frequent comparisons:

Serialization Overhead:
- Serializing and deserializing objects involve significant overhead compared to reference-based comparisons. For large and complex data structures, this could lead to performance bottlenecks.
Frequency of Operation:
- If used excessively in performance-critical sections of your application, the cumulative impact might be noticeable. However, for infrequent or isolated checks, the performance impact might be negligible.

const largeObject1 = { /* a large complex structure */ };
const largeObject2 = { /* a similarly large complex structure */ };

// Comparing using reference
console.time('Reference Comparison');
console.log(largeObject1 === largeObject2);
console.timeEnd('Reference Comparison');

// Comparing using JSON
console.time('JSON Comparison');
console.log(JSON.stringify(largeObject1) === JSON.stringify(largeObject2));
console.timeEnd('JSON Comparison');

In most cases, the reference comparison will be significantly faster.

Conclusion

No one-size-fits-all solution exists in software development. Understanding the trade-offs and careful application of these techniques will greatly enhance your ability to manage and optimize equality checks in JavaScript. This method of using JSON.stringify and JSON.parse for object comparison, especially in React, guarantees accurate value-based comparisons, making your components more reliable and efficient.

Until next time, happy coding!

DEV Community: Brian Baliach

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript

The Current Limitations

Hands-On: Building a Persistent ADK Agent

1. Patching @google/adk

2. The Webpack Shim (For NX/Webpack users)

3. Implementing Persistent Sessions

The Persistence Schema: Mapping ADK to PostgreSQL

The Session Entity

The Event Entity

The Memory Entity

Actual Implementation: The Services Layer

4. Long-Term Memory (Vector Search)

5) Giving the Agent a "Memory" Tool

Why toolContext is Key

6) Orchestrating the Agent (The "General Agent" Factory)

Why This Structure Wins

Architectural Benefits

Wrapping Up

AI Agents, Not If-Else: A Friendly Intro to Tool-Calling with CSVs

How Agentic AI Solves the Spreadsheet Sweat

What Is Tool-Calling, Really?

A Friendly Real-World Aside

Try It Yourself

Hands-On: Building a CSV Agent with Next.js and TypeScript

1) Define the Agent

2) Create a Tool: Average

3) Run the Agent on an API Route

4) A Minimal Frontend Chat

Why Tool-Calling Changes the UX (and Programming)

What’s Next

Wrapping Up

Weekly Coding Challenge #2: Generating Parentheses with Backtracking and Recursion

Problem Overview

1. Understanding Backtracking and Recursion

2. TypeScript Solution

3. Step-By-Step Explanation

a) State and Constraints

b) The Backtracking Function

c) Choosing "("

d) Choosing ")"

e) Building Results

4. Example

Conclusion

Weekly Coding Challenge #1: Solving Subsets II with Backtracking

Problem Overview

1. Understanding Backtracking

2. TypeScript Solution

3. Step-By-Step Explanation

a) Sorting the Input

b) The Backtracking Function

c) Generating Results

4. Example

Conclusion

End-to-End GraphQL File Uploads with Apollo Server and Apollo Client: A Comprehensive Guide

1. Spinning Up the Backend: Dependencies & Configuration

For the nestjs category:

for the bare-metal express server category:

2. Server Models, DTOs, & Resolvers: Building Your Upload Endpoint

Request & Response DTOs

Our Resolver and FileUploadService class

3. Client-Side Wizardry: Uploading Files with Apollo Client

Install necessary dependencies:

Setup Apollo Client Setup (with Upload)

The GraphQL Mutation

File Input and Upload Logic

I hope the code snippets above are self-explanatory (considering this is applicable to all frontend frameworks). If you run into any issues, always feel free to tag me in the comment section, and I'll respond as soon as I can!

Wrapping Up...

Integrating Model Context Protocol with Gemini: The Definitive Guide to Modern Tool Calling (Agentic-AI)

Setting Up Your AI Tooling Playground

Step 1: Initialize Your Node.js Project

Step 2: Install Required Dependencies

Defining MCP Servers and Tools

(A) Creating an MCP Server

(B) Defining and Registering a Tool

Implementing the MCP Client

(A) MCP Client Bootstrap

(B) Running the Client Loop

Wrapping Up: What We’ve Built and Where You Can Go Next

Permit IO Auth Challenge: Document and Team Management API with Fine-Grained Access Control

Why `toolContext` is Key

Setting Up with `pnpm`

Step 1: Install `pnpm`

The Magic of `JSON.stringify` and `JSON.parse`