@debugged-development/ticketapp-sdk 0.0.3 → 1.0.2

package/README.md

@@ -1,196 +1,682 @@
-# Basket Manager Usage Guide
+# Ticketapp SDK
+
+A TypeScript SDK for integrating Ticketapp's event ticketing and package management system into your application.
 
 ## Installation
 
 ```bash
-npm install @your-scope/basket-manager luxon
+npm install @debugged-development/ticketapp-sdk
+```
+
+## Quick Start
+
+```typescript
+import { TicketappSDK } from '@ticketapp/sdk';
+
+const sdk = new TicketappSDK({
+  organizationId: 'your-organization-id',
+  shopId: 'your-shop-id',
+  shopSlug: 'your-shop-slug',
+  debug: true, // Enable debug logging (optional)
+});
 ```
 
-## Setup
+## Table of Contents
+
+- [Configuration](#configuration)
+- [Events](#events)
+- [Basket (Cart)](#basket-cart)
+- [Packages](#packages)
+- [Payment](#payment)
+- [Examples](#examples)
+
+---
 
-You need to provide your GraphQL API client when initializing the BasketService:
+## Configuration
+
+### Basic Configuration
 
 ```typescript
-import { BasketService, store } from '@your-scope/basket-manager';
-import { ApolloClient } from '@apollo/client';
+const sdk = new TicketappSDK({
+  organizationId: 'eed7fb11-f5c4-4467-8393-6da072b7f752',
+  shopId: '1fbdf73d-6ee6-438b-b8e5-a76907a6d76b',
+  shopSlug: 'hvrmq',
+  debug: true,
+});
+```
 
-// Your GraphQL mutations (from your generated types)
-import {
-  useAddToOrderMutation,
-  useRemoveFromOrderMutation,
-  useConfigurePackageMutation,
-  useConfigureOrderDeliveryOptionMutation,
-  useCreateOrderCustomerMutation,
-  useDeleteOrderMutation,
-} from './order-provider.generated';
+### Advanced Configuration
 
-// Create API client wrapper
-const apiClient = {
-  addToOrder: async (variables) => {
-    const [mutate] = useAddToOrderMutation();
-    return await mutate({ variables });
-  },
-  removeFromOrder: async (variables) => {
-    const [mutate] = useRemoveFromOrderMutation();
-    return await mutate({ variables });
-  },
-  configurePackage: async (variables) => {
-    const [mutate] = useConfigurePackageMutation();
-    return await mutate({ variables });
-  },
-  configureDeliveryOption: async (variables) => {
-    const [mutate] = useConfigureOrderDeliveryOptionMutation();
-    return await mutate({ variables });
-  },
-  createCustomer: async (variables) => {
-    const [mutate] = useCreateOrderCustomerMutation();
-    return await mutate({ variables });
+```typescript
+const sdk = new TicketappSDK({
+  organizationId: 'your-organization-id',
+  shopId: 'your-shop-id',
+  shopSlug: 'your-shop-slug',
+  debug: true,
+  filteredLocationIds: ['location-id-1', 'location-id-2'], // Optional: Filter events by location
+  filteredHostingIds: ['host-id-1', 'host-id-2'],           // Optional: Filter events by host
+  enableDoorTickets: true,                                   // Optional: Include door tickets
+});
+```
+
+---
+
+## Events
+
+### Fetching Events
+
+Load all available events for your organization:
+
+```typescript
+await sdk.event.fetchEvents();
+```
+
+### Subscribing to Event Updates
+
+Get real-time updates when events change:
+
+```typescript
+const unsubscribe = sdk.event.subscribe(() => {
+  const state = sdk.event.getState();
+  console.log('Events:', state.events);
+  console.log('Loading:', state.processing);
+  console.log('Error:', state.error);
+});
+
+// Later, when you want to stop listening:
+unsubscribe();
+```
+
+### Getting Current Event State
+
+```typescript
+const state = sdk.event.getState();
+
+// state structure:
+{
+  events: Event[],      // Array of events
+  processing: boolean,  // Loading state
+  error: string | null, // Error message if any
+  loadingProducts: {}   // Products loading state per event
+}
+```
+
+### Fetching Products for an Event
+
+```typescript
+// Fetch all ticket types
+await sdk.event.fetchProductsForEvent(
+  'event-id',
+  ['TICKET', 'DOOR', 'ADDON']
+);
+
+// Fetch only regular tickets
+await sdk.event.fetchProductsForEvent(
+  'event-id',
+  ['TICKET']
+);
+
+// Fetch with promo code
+await sdk.event.fetchProductsForEvent(
+  'event-id',
+  ['TICKET'],
+  'PROMO2024'
+);
+```
+
+### Event Object Structure
+
+```typescript
+{
+  id: string,
+  name: string,
+  icon: string | null,
+  banner: string | null,
+  description: string | null,
+  startAt: DateTime,        // Luxon DateTime object
+  endAt: DateTime,
+  timezone: string,
+  location: {
+    id: string,
+    name: string,
+    address: string | null
   },
-  cancelOrder: async (variables) => {
-    const [mutate] = useDeleteOrderMutation();
-    return await mutate({ variables });
+  products: Product[]       // Available after fetchProductsForEvent
+}
+```
+
+---
+
+## Basket (Cart)
+
+The basket manages the user's shopping cart and order.
+
+### Adding a Product
+
+```typescript
+await sdk.basket.addProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  price: 50,
+  serviceFee: 5,
+  amount: 2,
+  currency: 'EUR',
+});
+```
+
+### Adding a Product with Seat Assignment
+
+```typescript
+await sdk.basket.addProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  price: 50,
+  serviceFee: 5,
+  amount: 1,
+  currency: 'EUR',
+  seat: {
+    id: 'seat-a1',
+    label: 'A1',
+    holdToken: 'hold-token-123'
+  }
+});
+```
+
+### Removing a Product
+
+```typescript
+await sdk.basket.removeProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  currency: 'EUR',
+  amount: 1,
+});
+```
+
+### Adding Customer Information
+
+```typescript
+await sdk.basket.createCustomer({
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,                    // Optional
+  gender: 'Male',             // Optional
+  residence: 'Amsterdam',     // Optional
+  extraInfo: [                // Optional: Custom key-value pairs
+    { key: 'dietaryRestrictions', value: 'Vegetarian' },
+    { key: 'tshirtSize', value: 'L' },
+    { key: 'emergencyContact', value: '+31612345678' }
+  ]
+});
+```
+
+### Getting Current Order
+
+```typescript
+const order = sdk.basket.getCurrentOrder();
+
+// order structure:
+{
+  id: string,
+  currency: string,
+  items: OrderItem[],
+  customer: Customer,
+  count: number,        // Total number of items
+  expiredAt: string
+}
+```
+
+### Subscribing to Basket Updates
+
+```typescript
+const unsubscribe = sdk.basket.subscribe(() => {
+  const order = sdk.basket.getCurrentOrder();
+  console.log('Order updated:', order);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+### Canceling an Order
+
+```typescript
+await sdk.basket.cancelOrder();
+```
+
+### Clearing Session
+
+```typescript
+sdk.basket.clearOrderFromSession();
+```
+
+---
+
+## Packages
+
+Packages are bundled event tickets (e.g., weekend passes, season tickets).
+
+### Fetching Packages
+
+```typescript
+const result = await sdk.package.getPackages();
+
+console.log('Total packages:', result.count);
+console.log('Packages:', result.data);
+```
+
+### Fetching Package Items
+
+Get the individual events/items that make up a package:
+
+```typescript
+const result = await sdk.package.getPackageItems(
+  'package-id',
+  ['REGULAR', 'ADDITIONAL_EVENT']
+);
+
+console.log('Package items:', result.data);
+```
+
+### Configuring and Adding a Package to Order
+
+```typescript
+await sdk.basket.configurePackage({
+  id: 'package-id',
+  name: 'Weekend Pass',
+  currency: 'EUR',
+  price: 200,
+  depositPrice: 200,
+  serviceFee: 20,
+  amount: 1,              // Number of persons
+  items: [
+    {
+      packageItemId: 'item-1-id',
+      eventId: 'event-1-id',
+    },
+    {
+      packageItemId: 'item-2-id',
+      eventId: 'event-2-id',
+    }
+  ]
+});
+```
+
+### Adding Additional Package Items
+
+Add extra events to an existing package order:
+
+```typescript
+const sessionId = sessionStorage.getItem('ORDER_ID_hvrmq');
+
+await sdk.package.setAdditionalPackageItem(
+  sessionId,
+  'package-item-id',
+  'event-id',
+  1 // amount
+);
+```
+
+### Package Object Structure
+
+```typescript
+{
+  id: string,
+  name: string,
+  shortDescription: string,
+  status: 'ACTIVE' | 'PAUSED' | 'SOLD_OUT' | 'CONCEPT',
+  prices: {
+    price: number,
+    discount: number | null
   },
+  amountOfEvents: number,
+  maxAmountOfPersonsPerOrder: number | null
+}
+```
+
+---
+
+## Payment
+
+### Getting Payment Methods
+
+Fetch available payment methods for an order:
+
+```typescript
+const paymentDetails = await sdk.payment.getPaymentMethods({
+  orderId: 'order-id',
+  orderItemId: 'item-id',      // Optional
+  amountOfTickets: 2,          // Optional
+  paymentMethodId: 'method-id' // Optional
+});
+
+// paymentDetails structure:
+{
+  transactionPrice: number,
+  baseTransactionFee: number | null,
+  additionalTransactionFee: number | null,
+  methods: PaymentMethod[]
+}
+```
+
+### Payment Method Structure
+
+```typescript
+{
+  id: number,
+  name: string,
+  image: string,
+  fee: {
+    type: 'FIXED' | 'PERCENTAGE',
+    value: number
+  } | null,
+  issuers: Array<{
+    id: number,
+    name: string,
+    image: string
+  }> | null
+}
+```
+
+### Calculating Payment Fees
+
+```typescript
+const paymentMethod = {
+  id: 1,
+  name: 'iDEAL',
+  image: 'https://...',
+  fee: { type: 'FIXED', value: 0.29 }
 };
 
-// Initialize the basket service
-const basketService = new BasketService({
+// Calculate fee amount
+const fee = sdk.payment.calculateFee(50, paymentMethod);
+console.log('Fee:', fee); // 0.29
+
+// Calculate total with fee
+const total = sdk.payment.calculateTotalWithFee(50, paymentMethod);
+console.log('Total:', total); // 50.29
+
+// Format fee for display
+const formatted = sdk.payment.formatFee(paymentMethod);
+console.log('Fee:', formatted); // "€0.29"
+```
+
+### Creating a Payment
+
+```typescript
+const response = await sdk.payment.createPayment({
+  orderId: 'order-id',
+  paymentMethodId: '1',
+  redirectUrl: 'https://yoursite.com/payment/return',
+  customer: {
+    firstName: 'John',
+    lastName: 'Doe',
+    email: 'john@example.com',
+    phone: '+31612345678',
+    gender: 'Male',
+    company: {                    // Optional
+      name: 'Company BV',
+      cocNumber: '12345678',
+      vatNumber: 'NL123456789B01'
+    }
+  },
+  issuerId: '1234',              // Required for bank selection (iDEAL, etc.)
+  orderItemId: 'item-id',        // Optional
+  amountOfTickets: 2,            // Optional
+});
+
+// Open payment URL
+window.open(response.paymentUrl, '_blank');
+```
+
+---
+
+## Examples
+
+### Complete Event Browsing Flow
+
+```typescript
+import { TicketappSDK } from '@ticketapp/sdk';
+
+const sdk = new TicketappSDK({
+  organizationId: 'your-org-id',
   shopId: 'your-shop-id',
   shopSlug: 'your-shop-slug',
-  apiClient,
-});
-```
-
-## Usage in React
-
-```typescript
-import { useEffect, useState } from 'react';
-import { store, Currency } from '@your-scope/basket-manager';
-
-function MyComponent() {
-  const [order, setOrder] = useState(store.getState().basket.order);
-
-  // Subscribe to store changes
-  useEffect(() => {
-    const unsubscribe = store.subscribe(() => {
-      setOrder(store.getState().basket.order);
-    });
-    return unsubscribe;
-  }, []);
-
-  const handleAddProduct = async () => {
-    await basketService.addProduct({
-      id: 'product-123',
-      name: 'My Product',
-      price: 29.99,
-      currency: Currency.EUR,
-      amount: 1,
-    });
-  };
-
-  return (
-    <div>
-      <h1>Basket</h1>
-      {order && (
-        <div>
-          <p>Order ID: {order.id}</p>
-          <p>Items: {order.items.length}</p>
-        </div>
-      )}
-      <button onClick={handleAddProduct}>Add Product</button>
-    </div>
-  );
-}
+});
+
+// 1. Fetch and display events
+await sdk.event.fetchEvents();
+const { events } = sdk.event.getState();
+
+// 2. Load products for selected event
+await sdk.event.fetchProductsForEvent(events[0].id, ['TICKET']);
+
+// 3. Add product to basket
+await sdk.basket.addProduct({
+  id: events[0].products[0].id,
+  name: events[0].products[0].name,
+  price: events[0].products[0].price,
+  serviceFee: events[0].products[0].serviceFee,
+  amount: 1,
+  currency: 'EUR',
+});
+
+// 4. Check basket
+const order = sdk.basket.getCurrentOrder();
+console.log('Items in basket:', order.count);
 ```
 
-## Usage in Vue
+### Complete Package Purchase Flow
 
 ```typescript
-import { ref, onMounted, onUnmounted } from 'vue';
-import { store, Currency } from '@your-scope/basket-manager';
+// 1. Fetch available packages
+const packagesResult = await sdk.package.getPackages();
+const selectedPackage = packagesResult.data[0];
+
+// 2. Get package items
+const itemsResult = await sdk.package.getPackageItems(
+  selectedPackage.id,
+  ['REGULAR']
+);
+
+// 3. User selects events for each item
+const items = itemsResult.data.map(item => ({
+  packageItemId: item.id,
+  eventId: item.activeEvents[0].id // User's selection
+}));
+
+// 4. Add package to basket
+await sdk.basket.configurePackage({
+  id: selectedPackage.id,
+  name: selectedPackage.name,
+  currency: 'EUR',
+  price: selectedPackage.prices.discount ?? selectedPackage.prices.price,
+  depositPrice: selectedPackage.prices.discount ?? selectedPackage.prices.price,
+  serviceFee: 0,
+  amount: 1,
+  items: items,
+});
+```
+
+### Complete Payment Flow
+
+```typescript
+// 1. Get current order
+const order = sdk.basket.getCurrentOrder();
+
+// 2. Fetch payment methods
+const paymentDetails = await sdk.payment.getPaymentMethods({
+  orderId: order.id,
+});
 
-export default {
-  setup() {
-    const order = ref(store.getState().basket.order);
-    let unsubscribe;
+// 3. User selects payment method
+const selectedMethod = paymentDetails.methods[0];
+
+// 4. Calculate total with fees
+const total = sdk.payment.calculateTotalWithFee(
+  paymentDetails.transactionPrice,
+  selectedMethod
+);
+
+// 5. Add customer info if not already added
+await sdk.basket.createCustomer({
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  extraInfo: [
+    { key: 'phoneNumber', value: '+31612345678' }
+  ]
+});
 
-    onMounted(() => {
-      unsubscribe = store.subscribe(() => {
-        order.value = store.getState().basket.order;
-      });
-    });
+// 6. Create payment
+const paymentResponse = await sdk.payment.createPayment({
+  orderId: order.id,
+  paymentMethodId: selectedMethod.id.toString(),
+  redirectUrl: 'https://yoursite.com/payment/return',
+  customer: {
+    firstName: 'John',
+    lastName: 'Doe',
+    email: 'customer@example.com',
+    phone: '+31612345678',
+  },
+  issuerId: '1234', // If required by payment method
+});
 
-    onUnmounted(() => {
-      if (unsubscribe) unsubscribe();
-    });
+// 7. Redirect to payment page
+window.location.href = paymentResponse.paymentUrl;
+```
 
-    const handleAddProduct = async () => {
-      await basketService.addProduct({
-        id: 'product-123',
-        name: 'My Product',
-        price: 29.99,
-        currency: Currency.EUR,
-        amount: 1,
-      });
-    };
+### Reactive UI Updates
+
+```typescript
+// Subscribe to basket changes
+const unsubscribeBasket = sdk.basket.subscribe(() => {
+  const order = sdk.basket.getCurrentOrder();
+  updateBasketIcon(order?.count || 0);
+  updateOrderSummary(order);
+});
 
-    return { order, handleAddProduct };
+// Subscribe to event changes
+const unsubscribeEvents = sdk.event.subscribe(() => {
+  const state = sdk.event.getState();
+  
+  if (state.processing) {
+    showLoadingSpinner();
+  } else if (state.error) {
+    showError(state.error);
+  } else {
+    displayEvents(state.events);
   }
-};
+});
+
+// Cleanup when component unmounts
+function cleanup() {
+  unsubscribeBasket();
+  unsubscribeEvents();
+}
+```
+
+---
+
+## TypeScript Support
+
+The SDK is written in TypeScript and exports all necessary types:
+
+```typescript
+import { 
+  TicketappSDK,
+  ProductInput,
+  PackageInput,
+  // ... other types
+} from '@ticketapp/sdk';
 ```
 
-## Usage in Vanilla JS
+However, if you prefer to avoid importing types, you can use `any`:
 
 ```typescript
-import { store, basketService, Currency } from '@your-scope/basket-manager';
+const productInput: any = {
+  id: 'product-id',
+  name: 'Ticket',
+  price: 50,
+  // ...
+};
+```
 
-// Subscribe to changes
-store.subscribe(() => {
-  const order = store.getState().basket.order;
-  console.log('Order updated:', order);
-  updateUI(order);
-});
-
-// Add product
-document.querySelector('#add-btn').addEventListener('click', async () => {
-  await basketService.addProduct({
-    id: 'product-123',
-    name: 'My Product',
-    price: 29.99,
-    currency: Currency.EUR,
-    amount: 1,
-  });
-});
-
-function updateUI(order) {
-  const orderElement = document.querySelector('#order-display');
-  if (order) {
-    orderElement.innerHTML = `
-      <p>Order ID: ${order.id}</p>
-      <p>Items: ${order.items.length}</p>
-    `;
+---
+
+## Error Handling
+
+All async methods can throw errors. Always wrap them in try-catch blocks:
+
+```typescript
+try {
+  await sdk.basket.addProduct(productInput);
+} catch (error) {
+  console.error('Failed to add product:', error.message);
+  
+  // Handle specific GraphQL errors
+  if (error.response?.errors) {
+    const graphQLError = error.response.errors[0];
+    console.error('GraphQL error:', graphQLError.message);
+    
+    // Check for specific error codes
+    if (graphQLError.extensions?.status === 'SOLD_OUT') {
+      alert('This product is sold out');
+    }
   }
 }
 ```
 
-## API Methods
+---
+
+## Session Management
+
+The SDK automatically manages sessions using `sessionStorage`:
+
+- Order ID is stored as `ORDER_ID_{shopSlug}`
+- Session persists across page reloads
+- Use `sdk.basket.clearOrderFromSession()` to clear
+
+---
+
+## Debug Mode
+
+Enable debug mode to see detailed logs:
+
+```typescript
+const sdk = new TicketappSDK({
+  organizationId: 'your-org-id',
+  shopId: 'your-shop-id',
+  shopSlug: 'your-shop-slug',
+  debug: true, // Enable logging
+});
+```
+
+Debug logs will appear in the browser console with prefixes like:
+- `[EventService]`
+- `[BasketService]`
+- `[PackageService]`
+- `[PaymentService]`
+
+---
+
+## Browser Support
 
-### `addProduct(input: ProductInput)`
-Add a product to the basket.
+The SDK works in all modern browsers that support:
+- ES6+
+- Fetch API
+- sessionStorage
+- Promise
 
-### `removeProduct(input: ProductInput)`
-Remove a product from the basket.
+---
 
-### `configurePackage(input: PackageInput)`
-Configure a package in the basket.
+## License
 
-### `configureDeliveryOption(input?: DeliveryInput)`
-Set or remove delivery option.
+MIT
 
-### `createCustomer(input: CreateCustomerInput)`
-Add customer information to the order.
+---
 
-### `cancelOrder()`
-Cancel the current order.
+## Support
 
-### `clearOrderFromSession()`
-Clear the order from session storage and state.
+For issues, questions, or feature requests, please contact support or open an issue on GitHub.