@debugged-development/ticketapp-sdk 1.0.9 → 1.0.10-dev.0

package/README.md

@@ -1,6 +1,6 @@
 # Ticketapp SDK
 
-A TypeScript SDK for integrating Ticketapp's event ticketing and package management system into your application.
+A TypeScript SDK for integrating Ticketapp's event ticketing, package, and category management system into your application.
 
 ## Installation
 
@@ -15,20 +15,34 @@ 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)
 });
 ```
 
+> Who is this for?
+> - Teams who want to show events, let visitors pick tickets, and pay online.
+> - You don’t need to be a developer to follow the examples below—each step is explained in plain English.
+>
+> Core concepts in 60 seconds:
+> - Organization: your brand or company in Ticketapp.
+> - Event: something you sell tickets for (e.g., Friday Night Show).
+> - Product: a sellable ticket or add-on (e.g., Regular Ticket, VIP, Door ticket).
+> - Basket: the visitor’s shopping cart (we keep it in the browser so it survives page reloads).
+> - Package: a bundle of tickets/events (e.g., Weekend Pass with several included events).
+> - Category: a label to group products or events (e.g., Music, Sports).
+> - Payment: the step where the visitor selects a method (iDEAL, card, etc.) and pays.
+
 ## Table of Contents
 
 - [Configuration](#configuration)
 - [Events](#events)
-- [Basket (Cart)](#basket-cart)
+- [Categories](#categories)
 - [Packages](#packages)
+- [Basket](#basket)
 - [Payment](#payment)
 - [Examples](#examples)
+- [Services Overview](#services-overview)
+- [FAQ and Troubleshooting](#faq-and-troubleshooting)
 
 ---
 
@@ -39,8 +53,6 @@ const sdk = new TicketappSDK({
 ```typescript
 const sdk = new TicketappSDK({
   organizationId: 'eed7fb11-f5c4-4467-8393-6da072b7f752',
-  shopId: '1fbdf73d-6ee6-438b-b8e5-a76907a6d76b',
-  shopSlug: 'hvrmq',
   debug: true,
 });
 ```
@@ -50,12 +62,8 @@ const sdk = new TicketappSDK({
 ```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
+  // Optionally add shopId, shopSlug, filteredLocationIds, filteredHostingIds, enableDoorTickets, etc.
 });
 ```
 
@@ -63,68 +71,90 @@ const sdk = new TicketappSDK({
 
 ## Events
 
-### Fetching Events
+// In plain English: Use EventService to show a list of events, open one event’s details, and load its ticket types (products). You can filter by date or status, and sort or paginate results.
+
+### EventService overview
+
+Methods:
+- fetchEvents(options?): Promise<[Event[], number]>
+  - options.statuses?: EventStatus[]
+  - options.hostingIds?: string[]
+  - options.dateRange?: { from: DateTime; till: DateTime }
+  - options.page?: { index: number; size: number }
+  - options.sorts?: { field: string; order: SortOrder }[]
+- fetchEvent(eventId: string): Promise<Event | undefined>
+- fetchProducts(eventId: string, productTypes?: ProductType[], promoCode?: string): Promise<Product[] | undefined>
 
-Load all available events for your organization:
+Types available from the SDK:
+- EventStatus: ACTIVE | INACTIVE | PAUSED | SOLD_OUT
+- ProductType: TICKET | DOOR | ADDON | ...
+- SortOrder: ASC | DESC
+
+You can import these enums directly:
 
 ```typescript
-await sdk.event.fetchEvents();
+import { EventStatus, ProductType, SortOrder } from '@ticketapp/sdk';
+import { DateTime } from 'luxon';
 ```
 
-### Subscribing to Event Updates
+### Fetching Events (with options)
 
-Get real-time updates when events change:
+Load events with optional filters, pagination, and sorting. Returns a tuple: [events, totalCount].
 
 ```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);
+import { DateTime } from 'luxon';
+import { EventStatus, SortOrder } from '@ticketapp/sdk';
+
+// 1) Ask the server: "give me events that are ACTIVE, starting in the next 3 months"
+const [events, total] = await sdk.event.fetchEvents({
+  statuses: [EventStatus.Active],      // Only active events
+  hostingIds: undefined,               // Or filter by specific locations/hosts
+  dateRange: {                         // Time window
+    from: DateTime.local(),
+    till: DateTime.local().plus({ months: 3 })
+  },
+  page: { index: 0, size: 20 },        // First page, 20 items
+  sorts: [{ field: 'startAt', order: SortOrder.Asc }], // Soonest first
 });
 
