batteryincluded 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Frederik Bußmann
+
+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.
+
+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,119 @@
+<p align="center">
+  <picture>
+    <img src="https://batteryincluded.ai/wp-content/uploads/2026/04/full-logo-compact-4c-header.webp" alt="BatteryIncluded" width="290">
+  </picture>
+</p>
+
+# 🔋 BatteryIncluded TypeScript SDK
+
+[![Github Actions][github-actions-src]][github-actions-href]
+[![NPM version][npm-version-src]][npm-version-href]
+[![NPM last update][npm-last-update-src]][npm-last-update-href]
+[![License][license-src]][license-href]
+
+An unofficial TypeScript SDK for [BatteryIncluded](https://batteryincluded.ai), the AI-infrastructure for E-Commerce search.
+Provides type-safe access to the BatteryIncluded API for search, filters, recommendations and more.
+
+## Installation
+
+```sh
+npm install batteryincluded
+```
+
+## Usage
+
+1. Create a .env file in the root of your project with the following content:
+
+```
+BATTERYINCLUDED_COLLECTION=your-collection-name
+BATTERYINCLUDED_API_KEY=your-api-key
+```
+
+2. Run the CLI to generate types based on your collection schema:
+
+```sh
+npx batteryincluded ./path/to/output/dir
+```
+
+3. Use the client with full type safety:
+
+```typescript
+import { createClient } from 'batteryincluded'
+
+const client = createClient({
+  collection: 'your-collection-name',
+  apiKey: 'your-api-key',
+})
+
+const { data, error } = await client.GET('/browse', {
+  params: {
+    query: {
+      page: 1,
+      per_page: 20,
+    }
+  }
+})
+
+// Fully typed response data
+console.log(data)
+```
+
+> Make sure the output directory is included in your TypeScript project's `tsconfig.json` under the `include` array to ensure the generated types are available for import.
+
+## Available Endpoints
+
+The SDK provides type-safe access to the following BatteryIncluded API endpoints:
+
+- `/browse`: Search endpoint for retrieving documents.
+- `/highlights`: Endpoint for retrieving query highlights.
+- `/suggest`: Endpoint for getting search suggestions based on a text query.
+- `/recommendations`: Endpoint for getting product recommendations based on a document ID.
+- `/recommendations/cart`: Endpoint for getting product recommendations based on a cart ID.
+- `/similar-search`: Endpoint for finding similar products based on a text query.
+- `/presets`: Endpoint for retrieving available search presets.
+
+## Type Generation
+
+The SDK includes a CLI tool that generates TypeScript types based on the responses from your BatteryIncluded collection.
+This is a workaround to provide type safety for the API responses, as BatteryIncluded does not currently provide an OpenAPI schema.
+
+In order to generate the types for these endpoints, the CLI will attempt to discover the schema by making requests to the API. For the `/recommendations` endpoint, it requires a document ID to generate recommendations. If no document ID is provided via the `--recommendation-id` flag, the CLI will automatically fetch the first document from the `/browse` endpoint to use its ID for generating recommendation types.
+
+The query used for the `/suggest` and `/similar-search` endpoints can be customized using the `--suggest-query` flag, which defaults to 'a' to ensure it returns results for discovery.
+
+### Custom Probe Config
+
+The CLI also supports loading custom probe configurations from a `batteryincluded.config.{js,json,mjs}` file in your project. This allows you to specify additional endpoints or customize the discovery process. If no custom config is provided, the CLI will use a default configuration that includes the necessary endpoints for generating types for search, suggestions, and recommendations.
+
+```ts
+// batteryincluded.config.mjs
+import { defineCodegenConfig } from 'batteryincluded'
+
+export default defineCodegenConfig({
+  '/browse': {
+    query: {
+      page: 1,
+      // Load more documents for better schema discovery
+      per_page: 100,
+    },
+  },
+})
+```
+
+For more information on the code generator and how to customize the probe configuration, see the [AutoDisco](https://github.com/freb97/autodisco) documentation.
+
+## License
+
+Published under the [MIT License](https://github.com/freb97/autodisco/tree/main/LICENSE).
+
+[github-actions-src]: https://github.com/freb97/batteryincluded-ts/actions/workflows/test.yml/badge.svg
+[github-actions-href]: https://github.com/freb97/batteryincluded-ts/actions
+
+[npm-version-src]: https://img.shields.io/npm/v/batteryincluded-ts/latest.svg?style=flat&colorA=18181B&colorB=31C553
+[npm-version-href]: https://npmjs.com/package/batteryincluded-ts
+
+[npm-last-update-src]: https://img.shields.io/npm/last-update/batteryincluded-ts.svg?style=flat&colorA=18181B&colorB=31C553
+[npm-last-update-href]: https://npmjs.com/package/batteryincluded-ts
+
+[license-src]: https://img.shields.io/github/license/freb97/batteryincluded-ts.svg?style=flat&colorA=18181B&colorB=31C553
+[license-href]: https://github.com/freb97/batteryincluded-ts/tree/main/LICENSE

package/dist/_chunks/client.mjs

@@ -0,0 +1,10 @@
+import createOpenAPIClient from "openapi-fetch";
+const buildBaseUrl = (collection) => `https://api.batteryincluded.io/api/v1/collections/${collection}/documents`;
+const buildHeaders = (apiKey) => ({ "X-BI-API-KEY": apiKey });
+function createClient(config) {
+	return createOpenAPIClient({
+		baseUrl: buildBaseUrl(config.collection),
+		headers: buildHeaders(config.apiKey)
+	});
+}
+export { buildBaseUrl, buildHeaders, createClient };

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli/index.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { buildBaseUrl, buildHeaders, createClient } from "../_chunks/client.mjs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import process from "node:process";
+import discover from "autodisco";
+import { loadConfig } from "c12";
+import { defineCommand, runMain } from "citty";
+import defu from "defu";
+import { config } from "dotenv";
+const { parsed } = config({ quiet: true });
+const env = parsed ?? process.env;
+const COLLECTION = Object.entries(env).find(([key]) => key.endsWith("BATTERYINCLUDED_COLLECTION"))?.[1];
+const API_KEY = Object.entries(env).find(([key]) => key.endsWith("BATTERYINCLUDED_API_KEY"))?.[1];
+function buildAugmentationFile() {
+	return [
+		"import type { paths as generatedPaths, components as generatedComponents } from './openapi/types'",
+		"",
+		"declare module 'batteryincluded' {",
+		"  interface paths extends generatedPaths {}",
+		"  interface components extends generatedComponents {}",
+		"}",
+		"",
+		"export {}",
+		""
+	].join("\n");
+}
+runMain(defineCommand({
+	meta: {
+		name: "codegen",
+		description: "Generate OpenAPI Schema and TypeScript types for a BatteryIncluded collection."
+	},
+	args: {
+		outputDir: {
+			type: "positional",
+			description: "Location of the output directory.",
+			default: env.BATTERYINCLUDED_CODEGEN_OUTDIR ?? "batteryincluded/types",
+			required: false
+		},
+		collection: {
+			type: "string",
+			description: "The BatteryIncluded collection to use.",
+			default: COLLECTION,
+			required: false
+		},
+		apiKey: {
+			type: "string",
+			description: "The BatteryIncluded API key to use for authentication.",
+			default: API_KEY,
+			required: false
+		},
+		recommendationId: {
+			type: "string",
+			description: "The ID of the document to scan for generating recommendation types.",
+			required: false
+		},
+		suggestQuery: {
+			type: "string",
+			description: "The query for the suggestions to scan for generating suggestion types.",
+			required: false
+		}
+	},
+	run: async ({ args }) => {
+		if (!args.collection) throw new Error("Collection name is required. Please specify it using the --collection flag or set the BATTERYINCLUDED_COLLECTION environment variable.");
+		if (!args.apiKey) throw new Error("API key is required. Please specify it using the --api-key flag or set the BATTERYINCLUDED_API_KEY environment variable.");
+		const { config: resolved } = await loadConfig({
+			name: "batteryincluded",
+			cwd: process.cwd(),
+			rcFile: "batteryincluded-rc",
+			globalRc: false,
+			dotenv: false
+		});
+		let config = resolved ?? {};
+		const suggestQuery = args.suggestQuery ?? "a";
+		let recommendationId = args.recommendationId;
+		if (!recommendationId) recommendationId = await createClient({
+			collection: args.collection,
+			apiKey: args.apiKey
+		}).GET("/browse", { params: { query: { per_page: 1 } } }).then(({ data }) => data?.hits?.[0]?.document?.id);
+		if (!recommendationId) throw new Error("No document found in the collection to use for generating recommendation types. Please specify a document ID using the --recommendation-id flag or ensure that the collection contains at least one document.");
+		config = defu(config, {
+			"/browse": { query: {
+				page: 1,
+				per_page: 10
+			} },
+			"/highlights": {},
+			"/suggest": { query: { q: suggestQuery } },
+			"/recommendations": { query: { id: recommendationId } },
+			"/similar-search": { query: { q: suggestQuery } },
+			"/presets": {}
+		});
+		await discover({
+			baseUrl: buildBaseUrl(args.collection),
+			headers: buildHeaders(args.apiKey),
+			outputDir: args.outputDir,
+			generate: {
+				markdown: false,
+				openapi: { typescript: true }
+			},
+			probes: { get: { ...config } }
+		});
+		await writeFile(join(args.outputDir, "index.d.ts"), buildAugmentationFile(), "utf8");
+	}
+}));
+export {};

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import { ProbeConfig } from "autodisco";
+interface paths {}
+interface components {}
+type Suggest = components['schemas']['GetApiV1CollectionsDocumentsSuggest'];
+type Browse = components['schemas']['GetApiV1CollectionsDocumentsBrowse'];
+type Highlights = components['schemas']['GetApiV1CollectionsDocumentsHighlights'];
+type Recommendations = components['schemas']['GetApiV1CollectionsDocumentsRecommendations'];
+type SelectFacet = Extract<Browse['facet_counts'][number], {
+  type: 'select';
+}>;
+type RangeFacet = Extract<Browse['facet_counts'][number], {
+  type: 'range';
+}>;
+interface Filter {
+  field: string;
+  values: string[] | {
+    min?: string;
+    max?: string;
+  };
+}
+declare const buildBaseUrl: (collection: string) => string;
+declare const buildHeaders: (apiKey: string) => {
+  'X-BI-API-KEY': string;
+};
+declare function createClient<customPaths extends object = paths>(config: {
+  collection: string;
+  apiKey: string;
+}): import("openapi-fetch").Client<customPaths, `${string}/${string}`>;
+declare function defineCodegenConfig(config: Record<string, ProbeConfig | ProbeConfig[]>): Record<string, ProbeConfig | ProbeConfig[]>;
+export { type Browse, type Filter, type Highlights, type RangeFacet, type Recommendations, type SelectFacet, type Suggest, buildBaseUrl, buildHeaders, type components, createClient, defineCodegenConfig, type paths };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { buildBaseUrl, buildHeaders, createClient } from "./_chunks/client.mjs";
+function defineCodegenConfig(config) {
+	return config;
+}
+export { buildBaseUrl, buildHeaders, createClient, defineCodegenConfig };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "batteryincluded",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A TypeScript client for the BatteryIncluded API",
+  "author": "Frederik Bußmann <frederik@bussmann.io>",
+  "license": "MIT",
+  "repository": "freb97/batteryincluded",
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "batteryincluded": "dist/cli/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "obuild",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepack": "bun run build",
+    "release": "bun test && npm publish && git push --follow-tags",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "autodisco": "^2.0.5",
+    "c12": "^4.0.0-beta.5",
+    "citty": "^0.2.2",
+    "defu": "^6.1.7",
+    "dotenv": "^17.4.2",
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.0.0",
+    "@types/node": "^24",
+    "eslint": "^10.4.1",
+    "obuild": "^0.4.34",
+    "typescript": "^6.0.3"
+  }
+}