@slotchain/sdk 1.1.3 → 1.2.0

package/src/clients/customer-client.ts.bak

@@ -0,0 +1,165 @@
+import { AxiosInstance } from 'axios';
+import { ApiResponse, Customer, Booking } from '../types/api';
+
+export class CustomerClient {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * Get customer by ID
+   * GET /api/v1/customers/:id
+   * 
+   * @param id - Customer ID
+   * @returns Customer details
+   */
+  async getById(id: string): Promise<ApiResponse<Customer>> {
+    const response = await this.client.get<ApiResponse<Customer>>(
+      `/api/v1/customers/${id}`
+    );
+    return response.data;
+  }
+
+  /**
+   * Get customer by email
+   * GET /api/v1/customers?email=:email&tenant_id=:id
+   * 
+   * @param email - Customer email
+   * @param tenantId - Required tenant ID for scoping
+   * @returns Customer details
+   */
+  async getByEmail(email: string, tenantId: string): Promise<ApiResponse<Customer>> {
+    const response = await this.client.get<ApiResponse<Customer>>(
+      '/api/v1/customers',
+      { params: { email, tenant_id: tenantId } }
+    );
+    return response.data;
+  }
+
+  /**
+   * List customers with optional filters
+   * GET /api/v1/customers
+   * 
+   * @param params - Query parameters (tenant_id required, page, limit, search, is_guest)
+   * @returns Paginated list of customers
+   */
+  async list(params: {
+    tenant_id: string;
+    page?: number;
+    limit?: number;
+    search?: string;
+    is_guest?: boolean;
+  }): Promise<ApiResponse<Customer[]>> {
+    const response = await this.client.get<ApiResponse<Customer[]>>(
+      '/api/v1/customers',
+      { params }
+    );
+    return response.data;
+  }
+
+  /**
+   * Create a new customer
+   * POST /api/v1/customers
+   * 
+   * @param data - Customer creation data (tenant_id, name, email required)
+   * @returns Created customer
+   */
+  async create(data: Partial<Customer>): Promise<ApiResponse<Customer>> {
+    const response = await this.client.post<ApiResponse<Customer>>(
+      '/api/v1/customers',
+      data
+    );
+    return response.data;
+  }
+
+  /**
+   * Update customer by ID
+   * PUT /api/v1/customers/:id
+   * 
+   * @param id - Customer ID
+   * @param data - Customer update data
+   * @returns Updated customer
+   */
+  async update(id: string, data: Partial<Customer>): Promise<ApiResponse<Customer>> {
+    const response = await this.client.put<ApiResponse<Customer>>(
+      `/api/v1/customers/${id}`,
+      data
+    );
+    return response.data;
+  }
+
+  /**
+   * Delete customer by ID
+   * DELETE /api/v1/customers/:id
+   * 
+   * @param id - Customer ID
+   * @returns Empty response on success
+   */
+  async delete(id: string): Promise<ApiResponse<void>> {
+    const response = await this.client.delete<ApiResponse<void>>(
+      `/api/v1/customers/${id}`
+    );
+    return response.data;
+  }
+
+  /**
+   * Lookup customer by userId or tenantId
+   * GET /api/v1/customers/lookup
+   * 
+   * @param params - Query parameters (userId optional, tenantId required)
+   * @returns Customer or null
+   */
+  async lookup(params: {
+    userId?: string;
+    tenantId: string;
+  }): Promise<ApiResponse<Customer | null>> {
+    const response = await this.client.get<ApiResponse<Customer | null>>(
+      '/api/v1/customers/lookup',
+      { params: { userId: params.userId, tenantId: params.tenantId } }
+    );
+    return response.data;
+  }
+
+  /**
+   * Get autocomplete data from existing customers and bookings
+   * GET /api/v1/customers/autocomplete
+   * 
+   * @param tenantId - Tenant ID (required)
+   * @returns Autocomplete data
+   */
+  async autocomplete(tenantId: string): Promise<ApiResponse<any>> {
+    const response = await this.client.get<ApiResponse<any>>(
+      '/api/v1/customers/autocomplete',
+      { params: { tenantId } }
+    );
+    return response.data;
+  }
+
+  /**
+   * Get all bookings for a customer
+   * GET /api/v1/customers/bookings
+   * 
+   * @param params - Query parameters (email optional, userId optional, tenantId required)
+   * @returns Customer bookings data
+   */
+  async getBookings(params: {
+    email?: string;
+    userId?: string;
+    tenantId: string;
+  }): Promise<ApiResponse<{
+    customer: Customer | null;
+    bookings: Booking[];
+    groupedBySlot: Record<string, Booking[]>;
+    total: number;
+  }>> {
+    const response = await this.client.get<ApiResponse<{
+      customer: Customer | null;
+      bookings: Booking[];
+      groupedBySlot: Record<string, Booking[]>;
+      total: number;
+    }>>(
+      '/api/v1/customers/bookings',
+      { params }
+    );
+    return response.data;
+  }
+}
+