-// Later, when you want to stop listening:
-unsubscribe();
+// 2) You can now render these events in a grid or list
+console.log(`Found ${total} events`, events.map(e => e.name));
 ```
 
-### Getting Current Event State
+### Fetching a Single Event
 
 ```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
+// When a visitor clicks an event, load its extra details (like sales times)
+const event = await sdk.event.fetchEvent('event-id');
+if (!event) {
+  // No event found (maybe it was removed)
 }
 ```
 
 ### Fetching Products for an Event
 
 ```typescript
-// Fetch all ticket types
-await sdk.event.fetchProductsForEvent(
-  'event-id',
-  ['TICKET', 'DOOR', 'ADDON']
-);
+import { ProductType } from '@ticketapp/sdk';
 
-// Fetch only regular tickets
-await sdk.event.fetchProductsForEvent(
+// Load all ticket types for a chosen event
+const products = await sdk.event.fetchProducts(
   'event-id',
-  ['TICKET']
+  [ProductType.Ticket, ProductType.Door, ProductType.Addon], // Which types to include
+  'PROMO2024'                                                // Optional discount code
 );
 
-// Fetch with promo code
-await sdk.event.fetchProductsForEvent(
-  'event-id',
-  ['TICKET'],
-  'PROMO2024'
-);
+// Show each product with price so visitors can pick one
+products?.forEach(p => console.log(p.name, p.price));
 ```
 
-### Event Object Structure
+### Event object shapes
+
+There are two event shapes depending on the call you use.
+
+- Overview events (from `fetchEvents`) are lightweight for listing
+- Detailed event (from `fetchEvent`) contains full metadata
+
+Overview (fetchEvents):
 
 ```typescript
 {
@@ -133,153 +163,302 @@ await sdk.event.fetchProductsForEvent(
   icon: string | null,
   banner: string | null,
   description: string | null,
-  startAt: DateTime,        // Luxon DateTime object
+  addonDescription?: string | null,
+  startAt: DateTime,
   endAt: DateTime,
   timezone: string,
-  location: {
+  slug: string,
+  status: string,
+  location?: {
     id: string,
     name: string,
     address: string | null
   },
-  products: Product[]       // Available after fetchProductsForEvent
+  infoDescription?: string | null
 }
 ```
 
----
-
-## Basket (Cart)
+Detail (fetchEvent):
 
-The basket manages the user's shopping cart and order.
+```typescript
+{
+  id: string,
+  name: string,
+  icon: string | null,
+  banner: string | null,
+  description: string | null,
+  addonDescription?: string | null,
+  startAt: DateTime,
+  endAt: DateTime,
+  timezone: string,
+  startSalesAt: string | null,
+  endSalesAt: string | null,
+  slug: string,
+  facebookPixelId: string | null,
+  status: string,
+  location?: {
+    id: string,
+    name: string,
+    address: string | null
+  },
+  infoDescription?: string | null
+}
+```
 
-### Adding a Product
+### Product Object Structure (from fetchProducts)
 
 ```typescript
-await sdk.basket.addProduct({
-  id: 'product-id',
-  name: 'VIP Ticket',
-  price: 50,
-  serviceFee: 5,
-  amount: 2,
-  currency: 'EUR',
-});
+{
+  id: string,
+  name: string,
+  category?: {
+    id: string,
+    name: string,
+    description?: string
+  },
+  currency: 'EUR' | 'USD' | string, // see Currency in types
+  depositPrice?: number,
+  description?: string,
+  discountPrice?: number,
+  startSalesAt?: string,
+  endSalesAt?: string,
+  icon?: string,
+  maxAmountOfAddons?: number,
+  minAmountOfAddons?: number,
+  maxAmountPerOrder?: number,
+  price?: number,
+  serviceFee?: number,
+  showEndSalesAtTag: boolean,
+  status: ProductStatus,
+  type: ProductType
+}
 ```
 
-### Adding a Product with Seat Assignment
+---
+
+## Categories
+
+// In plain English: Categories are simple labels you can show to help people browse. You can list them or open one category by its id.
+
+### CategoryService overview
+
+Methods:
+- getCategories(): Promise<Category[]>
+- getCategory(categoryId: string): Promise<Category | null>
+
+Types available from the SDK:
+- Category
+
+You can import the Category type directly:
 
 ```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'
-  }
-});
+import { Category } from '@ticketapp/sdk';
 ```
 
-### Removing a Product
+### Fetching Categories
+
+Load all available categories for your organization:
 
 ```typescript
