@slotchain/sdk 1.1.3 → 1.2.0

package/dist/index.d.mts

@@ -57,20 +57,32 @@ interface TenantBranding {
  */
 interface ServiceItem {
     id: string;
-    serviceId: string;
+    service_id: string;
     name: string;
     description?: string;
     price?: number;
     duration?: number;
-    available?: boolean;
+    is_available?: boolean;
+    sort_order?: number;
+    created_at: string;
+    updated_at: string;
 }
 /**
- * Enhanced Service type with nested service items
+ * Enhanced Service type with nested service items (for tenant endpoint)
+ * Uses 'serviceItems' property name
  */
 interface ServiceWithItems extends Service {
     /** Array of service items nested within this service (optional, may be empty array) */
     serviceItems?: ServiceItem[];
 }
+/**
+ * Service with items for slot endpoint
+ * Uses 'items' property name (different from tenant endpoint)
+ */
+interface SlotServiceWithItems extends Service {
+    /** Array of service items nested within this service (always included for slot endpoint) */
+    items: ServiceItem[];
+}
 /**
  * Service item with parent service reference
  */
@@ -137,11 +149,16 @@ interface ListBookingsOptions {
 }
 interface Service {
     id: string;
-    tenantId: string;
+    tenant_id: string;
+    slot_id?: string;
     name: string;
     description?: string;
+    category?: string;
+    is_active?: boolean;
     duration?: number;
     price?: number;
+    created_at: string;
+    updated_at: string;
 }
 interface Slot {
     id: string;
@@ -153,12 +170,93 @@ interface Slot {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Customer record — matches the `customers` table.
+ */
 interface Customer {
     id: string;
+    tenant_id: string;
+    customer_type: 'individual' | 'organization';
+    name: string;
+    email: string;
+    phone?: string;
+    address?: string;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    is_guest?: boolean;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * A row in `customer_users` — links an IDP user (Clerk userId, Auth0 sub, etc.) to a Customer.
+ */
+interface CustomerIdentity {
+    id: string;
+    customer_id: string;
+    idp_id: string;
+    role: 'owner' | 'admin' | 'member';
+    is_primary: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Customer with their associated IDP identities (from `customer_users` join).
+ */
+interface CustomerWithIdentities extends Customer {
+    identities?: CustomerIdentity[];
+}
+/**
+ * Notification preferences stored in `customer.metadata.notification_preferences`.
+ */
+interface NotificationPreferences {
+    email?: boolean;
+    sms?: boolean;
+    push?: boolean;
+    booking_confirmation?: boolean;
+    booking_reminder?: boolean;
+    booking_cancellation?: boolean;
+    marketing?: boolean;
+    [key: string]: boolean | undefined;
+}
+/**
+ * Customer with their bookings, as returned by GET /api/v1/customers/bookings.
+ */
+interface CustomerWithBookings {
+    customer: Customer;
+    bookings: Booking[];
+    /** Bookings organised by slot ID → array of bookings */
+    groupedBySlot: Record<string, Booking[]>;
+    total: number;
+    total_slots: number;
+}
+/**
+ * Options for resolving a customer from an IDP identity or email.
+ * At least one of `idpId` or `email` must be provided.
+ */
+interface ResolveCustomerOptions {
     tenantId: string;
+    /** IDP user ID (Clerk userId, Auth0 sub, etc.) — checked first */
+    idpId?: string;
+    /** Email address — used as fallback if idpId lookup returns nothing */
     email?: string;
+}
+/**
+ * Options for atomic customer upsert (find or create by email within a tenant).
+ */
+interface FindOrCreateCustomerOptions {
+    tenant_id: string;
+    email: string;
     name?: string;
     phone?: string;
+    address?: string;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    customer_type?: 'individual' | 'organization';
+    is_guest?: boolean;
+    metadata?: Record<string, unknown>;
 }
 interface Flow {
     id: string;
@@ -220,6 +318,63 @@ interface GetOrganizationOptions {
     limit?: number;
     is_public?: boolean;
 }
+/**
+ * Artifact / document attached to a customer or booking
+ */
+type ArtifactEntityType = 'customer' | 'booking' | 'slot' | 'service' | 'tenant';
+type ArtifactMimeCategory = 'pdf' | 'document' | 'image' | 'spreadsheet' | 'video' | 'audio' | 'other';
+interface Artifact {
+    id: string;
+    tenant_id: string;
+    /** The Slotly entity this file is attached to */
+    related_entity_type: ArtifactEntityType;
+    related_entity_id: string;
+    /** Original filename supplied by the uploader */
+    original_filename: string;
+    /** Storage path within the tenant bucket (opaque — use url/signed_url to access) */
+    storage_path: string;
+    /** MIME category, derived server-side */
+    mime_category: ArtifactMimeCategory;
+    mime_type?: string;
+    size_bytes?: number;
+    /** Optional label, e.g. "CV", "Invoice", "Contract" */
+    label?: string;
+    metadata?: Record<string, unknown>;
+    uploaded_by_user_id?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Artifact with a short-lived signed download URL (returned from getUrl / list with signed=true)
+ */
+interface ArtifactWithUrl extends Artifact {
+    signed_url: string;
+    /** Unix timestamp (seconds) when the signed_url expires */
+    signed_url_expires_at: number;
+}
+interface ListArtifactsOptions {
+    related_entity_type?: ArtifactEntityType;
+    related_entity_id?: string;
+    /** Include signed download URLs in each result (adds latency) */
+    signed?: boolean;
+    mime_category?: ArtifactMimeCategory;
+    label?: string;
+    page?: number;
+    limit?: number;
+}
+interface UploadArtifactOptions {
+    /** The file binary */
+    file: Blob | Buffer | ArrayBuffer;
+    /** Original filename */
+    filename: string;
+    /** The entity this artifact belongs to */
+    related_entity_type: ArtifactEntityType;
+    related_entity_id: string;
+    /** Optional label for the UI, e.g. "CV", "Invoice" */
+    label?: string;
+    mime_type?: string;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Full tenant configuration including branding, services, and service items
  * Service items are nested within each service object (not as a separate top-level array)
@@ -488,10 +643,45 @@ declare class ServiceClient {
      * @returns Service details (with items if includeItems=true)
      */
     getById(id: string, includeItems?: boolean): Promise<ApiResponse<Service | ServiceWithItems>>;
+    /**
+     * 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
+     */
+    getServicesByTenant(options: {
+        tenantId?: string;
+        tenantSlug?: string;
+        slotId?: string;
+        isActive?: boolean;
+        includeItems?: boolean;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Service[] | ServiceWithItems[]>>;
+    /**
+     * 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)
+     */
+    getServicesBySlot(slotId: string): Promise<ApiResponse<SlotServiceWithItems[]>>;
     /**
      * 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
@@ -506,6 +696,7 @@ declare 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
      */
@@ -728,10 +919,13 @@ declare 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)
      */
-    getServices(id: string): Promise<ApiResponse<ServiceWithItems[]>>;
+    getServices(id: string): Promise<ApiResponse<SlotServiceWithItems[]>>;
     /**
      * Get slot with tenant information
      * GET /api/v1/slots/:id/tenant-info
@@ -781,11 +975,12 @@ declare class CustomerClient {
     /**
      * Create a new customer
      * POST /api/v1/customers
-     *
-     * @param data - Customer creation data (tenant_id, name, email required)
-     * @returns Created customer
      */
-    create(data: Partial<Customer>): Promise<ApiResponse<Customer>>;
+    create(data: Partial<Customer> & {
+        tenant_id: string;
+        name: string;
+        email: string;
+    }): Promise<ApiResponse<Customer>>;
     /**
      * Update customer by ID
      * PUT /api/v1/customers/:id
@@ -815,30 +1010,67 @@ declare class CustomerClient {
         tenantId: string;
     }): Promise<ApiResponse<Customer | null>>;
     /**
-     * Get autocomplete data from existing customers and bookings
-     * GET /api/v1/customers/autocomplete
-     *
-     * @param tenantId - Tenant ID (required)
-     * @returns Autocomplete data
+     * Get autocomplete data from existing customers and bookings.
+     * GET /api/v1/customers/autocomplete?tenantId=:tenantId
      */
-    autocomplete(tenantId: string): Promise<ApiResponse<any>>;
+    autocomplete(tenantId: string): Promise<ApiResponse<{
+        companies: string[];
+        jobTitles: string[];
+        experienceLevels: string[];
+        cities: string[];
+        states: string[];
+        zipCodes: string[];
+    }>>;
     /**
-     * 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
+     * Get all bookings for a customer, grouped by slot.
+     * GET /api/v1/customers/bookings?tenantId=:id
      */
     getBookings(params: {
         email?: string;
         userId?: string;
         tenantId: string;
-    }): Promise<ApiResponse<{
-        customer: Customer | null;
-        bookings: Booking[];
-        groupedBySlot: Record<string, Booking[]>;
-        total: number;
+    }): Promise<ApiResponse<CustomerWithBookings>>;
+    /**
+     * Atomic upsert: find an existing customer by email within a tenant, or create one.
+     * POST /api/v1/customers/find-or-create
+     */
+    findOrCreate(options: FindOrCreateCustomerOptions): Promise<ApiResponse<Customer & {
+        created: boolean;
     }>>;
+    /**
+     * Resolve a customer from an IDP identity or email.
+     * Tries idpId lookup (customer_users) first, then falls back to email.
+     * POST /api/v1/customers/resolve
+     */
+    resolve(options: ResolveCustomerOptions): Promise<ApiResponse<Customer | null>>;
+    /**
+     * Get a customer with their linked IDP identities (customer_users rows).
+     * GET /api/v1/customers/:id?include_identities=true
+     */
+    getWithIdentities(id: string): Promise<ApiResponse<CustomerWithIdentities>>;
+    /**
+     * Link an IDP user ID to a customer (creates a customer_users row).
+     * POST /api/v1/customers/:id/users
+     */
+    linkUser(customerId: string, idpId: string, options?: {
+        role?: CustomerIdentity['role'];
+        is_primary?: boolean;
+    }): Promise<ApiResponse<CustomerIdentity>>;
+    /**
+     * Unlink an IDP user from a customer (deletes the customer_users row).
+     * DELETE /api/v1/customers/:id/users/:idpId
+     */
+    unlinkUser(customerId: string, idpId: string): Promise<ApiResponse<void>>;
+    /**
+     * Get notification preferences for a customer.
+     * GET /api/v1/customers/:id/preferences/notifications
+     */
+    getNotificationPreferences(customerId: string): Promise<ApiResponse<NotificationPreferences>>;
+    /**
+     * Update notification preferences for a customer (partial merge).
+     * PATCH /api/v1/customers/:id/preferences/notifications
+     */
+    updateNotificationPreferences(customerId: string, preferences: Partial<NotificationPreferences>): Promise<ApiResponse<NotificationPreferences>>;
 }
 
 declare class FlowClient {
@@ -1129,6 +1361,68 @@ declare class OrganizationClient {
     getBySlug(slug: string, options?: GetOrganizationOptions): Promise<ApiResponse<Organization | OrganizationFullConfig>>;
 }
 
+/**
+ * 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 });
+ * ```
+ */
+declare class DocumentClient {
+    private readonly client;
+    private readonly base;
+    constructor(client: AxiosInstance);
+    /**
+     * Upload a file artifact.
+     * Sends as multipart/form-data.
+     */
+    upload(options: UploadArtifactOptions): Promise<Artifact>;
+    /**
+     * List artifacts for a specific entity.
+     * Pass `signed: true` to get download URLs in each result.
+     */
+    listByEntity(entityType: ArtifactEntityType, entityId: string, options?: Omit<ListArtifactsOptions, 'related_entity_type' | 'related_entity_id'>): Promise<ApiResponse<(Artifact | ArtifactWithUrl)[]>>;
+    /**
+     * List artifacts with full filter options.
+     */
+    list(options: ListArtifactsOptions): Promise<ApiResponse<(Artifact | ArtifactWithUrl)[]>>;
+    /**
+     * Get a single artifact by ID.
+     */
+    get(id: string, signed?: boolean): Promise<Artifact | ArtifactWithUrl>;
+    /**
+     * Get a signed download URL for an artifact.
+     * Returns the full ArtifactWithUrl including `signed_url` and `signed_url_expires_at`.
+     */
+    getUrl(id: string): Promise<ArtifactWithUrl>;
+    /**
+     * Delete an artifact and its stored file.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Update artifact label or metadata.
+     */
+    update(id: string, patch: {
+        label?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Artifact>;
+}
+
 /**
  * Custom error classes for Slotly SDK
  */
@@ -1291,6 +1585,8 @@ interface SlotlyApi {
     notification: NotificationClient;
     dataQuality: DataQualityClient;
     organization: OrganizationClient;
+    /** Upload and retrieve file artifacts (CVs, invoices, images) linked to any Slotly entity */
+    document: DocumentClient;
 }
 /**
  * Initialize and configure a new Slotly API client with dual authentication.
@@ -1355,4 +1651,4 @@ interface SlotlyApi {
  */
 declare const useSlotly: (options: SlotlyClientOptions) => SlotlyApi;
 
-export { type ApiResponse, type Booking, type BookingWithSlot, type Category, type Customer, type DataQualityIssue, type Flow, type FlowStep, type GetOrganizationOptions, type ListBookingsOptions, type Notification, type Organization, type OrganizationFullConfig, type Service, type ServiceItem, type ServiceItemWithService, type ServiceWithItems, type Slot, type SlotlyApi, SlotlyApiError, type SlotlyAuthContext, SlotlyAuthError, type SlotlyClientOptions, SlotlyConfigurationError, SlotlyNetworkError, type SlotlyRequest, type Studio, type Tenant, type TenantBranding, type TenantFullConfig, useSlotly as default, getSlotlyContext, useSlotly, validateSlotlyRequest };
+export { type ApiResponse, type Artifact, type ArtifactEntityType, type ArtifactMimeCategory, type ArtifactWithUrl, type Booking, type BookingWithSlot, type Category, type Customer, type CustomerIdentity, type CustomerWithBookings, type CustomerWithIdentities, type DataQualityIssue, type FindOrCreateCustomerOptions, type Flow, type FlowStep, type GetOrganizationOptions, type ListArtifactsOptions, type ListBookingsOptions, type Notification, type NotificationPreferences, type Organization, type OrganizationFullConfig, type ResolveCustomerOptions, type Service, type ServiceItem, type ServiceItemWithService, type ServiceWithItems, type Slot, type SlotServiceWithItems, type SlotlyApi, SlotlyApiError, type SlotlyAuthContext, SlotlyAuthError, type SlotlyClientOptions, SlotlyConfigurationError, SlotlyNetworkError, type SlotlyRequest, type Studio, type Tenant, type TenantBranding, type TenantFullConfig, type UploadArtifactOptions, useSlotly as default, getSlotlyContext, useSlotly, validateSlotlyRequest };