@open-loyalty/mcp-server 1.0.0

package/dist/types/schemas/campaign.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import { TranslationsSchema } from "./common.js";
+// Campaign Type Enum
+export const CampaignTypeEnum = z.enum(["direct", "referral"]);
+// Campaign Trigger Enum
+export const CampaignTriggerEnum = z.enum([
+    "transaction",
+    "custom_event",
+    "time",
+    "achievement",
+    "custom_event_unique_code",
+    "leaderboard",
+    "internal_event",
+    "return_transaction",
+    "challenge",
+    "fortune_wheel",
+]);
+// Campaign Effect Enum
+export const CampaignEffectEnum = z.enum([
+    "give_points",
+    "give_reward",
+    "deduct_unit",
+    "assign_member_custom_attribute",
+    "remove_member_custom_attribute",
+]);
+// Points Rule Schema for give_points effect
+export const CampaignPointsRuleSchema = z.object({
+    description: z.string().optional(),
+    expression: z.string().optional(),
+    multiplier: z.number().optional(),
+    fixedValue: z.number().optional(),
+});
+// Units Lock Rule Schema
+export const CampaignUnitsLockRuleSchema = z.object({
+    lockStrategy: z.enum(["from_wallet", "no_pending", "expression"]).optional(),
+    expression: z.string().optional(),
+});
+// Units Expiration Rule Schema
+export const CampaignUnitsExpirationRuleSchema = z.object({
+    expirationStrategy: z.enum(["from_wallet", "never_expires", "expression"]).optional(),
+    expression: z.string().optional(),
+});
+// Campaign Effect Schema
+export const CampaignEffectSchema = z.object({
+    effect: CampaignEffectEnum,
+    pointsRule: CampaignPointsRuleSchema.optional(),
+    walletCode: z.string().optional(),
+    unitsLockRule: CampaignUnitsLockRuleSchema.optional(),
+    unitsExpirationRule: CampaignUnitsExpirationRuleSchema.optional(),
+    rewardId: z.string().optional(),
+    couponValueRule: z.string().optional(),
+    customAttributeKey: z.string().optional(),
+    customAttributeValueRule: z.string().optional(),
+});
+// Campaign Condition Schema
+export const CampaignConditionSchema = z.object({
+    operator: z.string(),
+    attribute: z.string(),
+    data: z.record(z.unknown()).optional(),
+});
+// Campaign Rule Schema
+export const CampaignRuleSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    target: z.enum(["self", "referrer"]).optional(),
+    effects: z.array(CampaignEffectSchema),
+    conditions: z.array(CampaignConditionSchema).optional(),
+});
+// Campaign Activity Schema (time period)
+export const CampaignActivitySchema = z.object({
+    startsAt: z.string(), // ISO datetime
+    endsAt: z.string().optional(), // ISO datetime
+});
+// Campaign Visibility Schema (who can see the campaign)
+export const CampaignVisibilitySchema = z.object({
+    target: z.enum(["all", "tier", "segment"]),
+    tiers: z.array(z.string()).optional(),
+    segments: z.array(z.string()).optional(),
+});
+// Campaign Audience Schema (who can participate)
+export const CampaignAudienceSchema = z.object({
+    target: z.enum(["all", "tier", "segment"]),
+    tiers: z.array(z.string()).optional(),
+    segments: z.array(z.string()).optional(),
+});
+// Limit Interval Schema
+export const CampaignLimitIntervalSchema = z.object({
+    type: z.enum(["days", "weeks", "months", "years", "forever"]),
+    value: z.number().optional(),
+});
+// Limit Value Schema
+export const CampaignLimitValueSchema = z.object({
+    value: z.number(),
+    interval: CampaignLimitIntervalSchema.optional(),
+});
+// Campaign Limits Schema
+export const CampaignLimitsSchema = z.object({
+    points: CampaignLimitValueSchema.optional(),
+    pointsPerMember: CampaignLimitValueSchema.optional(),
+    executionsPerMember: CampaignLimitValueSchema.optional(),
+});
+// Trigger Strategy Schema
+export const CampaignTriggerStrategySchema = z.object({
+    type: z.enum(["daily", "weekly", "monthly", "cron"]).optional(),
+    executionSchedule: z.object({
+        dayOfWeek: z.array(z.number()).optional(),
+        dayOfMonth: z.array(z.number()).optional(),
+    }).optional(),
+});
+// Transaction Items Filter Schema
+export const CampaignTransactionItemFilterSchema = z.object({
+    value: z.object({
+        field: z.enum(["sku", "name", "category", "maker", "qty"]),
+    }),
+    condition: z.object({
+        operator: z.string(),
+        value: z.union([z.string(), z.number()]),
+    }),
+});
+export const CampaignTransactionItemsFilterSchema = z.object({
+    code: z.string(),
+    name: z.string().optional(),
+    filters: z.array(CampaignTransactionItemFilterSchema),
+});
+// Label Schema
+export const CampaignLabelSchema = z.object({
+    key: z.string(),
+    value: z.string(),
+});
+// Main Campaign Schema
+export const CampaignSchema = z.object({
+    campaignId: z.string(),
+    type: CampaignTypeEnum,
+    trigger: CampaignTriggerEnum,
+    translations: TranslationsSchema,
+    active: z.boolean(),
+    activity: CampaignActivitySchema.optional(),
+    rules: z.array(CampaignRuleSchema),
+    visibility: CampaignVisibilitySchema.optional(),
+    audience: CampaignAudienceSchema.optional(),
+    limits: CampaignLimitsSchema.optional(),
+    triggerStrategy: CampaignTriggerStrategySchema.optional(),
+    transactionItemsFilters: z.array(CampaignTransactionItemsFilterSchema).optional(),
+    event: z.string().optional(),
+    displayOrder: z.number().optional(),
+    labels: z.array(CampaignLabelSchema).optional(),
+    memberFilter: z.record(z.unknown()).optional(),
+});
+// Campaign Create Input Schema (matches POST body structure)
+export const CampaignCreateInputSchema = z.object({
+    type: CampaignTypeEnum,
+    trigger: CampaignTriggerEnum,
+    translations: TranslationsSchema,
+    activity: CampaignActivitySchema,
+    rules: z.array(CampaignRuleSchema),
+    visibility: CampaignVisibilitySchema.optional(),
+    audience: CampaignAudienceSchema.optional(),
+    limits: CampaignLimitsSchema.optional(),
+    triggerStrategy: CampaignTriggerStrategySchema.optional(),
+    transactionItemsFilters: z.array(CampaignTransactionItemsFilterSchema).optional(),
+    event: z.string().optional(),
+    displayOrder: z.number().optional(),
+    active: z.boolean().optional(),
+    labels: z.array(CampaignLabelSchema).optional(),
+    memberFilter: z.record(z.unknown()).optional(),
+});
+// Campaign List Item Schema (simplified for list responses)
+export const CampaignListItemSchema = z.object({
+    campaignId: z.string(),
+    name: z.string().optional(),
+    type: CampaignTypeEnum,
+    trigger: CampaignTriggerEnum,
+    active: z.boolean(),
+    displayOrder: z.number().optional(),
+});
+// Simulated Effect Schema
+export const CampaignSimulatedEffectSchema = z.object({
+    campaignId: z.string(),
+    campaignName: z.string().optional(),
+    effects: z.array(z.record(z.unknown())),
+    limitReached: z.boolean().optional(),
+});
+// Campaign Code Schema
+export const CampaignCodeSchema = z.object({
+    code: z.string(),
+    used: z.boolean(),
+    usedAt: z.string().optional(),
+    memberId: z.string().optional(),
+});

