@htlkg/data 0.0.1 → 0.0.3

package/src/client/client.md

@@ -0,0 +1,91 @@
+# Client Module
+
+GraphQL client generation for client-side and server-side data fetching.
+
+## Installation
+
+```typescript
+import { 
+  generateClient,
+  generateServerClient,
+  getSharedClient,
+  resetSharedClient,
+} from '@htlkg/data/client';
+```
+
+## Client-Side
+
+### getSharedClient
+
+Singleton client for client-side fetching. Avoids creating multiple instances.
+
+```typescript
+import { getSharedClient } from '@htlkg/data/client';
+import type { Schema } from '@backend/data/resource';
+
+const client = getSharedClient<Schema>();
+const { data } = await client.models.Account.list();
+```
+
+### generateClient
+
+Create a new client instance. Use in component setup or after hydration.
+
+```typescript
+import { generateClient } from '@htlkg/data/client';
+
+const client = generateClient<Schema>();
+const { data: brands } = await client.models.Brand.list();
+```
+
+### resetSharedClient
+
+Reset the singleton (useful for auth state changes or testing).
+
+```typescript
+import { resetSharedClient } from '@htlkg/data/client';
+
+// After logout
+resetSharedClient();
+```
+
+## Server-Side
+
+### generateServerClient
+
+Create a server-side client for SSR. Must be called inside `runWithAmplifyServerContext`.
+
+```typescript
+import { generateServerClient } from '@htlkg/data/client';
+import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+
+const runWithAmplifyServerContext = createRunWithAmplifyServerContext({ 
+  config: amplifyConfig 
+});
+
+const result = await runWithAmplifyServerContext({
+  astroServerContext: {
+    cookies: Astro.cookies,
+    request: Astro.request,
+  },
+  operation: async (contextSpec) => {
+    const client = generateServerClient<Schema>();
+    return await client.models.User.list();
+  },
+});
+```
+
+## Auth Modes
+
+| Mode | Description |
+|------|-------------|
+| `userPool` | Uses JWT from cookies (default) |
+| `apiKey` | Uses API key for public requests |
+
+```typescript
+// Authenticated request
+const client = generateServerClient<Schema>({ authMode: 'userPool' });
+
+// Public request
+const client = generateServerClient<Schema>({ authMode: 'apiKey' });
+```

