saudi-utils 0.1.0 → 0.2.0

package/dist/telecom.d.ts

@@ -1,9 +1,61 @@
-import type { NormalizedSaudiPhone, ValidationResult } from "./types.js";
+import type { ValidationResult } from "./types.js";
+/**
+ * Validates a Saudi mobile number in national 05... or +9665... form.
+ *
+ * Requires ASCII digits and no separators; does not verify allocation, reachability, or carrier.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export declare function validateMobileNumber(value: unknown): ValidationResult;
+/**
+ * Checks the national or +966 Saudi mobile number structure.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export declare function isMobileNumber(value: unknown): value is string;
+/**
+ * Validates a Saudi landline in national 01... or +9661... form with a supported area code.
+ *
+ * Requires ASCII digits and no separators; does not verify allocation or reachability.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export declare function validateLandlineNumber(value: unknown): ValidationResult;
+/**
+ * Checks the national or +966 Saudi landline structure and area code.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export declare function isLandlineNumber(value: unknown): value is string;
+/**
+ * Validates a Saudi toll-free number in 10-digit national 800... form only.
+ *
+ * International forms and 9200 numbers are not accepted; reachability is not verified.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export declare function validateTollFreeNumber(value: unknown): ValidationResult;
+/**
+ * Checks the national 800... Saudi toll-free structure only.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export declare function isTollFreeNumber(value: unknown): value is string;
-export declare function normalizePhoneNumber(value: unknown): NormalizedSaudiPhone | null;
+/**
+ * Normalizes a supported phone representation without validating its prefix or length.
+ *
+ * Mobile and landline accept national, +966, 966, or 00966 forms and return +966 form. Toll-free accepts national 800 form only. Whitespace, punctuation, extensions, and Unicode digits are rejected.
+ *
+ * @param value - Unknown input; only unseparated primitive ASCII strings in supported forms are accepted.
+ * @returns The canonical string candidate, even when its prefix or length is invalid; null when the representation cannot be converted.
+ */
+export declare function normalizePhoneNumber(value: unknown): string | null;
+/** @internal Produces a candidate without claiming that the phone number is valid. */
+export declare function normalizePhoneNumberInput(value: unknown): string | null;
 //# sourceMappingURL=telecom.d.ts.map

