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

​
Installation

npm install @heychocolate/sdk

​
Setup

import { HeyChocolate } from '@heychocolate/sdk';

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

​
Query products

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

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

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

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

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

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: 
import type { Product, ImpactScore, SectorTag } from '@heychocolate/sdk';

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