@caucasus/az-utils 0.1.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 samurai-jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+![pipeline status](https://gitlab.com/samurai-jack/az-utils/badges/master/pipeline.svg)
+![npm version](https://img.shields.io/npm/v/@samurai-jack/az-utils)
+![license](https://img.shields.io/npm/l/@samurai-jack/az-utils)
+
+
+# az-utils 🇦🇿
+
+A lightweight, TypeScript-first utility library providing **Azerbaijan-specific helpers** commonly needed in backend development.
+
+This package focuses on **validation, normalization, and parsing** of data formats frequently used in Azerbaijan-based systems.
+
+> ✅ Current version: **v0.1.0**  
+> Initial release focuses on **Azerbaijan mobile phone utilities**
+
+---
+
+## ✨ Features
+
+### 📱 Phone Utilities
+
+- Validate Azerbaijan mobile phone numbers
+- Normalize phone numbers to a standard local format
+- Detect mobile operator (Azercell, Bakcell, Nar)
+
+More utilities (FIN, IBAN, passport, addresses) will be added incrementally.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @samurai-jack/az-utils
+
+```
+
+## Usage
+
+```
+import {
+  isValidAzPhone,
+  normalizeAzPhone,
+  getAzMobileOperator
+} from "az-utils";
+
+```
+
+## ✅ Validate Phone Number
+
+```
+isValidAzPhone("+994 (50) 123-45-67"); // true
+isValidAzPhone("0501234567");         // true
+isValidAzPhone("0401234567");         // false
+```
+Supported input formats:
+- 0501234567
+- 050 123 45 67
+- (050) 123-45-67
+- 994501234567
+- +994501234567
+
+## 🔄Normalize Phone Number
+
+```
+normalizeAzPhone("+994701112233");
+// "0701112233"
+
+normalizeAzPhone("(050) 123-45-67");
+// "0501234567"
+
+```
+
+## 🏷 Detect Mobile Operator
+
+```
+getAzMobileOperator("0501234567");
+// "Azercell"
+
+getAzMobileOperator("0551234567");
+// "Bakcell"
+
+getAzMobileOperator("0771234567");
+// "Nar"
+
+```
+
+### Supported Prefixes
+
+| Prefix       | Operator |
+| --------     | -------- |
+| 050, 051,010 | Azercell |
+| 055, 099     | Bakcell  |
+| 070, 077     | Nar      |
+
+
+
+## 🛣 Roadmap   
+
+Planned additions:
+
+- FIN (Fərdi İdentifikasiya Nömrəsi) validation
+
+- Azerbaijan IBAN validation
+
+- Passport series validation
+
+- Address parsing utilities
+
+- Localization helpers (AZ / EN / RU)
+
+## 🤝 Contributing
+
+Contributions are welcome.
+
+Please:
+
+- Keep changes small and focused
+
+- Add tests for new functionality
+
+- Avoid breaking changes without discussion
+
+##  📄 License
+
+MIT License © Contributors
+
+--- 
+

package/dist/date/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/date/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/fin/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fin/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/iban/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/iban/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./phone";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./phone"), exports);

package/dist/passport/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/passport/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/phone/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const NUMBER_LENGTH_REX: RegExp;
+export declare const NUMBER_CLEANING_REX: RegExp;

package/dist/phone/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NUMBER_CLEANING_REX = exports.NUMBER_LENGTH_REX = void 0;
+exports.NUMBER_LENGTH_REX = /^\d{9}$/;
+exports.NUMBER_CLEANING_REX = /[\s\-()]/g;

package/dist/phone/getAzMobileOperator.d.ts

@@ -0,0 +1,2 @@
+import { AzMobileOperator } from "./operators";
+export declare function getAzMobileOperator(phone: string): AzMobileOperator;

package/dist/phone/getAzMobileOperator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAzMobileOperator = getAzMobileOperator;
+const operators_1 = require("./operators");
+const normalizeAzPhone_1 = require("./normalizeAzPhone");
+function getAzMobileOperator(phone) {
+    const normalized = (0, normalizeAzPhone_1.normalizeAzPhone)(phone);
+    if (!normalized) {
+        return "Unknown";
+    }
+    const prefix = normalized.slice(1, 3);
+    return operators_1.OPERATOR_PREFIX_MAP[prefix] ?? "Unknown";
+}

package/dist/phone/index.d.ts

@@ -0,0 +1,4 @@
+export { isValidAzPhone } from "./isValidAzPhone";
+export { normalizeAzPhone } from "./normalizeAzPhone";
+export { getAzMobileOperator } from "./getAzMobileOperator";
+export type { AzMobileOperator } from "./operators";

package/dist/phone/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAzMobileOperator = exports.normalizeAzPhone = exports.isValidAzPhone = void 0;
+var isValidAzPhone_1 = require("./isValidAzPhone");
+Object.defineProperty(exports, "isValidAzPhone", { enumerable: true, get: function () { return isValidAzPhone_1.isValidAzPhone; } });
+var normalizeAzPhone_1 = require("./normalizeAzPhone");
+Object.defineProperty(exports, "normalizeAzPhone", { enumerable: true, get: function () { return normalizeAzPhone_1.normalizeAzPhone; } });
+var getAzMobileOperator_1 = require("./getAzMobileOperator");
+Object.defineProperty(exports, "getAzMobileOperator", { enumerable: true, get: function () { return getAzMobileOperator_1.getAzMobileOperator; } });

package/dist/phone/isValidAzPhone.d.ts

@@ -0,0 +1 @@
+export declare function isValidAzPhone(phone: string): boolean;

package/dist/phone/isValidAzPhone.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAzPhone = isValidAzPhone;
+const operators_1 = require("./operators");
+const constants_1 = require("./constants");
+function isValidAzPhone(phone) {
+    if (!phone)
+        return false;
+    // Remove spaces, dashes, parentheses
+    const cleaned = phone.replace(constants_1.NUMBER_CLEANING_REX, "");
+    let localNumber;
+    if (cleaned.startsWith("+994")) {
+        localNumber = cleaned.slice(4);
+    }
+    else if (cleaned.startsWith("994")) {
+        localNumber = cleaned.slice(3);
+    }
+    else if (cleaned.startsWith("0")) {
+        localNumber = cleaned.slice(1);
+    }
+    else if (cleaned.slice(0, 2) in operators_1.OPERATOR_PREFIX_MAP) {
+        localNumber = cleaned;
+    }
+    else {
+        return false;
+    }
+    // Must be exactly 9 digits after prefix removal
+    if (!constants_1.NUMBER_LENGTH_REX.test(localNumber)) {
+        return false;
+    }
+    const operatorPrefix = localNumber.slice(0, 2);
+    return operatorPrefix in operators_1.OPERATOR_PREFIX_MAP;
+}

package/dist/phone/normalizeAzPhone.d.ts

@@ -0,0 +1 @@
+export declare function normalizeAzPhone(phone: string): string | null;

package/dist/phone/normalizeAzPhone.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAzPhone = normalizeAzPhone;
+const isValidAzPhone_1 = require("./isValidAzPhone");
+const constants_1 = require("./constants");
+function normalizeAzPhone(phone) {
+    if (!(0, isValidAzPhone_1.isValidAzPhone)(phone)) {
+        return null;
+    }
+    const cleaned = phone.replace(constants_1.NUMBER_CLEANING_REX, "");
+    let localNumber;
+    if (cleaned.startsWith("+994")) {
+        localNumber = cleaned.slice(4);
+    }
+    else if (cleaned.startsWith("994")) {
+        localNumber = cleaned.slice(3);
+    }
+    else if (cleaned.startsWith("0")) {
+        localNumber = cleaned.slice(1);
+    }
+    else {
+        localNumber = cleaned;
+    }
+    return "0".concat(localNumber);
+}

package/dist/phone/operators.d.ts

@@ -0,0 +1,2 @@
+export type AzMobileOperator = "Azercell" | "Bakcell" | "Nar" | "Unknown";
+export declare const OPERATOR_PREFIX_MAP: Record<string, AzMobileOperator>;

package/dist/phone/operators.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATOR_PREFIX_MAP = void 0;
+exports.OPERATOR_PREFIX_MAP = {
+    "50": "Azercell",
+    "51": "Azercell",
+    "10": "Azercell",
+    "55": "Bakcell",
+    "99": "Bakcell",
+    "70": "Nar",
+    "77": "Nar",
+};

package/dist/phone/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const NUMBER_LENGTH_REX: RegExp;
+export declare const NUMBER_CLEANING_REX: RegExp;

package/dist/phone/utils.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NUMBER_CLEANING_REX = exports.NUMBER_LENGTH_REX = void 0;
+exports.NUMBER_LENGTH_REX = /^\d{9}$/;
+exports.NUMBER_CLEANING_REX = /[\s\-()]/g;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@caucasus/az-utils",
+  "version": "0.1.0",
+  "description": "Azerbaijan-specific utility functions for Node.js backends",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "keywords": [
+    "azerbaijan",
+    "utils",
+    "validation",
+    "nodejs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Javid Guliyev",
+  "license": "MIT"
+}