@propxchain/core-client 0.3.0-canary.38 → 0.4.0-canary.39

package/dist/jurisdiction.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (C) 2025 PropXchain. All rights reserved.
+ * Proprietary and confidential.
+ *
+ * Which legal system a UK property sits in, from its postcode.
+ *
+ * PropXchain operates in England and Wales only. Scotland runs an entirely
+ * different conveyancing system — missives rather than exchange, the Land
+ * Register of Scotland rather than HM Land Registry, and no CON29 or LLC1 at
+ * all. Northern Ireland is different again. None of our searches, forms or
+ * title pulls mean anything there.
+ *
+ * This exists because nothing stopped an out-of-jurisdiction property entering
+ * the flow. On 2026-08-10 a Scottish UPRN went all the way to a priced tmGroup
+ * draft and came back at £0.00 with an empty failure list — the searches simply
+ * do not exist in Scotland, so there was nothing to price and nothing to
+ * report. tmGroup confirmed it: "That UPRN is in Scotland and therefore
+ * authority look-ups do not apply." A £0 quote is the LAST place that should be
+ * caught. The address is the first.
+ */
+export type Jurisdiction = 'england-wales' | 'scotland' | 'northern-ireland' | 'crown-dependency' | 'ambiguous' | 'unknown';
+/**
+ * The postcode AREA — the leading letters before the first digit. `EH10 6QL`
+ * gives `EH`, `G1 1AA` gives `G`.
+ *
+ * Deliberately tolerant of missing spaces and lower case, because this runs on
+ * whatever a person typed. It is deliberately NOT tolerant of things that are
+ * not postcodes: an unparseable value returns null and the caller decides,
+ * rather than being silently treated as England.
+ */
+export declare function postcodeArea(postcode: string | null | undefined): string | null;
+/** Which legal system this postcode falls in. */
+export declare function jurisdictionFromPostcode(postcode: string | null | undefined): Jurisdiction;
+/**
+ * Can PropXchain handle this property?
+ *
+ * 'ambiguous' and 'unknown' both pass. That is deliberate: this is a guard
+ * against the clearly-wrong, not an address validator. Refusing every postcode
+ * we failed to parse would turn a typo into a dead end, and refusing Berwick
+ * would turn a correct English address into one. What must never happen is a
+ * confidently Scottish property reaching a payment screen.
+ */
+export declare function isSupportedJurisdiction(postcode: string | null | undefined): boolean;
+/**
+ * What to tell the person, in their terms. Never "invalid postcode" — their
+ * postcode is perfectly valid, it is our coverage that is limited, and saying
+ * so plainly is the difference between a clear no and a broken form.
+ */
+export declare function unsupportedJurisdictionMessage(postcode: string | null | undefined): string | null;
+//# sourceMappingURL=jurisdiction.d.ts.map

package/dist/jurisdiction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jurisdiction.d.ts","sourceRoot":"","sources":["../src/jurisdiction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAyBH,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,UAAU,GACV,kBAAkB,GAClB,kBAAkB,GAClB,WAAW,GACX,SAAS,CAAC;AAEd;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAO/E;AAED,iDAAiD;AACjD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAQ1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAKpF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAcjG"}

package/dist/jurisdiction.js

