@slotchain/sdk 1.1.4 → 1.2.1

package/dist/index.d.mts

@@ -170,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;
@@ -237,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)
@@ -265,7 +403,7 @@ declare class TenantClient {
     constructor(client: AxiosInstance);
     /**
      * Get tenant configuration by slug
-     * GET /api/v1/tenant-config/:slug
+     * GET /api/v1/tenants/:slug
      */
     getBySlug(slug: string): Promise<ApiResponse<Tenant>>;
     /**
@@ -837,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
@@ -871,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 {
@@ -1185,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
  */
@@ -1347,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.
@@ -1411,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 SlotServiceWithItems, 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 };