package/dist/types/schemas/common.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * Common schema for paginated list responses.
+ * The Open Loyalty API returns total in varying formats depending on the endpoint:
+ * - Sometimes empty object {}
+ * - Sometimes { all: number|boolean, filtered: number|boolean, estimated: boolean|string|number }
+ * We use a flexible schema that accepts all variations.
+ */
+export declare const TotalSchema: z.ZodObject<{
+    all: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean]>>;
+    filtered: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+    estimated: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodNumber]>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    all: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean]>>;
+    filtered: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+    estimated: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodNumber]>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    all: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean]>>;
+    filtered: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+    estimated: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodNumber]>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type Total = z.infer<typeof TotalSchema>;
+/**
+ * Translation entry schema for multilingual content.
+ * Most Open Loyalty endpoints require translations with at least 'en' key.
+ */
+export declare const TranslationEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description?: string | undefined;
+}, {
+    name: string;
+    description?: string | undefined;
+}>;
+export type TranslationEntry = z.infer<typeof TranslationEntrySchema>;
+/**
+ * Translations schema - keyed by language code.
+ * The 'en' key is typically required, other languages (pl, de, etc.) are optional.
+ */
+export declare const TranslationsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description?: string | undefined;
+}, {
+    name: string;
+    description?: string | undefined;
+}>>;
+export type Translations = z.infer<typeof TranslationsSchema>;

