Veganify API Wrapper 2.0

A modern, type-safe wrapper for the official Veganify API with built-in validation, caching, and comprehensive error handling.

Features

• 🎯 Type Safety: Full TypeScript support with Zod v4 validation
• 🚀 Performance: Built-in TTL + LRU caching per API method
• 🛡️ Robust Error Handling: Custom error types with native Error.cause chaining
• ⚡ Framework Agnostic: Works with any JavaScript framework
• 🔄 Modern Architecture: Singleton pattern with resetInstance() for testing
• 📦 Dual Package: Ships both CommonJS (require) and ESM (import) builds
• ⏱️ Timeout Support: Requests are automatically aborted after a configurable deadline

Installation

You can install the package via npm, yarn, or pnpm, bun, etc.:

# Using npm
npm install @frontendnetwork/veganify

# Using yarn
yarn add @frontendnetwork/veganify

# Using pnpm
pnpm add @frontendnetwork/veganify

Quick Start

import Veganify from "@frontendnetwork/veganify";

// Get an instance with default configuration
const veganify = Veganify.getInstance();

// Example: Check if ingredients are vegan
async function checkIngredients() {
  try {
    const result = await veganify.checkIngredientsListV1("water, sugar, milk");
    console.log("Is vegan:", result.data.vegan);
    console.log("Non-vegan ingredients:", result.data.not_vegan);
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error("Invalid ingredients format:", error.message);
    }
  }
}

Configuration

interface VeganifyConfig {
  baseUrl?: string;      // Override the API base URL entirely
  cacheTTL?: number;     // Cache TTL in ms (0 or negative = disabled). Default: 1 800 000 (30 min)
  staging?: boolean;     // Point requests at the staging API
  timeout?: number;      // Request timeout in ms. Default: 10 000 (10 s)
  cacheMaxSize?: number; // Max entries per cache bucket before LRU eviction. Default: 500
}

// Example: Configure with custom settings
const veganify = Veganify.getInstance({
  cacheTTL: 3600000,   // 1 hour cache
  staging: true,       // Use staging environment
  timeout: 5000,       // Abort requests after 5 s
  cacheMaxSize: 200,   // Keep at most 200 entries per cache
});

API Reference

Instance Management

Veganify.getInstance(config?: VeganifyConfig): Veganify

Returns the shared singleton instance, creating it on the first call. Subsequent calls with different config values are ignored — use resetInstance() first to apply new configuration.

Veganify.resetInstance(): void

Destroys the current singleton so the next getInstance() call creates a fresh instance with new configuration. Primarily intended for tests and server-side lifecycle hooks.

Veganify.resetInstance();
const fresh = Veganify.getInstance({ cacheTTL: 0, staging: true });

Product Information

getProductByBarcode(barcode: string): Promise<ProductResponse>

Retrieves detailed product information using a barcode number. This method queries multiple databases to gather comprehensive vegan and ethical product data.

Parameters:

• barcode: A string containing the product barcode (must contain only digits)

Returns:

A promise that resolves to a ProductResponse object containing the response type.

try {
  const product = await veganify.getProductByBarcode("4066600204404");
  console.log(product.product.vegan); // true/false/"n/a"
  console.log(product.product.productname); // "Product Name"
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Product not found");
  } else if (error instanceof ValidationError) {
    console.error("Invalid barcode format");
  }
}

Response Type:

interface ProductResponse {
  status: number;
  product: {
    productname: string;
    genericname?: string;
    vegan?: boolean | "n/a";
    vegetarian?: boolean | "n/a";
    animaltestfree?: boolean | "n/a";
    palmoil?: boolean | "n/a";
    nutriscore?: string;
    grade?: string;
  };
  sources: {
    processed: boolean;
    api: string;
    baseuri: string;
  };
}

Ingredients Analysis

checkIngredientsListV1(ingredientsList: string, preprocessed?: boolean): Promise<IngredientsCheckResponseV1>

Analyzes a list of ingredients to determine their vegan status. The method categorizes ingredients into different groups based on certainty of their vegan status.

Parameters:

• ingredientsList: A string containing comma-separated ingredients
• preprocessed: (Optional) Boolean indicating whether to preprocess the ingredients list (defaults to true)

Returns:

A promise that resolves to an IngredientsCheckResponseV1 return type.

try {
  const result = await veganify.checkIngredientsListV1("water, sugar, milk");
  console.log("Is vegan:", result.data.vegan);
  console.log("Surely vegan:", result.data.surely_vegan);
  console.log("Not vegan:", result.data.not_vegan);
  console.log("Maybe not vegan:", result.data.maybe_not_vegan);
  console.log("Unknown:", result.data.unknown);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Invalid ingredients format");
  }
}

Response Type:

interface IngredientsCheckResponseV1 {
  code: string;
  status: string;
  message: string;
  data: {
    vegan: boolean;
    surely_vegan: string[];
    not_vegan: string[];
    maybe_not_vegan: string[];
    unknown: string[];
  };
}

PETA Cruelty-Free Brands

getPetaCrueltyFreeBrands(): Promise<PetaCrueltyFreeResponse>

Retrieves the current list of PETA-certified cruelty-free brands.

Returns: A promise that resolves to a PetaCrueltyFreeResponse object:

interface PetaCrueltyFreeResponse {
  LAST_UPDATE: string; // Last database update timestamp
  PETA_DOES_NOT_TEST: string[]; // Array of cruelty-free brand names
}

try {
  const brands = await veganify.getPetaCrueltyFreeBrands();
  console.log("Last update:", brands.LAST_UPDATE);
  console.log("Cruelty-free brands:", brands.PETA_DOES_NOT_TEST);
} catch (error) {
  console.error("Failed to fetch PETA brands:", error.message);
}

