Creating a Custom Integration

Custom Alokai Integration - REST API

This is a custom integration for Alokai Storefront Middleware that connects your storefront to a third-party service.

File Structure

The integration follows this structure:

The __tests__/ directory holds integration and unit tests, ai/ contains AI agent guidance and instructions, api/ holds the API method implementations, client/ holds the HTTP client configuration, and types/ holds the TypeScript type definitions. At the root, config.ts holds the integration configuration, index.server.ts holds the server-side exports, index.ts holds the main integration exports, and README.md is this file.

AI Support

This integration includes AI guidance for code editors like Copilot, Windsurf or Cursor.

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions for AI agents to help implement:

• HTTP client connecting to third-party platforms
• API methods for fetching data from external services
• Unified API methods with proper data normalization

Compatibility: These instructions have been tested with Claude 3.5 and 4.0 and can be executed with ClaudeCode, the Gemini AI assistant, and other agents that use these models.

To use these instructions, add the file to your AI context with the prompt "run instruction".

AI driven setup (recommended)

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions to complete the setup of the integration. Use your AI agent to run the instructions.

Manual setup (alternative)

1. Implement Custom Methods

Create API methods in the apps/storefront-middleware/integrations/my-integration/api/ directory. Each method should be in its own folder. Here's an example based on api/exampleMethod/index.ts:

import type { IntegrationContext } from '../../types';

export interface ExampleMethodArgs {
  id: string;
}

export const exampleMethod = async (context: IntegrationContext, args: ExampleMethodArgs) => {
  // Make HTTP requests using the Axios client:
  // return await context.client.get(`/example-url?id=${args.id}`);

  // Or make POST requests:
  // return await context.client.post('/example-url', { data: args });

  return { data: 'Hello, Alokai Integrator!' };
};

2. Register Integration

Add your integration to the middleware configuration in apps/storefront-middleware/middleware.config.ts:

+ import { config as myIntegrationConfig } from './integrations/my-integration';

export const config = {
  integrations: {
+   myIntegration: myIntegrationConfig,
  },
};

3. Export SDK Module

To use the integration in your frontend, you need to reexport the SDK module. Add the following line to apps/storefront-unified-nextjs/sdk/modules/index.ts:

export * from '@/sdk/modules/checkout';
export * from '@/sdk/modules/commerce';
export * from '@/sdk/modules/custom-extension';
+ export * from '@/sdk/modules/my-integration';
export * from '@/sdk/modules/unified';
export * from '@/sdk/modules/unified-cms-mock';

Running Tests

Tests use Vitest which is already configured in the storefront-middleware via vitest.config.ts.

Run all middleware tests (including this integration):

cd apps/storefront-middleware
yarn test

Run only this integration's tests:

cd apps/storefront-middleware
npx vitest run integrations/my-integration

Test files should use explicit vitest imports (globals are disabled):

import { describe, expect, it, vi } from 'vitest';

Usage

Once registered, you can use the integration in your components:

import { getSdk } from '@/sdk';

export default async function MyComponent() {
  const sdk = await getSdk();

  // Call your integration methods
  const result = await sdk.myIntegration.exampleMethod({ id: '1' });

  return (
    <div>
      {/* Your component JSX */}
    </div>
  );
}

For client-side usage:

import { useSdk } from '@/sdk/alokai-context';

export default function MyClientComponent() {
  const sdk = useSdk();

  const handleClick = async () => {
    const result = await sdk.myIntegration.exampleMethod({ id: '1' });
    console.log(result);
  };

  return (
    <button onClick={handleClick}>
      Call Integration
    </button>
  );
}

Custom Alokai Integration - GraphQL

This is a custom integration for Alokai Storefront Middleware that connects your storefront to a third-party service using GraphQL.

File Structure

Here's an overview of the integration's file structure:

The __tests__/ directory holds unit and integration tests, ai/ contains AI assistant guidance files, api/ holds the API method implementation, client/ sets up and configures the GraphQL client, and types/ holds the TypeScript type definitions. At the root, codegen.ts configures GraphQL code generation, config.ts holds the integration configuration and settings, index.server.ts handles server-side initialization and API client setup, index.ts is the main export file, and README.md is this documentation file.

