more-apartments-astro-integration 1.5.10 → 2.0.2

package/README.md

@@ -24,6 +24,98 @@ yarn add @shelfwood/more-apartments-astro-integration
 bun add @shelfwood/more-apartments-astro-integration
 ```
 
+## Build Process & Type Generation
+
+### How Types are Generated
+
+This package provides fully-typed API clients generated from the Laravel backend's OpenAPI specification. The types are **not committed to git** and are instead generated during the build process.
+
+#### CI/CD Build Process (Automated)
+
+When you install or publish this package, the build automatically:
+
+1. **Fetches OpenAPI Spec** from GitHub Releases (latest **stable/production** spec from Laravel backend)
+2. **Generates TypeScript Types** using `openapi-typescript`
+3. **Generates Zod Schemas** for runtime validation
+4. **Builds Package** with all generated types included
+
+```bash
+# This happens automatically during:
+npm install @shelfwood/more-apartments-astro-integration
+
+# Or when publishing:
+npm publish  # Runs prepublishOnly hook
+```
+
+**Environment-Specific Fetching:**
+
+The package supports fetching from different release channels:
+
+```bash
+# Production (stable releases only - default)
+bun run fetch:spec
+
+# Staging (pre-release/staging builds)
+bun run fetch:spec:staging
+```
+
+**How it works:**
+- **Production:** Fetches from `releases/latest` (stable releases only, excludes pre-releases)
+- **Staging:** Fetches from latest pre-release tagged with `staging-*`
+
+#### Local Development Workflow
+
+For local development when you have the Laravel project available:
+
+```bash
+# Clone both repositories side-by-side:
+# ~/projects/prj-more-apartments
+# ~/projects/more-apartments-astro-integration
+
+cd more-apartments-astro-integration
+
+# Generate types from local Laravel project
+bun run generate:types
+
+# Or use watch mode for automatic regeneration
+bun run dev:local
+```
+
+**Custom Laravel project path:**
+
+```bash
+# If your Laravel project is elsewhere
+MORE_APARTMENTS_PROJECT_PATH=~/custom/path/to/laravel bun run generate:types
+```
+
+#### Manual Type Generation (Advanced)
+
+You can also manually fetch and generate types:
+
+```bash
+# 1. Fetch latest OpenAPI spec from GitHub Releases
+bun run fetch:spec
+
+# 2. Generate TypeScript types from fetched spec
+bun run generate:types:local
+
+# 3. Generate Zod validation schemas
+bun run generate:schemas
+
+# 4. Build package
+bun run build
+```
+
+### Generated Files (Gitignored)
+
+The following files are generated during build and **excluded from git**:
+
+- `.openapi/api-v1.json` - OpenAPI specification (fetched from GitHub Releases)
+- `src/types/generated/api.d.ts` - TypeScript type definitions
+- `src/types/generated/schemas.ts` - Zod validation schemas
+
+These files are automatically generated, so you'll never see them in pull requests or git diffs.
+
 ## CLI Usage
 
 The package includes a powerful CLI for interacting with the More Apartments API directly from the command line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "more-apartments-astro-integration",
-  "version": "1.5.10",
+  "version": "2.0.2",
   "description": "Astro integration for More Apartments REST API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "routes",
+    "scripts",
     "src/components",
     "src/pages",
     ".more-apartments"
@@ -28,12 +29,15 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "prepublishOnly": "bun run build",
+    "prepublishOnly": "bun run fetch:spec && bun run generate:types:local && bun run generate:schemas && bun run build",
+    "fetch:spec": "mkdir -p .openapi && gh release download --repo Feelgood-Apartments/prj-more-apartments --pattern 'api-v1.json' --output .openapi/api-v1.json --clobber || (echo '❌ Failed to fetch OpenAPI spec from GitHub Releases (production)' && exit 1)",
+    "fetch:spec:staging": "node scripts/fetch-staging-spec.mjs",
     "generate:types": "node scripts/generate-types.mjs",
-    "generate:types:skip-export": "node scripts/generate-types.mjs --skip-export",
+    "generate:types:local": "openapi-typescript .openapi/api-v1.json -o src/types/generated/api.d.ts",
     "generate:schemas": "node scripts/generate-zod-schemas.mjs",
     "validate:schemas": "bun scripts/validate-schemas.mjs",
     "detect:breaking": "node scripts/detect-breaking-changes.mjs",
+    "dev:local": "MORE_APARTMENTS_PROJECT_PATH=../prj-more-apartments node scripts/generate-types.mjs && tsup --watch",
     "test": "node test-runner.js all",
     "test:watch": "vitest",
     "test:unit": "node test-runner.js unit",

package/scripts/detect-breaking-changes.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * Detect breaking changes by comparing OpenAPI specs
+ * Suggests appropriate version bump (major/minor/patch)
+ *
+ * This script analyzes differences between the current and previous
+ * OpenAPI specifications to determine if breaking changes have been
+ * introduced, helping maintain proper semantic versioning.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const CURRENT_SPEC = resolve(__dirname, '../.openapi/api-v1.json');
+const PREVIOUS_SPEC = resolve(__dirname, '../.openapi/api-v1.previous.json');
+
+async function analyzeChanges() {
+  console.log('🔍 Analyzing API changes for breaking compatibility...\n');
+
+  if (!existsSync(CURRENT_SPEC)) {
+    console.error('❌ Current OpenAPI spec not found:', CURRENT_SPEC);
+    console.log('SUGGESTED_BUMP=patch');
+    process.exit(0);
+  }
+
+  if (!existsSync(PREVIOUS_SPEC)) {
+    console.log('📝 No previous spec found. This appears to be a new version.');
+    console.log('   Future runs will compare against this spec.');
+    console.log('\nSUGGESTED_BUMP=minor');
+
+    // Set output for GitHub Actions
+    if (process.env.GITHUB_OUTPUT) {
+      const { appendFileSync } = await import('fs');
+      appendFileSync(process.env.GITHUB_OUTPUT, 'suggested_bump=minor\n');
+    }
+
+    return;
+  }
+
+  const current = JSON.parse(readFileSync(CURRENT_SPEC, 'utf-8'));
+  const previous = JSON.parse(readFileSync(PREVIOUS_SPEC, 'utf-8'));
+
+  const changes = {
+    breaking: [],
+    additions: [],
+    modifications: [],
+    deprecations: []
+  };
+
+  // 1. Check for removed endpoints
+  for (const path in previous.paths) {
+    if (!current.paths[path]) {
+      changes.breaking.push(`Removed endpoint: ${path}`);
+    }
+  }
+
+  // 2. Check for removed or modified operations
+  for (const path in current.paths) {
+    if (!previous.paths[path]) {
+      changes.additions.push(`New endpoint: ${path}`);
+      continue;
+    }
+
+    for (const method in current.paths[path]) {
+      const currentOp = current.paths[path][method];
+      const previousOp = previous.paths[path]?.[method];
+
+      if (!previousOp) {
+        changes.additions.push(`New method: ${method.toUpperCase()} ${path}`);
+        continue;
+      }
+
+      // 3. Check for parameter changes
+      const prevParams = previousOp.parameters || [];
+      const currParams = currentOp.parameters || [];
+
+      // Check for removed required parameters (BREAKING)
+      for (const prevParam of prevParams) {
+        const stillExists = currParams.find(p => p.name === prevParam.name && p.in === prevParam.in);
+
+        if (!stillExists) {
+          if (prevParam.required) {
+            changes.breaking.push(
+              `Removed required parameter: ${prevParam.name} from ${method.toUpperCase()} ${path}`
+            );
+          } else {
+            changes.modifications.push(
+              `Removed optional parameter: ${prevParam.name} from ${method.toUpperCase()} ${path}`
+            );
+          }
+        } else if (prevParam.required && !stillExists.required) {
+          changes.modifications.push(
+            `Parameter ${prevParam.name} is now optional in ${method.toUpperCase()} ${path}`
+          );
+        }
+      }
+
+      // Check for new required parameters (BREAKING)
+      for (const currParam of currParams) {
+        const existed = prevParams.find(p => p.name === currParam.name && p.in === currParam.in);
+
+        if (!existed && currParam.required) {
+          changes.breaking.push(
+            `New required parameter: ${currParam.name} in ${method.toUpperCase()} ${path}`
+          );
+        } else if (!existed) {
+          changes.additions.push(
+            `New optional parameter: ${currParam.name} in ${method.toUpperCase()} ${path}`
+          );
+        } else if (!existed.required && currParam.required) {
+          changes.breaking.push(
+            `Parameter ${currParam.name} is now required in ${method.toUpperCase()} ${path}`
+          );
+        }
+      }
+
+      // 4. Check for response schema changes (simplified check)
+      if (currentOp.responses && previousOp.responses) {
+        const prev200 = previousOp.responses['200'];
+        const curr200 = currentOp.responses['200'];
+
+        if (prev200 && !curr200) {
+          changes.breaking.push(`Removed 200 response from ${method.toUpperCase()} ${path}`);
+        }
+      }
+    }
+  }
+
+  // Determine version bump based on changes
+  let suggestedBump = 'patch';
+
+  console.log('📊 Change Summary:\n');
+  console.log('─'.repeat(60));
+
+  if (changes.breaking.length > 0) {
+    suggestedBump = 'major';
+    console.log('🚨 BREAKING CHANGES DETECTED:\n');
+    changes.breaking.forEach(c => console.log(`  ❌ ${c}`));
+    console.log('');
+  }
+
+  if (changes.additions.length > 0 && suggestedBump !== 'major') {
+    suggestedBump = 'minor';
+    console.log('✨ New Features:\n');
+    changes.additions.forEach(c => console.log(`  ✅ ${c}`));
+    console.log('');
+  }
+
+  if (changes.modifications.length > 0) {
+    console.log('🔧 Modifications:\n');
+    changes.modifications.forEach(c => console.log(`  📝 ${c}`));
+    console.log('');
+  }
+
+  if (changes.deprecations.length > 0) {
+    console.log('⚠️  Deprecations:\n');
+    changes.deprecations.forEach(c => console.log(`  ⏳ ${c}`));
+    console.log('');
+  }
+
+  console.log('─'.repeat(60));
+  console.log(`\n📦 RECOMMENDED VERSION BUMP: ${suggestedBump.toUpperCase()}`);
+
+  if (suggestedBump === 'major') {
+    console.log('⚠️  This is a MAJOR version bump due to breaking changes.');
+    console.log('   Consumers will need to update their code.');
+  } else if (suggestedBump === 'minor') {
+    console.log('✅ This is a MINOR version bump (new features, backwards compatible).');
+  } else {
+    console.log('✅ This is a PATCH version bump (bug fixes, backwards compatible).');
+  }
+
+  console.log(`\nSUGGESTED_BUMP=${suggestedBump}`);
+
+  // Set output for GitHub Actions
+  if (process.env.GITHUB_OUTPUT) {
+    const { appendFileSync } = await import('fs');
+    appendFileSync(process.env.GITHUB_OUTPUT, `suggested_bump=${suggestedBump}\n`);
+    appendFileSync(process.env.GITHUB_OUTPUT, `breaking_count=${changes.breaking.length}\n`);
+    appendFileSync(process.env.GITHUB_OUTPUT, `feature_count=${changes.additions.length}\n`);
+  }
+
+  // Exit with error code if breaking changes detected (optional strict mode)
+  if (process.argv.includes('--strict') && changes.breaking.length > 0) {
+    console.error('\n❌ Breaking changes detected in strict mode!');
+    process.exit(1);
+  }
+}
+
+analyzeChanges().catch(error => {
+  console.error('❌ Error analyzing changes:', error.message);
+  console.log('\nSUGGESTED_BUMP=patch');
+  process.exit(0);
+});

package/scripts/fetch-staging-spec.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * Fetch OpenAPI spec from GitHub Releases (Staging/Pre-release)
+ *
+ * This script fetches the latest staging pre-release from GitHub Releases.
+ * Staging releases are marked with --prerelease flag and have "staging" in the tag.
+ *
+ * Usage:
+ *   bun run fetch:spec:staging
+ */
+
+import { execSync } from 'child_process';
+import { mkdirSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const GITHUB_REPO = 'Feelgood-Apartments/prj-more-apartments';
+const OPENAPI_DEST = resolve(__dirname, '../.openapi/api-v1.json');
+
+console.log('═══════════════════════════════════════════════');
+console.log('🚀 Fetching Staging OpenAPI Spec');
+console.log('═══════════════════════════════════════════════\n');
+
+try {
+  // Ensure .openapi directory exists
+  const openapiDir = dirname(OPENAPI_DEST);
+  if (!existsSync(openapiDir)) {
+    mkdirSync(openapiDir, { recursive: true });
+  }
+
+  // Get latest staging pre-release tag
+  console.log('📡 Fetching latest staging pre-release from GitHub...');
+
+  const getLatestStagingTag = `gh release list --repo ${GITHUB_REPO} --limit 50 --json tagName,isPrerelease | jq -r '.[] | select(.isPrerelease == true and (.tagName | contains("staging"))) | .tagName' | head -1`;
+
+  let latestTag;
+  try {
+    latestTag = execSync(getLatestStagingTag, { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    console.error('\n❌ Failed to fetch staging release information');
+    console.error('   Make sure you have GitHub CLI (gh) and jq installed:');
+    console.error('   brew install gh jq');
+    console.error('\n   Or use production spec: bun run fetch:spec');
+    process.exit(1);
+  }
+
+  if (!latestTag) {
+    console.error('\n❌ No staging pre-releases found');
+    console.error('   Use production spec instead: bun run fetch:spec');
+    process.exit(1);
+  }
+
+  console.log(`✅ Latest staging release: ${latestTag}`);
+
+  // Download the spec from the staging release
+  console.log('\n📥 Downloading OpenAPI spec...');
+
+  // Use gh CLI for authenticated downloads from private repositories
+  execSync(`gh release download ${latestTag} --repo ${GITHUB_REPO} --pattern "api-v1.json" --output "${OPENAPI_DEST}" --clobber`, {
+    stdio: 'inherit'
+  });
+
+  console.log(`✅ Staging spec downloaded to: ${OPENAPI_DEST}`);
+
+  console.log('\n═══════════════════════════════════════════════');
+  console.log('✨ Staging OpenAPI spec fetched successfully!');
+  console.log('═══════════════════════════════════════════════');
+  console.log(`\n💡 Next steps:`);
+  console.log(`   1. Generate TypeScript types: bun run generate:types:local`);
+  console.log(`   2. Generate Zod schemas: bun run generate:schemas`);
+  console.log(`   3. Build package: bun run build\n`);
+
+} catch (error) {
+  console.error('\n❌ Failed to fetch staging OpenAPI spec');
+  console.error(error.message);
+  process.exit(1);
+}

package/scripts/generate-types.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * Generate TypeScript types from OpenAPI specification (LOCAL DEVELOPMENT ONLY)
+ *
+ * This script is for local development when you have the Laravel project available.
+ * It exports the OpenAPI spec from your local Laravel backend and generates types.
+ *
+ * For CI/CD builds, use the fetch:spec + generate:types:local workflow instead.
+ *
+ * Usage:
+ *   bun run generate:types  (local Laravel export + type generation)
+ *   bun run dev:local       (watch mode for local development)
+ */
+
+import { execSync } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync, mkdirSync, copyFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Configuration
+const LARAVEL_PROJECT_PATH = process.env.MORE_APARTMENTS_PROJECT_PATH || '../prj-more-apartments';
+const OPENAPI_SOURCE = resolve(LARAVEL_PROJECT_PATH, 'api-v1.json');
+const OPENAPI_DEST = resolve(__dirname, '../.openapi/api-v1.json');
+const TYPES_OUTPUT = resolve(__dirname, '../src/types/generated/api.d.ts');
+
+/**
+ * Run a command and log output
+ */
+function run(command, cwd = process.cwd()) {
+  console.log(`\n🔧 Running: ${command}`);
+  console.log(`   Working directory: ${cwd}`);
+
+  try {
+    execSync(command, {
+      cwd,
+      stdio: 'inherit',
+      env: process.env,
+    });
+    return true;
+  } catch (error) {
+    console.error(`\n❌ Command failed: ${command}`);
+    console.error(error.message);
+    return false;
+  }
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  console.log('═══════════════════════════════════════════════');
+  console.log('🚀 Local Development Type Generation');
+  console.log('═══════════════════════════════════════════════\n');
+
+  // Step 1: Export OpenAPI spec from local Laravel project
+  console.log('📤 Step 1: Exporting OpenAPI spec from local Laravel project...');
+
+  const laravelPath = resolve(__dirname, LARAVEL_PROJECT_PATH);
+
+  if (!existsSync(laravelPath)) {
+    console.error(`\n❌ Laravel project not found at: ${laravelPath}`);
+    console.error(`   Expected path: ${laravelPath}`);
+    console.error('\n   For CI/CD builds, use:');
+    console.error('     bun run fetch:spec && bun run generate:types:local');
+    console.error('\n   Set MORE_APARTMENTS_PROJECT_PATH if your Laravel project is elsewhere');
+    process.exit(1);
+  }
+
+  const success = run(`php artisan scramble:export --path=api-v1.json`, laravelPath);
+
+  if (!success) {
+    console.error('\n❌ Failed to export OpenAPI spec from Laravel');
+    process.exit(1);
+  }
+
+  if (!existsSync(OPENAPI_SOURCE)) {
+    console.error(`\n❌ OpenAPI spec not found at: ${OPENAPI_SOURCE}`);
+    process.exit(1);
+  }
+
+  console.log(`✅ OpenAPI spec exported to: ${OPENAPI_SOURCE}`);
+
+  // Step 2: Copy OpenAPI spec to integration package
+  console.log('\n📋 Step 2: Copying OpenAPI spec to integration package...');
+
+  const openapiDir = dirname(OPENAPI_DEST);
+  if (!existsSync(openapiDir)) {
+    mkdirSync(openapiDir, { recursive: true });
+  }
+
+  copyFileSync(OPENAPI_SOURCE, OPENAPI_DEST);
+  console.log(`✅ Copied to: ${OPENAPI_DEST}`);
+
+  // Step 3: Generate TypeScript types
+  console.log('\n🎯 Step 3: Generating TypeScript types...');
+
+  const typesDir = dirname(TYPES_OUTPUT);
+  if (!existsSync(typesDir)) {
+    mkdirSync(typesDir, { recursive: true });
+  }
+
+  const success = run(
+    `npx openapi-typescript ${OPENAPI_DEST} --output ${TYPES_OUTPUT}`,
+    resolve(__dirname, '..')
+  );
+
+  if (!success) {
+    console.error('\n❌ Failed to generate TypeScript types');
+    process.exit(1);
+  }
+
+  if (!existsSync(TYPES_OUTPUT)) {
+    console.error(`\n❌ Generated types not found at: ${TYPES_OUTPUT}`);
+    process.exit(1);
+  }
+
+  console.log(`✅ Types generated at: ${TYPES_OUTPUT}`);
+
+  // Summary
+  console.log('\n═══════════════════════════════════════════════');
+  console.log('✨ Local development types generated!');
+  console.log('═══════════════════════════════════════════════');
+  console.log(`\n📁 Generated files:`);
+  console.log(`   - ${OPENAPI_DEST}`);
+  console.log(`   - ${TYPES_OUTPUT}`);
+  console.log(`\n💡 Next steps:`);
+  console.log(`   1. Generate Zod schemas: bun run generate:schemas`);
+  console.log(`   2. Run tests: bun test`);
+  console.log(`   3. Build package: bun run build`);
+  console.log(`\n🔄 For watch mode: bun run dev:local\n`);
+}
+
+main().catch((error) => {
+  console.error('\n❌ Fatal error:', error);
+  process.exit(1);
+});

package/scripts/generate-zod-schemas.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * Generate Zod schemas from OpenAPI specification
+ *
+ * This script parses the OpenAPI spec and generates:
+ * - Consolidated Zod object schemas for query parameters
+ * - Zod schemas for request/response bodies
+ * - Exports for use in client.ts
+ *
+ * Usage:
+ *   bun run scripts/generate-zod-schemas.mjs
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Configuration
+const OPENAPI_SOURCE = resolve(__dirname, '../.openapi/api-v1.json');
+const OUTPUT_FILE = resolve(__dirname, '../src/types/generated/schemas.ts');
+
+/**
+ * Convert OpenAPI type to Zod schema
+ */
+function openapiTypeToZod(param) {
+  const { schema, required } = param;
+
+  if (!schema) return 'z.unknown()';
+
+  let zodType;
+
+  // Handle OpenAPI 3.1 array type format: ["string", "null"]
+  let type = schema.type;
+  let isNullable = false;
+
+  if (Array.isArray(type)) {
+    isNullable = type.includes('null');
+    type = type.find(t => t !== 'null') || type[0];
+  } else if (schema.nullable) {
+    isNullable = true;
+  }
+
+  // Handle type
+  switch (type) {
+    case 'string':
+      if (schema.format === 'date' || schema.format === 'date-time') {
+        zodType = 'z.string()';
+      } else if (schema.enum) {
+        const enumValues = schema.enum.map(v => `"${v}"`).join(', ');
+        zodType = `z.enum([${enumValues}])`;
+      } else {
+        zodType = 'z.string()';
+      }
+      break;
+
+    case 'integer':
+    case 'number':
+      zodType = 'z.number()';
+      break;
+
+    case 'boolean':
+      zodType = 'z.boolean()';
+      break;
+
+    case 'array':
+      const itemType = schema.items ? openapiTypeToZod({ schema: schema.items, required: true }) : 'z.unknown()';
+      zodType = `z.array(${itemType})`;
+      break;
+
+    case 'object':
+      zodType = 'z.object({})';
+      break;
+
+    default:
+      zodType = 'z.unknown()';
+  }
+
+  // Handle nullable (from array type or nullable property)
+  if (isNullable) {
+    zodType = `${zodType}.nullable()`;
+  }
+
+  // Handle optional (if not required)
+  if (!required) {
+    zodType = `${zodType}.optional()`;
+  }
+
+  return zodType;
+}
+
+/**
+ * Generate schemas from OpenAPI spec
+ */
+function generateSchemas() {
+  console.log('═══════════════════════════════════════════════');
+  console.log('🚀 Zod Schema Generation from OpenAPI');
+  console.log('═══════════════════════════════════════════════\n');
+
+  // Read OpenAPI spec
+  console.log(`📖 Reading OpenAPI spec from: ${OPENAPI_SOURCE}`);
+  const openapi = JSON.parse(readFileSync(OPENAPI_SOURCE, 'utf-8'));
+
+  // Start building output
+  let output = `// Generated by scripts/generate-zod-schemas.mjs
+// DO NOT EDIT MANUALLY - This file is auto-generated from OpenAPI spec
+
+import { z } from 'zod';
+
+`;
+
+  const schemas = [];
+
+  // Process each path/operation
+  for (const [path, pathItem] of Object.entries(openapi.paths)) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) continue;
+
+      const operationId = operation.operationId;
+      if (!operationId) continue;
+
+      // Extract query parameters
+      const queryParams = (operation.parameters || [])
+        .filter(p => p.in === 'query');
+
+      if (queryParams.length > 0) {
+        const schemaName = toCamelCase(operationId) + 'ParamsSchema';
+        const properties = queryParams.map(param => {
+          const zodType = openapiTypeToZod(param);
+          const comment = param.description ? `  // ${param.description}\n` : '';
+          return `${comment}  ${param.name}: ${zodType}`;
+        }).join(',\n');
+
+        const schema = `/**
+ * Query parameters for ${operationId}
+ * Generated from OpenAPI operation: ${method.toUpperCase()} ${path}
+ */
+export const ${schemaName} = z.object({
+${properties}
+});
+
+export type ${toCamelCase(operationId)}Params = z.infer<typeof ${schemaName}>;
+
+`;
+
+        schemas.push(schema);
+        console.log(`✅ Generated schema: ${schemaName} (${queryParams.length} parameters)`);
+      }
+
+      // Extract request body schema
+      if (operation.requestBody?.content?.['application/json']?.schema) {
+        const bodySchema = operation.requestBody.content['application/json'].schema;
+        const schemaName = toCamelCase(operationId) + 'RequestSchema';
+
+        // For now, just reference the schema (detailed generation would go here)
+        if (bodySchema.$ref) {
+          const refName = bodySchema.$ref.split('/').pop();
+          schemas.push(`// Request body schema for ${operationId} references: ${refName}\n`);
+        }
+      }
+    }
+  }
+
+  output += schemas.join('\n');
+
+  // Write output file
+  console.log(`\n📝 Writing schemas to: ${OUTPUT_FILE}`);
+  writeFileSync(OUTPUT_FILE, output, 'utf-8');
+
+  console.log('\n═══════════════════════════════════════════════');
+  console.log('✨ Zod schema generation complete!');
+  console.log('═══════════════════════════════════════════════');
+  console.log(`\n📁 Generated file: ${OUTPUT_FILE}`);
+  console.log(`📊 Total schemas: ${schemas.length}\n`);
+}
+
+/**
+ * Convert string to CamelCase
+ */
+function toCamelCase(str) {
+  return str
+    .split(/[.\-_]/)
+    .map((word, index) =>
+      index === 0
+        ? word.charAt(0).toUpperCase() + word.slice(1)
+        : word.charAt(0).toUpperCase() + word.slice(1)
+    )
+    .join('');
+}
+
+// Run generator
+try {
+  generateSchemas();
+} catch (error) {
+  console.error('\n❌ Fatal error:', error);
+  process.exit(1);
+}

