@htlkg/data 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htlkg/data",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "exports": {
     ".": {

package/src/hooks/contacts/index.ts

@@ -0,0 +1,2 @@
+export * from "./useContacts";
+export * from "./usePaginatedContacts";

package/src/hooks/contacts/useContacts.ts

@@ -0,0 +1,176 @@
+/**
+ * useContacts Hook
+ *
+ * Vue composable for fetching and managing contact data with reactive state.
+ * Provides loading states, error handling, search, pagination, and refetch capabilities.
+ */
+
+import type { Ref, ComputedRef } from "vue";
+import type { Contact } from "@htlkg/core/types";
+import { createDataHook, type BaseHookOptions } from "../createDataHook";
+
+export interface UseContactsOptions extends BaseHookOptions {
+	/** Filter by brand ID */
+	brandId?: string;
+	/** Search query (searches email, firstName, lastName) */
+	search?: string;
+	/** Filter by GDPR consent */
+	gdprConsent?: boolean;
+	/** Filter by marketing opt-in */
+	marketingOptIn?: boolean;
+	/** Filter by tags (contact must have at least one of these tags) */
+	tags?: string[];
+	/** Pagination token for fetching next page */
+	nextToken?: string;
+}
+
+export interface UseContactsReturn {
+	/** Reactive array of contacts */
+	contacts: Ref<Contact[]>;
+	/** Computed array of contacts with GDPR consent */
+	consentedContacts: ComputedRef<Contact[]>;
+	/** Computed array of contacts opted-in for marketing */
+	marketingContacts: ComputedRef<Contact[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch contacts */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Build filter from hook options
+ */
+function buildFilter(options: UseContactsOptions): any {
+	const conditions: any[] = [];
+
+	// Filter by brand
+	if (options.brandId) {
+		conditions.push({ brandId: { eq: options.brandId } });
+	}
+
+	// Search across email, firstName, lastName
+	if (options.search) {
+		conditions.push({
+			or: [
+				{ email: { contains: options.search } },
+				{ firstName: { contains: options.search } },
+				{ lastName: { contains: options.search } },
+			],
+		});
+	}
+
+	// Filter by GDPR consent
+	if (options.gdprConsent !== undefined) {
+		conditions.push({ gdprConsent: { eq: options.gdprConsent } });
+	}
+
+	// Filter by marketing opt-in
+	if (options.marketingOptIn !== undefined) {
+		conditions.push({ marketingOptIn: { eq: options.marketingOptIn } });
+	}
+
+	// Filter by tags (contact must have at least one of these tags)
+	if (options.tags && options.tags.length > 0) {
+		const tagConditions = options.tags.map((tag) => ({
+			tags: { contains: tag },
+		}));
+		conditions.push({ or: tagConditions });
+	}
+
+	// Include any additional custom filter
+	if (options.filter) {
+		conditions.push(options.filter);
+	}
+
+	if (conditions.length === 0) {
+		return undefined;
+	}
+
+	if (conditions.length === 1) {
+		return conditions[0];
+	}
+
+	return { and: conditions };
+}
+
+/**
+ * Internal hook created by factory
+ */
+const useContactsInternal = createDataHook<
+	Contact,
+	UseContactsOptions,
+	{ consentedContacts: Contact[]; marketingContacts: Contact[] }
+>({
+	model: "Contact",
+	dataPropertyName: "contacts",
+	buildFilter,
+	computedProperties: {
+		consentedContacts: (contacts) =>
+			contacts.filter((c) => c.gdprConsent === true),
+		marketingContacts: (contacts) =>
+			contacts.filter((c) => c.marketingOptIn === true),
+	},
+});
+
+/**
+ * Composable for fetching and managing contacts
+ *
+ * @example
+ * ```typescript
+ * import { useContacts } from '@htlkg/data/hooks';
+ *
+ * const { contacts, loading, error, refetch } = useContacts({
+ *   brandId: 'brand-123',
+ *   limit: 25
+ * });
+ * ```
+ *
+ * @example With search
+ * ```typescript
+ * const { contacts, loading } = useContacts({
+ *   brandId: 'brand-123',
+ *   search: 'john',
+ *   limit: 25
+ * });
+ * ```
+ *
+ * @example With GDPR and marketing filters
+ * ```typescript
+ * const { contacts, marketingContacts } = useContacts({
+ *   brandId: 'brand-123',
+ *   gdprConsent: true,
+ *   marketingOptIn: true
+ * });
+ * ```
+ *
+ * @example With computed properties
+ * ```typescript
+ * const { contacts, consentedContacts, marketingContacts } = useContacts({
+ *   brandId: 'brand-123'
+ * });
+ *
+ * // consentedContacts - contacts with GDPR consent
+ * // marketingContacts - contacts opted-in for marketing
+ * ```
+ *
+ * @example With tag filtering
+ * ```typescript
+ * const { contacts } = useContacts({
+ *   brandId: 'brand-123',
+ *   tags: ['vip', 'returning']
+ * });
+ * ```
+ */
+export function useContacts(options: UseContactsOptions = {}): UseContactsReturn {
+	const result = useContactsInternal(options);
+	return {
+		contacts: result.contacts as Ref<Contact[]>,
+		consentedContacts: result.consentedContacts as ComputedRef<Contact[]>,
+		marketingContacts: result.marketingContacts as ComputedRef<Contact[]>,
+		loading: result.loading,
+		error: result.error,
+		refetch: result.refetch,
+	};
+}

package/src/hooks/contacts/usePaginatedContacts.ts

@@ -0,0 +1,261 @@
+/**
+ * Paginated Contacts Hooks
+ *
+ * Vue composables for fetching contacts with server-side pagination.
+ * Provides separate hooks for active and deleted contacts to enable
+ * efficient tab-based filtering in large datasets.
+ */
+
+import type { Ref, ComputedRef } from "vue";
+import type { Contact } from "@htlkg/core/types";
+import {
+	createPaginatedDataHook,
+	ACTIVE_FILTER,
+	DELETED_FILTER,
+	type PaginatedHookOptions,
+	type PaginationState,
+} from "../createPaginatedDataHook";
+
+/** Extended Contact type with computed fields */
+export type ContactWithRelations = Contact & {
+	brandName?: string;
+	name?: string;
+	deletedAt?: string;
+	deletedBy?: string;
+};
+
+export interface UsePaginatedContactsOptions extends PaginatedHookOptions {
+	/** Filter by brand ID */
+	brandId?: string;
+	/** Search query (searches email, firstName, lastName) */
+	search?: string;
+	/** Filter by GDPR consent */
+	gdprConsent?: boolean;
+	/** Filter by marketing opt-in */
+	marketingOptIn?: boolean;
+	/** Filter by tags (contact must have at least one of these tags) */
+	tags?: string[];
+}
+
+export interface UsePaginatedContactsReturn {
+	/** Reactive array of contacts */
+	contacts: Ref<ContactWithRelations[]>;
+	/** Loading state (true during any fetch) */
+	loading: Ref<boolean>;
+	/** Loading state for initial fetch */
+	initialLoading: Ref<boolean>;
+	/** Loading state for loadMore */
+	loadingMore: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Pagination state */
+	pagination: Ref<PaginationState>;
+	/** Whether there are more items to load */
+	hasMore: ComputedRef<boolean>;
+	/** Load next page of data */
+	loadMore: () => Promise<void>;
+	/** Refetch data (resets to first page) */
+	refetch: () => Promise<void>;
+	/** Reset data and pagination state */
+	reset: () => void;
+	/** Update search filter and refetch from server (searches ALL data) */
+	setSearchFilter: (filter: any) => Promise<void>;
+	/** Current search filter */
+	searchFilter: Ref<any>;
+}
+
+/**
+ * Build additional filter from hook options
+ */
+function buildFilter(options: UsePaginatedContactsOptions): any {
+	const conditions: any[] = [];
+
+	if (options.brandId) {
+		conditions.push({ brandId: { eq: options.brandId } });
+	}
+
+	// Search across email, firstName, lastName
+	if (options.search) {
+		conditions.push({
+			or: [
+				{ email: { contains: options.search } },
+				{ firstName: { contains: options.search } },
+				{ lastName: { contains: options.search } },
+			],
+		});
+	}
+
+	// Filter by GDPR consent
+	if (options.gdprConsent !== undefined) {
+		conditions.push({ gdprConsent: { eq: options.gdprConsent } });
+	}
+
+	// Filter by marketing opt-in
+	if (options.marketingOptIn !== undefined) {
+		conditions.push({ marketingOptIn: { eq: options.marketingOptIn } });
+	}
+
+	// Filter by tags (contact must have at least one of these tags)
+	if (options.tags && options.tags.length > 0) {
+		const tagConditions = options.tags.map((tag) => ({
+			tags: { contains: tag },
+		}));
+		conditions.push({ or: tagConditions });
+	}
+
+	if (options.filter && Object.keys(options.filter).length > 0) {
+		conditions.push(options.filter);
+	}
+
+	if (conditions.length === 0) {
+		return undefined;
+	}
+	if (conditions.length === 1) {
+		return conditions[0];
+	}
+	return { and: conditions };
+}
+
+/**
+ * Transform contact data
+ */
+function transformContact(contact: any): ContactWithRelations {
+	return {
+		...contact,
+		name: `${contact.firstName || ""} ${contact.lastName || ""}`.trim() || contact.email,
+		brandName: contact.brand?.name || "",
+	};
+}
+
+/**
+ * Selection set for contact queries
+ */
+const CONTACT_SELECTION_SET = [
+	"id",
+	"email",
+	"phone",
+	"firstName",
+	"lastName",
+	"locale",
+	"brandId",
+	"gdprConsent",
+	"gdprConsentDate",
+	"marketingOptIn",
+	"preferences",
+	"tags",
+	"totalVisits",
+	"lastVisitDate",
+	"firstVisitDate",
+	"source",
+	"status",
+	"createdAt",
+	"updatedAt",
+	"deletedAt",
+	"deletedBy",
+	"brand.name",
+];
+
+/**
+ * Internal hook for active contacts
+ */
+const useActiveContactsInternal = createPaginatedDataHook<ContactWithRelations, UsePaginatedContactsOptions>({
+	model: "Contact",
+	dataPropertyName: "contacts",
+	defaultPageSize: 25,
+	selectionSet: CONTACT_SELECTION_SET,
+	transform: transformContact,
+	buildFilter,
+	baseFilter: ACTIVE_FILTER,
+});
+
+/**
+ * Internal hook for deleted contacts
+ */
+const useDeletedContactsInternal = createPaginatedDataHook<ContactWithRelations, UsePaginatedContactsOptions>({
+	model: "Contact",
+	dataPropertyName: "contacts",
+	defaultPageSize: 25,
+	selectionSet: CONTACT_SELECTION_SET,
+	transform: transformContact,
+	buildFilter,
+	baseFilter: DELETED_FILTER,
+});
+
+/**
+ * Composable for fetching active (non-deleted) contacts with pagination
+ *
+ * @example
+ * ```typescript
+ * import { useActiveContacts } from '@htlkg/data/hooks';
+ *
+ * const { contacts, loading, hasMore, loadMore, refetch, setSearchFilter } = useActiveContacts({
+ *   pageSize: 25,
+ * });
+ *
+ * // Load more when user scrolls or clicks "Load More"
+ * async function onLoadMore() {
+ *   await loadMore();
+ * }
+ *
+ * // Server-side search (searches ALL contacts in database)
+ * async function onSearch(filter: any) {
+ *   await setSearchFilter(filter);
+ * }
+ * ```
+ *
+ * @example With filters
+ * ```typescript
+ * const { contacts, loading } = useActiveContacts({
+ *   brandId: 'brand-123',
+ *   gdprConsent: true,
+ *   pageSize: 50
+ * });
+ * ```
+ */
+export function useActiveContacts(options: UsePaginatedContactsOptions = {}): UsePaginatedContactsReturn {
+	const result = useActiveContactsInternal(options);
+	return {
+		contacts: result.contacts as Ref<ContactWithRelations[]>,
+		loading: result.loading,
+		initialLoading: result.initialLoading,
+		loadingMore: result.loadingMore,
+		error: result.error,
+		pagination: result.pagination,
+		hasMore: result.hasMore,
+		loadMore: result.loadMore,
+		refetch: result.refetch,
+		reset: result.reset,
+		setSearchFilter: result.setSearchFilter,
+		searchFilter: result.searchFilter,
+	};
+}
+
+/**
+ * Composable for fetching deleted contacts with pagination
+ *
+ * @example
+ * ```typescript
+ * import { useDeletedContacts } from '@htlkg/data/hooks';
+ *
+ * const { contacts, loading, hasMore, loadMore, refetch } = useDeletedContacts({
+ *   pageSize: 25,
+ * });
+ * ```
+ */
+export function useDeletedContacts(options: UsePaginatedContactsOptions = {}): UsePaginatedContactsReturn {
+	const result = useDeletedContactsInternal(options);
+	return {
+		contacts: result.contacts as Ref<ContactWithRelations[]>,
+		loading: result.loading,
+		initialLoading: result.initialLoading,
+		loadingMore: result.loadingMore,
+		error: result.error,
+		pagination: result.pagination,
+		hasMore: result.hasMore,
+		loadMore: result.loadMore,
+		refetch: result.refetch,
+		reset: result.reset,
+		setSearchFilter: result.setSearchFilter,
+		searchFilter: result.searchFilter,
+	};
+}

package/src/hooks/index.ts

@@ -107,6 +107,11 @@ export {
 // ============================================
 export {
 	useContacts,
+	useActiveContacts,
+	useDeletedContacts,
 	type UseContactsOptions,
 	type UseContactsReturn,
-} from "./useContacts";
+	type ContactWithRelations,
+	type UsePaginatedContactsOptions,
+	type UsePaginatedContactsReturn,
+} from "./contacts";