@open-loyalty/mcp-server 1.0.0 → 1.0.1

package/dist/tools/transaction.test.js

@@ -1,235 +0,0 @@
-// src/tools/transaction.test.ts
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { setupMockAxios, teardownMockAxios, getMockAxios } from '../../tests/mocks/http.mock.js';
-import { transactionFixtures } from '../../tests/fixtures/transaction.fixtures.js';
-import { transactionCreate, transactionGet, transactionList, transactionAssignMember, } from './transaction.js';
-describe('Transaction Operations', () => {
-    beforeEach(() => {
-        setupMockAxios();
-    });
-    afterEach(() => {
-        teardownMockAxios();
-    });
-    describe('transactionCreate', () => {
-        it('should create transaction with transaction wrapper', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction').reply(200, transactionFixtures.createResponse);
-            const result = await transactionCreate({
-                header: {
-                    documentNumber: 'DOC-001',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                },
-                items: [
-                    {
-                        sku: 'PROD-001',
-                        name: 'Test Product',
-                        grossValue: 100,
-                        category: 'Electronics',
-                    },
-                ],
-            });
-            expect(result.transactionId).toBe('txn-uuid-123');
-            // Verify request body format with transaction wrapper
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.transaction).toBeDefined();
-            expect(requestData.transaction.header.documentNumber).toBe('DOC-001');
-            expect(requestData.transaction.header.documentType).toBe('sell');
-            expect(requestData.transaction.items).toHaveLength(1);
-            expect(requestData.transaction.items[0].sku).toBe('PROD-001');
-        });
-        it('should include customerData for member matching', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction').reply(200, {
-                transactionId: 'txn-uuid',
-                pointsEarned: 100,
-            });
-            const result = await transactionCreate({
-                header: {
-                    documentNumber: 'DOC-002',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                },
-                items: [
-                    {
-                        sku: 'PROD-001',
-                        name: 'Product',
-                        grossValue: 100,
-                        category: 'Category',
-                    },
-                ],
-                customerData: {
-                    email: 'customer@example.com',
-                },
-            });
-            expect(result.pointsEarned).toBe(100);
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.transaction.customerData.email).toBe('customer@example.com');
-        });
-        it('should handle return transactions', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction').reply(200, transactionFixtures.createResponse);
-            await transactionCreate({
-                header: {
-                    documentNumber: 'RETURN-001',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                    documentType: 'return',
-                    linkedDocumentNumber: 'DOC-001',
-                },
-                items: [
-                    {
-                        sku: 'PROD-001',
-                        name: 'Product',
-                        grossValue: -50,
-                        category: 'Category',
-                    },
-                ],
-            });
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.transaction.header.documentType).toBe('return');
-            expect(requestData.transaction.header.linkedDocumentNumber).toBe('DOC-001');
-        });
-        it('should use highPrecisionQuantity', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction').reply(200, transactionFixtures.createResponse);
-            await transactionCreate({
-                header: {
-                    documentNumber: 'DOC-003',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                },
-                items: [
-                    {
-                        sku: 'PROD-001',
-                        name: 'Product',
-                        grossValue: 100,
-                        category: 'Category',
-                        highPrecisionQuantity: 1.5,
-                    },
-                ],
-            });
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.transaction.items[0].highPrecisionQuantity).toBe(1.5);
-        });
-        it('should use custom storeCode', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/custom-store/transaction').reply(200, transactionFixtures.createResponse);
-            await transactionCreate({
-                storeCode: 'custom-store',
-                header: {
-                    documentNumber: 'DOC-001',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                },
-                items: [
-                    {
-                        sku: 'PROD-001',
-                        name: 'Product',
-                        grossValue: 100,
-                        category: 'Category',
-                    },
-                ],
-            });
-            expect(mockAxios.history.post[0].url).toBe('/custom-store/transaction');
-        });
-    });
-    describe('transactionGet', () => {
-        it('should get transaction details', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onGet('/default/transaction/txn-uuid').reply(200, transactionFixtures.getResponse);
-            const result = await transactionGet({ transactionId: 'txn-uuid' });
-            expect(result.transactionId).toBe('txn-uuid-123');
-            expect(result.documentNumber).toBe('DOC-001');
-            expect(result.documentType).toBe('sell');
-            expect(result.matched).toBe(true);
-            expect(result.grossValue).toBe(150);
-            expect(result.pointsEarned).toBe(150);
-        });
-        it('should extract documentNumber from header', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onGet('/default/transaction/txn-uuid').reply(200, {
-                transactionId: 'txn-uuid',
-                header: {
-                    documentNumber: 'DOC-FROM-HEADER',
-                    documentType: 'sell',
-                    purchasedAt: '2026-01-15T10:00:00Z',
-                },
-                items: [],
-                matched: true,
-                grossValue: 100,
-            });
-            const result = await transactionGet({ transactionId: 'txn-uuid' });
-            expect(result.documentNumber).toBe('DOC-FROM-HEADER');
-        });
-    });
-    describe('transactionList', () => {
-        it('should list transactions from items array', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onGet('/default/transaction').reply(200, transactionFixtures.listResponse);
-            const result = await transactionList({});
-            expect(result.transactions).toHaveLength(2);
-            expect(result.transactions[0].transactionId).toBe('txn-uuid-1');
-            expect(result.transactions[0].documentNumber).toBe('DOC-001');
-            expect(result.transactions[0].matched).toBe(true);
-        });
-        it('should include pagination params', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onGet(/\/default\/transaction/).reply(200, transactionFixtures.listResponse);
-            await transactionList({ page: 2, perPage: 25 });
-            const url = mockAxios.history.get[0].url;
-            expect(url).toContain('_page=2');
-            expect(url).toContain('_itemsOnPage=25');
-        });
-        it('should include filter params', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onGet(/\/default\/transaction/).reply(200, transactionFixtures.listResponse);
-            await transactionList({
-                customerId: 'member-uuid',
-                documentNumber: 'DOC-001',
-                documentType: 'sell',
-                matched: true,
-            });
-            const url = mockAxios.history.get[0].url;
-            expect(url).toContain('customerId=member-uuid');
-            expect(url).toContain('header%3AdocumentNumber=DOC-001');
-            expect(url).toContain('header%3AdocumentType=sell');
-            expect(url).toContain('matched=true');
-        });
-    });
-    describe('transactionAssignMember', () => {
-        it('should assign transaction to member by customerId', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction/customer/assign').reply(200, transactionFixtures.assignResponse);
-            const result = await transactionAssignMember({
-                documentNumber: 'DOC-001',
-                customerId: 'member-uuid',
-            });
-            expect(result.transactionId).toBe('txn-uuid-123');
-            expect(result.customerId).toBe('member-uuid');
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.transactionDocumentNumber).toBe('DOC-001');
-            expect(requestData.customerId).toBe('member-uuid');
-        });
-        it('should assign by loyalty card number', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction/customer/assign').reply(200, transactionFixtures.assignResponse);
-            await transactionAssignMember({
-                documentNumber: 'DOC-001',
-                loyaltyCardNumber: 'CARD123456',
-            });
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.customerLoyaltyCardNumber).toBe('CARD123456');
-        });
-        it('should assign by phone number', async () => {
-            const mockAxios = getMockAxios();
-            mockAxios.onPost('/default/transaction/customer/assign').reply(200, transactionFixtures.assignResponse);
-            await transactionAssignMember({
-                documentNumber: 'DOC-001',
-                phone: '+1234567890',
-            });
-            const requestData = JSON.parse(mockAxios.history.post[0].data);
-            expect(requestData.customerPhoneNumber).toBe('+1234567890');
-        });
-        it('should throw error when no identifier provided', async () => {
-            await expect(transactionAssignMember({
-                documentNumber: 'DOC-001',
-            })).rejects.toThrow('At least one member identifier required');
-        });
-    });
-});