-await sdk.basket.removeProduct({
-  id: 'product-id',
-  name: 'VIP Ticket',
-  currency: 'EUR',
-  amount: 1,
-});
+const categories: Category[] = await sdk.category.getCategories();
+console.log('Categories:', categories.map(c => c.name));
 ```
 
-### Adding Customer Information
+### Fetching a Single Category by ID
 
 ```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' }
-  ]
-});
+const category = await sdk.category.getCategory('category-id');
+if (category) {
+  console.log('Category:', category.name);
+} else {
+  console.log('Category not found');
+}
 ```
 
-### Getting Current Order
+### Category Object Structure
 
 ```typescript
-const order = sdk.basket.getCurrentOrder();
-
-// order structure:
 {
   id: string,
-  currency: string,
-  items: OrderItem[],
-  customer: Customer,
-  count: number,        // Total number of items
-  expiredAt: string
+  name: string,
+  icon?: string | null
 }
 ```
 
-### Subscribing to Basket Updates
+---
+
+## Packages
+
+// In plain English: Packages are bundles (like a Weekend Pass) that include multiple events. You can show all packages, open one, and list the events inside it.
+
+### PackageService overview
+
+Methods:
+- getPackages(options?: { page?: { index?: number; size?: number }; tab?: PackageTabType; statuses?: PackageStatus[] }): Promise<{ count: number; data: any[] } | null>
+- getPackage(packageId: string): Promise<any | null>
+- getPackageItems(packageId: string, types?: PackageItemType[]): Promise<{ count: number; data: any[] } | null>
+
+Types available from the SDK:
+- PackageItemType: REGULAR | ADDITIONAL_EVENT
+- PackageStatus: ACTIVE | CONCEPT | PAUSED | SOLD_OUT
+- PackageTabType: ACTIVE | INACTIVE
+
+You can import these enums directly:
 
 ```typescript
-const unsubscribe = sdk.basket.subscribe(() => {
-  const order = sdk.basket.getCurrentOrder();
-  console.log('Order updated:', order);
-});
+import { PackageItemType, PackageStatus, PackageTabType } from '@ticketapp/sdk';
+```
 
-// Cleanup
-unsubscribe();
+### Fetching Packages (with options)
+
+```typescript
+// Example: show available bundles on your homepage
+const result = await sdk.package.getPackages();
+if (result) {
+  console.log('We have these bundles:', result.data.map(p => p.name));
+}
 ```
 
-### Canceling an Order
+### Fetch a Single Package by ID
 
 ```typescript
-await sdk.basket.cancelOrder();
+const pkg = await sdk.package.getPackage('package-id');
+console.log('Package:', pkg);
 ```
 
-### Clearing Session
+### Fetch Package Items (by types)
 
 ```typescript
-sdk.basket.clearOrderFromSession();
+// Default: REGULAR and ADDITIONAL_EVENT
+const itemsDefault = await sdk.package.getPackageItems('package-id');
+console.log('Items:', itemsDefault?.data);
+
+// Explicit types
+const items = await sdk.package.getPackageItems('package-id', [
+  PackageItemType.Regular,
+  PackageItemType.AdditionalEvent,
+]);
+console.log('Filtered items:', items?.data);
 ```
 
----
+### 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
+}
+```
 
-## Packages
 
-Packages are bundled event tickets (e.g., weekend passes, season tickets).
 
