@workbenchcrm/sdk 1.0.4 → 1.2.0

package/dist/index.d.mts

@@ -529,6 +529,89 @@ interface WebhookEventTypeInfo {
     description: string;
     category: 'client' | 'invoice' | 'quote' | 'job' | 'service_request';
 }
+/**
+ * Notification type - who receives the notification
+ */
+type NotificationType = 'CLIENT' | 'BUSINESS';
+/**
+ * Notification events supported by the SDK
+ * - sdk_client_created: Welcome notification for new clients
+ * - sdk_request_created: New service request notification
+ * - sdk_quote_created: Quote sent notification
+ * - sdk_invoice_created: Invoice sent notification
+ * - sdk_job_created: Job scheduled notification
+ * - sdk_custom: Custom notification (requires subject/html overrides)
+ */
+type NotificationEvent = 'sdk_client_created' | 'sdk_request_created' | 'sdk_quote_created' | 'sdk_invoice_created' | 'sdk_job_created' | 'sdk_custom';
+/**
+ * Business user roles for BUSINESS notifications
+ */
+type BusinessUserRole = 'owner' | 'admin' | 'manager' | 'member';
+/**
+ * Base options for sending notifications
+ */
+interface SendNotificationBaseOptions {
+    /** Template data for variable interpolation (e.g., client_name, quote_total) */
+    templateData?: Record<string, string | number>;
+    /** Custom subject line (overrides template) */
+    subjectOverride?: string;
+    /** Custom HTML body (overrides template) */
+    htmlOverride?: string;
+    /** Entity type for audit logging (e.g., 'client', 'invoice') */
+    entityType?: string;
+    /** Entity ID for audit logging */
+    entityId?: string;
+}
+/**
+ * Options for sending a notification to a client
+ */
+interface SendToClientOptions extends SendNotificationBaseOptions {
+    /** Client ID to send the notification to */
+    clientId: string;
+    /** Event type for template selection */
+    event: NotificationEvent;
+}
+/**
+ * Options for sending a notification to business team members
+ */
+interface SendToTeamOptions extends SendNotificationBaseOptions {
+    /** Event type for template selection */
+    event: NotificationEvent;
+    /** Roles to notify (defaults to all if not specified) */
+    roles?: BusinessUserRole[];
+}
+/**
+ * Options for sending a custom notification
+ */
+interface SendCustomNotificationOptions extends SendNotificationBaseOptions {
+    /** Notification type - CLIENT or BUSINESS */
+    type: NotificationType;
+    /** Client ID (required for CLIENT type) */
+    clientId?: string;
+    /** Roles to notify (for BUSINESS type) */
+    roles?: BusinessUserRole[];
+    /** Required: Custom subject line */
+    subject: string;
+    /** Required: Custom HTML body */
+    html: string;
+}
+/**
+ * Result of sending notifications
+ */
+interface NotificationResult {
+    /** Whether at least one notification was sent successfully */
+    success: boolean;
+    /** Unique ID for this notification batch */
+    notification_id: string;
+    /** Total number of recipients */
+    recipients_count: number;
+    /** Number of successful email sends */
+    sent_count: number;
+    /** Number of failed email sends */
+    failed_count: number;
+    /** Error messages if any failures occurred */
+    errors?: string[];
+}
 
 /**
  * @file resources/clients.ts
@@ -1057,48 +1140,47 @@ declare class JobsResource {
 }
 
 /**
- * @file resources/service-requests.ts
- * @description Service Requests resource for the Workbench SDK
+ * Requests resource for the Workbench SDK.
  *
  * Provides methods for managing service requests in Workbench CRM.
+ *
+ * @module resources/requests
  */
 
 /**
- * Service Requests resource
+ * Requests resource for managing service requests.
+ *
+ * Service requests track customer service inquiries, including
+ * contact information, service details, and status.
  *
  * @example
  * ```typescript
  * const workbench = new WorkbenchClient({ apiKey: 'wbk_live_xxx' });
  *
- * // Create a service request
- * const { data: request } = await workbench.serviceRequests.create({
- *   title: 'Leaky Faucet Repair',
- *   contact_name: 'Jane Smith',
- *   contact_email: 'jane@example.com',
- *   contact_phone: '+1-555-987-6543',
- *   address: '123 Main St, Anytown, USA',
- *   priority: 'high'
+ * // Create a new request
+ * const { data: request } = await workbench.requests.create({
+ *   title: 'AC Not Cooling',
+ *   contact_name: 'John Doe',
+ *   contact_email: 'john@example.com',
+ *   priority: 'urgent'
  * });
- *
- * // Update request status
- * await workbench.serviceRequests.update(request.id, { status: 'scheduled' });
  * ```
  */
