@open-loyalty/mcp-server 1.5.3 → 1.7.0

package/dist/config.d.ts

@@ -27,5 +27,9 @@ export declare function runWithConfig<T>(override: {
  * Throws a clear error if no store code is available from either source.
  */
 export declare function getStoreCode(storeCode?: string): string;
+/**
+ * Returns true if required env vars are set (non-throwing check).
+ */
+export declare function isConfigured(): boolean;
 export declare function getConfig(): Config;
 export {};

package/dist/config.js

@@ -32,6 +32,17 @@ export function getStoreCode(storeCode) {
     }
     return code;
 }
+/**
+ * Returns true if required env vars are set (non-throwing check).
+ */
+export function isConfigured() {
+    if (config)
+        return true;
+    const requestConfig = configStorage.getStore();
+    if (requestConfig)
+        return true;
+    return !!(process.env.OPENLOYALTY_API_URL && process.env.OPENLOYALTY_API_TOKEN);
+}
 export function getConfig() {
     // Return request-scoped config if set (OAuth mode)
     const requestConfig = configStorage.getStore();

package/dist/index.js

@@ -2,15 +2,7 @@
 import "dotenv/config";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
-import { getConfig } from "./config.js";
 async function main() {
-    try {
-        getConfig();
-    }
-    catch (error) {
-        console.error("Configuration error:", error instanceof Error ? error.message : error);
-        process.exit(1);
-    }
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/server.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { getAllTools, getToolHandler } from "./tools/index.js";
 import { OpenLoyaltyError } from "./utils/errors.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { isConfigured } from "./config.js";
 /**
  * Convert an inputSchema object (Record<string, ZodType>) to a Zod object schema.
  * This allows centralized validation of all tool inputs.
@@ -50,9 +51,21 @@ export function createServer() {
             annotations: {
                 readOnlyHint: tool.readOnly,
                 destructiveHint: tool.destructive,
+                idempotentHint: tool.idempotent,
                 openWorldHint: true,
             },
         }, async (args) => {
+            if (!isConfigured()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Open Loyalty MCP server is not configured yet.\n\nRequired environment variables:\n- OPENLOYALTY_API_URL: Your OL instance API endpoint (e.g. https://your-instance.openloyalty.io/api)\n- OPENLOYALTY_API_TOKEN: API authentication token (Admin Panel > Settings > API Keys)\n- OPENLOYALTY_DEFAULT_STORE_CODE: Store identifier (optional, defaults to 'default')\n\nRun /openloyalty:setup in Claude Code to configure.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             const handler = getToolHandler(tool.name);
             if (!handler) {
                 return {

package/dist/tools/achievement/handlers.js

@@ -125,6 +125,15 @@ export async function achievementGet(input) {
         return response;
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Achievement '${input.achievementId}' not found`,
+                hint: "Use ol_achievement_list() to find existing achievements and their IDs.",
+                relatedTool: "ol_achievement_get",
+            });
+        }
         throw formatApiError(error, "ol_achievement_get");
     }
 }
@@ -147,6 +156,29 @@ export async function achievementUpdate(input) {
         await apiPut(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Achievement '${input.achievementId}' not found`,
+                hint: "Use ol_achievement_list() to find existing achievements and their IDs.", relatedTool: "ol_achievement_update" });
+        }
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [error instanceof Error ? error.message : "", axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)].join(" ").toLowerCase();
+        if (allMessages.includes("period") && (allMessages.includes("choice is invalid") || allMessages.includes("not valid"))) {
+            throw new OpenLoyaltyError({ code: "INVALID_PERIOD_TYPE", message: "Invalid period type in achievement rules",
+                hint: "For period.type use: 'day' (NOT 'days'), 'week', 'month', 'year', 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'.",
+                relatedTool: "ol_achievement_update" });
+        }
+        if (allMessages.includes("interval") && (allMessages.includes("choice is invalid") || allMessages.includes("not valid"))) {
+            throw new OpenLoyaltyError({ code: "INVALID_INTERVAL_TYPE", message: "Invalid interval type in achievement rule limit",
+                hint: "For limit.interval.type use: 'calendarDays' (NOT 'days'), 'calendarWeeks', 'calendarMonths', 'calendarYears'.",
+                relatedTool: "ol_achievement_update" });
+        }
+        if (allMessages.includes("choice is invalid") || allMessages.includes("selected choice is invalid")) {
+            throw new OpenLoyaltyError({ code: "INVALID_ENUM_VALUE", message: "An enum value in the achievement configuration is invalid",
+                hint: "Check: period.type ('day' not 'days'), limit.interval.type ('calendarDays' not 'days'), trigger, aggregation.type ('quantity').",
+                relatedTool: "ol_achievement_update" });
+        }
         throw formatApiError(error, "ol_achievement_update");
     }
 }
@@ -162,6 +194,11 @@ export async function achievementPatch(input) {
         await apiPatch(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Achievement '${input.achievementId}' not found`,
+                hint: "Use ol_achievement_list() to find existing achievements and their IDs.", relatedTool: "ol_achievement_patch" });
+        }
         throw formatApiError(error, "ol_achievement_patch");
     }
 }
@@ -186,6 +223,11 @@ export async function achievementGetMemberProgress(input) {
         return achievements[0];
     }
     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_achievement_get_member_progress" });
+        }
         throw formatApiError(error, "ol_achievement_get_member_progress");
     }
 }
@@ -215,6 +257,11 @@ export async function achievementListMemberAchievements(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_achievement_list_member_achievements" });
+        }
         throw formatApiError(error, "ol_achievement_list_member_achievements");
     }
 }

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

@@ -7,6 +7,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "List Achievements";
     readonly description: "List achievements. Achievements gamify member behavior by setting goals (e.g., 'Make 5 purchases this month'). Returns achievementId, name, active status, and associated badge. Use achievement_get for full rules and configuration.";
     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 achievementToolDefinitions: readonly [{
     readonly title: "Create Achievement";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         translations: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
@@ -155,7 +157,7 @@ export declare const achievementToolDefinitions: readonly [{
             uniqueReferee: import("zod").ZodOptional<import("zod").ZodBoolean>;
         }, "strip", import("zod").ZodTypeAny, {
             type: "direct" | "referral";
-            trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+            trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
             completeRule: {
                 periodGoal: string | number;
                 period: {
@@ -185,7 +187,7 @@ export declare const achievementToolDefinitions: readonly [{
             uniqueReferee?: boolean | undefined;
         }, {
             type: "direct" | "referral";
-            trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+            trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
             completeRule: {
                 periodGoal: string | number;
                 period: {
@@ -222,6 +224,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "Get Achievement Details";
     readonly description: "Get achievement details including all rules, conditions, activity period, limits, and completions count.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         achievementId: import("zod").ZodString;
@@ -232,6 +235,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "Update Achievement";
     readonly description: "Update achievement configuration. Requires full achievement object (translations, rules). Use achievement_get first to retrieve current configuration.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         achievementId: import("zod").ZodString;
@@ -368,7 +372,7 @@ export declare const achievementToolDefinitions: readonly [{
             uniqueReferee: import("zod").ZodOptional<import("zod").ZodBoolean>;
         }, "strip", import("zod").ZodTypeAny, {
             type: "direct" | "referral";
-            trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+            trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
             completeRule: {
                 periodGoal: string | number;
                 period: {
@@ -398,7 +402,7 @@ export declare const achievementToolDefinitions: readonly [{
             uniqueReferee?: boolean | undefined;
         }, {
             type: "direct" | "referral";
-            trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+            trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
             completeRule: {
                 periodGoal: string | number;
                 period: {
@@ -435,6 +439,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "Patch Achievement";
     readonly description: "Partial update of achievement. Use for simple changes like activating/deactivating or updating translations without providing full rules.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         achievementId: import("zod").ZodString;
@@ -456,6 +461,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "Get Member Achievement Progress";
     readonly description: "Get member's progress on a specific achievement. Returns completedCount, and for each rule: periodGoal, currentPeriodValue, and consecutive period tracking.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -467,6 +473,7 @@ export declare const achievementToolDefinitions: readonly [{
     readonly title: "List Member Achievements";
     readonly description: "List all achievements with member's progress. Returns each achievement's status, completion count, and per-rule progress. Use for displaying gamification dashboard.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;

package/dist/tools/achievement/index.js

@@ -10,6 +10,7 @@ export const achievementToolDefinitions = [
         title: "List Achievements",
         description: "List achievements. Achievements gamify member behavior by setting goals (e.g., 'Make 5 purchases this month'). Returns achievementId, name, active status, and associated badge. Use achievement_get for full rules and configuration.",
         readOnly: true,
+        idempotent: true,
         inputSchema: AchievementListInputSchema,
         handler: achievementList,
     },
@@ -25,8 +26,13 @@ export const achievementToolDefinitions = [
             "PATTERNS: " +
             "ONE-TIME: period: { type: 'day', consecutive: 1 }, limit: { value: 1 }, NO rule-level limit. " +
             "STREAK: period: { type: 'calendarDays', consecutive: 7 }, rule limit: { value: 1, interval: { type: 'calendarDays', value: 1 } }. " +
-            "Every rule requires: type='direct', aggregation: { type: 'quantity' }, completeRule with periodGoal.",
+            "Every rule requires: type='direct', aggregation: { type: 'quantity' }, completeRule with periodGoal. " +
+            "COMPLETE EXAMPLE for one-time badge: " +
+            "rules: [{ type: 'direct', trigger: 'transaction', aggregation: { type: 'quantity' }, " +
+            "completeRule: { periodGoal: 1, period: { type: 'day', consecutive: 1 } } }], " +
+            "limit: { value: 1 }",
         readOnly: false,
+        idempotent: false,
         inputSchema: AchievementCreateInputSchema,
         handler: achievementCreate,
     },
@@ -35,6 +41,7 @@ export const achievementToolDefinitions = [
         title: "Get Achievement Details",
         description: "Get achievement details including all rules, conditions, activity period, limits, and completions count.",
         readOnly: true,
+        idempotent: true,
         inputSchema: AchievementGetInputSchema,
         handler: achievementGet,
     },
@@ -43,6 +50,7 @@ export const achievementToolDefinitions = [
         title: "Update Achievement",
         description: "Update achievement configuration. Requires full achievement object (translations, rules). Use achievement_get first to retrieve current configuration.",
         readOnly: false,
+        idempotent: true,
         inputSchema: AchievementUpdateInputSchema,
         handler: achievementUpdate,
     },
@@ -51,6 +59,7 @@ export const achievementToolDefinitions = [
         title: "Patch Achievement",
         description: "Partial update of achievement. Use for simple changes like activating/deactivating or updating translations without providing full rules.",
         readOnly: false,
+        idempotent: true,
         inputSchema: AchievementPatchInputSchema,
         handler: achievementPatch,
     },
@@ -59,6 +68,7 @@ export const achievementToolDefinitions = [
         title: "Get Member Achievement Progress",
         description: "Get member's progress on a specific achievement. Returns completedCount, and for each rule: periodGoal, currentPeriodValue, and consecutive period tracking.",
         readOnly: true,
+        idempotent: true,
         inputSchema: AchievementGetMemberProgressInputSchema,
         handler: achievementGetMemberProgress,
     },
@@ -67,6 +77,7 @@ export const achievementToolDefinitions = [
         title: "List Member Achievements",
         description: "List all achievements with member's progress. Returns each achievement's status, completion count, and per-rule progress. Use for displaying gamification dashboard.",
         readOnly: true,
+        idempotent: true,
         inputSchema: AchievementListMemberAchievementsInputSchema,
         handler: achievementListMemberAchievements,
     },

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

@@ -141,7 +141,7 @@ export declare const AchievementCreateInputSchema: {
         uniqueReferee: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         type: "direct" | "referral";
-        trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+        trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
         completeRule: {
             periodGoal: string | number;
             period: {
@@ -171,7 +171,7 @@ export declare const AchievementCreateInputSchema: {
         uniqueReferee?: boolean | undefined;
     }, {
         type: "direct" | "referral";
-        trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+        trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
         completeRule: {
             periodGoal: string | number;
             period: {
@@ -342,7 +342,7 @@ export declare const AchievementUpdateInputSchema: {
         uniqueReferee: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         type: "direct" | "referral";
-        trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+        trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
         completeRule: {
             periodGoal: string | number;
             period: {
@@ -372,7 +372,7 @@ export declare const AchievementUpdateInputSchema: {
         uniqueReferee?: boolean | undefined;
     }, {
         type: "direct" | "referral";
-        trigger: "referral" | "transaction" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
+        trigger: "transaction" | "referral" | "custom_event" | "achievement" | "points_transfer" | "reward_redemption" | "tier_change" | "profile_update";
         completeRule: {
             periodGoal: string | number;
             period: {

package/dist/tools/achievement/schemas.js

@@ -83,15 +83,15 @@ export const AchievementCreateInputSchema = {
     })).describe("Achievement name and description. At least 'en' key required."),
     active: z.boolean().optional().describe("Whether achievement is active (default: false)."),
     activity: z.object({
-        startsAt: z.string().optional().describe("ISO datetime when achievement becomes active."),
-        endsAt: z.string().optional().describe("ISO datetime when achievement ends."),
-        operator: z.string().optional().describe("Activity condition operator."),
+        startsAt: z.string().optional().describe("ISO 8601 datetime when achievement becomes active (e.g., '2026-01-01T00:00:00+00:00')."),
+        endsAt: z.string().optional().describe("ISO 8601 datetime when achievement ends (e.g., '2026-12-31T23:59:59+00:00')."),
+        operator: z.string().optional().describe("Activity condition operator: 'between' (both startsAt and endsAt), 'from' (start only), or 'to' (end only)."),
     }).optional().describe("Time period configuration."),
     limit: z.object({
-        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges)."),
+        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges). Omit for unlimited."),
         interval: z.object({
-            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'."),
-            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period)."),
+            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'. NOT 'days'/'weeks' -- must use 'calendar' prefix."),
+            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period, 7 for every 7 calendar days)."),
         }).optional().describe("Interval for repeatable achievements (omit for one-time badges)."),
     }).optional().describe("How many times a member can earn this achievement. " +
         "BUSINESS DECISION: For one-time badges ('First Purchase'): set value=1 with NO interval. For repeatable challenges: omit or set higher. " +
@@ -115,18 +115,19 @@ export const AchievementUpdateInputSchema = {
     active: z.boolean().optional().describe("Whether achievement is active."),
     activity: z.object({
         startsAt: z.string().optional().describe("ISO datetime when achievement becomes active (e.g., '2026-01-01T00:00:00+00:00')."),
-        endsAt: z.string().optional().describe("ISO datetime when achievement ends."),
-        operator: z.string().optional().describe("Activity condition operator: 'between' (both dates) or 'from' (start only) or 'to' (end only)."),
+        endsAt: z.string().optional().describe("ISO datetime when achievement ends (e.g., '2026-12-31T23:59:59+00:00')."),
+        operator: z.string().optional().describe("Activity condition operator: 'between' (both startsAt and endsAt), 'from' (start only), or 'to' (end only)."),
     }).optional().describe("Time period configuration."),
     limit: z.object({
-        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges)."),
+        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges). Omit for unlimited."),
         interval: z.object({
-            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'."),
-            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period)."),
+            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'. NOT 'days'/'weeks' -- must use 'calendar' prefix."),
+            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period, 7 for every 7 calendar days)."),
         }).optional().describe("Interval for repeatable achievements (omit for one-time badges)."),
     }).optional().describe("Achievement limit. For ONE-TIME badges: { value: 1 } with NO interval. " +
         "For repeatable: omit or set higher value."),
-    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules. Use achievement_get first to retrieve current rules and include achievementRuleId for existing rules."),
+    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules defining completion criteria. Use achievement_get first to retrieve current rules and include achievementRuleId for existing rules. " +
+        "See AchievementCreateInputSchema rules for full pattern guidance (ONE-TIME vs STREAK)."),
     badgeTypeId: z.string().optional().describe("Badge type ID to award. Use ol_badge_list() to find valid IDs. " +
         "May cause 'extra fields' errors in some API versions - try without if creation fails."),
 };

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

@@ -0,0 +1,48 @@
+import { AdminUser, AdminUserListItem, AdminPermission } from "../../types/schemas/admin.js";
+export declare function adminList(input: {
+    page?: number;
+    perPage?: number;
+    email?: string;
+    isActive?: boolean;
+    firstName?: string;
+    lastName?: string;
+    role?: string;
+}): Promise<{
+    items: AdminUserListItem[];
+    total?: number;
+}>;
+export declare function adminCreate(input: {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    roles?: (string | number)[];
+    isActive?: boolean;
+    external?: boolean;
+    notificationsEnabled?: boolean;
+}): Promise<{
+    adminId: string;
+}>;
+export declare function adminGet(input: {
+    adminId: string;
+}): Promise<AdminUser>;
+export declare function adminUpdate(input: {
+    adminId: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    roles?: (string | number)[];
+    isActive?: boolean;
+    external?: boolean;
+    notificationsEnabled?: boolean;
+    password?: string;
+}): Promise<{
+    adminId: string;
+}>;
+export declare function adminChangePassword(input: {
+    currentPassword: string;
+    newPassword: string;
+}): Promise<void>;
+export declare function adminGetPermissions(): Promise<AdminPermission>;

package/dist/tools/admin/handlers.js

@@ -0,0 +1,159 @@
+import { apiGet, apiPost, apiPut } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+export async function adminList(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.email)
+        params.append("email", input.email);
+    if (input.isActive !== undefined)
+        params.append("isActive", String(input.isActive));
+    if (input.firstName)
+        params.append("firstName", input.firstName);
+    if (input.lastName)
+        params.append("lastName", input.lastName);
+    if (input.role)
+        params.append("role", input.role);
+    const queryString = params.toString();
+    const url = `/admin${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ADMIN_PERMISSION_DENIED",
+                message: "You don't have permission to list admin users",
+                hint: "Admin management requires the ADMIN:VIEW permission or super admin access. Use ol_admin_get_permissions() to check your current access level.",
+                relatedTool: "ol_admin_list",
+            });
+        }
+        throw formatApiError(error, "ol_admin_list");
+    }
+}
+export async function adminCreate(input) {
+    const payload = {
+        email: input.email,
+        plainPassword: input.password,
+    };
+    if (input.firstName)
+        payload.firstName = input.firstName;
+    if (input.lastName)
+        payload.lastName = input.lastName;
+    if (input.phone)
+        payload.phone = input.phone;
+    if (input.roles)
+        payload.roles = input.roles;
+    if (input.isActive !== undefined)
+        payload.isActive = input.isActive;
+    if (input.external !== undefined)
+        payload.external = input.external;
+    if (input.notificationsEnabled !== undefined)
+        payload.notificationsEnabled = input.notificationsEnabled;
+    try {
+        const response = await apiPost("/admin/data", { admin: 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("email") && (allMessages.includes("already") || allMessages.includes("unique") || allMessages.includes("exists"))) {
+                throw new OpenLoyaltyError({ code: "DUPLICATE_EMAIL", message: `Admin with email '${input.email}' already exists`,
+                    hint: `Use ol_admin_list(email: "${input.email}") to find the existing admin.`, relatedTool: "ol_admin_create" });
+            }
+        }
+        throw formatApiError(error, "ol_admin_create");
+    }
+}
+export async function adminGet(input) {
+    try {
+        const response = await apiGet(`/admin/data/${input.adminId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Admin '${input.adminId}' not found`,
+                hint: "Use ol_admin_list() to find existing admin users and their IDs.", relatedTool: "ol_admin_get" });
+        }
+        throw formatApiError(error, "ol_admin_get");
+    }
+}
+export async function adminUpdate(input) {
+    const payload = {};
+    if (input.email)
+        payload.email = input.email;
+    if (input.firstName)
+        payload.firstName = input.firstName;
+    if (input.lastName)
+        payload.lastName = input.lastName;
+    if (input.phone)
+        payload.phone = input.phone;
+    if (input.roles)
+        payload.roles = input.roles;
+    if (input.isActive !== undefined)
+        payload.isActive = input.isActive;
+    if (input.external !== undefined)
+        payload.external = input.external;
+    if (input.notificationsEnabled !== undefined)
+        payload.notificationsEnabled = input.notificationsEnabled;
+    if (input.password)
+        payload.plainPassword = input.password;
+    try {
+        const response = await apiPut(`/admin/data/${input.adminId}`, { admin: payload });
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Admin '${input.adminId}' not found`,
+                hint: "Use ol_admin_list() to find existing admin users and their IDs.", relatedTool: "ol_admin_update" });
+        }
+        throw formatApiError(error, "ol_admin_update");
+    }
+}
+export async function adminChangePassword(input) {
+    try {
+        await apiPut("/admin/password", {
+            currentPassword: input.currentPassword,
+            plainPassword: input.newPassword,
+        });
+    }
+    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("password") && (allMessages.includes("invalid") || allMessages.includes("incorrect") || allMessages.includes("wrong") || allMessages.includes("mismatch"))) {
+                throw new OpenLoyaltyError({ code: "INVALID_PASSWORD", message: "Current password is incorrect",
+                    hint: "The currentPassword you provided does not match. Verify the current password and try again.", relatedTool: "ol_admin_change_password" });
+            }
+            if (allMessages.includes("password") && (allMessages.includes("short") || allMessages.includes("weak") || allMessages.includes("length") || allMessages.includes("requirements") || allMessages.includes("strong"))) {
+                throw new OpenLoyaltyError({
+                    code: "WEAK_PASSWORD",
+                    message: "The new password does not meet security requirements",
+                    hint: "Password must be at least 8 characters and include a mix of uppercase, lowercase, numbers, and special characters.",
+                    relatedTool: "ol_admin_change_password",
+                });
+            }
+        }
+        throw formatApiError(error, "ol_admin_change_password");
+    }
+}
+export async function adminGetPermissions() {
+    try {
+        const response = await apiGet("/admin/permissions");
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 401) {
+            throw new OpenLoyaltyError({
+                code: "UNAUTHORIZED",
+                message: "Cannot retrieve permissions - authentication failed",
+                hint: "Your API token may be invalid or expired. Check the OL_API_TOKEN environment variable. If using OAuth, the token may need to be refreshed.",
+                relatedTool: "ol_admin_get_permissions",
+            });
+        }
+        throw formatApiError(error, "ol_admin_get_permissions");
+    }
+}