@go-avro/avro-js 0.0.25 → 0.0.27

package/dist/client/QueryClient.d.ts

@@ -7,6 +7,16 @@ import { CancelToken, RetryStrategy } from '../types/client';
 import { StandardError } from '../types/error';
 import { CacheData } from '../types/cache';
 import { Waiver } from '../types/api/Waiver';
+import type { EmailSucceededPayload, EmailFailedPayload, EmailType } from "../types/api/EmailNotification";
+/** Callbacks for a tracked email request. */
+export interface TrackEmailOptions {
+    emailType?: EmailType;
+    /** How long to wait before firing onTimeout (ms). Default 30 000. */
+    timeout?: number;
+    onSuccess?: (data: EmailSucceededPayload) => void;
+    onFailure?: (data: EmailFailedPayload) => void;
+    onTimeout?: (requestId: string) => void;
+}
 export interface AvroQueryClientConfig {
     baseUrl: string;
     authManager: AuthManager;
@@ -130,6 +140,7 @@ declare module '../client/QueryClient' {
             billId: string;
             subject?: string;
             recipients?: string[][];
+            request_id?: string;
         }): Promise<{
             msg: string;
         }>;
@@ -515,6 +526,8 @@ export declare class AvroQueryClient {
     private authStateListeners;
     private _queryClient;
     private _socketInvalidationCleanup;
+    private _emailTracking;
+    private _emailListenersInit;
     constructor(config: AvroQueryClientConfig);
     emit(eventName: string, data: unknown): void;
     on<T>(eventName: string, callback: (data: T) => void): void;
@@ -708,10 +721,26 @@ export declare class AvroQueryClient {
         query?: string;
         offset?: number;
     }, cancelToken?: CancelToken, headers?: Record<string, string>): Promise<any>;
+    /**
+     * Lazily register socket listeners for email_succeeded / email_failed.
+     * Listeners live on the socket (not in a React effect) so they survive
+     * component unmounts.
+     */
+    private _initEmailListeners;
+    /**
+     * Track an outbound email request.
+     *
+     * Generates a `request_id`, registers socket listeners (once), and returns
+     * the ID so callers can pass it in the HTTP body. The backend emits
+     * `email_succeeded` / `email_failed` to the user's GUID room; this method
+     * correlates the event by `request_id` and fires the appropriate callback.
+     */
+    trackEmail(options?: TrackEmailOptions): string;
     sendEmail(emailId: string, formData: FormData, progressUpdateCallback?: (loaded: number, total: number) => void): Promise<void>;
     sendBillEmail(billId: string, body?: {
         subject?: string;
         recipients?: string[][];
         base_url?: string;
+        request_id?: string;
     }): Promise<void>;
 }

package/dist/client/QueryClient.js

@@ -1,5 +1,6 @@
 import io from 'socket.io-client';
 import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { v4 as uuidv4 } from "uuid";
 import { LoginResponse } from '../types/api';
 import { AuthState } from '../types/auth';
 import { StandardError } from '../types/error';
@@ -88,6 +89,8 @@ export class AvroQueryClient {
         this.authStateListeners = [];
         this._queryClient = null;
         this._socketInvalidationCleanup = null;
+        this._emailTracking = new Map();
+        this._emailListenersInit = false;
         this.config = {
             baseUrl: config.baseUrl,
             authManager: config.authManager,
@@ -685,6 +688,63 @@ export class AvroQueryClient {
             throw new StandardError(500, 'Failed to fetch sessions');
         });
     }
