@open-loyalty/mcp-server 1.5.3 → 1.7.0

package/dist/tools/store/handlers.js

@@ -0,0 +1,89 @@
+import { apiGet, apiPost, apiPut } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+export async function storeList(input) {
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.active !== undefined)
+        params.append("active[eq]", String(input.active));
+    if (input.name)
+        params.append("name[eq]", input.name);
+    if (input.code)
+        params.append("code", input.code);
+    const queryString = params.toString();
+    const url = `/store${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "STORE_PERMISSION_DENIED",
+                message: "You don't have permission to list stores",
+                hint: "Store management requires the STORE:VIEW permission or super admin access. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_store_list",
+            });
+        }
+        throw formatApiError(error, "ol_store_list");
+    }
+}
+export async function storeCreate(input) {
+    const payload = {
+        code: input.code,
+        name: input.name,
+    };
+    if (input.currency)
+        payload.currency = input.currency;
+    if (input.active !== undefined)
+        payload.active = input.active;
+    try {
+        const response = await apiPost("/store", { store: payload });
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            const allMessages = [error.response?.data?.message || "", ...(error.response?.data?.errors || []).map((e) => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("code") && (allMessages.includes("already") || allMessages.includes("unique") || allMessages.includes("exists"))) {
+                throw new OpenLoyaltyError({ code: "DUPLICATE_CODE", message: `Store with code '${input.code}' already exists`,
+                    hint: `Use ol_store_list(code: "${input.code}") to find the existing store, or choose a different code.`, relatedTool: "ol_store_create" });
+            }
+        }
+        throw formatApiError(error, "ol_store_create");
+    }
+}
+export async function storeGet(input) {
+    try {
+        const response = await apiGet(`/store/${input.storeId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Store '${input.storeId}' not found`,
+                hint: "Use ol_store_list() to find existing stores and their IDs.", relatedTool: "ol_store_get" });
+        }
+        throw formatApiError(error, "ol_store_get");
+    }
+}
+export async function storeUpdate(input) {
+    const payload = {};
+    if (input.name)
+        payload.name = input.name;
+    if (input.active !== undefined)
+        payload.active = input.active;
+    if (input.currency)
+        payload.currency = input.currency;
+    try {
+        await apiPut(`/store/${input.storeId}`, { store: payload });
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Store '${input.storeId}' not found`,
+                hint: "Use ol_store_list() to find existing stores and their IDs.", relatedTool: "ol_store_update" });
+        }
+        throw formatApiError(error, "ol_store_update");
+    }
+}

package/dist/tools/store/index.d.ts

@@ -0,0 +1,55 @@
+export { StoreListInputSchema, StoreCreateInputSchema, StoreGetInputSchema, StoreUpdateInputSchema, } from "./schemas.js";
+export type { Store, StoreListResponse } from "./schemas.js";
+export { storeList, storeCreate, storeGet, storeUpdate, } from "./handlers.js";
+import { storeList, storeCreate, storeGet, storeUpdate } from "./handlers.js";
+export declare const storeToolDefinitions: readonly [{
+    readonly name: "ol_store_list";
+    readonly title: "List Stores";
+    readonly description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        code: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof storeList;
+}, {
+    readonly name: "ol_store_create";
+    readonly title: "Create Store";
+    readonly description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.";
+    readonly readOnly: false;
+    readonly idempotent: false;
+    readonly inputSchema: {
+        code: import("zod").ZodString;
+        name: import("zod").ZodString;
+        currency: import("zod").ZodOptional<import("zod").ZodString>;
+        active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof storeCreate;
+}, {
+    readonly name: "ol_store_get";
+    readonly title: "Get Store Details";
+    readonly description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeId: import("zod").ZodString;
+    };
+    readonly handler: typeof storeGet;
+}, {
+    readonly name: "ol_store_update";
+    readonly title: "Update Store";
+    readonly description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).";
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeId: import("zod").ZodString;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        currency: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof storeUpdate;
+}];

package/dist/tools/store/index.js

