@open-loyalty/mcp-server 1.0.0

package/dist/tools/transaction.d.ts

@@ -0,0 +1,357 @@
+import { z } from "zod";
+export declare const TransactionCreateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    header: z.ZodObject<{
+        documentNumber: z.ZodString;
+        purchasedAt: z.ZodString;
+        documentType: z.ZodOptional<z.ZodEnum<["sell", "return"]>>;
+        linkedDocumentNumber: z.ZodOptional<z.ZodString>;
+        purchasePlace: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            key: string;
+        }, {
+            value: string;
+            key: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        documentNumber: string;
+        purchasedAt: string;
+        documentType?: "sell" | "return" | undefined;
+        linkedDocumentNumber?: string | undefined;
+        purchasePlace?: string | undefined;
+        labels?: {
+            value: string;
+            key: string;
+        }[] | undefined;
+    }, {
+        documentNumber: string;
+        purchasedAt: string;
+        documentType?: "sell" | "return" | undefined;
+        linkedDocumentNumber?: string | undefined;
+        purchasePlace?: string | undefined;
+        labels?: {
+            value: string;
+            key: string;
+        }[] | undefined;
+    }>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        name: z.ZodString;
+        grossValue: z.ZodNumber;
+        category: z.ZodString;
+        quantity: z.ZodOptional<z.ZodNumber>;
+        highPrecisionQuantity: z.ZodOptional<z.ZodNumber>;
+        maker: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            key: string;
+        }, {
+            value: string;
+            key: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        sku: string;
+        grossValue: number;
+        category: string;
+        quantity?: number | undefined;
+        labels?: {
+            value: string;
+            key: string;
+        }[] | undefined;
+        highPrecisionQuantity?: number | undefined;
+        maker?: string | undefined;
+    }, {
+        name: string;
+        sku: string;
+        grossValue: number;
+        category: string;
+        quantity?: number | undefined;
+        labels?: {
+            value: string;
+            key: string;
+        }[] | undefined;
+        highPrecisionQuantity?: number | undefined;
+        maker?: string | undefined;
+    }>, "many">;
+    customerData: z.ZodOptional<z.ZodObject<{
+        customerId: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        phone: z.ZodOptional<z.ZodString>;
+        loyaltyCardNumber: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | undefined;
+        email?: string | undefined;
+        phone?: string | undefined;
+        loyaltyCardNumber?: string | undefined;
+        customerId?: string | undefined;
+    }, {
+        name?: string | undefined;
+        email?: string | undefined;
+        phone?: string | undefined;
+        loyaltyCardNumber?: string | undefined;
+        customerId?: string | undefined;
+    }>>;
+};
+export declare const TransactionGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    transactionId: z.ZodString;
+};
+export declare const TransactionListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    customerId: z.ZodOptional<z.ZodString>;
+    documentNumber: z.ZodOptional<z.ZodString>;
+    documentType: z.ZodOptional<z.ZodEnum<["sell", "return"]>>;
+    matched: z.ZodOptional<z.ZodBoolean>;
+    purchasedAtFrom: z.ZodOptional<z.ZodString>;
+    purchasedAtTo: z.ZodOptional<z.ZodString>;
+};
+export declare const TransactionAssignMemberInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    documentNumber: z.ZodString;
+    customerId: z.ZodOptional<z.ZodString>;
+    loyaltyCardNumber: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+};
+export declare function transactionCreate(input: {
+    storeCode?: string;
+    header: {
+        documentNumber: string;
+        purchasedAt: string;
+        documentType?: string;
+        linkedDocumentNumber?: string;
+        purchasePlace?: string;
+        labels?: Array<{
+            key: string;
+            value: string;
+        }>;
+    };
+    items: Array<{
+        sku: string;
+        name: string;
+        grossValue: number;
+        category: string;
+        quantity?: number;
+        highPrecisionQuantity?: number;
+        maker?: string;
+        labels?: Array<{
+            key: string;
+            value: string;
+        }>;
+    }>;
+    customerData?: {
+        customerId?: string;
+        email?: string;
+        name?: string;
+        phone?: string;
+        loyaltyCardNumber?: string;
+    };
+}): Promise<{
+    transactionId: string;
+    pointsEarned?: number;
+}>;
+export declare function transactionGet(input: {
+    storeCode?: string;
+    transactionId: string;
+}): Promise<{
+    transactionId: string;
+    documentNumber: string;
+    documentType: string;
+    items: unknown[];
+    customerData?: unknown;
+    matched: boolean;
+    grossValue: number;
+    pointsEarned?: number;
+    purchasedAt?: string;
+}>;
+export declare function transactionList(input: {
+    storeCode?: string;
+    cursor?: string;
+    page?: number;
+    perPage?: number;
+    customerId?: string;
+    documentNumber?: string;
+    documentType?: string;
+    matched?: boolean;
+    purchasedAtFrom?: string;
+    purchasedAtTo?: string;
+}): Promise<{
+    transactions: Array<{
+        transactionId: string;
+        documentNumber: string;
+        grossValue: number;
+        matched: boolean;
+        customerId?: string;
+        pointsEarned?: number;
+        purchasedAt?: string;
+    }>;
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+    cursor?: string;
+}>;
+export declare function transactionAssignMember(input: {
+    storeCode?: string;
+    documentNumber: string;
+    customerId?: string;
+    loyaltyCardNumber?: string;
+    phone?: string;
+}): Promise<{
+    transactionId: string;
+    customerId: string;
+    pointsEarned?: number;
+}>;
+export declare const transactionToolDefinitions: readonly [{
+    readonly name: "openloyalty_transaction_create";
+    readonly description: string;
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        header: z.ZodObject<{
+            documentNumber: z.ZodString;
+            purchasedAt: z.ZodString;
+            documentType: z.ZodOptional<z.ZodEnum<["sell", "return"]>>;
+            linkedDocumentNumber: z.ZodOptional<z.ZodString>;
+            purchasePlace: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                value: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                key: string;
+            }, {
+                value: string;
+                key: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            documentNumber: string;
+            purchasedAt: string;
+            documentType?: "sell" | "return" | undefined;
+            linkedDocumentNumber?: string | undefined;
+            purchasePlace?: string | undefined;
+            labels?: {
+                value: string;
+                key: string;
+            }[] | undefined;
+        }, {
+            documentNumber: string;
+            purchasedAt: string;
+            documentType?: "sell" | "return" | undefined;
+            linkedDocumentNumber?: string | undefined;
+            purchasePlace?: string | undefined;
+            labels?: {
+                value: string;
+                key: string;
+            }[] | undefined;
+        }>;
+        items: z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            name: z.ZodString;
+            grossValue: z.ZodNumber;
+            category: z.ZodString;
+            quantity: z.ZodOptional<z.ZodNumber>;
+            highPrecisionQuantity: z.ZodOptional<z.ZodNumber>;
+            maker: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                value: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                key: string;
+            }, {
+                value: string;
+                key: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            sku: string;
+            grossValue: number;
+            category: string;
+            quantity?: number | undefined;
+            labels?: {
+                value: string;
+                key: string;
+            }[] | undefined;
+            highPrecisionQuantity?: number | undefined;
+            maker?: string | undefined;
+        }, {
+            name: string;
+            sku: string;
+            grossValue: number;
+            category: string;
+            quantity?: number | undefined;
+            labels?: {
+                value: string;
+                key: string;
+            }[] | undefined;
+            highPrecisionQuantity?: number | undefined;
+            maker?: string | undefined;
+        }>, "many">;
+        customerData: z.ZodOptional<z.ZodObject<{
+            customerId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            loyaltyCardNumber: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name?: string | undefined;
+            email?: string | undefined;
+            phone?: string | undefined;
+            loyaltyCardNumber?: string | undefined;
+            customerId?: string | undefined;
+        }, {
+            name?: string | undefined;
+            email?: string | undefined;
+            phone?: string | undefined;
+            loyaltyCardNumber?: string | undefined;
+            customerId?: string | undefined;
+        }>>;
+    };
+    readonly handler: typeof transactionCreate;
+}, {
+    readonly name: "openloyalty_transaction_get";
+    readonly description: "Get transaction details including items, customerData, matched status, and pointsEarned.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        transactionId: z.ZodString;
+    };
+    readonly handler: typeof transactionGet;
+}, {
+    readonly name: "openloyalty_transaction_list";
+    readonly description: string;
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        page: z.ZodOptional<z.ZodNumber>;
+        perPage: z.ZodOptional<z.ZodNumber>;
+        customerId: z.ZodOptional<z.ZodString>;
+        documentNumber: z.ZodOptional<z.ZodString>;
+        documentType: z.ZodOptional<z.ZodEnum<["sell", "return"]>>;
+        matched: z.ZodOptional<z.ZodBoolean>;
+        purchasedAtFrom: z.ZodOptional<z.ZodString>;
+        purchasedAtTo: z.ZodOptional<z.ZodString>;
+    };
+    readonly handler: typeof transactionList;
+}, {
+    readonly name: "openloyalty_transaction_assign_member";
+    readonly description: string;
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        documentNumber: z.ZodString;
+        customerId: z.ZodOptional<z.ZodString>;
+        loyaltyCardNumber: z.ZodOptional<z.ZodString>;
+        phone: z.ZodOptional<z.ZodString>;
+    };
+    readonly handler: typeof transactionAssignMember;
+}];

