@slotchain/sdk 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -160,16 +160,81 @@ interface Service {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Metadata bag for a slot — open-ended key/value store, with well-known
+ * optional fields for childcare / nursery term-based scheduling.
+ */
+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;
+}
 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.
+ */
+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).
+ */
+type UpdateSlotInput = Partial<Omit<CreateSlotInput, 'tenant_id'>>;
 /**
  * Customer record — matches the `customers` table.
  */
@@ -923,19 +988,41 @@ declare class SlotClient {
         limit?: number;
     }): Promise<ApiResponse<Slot[]>>;
     /**
-     * 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);
      */
     create(data: Partial<Slot>): Promise<ApiResponse<Slot>>;
     /**
-     * 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
      */
     update(id: string, data: Partial<Slot>): Promise<ApiResponse<Slot>>;
@@ -954,10 +1041,20 @@ declare 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).
+     */
     bulkCreate(slots: Partial<Slot>[]): Promise<ApiResponse<Slot[]>>;
     /**
-     * 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.
      */
     setAvailability(id: string, available: boolean): Promise<ApiResponse<Slot>>;
     /**
@@ -1696,4 +1793,4 @@ interface SlotlyApi {
  */
 declare const useSlotly: (options: SlotlyClientOptions) => SlotlyApi;
 
-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 };
+export { type ApiResponse, type Artifact, type ArtifactEntityType, type ArtifactMimeCategory, type ArtifactWithUrl, type Booking, type BookingWithSlot, type Category, type CreateSlotInput, 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 SlotMetadata, type SlotServiceWithItems, type SlotlyApi, SlotlyApiError, type SlotlyAuthContext, SlotlyAuthError, type SlotlyClientOptions, SlotlyConfigurationError, SlotlyNetworkError, type SlotlyRequest, type Studio, type Tenant, type TenantBranding, type TenantFullConfig, type UpdateSlotInput, type UploadArtifactOptions, useSlotly as default, getSlotlyContext, useSlotly, validateSlotlyRequest };

package/dist/index.d.ts

@@ -160,16 +160,81 @@ interface Service {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Metadata bag for a slot — open-ended key/value store, with well-known
+ * optional fields for childcare / nursery term-based scheduling.
+ */
+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;
+}
 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.
+ */
+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).
+ */
+type UpdateSlotInput = Partial<Omit<CreateSlotInput, 'tenant_id'>>;
 /**
  * Customer record — matches the `customers` table.
  */
@@ -923,19 +988,41 @@ declare class SlotClient {
         limit?: number;
     }): Promise<ApiResponse<Slot[]>>;
     /**
-     * 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);
      */
     create(data: Partial<Slot>): Promise<ApiResponse<Slot>>;
     /**
-     * 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
      */
     update(id: string, data: Partial<Slot>): Promise<ApiResponse<Slot>>;
@@ -954,10 +1041,20 @@ declare 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).
+     */
     bulkCreate(slots: Partial<Slot>[]): Promise<ApiResponse<Slot[]>>;
     /**
-     * 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.
      */
     setAvailability(id: string, available: boolean): Promise<ApiResponse<Slot>>;
     /**
@@ -1696,4 +1793,4 @@ interface SlotlyApi {
  */
 declare const useSlotly: (options: SlotlyClientOptions) => SlotlyApi;
 
-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 };
+export { type ApiResponse, type Artifact, type ArtifactEntityType, type ArtifactMimeCategory, type ArtifactWithUrl, type Booking, type BookingWithSlot, type Category, type CreateSlotInput, 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 SlotMetadata, type SlotServiceWithItems, type SlotlyApi, SlotlyApiError, type SlotlyAuthContext, SlotlyAuthError, type SlotlyClientOptions, SlotlyConfigurationError, SlotlyNetworkError, type SlotlyRequest, type Studio, type Tenant, type TenantBranding, type TenantFullConfig, type UpdateSlotInput, type UploadArtifactOptions, useSlotly as default, getSlotlyContext, useSlotly, validateSlotlyRequest };

package/dist/index.esm.js

@@ -699,11 +699,27 @@ var SlotClient = class {
     return response.data;
   }
   /**
-   * 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) {
     const response = await this.client.post(
@@ -713,11 +729,17 @@ var SlotClient = class {
     return response.data;
   }
   /**
-   * 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, data) {
@@ -747,6 +769,13 @@ var SlotClient = class {
    * @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) {
     const response = await this.client.post(
       "/api/v1/slots/bulk",
@@ -755,11 +784,14 @@ var SlotClient = class {
     return response.data;
   }
   /**
-   * 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, available) {
-    return this.update(id, { status: available ? "active" : "inactive" });
+    return this.update(id, { status: available ? "live" : "archived" });
   }
   /**
    * Get all active services for a slot with their items