package/dist/utils/cursor.d.ts

@@ -1,84 +0,0 @@
-/**
- * Cursor-based pagination utilities for Open Loyalty MCP.
- *
- * Since the Open Loyalty API only supports offset-based pagination (_page/_itemsOnPage),
- * we implement client-side cursor emulation by encoding pagination state into opaque cursors.
- */
-/**
- * Internal cursor data structure.
- * Encoded as base64url JSON for the external cursor string.
- */
-export interface CursorData {
-    /** Page number (1-indexed) */
-    p: number;
-    /** Items per page */
-    pp: number;
-    /** Version for future migrations */
-    v: number;
-    /** Optional timestamp for expiration (not currently enforced) */
-    ts?: number;
-}
-/**
- * Pagination metadata returned in list responses.
- */
-export interface PaginationMeta {
-    /** Current cursor (encodes current page state) */
-    cursor: string;
-    /** Cursor for the next page, or undefined if no more pages */
-    nextCursor: string | undefined;
-    /** Whether there are more items after the current page */
-    hasMore: boolean;
-}
-/**
- * Encode pagination state into an opaque cursor string.
- * Uses base64url encoding of JSON data.
- *
- * @param data - Pagination state to encode
- * @returns Opaque cursor string
- */
-export declare function encodeCursor(data: Omit<CursorData, 'v'>): string;
-/**
- * Decode an opaque cursor string back to pagination state.
- *
- * @param cursor - Opaque cursor string
- * @returns Decoded pagination state, or null if invalid
- */
-export declare function decodeCursor(cursor: string): CursorData | null;
-/**
- * Build pagination metadata for a list response.
- *
- * @param page - Current page number (1-indexed)
- * @param perPage - Items per page
- * @param itemCount - Number of items returned in current page
- * @param total - Total number of items (from API response, may be undefined)
- * @returns Pagination metadata with cursors
- */
-export declare function buildPaginationMeta(page: number, perPage: number, itemCount: number, total?: number): PaginationMeta;
-/**
- * Pagination input that supports both cursor and page/perPage.
- */
-export interface PaginationInput {
-    /** Opaque cursor from previous response (takes priority over page/perPage) */
-    cursor?: string;
-    /** Page number (1-indexed, used if no cursor) */
-    page?: number;
-    /** Items per page (used if no cursor) */
-    perPage?: number;
-}
-/**
- * Resolved pagination parameters for API calls.
- */
-export interface ResolvedPagination {
-    /** Page number to request (1-indexed) */
-    page: number;
-    /** Items per page */
-    perPage: number;
-}
-/**
- * Resolve pagination input to concrete page/perPage values.
- * If a cursor is provided and valid, it takes priority over page/perPage.
- *
- * @param input - Pagination input with optional cursor
- * @returns Resolved page and perPage values
- */
-export declare function resolvePaginationInput(input: PaginationInput): ResolvedPagination;

