> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heychocolate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Universal JavaScript/TypeScript client for the Hey Chocolate API.

The Hey Chocolate JavaScript SDK provides a type-safe GraphQL client for Node.js and browser environments.

## Installation

```bash theme={null}
npm install @heychocolate/sdk
```

## Setup

```typescript theme={null}
import { HeyChocolate } from '@heychocolate/sdk';

const client = new HeyChocolate({
  apiKey: process.env.HEYCHOCOLATE_API_KEY,
  environment: 'production', // or 'sandbox'
});
```

## Query products

```typescript theme={null}
const { products } = await client.products.list({
  first: 20,
  filter: {
    sectorTag: 'FOOD',
    co2Range: { min: 0, max: 50 },
  },
});

for (const product of products.edges) {
  console.log(product.node.name, product.node.impactScore.co2Equivalent);
}
```

## Calculate impact

```typescript theme={null}
const result = await client.calculations.impact({
  productId: 'prod_abc123',
  quantity: 100,
  transportMethod: 'TRUCK',
  distance: 500,
  distanceUnit: 'KM',
});

console.log(`CO2: ${result.co2Equivalent} kg`);
console.log(`Equivalent to: ${result.equivalency.description} ${result.equivalency.value}`);
```

## Run scenarios

```typescript theme={null}
const scenario = await client.scenarios.simulate({
  baseProductId: 'prod_abc123',
  quantity: 100,
  overrides: [
    { parameter: 'MATERIAL', value: 'bio_based_composite' },
    { parameter: 'TRANSPORT_METHOD', value: 'RAIL' },
  ],
});

console.log(`Baseline: ${scenario.baseline.co2Equivalent} kg`);
console.log(`Simulated: ${scenario.simulated.co2Equivalent} kg`);
console.log(`Reduction: ${scenario.delta.percentageChange}%`);
```

## Shopping cart

```typescript theme={null}
const cart = await client.cart.calculate({
  sessionId: 'user_session_123',
  items: [
    { productId: 'prod_abc123', quantity: 2 },
    { productId: 'prod_def456', quantity: 1 },
  ],
  shippingMethod: 'STANDARD',
  shippingAddress: { country: 'NL' },
});

console.log(`Cart total: ${cart.totalCo2Equivalent} kg CO2e`);
```

## Generate DPP

```typescript theme={null}
const dpp = await client.dpp.generate({
  productId: 'prod_abc123',
  locale: 'en',
  includeQrCode: true,
});

console.log(`DPP URL: ${dpp.publicUrl}`);
console.log(`QR Code: ${dpp.qrCodeUrl}`);
```

## Error handling

```typescript theme={null}
import { HeyChocolateError, RateLimitError } from '@heychocolate/sdk';

try {
  const result = await client.products.get('prod_nonexistent');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof HeyChocolateError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  }
}
```

## TypeScript support

The SDK includes full TypeScript definitions for all types, inputs, and responses:

```typescript theme={null}
import type { Product, ImpactScore, SectorTag } from '@heychocolate/sdk';

const product: Product = await client.products.get('prod_abc123');
const score: ImpactScore = product.impactScore;
```