@open-loyalty/mcp-server 1.5.3 → 1.7.0

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

@@ -0,0 +1,86 @@
+export { AdminListInputSchema, AdminCreateInputSchema, AdminGetInputSchema, AdminUpdateInputSchema, AdminChangePasswordInputSchema, } from "./schemas.js";
+export { adminList, adminCreate, adminGet, adminUpdate, adminChangePassword, adminGetPermissions, } from "./handlers.js";
+import { adminList, adminCreate, adminGet, adminUpdate, adminChangePassword, adminGetPermissions } from "./handlers.js";
+export declare const adminToolDefinitions: readonly [{
+    readonly name: "ol_admin_list";
+    readonly title: "List Admin Users";
+    readonly description: "List admin users with optional filtering. Returns paginated list of admin users with id, email, firstName, lastName, isActive, createdAt.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        email: import("zod").ZodOptional<import("zod").ZodString>;
+        isActive: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        firstName: import("zod").ZodOptional<import("zod").ZodString>;
+        lastName: import("zod").ZodOptional<import("zod").ZodString>;
+        role: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof adminList;
+}, {
+    readonly name: "ol_admin_create";
+    readonly title: "Create Admin User";
+    readonly description: "Create a new admin user. Requires email and password. Optionally assign roles, set active status, and configure notifications. Returns adminId.";
+    readonly readOnly: false;
+    readonly idempotent: false;
+    readonly inputSchema: {
+        email: import("zod").ZodString;
+        password: import("zod").ZodString;
+        firstName: import("zod").ZodOptional<import("zod").ZodString>;
+        lastName: import("zod").ZodOptional<import("zod").ZodString>;
+        phone: import("zod").ZodOptional<import("zod").ZodString>;
+        roles: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>, "many">>;
+        isActive: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        external: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        notificationsEnabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof adminCreate;
+}, {
+    readonly name: "ol_admin_get";
+    readonly title: "Get Admin User Details";
+    readonly description: "Get full admin user details by ID. Returns profile including email, name, roles, settings, active status, and creation date.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        adminId: import("zod").ZodString;
+    };
+    readonly handler: typeof adminGet;
+}, {
+    readonly name: "ol_admin_update";
+    readonly title: "Update Admin User";
+    readonly description: "Update admin user profile. Can update email, name, phone, roles, active status, and password. Returns adminId on success.";
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        adminId: import("zod").ZodString;
+        email: import("zod").ZodOptional<import("zod").ZodString>;
+        firstName: import("zod").ZodOptional<import("zod").ZodString>;
+        lastName: import("zod").ZodOptional<import("zod").ZodString>;
+        phone: import("zod").ZodOptional<import("zod").ZodString>;
+        roles: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>, "many">>;
+        isActive: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        external: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        notificationsEnabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        password: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof adminUpdate;
+}, {
+    readonly name: "ol_admin_change_password";
+    readonly title: "Change Admin Password";
+    readonly description: "Change the currently logged-in admin's password. Requires current password for verification. Returns void on success.";
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        currentPassword: import("zod").ZodString;
+        newPassword: import("zod").ZodString;
+    };
+    readonly handler: typeof adminChangePassword;
+}, {
+    readonly name: "ol_admin_get_permissions";
+    readonly title: "Get Admin Permissions";
+    readonly description: "Get the current admin user's permissions. Returns superAdmin flag, list of roles, and list of permission strings. Use to check what actions are available.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {};
+    readonly handler: typeof adminGetPermissions;
+}];

package/dist/tools/admin/index.js

