@paid-tw/ubn 0.0.0-stage → 0.1.0

package/dist/checksum.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Taiwan Unified Business Number (統一編號, UBN/BAN) checksum validation.
+ *
+ * The 8-digit UBN carries a check digit. The algorithm below was verified
+ * empirically against ALL 1,714,969 active UBNs in the FIA tax registry
+ * (dataset snapshot 2026-10-27): it matches 100%.
+ *
+ * History: before 2023 the valid condition was `sum % 10 === 0` (with a
+ * special case when the 7th digit is 7). Because the UBN space was running
+ * out, the Ministry of Finance broadened the rule to `sum % 5 === 0`, which
+ * is a superset and therefore backward compatible. The pre-2023 `% 10` rule
+ * only matches ~88% of currently-registered UBNs, so do NOT use it.
+ */
+/** Returns true if `ban` is a syntactically valid 8-digit UBN. */
+export declare function validateUBN(ban: string): boolean;

package/dist/checksum.js

@@ -0,0 +1,31 @@
+/**
+ * Taiwan Unified Business Number (統一編號, UBN/BAN) checksum validation.
+ *
+ * The 8-digit UBN carries a check digit. The algorithm below was verified
+ * empirically against ALL 1,714,969 active UBNs in the FIA tax registry
+ * (dataset snapshot 2026-10-27): it matches 100%.
+ *
+ * History: before 2023 the valid condition was `sum % 10 === 0` (with a
+ * special case when the 7th digit is 7). Because the UBN space was running
+ * out, the Ministry of Finance broadened the rule to `sum % 5 === 0`, which
+ * is a superset and therefore backward compatible. The pre-2023 `% 10` rule
+ * only matches ~88% of currently-registered UBNs, so do NOT use it.
+ */
+const WEIGHTS = [1, 2, 1, 2, 1, 2, 4, 1];
+/** Returns true if `ban` is a syntactically valid 8-digit UBN. */
+export function validateUBN(ban) {
+    if (!/^\d{8}$/.test(ban))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < 8; i++) {
+        const product = Number(ban[i]) * WEIGHTS[i];
+        // accumulate the digits of each product (tens + units)
+        sum += Math.floor(product / 10) + (product % 10);
+    }
+    if (sum % 5 === 0)
+        return true;
+    // Historical exception: when the 7th digit (index 6) is 7, one may be added.
+    if (ban[6] === '7' && (sum + 1) % 5 === 0)
+        return true;
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { validateUBN } from './checksum.js';
+export { rocToISO } from './rocDate.js';
+export { shardOf, DEFAULT_SHARDS } from './shard.js';
+export { lookupVAT, InvalidUBNError } from './lookup.js';
+export type { UBNRecord, LookupOptions, RegistryStatus } from './lookup.js';
+export { fiaRegistration, gcisCompany } from './sources.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { validateUBN } from './checksum.js';
+export { rocToISO } from './rocDate.js';
+export { shardOf, DEFAULT_SHARDS } from './shard.js';
+export { lookupVAT, InvalidUBNError } from './lookup.js';
+export { fiaRegistration, gcisCompany } from './sources.js';

package/dist/lookup.d.ts

@@ -0,0 +1,52 @@
+/** Registry status written onto shards. Older shards omit the field. */
+export type RegistryStatus = 'active' | 'suspended';
+export interface UBNRecord {
+    ban: string;
+    /** Business name as registered for tax — this is the invoice title (抬頭). */
+    name: string;
+    /** Registered business address. */
+    address?: string;
+    /** Whether the entity issues uniform invoices (使用統一發票). */
+    useInvoice?: boolean;
+    /**
+     * `active` or `suspended`, from `BGMOPEN1` / `BGMOPEN1X`.
+     *
+     * Present on shards built by the header-driven pipeline. Shards published
+     * before that omit `status`; a missing value means unknown — do not treat
+     * it as active. The suspension date itself is not on the shard; it is only
+     * in the full dataset (`ubn.ndjson.gz` / `ubn.sqlite`).
+     */
+    status?: RegistryStatus;
+}
+export interface LookupOptions {
+    /** Base URL serving the dataset (e.g. your CDN in front of R2). */
+    baseUrl: string;
+    /** Shard count; must match the published manifest.json. Default 8192. */
+    shards?: number;
+    /** Abort the request after this many ms. Default 2000. */
+    timeoutMs?: number;
+    /** Inject a fetch implementation (tests / non-browser runtimes). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Version prefix of the published shards (e.g. `"v/20261028"`). When omitted,
+     * the client reads `<baseUrl>/latest.json` to discover it. Set this to pin a
+     * version, or to `""` to read shards flat at `<baseUrl>/shards/` (e.g. when
+     * `baseUrl` already points inside a version).
+     */
+    version?: string;
+}
+export declare class InvalidUBNError extends Error {
+    readonly ban: string;
+    constructor(ban: string);
+}
+/**
+ * Look up a UBN against the static dataset: one request for its shard, then a
+ * local match. Designed for checkout "type UBN -> fill company title".
+ *
+ * - Validates the checksum first and throws InvalidUBNError before any network.
+ * - Returns null when the UBN is well-formed but not in the dataset
+ *   (e.g. a brand-new registration not yet in the daily snapshot). Callers
+ *   can then fall back to the live FIA API; see src/sources.ts.
+ * - Never let a lookup block checkout: treat a thrown/timeout as "no autofill".
+ */
+export declare function lookupVAT(ban: string, opts: LookupOptions): Promise<UBNRecord | null>;