@@ -0,0 +1,46 @@
+// Re-export schemas and types
+export { StoreListInputSchema, StoreCreateInputSchema, StoreGetInputSchema, StoreUpdateInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { storeList, storeCreate, storeGet, storeUpdate, } from "./handlers.js";
+// Imports for tool definitions
+import { StoreListInputSchema, StoreCreateInputSchema, StoreGetInputSchema, StoreUpdateInputSchema, } from "./schemas.js";
+import { storeList, storeCreate, storeGet, storeUpdate, } from "./handlers.js";
+// Tool definitions
+export const storeToolDefinitions = [
+    {
+        name: "ol_store_list",
+        title: "List Stores",
+        description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: StoreListInputSchema,
+        handler: storeList,
+    },
+    {
+        name: "ol_store_create",
+        title: "Create Store",
+        description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.",
+        readOnly: false,
+        idempotent: false,
+        inputSchema: StoreCreateInputSchema,
+        handler: storeCreate,
+    },
+    {
+        name: "ol_store_get",
+        title: "Get Store Details",
+        description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: StoreGetInputSchema,
+        handler: storeGet,
+    },
+    {
+        name: "ol_store_update",
+        title: "Update Store",
+        description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: StoreUpdateInputSchema,
+        handler: storeUpdate,
+    },
+];

package/dist/tools/store/schemas.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export interface Store {
+    storeId: string;
+    code: string;
+    currency: string;
+    name: string;
+    active: boolean;
+    createdBy?: string;
+    createdAt?: string;
+    updatedBy?: string;
+    updatedAt?: string;
+}
+export interface StoreListResponse {
+    items: Store[];
+    total?: Record<string, unknown>;
+}
+export declare const StoreListInputSchema: {
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+};
+export declare const StoreCreateInputSchema: {
+    code: z.ZodString;
+    name: z.ZodString;
+    currency: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const StoreGetInputSchema: {
+    storeId: z.ZodString;
+};
+export declare const StoreUpdateInputSchema: {
+    storeId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    currency: z.ZodOptional<z.ZodString>;
+};

package/dist/tools/store/schemas.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export const StoreListInputSchema = {
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    active: z.boolean().optional().describe("Filter by active status."),
+    name: z.string().optional().describe("Filter by store name."),
+    code: z.string().optional().describe("Filter by store code."),
+};
+export const StoreCreateInputSchema = {
+    code: z.string().describe("Store code (required, unique identifier like 'US', 'EU')."),
+    name: z.string().describe("Store name (required)."),
+    currency: z.string().optional().describe("Currency code (e.g., 'USD', 'EUR')."),
+    active: z.boolean().optional().describe("Whether the store is active (default: true)."),
+};
+export const StoreGetInputSchema = {
+    storeId: z.string().describe("The store ID (UUID) to retrieve."),
+};
+export const StoreUpdateInputSchema = {
+    storeId: z.string().describe("The store ID (UUID) to update."),
+    name: z.string().optional().describe("Store name."),
+    active: z.boolean().optional().describe("Whether the store is active."),
+    currency: z.string().optional().describe("Currency code."),
+};

package/dist/tools/tierset/handlers.js

@@ -26,6 +26,23 @@ export async function tiersetList(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "Cannot list tier sets - store not found",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_tierset_list",
+            });
+        }
+        if (axiosError.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "TIERSET_PERMISSION_DENIED",
+                message: "You don't have permission to view tier sets",
+                hint: "Tier set management requires the LEVEL:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_tierset_list",
+            });
+        }
         throw formatApiError(error, "ol_tierset_list");
     }
 }
@@ -70,7 +87,12 @@ export async function tiersetCreate(input) {
         // We need to fetch the full tier set to get the conditionId values
         const createResponse = response;
         if (!createResponse.tierSetId) {
-            throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
+            throw new OpenLoyaltyError({
+                code: "UNEXPECTED_RESPONSE",
+                message: `Unexpected response format from tier set creation: ${JSON.stringify(response)}`,
+                hint: "The API returned an unexpected response. This is likely a temporary issue or an MCP implementation bug. Try again, or use ol_tierset_list() to check if the tier set was created.",
+                relatedTool: "ol_tierset_create",
+            });
         }
         // Fetch the created tier set to get condition IDs
         const tierSetResponse = await apiGet(`/${storeCode}/tierSet/${createResponse.tierSetId}`);
@@ -109,6 +131,15 @@ export async function tiersetGet(input) {
         return validated;
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Tier set '${input.tierSetId}' not found`,
+                hint: "Use ol_tierset_list() to find existing tier sets and their IDs.",
+                relatedTool: "ol_tierset_get",
+            });
+        }
         throw formatApiError(error, "ol_tierset_get");
     }
 }
@@ -122,6 +153,15 @@ export async function tiersetUpdate(input) {
         existingTierSet = TierSetSchema.parse(response);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Tier set '${input.tierSetId}' not found`,
+                hint: "Use ol_tierset_list() to find existing tier sets and their IDs.",
+                relatedTool: "ol_tierset_update",
+            });
+        }
         throw formatApiError(error, "ol_tierset_update");
     }
     // Build payload using existing values as defaults
