@verisure-italy/zipcode-types 1.3.0 → 1.5.0

package/README.md

@@ -0,0 +1,171 @@
+# ZipCode Types
+
+TypeScript types and Zod schemas for ZipCode service entities. This package provides type-safe definitions for areas and enabled zip codes.
+
+## Features
+
+- ✅ **Type-Safe** - Full TypeScript support with Zod runtime validation
+- ✅ **Shared Types** - Built on top of `@verisure-italy/shared-types`
+- ✅ **Runtime Validation** - Zod schemas for request/response validation
+- ✅ **Tree-Shakeable** - ESM and CJS support for optimal bundle size
+
+## Installation
+
+```bash
+pnpm add @verisure-italy/zipcode-types
+```
+
+## Types
+
+### Area
+
+Represents a geographic area with zip code information.
+
+```typescript
+import { Area, areaSchema } from '@verisure-italy/zipcode-types'
+
+// TypeScript type
+const area: Area = {
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  city: 'Milano',
+  province: 'MI',
+  region: 'Lombardia',
+  town: 'Milano',
+  zipCode: '20100',
+}
+
+// Runtime validation with Zod
+const result = areaSchema.safeParse(data)
+if (result.success) {
+  const validArea: Area = result.data
+}
+```
+
+**Schema:**
+
+```typescript
+const areaSchema = z.object({
+  id: z.uuid(),                                              // UUID v4
+  city: z.string().min(2, 'city.required'),                 // Min 2 chars
+  province: z.string().min(2).max(3),                       // 2-3 chars (e.g., MI, RM)
+  region: z.string().min(2, 'region.required'),            // Min 2 chars
+  town: z.string().min(2, 'town.required'),                // Min 2 chars
+  zipCode: zipCodeSchema,                                    // From shared-types
+})
+```
+
+### Enabled
+
+Represents an enabled zip code.
+
+```typescript
+import { Enabled, enabledSchema } from '@verisure-italy/zipcode-types'
+
+// TypeScript type
+const enabled: Enabled = {
+  zipCode: '20100',
+}
+
+// Runtime validation with Zod
+const result = enabledSchema.safeParse(data)
+if (result.success) {
+  const validEnabled: Enabled = result.data
+}
+```
+
+**Schema:**
+
+```typescript
+const enabledSchema = z.object({
+  zipCode: zipCodeSchema,  // From shared-types
+})
+```
+
+## Usage Examples
+
+### Express Route with Validation
+
+```typescript
+import express from 'express'
+import { areaSchema, type Area } from '@verisure-italy/zipcode-types'
+
+const router = express.Router()
+
+router.post('/areas', async (req, res) => {
+  // Validate request body
+  const result = areaSchema.safeParse(req.body)
+  
+  if (!result.success) {
+    return res.status(400).json({ 
+      error: 'Invalid area data',
+      details: result.error.issues 
+    })
+  }
+  
+  const area: Area = result.data
+  // ... save to database ...
+  
+  res.json(area)
+})
+```
+
+### With Router Middleware
+
+```typescript
+import { createRestResource } from '@verisure-italy/router-middleware'
+import { areaSchema, type Area } from '@verisure-italy/zipcode-types'
+
+const areaResource = createRestResource<Area>({
+  name: 'area',
+  schema: areaSchema,
+  // ... repository methods ...
+})
+
+// Validation is handled automatically by router-middleware
+```
+
+### Type Guards
+
+```typescript
+import { areaSchema, type Area } from '@verisure-italy/zipcode-types'
+
+function isValidArea(data: unknown): data is Area {
+  return areaSchema.safeParse(data).success
+}
+
+// Usage
+if (isValidArea(unknownData)) {
+  // TypeScript knows this is an Area
+  console.log(unknownData.city)
+}
+```
+
+## Dependencies
+
+- `@verisure-italy/shared-types` - Provides `zipCodeSchema` and other shared types
+- `zod` ^4.1.12 - Runtime validation library
+
+## Related Packages
+
+- [`@verisure-italy/shared-types`](../shared-types) - Shared types across services
+- [`@verisure-italy/router-middleware`](../router-middleware) - REST resource creation with validation
+- [`@verisure-italy/error-handler-middleware`](../error-handler-middleware) - Handles validation errors
+
+## TypeScript Configuration
+
+This package is built with TypeScript 5.9+ and exports both type definitions and runtime schemas.
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022"
+  }
+}
+```
+
+## License
+
+Internal Verisure Italy package
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@verisure-italy/zipcode-types",
   "description": "Types for ZipCode service",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "4.1.12",
-    "@verisure-italy/shared-types": "1.3.0"
+    "@verisure-italy/shared-types": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "24.6.0",