file: ./content/docs/agent-bridge/index.mdx meta: { "title": "Getting Started", "description": "Get to know the project, philosophy and how to use it.", "icon": "Telescope" } ## Introduction AgentBridge protocol is a format designed to make APIs more accessible and understandable for AI agents. It enhances standard API specifications with: } title="AI-First Design"> Optimized for LLM consumption with clear, semantic descriptions } title="Flow-Oriented"> Focuses on complete workflows rather than isolated endpoints } title="Semantic Understanding"> Goes beyond syntax to capture the purpose of API operations ## Integrating into your projects AgentBridge comes with a CLI tool and a TypeScript client library, making integration plain and simple: file: ./content/docs/enterprise-commerce/architecture.mdx meta: { "title": "Architecture", "description": "A cheat sheet of e-commerce architecture regarding rendering strategies with caching strategies, A/B testing and personalization.", "icon": "Landmark" } import { BrandLink } from "@/components/brand-link" # Introduction The **rendering strategy terminology** referenced in this guide is derived specifically from the **Next.js** framework, summed up and posted on Vercel Community[^1] and are used in the 's Enterprise Commerce project. ## Rendering strategies | Term | Full Name | Rendering Strategy | Caching Strategy | A/B Testing or Personalization | | ------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **HP** | Home Page | **ISR**/**SSG**/**PPR** | **Static** | **ISR** variants above the fold and **CSR** below the fold or **PPR** | | **CLP** | Category Landing Page (products + CMS content) | **ISR**/**SSG**/**PPR** | **Static** | **ISR** variants above the fold and **CSR** below the fold or **PPR** | | **PLP** | Product Landing Page (products only) | **ISR** for main categories with pagination **PPR**/**CSR**/**SSR**/**ISR** for filtering/faceting/sorting | 1. **Static** for all SEO indexable URL
2. **Dynamic** for the faceting/filtering/sorting and long tail pagination | Ideally **PPR**/**ISR** variants for SEO indexable URLs. **CSR**/**SSR** for long tail | | **SRP** | Search Results Page | **SSR**/**ISR**/**CSR** | **Dynamic** | **PPR** or **CSR** | | **PDP** | Product Details Page | Pareto rule 80/20. **SSG** for the bestsellers. **ISR** for the long tail. | 1. **Static** for above the fold line
2. **Dynamic** below the fold line | **ISR** variants above the fold and **CSR** below the fold or **PPR** | A **Category Landing Page (CLP)** is a *key category page* that users commonly land on while browsing an e-commerce site. These pages are **shareable** and **indexable by Google**, hence the term *“Landing Page.”* **CLPs** are often *manually curated*, *enriched with CMS content*, and represent *top-level categories* or *special landing pages*. They are usually *linked in the Mega Navigation bar* to facilitate better browsing. CLPs are *designed to load quickly* with **SEO-friendly URLs** and can include a mix of *manually curated content* and *automatically generated product listings*. In contrast, a **Product Listing Page (PLP)** is a *purely automated page* that lists products from the database *without any additional CMS content*. **PLPs** offer features like *filtering*, *sorting*, and *pagination*, and their URLs may include *query strings* for these options. PLPs may or may not be **SEO indexable**, depending on the setup. [^1]: [Post 'Enterprise e-commerce migration cheat-sheet: essential terms and definitions' by Dom Sipowicz on Vercel Community](https://community.vercel.com/t/enterprise-e-commerce-migration-cheat-sheet-essential-terms-and-definitions/586) file: ./content/docs/enterprise-commerce/glossary.mdx meta: { "title": "Technical glossary", "description": "A glossary and cheat sheet of terminology used in the e-commerce technical documentation.", "icon": "Book" } # Introduction This **cheat sheet** offers a comprehensive overview of *key terms* and *definitions* essential for **enterprise e-commerce understanding**. ## Origin of the terminology Although the terminology originates from the e-commerce sector, it is **equally applicable** to related projects such as *product directories* - where features like **“add to favorites”** may replace traditional basket and checkout systems - or to any directory-based application involving **classifications, categories, hierarchical structures, searching, filtering, sorting,** and **pagination**. | Term | Definition | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ISR** | **Incremental Static Generation** (on build and runtime phase) | | **CSR** | **Client Side Rendering** (in the browser) | | **SSR** | **Server Side Rendering** (on the server, on runtime phase, on each request) | | **SSG** | **Static Site Generation** (on build phase) | | **PPR** | **Partial Prerendering** - a combination of static and dynamic. The best of both worlds. It's *still* an experimental feature of Next.js. | | **static** | Cached document on CDN like HTML output (uses only bandwidth) | | **dynamic** | Document rendered dynamically on the request (uses compute) | | **long tail** | Less frequently accessed pages or content that are typically generated dynamically at the time of the request, often using **SSR** or **ISR** to optimize compute resources. | | **above the fold line** | The visible part of a webpage without scrolling, critical for **SEO** and **Core Web Vitals**, as optimizing it enhances **UX** and load times. | | **below the fold line** | The part of a webpage that is only visible after scrolling, may contain CSR, media players or other things that can be lazily loaded | file: ./content/docs/enterprise-commerce/index.mdx meta: { "title": "Getting started", "icon": "Telescope", "description": "Introduction to open source enterprise-grade e-commerce platform with Headless Next.js, Algolia middle layer and Shopify backend" } import { ZoomInIcon } from "lucide-react" import { BrandLink } from "@/components/brand-link" # Introduction Enterprise E-Commerce by is a open source enterprise-grade template of a Next.js project using as the e-commerce platform (product data, categories) and as the middle layer (data fetching, searching, faceting and recommendations). This documentation serves purpose of explaining our architectural decisions, containing in-details features descriptions and read-worthy guidelines. Everything with focus on the business values and theirs impact on the implementations. ## Philosophy & motivation Building e-commerce platform is a tough topic. Creating one that has all the features that enterprise companies want is hard, way harder than implementing Headless CMS. There are bunch of templates out there that struggle with couple areas, while they may be a great choice for a small or medium-sized businesses, the huge needs for e.g. crawling budget optimization, SEO, excellent browsing journey, simplicity of the implementation are way more than can be expected from other projects. ### The browsing journey A monolithic commerce platform will never beat the speed of a fast-lookup system like , Constructor, or other enterprise search systems. What if you cache your platform's responses? Even still, the combinatorics of search terms, filters, and sort options create endless unique queries. A fast source-of-truth is table-stakes for speedy browsing UX. #### Architecture diagram Simple, winning e-commerce architecture. Take a closer look at the arrow colors as they represent the times between high-level user's browsing journey interactions and network latencies in the lower level.  ### Features import {Search, Folders, Workflow, Image, Cable, Keyboard, Brain, ChartArea, BrickWallFire, Gauge} from "lucide-react" } title="Hierarchical categories"> Out of the box support for hierarchical product categories, with simplicity of an implementation. Even for platforms that does not support hierarchical categories by default. } title="Fast search"> Sub-15ms search, filters, sort and pagination experience, even when traversing through the tens ofthousands of products with loads of metadata and variants. } title="Mega Nav"> MegaNav module with ISR updates on-the-fly. } title="Rendering and caching"> Carefully picked Next.js rendering strategies for crucial pages; HP, CLP, PLP, PDP, SRP. Implemented with ability to scale indefinitely, optimized for SEO and excellent user browsing journey experience. } title="Analytics"> Uncomplicated analytics implementation. Vercel Analytics, Google Analytics or any other - you choose. } title="Enterprise-grade Redirects"> Redirects setup that can handle 50k+ or more redirects without lookup overhead. Implemented using the bloom-filters structure it ensures the reliability of high-scale of your operations. } title="Performance"> Perfect Core Web Vitals scores. Instant-navigation browsing journey without compromises. file: ./content/docs/enterprise-commerce/setup.mdx meta: { "title": "Setup & Configuration", "description": "Technical setup guide for Enterprise Commerce starter", "icon": "Settings" } import { Step, Steps } from "fumadocs-ui/components/steps"; import { BrandLink } from "@/components/brand-link"; # Introduction This guide covers the technical configuration steps for Enterprise Commerce starter by . Follow these instructions to properly set up search, redirects, and make the codebase ready to launch. As you will see throughout this guide, the `.env.local` file is used to configure the environment variables, which are the **source of truth** for the features and settings. If something happens to be not working, it is very likely that the environment variables are not set correctly ## Clone the repository Using Git via HTTPS: ```bash git clone https://github.com/blazity/enterprise-commerce.git && cd enterprise-commerce/starters/shopify-algolia ``` or using GitHub CLI: ```bash gh repo clone blazity/enterprise-commerce && cd enterprise-commerce/starters/shopify-algolia ``` Install the dependencies ``` yarn ``` ## Shopify is our source for all the product data and e-commerce platform of our choice. ### Shopify environment variables ```bash SHOPIFY_STORE_DOMAIN SHOPIFY_STOREFRONT_ACCESS_TOKEN SHOPIFY_ADMIN_ACCESS_TOKEN SHOPIFY_APP_API_SECRET_KEY ``` Below you will see steps to find the environment variables for your store that are crucial for the starter to work. #### Shopify Store Domain * **Variable required**: `SHOPIFY_STORE_DOMAIN` * **How to obtain it**: Your store domain is the URL of your store. You can obtain it in dashboard, it should be without https and / at the end of the string. Example: cool-socks.myshopify.com #### Headless App * **Variable Required:** `SHOPIFY_STOREFRONT_ACCESS_TOKEN` * **Installation and Configuration:** 1. Visit the Marketplace and search for the Headless commerce application or navigate directly to [https://apps.shopify.com/headless](https://apps.shopify.com/headless). 2. Install the application, open it, and create a new Storefront within the app. 3. In the "Manage API Access" section, click on the `Manage` button next to **Storefront API**. 4. Make sure you have enabled `unauthenticated_read_product_inventory` and `unauthenticated_read_customer_tags` scopes 5. Copy the **Private access token** displayed and place it in your `.env` file under `SHOPIFY_STOREFRONT_ACCESS_TOKEN`. #### Private Admin App * **Variables Required:** `SHOPIFY_ADMIN_ACCESS_TOKEN`, `SHOPIFY_APP_API_SECRET_KEY` * **Application Setup and Scopes Configuration:** 1. Go to the admin dashboard, navigate to Settings > `Apps and sales channels` > `Develop Apps`, and click on `Create app`. 2. After naming and creating your app, move to the `Configuration` tab. 3. In the "Admin API access scopes" section, click `Edit` and select the following scopes: * `write_product_listings` * `read_product_listings` * `read_products` * `write_products` 4. Under **Webhook subscriptions**, choose the `2024-01` API version. 5. Lastly, navigate to the `API Credentials` section. * Copy the **Admin API access token** and place it in your `.env.local` file under `SHOPIFY_ADMIN_ACCESS_TOKEN` #### Shopify App API Secret Key * **Variable required**: `SHOPIFY_APP_API_SECRET_KEY` * **How to obtain it**: 1. Launch the Terminal of your choice (e.g. [Ghostty](https://ghostty.org/) or [iTerm](https://iterm2.com/) or MacOS built-in Terminal) 2. Run the following command to generate the API secret key ```bash node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` 3. Copy the generated key and place it in your `.env.local` file under `SHOPIFY_APP_API_SECRET_KEY` ### Shopify Webhooks As serves as a source of truth for the product data but the direct requests are not made to its API from the storefront, you need to set up webhooks to correctly update and sync the data in the indices each time the product/category is updated in the . In order for the webhooks creation scripts to work, all -related environment variables need to be set in the root level of the `shopify-algolia` starter. Prepare your URL that project's API will be accessible publicly. It can be URL of a deployment from the dashboard. The script will handle appending the path of an `sync` endpoint to the domain If you're on localhost, we recommend using [ngrok](https://ngrok.com/) to expose your local server to the public internet. The URL will be passed to the webhooks creation script's `--domain=` argument. Run the webhooks creation script (assuming you've already cloned the repository and you're in the `starters/shopify-algolia` directory) ```bash yarn build:scripts && node scripts/dist/webhooks/setup-webhooks.mjs --domain=https://your-domain.com ``` and replace `https://your-domain.com` with your actual domain. ## Algolia ### Algolia environment variables ```bash ALGOLIA_APP_ID ALGOLIA_WRITE_API_KEY ALGOLIA_PRODUCTS_INDEX ALGOLIA_CATEGORIES_INDEX ALGOLIA_REVIEWS_INDEX ``` #### Algolia App ID * **Variable required**: `ALGOLIA_APP_ID` * **How to obtain it**: * Go to your dashboard * Click on "API Keys" * Copy the "Application ID" #### Algolia Write API Key * **Variable required**: `ALGOLIA_WRITE_API_KEY` * **How to obtain it**: * Go to your dashboard * Click on "API Keys" * Copy the "Write API Key" #### Algolia Indices * **Variable required**: `ALGOLIA_PRODUCTS_INDEX`, `ALGOLIA_CATEGORIES_INDEX`, `ALGOLIA_REVIEWS_INDEX` (optional) * **How to setup and obtain them**: * Products index 1. Go to your dashboard to the "Search" section 2. Click on "Index" dropdown and select "Create Index" at the bottom 3. Name it `products` 4. Copy the name of the index to your `.env.local` file under `ALGOLIA_PRODUCTS_INDEX` 5. Click on "Create" 6. Navigate to the "Configuration" tab of newly created index 7. Search for "Searchable attributes" (or `searchableAttributes`) 8. Add `handle`, `title`, `description`, `id` to the list of searchable attributes (it does not matter if they are marked as "ordered" or "unordered") 9. Search for "Attributes for faceting" (or `attributesForFaceting`) 10. Add every single attribute from this list to the ```json [ "collections.handle", "collections.id", "flatOptions.color", "handle", "minPrice", "tags", "variants.availableForSale", "vendor", "hierarchicalCategories.lvl0", "hierarchicalCategories.lvl1", "hierarchicalCategories.lvl2", "avgRating" ] ``` and mark all of them as "searchable" 11. Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else) * Categories index 1. Go to your dashboard to the "Search" section 2. Click on "Index" dropdown and select "Create Index" at the bottom 3. Name it `categories` 4. Copy the name of the index to your `.env.local` file under `ALGOLIA_CATEGORIES_INDEX` 5. Click on "Create" 6. Navigate to the "Configuration" tab of newly created index 7. Search for "Attributes for faceting" (or `attributesForFaceting`) 8. Add `handle` to the list of attributes for faceting (it does not mean if its marked as "searchable" or "not searchable") 9. Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else) * Reviews index (optional) * Go to your dashboard to the "Search" section * Click on "Index" dropdown and select "Create Index" at the bottom * Name it `reviews` * Copy the name of the index to your `.env.local` file under `ALGOLIA_REVIEWS_INDEX` * Click on "Create" * Navigate to the "Configuration" tab of newly created index * Search for "Searchable attributes" (or `searchableAttributes`) * Add `product_handle`, `body`, to the list of searchable attributes (it does not matter if they are marked as "ordered" or "unordered") * Search for "Attributes for faceting" (or `attributesForFaceting`) * Add `product_handle`, `body`, `hidden`, `published` to the list of attributes for faceting (it does not matter if they are marked as "searchable" or "not searchable") * Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else) ### Algolia Sorting Replicas If you followed the steps above, you should have 3 indices created in and all the environment variables set. Apart from that, you need to create 5 sorting replicas indices for products ```json {indexName}_price_desc {indexName}_price_asc {indexName}_rating_desc {indexName}_updated_asc {indexName}_updated_desc ``` Sorting replicas are not affecting the `.env.local` environment variables file. This lives only inside the dashboard. 1. Go to your dashboard to the "Search" section 2. Click on "Index" dropdown and select previously created `products` index 3. Go to the `Replicas` tab (near `Configuration` tab) 4. Click on `+ Create Replica index` 5. Name it the names from the list, e.g. `products_price_desc` (since our `indexName` is `products`) 6. Repeat adding the rest of the sorting replicas (you will see them marked as "Draft" in the UI) 7. Click on `Review and Save Settings` 8. Click on `Save Settings` in the modal (do not click anything else) 9. Go back to the dashboard to the "Search" section 10. Click on "Index" dropdown and select previously created `products` index 11. Go to each replica index from the list to theirs corresponding `Configuration` tab 12. Search for `Ranking and Sorting` 13. Add corresponding sorting rules and fields to each of the replicas (basing on their names), e.g. `products_price_desc` should have `minPrice` field and **Descending** sorting rule. Apart from `minPrice` field for this particular replica index from the example, the remaining fields of your interest for other replicas are: `avgRating`, `updatedAtTimestamp` ## Initial data sources synchronization After setting up the crucial environment variables and webhooks (everything from [](#algolia) and [](#shopify) sections), you can start the initial data sources synchronization. Run the data synchronization script (assuming you've already cloned the repository and you're in the `starters/shopify-algolia` directory) ```bash yarn build:scripts && node scripts/dist/sync/sync.mjs ``` The script may run for a while, depending on the size of your store. It will create the data inside the indices and sync the products & categories from to basing on calculated differences between the datasets. This script can also be used periodically in development environments if needed. ## Enterprise-grade redirects Inside of the `middleware.ts` in the starter, there's an import of a file (`bloom-filter.json`) that contains the output of the bloom filter algorithm. On the other hand, the actual redirects are stored in the `lib/redirects/redirects.json` file. In production cases, this probably should not be a file, but a query to some edge storage with extremely low latency, e.g. Edge Config. However, in development / less sophisticated cases, this file is good enough and we provide a straightforward way to generate the bloom filter or seed the filter with example redirects for testing purposes. ### Generating the filter and redirects Run the redirects seeding script (assuming you've already cloned the repository and you're in the `starters/shopify-algolia` directory) ```bash yarn build:scripts && node scripts/dist/redirects/generate-test-redirects.mjs --count=10000 --output=lib/redirects/redirects.json ``` After successfull execution, you will have 10k redirects inside the `lib/redirects/redirects.json` directory. This file is automatically used by the `/api/redirects/` endpoint to check the redirect's details. After seeding the redirects, you actually need to generate the bloom filter. ```bash yarn build:scripts && node scripts/dist/redirects/generate-bloom-filter.mjs --input=lib/redirects/redirects.json --output=lib/redirects/bloom-filter.json ``` After successfull execution, you will have the bloom filter inside the `lib/redirects/bloom-filter.json` directory. This file is automatically used by the `middleware.ts` file to check if the redirect exists. Quick note: After each modification of the redirects, you need to regenerate the bloom filter. Launch the development server and test if the redirects are working. ## Analytics ### Vercel Analytics (recommended) analytics are enabled by default. However, you may want to disable it by settings the `IS_VERCEL_ANALYTICS_ENABLED` environment variable to `false` in your `.env.local` file. ### Google Analytics Enterprise Commerce also supports Google Analytics integration through the official Next.js module. While it is disabled by default, you can easily enable it by setting the feature flag `IS_GTM_ENABLED` in your `.env.local` file: ```bash .env IS_GTM_ENABLED=true ``` Once enabled, the Google Analytics tracking code will be automatically added to your website, allowing you to track and analyze user behavior and traffic data. ## Reviews We use [](https://judge.me/) as a reviews provider. ### JudgeMe environment variables ```bash JUDGE_BASE_URL JUDGE_API_TOKEN SHOPIFY_STORE_DOMAIN ``` You can obtain these by setting up an account on the provider's website and traversing through the dashboard. file: ./content/docs/next-enterprise/index.mdx meta: { "title": "Getting Started", "description": "Get to know the project, philosophy and how to use it.", "icon": "Telescope" } import { Step, Steps } from 'fumadocs-ui/components/steps'; # Introduction `next-enterprise` is an carefully crafted Next.js boilerplate for enterprise, high-performance, maintainable applications and fast iterating teams. Packed with features like **TailwindCSS v4**, **Extremely strict TypeScript**, **ESLint 9**, **Prettier**, **testing tools** and more to accelerate your development and help to bootstrap your project faster. ## Philosophy While numerous **Next.js** boilerplates exist in the market today, the majority are designed to address individual developer requirements rather than the strategic needs of development teams, particularly those operating in enterprise environments. Many solutions incorporate excessive features and tooling that add complexity without proportional value. In `next-enterprise`, based on our enterprise clients, we recognize that operational efficiency originates from strategic simplicity. Our solution delivers a streamlined, enterprise-ready foundation with carefully selected, high-impact features and tools that maximize developer productivity and accelerate time-to-market for your business-critical applications. ## Documentation purpose This documentation serves as a comprehensive technical reference for the project features and a practical guide for enterprise application development. It incorporates knowledge gained from our work with large organizations. You will find detailed guidelines, best practices, and recommendations, along with explanations of our decision-making process that emphasizes business value. ## Installation ### Clone the project ```bash git clone https://github.com/blazity/next-enterprise.git ``` *...or using GitHub CLI* ```bash gh repo clone blazity/next-enterprise ``` ### Enable corepack ```bash corepack enable && corepack enable npm ``` This needs to be done only once - you do not need to run it again for other projects. The `corepack enable npm` command may seem unreasonable as we are using `pnpm`. It is well explained in the [Matt's TotalTypeScript article](https://www.totaltypescript.com/how-to-use-corepack#why-do-we-need-corepack-enable-npm) ### Install dependencies ```bash pnpm install --frozen-lockfile ``` ### Run the project ```bash pnpm dev ``` You can now begin development on your project. We recommend reviewing the rest of the documentation to understand the project structure and the business benefits our configuration provides. file: ./content/docs/agent-bridge/packages/cli.mdx meta: { "title": "CLI", "description": "Convert or migrate OpenAPI definitions to AgentBridge protocol", "icon": "SquareTerminal" } ## Usage Run the CLI to convert an OpenAPI/Swagger file to AgentBridge: ```bash tab="npm" npx @agent-bridge/cli ``` ```bash tab="pnpm" pnpm dlx @agent-bridge/cli ``` ```bash tab="bun" bunx @agent-bridge/cli ``` CLI will prompt you for the `ANTHROPIC_API_KEY` environment variable if it's not already set, nonetheless, it's required to run. You can find your API key in the [Anthropic console](https://console.anthropic.com/). ### Options | Option | Alias | Description | | ------------ | ------------------------ | ----------------------------------------------------------- | | `-V` | `--version` | Output the version number | | `-o` | `--output ` | Output file path (default: `agentbridge.json`) | | `--no-cache` | - | Disable LLM response caching | | `-d` | `--debug` | Enable debug mode with detailed output | | `-v` | `--verbose` | Enable verbose logging with detailed processing information | | `-c` | `--concurrency ` | Number of endpoints to process in parallel (default: `3`) | | `-h` | `--help` | Display help for command | ### Performance tuning #### Concurrency The `-c` or `--concurrency` flag controls how many endpoints are processed simultaneously. Higher values can speed up processing for large APIs but may increase the likelihood of hitting rate limits. Default is `5`. #### Rate limit handling The CLI automatically handles Anthropic API rate limits: * Uses the retry-after header from Anthropic for precise backoff timing * Implements exponential backoff with jitter when headers aren't available * Scales retry attempts based on concurrency settings * Provides detailed logs about rate limit status when in verbose mode 1. Reducing the concurrency value 2. Using the cache (enabled by default) to reduce API calls in subsequent runs 3. Upgrading your Anthropic API tier for higher rate limits ## Features * Parse OpenAPI/Swagger specifications * Enhance API descriptions with AI * Detect multi-step workflows * Map data flows between endpoints * Debug mode with detailed processing information * Token usage tracking and cost estimation * Intelligent rate limit handling with automatic retries * Parallel processing of endpoints with configurable concurrency file: ./content/docs/agent-bridge/packages/client.mdx meta: { "title": "TypeScript Library", "description": "Seamlessly integrate AgentBridge-defined APIs with AI agents through AI SDK", "icon": "Fa6BrandsJS" } import { BrandLink } from "@/components/brand-link" ## Installation ```bash tab="npm" npm install @agent-bridge/client ``` ```bash tab="pnpm" pnpm install @agent-bridge/client ``` ```bash tab="yarn" yarn add @agent-bridge/client ``` ```bash tab="bun" bun install @agent-bridge/client ``` ## Usage This library is currently tailored to work with the [AI SDK](https://github.com/vercel/ai), providing a simple interface for interacting with AgentBridge-defined APIs. Support beyond AI SDK is on the roadmap. While technically it can be used in other contexts, DX may be worse. ### Loading a Schema You can load an AgentBridge schema from either a local file or a remote URL: ```ts import { readSchemaFromFile, fetchSchemaFromUrl } from "@agent-bridge/client"; // From a local file const localSchema = await readSchemaFromFile("./path/to/schema.json"); // From a remote URL const remoteSchema = await fetchSchemaFromUrl( "https://api.example.com/schema.json" ); ``` ### Creating a Client ```ts import { AgentBridgeClient, LogLevel } from "@agent-bridge/client"; const client = AgentBridgeClient(schema, { apiKey: "your-api-key" }, LogLevel.INFO); ``` ### Usage with Vercel AI SDK ```ts import { openai } from "@ai-sdk/openai"; import { generateText } from "ai"; // ... code to initialize the client const { messages } = await req.json(); const { text } = await generateText({ model: openai("gpt-4o"), messages, tools: client.getTools(), }); ``` ### Logging The client includes a configurable logging system: ```ts // Set log level during initialization const client = new AgentBridgeClient(schema, credentials, LogLevel.DEBUG); // Or change it later client.setLogLevel(LogLevel.TRACE); ``` Available log levels: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE` ## Methods ### executeAction A method that executes a single API action. Returns a promise that resolves to the action result. ```ts const result = await client.executeAction("get_weather", { city: "London" }); ``` ### executeFlow A method that executes a multi-step flow. Returns a promise that resolves to the flow result. ```ts const result = await client.executeFlow("aviation_weather_briefing", { date: "2023-03-01", atsu: "LHR", time: "1200", }); ``` ### getTools A method that returns a list of tools in `ToolSet` type from `ai-sdk` library. ```ts const tools = client.getTools(); ``` ### listFlows A method that returns a list of flows that can be executed. ```ts const flows = client.listFlows(); ``` ### listActions A method that returns a list of actions that can be executed. ```ts const actions = client.listActions(); ``` ### setLogLevel A method that sets the log level, controlling the verbosity of the client's logging output. ```ts client.setLogLevel(LogLevel.DEBUG); ``` ## Helpers ### readSchemaFromFile A helper function that reads a AgentBridge schema from a local file. ```ts import { readSchemaFromFile } from "@agent-bridge/client"; const schema = await readSchemaFromFile("./path/to/schema.json"); ``` ### fetchSchemaFromUrl A helper function that fetches a AgentBridge schema from a remote URL. ```ts import { fetchSchemaFromUrl } from "@agent-bridge/client"; const schema = await fetchSchemaFromUrl("https://api.example.com/schema.json"); ``` file: ./content/docs/agent-bridge/v1_0/design.mdx meta: { "title": "Design principles", "description": "Understanding the design principles behind AgentBridge" } ## AI-First AgentBridge is designed with a goal of making AI agents more capable of understanding and completing tasks autonomously. It takes a unique and tailored approach - unlike traditional API specifications that focus on isolated endpoints, AgentBridge organizes APIs into actions, flows (multi-step workflows), and entities, enriched with clear, semantic descriptions. This specific structure, provides an optimized way for LLMs to consume and perform up to expectations of the user accurately. ## Flow-Oriented Workflows are fundamental blocks in many systems, so providing a structured approach to handling complex, multi-step tasks is crucial for AI agents. AgentBridge defines a standard format for describing workflows, making it simple for AI agents to understand and execute them. ## Semantic Understanding AgentBridge excels at capturing the purpose of API operations, which helps AI agents in understanding the context and intent behind the requests. It promotes meaningful descriptions in API documentation, giving meaning to actions and entities, and conveying the relationships between steps in workflows. file: ./content/docs/enterprise-commerce/browsing-journey/clp.mdx meta: { "title": "Category Landing Page", "prefix": "CLP", "description": "Business-critical category pages optimized for conversion and discovery" } import { BrandLink } from "@/components/brand-link"; # Introduction Category Landing Pages serve as crucial entry points for browsing journeys, combining visual storytelling with curated product discovery. The implementation dynamically switches between CLP and PLP layouts with two source of truths, Shopify as product data source and CMS as cover image + content source ## Media import { MediaPanel } from "@/components/media-panel"; ## High level overview of the features * Optimized Headless CMS driven CLP cover images and descriptions * Showcase of products from the particular category * "Show all products" button navigating to the actual PLP * Tightly bound to the categories user in the e-commerce provider configured (default: ) * Possibility to declare category to be viewable as \[PLP] or \[CLP], depending on the hierarchical level after clicking it in the \[MegaNav] file: ./content/docs/enterprise-commerce/browsing-journey/hp.mdx meta: { "title": "Home Page", "description": "High-performance homepage with SSG and A/B testing", "prefix": "HP" } # Introduction The Homepage serves as the primary entry point, showcasing featured products and categories. Built with SSG (Static Site Generation) and A/B testing capabilities, it delivers instant loads while maintaining merchandising flexibility. ## Media import { MediaPanel } from '@/components/media-panel' ## High level overview of the features * Super optimized above-the-fold category carousel with CTA buttons forwarding to CLPs/PLPs * SSG for best possible performance * A/B testing out of the box with simple implementation * Sales banner file: ./content/docs/enterprise-commerce/browsing-journey/pdp.mdx meta: { "title": "Product Details Page", "description": "Hybrid SSG/SSR rendering for optimal performance and SEO", "prefix": "PDP" } # Introduction The Product Details Page implements a sophisticated hybrid rendering strategy optimizing for performance and SEO. Base product handles use SSG for instant loading, while variant-specific URLs leverage SSR for dynamic content. This approach delivers sub-second performance while supporting infinite variant combinations. ## Media import { MediaPanel } from '@/components/media-panel' ## High level overview of the features * Multiple variants configurations with robust variants' combinations handling * Image variants carousel with auto-changing the preview based on the selected variant * FAQ sections driven by headless CMS * Product reviews panel with "View all reviews" subpage * Recommended products at the bottom of the page * Above the fold content visible with JavaScript disabled (SEO-optimized) * Base product generated as SSG + variants SSR file: ./content/docs/enterprise-commerce/browsing-journey/plp.mdx meta: { "title": "Product Listing Page", "description": "Algolia-powered product discovery with advanced filtering", "prefix": "PLP" } # Introduction The Product Listing Page serves as the primary discovery interface, combining Algolia's powerful search with sophisticated filtering. Delivering sub-100ms response times, the PLP handles complex faceted search across thousands of products (possibly even millions) while maintaining exceptional user experience. ## Media import { MediaPanel } from '@/components/media-panel' ## High level overview of the features * Sub-second search experience, thanks to \[Algolia] * Intelligent values faceting through multiple filters, such as: * Product's copywriting content * Average rating and reviews * Vendors * Variants * Minimum/maximum price * Sorting of the PLP output display * Efficient and battle-tested pagination without fancy infinite loading sections * Query params driven, easily shareable links * Browsing journey helpers, such as tiny vendors' list search file: ./content/docs/enterprise-commerce/features/ab-tests.mdx meta: { "title": "A/B Tests", "description": "A/B testing without performance overhead in enterprise commerce", "icon": "FlaskConical" } # Introduction Enterprise Commerce empowers you to optimize your storefront and user experience through its built-in A/B testing system. This system allows you to experiment with different website elements and features **without compromising performance or causing layout shifts.** ## How it Works The A/B testing system utilizes a mathematical approach to assign users to different test buckets. This ensures a fair and unbiased distribution, allowing you to accurately compare the performance of different variations. Users are assigned to a specific bucket based on a random number generator and percentage allocation calculations. This ensures that each user consistently sees the same variation throughout their session, providing a controlled testing environment. ### Example Usage A/B testing allows you to display different components or even entire pages to different user groups. This enables you to test various versions of elements like buttons, banners, or product descriptions to identify the most effective design and messaging. Here's an example of how to implement A/B testing for a hero section title: ```tsx export default function Homepage({ params: { bucket } }) { const heroTitles = { a: "Your daily trendsetting deals", b: "Your daily top deals", } return } ``` In this example, users assigned to bucket "a" will see the title "Your daily trendsetting deals," while users in bucket "b" will see "Your daily top deals." By tracking user engagement and conversion rates for each variation, you can determine which title performs better and implement the optimal version for your storefront. file: ./content/docs/enterprise-commerce/features/analytics.mdx meta: { "title": "Analytics", "description": "Track your websites visits without losing performance", "icon": "ChartArea" } import { BrandLink } from "@/components/brand-link" # Introduction Enterprise Commerce provides built-in support for two powerful analytics tools: Vercel Analytics and Google Analytics. While you have the flexibility to integrate any third-party analytics solution of your choice, these two options are readily available out of the box. ## Vercel Analytics (Recommended) Vercel Analytics is the recommended and default analytics solution in Enterprise Commerce. It offers several key advantages: * **Privacy-friendly**: Vercel Analytics respects user privacy and does not collect personally identifiable information (PII). * **Real-time insights**: Get instant visibility into your website's traffic and user behavior with real-time data updates. * **Minimal performance impact**: Unlike other analytics solutions, Vercel Analytics has negligible impact on your website's performance, ensuring optimal speed and user experience. ## Google Analytics Enterprise Commerce also supports Google Analytics integration through the official Next.js module. Learn more how to set it up in the [Analytics section in Setup & Configuration page](../setup#analytics) file: ./content/docs/enterprise-commerce/features/enterprise-redirects.mdx meta: { "title": "Enterprise Redirects", "description": "High-performance URL redirect management for seamless e-commerce transitions", "icon": "Cable" } # Introduction Managing thousands of redirects efficiently is critical for enterprise e-commerce. Platform migrations, URL restructuring, and product lifecycle changes all demand redirect management that scales without impacting performance. Enterprise Commerce achieves this through innovative bloom filter technology. ## The E-commerce Challenge **Platform migrations** can result in 50% traffic loss if poorly executed. Thousands of product URLs must redirect seamlessly to preserve years of SEO investment. **Product lifecycle** creates ongoing redirect needs. Discontinued products, seasonal collections, and naming changes all require permanent URL management. **URL evolution** happens as catalogs grow. Simple structures like `/products/widget` evolve into `/category/subcategory/widget`, affecting thousands of URLs simultaneously. ## Bloom Filter Solution The implementation uses **ScalableBloomFilter** technology for constant-time redirect lookups regardless of dataset size. Key advantages: * **Memory efficient**: 50,000 redirects use minimal memory * **Constant performance**: Sub-millisecond checks whether managing 1,000 or 100,000 redirects * **Edge-ready**: Deploys anywhere without infrastructure changes ## Two-Tier Architecture The system balances performance with accuracy through smart design: 1. **Bloom filter check** (\< 1ms) eliminates 95%+ of requests instantly 2. **API lookup** (5-10ms) retrieves actual redirect only when needed ## Real-World Performance Traditional approaches show linear degradation - database lookups might start at 5ms but climb to 50ms+ under load. The bloom filter approach maintains consistency: * Bloom filter check: \< 1ms * API call (only for matches): 5-10ms * Overall request impact: Negligible for 95%+ of traffic file: ./content/docs/enterprise-commerce/features/fast-search.mdx meta: { "title": "Fast Search", "description": "Sub-second search and autocomplete powered by Algolia", "icon": "Search" } import { BrandLink } from "@/components/brand-link" # Introduction Modern e-commerce faces a critical challenge: delivering instant search results to users without compromising performance due to excessive network latency. Enterprise Commerce solves this with -powered search that scales effortlessly. ## Algolia-Powered Solution Enterprise Commerce leverages 's globally distributed infrastructure to deliver consistent sub-15ms response times worldwide. The integration provides: * **Typo tolerance** and spelling corrections * **Synonym recognition** for natural language queries * **Advanced faceting** for complex combinations of search attributes; variants, prices, vendors, categories * **Robust sorting** for displaying the results for different shapes and needs * **Reliable Pagination** without fancy infinite scrolling mechanisms, a battle-tested classic solution ## Real-World Impact * **Sub-15ms global latency** ensures instant feedback * **99.99% uptime** through redundant infrastructure * **Predictable costs** even during Black Friday traffic spikes file: ./content/docs/enterprise-commerce/features/favorites.mdx meta: { "title": "Favorites", "description": "Favorites under the hood", "icon": "Heart" } # Introduction The Favorites feature allows users to "like" products and save them for later viewing or purchase. This functionality is accessible without requiring user accounts or logins. ## Technical Implementation Favorites data is stored exclusively within the user's browser, specifically in cookies. This means that: * **No server-side storage or user accounts are involved.** * **Favorites data is specific to the browser and device used.** * **Data is not shared across devices or browsers.** **Note:** Due to the reliance on cookies, clearing browser data or using a different browser will result in the loss of saved favorites. file: ./content/docs/enterprise-commerce/features/hierarchical-categories.mdx meta: { "title": "Hierarchical Categories", "description": "Narrow results for large subset of products", "icon": "Workflow" } import { BrandLink } from "@/components/brand-link" # Introduction In an e-commerce shop with a vast array of products, helping users find what they need quickly and efficiently is crucial. Hierarchical categories provide a powerful way to organize and navigate large product inventories. By structuring products into parent and child categories, users can easily drill down from broad categories to more specific ones, refining their search and improving their overall shopping experience. This feature allows users to filter and refine large product selections efficiently. ## High-level Overview Implementation can be broken down into: * Setting up categories * Defining hierarchies * Assigning products to categories * Synchronizing with your search platform * Retrieval of facets in the frontend ## Implementation overview Defining categories and their hierarchical structure may vary depending on the platform, however we try to minimize the amount of work needed in order to get them working with your storefront. Following the design of our architecture, we push all categories to our search platform whilst also enabling other benefits, ie. categories search. ### Setting up categories To set up categories in , log in to your [ Admin Dashboard](https://admin.shopify.com/). From the left-side menu, select Products, then from the sub-menu that opens, select Collections. Here, you can manage your collections.  When you're creating a new category, offers two types: * Manual: You manually curate products that belong to the given category. * Automated: You create conditions upon which products will automatically be assigned to this category. **Keep in mind, once you create a collection, you cannot change its type**  As you create a new category, make sure you publish it to the Headless Channel then fill in all of the fields. We recommend choosing automated categories. When creating your category, consider where it belongs in the hierarchy so you can set appropriate conditions. For example: Given the following structure, we want to create a top-level Fashion category. ``` - Fashion - Men - Shorts - Blazers & suits - Women - Skirts - Dresses ``` To simplify the process of product assignment, create a condition based on matching tags for each sub-category.  Now, looking at the above screenshot, all you have to do is to ensure that every time someone creates a new product, the proper tag is assigned to it. For sub-categories, create them following the same principle but with fewer conditions, as the whole point of hierarchies is to narrow down the results!  ### Defining Hierarchies Defining hierarchies in can be tricky and may vary depending on the platform. In , you can use the Menu feature. From the left-side menu, select Content, then Menu, and finally Add menu.  Fill in all the fields, such as title and handle (this is very important), add menu items, and then define hierarchies.  You can nest menus by dragging one over another; this will create a sub-menu within one. This part is crucial, as it defines hierarchies for our sync scripts.  ### Different platforms integration If you want to create hierarchical categories using a different platform, ensure the following data structure is provided whenever you push products to your search solution: ```json { "hierarchicalCategories": { "lvl0": ["fashion"], "lvl1": ["fashion > women", "fashion > men"], "lvl2": [ "fashion > women > skirts", "fashion > women > dresses", "fashion > men > shorts", "fashion > men > blazers-and-suits" ] } } ``` *** Once this is done and the environment variable can be read, you're all set! file: ./content/docs/enterprise-commerce/features/mega-nav.mdx meta: { "title": "Mega Nav", "description": "Mega Navigation with ISR updates and on-the-fly data refresh", "icon": "Folders" } # Introduction Mega Navigation with ISR updates and on-the-fly data refresh ## Media  ### Server-Side Rendered with Client-Side Updates * Initial render is done on the server using build-time data * Client-side updates using SWR for data freshness * Zero Cumulative Layout Shift (CLS) due to CSS-first approach * Navigation data is always fresh in the client without affecting page performance ### Smart Caching Strategy * Navigation endpoint is cached (like ISR) and can be revalidated using `revalidatePath` * All product pages are static (ISR) with time-based revalidation (1 hour) * Perfect for large sites with thousands of pages - update navigation without revalidat file: ./content/docs/enterprise-commerce/features/performance.mdx meta: { "title": "Hierarchical Categories", "description": "hehe", "icon": "Workflow" } siema file: ./content/docs/enterprise-commerce/features/reviews.mdx meta: { "title": "Reviews", "description": "Product reviews and rating system in enterprise-commerce", "icon": "Star" } import { BrandLink } from "@/components/brand-link" # Introduction Reviews are critical for every e-commerce platform, and Enterprise Commerce provides an easy way to integrate reviews with your storefront. Currently, we've implemented logic for the provider, **but more integrations are coming soon.** ## How It Works From a high-level perspective, the implementation breaks down into the following steps: * A user submits a review, and the data is pushed directly to the reviews provider. * A scheduled cron job periodically syncs reviews with the search index. * The data cache revalidates the frontend. ### Why This Approach? We've integrated reviews with our search solution because our architecture is designed to have a single source of truth for data retrieval. We run daily cron jobs (adjustable) between the search and review providers to ensure data stays in sync. This approach also allows us to extend our Product Listing Page (PLP) functionality to filter and sort results based on their **average rating**. ### Making Reviews More Dynamic Near real-time updates are possible but often require a paid plan depending on the provider. If this is the case for your business, we can set up webhooks that will: * Call a webhook to update search when a new review is added. * Have the search call another webhook once data is updated to revalidate the Next.js data cache. Please note that this functionality is currently not available in the demo. We are actively working on adding it and will update the documentation accordingly. file: ./content/docs/enterprise-commerce/features/seo.mdx meta: { "title": "SEO", "description": "SEO and crawling budget optimization strategies implemented in the enterprise-commerce", "icon": "Binoculars" } import { BrandLink } from "@/components/brand-link" # Introduction We prioritize search engine optimization (SEO) with a comprehensive approach that includes * **Lighthouse Score** - We maintain a perfect 100 score in Lighthouse audits, ensuring optimal technical performance. * **Best Practices** - We adhere to SEO best practices, including canonicals, server-side pagination, and a well-defined URL structure. * **JSON-LD** - We implement structured data using JSON-LD for product pages, providing rich information to search engines and enhancing search visibility. JSON-LD is rendered as a `