@bates-solutions/squareup 0.1.0

package/dist/core/services/loyalty.service.js

@@ -0,0 +1,340 @@
+import { parseSquareError, SquareValidationError } from '../errors.js';
+import { createIdempotencyKey } from '../utils.js';
+/**
+ * Loyalty service for managing Square loyalty programs
+ *
+ * @example
+ * ```typescript
+ * // Create a loyalty account
+ * const account = await square.loyalty.createAccount({
+ *   programId: 'PROG_123',
+ *   phoneNumber: '+15551234567',
+ * });
+ *
+ * // Add points
+ * await square.loyalty.accumulatePoints(account.id, {
+ *   points: 100,
+ * });
+ *
+ * // Redeem a reward
+ * await square.loyalty.redeemReward(account.id, 'REWARD_123');
+ * ```
+ */
+export class LoyaltyService {
+    client;
+    defaultLocationId;
+    constructor(client, defaultLocationId) {
+        this.client = client;
+        this.defaultLocationId = defaultLocationId;
+    }
+    /**
+     * Get the loyalty program for the current location
+     *
+     * @param programId - Optional program ID (uses main program if not provided)
+     * @returns Loyalty program details
+     *
+     * @example
+     * ```typescript
+     * const program = await square.loyalty.getProgram();
+     * console.log(`Points name: ${program.terminology?.other}`);
+     * ```
+     */
+    async getProgram(programId) {
+        try {
+            if (programId) {
+                const response = await this.client.loyalty.programs.get({ programId });
+                if (!response.program) {
+                    throw new Error('Loyalty program not found');
+                }
+                return response.program;
+            }
+            // Get the main program
+            const response = await this.client.loyalty.programs.list();
+            const programs = response.programs ?? [];
+            if (programs.length === 0) {
+                throw new Error('No loyalty program found');
+            }
+            return programs[0];
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Create a new loyalty account
+     *
+     * @param options - Account creation options
+     * @returns Created loyalty account
+     *
+     * @example
+     * ```typescript
+     * const account = await square.loyalty.createAccount({
+     *   programId: 'PROG_123',
+     *   phoneNumber: '+15551234567',
+     * });
+     * ```
+     */
+    async createAccount(options) {
+        if (!options.programId) {
+            throw new SquareValidationError('programId is required', 'programId');
+        }
+        if (!options.phoneNumber && !options.customerId) {
+            throw new SquareValidationError('Either phoneNumber or customerId is required', 'phoneNumber');
+        }
+        try {
+            const response = await this.client.loyalty.accounts.create({
+                loyaltyAccount: {
+                    programId: options.programId,
+                    mapping: options.phoneNumber
+                        ? {
+                            phoneNumber: options.phoneNumber,
+                        }
+                        : undefined,
+                    customerId: options.customerId,
+                },
+                idempotencyKey: options.idempotencyKey ?? createIdempotencyKey(),
+            });
+            if (!response.loyaltyAccount) {
+                throw new Error('Loyalty account was not created');
+            }
+            return response.loyaltyAccount;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Get a loyalty account by ID
+     *
+     * @param accountId - Loyalty account ID
+     * @returns Loyalty account details
+     *
+     * @example
+     * ```typescript
+     * const account = await square.loyalty.getAccount('ACCT_123');
+     * console.log(`Balance: ${account.balance} points`);
+     * ```
+     */
+    async getAccount(accountId) {
+        try {
+            const response = await this.client.loyalty.accounts.get({ accountId });
+            if (!response.loyaltyAccount) {
+                throw new Error('Loyalty account not found');
+            }
+            return response.loyaltyAccount;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Search for loyalty accounts
+     *
+     * @param options - Search options
+     * @returns Matching loyalty accounts
+     *
+     * @example
+     * ```typescript
+     * // Find by phone number
+     * const accounts = await square.loyalty.searchAccounts({
+     *   phoneNumber: '+15551234567',
+     * });
+     *
+     * // Find by customer ID
+     * const accounts = await square.loyalty.searchAccounts({
+     *   customerId: 'CUST_123',
+     * });
+     * ```
+     */
+    async searchAccounts(options) {
+        try {
+            const mappings = [];
+            const customerIds = [];
+            if (options?.phoneNumber) {
+                mappings.push({ phoneNumber: options.phoneNumber });
+            }
+            if (options?.customerId) {
+                customerIds.push(options.customerId);
+            }
+            const response = await this.client.loyalty.accounts.search({
+                cursor: options?.cursor,
+                limit: options?.limit,
+                query: mappings.length > 0 || customerIds.length > 0
+                    ? {
+                        mappings: mappings.length > 0 ? mappings : undefined,
+                        customerIds: customerIds.length > 0 ? customerIds : undefined,
+                    }
+                    : undefined,
+            });
+            return {
+                data: (response.loyaltyAccounts ?? []),
+                cursor: response.cursor,
+            };
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Accumulate (add) points to a loyalty account
+     *
+     * @param accountId - Loyalty account ID
+     * @param options - Accumulation options
+     * @returns Loyalty event
+     *
+     * @example
+     * ```typescript
+     * // Add points from an order
+     * await square.loyalty.accumulatePoints('ACCT_123', {
+     *   orderId: 'ORDER_456',
+     * });
+     *
+     * // Add points manually
+     * await square.loyalty.accumulatePoints('ACCT_123', {
+     *   points: 50,
+     * });
+     * ```
+     */
+    async accumulatePoints(accountId, options) {
+        const locationId = this.defaultLocationId;
+        if (!locationId) {
+            throw new SquareValidationError('locationId is required. Set it in client config.', 'locationId');
+        }
+        if (!options.orderId && !options.points) {
+            throw new SquareValidationError('Either orderId or points is required');
+        }
+        try {
+            const response = await this.client.loyalty.accounts.accumulatePoints({
+                accountId,
+                accumulatePoints: {
+                    orderId: options.orderId,
+                    points: options.points,
+                },
+                locationId,
+                idempotencyKey: options.idempotencyKey ?? createIdempotencyKey(),
+            });
+            if (!response.event) {
+                throw new Error('Points accumulation failed');
+            }
+            return response.event;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Adjust points on a loyalty account (add or subtract)
+     *
+     * @param accountId - Loyalty account ID
+     * @param points - Points to add (positive) or subtract (negative)
+     * @param reason - Reason for adjustment
+     * @returns Loyalty event
+     *
+     * @example
+     * ```typescript
+     * // Add bonus points
+     * await square.loyalty.adjustPoints('ACCT_123', 100, 'Birthday bonus');
+     *
+     * // Remove points
+     * await square.loyalty.adjustPoints('ACCT_123', -50, 'Points correction');
+     * ```
+     */
+    async adjustPoints(accountId, points, reason, idempotencyKey) {
+        try {
+            const response = await this.client.loyalty.accounts.adjust({
+                accountId,
+                adjustPoints: {
+                    points,
+                    reason,
+                },
+                idempotencyKey: idempotencyKey ?? createIdempotencyKey(),
+            });
+            if (!response.event) {
+                throw new Error('Points adjustment failed');
+            }
+            return response.event;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Redeem a reward
+     *
+     * @param accountId - Loyalty account ID
+     * @param rewardTierId - Reward tier ID to redeem
+     * @param orderId - Optional order ID to apply reward to
+     * @returns Created reward
+     *
+     * @example
+     * ```typescript
+     * const reward = await square.loyalty.redeemReward(
+     *   'ACCT_123',
+     *   'TIER_123',
+     *   'ORDER_456'
+     * );
+     * ```
+     */
+    async redeemReward(accountId, rewardTierId, orderId, idempotencyKey) {
+        const locationId = this.defaultLocationId;
+        if (!locationId) {
+            throw new SquareValidationError('locationId is required. Set it in client config.', 'locationId');
+        }
+        try {
+            const response = await this.client.loyalty.rewards.create({
+                reward: {
+                    loyaltyAccountId: accountId,
+                    rewardTierId,
+                    orderId,
+                },
+                idempotencyKey: idempotencyKey ?? createIdempotencyKey(),
+            });
+            if (!response.reward?.id) {
+                throw new Error('Reward creation failed');
+            }
+            const rewardId = response.reward.id;
+            // Redeem the reward
+            const redeemResponse = await this.client.loyalty.rewards.redeem({
+                rewardId,
+                locationId,
+                idempotencyKey: createIdempotencyKey(),
+            });
+            if (!redeemResponse.event) {
+                throw new Error('Reward redemption failed');
+            }
+            return {
+                id: rewardId,
+                status: 'REDEEMED',
+            };
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Calculate points that would be earned for an order
+     *
+     * @param programId - Loyalty program ID
+     * @param orderId - Order ID to calculate points for
+     * @returns Points that would be earned
+     *
+     * @example
+     * ```typescript
+     * const points = await square.loyalty.calculatePoints('PROG_123', 'ORDER_123');
+     * console.log(`This order earns ${points} points`);
+     * ```
+     */
+    async calculatePoints(programId, orderId) {
+        try {
+            const response = await this.client.loyalty.programs.calculate({
+                programId,
+                orderId,
+            });
+            return response.points ?? 0;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+}
+//# sourceMappingURL=loyalty.service.js.map

package/dist/core/services/loyalty.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loyalty.service.js","sourceRoot":"","sources":["../../../src/core/services/loyalty.service.ts"],"names":[],"mappings":"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"}

package/dist/core/services/orders.service.d.ts

@@ -0,0 +1,121 @@
+import type { SquareClient } from 'square';
+import type { CreateOrderOptions } from '../types/index.js';
+import { OrderBuilder, type Order } from '../builders/order.builder.js';
+/**
+ * Orders service for managing Square orders
+ *
+ * @example
+ * ```typescript
+ * // Using the builder (recommended)
+ * const order = await square.orders
+ *   .builder()
+ *   .addItem({ name: 'Latte', amount: 450 })
+ *   .withCustomer('CUST_123')
+ *   .build();
+ *
+ * // Or create directly
+ * const order = await square.orders.create({
+ *   lineItems: [{ name: 'Latte', amount: 450 }],
+ * });
+ * ```
+ */
+export declare class OrdersService {
+    private readonly client;
+    private readonly defaultLocationId?;
+    constructor(client: SquareClient, defaultLocationId?: string | undefined);
+    /**
+     * Create a new order builder
+     *
+     * @param locationId - Optional location ID (uses default if not provided)
+     * @returns Order builder instance
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders
+     *   .builder()
+     *   .addItem({ name: 'Coffee', amount: 350 })
+     *   .addItem({ name: 'Muffin', amount: 250 })
+     *   .withTip(100)
+     *   .build();
+     * ```
+     */
+    builder(locationId?: string): OrderBuilder;
+    /**
+     * Create an order directly (without builder)
+     *
+     * @param options - Order creation options
+     * @param locationId - Optional location ID
+     * @returns Created order
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.create({
+     *   lineItems: [
+     *     { name: 'Coffee', amount: 350 },
+     *     { catalogObjectId: 'ITEM_123', quantity: 2 },
+     *   ],
+     *   customerId: 'CUST_123',
+     * });
+     * ```
+     */
+    create(options: CreateOrderOptions, locationId?: string): Promise<Order>;
+    /**
+     * Get an order by ID
+     *
+     * @param orderId - Order ID
+     * @returns Order details
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.get('ORDER_123');
+     * ```
+     */
+    get(orderId: string): Promise<Order>;
+    /**
+     * Update an order
+     *
+     * @param orderId - Order ID to update
+     * @param updates - Update fields
+     * @returns Updated order
+     */
+    update(orderId: string, updates: {
+        version: number;
+        referenceId?: string;
+    }, locationId?: string): Promise<Order>;
+    /**
+     * Pay for an order
+     *
+     * @param orderId - Order ID
+     * @param paymentIds - Payment IDs to apply
+     * @returns Updated order
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.pay('ORDER_123', ['PAYMENT_456']);
+     * ```
+     */
+    pay(orderId: string, paymentIds: string[]): Promise<Order>;
+    /**
+     * Search for orders
+     *
+     * @param options - Search options
+     * @returns Paginated list of orders
+     *
+     * @example
+     * ```typescript
+     * const { data, cursor } = await square.orders.search({
+     *   locationIds: ['LXXX'],
+     *   limit: 10,
+     * });
+     * ```
+     */
+    search(options?: {
+        locationIds?: string[];
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        data: Order[];
+        cursor?: string;
+    }>;
+}
+//# sourceMappingURL=orders.service.d.ts.map

package/dist/core/services/orders.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/orders.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,OAAO,EAAE,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAExE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;gBADlB,MAAM,EAAE,YAAY,EACpB,iBAAiB,CAAC,EAAE,MAAM,YAAA;IAG7C;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY;IAW1C;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,OAAO,EAAE,kBAAkB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IA+B9E;;;;;;;;;;OAUG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAc1C;;;;;;OAMG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EACD,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,KAAK,CAAC;IA8BjB;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;IAkBhE;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,OAAO,CAAC,EAAE;QACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAsBhD"}

package/dist/core/services/orders.service.js

@@ -0,0 +1,208 @@
+import { parseSquareError, SquareValidationError } from '../errors.js';
+import { createIdempotencyKey } from '../utils.js';
+import { OrderBuilder } from '../builders/order.builder.js';
+/**
+ * Orders service for managing Square orders
+ *
+ * @example
+ * ```typescript
+ * // Using the builder (recommended)
+ * const order = await square.orders
+ *   .builder()
+ *   .addItem({ name: 'Latte', amount: 450 })
+ *   .withCustomer('CUST_123')
+ *   .build();
+ *
+ * // Or create directly
+ * const order = await square.orders.create({
+ *   lineItems: [{ name: 'Latte', amount: 450 }],
+ * });
+ * ```
+ */
+export class OrdersService {
+    client;
+    defaultLocationId;
+    constructor(client, defaultLocationId) {
+        this.client = client;
+        this.defaultLocationId = defaultLocationId;
+    }
+    /**
+     * Create a new order builder
+     *
+     * @param locationId - Optional location ID (uses default if not provided)
+     * @returns Order builder instance
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders
+     *   .builder()
+     *   .addItem({ name: 'Coffee', amount: 350 })
+     *   .addItem({ name: 'Muffin', amount: 250 })
+     *   .withTip(100)
+     *   .build();
+     * ```
+     */
+    builder(locationId) {
+        const location = locationId ?? this.defaultLocationId;
+        if (!location) {
+            throw new SquareValidationError('locationId is required. Set it in client config or provide it explicitly.', 'locationId');
+        }
+        return new OrderBuilder(this.client, location);
+    }
+    /**
+     * Create an order directly (without builder)
+     *
+     * @param options - Order creation options
+     * @param locationId - Optional location ID
+     * @returns Created order
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.create({
+     *   lineItems: [
+     *     { name: 'Coffee', amount: 350 },
+     *     { catalogObjectId: 'ITEM_123', quantity: 2 },
+     *   ],
+     *   customerId: 'CUST_123',
+     * });
+     * ```
+     */
+    async create(options, locationId) {
+        const location = locationId ?? this.defaultLocationId;
+        if (!location) {
+            throw new SquareValidationError('locationId is required. Set it in client config or provide it explicitly.', 'locationId');
+        }
+        if (options.lineItems.length === 0) {
+            throw new SquareValidationError('Order must have at least one line item', 'lineItems');
+        }
+        // Use builder internally for consistent validation
+        const builder = new OrderBuilder(this.client, location);
+        for (const item of options.lineItems) {
+            builder.addItem(item);
+        }
+        if (options.customerId) {
+            builder.withCustomer(options.customerId);
+        }
+        if (options.referenceId) {
+            builder.withReference(options.referenceId);
+        }
+        return builder.build();
+    }
+    /**
+     * Get an order by ID
+     *
+     * @param orderId - Order ID
+     * @returns Order details
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.get('ORDER_123');
+     * ```
+     */
+    async get(orderId) {
+        try {
+            const response = await this.client.orders.get({ orderId });
+            if (!response.order) {
+                throw new Error('Order not found');
+            }
+            return response.order;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Update an order
+     *
+     * @param orderId - Order ID to update
+     * @param updates - Update fields
+     * @returns Updated order
+     */
+    async update(orderId, updates, locationId) {
+        const location = locationId ?? this.defaultLocationId;
+        if (!location) {
+            throw new SquareValidationError('locationId is required. Set it in client config or provide it explicitly.', 'locationId');
+        }
+        try {
+            const response = await this.client.orders.update({
+                orderId,
+                order: {
+                    locationId: location,
+                    version: updates.version,
+                    referenceId: updates.referenceId,
+                },
+                idempotencyKey: createIdempotencyKey(),
+            });
+            if (!response.order) {
+                throw new Error('Order update failed');
+            }
+            return response.order;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Pay for an order
+     *
+     * @param orderId - Order ID
+     * @param paymentIds - Payment IDs to apply
+     * @returns Updated order
+     *
+     * @example
+     * ```typescript
+     * const order = await square.orders.pay('ORDER_123', ['PAYMENT_456']);
+     * ```
+     */
+    async pay(orderId, paymentIds) {
+        try {
+            const response = await this.client.orders.pay({
+                orderId,
+                idempotencyKey: createIdempotencyKey(),
+                paymentIds,
+            });
+            if (!response.order) {
+                throw new Error('Order payment failed');
+            }
+            return response.order;
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+    /**
+     * Search for orders
+     *
+     * @param options - Search options
+     * @returns Paginated list of orders
+     *
+     * @example
+     * ```typescript
+     * const { data, cursor } = await square.orders.search({
+     *   locationIds: ['LXXX'],
+     *   limit: 10,
+     * });
+     * ```
+     */
+    async search(options) {
+        try {
+            const locationIds = options?.locationIds ?? (this.defaultLocationId ? [this.defaultLocationId] : []);
+            if (locationIds.length === 0) {
+                throw new SquareValidationError('At least one locationId is required for search');
+            }
+            const response = await this.client.orders.search({
+                locationIds,
+                cursor: options?.cursor,
+                limit: options?.limit,
+            });
+            return {
+                data: (response.orders ?? []),
+                cursor: response.cursor,
+            };
+        }
+        catch (error) {
+            throw parseSquareError(error);
+        }
+    }
+}
+//# sourceMappingURL=orders.service.js.map

package/dist/core/services/orders.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.service.js","sourceRoot":"","sources":["../../../src/core/services/orders.service.ts"],"names":[],"mappings":"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"}