-### Fetching Packages
+## Basket
+
+The basket manages the user's shopping cart and order. It maintains internal state and restores active orders from session automatically.
+
+// In plain English: Think of the basket like a shopping cart. When someone clicks “Add to cart” we reserve that ticket for a short time (so nobody else can grab it). If they refresh the page, we restore the cart from the browser.
+
+### BasketService overview
+
+Methods:
+- subscribe(listener: () => void): () => void
+- getCurrentOrder(): { id: string; currency: string; items: OrderItem[]; count: number; expiredAt?: DateTime | null } | null
+- getSelectedPackageEvent(): string[]
+- addProduct(input: ProductInput): Promise<void>
+- removeProduct(input: ProductInput): Promise<void>
+- configurePackage(input: ConfigurePackageInput): Promise<{ error: unknown } | null>
+- configureDelivery(input?: ConfigureDeliveryInput): Promise<void>
+- configureCustomer(input: ConfigureCustomerInput): Promise<void>
+- reserveAdditionalPackageItem(input: ReserveAdditionalPackageItemInput): Promise<{ error: unknown } | null>
+- cancelOrder(): Promise<void>
+- clearOrderFromSession(): void
+
+Types available from the SDK:
+- ProductInput, ConfigurePackageInput, ConfigureDeliveryInput, ConfigureCustomerInput, ReserveAdditionalPackageItemInput, OrderItem
+
+You can import these types directly:
 
 ```typescript
-const result = await sdk.package.getPackages();
+import {
+  ProductInput,
+  ConfigurePackageInput,
+  ConfigureDeliveryInput,
+  ConfigureCustomerInput,
+  ReserveAdditionalPackageItemInput,
+} from '@ticketapp/sdk';
+```
 
-console.log('Total packages:', result.count);
-console.log('Packages:', result.data);
+### Subscribing to Basket Updates
+
+```typescript
+// This runs every time the basket changes (e.g., added/removed a ticket)
+const unsubscribe = sdk.basket.subscribe(() => {
+  const order = sdk.basket.getCurrentOrder();
+  console.log('Order updated:', order);
+});
+
+// Later: stop listening
+unsubscribe();
 ```
 
-### Fetching Package Items
+### Getting Current Order
+
+```typescript
+// Ask: what’s currently in the cart?
+const order = sdk.basket.getCurrentOrder();
+if (order) {
+  console.log('Total items:', order.count);
+  console.log('Expires at:', order.expiredAt?.toISO()); // Tickets are held for a limited time
+}
+```
 
-Get the individual events/items that make up a package:
+### Add and Remove Products
 
 ```typescript
-const result = await sdk.package.getPackageItems(
-  'package-id',
-  ['REGULAR', 'ADDITIONAL_EVENT']
-);
+// Add a regular ticket
+await sdk.basket.addProduct({
+  id: 'product-id',        // Ticket/product id from fetchProducts
+  name: 'VIP Ticket',
+  price: 50,
+  serviceFee: 5,
+  amount: 2,               // How many
+  currency: 'EUR',
+});
+
+// Add a seated ticket (we also pass a seat)
+await sdk.basket.addProduct({
+  id: 'seated-ticket-id',
+  name: 'Seated Ticket',
+  price: 75,
+  serviceFee: 5,
+  amount: 1,
+  currency: 'EUR',
+  seat: { id: 'seat-a1', label: 'A1', holdToken: 'hold-abc' },
+});
 
-console.log('Package items:', result.data);
+// Remove one from the basket
+await sdk.basket.removeProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  currency: 'EUR',
+  amount: 1,
+});
 ```
 
-### Configuring and Adding a Package to Order
+Notes:
+- When you add the first item, we create an order and remember it in the browser.
+- If you remove everything, we automatically cancel the order on the server and clear the browser.
+- If you see SOLD_OUT or RATE_LIMIT errors, it means the product is gone or you clicked too fast—try again.
+
+### Configure a Package
 
 ```typescript
 await sdk.basket.configurePackage({
@@ -291,60 +470,77 @@ await sdk.basket.configurePackage({
   serviceFee: 20,
   amount: 1,              // Number of persons
   items: [
-    {
-      packageItemId: 'item-1-id',
-      eventId: 'event-1-id',
-    },
-    {
-      packageItemId: 'item-2-id',
-      eventId: 'event-2-id',
-    }
-  ]
+    { packageItemId: 'item-1-id', eventId: 'event-1-id' },
+    { packageItemId: 'item-2-id', eventId: 'event-2-id' },
+  ],
+});
+```
+
+- Returns null on success; returns an error object if no items are reserved.
+
+### Reserve Additional Package Items
+
+```typescript
+await sdk.basket.reserveAdditionalPackageItem({
+  packageId: 'package-id',
+  packageItemId: 'package-item-id',
+  eventId: 'event-id',
+  amount: 1,
+  currency: 'EUR',
 });
 ```
 
-### Adding Additional Package Items
+- Use this to add additional events to an existing package reservation.
 