package/dist/types/schemas/common.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+/**
+ * Common schema for paginated list responses.
+ * The Open Loyalty API returns total in varying formats depending on the endpoint:
+ * - Sometimes empty object {}
+ * - Sometimes { all: number|boolean, filtered: number|boolean, estimated: boolean|string|number }
+ * We use a flexible schema that accepts all variations.
+ */
+export const TotalSchema = z.object({
+    all: z.union([z.number(), z.boolean()]).optional(),
+    filtered: z.union([z.number(), z.boolean(), z.string()]).optional(),
+    estimated: z.union([z.boolean(), z.string(), z.number()]).optional(),
+}).passthrough(); // Allow additional fields
+/**
+ * Translation entry schema for multilingual content.
+ * Most Open Loyalty endpoints require translations with at least 'en' key.
+ */
+export const TranslationEntrySchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+});
+/**
+ * Translations schema - keyed by language code.
+ * The 'en' key is typically required, other languages (pl, de, etc.) are optional.
+ */
+export const TranslationsSchema = z.record(z.string(), TranslationEntrySchema);

package/dist/types/schemas/export.d.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+export declare const ExportTypeEnum: z.ZodEnum<["campaignCode", "member", "memberTier", "memberSegment", "rewardFulfillment"]>;
+export type ExportType = z.infer<typeof ExportTypeEnum>;
+export declare const ExportStatusEnum: z.ZodEnum<["pending", "done", "failed", "error"]>;
+export type ExportStatus = z.infer<typeof ExportStatusEnum>;
+export declare const ExportSchema: z.ZodObject<{
+    exportId: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<["campaignCode", "member", "memberTier", "memberSegment", "rewardFulfillment"]>>;
+    status: z.ZodOptional<z.ZodEnum<["pending", "done", "failed", "error"]>>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    criteria: z.ZodOptional<z.ZodString>;
+    exportedRows: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    exportId: string;
+    message?: string | undefined;
+    type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+    status?: "pending" | "done" | "failed" | "error" | undefined;
+    createdAt?: string | undefined;
+    criteria?: string | undefined;
+    finishedAt?: string | undefined;
+    exportedRows?: number | undefined;
+}, {
+    exportId: string;
+    message?: string | undefined;
+    type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+    status?: "pending" | "done" | "failed" | "error" | undefined;
+    createdAt?: string | undefined;
+    criteria?: string | undefined;
+    finishedAt?: string | undefined;
+    exportedRows?: number | undefined;
+}>;
+export type Export = z.infer<typeof ExportSchema>;
+export declare const ExportListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        exportId: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<["campaignCode", "member", "memberTier", "memberSegment", "rewardFulfillment"]>>;
+        status: z.ZodOptional<z.ZodEnum<["pending", "done", "failed", "error"]>>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        finishedAt: z.ZodOptional<z.ZodString>;
+        criteria: z.ZodOptional<z.ZodString>;
+        exportedRows: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        exportId: string;
+        message?: string | undefined;
+        type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+        status?: "pending" | "done" | "failed" | "error" | undefined;
+        createdAt?: string | undefined;
+        criteria?: string | undefined;
+        finishedAt?: string | undefined;
+        exportedRows?: number | undefined;
+    }, {
+        exportId: string;
+        message?: string | undefined;
+        type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+        status?: "pending" | "done" | "failed" | "error" | undefined;
+        createdAt?: string | undefined;
+        criteria?: string | undefined;
+        finishedAt?: string | undefined;
+        exportedRows?: number | undefined;
+    }>, "many">;
+    total: z.ZodOptional<z.ZodObject<{
+        all: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+        filtered: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+        estimated: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    }, {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        exportId: string;
+        message?: string | undefined;
+        type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+        status?: "pending" | "done" | "failed" | "error" | undefined;
+        createdAt?: string | undefined;
+        criteria?: string | undefined;
+        finishedAt?: string | undefined;
+        exportedRows?: number | undefined;
+    }[];
+    total?: {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    } | undefined;
+}, {
+    items: {
+        exportId: string;
+        message?: string | undefined;
+        type?: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment" | undefined;
+        status?: "pending" | "done" | "failed" | "error" | undefined;
+        createdAt?: string | undefined;
+        criteria?: string | undefined;
+        finishedAt?: string | undefined;
+        exportedRows?: number | undefined;
+    }[];
+    total?: {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    } | undefined;
+}>;
+export type ExportListResponse = z.infer<typeof ExportListResponseSchema>;
+export declare const ExportCreateInputSchema: z.ZodObject<{
+    type: z.ZodEnum<["campaignCode", "member", "memberTier", "memberSegment", "rewardFulfillment"]>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment";
+    filters?: Record<string, unknown> | undefined;
+    page?: number | undefined;
+    perPage?: number | undefined;
+}, {
+    type: "member" | "campaignCode" | "memberTier" | "memberSegment" | "rewardFulfillment";
+    filters?: Record<string, unknown> | undefined;
+    page?: number | undefined;
+    perPage?: number | undefined;
+}>;
+export type ExportCreateInput = z.infer<typeof ExportCreateInputSchema>;

