@open-loyalty/mcp-server 1.3.7 → 1.5.3

package/dist/tools/export.js

@@ -5,7 +5,7 @@ import { getConfig, getStoreCode } from "../config.js";
 import axios from "axios";
 // Input Schemas
 export const ExportCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     type: z.enum([
         "campaignCode",
         "member",
@@ -18,7 +18,7 @@ export const ExportCreateInputSchema = {
     perPage: z.number().optional().describe("Items per page for export."),
 };
 export const ExportListInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     exportId: z.string().optional().describe("Filter by export ID."),
@@ -32,11 +32,11 @@ export const ExportListInputSchema = {
     status: z.enum(["pending", "done", "failed", "error"]).optional().describe("Filter by export status."),
 };
 export const ExportGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     exportId: z.string().describe("The export ID (UUID) to retrieve."),
 };
 export const ExportDownloadInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     exportId: z.string().describe("The export ID (UUID) to download. Export must have status 'done'."),
 };
 // Handler functions

package/dist/tools/import.d.ts

@@ -79,7 +79,7 @@ export declare function importGet(input: {
 export declare const importToolDefinitions: readonly [{
     readonly name: "ol_import_create";
     readonly title: "Create Bulk Import";
-    readonly description: "Create a new bulk import from CSV content. Returns importId for async tracking. Import types: member (member data), groupValue (group values), segmentMembers (segment membership), unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), campaignCode (campaign codes), rewardCoupon (reward coupons). CSV format required - provide plain text CSV content.";
+    readonly description: string;
     readonly readOnly: false;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;

package/dist/tools/import.js

@@ -6,7 +6,7 @@ import axios from "axios";
 import FormDataNode from "form-data";
 // Input Schemas
 export const ImportCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     type: z.enum([
         "member",
         "groupValue",
@@ -17,11 +17,12 @@ export const ImportCreateInputSchema = {
         "campaignCode",
         "rewardCoupon",
     ]).describe("Import type. Options: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon."),
-    fileContent: z.string().describe("CSV file content (plain text, not base64 encoded). Each line should be a comma-separated row."),
-    fileName: z.string().optional().describe("Optional file name for the import (default: import.csv)."),
+    fileContent: z.string().describe("File content as plain text (not base64 encoded). Accepts CSV (comma-separated rows) or XML format. " +
+        "For member imports, XML is the standard format. Auto-detected based on content or fileName extension."),
+    fileName: z.string().optional().describe("Optional file name for the import (default: import.xml). Use .xml extension for XML content, .csv for CSV content."),
 };
 export const ImportListInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     importId: z.string().optional().describe("Filter by import ID."),
@@ -37,7 +38,7 @@ export const ImportListInputSchema = {
     ]).optional().describe("Filter by import type."),
 };
 export const ImportGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     importId: z.string().describe("The import ID (UUID) to retrieve."),
     page: z.number().optional().describe("Page number for import items (default: 1)."),
     perPage: z.number().optional().describe("Items per page for import items (default: 25)."),
@@ -114,7 +115,11 @@ export const importToolDefinitions = [
     {
         name: "ol_import_create",
         title: "Create Bulk Import",
-        description: "Create a new bulk import from CSV content. Returns importId for async tracking. Import types: member (member data), groupValue (group values), segmentMembers (segment membership), unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), campaignCode (campaign codes), rewardCoupon (reward coupons). CSV format required - provide plain text CSV content.",
+        description: "Create a new bulk import from file content (CSV or XML). Returns importId for async tracking. " +
+            "Import types: member (member data - typically XML), groupValue (group values), segmentMembers (segment membership), " +
+            "unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), " +
+            "campaignCode (campaign codes), rewardCoupon (reward coupons). " +
+            "Provide plain text file content (CSV or XML). Format is auto-detected from content or fileName extension.",
         readOnly: false,
         inputSchema: ImportCreateInputSchema,
         handler: importCreate,

package/dist/tools/index.js

@@ -1,9 +1,9 @@
-import { walletTypeToolDefinitions } from "./wallet-type.js";
-import { tiersetToolDefinitions } from "./tierset.js";
+import { walletTypeToolDefinitions } from "./wallet-type/index.js";
+import { tiersetToolDefinitions } from "./tierset/index.js";
 import { memberToolDefinitions } from "./member/index.js";
-import { pointsToolDefinitions } from "./points.js";
+import { pointsToolDefinitions } from "./points/index.js";
 import { rewardToolDefinitions } from "./reward/index.js";
-import { transactionToolDefinitions } from "./transaction.js";
+import { transactionToolDefinitions } from "./transaction/index.js";
 // Phase 2 tools
 import { campaignToolDefinitions } from "./campaign/index.js";
 import { segmentToolDefinitions } from "./segment/index.js";

package/dist/tools/member/handlers.js

@@ -1,6 +1,6 @@
 import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
 import { MemberSchema } from "../../types/schemas/member.js";
-import { formatApiError } from "../../utils/errors.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
 import { getStoreCode } from "../../config.js";
 import { buildPaginationParams } from "../../utils/pagination.js";
 import { omitUndefined } from "../../utils/payload.js";
@@ -28,6 +28,21 @@ export async function memberCreate(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 (allMessages.includes("email") && (allMessages.includes("already") || allMessages.includes("unique") || allMessages.includes("exists"))) {
+            throw new OpenLoyaltyError({
+                code: "DUPLICATE_EMAIL",
+                message: `Member with email '${input.email}' already exists`,
+                hint: `Use ol_member_list(email: "${input.email}") to find the existing member. Each email must be unique per store.`,
+                relatedTool: "ol_member_create",
+            });
+        }
         throw formatApiError(error, "ol_member_create");
     }
 }
@@ -59,6 +74,15 @@ export async function memberGet(input) {
         return MemberSchema.parse(mapped);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Member '${input.memberId}' not found`,
+                hint: `Use ol_member_list() to search for the member by email, name, or phone. The member ID may have changed or the member may have been deleted.`,
+                relatedTool: "ol_member_get",
+            });
+        }
         throw formatApiError(error, "ol_member_get");
     }
 }
@@ -191,6 +215,29 @@ export async function memberAssignTier(input) {
         await apiPost(`/${storeCode}/member/${input.memberId}/tier`, { levelId: input.levelId });
     }
     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 (allMessages.includes("level") && (allMessages.includes("not found") || allMessages.includes("invalid") || allMessages.includes("does not exist"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_LEVEL",
+                message: `Level ID '${input.levelId}' is not valid`,
+                hint: `Use ol_tierset_get_tiers(tierSetId: "...") to find valid levelId values. The levelId must be a UUID from an existing tier in an active tier set.`,
+                relatedTool: "ol_member_assign_tier",
+            });
+        }
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Member '${input.memberId}' not found`,
+                hint: `Use ol_member_list() to search for the member by email, name, or phone. Verify the member ID is correct.`,
+                relatedTool: "ol_member_assign_tier",
+            });
+        }
         throw formatApiError(error, "ol_member_assign_tier");
     }
 }

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

