@open-loyalty/mcp-server 1.0.0

package/dist/tools/segment.js

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPut, apiDelete } from "../client/http.js";
+import { formatApiError } from "../utils/errors.js";
+import { getConfig } from "../config.js";
+// Input Schemas
+export const SegmentListInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 10)."),
+    active: z.boolean().optional().describe("Filter by active status."),
+    name: z.string().optional().describe("Filter by segment name."),
+};
+// Criterion input schema - flexible to support all criterion types
+const SegmentCriterionInputSchema = z.object({
+    type: z.string().describe("Criterion type (e.g., 'tier', 'transaction_count', 'points_balance')."),
+    criterionId: z.string().optional().describe("Criterion ID (optional, generated if not provided)."),
+    // Common criterion data fields
+    days: z.number().optional().describe("Days for time-based criteria."),
+    fromDate: z.string().optional().describe("Start date (ISO format)."),
+    toDate: z.string().optional().describe("End date (ISO format)."),
+    min: z.number().optional().describe("Minimum value."),
+    max: z.number().optional().describe("Maximum value."),
+    posIds: z.array(z.string()).optional().describe("POS IDs."),
+    skus: z.array(z.string()).optional().describe("SKU codes."),
+    makers: z.array(z.string()).optional().describe("Maker/brand names."),
+    labels: z.array(z.object({ key: z.string(), value: z.string() })).optional().describe("Label key-value pairs."),
+    tierIds: z.array(z.string()).optional().describe("Tier level IDs."),
+    campaignId: z.string().optional().describe("Campaign ID for campaign_completion criterion."),
+    countries: z.array(z.string()).optional().describe("Country codes."),
+    anniversaryType: z.string().optional().describe("Anniversary type."),
+    customAttributeKey: z.string().optional().describe("Custom attribute key."),
+    customAttributeValue: z.string().optional().describe("Custom attribute value."),
+}).passthrough();
+// Part input schema
+const SegmentPartInputSchema = z.object({
+    segmentPartId: z.string().optional().describe("Part ID (optional)."),
+    criteria: z.array(SegmentCriterionInputSchema).describe("Criteria for this part (AND logic)."),
+});
+export const SegmentCreateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    name: z.string().describe("Segment name (required)."),
+    description: z.string().optional().describe("Segment description."),
+    active: z.boolean().optional().describe("Whether segment is active (default: false)."),
+    parts: z.array(SegmentPartInputSchema).describe("Segment parts. Parts use OR logic (ANY part matches), criteria within parts use AND logic (ALL criteria must match)."),
+};
+export const SegmentGetInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to retrieve."),
+};
+export const SegmentUpdateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to update."),
+    name: z.string().describe("Segment name."),
+    description: z.string().optional().describe("Segment description."),
+    active: z.boolean().optional().describe("Whether segment is active."),
+    parts: z.array(SegmentPartInputSchema).describe("Segment parts."),
+};
+export const SegmentDeleteInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to delete."),
+};
+export const SegmentGetMembersInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to get members for."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+};
+export const SegmentActivateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to activate."),
+};
+export const SegmentDeactivateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to deactivate."),
+};
+export const SegmentGetResourcesInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    segmentId: z.string().describe("The segment ID (UUID) to get associated resources for."),
+};
+// Handler functions
+export async function segmentList(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.active !== undefined)
+        params.append("active", String(input.active));
+    if (input.name)
+        params.append("name", input.name);
+    const queryString = params.toString();
+    const url = `/${storeCode}/segment${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const segments = (response.items || []).map((item) => ({
+            segmentId: item.segmentId,
+            name: item.name,
+            description: item.description,
+            active: item.active,
+            customersCount: item.customersCount,
+            createdAt: item.createdAt,
+        }));
+        const total = response.total || {};
+        return {
+            segments,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_list");
+    }
+}
+export async function segmentCreate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const segmentPayload = {
+        name: input.name,
+        parts: input.parts,
+    };
+    if (input.description)
+        segmentPayload.description = input.description;
+    if (input.active !== undefined)
+        segmentPayload.active = input.active;
+    try {
+        // CRITICAL: Wrap body as { segment: {...} }
+        const response = await apiPost(`/${storeCode}/segment`, { segment: segmentPayload });
+        return { segmentId: response.segmentId };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_create");
+    }
+}
+export async function segmentGet(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        const response = await apiGet(`/${storeCode}/segment/${input.segmentId}`);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_get");
+    }
+}
+export async function segmentUpdate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const segmentPayload = {
+        name: input.name,
+        parts: input.parts,
+    };
+    if (input.description !== undefined)
+        segmentPayload.description = input.description;
+    if (input.active !== undefined)
+        segmentPayload.active = input.active;
+    try {
+        // CRITICAL: Wrap body as { segment: {...} }
+        await apiPut(`/${storeCode}/segment/${input.segmentId}`, { segment: segmentPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_update");
+    }
+}
+export async function segmentDelete(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        await apiDelete(`/${storeCode}/segment/${input.segmentId}`);
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_delete");
+    }
+}
+export async function segmentGetMembers(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const params = new URLSearchParams();
+    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}/segment/${input.segmentId}/members${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const members = (response.items || []).map((item) => ({
+            customerId: item.customerId,
+            firstName: item.firstName,
+            lastName: item.lastName,
+            email: item.email,
+            loyaltyCardNumber: item.loyaltyCardNumber,
+            active: item.active,
+        }));
+        const total = response.total || {};
+        return {
+            members,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_get_members");
+    }
+}
+export async function segmentActivate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        await apiPost(`/${storeCode}/segment/${input.segmentId}/activate`, {});
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_activate");
+    }
+}
+export async function segmentDeactivate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        await apiPost(`/${storeCode}/segment/${input.segmentId}/deactivate`, {});
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_deactivate");
+    }
+}
+export async function segmentGetResources(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        const response = await apiGet(`/${storeCode}/segment/${input.segmentId}/resources`);
+        const resources = response.items || response.resources || [];
+        return { resources };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_segment_get_resources");
+    }
+}
+// Tool definitions
+export const segmentToolDefinitions = [
+    {
+        name: "openloyalty_segment_list",
+        description: "List customer segments. Segments group members by criteria (purchase behavior, tier, location, etc). Use for campaign targeting and analytics.",
+        inputSchema: SegmentListInputSchema,
+        handler: segmentList,
+    },
+    {
+        name: "openloyalty_segment_create",
+        description: "Create segment to group members. Parts use OR logic (member matches if ANY part matches). Criteria within parts use AND logic (must match ALL criteria in that part). Common criteria: tier, transaction_count, points_balance, country. Example - VIP segment: parts: [{ criteria: [{ type: 'tier', tierIds: ['gold-level-id'] }] }]",
+        inputSchema: SegmentCreateInputSchema,
+        handler: segmentCreate,
+    },
+    {
+        name: "openloyalty_segment_get",
+        description: "Get full segment details including all parts and criteria configurations.",
+        inputSchema: SegmentGetInputSchema,
+        handler: segmentGet,
+    },
+    {
+        name: "openloyalty_segment_update",
+        description: "Update segment configuration. Requires full segment definition (name, parts with criteria). Use segment_get first to retrieve current configuration.",
+        inputSchema: SegmentUpdateInputSchema,
+        handler: segmentUpdate,
+    },
+    {
+        name: "openloyalty_segment_delete",
+        description: "Permanently delete a segment. Cannot be undone. Check segment_get_resources first to see what uses this segment.",
+        inputSchema: SegmentDeleteInputSchema,
+        handler: segmentDelete,
+    },
+    {
+        name: "openloyalty_segment_get_members",
+        description: "Get members belonging to a segment. Returns paginated list of member details. Use for verifying segment criteria or exporting member lists.",
+        inputSchema: SegmentGetMembersInputSchema,
+        handler: segmentGetMembers,
+    },
+    {
+        name: "openloyalty_segment_activate",
+        description: "Activate a segment. Active segments are used for campaign targeting and can be queried for members.",
+        inputSchema: SegmentActivateInputSchema,
+        handler: segmentActivate,
+    },
+    {
+        name: "openloyalty_segment_deactivate",
+        description: "Deactivate a segment. Deactivated segments are not used for campaign targeting but retain their configuration.",
+        inputSchema: SegmentDeactivateInputSchema,
+        handler: segmentDeactivate,
+    },
+    {
+        name: "openloyalty_segment_get_resources",
+        description: "Get resources (campaigns, rewards, etc.) that use this segment for targeting. Check before deleting a segment.",
+        inputSchema: SegmentGetResourcesInputSchema,
+        handler: segmentGetResources,
+    },
+];

package/dist/tools/store.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+export interface Store {
+    storeId: string;
+    code: string;
+    currency: string;
+    name: string;
+    active: boolean;
+    createdBy?: string;
+    createdAt?: string;
+    updatedBy?: string;
+    updatedAt?: string;
+}
+export interface StoreListResponse {
+    items: Store[];
+    total?: Record<string, unknown>;
+}
+export declare const StoreListInputSchema: {
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+};
+export declare const StoreCreateInputSchema: {
+    code: z.ZodString;
+    name: z.ZodString;
+    currency: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const StoreGetInputSchema: {
+    storeId: z.ZodString;
+};
+export declare const StoreUpdateInputSchema: {
+    storeId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    currency: z.ZodOptional<z.ZodString>;
+};
+export declare function storeList(input: {
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+    name?: string;
+    code?: string;
+}): Promise<StoreListResponse>;
+export declare function storeCreate(input: {
+    code: string;
+    name: string;
+    currency?: string;
+    active?: boolean;
+}): Promise<{
+    storeId: string;
+}>;
+export declare function storeGet(input: {
+    storeId: string;
+}): Promise<Store>;
+export declare function storeUpdate(input: {
+    storeId: string;
+    name?: string;
+    active?: boolean;
+    currency?: string;
+}): Promise<void>;
+export declare const storeToolDefinitions: readonly [{
+    readonly name: "openloyalty_store_list";
+    readonly description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.";
+    readonly inputSchema: {
+        page: z.ZodOptional<z.ZodNumber>;
+        perPage: z.ZodOptional<z.ZodNumber>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    };
+    readonly handler: typeof storeList;
+}, {
+    readonly name: "openloyalty_store_create";
+    readonly description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.";
+    readonly inputSchema: {
+        code: z.ZodString;
+        name: z.ZodString;
+        currency: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+    };
+    readonly handler: typeof storeCreate;
+}, {
+    readonly name: "openloyalty_store_get";
+    readonly description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.";
+    readonly inputSchema: {
+        storeId: z.ZodString;
+    };
+    readonly handler: typeof storeGet;
+}, {
+    readonly name: "openloyalty_store_update";
+    readonly description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).";
+    readonly inputSchema: {
+        storeId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        currency: z.ZodOptional<z.ZodString>;
+    };
+    readonly handler: typeof storeUpdate;
+}];

package/dist/tools/store.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPut } from "../client/http.js";
+import { formatApiError } from "../utils/errors.js";
+// Input Schemas
+export const StoreListInputSchema = {
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    active: z.boolean().optional().describe("Filter by active status."),
+    name: z.string().optional().describe("Filter by store name."),
+    code: z.string().optional().describe("Filter by store code."),
+};
+export const StoreCreateInputSchema = {
+    code: z.string().describe("Store code (required, unique identifier like 'US', 'EU')."),
+    name: z.string().describe("Store name (required)."),
+    currency: z.string().optional().describe("Currency code (e.g., 'USD', 'EUR')."),
+    active: z.boolean().optional().describe("Whether the store is active (default: true)."),
+};
+export const StoreGetInputSchema = {
+    storeId: z.string().describe("The store ID (UUID) to retrieve."),
+};
+export const StoreUpdateInputSchema = {
+    storeId: z.string().describe("The store ID (UUID) to update."),
+    name: z.string().optional().describe("Store name."),
+    active: z.boolean().optional().describe("Whether the store is active."),
+    currency: z.string().optional().describe("Currency code."),
+};
+// Handler functions
+export async function storeList(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.active !== undefined)
+        params.append("active[eq]", String(input.active));
+    if (input.name)
+        params.append("name[eq]", input.name);
+    if (input.code)
+        params.append("code", input.code);
+    const queryString = params.toString();
+    const url = `/store${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_store_list");
+    }
+}
+export async function storeCreate(input) {
+    const payload = {
+        code: input.code,
+        name: input.name,
+    };
+    if (input.currency)
+        payload.currency = input.currency;
+    if (input.active !== undefined)
+        payload.active = input.active;
+    try {
+        const response = await apiPost("/store", { store: payload });
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_store_create");
+    }
+}
+export async function storeGet(input) {
+    try {
+        const response = await apiGet(`/store/${input.storeId}`);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_store_get");
+    }
+}
+export async function storeUpdate(input) {
+    const payload = {};
+    if (input.name)
+        payload.name = input.name;
+    if (input.active !== undefined)
+        payload.active = input.active;
+    if (input.currency)
+        payload.currency = input.currency;
+    try {
+        await apiPut(`/store/${input.storeId}`, { store: payload });
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_store_update");
+    }
+}
+// Tool definitions
+export const storeToolDefinitions = [
+    {
+        name: "openloyalty_store_list",
+        description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.",
+        inputSchema: StoreListInputSchema,
+        handler: storeList,
+    },
+    {
+        name: "openloyalty_store_create",
+        description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.",
+        inputSchema: StoreCreateInputSchema,
+        handler: storeCreate,
+    },
+    {
+        name: "openloyalty_store_get",
+        description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.",
+        inputSchema: StoreGetInputSchema,
+        handler: storeGet,
+    },
+    {
+        name: "openloyalty_store_update",
+        description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).",
+        inputSchema: StoreUpdateInputSchema,
+        handler: storeUpdate,
+    },
+];