@slotchain/sdk 1.2.4 → 1.4.0

package/src/clients/booking-client.ts

@@ -113,9 +113,14 @@ export class BookingClient {
   /**
    * Create a new booking (publishes booking.created event)
    * POST /api/v1/bookings
+   *
+   * Provide either `slot_id` (explicit) or `tenant_id` (auto-resolve).
+   * When only `tenant_id` is given the API resolves the first active slot for that tenant,
+   * creating a default slot if none exists — so callers never need to manage slot IDs.
    */
   async create(data: {
-    slot_id: string;
+    slot_id?: string;
+    tenant_id?: string;
     customer_info: {
       name: string;
       email: string;
@@ -135,6 +140,51 @@ export class BookingClient {
     return response.data;
   }
 
+  /**
+   * Create a booking for a specific service item (job posting, class, product, etc.)
+   * without requiring the caller to supply or know a slot ID.
+   *
+   * The API resolves the correct slot for the tenant automatically, creating a
+   * default slot if none exists. This is the preferred method for application flows
+   * where slots are an internal infrastructure concern, not a user-facing concept.
+   *
+   * POST /api/v1/bookings  (with tenant_id instead of slot_id)
+   *
+   * @example
+   * ```typescript
+   * const booking = await slotly.booking.createFromServiceItem({
+   *   tenantId: 'tenant-123',
+   *   serviceId: 'service-abc',
+   *   serviceItemId: 'item-xyz',
+   *   customerInfo: { name: 'Jane Smith', email: 'jane@example.com' },
+   *   extraData: { kind: 'job_application', booking_moment: 'submitted' },
+   * });
+   * ```
+   */
+  async createFromServiceItem(data: {
+    tenantId: string;
+    serviceId: string;
+    serviceItemId: string;
+    customerInfo: {
+      name: string;
+      email: string;
+      phone?: string;
+      isGuestCheckout?: boolean;
+    };
+    /** Additional fields merged into booking_data alongside service/item IDs */
+    extraData?: Record<string, unknown>;
+  }): Promise<ApiResponse<Booking>> {
+    return this.create({
+      tenant_id: data.tenantId,
+      customer_info: data.customerInfo,
+      booking_data: {
+        service_id: data.serviceId,
+        service_item_id: data.serviceItemId,
+        ...data.extraData,
+      },
+    });
+  }
+
   /**
    * Update booking by ID
    * PUT /api/v1/bookings/:id

package/src/clients/slot-client.ts

@@ -1,5 +1,7 @@
 import { AxiosInstance } from 'axios';
 import { ApiResponse, Slot, SlotServiceWithItems, Tenant } from '../types/api';
+// CreateSlotInput and UpdateSlotInput are exported for consumer use but not yet
+// enforced on method signatures — see SLOT_TYPE_UPGRADE_PLAN.md Phase 2.
 
 export class SlotClient {
   constructor(private client: AxiosInstance) {}
@@ -41,11 +43,27 @@ export class SlotClient {
   }
 
   /**
-   * Create a new slot
+   * Create a new slot.
    * POST /api/v1/slots
-   * 
-   * @param data - Slot creation data (tenant_id, name required)
+   *
+   * Accepts any subset of `Slot` fields. For new integrations, prefer the
+   * exported `CreateSlotInput` type which documents the recommended shape
+   * and will become the enforced signature in v2.0 (see SLOT_TYPE_UPGRADE_PLAN.md).
+   *
+   * New fields available as of v1.4:
+   * - `starts_at` — ISO 8601 datetime when the slot opens
+   * - `ends_at`   — ISO 8601 datetime when the slot closes (omit for open-ended slots)
+   * - `metadata`  — term enrichment bag (term_name, season, half_term_start,
+   *                 half_term_end, capacity); see `SlotMetadata` type
+   *
+   * @param data - Slot creation data
    * @returns Created slot
+   *
+   * @example
+   * // Recommended — opt into stricter typing now:
+   * import { CreateSlotInput } from '@slotly/sdk';
+   * const input: CreateSlotInput = { name: 'Autumn Term', tenant_id: '...', starts_at: '...' };
+   * sdk.slots.create(input);
    */
   async create(data: Partial<Slot>): Promise<ApiResponse<Slot>> {
     const response = await this.client.post<ApiResponse<Slot>>(
@@ -56,11 +74,17 @@ export class SlotClient {
   }
 
   /**
-   * Update slot by ID
+   * Update slot by ID.
    * PUT /api/v1/slots/:id
-   * 
-   * @param id - Slot ID
-   * @param data - Slot update data
+   *
+   * Accepts any subset of `Slot` fields. For new integrations, prefer the
+   * exported `UpdateSlotInput` type — it will become the enforced signature
+   * in v2.0 (see SLOT_TYPE_UPGRADE_PLAN.md).
+   *
+   * New fields available as of v1.4: `starts_at`, `ends_at`, `metadata`.
+   *
+   * @param id   - Slot ID
+   * @param data - Fields to update
    * @returns Updated slot
    */
   async update(id: string, data: Partial<Slot>): Promise<ApiResponse<Slot>> {
@@ -92,6 +116,13 @@ export class SlotClient {
    * @param slots - Array of slots to create
    * @returns Created slots
    */
+  /**
+   * Bulk create slots.
+   * POST /api/v1/slots/bulk
+   *
+   * For new integrations, prefer passing `CreateSlotInput[]` — it will become
+   * the enforced signature in v2.0 (see SLOT_TYPE_UPGRADE_PLAN.md).
+   */
   async bulkCreate(slots: Partial<Slot>[]): Promise<ApiResponse<Slot[]>> {
     // Note: Verify if bulk endpoint exists in API
     const response = await this.client.post<ApiResponse<Slot[]>>(
@@ -102,11 +133,14 @@ export class SlotClient {
   }
 
   /**
-   * Mark slot as available/unavailable
-   * Note: Use update() method with status or other fields
+   * Mark slot as available (live) or unavailable (archived).
+   *
+   * Note: previous versions sent 'active'/'inactive' which were not valid DB
+   * enum values. Fixed in v1.4 to use 'live'/'archived' — the only valid
+   * non-draft statuses. If you need 'draft', use update() directly.
    */
   async setAvailability(id: string, available: boolean): Promise<ApiResponse<Slot>> {
-    return this.update(id, { status: available ? 'active' : 'inactive' } as Partial<Slot>);
+    return this.update(id, { status: available ? 'live' : 'archived' });
   }
 
   /**

package/src/index.ts

@@ -31,6 +31,9 @@ export type {
   ServiceItemWithService,
   Category,
   Slot,
+  SlotMetadata,
+  CreateSlotInput,
+  UpdateSlotInput,
   Customer,
   CustomerIdentity,
   CustomerWithIdentities,

package/src/types/api.ts

@@ -172,17 +172,85 @@ export interface Service {
   updated_at: string;
 }
 
+/**
+ * Metadata bag for a slot — open-ended key/value store, with well-known
+ * optional fields for childcare / nursery term-based scheduling.
+ */
+export interface SlotMetadata {
+  /** Human-readable term name, e.g. "Autumn Term 2024" */
+  term_name?: string;
+  /** Season identifier, e.g. "autumn" | "spring" | "summer" */
+  season?: string;
+  /** ISO date string for when the half-term break starts */
+  half_term_start?: string;
+  /** ISO date string for when the half-term break ends */
+  half_term_end?: string;
+  /** Maximum number of children / participants in this slot */
+  capacity?: number;
+  /**
+   * Headcount at -2 weeks (used for register generation / staffing).
+   * Negative prefix avoids collision with positive operational fields.
+   */
+  neg_headcount_neg2?: number;
+  /**
+   * Headcount at -3 weeks (used for register generation / staffing).
+   */
+  neg_headcount_neg3?: number;
+  /** Arbitrary additional metadata */
+  [key: string]: unknown;
+}
+
 export interface Slot {
   id: string;
   tenant_id: string;
+  /** Display name / title of the slot */
   name: string;
   description?: string;
   status?: string;
   is_active?: boolean;
+  /**
+   * ISO 8601 datetime when the slot opens (combines start_date + start_time from the DB).
+   * Present when the API serialises scheduled slots.
+   */
+  starts_at?: string;
+  /**
+   * ISO 8601 datetime when the slot closes (combines end_date + end_time from the DB).
+   * Absent for open-ended / on-demand slots.
+   */
+  ends_at?: string;
+  /** Arbitrary metadata bag — see SlotMetadata for well-known keys */
+  metadata?: SlotMetadata;
   created_at: string;
   updated_at: string;
 }
 
+/**
+ * Input shape for creating or updating a slot.
+ * Omits server-generated fields; all scheduling fields optional.
+ */
+export interface CreateSlotInput {
+  name: string;
+  description?: string;
+  tenant_id: string;
+  status?: 'draft' | 'live' | 'archived';
+  /**
+   * ISO 8601 datetime for when the slot opens.
+   * The API splits this into start_date + start_time before persisting.
+   */
+  starts_at?: string;
+  /**
+   * ISO 8601 datetime for when the slot closes.
+   * Omit for on-demand / open-ended slots.
+   */
+  ends_at?: string;
+  metadata?: SlotMetadata;
+}
+
+/**
+ * Partial update shape — all fields optional except id (supplied as path param).
+ */
+export type UpdateSlotInput = Partial<Omit<CreateSlotInput, 'tenant_id'>>;
+
 /**
  * Customer record — matches the `customers` table.
  */