@@ -148,6 +188,26 @@ export async function tiersetUpdate(input) {
         await apiPut(`/${storeCode}/tierSet/${input.tierSetId}`, { tierSet: tierSetPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Tier set '${input.tierSetId}' not found`,
+                hint: "The tier set may have been deleted after it was read. Use ol_tierset_list() to verify it still exists.",
+                relatedTool: "ol_tierset_update",
+            });
+        }
+        if (axiosError.response?.status === 400) {
+            const allMessages = [axiosError.response?.data?.message || "", ...(axiosError.response?.data?.errors || []).map(e => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("active") && allMessages.includes("maximum")) {
+                throw new OpenLoyaltyError({
+                    code: "TIER_SET_LIMIT",
+                    message: "Cannot activate tier set - maximum 3 active tier sets per store",
+                    hint: "Use ol_tierset_list() to see existing active tier sets. Deactivate one before activating this one.",
+                    relatedTool: "ol_tierset_update",
+                });
+            }
+        }
         throw formatApiError(error, "ol_tierset_update");
     }
 }
@@ -174,6 +234,28 @@ export async function tiersetUpdateTiers(input) {
         await apiPut(`/${storeCode}/tierSet/${input.tierSetId}/tiers`, payload);
     }
     catch (error) {
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("condition") && (allMessages.includes("not found") || allMessages.includes("invalid") || allMessages.includes("does not exist"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_CONDITION_ID",
+                message: "Invalid conditionId in tier configuration",
+                hint: `Use ol_tierset_get(tierSetId: "${input.tierSetId}") to find valid conditionId values from conditions[].id. Use the SAME conditionId for ALL tiers.`,
+                relatedTool: "ol_tierset_update_tiers",
+            });
+        }
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Tier set '${input.tierSetId}' not found`,
+                hint: "Use ol_tierset_list() to find existing tier sets and their IDs.",
+                relatedTool: "ol_tierset_update_tiers",
+            });
+        }
         throw formatApiError(error, "ol_tierset_update_tiers");
     }
 }
