@open-loyalty/mcp-server 1.5.3 → 1.7.0

package/dist/tools/points/handlers.js

@@ -60,6 +60,31 @@ export async function pointsSpend(input) {
                 relatedTool: "ol_points_spend",
             });
         }
+        const axiosError2 = error;
+        if (axiosError2.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_spend",
+            });
+        }
+        if (axiosError2.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "POINTS_PERMISSION_DENIED",
+                message: "You don't have permission to spend member points",
+                hint: "Spending points requires the POINTS:MODIFY permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_points_spend",
+            });
+        }
+        if (allMessages.includes("points") && (allMessages.includes("positive") || allMessages.includes("greater") || allMessages.includes("zero") || allMessages.includes("negative"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_POINTS_AMOUNT",
+                message: "Points amount must be a positive number greater than zero",
+                hint: `You requested to spend ${input.points} points. The amount must be a positive integer greater than 0.`,
+                relatedTool: "ol_points_spend",
+            });
+        }
         throw formatApiError(error, "ol_points_spend");
     }
 }
@@ -102,6 +127,39 @@ export async function pointsTransfer(input) {
                 relatedTool: "ol_points_transfer",
             });
         }
+        const axiosError2 = error;
+        if (axiosError2.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "MEMBER_NOT_FOUND",
+                message: "Sender or receiver member not found",
+                hint: `Verify both member IDs exist: ol_member_get(memberId: "${input.senderId}") for sender and ol_member_get(memberId: "${input.receiverId}") for receiver. Use ol_member_list() to search by email if needed.`,
+                relatedTool: "ol_points_transfer",
+            });
+        }
+        if (axiosError2.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "POINTS_PERMISSION_DENIED",
+                message: "You don't have permission to transfer points between members",
+                hint: "Points transfer requires the POINTS:MODIFY permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_points_transfer",
+            });
+        }
+        if (allMessages.includes("transfer") && (allMessages.includes("disabled") || allMessages.includes("not allowed") || allMessages.includes("not enabled"))) {
+            throw new OpenLoyaltyError({
+                code: "TRANSFER_DISABLED",
+                message: "Points transfers are not enabled for this store",
+                hint: "Point-to-point transfers must be enabled in store settings. Contact a super admin to enable the transfer feature.",
+                relatedTool: "ol_points_transfer",
+            });
+        }
+        if (allMessages.includes("points") && (allMessages.includes("positive") || allMessages.includes("greater") || allMessages.includes("zero"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_POINTS_AMOUNT",
+                message: "Transfer amount must be a positive number greater than zero",
+                hint: `You requested to transfer ${input.points} points. The amount must be a positive integer greater than 0.`,
+                relatedTool: "ol_points_transfer",
+            });
+        }
         throw formatApiError(error, "ol_points_transfer");
     }
 }
@@ -151,6 +209,11 @@ export async function pointsGetBalance(input) {
         };
     }
     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.", relatedTool: "ol_points_get_balance" });
+        }
         throw formatApiError(error, "ol_points_get_balance");
     }
 }
