@htlkg/core 0.0.1 → 0.0.3

package/dist/utils/index.d.ts

@@ -1,7 +1,10 @@
+export { c as createLogger, l as logger } from '../logger-BTW3fOeM.js';
+
 /**
  * @htlkg/core/utils
  * Core utility functions for Hotelinking applications
  */
+
 /**
  * Format a date to a localized string
  * @param date - Date to format

package/dist/utils/index.js

@@ -1,3 +1,56 @@
+// src/utils/logger.ts
+var isDebugEnabled = () => {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.DEBUG === "true" || process.env.HTLKG_DEBUG === "true" || process.env.DEBUG === "*";
+  }
+  try {
+    if (typeof import.meta !== "undefined" && import.meta.env) {
+      return import.meta.env.DEBUG === "true" || // @ts-ignore
+      import.meta.env.HTLKG_DEBUG === "true" || // @ts-ignore
+      import.meta.env.DEV === true;
+    }
+  } catch {
+  }
+  return false;
+};
+var formatMessage = (namespace, message) => {
+  return `[${namespace}] ${message}`;
+};
+var logger = {
+  /**
+   * Debug log - only shown when DEBUG=true
+   */
+  debug(namespace, message, ...args) {
+    if (isDebugEnabled()) {
+      console.log(formatMessage(namespace, message), ...args);
+    }
+  },
+  /**
+   * Info log - always shown
+   */
+  info(namespace, message, ...args) {
+    console.info(formatMessage(namespace, message), ...args);
+  },
+  /**
+   * Warning log - always shown
+   */
+  warn(namespace, message, ...args) {
+    console.warn(formatMessage(namespace, message), ...args);
+  },
+  /**
+   * Error log - always shown
+   */
+  error(namespace, message, ...args) {
+    console.error(formatMessage(namespace, message), ...args);
+  }
+};
+var createLogger = (namespace) => ({
+  debug: (message, ...args) => logger.debug(namespace, message, ...args),
+  info: (message, ...args) => logger.info(namespace, message, ...args),
+  warn: (message, ...args) => logger.warn(namespace, message, ...args),
+  error: (message, ...args) => logger.error(namespace, message, ...args)
+});
+
 // src/utils/index.ts
 function formatDate(date, locale = "en-US", options = {
   year: "numeric",
@@ -49,9 +102,11 @@ function throttle(fn, limit) {
   };
 }
 export {
+  createLogger,
   debounce,
   formatDate,
   groupBy,
+  logger,
   throttle,
   truncateText
 };

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/index.ts"],"sourcesContent":["/**\n * @htlkg/core/utils\n * Core utility functions for Hotelinking applications\n */\n\n/**\n * Format a date to a localized string\n * @param date - Date to format\n * @param locale - Locale string (default: 'en-US')\n * @param options - Intl.DateTimeFormatOptions\n * @returns Formatted date string\n */\nexport function formatDate(\n\tdate: Date | string | number,\n\tlocale = \"en-US\",\n\toptions: Intl.DateTimeFormatOptions = {\n\t\tyear: \"numeric\",\n\t\tmonth: \"short\",\n\t\tday: \"numeric\",\n\t},\n): string {\n\tconst dateObj = typeof date === \"string\" || typeof date === \"number\" ? new Date(date) : date;\n\treturn new Intl.DateTimeFormat(locale, options).format(dateObj);\n}\n\n/**\n * Truncate text to a maximum length with ellipsis\n * @param text - Text to truncate\n * @param maxLength - Maximum length before truncation\n * @param suffix - Suffix to append (default: '...')\n * @returns Truncated text\n */\nexport function truncateText(\n\ttext: string,\n\tmaxLength: number,\n\tsuffix = \"...\",\n): string {\n\tif (text.length <= maxLength) return text;\n\treturn text.slice(0, maxLength - suffix.length) + suffix;\n}\n\n/**\n * Group an array of items by a key\n * @param items - Array of items to group\n * @param keyFn - Function to extract the grouping key\n * @returns Object with keys as group names and values as arrays of items\n */\nexport function groupBy<T>(\n\titems: T[],\n\tkeyFn: (item: T) => string | number,\n): Record<string | number, T[]> {\n\treturn items.reduce(\n\t\t(groups, item) => {\n\t\t\tconst key = keyFn(item);\n\t\t\tif (!groups[key]) {\n\t\t\t\tgroups[key] = [];\n\t\t\t}\n\t\t\tgroups[key].push(item);\n\t\t\treturn groups;\n\t\t},\n\t\t{} as Record<string | number, T[]>,\n\t);\n}\n\n/**\n * Debounce a function call\n * @param fn - Function to debounce\n * @param delay - Delay in milliseconds\n * @returns Debounced function\n */\nexport function debounce<T extends (...args: any[]) => any>(\n\tfn: T,\n\tdelay: number,\n): (...args: Parameters<T>) => void {\n\tlet timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n\treturn function debounced(...args: Parameters<T>) {\n\t\tif (timeoutId !== null) {\n\t\t\tclearTimeout(timeoutId);\n\t\t}\n\t\ttimeoutId = setTimeout(() => {\n\t\t\tfn(...args);\n\t\t\ttimeoutId = null;\n\t\t}, delay);\n\t};\n}\n\n/**\n * Throttle a function call\n * @param fn - Function to throttle\n * @param limit - Minimum time between calls in milliseconds\n * @returns Throttled function\n */\nexport function throttle<T extends (...args: any[]) => any>(\n\tfn: T,\n\tlimit: number,\n): (...args: Parameters<T>) => void {\n\tlet inThrottle = false;\n\n\treturn function throttled(...args: Parameters<T>) {\n\t\tif (!inThrottle) {\n\t\t\tfn(...args);\n\t\t\tinThrottle = true;\n\t\t\tsetTimeout(() => {\n\t\t\t\tinThrottle = false;\n\t\t\t}, limit);\n\t\t}\n\t};\n}\n"],"mappings":";AAYO,SAAS,WACf,MACA,SAAS,SACT,UAAsC;AAAA,EACrC,MAAM;AAAA,EACN,OAAO;AAAA,EACP,KAAK;AACN,GACS;AACT,QAAM,UAAU,OAAO,SAAS,YAAY,OAAO,SAAS,WAAW,IAAI,KAAK,IAAI,IAAI;AACxF,SAAO,IAAI,KAAK,eAAe,QAAQ,OAAO,EAAE,OAAO,OAAO;AAC/D;AASO,SAAS,aACf,MACA,WACA,SAAS,OACA;AACT,MAAI,KAAK,UAAU,UAAW,QAAO;AACrC,SAAO,KAAK,MAAM,GAAG,YAAY,OAAO,MAAM,IAAI;AACnD;AAQO,SAAS,QACf,OACA,OAC+B;AAC/B,SAAO,MAAM;AAAA,IACZ,CAAC,QAAQ,SAAS;AACjB,YAAM,MAAM,MAAM,IAAI;AACtB,UAAI,CAAC,OAAO,GAAG,GAAG;AACjB,eAAO,GAAG,IAAI,CAAC;AAAA,MAChB;AACA,aAAO,GAAG,EAAE,KAAK,IAAI;AACrB,aAAO;AAAA,IACR;AAAA,IACA,CAAC;AAAA,EACF;AACD;AAQO,SAAS,SACf,IACA,OACmC;AACnC,MAAI,YAAkD;AAEtD,SAAO,SAAS,aAAa,MAAqB;AACjD,QAAI,cAAc,MAAM;AACvB,mBAAa,SAAS;AAAA,IACvB;AACA,gBAAY,WAAW,MAAM;AAC5B,SAAG,GAAG,IAAI;AACV,kBAAY;AAAA,IACb,GAAG,KAAK;AAAA,EACT;AACD;AAQO,SAAS,SACf,IACA,OACmC;AACnC,MAAI,aAAa;AAEjB,SAAO,SAAS,aAAa,MAAqB;AACjD,QAAI,CAAC,YAAY;AAChB,SAAG,GAAG,IAAI;AACV,mBAAa;AACb,iBAAW,MAAM;AAChB,qBAAa;AAAA,MACd,GAAG,KAAK;AAAA,IACT;AAAA,EACD;AACD;","names":[]}
+{"version":3,"sources":["../../src/utils/logger.ts","../../src/utils/index.ts"],"sourcesContent":["/**\n * Simple debug logger utility\n * \n * Debug logs are only shown when DEBUG=true or HTLKG_DEBUG=true is set in environment.\n * Info logs are always shown.\n * \n * @example\n * ```typescript\n * import { logger } from '@htlkg/core/utils/logger';\n * \n * logger.debug('server-client', 'Detailed debug info', { data });\n * logger.info('server-client', 'Important info message');\n * logger.warn('server-client', 'Warning message');\n * logger.error('server-client', 'Error occurred', error);\n * ```\n */\n\ntype LogLevel = 'debug' | 'info' | 'warn' | 'error';\n\nconst isDebugEnabled = (): boolean => {\n  // Check Node.js environment variables\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env.DEBUG === 'true' || \n           process.env.HTLKG_DEBUG === 'true' ||\n           process.env.DEBUG === '*';\n  }\n  // Browser/Vite environment - check for DEV mode\n  try {\n    // @ts-ignore - import.meta.env is Vite-specific\n    if (typeof import.meta !== 'undefined' && import.meta.env) {\n      // @ts-ignore\n      return import.meta.env.DEBUG === 'true' || \n             // @ts-ignore\n             import.meta.env.HTLKG_DEBUG === 'true' ||\n             // @ts-ignore\n             import.meta.env.DEV === true;\n    }\n  } catch {\n    // Ignore errors accessing import.meta\n  }\n  return false;\n};\n\nconst formatMessage = (namespace: string, message: string): string => {\n  return `[${namespace}] ${message}`;\n};\n\nexport const logger = {\n  /**\n   * Debug log - only shown when DEBUG=true\n   */\n  debug(namespace: string, message: string, ...args: unknown[]): void {\n    if (isDebugEnabled()) {\n      console.log(formatMessage(namespace, message), ...args);\n    }\n  },\n\n  /**\n   * Info log - always shown\n   */\n  info(namespace: string, message: string, ...args: unknown[]): void {\n    console.info(formatMessage(namespace, message), ...args);\n  },\n\n  /**\n   * Warning log - always shown\n   */\n  warn(namespace: string, message: string, ...args: unknown[]): void {\n    console.warn(formatMessage(namespace, message), ...args);\n  },\n\n  /**\n   * Error log - always shown\n   */\n  error(namespace: string, message: string, ...args: unknown[]): void {\n    console.error(formatMessage(namespace, message), ...args);\n  },\n};\n\n/**\n * Create a namespaced logger for a specific module\n */\nexport const createLogger = (namespace: string) => ({\n  debug: (message: string, ...args: unknown[]) => logger.debug(namespace, message, ...args),\n  info: (message: string, ...args: unknown[]) => logger.info(namespace, message, ...args),\n  warn: (message: string, ...args: unknown[]) => logger.warn(namespace, message, ...args),\n  error: (message: string, ...args: unknown[]) => logger.error(namespace, message, ...args),\n});\n","/**\n * @htlkg/core/utils\n * Core utility functions for Hotelinking applications\n */\n\n// Logger utility\nexport { logger, createLogger } from './logger';\n\n/**\n * Format a date to a localized string\n * @param date - Date to format\n * @param locale - Locale string (default: 'en-US')\n * @param options - Intl.DateTimeFormatOptions\n * @returns Formatted date string\n */\nexport function formatDate(\n\tdate: Date | string | number,\n\tlocale = \"en-US\",\n\toptions: Intl.DateTimeFormatOptions = {\n\t\tyear: \"numeric\",\n\t\tmonth: \"short\",\n\t\tday: \"numeric\",\n\t},\n): string {\n\tconst dateObj = typeof date === \"string\" || typeof date === \"number\" ? new Date(date) : date;\n\treturn new Intl.DateTimeFormat(locale, options).format(dateObj);\n}\n\n/**\n * Truncate text to a maximum length with ellipsis\n * @param text - Text to truncate\n * @param maxLength - Maximum length before truncation\n * @param suffix - Suffix to append (default: '...')\n * @returns Truncated text\n */\nexport function truncateText(\n\ttext: string,\n\tmaxLength: number,\n\tsuffix = \"...\",\n): string {\n\tif (text.length <= maxLength) return text;\n\treturn text.slice(0, maxLength - suffix.length) + suffix;\n}\n\n/**\n * Group an array of items by a key\n * @param items - Array of items to group\n * @param keyFn - Function to extract the grouping key\n * @returns Object with keys as group names and values as arrays of items\n */\nexport function groupBy<T>(\n\titems: T[],\n\tkeyFn: (item: T) => string | number,\n): Record<string | number, T[]> {\n\treturn items.reduce(\n\t\t(groups, item) => {\n\t\t\tconst key = keyFn(item);\n\t\t\tif (!groups[key]) {\n\t\t\t\tgroups[key] = [];\n\t\t\t}\n\t\t\tgroups[key].push(item);\n\t\t\treturn groups;\n\t\t},\n\t\t{} as Record<string | number, T[]>,\n\t);\n}\n\n/**\n * Debounce a function call\n * @param fn - Function to debounce\n * @param delay - Delay in milliseconds\n * @returns Debounced function\n */\nexport function debounce<T extends (...args: any[]) => any>(\n\tfn: T,\n\tdelay: number,\n): (...args: Parameters<T>) => void {\n\tlet timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n\treturn function debounced(...args: Parameters<T>) {\n\t\tif (timeoutId !== null) {\n\t\t\tclearTimeout(timeoutId);\n\t\t}\n\t\ttimeoutId = setTimeout(() => {\n\t\t\tfn(...args);\n\t\t\ttimeoutId = null;\n\t\t}, delay);\n\t};\n}\n\n/**\n * Throttle a function call\n * @param fn - Function to throttle\n * @param limit - Minimum time between calls in milliseconds\n * @returns Throttled function\n */\nexport function throttle<T extends (...args: any[]) => any>(\n\tfn: T,\n\tlimit: number,\n): (...args: Parameters<T>) => void {\n\tlet inThrottle = false;\n\n\treturn function throttled(...args: Parameters<T>) {\n\t\tif (!inThrottle) {\n\t\t\tfn(...args);\n\t\t\tinThrottle = true;\n\t\t\tsetTimeout(() => {\n\t\t\t\tinThrottle = false;\n\t\t\t}, limit);\n\t\t}\n\t};\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,34 +1,57 @@
 {
-	"name": "@htlkg/core",
-	"version": "0.0.1",
-	"type": "module",
-	"exports": {
-		".": "./dist/index.js",
-		"./auth": "./dist/auth/index.js",
-		"./types": "./dist/types/index.js",
-		"./utils": "./dist/utils/index.js",
-		"./constants": "./dist/constants/index.js",
-		"./errors": "./dist/errors/index.js"
-	},
-	"files": [
-		"dist"
-	],
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"test": "vitest run",
-		"test:watch": "vitest"
-	},
-	"dependencies": {
-		"aws-amplify": "^6.15.7"
-	},
-	"devDependencies": {
-		"astro": "^5.14.7",
-		"tsup": "^8.0.0",
-		"typescript": "^5.9.2",
-		"vitest": "^3.2.4"
-	},
-	"publishConfig": {
-		"access": "restricted"
-	}
-}
+  "name": "@htlkg/core",
+  "version": "0.0.3",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth/index.js",
+      "types": "./dist/auth/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    },
+    "./constants": {
+      "import": "./dist/constants/index.js",
+      "types": "./dist/constants/index.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/errors/index.js",
+      "types": "./dist/errors/index.d.ts"
+    },
+    "./amplify-astro-adapter": {
+      "import": "./dist/amplify-astro-adapter/index.js",
+      "types": "./dist/amplify-astro-adapter/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "aws-amplify": "^6.15.7"
+  },
+  "devDependencies": {
+    "astro": "^5.14.7",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/amplify-astro-adapter/amplify-astro-adapter.md

@@ -0,0 +1,167 @@
+# Amplify Astro Adapter
+
+Server-side authentication support for Astro applications using AWS Amplify. Handles cookie-based authentication context for SSR.
+
+## Installation
+
+```typescript
+import { 
+  createRunWithAmplifyServerContext,
+  createCookieStorageAdapterFromAstroContext,
+  globalSettings 
+} from '@htlkg/core/amplify-astro-adapter';
+```
+
+## Core Functions
+
+### createRunWithAmplifyServerContext
+
+Creates a function that runs operations within an authenticated Amplify server context.
+
+```typescript
+import { Amplify } from 'aws-amplify';
+import { createRunWithAmplifyServerContext, globalSettings } from '@htlkg/core/amplify-astro-adapter';
+
+const amplifyConfig = Amplify.getConfig();
+
+const runWithAmplifyServerContext = createRunWithAmplifyServerContext({
+  config: amplifyConfig,
+  globalSettings, // Pass explicitly to avoid module singleton issues
+});
+
+// Use in Astro page or API route
+const result = await runWithAmplifyServerContext({
+  astroServerContext: {
+    cookies: Astro.cookies,
+    request: Astro.request,
+  },
+  operation: async (contextSpec) => {
+    // Perform authenticated operations
+    const user = await getCurrentUser(contextSpec);
+    return user;
+  },
+});
+```
+
+### createCookieStorageAdapterFromAstroContext
+
+Creates a cookie storage adapter compatible with Amplify's auth system.
+
+```typescript
+import { createCookieStorageAdapterFromAstroContext } from '@htlkg/core/amplify-astro-adapter';
+
+const cookieAdapter = await createCookieStorageAdapterFromAstroContext({
+  cookies: Astro.cookies,
+  request: Astro.request,
+});
+
+// Adapter methods
+cookieAdapter.get('cookie-name');
+cookieAdapter.getAll();
+cookieAdapter.set('name', 'value', options);
+cookieAdapter.delete('name');
+```
+
+### globalSettings
+
+Runtime configuration for the adapter.
+
+```typescript
+import { globalSettings } from '@htlkg/core/amplify-astro-adapter';
+
+// Enable server-side auth (enabled by default)
+globalSettings.enableServerSideAuth();
+
+// Check if SSL origin (affects secure cookie flag)
+globalSettings.setIsSSLOrigin(true);
+
+// Set custom cookie options
+globalSettings.setRuntimeOptions({
+  cookies: {
+    domain: '.example.com',
+    sameSite: 'lax',
+  },
+});
+```
+
+## Error Handling
+
+The adapter provides specific error classes for different failure scenarios:
+
+```typescript
+import { 
+  AmplifyAstroAdapterError,
+  ErrorCodes,
+  createAuthFailedError,
+  createCookieError,
+  createConfigMissingError,
+} from '@htlkg/core/amplify-astro-adapter';
+
+try {
+  // ... adapter operations
+} catch (error) {
+  if (error instanceof AmplifyAstroAdapterError) {
+    console.error(`[${error.code}] ${error.message}`);
+    if (error.recoverySuggestion) {
+      console.log('Suggestion:', error.recoverySuggestion);
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `CONFIG_MISSING` | Amplify configuration not found |
+| `AUTH_FAILED` | Authentication failed |
+| `COOKIE_ERROR` | Cookie read/write error |
+| `GRAPHQL_ERROR` | GraphQL operation failed |
+| `CONTEXT_CREATION_FAILED` | Server context creation failed |
+| `TOKEN_REFRESH_FAILED` | Token refresh failed |
+
+## Types
+
+```typescript
+import type { AstroServer, AstroAmplifyConfig } from '@htlkg/core/amplify-astro-adapter';
+
+// Server context types
+type ServerContext = AstroServer.AstroComponentContext | AstroServer.APIEndpointContext | null;
+
+// Runtime options
+interface RuntimeOptions {
+  cookies?: RuntimeCookieOptions;
+}
+
+// Run operation signature
+type RunOperationWithContext = <T>(input: {
+  astroServerContext: ServerContext;
+  operation: (contextSpec: unknown) => Promise<T>;
+}) => Promise<T>;
+```
+
+## Cookie Handling
+
+The adapter handles Cognito authentication cookies with:
+
+- Automatic encoding compatible with js-cookie
+- Secure defaults (`httpOnly`, `sameSite: 'lax'`, `secure` based on SSL)
+- Support for both Astro component and API endpoint contexts
+
+## Debug Logging
+
+Enable debug logs by setting environment variables:
+
+```bash
+DEBUG=true
+# or
+HTLKG_DEBUG=true
+```
+
+```typescript
+import { createLogger } from '@htlkg/core/amplify-astro-adapter';
+
+const log = createLogger('my-module');
+log.debug('Debug message'); // Only shown when DEBUG=true
+log.info('Info message');   // Always shown
+```

package/src/amplify-astro-adapter/createCookieStorageAdapterFromAstroContext.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi } from "vitest";
+import { createCookieStorageAdapterFromAstroContext } from "./createCookieStorageAdapterFromAstroContext";
+import type { AstroServer } from "./types";
+
+describe("createCookieStorageAdapterFromAstroContext", () => {
+	describe("with null context", () => {
+		it("should return a no-op adapter", async () => {
+			const adapter = await createCookieStorageAdapterFromAstroContext(null as any);
+
+			expect(adapter.get("test")).toBeUndefined();
+			expect(adapter.getAll()).toEqual([]);
+			
+			// These should not throw
+			adapter.set("test", "value");
+			adapter.delete("test");
+		});
+	});
+
+	describe("with valid context", () => {
+		it("should get cookie from Astro cookies", async () => {
+			const mockCookies = {
+				get: vi.fn((name: string) => ({ name, value: "cookie-value" })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "cookie-value" });
+			expect(mockCookies.get).toHaveBeenCalledWith("test");
+		});
+
+		it("should get cookie from request headers if not in Astro cookies", async () => {
+			// When cookies.get returns an object without value property, it falls back to headers
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "test=header-value; other=value2" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "header-value" });
+		});
+
+		it("should handle URL-encoded cookie values", async () => {
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "test=hello%20world" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "hello world" });
+		});
+
+		it("should get all cookies from getAll method", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				getAll: vi.fn(() => [
+					{ name: "cookie1", value: "value1" },
+					{ name: "cookie2", value: "value2" },
+				]),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.getAll();
+
+			expect(result).toEqual([
+				{ name: "cookie1", value: "value1" },
+				{ name: "cookie2", value: "value2" },
+			]);
+		});
+
+		it("should get all cookies from headers when getAll is not available", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+				// No getAll method
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "cookie1=value1; cookie2=value2" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.getAll();
+
+			expect(result).toEqual([
+				{ name: "cookie1", value: "value1" },
+				{ name: "cookie2", value: "value2" },
+			]);
+		});
+
+		it("should set cookie with options", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			adapter.set("test", "value", {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+			});
+
+			expect(mockCookies.set).toHaveBeenCalledWith("test", "value", {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+			});
+		});
+
+		it("should map sameSite boolean values", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// sameSite: true -> 'strict'
+			adapter.set("test1", "value1", { sameSite: true as any });
+			expect(mockCookies.set).toHaveBeenCalledWith("test1", "value1", {
+				sameSite: "strict",
+			});
+
+			// sameSite: false -> 'lax'
+			adapter.set("test2", "value2", { sameSite: false as any });
+			expect(mockCookies.set).toHaveBeenCalledWith("test2", "value2", {
+				sameSite: "lax",
+			});
+		});
+
+		it("should delete cookie", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			adapter.delete("test");
+
+			expect(mockCookies.delete).toHaveBeenCalledWith("test");
+		});
+
+		it("should handle errors gracefully when setting cookies", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(() => {
+					throw new Error("Cookie error");
+				}),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// Should not throw
+			expect(() => adapter.set("test", "value")).not.toThrow();
+		});
+
+		it("should handle errors gracefully when deleting cookies", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(() => {
+					throw new Error("Delete error");
+				}),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// Should not throw
+			expect(() => adapter.delete("test")).not.toThrow();
+		});
+
+		it("should return undefined when cookie not found anywhere", async () => {
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("nonexistent");
+
+			expect(result).toBeUndefined();
+		});
+	});
+});