AI Support

This integration includes AI guidance for code editors like Copilot, Windsurf or Cursor.

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions for AI agents to help implement:

• HTTP client connecting to third-party platforms
• API methods for fetching data from external services
• Unified API methods with proper data normalization

Compatibility: These instructions have been tested with Claude 3.5 and 4.0 and can be executed with ClaudeCode, the Gemini AI assistant, and other agents that use these models.

To use these instructions, add the file to your AI context with the prompt "run instruction".

AI driven setup

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions to complete the setup of the integration. Use your AI agent to run the instructions.

Manual setup (alternative)

Step 0: Install Dependencies

Install in apps/storefront-middleware/package.json, do it before you start next step.

Dependencies:

• graphql@^16.11.0
• graphql-request@^6

Dev Dependencies:

• @graphql-codegen/cli@5.0.7
• @graphql-codegen/schema-ast@^4.1.0
• @graphql-codegen/typescript@^4.1.6
• @graphql-codegen/typescript-graphql-request@^6.3.0
• @graphql-codegen/typescript-operations@^4.6.1
• graphql-config@^5.1.3
• supertest@^7.0.0
• @types/supertest@^6

1. Configure Integration

Add configuration properties to the MiddlewareConfig in apps/storefront-middleware/integrations/my-integration/types/config/index.ts:

export interface MiddlewareConfig {
  baseUrl: string;
  apiKey?: string;
  timeout?: number;
  // Add other GraphQL-specific configuration options as needed
}

2. Generate GraphQL Types

This integration uses codegen to automatically generate TypeScript types and interfaces from your GraphQL schema. Before using the integration, generate the GraphQL schema and TypeScript interfaces:

cd apps/storefront-middleware
yarn graphql-codegen --config integrations/my-integration/codegen.ts

The configuration is defined in codegen.ts and will generate types in the types/ directory.

This integration provides a request method that is used to send GraphQL queries or mutations to the GraphQL API. You can use this method to execute any GraphQL operation against your configured endpoint.

3. Register Integration

Add the integration to apps/storefront-middleware/middleware.config.ts:

+ import { config as myIntegrationConfig } from './integrations/my-integration';

export const config = {
  integrations: {
+   myIntegration: myIntegrationConfig,
  },
};

4. Export SDK Module

Export the SDK module in apps/storefront-unified-nextjs/sdk/modules/index.ts:

+ export * from './my-integration';

This allows you to use the integration methods in your frontend components.

Running Tests

Tests use Vitest which is already configured in the storefront-middleware via vitest.config.ts.

Run all middleware tests (including this integration):

cd apps/storefront-middleware
yarn test

Run only this integration's tests:

cd apps/storefront-middleware
npx vitest run integrations/my-integration

Test files should use explicit vitest imports (globals are disabled):

import { describe, expect, it, vi } from 'vitest';

Usage

Once registered, you can use the integration in your Next.js application:

import { getSdk } from '@/sdk';

export default async function MyComponent() {
  const sdk = await getSdk();

  // Define your GraphQL query
  const query = `
    query GetProduct($id: ID!) {
      product(id: $id) {
        id
        name
        price
      }
    }
  `;

  // Call the integration using a GraphQL query
  const result = await sdk.myIntegration.request(query, { id: '123' });

  return <div>{/* Your component */}</div>;
}

For client-side usage:

'use client';

import { useSdk } from '@/sdk/alokai-context';
import { useQuery } from '@tanstack/react-query';

export default function MyClientComponent() {
  const sdk = useSdk();

  const query = `
    query GetProduct($id: ID!) {
      product(id: $id) {
        id
        name
        price
      }
    }
  `;

  const { data, isLoading } = useQuery({
    queryKey: ['myData'],
    queryFn: () => sdk.myIntegration.request(query, { id: '123' }),
  });

  if (isLoading) return <div>Loading...</div>;

  return <div>{/* Your component */}</div>;
}

Custom Alokai Integration - OpenAPI

