@juspay/neurolink 9.44.1 → 9.48.1

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## [9.48.1](https://github.com/juspay/neurolink/compare/v9.48.0...v9.48.1) (2026-04-06)
+
+### Bug Fixes
+
+- **(types):** update index to export directly from multimodal (fixes [#275](https://github.com/juspay/neurolink/issues/275)) ([739ad2a](https://github.com/juspay/neurolink/commit/739ad2aa91d9766f098bb7d804de6fbb00d1c9d8))
+
+## [9.48.0](https://github.com/juspay/neurolink/compare/v9.47.0...v9.48.0) (2026-04-05)
+
+### Features
+
+- **(docs):** generate unique OG images per page for rich social previews ([cb1998d](https://github.com/juspay/neurolink/commit/cb1998d5f4c57e17c1b7a7619516f98020112afe))
+
+## [9.47.0](https://github.com/juspay/neurolink/compare/v9.46.1...v9.47.0) (2026-04-04)
+
+### Features
+
+- **(observability):** auto-write OTEL endpoint to ~/.neurolink/.env on telemetry setup ([a6e56f3](https://github.com/juspay/neurolink/commit/a6e56f392b66005bbd4bbfeeff952aefebf172d4))
+
+## [9.46.1](https://github.com/juspay/neurolink/compare/v9.46.0...v9.46.1) (2026-04-04)
+
+### Bug Fixes
+
+- **(proxy):** PID-scoped token store temp files and dynamic launchd PATH ([dc63fa8](https://github.com/juspay/neurolink/commit/dc63fa80690d214105ccc42705bac7b821395b52))
+
+## [9.46.0](https://github.com/juspay/neurolink/compare/v9.45.0...v9.46.0) (2026-04-04)
+
+### Features
+
+- **(image):** add extension whitelist validation utilities (IMG-021) ([1cfdf30](https://github.com/juspay/neurolink/commit/1cfdf30aeb57ea3566ad4c4837de6f27228514ae))
+
+## [9.45.0](https://github.com/juspay/neurolink/compare/v9.44.1...v9.45.0) (2026-04-04)
+
+### Features
+
+- **(image):** implement JPEG dimension extraction via SOF marker parsing ([9fac5cb](https://github.com/juspay/neurolink/commit/9fac5cb883fcd1a3550160ecc546146ccc3a3407))
+
+### Bug Fixes
+
+- **(ci):** pin npm to v10 instead of latest in release workflow ([357ccf3](https://github.com/juspay/neurolink/commit/357ccf36b8a038a29b11b67988b3c30192fcc636))
+- **(mb):** Make text optional when multimodal content present ([ae12580](https://github.com/juspay/neurolink/commit/ae125808cc9853e56ef62957210332da702695e4))
+- **(utils):** add content-length:0 validation in URL downloader ([8fcb795](https://github.com/juspay/neurolink/commit/8fcb795e28fb3687341eb4e3853479a1bdc2d7f7)), closes [#549](https://github.com/juspay/neurolink/issues/549)
+
 ## [9.44.1](https://github.com/juspay/neurolink/compare/v9.44.0...v9.44.1) (2026-04-03)
 
 ## [9.44.0](https://github.com/juspay/neurolink/compare/v9.43.0...v9.44.0) (2026-04-02)

package/README.md

@@ -150,17 +150,242 @@ const result = await neurolink.generate({
 
 **[Enterprise HITL Guide](docs/features/enterprise-hitl.md)** | **[Quick Start](docs/features/hitl.md)**
 
-## Get Started in Two Steps
+## 📚 Quick Start Guide
+
+This guide will have you generating AI responses in under 5 minutes using either the SDK or CLI.
+
+### Installation
+
+Choose your preferred package manager:
 
 ```bash
-# 1. Run the interactive setup wizard (select providers, validate keys)
+# npm
+npm install @juspay/neurolink
+
+# pnpm (recommended)
+pnpm add @juspay/neurolink
+
+# yarn
+yarn add @juspay/neurolink
+
+# CLI only (no installation needed)
+npx @juspay/neurolink --help
+```
+
+### Configuration
+
+NeuroLink works with 13+ AI providers. You'll need at least one API key to get started:
+
+**Option 1: Interactive Setup (Recommended)**
+
+```bash
+# Run the setup wizard to configure providers
 pnpm dlx @juspay/neurolink setup
+```
+
+The wizard will guide you through:
+
+- Selecting your preferred AI providers
+- Validating API keys
+- Setting up configuration files
+
+**Option 2: Manual Configuration**
+
+Create a `.env` file in your project root:
+
+```bash
+# Choose one or more providers
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_AI_API_KEY=...
+```
+
+**Free Tier Options:**
+
+- **Google AI Studio**: Get a free API key at [aistudio.google.com](https://aistudio.google.com)
+- **Mistral AI**: Free tier available at [console.mistral.ai](https://console.mistral.ai)
+- **Ollama**: 100% free local models (requires [Ollama installation](https://ollama.ai))
+
+### Your First API Call (SDK)
+
+**Basic Text Generation:**
+
+```typescript
+import { NeuroLink } from "@juspay/neurolink";
+
+// Initialize (auto-selects best available provider from your .env)
+const neurolink = new NeuroLink();
+
+// Generate a response
+const result = await neurolink.generate({
+  input: { text: "Explain quantum computing in simple terms" },
+});
+
+console.log(result.content);
+```
+
+**Streaming Responses:**
+
+```typescript
+// Stream tokens in real-time
+const stream = await neurolink.stream({
+  input: { text: "Write a haiku about code" },
+});
+for await (const chunk of stream.stream) {
+  if ("content" in chunk) process.stdout.write(chunk.content);
+}
+```
+
+**Multimodal Input (Images + Text):**
+
+```typescript
+const result = await neurolink.generate({
+  input: {
+    text: "What's in this image?",
+    images: ["./photo.jpg"],
+  },
+});
+```
+
+**Using Tools:**
+
+```typescript
+// Built-in tools are automatically available
+const result = await neurolink.generate({
+  input: {
+    text: "What time is it and what files are in the current directory?",
+  },
+  // AI can call getCurrentTime and listDirectory tools
+});
+```
+
+### Your First API Call (CLI)
+
+**Basic Generation:**
 
-# 2. Start generating with automatic provider selection
-npx @juspay/neurolink generate "Write a launch plan for multimodal chat"
+```bash
+# Simple text generation
+npx @juspay/neurolink generate "Explain TypeScript generics"
+
+# Specify provider and model
+npx @juspay/neurolink generate "Hello!" --provider openai --model gpt-4o
+
+# Stream responses
+npx @juspay/neurolink stream "Write a story about AI" --provider anthropic
+```
+
+**Multimodal Input:**
+
+```bash
+# Analyze images
+npx @juspay/neurolink generate "Describe this image" --image photo.jpg
+
+# Process PDFs
+npx @juspay/neurolink generate "Summarize this document" --pdf report.pdf
+
+# Combine multiple file types
+npx @juspay/neurolink generate "Analyze this data" --file data.xlsx --file config.json
+```
+
+**Interactive Loop Mode:**
+
+```bash
+# Start an interactive session with persistent context
+npx @juspay/neurolink loop
+
+# Inside loop mode:
+> set provider anthropic
+> set model claude-opus-4
+> generate "Hello, Claude!"
+> history  # View conversation history
+> exit
+```
+
+### Common Use Cases
+
+**RAG (Retrieval-Augmented Generation):**
+
+```typescript
+// Automatically chunk, embed, and search documents
+const result = await neurolink.generate({
+  input: { text: "What are the key features mentioned in the documentation?" },
+  rag: {
+    files: ["./docs/guide.md", "./docs/api.md"],
+    chunkSize: 512,
+    topK: 5,
+  },
+});
 ```
 
-Need a persistent workspace? Launch loop mode with `npx @juspay/neurolink loop` - [Learn more →](docs/features/cli-loop-sessions.md)
+**Structured Output with Zod:**
+
+```typescript
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+});
+
+const result = await neurolink.generate({
+  input: {
+    text: "Extract user info: John Doe, 30 years old, john@example.com",
+  },
+  schema,
+  output: { format: "json" },
+});
+
+// Parse the structured JSON from result.content
+const parsed = schema.parse(JSON.parse(result.content));
+console.log(parsed); // { name: "John Doe", age: 30, email: "john@example.com" }
+```
+
+**External MCP Servers (GitHub, Slack, etc.):**
+
+```typescript
+// Connect to GitHub MCP server
+await neurolink.addExternalMCPServer("github", {
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-github"],
+  transport: "stdio",
+  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+});
+
+// AI can now interact with GitHub
+const result = await neurolink.generate({
+  input: { text: 'Create an issue titled "Bug: login fails"' },
+});
+```
+
+### Next Steps
+
+- **[Complete Documentation](https://docs.neurolink.ink)** - Comprehensive guides and API reference
+- **[Provider Setup Guide](docs/getting-started/provider-setup.md)** - Configure all 13 providers
+- **[SDK API Reference](docs/sdk/api-reference.md)** - Full TypeScript API documentation
+- **[CLI Command Reference](docs/cli/commands.md)** - Complete CLI documentation
+- **[Example Projects](docs/examples/index.md)** - Real-world integration examples
+- **[Advanced Features](docs/advanced/index.md)** - Middleware, observability, workflows
+
+### Troubleshooting
+
+**Issue: "Provider not configured"**
+
+- Run `npx @juspay/neurolink setup` or add provider API key to `.env`
+
+**Issue: Rate limit errors**
+
+- Configure multiple providers for redundancy — NeuroLink auto-selects the best available
+- Use `provider: "litellm"` with LiteLLM to proxy across many providers
+
+**Issue: Large context overflows**
+
+- Enable conversation memory with compaction: `new NeuroLink({ conversationMemory: { enabled: true } })`
+- Use `rag` option to search documents instead of sending full content
+
+Need help? Check our [Troubleshooting Guide](docs/reference/troubleshooting.md) or [open an issue](https://github.com/juspay/neurolink/issues).
+
+---
 
 ## 🌟 Complete Feature Set
 

package/dist/auth/tokenStore.js

@@ -148,7 +148,8 @@ export class TokenStore {
                 ? this.obfuscate(JSON.stringify(storageData))
                 : JSON.stringify(storageData, null, 2);
             // Write to temporary file first for atomic operation
-            const tempPath = `${this.storagePath}.tmp`;
+            // Use PID-scoped temp file to avoid cross-process race conditions
+            const tempPath = `${this.storagePath}.tmp.${process.pid}`;
             await writeFile(tempPath, content, "utf-8");
             // Set restrictive permissions before moving to final location
             await chmod(tempPath, TokenStore.FILE_PERMISSIONS);
@@ -681,7 +682,8 @@ export class TokenStore {
             const content = this.encryptionEnabled
                 ? this.obfuscate(JSON.stringify(data))
                 : JSON.stringify(data, null, 2);
-            const tmpPath = `${this.storagePath}.tmp`;
+            // Use PID-scoped temp file to avoid cross-process race conditions
+            const tmpPath = `${this.storagePath}.tmp.${process.pid}`;
             await writeFile(tmpPath, content, "utf-8");
             await chmod(tmpPath, TokenStore.FILE_PERMISSIONS);
             await rename(tmpPath, this.storagePath);