gemini-reverse 1.0.2 → 1.0.4

package/README.md

@@ -1,25 +1,59 @@
-![Banner](https://nc-cdn.oss-accelerate.aliyuncs.com/nx/a772a980daeb.png)
+![Banner](https://napkinsdev.s3.us-east-1.amazonaws.com/next-s3-uploads/2a5843b5-3f5e-4ccd-bd61-f1ba6d6ae267/fb866bbfc5b3.png)
 
 # Gemini-Reverse
 
-An unofficial Node.js client for [gemini.google.com](https://gemini.google.com), inspired by [Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) — a Python reverse engineering project by [@HanaokaYuzu](https://github.com/HanaokaYuzu).
-
-This package ports the core concepts and functionality of the original Python library to Node.js, with full CommonJS and TypeScript support.
-
----
+An unofficial Node.js client for [Google Gemini](https://gemini.google.com), inspired by [Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) — a Python reverse engineering project by [@HanaokaYuzu](https://github.com/HanaokaYuzu).
 
 ## Features
 
-- Send messages and receive responses from Gemini
-- Streaming support with text deltas
-- Multi-turn chat sessions with conversation history
-- File and image upload support
-- Gem (system prompt) management — create, update, delete, fetch
-- Auto cookie refresh to keep sessions alive
-- TypeScript type declarations included
-- Proxy support
-
----
+- **Persistent Cookies** — Automatically refreshes cookies in the background. Optimized for always-on services.
+- **Image Generation** — Natively supports generating and editing images with natural language.
+- **Video & Audio Generation** — Supports generating videos and audio/music content natively.
+- **Deep Research** — Full deep research workflow with plan creation, status polling, and result retrieval.
+- **System Prompt** — Supports customizing the model's system prompt with [Gemini Gems](https://gemini.google.com/gems/view).
+- **Extension Support** — Supports generating content with Gemini extensions such as YouTube and Gmail.
+- **Classified Outputs** — Categorizes text, thoughts, images, videos, and audio in the response.
+- **Streaming Mode** — Supports stream generation, yielding partial outputs as they are generated.
+- **Dynamic Model Discovery** — Automatically discovers available models from your account at initialization.
+- **TypeScript Support** — Full TypeScript type declarations included out of the box.
+
+## Table of Contents
+
+- [Features](#features)
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Usage](#usage)
+  - [Initialization](#initialization)
+  - [Generate Content](#generate-content)
+  - [Generate Content with Files](#generate-content-with-files)
+  - [Conversations Across Multiple Turns](#conversations-across-multiple-turns)
+  - [Continue Previous Conversations](#continue-previous-conversations)
+  - [Read Conversation History](#read-conversation-history)
+  - [List Recent Chats](#list-recent-chats)
+  - [Delete a Conversation](#delete-a-conversation)
+  - [Temporary Mode](#temporary-mode)
+  - [Streaming Mode](#streaming-mode)
+  - [Select Language Model](#select-language-model)
+  - [List Available Models](#list-available-models)
+  - [Apply System Prompt with Gemini Gems](#apply-system-prompt-with-gemini-gems)
+  - [Manage Custom Gems](#manage-custom-gems)
+    - [Create a Custom Gem](#create-a-custom-gem)
+    - [Update an Existing Gem](#update-an-existing-gem)
+    - [Delete a Custom Gem](#delete-a-custom-gem)
+  - [Retrieve Model's Thought Process](#retrieve-models-thought-process)
+  - [Retrieve Images in Response](#retrieve-images-in-response)
+  - [Generate and Edit Images](#generate-and-edit-images)
+  - [Retrieve Videos and Audio](#retrieve-videos-and-audio)
+  - [Generate Content with Gemini Extensions](#generate-content-with-gemini-extensions)
+  - [Check and Switch to Other Reply Candidates](#check-and-switch-to-other-reply-candidates)
+  - [Deep Research](#deep-research)
+  - [Account Status](#account-status)
+- [Error Handling](#error-handling)
+- [Cookie Persistence](#cookie-persistence)
+- [TypeScript](#typescript)
+- [Project Structure](#project-structure)
+- [References](#references)
 
 ## Installation
 
@@ -27,79 +61,67 @@ This package ports the core concepts and functionality of the original Python li
 npm install gemini-reverse
 ```
 
----
-
 ## Authentication
 
-This package uses browser cookies to authenticate with Gemini. You need to obtain your `__Secure-1PSID` cookie from your browser after logging in to [gemini.google.com](https://gemini.google.com).
+- Go to [gemini.google.com](https://gemini.google.com) and log in with your Google account
+- Press F12 to open DevTools, go to the `Application` tab → `Cookies` → `https://gemini.google.com`
+- Copy the value of `__Secure-1PSID` (and optionally `__Secure-1PSIDTS`)
 
-**Steps:**
-1. Open [gemini.google.com](https://gemini.google.com) in your browser and log in
-2. Open DevTools → Application → Cookies → `https://gemini.google.com`
-3. Copy the value of `__Secure-1PSID` (and optionally `__Secure-1PSIDTS`)
+> `__Secure-1PSIDTS` is optional — the client will attempt to refresh and cache it automatically after the first successful initialization.
 
-> `__Secure-1PSIDTS` is optional — the client will attempt to refresh and cache it automatically after the first successful init.
+## Usage
 
----
+### Initialization
 
-## Quick Start
+Import the package and initialize a client with your cookies. After a successful initialization, the client will automatically refresh `__Secure-1PSIDTS` in the background as long as the process is alive.
 
 ```js
-const { GeminiClient } = require('gemini-core');
-
-const client = new GeminiClient({
-    secure_1psid: 'YOUR_SECURE_1PSID',
-});
+const { GeminiClient } = require('gemini-reverse');
 
-await client.init();
-
-const chat = client.startChat();
-const response = await chat.sendMessage({ prompt: 'Hello, Gemini!' });
-
-console.log(response.text);
-```
-
----
-
-## Usage
-
-### Initialize Client
-
-```js
 const client = new GeminiClient({
     secure_1psid: 'YOUR_SECURE_1PSID',
     secure_1psidts: 'YOUR_SECURE_1PSIDTS', // optional
-    proxy: 'http://host:port',              // optional
+    proxy: null,                            // optional, e.g. 'http://host:port'
 });
 
 await client.init({
     timeout: 300000,        // request timeout in ms, default 300000
-    autoClose: false,       // auto close client after inactivity
+    autoClose: false,       // auto-close client after inactivity
     closeDelay: 300000,     // inactivity delay before closing in ms
-    autoRefresh: true,      // auto refresh cookies in background
+    autoRefresh: true,      // auto-refresh cookies in the background
     refreshInterval: 540000 // cookie refresh interval in ms
 });
 ```
 
-### Generate Content (single turn)
+> `autoClose` and `closeDelay` are optional arguments for automatically closing the client after a period of inactivity. In an always-on service like a chatbot, it is recommended to set `autoClose` to `true` with a reasonable `closeDelay` value for better resource management.
+
+### Generate Content
+
+Ask a single-turn question by calling `generateContent`, which returns a `ModelOutput` object containing the generated text, images, thoughts, and conversation metadata.
 
 ```js
-const response = await client.generateContent({ prompt: 'What is the capital of France?' });
+const response = await client.generateContent({ prompt: 'Hello World!' });
 console.log(response.text);
 ```
 
-### Streaming
+### Generate Content with Files
+
+Gemini supports file input, including images and documents. Pass an array of file paths or `Buffer` objects alongside your text prompt.
 
 ```js
-for await (const chunk of client.generateContentStream({ prompt: 'Tell me a long story.' })) {
-    process.stdout.write(chunk.text_delta);
-}
+const response = await client.generateContent({
+    prompt: 'Describe the contents of these files.',
+    files: ['./document.pdf', './photo.png'],
+});
+console.log(response.text);
 ```
 
-### Chat Session
+### Conversations Across Multiple Turns
+
+Use `startChat` to create a `ChatSession` object and send messages through it. The conversation history is handled automatically and updated after each turn.
 
 ```js
-const chat = client.startChat({ model: 'gemini-3.1-pro' });
+const chat = client.startChat();
 
 const res1 = await chat.sendMessage({ prompt: 'My name is Alice.' });
 console.log(res1.text);
@@ -108,191 +130,457 @@ const res2 = await chat.sendMessage({ prompt: 'What is my name?' });
 console.log(res2.text); // remembers context
 ```
 
-### Streaming in Chat
+### Continue Previous Conversations
+
+Pass a previous `ChatSession`'s metadata to `startChat` to resume a conversation. You can persist the metadata to a file or database to restore it across process restarts.
 
 ```js
-const chat = client.startChat({ model: 'gemini-3.0-flash' });
+const chat = client.startChat();
+await chat.sendMessage({ prompt: 'Fine weather today.' });
 
-for await (const chunk of chat.sendMessageStream({ prompt: 'Explain quantum computing.' })) {
-    process.stdout.write(chunk.text_delta);
-}
+// Save the session metadata
+const savedMetadata = chat.metadata;
+const savedCid = chat.cid;
+
+// Resume in a new session
+const previousChat = client.startChat({ metadata: savedMetadata });
+const response = await previousChat.sendMessage({ prompt: 'What was my previous message?' });
+console.log(response.text);
 ```
 
-### Temporary Chat (no history saved)
+### Read Conversation History
+
+Fetch the full conversation history of a chat by calling `readChat` with the chat ID. It returns a `ChatHistory` object containing a list of `ChatTurn` objects ordered from newest to oldest.
 
 ```js
 const chat = client.startChat();
-const response = await chat.sendMessage({ prompt: 'This will not appear in history.', temporary: true });
+await chat.sendMessage({ prompt: 'What is the capital of France?' });
+
+const history = await client.readChat(chat.cid);
+if (history) {
+    for (const turn of history.turns) {
+        console.log(`[${turn.role.toUpperCase()}] ${turn.text}`);
+    }
+}
+```
+
+You can also read the history directly from the session:
+
+```js
+const history = await chat.readHistory(10); // fetch last 10 turns
+```
+
+### List Recent Chats
+
+Use `listChats` to get a list of recent chat sessions cached at initialization.
+
+```js
+const chats = client.listChats();
+if (chats) {
+    for (const info of chats) {
+        console.log(`${info.cid}: ${info.title} (pinned: ${info.is_pinned})`);
+    }
+}
 ```
 
-### Send with Files
+### Delete a Conversation
+
+Delete a specific chat from Gemini history on the server by calling `deleteChat` with the chat ID.
 
 ```js
 const chat = client.startChat();
-const response = await chat.sendMessage({
-    prompt: 'Describe this image.',
-    files: ['./photo.jpg'],
+await chat.sendMessage({ prompt: 'This is a temporary conversation.' });
+
+await client.deleteChat(chat.cid);
+console.log(`Chat deleted: ${chat.cid}`);
+```
+
+### Temporary Mode
+
+Pass `temporary: true` to `generateContent` or `sendMessage` to prevent the conversation from being saved to Gemini history.
+
+```js
+const response = await client.generateContent({
+    prompt: 'Hello World!',
+    temporary: true,
 });
 console.log(response.text);
+
+// Also works in chat sessions
+const chat = client.startChat();
+await chat.sendMessage({ prompt: 'Fine weather today.', temporary: false });
+const res2 = await chat.sendMessage({ prompt: "What's my last message?", temporary: true });
+console.log(res2.text);
 ```
 
-### Multiple Candidates
+### Streaming Mode
+
+For longer responses, use streaming mode to receive partial outputs as they are generated. The `text_delta` attribute contains only the **new characters** received since the last yield, making it easy to display incremental updates.
 
 ```js
-const chat = client.startChat();
-const response = await chat.sendMessage({ prompt: 'Give me a poem.' });
+for await (const chunk of client.generateContentStream({
+    prompt: "What's the difference between 'await' and 'async for'?",
+})) {
+    process.stdout.write(chunk.text_delta);
+}
+console.log();
+```
 
-// list all candidates
-response.candidates.forEach((c, i) => console.log(`[${i}] ${c.text}`));
+Streaming also works inside a chat session:
 
-// choose a specific candidate to continue the conversation
-chat.chooseCandidate(1);
+```js
+const chat = client.startChat();
+for await (const chunk of chat.sendMessageStream({ prompt: 'Tell me a long story.' })) {
+    process.stdout.write(chunk.text_delta);
+}
 ```
 
-### Models
+### Select Language Model
+
+Specify which language model to use by passing a `model` argument. Available models are discovered dynamically at init time based on your account tier.
 
 ```js
-// use model name string
-const chat = client.startChat({ model: 'gemini-3.1-pro' });
+const { Model } = require('gemini-reverse');
+
+// Using a built-in constant
+const response1 = await client.generateContent({
+    prompt: 'What is your model version?',
+    model: Model.BASIC_FLASH,
+});
 
-// or use the Model constant
-const { Model } = require('gemini-api');
-const chat = client.startChat({ model: Model.G_3_0_FLASH });
+// Using a model name string
+const chat = client.startChat({ model: 'gemini-3-pro' });
 
-// or use a custom model dict
-const chat = client.startChat({
+// Using a custom model header dict
+const chat2 = client.startChat({
     model: {
-        model_name: 'my-model',
-        model_header: { 'x-goog-ext-525001261-jspb': '...' },
+        model_name: 'custom',
+        model_header: {
+            'x-goog-ext-525001261-jspb': '[1,null,null,null,"MODEL_ID",null,null,0,[4],null,null,2]',
+        },
     },
 });
 ```
 
-**Available models:**
+**Built-in model constants:**
 
-| String | Constant |
-|---|---|
-| `gemini-3.1-pro` | `Model.G_3_1_PRO` |
-| `gemini-3.0-flash` | `Model.G_3_0_FLASH` |
-| `gemini-3.0-flash-thinking` | `Model.G_3_0_FLASH_THINKING` |
-| `unspecified` (default) | `Model.UNSPECIFIED` |
+| Constant | `model_name` | Notes |
+|---|---|---|
+| `Model.UNSPECIFIED` | `unspecified` | Default, lets Gemini choose |
+| `Model.BASIC_PRO` | `gemini-3-pro` | Free tier |
+| `Model.BASIC_FLASH` | `gemini-3-flash` | Free tier, fastest |
+| `Model.BASIC_THINKING` | `gemini-3-flash-thinking` | Free tier, thinking model |
+| `Model.PLUS_PRO` | `gemini-3-pro-plus` | Plus tier |
+| `Model.PLUS_FLASH` | `gemini-3-flash-plus` | Plus tier |
+| `Model.PLUS_THINKING` | `gemini-3-flash-thinking-plus` | Plus tier |
+| `Model.ADVANCED_PRO` | `gemini-3-pro-advanced` | Advanced tier |
+| `Model.ADVANCED_FLASH` | `gemini-3-flash-advanced` | Advanced tier |
+| `Model.ADVANCED_THINKING` | `gemini-3-flash-thinking-advanced` | Advanced tier |
 
-### Images
+### List Available Models
 
-Responses may include web images or AI-generated images.
+The client dynamically discovers which models your account can access during initialization. Use `listModels` to inspect them.
 
 ```js
-const response = await chat.sendMessage({ prompt: 'Send me an image of a cat.' });
+await client.init();
 
-for (const img of response.images) {
-    console.log(img.url, img.title, img.alt);
-    await img.save({ path: './downloads', verbose: true });
+const models = client.listModels();
+if (models) {
+    for (const model of models) {
+        console.log(`${model.model_id} → ${model.model_name || model.display_name}`);
+        console.log(`  capacity: ${model.capacity}, advanced_only: ${model.advanced_only}`);
+    }
 }
 ```
 
-### Read Chat History
+### Apply System Prompt with Gemini Gems
+
+System prompts can be applied to conversations via [Gemini Gems](https://gemini.google.com/gems/view). Pass the `gem` argument to `generateContent` or `startChat` — it can be a `Gem` object or a gem ID string.
 
 ```js
-const turns = await client.readChat('c_YOUR_CHAT_ID');
+// Fetch all gems for the account
+await client.fetchGems();
+const gems = client.gems;
+
+// Get a specific gem
+const codingPartner = gems.get({ name: 'Coding partner' });
+
+const response = await client.generateContent({
+    prompt: "What's your system prompt?",
+    gem: codingPartner,
+});
+console.log(response.text);
+
+// Use a gem in a multi-turn chat
+const chat = client.startChat({ gem: codingPartner });
+const res2 = await chat.sendMessage({ prompt: 'Help me write a binary search.' });
+console.log(res2.text);
+```
+
+> There are some system predefined gems that are hidden by default. Use `fetchGems({ includeHidden: true })` to include them.
+
+### Manage Custom Gems
+
+You can create, update, and delete custom gems programmatically. Predefined system gems cannot be modified.
+
+#### Create a Custom Gem
+
+```js
+const newGem = await client.createGem({
+    name: 'Python Tutor',
+    prompt: 'You are a helpful Python programming tutor. Always provide runnable code examples.',
+    description: 'A specialized gem for Python programming',
+});
+
+console.log(`Created: ${newGem.id}`);
+
+// Use the new gem immediately
+const response = await client.generateContent({
+    prompt: 'Explain list comprehensions.',
+    gem: newGem,
+});
+console.log(response.text);
+```
+
+#### Update an Existing Gem
+
+> When updating a gem, all parameters (`name`, `prompt`, `description`) must be provided even if only one is changing.
 
-for (const turn of turns) {
-    console.log('User:', turn.user_prompt);
-    console.log('Gemini:', turn.assistant_response);
+```js
+await client.fetchGems();
+const pythonTutor = client.gems.get({ name: 'Python Tutor' });
+
+const updatedGem = await client.updateGem({
+    gem: pythonTutor,
+    name: 'Advanced Python Tutor',
+    prompt: 'You are an expert Python programming tutor. Focus on performance and best practices.',
+    description: 'An advanced Python programming assistant',
+});
+
+console.log(`Updated: ${updatedGem.id}`);
+```
+
+#### Delete a Custom Gem
+
+```js
+await client.fetchGems();
+const gemToDelete = client.gems.get({ name: 'Advanced Python Tutor' });
+
+await client.deleteGem(gemToDelete); // can also pass a gem ID string
+console.log(`Deleted: ${gemToDelete.name}`);
+```
+
+### Retrieve Model's Thought Process
+
+When using thinking-capable models, the model's internal reasoning is exposed via `response.thoughts`.
+
+```js
+const response = await client.generateContent({
+    prompt: 'What is 17 × 23?',
+    model: Model.BASIC_THINKING,
+});
+
+if (response.thoughts) {
+    console.log('Thoughts:', response.thoughts);
 }
+console.log('Answer:', response.text);
 ```
 
-### Delete Chat
+### Retrieve Images in Response
+
+Images in the response are stored as a list of `Image` objects accessible via `response.images`. Each image has a `url`, `title`, and `alt` description.
 
 ```js
-await client.deleteChat('c_YOUR_CHAT_ID');
+const response = await client.generateContent({ prompt: 'Send me some pictures of cats.' });
+
+for (const image of response.images) {
+    console.log(`${image.title}: ${image.url}`);
+    console.log(`Alt: ${image.alt}`);
+}
 ```
 
-### Gems
+### Generate and Edit Images
+
+Ask Gemini to generate or edit images using natural language. Generated images are returned as `GeneratedImage` objects and can be saved to disk.
+
+> Google has limitations on image generation availability that vary by region and account type. Users under 18 cannot use this feature.
 
 ```js
-// fetch all gems
-const gems = await client.fetchGems();
+const response = await client.generateContent({
+    prompt: 'Generate a photo-realistic image of a cat in a space suit.',
+});
+
+for (let i = 0; i < response.images.length; i++) {
+    const image = response.images[i];
+    const savedPath = await image.save({
+        path: './temp',
+        filename: `cat_space_${i}.png`,
+        verbose: true,
+    });
+    console.log(`Saved to: ${savedPath}`);
+}
+```
 
-// get by name
-const gem = gems.get({ name: 'Coding partner' });
+> When asking Gemini to "send" images, it returns web images (`WebImage`). When asking to "generate" images, it returns AI-generated images (`GeneratedImage`). Both are automatically categorized in `response.images`.
 
-// filter user-created gems
-const myGems = gems.filter({ predefined: false });
+### Retrieve Videos and Audio
 
-// use a gem in chat
-const chat = client.startChat({ gem: gem });
+Gemini can generate short videos and audio/music. These are returned as `GeneratedVideo` and `GeneratedMedia` objects in `response.videos` and `response.media` respectively.
 
-// create a gem
-const newGem = await client.createGem({
-    name: 'My Assistant',
-    prompt: 'You are a helpful assistant that speaks formally.',
-    description: 'Formal assistant gem',
+> You may need an active Gemini subscription to access video and audio generation.
+
+```js
+// Generate a video
+const videoResponse = await client.generateContent({
+    prompt: 'Generate a short video of waves on a beach.',
 });
 
-// update a gem
-await client.updateGem({
-    gem: newGem,
-    name: 'My Assistant v2',
-    prompt: 'You are a helpful assistant that speaks casually.',
+for (const video of videoResponse.videos) {
+    const result = await video.save({ savePath: './temp', verbose: true });
+    console.log('Video:', result.video);
+    console.log('Thumbnail:', result.video_thumbnail);
+}
+
+// Generate audio/music
+const mediaResponse = await client.generateContent({
+    prompt: 'Compose a short calming piano melody.',
 });
 
-// delete a gem
-await client.deleteGem(newGem);
+for (const media of mediaResponse.media) {
+    // downloadType: 'audio' | 'video' | 'both' (default)
+    const result = await media.save({ savePath: './temp', downloadType: 'both', verbose: true });
+    console.log('MP3:', result.audio);
+    console.log('MP4:', result.video);
+}
 ```
 
-### Close Client
+> `GeneratedMedia.save()` accepts a `downloadType` parameter: `"audio"`, `"video"`, or `"both"` (default). The save method polls automatically if content is still generating (HTTP 206).
+
+### Generate Content with Gemini Extensions
+
+To use Gemini extensions (Gmail, YouTube, etc.), you must first activate them on the [Gemini website](https://gemini.google.com/extensions). Reference them in prompts with the `@` prefix or in natural language.
+
+> You must have Gemini Apps Activity enabled in your account to use extensions.
 
 ```js
-await client.close();
+const gmailResponse = await client.generateContent({
+    prompt: "@Gmail What's the latest message in my mailbox?",
+});
+console.log(gmailResponse.text);
+
+const youtubeResponse = await client.generateContent({
+    prompt: "@YouTube What's the latest video from Fireship?",
+});
+console.log(youtubeResponse.text);
 ```
 
----
+### Check and Switch to Other Reply Candidates
 
-## TypeScript
+A Gemini response sometimes contains multiple reply candidates with different generated content. You can inspect all candidates and choose one to continue the conversation flow.
 
-This package includes full TypeScript declarations out of the box.
+```js
+const chat = client.startChat();
+const response = await chat.sendMessage({ prompt: 'Recommend a science fiction book.' });
 
-```ts
-import { GeminiClient, ChatSession, ModelOutput, ConversationTurn, Gem, Model } from 'gemini-api';
+// List all candidates
+response.candidates.forEach((candidate, i) => {
+    console.log(`[${i}] ${candidate.text.slice(0, 80)}...`);
+});
 
-const client = new GeminiClient({ secure_1psid: '...' });
-await client.init();
+if (response.candidates.length > 1) {
+    // Choose the second candidate to continue from
+    chat.chooseCandidate(1);
 
-const chat: ChatSession = client.startChat({ model: 'gemini-3.1-pro' });
-const response: ModelOutput = await chat.sendMessage({ prompt: 'Hello!' });
+    const followup = await chat.sendMessage({ prompt: 'Tell me more about it.' });
+    console.log(followup.text);
+} else {
+    console.log('Only one candidate available.');
+}
+```
 
-console.log(response.text);
+### Deep Research
+
+Gemini's deep research feature is an autonomous agent that browses the web, analyzes sources, and produces a comprehensive report.
+
+> You may need an active Gemini subscription to access deep research.
+
+**Quick one-call method:**
+
+```js
+const result = await client.deepResearch(
+    'Compare the top 3 cloud providers and their AI offerings',
+    10000,   // poll interval in ms
+    600000,  // timeout in ms
+    (status) => console.log(`Status: ${status.state} — ${status.notes.slice(0, 1).join(', ')}`),
+);
+
+console.log(`Done: ${result.done}`);
+console.log(result.text);
 ```
 
----
+**Step-by-step workflow** for more control:
 
-## Project Structure
+```js
+// Step 1: Create a research plan
+const plan = await client.createDeepResearchPlan(
+    'What are the latest advancements in quantum computing?'
+);
+
+console.log(`Title: ${plan.title}`);
+console.log(`ETA: ${plan.eta_text}`);
+for (const step of plan.steps) {
+    console.log(`  - ${step}`);
+}
 
+// Step 2: Start the research
+const startOutput = await client.startDeepResearch(plan);
+console.log('Research started:', startOutput.text.slice(0, 100));
+
+// Step 3: Poll for completion
+const result = await client.waitForDeepResearch(
+    plan,
+    10000,   // poll interval in ms
+    600000,  // timeout in ms
+    (status) => console.log(`[${status.state}] ${status.notes[0] || ''}`),
+);
+
+console.log(result.text);
 ```
-gemini-api/
-├── index.js          # entry point
-├── index.d.ts        # TypeScript declarations
-├── client.js         # GeminiClient + ChatSession
-├── constants.js      # Endpoint, GRPC, Headers, Model, ErrorCode
-├── exceptions.js     # custom error classes
-├── types/
-│   ├── candidate.js
-│   ├── conversation.js
-│   ├── gem.js
-│   ├── grpc.js
-│   ├── image.js
-│   └── modeloutput.js
-├── utils/
-│   ├── accessToken.js
-│   ├── parsing.js
-│   ├── rotate.js
-│   └── upload.js
-└── components/
-    ├── chatMixin.js
-    └── gemMixin.js
+
+### Account Status
+
+The client detects your account's capability tier at initialization and exposes it via `client.accountStatus`.
+
+```js
+const { AccountStatus } = require('gemini-reverse');
+
+await client.init();
+
+if (client.accountStatus === AccountStatus.AVAILABLE) {
+    console.log('Account is fully authorized.');
+} else if (client.accountStatus === AccountStatus.UNAUTHENTICATED) {
+    console.error('Cookies are expired or invalid.');
+} else if (client.accountStatus === AccountStatus.LOCATION_REJECTED) {
+    console.error('Gemini is not available in your region.');
+} else {
+    console.warn(`Account status: ${client.accountStatus.name} — ${client.accountStatus.description}`);
+}
 ```
 
----
+**All account status values:**
+
+| Constant | Code | Description |
+|---|---|---|
+| `AccountStatus.AVAILABLE` | 1000 | Account is authorized and has normal access |
+| `AccountStatus.ACCESS_TEMPORARILY_UNAVAILABLE` | 1014 | Access restricted, possibly regional/temporary |
+| `AccountStatus.UNAUTHENTICATED` | 1016 | Cookies have expired or are invalid |
+| `AccountStatus.ACCOUNT_REJECTED` | 1021 | Account access rejected |
+| `AccountStatus.ACCOUNT_UNTRUSTED` | 1033 | Did not pass safety/trust checks |
+| `AccountStatus.TOS_PENDING` | 1040 | Must accept latest Terms of Service |
+| `AccountStatus.TOS_OUT_OF_DATE` | 1042 | Terms of Service are out of date |
+| `AccountStatus.ACCOUNT_REJECTED_BY_GUARDIAN` | 1054 | Blocked by parent or guardian |
+| `AccountStatus.GUARDIAN_APPROVAL_REQUIRED` | 1057 | Requires parental approval |
+| `AccountStatus.LOCATION_REJECTED` | 1060 | Not available in your country/region |
 
 ## Error Handling
 
@@ -305,41 +593,125 @@ const {
     UsageLimitExceeded,
     ModelInvalid,
     TemporarilyBlocked,
-} = require('gemini-api');
+} = require('gemini-reverse');
 
 try {
     const response = await chat.sendMessage({ prompt: 'Hello!' });
+    console.log(response.text);
 } catch (e) {
     if (e instanceof AuthError) {
-        console.error('Cookie expired or invalid.');
+        console.error('Cookie expired or invalid. Please refresh your cookies.');
     } else if (e instanceof UsageLimitExceeded) {
-        console.error('Usage limit reached. Try again later or switch models.');
+        console.error('Usage limit reached. Try again later or switch to a different model.');
     } else if (e instanceof TemporarilyBlocked) {
-        console.error('IP temporarily blocked. Try using a proxy.');
+        console.error('IP temporarily blocked by Google. Try using a proxy or wait a while.');
     } else if (e instanceof TimeoutError) {
-        console.error('Request timed out.');
+        console.error('Request timed out. Try increasing the timeout value in init().');
     } else if (e instanceof ModelInvalid) {
-        console.error('Invalid or unavailable model.');
+        console.error('Invalid or unavailable model. Try a different model.');
     } else if (e instanceof APIError) {
         console.error('API error:', e.message);
+    } else {
+        throw e;
     }
 }
 ```
 
----
+## Cookie Persistence
 
-## Credits
+If your application runs in a containerized environment (e.g. Docker), you can persist the auto-refreshed cookie cache to a volume by setting the `GEMINI_COOKIE_PATH` environment variable to a writable path.
 
-Inspired by [Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) by [@HanaokaYuzu](https://github.com/HanaokaYuzu) — an unofficial Python client for Gemini through reverse engineering.
+```yaml
+# docker-compose.yml
+services:
+    app:
+        environment:
+            GEMINI_COOKIE_PATH: /tmp/gemini_cache
+        volumes:
+            - ./gemini_cookies:/tmp/gemini_cache
+```
 
----
+By default, the cache is stored in `utils/temp/` relative to the package directory.
+
+## TypeScript
+
+This package includes full TypeScript declarations.
+
+```ts
+import {
+    GeminiClient,
+    ChatSession,
+    ModelOutput,
+    ChatHistory,
+    ChatTurn,
+    ChatInfo,
+    Gem,
+    AvailableModel,
+    Model,
+    AccountStatus,
+    DeepResearchPlan,
+    DeepResearchResult,
+} from 'gemini-reverse';
+
+const client = new GeminiClient({ secure_1psid: '...' });
+await client.init();
+
+const chat: ChatSession = client.startChat({ model: 'gemini-3-flash' });
+const response: ModelOutput = await chat.sendMessage({ prompt: 'Hello!' });
+
+console.log(response.text);
+
+const history: ChatHistory | null = await chat.readHistory();
+if (history) {
+    history.turns.forEach((turn: ChatTurn) => console.log(turn.role, turn.text));
+}
+
+const models: AvailableModel[] | null = client.listModels();
+```
+
+## Project Structure
+
+```
+gemini-reverse/
+├── index.js            # entry point & exports
+├── index.d.ts          # TypeScript declarations
+├── client.js           # GeminiClient + ChatSession
+├── constants.js        # Endpoint, GRPC, Headers, Model, AccountStatus, ErrorCode
+├── exceptions.js       # custom error classes
+├── types/
+│   ├── availablemodel.js   # AvailableModel (dynamic model from API)
+│   ├── candidate.js        # Candidate
+│   ├── chathistory.js      # ChatTurn, ChatHistory
+│   ├── chatinfo.js         # ChatInfo
+│   ├── gem.js              # Gem, GemJar
+│   ├── grpc.js             # RPCData
+│   ├── image.js            # Image, WebImage, GeneratedImage
+│   ├── modeloutput.js      # ModelOutput
+│   ├── research.js         # DeepResearchPlan, DeepResearchStatus
+│   ├── researchresult.js   # DeepResearchResult
+│   └── video.js            # Video, GeneratedVideo, GeneratedMedia
+├── utils/
+│   ├── accessToken.js      # cookie handling & init request
+│   ├── parsing.js          # response parsing utilities
+│   ├── research.js         # deep research payload extractors
+│   ├── rotate.js           # cookie rotation (kept from original)
+│   └── upload.js           # file upload helpers
+└── components/
+    ├── chatMixin.js        # chat history methods
+    ├── gemMixin.js         # gem management methods
+    └── researchMixin.js    # deep research methods
+```
+
+## References
+
+[Google AI Studio](https://ai.google.dev/tutorials/ai-studio_quickstart)
 
-## Disclaimer
+[Gemini-API (Python)](https://github.com/HanaokaYuzu/Gemini-API) by [@HanaokaYuzu](https://github.com/HanaokaYuzu)
 
-This is an unofficial package and is not affiliated with or endorsed by Google. Use at your own risk. Cookie-based authentication may break if Google changes its internal API.
+[acheong08/Bard](https://github.com/acheong08/Bard)
 
 ---
 
-## License
+**Disclaimer:** This is an unofficial package and is not affiliated with or endorsed by Google. Cookie-based authentication may break if Google changes its internal API. Use at your own risk.
 
-MIT
+**License:** MIT