-Add extra events to an existing package order:
+### Configure Delivery and Customer
 
 ```typescript
-const sessionId = sessionStorage.getItem('ORDER_ID_hvrmq');
+// Delivery: use this to show “e-ticket” or “pickup” in your order summary
+sdk.basket.configureDelivery({ id: 'delivery-id', name: 'E-ticket', serviceFee: 0, currency: 'EUR' });
 
-await sdk.package.setAdditionalPackageItem(
-  sessionId,
-  'package-item-id',
-  'event-id',
-  1 // amount
-);
+// Customer: minimum is email, but more fields help customer support
+await sdk.basket.configureCustomer({
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,
+});
 ```
 
-### Package Object Structure
+### Get Selected Package Event IDs
 
 ```typescript
-{
-  id: string,
-  name: string,
-  shortDescription: string,
-  status: 'ACTIVE' | 'PAUSED' | 'SOLD_OUT' | 'CONCEPT',
-  prices: {
-    price: number,
-    discount: number | null
-  },
-  amountOfEvents: number,
-  maxAmountOfPersonsPerOrder: number | null
-}
+const selectedEventIds = sdk.basket.getSelectedPackageEvent();
+// e.g., ['event-1', 'event-2']
+```
+
+### Cancel and Clear Order
+
+```typescript
+// Cancel current order on server (if ORDER_ID exists) and clear local session
+await sdk.basket.cancelOrder();
+
+// Clear local basket state and session key without contacting the server
+sdk.basket.clearOrderFromSession();
 ```
 
+Behavior notes:
+- On page load, we try to restore a previous order (if it still exists) so your visitors don’t lose their cart.
+- Each reserved ticket has an expiration. We track the earliest one and show it as the order’s expiration time.
+- You can “listen” for changes with subscribe() to keep your UI in sync (e.g., update the cart icon).
+
 ---
 
 ## Payment
 
-### Getting Payment Methods
+// In plain English: First ask “what payment methods are available for this order?”, then create the payment and send the visitor to the checkout page.
+
+### Getting Payment Details
 
-Fetch available payment methods for an order:
+Fetch available payment methods and details for an order:
 
 ```typescript
-const paymentDetails = await sdk.payment.getPaymentMethods({
+const paymentDetails = await sdk.payment.getPaymentDetails({
   orderId: 'order-id',
   orderItemId: 'item-id',      // Optional
   amountOfTickets: 2,          // Optional
@@ -354,9 +550,10 @@ const paymentDetails = await sdk.payment.getPaymentMethods({
 // paymentDetails structure:
 {
   transactionPrice: number,
-  baseTransactionFee: number | null,
-  additionalTransactionFee: number | null,
-  methods: PaymentMethod[]
+  transactionDiscount?: number | null,
+  transactionFee?: number | null,
+  paymentSpesificTransactionFee?: number | null,
+  methods?: PaymentMethod[] | null
 }
 ```
 
@@ -379,202 +576,261 @@ const paymentDetails = await sdk.payment.getPaymentMethods({
 }
 ```
 
-### Calculating Payment Fees
-
-```typescript
-const paymentMethod = {
-  id: 1,
-  name: 'iDEAL',
-  image: 'https://...',
-  fee: { type: 'FIXED', value: 0.29 }
-};
-
-// 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
+// 1) Ask for details and methods
+const details = await sdk.payment.getPaymentDetails({ orderId: 'order-id' });
+const method = details.methods?.[0]; // e.g., iDEAL, Credit Card
+
+// 2) Start the payment. The server gives back a URL.
 const response = await sdk.payment.createPayment({
   orderId: 'order-id',
-  paymentMethodId: '1',
+  paymentMethodId: String(method?.id),
   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
+  customer: { firstName: 'John', lastName: 'Doe', email: 'john@example.com' },
 });
 
-// Open payment URL
-window.open(response.paymentUrl, '_blank');
+// 3) Send the visitor to the payment page
+window.location.href = response.paymentUrl;
 ```
 
 ---
 
 ## Examples
 
-### Complete Event Browsing Flow
+// End-to-end example: Browse → Pick ticket → Pay
 
 ```typescript
-import { TicketappSDK } from '@ticketapp/sdk';
+import { TicketappSDK, ProductType, SortOrder, EventStatus } from '@ticketapp/sdk';
+import { DateTime } from 'luxon';
 
-const sdk = new TicketappSDK({
-  organizationId: 'your-org-id',
-  shopId: 'your-shop-id',
-  shopSlug: 'your-shop-slug',
-});
+// Create the SDK once
+const sdk = new TicketappSDK({ organizationId: 'your-org-id' });
 
-// 1. Fetch and display events
-await sdk.event.fetchEvents();
-const { events } = sdk.event.getState();
+// 1) List upcoming events for the next month
+const [events] = await sdk.event.fetchEvents({
+  statuses: [EventStatus.Active],
+  dateRange: { from: DateTime.local(), till: DateTime.local().plus({ months: 1 }) },
+  sorts: [{ field: 'startAt', order: SortOrder.Asc }]
+});
 
-// 2. Load products for selected event
-await sdk.event.fetchProductsForEvent(events[0].id, ['TICKET']);
+// 2) Let the visitor pick an event, then load its tickets
+const products = await sdk.event.fetchProducts(events[0].id, [ProductType.Ticket]);
 
-// 3. Add product to basket
+// 3) Add the first ticket to the 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,
+  id: products![0].id,
+  name: products![0].name,
+  price: products![0].price!,
+  serviceFee: products![0].serviceFee ?? 0,
   amount: 1,
   currency: 'EUR',
 });
 