@@ -188,6 +251,11 @@ export async function pointsGetHistory(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found or no history available`,
+                hint: "Use ol_member_list() to verify the member exists.", relatedTool: "ol_points_get_history" });
+        }
         throw formatApiError(error, "ol_points_get_history");
     }
 }
@@ -228,6 +296,11 @@ export async function pointsGetHistogram(input) {
         });
     }
     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 verify the member exists.", relatedTool: "ol_points_get_histogram" });
+        }
         throw formatApiError(error, "ol_points_get_histogram");
     }
 }

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

@@ -6,6 +6,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "Add Points to Member";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -21,6 +22,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "Spend Member Points";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -34,6 +36,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "Transfer Points Between Members";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         senderId: import("zod").ZodString;
@@ -46,6 +49,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "Check Points Balance";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -57,6 +61,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "View Points History";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -71,6 +76,7 @@ export declare const pointsToolDefinitions: readonly [{
     readonly title: "View Points Trends";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;

package/dist/tools/points/index.js

@@ -15,6 +15,7 @@ export const pointsToolDefinitions = [
             "Confirm amount and reason with user before proceeding. " +
             "Use for welcome bonuses, goodwill adjustments, or compensation. Returns transferId.",
         readOnly: false,
+        idempotent: false,
         inputSchema: PointsAddInputSchema,
         handler: pointsAdd,
     }, {
@@ -24,6 +25,7 @@ export const pointsToolDefinitions = [
             "WORKFLOW: Use ol_points_get_balance first to verify available (activeUnits) points before spending. " +
             "Returns transferId.",
         readOnly: false,
+        idempotent: false,
         inputSchema: PointsSpendInputSchema,
         handler: pointsSpend,
     }, {
@@ -32,6 +34,7 @@ export const pointsToolDefinitions = [
         description: "Transfer points from one member to another (P2P transfer). " +
             "Sender must have sufficient balance. Returns transferId.",
         readOnly: false,
+        idempotent: false,
         inputSchema: PointsTransferInputSchema,
         handler: pointsTransfer,
     }, {
@@ -40,6 +43,7 @@ export const pointsToolDefinitions = [
         description: "Get member points balance breakdown. activeUnits is available for spending. " +
             "earnedUnits shows lifetime earnings, lockedUnits shows pending points.",
         readOnly: true,
+        idempotent: true,
         inputSchema: PointsBalanceInputSchema,
         handler: pointsGetBalance,
     }, {
@@ -49,6 +53,7 @@ export const pointsToolDefinitions = [
             "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,
+        idempotent: true,
         inputSchema: PointsHistoryInputSchema,
         handler: pointsGetHistory,
     }, {
@@ -57,6 +62,7 @@ export const pointsToolDefinitions = [
         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,
+        idempotent: true,
         inputSchema: PointsHistogramInputSchema,
         handler: pointsGetHistogram,
     },

package/dist/tools/points/schemas.js

@@ -21,7 +21,7 @@ export const PointsTransferInputSchema = {
     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."),
     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."),
+    points: z.number().describe("Number of points to transfer (positive integer, e.g., 100). Sender must have sufficient active balance."),
 };
 export const PointsBalanceInputSchema = {
     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."),

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

@@ -6,6 +6,7 @@ export declare const referralToolDefinitions: readonly [{
     readonly title: "Create Referral Relationship";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -17,6 +18,7 @@ export declare const referralToolDefinitions: readonly [{
     readonly title: "List Referrals";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         referralId: import("zod").ZodOptional<import("zod").ZodString>;
@@ -36,6 +38,7 @@ export declare const referralToolDefinitions: readonly [{
     readonly description: string;
     readonly readOnly: false;
     readonly destructive: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;

package/dist/tools/referral/index.js

@@ -16,6 +16,7 @@ export const referralToolDefinitions = [
             "Use this after creating a new member who was referred by an existing member. " +
             "Both members must exist. A member can only have one referrer.",
         readOnly: false,
+        idempotent: false,
         inputSchema: ReferralCreateInputSchema,
         handler: referralCreate,
     },
@@ -27,6 +28,7 @@ export const referralToolDefinitions = [
             "Filter by refereeId to find who referred a specific member. " +
             "Returns referralId, referrerId, referrerName, refereeId, refereeName, and createdAt.",
         readOnly: true,
+        idempotent: true,
         inputSchema: ReferralListInputSchema,
         handler: referralList,
     },
@@ -38,6 +40,7 @@ export const referralToolDefinitions = [
             "The memberId is the referee (the member who was referred).",
         readOnly: false,
         destructive: true,
+        idempotent: true,
         inputSchema: ReferralDeleteInputSchema,
         handler: referralDelete,
     },

package/dist/tools/reward/handlers.js

@@ -117,6 +117,10 @@ export async function rewardGet(input) {
         return RewardSchema.parse(response);
     }
     catch (error) {
+        if (error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Reward '${input.rewardId}' not found`,
+                hint: "Use ol_reward_list() to find existing rewards and their IDs.", relatedTool: "ol_reward_get" });
+        }
         throw formatApiError(error, "ol_reward_get");
     }
 }
@@ -229,6 +233,10 @@ export async function rewardUpdate(input) {
         await apiPut(`/${storeCode}/reward/${input.rewardId}`, { reward: payload });
     }
     catch (error) {
+        if (error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Reward '${input.rewardId}' not found`,
+                hint: "Use ol_reward_list() to find existing rewards and their IDs.", relatedTool: "ol_reward_update" });
+        }
         throw formatApiError(error, "ol_reward_update");
     }
 }
@@ -238,6 +246,10 @@ export async function rewardActivate(input) {
         await apiPost(`/${storeCode}/reward/${input.rewardId}/activate`);
     }
     catch (error) {
+        if (error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Reward '${input.rewardId}' not found`,
+                hint: "Use ol_reward_list() to find existing rewards and their IDs.", relatedTool: "ol_reward_activate" });
+        }
         throw formatApiError(error, "ol_reward_activate");
     }
 }
