@open-loyalty/mcp-server 1.1.0 → 1.3.3

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

@@ -0,0 +1,47 @@
+/**
+ * Create a referral relationship between two members
+ * POST /api/:storeCode/member/:member/referral
+ */
+export declare function referralCreate(input: {
+    storeCode?: string;
+    memberId: string;
+    referrerId: string;
+}): Promise<void>;
+/**
+ * List referrals with optional filters
+ * GET /api/:storeCode/referral
+ */
+export declare function referralList(input: {
+    storeCode?: string;
+    referralId?: string;
+    referrerId?: string;
+    referrerName?: string;
+    referrerToken?: string;
+    refereeId?: string;
+    refereeName?: string;
+    createdAt?: string;
+    page?: number;
+    perPage?: number;
+}): Promise<{
+    referrals: Array<{
+        referralId: string;
+        referrerId: string;
+        referrerName?: string;
+        referrerToken?: string;
+        refereeId: string;
+        refereeName?: string;
+        createdAt: string;
+    }>;
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+/**
+ * Delete a referral relationship
+ * DELETE /api/:storeCode/member/:member/referral
+ */
+export declare function referralDelete(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<void>;

package/dist/tools/referral/handlers.js

@@ -0,0 +1,115 @@
+import { apiGet, apiPost, apiDelete } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+/**
+ * Create a referral relationship between two members
+ * POST /api/:storeCode/member/:member/referral
+ */
+export async function referralCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // Validate that memberId and referrerId are different
+    if (input.memberId === input.referrerId) {
+        throw new OpenLoyaltyError({
+            code: "INVALID_REFERRAL",
+            message: "A member cannot refer themselves",
+            hint: "The memberId (referee) must be different from the referrerId (referrer). The referee is the new member, the referrer is the existing member who made the referral.",
+            relatedTool: "ol_referral_create",
+        });
+    }
+    try {
+        await apiPost(`/${storeCode}/member/${input.memberId}/referral`, { referrerId: input.referrerId });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("already has a referrer") || errorMessage.includes("referral already exists")) {
+            throw new OpenLoyaltyError({
+                code: "REFERRAL_EXISTS",
+                message: "This member already has a referral relationship",
+                hint: `Member ${input.memberId} has already been referred by someone. Use referral_list(refereeId: "${input.memberId}") to see existing referral.`,
+                relatedTool: "ol_referral_create",
+            });
+        }
+        if (errorMessage.includes("not found") || errorMessage.includes("Not Found")) {
+            throw new OpenLoyaltyError({
+                code: "MEMBER_NOT_FOUND",
+                message: "One or both member IDs do not exist",
+                hint: `Verify both members exist: member_get(memberId: "${input.memberId}") for referee and member_get(memberId: "${input.referrerId}") for referrer.`,
+                relatedTool: "ol_referral_create",
+            });
+        }
+        throw formatApiError(error, "ol_referral_create");
+    }
+}
+/**
+ * List referrals with optional filters
+ * GET /api/:storeCode/referral
+ */
+export async function referralList(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.referralId)
+        params.append("referralId", input.referralId);
+    if (input.referrerId)
+        params.append("referrerId", input.referrerId);
+    if (input.referrerName)
+        params.append("referrerName", input.referrerName);
+    if (input.referrerToken)
+        params.append("referrerToken", input.referrerToken);
+    if (input.refereeId)
+        params.append("refereeId", input.refereeId);
+    if (input.refereeName)
+        params.append("refereeName", input.refereeName);
+    if (input.createdAt)
+        params.append("createdAt", input.createdAt);
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    const queryString = params.toString();
+    const url = `/${storeCode}/referral${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const referrals = (response.items || []).map((item) => ({
+            referralId: item.referralId,
+            referrerId: item.referrerId,
+            referrerName: item.referrerName,
+            referrerToken: item.referrerToken,
+            refereeId: item.refereeId,
+            refereeName: item.refereeName,
+            createdAt: item.createdAt,
+        }));
+        const total = response.total || {};
+        return {
+            referrals,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_referral_list");
+    }
+}
+/**
+ * Delete a referral relationship
+ * DELETE /api/:storeCode/member/:member/referral
+ */
+export async function referralDelete(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiDelete(`/${storeCode}/member/${input.memberId}/referral`);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("not found") || errorMessage.includes("Not Found")) {
+            throw new OpenLoyaltyError({
+                code: "REFERRAL_NOT_FOUND",
+                message: "No referral relationship found for this member",
+                hint: `Member ${input.memberId} does not have a referral relationship. Use referral_list(refereeId: "${input.memberId}") to verify.`,
+                relatedTool: "ol_referral_delete",
+            });
+        }
+        throw formatApiError(error, "ol_referral_delete");
+    }
+}

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

@@ -0,0 +1,44 @@
+export { ReferralCreateInputSchema, ReferralListInputSchema, ReferralDeleteInputSchema, } from "./schemas.js";
+export { referralCreate, referralList, referralDelete } from "./handlers.js";
+import { referralCreate, referralList, referralDelete } from "./handlers.js";
+export declare const referralToolDefinitions: readonly [{
+    readonly name: "ol_referral_create";
+    readonly title: "Create Referral Relationship";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        referrerId: import("zod").ZodString;
+    };
+    readonly handler: typeof referralCreate;
+}, {
+    readonly name: "ol_referral_list";
+    readonly title: "List Referrals";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        referralId: import("zod").ZodOptional<import("zod").ZodString>;
+        referrerId: import("zod").ZodOptional<import("zod").ZodString>;
+        referrerName: import("zod").ZodOptional<import("zod").ZodString>;
+        referrerToken: import("zod").ZodOptional<import("zod").ZodString>;
+        refereeId: import("zod").ZodOptional<import("zod").ZodString>;
+        refereeName: import("zod").ZodOptional<import("zod").ZodString>;
+        createdAt: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    readonly handler: typeof referralList;
+}, {
+    readonly name: "ol_referral_delete";
+    readonly title: "Delete Referral Relationship";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly destructive: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+    };
+    readonly handler: typeof referralDelete;
+}];

package/dist/tools/referral/index.js

@@ -0,0 +1,44 @@
+// Re-export schemas
+export { ReferralCreateInputSchema, ReferralListInputSchema, ReferralDeleteInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { referralCreate, referralList, referralDelete } from "./handlers.js";
+// Imports for tool definitions
+import { ReferralCreateInputSchema, ReferralListInputSchema, ReferralDeleteInputSchema, } from "./schemas.js";
+import { referralCreate, referralList, referralDelete } from "./handlers.js";
+// Tool definitions
+export const referralToolDefinitions = [
+    {
+        name: "ol_referral_create",
+        title: "Create Referral Relationship",
+        description: "Create a referral relationship between an existing member (referrer) and a new member (referee). " +
+            "The referrer is the member who made the referral and will receive referral rewards. " +
+            "The referee (memberId) is the new member who was referred. " +
+            "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,
+        inputSchema: ReferralCreateInputSchema,
+        handler: referralCreate,
+    },
+    {
+        name: "ol_referral_list",
+        title: "List Referrals",
+        description: "List referral relationships with optional filters. " +
+            "Filter by referrerId to see all members a specific person has referred. " +
+            "Filter by refereeId to find who referred a specific member. " +
+            "Returns referralId, referrerId, referrerName, refereeId, refereeName, and createdAt.",
+        readOnly: true,
+        inputSchema: ReferralListInputSchema,
+        handler: referralList,
+    },
+    {
+        name: "ol_referral_delete",
+        title: "Delete Referral Relationship",
+        description: "Delete a referral relationship for a member. " +
+            "Use with caution - this removes the referral tracking but may not reverse any rewards already given. " +
+            "The memberId is the referee (the member who was referred).",
+        readOnly: false,
+        destructive: true,
+        inputSchema: ReferralDeleteInputSchema,
+        handler: referralDelete,
+    },
+];

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

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/**
+ * Schema for creating a referral relationship
+ * POST /api/:storeCode/member/:member/referral
+ */
+export declare const ReferralCreateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    referrerId: z.ZodString;
+};
+/**
+ * Schema for listing referrals
+ * GET /api/:storeCode/referral
+ */
+export declare const ReferralListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    referralId: z.ZodOptional<z.ZodString>;
+    referrerId: z.ZodOptional<z.ZodString>;
+    referrerName: z.ZodOptional<z.ZodString>;
+    referrerToken: z.ZodOptional<z.ZodString>;
+    refereeId: z.ZodOptional<z.ZodString>;
+    refereeName: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+};
+/**
+ * Schema for deleting a referral relationship
+ * DELETE /api/:storeCode/member/:member/referral
+ */
+export declare const ReferralDeleteInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+};

package/dist/tools/referral/schemas.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * Schema for creating a referral relationship
+ * POST /api/:storeCode/member/:member/referral
+ */
+export const ReferralCreateInputSchema = {
+    storeCode: z
+        .string()
+        .optional()
+        .describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    memberId: z
+        .string()
+        .uuid()
+        .describe("The member ID (UUID) of the referee (the new member being referred). This is the member who was referred by someone else."),
+    referrerId: z
+        .string()
+        .uuid()
+        .describe("The member ID (UUID) of the referrer (the existing member who made the referral). This member will receive referral rewards."),
+};
+/**
+ * Schema for listing referrals
+ * GET /api/:storeCode/referral
+ */
+export const ReferralListInputSchema = {
+    storeCode: z
+        .string()
+        .optional()
+        .describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    referralId: z.string().uuid().optional().describe("Filter by specific referral ID"),
+    referrerId: z.string().uuid().optional().describe("Filter by referrer member ID"),
+    referrerName: z.string().max(255).optional().describe("Filter by referrer name"),
+    referrerToken: z.string().max(255).optional().describe("Filter by referrer token"),
+    refereeId: z.string().uuid().optional().describe("Filter by referee member ID"),
+    refereeName: z.string().max(255).optional().describe("Filter by referee name"),
+    createdAt: z.string().optional().describe("Filter by creation date (ISO 8601)"),
+    page: z.number().int().min(1).optional().describe("Page number (starts from 1)"),
+    perPage: z.number().int().min(1).max(100).optional().describe("Items per page (default 25, max 100)"),
+};
+/**
+ * Schema for deleting a referral relationship
+ * DELETE /api/:storeCode/member/:member/referral
+ */
+export const ReferralDeleteInputSchema = {
+    storeCode: z
+        .string()
+        .optional()
+        .describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    memberId: z
+        .string()
+        .uuid()
+        .describe("The member ID (UUID) of the referee whose referral relationship should be deleted."),
+};

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

@@ -0,0 +1,110 @@
+import { Reward } from "../../types/schemas/reward.js";
+export declare function rewardList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+    type?: string;
+    categoryId?: string;
+}): Promise<{
+    rewards: Array<{
+        rewardId: string;
+        name: string;
+        type: string;
+        costInPoints?: number;
+        active: boolean;
+    }>;
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function rewardCreate(input: {
+    storeCode?: string;
+    translations: {
+        en: {
+            name: string;
+        };
+    };
+    reward: string;
+    activity: {
+        from: string;
+        to: string;
+    };
+    visibility: {
+        from: string;
+        to: string;
+    };
+    usageLimit: {
+        perUser: number;
+        general?: number;
+    };
+    costInPoints?: number;
+    usageInstruction?: string;
+    active?: boolean;
+    categories?: string[];
+    levels?: string[];
+    segments?: string[];
+    target?: string | null;
+    couponValue?: number;
+    couponValueType?: string;
+    daysValid?: number;
+}): Promise<{
+    rewardId: string;
+    name: string;
+    costInPoints?: number;
+}>;
+export declare function rewardGet(input: {
+    storeCode?: string;
+    rewardId: string;
+}): Promise<Reward>;
+export declare function rewardUpdate(input: {
+    storeCode?: string;
+    rewardId: string;
+    name?: string;
+    costInPoints?: number;
+    description?: string;
+    active?: boolean;
+    categories?: string[];
+    levels?: string[];
+    segments?: string[];
+}): Promise<void>;
+export declare function rewardActivate(input: {
+    storeCode?: string;
+    rewardId: string;
+}): Promise<void>;
+export declare function rewardDeactivate(input: {
+    storeCode?: string;
+    rewardId: string;
+}): Promise<void>;
+export declare function rewardBuy(input: {
+    storeCode?: string;
+    rewardId: string;
+    memberId: string;
+    quantity?: number;
+    couponValue?: number;
+    withoutPoints?: boolean;
+}): Promise<{
+    issuedRewardId: string;
+    couponCode?: string;
+}>;
+export declare function rewardRedeem(input: {
+    storeCode?: string;
+    memberId: string;
+    couponCode: string;
+}): Promise<{
+    code: string;
+    used: boolean;
+}>;
+export declare function rewardCategoryList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+}): Promise<{
+    categories: Array<{
+        categoryId: string;
+        name: string;
+        active: boolean;
+    }>;
+}>;