more-apartments-astro-integration 1.5.9 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +92 -0
  2. package/dist/.metadata_never_index +0 -0
  3. package/package.json +6 -3
package/README.md CHANGED
@@ -24,6 +24,98 @@ yarn add @shelfwood/more-apartments-astro-integration
24
24
  bun add @shelfwood/more-apartments-astro-integration
25
25
  ```
26
26
 
27
+ ## Build Process & Type Generation
28
+
29
+ ### How Types are Generated
30
+
31
+ 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.
32
+
33
+ #### CI/CD Build Process (Automated)
34
+
35
+ When you install or publish this package, the build automatically:
36
+
37
+ 1. **Fetches OpenAPI Spec** from GitHub Releases (latest **stable/production** spec from Laravel backend)
38
+ 2. **Generates TypeScript Types** using `openapi-typescript`
39
+ 3. **Generates Zod Schemas** for runtime validation
40
+ 4. **Builds Package** with all generated types included
41
+
42
+ ```bash
43
+ # This happens automatically during:
44
+ npm install @shelfwood/more-apartments-astro-integration
45
+
46
+ # Or when publishing:
47
+ npm publish # Runs prepublishOnly hook
48
+ ```
49
+
50
+ **Environment-Specific Fetching:**
51
+
52
+ The package supports fetching from different release channels:
53
+
54
+ ```bash
55
+ # Production (stable releases only - default)
56
+ bun run fetch:spec
57
+
58
+ # Staging (pre-release/staging builds)
59
+ bun run fetch:spec:staging
60
+ ```
61
+
62
+ **How it works:**
63
+ - **Production:** Fetches from `releases/latest` (stable releases only, excludes pre-releases)
64
+ - **Staging:** Fetches from latest pre-release tagged with `staging-*`
65
+
66
+ #### Local Development Workflow
67
+
68
+ For local development when you have the Laravel project available:
69
+
70
+ ```bash
71
+ # Clone both repositories side-by-side:
72
+ # ~/projects/prj-more-apartments
73
+ # ~/projects/more-apartments-astro-integration
74
+
75
+ cd more-apartments-astro-integration
76
+
77
+ # Generate types from local Laravel project
78
+ bun run generate:types
79
+
80
+ # Or use watch mode for automatic regeneration
81
+ bun run dev:local
82
+ ```
83
+
84
+ **Custom Laravel project path:**
85
+
86
+ ```bash
87
+ # If your Laravel project is elsewhere
88
+ MORE_APARTMENTS_PROJECT_PATH=~/custom/path/to/laravel bun run generate:types
89
+ ```
90
+
91
+ #### Manual Type Generation (Advanced)
92
+
93
+ You can also manually fetch and generate types:
94
+
95
+ ```bash
96
+ # 1. Fetch latest OpenAPI spec from GitHub Releases
97
+ bun run fetch:spec
98
+
99
+ # 2. Generate TypeScript types from fetched spec
100
+ bun run generate:types:local
101
+
102
+ # 3. Generate Zod validation schemas
103
+ bun run generate:schemas
104
+
105
+ # 4. Build package
106
+ bun run build
107
+ ```
108
+
109
+ ### Generated Files (Gitignored)
110
+
111
+ The following files are generated during build and **excluded from git**:
112
+
113
+ - `.openapi/api-v1.json` - OpenAPI specification (fetched from GitHub Releases)
114
+ - `src/types/generated/api.d.ts` - TypeScript type definitions
115
+ - `src/types/generated/schemas.ts` - Zod validation schemas
116
+
117
+ These files are automatically generated, so you'll never see them in pull requests or git diffs.
118
+
27
119
  ## CLI Usage
28
120
 
29
121
  The package includes a powerful CLI for interacting with the More Apartments API directly from the command line.
package/dist/.metadata_never_index ADDED
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "more-apartments-astro-integration",
3
- "version": "1.5.9",
3
+ "version": "2.0.1",
4
4
  "description": "Astro integration for More Apartments REST API",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -28,12 +28,15 @@
28
28
  "scripts": {
29
29
  "build": "tsup",
30
30
  "dev": "tsup --watch",
31
- "prepublishOnly": "bun run build",
31
+ "prepublishOnly": "bun run fetch:spec && bun run generate:types:local && bun run generate:schemas && bun run build",
32
+ "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)",
33
+ "fetch:spec:staging": "node scripts/fetch-staging-spec.mjs",
32
34
  "generate:types": "node scripts/generate-types.mjs",
33
- "generate:types:skip-export": "node scripts/generate-types.mjs --skip-export",
35
+ "generate:types:local": "openapi-typescript .openapi/api-v1.json -o src/types/generated/api.d.ts",
34
36
  "generate:schemas": "node scripts/generate-zod-schemas.mjs",
35
37
  "validate:schemas": "bun scripts/validate-schemas.mjs",
36
38
  "detect:breaking": "node scripts/detect-breaking-changes.mjs",
39
+ "dev:local": "MORE_APARTMENTS_PROJECT_PATH=../prj-more-apartments node scripts/generate-types.mjs && tsup --watch",
37
40
  "test": "node test-runner.js all",
38
41
  "test:watch": "vitest",
39
42
  "test:unit": "node test-runner.js unit",