@@ -191,6 +273,15 @@ export async function tiersetGetTiers(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Tier set '${input.tierSetId}' not found`,
+                hint: "Use ol_tierset_list() to find existing tier sets and their IDs.",
+                relatedTool: "ol_tierset_get_tiers",
+            });
+        }
         throw formatApiError(error, "ol_tierset_get_tiers");
     }
 }

package/dist/tools/tierset/index.d.ts

@@ -7,6 +7,7 @@ export declare const tiersetToolDefinitions: readonly [{
     readonly title: "List Loyalty Programs";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         page: import("zod").ZodOptional<import("zod").ZodNumber>;
@@ -18,6 +19,7 @@ export declare const tiersetToolDefinitions: readonly [{
     readonly title: "Create Loyalty Program";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         name: import("zod").ZodString;
@@ -39,6 +41,7 @@ export declare const tiersetToolDefinitions: readonly [{
     readonly title: "Get Loyalty Program Details";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         tierSetId: import("zod").ZodString;
@@ -47,6 +50,7 @@ export declare const tiersetToolDefinitions: readonly [{
 }, {
     readonly name: "ol_tierset_update";
     readonly title: "Update Loyalty Program";
+    readonly idempotent: true;
     readonly description: string;
     readonly readOnly: false;
     readonly inputSchema: {
@@ -70,6 +74,7 @@ export declare const tiersetToolDefinitions: readonly [{
 }, {
     readonly name: "ol_tierset_update_tiers";
     readonly title: "Configure Tier Thresholds";
+    readonly idempotent: true;
     readonly description: "Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.\n\n⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.\n\n⚠️ INPUT FORMAT: Pass 'name' and 'description' as TOP-LEVEL fields on each tier object.\n❌ WRONG: { translations: { en: { name: \"Bronze\" } } }\n✅ CORRECT: { name: \"Bronze\", description: \"Entry tier\" }\n\nExample - Creating 4 tiers in ONE call:\ntiers: [\n  { name: \"Bronze\", description: \"Entry tier\", conditions: [{ conditionId: \"xxx\", value: 0 }] },\n  { name: \"Silver\", description: \"500+ points\", conditions: [{ conditionId: \"xxx\", value: 500 }] },\n  { name: \"Gold\", description: \"1000+ points\", conditions: [{ conditionId: \"xxx\", value: 1000 }] },\n  { name: \"Platinum\", description: \"Top tier\", conditions: [{ conditionId: \"xxx\", value: 2000 }] }\n]\n\nThe conditionId must match the one from tierset_get response - use the SAME conditionId for all tiers.";
     readonly readOnly: false;
     readonly inputSchema: {
@@ -116,6 +121,7 @@ export declare const tiersetToolDefinitions: readonly [{
     readonly title: "Get Tier Configuration";
     readonly description: "Get all tiers in a tier set. Returns levelId values that can be used for campaign targeting. Includes each tier's name and condition thresholds.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         tierSetId: import("zod").ZodString;

package/dist/tools/tierset/index.js

@@ -14,6 +14,7 @@ export const tiersetToolDefinitions = [
             "⚠️ ALWAYS check existing tier sets FIRST before creating - reuse if one exists. " +
             "Returns tierSetId, name, active status, and tier count for each tier set.",
         readOnly: true,
+        idempotent: true,
         inputSchema: TierSetListInputSchema,
         handler: tiersetList,
     },
@@ -28,6 +29,7 @@ export const tiersetToolDefinitions = [
             "REQUIRED: name, conditions array. Only name/description/conditions accepted at creation. " +
             "NOTE: Use 'attribute' NOT 'type' in conditions. For unit-based attributes, set walletType to 'default'.",
         readOnly: false,
+        idempotent: false,
         inputSchema: TierSetCreateInputSchema,
         handler: tiersetCreate,
     },
@@ -38,17 +40,20 @@ export const tiersetToolDefinitions = [
             "CRITICAL: After tierset_create, call this to get the conditionId from conditions[].id. " +
             "Use this SAME conditionId for ALL tiers when calling tierset_update_tiers.",
         readOnly: true,
+        idempotent: true,
         inputSchema: TierSetGetInputSchema,
         handler: tiersetGet,
     },
     {
         name: "ol_tierset_update",
         title: "Update Loyalty Program",
+        idempotent: true,
         description: "Update tier set metadata (name, description, active status, downgrade settings). " +
             "KEY DECISIONS (confirm with user if not specified): " +
             "1. Downgrade policy -- 'none' (members never lose tier), 'automatic' (instant downgrade), 'x_days' (grace period) " +
             "2. Active toggle -- activating affects ALL members' tier placement immediately " +
-            "Automatically preserves existing conditions. Does not modify tiers -- use tierset_update_tiers for that.",
+            "Automatically preserves existing conditions. Does not modify tiers -- use tierset_update_tiers for that. " +
+            "downgrade.mode valid values: 'none' (no downgrade), 'x_days' (downgrade after X days -- set downgrade.days), 'automatic' (immediate downgrade when conditions not met).",
         readOnly: false,
         inputSchema: TierSetUpdateInputSchema,
         handler: tiersetUpdate,
@@ -56,6 +61,7 @@ export const tiersetToolDefinitions = [
     {
         name: "ol_tierset_update_tiers",
         title: "Configure Tier Thresholds",
+        idempotent: true,
         description: `Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.
 
 ⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.
@@ -82,6 +88,7 @@ The conditionId must match the one from tierset_get response - use the SAME cond
         title: "Get Tier Configuration",
         description: "Get all tiers in a tier set. Returns levelId values that can be used for campaign targeting. Includes each tier's name and condition thresholds.",
         readOnly: true,
+        idempotent: true,
         inputSchema: TierSetGetTiersInputSchema,
         handler: tiersetGetTiers,
     },

package/dist/tools/transaction/handlers.js