package/scripts/setup-test-api-key.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * Test API Key Setup Script
+ * 
+ * This script automatically generates a test API key from your Laravel project
+ * and configures the integration tests to use it.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const LARAVEL_PROJECT_PATH = '/Users/shelfwood/Projects/prj-more-apartments';
+const INTEGRATION_PROJECT_PATH = __dirname + '/..';
+const ENV_TEST_FILE = path.join(INTEGRATION_PROJECT_PATH, '.env.test.local');
+
+async function setupTestApiKey() {
+  console.log('🔑 Setting up test API key for integration tests...\n');
+
+  try {
+    // Step 1: Check if Laravel project exists
+    console.log('📁 Checking Laravel project...');
+    if (!fs.existsSync(path.join(LARAVEL_PROJECT_PATH, 'artisan'))) {
+      throw new Error(`Laravel project not found at ${LARAVEL_PROJECT_PATH}`);
+    }
+    console.log('✅ Laravel project found\n');
+
+    // Step 2: Generate or get existing API token
+    console.log('🔐 Generating API token...');
+    const command = `cd ${LARAVEL_PROJECT_PATH} && php artisan tinker --execute="
+      \\$user = App\\\\Models\\\\User::firstOrCreate(
+        ['email' => 'test-integration@more-apartments.test'],
+        ['name' => 'Integration Test User', 'password' => bcrypt('password')]
+      );
+      
+      // Remove old test tokens
+      \\$user->tokens()->where('name', 'integration-test')->delete();
+      
+      // Create new token
+      \\$token = \\$user->createToken('integration-test', ['*']);
+      echo 'TOKEN:' . \\$token->plainTextToken;
+    "`;
+
+    const output = execSync(command, { encoding: 'utf8' });
+    
+    // Extract token from output
+    const tokenMatch = output.match(/TOKEN:([a-zA-Z0-9|_-]+)/);
+    if (!tokenMatch) {
+      throw new Error('Failed to extract API token from Laravel output');
+    }
+    
+    const apiToken = tokenMatch[1];
+    console.log('✅ API token generated successfully\n');
+
+    // Step 3: Update .env.test.local file
+    console.log('📝 Updating test environment configuration...');
+    const envContent = `# Auto-generated test environment configuration
+# Generated on: ${new Date().toISOString()}
+
+# Laravel API Configuration
+MORE_APARTMENTS_BASE_URL=http://prj-more-apartments.test
+MORE_APARTMENTS_API_KEY=${apiToken}
+MORE_APARTMENTS_INSTANCE=cheap-gotham-apartments
+
+# Test Configuration
+NODE_ENV=test
+`;
+
+    fs.writeFileSync(ENV_TEST_FILE, envContent);
+    console.log('✅ Environment configuration updated\n');
+
+    // Step 4: Verify API connectivity
+    console.log('🔍 Testing API connectivity...');
+    try {
+      const testCommand = `cd ${INTEGRATION_PROJECT_PATH} && bun run test:integration -- --reporter=dot`;
+      execSync(testCommand, { encoding: 'utf8', stdio: 'pipe' });
+      console.log('✅ Integration tests can now access the API\n');
+    } catch (testError) {
+      // Test might fail for other reasons, but if it's not auth, that's OK
+      if (testError.stdout && testError.stdout.includes('Unauthenticated')) {
+        throw new Error('API token is not working correctly');
+      }
+      console.log('✅ API authentication is working (tests may have other issues)\n');
+    }
+
+    // Step 5: Success message
+    console.log('🎉 Setup complete!');
+    console.log('');
+    console.log('Your integration tests are now configured with:');
+    console.log(`   API Key: ${apiToken.substring(0, 20)}...`);
+    console.log(`   Base URL: http://prj-more-apartments.test`);
+    console.log(`   Instance: cheap-gotham-apartments`);
+    console.log('');
+    console.log('Run integration tests with:');
+    console.log('   bun run test:integration');
+    console.log('');
+
+  } catch (error) {
+    console.error('❌ Setup failed:', error.message);
+    console.log('');
+    console.log('Troubleshooting:');
+    console.log('1. Make sure Laravel is running at http://prj-more-apartments.test');
+    console.log('2. Ensure you can access the Laravel project directory');
+    console.log('3. Try running: cd /Users/shelfwood/Projects/prj-more-apartments && php artisan --version');
+    console.log('');
+    process.exit(1);
+  }
+}
+
+// Run the setup
+setupTestApiKey();

