gemini-reverse 1.0.3 → 1.0.5

package/README.md

@@ -1,25 +1,59 @@
-# Gemini-Reverse
+![Banner](https://napkinsdev.s3.us-east-1.amazonaws.com/next-s3-uploads/2a5843b5-3f5e-4ccd-bd61-f1ba6d6ae267/fb866bbfc5b3.png)
 
-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).
+# Gemini-Reverse
 
----
+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
-- Video and media (audio) support
-- Gem (system prompt) management — create, update, delete, fetch
-- Deep research support — create plan, start, poll, and get results
-- Dynamic model discovery from account RPC
-- Account status detection
-- 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,304 +61,657 @@ An unofficial Node.js client for [gemini.google.com](https://gemini.google.com),
 npm install gemini-reverse
 ```
 
----
-
 ## Authentication
 
+- 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`)
+
+> `__Secure-1PSIDTS` is optional — the client will attempt to refresh and cache it automatically after the first successful initialization.
+
+## Usage
+
+### Initialization
+
+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-reverse');
+
+const client = new GeminiClient({
+    secure_1psid: 'YOUR_SECURE_1PSID',
+    secure_1psidts: 'YOUR_SECURE_1PSIDTS', // 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
+    closeDelay: 300000,     // inactivity delay before closing in ms
+    autoRefresh: true,      // auto-refresh cookies in the background
+    refreshInterval: 540000 // cookie refresh interval in ms
+});
 ```
-1. Open gemini.google.com and log in
-2. DevTools → Application → Cookies → https://gemini.google.com
-3. Copy __Secure-1PSID (and optionally __Secure-1PSIDTS)
+
+> `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: 'Hello World!' });
+console.log(response.text);
 ```
 
----
+### Generate Content with Files
 
-## Quick Start
+Gemini supports file input, including images and documents. Pass an array of file paths or `Buffer` objects alongside your text prompt.
 
 ```js
-const { GeminiClient } = require('gemini-reverse');
+const response = await client.generateContent({
+    prompt: 'Describe the contents of these files.',
+    files: ['./document.pdf', './photo.png'],
+});
+console.log(response.text);
+```
 
-const client = new GeminiClient({ secure_1psid: 'YOUR_SECURE_1PSID' });
+### Conversations Across Multiple Turns
 
-await client.init();
+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();
-const response = await chat.sendMessage({ prompt: 'Hello, Gemini!' });
-console.log(response.text);
 
-await client.close();
+const res1 = await chat.sendMessage({ prompt: 'My name is Alice.' });
+console.log(res1.text);
+
+const res2 = await chat.sendMessage({ prompt: 'What is my name?' });
+console.log(res2.text); // remembers context
 ```
 
----
+### Continue Previous Conversations
 
-## Usage
+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.
 
-### Initialize Client
+```js
+const chat = client.startChat();
+await chat.sendMessage({ prompt: 'Fine weather today.' });
+
+// 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);
+```
+
+### 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
-await client.init({
-    timeout: 300000,
-    autoClose: false,
-    closeDelay: 300000,
-    autoRefresh: true,
-    refreshInterval: 540000,
-    verbose: false,
-    watchdogTimeout: 30000,
-});
+const chat = client.startChat();
+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}`);
+    }
+}
 ```
 
-### Generate Content
+You can also read the history directly from the session:
 
 ```js
-const response = await client.generateContent({ prompt: 'What is the capital of France?' });
-console.log(response.text);
+const history = await chat.readHistory(10); // fetch last 10 turns
 ```
 
-### Streaming
+### List Recent Chats
+
+Use `listChats` to get a list of recent chat sessions cached at initialization.
 
 ```js
-for await (const chunk of client.generateContentStream({ prompt: 'Tell me a long story.' })) {
-    process.stdout.write(chunk.text_delta);
+const chats = client.listChats();
+if (chats) {
+    for (const info of chats) {
+        console.log(`${info.cid}: ${info.title} (pinned: ${info.is_pinned})`);
+    }
 }
 ```
 
-### Chat Session
+### 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({ model: 'gemini-3-flash' });
+const chat = client.startChat();
+await chat.sendMessage({ prompt: 'This is a temporary conversation.' });
 
-const res1 = await chat.sendMessage({ prompt: 'My name is Alice.' });
-const res2 = await chat.sendMessage({ prompt: 'What is my name?' });
-console.log(res2.text);
+await client.deleteChat(chat.cid);
+console.log(`Chat deleted: ${chat.cid}`);
 ```
 
-### Streaming in Chat
+### 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();
-for await (const chunk of chat.sendMessageStream({ prompt: 'Explain quantum computing.' })) {
+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);
+```
+
+### 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
+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();
 ```
 
-### Temporary Chat
+Streaming also works inside a chat session:
 
 ```js