-declare class ServiceRequestsResource {
+declare class RequestsResource {
     private readonly client;
     constructor(client: WorkbenchClient);
     /**
-     * List all service requests
+     * List all requests
      *
      * Returns a paginated list of service requests for the authenticated business.
      *
      * @param options - List options (pagination, filtering, sorting)
-     * @returns Paginated list of service requests
+     * @returns Paginated list of requests
      *
      * @example
      * ```typescript
      * // List new requests
-     * const { data, pagination } = await workbench.serviceRequests.list({
+     * const { data, pagination } = await workbench.requests.list({
      *   status: 'new',
      *   priority: 'urgent',
      *   per_page: 50
@@ -1107,27 +1189,27 @@ declare class ServiceRequestsResource {
      */
     list(options?: ListServiceRequestsOptions): Promise<ListResponse<ServiceRequest>>;
     /**
-     * Get a service request by ID
+     * Get a request by ID
      *
-     * @param id - Service request UUID
-     * @returns Service request details
+     * @param id - Request UUID
+     * @returns Request details
      *
      * @example
      * ```typescript
-     * const { data: request } = await workbench.serviceRequests.get('request-uuid');
+     * const { data: request } = await workbench.requests.get('request-uuid');
      * console.log(`Request: ${request.title} (${request.status})`);
      * ```
      */
     get(id: string): Promise<ApiResponse<ServiceRequest>>;
     /**
-     * Create a new service request
+     * Create a new request
      *
-     * @param data - Service request data
-     * @returns Created service request
+     * @param data - Request data
+     * @returns Created request
      *
      * @example
      * ```typescript
-     * const { data: request } = await workbench.serviceRequests.create({
+     * const { data: request } = await workbench.requests.create({
      *   title: 'AC Not Cooling',
      *   description: 'Air conditioner is running but not producing cold air',
      *   contact_name: 'John Doe',
@@ -1143,16 +1225,16 @@ declare class ServiceRequestsResource {
      */
     create(data: CreateServiceRequestOptions): Promise<ApiResponse<ServiceRequest>>;
     /**
-     * Update a service request
+     * Update a request
      *
-     * @param id - Service request UUID
+     * @param id - Request UUID
      * @param data - Fields to update
-     * @returns Updated service request
+     * @returns Updated request
      *
      * @example
      * ```typescript
      * // Assign to client and schedule
-     * const { data: request } = await workbench.serviceRequests.update('request-uuid', {
+     * const { data: request } = await workbench.requests.update('request-uuid', {
      *   client_id: 'client-uuid',
      *   status: 'scheduled',
      *   notes: 'Scheduled for Monday morning'
@@ -1161,15 +1243,15 @@ declare class ServiceRequestsResource {
      */
     update(id: string, data: UpdateServiceRequestOptions): Promise<ApiResponse<ServiceRequest>>;
     /**
-     * Delete a service request
+     * Delete a request
      *
-     * Permanently deletes a service request. This action cannot be undone.
+     * Permanently deletes a request. This action cannot be undone.
      *
-     * @param id - Service request UUID
+     * @param id - Request UUID
      *
      * @example
      * ```typescript
-     * await workbench.serviceRequests.delete('request-uuid');
+     * await workbench.requests.delete('request-uuid');
      * ```
      */
     delete(id: string): Promise<void>;
@@ -1396,6 +1478,156 @@ declare class WebhooksResource {
     listEventTypes(): Promise<ApiResponse<WebhookEventTypeInfo[]>>;
 }
 
+/**
+ * Notifications Resource
+ *
+ * Provides methods for sending email notifications to clients and
+ * business team members via the Workbench API.
+ *
+ * @module resources/notifications
+ *
+ * @example
+ * // Send a welcome notification to a new client
+ * await workbench.notifications.sendToClient({
+ *   clientId: 'client-uuid',
+ *   event: 'sdk_client_created',
+ *   templateData: { client_name: 'John Doe' }
+ * });
+ *
+ * @example
+ * // Notify business admins about a new request
+ * await workbench.notifications.sendToTeam({
+ *   event: 'sdk_request_created',
+ *   roles: ['owner', 'admin'],
+ *   templateData: { request_title: 'AC Repair', client_name: 'John' }
+ * });
+ *
+ * @example
+ * // Send a custom notification
+ * await workbench.notifications.sendCustom({
+ *   type: 'CLIENT',
+ *   clientId: 'client-uuid',
+ *   subject: 'Your appointment is confirmed!',
+ *   html: '<h1>Confirmed!</h1><p>See you tomorrow at 10am.</p>'
+ * });
+ */
+
+/**
+ * Notifications resource for sending email notifications via the SDK
+ */
+declare class NotificationsResource {
+    private readonly client;
+    constructor(client: WorkbenchClient);
+    /**
+     * Send a notification to a specific client
+     *
+     * Sends an email notification to a client using a predefined template
+     * or custom content. The client must have a valid email address.
+     *
+     * @param options - Notification options
+     * @returns Notification result with delivery statistics
+     *
+     * @example
+     * // Welcome a new client
+     * const result = await workbench.notifications.sendToClient({
+     *   clientId: 'client-uuid',
+     *   event: 'sdk_client_created',
+     *   templateData: {
+     *     client_name: 'John Doe'
+     *   }
+     * });
+     * console.log(`Sent to ${result.data.sent_count} recipient(s)`);
+     *
+     * @example
+     * // Notify client about a new quote with custom subject
+     * const result = await workbench.notifications.sendToClient({
+     *   clientId: 'client-uuid',
+     *   event: 'sdk_quote_created',
+     *   templateData: {
+     *     client_name: 'John',
+     *     quote_number: 'Q-001',
+     *     quote_total: '$1,500.00'
+     *   },
+     *   subjectOverride: 'Your custom quote is ready!'
+     * });
+     */
+    sendToClient(options: SendToClientOptions): Promise<ApiResponse<NotificationResult>>;
+    /**
+     * Send a notification to business team members
+     *
+     * Sends an email notification to team members, optionally filtered
+     * by their role in the business.
+     *
+     * @param options - Notification options
+     * @returns Notification result with delivery statistics
+     *
+     * @example
+     * // Notify all team members about a new service request
+     * const result = await workbench.notifications.sendToTeam({
+     *   event: 'sdk_request_created',
+     *   templateData: {
+     *     request_title: 'Emergency AC Repair',
+     *     client_name: 'John Doe',
+     *     request_description: 'AC not cooling, needs urgent attention'
+     *   }
+     * });
+     *
+     * @example
+     * // Notify only owners and admins
+     * const result = await workbench.notifications.sendToTeam({
+     *   event: 'sdk_invoice_created',
+     *   roles: ['owner', 'admin'],
+     *   templateData: {
+     *     invoice_number: 'INV-001',
+     *     invoice_total: '$2,500.00',
+     *     client_name: 'Acme Corp'
+     *   }
+     * });
+     */
+    sendToTeam(options: SendToTeamOptions): Promise<ApiResponse<NotificationResult>>;
+    /**
+     * Send a custom notification
+     *
+     * Sends a notification with fully custom subject and HTML content.
+     * Can be sent to either a client or business team members.
+     *
+     * @param options - Custom notification options
+     * @returns Notification result with delivery statistics
+     *
+     * @example
+     * // Send custom appointment confirmation to client
+     * const result = await workbench.notifications.sendCustom({
+     *   type: 'CLIENT',
+     *   clientId: 'client-uuid',
+     *   subject: 'Your appointment is confirmed for tomorrow!',
+     *   html: `
+     *     <h1>Appointment Confirmed</h1>
+     *     <p>Hi John,</p>
+     *     <p>Your appointment has been confirmed:</p>
+     *     <ul>
+     *       <li><strong>Date:</strong> January 23, 2026</li>
+     *       <li><strong>Time:</strong> 10:00 AM</li>
+     *       <li><strong>Service:</strong> AC Maintenance</li>
+     *     </ul>
+     *     <p>See you tomorrow!</p>
+     *   `
+     * });
+     *
+     * @example
+     * // Send custom alert to admins
+     * const result = await workbench.notifications.sendCustom({
+     *   type: 'BUSINESS',
+     *   roles: ['owner', 'admin'],
+     *   subject: 'High-value quote approved!',
+     *   html: '<p>Quote Q-001 for $10,000 has been approved by Acme Corp.</p>',
+     *   templateData: {
+     *     quote_number: 'Q-001'
+     *   }
+     * });
+     */
+    sendCustom(options: SendCustomNotificationOptions): Promise<ApiResponse<NotificationResult>>;
+}
+
 /**
  * @file client.ts
  * @description Main Workbench API client class
@@ -1480,10 +1712,12 @@ declare class WorkbenchClient {
     readonly quotes: QuotesResource;
     /** Jobs resource */
     readonly jobs: JobsResource;
-    /** Service requests resource */
-    readonly serviceRequests: ServiceRequestsResource;
+    /** Requests resource */
+    readonly requests: RequestsResource;
     /** Webhooks resource */
     readonly webhooks: WebhooksResource;
+    /** Notifications resource */
+    readonly notifications: NotificationsResource;
     /**
      * Create a new Workbench client
      *
@@ -1665,4 +1899,4 @@ declare function constructWebhookEvent<T = Record<string, unknown>>(payload: str
     timestamp: string;
 };
 
-export { type ApiError, type ApiResponse, type Client, type ClientStatus, ClientsResource, type CreateClientOptions, type CreateInvoiceOptions, type CreateJobOptions, type CreateQuoteOptions, type CreateServiceRequestOptions, type CreateWebhookOptions, type Invoice, type InvoiceItem, type InvoiceStatus, InvoicesResource, type Job, type JobPriority, type JobStatus, JobsResource, type ListClientsOptions, type ListInvoicesOptions, type ListJobsOptions, type ListOptions, type ListQuotesOptions, type ListResponse, type ListServiceRequestsOptions, type ListWebhookDeliveriesOptions, type Pagination, type Quote, type QuoteItem, type QuoteStatus, QuotesResource, type RequestOptions, type ResponseMeta, type ServiceRequest, type ServiceRequestPriority, type ServiceRequestStatus, ServiceRequestsResource, type UpdateClientOptions, type UpdateInvoiceOptions, type UpdateJobOptions, type UpdateQuoteOptions, type UpdateServiceRequestOptions, type UpdateWebhookOptions, type VerifyOptions, type Webhook, type WebhookDelivery, type WebhookEvent, type WebhookSignature, WebhookVerificationError, WebhooksResource, WorkbenchClient, type WorkbenchConfig, WorkbenchError, computeSignature, constructWebhookEvent, parseSignatureHeader, verifyWebhookSignature };
+export { type ApiError, type ApiResponse, type BusinessUserRole, type Client, type ClientStatus, ClientsResource, type CreateClientOptions, type CreateInvoiceOptions, type CreateJobOptions, type CreateQuoteOptions, type CreateServiceRequestOptions, type CreateWebhookOptions, type Invoice, type InvoiceItem, type InvoiceStatus, InvoicesResource, type Job, type JobPriority, type JobStatus, JobsResource, type ListClientsOptions, type ListInvoicesOptions, type ListJobsOptions, type ListOptions, type ListQuotesOptions, type ListResponse, type ListServiceRequestsOptions, type ListWebhookDeliveriesOptions, type NotificationEvent, type NotificationResult, type NotificationType, NotificationsResource, type Pagination, type Quote, type QuoteItem, type QuoteStatus, QuotesResource, type RequestOptions, RequestsResource, type ResponseMeta, type SendCustomNotificationOptions, type SendToClientOptions, type SendToTeamOptions, type ServiceRequest, type ServiceRequestPriority, type ServiceRequestStatus, type UpdateClientOptions, type UpdateInvoiceOptions, type UpdateJobOptions, type UpdateQuoteOptions, type UpdateServiceRequestOptions, type UpdateWebhookOptions, type VerifyOptions, type Webhook, type WebhookDelivery, type WebhookEvent, type WebhookSignature, WebhookVerificationError, WebhooksResource, WorkbenchClient, type WorkbenchConfig, WorkbenchError, computeSignature, constructWebhookEvent, parseSignatureHeader, verifyWebhookSignature };