@slotchain/sdk 1.1.4 → 1.2.0

package/src/clients/customer-client.ts

@@ -1,5 +1,14 @@
 import { AxiosInstance } from 'axios';
-import { ApiResponse, Customer, Booking } from '../types/api';
+import {
+  ApiResponse,
+  Customer,
+  CustomerIdentity,
+  CustomerWithIdentities,
+  CustomerWithBookings,
+  NotificationPreferences,
+  FindOrCreateCustomerOptions,
+  ResolveCustomerOptions,
+} from '../types/api';
 
 export class CustomerClient {
   constructor(private client: AxiosInstance) {}
@@ -58,11 +67,8 @@ export class CustomerClient {
   /**
    * 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>> {
+  async create(data: Partial<Customer> & { tenant_id: string; name: string; email: string }): Promise<ApiResponse<Customer>> {
     const response = await this.client.post<ApiResponse<Customer>>(
       '/api/v1/customers',
       data
@@ -119,14 +125,25 @@ export class CustomerClient {
   }
 
   /**
-   * 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
    */
-  async autocomplete(tenantId: string): Promise<ApiResponse<any>> {
-    const response = await this.client.get<ApiResponse<any>>(
+  async autocomplete(tenantId: string): Promise<ApiResponse<{
+    companies: string[];
+    jobTitles: string[];
+    experienceLevels: string[];
+    cities: string[];
+    states: string[];
+    zipCodes: string[];
+  }>> {
+    const response = await this.client.get<ApiResponse<{
+      companies: string[];
+      jobTitles: string[];
+      experienceLevels: string[];
+      cities: string[];
+      states: string[];
+      zipCodes: string[];
+    }>>(
       '/api/v1/customers/autocomplete',
       { params: { tenantId } }
     );
@@ -134,32 +151,115 @@ export class CustomerClient {
   }
 
   /**
-   * 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
    */
   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;
-    }>>(
+  }): Promise<ApiResponse<CustomerWithBookings>> {
+    const response = await this.client.get<ApiResponse<CustomerWithBookings>>(
       '/api/v1/customers/bookings',
       { params }
     );
     return response.data;
   }
+
+  // ─── Atomic upsert ────────────────────────────────────────────────────────
+
+  /**
+   * Atomic upsert: find an existing customer by email within a tenant, or create one.
+   * POST /api/v1/customers/find-or-create
+   */
+  async findOrCreate(options: FindOrCreateCustomerOptions): Promise<ApiResponse<Customer & { created: boolean }>> {
+    const response = await this.client.post<ApiResponse<Customer & { created: boolean }>>(
+      '/api/v1/customers/find-or-create',
+      options
+    );
+    return response.data;
+  }
+
+  /**
+   * 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
+   */
+  async resolve(options: ResolveCustomerOptions): Promise<ApiResponse<Customer | null>> {
+    const response = await this.client.post<ApiResponse<Customer | null>>(
+      '/api/v1/customers/resolve',
+      options
+    );
+    return response.data;
+  }
+
+  // ─── IDP Identity Management ─────────────────────────────────────────────
+
+  /**
+   * Get a customer with their linked IDP identities (customer_users rows).
+   * GET /api/v1/customers/:id?include_identities=true
+   */
+  async getWithIdentities(id: string): Promise<ApiResponse<CustomerWithIdentities>> {
+    const response = await this.client.get<ApiResponse<CustomerWithIdentities>>(
+      `/api/v1/customers/${id}`,
+      { params: { include_identities: true } }
+    );
+    return response.data;
+  }
+
+  /**
+   * Link an IDP user ID to a customer (creates a customer_users row).
+   * POST /api/v1/customers/:id/users
+   */
+  async linkUser(
+    customerId: string,
+    idpId: string,
+    options?: { role?: CustomerIdentity['role']; is_primary?: boolean }
+  ): Promise<ApiResponse<CustomerIdentity>> {
+    const response = await this.client.post<ApiResponse<CustomerIdentity>>(
+      `/api/v1/customers/${customerId}/users`,
+      { idp_id: idpId, role: options?.role ?? 'member', is_primary: options?.is_primary ?? false }
+    );
+    return response.data;
+  }
+
+  /**
+   * Unlink an IDP user from a customer (deletes the customer_users row).
+   * DELETE /api/v1/customers/:id/users/:idpId
+   */
+  async unlinkUser(customerId: string, idpId: string): Promise<ApiResponse<void>> {
+    const response = await this.client.delete<ApiResponse<void>>(
+      `/api/v1/customers/${customerId}/users/${encodeURIComponent(idpId)}`
+    );
+    return response.data;
+  }
+
+  // ─── Notification Preferences ────────────────────────────────────────────
+
+  /**
+   * Get notification preferences for a customer.
+   * GET /api/v1/customers/:id/preferences/notifications
+   */
+  async getNotificationPreferences(customerId: string): Promise<ApiResponse<NotificationPreferences>> {
+    const response = await this.client.get<ApiResponse<NotificationPreferences>>(
+      `/api/v1/customers/${customerId}/preferences/notifications`
+    );
+    return response.data;
+  }
+
+  /**
+   * Update notification preferences for a customer (partial merge).
+   * PATCH /api/v1/customers/:id/preferences/notifications
+   */
+  async updateNotificationPreferences(
+    customerId: string,
+    preferences: Partial<NotificationPreferences>
+  ): Promise<ApiResponse<NotificationPreferences>> {
+    const response = await this.client.patch<ApiResponse<NotificationPreferences>>(
+      `/api/v1/customers/${customerId}/preferences/notifications`,
+      preferences
+    );
+    return response.data;
+  }
 }
 

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/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';
@@ -31,6 +32,12 @@ export type {
   Category,
   Slot,
   Customer,
+  CustomerIdentity,
+  CustomerWithIdentities,
+  NotificationPreferences,
+  CustomerWithBookings,
+  ResolveCustomerOptions,
+  FindOrCreateCustomerOptions,
   Flow,
   FlowStep,
   Studio,
@@ -39,6 +46,12 @@ export type {
   Organization,
   OrganizationFullConfig,
   GetOrganizationOptions,
+  Artifact,
+  ArtifactWithUrl,
+  ArtifactEntityType,
+  ArtifactMimeCategory,
+  ListArtifactsOptions,
+  UploadArtifactOptions,
 } from './types/api';
 
 // Re-export errors
@@ -105,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 
@@ -298,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),
   };
 };