@open-loyalty/mcp-server 1.0.0

package/dist/types/schemas/transaction.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { TotalSchema } from "./common.js";
+export const LabelSchema = z.object({
+    key: z.string(),
+    value: z.string(),
+});
+export const TransactionHeaderSchema = z.object({
+    documentNumber: z.string(),
+    purchasedAt: z.string(),
+    documentType: z.enum(["sell", "return"]).optional(),
+    linkedDocumentNumber: z.string().optional(),
+    purchasePlace: z.string().optional(),
+    labels: z.array(LabelSchema).optional(),
+});
+export const TransactionItemSchema = z.object({
+    sku: z.string(),
+    name: z.string(),
+    grossValue: z.number(),
+    category: z.string(),
+    quantity: z.number().optional(),
+    highPrecisionQuantity: z.number().optional(),
+    maker: z.string().optional(),
+    labels: z.array(LabelSchema).optional(),
+});
+export const TransactionAddressSchema = z.object({
+    street: z.string().optional(),
+    address1: z.string().optional(),
+    province: z.string().optional(),
+    city: z.string().optional(),
+    postal: z.string().optional(),
+    country: z.string().optional(),
+});
+export const TransactionCustomerDataSchema = z.object({
+    customerId: z.string().optional(),
+    email: z.string().optional(),
+    name: z.string().optional(),
+    phone: z.string().optional(),
+    loyaltyCardNumber: z.string().optional(),
+    nip: z.string().optional(),
+    address: TransactionAddressSchema.optional(),
+});
+export const TransactionSchema = z.object({
+    transactionId: z.string(),
+    header: TransactionHeaderSchema,
+    items: z.array(TransactionItemSchema),
+    customerData: TransactionCustomerDataSchema.optional(),
+    customerId: z.string().optional(),
+    matched: z.boolean(),
+    grossValue: z.number(),
+    pointsEarned: z.number().optional(),
+    createdAt: z.string().optional(),
+});
+export const TransactionCreateInputSchema = z.object({
+    storeCode: z.string().optional(),
+    header: TransactionHeaderSchema,
+    items: z.array(TransactionItemSchema),
+    customerData: TransactionCustomerDataSchema.optional(),
+    channelId: z.string().optional(),
+});
+export const TransactionListResponseSchema = z.object({
+    items: z.array(TransactionSchema),
+    total: TotalSchema,
+});

package/dist/types/schemas/wallet-type.d.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+export declare const WalletTypeSchema: z.ZodObject<{
+    walletTypeId: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    unitSingularName: z.ZodOptional<z.ZodString>;
+    unitPluralName: z.ZodOptional<z.ZodString>;
+    active: z.ZodBoolean;
+    isDefault: z.ZodBoolean;
+    createdAt: z.ZodOptional<z.ZodString>;
+    limits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    allowNegativeBalance: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    walletTypeId: string;
+    name: string;
+    active: boolean;
+    isDefault: boolean;
+    unitSingularName?: string | undefined;
+    unitPluralName?: string | undefined;
+    createdAt?: string | undefined;
+    limits?: Record<string, unknown> | undefined;
+    allowNegativeBalance?: boolean | undefined;
+}, {
+    code: string;
+    walletTypeId: string;
+    name: string;
+    active: boolean;
+    isDefault: boolean;
+    unitSingularName?: string | undefined;
+    unitPluralName?: string | undefined;
+    createdAt?: string | undefined;
+    limits?: Record<string, unknown> | undefined;
+    allowNegativeBalance?: boolean | undefined;
+}>;
+export declare const WalletTypeListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        walletTypeId: z.ZodString;
+        code: z.ZodString;
+        name: z.ZodString;
+        unitSingularName: z.ZodOptional<z.ZodString>;
+        unitPluralName: z.ZodOptional<z.ZodString>;
+        active: z.ZodBoolean;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodOptional<z.ZodString>;
+        limits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        allowNegativeBalance: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        walletTypeId: string;
+        name: string;
+        active: boolean;
+        isDefault: boolean;
+        unitSingularName?: string | undefined;
+        unitPluralName?: string | undefined;
+        createdAt?: string | undefined;
+        limits?: Record<string, unknown> | undefined;
+        allowNegativeBalance?: boolean | undefined;
+    }, {
+        code: string;
+        walletTypeId: string;
+        name: string;
+        active: boolean;
+        isDefault: boolean;
+        unitSingularName?: string | undefined;
+        unitPluralName?: string | undefined;
+        createdAt?: string | undefined;
+        limits?: Record<string, unknown> | undefined;
+        allowNegativeBalance?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        code: string;
+        walletTypeId: string;
+        name: string;
+        active: boolean;
+        isDefault: boolean;
+        unitSingularName?: string | undefined;
+        unitPluralName?: string | undefined;
+        createdAt?: string | undefined;
+        limits?: Record<string, unknown> | undefined;
+        allowNegativeBalance?: boolean | undefined;
+    }[];
+}, {
+    items: {
+        code: string;
+        walletTypeId: string;
+        name: string;
+        active: boolean;
+        isDefault: boolean;
+        unitSingularName?: string | undefined;
+        unitPluralName?: string | undefined;
+        createdAt?: string | undefined;
+        limits?: Record<string, unknown> | undefined;
+        allowNegativeBalance?: boolean | undefined;
+    }[];
+}>;
+export type WalletType = z.infer<typeof WalletTypeSchema>;
+export type WalletTypeListResponse = z.infer<typeof WalletTypeListResponseSchema>;