+    /* ── Email delivery tracking ──────────────────────────────────────── */
+    /**
+     * Lazily register socket listeners for email_succeeded / email_failed.
+     * Listeners live on the socket (not in a React effect) so they survive
+     * component unmounts.
+     */
+    _initEmailListeners() {
+        if (this._emailListenersInit)
+            return;
+        this._emailListenersInit = true;
+        this.socket.on("email_succeeded", (data) => {
+            const entry = this._emailTracking.get(data.request_id);
+            if (!entry)
+                return;
+            // Reset timeout — more recipients may follow for the same request_id
+            clearTimeout(entry.timerId);
+            entry.timerId = setTimeout(() => {
+                this._emailTracking.delete(data.request_id);
+            }, 5000);
+            entry.onSuccess?.(data);
+        });
+        this.socket.on("email_failed", (data) => {
+            const entry = this._emailTracking.get(data.request_id);
+            if (!entry)
+                return;
+            clearTimeout(entry.timerId);
+            entry.timerId = setTimeout(() => {
+                this._emailTracking.delete(data.request_id);
+            }, 5000);
+            entry.onFailure?.(data);
+        });
+    }
+    /**
+     * Track an outbound email request.
+     *
+     * Generates a `request_id`, registers socket listeners (once), and returns
+     * the ID so callers can pass it in the HTTP body. The backend emits
+     * `email_succeeded` / `email_failed` to the user's GUID room; this method
+     * correlates the event by `request_id` and fires the appropriate callback.
+     */
+    trackEmail(options = {}) {
+        this._initEmailListeners();
+        const requestId = uuidv4();
+        const { timeout = 30000 } = options;
+        const timerId = setTimeout(() => {
+            this._emailTracking.delete(requestId);
+            options.onTimeout?.(requestId);
+        }, timeout);
+        this._emailTracking.set(requestId, {
+            emailType: options.emailType,
+            timerId,
+            onSuccess: options.onSuccess,
+            onFailure: options.onFailure,
+            onTimeout: options.onTimeout,
+        });
+        return requestId;
+    }
     sendEmail(emailId, formData, progressUpdateCallback) {
         try {
             return this.post({

package/dist/client/hooks/bills.js

@@ -193,10 +193,10 @@ AvroQueryClient.prototype.generatePDFFromBackend = function ({ billId }) {
         return response;
     });
 };
-AvroQueryClient.prototype.sendBillingEmail = async function ({ subject, billId, recipients, }) {
+AvroQueryClient.prototype.sendBillingEmail = async function ({ subject, billId, recipients, request_id, }) {
     return this.post({
         path: `/bill/${billId}/email`,
-        data: JSON.stringify({ recipients, subject }),
+        data: JSON.stringify({ recipients, subject, request_id }),
         headers: {
             "Content-Type": "application/json"
         }

package/dist/client/hooks/email.d.ts

@@ -0,0 +1,47 @@
+import type { EmailFailedPayload, EmailType } from "../../types/api/EmailNotification";
+export type EmailResultStatus = "succeeded" | "failed" | "timeout";
+export interface EmailResult {
+    requestId: string;
+    status: EmailResultStatus;
+    emailType?: EmailType;
+    recipient?: string;
+    error?: EmailFailedPayload["error"];
+}
+export interface UseEmailStatusOptions {
+    /** How long to wait for a socket event before firing `onTimeout` (ms). Default 30 000. */
+    timeout?: number;
+    /** Called when the backend reports success. */
+    onSuccess?: (result: EmailResult) => void;
+    /** Called when the backend reports failure. */
+    onFailure?: (result: EmailResult) => void;
+    /** Called when neither success nor failure arrives within the timeout window. */
+    onTimeout?: (requestId: string) => void;
+}
+/**
+ * Subscribe to backend email delivery notifications via Socket.IO.
+ *
+ * Delegates to `AvroQueryClient.trackEmail()` which registers socket
+ * listeners on the client itself (not in a React effect), so
+ * notifications survive component unmounts.
+ *
+ * Usage:
+ * ```ts
+ * const { trackEmail, pending, results } = useEmailStatus({
+ *   onSuccess: (r) => toast.success(`Email sent to ${r.recipient}`),
+ *   onFailure: (r) => toast.error(`Email failed: ${r.error?.message}`),
+ *   onTimeout: (id) => toast.warn("Email status unknown"),
+ * });
+ *
+ * const requestId = trackEmail("bill");
+ * await avroQueryClient.sendBillingEmail({ billId, request_id: requestId });
+ * ```
+ */
+export declare function useEmailStatus(options?: UseEmailStatusOptions): {
+    readonly trackEmail: (emailType?: EmailType) => string;
+    readonly pending: Map<string, {
+        emailType?: EmailType;
+        trackedAt: number;
+    }>;
+    readonly results: Map<string, EmailResult>;
+    readonly clearResult: (requestId: string) => void;
+};

package/dist/client/hooks/email.js

@@ -0,0 +1,104 @@
+import { useCallback, useRef, useState } from "react";
+import { useAvroQueryClient } from "../../client/AvroQueryClientProvider";
+/* ──────────────────────────────────────────────────────────────────────── */
+/*  Hook                                                                    */
+/* ──────────────────────────────────────────────────────────────────────── */
+/**
+ * Subscribe to backend email delivery notifications via Socket.IO.
+ *
+ * Delegates to `AvroQueryClient.trackEmail()` which registers socket
+ * listeners on the client itself (not in a React effect), so
+ * notifications survive component unmounts.
+ *
+ * Usage:
+ * ```ts
+ * const { trackEmail, pending, results } = useEmailStatus({
+ *   onSuccess: (r) => toast.success(`Email sent to ${r.recipient}`),
+ *   onFailure: (r) => toast.error(`Email failed: ${r.error?.message}`),
+ *   onTimeout: (id) => toast.warn("Email status unknown"),
+ * });
+ *
+ * const requestId = trackEmail("bill");
+ * await avroQueryClient.sendBillingEmail({ billId, request_id: requestId });
+ * ```
+ */
+export function useEmailStatus(options = {}) {
+    const { timeout = 30000 } = options;
+    const client = useAvroQueryClient();
+    // Use refs for callbacks so the client-level handlers always see the latest
+    const onSuccessRef = useRef(options.onSuccess);
+    const onFailureRef = useRef(options.onFailure);
+    const onTimeoutRef = useRef(options.onTimeout);
+    onSuccessRef.current = options.onSuccess;
+    onFailureRef.current = options.onFailure;
+    onTimeoutRef.current = options.onTimeout;
+    // Expose reactive state so the UI can render pending / completed
+    const [pending, setPending] = useState(new Map());
+    const [results, setResults] = useState(new Map());
+    /* ── trackEmail — delegates to client.trackEmail() ──────────────── */
+    const trackEmail = useCallback((emailType) => {
+        const requestId = client.trackEmail({
+            emailType,
+            timeout,
+            onSuccess: (data) => {
+                const result = {
+                    requestId: data.request_id,
+                    status: "succeeded",
+                    emailType: data.email_type,
+                    recipient: data.recipient,
+                };
+                setPending((prev) => {
+                    const next = new Map(prev);
+                    next.delete(data.request_id);
+                    return next;
+                });
+                setResults((prev) => new Map(prev).set(data.request_id, result));
+                onSuccessRef.current?.(result);
+            },
+            onFailure: (data) => {
+                const result = {
+                    requestId: data.request_id,
+                    status: "failed",
+                    emailType: data.email_type,
+                    recipient: data.recipient,
+                    error: data.error,
+                };
+                setPending((prev) => {
+                    const next = new Map(prev);
+                    next.delete(data.request_id);
+                    return next;
+                });
+                setResults((prev) => new Map(prev).set(data.request_id, result));
+                onFailureRef.current?.(result);
+            },
+            onTimeout: (rid) => {
+                const result = {
+                    requestId: rid,
+                    status: "timeout",
+                    emailType,
+                };
+                setPending((prev) => {
+                    const next = new Map(prev);
+                    next.delete(rid);
+                    return next;
+                });
+                setResults((prev) => new Map(prev).set(rid, result));
+                onTimeoutRef.current?.(rid);
+            },
+        });
+        setPending((prev) => new Map(prev).set(requestId, {
+            emailType,
+            trackedAt: Date.now(),
+        }));
+        return requestId;
+    }, [client, timeout]);
+    /* ── clearResult (optional cleanup) ─────────────────────────────── */
+    const clearResult = useCallback((requestId) => {
+        setResults((prev) => {
+            const next = new Map(prev);
+            next.delete(requestId);
+            return next;
+        });
+    }, []);
+    return { trackEmail, pending, results, clearResult };
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { AvroQueryClientConfig, AvroQueryClient } from './client/QueryClient';
 export { AvroQueryClientProvider, useAvroQueryClient, useSocketEvent } from './client/AvroQueryClientProvider';
+export { useEmailStatus } from './client/hooks/email';
+export type { EmailResult, EmailResultStatus, UseEmailStatusOptions } from './client/hooks/email';
 export { AuthManager } from './auth/AuthManager';
 export { MemoryStorage, LocalStorage } from './auth/storage';
 import './client/core/xhr';
@@ -28,6 +30,7 @@ import './client/hooks/skills';
 import './client/hooks/proposal';
 import './client/hooks/timecards';
 import './client/hooks/waivers';
+import './client/hooks/email';
 export * from './types/api';
 export * from './types/auth';
 export * from './types/cache';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { AvroQueryClient } from './client/QueryClient';
 export { AvroQueryClientProvider, useAvroQueryClient, useSocketEvent } from './client/AvroQueryClientProvider';
+export { useEmailStatus } from './client/hooks/email';
 export { AuthManager } from './auth/AuthManager';
 export { MemoryStorage, LocalStorage } from './auth/storage';
 import './client/core/xhr';
@@ -28,6 +29,7 @@ import './client/hooks/skills';
 import './client/hooks/proposal';
 import './client/hooks/timecards';
 import './client/hooks/waivers';
+import './client/hooks/email';
 export * from './types/api';
 export * from './types/auth';
 export * from './types/cache';

package/dist/types/api/EmailNotification.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Socket event payloads for email delivery notifications.
+ *
+ * The backend emits `email_succeeded` or `email_failed` after an email
+ * thread finishes. Both events include a `request_id` that the frontend
+ * uses to correlate the notification with the original HTTP request.
+ */
+/** Provider-agnostic error shape emitted by the backend. */
+export interface EmailError {
+    code: string;
+    message: string;
+    provider: "outlook" | "gmail" | "smtp";
+}
+export type EmailType = "bill" | "proposal" | "job" | "generic";
+export interface EmailSucceededPayload {
+    request_id: string;
+    email_type: EmailType;
+    recipient?: string;
+}
+export interface EmailFailedPayload {
+    request_id: string;
+    email_type: EmailType;
+    error: EmailError;
+    recipient?: string;
+}

package/dist/types/api/EmailNotification.js

@@ -0,0 +1,8 @@
+/**
+ * Socket event payloads for email delivery notifications.
+ *
+ * The backend emits `email_succeeded` or `email_failed` after an email
+ * thread finishes. Both events include a `request_id` that the frontend
+ * uses to correlate the notification with the original HTTP request.
+ */
+export {};

package/dist/types/api.d.ts

@@ -11,6 +11,7 @@ export * from "../types/api/Chat";
 export * from "../types/api/Company";
 export * from "../types/api/CustomLineItem";
 export * from "../types/api/Email";
+export * from "../types/api/EmailNotification";
 export * from "../types/api/Friendship";
 export * from "../types/api/Group";
 export * from "../types/api/Job";

package/dist/types/api.js

@@ -10,6 +10,7 @@ export * from "../types/api/Chat";
 export * from "../types/api/Company";
 export * from "../types/api/CustomLineItem";
 export * from "../types/api/Email";
+export * from "../types/api/EmailNotification";
 export * from "../types/api/Friendship";
 export * from "../types/api/Group";
 export * from "../types/api/Job";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-avro/avro-js",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "JS client for Avro backend integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,6 +33,7 @@
   "license": "CC-BY-SA-4.0",
   "devDependencies": {
     "@types/react": "^19.2.2",
+    "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",
     "eslint": "^8.57.1",
@@ -51,6 +52,7 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.90.2",
-    "socket.io-client": "^4.8.1"
+    "socket.io-client": "^4.8.1",
+    "uuid": "^14.0.0"
   }
 }