This is a custom integration for Alokai Storefront Middleware that connects your storefront to a third-party service using the OpenAPI specification.

File Structure

The integration follows a standard structure for Alokai integrations:

The __tests__/ directory holds unit and integration tests, ai/ contains AI assistance files and documentation, api/ holds the API method implementations, client/ holds the HTTP client configuration, generated/ holds auto-generated files from the OpenAPI spec, and types/ holds the TypeScript type definitions. At the root, config.ts holds the integration configuration, index.server.ts holds the server-side exports, index.ts is the main entry point, and README.md is this file.

AI Support

This integration includes AI guidance for code editors like Copilot, Windsurf or Cursor.

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions for AI agents to help implement:

• HTTP client connecting to third-party platforms
• API methods for fetching data from external services
• Unified API methods with proper data normalization

Compatibility: These instructions have been tested with Claude 3.5 and 4.0 and can be executed with ClaudeCode, the Gemini AI assistant, and other agents that use these models.

To use these instructions, add the file to your AI context with the prompt "run instruction".

AI driven setup (recommended)

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions to complete the setup of the integration. Use your AI agent to run the instructions.

Manual setup (alternative)

1. Configure Client

First, add configuration properties to the MiddlewareConfig in apps/storefront-middleware/integrations/my-integration/types/config/index.ts:

export interface MiddlewareConfig {
  baseUrl: string;
  apiKey?: string;
  timeout?: number;
  // Add other configuration options as needed
}

Then, configure DefaultParams in apps/storefront-middleware/integrations/my-integration/api/proxy/createProxyApi.ts:

export interface DefaultParams {
  // Add default parameters that should be included in all API calls
  // For example:
  // version?: string;
  // format?: 'json' | 'xml';
  // locale?: string;
}

Note: OpenAPI generates method interfaces automatically from your API specification. You only need to configure the client and default parameters.

2. Register Integration

Register your integration in the apps/storefront-middleware/middleware.config.ts file:

+ import { config as myIntegrationConfig } from './integrations/my-integration';

export const config = {
  integrations: {
+   myIntegration: myIntegrationConfig,
  },
};

3. Export SDK Module

Export the SDK module in apps/storefront-unified-nextjs/sdk/modules/index.ts:

+ export * from './my-integration';

This allows you to use the integration methods in your frontend components.

Running Tests

Tests use Vitest which is already configured in the storefront-middleware via vitest.config.ts.

Run all middleware tests (including this integration):

cd apps/storefront-middleware
yarn test

Run only this integration's tests:

cd apps/storefront-middleware
npx vitest run integrations/my-integration

Test files should use explicit vitest imports (globals are disabled):

import { describe, expect, it, vi } from 'vitest';

Usage

Once registered, you can use the integration in your Next.js components:

import { getSdk } from '@/sdk';

export default async function MyComponent() {
  const sdk = await getSdk();

  // Call integration methods
  const result = await sdk.myIntegration.exampleMethod({ id: '1' });

  // Call unified methods (if implemented)
  const unifiedResult = await sdk.unifiedMyIntegration.getProduct({ id: '1' });

  return (
    <div>
      {/* Render your content */}
    </div>
  );
}

For client-side usage:

'use client';

import { useSdk } from '@/sdk/alokai-context';
import { useQuery } from '@tanstack/react-query';