-// 4. Check basket
-const order = sdk.basket.getCurrentOrder();
-console.log('Items in basket:', order.count);
+// 4) Ask for payment methods and create a payment
+const order = sdk.basket.getCurrentOrder()!;
+const details = await sdk.payment.getPaymentDetails({ orderId: order.id });
+const method = details.methods?.[0];
+const payment = await sdk.payment.createPayment({
+  orderId: order.id,
+  paymentMethodId: String(method?.id),
+  redirectUrl: 'https://yoursite.com/payment/return',
+});
+
+// 5) Redirect the visitor to pay
+window.location.href = payment.paymentUrl;
 ```
 
-### Complete Package Purchase Flow
+---
 
-```typescript
-// 1. Fetch available packages
-const packagesResult = await sdk.package.getPackages();
-const selectedPackage = packagesResult.data[0];
+## Services Overview
 
-// 2. Get package items
-const itemsResult = await sdk.package.getPackageItems(
-  selectedPackage.id,
-  ['REGULAR']
-);
+Below are the available services with their methods, options, and usage examples.
 
-// 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,
+## EventService
+
+Methods:
+- fetchEvents(options?): Promise<[Event[], number]>
+  - options.statuses?: EventStatus[]
+  - options.hostingIds?: string[]
+  - options.dateRange?: { from: DateTime; till: DateTime }
+  - options.page?: { index: number; size: number }
+  - options.sorts?: { field: string; order: SortOrder }[]
+- fetchEvent(eventId: string): Promise<Event | undefined>
+- fetchProducts(eventId: string, productTypes?: ProductType[], promoCode?: string): Promise<Product[] | undefined>
+
+Examples:
+```typescript
+import { DateTime } from 'luxon';
+
+// Fetch events with filters and pagination
+const [events, total] = await sdk.event.fetchEvents({
+  statuses: ['ACTIVE'],
+  hostingIds: ['host-1'],
+  dateRange: { from: DateTime.local(), till: DateTime.local().plus({ weeks: 8 }) },
+  page: { index: 0, size: 20 },
+  sorts: [{ field: 'startAt', order: 'ASC' }],
 });
+
+// Fetch a single event
+const event = await sdk.event.fetchEvent('event-id');
+
+// Fetch products for an event
+const products = await sdk.event.fetchProducts('event-id', ['TICKET', 'DOOR'], 'PROMO2024');
 ```
 
-### Complete Payment Flow
+---
+
+## CategoryService
+
+Methods:
+- getCategories(): Promise<Category[]>
+- getCategory(categoryId: string): Promise<Category | null>
 
+Examples:
 ```typescript
-// 1. Get current order
-const order = sdk.basket.getCurrentOrder();
+// Fetch all categories
+const categories = await sdk.category.getCategories();
 
-// 2. Fetch payment methods
-const paymentDetails = await sdk.payment.getPaymentMethods({
-  orderId: order.id,
-});
+// Fetch a single category
+const category = await sdk.category.getCategory('category-id');
+```
+
+---
 
-// 3. User selects payment method
-const selectedMethod = paymentDetails.methods[0];
+## BasketService
 