@@ -4,7 +4,7 @@ import { memberCreate, memberGet, memberList, memberUpdate, memberActivate, memb
 export declare const memberToolDefinitions: readonly [{
     readonly name: "ol_member_create";
     readonly title: "Register New Member";
-    readonly description: "Register a new loyalty program member. Returns memberId for subsequent operations like points_add or member_get. Email must be unique within the store.";
+    readonly description: string;
     readonly readOnly: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;

package/dist/tools/member/index.js

@@ -10,7 +10,9 @@ export const memberToolDefinitions = [
     {
         name: "ol_member_create",
         title: "Register New Member",
-        description: "Register a new loyalty program member. Returns memberId for subsequent operations like points_add or member_get. Email must be unique within the store.",
+        description: "Register a new loyalty program member. Returns memberId for subsequent operations like points_add or member_get. " +
+            "REQUIRED: email (must be unique). OPTIONAL: firstName, lastName, phone, birthDate (YYYY-MM-DD), gender, loyaltyCardNumber. " +
+            "NOTE: agreement1 (terms) and agreement2 (marketing consent) are consent decisions -- never default these to true without explicit user approval.",
         readOnly: false,
         inputSchema: MemberCreateInputSchema,
         handler: memberCreate,

package/dist/tools/member/schemas.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export const MemberCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     email: z.string().describe("Member email address (required, must be unique)."),
     firstName: z.string().optional().describe("Member first name."),
     lastName: z.string().optional().describe("Member last name."),
@@ -8,9 +8,9 @@ export const MemberCreateInputSchema = {
     birthDate: z.string().optional().describe("Member birth date (YYYY-MM-DD format)."),
     gender: z.enum(["male", "female", "not_disclosed"]).optional().describe("Member gender."),
     loyaltyCardNumber: z.string().optional().describe("Loyalty card number. Auto-generated if not provided."),
-    agreement1: z.boolean().optional().describe("Terms acceptance."),
-    agreement2: z.boolean().optional().describe("Marketing consent."),
-    agreement3: z.boolean().optional().describe("Additional agreement."),
+    agreement1: z.boolean().optional().describe("Terms acceptance. BUSINESS DECISION: Legal requirement. Cannot default to true without explicit consent from the member."),
+    agreement2: z.boolean().optional().describe("Marketing consent. BUSINESS IMPACT: GDPR violation risk. Defaulting marketing consent to true without explicit approval can result in fines up to 4% of annual revenue or EUR 20M. NEVER silently default to true."),
+    agreement3: z.boolean().optional().describe("Additional agreement. Depends on store configuration."),
     address: z.object({
         street: z.string().optional(),
         city: z.string().optional(),
@@ -20,11 +20,11 @@ export const MemberCreateInputSchema = {
     }).optional().describe("Member address."),
 };
 export const MemberGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID) to retrieve."),
 };
 export const MemberListInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     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().optional().describe("Items per page (default: 10)."),
@@ -36,7 +36,7 @@ export const MemberListInputSchema = {
     active: z.boolean().optional().describe("Filter by active status."),
 };
 export const MemberUpdateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID) to update."),
     firstName: z.string().optional().describe("Member first name."),
     lastName: z.string().optional().describe("Member last name."),
@@ -50,16 +50,16 @@ export const MemberUpdateInputSchema = {
         country: z.string().optional(),
         province: z.string().optional(),
     }).optional().describe("Member address."),
-    agreement1: z.boolean().optional().describe("Terms acceptance."),
-    agreement2: z.boolean().optional().describe("Marketing consent."),
-    agreement3: z.boolean().optional().describe("Additional agreement."),
+    agreement1: z.boolean().optional().describe("Terms acceptance. BUSINESS DECISION: Legal requirement. Cannot default to true without explicit consent."),
+    agreement2: z.boolean().optional().describe("Marketing consent. BUSINESS IMPACT: GDPR violation risk. Changing marketing consent requires explicit member approval."),
+    agreement3: z.boolean().optional().describe("Additional agreement. Depends on store configuration."),
 };
 export const MemberIdInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
 };
 export const MemberAssignTierInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
     levelId: z.string().describe("The tier level ID (UUID) to assign."),
 };