export default function MyClientComponent() {
  const sdk = useSdk();

  const { data, isLoading } = useQuery({
    queryKey: ['my-integration', 'example'],
    queryFn: () => sdk.myIntegration.exampleMethod({ id: '1' }),
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {/* Render your content */}
    </div>
  );
}

Custom Alokai Integration - SDK Proxy

This is a custom integration for Alokai Storefront Middleware that connects your storefront to a third-party service.

File Structure

The __tests__/ directory holds test files, ai/ contains AI guidance files for code editors, client/ holds the HTTP client implementation, helpers/ holds utility functions and factories, and types/ holds the TypeScript type definitions. At the root, config.ts holds the integration configuration, index.server.ts handles server-side integration setup, and index.ts is the main integration entry point.

AI Support

This integration includes AI guidance for code editors like Copilot, Windsurf or Cursor.

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions for AI agents to help implement:

• HTTP client connecting to third-party platforms
• API methods for fetching data from external services
• Unified API methods with proper data normalization

Compatibility: These instructions have been tested with Claude 3.5 and 4.0 and can be executed with ClaudeCode, the Gemini AI assistant, and other agents that use these models.

To use these instructions, add the file to your AI context with the prompt "run instruction".

AI driven setup (recommended)

The file apps/storefront-middleware/integrations/my-integration/ai/getting-started.md contains detailed instructions to complete the setup of the integration. Use your AI agent to run the instructions.

Manual setup (alternative)

1. Configure Client

First, add configuration properties to the MiddlewareConfig in apps/storefront-middleware/integrations/my-integration/types/config/index.ts:

export interface MiddlewareConfig {
  apiKey: string;
  baseUrl?: string;
  // Add other configuration options as needed
}

Then implement the client initialization by setting up the third-party SDK in apps/storefront-middleware/integrations/my-integration/client/index.ts:

import { MyThirdPartySDK } from 'third-party-sdk';
import type { MiddlewareConfig } from '../types/config';

export function buildClient(config: MiddlewareConfig) {
  const client = new MyThirdPartySDK({
    apiKey: config.apiKey,
    baseUrl: config.baseUrl || 'https://api.example.com',
  });

  return client;
}

Update the IntegrationContext in apps/storefront-middleware/integrations/my-integration/types/context/index.ts:

import type { BaseIntegrationContext } from '@alokai/middleware';
import type { MyThirdPartySDK } from 'third-party-sdk';
import type { MiddlewareConfig } from '../config';
import type { Endpoints } from '../endpoints';

export interface IntegrationContext
  extends BaseIntegrationContext<MyThirdPartySDK, MiddlewareConfig, Endpoints> {}

Finally, add the methods that need to be exposed in apps/storefront-middleware/integrations/my-integration/types/endpoints/index.ts:

import type { MyThirdPartySDK } from 'third-party-sdk';
import type { IntegrationContext } from '../context';

export interface ApiMethods {
  exampleMethod: (
    context: IntegrationContext,
    ...args: Parameters<MyThirdPartySDK['exampleMethod']>
  ) => ReturnType<MyThirdPartySDK['exampleMethod']>;
  // Add other methods as needed
}

// Note: Remember that the context: IntegrationContext must be the first parameter
// and method parameters should come later (can be destructured with ...Parameters[])

2. Register Integration

Register your integration in the apps/storefront-middleware/middleware.config.ts file:

+ import { config as myIntegrationConfig } from './integrations/my-integration';

export const config = {
  integrations: {
+   myIntegration: myIntegrationConfig,
  },
};

3. Export SDK Module

Export the SDK module in apps/storefront-unified-nextjs/sdk/modules/index.ts:

+ export * from './my-integration';

This allows you to use the integration methods in your frontend components.

Running Tests

Tests use Vitest which is already configured in the storefront-middleware via vitest.config.ts.

Run all middleware tests (including this integration):

cd apps/storefront-middleware
yarn test

Run only this integration's tests:

cd apps/storefront-middleware
npx vitest run integrations/my-integration

Test files should use explicit vitest imports (globals are disabled):

import { describe, expect, it, vi } from 'vitest';

Usage

Once registered, you can use the integration in your components:

import { getSdk } from '@/sdk';

export default async function MyComponent() {
  const sdk = await getSdk();

  // Call custom integration methods
  const result = await sdk.myIntegration.exampleMethod({ id: '1' });

  return <div>{/* Your component */}</div>;
}

For client-side usage:

'use client';

import { useSdk } from '@/sdk/alokai-context';
import { useQuery } from '@tanstack/react-query';

export default function MyClientComponent() {
  const sdk = useSdk();

  const { data, isLoading } = useQuery({
    queryKey: ['myData'],
    queryFn: () => sdk.myIntegration.exampleMethod({ id: '1' }),
  });

  if (isLoading) return <div>Loading...</div>;

  return <div>{/* Your component */}</div>;
}