package/src/client/index.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for @htlkg/data/client
+ * 
+ * Tests the GraphQL client generation functions for both client-side and server-side usage
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { AstroCookies } from 'astro';
+
+// Mock aws-amplify
+vi.mock('aws-amplify', () => ({
+	Amplify: {
+		configure: vi.fn(),
+		getConfig: vi.fn(() => ({}))
+	}
+}));
+
+// Mock aws-amplify/data
+vi.mock('aws-amplify/data', () => ({
+	generateClient: vi.fn(() => ({
+		models: {
+			Brand: {
+				list: vi.fn(),
+				get: vi.fn(),
+				create: vi.fn(),
+				update: vi.fn(),
+				delete: vi.fn()
+			},
+			User: {
+				list: vi.fn(),
+				get: vi.fn()
+			}
+		}
+	}))
+}));
+
+// Mock @htlkg/core/amplify-astro-adapter
+vi.mock('@htlkg/core/amplify-astro-adapter', () => ({
+	createRunWithAmplifyServerContext: vi.fn(() => vi.fn())
+}));
+
+// Mock aws-amplify/auth/server
+vi.mock('aws-amplify/auth/server', () => ({
+	fetchAuthSession: vi.fn()
+}));
+
+// Import after mocks are set up
+import { generateClient, generateServerClient } from './index';
+import { Amplify } from 'aws-amplify';
+import { generateClient as generateDataClient } from 'aws-amplify/data';
+import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+
+describe('generateClient', () => {
+	it('should generate a client-side GraphQL client', () => {
+		const client = generateClient();
+		
+		expect(client).toBeDefined();
+		expect(client.models).toBeDefined();
+		expect(client.models.Brand).toBeDefined();
+	});
+	
+	it('should return a client with model operations', () => {
+		const client = generateClient();
+		
+		expect(client.models.Brand.list).toBeDefined();
+		expect(client.models.Brand.get).toBeDefined();
+		expect(client.models.Brand.create).toBeDefined();
+		expect(client.models.Brand.update).toBeDefined();
+		expect(client.models.Brand.delete).toBeDefined();
+	});
+	
+	it('should be callable multiple times', () => {
+		const client1 = generateClient();
+		const client2 = generateClient();
+		
+		expect(client1).toBeDefined();
+		expect(client2).toBeDefined();
+	});
+});
+
+describe('generateServerClient', () => {
+	let mockConfig: any;
+	
+	beforeEach(() => {
+		// Mock Amplify config
+		mockConfig = {
+			auth: {
+				user_pool_id: 'test-pool',
+				aws_region: 'us-east-1',
+				user_pool_client_id: 'test-client'
+			},
+			data: {
+				url: 'https://test.appsync-api.us-east-1.amazonaws.com/graphql',
+				aws_region: 'us-east-1',
+				api_key: 'test-api-key',
+				default_authorization_type: 'AMAZON_COGNITO_USER_POOLS',
+				authorization_types: ['API_KEY', 'AWS_IAM']
+			}
+		};
+	});
+	
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+	
+	describe('with userPool auth mode (default)', () => {
+		it('should generate a server-side client with default userPool auth', () => {
+			const client = generateServerClient({
+				config: mockConfig
+			});
+			
+			expect(client).toBeDefined();
+			expect(client.models).toBeDefined();
+		});
+		
+		it('should use userPool auth mode by default', () => {
+			generateServerClient({
+				config: mockConfig
+			});
+			
+			expect(generateDataClient).toHaveBeenCalledWith({
+				authMode: 'userPool'
+			});
+		});
+		
+		it('should not call Amplify.configure (should be done at app startup)', () => {
+			vi.clearAllMocks();
+			
+			generateServerClient({
+				config: mockConfig
+			});
+			
+			// generateServerClient should NOT call Amplify.configure
+			// It should be called once at app startup (e.g., in amplify-server.ts)
+			expect(Amplify.configure).not.toHaveBeenCalled();
+		});
+		
+		it('should not call createRunWithAmplifyServerContext (should be done outside)', () => {
+			vi.clearAllMocks();
+			
+			generateServerClient({
+				config: mockConfig
+			});
+			
+			// generateServerClient should NOT call createRunWithAmplifyServerContext
+			// The caller should wrap the operation with runWithAmplifyServerContext
+			expect(createRunWithAmplifyServerContext).not.toHaveBeenCalled();
+		});
+	});
+	
+	describe('with apiKey auth mode', () => {
+		it('should generate a server-side client with API key auth', () => {
+			const client = generateServerClient({
+				config: mockConfig,
+				authMode: 'apiKey'
+			});
+			
+			expect(client).toBeDefined();
+			expect(client.models).toBeDefined();
+		});
+		
+		it('should use apiKey auth mode when specified', () => {
+			generateServerClient({
+				config: mockConfig,
+				authMode: 'apiKey'
+			});
+			
+			expect(generateDataClient).toHaveBeenCalledWith({
+				authMode: 'apiKey'
+			});
+		});
+	});
+	
+	describe('configuration', () => {
+		it('should accept valid Amplify configuration', () => {
+			const client = generateServerClient({
+				config: mockConfig
+			});
+			
+			expect(client).toBeDefined();
+		});
+		
+		it('should handle configuration with minimal auth setup', () => {
+			const minimalConfig = {
+				auth: {
+					user_pool_id: 'test-pool',
+					aws_region: 'us-east-1',
+					user_pool_client_id: 'test-client'
+				}
+			};
+			
+			const client = generateServerClient({
+				config: minimalConfig,
+				authMode: 'apiKey'
+			});
+			
+			expect(client).toBeDefined();
+		});
+	});
+	
+	describe('multiple instances', () => {
+		it('should allow creating multiple server clients', () => {
+			const client1 = generateServerClient({
+				config: mockConfig,
+				authMode: 'userPool'
+			});
+			
+			const client2 = generateServerClient({
+				config: mockConfig,
+				authMode: 'apiKey'
+			});
+			
+			expect(client1).toBeDefined();
+			expect(client2).toBeDefined();
+		});
+	});
+});
+
+describe('type exports', () => {
+	it('should export AstroAmplifyConfig type', () => {
+		// This is a compile-time check, but we can verify the import works
+		const config: any = {
+			auth: {
+				user_pool_id: 'test',
+				aws_region: 'us-east-1',
+				user_pool_client_id: 'test'
+			}
+		};
+		
+		expect(config).toBeDefined();
+	});
+});