package/dist/tools/points/handlers.d.ts

@@ -0,0 +1,75 @@
+import "../../types/schemas/points.js";
+export declare function pointsAdd(input: {
+    storeCode?: string;
+    memberId: string;
+    points: number;
+    walletCode?: string;
+    comment?: string;
+    expiresInDays?: number;
+    lockedUntilDays?: number;
+}): Promise<{
+    transferId: string;
+}>;
+export declare function pointsSpend(input: {
+    storeCode?: string;
+    memberId: string;
+    points: number;
+    walletCode?: string;
+    comment?: string;
+}): Promise<{
+    transferId: string;
+}>;
+export declare function pointsTransfer(input: {
+    storeCode?: string;
+    senderId: string;
+    receiverId: string;
+    points: number;
+}): Promise<{
+    transferId: string;
+}>;
+export declare function pointsGetBalance(input: {
+    storeCode?: string;
+    memberId: string;
+    walletCode?: string;
+}): Promise<{
+    activeUnits: number;
+    earnedUnits: number;
+    spentUnits: number;
+    lockedUnits: number;
+    expiredUnits: number;
+}>;
+export declare function pointsGetHistory(input: {
+    storeCode?: string;
+    memberId: string;
+    cursor?: string;
+    page?: number;
+    perPage?: number;
+    type?: string;
+}): Promise<{
+    transfers: Array<{
+        transferId: string;
+        type: string;
+        points: number;
+        comment?: string;
+        createdAt: string;
+    }>;
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+    cursor?: string;
+}>;
+export declare function pointsGetHistogram(input: {
+    storeCode?: string;
+    memberId: string;
+    pointType: string;
+    walletCode?: string;
+    interval?: string;
+    dateFrom?: string;
+    dateTo?: string;
+}): Promise<Array<{
+    date: string;
+    earned: number;
+    spent: number;
+    balance: number;
+}>>;

package/dist/tools/{points.js → points/handlers.js}