-// 4. Calculate total with fees
-const total = sdk.payment.calculateTotalWithFee(
-  paymentDetails.transactionPrice,
-  selectedMethod
-);
+Methods:
+- subscribe(listener: () => void): () => void
+- getCurrentOrder(): { id: string; currency: string; items: OrderItem[]; count: number; expiredAt?: DateTime | null } | null
+- getSelectedPackageEvent(): string[]
+- addProduct(input: ProductInput): Promise<void>
+- removeProduct(input: ProductInput): Promise<void>
+- configurePackage(input: ConfigurePackageInput): Promise<{ error: unknown } | null>
+- configureDelivery(input?: ConfigureDeliveryInput): Promise<void>
+- configureCustomer(input: ConfigureCustomerInput): Promise<void>
+- reserveAdditionalPackageItem(input: ReserveAdditionalPackageItemInput): Promise<{ error: unknown } | null>
+- cancelOrder(): Promise<void>
+- clearOrderFromSession(): void
 
-// 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' }
-  ]
+Examples:
+```typescript
+// Subscribe to basket changes
+const unsubscribe = sdk.basket.subscribe(() => {
+  const order = sdk.basket.getCurrentOrder();
+  console.log('Order updated:', 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
+// Add a product
+await sdk.basket.addProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  price: 50,
+  serviceFee: 5,
+  amount: 2,
+  currency: 'EUR',
 });
 
-// 7. Redirect to payment page
-window.location.href = paymentResponse.paymentUrl;
+// Remove a product
+await sdk.basket.removeProduct({
+  id: 'product-id',
+  name: 'VIP Ticket',
+  currency: 'EUR',
+  amount: 1,
+});
+
+// Configure a package
+await sdk.basket.configurePackage({
+  id: 'package-id',
+  name: 'Weekend Pass',
+  currency: 'EUR',
+  price: 200,
+  depositPrice: 200,
+  serviceFee: 20,
+  amount: 1,
+  items: [
+    { packageItemId: 'item-1', eventId: 'event-1' },
+    { packageItemId: 'item-2', eventId: 'event-2' },
+  ],
+});
+
+// Set delivery option
+await sdk.basket.configureDelivery({ id: 'delivery-id', name: 'E-ticket', serviceFee: 0, currency: 'EUR' });
+
+// Set customer information
+await sdk.basket.configureCustomer({ email: 'customer@example.com', firstName: 'John', lastName: 'Doe' });
+
+// Cancel order
+await sdk.basket.cancelOrder();
+
+// Clear session
+sdk.basket.clearOrderFromSession();
 ```
 
-### Reactive UI Updates
+---
+
+## PackageService
 
+Methods:
+- getPackages(options?: { page?: { index?: number; size?: number }; tab?: PackageTabType; statuses?: PackageStatus[] }): Promise<{ count: number; data: any[] } | null>
+- getPackage(packageId: string): Promise<any | null>
+- getPackageItems(packageId: string, types?: PackageItemType[]): Promise<{ count: number; data: any[] } | null>
+
+Examples:
 ```typescript
-// Subscribe to basket changes
-const unsubscribeBasket = sdk.basket.subscribe(() => {
-  const order = sdk.basket.getCurrentOrder();
-  updateBasketIcon(order?.count || 0);
-  updateOrderSummary(order);
+// Basic
+const result = await sdk.package.getPackages();
+console.log('Total packages:', result?.count);
+console.log('Packages:', result?.data);
+
+// With options (pagination, tab, statuses)
+const paged = await sdk.package.getPackages({
+  page: { index: 0, size: 20 },
+  tab: PackageTabType.Active,
+  statuses: [PackageStatus.Active, PackageStatus.Paused],
 });
+console.log('Paged packages:', paged?.data);
 
-// 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);
-  }
-});
+// Fetch a single package
+const pkg = await sdk.package.getPackage('package-id');
+console.log('Package:', pkg);
 
-// Cleanup when component unmounts
-function cleanup() {
-  unsubscribeBasket();
-  unsubscribeEvents();
-}
+// Fetch package items
+const itemsDefault = await sdk.package.getPackageItems('package-id');
+console.log('Items:', itemsDefault?.data);
+
+const items = await sdk.package.getPackageItems('package-id', [
+  PackageItemType.Regular,
+  PackageItemType.AdditionalEvent,
+]);
+console.log('Filtered items:', items?.data);
+```
+
+---
+
+## PaymentService
+
+Methods:
+- getPaymentDetails(options: { orderId: string; orderItemId?: string; amountOfTickets?: number; paymentMethodId?: string }): Promise<PaymentDetails>
+- createPayment(input: CreatePaymentInput): Promise<{ paymentUrl: string }>
+
+Examples:
+```typescript
+// Fetch payment details
+const details = await sdk.payment.getPaymentDetails({ orderId: 'order-id' });
+console.log(details.methods);
+
+// Create a payment
+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' },
+});
+window.location.href = response.paymentUrl;
 ```
 
 ---
