@htlkg/data 0.0.1 → 0.0.3

package/src/queries/brands.ts

@@ -0,0 +1,176 @@
+/**
+ * Brand Query Functions
+ *
+ * Provides query functions for fetching brand data from the GraphQL API.
+ */
+
+import type { Brand } from "@htlkg/core/types";
+
+/**
+ * Get a single brand by ID
+ *
+ * @example
+ * ```typescript
+ * import { getBrand } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const brand = await getBrand(client, 'brand-123');
+ * ```
+ */
+export async function getBrand<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<Brand | null> {
+	try {
+		const { data, errors } = await (client as any).models.Brand.get({ id });
+
+		if (errors) {
+			console.error("[getBrand] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as Brand;
+	} catch (error) {
+		console.error("[getBrand] Error fetching brand:", error);
+		throw error;
+	}
+}
+
+/**
+ * List all brands with optional filtering
+ *
+ * @example
+ * ```typescript
+ * import { listBrands } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const brands = await listBrands(client, {
+ *   filter: { status: { eq: 'active' } }
+ * });
+ * ```
+ */
+export async function listBrands<TClient = any>(
+	client: TClient,
+	options?: {
+		filter?: any;
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: Brand[]; nextToken?: string }> {
+	try {
+		const { data, errors, nextToken } = await (client as any).models.Brand.list(
+			options,
+		);
+
+		if (errors) {
+			console.error("[listBrands] GraphQL errors:", errors);
+			return { items: [], nextToken: undefined };
+		}
+
+		return {
+			items: (data || []) as Brand[],
+			nextToken,
+		};
+	} catch (error) {
+		console.error("[listBrands] Error fetching brands:", error);
+		throw error;
+	}
+}
+
+/**
+ * Get a brand with its product instances
+ *
+ * @example
+ * ```typescript
+ * import { getBrandWithProducts } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const brand = await getBrandWithProducts(client, 'brand-123');
+ * ```
+ */
+export async function getBrandWithProducts<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<Brand | null> {
+	try {
+		const { data, errors } = await (client as any).models.Brand.get(
+			{ id },
+			{
+				selectionSet: [
+					"id",
+					"name",
+					"accountId",
+					"logo",
+					"timezone",
+					"status",
+					"settings",
+					"productInstances.*",
+				],
+			},
+		);
+
+		if (errors) {
+			console.error("[getBrandWithProducts] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as Brand;
+	} catch (error) {
+		console.error("[getBrandWithProducts] Error fetching brand:", error);
+		throw error;
+	}
+}
+
+/**
+ * List brands by account ID
+ *
+ * @example
+ * ```typescript
+ * import { listBrandsByAccount } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const brands = await listBrandsByAccount(client, 'account-123');
+ * ```
+ */
+export async function listBrandsByAccount<TClient = any>(
+	client: TClient,
+	accountId: string,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: Brand[]; nextToken?: string }> {
+	return listBrands(client, {
+		filter: { accountId: { eq: accountId } },
+		...options,
+	});
+}
+
+/**
+ * List active brands
+ *
+ * @example
+ * ```typescript
+ * import { listActiveBrands } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const brands = await listActiveBrands(client);
+ * ```
+ */
+export async function listActiveBrands<TClient = any>(
+	client: TClient,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: Brand[]; nextToken?: string }> {
+	return listBrands(client, {
+		filter: { status: { eq: "active" } },
+		...options,
+	});
+}

package/src/queries/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Query Functions for @htlkg/data
+ *
+ * Provides query functions for fetching data from the GraphQL API.
+ */
+
+// Brand queries
+export {
+	getBrand,
+	listBrands,
+	getBrandWithProducts,
+	listBrandsByAccount,
+	listActiveBrands,
+} from "./brands";
+
+// Account queries
+export {
+	getAccount,
+	listAccounts,
+	getAccountWithBrands,
+} from "./accounts";
+
+// User queries
+export {
+	getUser,
+	getUserByCognitoId,
+	getUserByEmail,
+	listUsers,
+	listUsersByAccount,
+	listActiveUsers,
+} from "./users";
+
+// Product queries
+export {
+	getProduct,
+	listProducts,
+	listActiveProducts,
+	getProductInstance,
+	listProductInstancesByBrand,
+	listProductInstancesByAccount,
+	listEnabledProductInstancesByBrand,
+} from "./products";
+
+// Server-side query helpers
+export { executeServerQuery, executePublicQuery } from "./server-helpers";

package/src/queries/products.ts

@@ -0,0 +1,282 @@
+/**
+ * Product Query Functions
+ *
+ * Provides query functions for fetching product and product instance data from the GraphQL API.
+ */
+
+import type { Product, ProductInstance } from "@htlkg/core/types";
+
+/**
+ * Get a single product by ID
+ *
+ * @example
+ * ```typescript
+ * import { getProduct } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const product = await getProduct(client, 'product-123');
+ * ```
+ */
+export async function getProduct<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<Product | null> {
+	try {
+		const { data, errors } = await (client as any).models.Product.get({ id });
+
+		if (errors) {
+			console.error("[getProduct] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as Product;
+	} catch (error) {
+		console.error("[getProduct] Error fetching product:", error);
+		throw error;
+	}
+}
+
+/**
+ * List all products with optional filtering
+ *
+ * @example
+ * ```typescript
+ * import { listProducts } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const products = await listProducts(client, {
+ *   filter: { isActive: { eq: true } }
+ * });
+ * ```
+ */
+export async function listProducts<TClient = any>(
+	client: TClient,
+	options?: {
+		filter?: any;
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: Product[]; nextToken?: string }> {
+	try {
+		const { data, errors, nextToken } = await (
+			client as any
+		).models.Product.list(options);
+
+		if (errors) {
+			console.error("[listProducts] GraphQL errors:", errors);
+			return { items: [], nextToken: undefined };
+		}
+
+		return {
+			items: (data || []) as Product[],
+			nextToken,
+		};
+	} catch (error) {
+		console.error("[listProducts] Error fetching products:", error);
+		throw error;
+	}
+}
+
+/**
+ * List active products
+ *
+ * @example
+ * ```typescript
+ * import { listActiveProducts } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const products = await listActiveProducts(client);
+ * ```
+ */
+export async function listActiveProducts<TClient = any>(
+	client: TClient,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: Product[]; nextToken?: string }> {
+	return listProducts(client, {
+		filter: { isActive: { eq: true } },
+		...options,
+	});
+}
+
+/**
+ * Get a single product instance by ID
+ *
+ * @example
+ * ```typescript
+ * import { getProductInstance } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const instance = await getProductInstance(client, 'instance-123');
+ * ```
+ */
+export async function getProductInstance<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<ProductInstance | null> {
+	try {
+		const { data, errors } = await (client as any).models.ProductInstance.get({
+			id,
+		});
+
+		if (errors) {
+			console.error("[getProductInstance] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as ProductInstance;
+	} catch (error) {
+		console.error("[getProductInstance] Error fetching product instance:", error);
+		throw error;
+	}
+}
+
+/**
+ * List product instances by brand ID
+ *
+ * @example
+ * ```typescript
+ * import { listProductInstancesByBrand } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const instances = await listProductInstancesByBrand(client, 'brand-123');
+ * ```
+ */
+export async function listProductInstancesByBrand<TClient = any>(
+	client: TClient,
+	brandId: string,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: ProductInstance[]; nextToken?: string }> {
+	try {
+		const { data, errors, nextToken } = await (
+			client as any
+		).models.ProductInstance.list({
+			filter: { brandId: { eq: brandId } },
+			...options,
+		});
+
+		if (errors) {
+			console.error("[listProductInstancesByBrand] GraphQL errors:", errors);
+			return { items: [], nextToken: undefined };
+		}
+
+		return {
+			items: (data || []) as ProductInstance[],
+			nextToken,
+		};
+	} catch (error) {
+		console.error(
+			"[listProductInstancesByBrand] Error fetching product instances:",
+			error,
+		);
+		throw error;
+	}
+}
+
+/**
+ * List product instances by account ID
+ *
+ * @example
+ * ```typescript
+ * import { listProductInstancesByAccount } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const instances = await listProductInstancesByAccount(client, 'account-123');
+ * ```
+ */
+export async function listProductInstancesByAccount<TClient = any>(
+	client: TClient,
+	accountId: string,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: ProductInstance[]; nextToken?: string }> {
+	try {
+		const { data, errors, nextToken } = await (
+			client as any
+		).models.ProductInstance.list({
+			filter: { accountId: { eq: accountId } },
+			...options,
+		});
+
+		if (errors) {
+			console.error("[listProductInstancesByAccount] GraphQL errors:", errors);
+			return { items: [], nextToken: undefined };
+		}
+
+		return {
+			items: (data || []) as ProductInstance[],
+			nextToken,
+		};
+	} catch (error) {
+		console.error(
+			"[listProductInstancesByAccount] Error fetching product instances:",
+			error,
+		);
+		throw error;
+	}
+}
+
+/**
+ * List enabled product instances by brand ID
+ *
+ * @example
+ * ```typescript
+ * import { listEnabledProductInstancesByBrand } from '@htlkg/data/queries';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const instances = await listEnabledProductInstancesByBrand(client, 'brand-123');
+ * ```
+ */
+export async function listEnabledProductInstancesByBrand<TClient = any>(
+	client: TClient,
+	brandId: string,
+	options?: {
+		limit?: number;
+		nextToken?: string;
+	},
+): Promise<{ items: ProductInstance[]; nextToken?: string }> {
+	try {
+		const { data, errors, nextToken } = await (
+			client as any
+		).models.ProductInstance.list({
+			filter: {
+				brandId: { eq: brandId },
+				enabled: { eq: true },
+			},
+			...options,
+		});
+
+		if (errors) {
+			console.error(
+				"[listEnabledProductInstancesByBrand] GraphQL errors:",
+				errors,
+			);
+			return { items: [], nextToken: undefined };
+		}
+
+		return {
+			items: (data || []) as ProductInstance[],
+			nextToken,
+		};
+	} catch (error) {
+		console.error(
+			"[listEnabledProductInstancesByBrand] Error fetching product instances:",
+			error,
+		);
+		throw error;
+	}
+}

package/src/queries/queries.md

@@ -0,0 +1,88 @@
+# Queries Module
+
+GraphQL query functions for fetching data from Amplify models.
+
+## Installation
+
+```typescript
+import { 
+  fetchAccounts,
+  fetchBrands,
+  fetchUsers,
+  fetchProducts,
+} from '@htlkg/data/queries';
+```
+
+## Available Queries
+
+### fetchAccounts
+
+```typescript
+const accounts = await fetchAccounts(client, {
+  filter: { status: { eq: 'active' } },
+  limit: 50,
+});
+```
+
+### fetchBrands
+
+```typescript
+const brands = await fetchBrands(client, {
+  accountId: 'account-123',
+  activeOnly: true,
+  limit: 100,
+});
+```
+
+### fetchUsers
+
+```typescript
+const users = await fetchUsers(client, {
+  brandId: 'brand-456',
+  accountId: 'account-123',
+});
+```
+
+### fetchProducts
+
+```typescript
+const products = await fetchProducts(client, {
+  activeOnly: true,
+});
+```
+
+## Server-Side Usage
+
+```typescript
+import { fetchBrands } from '@htlkg/data/queries';
+import { generateServerClient } from '@htlkg/data/client';
+
+const result = await runWithAmplifyServerContext({
+  astroServerContext: { cookies: Astro.cookies, request: Astro.request },
+  operation: async () => {
+    const client = generateServerClient<Schema>();
+    return await fetchBrands(client, { accountId });
+  },
+});
+```
+
+## Filter Options
+
+All queries support GraphQL filter syntax:
+
+```typescript
+// Equality
+{ status: { eq: 'active' } }
+
+// Contains
+{ name: { contains: 'hotel' } }
+
+// Begins with
+{ email: { beginsWith: 'admin' } }
+
+// Comparison
+{ createdAt: { gt: '2024-01-01' } }
+
+// Combining filters
+{ and: [{ status: { eq: 'active' } }, { accountId: { eq: '123' } }] }
+```

package/src/queries/server-helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * Server-Side Query Helpers
+ *
+ * Convenience functions for executing server-side queries in Astro pages.
+ * These helpers simplify the common pattern of using runWithAmplifyServerContext.
+ */
+
+import type { AstroGlobal } from "astro";
+import { generateServerClient } from "../client";
+
+/**
+ * Type for the runWithAmplifyServerContext function
+ */
+type RunWithAmplifyServerContext = (options: {
+	astroServerContext: {
+		cookies: AstroGlobal["cookies"];
+		request: AstroGlobal["request"];
+	};
+	operation: (contextSpec: unknown) => Promise<unknown>;
+}) => Promise<unknown>;
+
+/**
+ * Helper to execute server-side queries in Astro pages
+ *
+ * This function wraps the common pattern of using runWithAmplifyServerContext
+ * with generateServerClient, making it easier to fetch data server-side.
+ *
+ * **Note**: This requires `createRunWithAmplifyServerContext` from `@htlkg/core/amplify-astro-adapter`.
+ * If you need more control, use the full pattern directly.
+ *
+ * @example
+ * ```typescript
+ * import type { Schema } from '../amplify/data/resource';
+ * import { executeServerQuery } from '@htlkg/data/queries/server-helpers';
+ * import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+ * import outputs from '../amplify_outputs.json';
+ *
+ * const runWithAmplifyServerContext = createRunWithAmplifyServerContext({ config: outputs });
+ *
+ * const users = await executeServerQuery<Schema>(
+ *   Astro,
+ *   runWithAmplifyServerContext,
+ *   async (client) => {
+ *     const result = await client.models.User.list();
+ *     return result.data || [];
+ *   }
+ * );
+ * ```
+ */
+export async function executeServerQuery<
+	TSchema extends Record<string, unknown>,
+	TResult,
+>(
+	astro: AstroGlobal,
+	runWithAmplifyServerContext: RunWithAmplifyServerContext,
+	operation: (client: ReturnType<typeof generateServerClient<TSchema>>) => Promise<TResult>,
+): Promise<TResult> {
+	const result = await runWithAmplifyServerContext({
+		astroServerContext: {
+			cookies: astro.cookies,
+			request: astro.request,
+		},
+		operation: async (contextSpec: unknown) => {
+			const client = generateServerClient<TSchema>();
+			return await operation(client);
+		},
+	});
+	return result as TResult;
+}
+
+/**
+ * Helper to execute server-side queries with API key authentication (public data)
+ *
+ * Use this for fetching public data that doesn't require user authentication.
+ *
+ * @example
+ * ```typescript
+ * import type { Schema } from '../amplify/data/resource';
+ * import { executePublicQuery } from '@htlkg/data/queries/server-helpers';
+ * import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+ * import outputs from '../amplify_outputs.json';
+ *
+ * const runWithAmplifyServerContext = createRunWithAmplifyServerContext({ config: outputs });
+ *
+ * const brands = await executePublicQuery<Schema>(
+ *   Astro,
+ *   runWithAmplifyServerContext,
+ *   async (client) => {
+ *     const result = await client.models.Brand.list();
+ *     return result.data || [];
+ *   }
+ * );
+ * ```
+ */
+export async function executePublicQuery<
+	TSchema extends Record<string, unknown>,
+	TResult,
+>(
+	astro: AstroGlobal,
+	runWithAmplifyServerContext: RunWithAmplifyServerContext,
+	operation: (client: ReturnType<typeof generateServerClient<TSchema>>) => Promise<TResult>,
+): Promise<TResult> {
+	const result = await runWithAmplifyServerContext({
+		astroServerContext: {
+			cookies: astro.cookies,
+			request: astro.request,
+		},
+		operation: async (_contextSpec: unknown) => {
+			const client = generateServerClient<TSchema>({ authMode: "apiKey" });
+			return await operation(client);
+		},
+	});
+	return result as TResult;
+}