package/src/clients/document-client.ts

@@ -0,0 +1,148 @@
+import type { AxiosInstance } from 'axios';
+import type {
+  ApiResponse,
+  Artifact,
+  ArtifactWithUrl,
+  ListArtifactsOptions,
+  UploadArtifactOptions,
+  ArtifactEntityType,
+} from '../types/api';
+
+/**
+ * DocumentClient — manage file artifacts attached to Slotly entities.
+ *
+ * Artifacts are tenant-scoped files (CVs, invoices, images, etc.) linked
+ * to a customer, booking, slot, service, or tenant record.
+ *
+ * @example Upload a CV for a customer
+ * ```ts
+ * const artifact = await slotly.document.upload({
+ *   file: buffer,
+ *   filename: 'cv-2024.pdf',
+ *   related_entity_type: 'customer',
+ *   related_entity_id: customerId,
+ *   label: 'CV',
+ * });
+ * ```
+ *
+ * @example List all CVs for a customer
+ * ```ts
+ * const { data } = await slotly.document.listByEntity('customer', customerId, { signed: true });
+ * ```
+ */
+export class DocumentClient {
+  private readonly client: AxiosInstance;
+  private readonly base = '/api/v1/artifacts';
+
+  constructor(client: AxiosInstance) {
+    this.client = client;
+  }
+
+  /**
+   * Upload a file artifact.
+   * Sends as multipart/form-data.
+   */
+  async upload(options: UploadArtifactOptions): Promise<Artifact> {
+    const form = new FormData();
+
+    // Normalise file to Blob for FormData compatibility
+    let blob: Blob;
+    if (options.file instanceof Blob) {
+      blob = options.file;
+    } else {
+      blob = new Blob([options.file], { type: options.mime_type ?? 'application/octet-stream' });
+    }
+    form.append('file', blob, options.filename);
+    form.append('related_entity_type', options.related_entity_type);
+    form.append('related_entity_id', options.related_entity_id);
+    if (options.label) form.append('label', options.label);
+    if (options.mime_type) form.append('mime_type', options.mime_type);
+    if (options.metadata) form.append('metadata', JSON.stringify(options.metadata));
+
+    const response = await this.client.post<ApiResponse<Artifact>>(this.base, form, {
+      headers: { 'Content-Type': 'multipart/form-data' },
+    });
+    const { data } = response.data;
+    if (!data) throw new Error('No artifact returned from upload');
+    return data;
+  }
+
+  /**
+   * List artifacts for a specific entity.
+   * Pass `signed: true` to get download URLs in each result.
+   */
+  async listByEntity(
+    entityType: ArtifactEntityType,
+    entityId: string,
+    options?: Omit<ListArtifactsOptions, 'related_entity_type' | 'related_entity_id'>
+  ): Promise<ApiResponse<(Artifact | ArtifactWithUrl)[]>> {
+    const response = await this.client.get<ApiResponse<(Artifact | ArtifactWithUrl)[]>>(
+      this.base,
+      {
+        params: {
+          related_entity_type: entityType,
+          related_entity_id: entityId,
+          ...options,
+        },
+      }
+    );
+    return response.data;
+  }
+
+  /**
+   * List artifacts with full filter options.
+   */
+  async list(
+    options: ListArtifactsOptions
+  ): Promise<ApiResponse<(Artifact | ArtifactWithUrl)[]>> {
+    const response = await this.client.get<ApiResponse<(Artifact | ArtifactWithUrl)[]>>(
+      this.base,
+      { params: options }
+    );
+    return response.data;
+  }
+
+  /**
+   * Get a single artifact by ID.
+   */
+  async get(id: string, signed = false): Promise<Artifact | ArtifactWithUrl> {
+    const response = await this.client.get<ApiResponse<Artifact | ArtifactWithUrl>>(
+      `${this.base}/${id}`,
+      { params: signed ? { signed: true } : undefined }
+    );
+    const { data } = response.data;
+    if (!data) throw new Error(`Artifact ${id} not found`);
+    return data;
+  }
+
+  /**
+   * Get a signed download URL for an artifact.
+   * Returns the full ArtifactWithUrl including `signed_url` and `signed_url_expires_at`.
+   */
+  async getUrl(id: string): Promise<ArtifactWithUrl> {
+    return this.get(id, true) as Promise<ArtifactWithUrl>;
+  }
+
+  /**
+   * Delete an artifact and its stored file.
+   */
+  async delete(id: string): Promise<void> {
+    await this.client.delete(`${this.base}/${id}`);
+  }
+
+  /**
+   * Update artifact label or metadata.
+   */
+  async update(
+    id: string,
+    patch: { label?: string; metadata?: Record<string, unknown> }
+  ): Promise<Artifact> {
+    const response = await this.client.patch<ApiResponse<Artifact>>(
+      `${this.base}/${id}`,
+      patch
+    );
+    const { data } = response.data;
+    if (!data) throw new Error(`Artifact ${id} not found`);
+    return data;
+  }
+}