package/dist/telecom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telecom.d.ts","sourceRoot":"","sources":["../src/telecom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiBzE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAuBrE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAuBvE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAoBvE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAgChF"}
+{"version":3,"file":"telecom.d.ts","sourceRoot":"","sources":["../src/telecom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiBnD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAuBrE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAuBvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAoBvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAElE;AAED,sFAAsF;AACtF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA2BvE"}

package/dist/telecom.js

@@ -11,6 +11,14 @@ function validateNationalOrE164Format(value) {
 function hasE164SaudiPrefix(value) {
     return value.startsWith("+966");
 }
+/**
+ * Validates a Saudi mobile number in national 05... or +9665... form.
+ *
+ * Requires ASCII digits and no separators; does not verify allocation, reachability, or carrier.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export function validateMobileNumber(value) {
     const input = checkStringInput(value);
     if (!input.valid) {
@@ -28,9 +36,23 @@ export function validateMobileNumber(value) {
     }
     return { valid: true, value: input.value };
 }
+/**
+ * Checks the national or +966 Saudi mobile number structure.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export function isMobileNumber(value) {
     return validateMobileNumber(value).valid;
 }
+/**
+ * Validates a Saudi landline in national 01... or +9661... form with a supported area code.
+ *
+ * Requires ASCII digits and no separators; does not verify allocation or reachability.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export function validateLandlineNumber(value) {
     const input = checkStringInput(value);
     if (!input.valid) {
@@ -48,9 +70,23 @@ export function validateLandlineNumber(value) {
     }
     return { valid: true, value: input.value };
 }
+/**
+ * Checks the national or +966 Saudi landline structure and area code.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export function isLandlineNumber(value) {
     return validateLandlineNumber(value).valid;
 }
+/**
+ * Validates a Saudi toll-free number in 10-digit national 800... form only.
+ *
+ * International forms and 9200 numbers are not accepted; reachability is not verified.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns A result containing the unchanged string when valid, or the first applicable error code.
+ */
 export function validateTollFreeNumber(value) {
     const input = checkStringInput(value);
     if (!input.valid) {
@@ -67,38 +103,50 @@ export function validateTollFreeNumber(value) {
     }
     return { valid: true, value: input.value };
 }
+/**
+ * Checks the national 800... Saudi toll-free structure only.
+ *
+ * @param value - Unknown input; only a primitive string in the stated canonical format is accepted.
+ * @returns True when the input satisfies the stated offline rules; false otherwise.
+ */
 export function isTollFreeNumber(value) {
     return validateTollFreeNumber(value).valid;
 }
+/**
+ * Normalizes a supported phone representation without validating its prefix or length.
+ *
+ * Mobile and landline accept national, +966, 966, or 00966 forms and return +966 form. Toll-free accepts national 800 form only. Whitespace, punctuation, extensions, and Unicode digits are rejected.
+ *
+ * @param value - Unknown input; only unseparated primitive ASCII strings in supported forms are accepted.
+ * @returns The canonical string candidate, even when its prefix or length is invalid; null when the representation cannot be converted.
+ */
 export function normalizePhoneNumber(value) {
+    return normalizePhoneNumberInput(value);
+}
+/** @internal Produces a candidate without claiming that the phone number is valid. */
+export function normalizePhoneNumberInput(value) {
     if (typeof value !== "string") {
         return null;
     }
-    if (validateTollFreeNumber(value).valid) {
-        return { kind: "toll-free", value: `800${value.slice(3)}` };
-    }
-    let canonical;
-    if (hasE164SaudiPrefix(value)) {
-        canonical = value;
-    }
-    else if (value.startsWith("00966")) {
-        canonical = `+966${value.slice(5)}`;
-    }
-    else if (value.startsWith("966")) {
-        canonical = `+966${value.slice(3)}`;
-    }
-    else if (value.startsWith("0")) {
-        canonical = `+966${value.slice(1)}`;
-    }
-    else {
-        return null;
-    }
-    if (validateMobileNumber(canonical).valid) {
-        return { kind: "mobile", value: canonical };
-    }
-    if (validateLandlineNumber(canonical).valid) {
-        return { kind: "landline", value: canonical };
-    }
-    return null;
+    if (value.startsWith("800")) {
+        return isAsciiDigits(value) ? value : null;
+    }
+    const national = hasE164SaudiPrefix(value)
+        ? value.slice(4)
+        : value.startsWith("00966")
+            ? value.slice(5)
+            : value.startsWith("966")
+                ? value.slice(3)
+                : value.startsWith("0")
+                    ? value.slice(1)
+                    : null;
+    return national !== null &&
+        national !== "" &&
+        isAsciiDigits(national) &&
+        !national.startsWith("0") &&
+        !national.startsWith("966") &&
+        !national.startsWith("800")
+        ? `+966${national}`
+        : null;
 }
 //# sourceMappingURL=telecom.js.map

package/dist/telecom.js.map

@@ -1 +1 @@
-{"version":3,"file":"telecom.js","sourceRoot":"","sources":["../src/telecom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"telecom.js","sourceRoot":"","sources":["../src/telecom.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,6 @@
+/** Stable reason for a failed offline validation, ordered from missing input through checksum failure. */
 export type ValidationErrorCode = "REQUIRED" | "INVALID_TYPE" | "INVALID_LENGTH" | "INVALID_FORMAT" | "INVALID_PREFIX" | "INVALID_CHECKSUM";
+/** A valid canonical input or a deterministic error code; validation never normalizes the input. */
 export type ValidationResult = {
     valid: true;
     value: string;
@@ -6,7 +8,19 @@ export type ValidationResult = {
     valid: false;
     code: ValidationErrorCode;
 };
+/** A validated value or a stable error code with a short, consumer-facing explanation. */
+export type DetailedValidationResult<T = string> = {
+    valid: true;
+    value: T;
+} | {
+    valid: false;
+    code: ValidationErrorCode;
+    message: string;
+    normalizedValue?: string;
+};
+/** Documentation-only strength of evidence behind a validation rule; not returned at runtime. */
 export type ValidationEvidence = "official-checksum" | "official-structural" | "official-structural-community-checksum" | "best-known-structural";
+/** Validated combined phone result and its kind: E.164 for mobile/landline, national form for toll-free. */
 export type NormalizedSaudiPhone = {
     kind: "mobile" | "landline";
     value: `+966${string}`;
@@ -14,6 +28,7 @@ export type NormalizedSaudiPhone = {
     kind: "toll-free";
     value: `800${string}`;
 };
+/** Required Saudi National Address fields; structural validation does not prove an address exists. */
 export type NationalAddress = {
     buildingNumber: string;
     street: string;
@@ -22,6 +37,7 @@ export type NationalAddress = {
     postalCode: string;
     additionalNumber: string;
 };
+/** A structurally valid address object or the first deterministic validation error. */
 export type NationalAddressValidationResult = {
     valid: true;
     value: NationalAddress;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,gBAAgB,GACxB;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC;AAEN,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,qBAAqB,GACrB,wCAAwC,GACxC,uBAAuB,CAAC;AAE5B,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,MAAM,EAAE,CAAC;CACxB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,MAAM,EAAE,CAAC;CACvB,CAAC;AAEN,MAAM,MAAM,eAAe,GAAG;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,+BAA+B,GACvC;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,eAAe,CAAC;CACxB,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,oGAAoG;AACpG,MAAM,MAAM,gBAAgB,GACxB;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC;AAEN,0FAA0F;AAC1F,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,MAAM,IAC3C;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACzB;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,iGAAiG;AACjG,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,qBAAqB,GACrB,wCAAwC,GACxC,uBAAuB,CAAC;AAE5B,4GAA4G;AAC5G,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,MAAM,EAAE,CAAC;CACxB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,MAAM,EAAE,CAAC;CACvB,CAAC;AAEN,sGAAsG;AACtG,MAAM,MAAM,eAAe,GAAG;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,+BAA+B,GACvC;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,eAAe,CAAC;CACxB,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saudi-utils",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Strict Saudi identity, IBAN, business, telecom, and address validation utilities",
   "keywords": [
     "saudi",