-const response = await chat.sendMessage({ prompt: 'This will not appear in history.', temporary: true });
+const chat = client.startChat();
+for await (const chunk of chat.sendMessageStream({ prompt: 'Tell me a long story.' })) {
+    process.stdout.write(chunk.text_delta);
+}
 ```
 
-### Send with Files
+### 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
-const response = await chat.sendMessage({
-    prompt: 'Describe this image.',
-    files: ['./photo.jpg'],
+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,
+});
+
+// Using a model name string
+const chat = client.startChat({ model: 'gemini-3-pro' });
+
+// Using a custom model header dict
+const chat2 = client.startChat({
+    model: {
+        model_name: 'custom',
+        model_header: {
+            'x-goog-ext-525001261-jspb': '[1,null,null,null,"MODEL_ID",null,null,0,[4],null,null,2]',
+        },
+    },
 });
 ```
 
-### Multiple Candidates
+**Built-in model constants:**
 
-```js
-const response = await chat.sendMessage({ prompt: 'Give me a poem.' });
-response.candidates.forEach((c, i) => console.log(`[${i}] ${c.text}`));
-chat.chooseCandidate(1);
-```
+| 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 |
 
-### Models
+### List Available Models
+
+The client dynamically discovers which models your account can access during initialization. Use `listModels` to inspect them.
 
 ```js
+await client.init();
+
 const models = client.listModels();
 if (models) {
-    for (const m of models) {
-        console.log(m.model_id, m.model_name, m.display_name);
+    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}`);
     }
 }
+```
 
-const chat = client.startChat({ model: 'gemini-3-flash' });
+### Apply System Prompt with Gemini Gems
 
-const { Model } = require('gemini-reverse');
-const chat2 = client.startChat({ model: Model.BASIC_FLASH });
+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
+// Fetch all gems for the account
+await client.fetchGems();
+const gems = client.gems;
 
-const chat3 = client.startChat({
-    model: { model_name: 'my-model', model_header: { 'x-goog-ext-525001261-jspb': '...' } },
+// 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);
 ```
 
-**Built-in model constants:**
+> There are some system predefined gems that are hidden by default. Use `fetchGems({ includeHidden: true })` to include them.
+
+### Manage Custom Gems
 
-| Constant | model_name |
-|---|---|
-| `Model.UNSPECIFIED` | `unspecified` (default) |
-| `Model.BASIC_PRO` | `gemini-3-pro` |
-| `Model.BASIC_FLASH` | `gemini-3-flash` |
-| `Model.BASIC_THINKING` | `gemini-3-flash-thinking` |
-| `Model.PLUS_PRO` | `gemini-3-pro-plus` |
-| `Model.PLUS_FLASH` | `gemini-3-flash-plus` |
-| `Model.PLUS_THINKING` | `gemini-3-flash-thinking-plus` |
-| `Model.ADVANCED_PRO` | `gemini-3-pro-advanced` |
-| `Model.ADVANCED_FLASH` | `gemini-3-flash-advanced` |
-| `Model.ADVANCED_THINKING` | `gemini-3-flash-thinking-advanced` |
-
-### Images
+You can create, update, and delete custom gems programmatically. Predefined system gems cannot be modified.
+
+#### Create a Custom Gem
 
 ```js
-for (const img of response.images) {
-    console.log(img.url, img.title, img.alt);
-    await img.save({ path: './downloads', verbose: true });
-}
+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.
+
+```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}`);
 ```
 
-### Videos & Media
+#### Delete a Custom Gem
 
 ```js
-for (const video of response.videos) {
-    await video.save({ savePath: './downloads', verbose: true });
+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);
 }
-for (const media of response.media) {
-    await media.save({ savePath: './downloads', downloadType: 'both', verbose: true });
+console.log('Answer:', response.text);
+```
+
+### 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
+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}`);
 }
 ```
 
-### Chat History
+### 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
-const history = await client.readChat('c_YOUR_CHAT_ID');
-if (history) {
-    for (const turn of history.turns) {
-        console.log(turn.role, turn.text);
-    }
+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}`);
 }
+```
 