package/dist/types/schemas/export.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+// Export type enum
+export const ExportTypeEnum = z.enum([
+    "campaignCode",
+    "member",
+    "memberTier",
+    "memberSegment",
+    "rewardFulfillment",
+]);
+// Export status enum
+export const ExportStatusEnum = z.enum([
+    "pending",
+    "done",
+    "failed",
+    "error",
+]);
+// Export schema
+export const ExportSchema = z.object({
+    exportId: z.string().describe("Unique export ID (UUID)."),
+    type: ExportTypeEnum.optional().describe("Export type."),
+    status: ExportStatusEnum.optional().describe("Export status: pending, done, failed, error."),
+    createdAt: z.string().optional().describe("Creation timestamp."),
+    finishedAt: z.string().optional().describe("Completion timestamp."),
+    criteria: z.string().optional().describe("Filter criteria used for export."),
+    exportedRows: z.number().optional().describe("Number of rows exported."),
+    message: z.string().optional().describe("Status message or error description."),
+});
+// Export list response
+export const ExportListResponseSchema = z.object({
+    items: z.array(ExportSchema),
+    total: z.object({
+        all: z.union([z.number(), z.string()]).optional(),
+        filtered: z.union([z.number(), z.string()]).optional(),
+        estimated: z.boolean().optional(),
+    }).optional(),
+});
+// Export create input schema - filters vary by type
+export const ExportCreateInputSchema = z.object({
+    type: ExportTypeEnum.describe("Export type: campaignCode, member, memberTier, memberSegment, rewardFulfillment."),
+    filters: z.record(z.unknown()).optional().describe("Type-specific filters. For campaignCode: { campaignId?, code?, status?, codeId?, usedByMemberId?, createdAt?, usedAt? }. For member exports: member-specific filters."),
+    page: z.number().optional().describe("Page number for export."),
+    perPage: z.number().optional().describe("Items per page for export."),
+});