@joymerrevent/porters-connect 0.1.0

package/dist/index.js

@@ -0,0 +1,1255 @@
+// src/errors/porters-error.ts
+var PortersError = class extends Error {
+  category;
+  code;
+  retryable;
+  hint;
+  httpStatus;
+  context;
+  constructor(message, options) {
+    super(
+      message,
+      options.cause === void 0 ? void 0 : { cause: options.cause }
+    );
+    this.name = new.target.name;
+    this.category = options.category;
+    this.code = options.code ?? null;
+    this.retryable = options.retryable ?? false;
+    this.hint = options.hint;
+    this.httpStatus = options.httpStatus;
+    this.context = options.context;
+  }
+};
+var PortersAuthError = class extends PortersError {
+};
+var PortersResourceError = class extends PortersError {
+};
+var PortersNetworkError = class extends PortersError {
+};
+var PortersConfigError = class extends PortersError {
+};
+
+// src/errors/classify.ts
+var RESOURCE_VALIDATION = /* @__PURE__ */ new Set([8, 124, 126, 127, 133, 146, 500]);
+var resourceCategory = (code) => {
+  if (code === 9 || code === 302) return "transient";
+  if (code === 401 || code === 402) return "auth";
+  if (code === 6 || code === 400 || code === 403 || code === 406 || code === 601)
+    return "permission";
+  if (code === 7 || code === 404) return "notFound";
+  if (code === 301 || code === 303 || code === 304) return "conflict";
+  if (code === 1e3) return "server";
+  if (RESOURCE_VALIDATION.has(code) || code >= 100 && code <= 116)
+    return "validation";
+  return "unknown";
+};
+var authCategory = (code) => {
+  if (code === 400) return "auth";
+  if ([401, 103, 104, 105, 106, 107, 109, 114, 117].includes(code))
+    return "auth";
+  if ([100, 101, 102, 110, 112].includes(code)) return "validation";
+  if ([111, 115, 116, 402].includes(code)) return "permission";
+  if (code === 108) return "server";
+  return "unknown";
+};
+var resourceHint = (code) => {
+  if (code === 403)
+    return "No data permission. Run the initial browser `code` grant for this Company DB, or check scopes.";
+  if (code === 404)
+    return "Partition not found or outside the contract period. Verify the partition id.";
+  return void 0;
+};
+var resourceError = (code, message, context) => {
+  const category = resourceCategory(code);
+  return new PortersResourceError(message, {
+    category,
+    code,
+    retryable: category === "transient",
+    hint: resourceHint(code),
+    context
+  });
+};
+var authError = (code, message) => {
+  const category = authCategory(code);
+  return new PortersAuthError(message, {
+    category,
+    code,
+    retryable: false,
+    hint: category === "auth" ? "Authentication failed; re-authenticate (browser `code` grant) or check app credentials." : void 0
+  });
+};
+
+// src/xml/parser.ts
+import { XMLParser } from "fast-xml-parser";
+
+// src/xml/raw.ts
+var asRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
+var asString = (v) => typeof v === "string" ? v : void 0;
+var asArray = (v) => {
+  if (Array.isArray(v)) return v;
+  return v === void 0 || v === null ? [] : [v];
+};
+
+// src/xml/parser.ts
+var parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  ignoreDeclaration: true,
+  parseTagValue: false,
+  parseAttributeValue: false,
+  trimValues: true,
+  // asArray() already normalizes a single/missing/repeated <Item> into an array,
+  // so isArray is belt-and-suspenders: these mutants are equivalent (no test can
+  // observe the difference once asArray() runs).
+  // Stryker disable next-line ArrowFunction,ConditionalExpression,StringLiteral: equivalent — asArray() normalizes regardless
+  isArray: (name) => name === "Item"
+});
+var toInt = (v) => {
+  const s = asString(v);
+  return s === void 0 ? 0 : Number(s);
+};
+var parseResourcePage = (xml) => {
+  const root = asRecord(parser.parse(xml));
+  const rootKey = root ? Object.keys(root)[0] : void 0;
+  const body = root && rootKey ? asRecord(root[rootKey]) : void 0;
+  if (!body) {
+    throw new PortersResourceError("unparseable resource response", {
+      category: "unknown"
+    });
+  }
+  const code = toInt(body.Code);
+  if (code !== 0) {
+    throw resourceError(code, `resource returned code ${code}`, {
+      resource: rootKey
+    });
+  }
+  return {
+    total: toInt(body["@_Total"]),
+    count: toInt(body["@_Count"]),
+    start: toInt(body["@_Start"]),
+    items: asArray(body.Item).map((it) => asRecord(it) ?? {})
+  };
+};
+var parseWriteResult = (xml) => {
+  const root = asRecord(parser.parse(xml));
+  const rootKey = root ? Object.keys(root)[0] : void 0;
+  const body = root && rootKey ? asRecord(root[rootKey]) : void 0;
+  if (!body) {
+    throw new PortersResourceError("unparseable write response", {
+      category: "unknown"
+    });
+  }
+  return asArray(body.Item).map((it) => {
+    const item = asRecord(it) ?? {};
+    return { id: toInt(item.Id), code: toInt(item.Code) };
+  });
+};
+var parseAuthentication = (xml) => {
+  const root = asRecord(parser.parse(xml));
+  const body = root ? asRecord(root.Authentication) : void 0;
+  if (!body) {
+    throw new PortersAuthError("unparseable authentication response", {
+      category: "unknown"
+    });
+  }
+  const error = toInt(body.Error);
+  if (error !== 0) {
+    throw authError(
+      error,
+      asString(body.Message) ?? `authentication error ${error}`
+    );
+  }
+  const num = (v) => {
+    const s = asString(v);
+    return s === void 0 ? void 0 : Number(s);
+  };
+  return {
+    code: asString(body.Code),
+    accessToken: asString(body.AccessToken),
+    accessTokenExpiresIn: num(body.AccessTokenExpiresIn),
+    refreshToken: asString(body.RefreshToken),
+    refreshTokenExpiresIn: num(body.RefreshTokenExpiresIn)
+  };
+};
+
+// src/auth/memory-store.ts
+var createMemoryTokenStore = () => {
+  let tokens;
+  return {
+    get: () => Promise.resolve(tokens),
+    set: (t) => {
+      tokens = t;
+      return Promise.resolve();
+    },
+    clear: () => {
+      tokens = void 0;
+      return Promise.resolve();
+    }
+  };
+};
+
+// src/auth/token-provider.ts
+var DEFAULT_MARGIN_MS = 6e4;
+var createDefaultTokenProvider = (opts) => {
+  const store = opts.tokenStore ?? createMemoryTokenStore();
+  const margin = opts.refreshMarginMs ?? DEFAULT_MARGIN_MS;
+  const now = opts.now ?? (() => Date.now());
+  let cached;
+  let inflight;
+  const accessValid = (t) => t !== void 0 && now() < t.accessTokenExpiresAt - margin;
+  const canRefresh = (t) => t !== void 0 && now() < t.refreshTokenExpiresAt - margin;
+  const exchange = async (grantType, code) => {
+    const body = new URLSearchParams({
+      app_id: opts.appId,
+      secret: opts.appSecret,
+      grant_type: grantType,
+      code
+    }).toString();
+    const res = await opts.transport.send({
+      method: "POST",
+      url: `https://${opts.host}/v1/token`,
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body
+    });
+    const a = parseAuthentication(res.body);
+    if (a.accessToken === void 0 || a.refreshToken === void 0) {
+      throw new PortersAuthError("token response missing tokens", {
+        category: "auth"
+      });
+    }
+    const t = {
+      accessToken: a.accessToken,
+      refreshToken: a.refreshToken,
+      accessTokenExpiresAt: now() + (a.accessTokenExpiresIn ?? 0),
+      refreshTokenExpiresAt: now() + (a.refreshTokenExpiresIn ?? 0)
+    };
+    cached = t;
+    await store.set(t);
+    return t;
+  };
+  const acquire = async () => {
+    const url = `https://${opts.host}/v1/oauth?app_id=${encodeURIComponent(opts.appId)}&response_type=code_direct`;
+    const res = await opts.transport.send({ method: "GET", url, headers: {} });
+    const { code } = parseAuthentication(res.body);
+    if (code === void 0) {
+      throw new PortersAuthError("code_direct returned no code", {
+        category: "auth"
+      });
+    }
+    return exchange("oauth_code", code);
+  };
+  const renew = async () => {
+    if (cached === void 0) cached = await store.get();
+    if (canRefresh(cached)) {
+      return exchange("refresh_token", cached.refreshToken);
+    }
+    return acquire();
+  };
+  const ensure = (forceRefresh) => {
+    if (!forceRefresh && accessValid(cached)) return Promise.resolve(cached);
+    return inflight ??= renew().finally(() => {
+      inflight = void 0;
+    });
+  };
+  return {
+    getAccessToken: async (o) => (await ensure(o?.forceRefresh ?? false)).accessToken
+  };
+};
+
+// src/http/fetch-transport.ts
+var createFetchTransport = (opts = {}) => {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  return {
+    send: async (req) => {
+      try {
+        const res = await doFetch(req.url, {
+          method: req.method,
+          headers: req.headers,
+          body: req.body,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+        return { status: res.status, body: await res.text() };
+      } catch (cause) {
+        throw new PortersNetworkError("transport request failed", {
+          category: "network",
+          retryable: true,
+          cause
+        });
+      }
+    }
+  };
+};
+
+// src/http/mock-transport.ts
+var AUTH_CODE_XML = `<Authentication><Code>mock-code</Code><Error>0</Error></Authentication>`;
+var AUTH_TOKEN_XML = `<Authentication><AccessToken>mock-access-token</AccessToken><AccessTokenExpiresIn>1800000</AccessTokenExpiresIn><RefreshToken>mock-refresh-token</RefreshToken><RefreshTokenExpiresIn>7200000</RefreshTokenExpiresIn><Error>0</Error></Authentication>`;
+var toResponse = (reply) => typeof reply === "string" ? { status: 200, body: reply } : { status: reply.status ?? 200, body: reply.body };
+var routeLabel = (method, url) => {
+  try {
+    return `${method} ${new URL(url).pathname}`;
+  } catch {
+    return `${method} ${url}`;
+  }
+};
+var createMockTransport = (handler, options = {}) => {
+  const autoAuth = options.auth ?? true;
+  return {
+    send: (req) => {
+      if (autoAuth && req.url.includes("/v1/token")) {
+        return Promise.resolve({ status: 200, body: AUTH_TOKEN_XML });
+      }
+      if (autoAuth && req.url.includes("/v1/oauth")) {
+        return Promise.resolve({ status: 200, body: AUTH_CODE_XML });
+      }
+      const reply = handler(req);
+      if (reply === void 0) {
+        return Promise.reject(
+          new PortersConfigError(
+            `createMockTransport: no mock response for ${routeLabel(req.method, req.url)} \u2014 add a case to your handler (or pass { auth: false } to mock the auth endpoints too)`,
+            { category: "config" }
+          )
+        );
+      }
+      return Promise.resolve(toResponse(reply));
+    }
+  };
+};
+
+// src/http/throttle.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var makeBucket = (capacity, now) => {
+  const ratePerMs = capacity / 6e4;
+  let tokens = capacity;
+  let last = now();
+  return async () => {
+    for (; ; ) {
+      const t = now();
+      tokens = Math.min(capacity, tokens + (t - last) * ratePerMs);
+      last = t;
+      if (tokens >= 1) {
+        tokens -= 1;
+        return;
+      }
+      await sleep(Math.ceil((1 - tokens) / ratePerMs));
+    }
+  };
+};
+var createThrottle = (opts = {}) => {
+  const safety = opts.safety ?? 0.9;
+  const now = opts.now ?? (() => Date.now());
+  const read = makeBucket(Math.floor((opts.readPerMin ?? 2e3) * safety), now);
+  const write = makeBucket(Math.floor((opts.writePerMin ?? 500) * safety), now);
+  return { take: (isWrite) => isWrite ? write() : read() };
+};
+
+// src/http/retry.ts
+var expoBackoff = (baseMs = 200, maxMs = 8e3) => (attempt) => Math.floor(Math.random() * Math.min(maxMs, baseMs * 2 ** attempt));
+
+// src/http/requester.ts
+var API_VERSION = "2";
+var MAX_REQUEST_LENGTH = 15e3;
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var withAuth = (req, token, write) => ({
+  ...req,
+  headers: {
+    ...req.headers,
+    "X-porters-hrbc-oauth-token": token,
+    "X-P-ConnectAPI-Version": API_VERSION,
+    ...write ? { "Content-Type": "application/xml; charset=UTF-8" } : {}
+  }
+});
+var createRequester = (o) => {
+  const maxRetries = o.maxRetries ?? 3;
+  const request = async (req, parse, spec = {}) => {
+    const requestLength = req.url.length + (req.body?.length ?? 0);
+    if (!spec.unboundedBody && requestLength > MAX_REQUEST_LENGTH) {
+      throw new PortersConfigError(
+        `request is ${requestLength} characters, over the ~${MAX_REQUEST_LENGTH}-character limit`,
+        {
+          category: "config",
+          hint: "Shorten the request: narrow a read's field/condition, or split a write into batches of 200 or fewer records (PORTERS caps a request at ~15000 characters)."
+        }
+      );
+    }
+    const write = spec.write ?? false;
+    const idempotent = spec.idempotent ?? !write;
+    let authRetried = false;
+    let forceRefresh = false;
+    let attempt = 0;
+    for (; ; ) {
+      await o.throttle.take(write);
+      try {
+        const token = await o.auth.getAccessToken(
+          forceRefresh ? { forceRefresh: true } : void 0
+        );
+        forceRefresh = false;
+        const res = await o.transport.send(withAuth(req, token, write));
+        return parse(res.body);
+      } catch (e) {
+        if (!(e instanceof PortersError)) throw e;
+        if ((e.code === 401 || e.code === 402) && !authRetried) {
+          authRetried = true;
+          forceRefresh = true;
+          continue;
+        }
+        if (e instanceof PortersNetworkError && write && !idempotent) throw e;
+        if (e.retryable && attempt < maxRetries) {
+          attempt += 1;
+          await sleep2(o.backoff(attempt - 1));
+          continue;
+        }
+        throw e;
+      }
+    }
+  };
+  return { request };
+};
+
+// src/util/datetime.ts
+var DATETIME_RE = /^(\d{4})\/(\d{2})\/(\d{2}) (\d{2}):(\d{2}):(\d{2})$/;
+var DATE_RE = /^(\d{4})\/(\d{2})\/(\d{2})$/;
+var ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})/;
+var portersDateTimeToIso = (value) => {
+  const m = DATETIME_RE.exec(value);
+  if (!m) throw new RangeError(`invalid PORTERS DateTime: "${value}"`);
+  const iso = `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`;
+  if (Number.isNaN(Date.parse(iso))) {
+    throw new RangeError(`invalid PORTERS DateTime: "${value}"`);
+  }
+  return iso;
+};
+var isoToPortersDateTime = (value) => {
+  const t = Date.parse(value);
+  if (Number.isNaN(t)) throw new RangeError(`invalid ISO datetime: "${value}"`);
+  const d = new Date(t);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getUTCFullYear()}/${pad(d.getUTCMonth() + 1)}/${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+};
+var portersDateToIso = (value) => {
+  const m = DATE_RE.exec(value);
+  if (!m) throw new RangeError(`invalid PORTERS Date: "${value}"`);
+  return `${m[1]}-${m[2]}-${m[3]}`;
+};
+var isoToPortersDate = (value) => {
+  const m = ISO_DATE_RE.exec(value);
+  if (!m) throw new RangeError(`invalid ISO date: "${value}"`);
+  return `${m[1]}/${m[2]}/${m[3]}`;
+};
+
+// src/xml/encode.ts
+var escapeXml = (s) => s.replace(
+  /[&<>]/g,
+  (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"
+);
+var scalar = (v) => escapeXml(String(v));
+var encodeField = (type, value) => {
+  switch (type) {
+    // Option: the selected aliases as empty child elements. Canonical input is an
+    // array (ADR-0017, symmetric with read); a lone string is wrapped as a 1-element
+    // selection (fail-safe).
+    case "Option":
+      return (Array.isArray(value) ? value : [value]).map((alias) => `<${alias}/>`).join("");
+    // System[DateTime] (registration/update) is Write-restricted by PORTERS; we still
+    // serialize it identically — rejecting the write is the input type's job (SD-3).
+    case "DateTime":
+    case "System[DateTime]":
+      return scalar(isoToPortersDateTime(String(value)));
+    // Age shares Date's wire format (`yyyy/mm/dd`): we write the birthdate.
+    case "Date":
+    case "Age":
+      return scalar(isoToPortersDate(String(value)));
+    // System[Id] / Number / User & System[Reference] (ID-only) / string Data Types all
+    // serialize as a scalar (the string types stay distinct labels per ADR-0016).
+    case "System[Id]":
+    case "Number":
+    case "User":
+    case "System[Reference]":
+    case "SinglelineText":
+    case "MultilineText":
+    case "Mail":
+    case "Telephone":
+    case "URL":
+      return scalar(value);
+  }
+};
+var encodeItem = (prefix, fields, item) => {
+  const parts = [];
+  for (const [alias, value] of Object.entries(item)) {
+    if (value === null || value === void 0) continue;
+    const type = fields.get(alias);
+    const inner = type === void 0 ? scalar(value) : encodeField(type, value);
+    parts.push(`<${prefix}.${alias}>${inner}</${prefix}.${alias}>`);
+  }
+  return parts.join("");
+};
+var buildWriteXml = (config) => {
+  const items = config.items.map(
+    (item) => `<Item>${encodeItem(config.prefix, config.fields, item)}</Item>`
+  ).join("");
+  return `<${config.resource}>${items}</${config.resource}>`;
+};
+
+// src/xml/decode.ts
+var pickPrefixed = (obj, prefix, key) => asString(obj[`${prefix}.${key}`]) ?? asString(obj[key]);
+var decodeUser = (raw) => {
+  const outer = asRecord(raw);
+  const user = outer ? asRecord(outer.User) : void 0;
+  if (!user) return null;
+  const id = pickPrefixed(user, "User", "P_Id");
+  return {
+    P_Id: id === void 0 ? null : Number(id),
+    P_Type: pickPrefixed(user, "User", "P_Type") ?? null,
+    P_Name: pickPrefixed(user, "User", "P_Name") ?? null,
+    P_Mail: pickPrefixed(user, "User", "P_Mail") ?? null
+  };
+};
+var decodeOption = (raw) => {
+  const outer = asRecord(raw);
+  if (!outer) return null;
+  const root = "OptionRoot" in outer ? asRecord(outer.OptionRoot) : outer;
+  if (!root) return null;
+  const keys = Object.keys(root);
+  return keys.length > 0 ? keys : null;
+};
+var decodeReference = (raw) => {
+  const outer = asRecord(raw);
+  if (!outer) return null;
+  for (const [tag2, value] of Object.entries(outer)) {
+    const inner = asRecord(value);
+    if (!inner) continue;
+    const id = asString(inner[`${tag2}.P_Id`]) ?? asString(inner.P_Id);
+    return id === void 0 ? null : Number(id);
+  }
+  return null;
+};
+var decodeField = (type, raw) => {
+  if (raw === "" || raw === void 0 || raw === null) return null;
+  switch (type) {
+    case "System[Id]":
+    case "Number": {
+      const s = asString(raw);
+      return s === void 0 ? null : Number(s);
+    }
+    // String Data Types share one decode (a plain string); they stay distinct
+    // labels for fidelity / future per-type validation (ADR-0016).
+    case "SinglelineText":
+    case "MultilineText":
+    case "Mail":
+    case "Telephone":
+    case "URL":
+      return asString(raw) ?? null;
+    // FT-12 DateTime and the system timestamps (registration/update) share the wire
+    // format; System[DateTime] is Write-restricted, but that is a write-time concern.
+    case "DateTime":
+    case "System[DateTime]": {
+      const s = asString(raw);
+      return s === void 0 ? null : portersDateTimeToIso(s);
+    }
+    // Age shares Date's wire format (`yyyy/mm/dd`); PORTERS transmits the birthdate
+    // and derives the age in its UI, so the faithful value is the date itself.
+    case "Date":
+    case "Age": {
+      const s = asString(raw);
+      return s === void 0 ? null : portersDateToIso(s);
+    }
+    case "User":
+      return decodeUser(raw);
+    case "Option":
+      return decodeOption(raw);
+    case "System[Reference]":
+      return decodeReference(raw);
+  }
+};
+
+// src/resources/read-core.ts
+var bareAlias = (key) => key.includes(".") ? key.slice(key.indexOf(".") + 1) : key;
+var decoderFor = (fields) => {
+  const fieldMap = new Map(Object.entries(fields));
+  return (item) => {
+    const out = {};
+    for (const [key, raw] of Object.entries(item)) {
+      const alias = bareAlias(key);
+      const type = fieldMap.get(alias);
+      out[alias] = type ? decodeField(type, raw) : typeof raw === "string" ? raw : null;
+    }
+    return out;
+  };
+};
+var runRead = (requester, url, decode) => requester.request({ method: "GET", url, headers: {} }, (body) => {
+  const page = parseResourcePage(body);
+  return {
+    items: page.items.map(decode),
+    total: page.total,
+    count: page.count,
+    start: page.start
+  };
+});
+var PAGE_SIZE = 200;
+var paginate = async function* (fetchPage) {
+  let start = 0;
+  for (; ; ) {
+    const page = await fetchPage(PAGE_SIZE, start);
+    for (const item of page.items) yield item;
+    start += page.items.length;
+    if (page.items.length === 0 || start >= page.total) return;
+  }
+};
+
+// src/resources/resource.ts
+var USER_SUBFIELDS = ["P_Id", "P_Type", "P_Name", "P_Mail"];
+var defaultFieldList = (prefix, fields) => Object.entries(fields).map(
+  ([alias, type]) => type === "User" ? `${prefix}.${alias}(${USER_SUBFIELDS.map((s) => `User.${s}`).join(",")})` : `${prefix}.${alias}`
+);
+var firstWriteResultId = (body, path, name) => {
+  const first = parseWriteResult(body)[0];
+  if (first === void 0) {
+    throw new PortersResourceError("write returned no result item", {
+      category: "unknown"
+    });
+  }
+  if (first.code !== 0) {
+    throw resourceError(
+      first.code,
+      `${path} write returned code ${first.code}`,
+      {
+        resource: name
+      }
+    );
+  }
+  return first.id;
+};
+var buildReadUrl = (host, partition, path, q) => {
+  const p = new URLSearchParams();
+  p.set("partition", String(partition));
+  if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
+  if (q.condition) {
+    const conds = Object.entries(q.condition).map(([k, v]) => `${k}=${v}`);
+    if (conds.length > 0) p.set("condition", conds.join(","));
+  }
+  if (q.count !== void 0) p.set("count", String(q.count));
+  if (q.start !== void 0) p.set("start", String(q.start));
+  return `https://${host}/v1/${path}?${p.toString()}`;
+};
+var buildWriteUrl = (host, partition, path) => `https://${host}/v1/${path}?partition=${partition}`;
+var createResource = (config, deps) => {
+  const fieldMap = new Map(Object.entries(config.fields));
+  const decode = decoderFor(config.fields);
+  const defaultFields = defaultFieldList(config.prefix, config.fields);
+  const readUrl = (q) => buildReadUrl(deps.host, deps.partition, config.path, q);
+  const writeUrl = () => buildWriteUrl(deps.host, deps.partition, config.path);
+  const firstWriteId = (body) => firstWriteResultId(body, config.path, config.name);
+  const search = (query = {}) => runRead(
+    deps.requester,
+    readUrl({ ...query, field: query.field ?? defaultFields }),
+    decode
+  );
+  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  const get = async (id) => {
+    const page = await search({
+      condition: { [`${config.prefix}.P_Id:eq`]: String(id) },
+      count: 1
+    });
+    return page.items[0];
+  };
+  const write = (item, idempotent) => deps.requester.request(
+    {
+      method: "POST",
+      url: writeUrl(),
+      headers: {},
+      body: buildWriteXml({
+        resource: config.name,
+        prefix: config.prefix,
+        fields: fieldMap,
+        items: [item]
+      })
+    },
+    firstWriteId,
+    { write: true, idempotent }
+  );
+  const create = (input) => write({ ...input, P_Id: -1 }, false);
+  const update = (id, input) => write({ ...input, P_Id: id }, true);
+  return { search, searchAll, get, create, update };
+};
+
+// src/resources/candidate.ts
+var FIELDS = {
+  P_Id: "System[Id]",
+  P_Owner: "User",
+  P_RegistrationDate: "System[DateTime]",
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User",
+  P_Phase: "Option",
+  P_PhaseDate: "DateTime",
+  P_Name: "SinglelineText",
+  P_Reading: "SinglelineText",
+  P_Mail: "Mail",
+  P_MobileMail: "Mail",
+  P_Telephone: "Telephone",
+  P_Mobile: "Telephone",
+  P_Country: "SinglelineText",
+  P_Prefecture: "SinglelineText",
+  P_City: "SinglelineText",
+  P_Zipcode: "SinglelineText"
+};
+var REQUIRED_ON_CREATE = [
+  "P_Owner"
+];
+var createCandidateResource = (deps, custom) => {
+  const fields = { ...FIELDS, ...custom };
+  return createResource(
+    {
+      name: "Candidate",
+      path: "candidate",
+      prefix: "Person",
+      fields,
+      requiredOnCreate: REQUIRED_ON_CREATE
+    },
+    deps
+  );
+};
+
+// src/resources/job.ts
+var FIELDS2 = {
+  P_Id: "System[Id]",
+  P_Owner: "User",
+  P_Client: "System[Reference]",
+  P_Recruiter: "System[Reference]",
+  P_RegistrationDate: "System[DateTime]",
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User",
+  P_Phase: "Option",
+  P_PhaseDate: "DateTime",
+  P_PhaseMemo: "MultilineText",
+  P_Position: "SinglelineText",
+  P_Publish: "Option",
+  P_JobCategorySummary: "MultilineText",
+  P_JobCategory: "Option",
+  P_IndustrySummary: "MultilineText",
+  P_Industry: "Option",
+  P_SalarySummary: "MultilineText",
+  P_MinSalary: "Number",
+  P_MaxSalary: "Number",
+  P_AreaSummary: "MultilineText",
+  P_Area: "Option",
+  P_PayrollsText: "SinglelineText",
+  P_Memo: "MultilineText",
+  P_EmploymentPeriod: "MultilineText",
+  // "P_WokingHours" is the alias as published by PORTERS (source typo); keep verbatim.
+  P_WokingHours: "MultilineText",
+  P_Holidays: "MultilineText",
+  P_Benefits: "MultilineText",
+  P_PubliclyTraded: "Option",
+  P_SalesAmountText: "SinglelineText",
+  P_EstablishmentDateText: "SinglelineText",
+  P_CapitalText: "SinglelineText",
+  P_EmploymentType: "Option",
+  P_ExpectedAgeReason: "Option"
+};
+var REQUIRED_ON_CREATE2 = [
+  "P_Owner",
+  "P_Client",
+  "P_Recruiter"
+];
+var createJobResource = (deps, custom) => {
+  const fields = { ...FIELDS2, ...custom };
+  return createResource(
+    {
+      name: "Job",
+      path: "job",
+      prefix: "Job",
+      fields,
+      requiredOnCreate: REQUIRED_ON_CREATE2
+    },
+    deps
+  );
+};
+
+// src/resources/client.ts
+var FIELDS3 = {
+  P_Id: "System[Id]",
+  P_Owner: "User",
+  P_RegistrationDate: "System[DateTime]",
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User",
+  P_Phase: "Option",
+  P_PhaseDate: "DateTime",
+  P_PhaseMemo: "MultilineText",
+  P_Name: "SinglelineText",
+  P_Memo: "MultilineText",
+  P_Country: "SinglelineText",
+  P_Prefecture: "SinglelineText",
+  P_City: "SinglelineText",
+  P_Street: "MultilineText",
+  P_Zipcode: "SinglelineText",
+  P_Telephone: "Telephone",
+  P_Fax: "Telephone"
+};
+var REQUIRED_ON_CREATE3 = [
+  "P_Owner"
+];
+var createClientResource = (deps, custom) => {
+  const fields = { ...FIELDS3, ...custom };
+  return createResource(
+    {
+      name: "Client",
+      path: "client",
+      prefix: "Client",
+      fields,
+      requiredOnCreate: REQUIRED_ON_CREATE3
+    },
+    deps
+  );
+};
+
+// src/resources/process.ts
+var FIELDS4 = {
+  P_Id: "System[Id]",
+  P_Owner: "User",
+  P_Client: "System[Reference]",
+  P_Recruiter: "System[Reference]",
+  P_Job: "System[Reference]",
+  P_Candidate: "System[Reference]",
+  P_Resume: "System[Reference]",
+  P_RegistrationDate: "System[DateTime]",
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User",
+  P_Phase: "Option",
+  P_PhaseDate: "DateTime",
+  P_PhaseMemo: "MultilineText",
+  P_Close: "Option",
+  P_CloseReason: "Option",
+  P_ExpectedSalesAmount: "Number",
+  P_ExpectedClosingDate: "Date"
+};
+var REQUIRED_ON_CREATE4 = [
+  "P_Owner",
+  "P_Client",
+  "P_Recruiter",
+  "P_Job",
+  "P_Candidate",
+  "P_Resume"
+];
+var createProcessResource = (deps, custom) => {
+  const fields = { ...FIELDS4, ...custom };
+  return createResource(
+    {
+      name: "Process",
+      path: "process",
+      prefix: "Process",
+      fields,
+      requiredOnCreate: REQUIRED_ON_CREATE4
+    },
+    deps
+  );
+};
+
+// src/resources/resume.ts
+var FIELDS5 = {
+  P_Id: "System[Id]",
+  P_Owner: "User",
+  P_Candidate: "System[Reference]",
+  P_RegistrationDate: "System[DateTime]",
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User",
+  P_Phase: "Option",
+  P_PhaseDate: "DateTime",
+  P_PhaseMemo: "MultilineText",
+  P_Name: "SinglelineText",
+  P_RegisterChannel: "Option",
+  P_Memo: "MultilineText",
+  P_CurrentStatus: "Option",
+  P_Education: "MultilineText",
+  P_CarrierSummary: "MultilineText",
+  P_CurrentSalary: "Number",
+  P_ExperiencedJobCategory: "Option",
+  P_ExperiencedIndustry: "Option",
+  P_ChangeJobsCount: "Number",
+  P_Gender: "Option",
+  P_DateOfBirth: "Age",
+  P_ExpectEmploymentType: "Option",
+  P_ExpectArea: "Option",
+  P_ExpectJobCategory: "Option",
+  P_ExpectIndustry: "Option",
+  P_ExpectCondition: "MultilineText",
+  P_ExpectSalary: "Number",
+  P_DesiredHourlyRate: "Number",
+  P_HourlyRate: "Number"
+};
+var REQUIRED_ON_CREATE5 = [
+  "P_Owner",
+  "P_Candidate"
+];
+var createResumeResource = (deps, custom) => {
+  const fields = { ...FIELDS5, ...custom };
+  return createResource(
+    {
+      name: "Resume",
+      path: "resume",
+      prefix: "Resume",
+      fields,
+      requiredOnCreate: REQUIRED_ON_CREATE5
+    },
+    deps
+  );
+};
+
+// src/resources/attachment.ts
+var MAX_CONTENT_CHARS = 14e6;
+var ALL_FIELDS = [
+  "Id",
+  "Resource",
+  "ResourceId",
+  "ContentType",
+  "FileName",
+  "Content"
+];
+var DEFAULT_FIELDS = [
+  "Id",
+  "Resource",
+  "ResourceId",
+  "ContentType",
+  "FileName"
+];
+var numOrNull = (v) => {
+  const s = asString(v);
+  return s === void 0 ? null : Number(s);
+};
+var decodeAttachment = (item) => ({
+  id: numOrNull(item.Id),
+  resource: numOrNull(item.Resource),
+  resourceId: numOrNull(item.ResourceId),
+  contentType: asString(item.ContentType) ?? null,
+  fileName: asString(item.FileName) ?? null,
+  content: asString(item.Content) ?? null
+});
+var tag = (name, value) => `<${name}>${encodeField("SinglelineText", String(value))}</${name}>`;
+var guardContent = (content) => {
+  if (content !== void 0 && content.length > MAX_CONTENT_CHARS) {
+    throw new PortersConfigError(
+      `attachment content is ${content.length} characters, over the ~10MB file limit`,
+      { category: "config", hint: "Attachment files must be 10MB or less." }
+    );
+  }
+};
+var createAttachmentResource = (deps) => {
+  const search = (query = {}) => deps.requester.request(
+    {
+      method: "GET",
+      url: buildReadUrl(deps.host, deps.partition, "attachment", {
+        ...query,
+        field: query.field ?? DEFAULT_FIELDS
+      }),
+      headers: {}
+    },
+    (body) => {
+      const page = parseResourcePage(body);
+      return {
+        items: page.items.map(decodeAttachment),
+        total: page.total,
+        count: page.count,
+        start: page.start
+      };
+    }
+  );
+  const get = async (id) => {
+    const page = await search({
+      field: ALL_FIELDS,
+      condition: { "Id:eq": String(id) },
+      count: 1
+    });
+    return page.items[0];
+  };
+  const write = (inner, idempotent) => deps.requester.request(
+    {
+      method: "POST",
+      url: buildWriteUrl(deps.host, deps.partition, "attachment"),
+      headers: {},
+      body: `<Attachment><Item>${inner}</Item></Attachment>`
+    },
+    (body) => firstWriteResultId(body, "attachment", "Attachment"),
+    { write: true, idempotent, unboundedBody: true }
+  );
+  const create = (input) => {
+    guardContent(input.content);
+    const inner = tag("Id", -1) + tag("Resource", input.resource) + tag("ResourceId", input.resourceId) + tag("ContentType", input.contentType) + tag("FileName", input.fileName) + tag("Content", input.content);
+    return write(inner, false);
+  };
+  const update = (id, input) => {
+    guardContent(input.content);
+    let inner = tag("Id", id);
+    if (input.contentType !== void 0) {
+      inner += tag("ContentType", input.contentType);
+    }
+    if (input.fileName !== void 0) inner += tag("FileName", input.fileName);
+    if (input.content !== void 0) inner += tag("Content", input.content);
+    return write(inner, true);
+  };
+  return { search, get, create, update };
+};
+
+// src/resources/partition.ts
+var FIELDS6 = {
+  P_Id: "System[Id]",
+  P_Name: "SinglelineText",
+  P_CompanyId: "SinglelineText"
+};
+var buildUrl = (host, q) => {
+  const p = new URLSearchParams();
+  p.set("request_type", String(q.requestType ?? 1));
+  if (q.count !== void 0) p.set("count", String(q.count));
+  if (q.start !== void 0) p.set("start", String(q.start));
+  return `https://${host}/v1/partition?${p.toString()}`;
+};
+var createPartitionResource = (deps) => {
+  const decode = decoderFor(FIELDS6);
+  const search = (query = {}) => runRead(deps.requester, buildUrl(deps.host, query), decode);
+  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  return { search, searchAll };
+};
+
+// src/resources/user.ts
+var FIELDS7 = {
+  P_Id: "System[Id]",
+  P_Type: "Number",
+  P_Name: "SinglelineText",
+  P_Mail: "Mail"
+};
+var buildUrl2 = (host, partition, q) => {
+  const p = new URLSearchParams();
+  p.set("partition", String(partition));
+  p.set("request_type", String(q.requestType ?? 1));
+  p.set("user_type", String(q.userType ?? -1));
+  if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
+  if (q.count !== void 0) p.set("count", String(q.count));
+  if (q.start !== void 0) p.set("start", String(q.start));
+  return `https://${host}/v1/user?${p.toString()}`;
+};
+var createUserResource = (deps) => {
+  const decode = decoderFor(FIELDS7);
+  const search = (query = {}) => runRead(deps.requester, buildUrl2(deps.host, deps.partition, query), decode);
+  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  const current = async () => (await search({ requestType: 0, count: 1 })).items[0];
+  return { search, searchAll, current };
+};
+
+// src/resources/field.ts
+var RESOURCE_VALUE = {
+  candidate: 1,
+  job: 3,
+  client: 5,
+  recruiter: 9,
+  sales: 11,
+  contract: 13,
+  resume: 17,
+  activity: 19,
+  opportunity: 25,
+  contact: 27
+};
+var FIELDS8 = {
+  P_Id: "System[Id]",
+  P_Name: "SinglelineText",
+  P_Alias: "SinglelineText",
+  P_Type: "Number",
+  P_Required: "Number",
+  P_Max: "Number",
+  P_Min: "Number",
+  P_DecimalFraction: "Number",
+  // Nested alias(es): the referenced option group / parent field. Reuse Option decode -> the
+  // referenced alias(es) as string[] (usually one); empty -> null (ADR-0017/0022).
+  // VERIFY(live): Reference-type P_ReferTo nesting is doc-only. See docs/live-verification.md (LV-6).
+  P_ReferTo: "Option",
+  P_ResourceType: "Number"
+};
+var buildUrl3 = (host, partition, q) => {
+  const p = new URLSearchParams();
+  p.set("partition", String(partition));
+  p.set("resource", String(RESOURCE_VALUE[q.resource]));
+  p.set("active", String(q.active ?? -1));
+  if (q.count !== void 0) p.set("count", String(q.count));
+  if (q.start !== void 0) p.set("start", String(q.start));
+  return `https://${host}/v1/field?${p.toString()}`;
+};
+var createFieldResource = (deps) => {
+  const decode = decoderFor(FIELDS8);
+  const search = (query) => runRead(deps.requester, buildUrl3(deps.host, deps.partition, query), decode);
+  const searchAll = (query) => paginate((count, start) => search({ ...query, count, start }));
+  return { search, searchAll };
+};
+
+// src/resources/option.ts
+var FIELDS9 = {
+  P_Id: "System[Id]",
+  P_Name: "SinglelineText",
+  P_Alias: "SinglelineText",
+  P_ParentId: "Number",
+  P_Type: "Number",
+  P_Order: "Number"
+};
+var buildUrl4 = (host, partition, q) => {
+  const p = new URLSearchParams();
+  p.set("partition", String(partition));
+  if (q.alias !== void 0) p.set("alias", q.alias);
+  if (q.level !== void 0) p.set("level", String(q.level));
+  if (q.enabled !== void 0) p.set("enabled", String(q.enabled));
+  if (q.count !== void 0) p.set("count", String(q.count));
+  return `https://${host}/v1/option?${p.toString()}`;
+};
+var withoutItems = (raw) => Object.fromEntries(Object.entries(raw).filter(([k]) => k !== "Items"));
+var createOptionResource = (deps) => {
+  const decode = decoderFor(FIELDS9);
+  const flatten = (items, out) => {
+    for (const raw of items) {
+      out.push(decode(withoutItems(raw)));
+      const children = asArray(asRecord(raw.Items)?.Item).map(
+        (it) => asRecord(it) ?? {}
+      );
+      flatten(children, out);
+    }
+  };
+  const search = (query = {}) => deps.requester.request(
+    {
+      method: "GET",
+      url: buildUrl4(deps.host, deps.partition, query),
+      headers: {}
+    },
+    (body) => {
+      const out = [];
+      flatten(parseResourcePage(body).items, out);
+      return out;
+    }
+  );
+  return { search };
+};
+
+// src/client.ts
+var PortersClient = class {
+  candidate;
+  job;
+  client;
+  process;
+  resume;
+  attachment;
+  /** Master Read: accessible partitions (ADR-0021/0022). */
+  partition;
+  /** Master Read: users, plus `current()` self-identification (ADR-0021/0022). */
+  user;
+  /** Master Read: a resource's field catalog (ADR-0021/0022). */
+  field;
+  /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
+  option;
+  #host;
+  constructor(options) {
+    const transport = options.transport ?? createFetchTransport();
+    const auth = options.auth ?? createDefaultTokenProvider({
+      host: options.host,
+      appId: options.appId ?? "",
+      appSecret: options.appSecret ?? "",
+      transport,
+      tokenStore: options.tokenStore
+    });
+    const requester = createRequester({
+      transport,
+      auth,
+      throttle: createThrottle(),
+      backoff: expoBackoff()
+    });
+    this.#host = options.host;
+    const deps = {
+      requester,
+      host: options.host,
+      partition: options.partition ?? 0
+    };
+    const customFor = (key) => options.fields?.[key] ?? {};
+    this.candidate = createCandidateResource(deps, customFor("candidate"));
+    this.job = createJobResource(deps, customFor("job"));
+    this.client = createClientResource(deps, customFor("client"));
+    this.process = createProcessResource(deps, customFor("process"));
+    this.resume = createResumeResource(deps, customFor("resume"));
+    this.attachment = createAttachmentResource(deps);
+    this.partition = createPartitionResource({ requester, host: options.host });
+    this.user = createUserResource(deps);
+    this.field = createFieldResource(deps);
+    this.option = createOptionResource(deps);
+  }
+  /** The configured API host. */
+  get host() {
+    return this.#host;
+  }
+};
+
+// src/fields/define-fields.ts
+var def = (dataType) => ({
+  dataType
+});
+var builder = {
+  number: () => def("Number"),
+  singlelineText: () => def("SinglelineText"),
+  multilineText: () => def("MultilineText"),
+  mail: () => def("Mail"),
+  telephone: () => def("Telephone"),
+  url: () => def("URL"),
+  date: () => def("Date"),
+  dateTime: () => def("DateTime"),
+  age: () => def("Age"),
+  option: () => def("Option"),
+  user: () => def("User")
+};
+var ALIAS_PATTERN = /^[UA]_/;
+var KNOWN_RESOURCES = [
+  "candidate",
+  "job",
+  "client",
+  "process",
+  "resume"
+];
+var defineFields = (decls) => {
+  const catalogs = {};
+  for (const [resource, declare] of Object.entries(decls)) {
+    if (declare === void 0) continue;
+    if (!KNOWN_RESOURCES.includes(resource)) {
+      throw new PortersConfigError(
+        `defineFields: unknown resource "${resource}" (expected one of ${KNOWN_RESOURCES.join(", ")})`,
+        { category: "config" }
+      );
+    }
+    const catalog = {};
+    for (const [alias, fieldDef] of Object.entries(declare(builder))) {
+      if (!ALIAS_PATTERN.test(alias)) {
+        throw new PortersConfigError(
+          `defineFields: custom field alias "${alias}" on "${resource}" must start with "U_" or "A_" (standard P_ fields are built in)`,
+          { category: "config" }
+        );
+      }
+      catalog[alias] = fieldDef.dataType;
+    }
+    catalogs[resource] = catalog;
+  }
+  return Object.freeze(catalogs);
+};
+
+// src/util/base64.ts
+var bytesToBase64 = (bytes) => {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+};
+var base64ToBytes = (b64) => Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+export {
+  PortersAuthError,
+  PortersClient,
+  PortersConfigError,
+  PortersError,
+  PortersNetworkError,
+  PortersResourceError,
+  base64ToBytes,
+  bytesToBase64,
+  createMockTransport,
+  defineFields
+};
+//# sourceMappingURL=index.js.map