> For the complete documentation index, see [llms.txt](https://docs.halfred.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halfred.ai/02-sdk-integration/01-nodejs.md).

# Halfred Node.js SDK

Official Halfred SDK for Node.js and TypeScript with modern JavaScript features, full type support, and easy integration.

## Installation

Install the Halfred SDK using your preferred package manager:

```bash
npm install halfred.ai
```

```bash
yarn add halfred.ai
```

```bash
pnpm add halfred.ai
```

## Quick Start

### Basic Setup

```javascript
import { Halfred } from "halfred.ai";

const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "lite",
    messages: [{ role: "user", content: "What is the capital of France?" }],
  });

  console.log(completion.choices[0].message.content);
}

main();
```

### With Environment Variables (Recommended)

```bash
# .env file
HALFRED_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```javascript
import { Halfred } from "halfred.ai";

// SDK automatically reads HALFRED_API_KEY from environment
const client = new Halfred();
```

You can also explicitly provide the API key if needed:

```javascript
const client = new Halfred({
  apiKey: process.env.HALFRED_API_KEY,
});
```

## Chat Completions

### Simple Completion

```javascript
const completion = await client.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Hello, Halfred!" }],
});

console.log(completion.choices[0].message.content);
```

### With System Message

```javascript
const completion = await client.chat.completions.create({
  model: "lite",
  messages: [
    {
      role: "system",
      content: "You are a helpful programming assistant.",
    },
    {
      role: "user",
      content: "How do I create an async function in JavaScript?",
    },
  ],
});
```

### Conversation History

```javascript
const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What's the weather like?" },
  { role: "assistant", content: "I don't have access to real-time weather data." },
  { role: "user", content: "What can you help me with?" },
];

const completion = await client.chat.completions.create({
  model: "standard",
  messages: messages,
});
```

### With Options

```javascript
const completion = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Explain quantum computing" }],
  temperature: 0.7, // Control randomness (0.0 - 2.0)
  max_tokens: 500, // Limit response length
});
```

## Choosing a Model Profile

Halfred offers different profiles optimized for various use cases:

```javascript
// LITE - Fast and cost-effective
const lite = await client.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Quick question..." }],
});

// STANDARD - Balanced performance (recommended)
const standard = await client.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "General query..." }],
});

// DEEPTHINK - Advanced reasoning
const deepthink = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Complex analysis..." }],
});

// DEV - Free for testing
const dev = await client.chat.completions.create({
  model: "dev",
  messages: [{ role: "user", content: "Test message..." }],
});
```

Learn more about profiles in our [Model Profiles guide](https://docs.halfred.ai/03-concepts/01-profiles.md).

## Response Format

### JSON Mode

Request JSON-formatted responses:

```javascript
const completion = await client.chat.completions.create({
  model: "standard",
  messages: [
    {
      role: "user",
      content: "List three programming languages in JSON format",
    },
  ],
  response_format: { type: "json_object" },
});

const data = JSON.parse(completion.choices[0].message.content);
console.log(data);
// Expected output:
// {
//   "languages": ["JavaScript", "Python", "Go"]
// }
```

### JSON Schema Mode

Enforce a specific JSON structure using JSON Schema:

```javascript
const completion = await client.chat.completions.create({
  model: "standard",
  messages: [
    {
      role: "user",
      content: "Generate information about three programming languages",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "programming_languages",
      strict: true,
      schema: {
        type: "object",
        properties: {
          languages: {
            type: "array",
            items: {
              type: "object",
              properties: {
                name: { type: "string" },
                year_created: { type: "number" },
                paradigm: { type: "string" },
                popular_frameworks: {
                  type: "array",
                  items: { type: "string" },
                },
              },
              required: ["name", "year_created", "paradigm"],
              additionalProperties: false,
            },
          },
        },
        required: ["languages"],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(completion.choices[0].message.content);
console.log(data);
// Expected output:
// {
//   "languages": [
//     {
//       "name": "JavaScript",
//       "year_created": 1995,
//       "paradigm": "Multi-paradigm",
//       "popular_frameworks": ["React", "Vue", "Angular"]
//     },
//     {
//       "name": "Python",
//       "year_created": 1991,
//       "paradigm": "Multi-paradigm",
//       "popular_frameworks": ["Django", "Flask", "FastAPI"]
//     },
//     {
//       "name": "Go",
//       "year_created": 2009,
//       "paradigm": "Concurrent",
//       "popular_frameworks": ["Gin", "Echo", "Fiber"]
//     }
//   ]
// }
```

## Error Handling

```javascript
try {
  const completion = await client.chat.completions.create({
    model: "standard",
    messages: [{ role: "user", content: "Hello!" }],
  });

  console.log(completion.choices[0].message.content);
} catch (error) {
  if (error.status === 401) {
    console.error("Invalid API key");
  } else if (error.status === 429) {
    console.error("Rate limit exceeded or insufficient credits");
  } else if (error.status === 400) {
    console.error("Bad request:", error.message);
  } else {
    console.error("API error:", error.message);
  }
}
```

## Streaming Responses (Coming Soon)

Real-time streaming support is coming soon. Contact support for early access.

```javascript
// Coming soon
const stream = await client.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
```

## List Available Models

```javascript
const models = await client.models.list();

console.log(models.data);
// [
//   { id: 'standard', object: 'model', ... },
//   { id: 'deepthink', object: 'model', ... },
//   ...
// ]
```

## Best Practices

### 1. Use Environment Variables

```bash
# .env file
HALFRED_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```javascript
// ✅ Good
const client = new Halfred();

// ❌ Bad
const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});
```

### 2. Handle Errors Gracefully

```javascript
async function getCompletion(prompt: string) {
  try {
    const completion = await client.chat.completions.create({
      model: "standard",
      messages: [{ role: "user", content: prompt }]
    });
    return completion.choices[0].message.content;
  } catch (error) {
    console.error("Failed to get completion:", error);
    return "Sorry, I couldn't process that request.";
  }
}
```

### 3. Choose the Right Profile

```javascript
// Simple UI responses - use lite
const uiResponse = await client.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Format this date" }],
});

// Complex analysis - use deepthink
const analysis = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Analyze this business strategy..." }],
});
```

### 4. Monitor Token Usage

```javascript
const completion = await client.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(`Tokens used: ${completion.usage.total_tokens}`);
console.log(`Prompt tokens: ${completion.usage.prompt_tokens}`);
console.log(`Completion tokens: ${completion.usage.completion_tokens}`);
```

## Troubleshooting

### Module Not Found

```bash
# Make sure the package is installed
npm install halfred.ai
```

### TypeScript Errors

```bash
# Install type definitions (included in package)
npm install --save-dev @types/node
```

### API Key Issues

```javascript
// Check if API key is loaded
if (!process.env.HALFRED_API_KEY) {
  throw new Error("HALFRED_API_KEY environment variable is required");
}
```

## Support

* **Documentation**: <https://docs.halfred.ai>
* **Email**: <support@halfred.ai>
* **Discord**: [Join our community](https://discord.gg/wS2awX4EV7)
* **GitHub**: [Report issues](https://github.com/halfred-ai/halfred-nodejs)

## Next Steps

* Learn about [Model Profiles](https://docs.halfred.ai/03-concepts/01-profiles.md)
* Explore the [REST API Reference](https://docs.halfred.ai/04-api-reference/01-endpoints.md)
* Check out [Best Practices](https://docs.halfred.ai/05-advanced/01-best-practices.md)