@@ -587,7 +843,7 @@ The SDK is written in TypeScript and exports all necessary types:
 import { 
   TicketappSDK,
   ProductInput,
-  PackageInput,
+  ConfigurePackageInput,
   // ... other types
 } from '@ticketapp/sdk';
 ```
@@ -634,49 +890,74 @@ try {
 
 The SDK automatically manages sessions using `sessionStorage`:
 
-- Order ID is stored as `ORDER_ID_{shopSlug}`
+- Order ID is stored as `ORDER_ID`
 - Session persists across page reloads
 - Use `sdk.basket.clearOrderFromSession()` to clear
 
 ---
 
-## Debug Mode
+## Tracker (Attribution)
 
-Enable debug mode to see detailed logs:
+Some marketing tools add a tracker id (for example, when a visitor arrives from a campaign). The SDK helps you keep this id during the visitor’s journey so conversions can be attributed.
+
+How it works:
+- The SDK looks for a tracker id in three places (in this order):
+  1) Explicitly passed in the SDK config as `trackerId`
+  2) The page URL as `?trackerId=abc123`
+  3) The browser session storage under `TIC_TRACKER_ID`
+- When found via config or URL, the SDK stores it in `sessionStorage` so it persists across page reloads.
+- The tracker id is automatically sent with Event- and Basket-related calls to the backend when supported, so your analytics remains consistent.
+
+Typical ways to use it:
 
 ```typescript
+// A) Let campaigns append ?trackerId=abc123 to your landing page URL
+//    The SDK will pick it up automatically and persist it.
+
+// B) Pass it explicitly when creating the SDK (overrides URL/session for the first load)
 const sdk = new TicketappSDK({
-  organizationId: 'your-org-id',
-  shopId: 'your-shop-id',
-  shopSlug: 'your-shop-slug',
-  debug: true, // Enable logging
+  organizationId: 'your-org',
+  trackerId: 'newsletter-jan',
 });
+
+// C) Read the stored value later if you need it (optional)
+const stored = sessionStorage.getItem('TIC_TRACKER_ID');
+console.log('trackerId:', stored);
 ```
 
-Debug logs will appear in the browser console with prefixes like:
-- `[EventService]`
-- `[BasketService]`
-- `[PackageService]`
-- `[PaymentService]`
+Notes:
+- If you don’t use trackers, you can ignore this section—everything works without it.
+- If your links already include `?trackerId=...`, no extra setup is needed.
+- For best results, use simple, URL-safe tracker ids (letters, numbers, dashes/underscores).
 
 ---
 
-## Browser Support
+## Debug Mode
 
-The SDK works in all modern browsers that support:
-- ES6+
-- Fetch API
-- sessionStorage
-- Promise
+Enable debug mode to see detailed logs:
 
----
+```typescript
+const sdk = new TicketappSDK({
+  organizationId: 'your-org',
+  debug: true, // Enable debug logs
+});
+```
 
-## License
+- Logs appear in the browser console.
+- Includes request/response details for SDK methods.
+- Great for troubleshooting issues.
 
-MIT
+Remember to disable or remove debug mode in production to avoid exposing sensitive data in logs.
 
 ---
 
-## Support
+## FAQ and Troubleshooting
 
-For issues, questions, or feature requests, please contact support or open an issue on GitHub.
+- I reloaded the page and my cart is gone.
+  - The basket only restores an order if it still exists on the server and contains valid items. If all items expired or were removed, we clear the session.
+- I see “SOLD_OUT” when adding a ticket.
+  - Someone else reserved the last ticket just before you. Try again or pick another product.
+- Prices look different after some time.
+  - A promo code may have changed the price or the event’s prices were updated. Refresh products using `sdk.event.fetchProducts(eventId)`.
+- My payment didn’t start.
+  - Make sure you picked a payment method from `getPaymentDetails()`. Some methods (like iDEAL) require an issuer/bank id.