package/dist/utils/cursor.js

@@ -1,117 +0,0 @@
-/**
- * Cursor-based pagination utilities for Open Loyalty MCP.
- *
- * Since the Open Loyalty API only supports offset-based pagination (_page/_itemsOnPage),
- * we implement client-side cursor emulation by encoding pagination state into opaque cursors.
- */
-/** Current cursor format version */
-const CURSOR_VERSION = 1;
-/**
- * Encode pagination state into an opaque cursor string.
- * Uses base64url encoding of JSON data.
- *
- * @param data - Pagination state to encode
- * @returns Opaque cursor string
- */
-export function encodeCursor(data) {
-    const cursorData = {
-        ...data,
-        v: CURSOR_VERSION,
-    };
-    const json = JSON.stringify(cursorData);
-    // Use base64url encoding (URL-safe base64)
-    return Buffer.from(json, 'utf-8')
-        .toString('base64')
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_')
-        .replace(/=+$/, '');
-}
-/**
- * Decode an opaque cursor string back to pagination state.
- *
- * @param cursor - Opaque cursor string
- * @returns Decoded pagination state, or null if invalid
- */
-export function decodeCursor(cursor) {
-    try {
-        // Restore base64 from base64url
-        let base64 = cursor.replace(/-/g, '+').replace(/_/g, '/');
-        // Add padding if needed
-        const paddingNeeded = (4 - (base64.length % 4)) % 4;
-        base64 += '='.repeat(paddingNeeded);
-        const json = Buffer.from(base64, 'base64').toString('utf-8');
-        const data = JSON.parse(json);
-        // Validate required fields
-        if (typeof data.p !== 'number' || data.p < 1)
-            return null;
-        if (typeof data.pp !== 'number' || data.pp < 1)
-            return null;
-        if (typeof data.v !== 'number')
-            return null;
-        return data;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Build pagination metadata for a list response.
- *
- * @param page - Current page number (1-indexed)
- * @param perPage - Items per page
- * @param itemCount - Number of items returned in current page
- * @param total - Total number of items (from API response, may be undefined)
- * @returns Pagination metadata with cursors
- */
-export function buildPaginationMeta(page, perPage, itemCount, total) {
-    // Build current cursor
-    const cursor = encodeCursor({ p: page, pp: perPage });
-    // Determine if there are more pages
-    let hasMore = false;
-    if (total !== undefined && typeof total === 'number') {
-        // If we have total, calculate if there are more pages
-        hasMore = page * perPage < total;
-    }
-    else {
-        // If no total, assume more pages if we got a full page of results
-        hasMore = itemCount >= perPage;
-    }
-    // Build next cursor if there are more pages
-    const nextCursor = hasMore
-        ? encodeCursor({ p: page + 1, pp: perPage })
-        : undefined;
-    return {
-        cursor,
-        nextCursor,
-        hasMore,
-    };
-}
-/** Default page number if not specified */
-const DEFAULT_PAGE = 1;
-/** Default items per page if not specified */
-const DEFAULT_PER_PAGE = 25;
-/**
- * Resolve pagination input to concrete page/perPage values.
- * If a cursor is provided and valid, it takes priority over page/perPage.
- *
- * @param input - Pagination input with optional cursor
- * @returns Resolved page and perPage values
- */
-export function resolvePaginationInput(input) {
-    // If cursor is provided, try to decode it
-    if (input.cursor) {
-        const cursorData = decodeCursor(input.cursor);
-        if (cursorData) {
-            return {
-                page: cursorData.p,
-                perPage: cursorData.pp,
-            };
-        }
-        // Invalid cursor - fall through to page/perPage
-    }
-    // Use page/perPage with defaults
-    return {
-        page: input.page ?? DEFAULT_PAGE,
-        perPage: input.perPage ?? DEFAULT_PER_PAGE,
-    };
-}