package/src/client/index.ts

@@ -0,0 +1,145 @@
+/**
+ * GraphQL Client for @htlkg/data
+ *
+ * Provides both client-side and server-side GraphQL capabilities using AWS Amplify Data.
+ * The server-side functions use the Amplify Astro adapter for proper SSR support.
+ */
+
+import { generateClient as generateDataClient } from "aws-amplify/data";
+import type { ResourcesConfig } from "aws-amplify";
+
+// Re-export server-side client generation
+export { generateServerClientUsingCookies } from "./server";
+
+// Singleton client instance for client-side fetching
+let sharedClientInstance: any = null;
+
+/**
+ * Get or create the shared GraphQL client instance (singleton pattern)
+ * Use this for client-side fetching to avoid creating multiple client instances.
+ *
+ * @example
+ * ```typescript
+ * const client = getSharedClient<Schema>();
+ * const { data } = await client.models.Account.list();
+ * ```
+ */
+export function getSharedClient<
+	TSchema extends Record<string, unknown> = Record<string, unknown>,
+>(): ReturnType<typeof generateDataClient<TSchema>> {
+	if (!sharedClientInstance) {
+		sharedClientInstance = generateDataClient<TSchema>();
+	}
+	return sharedClientInstance;
+}
+
+/**
+ * Reset the shared client instance (useful for testing or auth state changes)
+ */
+export function resetSharedClient(): void {
+	sharedClientInstance = null;
+}
+
+/**
+ * Generate a client-side GraphQL client for use in Vue components and browser contexts
+ * This is SSR-safe and should be called within a component's setup function or after hydration
+ *
+ * @example
+ * ```typescript
+ * import type { Schema } from '@backend/data/resource';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const { data: brands } = await client.models.Brand.list();
+ * ```
+ */
+export function generateClient<
+	TSchema extends Record<string, unknown> = Record<string, unknown>,
+>(): ReturnType<typeof generateDataClient<TSchema>> {
+	return generateDataClient<TSchema>();
+}
+
+/**
+ * Configuration for Amplify (matches amplify_outputs.json format)
+ */
+export type AstroAmplifyConfig = ResourcesConfig;
+
+/**
+ * Authentication mode for server-side GraphQL client
+ */
+export type ServerAuthMode = 'userPool' | 'apiKey';
+
+/**
+ * Options for generating a server-side GraphQL client
+ */
+export interface GenerateServerClientOptions {
+	/** Authentication mode - 'userPool' (default) uses JWT from cookies, 'apiKey' uses API key */
+	authMode?: ServerAuthMode;
+}
+
+/**
+ * Generate a server-side GraphQL client for use within runWithAmplifyServerContext
+ * 
+ * This function creates a GraphQL client that can be used for server-side data fetching in Astro.
+ * It MUST be called within runWithAmplifyServerContext to access JWT tokens from cookies.
+ * 
+ * The client supports two authentication modes:
+ * - 'userPool' (default): Uses JWT tokens from cookies (requires runWithAmplifyServerContext)
+ * - 'apiKey': Uses API key for public/unauthenticated requests
+ *
+ * **Important**: 
+ * - Amplify.configure() must be called once at app startup (e.g., in amplify-server.ts)
+ * - This function must be called INSIDE the operation function of runWithAmplifyServerContext
+ * - The context automatically provides the token provider that reads JWT tokens from cookies
+ *
+ * @example
+ * ```typescript
+ * // In your Astro page
+ * import type { Schema } from '../amplify/data/resource';
+ * import { generateServerClient } from '@htlkg/data/client';
+ * import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+ * import outputs from '../amplify_outputs.json';
+ *
+ * const runWithAmplifyServerContext = createRunWithAmplifyServerContext({ config: outputs });
+ *
+ * // Fetch data with authentication
+ * const result = await runWithAmplifyServerContext({
+ *   astroServerContext: {
+ *     cookies: Astro.cookies,
+ *     request: Astro.request
+ *   },
+ *   operation: async (contextSpec) => {
+ *     // Generate client INSIDE the operation
+ *     const client = generateServerClient<Schema>({ authMode: 'userPool' });
+ *     return await client.models.User.list();
+ *   }
+ * });
+ * 
+ * const users = result.data || [];
+ * ```
+ * 
+ * @example Using API key for public data
+ * ```typescript
+ * const result = await runWithAmplifyServerContext({
+ *   astroServerContext: {
+ *     cookies: Astro.cookies,
+ *     request: Astro.request
+ *   },
+ *   operation: async (contextSpec) => {
+ *     const client = generateServerClient<Schema>({ authMode: 'apiKey' });
+ *     return await client.models.Brand.list();
+ *   }
+ * });
+ * ```
+ */
+export function generateServerClient<
+	TSchema extends Record<string, unknown> = Record<string, unknown>,
+>(options?: GenerateServerClientOptions): ReturnType<typeof generateDataClient<TSchema>> {
+	// Generate the client without authMode parameter
+	// When called within runWithAmplifyServerContext, it will automatically use the token provider
+	// from the context (which reads JWT tokens from cookies)
+	// The authMode should be specified per-operation, not at client creation
+	const client = generateDataClient<TSchema>();
+	
+	return client;
+}