@@ -247,6 +259,10 @@ export async function rewardDeactivate(input) {
         await apiPost(`/${storeCode}/reward/${input.rewardId}/deactivate`);
     }
     catch (error) {
+        if (error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Reward '${input.rewardId}' not found`,
+                hint: "Use ol_reward_list() to find existing rewards and their IDs.", relatedTool: "ol_reward_deactivate" });
+        }
         throw formatApiError(error, "ol_reward_deactivate");
     }
 }
@@ -287,21 +303,13 @@ export async function rewardBuy(input) {
                 relatedTool: "ol_reward_buy",
             });
         }
-        if (allMessages.includes("not active") || allMessages.includes("inactive") || allMessages.includes("reward is not active")) {
-            throw new OpenLoyaltyError({
-                code: "REWARD_NOT_ACTIVE",
-                message: "This reward is not active and cannot be purchased",
-                hint: `Use ol_reward_activate(rewardId: "${input.rewardId}") to activate the reward first, or use ol_reward_get(rewardId: "${input.rewardId}") to check its status.`,
-                relatedTool: "ol_reward_buy",
-            });
+        if (allMessages.includes("not active") || allMessages.includes("inactive")) {
+            throw new OpenLoyaltyError({ code: "REWARD_NOT_ACTIVE", message: "Reward is not active",
+                hint: `Use ol_reward_activate(rewardId: "${input.rewardId}") to activate it first.`, relatedTool: "ol_reward_buy" });
         }
         if (allMessages.includes("usage limit") || allMessages.includes("limit reached") || allMessages.includes("limit exceeded")) {
-            throw new OpenLoyaltyError({
-                code: "USAGE_LIMIT_REACHED",
-                message: "The usage limit for this reward has been reached",
-                hint: `Use ol_reward_get(rewardId: "${input.rewardId}") to check usageLimit settings. To increase limits, use ol_reward_update(rewardId: "${input.rewardId}", usageLimitPerUser: N).`,
-                relatedTool: "ol_reward_buy",
-            });
+            throw new OpenLoyaltyError({ code: "USAGE_LIMIT_REACHED", message: "Usage limit reached for this reward",
+                hint: `Use ol_reward_get(rewardId: "${input.rewardId}") to check limits. Use ol_reward_update to increase usageLimitPerUser.`, relatedTool: "ol_reward_buy" });
         }
         throw formatApiError(error, "ol_reward_buy");
     }

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

@@ -6,6 +6,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Browse Rewards";
     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>;
@@ -20,6 +21,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Create New Reward";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         translations: import("zod").ZodObject<{
@@ -87,6 +89,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Get Reward Details";
     readonly description: "Get full reward details including configuration, targeting, and coupon settings.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         rewardId: import("zod").ZodString;
@@ -95,6 +98,7 @@ export declare const rewardToolDefinitions: readonly [{
 }, {
     readonly name: "ol_reward_update";
     readonly title: "Update Reward";
+    readonly idempotent: true;
     readonly description: string;
     readonly readOnly: false;
     readonly inputSchema: {
@@ -115,6 +119,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Activate Reward";
     readonly description: "Activate a reward, making it available for members to redeem.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         rewardId: import("zod").ZodString;
@@ -125,6 +130,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Deactivate Reward";
     readonly description: "Deactivate a reward, hiding it from members. Already purchased rewards remain valid.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         rewardId: import("zod").ZodString;
@@ -135,6 +141,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Redeem Reward for Member";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         rewardId: import("zod").ZodString;
@@ -149,6 +156,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "Use Coupon Code";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -160,6 +168,7 @@ export declare const rewardToolDefinitions: readonly [{
     readonly title: "List Reward Categories";
     readonly description: "List reward categories. Use categoryId when creating or filtering rewards.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         page: import("zod").ZodOptional<import("zod").ZodNumber>;

package/dist/tools/reward/index.js

@@ -13,6 +13,7 @@ export const rewardToolDefinitions = [
         description: "List available rewards. Use reward_get for full details or reward_buy to redeem. " +
             "Filter by type, active status, or category.",
         readOnly: true,
+        idempotent: true,
         inputSchema: RewardListInputSchema,
         handler: rewardList,
     },
@@ -26,8 +27,11 @@ export const rewardToolDefinitions = [
             "3. Usage limits -- how many redemptions per member? How many total? (0 = unlimited, creates uncapped liability) " +
             "4. Targeting -- all members, or restricted to specific tiers/segments? " +
             "REQUIRED: translations.en.name, reward type, activity period, visibility period. " +
-            "For static_coupon: couponValue is also required.",
+            "For static_coupon: couponValue is also required. " +
+            "TARGET: Use target='level' (NOT 'tier') for tier targeting, target='segment' for segment targeting, or omit for all members. " +
+            "DATETIME: Use 'from'/'to' (NOT 'startsAt'/'endsAt' like campaigns). Format: 'YYYY-MM-DD HH:mm' e.g., '2026-01-01 00:00'.",
         readOnly: false,
+        idempotent: false,
         inputSchema: RewardCreateInputSchema,
         handler: rewardCreate,
     },
@@ -36,12 +40,14 @@ export const rewardToolDefinitions = [
         title: "Get Reward Details",
         description: "Get full reward details including configuration, targeting, and coupon settings.",
         readOnly: true,
+        idempotent: true,
         inputSchema: RewardGetInputSchema,
         handler: rewardGet,
     },
     {
         name: "ol_reward_update",
         title: "Update Reward",
+        idempotent: true,
         description: "Update reward configuration. Cannot change reward type after creation. " +
             "Uses GET-then-PUT pattern (fetches existing reward, merges changes, sends full object). " +
             "usageLimitPerUser can be set here or at creation time. " +
@@ -55,6 +61,7 @@ export const rewardToolDefinitions = [
         title: "Activate Reward",
         description: "Activate a reward, making it available for members to redeem.",
         readOnly: false,
+        idempotent: true,
         inputSchema: RewardIdInputSchema,
         handler: rewardActivate,
     },
@@ -63,6 +70,7 @@ export const rewardToolDefinitions = [
         title: "Deactivate Reward",
         description: "Deactivate a reward, hiding it from members. Already purchased rewards remain valid.",
         readOnly: false,
+        idempotent: true,
         inputSchema: RewardIdInputSchema,
         handler: rewardDeactivate,
     },
@@ -72,6 +80,7 @@ export const rewardToolDefinitions = [
         description: "Purchase reward for member, deducting points. Returns issuedRewardId and couponCode if applicable. " +
             "Use reward_redeem to mark the coupon as used.",
         readOnly: false,
+        idempotent: false,
         inputSchema: RewardBuyInputSchema,
         handler: rewardBuy,
     },
@@ -81,6 +90,7 @@ export const rewardToolDefinitions = [
         description: "Mark coupon as used. Validates coupon exists, belongs to member, and is active. " +
             "Fails if coupon is expired, already used, or doesn't exist.",
         readOnly: false,
+        idempotent: false,
         inputSchema: RewardRedeemInputSchema,
         handler: rewardRedeem,
     },
@@ -89,6 +99,7 @@ export const rewardToolDefinitions = [
         title: "List Reward Categories",
         description: "List reward categories. Use categoryId when creating or filtering rewards.",
         readOnly: true,
+        idempotent: true,
         inputSchema: RewardCategoryListInputSchema,
         handler: rewardCategoryList,
     },

package/dist/tools/reward/schemas.js

@@ -73,9 +73,9 @@ export const RewardGetInputSchema = {
 export const RewardUpdateInputSchema = {
     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."),
     rewardId: z.string().describe("The reward ID (UUID) to update."),
-    name: z.string().optional().describe("Reward name."),
+    name: z.string().optional().describe("Reward name (updates translations.en.name internally)."),
     costInPoints: z.number().optional().describe("Points required to redeem."),
-    description: z.string().optional().describe("Reward description."),
+    description: z.string().optional().describe("Reward description (updates translations.en.description internally)."),
     active: z.boolean().optional().describe("Whether reward is active."),
     categories: z.array(z.string()).optional().describe("Array of category UUIDs. Use ol_reward_category_list() to find valid categoryId values."),
     levels: z.array(z.string()).optional().describe("Array of tier level UUIDs. Use ol_tierset_get_tiers(tierSetId) to find valid levelId values."),

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

@@ -0,0 +1,35 @@
+import { Role, RoleListItem, ACLResource } from "../../types/schemas/role.js";
+import type { RolePermissionInput } from "./schemas.js";
+export declare function roleList(input: {
+    page?: number;
+    perPage?: number;
+    name?: string;
+    master?: boolean;
+    default?: boolean;
+}): Promise<{
+    items: RoleListItem[];
+    total?: Record<string, unknown>;
+}>;
+export declare function roleCreate(input: {
+    name: string;
+    permissions?: RolePermissionInput[];
+    stores?: string[];
+    default?: boolean;
+}): Promise<void>;
+export declare function roleGet(input: {
+    roleId: string | number;
+}): Promise<Role>;
+export declare function roleUpdate(input: {
+    roleId: string | number;
+    name?: string;
+    permissions?: RolePermissionInput[];
+    stores?: string[];
+    default?: boolean;
+}): Promise<void>;
+export declare function roleDelete(input: {
+    roleId: string | number;
+}): Promise<void>;
+export declare function aclGetResources(): Promise<{
+    items: ACLResource[];
+    total?: Record<string, unknown>;
+}>;

package/dist/tools/role/handlers.js

@@ -0,0 +1,127 @@
+import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+export async function roleList(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.name)
+        params.append("name", input.name);
+    if (input.master !== undefined)
+        params.append("master", String(input.master));
+    if (input.default !== undefined)
+        params.append("default", String(input.default));
+    const queryString = params.toString();
+    const url = `/acl/role${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ROLE_PERMISSION_DENIED",
+                message: "You don't have permission to view roles",
+                hint: "Role management requires super admin access or the ROLE:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_role_list",
+            });
+        }
+        throw formatApiError(error, "ol_role_list");
+    }
+}
+export async function roleCreate(input) {
+    const payload = {
+        name: input.name,
+    };
+    if (input.permissions)
+        payload.permissions = input.permissions;
+    if (input.stores)
+        payload.stores = input.stores;
+    if (input.default !== undefined)
+        payload.default = input.default;
+    try {
+        await apiPost("/acl/role", { role: payload });
+    }
+    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("name") && (allMessages.includes("already") || allMessages.includes("unique") || allMessages.includes("exists"))) {
+                throw new OpenLoyaltyError({ code: "DUPLICATE_NAME", message: `Role with name '${input.name}' already exists`,
+                    hint: "Use ol_role_list() to find existing roles, or choose a different name.", relatedTool: "ol_role_create" });
+            }
+        }
+        throw formatApiError(error, "ol_role_create");
+    }
+}
+export async function roleGet(input) {
+    try {
+        const response = await apiGet(`/acl/role/${input.roleId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Role '${input.roleId}' not found`,
+                hint: "Use ol_role_list() to find existing roles and their IDs.", relatedTool: "ol_role_get" });
+        }
+        throw formatApiError(error, "ol_role_get");
+    }
+}
+export async function roleUpdate(input) {
+    const payload = {};
+    if (input.name)
+        payload.name = input.name;
+    if (input.permissions)
+        payload.permissions = input.permissions;
+    if (input.stores)
+        payload.stores = input.stores;
+    if (input.default !== undefined)
+        payload.default = input.default;
+    try {
+        await apiPut(`/acl/role/${input.roleId}`, { role: payload });
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Role '${input.roleId}' not found`,
+                hint: "Use ol_role_list() to find existing roles and their IDs.", relatedTool: "ol_role_update" });
+        }
+        throw formatApiError(error, "ol_role_update");
+    }
+}
+export async function roleDelete(input) {
+    try {
+        await apiDelete(`/acl/role/${input.roleId}`);
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            if (error.response?.status === 404) {
+                throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Role '${input.roleId}' not found`,
+                    hint: "Use ol_role_list() to find existing roles and their IDs.", relatedTool: "ol_role_delete" });
+            }
+            const allMessages = [error.response?.data?.message || "", ...(error.response?.data?.errors || []).map((e) => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("in use") || allMessages.includes("assigned") || allMessages.includes("cannot delete")) {
+                throw new OpenLoyaltyError({ code: "ROLE_IN_USE", message: `Role '${input.roleId}' is assigned to admin users and cannot be deleted`,
+                    hint: "Remove this role from all admin users first using ol_admin_update(), then retry deletion.", relatedTool: "ol_role_delete" });
+            }
+        }
+        throw formatApiError(error, "ol_role_delete");
+    }
+}
+export async function aclGetResources() {
+    try {
+        const response = await apiGet("/acl/resources");
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ACL_PERMISSION_DENIED",
+                message: "You don't have permission to view ACL resources",
+                hint: "ACL resource listing requires super admin access or the ROLE:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_acl_get_resources",
+            });
+        }
+        throw formatApiError(error, "ol_acl_get_resources");
+    }
+}