@@ -0,0 +1,109 @@
+/**
+ * Copyright (C) 2025 PropXchain. All rights reserved.
+ * Proprietary and confidential.
+ *
+ * Which legal system a UK property sits in, from its postcode.
+ *
+ * PropXchain operates in England and Wales only. Scotland runs an entirely
+ * different conveyancing system — missives rather than exchange, the Land
+ * Register of Scotland rather than HM Land Registry, and no CON29 or LLC1 at
+ * all. Northern Ireland is different again. None of our searches, forms or
+ * title pulls mean anything there.
+ *
+ * This exists because nothing stopped an out-of-jurisdiction property entering
+ * the flow. On 2026-08-10 a Scottish UPRN went all the way to a priced tmGroup
+ * draft and came back at £0.00 with an empty failure list — the searches simply
+ * do not exist in Scotland, so there was nothing to price and nothing to
+ * report. tmGroup confirmed it: "That UPRN is in Scotland and therefore
+ * authority look-ups do not apply." A £0 quote is the LAST place that should be
+ * caught. The address is the first.
+ */
+/** Postcode areas wholly within Scotland. */
+const SCOTLAND_AREAS = new Set([
+    'AB', 'DD', 'DG', 'EH', 'FK', 'G', 'HS', 'IV',
+    'KA', 'KW', 'KY', 'ML', 'PA', 'PH', 'ZE',
+]);
+/**
+ * Areas that straddle the border, so the postcode alone cannot decide.
+ *
+ * TD covers the Scottish Borders but also Berwick-upon-Tweed (TD15), which is
+ * in England. CA is Cumbria but a handful of CA6 addresses are Scottish.
+ * Guessing either way is wrong for real people in real houses, so these resolve
+ * to 'ambiguous' and the caller must confirm another way — for a tmGroup order
+ * the local-authority lookup is the answer, because it names the actual council.
+ */
+const BORDER_AREAS = new Set(['TD', 'CA']);
+/** Northern Ireland. Separate legal system, separate registry. */
+const NORTHERN_IRELAND_AREAS = new Set(['BT']);
+/** Crown dependencies. Not the UK for these purposes, and not our market. */
+const CROWN_DEPENDENCY_AREAS = new Set(['IM', 'GY', 'JE']);
+/**
+ * The postcode AREA — the leading letters before the first digit. `EH10 6QL`
+ * gives `EH`, `G1 1AA` gives `G`.
+ *
+ * Deliberately tolerant of missing spaces and lower case, because this runs on
+ * whatever a person typed. It is deliberately NOT tolerant of things that are
+ * not postcodes: an unparseable value returns null and the caller decides,
+ * rather than being silently treated as England.
+ */
+export function postcodeArea(postcode) {
+    if (typeof postcode !== 'string')
+        return null;
+    const cleaned = postcode.trim().toUpperCase().replace(/\s+/g, '');
+    if (!cleaned)
+        return null;
+    // A UK outward code is 1-2 letters, then a digit. Anything else is not one.
+    const match = /^([A-Z]{1,2})[0-9]/.exec(cleaned);
+    return match ? match[1] : null;
+}
+/** Which legal system this postcode falls in. */
+export function jurisdictionFromPostcode(postcode) {
+    const area = postcodeArea(postcode);
+    if (!area)
+        return 'unknown';
+    if (SCOTLAND_AREAS.has(area))
+        return 'scotland';
+    if (NORTHERN_IRELAND_AREAS.has(area))
+        return 'northern-ireland';
+    if (CROWN_DEPENDENCY_AREAS.has(area))
+        return 'crown-dependency';
+    if (BORDER_AREAS.has(area))
+        return 'ambiguous';
+    return 'england-wales';
+}
+/**
+ * Can PropXchain handle this property?
+ *
+ * 'ambiguous' and 'unknown' both pass. That is deliberate: this is a guard
+ * against the clearly-wrong, not an address validator. Refusing every postcode
+ * we failed to parse would turn a typo into a dead end, and refusing Berwick
+ * would turn a correct English address into one. What must never happen is a
+ * confidently Scottish property reaching a payment screen.
+ */
+export function isSupportedJurisdiction(postcode) {
+    const jurisdiction = jurisdictionFromPostcode(postcode);
+    return jurisdiction !== 'scotland'
+        && jurisdiction !== 'northern-ireland'
+        && jurisdiction !== 'crown-dependency';
+}
+/**
+ * What to tell the person, in their terms. Never "invalid postcode" — their
+ * postcode is perfectly valid, it is our coverage that is limited, and saying
+ * so plainly is the difference between a clear no and a broken form.
+ */
+export function unsupportedJurisdictionMessage(postcode) {
+    switch (jurisdictionFromPostcode(postcode)) {
+        case 'scotland':
+            return 'PropXchain currently covers England and Wales only. Scotland has a separate '
+                + 'conveyancing system and its own land register, so we cannot handle this property yet.';
+        case 'northern-ireland':
+            return 'PropXchain currently covers England and Wales only. Northern Ireland has a '
+                + 'separate conveyancing system and its own land registry, so we cannot handle this property yet.';
+        case 'crown-dependency':
+            return 'PropXchain currently covers England and Wales only, which does not include the '
+                + 'Isle of Man or the Channel Islands.';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=jurisdiction.js.map

package/dist/jurisdiction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jurisdiction.js","sourceRoot":"","sources":["../src/jurisdiction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,6CAA6C;AAC7C,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI;IAC7C,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CACzC,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE3C,kEAAkE;AAClE,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAE/C,6EAA6E;AAC7E,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAU3D;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAmC;IAC9D,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClE,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,wBAAwB,CAAC,QAAmC;IAC1E,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IAChD,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,kBAAkB,CAAC;IAChE,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,kBAAkB,CAAC;IAChE,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC;IAC/C,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAmC;IACzE,MAAM,YAAY,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IACxD,OAAO,YAAY,KAAK,UAAU;WAC7B,YAAY,KAAK,kBAAkB;WACnC,YAAY,KAAK,kBAAkB,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,QAAmC;IAChF,QAAQ,wBAAwB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,KAAK,UAAU;YACb,OAAO,8EAA8E;kBACjF,uFAAuF,CAAC;QAC9F,KAAK,kBAAkB;YACrB,OAAO,6EAA6E;kBAChF,gGAAgG,CAAC;QACvG,KAAK,kBAAkB;YACrB,OAAO,iFAAiF;kBACpF,qCAAqC,CAAC;QAC5C;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@propxchain/core-client",
-  "version": "0.3.0-canary.38",
+  "version": "0.4.0-canary.39",
   "description": "Typed TypeScript client for the PropXchain core canisters on the Internet Computer. Includes a deterministic mock mode for local development and tests.",
   "license": "UNLICENSED",
   "type": "module",
@@ -18,6 +18,10 @@
     "./auth": {
       "types": "./dist/auth.d.ts",
       "import": "./dist/auth.js"
+    },
+    "./jurisdiction": {
+      "types": "./dist/jurisdiction.d.ts",
+      "import": "./dist/jurisdiction.js"
     }
   },
   "files": [

package/src/jurisdiction.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (C) 2025 PropXchain. All rights reserved.
+ * Proprietary and confidential.
+ *
+ * Which legal system a UK property sits in, from its postcode.
+ *
+ * PropXchain operates in England and Wales only. Scotland runs an entirely
+ * different conveyancing system — missives rather than exchange, the Land
+ * Register of Scotland rather than HM Land Registry, and no CON29 or LLC1 at
+ * all. Northern Ireland is different again. None of our searches, forms or
+ * title pulls mean anything there.
+ *
+ * This exists because nothing stopped an out-of-jurisdiction property entering
+ * the flow. On 2026-08-10 a Scottish UPRN went all the way to a priced tmGroup
+ * draft and came back at £0.00 with an empty failure list — the searches simply
+ * do not exist in Scotland, so there was nothing to price and nothing to
+ * report. tmGroup confirmed it: "That UPRN is in Scotland and therefore
+ * authority look-ups do not apply." A £0 quote is the LAST place that should be
+ * caught. The address is the first.
+ */
+
+/** Postcode areas wholly within Scotland. */
+const SCOTLAND_AREAS = new Set([
+  'AB', 'DD', 'DG', 'EH', 'FK', 'G', 'HS', 'IV',
+  'KA', 'KW', 'KY', 'ML', 'PA', 'PH', 'ZE',
+]);
+
+/**
+ * Areas that straddle the border, so the postcode alone cannot decide.
+ *
+ * TD covers the Scottish Borders but also Berwick-upon-Tweed (TD15), which is
+ * in England. CA is Cumbria but a handful of CA6 addresses are Scottish.
+ * Guessing either way is wrong for real people in real houses, so these resolve
+ * to 'ambiguous' and the caller must confirm another way — for a tmGroup order
+ * the local-authority lookup is the answer, because it names the actual council.
+ */
+const BORDER_AREAS = new Set(['TD', 'CA']);
+
+/** Northern Ireland. Separate legal system, separate registry. */
+const NORTHERN_IRELAND_AREAS = new Set(['BT']);
+
+/** Crown dependencies. Not the UK for these purposes, and not our market. */
+const CROWN_DEPENDENCY_AREAS = new Set(['IM', 'GY', 'JE']);
+
+export type Jurisdiction =
+  | 'england-wales'
+  | 'scotland'
+  | 'northern-ireland'
+  | 'crown-dependency'
+  | 'ambiguous'
+  | 'unknown';
+
+/**
+ * The postcode AREA — the leading letters before the first digit. `EH10 6QL`
+ * gives `EH`, `G1 1AA` gives `G`.
+ *
+ * Deliberately tolerant of missing spaces and lower case, because this runs on
+ * whatever a person typed. It is deliberately NOT tolerant of things that are
+ * not postcodes: an unparseable value returns null and the caller decides,
+ * rather than being silently treated as England.
+ */
+export function postcodeArea(postcode: string | null | undefined): string | null {
+  if (typeof postcode !== 'string') return null;
+  const cleaned = postcode.trim().toUpperCase().replace(/\s+/g, '');
+  if (!cleaned) return null;
+  // A UK outward code is 1-2 letters, then a digit. Anything else is not one.
+  const match = /^([A-Z]{1,2})[0-9]/.exec(cleaned);
+  return match ? match[1] : null;
+}
+
+/** Which legal system this postcode falls in. */
+export function jurisdictionFromPostcode(postcode: string | null | undefined): Jurisdiction {
+  const area = postcodeArea(postcode);
+  if (!area) return 'unknown';
+  if (SCOTLAND_AREAS.has(area)) return 'scotland';
+  if (NORTHERN_IRELAND_AREAS.has(area)) return 'northern-ireland';
+  if (CROWN_DEPENDENCY_AREAS.has(area)) return 'crown-dependency';
+  if (BORDER_AREAS.has(area)) return 'ambiguous';
+  return 'england-wales';
+}
+
+/**
+ * Can PropXchain handle this property?
+ *
+ * 'ambiguous' and 'unknown' both pass. That is deliberate: this is a guard
+ * against the clearly-wrong, not an address validator. Refusing every postcode
+ * we failed to parse would turn a typo into a dead end, and refusing Berwick
+ * would turn a correct English address into one. What must never happen is a
+ * confidently Scottish property reaching a payment screen.
+ */
+export function isSupportedJurisdiction(postcode: string | null | undefined): boolean {
+  const jurisdiction = jurisdictionFromPostcode(postcode);
+  return jurisdiction !== 'scotland'
+    && jurisdiction !== 'northern-ireland'
+    && jurisdiction !== 'crown-dependency';
+}
+
+/**
+ * What to tell the person, in their terms. Never "invalid postcode" — their
+ * postcode is perfectly valid, it is our coverage that is limited, and saying
+ * so plainly is the difference between a clear no and a broken form.
+ */
+export function unsupportedJurisdictionMessage(postcode: string | null | undefined): string | null {
+  switch (jurisdictionFromPostcode(postcode)) {
+    case 'scotland':
+      return 'PropXchain currently covers England and Wales only. Scotland has a separate '
+        + 'conveyancing system and its own land register, so we cannot handle this property yet.';
+    case 'northern-ireland':
+      return 'PropXchain currently covers England and Wales only. Northern Ireland has a '
+        + 'separate conveyancing system and its own land registry, so we cannot handle this property yet.';
+    case 'crown-dependency':
+      return 'PropXchain currently covers England and Wales only, which does not include the '
+        + 'Isle of Man or the Channel Islands.';
+    default:
+      return null;
+  }
+}