@@ -1,56 +1,9 @@
-import { z } from "zod";
-import { apiGet, apiPost } from "../client/http.js";
-import "../types/schemas/points.js";
-import { formatApiError, OpenLoyaltyError } from "../utils/errors.js";
-import { getStoreCode } from "../config.js";
-import { buildPaginationParams } from "../utils/pagination.js";
-import { omitUndefined } from "../utils/payload.js";
-// Input Schemas
-export const PointsAddInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    memberId: z.string().describe("The member ID (UUID) to add points to."),
-    points: z.number().describe("Number of points to add (positive number)."),
-    walletCode: z.string().optional().describe("Wallet type code (e.g., 'default'). Uses default wallet if not specified."),
-    comment: z.string().optional().describe("Reason for adding points (max 500 chars)."),
-    expiresInDays: z.number().optional().describe("Days until points expire (1-9999)."),
-    lockedUntilDays: z.number().optional().describe("Days until points become available (1-9999)."),
-};
-export const PointsSpendInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    memberId: z.string().describe("The member ID (UUID) to spend points from."),
-    points: z.number().describe("Number of points to spend (positive number)."),
-    walletCode: z.string().optional().describe("Wallet type code (e.g., 'default'). Uses default wallet if not specified."),
-    comment: z.string().optional().describe("Reason for spending points (max 500 chars)."),
-};
-export const PointsTransferInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    senderId: z.string().describe("The sender member ID (UUID)."),
-    receiverId: z.string().describe("The receiver member ID (UUID)."),
-    points: z.number().describe("Number of points to transfer."),
-};
-export const PointsBalanceInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    memberId: z.string().describe("The member ID (UUID) to get balance for."),
-    walletCode: z.string().optional().describe("Wallet type code. Returns all wallets if not specified."),
-};
-export const PointsHistoryInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    memberId: z.string().describe("The member ID (UUID) to get history for."),
-    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().optional().describe("Items per page (default: 10)."),
-    type: z.enum(["adding", "spending", "p2p_spending", "p2p_adding", "blocked", "expired"]).optional().describe("Filter by transfer type."),
-};
-export const PointsHistogramInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
-    memberId: z.string().describe("The member ID (UUID) to get histogram for."),
-    pointType: z.enum(["spent", "earned", "expired", "pending"]).describe("Filter by point type (required). One of: spent, earned, expired, pending."),
-    walletCode: z.string().optional().describe("Wallet type code. Uses default if not specified."),
-    interval: z.enum(["day", "week", "month"]).optional().describe("Time interval for aggregation (default: month)."),
-    dateFrom: z.string().optional().describe("Start date for histogram (ISO format: YYYY-MM-DD)."),
-    dateTo: z.string().optional().describe("End date for histogram (ISO format: YYYY-MM-DD)."),
-};
-// Handler functions
+import { apiGet, apiPost } from "../../client/http.js";
+import "../../types/schemas/points.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+import { buildPaginationParams } from "../../utils/pagination.js";
+import { omitUndefined } from "../../utils/payload.js";
 export async function pointsAdd(input) {
     const storeCode = getStoreCode(input.storeCode);
     const payload = omitUndefined({
@@ -65,6 +18,15 @@ export async function pointsAdd(input) {
         return { transferId: response.transferId };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "MEMBER_NOT_FOUND",
+                message: `Member '${input.memberId}' not found`,
+                hint: `Verify the member ID exists using ol_member_get(memberId: "${input.memberId}"). If not found, use ol_member_list(email: "...") to search by email.`,
+                relatedTool: "ol_points_add",
+            });
+        }
         throw formatApiError(error, "ol_points_add");
     }
 }