package/scripts/validate-schemas.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+/**
+ * Validate generated Zod schemas
+ * Ensures schemas are syntactically valid and can be instantiated
+ *
+ * This script is run by CI/CD to catch invalid schema generation
+ * before code is committed or published.
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const SCHEMAS_FILE = resolve(__dirname, '../src/types/generated/schemas.ts');
+
+async function validateSchemas() {
+  console.log('🔍 Validating generated Zod schemas...\n');
+
+  try {
+    // 1. Check file exists and has content
+    const content = readFileSync(SCHEMAS_FILE, 'utf-8');
+
+    if (content.length < 100) {
+      console.error('❌ Schemas file is too small (< 100 bytes).');
+      console.error('   Generation may have failed or produced empty output.');
+      process.exit(1);
+    }
+
+    console.log(`✅ File size: ${content.length} bytes`);
+
+    // 2. Import and validate each schema
+    console.log('📦 Loading schemas module...');
+    const module = await import(SCHEMAS_FILE);
+    const schemas = Object.entries(module).filter(([key]) => key.endsWith('Schema'));
+
+    if (schemas.length === 0) {
+      console.error('❌ No schemas found in generated file!');
+      console.error('   Expected exports ending with "Schema"');
+      process.exit(1);
+    }
+
+    console.log(`\n📋 Found ${schemas.length} schemas to validate:\n`);
+
+    let failures = 0;
+    let warnings = 0;
+
+    for (const [name, schema] of schemas) {
+      try {
+        // Test that schema is a valid Zod object
+        if (!schema || typeof schema !== 'object') {
+          console.error(`❌ ${name} - Not a valid object`);
+          failures++;
+          continue;
+        }
+
+        // Check for Zod-specific methods
+        if (typeof schema.safeParse !== 'function') {
+          console.error(`❌ ${name} - Missing safeParse() method (not a Zod schema)`);
+          failures++;
+          continue;
+        }
+
+        // Test that schema can parse (validates structure)
+        const result = schema.safeParse({});
+
+        if (result.success) {
+          // Empty object is valid (all fields optional)
+          console.log(`✅ ${name} - Valid (all fields optional)`);
+        } else if (result.error) {
+          // Schema has required fields (expected)
+          console.log(`✅ ${name} - Valid (has required fields)`);
+        } else {
+          console.warn(`⚠️  ${name} - Unexpected parse result`);
+          warnings++;
+        }
+
+      } catch (error) {
+        console.error(`❌ ${name} - Error: ${error.message}`);
+        failures++;
+      }
+    }
+
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`Total schemas: ${schemas.length}`);
+    console.log(`Valid: ${schemas.length - failures}`);
+    if (warnings > 0) console.log(`Warnings: ${warnings}`);
+    if (failures > 0) console.log(`Failures: ${failures}`);
+    console.log('='.repeat(60));
+
+    if (failures > 0) {
+      console.error(`\n❌ Validation failed: ${failures} invalid schema(s)`);
+      process.exit(1);
+    }
+
+    if (warnings > 0) {
+      console.warn(`\n⚠️  Validation completed with ${warnings} warning(s)`);
+    } else {
+      console.log(`\n✅ All ${schemas.length} schemas validated successfully!`);
+    }
+
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.error('❌ Schemas file not found:', SCHEMAS_FILE);
+      console.error('   Run "bun run generate:schemas" first');
+    } else if (error.code === 'ERR_MODULE_NOT_FOUND') {
+      console.error('❌ Failed to import schemas:', error.message);
+      console.error('   Generated file may have syntax errors');
+    } else {
+      console.error('❌ Validation error:', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+// Run validation
+validateSchemas().catch(error => {
+  console.error('\n❌ Fatal validation error:', error);
+  process.exit(1);
+});