@halallens/halal-scanner 1.0.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 HalalLens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Attribution Requirement:
+- Any product, service, or derivative work using this Software must include
+  visible attribution to HalalLens (https://halallens.no) in user-facing
+  documentation or about screens.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <img src="assets/screenshot-hero.png" alt="Free Halal Scanner" width="600">
+
+  # Free Halal Scanner
+
+  **Check if any food ingredient is halal, haram, or mushbooh — instantly.**
+
+  [![npm](https://img.shields.io/npm/v/@halallens/halal-scanner?color=00A878&style=flat-square)](https://www.npmjs.com/package/@halallens/halal-scanner)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6?style=flat-square)](https://www.typescriptlang.org/)
+
+  [Live Demo](https://halallens-no.github.io/halal-scanner/) · [npm Package](https://www.npmjs.com/package/@halallens/halal-scanner) · [Full Web App](https://app.halallens.no)
+</div>
+
+---
+
+## What is this?
+
+A free, open-source npm package and demo UI for checking the halal status of food ingredients. Powered by the [HalalLens](https://halallens.no) API — a database of 10,000+ ingredients analyzed by AI and verified by the community.
+
+### Features
+
+- **Instant search** — Type any ingredient name or E-number
+- **Halal status** — HALAL, HARAM, MUSHBOOH, or UNKNOWN with confidence scores
+- **AI explanations** — Understand *why* an ingredient has its status
+- **TypeScript support** — Full type definitions included
+- **Zero dependencies** — Uses native `fetch`, works in Node.js 18+ and all modern browsers
+- **Free forever** — No API key required
+
+## Try it
+
+**[Live Demo →](https://halallens-no.github.io/halal-scanner/)**
+
+<img src="assets/screenshot-results.png" alt="Search Results" width="600">
+
+## Install
+
+```bash
+npm install @halallens/halal-scanner
+```
+
+## Usage
+
+```typescript
+import { HalalScanner } from '@halallens/halal-scanner';
+
+const scanner = new HalalScanner();
+
+// Search for ingredients
+const results = await scanner.search('gelatin');
+console.log(results.items[0].halal_status); // "HARAM"
+console.log(results.items[0].display_status); // "Verified HARAM"
+
+// Get detailed ingredient info
+const detail = await scanner.check('en', 'gelatin');
+console.log(detail.explanation);
+console.log(detail.food_source); // "Animal"
+
+// Batch analyze multiple ingredients
+const analysis = await scanner.analyze(['gelatin', 'sugar', 'E471']);
+console.log(`${analysis.halal_count} halal, ${analysis.haram_count} haram`);
+```
+
+## API
+
+### `new HalalScanner(options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | `https://halallens.no/api` | API base URL |
+| `deviceId` | `string` | Auto-generated | Device ID for usage tracking |
+| `timeout` | `number` | `10000` | Request timeout in ms |
+
+### `scanner.search(query, params?)`
+
+Search for ingredients by name or E-number.
+
+```typescript
+const results = await scanner.search('E471', { perPage: 5 });
+```
+
+### `scanner.check(lang, name)`
+
+Get detailed info about a specific ingredient.
+
+```typescript
+const info = await scanner.check('en', 'sugar');
+```
+
+### `scanner.analyze(ingredients)`
+
+Analyze multiple ingredients at once.
+
+```typescript
+const result = await scanner.analyze(['sugar', 'gelatin', 'citric acid']);
+```
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `HALAL` | Permissible to consume |
+| `HARAM` | Not permissible to consume |
+| `MUSHBOOH` | Doubtful — depends on source or processing |
+| `UNKNOWN` | Not yet analyzed |
+
+## Want more?
+
+This package provides ingredient lookup. For the **full experience**:
+
+- **Scan product labels** with your camera (OCR-powered)
+- **AI-powered analysis** of entire ingredient lists
+- **Multi-language support** in 14+ languages
+- **Mobile apps** for Android and iOS
+
+**[Try HalalLens →](https://app.halallens.no)**
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR.
+
+## License
+
+[MIT](LICENSE) — Free to use with attribution to [HalalLens](https://halallens.no).
+
+---
+
+<div align="center">
+  <sub>Built with care by <a href="https://halallens.no">HalalLens</a> — AI-powered halal food verification</sub>
+</div>

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+/** Halal status of an ingredient */
+type HalalStatus = 'HALAL' | 'HARAM' | 'MUSHBOOH' | 'UNKNOWN' | 'NOT_FOOD';
+/** Data source for the status determination */
+type IngredientSource = 'database' | 'llm' | 'manual' | 'cache';
+/** Scanner configuration options */
+interface ScannerOptions {
+    /** API base URL. Defaults to https://halallens.no/api */
+    baseUrl?: string;
+    /** Device ID for usage tracking. Auto-generated if not provided. */
+    deviceId?: string;
+    /** Request timeout in milliseconds. Defaults to 10000. */
+    timeout?: number;
+}
+interface SearchParams {
+    /** Search query text */
+    query: string;
+    /** Filter by halal status */
+    status?: HalalStatus;
+    /** Filter by category */
+    category?: string;
+    /** Language code (ISO 639-1). Defaults to "en". */
+    language?: string;
+    /** Only return verified ingredients */
+    verifiedOnly?: boolean;
+    /** Only return E-numbers */
+    eNumber?: boolean;
+    /** Page number. Defaults to 1. */
+    page?: number;
+    /** Results per page. Defaults to 20, max 100. */
+    perPage?: number;
+}
+interface SearchResult {
+    items: IngredientSummary[];
+    total: number;
+    page: number;
+    per_page: number;
+    pages: number;
+    language_matches: LanguageMatch[];
+    fuzzy_suggestions: FuzzySuggestion[];
+}
+interface IngredientSummary {
+    id: number;
+    name: string;
+    category: string | null;
+    language_code: string;
+    halal_status: HalalStatus;
+    display_status: string;
+    status_verified: boolean;
+    status_color: string;
+    image_url: string | null;
+    has_grounding: boolean;
+    has_elaborated_explanation: boolean;
+    is_gemini_enriched: boolean;
+    ai_review: AIReviewSummary | null;
+    similar_items: SimilarItem[];
+}
+interface AIReviewSummary {
+    ai_review_count: number;
+    agreement_percentage: number;
+    consensus_status: HalalStatus | null;
+    consensus_confidence: number | null;
+    analyzed_at: string | null;
+    opinions: AIOpinion[];
+    show_all_opinions: boolean;
+}
+interface AIOpinion {
+    halal_status: HalalStatus;
+    confidence: number;
+    explanation: string;
+    food_source: string | null;
+}
+interface SimilarItem {
+    id: number;
+    name: string;
+    halal_status: HalalStatus;
+    status_verified: boolean;
+    status_color: string;
+    ai_review_count: number;
+}
+interface LanguageMatch {
+    language_code: string;
+    language_name: string;
+    match_count: number;
+}
+interface FuzzySuggestion {
+    id: number;
+    name: string;
+    halal_status: HalalStatus;
+    display_status: string;
+    status_color: string;
+    similarity: number;
+}
+interface IngredientDetail extends IngredientSummary {
+    explanation: string | null;
+    food_source: string | null;
+    verified_at: string | null;
+    verification_notes: string | null;
+    translations: IngredientTranslation[];
+    explanation_language: string;
+    translation_available: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface IngredientTranslation {
+    language_code: string;
+    translated_name: string;
+    is_validated: boolean;
+}
+interface AnalyzeResult {
+    queue_id: string | null;
+    status: 'pending' | 'processing' | 'completed' | 'error';
+    ingredients: AnalyzedIngredient[];
+    total_count: number;
+    halal_count: number;
+    haram_count: number;
+    mushbooh_count: number;
+    unknown_count: number;
+    completion_percentage: number;
+    error: string | null;
+}
+interface AnalyzedIngredient {
+    ocr_item_id: string | null;
+    ingredient_id: number | null;
+    original_text: string;
+    display_name: string;
+    source_language: string;
+    halal_status: HalalStatus;
+    confidence: number;
+    source: IngredientSource;
+    explanation: string | null;
+    image_url: string | null;
+    is_verified: boolean;
+    has_grounding: boolean;
+}
+
+declare class HalalScanner {
+    private readonly baseUrl;
+    private readonly deviceId;
+    private readonly timeout;
+    constructor(options?: ScannerOptions);
+    /**
+     * Search for ingredients by name.
+     *
+     * @example
+     * const results = await scanner.search('gelatin');
+     * console.log(results.items[0].halal_status); // "HARAM"
+     */
+    search(query: string, params?: Partial<SearchParams>): Promise<SearchResult>;
+    /**
+     * Get detailed information about a specific ingredient.
+     *
+     * @param lang - Language code (e.g., "en", "ar", "no")
+     * @param name - Ingredient URL slug (e.g., "gelatin", "sugar")
+     *
+     * @example
+     * const detail = await scanner.check('en', 'gelatin');
+     * console.log(detail.explanation);
+     */
+    check(lang: string, name: string): Promise<IngredientDetail>;
+    /**
+     * Analyze a list of ingredients for halal status.
+     *
+     * @param ingredients - Array of ingredient names to check
+     *
+     * @example
+     * const result = await scanner.analyze(['gelatin', 'sugar', 'E471']);
+     * console.log(`${result.halal_count} halal, ${result.haram_count} haram`);
+     */
+    analyze(ingredients: string[]): Promise<AnalyzeResult>;
+    private request;
+}
+
+declare class HalalScannerError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly endpoint?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, endpoint?: string | undefined);
+}
+declare class RateLimitError extends HalalScannerError {
+    constructor(endpoint: string);
+}
+declare class NetworkError extends HalalScannerError {
+    constructor(message: string, endpoint: string);
+}
+
+export { type AIOpinion, type AIReviewSummary, type AnalyzeResult, type AnalyzedIngredient, type FuzzySuggestion, HalalScanner, HalalScannerError, type HalalStatus, type IngredientDetail, type IngredientSource, type IngredientSummary, type IngredientTranslation, type LanguageMatch, NetworkError, RateLimitError, type ScannerOptions, type SearchParams, type SearchResult, type SimilarItem };

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+/** Halal status of an ingredient */
+type HalalStatus = 'HALAL' | 'HARAM' | 'MUSHBOOH' | 'UNKNOWN' | 'NOT_FOOD';
+/** Data source for the status determination */
+type IngredientSource = 'database' | 'llm' | 'manual' | 'cache';
+/** Scanner configuration options */
+interface ScannerOptions {
+    /** API base URL. Defaults to https://halallens.no/api */
+    baseUrl?: string;
+    /** Device ID for usage tracking. Auto-generated if not provided. */
+    deviceId?: string;
+    /** Request timeout in milliseconds. Defaults to 10000. */
+    timeout?: number;
+}
+interface SearchParams {
+    /** Search query text */
+    query: string;
+    /** Filter by halal status */
+    status?: HalalStatus;
+    /** Filter by category */
+    category?: string;
+    /** Language code (ISO 639-1). Defaults to "en". */
+    language?: string;
+    /** Only return verified ingredients */
+    verifiedOnly?: boolean;
+    /** Only return E-numbers */
+    eNumber?: boolean;
+    /** Page number. Defaults to 1. */
+    page?: number;
+    /** Results per page. Defaults to 20, max 100. */
+    perPage?: number;
+}
+interface SearchResult {
+    items: IngredientSummary[];
+    total: number;
+    page: number;
+    per_page: number;
+    pages: number;
+    language_matches: LanguageMatch[];
+    fuzzy_suggestions: FuzzySuggestion[];
+}
+interface IngredientSummary {
+    id: number;
+    name: string;
+    category: string | null;
+    language_code: string;
+    halal_status: HalalStatus;
+    display_status: string;
+    status_verified: boolean;
+    status_color: string;
+    image_url: string | null;
+    has_grounding: boolean;
+    has_elaborated_explanation: boolean;
+    is_gemini_enriched: boolean;
+    ai_review: AIReviewSummary | null;
+    similar_items: SimilarItem[];
+}
+interface AIReviewSummary {
+    ai_review_count: number;
+    agreement_percentage: number;
+    consensus_status: HalalStatus | null;
+    consensus_confidence: number | null;
+    analyzed_at: string | null;
+    opinions: AIOpinion[];
+    show_all_opinions: boolean;
+}
+interface AIOpinion {
+    halal_status: HalalStatus;
+    confidence: number;
+    explanation: string;
+    food_source: string | null;
+}
+interface SimilarItem {
+    id: number;
+    name: string;
+    halal_status: HalalStatus;
+    status_verified: boolean;
+    status_color: string;
+    ai_review_count: number;
+}
+interface LanguageMatch {
+    language_code: string;
+    language_name: string;
+    match_count: number;
+}
+interface FuzzySuggestion {
+    id: number;
+    name: string;
+    halal_status: HalalStatus;
+    display_status: string;
+    status_color: string;
+    similarity: number;
+}
+interface IngredientDetail extends IngredientSummary {
+    explanation: string | null;
+    food_source: string | null;
+    verified_at: string | null;
+    verification_notes: string | null;
+    translations: IngredientTranslation[];
+    explanation_language: string;
+    translation_available: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface IngredientTranslation {
+    language_code: string;
+    translated_name: string;
+    is_validated: boolean;
+}
+interface AnalyzeResult {
+    queue_id: string | null;
+    status: 'pending' | 'processing' | 'completed' | 'error';
+    ingredients: AnalyzedIngredient[];
+    total_count: number;
+    halal_count: number;
+    haram_count: number;
+    mushbooh_count: number;
+    unknown_count: number;
+    completion_percentage: number;
+    error: string | null;
+}
+interface AnalyzedIngredient {
+    ocr_item_id: string | null;
+    ingredient_id: number | null;
+    original_text: string;
+    display_name: string;
+    source_language: string;
+    halal_status: HalalStatus;
+    confidence: number;
+    source: IngredientSource;
+    explanation: string | null;
+    image_url: string | null;
+    is_verified: boolean;
+    has_grounding: boolean;
+}
+
+declare class HalalScanner {
+    private readonly baseUrl;
+    private readonly deviceId;
+    private readonly timeout;
+    constructor(options?: ScannerOptions);
+    /**
+     * Search for ingredients by name.
+     *
+     * @example
+     * const results = await scanner.search('gelatin');
+     * console.log(results.items[0].halal_status); // "HARAM"
+     */
+    search(query: string, params?: Partial<SearchParams>): Promise<SearchResult>;
+    /**
+     * Get detailed information about a specific ingredient.
+     *
+     * @param lang - Language code (e.g., "en", "ar", "no")
+     * @param name - Ingredient URL slug (e.g., "gelatin", "sugar")
+     *
+     * @example
+     * const detail = await scanner.check('en', 'gelatin');
+     * console.log(detail.explanation);
+     */
+    check(lang: string, name: string): Promise<IngredientDetail>;
+    /**
+     * Analyze a list of ingredients for halal status.
+     *
+     * @param ingredients - Array of ingredient names to check
+     *
+     * @example
+     * const result = await scanner.analyze(['gelatin', 'sugar', 'E471']);
+     * console.log(`${result.halal_count} halal, ${result.haram_count} haram`);
+     */
+    analyze(ingredients: string[]): Promise<AnalyzeResult>;
+    private request;
+}
+
+declare class HalalScannerError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly endpoint?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, endpoint?: string | undefined);
+}
+declare class RateLimitError extends HalalScannerError {
+    constructor(endpoint: string);
+}
+declare class NetworkError extends HalalScannerError {
+    constructor(message: string, endpoint: string);
+}
+
+export { type AIOpinion, type AIReviewSummary, type AnalyzeResult, type AnalyzedIngredient, type FuzzySuggestion, HalalScanner, HalalScannerError, type HalalStatus, type IngredientDetail, type IngredientSource, type IngredientSummary, type IngredientTranslation, type LanguageMatch, NetworkError, RateLimitError, type ScannerOptions, type SearchParams, type SearchResult, type SimilarItem };

package/dist/index.js

@@ -0,0 +1,173 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HalalScanner: () => HalalScanner,
+  HalalScannerError: () => HalalScannerError,
+  NetworkError: () => NetworkError,
+  RateLimitError: () => RateLimitError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HalalScannerError = class extends Error {
+  constructor(message, statusCode, endpoint) {
+    super(message);
+    this.statusCode = statusCode;
+    this.endpoint = endpoint;
+    this.name = "HalalScannerError";
+  }
+};
+var RateLimitError = class extends HalalScannerError {
+  constructor(endpoint) {
+    super("Rate limit exceeded. Please wait before making more requests.", 429, endpoint);
+    this.name = "RateLimitError";
+  }
+};
+var NetworkError = class extends HalalScannerError {
+  constructor(message, endpoint) {
+    super(`Network error: ${message}`, void 0, endpoint);
+    this.name = "NetworkError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://halallens.no/api";
+var DEFAULT_TIMEOUT = 1e4;
+function generateDeviceId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id = "hs-";
+  for (let i = 0; i < 16; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+var HalalScanner = class {
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.deviceId = options.deviceId || generateDeviceId();
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Search for ingredients by name.
+   *
+   * @example
+   * const results = await scanner.search('gelatin');
+   * console.log(results.items[0].halal_status); // "HARAM"
+   */
+  async search(query, params = {}) {
+    const searchParams = new URLSearchParams({ search: query });
+    if (params.status) searchParams.set("status", params.status);
+    if (params.category) searchParams.set("category", params.category);
+    if (params.language) searchParams.set("language", params.language);
+    if (params.verifiedOnly) searchParams.set("verified_only", "true");
+    if (params.eNumber) searchParams.set("e_number", "true");
+    if (params.page) searchParams.set("page", String(params.page));
+    if (params.perPage) searchParams.set("per_page", String(params.perPage));
+    return this.request(
+      `/v1/public/ingredients?${searchParams.toString()}`
+    );
+  }
+  /**
+   * Get detailed information about a specific ingredient.
+   *
+   * @param lang - Language code (e.g., "en", "ar", "no")
+   * @param name - Ingredient URL slug (e.g., "gelatin", "sugar")
+   *
+   * @example
+   * const detail = await scanner.check('en', 'gelatin');
+   * console.log(detail.explanation);
+   */
+  async check(lang, name) {
+    return this.request(
+      `/v1/public/ingredients/${encodeURIComponent(lang)}/${encodeURIComponent(name)}`
+    );
+  }
+  /**
+   * Analyze a list of ingredients for halal status.
+   *
+   * @param ingredients - Array of ingredient names to check
+   *
+   * @example
+   * const result = await scanner.analyze(['gelatin', 'sugar', 'E471']);
+   * console.log(`${result.halal_count} halal, ${result.haram_count} haram`);
+   */
+  async analyze(ingredients) {
+    return this.request("/v1/queue/ingredients/json", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ingredients: ingredients.map((name) => ({
+          name,
+          halal_status: "UNKNOWN",
+          language: "en",
+          confidence: 0
+        })),
+        device_id: this.deviceId
+      })
+    });
+  }
+  async request(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          Accept: "application/json",
+          ...init?.headers
+        }
+      });
+      if (response.status === 429) {
+        throw new RateLimitError(path);
+      }
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new HalalScannerError(
+          text || `HTTP ${response.status}`,
+          response.status,
+          path
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof HalalScannerError) throw error;
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new NetworkError("Request timed out", path);
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Unknown error",
+        path
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HalalScanner,
+  HalalScannerError,
+  NetworkError,
+  RateLimitError
+});

package/dist/index.mjs

@@ -0,0 +1,143 @@
+// src/errors.ts
+var HalalScannerError = class extends Error {
+  constructor(message, statusCode, endpoint) {
+    super(message);
+    this.statusCode = statusCode;
+    this.endpoint = endpoint;
+    this.name = "HalalScannerError";
+  }
+};
+var RateLimitError = class extends HalalScannerError {
+  constructor(endpoint) {
+    super("Rate limit exceeded. Please wait before making more requests.", 429, endpoint);
+    this.name = "RateLimitError";
+  }
+};
+var NetworkError = class extends HalalScannerError {
+  constructor(message, endpoint) {
+    super(`Network error: ${message}`, void 0, endpoint);
+    this.name = "NetworkError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://halallens.no/api";
+var DEFAULT_TIMEOUT = 1e4;
+function generateDeviceId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id = "hs-";
+  for (let i = 0; i < 16; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+var HalalScanner = class {
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.deviceId = options.deviceId || generateDeviceId();
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Search for ingredients by name.
+   *
+   * @example
+   * const results = await scanner.search('gelatin');
+   * console.log(results.items[0].halal_status); // "HARAM"
+   */
+  async search(query, params = {}) {
+    const searchParams = new URLSearchParams({ search: query });
+    if (params.status) searchParams.set("status", params.status);
+    if (params.category) searchParams.set("category", params.category);
+    if (params.language) searchParams.set("language", params.language);
+    if (params.verifiedOnly) searchParams.set("verified_only", "true");
+    if (params.eNumber) searchParams.set("e_number", "true");
+    if (params.page) searchParams.set("page", String(params.page));
+    if (params.perPage) searchParams.set("per_page", String(params.perPage));
+    return this.request(
+      `/v1/public/ingredients?${searchParams.toString()}`
+    );
+  }
+  /**
+   * Get detailed information about a specific ingredient.
+   *
+   * @param lang - Language code (e.g., "en", "ar", "no")
+   * @param name - Ingredient URL slug (e.g., "gelatin", "sugar")
+   *
+   * @example
+   * const detail = await scanner.check('en', 'gelatin');
+   * console.log(detail.explanation);
+   */
+  async check(lang, name) {
+    return this.request(
+      `/v1/public/ingredients/${encodeURIComponent(lang)}/${encodeURIComponent(name)}`
+    );
+  }
+  /**
+   * Analyze a list of ingredients for halal status.
+   *
+   * @param ingredients - Array of ingredient names to check
+   *
+   * @example
+   * const result = await scanner.analyze(['gelatin', 'sugar', 'E471']);
+   * console.log(`${result.halal_count} halal, ${result.haram_count} haram`);
+   */
+  async analyze(ingredients) {
+    return this.request("/v1/queue/ingredients/json", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ingredients: ingredients.map((name) => ({
+          name,
+          halal_status: "UNKNOWN",
+          language: "en",
+          confidence: 0
+        })),
+        device_id: this.deviceId
+      })
+    });
+  }
+  async request(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          Accept: "application/json",
+          ...init?.headers
+        }
+      });
+      if (response.status === 429) {
+        throw new RateLimitError(path);
+      }
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new HalalScannerError(
+          text || `HTTP ${response.status}`,
+          response.status,
+          path
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof HalalScannerError) throw error;
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new NetworkError("Request timed out", path);
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Unknown error",
+        path
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  HalalScanner,
+  HalalScannerError,
+  NetworkError,
+  RateLimitError
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@halallens/halal-scanner",
+  "version": "1.0.0",
+  "description": "Free halal food scanner - check ingredients instantly. Powered by HalalLens AI.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "halal",
+    "halal-scanner",
+    "food-scanner",
+    "ingredient-checker",
+    "halal-food",
+    "halal-checker",
+    "free",
+    "open-source",
+    "e-numbers",
+    "food-ingredients",
+    "halal-status",
+    "muslim",
+    "islamic",
+    "food-safety"
+  ],
+  "author": "HalalLens <mac@halallens.no> (https://halallens.no)",
+  "license": "MIT",
+  "homepage": "https://halallens.no",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halallens-no/halal-scanner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/halallens-no/halal-scanner/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}