-const chats = client.listChats();
-if (chats) {
-    for (const info of chats) {
-        console.log(info.cid, info.title, info.is_pinned);
-    }
+> 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`.
+
+### Retrieve Videos and Audio
+
+Gemini can generate short videos and audio/music. These are returned as `GeneratedVideo` and `GeneratedMedia` objects in `response.videos` and `response.media` respectively.
+
+> 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.',
+});
+
+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);
 }
 
-const sessionHistory = await chat.readHistory(10);
+// Generate audio/music
+const mediaResponse = await client.generateContent({
+    prompt: 'Compose a short calming piano melody.',
+});
+
+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);
+}
 ```
 
-### Delete Chat
+> `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.deleteChat('c_YOUR_CHAT_ID');
+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);
 ```
 
-### Deep Research
+### Check and Switch to Other Reply Candidates
 
-```js
-const plan = await client.createDeepResearchPlan('History of artificial intelligence');
-console.log(plan.title, plan.steps);
+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.
 
-const startOutput = await client.startDeepResearch(plan);
+```js
+const chat = client.startChat();
+const response = await chat.sendMessage({ prompt: 'Recommend a science fiction book.' });
 
-const result = await client.waitForDeepResearch(plan, 10000, 600000, (status) => {
-    console.log(status.state, status.notes);
+// List all candidates
+response.candidates.forEach((candidate, i) => {
+    console.log(`[${i}] ${candidate.text.slice(0, 80)}...`);
 });
-console.log(result.text);
 
-const result2 = await client.deepResearch('Explain quantum computing', 10000, 600000);
-console.log(result2.text);
+if (response.candidates.length > 1) {
+    // Choose the second candidate to continue from
+    chat.chooseCandidate(1);
+
+    const followup = await chat.sendMessage({ prompt: 'Tell me more about it.' });
+    console.log(followup.text);
+} else {
+    console.log('Only one candidate available.');
+}
 ```
 
-### Account Status
+### 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 { AccountStatus } = require('gemini-reverse');
+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);
+```
 
-if (client.accountStatus === AccountStatus.UNAUTHENTICATED) {
-    console.error('Cookies expired.');
-} else if (client.accountStatus === AccountStatus.LOCATION_REJECTED) {
-    console.error('Gemini not available in your region.');
+**Step-by-step workflow** for more control:
+
+```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);
 ```
 
-### Gems
+### Account Status
+
+The client detects your account's capability tier at initialization and exposes it via `client.accountStatus`.
 
 ```js
-const gems = await client.fetchGems();
-const gem = gems.get({ name: 'Coding partner' });
-const myGems = gems.filter({ predefined: false });
-const chat = client.startChat({ gem });
+const { AccountStatus } = require('gemini-reverse');
 
-const newGem = await client.createGem({
-    name: 'My Assistant',
-    prompt: 'You are a helpful assistant that speaks formally.',
-});
+await client.init();
 
-await client.updateGem({ gem: newGem, name: 'My Assistant v2', prompt: 'Speak casually.' });
-await client.deleteGem(newGem);
+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
 
 ```js
-const { AuthError, APIError, GeminiError, TimeoutError, UsageLimitExceeded, ModelInvalid, TemporarilyBlocked } = require('gemini-reverse');
+const {
+    AuthError,
+    APIError,
+    GeminiError,
+    TimeoutError,
+    UsageLimitExceeded,
+    ModelInvalid,
+    TemporarilyBlocked,
+} = 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.');
-    else if (e instanceof UsageLimitExceeded) console.error('Usage limit reached.');
-    else if (e instanceof TemporarilyBlocked) console.error('IP temporarily blocked.');
-    else if (e instanceof TimeoutError) console.error('Request timed out.');
-    else if (e instanceof ModelInvalid) console.error('Invalid model.');
-    else if (e instanceof APIError) console.error('API error:', e.message);
+    if (e instanceof AuthError) {
+        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 to a different model.');
+    } else if (e instanceof TemporarilyBlocked) {
+        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. Try increasing the timeout value in init().');
+    } else if (e instanceof ModelInvalid) {
+        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
+
+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.
+
+```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
-├── index.d.ts
-├── client.js
-├── constants.js
-├── exceptions.js
+├── 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
-│   ├── candidate.js
-│   ├── chathistory.js
-│   ├── chatinfo.js
-│   ├── gem.js
-│   ├── grpc.js
-│   ├── image.js
-│   ├── modeloutput.js
-│   ├── research.js
-│   ├── researchresult.js
-│   └── video.js
+│   ├── 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
-│   ├── parsing.js
-│   ├── research.js
-│   ├── rotate.js
-│   └── upload.js
+│   ├── 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
-    ├── gemMixin.js
-    └── researchMixin.js
+    ├── chatMixin.js        # chat history methods
+    ├── gemMixin.js         # gem management methods
+    └── researchMixin.js    # deep research methods
 ```
 
----
-
-## Credits
-
-Inspired by [Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) by [@HanaokaYuzu](https://github.com/HanaokaYuzu).
+## 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)
 
-Unofficial package, not affiliated with Google. Use at your own risk.
+[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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemini-reverse",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Unofficial Node.js client for gemini.google.com — inspired by Gemini-API (Python). Supports streaming, chat sessions, gems, file uploads, and TypeScript.",
   "main": "index.js",
   "types": "index.d.ts",

package/types/image.js

@@ -3,6 +3,7 @@
 const axios = require('axios');
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 class Image {
     constructor({ url, title = '[Image]', alt = '', proxy = null } = {}) {
@@ -12,43 +13,76 @@ class Image {
         this.proxy = proxy;
     }
 
+    _getUrlForHash() {
+        return this.url;
+    }
+
     toString() {
         const short = this.url.length <= 20 ? this.url : this.url.slice(0, 8) + '...' + this.url.slice(-12);
         return `Image(title='${this.title}', alt='${this.alt}', url='${short}')`;
     }
 
-    async save({ path: savePath = 'temp', filename = null, cookies = null, verbose = false, skipInvalidFilename = false } = {}) {
-        let fname = filename || this.url.split('/').pop().split('?')[0];
-        const match = fname.match(/^(.*\.\w+)/);
-        if (match) {
-            fname = match[1];
-        } else {
-            if (verbose) console.warn(`Invalid filename: ${fname}`);
-            if (skipInvalidFilename) return null;
+    async save({ path: savePath = 'temp', filename = null, verbose = false } = {}) {
+        if (!filename || !path.extname(filename)) {
+            const timestamp = new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14);
+            const urlHash = crypto.createHash('sha256').update(this._getUrlForHash()).digest('hex').slice(0, 10);
+            const baseName = filename ? path.parse(filename).name : 'image';
+            filename = `${timestamp}_${urlHash}_${baseName}`;
         }
 
-        const proxyConfig = this.proxy ? (() => { try { const u = new URL(this.proxy); return { protocol: u.protocol.replace(':', ''), host: u.hostname, port: parseInt(u.port) }; } catch { return undefined; } })() : undefined;
+        fs.mkdirSync(savePath, { recursive: true });
+        return await this._performSave(savePath, filename, verbose);
+    }
+
+    async _performSave(savePath, filename, verbose) {
+        const imgUrl = this.url;
+        const proxyConfig = this._parseProxy(this.proxy);
+        const clientRef = this.client_ref || null;
+        const cookies = clientRef ? clientRef.cookies : null;
 
-        const res = await axios.get(this.url, {
+        const res = await axios.get(imgUrl, {
             responseType: 'arraybuffer',
-            headers: cookies ? { 'Cookie': Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; ') } : {},
+            headers: {
+                'Origin': 'https://gemini.google.com',
+                'Referer': 'https://gemini.google.com/',
+                ...(cookies ? { 'Cookie': Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; ') } : {}),
+            },
             maxRedirects: 5,
             ...(proxyConfig ? { proxy: proxyConfig } : {}),
         });
 
-        if (res.status !== 200) throw new Error(`Error downloading image: ${res.status}`);
+        if (verbose) console.debug(`HTTP Request: GET ${imgUrl} [${res.status}]`);
 
-        const contentType = res.headers['content-type'] || '';
-        if (contentType && !contentType.includes('image')) {
-            console.warn(`Content type of ${fname} is not image, but ${contentType}.`);
+        if (res.status !== 200) {
+            throw new Error(`Error downloading image: ${res.status}`);
         }
 
-        fs.mkdirSync(savePath, { recursive: true });
-        const dest = path.join(savePath, fname);
+        const contentType = (res.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+        let ext = path.extname(filename);
+        if (!ext) {
+            if (contentType.includes('jpeg') || contentType.includes('jpg')) ext = '.jpg';
+            else if (contentType.includes('png')) ext = '.png';
+            else if (contentType.includes('webp')) ext = '.webp';
+            else if (contentType.includes('gif')) ext = '.gif';
+            else ext = '.png';
+            filename = filename + ext;
+        }
+
+        const dest = path.join(savePath, filename);
         fs.writeFileSync(dest, Buffer.from(res.data));
-        if (verbose) console.log(`Image saved as ${path.resolve(dest)}`);
+        if (verbose) console.info(`Image saved as ${path.resolve(dest)}`);
         return path.resolve(dest);
     }
+
+    _parseProxy(proxyStr) {
+        if (!proxyStr) return undefined;
+        try {
+            const u = new URL(proxyStr);
+            return { protocol: u.protocol.replace(':', ''), host: u.hostname, port: parseInt(u.port) };
+        } catch {
+            return undefined;
+        }
+    }
 }
 
 class WebImage extends Image {
@@ -56,19 +90,72 @@ class WebImage extends Image {
 }
 
 class GeneratedImage extends Image {
-    constructor({ cookies, ...opts } = {}) {
-        super(opts);
-        if (!cookies || Object.keys(cookies).length === 0)
-            throw new Error('GeneratedImage requires cookies from GeminiClient.');
-        this.cookies = cookies;
+    constructor({ url, title = '[Image]', alt = '', proxy = null, client_ref = null, cid = '', rid = '', rcid = '', image_id = '' } = {}) {
+        super({ url, title, alt, proxy });
+        this.client_ref = client_ref;
+        this.cid = cid;
+        this.rid = rid;
+        this.rcid = rcid;
+        this.image_id = image_id;
     }
 
-    async save({ path: savePath = 'temp', filename = null, cookies = null, verbose = false, skipInvalidFilename = false, fullSize = true } = {}) {
-        if (fullSize) this.url += '=s2048';
-        const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
-        const fname = filename || `${ts}_${this.url.slice(-10)}.png`;
-        return super.save({ path: savePath, filename: fname, cookies: cookies || this.cookies, verbose, skipInvalidFilename });
+    async _performSave(savePath, filename, verbose, fullSize = true) {
+        if (fullSize) {
+            if (this.client_ref && this.cid && this.rid && this.rcid && this.image_id) {
+                try {
+                    const originalUrl = await this.client_ref._getFullSizeImage(
+                        this.cid, this.rid, this.rcid, this.image_id,
+                    );
+                    if (originalUrl) {
+                        const proxyConfig = this._parseProxy(this.proxy);
+                        const cookies = this.client_ref ? this.client_ref.cookies : null;
+                        const headers = {
+                            'Origin': 'https://gemini.google.com',
+                            'Referer': 'https://gemini.google.com/',
+                            ...(cookies ? { 'Cookie': Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; ') } : {}),
+                        };
+
+                        const r1 = await axios.get(`${originalUrl}=d-I?alr=yes`, {
+                            headers, maxRedirects: 5, ...(proxyConfig ? { proxy: proxyConfig } : {}),
+                        });
+                        const r2 = await axios.get(r1.data.trim(), {
+                            headers, maxRedirects: 5, ...(proxyConfig ? { proxy: proxyConfig } : {}),
+                        });
+                        this.url = r2.data.trim();
+                        return await super._performSave(savePath, filename, verbose);
+                    }
+                } catch (e) {
+                    if (verbose) console.debug(`Failed to fetch full size image via RPC: ${e.message}, falling back.`);
+                }
+            }
+
+            if (this.url.includes('=s1024-rj')) {
+                this.url = this.url.replace('=s1024-rj', '=s2048-rj');
+            } else if (!this.url.includes('=s2048-rj')) {
+                this.url += '=s2048-rj';
+            }
+        } else {
+            if (this.url.includes('=s2048-rj')) {
+                this.url = this.url.replace('=s2048-rj', '=s1024-rj');
+            } else if (!this.url.includes('=s1024-rj')) {
+                this.url += '=s1024-rj';
+            }
+        }
+
+        return await super._performSave(savePath, filename, verbose);
+    }
+
+    async save({ path: savePath = 'temp', filename = null, verbose = false, fullSize = true } = {}) {
+        if (!filename || !path.extname(filename)) {
+            const timestamp = new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14);
+            const urlHash = crypto.createHash('sha256').update(this._getUrlForHash()).digest('hex').slice(0, 10);
+            const baseName = filename ? path.parse(filename).name : 'image';
+            filename = `${timestamp}_${urlHash}_${baseName}`;
+        }
+
+        fs.mkdirSync(savePath, { recursive: true });
+        return await this._performSave(savePath, filename, verbose, fullSize);
     }
 }
 
-module.exports = { Image, WebImage, GeneratedImage };
+module.exports = { Image, WebImage, GeneratedImage };