@@ -69,6 +69,15 @@ export async function transactionGet(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Transaction '${input.transactionId}' not found`,
+                hint: `Use ol_transaction_list(documentNumber: "...") to verify the transaction exists. The transactionId may be incorrect.`,
+                relatedTool: "ol_transaction_get",
+            });
+        }
         throw formatApiError(error, "ol_transaction_get");
     }
 }
@@ -154,6 +163,37 @@ export async function transactionAssignMember(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : "",
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (axiosError.response?.status === 404 || (allMessages.includes("transaction") && allMessages.includes("not found"))) {
+            throw new OpenLoyaltyError({
+                code: "TRANSACTION_NOT_FOUND",
+                message: `Transaction with document number '${input.documentNumber}' not found`,
+                hint: `Use ol_transaction_list(documentNumber: "${input.documentNumber}") to verify the transaction exists. The documentNumber must match exactly.`,
+                relatedTool: "ol_transaction_assign_member",
+            });
+        }
+        if (allMessages.includes("already") && (allMessages.includes("assigned") || allMessages.includes("matched"))) {
+            throw new OpenLoyaltyError({
+                code: "ALREADY_ASSIGNED",
+                message: `Transaction '${input.documentNumber}' is already assigned to a member`,
+                hint: `Use ol_transaction_list(documentNumber: "${input.documentNumber}") to see which member this transaction is assigned to. Transactions can only be assigned once.`,
+                relatedTool: "ol_transaction_assign_member",
+            });
+        }
+        if (allMessages.includes("customer") && allMessages.includes("not found")) {
+            throw new OpenLoyaltyError({
+                code: "MEMBER_NOT_FOUND",
+                message: "The specified member was not found",
+                hint: "Use ol_member_list() to search for the member by email, name, or phone. Verify the customerId, loyaltyCardNumber, or phone is correct.",
+                relatedTool: "ol_transaction_assign_member",
+            });
+        }
         throw formatApiError(error, "ol_transaction_assign_member");
     }
 }

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

@@ -6,6 +6,7 @@ export declare const transactionToolDefinitions: readonly [{
     readonly title: "Record Purchase";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         header: import("zod").ZodObject<{
@@ -114,6 +115,7 @@ export declare const transactionToolDefinitions: readonly [{
     readonly title: "Get Transaction Details";
     readonly description: "Get transaction details including items, customerData, matched status, and pointsEarned.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         transactionId: import("zod").ZodString;
@@ -122,6 +124,7 @@ export declare const transactionToolDefinitions: readonly [{
 }, {
     readonly name: "ol_transaction_list";
     readonly title: "Search Transactions";
+    readonly idempotent: true;
     readonly description: string;
     readonly readOnly: true;
     readonly inputSchema: {
@@ -142,6 +145,7 @@ export declare const transactionToolDefinitions: readonly [{
     readonly title: "Link Transaction to Member";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         documentNumber: import("zod").ZodString;

package/dist/tools/transaction/index.js

@@ -16,6 +16,7 @@ export const transactionToolDefinitions = [
             "NOTE: Use 'purchasedAt' NOT 'purchaseDate'. Pass sku as STRING, NOT object. " +
             "Returns transactionId and pointsEarned if campaigns triggered.",
         readOnly: false,
+        idempotent: false,
         inputSchema: TransactionCreateInputSchema,
         handler: transactionCreate,
     },
@@ -24,12 +25,14 @@ export const transactionToolDefinitions = [
         title: "Get Transaction Details",
         description: "Get transaction details including items, customerData, matched status, and pointsEarned.",
         readOnly: true,
+        idempotent: true,
         inputSchema: TransactionGetInputSchema,
         handler: transactionGet,
     },
     {
         name: "ol_transaction_list",
         title: "Search Transactions",
+        idempotent: true,
         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. " +
@@ -48,6 +51,7 @@ export const transactionToolDefinitions = [
         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.",
         readOnly: false,
+        idempotent: false,
         inputSchema: TransactionAssignMemberInputSchema,
         handler: transactionAssignMember,
     },

package/dist/tools/transaction/schemas.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 // Input Schemas
 const LabelInputSchema = z.object({
-    key: z.string(),
-    value: z.string(),
+    key: z.string().describe("Label key (e.g., 'category', 'channel')."),
+    value: z.string().describe("Label value (e.g., 'electronics', 'online')."),
 });
 const TransactionHeaderInputSchema = z.object({
     documentNumber: z.string().describe("Unique document number (required, unique per store)."),
@@ -15,7 +15,7 @@ const TransactionHeaderInputSchema = z.object({
 const TransactionItemInputSchema = z.object({
     sku: z.string().describe("Product SKU as a STRING (required). Use 'sku: \"PROD-123\"' NOT 'sku: { code: \"...\" }'."),
     name: z.string().describe("Product name (required, max 255 chars)."),
-    grossValue: z.number().describe("Item gross value (required)."),
+    grossValue: z.number().describe("Item total gross value (required). This is the total for the line item (unit price * quantity)."),
     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)."),