@slotchain/sdk 1.4.0 → 1.6.0

package/src/clients/notices-client.ts

@@ -0,0 +1,52 @@
+import type { AxiosInstance } from 'axios';
+import type { ApiResponse, SlotNotice, ListNoticesOptions } from '../types/api';
+
+/**
+ * NoticesClient — read active slot-scoped operational notices.
+ *
+ * Notices are a product concept (early closure, venue change, general alert)
+ * backed by `slot_moments` internally — the SDK surface reflects the product,
+ * not the storage model. Each notice's attached graphic (if any) is already
+ * resolved to a signed `imageUrl` server-side.
+ *
+ * @example List active notices for a tenant
+ * ```ts
+ * const { data } = await slotly.notices.list({ tenantId });
+ * ```
+ */
+export class NoticesClient {
+  private readonly client: AxiosInstance;
+  private readonly base = '/api/v1/notices';
+
+  constructor(client: AxiosInstance) {
+    this.client = client;
+  }
+
+  /**
+   * List active notices for a tenant.
+   * Returns only notices where visible_until > activeAt (default: now).
+   */
+  async list(options: ListNoticesOptions): Promise<ApiResponse<SlotNotice[]>> {
+    const response = await this.client.get<ApiResponse<SlotNotice[]>>(this.base, {
+      params: {
+        tenant_id: options.tenantId,
+        active_at: options.activeAt,
+        slot_id: options.slotId,
+        types: options.types?.join(','),
+      },
+    });
+    return response.data;
+  }
+
+  /**
+   * Get a single notice by its slot_moment id.
+   */
+  async getById(id: string, tenantId: string): Promise<SlotNotice> {
+    const response = await this.client.get<ApiResponse<SlotNotice>>(`${this.base}/${id}`, {
+      params: { tenant_id: tenantId },
+    });
+    const { data } = response.data;
+    if (!data) throw new Error(`Notice ${id} not found`);
+    return data;
+  }
+}

package/src/clients/tenant-client.ts

@@ -172,7 +172,23 @@ export class TenantClient {
       `/api/v1/tenants/${slug}`,
       { params: { includeServices } }
     );
-    return response.data;
+
+    // Strip soft-deleted and withdrawn items so consumers never have to
+    // guard against them — a deleted service or withdrawn role should be
+    // invisible to anything built on the SDK.
+    const data = response.data;
+    if (data?.data?.services) {
+      data.data.services = data.data.services
+        .filter((s) => !s.deleted_at)
+        .map((s) => ({
+          ...s,
+          serviceItems: (s.serviceItems ?? []).filter(
+            (item) => !item.deleted_at && !item.withdrawn_at,
+          ),
+        }));
+    }
+
+    return data;
   }
 }
 

package/src/index.ts

@@ -11,6 +11,7 @@ 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 { NoticesClient } from './clients/notices-client';
 import { setupRequestInterceptor, setupResponseInterceptor, setupErrorInterceptor } from './interceptors';
 import { setupRetryInterceptor } from './retry';
 import { SlotlyConfigurationError } from './errors';
@@ -55,6 +56,10 @@ export type {
   ArtifactMimeCategory,
   ListArtifactsOptions,
   UploadArtifactOptions,
+  SlotNotice,
+  NoticeMomentType,
+  NoticeCta,
+  ListNoticesOptions,
 } from './types/api';
 
 // Re-export errors
@@ -123,6 +128,8 @@ export interface SlotlyApi {
   organization: OrganizationClient;
   /** Upload and retrieve file artifacts (CVs, invoices, images) linked to any Slotly entity */
   document: DocumentClient;
+  /** List slot-scoped operational notices (early closure, venue change, general alerts) */
+  notices: NoticesClient;
 }
 
 const defaultBaseURL = typeof process !== 'undefined' && process.env?.SLOTLY_API_URL 
@@ -317,6 +324,7 @@ export const useSlotly = (options: SlotlyClientOptions): SlotlyApi => {
     dataQuality: new DataQualityClient(client),
     organization: new OrganizationClient(client),
     document: new DocumentClient(client),
+    notices: new NoticesClient(client),
   };
 };
 

package/src/types/api.ts

@@ -68,6 +68,10 @@ export interface ServiceItem {
   sort_order?: number;
   created_at: string;
   updated_at: string;
+  /** Set when the item has been soft-deleted. Filtered out by the SDK. */
+  deleted_at?: string | null;
+  /** Set when the item was withdrawn by the publisher (syndication). Filtered out by the SDK. */
+  withdrawn_at?: string | null;
 }
 
 /**
@@ -170,6 +174,8 @@ export interface Service {
   price?: number;
   created_at: string;
   updated_at: string;
+  /** Set when the service has been soft-deleted. Filtered out by the SDK. */
+  deleted_at?: string | null;
 }
 
 /**
@@ -424,7 +430,7 @@ export interface GetOrganizationOptions {
 /**
  * Artifact / document attached to a customer or booking
  */
-export type ArtifactEntityType = 'customer' | 'booking' | 'slot' | 'service' | 'tenant';
+export type ArtifactEntityType = 'customer' | 'booking' | 'slot' | 'service' | 'tenant' | 'slot_moment';
 
 export type ArtifactMimeCategory = 'pdf' | 'document' | 'image' | 'spreadsheet' | 'video' | 'audio' | 'other';
 
@@ -488,6 +494,67 @@ export interface UploadArtifactOptions {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * Slot-scoped operational notice (early closure, venue change, general alert).
+ * Backed by a `slot_moment` — see NOTICES_PLAN.md in slotly-admin.
+ */
+export type NoticeMomentType =
+  | 'general_notice'
+  | 'early_closure'
+  | 'closure_notice'
+  | 'venue_change';
+
+/**
+ * Optional call-to-action button attached to a notice.
+ * `url` is either an absolute http(s) URL or a site-relative path ('/contact-us').
+ * Only returned when both halves are present — a partial CTA is dropped server-side.
+ */
+export interface NoticeCta {
+  label: string;
+  url: string;
+  /** Open the link in a new tab. Defaults to true for notices created without the flag. */
+  newTab: boolean;
+}
+
+export interface SlotNotice {
+  id: string;
+  slotId: string;
+  tenantId: string;
+  momentType: NoticeMomentType;
+  createdAt: string;
+  createdBy: string | null;
+  notice: {
+    type: string;
+    title: string;
+    message: string;
+    /** YYYY-MM-DD — the day the notice applies to */
+    affectedDate: string;
+    /** HH:MM — only present for early_closure notices */
+    closesAt?: string;
+    severity: 'info' | 'warning' | 'urgent';
+    visibleFrom: string;
+    visibleUntil: string;
+    dismissible: boolean;
+    /** Signed URL for the notice's attached graphic, if one was uploaded */
+    imageUrl?: string | null;
+    /** Staff-picked display treatment — 'banner' (compact, stacks) or 'modal' (full-screen, one at a time) */
+    presentation: 'banner' | 'modal';
+    /** Call-to-action button, or null when the notice has none */
+    cta?: NoticeCta | null;
+  };
+  affectedBookingIds: string[];
+}
+
+export interface ListNoticesOptions {
+  tenantId: string;
+  /** Filter to notices active at this ISO timestamp. Defaults to now. */
+  activeAt?: string;
+  /** Filter to a specific slot */
+  slotId?: string;
+  /** Specific notice types to include. Defaults to all notice types. */
+  types?: NoticeMomentType[];
+}
+
 /**
  * Full tenant configuration including branding, services, and service items
  * Service items are nested within each service object (not as a separate top-level array)