package/src/client/server.ts

@@ -0,0 +1,118 @@
+/**
+ * Server-side data client for Astro
+ *
+ * Provides a client generator similar to Next.js's generateServerClientUsingCookies
+ * using generateClientWithAmplifyInstance for proper server context integration.
+ */
+
+import type { AstroGlobal } from "astro";
+import type { ResourcesConfig } from "aws-amplify";
+import {
+	CommonPublicClientOptions,
+	DefaultCommonClientOptions,
+	V6ClientSSRCookies,
+	generateClientWithAmplifyInstance,
+} from "aws-amplify/api/internals";
+import { getAmplifyServerContext } from "aws-amplify/adapter-core/internals";
+import { createRunWithAmplifyServerContext, createLogger } from "@htlkg/core/amplify-astro-adapter";
+
+const log = createLogger('server-client');
+
+interface AstroCookiesClientParams {
+	cookies: AstroGlobal["cookies"];
+	request: AstroGlobal["request"];
+	config: ResourcesConfig;
+}
+
+/**
+ * Generates a server-side data client for Astro (matches Next.js implementation)
+ *
+ * This function creates a client that automatically wraps all operations in the Amplify server context,
+ * ensuring that authentication tokens from cookies are properly used.
+ *
+ * @example
+ * ```typescript
+ * import type { Schema } from '../amplify/data/resource';
+ * import { generateServerClientUsingCookies } from '@htlkg/data/client';
+ * import { parseAmplifyConfig } from 'aws-amplify/utils';
+ * import outputs from '../amplify_outputs.json';
+ *
+ * const amplifyConfig = parseAmplifyConfig(outputs);
+ *
+ * const client = generateServerClientUsingCookies<Schema>({
+ *   config: amplifyConfig,
+ *   cookies: Astro.cookies,
+ *   request: Astro.request,
+ * });
+ *
+ * // Use the client directly - operations are automatically wrapped
+ * const result = await client.models.User.list({
+ *   selectionSet: ['id', 'email'],
+ *   limit: 100,
+ * });
+ * ```
+ */
+export function generateServerClientUsingCookies<
+	T extends Record<any, any> = never,
+	Options extends CommonPublicClientOptions &
+		AstroCookiesClientParams = DefaultCommonClientOptions &
+		AstroCookiesClientParams,
+>(options: Options): V6ClientSSRCookies<T, Options> {
+	const runWithAmplifyServerContext = createRunWithAmplifyServerContext({
+		config: options.config,
+	});
+
+	const resourcesConfig = options.config;
+
+	// This function reference gets passed down to InternalGraphQLAPI.ts.graphql
+	// where this._graphql is passed in as the `fn` argument
+	// causing it to always get invoked inside `runWithAmplifyServerContext`
+	const getAmplify = (fn: (amplify: any) => Promise<any>) => {
+		return runWithAmplifyServerContext({
+			astroServerContext: {
+				cookies: options.cookies,
+				request: options.request,
+			},
+			operation: async (contextSpec: any) => {
+				const amplifyInstance = getAmplifyServerContext(contextSpec).amplify;
+				
+				// Debug logging (only when DEBUG=true)
+				try {
+					const config = amplifyInstance.getConfig();
+					log.debug('Amplify config from instance:', {
+						hasAPI: !!config.API,
+						hasGraphQL: !!config.API?.GraphQL,
+						endpoint: config.API?.GraphQL?.endpoint,
+						defaultAuthMode: config.API?.GraphQL?.defaultAuthMode,
+						region: config.API?.GraphQL?.region,
+					});
+					
+					const session = await amplifyInstance.Auth.fetchAuthSession();
+					log.debug('Auth session:', {
+						hasTokens: !!session.tokens,
+						hasAccessToken: !!session.tokens?.accessToken,
+						hasIdToken: !!session.tokens?.idToken,
+						hasCredentials: !!session.credentials,
+					});
+				} catch (e: any) {
+					log.debug('Error fetching session:', e.message);
+				}
+				
+				return fn(amplifyInstance);
+			},
+		});
+	};
+
+	const {
+		cookies: _cookies,
+		request: _request,
+		config: _config,
+		...params
+	} = options;
+
+	return generateClientWithAmplifyInstance<T, V6ClientSSRCookies<T, Options>>({
+		amplify: getAmplify,
+		config: resourcesConfig,
+		...params,
+	} as any);
+}