@@ -104,7 +66,12 @@ export async function pointsSpend(input) {
 export async function pointsTransfer(input) {
     const storeCode = getStoreCode(input.storeCode);
     if (input.senderId === input.receiverId) {
-        throw new Error("Cannot transfer points to yourself. senderId and receiverId must be different.");
+        throw new OpenLoyaltyError({
+            code: "SELF_TRANSFER",
+            message: "Cannot transfer points to yourself. senderId and receiverId must be different.",
+            hint: `The senderId and receiverId are both "${input.senderId}". Provide two different member IDs. Use ol_member_list() to find the correct receiver.`,
+            relatedTool: "ol_points_transfer",
+        });
     }
     const payload = {
         transfer: {
@@ -264,61 +231,3 @@ export async function pointsGetHistogram(input) {
         throw formatApiError(error, "ol_points_get_histogram");
     }
 }
-// Tool definitions
-export const pointsToolDefinitions = [
-    {
-        name: "ol_points_add",
-        title: "Add Points to Member",
-        description: "Add points to member wallet. Points can have optional expiration and lock period. " +
-            "Use for welcome bonuses, manual adjustments, or custom rewards. Returns transferId.",
-        readOnly: false,
-        inputSchema: PointsAddInputSchema,
-        handler: pointsAdd,
-    },
-    {
-        name: "ol_points_spend",
-        title: "Spend Member Points",
-        description: "Deduct points from member wallet. Fails if insufficient balance. " +
-            "Use points_get_balance first to verify available points. Returns transferId.",
-        readOnly: false,
-        inputSchema: PointsSpendInputSchema,
-        handler: pointsSpend,
-    },
-    {
-        name: "ol_points_transfer",
-        title: "Transfer Points Between Members",
-        description: "Transfer points from one member to another (P2P transfer). " +
-            "Sender must have sufficient balance. Returns transferId.",
-        readOnly: false,
-        inputSchema: PointsTransferInputSchema,
-        handler: pointsTransfer,
-    },
-    {
-        name: "ol_points_get_balance",
-        title: "Check Points Balance",
-        description: "Get member points balance breakdown. activeUnits is available for spending. " +
-            "earnedUnits shows lifetime earnings, lockedUnits shows pending points.",
-        readOnly: true,
-        inputSchema: PointsBalanceInputSchema,
-        handler: pointsGetBalance,
-    },
-    {
-        name: "ol_points_get_history",
-        title: "View Points History",
-        description: "Get points transaction history for a member. Filter by type: adding, spending, " +
-            "p2p_spending, p2p_adding, blocked, expired. Returns paginated list of transfers. " +
-            "Supports cursor pagination: provide 'cursor' from previous response to get next page.",
-        readOnly: true,
-        inputSchema: PointsHistoryInputSchema,
-        handler: pointsGetHistory,
-    },
-    {
-        name: "ol_points_get_histogram",
-        title: "View Points Trends",
-        description: "Get points histogram data for visualization. Shows earning and spending patterns over time. " +
-            "Use interval (day/week/month) to aggregate data and dateFrom/dateTo to filter range.",
-        readOnly: true,
-        inputSchema: PointsHistogramInputSchema,
-        handler: pointsGetHistogram,
-    },
-];

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

@@ -0,0 +1,84 @@
+export { PointsAddInputSchema, PointsSpendInputSchema, PointsTransferInputSchema, PointsBalanceInputSchema, PointsHistoryInputSchema, PointsHistogramInputSchema, } from "./schemas.js";
+export { pointsAdd, pointsSpend, pointsTransfer, pointsGetBalance, pointsGetHistory, pointsGetHistogram, } from "./handlers.js";
+import { pointsAdd, pointsSpend, pointsTransfer, pointsGetBalance, pointsGetHistory, pointsGetHistogram } from "./handlers.js";
+export declare const pointsToolDefinitions: readonly [{
+    readonly name: "ol_points_add";
+    readonly title: "Add Points to Member";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        points: import("zod").ZodNumber;
+        walletCode: import("zod").ZodOptional<import("zod").ZodString>;
+        comment: import("zod").ZodOptional<import("zod").ZodString>;
+        expiresInDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+        lockedUntilDays: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    readonly handler: typeof pointsAdd;
+}, {
+    readonly name: "ol_points_spend";
+    readonly title: "Spend Member Points";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        points: import("zod").ZodNumber;
+        walletCode: import("zod").ZodOptional<import("zod").ZodString>;
+        comment: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof pointsSpend;
+}, {
+    readonly name: "ol_points_transfer";
+    readonly title: "Transfer Points Between Members";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        senderId: import("zod").ZodString;
+        receiverId: import("zod").ZodString;
+        points: import("zod").ZodNumber;
+    };
+    readonly handler: typeof pointsTransfer;
+}, {
+    readonly name: "ol_points_get_balance";
+    readonly title: "Check Points Balance";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        walletCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof pointsGetBalance;
+}, {
+    readonly name: "ol_points_get_history";
+    readonly title: "View Points History";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        cursor: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        type: import("zod").ZodOptional<import("zod").ZodEnum<["adding", "spending", "p2p_spending", "p2p_adding", "blocked", "expired"]>>;
+    };
+    readonly handler: typeof pointsGetHistory;
+}, {
+    readonly name: "ol_points_get_histogram";
+    readonly title: "View Points Trends";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        pointType: import("zod").ZodEnum<["spent", "earned", "expired", "pending"]>;
+        walletCode: import("zod").ZodOptional<import("zod").ZodString>;
+        interval: import("zod").ZodOptional<import("zod").ZodEnum<["day", "week", "month"]>>;
+        dateFrom: import("zod").ZodOptional<import("zod").ZodString>;
+        dateTo: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof pointsGetHistogram;
+}];