package/dist/types/schemas/wallet-type.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const WalletTypeSchema = z.object({
+    walletTypeId: z.string(),
+    code: z.string(),
+    name: z.string(),
+    unitSingularName: z.string().optional(),
+    unitPluralName: z.string().optional(),
+    active: z.boolean(),
+    isDefault: z.boolean(),
+    createdAt: z.string().optional(),
+    limits: z.record(z.unknown()).optional(),
+    allowNegativeBalance: z.boolean().optional(),
+});
+// API returns { items: [...] } not just an array
+export const WalletTypeListResponseSchema = z.object({
+    items: z.array(WalletTypeSchema),
+});

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

@@ -0,0 +1,195 @@
+import { z } from "zod";
+export declare const WebhookHeaderSchema: z.ZodObject<{
+    headerName: z.ZodString;
+    headerValue: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headerName: string;
+    headerValue: string;
+}, {
+    headerName: string;
+    headerValue: string;
+}>;
+export type WebhookHeader = z.infer<typeof WebhookHeaderSchema>;
+export declare const WebhookSubscriptionSchema: z.ZodObject<{
+    webhookSubscriptionId: z.ZodString;
+    eventName: z.ZodString;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        headerName: z.ZodString;
+        headerValue: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        headerName: string;
+        headerValue: string;
+    }, {
+        headerName: string;
+        headerValue: string;
+    }>, "many">>;
+    createdAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    eventName: string;
+    webhookSubscriptionId: string;
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+    createdAt?: string | undefined;
+}, {
+    url: string;
+    eventName: string;
+    webhookSubscriptionId: string;
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+    createdAt?: string | undefined;
+}>;
+export type WebhookSubscription = z.infer<typeof WebhookSubscriptionSchema>;
+export declare const WebhookSubscriptionCreateInputSchema: z.ZodObject<{
+    eventName: z.ZodString;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        headerName: z.ZodString;
+        headerValue: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        headerName: string;
+        headerValue: string;
+    }, {
+        headerName: string;
+        headerValue: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    eventName: string;
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+}, {
+    url: string;
+    eventName: string;
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+}>;
+export type WebhookSubscriptionCreateInput = z.infer<typeof WebhookSubscriptionCreateInputSchema>;
+export declare const WebhookSubscriptionUpdateInputSchema: z.ZodObject<{
+    eventName: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        headerName: z.ZodString;
+        headerValue: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        headerName: string;
+        headerValue: string;
+    }, {
+        headerName: string;
+        headerValue: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+    url?: string | undefined;
+    eventName?: string | undefined;
+}, {
+    headers?: {
+        headerName: string;
+        headerValue: string;
+    }[] | undefined;
+    url?: string | undefined;
+    eventName?: string | undefined;
+}>;
+export type WebhookSubscriptionUpdateInput = z.infer<typeof WebhookSubscriptionUpdateInputSchema>;
+export declare const WebhookEventTypesSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: string[];
+}, {
+    items: string[];
+}>;
+export type WebhookEventTypes = z.infer<typeof WebhookEventTypesSchema>;
+export declare const WebhookSubscriptionListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        webhookSubscriptionId: z.ZodString;
+        eventName: z.ZodString;
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            headerName: z.ZodString;
+            headerValue: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            headerName: string;
+            headerValue: string;
+        }, {
+            headerName: string;
+            headerValue: string;
+        }>, "many">>;
+        createdAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        eventName: string;
+        webhookSubscriptionId: string;
+        headers?: {
+            headerName: string;
+            headerValue: string;
+        }[] | undefined;
+        createdAt?: string | undefined;
+    }, {
+        url: string;
+        eventName: string;
+        webhookSubscriptionId: string;
+        headers?: {
+            headerName: string;
+            headerValue: string;
+        }[] | undefined;
+        createdAt?: string | 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: {
+        url: string;
+        eventName: string;
+        webhookSubscriptionId: string;
+        headers?: {
+            headerName: string;
+            headerValue: string;
+        }[] | undefined;
+        createdAt?: string | undefined;
+    }[];
+    total?: {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    } | undefined;
+}, {
+    items: {
+        url: string;
+        eventName: string;
+        webhookSubscriptionId: string;
+        headers?: {
+            headerName: string;
+            headerValue: string;
+        }[] | undefined;
+        createdAt?: string | undefined;
+    }[];
+    total?: {
+        all?: string | number | undefined;
+        filtered?: string | number | undefined;
+        estimated?: boolean | undefined;
+    } | undefined;
+}>;
+export type WebhookSubscriptionListResponse = z.infer<typeof WebhookSubscriptionListResponseSchema>;