package/src/content-collections/content-collections.md

@@ -0,0 +1,87 @@
+# Content Collections Module
+
+Astro content collection generators and schema definitions for static content.
+
+## Installation
+
+```typescript
+import { 
+  generateCollections,
+  syncCollections,
+  contentSchemas,
+} from '@htlkg/data/content-collections';
+```
+
+## Overview
+
+This module provides utilities for generating Astro content collections from external data sources, enabling static site generation with dynamic content.
+
+## Schemas
+
+Pre-defined Zod schemas for content types:
+
+```typescript
+import { contentSchemas } from '@htlkg/data/content-collections';
+
+// Brand content schema
+const brandSchema = contentSchemas.brand;
+
+// Product content schema  
+const productSchema = contentSchemas.product;
+
+// Documentation schema
+const docSchema = contentSchemas.doc;
+```
+
+## Generator
+
+Generate content collection files from API data:
+
+```typescript
+import { generateCollections } from '@htlkg/data/content-collections';
+
+await generateCollections({
+  outputDir: './src/content',
+  collections: ['brands', 'products'],
+  client: amplifyClient,
+});
+```
+
+## Sync
+
+Synchronize content collections with remote data:
+
+```typescript
+import { syncCollections } from '@htlkg/data/content-collections';
+
+// In a build script or CI
+await syncCollections({
+  collections: ['brands'],
+  force: true, // Overwrite existing
+});
+```
+
+## Usage in Astro
+
+```typescript
+// src/content/config.ts
+import { defineCollection } from 'astro:content';
+import { contentSchemas } from '@htlkg/data/content-collections';
+
+export const collections = {
+  brands: defineCollection({
+    type: 'data',
+    schema: contentSchemas.brand,
+  }),
+};
+```
+
+```astro
+---
+// src/pages/brands/[id].astro
+import { getCollection, getEntry } from 'astro:content';
+
+const brands = await getCollection('brands');
+const brand = await getEntry('brands', Astro.params.id);
+---
+```