Error Handling

The package provides three custom error classes. All extend VeganifyError which extends the native Error:

| Class | statusCode | When thrown | |---|---|---| | VeganifyError | varies | Base class; also thrown for HTTP errors, timeouts (408) | | ValidationError | 400 | Malformed barcode, empty ingredients, invalid response schema | | NotFoundError | 404 | Product or resource not found |

The error.cause property is set on all errors (native Error.cause chaining):

import {
  ValidationError,
  NotFoundError,
  VeganifyError,
} from "@frontendnetwork/veganify";

try {
  // Your code here
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation errors (400)
    console.error(error.message, error.cause);
  } else if (error instanceof NotFoundError) {
    // Handle not found errors (404)
  } else if (error instanceof VeganifyError) {
    // Handle other API errors (timeouts return statusCode 408)
    console.error(`HTTP ${error.statusCode}:`, error.message);
  } else {
    // Handle unexpected errors
  }
}

Framework Examples

React Example

import { useState } from "react";
import Veganify, { ValidationError } from "@frontendnetwork/veganify";

const IngredientsChecker = () => {
  const [ingredients, setIngredients] = useState("");
  const [result, setResult] = useState(null);
  const [error, setError] = useState("");
  const veganify = Veganify.getInstance();

  const handleCheck = async (e) => {
    e.preventDefault();
    try {
      const analysis = await veganify.checkIngredientsListV1(ingredients);
      setResult(analysis);
      setError("");
    } catch (error) {
      setResult(null);
      if (error instanceof ValidationError) {
        setError("Please enter valid ingredients");
      } else {
        setError("An error occurred while checking ingredients");
      }
    }
  };

  return (
    <div>
      <form onSubmit={handleCheck}>
        <input
          value={ingredients}
          onChange={(e) => setIngredients(e.target.value)}
          placeholder="Enter ingredients (comma-separated)"
        />
        <button type="submit">Check Ingredients</button>
      </form>

      {error && <div className="error">{error}</div>}

      {result && (
        <div>
          <h3>Analysis Results:</h3>
          <p>Vegan: {result.data.vegan ? "Yes" : "No"}</p>
          {result.data.not_vegan.length > 0 && (
            <p>Non-vegan ingredients: {result.data.not_vegan.join(", ")}</p>
          )}
          {result.data.maybe_not_vegan.length > 0 && (
            <p>
              Potentially non-vegan: {result.data.maybe_not_vegan.join(", ")}
            </p>
          )}
        </div>
      )}
    </div>
  );
};

export default IngredientsChecker;

Vue Example

<template>
  <div>
    <form @submit.prevent="checkIngredients">
      <input
        v-model="ingredients"
        placeholder="Enter ingredients (comma-separated)"
      />
      <button type="submit">Check</button>
    </form>

    <div v-if="error" class="error">{{ error }}</div>

    <div v-if="result">
      <h3>Analysis Results:</h3>
      <p>Vegan Status: {{ result.data.vegan ? "Vegan" : "Not Vegan" }}</p>
      <p v-if="result.data.not_vegan.length">
        Non-vegan ingredients: {{ result.data.not_vegan.join(", ") }}
      </p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import Veganify, { ValidationError } from "@frontendnetwork/veganify";

const veganify = Veganify.getInstance();
const ingredients = ref("");
const result = ref(null);
const error = ref("");

async function checkIngredients() {
  try {
    result.value = await veganify.checkIngredientsListV1(ingredients.value);
    error.value = "";
  } catch (e) {
    result.value = null;
    if (e instanceof ValidationError) {
      error.value = "Please enter valid ingredients";
    } else {
      error.value = "An error occurred while checking ingredients";
    }
  }
}
</script>

Advanced Features

Caching

The package includes a built-in TTL + LRU cache. Each API method (product, ingredients, PETA brands) maintains its own cache bucket:

const veganify = Veganify.getInstance({
  cacheTTL: 1800000,  // 30 minutes TTL (set to 0 to disable)
  cacheMaxSize: 200,  // Evict least-recently-used entry when > 200 items
});

// Clear all cache buckets at any time
veganify.clearCache();

// The next call will fetch fresh data
const product = await veganify.getProductByBarcode("4066600204404");

Timeout

All requests are automatically cancelled after a configurable timeout:

const veganify = Veganify.getInstance({ timeout: 5000 }); // 5 s

try {
  const result = await veganify.checkIngredientsListV1("water,sugar");
} catch (error) {
  if (error instanceof VeganifyError && error.statusCode === 408) {
    console.error("Request timed out");
  }
}

Resetting the Singleton

Veganify uses a singleton pattern — getInstance() always returns the same object. Use resetInstance() to tear down the singleton so the next call creates a fresh one with new configuration. This is particularly useful in tests and server-side lifecycle code:

import Veganify from "@frontendnetwork/veganify";

// In tests — reset between each test case
afterEach(() => {
  Veganify.resetInstance();
});

it("uses short TTL", async () => {
  const veganify = Veganify.getInstance({ cacheTTL: 100 });
  // ...
});

Ingredient Preprocessing

The package exports a utility function that cleans and standardizes ingredient lists for analysis.

Parameters:

• ingredientsList: Raw ingredient list string

Returns:

An array of cleaned and normalized ingredient names

import { preprocessIngredients } from "@frontendnetwork/veganify";

const cleanIngredients = preprocessIngredients(
  "water 100%, sugar (organic), salt:"
);
// Result: ['water', 'sugar', 'organic', 'salt']

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © FrontEndNet.work, Philip Brembeck