XForce Serverless (Express + TypeScript)

This project is a small Express microservice written in TypeScript and ready to deploy as a Vercel Serverless Function.

It provides API endpoints that use the Gemini API to generate content:

• English grammar explanations with HTML formatting
• Cultural facts about countries in multiple languages

Features

• Express API running on Vercel Serverless
• TypeScript setup
• Gemini 2.5 Flash Lite integration
• Multiple endpoints for different use cases
• Error handling for rate limits and server errors

API

POST /api/grammar

Request body (JSON):

{
  "level": "B1",
  "concept": "Present Perfect",
  "description": "Actions started in the past and connected to now",
  "example": "I have lived here for five years."
}

Required fields:

• level
• concept
• description
• example

Response:

• Content-Type: text/plain
• Body: a string that contains semantic HTML with Tailwind classes (generated by Gemini)

POST /api/apps/cultural-explorer

Request body (JSON):

{
  "countryName": "Japan",
  "language": "English"
}

Required fields:

• countryName (string): The name of the country to get a cultural fact about

Optional fields:

• language (string): The language for the response. Defaults to "English" if not provided.

Response:

• Content-Type: application/json
• Body: JSON object with a data field containing a plain text cultural fact (2-3 sentences)

Example response:

{
  "data": "In Japan, there's a tradition called 'Hanami' where people gather to appreciate the transient beauty of cherry blossoms, but what's less known is that this practice dates back over a thousand years and was originally reserved for the elite samurai class."
}

Environment variables

Set this variable in your environment (local) and in Vercel (production):

• GEMINI_API_KEY (your Gemini API key)

There is also an example file: .env.example.

Run locally

Install dependencies:

npm install

Create your .env file:

cp .env.example .env

Start in dev mode:

npm run dev

Then call:

• POST http://localhost:3000/api/languages/english/grammar
• POST http://localhost:3000/api/apps/cultural-explorer

Deploy to Vercel

1. Push this repo to GitHub.
2. Import the project in Vercel.
3. Add GEMINI_API_KEY in Vercel Project Settings → Environment Variables.
4. Deploy.

The entry point for Vercel is api/index.ts, and routing is configured in vercel.json.