package/src/clients/service-client.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from 'axios';
-import { ApiResponse, Service, ServiceWithItems, Category } from '../types/api';
+import { ApiResponse, Service, ServiceWithItems, SlotServiceWithItems, Category } from '../types/api';
 
 export class ServiceClient {
   constructor(private client: AxiosInstance) {}
@@ -20,10 +20,95 @@ export class ServiceClient {
     return response.data;
   }
 
+  /**
+   * Get services for a tenant (full list with optional filters)
+   * GET /api/v1/services
+   * 
+   * @param options - Query options
+   * @param options.tenantId - Tenant ID (UUID) - required if tenantSlug not provided
+   * @param options.tenantSlug - Tenant slug - required if tenantId not provided
+   * @param options.slotId - Slot ID (DEPRECATED - accepted but ignored for API compatibility)
+   * @param options.isActive - Filter by active status
+   * @param options.includeItems - Include nested service items (default: false)
+   * @param options.page - Page number (default: 1)
+   * @param options.limit - Items per page (default: 20, max: 100)
+   * @returns Services with optional pagination metadata
+   */
+  async getServicesByTenant(options: {
+    tenantId?: string;
+    tenantSlug?: string;
+    slotId?: string; // DEPRECATED - accepted but ignored
+    isActive?: boolean;
+    includeItems?: boolean;
+    page?: number;
+    limit?: number;
+  }): Promise<ApiResponse<Service[] | ServiceWithItems[]>> {
+    // Validate that either tenantId or tenantSlug is provided
+    if (!options.tenantId && !options.tenantSlug) {
+      return {
+        success: false,
+        error: {
+          code: 'MISSING_TENANT_ID',
+          message: 'tenantId or tenantSlug is required',
+        },
+      };
+    }
+
+    // Build query parameters
+    const params: Record<string, any> = {};
+    
+    if (options.tenantId) {
+      params.tenant_id = options.tenantId;
+    }
+    if (options.tenantSlug) {
+      params.tenantSlug = options.tenantSlug;
+    }
+    if (options.slotId) {
+      // Include for API compatibility, even though it's ignored
+      params.slot_id = options.slotId;
+    }
+    if (options.isActive !== undefined) {
+      params.is_active = options.isActive;
+    }
+    if (options.includeItems) {
+      params.includeItems = true;
+    }
+    if (options.page !== undefined) {
+      params.page = options.page;
+    }
+    if (options.limit !== undefined) {
+      params.limit = Math.min(options.limit, 100); // Enforce max limit
+    }
+
+    const response = await this.client.get<ApiResponse<Service[] | ServiceWithItems[]>>(
+      '/api/v1/services',
+      { params }
+    );
+    return response.data;
+  }
+
+  /**
+   * Get services for a specific slot
+   * GET /api/v1/slots/:id/services
+   * 
+   * Note: Services are tenant-level entities. This endpoint returns all active services
+   * for the slot's tenant with items included. The response uses 'items' property (not 'serviceItems').
+   * 
+   * @param slotId - Slot ID (UUID)
+   * @returns Services with nested items (always includes items, only active services)
+   */
+  async getServicesBySlot(slotId: string): Promise<ApiResponse<SlotServiceWithItems[]>> {
+    const response = await this.client.get<ApiResponse<SlotServiceWithItems[]>>(
+      `/api/v1/slots/${slotId}/services`
+    );
+    return response.data;
+  }
+
   /**
    * List services by tenant slug
    * GET /api/v1/services?tenantSlug=:slug
    * 
+   * @deprecated Consider using getServicesByTenant() for better type safety and validation
    * @param slug - Tenant slug (or use tenant_id in list() method)
    * @param params - Optional parameters (includeItems, page, limit, is_active)
    * @returns List of services for the tenant
@@ -48,6 +133,7 @@ export class ServiceClient {
    * List services with optional filters
    * GET /api/v1/services
    * 
+   * @deprecated Consider using getServicesByTenant() for better type safety and validation
    * @param params - Query parameters (tenant_id, tenantSlug, slot_id, page, limit, is_active, includeItems)
    * @returns Paginated list of services
    */

package/src/clients/slot-client.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from 'axios';
-import { ApiResponse, Slot, ServiceWithItems, Tenant } from '../types/api';
+import { ApiResponse, Slot, SlotServiceWithItems, Tenant } from '../types/api';
 
 export class SlotClient {
   constructor(private client: AxiosInstance) {}
@@ -113,11 +113,14 @@ export class SlotClient {
    * Get all active services for a slot with their items
    * GET /api/v1/slots/:id/services
    * 
-   * @param id - Slot ID
-   * @returns Services with nested service items
+   * Note: Services are tenant-level entities. This endpoint returns all active services
+   * for the slot's tenant with items included. The response uses 'items' property (not 'serviceItems').
+   * 
+   * @param id - Slot ID (UUID)
+   * @returns Services with nested items (always includes items, only active services)
    */
-  async getServices(id: string): Promise<ApiResponse<ServiceWithItems[]>> {
-    const response = await this.client.get<ApiResponse<ServiceWithItems[]>>(
+  async getServices(id: string): Promise<ApiResponse<SlotServiceWithItems[]>> {
+    const response = await this.client.get<ApiResponse<SlotServiceWithItems[]>>(
       `/api/v1/slots/${id}/services`
     );
     return response.data;

package/src/index.ts

@@ -10,6 +10,7 @@ import { StudioClient } from './clients/studio-client';
 import { NotificationClient } from './clients/notification-client';
 import { DataQualityClient } from './clients/data-quality-client';
 import { OrganizationClient } from './clients/organization-client';
+import { DocumentClient } from './clients/document-client';
 import { setupRequestInterceptor, setupResponseInterceptor, setupErrorInterceptor } from './interceptors';
 import { setupRetryInterceptor } from './retry';
 import { SlotlyConfigurationError } from './errors';
@@ -26,10 +27,17 @@ export type {
   Service,
   ServiceItem,
   ServiceWithItems,
+  SlotServiceWithItems,
   ServiceItemWithService,
   Category,
   Slot,
   Customer,
+  CustomerIdentity,
+  CustomerWithIdentities,
+  NotificationPreferences,
+  CustomerWithBookings,
+  ResolveCustomerOptions,
+  FindOrCreateCustomerOptions,
   Flow,
   FlowStep,
   Studio,
@@ -38,6 +46,12 @@ export type {
   Organization,
   OrganizationFullConfig,
   GetOrganizationOptions,
+  Artifact,
+  ArtifactWithUrl,
+  ArtifactEntityType,
+  ArtifactMimeCategory,
+  ListArtifactsOptions,
+  UploadArtifactOptions,
 } from './types/api';
 
 // Re-export errors
@@ -104,6 +118,8 @@ export interface SlotlyApi {
   notification: NotificationClient;
   dataQuality: DataQualityClient;
   organization: OrganizationClient;
+  /** Upload and retrieve file artifacts (CVs, invoices, images) linked to any Slotly entity */
+  document: DocumentClient;
 }
 
 const defaultBaseURL = typeof process !== 'undefined' && process.env?.SLOTLY_API_URL 
@@ -297,6 +313,7 @@ export const useSlotly = (options: SlotlyClientOptions): SlotlyApi => {
     notification: new NotificationClient(client),
     dataQuality: new DataQualityClient(client),
     organization: new OrganizationClient(client),
+    document: new DocumentClient(client),
   };
 };