package/dist/types/schemas/webhook.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+// Webhook header for custom headers in subscriptions
+export const WebhookHeaderSchema = z.object({
+    headerName: z.string().describe("Header name."),
+    headerValue: z.string().describe("Header value."),
+});
+// Webhook subscription
+export const WebhookSubscriptionSchema = z.object({
+    webhookSubscriptionId: z.string().describe("Unique webhook subscription ID (UUID)."),
+    eventName: z.string().describe("Event name this subscription listens to."),
+    url: z.string().describe("URL to send webhook events to."),
+    headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
+    createdAt: z.string().optional().describe("Creation timestamp (ISO format)."),
+});
+// Input schema for creating a webhook subscription
+export const WebhookSubscriptionCreateInputSchema = z.object({
+    eventName: z.string().describe("Event name to subscribe to. Use webhook_events to discover available events."),
+    url: z.string().describe("URL to receive webhook events."),
+    headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
+});
+// Input schema for updating a webhook subscription
+export const WebhookSubscriptionUpdateInputSchema = z.object({
+    eventName: z.string().optional().describe("Event name to subscribe to."),
+    url: z.string().optional().describe("URL to receive webhook events."),
+    headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
+});
+// Response schema for webhook event types list
+export const WebhookEventTypesSchema = z.object({
+    items: z.array(z.string()).describe("List of available webhook event type names."),
+});
+// Response schema for webhook subscription list
+export const WebhookSubscriptionListResponseSchema = z.object({
+    items: z.array(WebhookSubscriptionSchema),
+    total: z.object({
+        all: z.union([z.number(), z.string()]).optional(),
+        filtered: z.union([z.number(), z.string()]).optional(),
+        estimated: z.boolean().optional(),
+    }).optional(),
+});

package/dist/utils/cursor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Cursor-based pagination utilities for Open Loyalty MCP.
+ *
+ * Since the Open Loyalty API only supports offset-based pagination (_page/_itemsOnPage),
+ * we implement client-side cursor emulation by encoding pagination state into opaque cursors.
+ */
+/**
+ * Internal cursor data structure.
+ * Encoded as base64url JSON for the external cursor string.
+ */
+export interface CursorData {
+    /** Page number (1-indexed) */
+    p: number;
+    /** Items per page */
+    pp: number;
+    /** Version for future migrations */
+    v: number;
+    /** Optional timestamp for expiration (not currently enforced) */
+    ts?: number;
+}
+/**
+ * Pagination metadata returned in list responses.
+ */
+export interface PaginationMeta {
+    /** Current cursor (encodes current page state) */
+    cursor: string;
+    /** Cursor for the next page, or undefined if no more pages */
+    nextCursor: string | undefined;
+    /** Whether there are more items after the current page */
+    hasMore: boolean;
+}
+/**
+ * Encode pagination state into an opaque cursor string.
+ * Uses base64url encoding of JSON data.
+ *
+ * @param data - Pagination state to encode
+ * @returns Opaque cursor string
+ */
+export declare function encodeCursor(data: Omit<CursorData, 'v'>): string;
+/**
+ * Decode an opaque cursor string back to pagination state.
+ *
+ * @param cursor - Opaque cursor string
+ * @returns Decoded pagination state, or null if invalid
+ */
+export declare function decodeCursor(cursor: string): CursorData | null;
+/**
+ * Build pagination metadata for a list response.
+ *
+ * @param page - Current page number (1-indexed)
+ * @param perPage - Items per page
+ * @param itemCount - Number of items returned in current page
+ * @param total - Total number of items (from API response, may be undefined)
+ * @returns Pagination metadata with cursors
+ */
+export declare function buildPaginationMeta(page: number, perPage: number, itemCount: number, total?: number): PaginationMeta;
+/**
+ * Pagination input that supports both cursor and page/perPage.
+ */
+export interface PaginationInput {
+    /** Opaque cursor from previous response (takes priority over page/perPage) */
+    cursor?: string;
+    /** Page number (1-indexed, used if no cursor) */
+    page?: number;
+    /** Items per page (used if no cursor) */
+    perPage?: number;
+}
+/**
+ * Resolved pagination parameters for API calls.
+ */
+export interface ResolvedPagination {
+    /** Page number to request (1-indexed) */
+    page: number;
+    /** Items per page */
+    perPage: number;
+}
+/**
+ * Resolve pagination input to concrete page/perPage values.
+ * If a cursor is provided and valid, it takes priority over page/perPage.
+ *
+ * @param input - Pagination input with optional cursor
+ * @returns Resolved page and perPage values
+ */
+export declare function resolvePaginationInput(input: PaginationInput): ResolvedPagination;