package/dist/tools/transaction.js

@@ -0,0 +1,242 @@
+import { z } from "zod";
+import { apiGet, apiPost } from "../client/http.js";
+import { formatApiError } from "../utils/errors.js";
+import { getConfig } from "../config.js";
+import { buildPaginationParams, normalizeDateToISO } from "../utils/pagination.js";
+// Input Schemas
+const LabelInputSchema = z.object({
+    key: z.string(),
+    value: z.string(),
+});
+const TransactionHeaderInputSchema = z.object({
+    documentNumber: z.string().describe("Unique document number (required, unique per store)."),
+    purchasedAt: z.string().describe("Purchase date/time in ISO format (required)."),
+    documentType: z.enum(["sell", "return"]).optional().describe("Document type: sell (default) or return."),
+    linkedDocumentNumber: z.string().optional().describe("Original document number (required for returns)."),
+    purchasePlace: z.string().optional().describe("Location/store where purchase was made."),
+    labels: z.array(LabelInputSchema).optional().describe("Custom key-value labels."),
+});
+const TransactionItemInputSchema = z.object({
+    sku: z.string().describe("Product SKU (required, max 255 chars)."),
+    name: z.string().describe("Product name (required, max 255 chars)."),
+    grossValue: z.number().describe("Item gross value (required)."),
+    category: z.string().describe("Product category (required, max 255 chars)."),
+    quantity: z.number().optional().describe("Item quantity (integer)."),
+    highPrecisionQuantity: z.number().optional().describe("High precision quantity (up to 3 decimals, recommended)."),
+    maker: z.string().optional().describe("Product brand/maker."),
+    labels: z.array(LabelInputSchema).optional().describe("Custom key-value labels."),
+});
+const CustomerDataInputSchema = z.object({
+    customerId: z.string().optional().describe("Member ID (UUID) for explicit assignment."),
+    email: z.string().optional().describe("Email for auto-matching to member."),
+    name: z.string().optional().describe("Customer name."),
+    phone: z.string().optional().describe("Phone for auto-matching to member."),
+    loyaltyCardNumber: z.string().optional().describe("Loyalty card for auto-matching."),
+});
+export const TransactionCreateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    header: TransactionHeaderInputSchema.describe("Transaction header with document info."),
+    items: z.array(TransactionItemInputSchema).describe("Array of purchased items (at least 1 required)."),
+    customerData: CustomerDataInputSchema.optional().describe("Customer data for auto-matching to member. If provided, triggers point campaigns."),
+};
+export const TransactionGetInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    transactionId: z.string().describe("The transaction ID (UUID) to retrieve."),
+};
+export const TransactionListInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    cursor: z.string().optional().describe("Pagination cursor from previous response. If provided, page/perPage are ignored."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().max(50).optional().describe("Items per page (default: 10, max: 50). Use 50 for aggregation queries to reduce API calls."),
+    customerId: z.string().optional().describe("Filter by member ID."),
+    documentNumber: z.string().optional().describe("Filter by document number."),
+    documentType: z.enum(["sell", "return"]).optional().describe("Filter by document type."),
+    matched: z.boolean().optional().describe("Filter by matched status."),
+    purchasedAtFrom: z.string().optional().describe("Filter transactions purchased on or after this date (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)."),
+    purchasedAtTo: z.string().optional().describe("Filter transactions purchased on or before this date (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)."),
+};
+export const TransactionAssignMemberInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    documentNumber: z.string().describe("Document number of the transaction to assign."),
+    customerId: z.string().optional().describe("Member ID (UUID) to assign."),
+    loyaltyCardNumber: z.string().optional().describe("Loyalty card number to match member."),
+    phone: z.string().optional().describe("Phone number to match member."),
+};
+// Handler functions
+export async function transactionCreate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const transactionPayload = {
+        header: {
+            documentNumber: input.header.documentNumber,
+            documentType: input.header.documentType || "sell",
+            purchasedAt: input.header.purchasedAt,
+            purchasePlace: input.header.purchasePlace,
+            linkedDocumentNumber: input.header.linkedDocumentNumber,
+            labels: input.header.labels,
+        },
+        items: input.items.map((item) => ({
+            sku: item.sku,
+            name: item.name,
+            grossValue: item.grossValue,
+            category: item.category,
+            highPrecisionQuantity: item.highPrecisionQuantity || item.quantity || 1,
+            maker: item.maker,
+            labels: item.labels,
+        })),
+    };
+    if (input.customerData) {
+        transactionPayload.customerData = input.customerData;
+    }
+    try {
+        const response = await apiPost(`/${storeCode}/transaction`, { transaction: transactionPayload });
+        return {
+            transactionId: response.transactionId,
+            pointsEarned: response.pointsEarned,
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_transaction_create");
+    }
+}
+export async function transactionGet(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        const response = await apiGet(`/${storeCode}/transaction/${input.transactionId}`);
+        const header = response.header;
+        return {
+            transactionId: response.transactionId,
+            documentNumber: (header?.documentNumber || response.documentNumber),
+            documentType: (header?.documentType || response.documentType || "sell"),
+            items: (response.items || []),
+            customerData: response.customerData,
+            matched: (response.matched ?? response.customerId != null),
+            grossValue: (response.grossValue || 0),
+            pointsEarned: response.pointsEarned,
+            purchasedAt: (header?.purchasedAt || response.purchasedAt),
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_transaction_get");
+    }
+}
+export async function transactionList(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const params = new URLSearchParams();
+    // Enforce max perPage of 50 (API limit)
+    const perPage = input.perPage ? Math.min(input.perPage, 50) : undefined;
+    // Use buildPaginationParams for cursor/page handling
+    buildPaginationParams({ cursor: input.cursor, page: input.page, perPage }, params);
+    if (input.customerId)
+        params.append("customerId", input.customerId);
+    if (input.documentNumber)
+        params.append("header:documentNumber", input.documentNumber);
+    if (input.documentType)
+        params.append("header:documentType", input.documentType);
+    if (input.matched !== undefined)
+        params.append("matched", String(input.matched));
+    if (input.purchasedAtFrom)
+        params.append("header:purchasedAt[gte]", normalizeDateToISO(input.purchasedAtFrom, "from"));
+    if (input.purchasedAtTo)
+        params.append("header:purchasedAt[lte]", normalizeDateToISO(input.purchasedAtTo, "to"));
+    const queryString = params.toString();
+    const url = `/${storeCode}/transaction${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const items = response.items || response.transactions || [];
+        const transactions = items.map((t) => {
+            const txn = t;
+            const header = txn.header;
+            const customerId = txn.customerId;
+            return {
+                transactionId: txn.transactionId,
+                documentNumber: (header?.documentNumber || txn.documentNumber),
+                grossValue: (txn.grossValue || 0),
+                matched: (txn.matched ?? customerId != null),
+                customerId,
+                pointsEarned: txn.pointsEarned,
+                purchasedAt: (header?.purchasedAt || txn.purchasedAt),
+            };
+        });
+        const total = response.total || {};
+        return {
+            transactions,
+            total: {
+                all: typeof total.all === 'number' ? total.all : undefined,
+                filtered: typeof total.filtered === 'number' ? total.filtered : undefined,
+            },
+            cursor: response.scroll,
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_transaction_list");
+    }
+}
+export async function transactionAssignMember(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    // At least one identifier required
+    if (!input.customerId && !input.loyaltyCardNumber && !input.phone) {
+        throw new Error("At least one member identifier required: customerId, loyaltyCardNumber, or phone.");
+    }
+    const assignPayload = {
+        transactionDocumentNumber: input.documentNumber,
+    };
+    if (input.customerId)
+        assignPayload.customerId = input.customerId;
+    if (input.loyaltyCardNumber)
+        assignPayload.customerLoyaltyCardNumber = input.loyaltyCardNumber;
+    if (input.phone)
+        assignPayload.customerPhoneNumber = input.phone;
+    try {
+        // API uses /transaction/assign with assign wrapper, not /transaction/customer/assign
+        const response = await apiPost(`/${storeCode}/transaction/assign`, { assign: assignPayload });
+        return {
+            transactionId: response.transactionId,
+            customerId: response.customerId,
+            pointsEarned: response.pointsEarned,
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_transaction_assign_member");
+    }
+}
+// Tool definitions
+export const transactionToolDefinitions = [
+    {
+        name: "openloyalty_transaction_create",
+        description: "Record a purchase transaction. If customerData provided, auto-matches to member and triggers point campaigns. " +
+            "For returns, set documentType='return' and provide linkedDocumentNumber referencing original sale. " +
+            "Returns transactionId and pointsEarned if campaigns triggered.",
+        inputSchema: TransactionCreateInputSchema,
+        handler: transactionCreate,
+    },
+    {
+        name: "openloyalty_transaction_get",
+        description: "Get transaction details including items, customerData, matched status, and pointsEarned.",
+        inputSchema: TransactionGetInputSchema,
+        handler: transactionGet,
+    },
+    {
+        name: "openloyalty_transaction_list",
+        description: "List transactions with optional filters. Filter by customerId, documentNumber, documentType, matched status, or date range (purchasedAtFrom/purchasedAtTo). " +
+            "Use ISO date format for date filters (e.g., '2025-07-01' or '2025-07-01T00:00:00Z'). " +
+            "Supports cursor pagination: provide 'cursor' from previous response to get next page. " +
+            "Returns customerId for matched transactions - use this for aggregation queries like 'top spenders'. " +
+            "IMPORTANT FOR AGGREGATION QUERIES: Always use cursor pagination and iterate through ALL pages, even for large datasets (1000+ transactions). " +
+            "Do NOT try to optimize or find shortcuts - the cursor approach is the correct and only way to get accurate results. " +
+            "Start with cursor='' (empty string), then use returned cursor for subsequent requests until no more data. " +
+            "Use perPage=50 to minimize API calls. Aggregate by customerId in your code, then use member_get for names.",
+        inputSchema: TransactionListInputSchema,
+        handler: transactionList,
+    },
+    {
+        name: "openloyalty_transaction_assign_member",
+        description: "Assign unmatched transaction to member by ID, card number, or phone. Triggers point campaigns. " +
+            "Use this to link a transaction that wasn't matched at creation time. Returns transactionId, customerId, and pointsEarned.",
+        inputSchema: TransactionAssignMemberInputSchema,
+        handler: transactionAssignMember,
+    },
+];

package/dist/tools/transaction.test.d.ts

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