package/dist/lookup.js

@@ -0,0 +1,64 @@
+import { validateUBN } from './checksum.js';
+import { shardOf, DEFAULT_SHARDS } from './shard.js';
+/**
+ * Resolve the directory that holds the shards. The dataset workflow publishes
+ * them under a versioned, immutable prefix (`v/<date>/shards/`) with a short-TTL
+ * `latest.json` = `{"latest":"v/<date>"}` pointer, so the client must resolve
+ * that pointer rather than assume a flat `/shards/`. Falls back to flat when
+ * `latest.json` is absent or `version` is given explicitly.
+ */
+async function resolveShardsDir(opts, doFetch, signal) {
+    const base = opts.baseUrl.replace(/\/$/, '');
+    if (opts.version !== undefined) {
+        return opts.version ? `${base}/${opts.version}/shards` : `${base}/shards`;
+    }
+    const res = await doFetch(`${base}/latest.json`, { signal });
+    if (res.ok) {
+        const { latest } = (await res.json());
+        return latest ? `${base}/${latest.replace(/^\/|\/$/g, '')}/shards` : `${base}/shards`;
+    }
+    // Only an absent pointer (404) means the legacy flat layout. Any other status
+    // is an outage: propagate it so the caller sees an error, not a false "not
+    // found" (returning null here would mask the outage as a missing record).
+    if (res.status === 404)
+        return `${base}/shards`;
+    throw new Error(`tw-ubn: latest.json resolution failed (HTTP ${res.status})`);
+}
+export class InvalidUBNError extends Error {
+    ban;
+    constructor(ban) {
+        super(`Invalid UBN: ${ban}`);
+        this.ban = ban;
+        this.name = 'InvalidUBNError';
+    }
+}
+/**
+ * Look up a UBN against the static dataset: one request for its shard, then a
+ * local match. Designed for checkout "type UBN -> fill company title".
+ *
+ * - Validates the checksum first and throws InvalidUBNError before any network.
+ * - Returns null when the UBN is well-formed but not in the dataset
+ *   (e.g. a brand-new registration not yet in the daily snapshot). Callers
+ *   can then fall back to the live FIA API; see src/sources.ts.
+ * - Never let a lookup block checkout: treat a thrown/timeout as "no autofill".
+ */
+export async function lookupVAT(ban, opts) {
+    if (!validateUBN(ban))
+        throw new InvalidUBNError(ban);
+    const shards = opts.shards ?? DEFAULT_SHARDS;
+    const bucket = shardOf(ban, shards);
+    const doFetch = opts.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2000);
+    try {
+        const dir = await resolveShardsDir(opts, doFetch, controller.signal);
+        const res = await doFetch(`${dir}/${bucket}.json`, { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const rows = (await res.json());
+        return rows.find((r) => r.ban === ban) ?? null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/rocDate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Convert a Republic-of-China (民國) date string to ISO (Gregorian).
+ *
+ * Government registries encode dates as a 7-digit string: 3-digit ROC year,
+ * 2-digit month, 2-digit day. ROC year + 1911 = Gregorian year.
+ * Example: "0760321" -> "1987-03-21".
+ *
+ * Returns null for empty / malformed values (month or day "00" included),
+ * which the source data uses for "unknown".
+ */
+export declare function rocToISO(roc: string | null | undefined): string | null;

package/dist/rocDate.js

@@ -0,0 +1,20 @@
+/**
+ * Convert a Republic-of-China (民國) date string to ISO (Gregorian).
+ *
+ * Government registries encode dates as a 7-digit string: 3-digit ROC year,
+ * 2-digit month, 2-digit day. ROC year + 1911 = Gregorian year.
+ * Example: "0760321" -> "1987-03-21".
+ *
+ * Returns null for empty / malformed values (month or day "00" included),
+ * which the source data uses for "unknown".
+ */
+export function rocToISO(roc) {
+    if (!roc || !/^\d{7}$/.test(roc))
+        return null;
+    const year = Number(roc.slice(0, 3)) + 1911;
+    const mm = roc.slice(3, 5);
+    const dd = roc.slice(5, 7);
+    if (mm === '00' || dd === '00')
+        return null;
+    return `${year}-${mm}-${dd}`;
+}

package/dist/shard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Static sharding of the dataset by UBN.
+ *
+ * The published dataset is split into N static JSON shards so a single lookup
+ * is one cache-friendly request. The bucket is derived from the UBN with a
+ * 32-bit FNV-1a hash (portable, no deps) so the client and the build pipeline
+ * agree exactly. `crates/ubn-core` (`shard_of`) and the worker copies MUST keep
+ * an identical implementation; shared test vectors guard against drift.
+ *
+ * The shard count lives in the published manifest.json ("shards"); a client
+ * should read it rather than hard-coding, but 8192 is the default.
+ */
+export declare const DEFAULT_SHARDS = 8192;
+export declare function shardOf(ban: string, shards?: number): number;

package/dist/shard.js

@@ -0,0 +1,21 @@
+/**
+ * Static sharding of the dataset by UBN.
+ *
+ * The published dataset is split into N static JSON shards so a single lookup
+ * is one cache-friendly request. The bucket is derived from the UBN with a
+ * 32-bit FNV-1a hash (portable, no deps) so the client and the build pipeline
+ * agree exactly. `crates/ubn-core` (`shard_of`) and the worker copies MUST keep
+ * an identical implementation; shared test vectors guard against drift.
+ *
+ * The shard count lives in the published manifest.json ("shards"); a client
+ * should read it rather than hard-coding, but 8192 is the default.
+ */
+export const DEFAULT_SHARDS = 8192;
+export function shardOf(ban, shards = DEFAULT_SHARDS) {
+    let h = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < ban.length; i++) {
+        h ^= ban.charCodeAt(i);
+        h = Math.imul(h, 0x01000193); // FNV prime
+    }
+    return (h >>> 0) % shards;
+}

package/dist/sources.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Official government sources, for enrichment / validation / fallback.
+ * These talk to government servers directly and are NOT the checkout hot path.
+ * All endpoints below were verified on 2026-10-27.
+ */
+/**
+ * FIA (財政部財政資訊中心) per-record tax-registration API.
+ * Documented at https://eip.fia.gov.tw/OAI/v2/api-docs
+ *
+ * CORS: `Access-Control-Allow-Origin: *` (browser-callable), but responses are
+ * `Cache-Control: private`. Do NOT call it per checkout — put your own edge
+ * cache in front and use it only as a fallback for UBNs missing from the daily
+ * bulk snapshot. Returns null on 404 (not found).
+ */
+export declare function fiaRegistration(ban: string, fetchImpl?: typeof fetch): Promise<Record<string, unknown> | null>;
+export declare function gcisCompany(ban: string, fetchImpl?: typeof fetch): Promise<Record<string, unknown> | null>;

package/dist/sources.js

@@ -0,0 +1,41 @@
+/**
+ * Official government sources, for enrichment / validation / fallback.
+ * These talk to government servers directly and are NOT the checkout hot path.
+ * All endpoints below were verified on 2026-10-27.
+ */
+/**
+ * FIA (財政部財政資訊中心) per-record tax-registration API.
+ * Documented at https://eip.fia.gov.tw/OAI/v2/api-docs
+ *
+ * CORS: `Access-Control-Allow-Origin: *` (browser-callable), but responses are
+ * `Cache-Control: private`. Do NOT call it per checkout — put your own edge
+ * cache in front and use it only as a fallback for UBNs missing from the daily
+ * bulk snapshot. Returns null on 404 (not found).
+ */
+export async function fiaRegistration(ban, fetchImpl = fetch) {
+    const res = await fetchImpl(`https://eip.fia.gov.tw/OAI/api/businessRegistration/${ban}`);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`FIA API ${res.status}`);
+    return (await res.json());
+}
+/**
+ * GCIS (經濟部商業司) company-registration OpenData API.
+ *
+ * Covers COMPANIES ONLY (公司 — 股份/有限公司); sole proprietors and
+ * partnerships (商號) are under a different business-registration resource.
+ * No CORS headers -> server-side only. Use it to cross-check the legal name
+ * and to detect dissolved/revoked status (Company_Status_Desc), which the FIA
+ * tax registry does not carry.
+ */
+const GCIS_COMPANY_RESOURCE = '5F64D864-61CB-4D0D-8AD9-492047CC1EA6';
+export async function gcisCompany(ban, fetchImpl = fetch) {
+    const url = `https://data.gcis.nat.gov.tw/od/data/api/${GCIS_COMPANY_RESOURCE}` +
+        `?$format=json&$filter=Business_Accounting_NO eq ${ban}&$skip=0&$top=1`;
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        return null;
+    const arr = (await res.json());
+    return arr?.[0] ?? null;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@paid-tw/ubn",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Taiwan business registry (統一編號) open dataset + a tiny checkout VAT-to-title lookup client",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paid-tw/tw-ubn.git",
+    "directory": "client"
+  },
+  "homepage": "https://github.com/paid-tw/tw-ubn#readme",
+  "bugs": "https://github.com/paid-tw/tw-ubn/issues",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": ["taiwan", "統一編號", "ubn", "ban", "vat", "einvoice", "open-data"],
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.