package/dist/utils/cursor.js

@@ -0,0 +1,117 @@
+/**
+ * Cursor-based pagination utilities for Open Loyalty MCP.
+ *
+ * Since the Open Loyalty API only supports offset-based pagination (_page/_itemsOnPage),
+ * we implement client-side cursor emulation by encoding pagination state into opaque cursors.
+ */
+/** Current cursor format version */
+const CURSOR_VERSION = 1;
+/**
+ * Encode pagination state into an opaque cursor string.
+ * Uses base64url encoding of JSON data.
+ *
+ * @param data - Pagination state to encode
+ * @returns Opaque cursor string
+ */
+export function encodeCursor(data) {
+    const cursorData = {
+        ...data,
+        v: CURSOR_VERSION,
+    };
+    const json = JSON.stringify(cursorData);
+    // Use base64url encoding (URL-safe base64)
+    return Buffer.from(json, 'utf-8')
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/**
+ * Decode an opaque cursor string back to pagination state.
+ *
+ * @param cursor - Opaque cursor string
+ * @returns Decoded pagination state, or null if invalid
+ */
+export function decodeCursor(cursor) {
+    try {
+        // Restore base64 from base64url
+        let base64 = cursor.replace(/-/g, '+').replace(/_/g, '/');
+        // Add padding if needed
+        const paddingNeeded = (4 - (base64.length % 4)) % 4;
+        base64 += '='.repeat(paddingNeeded);
+        const json = Buffer.from(base64, 'base64').toString('utf-8');
+        const data = JSON.parse(json);
+        // Validate required fields
+        if (typeof data.p !== 'number' || data.p < 1)
+            return null;
+        if (typeof data.pp !== 'number' || data.pp < 1)
+            return null;
+        if (typeof data.v !== 'number')
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build pagination metadata for a list response.
+ *
+ * @param page - Current page number (1-indexed)
+ * @param perPage - Items per page
+ * @param itemCount - Number of items returned in current page
+ * @param total - Total number of items (from API response, may be undefined)
+ * @returns Pagination metadata with cursors
+ */
+export function buildPaginationMeta(page, perPage, itemCount, total) {
+    // Build current cursor
+    const cursor = encodeCursor({ p: page, pp: perPage });
+    // Determine if there are more pages
+    let hasMore = false;
+    if (total !== undefined && typeof total === 'number') {
+        // If we have total, calculate if there are more pages
+        hasMore = page * perPage < total;
+    }
+    else {
+        // If no total, assume more pages if we got a full page of results
+        hasMore = itemCount >= perPage;
+    }
+    // Build next cursor if there are more pages
+    const nextCursor = hasMore
+        ? encodeCursor({ p: page + 1, pp: perPage })
+        : undefined;
+    return {
+        cursor,
+        nextCursor,
+        hasMore,
+    };
+}
+/** Default page number if not specified */
+const DEFAULT_PAGE = 1;
+/** Default items per page if not specified */
+const DEFAULT_PER_PAGE = 25;
+/**
+ * Resolve pagination input to concrete page/perPage values.
+ * If a cursor is provided and valid, it takes priority over page/perPage.
+ *
+ * @param input - Pagination input with optional cursor
+ * @returns Resolved page and perPage values
+ */
+export function resolvePaginationInput(input) {
+    // If cursor is provided, try to decode it
+    if (input.cursor) {
+        const cursorData = decodeCursor(input.cursor);
+        if (cursorData) {
+            return {
+                page: cursorData.p,
+                perPage: cursorData.pp,
+            };
+        }
+        // Invalid cursor - fall through to page/perPage
+    }
+    // Use page/perPage with defaults
+    return {
+        page: input.page ?? DEFAULT_PAGE,
+        perPage: input.perPage ?? DEFAULT_PER_PAGE,
+    };
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class OpenLoyaltyError extends Error {
+    code: string;
+    hint: string;
+    relatedTool: string;
+    constructor(options: {
+        code: string;
+        message: string;
+        hint: string;
+        relatedTool: string;
+    });
+}
+export declare function formatApiError(error: unknown, relatedTool: string): OpenLoyaltyError;