@@ -0,0 +1,64 @@
+// Re-export schemas
+export { AdminListInputSchema, AdminCreateInputSchema, AdminGetInputSchema, AdminUpdateInputSchema, AdminChangePasswordInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { adminList, adminCreate, adminGet, adminUpdate, adminChangePassword, adminGetPermissions, } from "./handlers.js";
+// Imports for tool definitions
+import { AdminListInputSchema, AdminCreateInputSchema, AdminGetInputSchema, AdminUpdateInputSchema, AdminChangePasswordInputSchema, } from "./schemas.js";
+import { adminList, adminCreate, adminGet, adminUpdate, adminChangePassword, adminGetPermissions, } from "./handlers.js";
+// Tool definitions
+export const adminToolDefinitions = [
+    {
+        name: "ol_admin_list",
+        title: "List Admin Users",
+        description: "List admin users with optional filtering. Returns paginated list of admin users with id, email, firstName, lastName, isActive, createdAt.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: AdminListInputSchema,
+        handler: adminList,
+    },
+    {
+        name: "ol_admin_create",
+        title: "Create Admin User",
+        description: "Create a new admin user. Requires email and password. Optionally assign roles, set active status, and configure notifications. Returns adminId.",
+        readOnly: false,
+        idempotent: false,
+        inputSchema: AdminCreateInputSchema,
+        handler: adminCreate,
+    },
+    {
+        name: "ol_admin_get",
+        title: "Get Admin User Details",
+        description: "Get full admin user details by ID. Returns profile including email, name, roles, settings, active status, and creation date.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: AdminGetInputSchema,
+        handler: adminGet,
+    },
+    {
+        name: "ol_admin_update",
+        title: "Update Admin User",
+        description: "Update admin user profile. Can update email, name, phone, roles, active status, and password. Returns adminId on success.",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: AdminUpdateInputSchema,
+        handler: adminUpdate,
+    },
+    {
+        name: "ol_admin_change_password",
+        title: "Change Admin Password",
+        description: "Change the currently logged-in admin's password. Requires current password for verification. Returns void on success.",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: AdminChangePasswordInputSchema,
+        handler: adminChangePassword,
+    },
+    {
+        name: "ol_admin_get_permissions",
+        title: "Get Admin Permissions",
+        description: "Get the current admin user's permissions. Returns superAdmin flag, list of roles, and list of permission strings. Use to check what actions are available.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: {},
+        handler: adminGetPermissions,
+    },
+];

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

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export declare const AdminListInputSchema: {
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    email: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+};
+export declare const AdminCreateInputSchema: {
+    email: z.ZodString;
+    password: z.ZodString;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    roles: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    external: z.ZodOptional<z.ZodBoolean>;
+    notificationsEnabled: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const AdminGetInputSchema: {
+    adminId: z.ZodString;
+};
+export declare const AdminUpdateInputSchema: {
+    adminId: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    roles: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    external: z.ZodOptional<z.ZodBoolean>;
+    notificationsEnabled: z.ZodOptional<z.ZodBoolean>;
+    password: z.ZodOptional<z.ZodString>;
+};
+export declare const AdminChangePasswordInputSchema: {
+    currentPassword: z.ZodString;
+    newPassword: z.ZodString;
+};

package/dist/tools/admin/schemas.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export const AdminListInputSchema = {
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    email: z.string().optional().describe("Filter by email address."),
+    isActive: z.boolean().optional().describe("Filter by active status."),
+    firstName: z.string().optional().describe("Filter by first name."),
+    lastName: z.string().optional().describe("Filter by last name."),
+    role: z.string().optional().describe("Filter by role."),
+};
+export const AdminCreateInputSchema = {
+    email: z.string().describe("Admin email address (required)."),
+    password: z.string().describe("Admin password (required)."),
+    firstName: z.string().optional().describe("Admin first name."),
+    lastName: z.string().optional().describe("Admin last name."),
+    phone: z.string().optional().describe("Admin phone number."),
+    roles: z.array(z.union([z.string(), z.number()])).optional().describe("Role IDs to assign. Use ol_role_list to find valid role IDs."),
+    isActive: z.boolean().optional().describe("Whether account is active (default: true)."),
+    external: z.boolean().optional().describe("Whether admin is external."),
+    notificationsEnabled: z.boolean().optional().describe("Whether notifications are enabled."),
+};
+export const AdminGetInputSchema = {
+    adminId: z.string().describe("The admin ID (UUID) to retrieve."),
+};
+export const AdminUpdateInputSchema = {
+    adminId: z.string().describe("The admin ID (UUID) to update."),
+    email: z.string().optional().describe("Admin email address."),
+    firstName: z.string().optional().describe("Admin first name."),
+    lastName: z.string().optional().describe("Admin last name."),
+    phone: z.string().optional().describe("Admin phone number."),
+    roles: z.array(z.union([z.string(), z.number()])).optional().describe("Role IDs to assign. Use ol_role_list to find valid role IDs."),
+    isActive: z.boolean().optional().describe("Whether account is active."),
+    external: z.boolean().optional().describe("Whether admin is external."),
+    notificationsEnabled: z.boolean().optional().describe("Whether notifications are enabled."),
+    password: z.string().optional().describe("New password (if changing)."),
+};
+export const AdminChangePasswordInputSchema = {
+    currentPassword: z.string().describe("Current password."),
+    newPassword: z.string().describe("New password."),
+};

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

@@ -0,0 +1,42 @@
+import { TierAnalytics, MemberAnalytics, PointsAnalytics, TransactionAnalytics, ReferralAnalytics, CampaignAnalytics, DashboardOverview, UnitsOverview } from "../../types/schemas/analytics.js";
+export declare function analyticsTiers(input: {
+    storeCode?: string;
+}): Promise<TierAnalytics>;
+export declare function analyticsMembers(input: {
+    storeCode?: string;
+    withTransaction?: boolean;
+}): Promise<MemberAnalytics>;
+export declare function analyticsPoints(input: {
+    storeCode?: string;
+}): Promise<PointsAnalytics>;
+export declare function analyticsTransactions(input: {
+    storeCode?: string;
+}): Promise<TransactionAnalytics>;
+export declare function analyticsReferrals(input: {
+    storeCode?: string;
+}): Promise<ReferralAnalytics>;
+export declare function analyticsCampaigns(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    executedAt?: string;
+}): Promise<CampaignAnalytics>;
+export declare function analyticsDashboard(input: {
+    storeCode?: string;
+    dataType?: string;
+    aggregationType?: string;
+    intervalStartDate?: string;
+    intervalEndDate?: string;
+}): Promise<DashboardOverview>;
+export declare function analyticsUnits(input: {
+    storeCode?: string;
+    walletTypeCode: string;
+    dataType?: string;
+    aggregationType?: string;
+    intervalStartDate?: string;
+    intervalEndDate?: string;
+}): Promise<UnitsOverview>;
+export declare function analyticsCampaignDetail(input: {
+    storeCode?: string;
+    campaignId: string;
+}): Promise<Record<string, unknown>>;

package/dist/tools/analytics/handlers.js

@@ -0,0 +1,282 @@
+import { apiGet } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+import { getStoreCode } from "../../config.js";
+export async function analyticsTiers(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/analytics/levels`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No tier analytics available. The store may not exist or has no tier data.",
+                hint: "Use ol_store_list() to verify the store code is correct. If the store is new, tier data may take a few minutes to populate.",
+                relatedTool: "ol_analytics_tiers",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view tier analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access, or contact a super admin.",
+                relatedTool: "ol_analytics_tiers",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_tiers");
+    }
+}
+export async function analyticsMembers(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.withTransaction !== undefined) {
+        params.append("withTransaction", String(input.withTransaction));
+    }
+    const queryString = params.toString();
+    const url = `/${storeCode}/analytics/members${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No member analytics available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_members",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view member analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_members",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_members");
+    }
+}
+export async function analyticsPoints(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/analytics/points`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No points analytics available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_points",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view points analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_points",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_points");
+    }
+}
+export async function analyticsTransactions(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/analytics/transactions`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No transaction analytics available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_transactions",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view transaction analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_transactions",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_transactions");
+    }
+}
+export async function analyticsReferrals(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/analytics/referrals`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No referral analytics available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_referrals",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view referral analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_referrals",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_referrals");
+    }
+}
+export async function analyticsCampaigns(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.executedAt)
+        params.append("executedAt", input.executedAt);
+    const queryString = params.toString();
+    const url = `/${storeCode}/analytics/campaigns${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No campaign analytics available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_campaigns",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+            const allMessages = [error.response?.data?.message || "", ...(error.response?.data?.errors || []).map((e) => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("date") || allMessages.includes("format") || allMessages.includes("executedat")) {
+                throw new OpenLoyaltyError({
+                    code: "INVALID_DATE_FORMAT",
+                    message: "Invalid executedAt date format",
+                    hint: "Use ISO 8601 format: 'YYYY-MM-DDTHH:mm:ss+00:00' (e.g., '2026-01-01T00:00:00+00:00').",
+                    relatedTool: "ol_analytics_campaigns",
+                });
+            }
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view campaign analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_campaigns",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_campaigns");
+    }
+}
+export async function analyticsDashboard(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.dataType)
+        params.append("dataType", input.dataType);
+    if (input.aggregationType)
+        params.append("aggregationType", input.aggregationType);
+    if (input.intervalStartDate)
+        params.append("intervalStartDate", input.intervalStartDate);
+    if (input.intervalEndDate)
+        params.append("intervalEndDate", input.intervalEndDate);
+    const queryString = params.toString();
+    const url = `/${storeCode}/analytics/dashboard/general-overview${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "No dashboard data available for this store",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_analytics_dashboard",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+            const allMessages = [error.response?.data?.message || "", ...(error.response?.data?.errors || []).map((e) => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("date") || allMessages.includes("interval")) {
+                throw new OpenLoyaltyError({
+                    code: "INVALID_DATE_RANGE",
+                    message: "Invalid date range or format for dashboard analytics",
+                    hint: "Use YYYY-MM-DD format for intervalStartDate and intervalEndDate (e.g., '2026-01-01'). Ensure start date is before end date. Valid aggregationType values: 'day', 'week', 'month'.",
+                    relatedTool: "ol_analytics_dashboard",
+                });
+            }
+            if (allMessages.includes("datatype") || allMessages.includes("data type") || allMessages.includes("choice")) {
+                throw new OpenLoyaltyError({
+                    code: "INVALID_DATA_TYPE",
+                    message: "Invalid dataType value for dashboard analytics",
+                    hint: "Valid dataType values: registeredMembers, activeMembers, revenue, avgSpending, transactions, avgTransactionValue, avgNumberOfTransactions.",
+                    relatedTool: "ol_analytics_dashboard",
+                });
+            }
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "ANALYTICS_PERMISSION_DENIED",
+                message: "You don't have permission to view dashboard analytics",
+                hint: "Analytics require the ANALYTICS:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_analytics_dashboard",
+            });
+        }
+        throw formatApiError(error, "ol_analytics_dashboard");
+    }
+}
+export async function analyticsUnits(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.dataType)
+        params.append("dataType", input.dataType);
+    if (input.aggregationType)
+        params.append("aggregationType", input.aggregationType);
+    if (input.intervalStartDate)
+        params.append("intervalStartDate", input.intervalStartDate);
+    if (input.intervalEndDate)
+        params.append("intervalEndDate", input.intervalEndDate);
+    const queryString = params.toString();
+    const url = `/${storeCode}/analytics/units-overview/${input.walletTypeCode}${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Wallet type code '${input.walletTypeCode}' not found`,
+                hint: "Use ol_wallet_type_list() to find valid wallet type codes (e.g., 'default').", relatedTool: "ol_analytics_units" });
+        }
+        throw formatApiError(error, "ol_analytics_units");
+    }
+}
+export async function analyticsCampaignDetail(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        // API endpoint uses /campaigns (plural) with campaign ID as query param
+        const response = await apiGet(`/${storeCode}/analytics/campaigns?campaignId=${input.campaignId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Campaign '${input.campaignId}' not found`,
+                hint: "Use ol_campaign_list() to find valid campaign IDs.", relatedTool: "ol_analytics_campaign_detail" });
+        }
+        throw formatApiError(error, "ol_analytics_campaign_detail");
+    }
+}

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

@@ -0,0 +1,108 @@
+export { AnalyticsTiersInputSchema, AnalyticsMembersInputSchema, AnalyticsPointsInputSchema, AnalyticsTransactionsInputSchema, AnalyticsReferralsInputSchema, AnalyticsCampaignsInputSchema, AnalyticsDashboardInputSchema, AnalyticsUnitsInputSchema, AnalyticsCampaignDetailInputSchema, } from "./schemas.js";
+export { analyticsTiers, analyticsMembers, analyticsPoints, analyticsTransactions, analyticsReferrals, analyticsCampaigns, analyticsDashboard, analyticsUnits, analyticsCampaignDetail, } from "./handlers.js";
+import { analyticsTiers, analyticsMembers, analyticsPoints, analyticsTransactions, analyticsReferrals, analyticsCampaigns, analyticsDashboard, analyticsUnits, analyticsCampaignDetail } from "./handlers.js";
+export declare const analyticsToolDefinitions: readonly [{
+    readonly name: "ol_analytics_tiers";
+    readonly title: "Get Tier Analytics";
+    readonly description: "Get tier (level) analytics showing member distribution across tiers. Returns tier IDs, names, and member counts for each tier level.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsTiers;
+}, {
+    readonly name: "ol_analytics_members";
+    readonly title: "Get Member Analytics";
+    readonly description: "Get member analytics showing registration trends. Returns member counts by time intervals (1 day, 7 days, 30 days, 365 days). Filter by transaction status to see engaged vs unengaged members.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        withTransaction: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof analyticsMembers;
+}, {
+    readonly name: "ol_analytics_points";
+    readonly title: "Get Points Analytics";
+    readonly description: "Get points analytics showing program health. Returns total active points, points spent, points issued, expired points, and pending points. Use to monitor points economy.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsPoints;
+}, {
+    readonly name: "ol_analytics_transactions";
+    readonly title: "Get Transaction Analytics";
+    readonly description: "Get transaction analytics showing purchase trends. Returns transaction counts by intervals, total count, total amount, and average values. Use to monitor sales performance.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsTransactions;
+}, {
+    readonly name: "ol_analytics_referrals";
+    readonly title: "Get Referral Analytics";
+    readonly description: "Get referral program analytics showing referral activity. Returns total referral count. Use to monitor referral program performance.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsReferrals;
+}, {
+    readonly name: "ol_analytics_campaigns";
+    readonly title: "Get Campaign Analytics";
+    readonly description: "Get campaign analytics showing execution counts per campaign. Returns list of campaigns with their execution counts. Use to identify most successful campaigns.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        executedAt: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsCampaigns;
+}, {
+    readonly name: "ol_analytics_dashboard";
+    readonly title: "Get Dashboard Overview";
+    readonly description: "Get dashboard overview metrics with time-series data. Returns key metrics (registered members, active members, revenue, avg spending, transactions) with optional date range and aggregation. Use for high-level program dashboards.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        dataType: import("zod").ZodEnum<["registeredMembers", "activeMembers", "revenue", "avgSpending", "transactions", "avgTransactionValue", "avgNumberOfTransactions"]>;
+        aggregationType: import("zod").ZodOptional<import("zod").ZodEnum<["day", "week", "month"]>>;
+        intervalStartDate: import("zod").ZodOptional<import("zod").ZodString>;
+        intervalEndDate: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsDashboard;
+}, {
+    readonly name: "ol_analytics_units";
+    readonly title: "Get Units Overview";
+    readonly description: "Get wallet-specific analytics (units overview). Returns units issued, spent, expired, pending, active, plus redemption and breakage rates. Requires walletTypeCode parameter. Use for detailed points economy analysis.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        walletTypeCode: import("zod").ZodString;
+        dataType: import("zod").ZodOptional<import("zod").ZodEnum<["unitsIssued", "unitsSpent", "unitsExpired", "unitsPending", "unitsActive"]>>;
+        aggregationType: import("zod").ZodOptional<import("zod").ZodEnum<["day", "week", "month"]>>;
+        intervalStartDate: import("zod").ZodOptional<import("zod").ZodString>;
+        intervalEndDate: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof analyticsUnits;
+}, {
+    readonly name: "ol_analytics_campaign_detail";
+    readonly title: "Get Campaign Detail Analytics";
+    readonly description: "Get detailed analytics for a specific campaign. Returns campaign-specific performance metrics. Use after analytics_campaigns to drill into individual campaign performance.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        campaignId: import("zod").ZodString;
+    };
+    readonly handler: typeof analyticsCampaignDetail;
+}];