node-autotask 0.69.1 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -618,6 +618,27 @@ function isKnownZone(zone) {
618
618
  return typeof zone === "string" && ZONES.includes(zone);
619
619
  }
620
620
 
621
+ // src/metadata-projection.ts
622
+ var METADATA_PROJECTION = /* @__PURE__ */ Symbol.for("node-autotask.metadata-projection.v1");
623
+ function projectMetadata(value, projector) {
624
+ return structuredClone(projector(value));
625
+ }
626
+ async function readMetadataProjection(holder, kind, projector, fallbackReader) {
627
+ const hook = holder !== null && (typeof holder === "object" || typeof holder === "function") ? holder[METADATA_PROJECTION] : void 0;
628
+ const owned = hook?.call(holder, kind, projector);
629
+ owned?.guard();
630
+ if (owned?.projected !== void 0) {
631
+ const value2 = await owned.projected;
632
+ owned.guard();
633
+ return value2;
634
+ }
635
+ const raw = await fallbackReader();
636
+ owned?.guard();
637
+ const value = projector(raw);
638
+ owned?.guard();
639
+ return value;
640
+ }
641
+
621
642
  // src/cache.ts
622
643
  var READ_CACHE_MAX_ENTRIES = 4096;
623
644
  var REFERENCE_TTL_MS = 36e5;
@@ -630,6 +651,7 @@ function readTtlFor(key, ttlMs) {
630
651
  const entity = key.split("\0")[0].split("/").at(-2);
631
652
  return entity !== void 0 && REFERENCE_ENTITIES.includes(entity) ? Math.max(ttlMs, REFERENCE_TTL_MS) : ttlMs;
632
653
  }
654
+ var MAX_ENTRY_PROJECTIONS = 8;
633
655
  var TtlCache = class {
634
656
  ttlMs;
635
657
  maxEntries;
@@ -650,15 +672,38 @@ var TtlCache = class {
650
672
  this.maxEntries = maxEntries;
651
673
  this.ttlFor = options.ttlFor ?? (() => ttlMs);
652
674
  }
653
- /** The live value (a copy), or `undefined` when absent or expired. */
654
- get(key) {
675
+ liveEntry(key) {
655
676
  const entry = this.store.get(key);
656
677
  if (entry === void 0) return void 0;
657
678
  if (entry.expiresAt <= Date.now()) {
658
679
  this.store.delete(key);
659
680
  return void 0;
660
681
  }
661
- return structuredClone(entry.value);
682
+ return entry;
683
+ }
684
+ /** The live value (a copy), or `undefined` when absent or expired. */
685
+ get(key) {
686
+ const entry = this.liveEntry(key);
687
+ return entry === void 0 ? void 0 : structuredClone(entry.value);
688
+ }
689
+ projectEntry(key, entry, projector) {
690
+ if (entry.projections?.has(projector)) return structuredClone(entry.projections.get(projector));
691
+ const value = projectMetadata(structuredClone(entry.value), projector);
692
+ if (this.store.get(key) === entry && entry.expiresAt > Date.now()) {
693
+ const projections = entry.projections ??= /* @__PURE__ */ new Map();
694
+ if (projections.size >= MAX_ENTRY_PROJECTIONS) {
695
+ const oldest = projections.keys().next();
696
+ if (!oldest.done) projections.delete(oldest.value);
697
+ }
698
+ projections.set(projector, value);
699
+ return structuredClone(value);
700
+ }
701
+ return value;
702
+ }
703
+ /** Clone a live derived value without cloning the full metadata on each hit. @internal */
704
+ getProjected(key, projector) {
705
+ const entry = this.liveEntry(key);
706
+ return entry === void 0 ? void 0 : this.projectEntry(key, entry, projector);
662
707
  }
663
708
  /**
664
709
  * Load one record once for concurrent callers. Each subscriber owns its
@@ -669,12 +714,23 @@ var TtlCache = class {
669
714
  * `shouldStore` controls retention, never the result returned to subscribers.
670
715
  * @internal
671
716
  */
672
- async load(key, loader, opts) {
717
+ load(key, loader, opts) {
718
+ return this.loadValue(key, loader, opts);
719
+ }
720
+ /** Projected and raw subscribers share the same raw flight and retention policy. @internal */
721
+ loadProjected(key, loader, projector, opts) {
722
+ return this.loadValue(key, loader, opts, projector);
723
+ }
724
+ async loadValue(key, loader, opts, projector) {
673
725
  const { signal } = opts;
674
726
  if (signal?.aborted) throw opts.abortError();
675
727
  if (!opts.fresh) {
676
- const hit = this.get(key);
677
- if (hit !== void 0) return hit;
728
+ const entry = this.liveEntry(key);
729
+ if (entry !== void 0 && entry.value !== void 0) {
730
+ const hit = projector === void 0 ? structuredClone(entry.value) : this.projectEntry(key, entry, projector);
731
+ if (signal?.aborted) throw opts.abortError();
732
+ return hit;
733
+ }
678
734
  }
679
735
  let flight = opts.fresh ? void 0 : this.loads.get(key);
680
736
  let start;
@@ -692,7 +748,10 @@ var TtlCache = class {
692
748
  }
693
749
  };
694
750
  }).then((value) => {
695
- if (this.loads.get(key) === created && !controller.signal.aborted && (opts.shouldStore?.(value) ?? true)) this.set(key, value, epoch);
751
+ if (this.loads.get(key) === created && !controller.signal.aborted) {
752
+ const retain = opts.shouldStore?.(value) ?? true;
753
+ if (retain && this.loads.get(key) === created && !controller.signal.aborted) created.entry = this.storeValue(key, value, epoch);
754
+ }
696
755
  return value;
697
756
  });
698
757
  const settled = () => {
@@ -726,7 +785,11 @@ var TtlCache = class {
726
785
  (value) => {
727
786
  if (leave()) {
728
787
  try {
729
- resolve(structuredClone(value));
788
+ if (signal?.aborted) throw opts.abortError();
789
+ const entry = shared.entry;
790
+ const selected = projector === void 0 ? structuredClone(value) : entry !== void 0 && this.liveEntry(key) === entry ? this.projectEntry(key, entry, projector) : projectMetadata(structuredClone(value), projector);
791
+ if (signal?.aborted) throw opts.abortError();
792
+ resolve(selected);
730
793
  } catch (error) {
731
794
  reject(error);
732
795
  }
@@ -743,14 +806,19 @@ var TtlCache = class {
743
806
  /** Store `value` under `key`. `epoch` is the value the caller read BEFORE its
744
807
  * wire request: a read that straddled a `clear()` (a write) is dropped. */
745
808
  set(key, value, epoch = this.epochCounter) {
746
- if (epoch !== this.epochCounter) return;
809
+ this.storeValue(key, value, epoch);
810
+ }
811
+ storeValue(key, value, epoch) {
812
+ if (epoch !== this.epochCounter) return void 0;
747
813
  if (!this.store.has(key) && this.store.size >= this.maxEntries && this.purgeExpired() === 0) {
748
814
  const oldest = this.store.keys().next();
749
815
  if (!oldest.done) this.store.delete(oldest.value);
750
816
  }
751
817
  const now = Date.now();
752
818
  this.store.delete(key);
753
- this.store.set(key, { value: structuredClone(value), storedAt: now, expiresAt: now + this.ttlFor(key) });
819
+ const entry = { value: structuredClone(value), storedAt: now, expiresAt: now + this.ttlFor(key) };
820
+ this.store.set(key, entry);
821
+ return entry;
754
822
  }
755
823
  /** `{ hit, age }` without consuming or cloning the entry (age in ms since stored). */
756
824
  peek(key) {
@@ -1734,6 +1802,12 @@ function isAbortLike(err) {
1734
1802
  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
1735
1803
  }
1736
1804
 
1805
+ // src/read-scope.ts
1806
+ var CAPTURE_READ_GUARD = /* @__PURE__ */ Symbol.for("node-autotask.capture-read-guard.v1");
1807
+ function captureReadGuard(http, operation) {
1808
+ return http[CAPTURE_READ_GUARD](operation);
1809
+ }
1810
+
1737
1811
  // src/auth.ts
1738
1812
  var AUTH_HEADERS = {
1739
1813
  integrationCode: "ApiIntegrationCode",
@@ -14793,6 +14867,13 @@ async function discoverZoneBase(userName, maxResponseBytes, signal, ctx) {
14793
14867
  var META_TRIO_VERBS = /* @__PURE__ */ new Set(["getEntityInfo", "getFieldInfo", "getUdfInfo"]);
14794
14868
  var RETRY = { done: false };
14795
14869
  var HttpClient = class {
14870
+ /** Retain this build's caller scope without sharing ambient storage. @internal */
14871
+ [CAPTURE_READ_GUARD](operation) {
14872
+ const signal = ambientCallerSignal();
14873
+ return () => {
14874
+ if (signal?.aborted) throw new AutotaskAbortError("Read aborted by the caller", { operation });
14875
+ };
14876
+ }
14796
14877
  /**
14797
14878
  * The LIVE base URL (issue #43): the construction-time value until a zone
14798
14879
  * re-point happens, then the tenant's newly resolved zone base. Reads are
@@ -15844,6 +15925,133 @@ var WORKFLOW_RESOURCES = [
15844
15925
  "projects"
15845
15926
  ];
15846
15927
 
15928
+ // src/metadata-views.ts
15929
+ function liveFieldNamesView(rows) {
15930
+ if (!Array.isArray(rows)) return null;
15931
+ const names = [];
15932
+ for (const row of rows) if (typeof row.name === "string") names.push(row.name);
15933
+ return names.length === 0 ? null : { names, known: new Set(names) };
15934
+ }
15935
+ function projectFieldRow(raw, labels = false, udf = false) {
15936
+ const r = typeof raw === "object" && raw !== null ? raw : {};
15937
+ const name = typeof r.name === "string" ? r.name : "";
15938
+ const type = typeof r.dataType === "string" ? r.dataType : typeof r.type === "string" ? r.type : "";
15939
+ const values = labels && r.isPickList === true && Array.isArray(r.picklistValues) && r.picklistValues.length > 0 ? r.picklistValues : void 0;
15940
+ const referenceEntityType = typeof r.referenceEntityType === "string" ? r.referenceEntityType : "";
15941
+ return {
15942
+ name,
15943
+ ...typeof r.label === "string" && r.label !== "" ? { label: r.label } : {},
15944
+ type,
15945
+ isRequired: r.isRequired === true,
15946
+ isReadOnly: r.isReadOnly === true,
15947
+ // Issue #219 N7: a UDF row never serves the vendor's isQueryable (it is
15948
+ // true for UDFs while a plain filter on a UDF name is refused); it serves
15949
+ // the marker the filter actually needs.
15950
+ ...udf ? { filterable: "udf-marker" } : { isQueryable: r.isQueryable === true },
15951
+ isPickList: r.isPickList === true,
15952
+ ...isObjectOrArrayType(type) ? { writeShape: "replace-all" } : {},
15953
+ maxLength: typeof r.length === "number" ? r.length : null,
15954
+ referenceEntityType,
15955
+ ...values !== void 0 ? { picklistValues: values } : {}
15956
+ };
15957
+ }
15958
+ function isObjectOrArrayType(type) {
15959
+ const t = type.trim().toLowerCase();
15960
+ return t === "object" || t === "array" || t === "collection" || t.endsWith("[]");
15961
+ }
15962
+ function exposesPicklistValues(raw) {
15963
+ const r = typeof raw === "object" && raw !== null ? raw : {};
15964
+ return Array.isArray(r.picklistValues) && r.picklistValues.length > 0;
15965
+ }
15966
+ function catalogList(raw, labels, udf) {
15967
+ return Array.isArray(raw) ? { rows: raw.map((row) => projectFieldRow(row, labels, udf)), exposesValues: raw.some(exposesPicklistValues) } : { rows: null, exposesValues: false };
15968
+ }
15969
+ var catalogFieldsView = (raw) => catalogList(raw, false, false);
15970
+ var catalogLabelledFieldsView = (raw) => catalogList(raw, true, false);
15971
+ var catalogUdfView = (raw) => catalogList(raw, false, true);
15972
+ var catalogLabelledUdfView = (raw) => catalogList(raw, true, true);
15973
+ function compactCatalogList(raw, keepValues, udf) {
15974
+ const view = catalogList(raw, keepValues, udf);
15975
+ if (view.rows === null) return { rows: null, exposesValues: view.exposesValues };
15976
+ const flags = {
15977
+ required: view.rows.filter((row) => row.isRequired).map((row) => row.name),
15978
+ readOnly: view.rows.filter((row) => row.isReadOnly).map((row) => row.name),
15979
+ queryable: view.rows.filter((row) => row.isQueryable).map((row) => row.name),
15980
+ picklistFields: view.rows.filter((row) => row.isPickList).map((row) => row.name)
15981
+ };
15982
+ return {
15983
+ rows: view.rows.map((row) => ({
15984
+ name: row.name,
15985
+ type: row.type,
15986
+ isPickList: row.isPickList,
15987
+ isReference: row.referenceEntityType !== "",
15988
+ udf,
15989
+ ...keepValues && row.picklistValues !== void 0 ? { picklistValues: row.picklistValues } : {}
15990
+ })),
15991
+ flags,
15992
+ exposesValues: view.exposesValues
15993
+ };
15994
+ }
15995
+ var compactCatalogFieldsView = (raw) => compactCatalogList(raw, false, false);
15996
+ var compactCatalogLabelledFieldsView = (raw) => compactCatalogList(raw, true, false);
15997
+ var compactCatalogUdfView = (raw) => compactCatalogList(raw, false, true);
15998
+ var compactCatalogLabelledUdfView = (raw) => compactCatalogList(raw, true, true);
15999
+ function ticketStatusView(fields) {
16000
+ if (!Array.isArray(fields)) return [];
16001
+ const status = fields.find((f) => typeof f?.name === "string" && f.name.toLowerCase() === "status");
16002
+ if (status === void 0 || status.isPickList !== true || !Array.isArray(status.picklistValues)) return [];
16003
+ const out = [];
16004
+ for (const v of status.picklistValues) {
16005
+ const id = Number(v?.value);
16006
+ if (!Number.isSafeInteger(id)) continue;
16007
+ out.push({ id, label: typeof v.label === "string" ? v.label : "" });
16008
+ }
16009
+ return out;
16010
+ }
16011
+ function primitiveData(descriptor2) {
16012
+ return descriptor2 !== void 0 && "value" in descriptor2 && (descriptor2.value === null || typeof descriptor2.value !== "object" && typeof descriptor2.value !== "function");
16013
+ }
16014
+ function picklistsView(raw) {
16015
+ if (!Array.isArray(raw)) return null;
16016
+ const fields = /* @__PURE__ */ new Map();
16017
+ for (const rawField of raw) {
16018
+ const field = projectFieldRow(rawField, true);
16019
+ if (fields.has(field.name)) continue;
16020
+ const values = field.picklistValues;
16021
+ if (values === void 0) {
16022
+ fields.set(field.name, void 0);
16023
+ continue;
16024
+ }
16025
+ const labels = /* @__PURE__ */ new Map();
16026
+ if (values.some((entry) => {
16027
+ if (entry === null || typeof entry !== "object" || Object.getPrototypeOf(entry) !== Object.prototype) return true;
16028
+ return !primitiveData(Object.getOwnPropertyDescriptor(entry, "value")) || !primitiveData(Object.getOwnPropertyDescriptor(entry, "label"));
16029
+ })) {
16030
+ fields.set(field.name, { labels, ordered: values });
16031
+ continue;
16032
+ }
16033
+ for (const value of values) {
16034
+ const key = String(value.value);
16035
+ if (!labels.has(key)) labels.set(key, typeof value.label === "string" ? value.label : null);
16036
+ }
16037
+ fields.set(field.name, { labels });
16038
+ }
16039
+ return fields;
16040
+ }
16041
+ function lookupPicklist(view, value) {
16042
+ if (view.ordered !== void 0) {
16043
+ const hit = view.ordered.find((entry) => String(entry.value) === String(value));
16044
+ return { found: hit !== void 0, label: typeof hit?.label === "string" ? hit.label : null };
16045
+ }
16046
+ const key = String(value);
16047
+ return { found: view.labels.has(key), label: view.labels.get(key) ?? null };
16048
+ }
16049
+ function ticketStatusFieldsView(fields) {
16050
+ if (!Array.isArray(fields)) return [];
16051
+ const status = fields.find((field) => typeof field?.name === "string" && field.name.toLowerCase() === "status");
16052
+ return status === void 0 ? [] : [status];
16053
+ }
16054
+
15847
16055
  // src/utils/bounded.ts
15848
16056
  async function runBounded(fn, items, opts) {
15849
16057
  const { concurrency, signal, settle } = opts;
@@ -15899,48 +16107,7 @@ var MAX_FIELD_CATALOG_WIRE = 60;
15899
16107
  var FIELD_CATALOG_HONESTY_NOTE = "Live field metadata reports the SHAPE of a field (existence, requiredness, type, maxLength, read-only, queryable, picklist-ness) as FLAGS and NAMES: picklist-ness as a flag (isPickList) and picklist field names (picklistFields). With the opt-in `labels: true`, picklist rows carry the vendor's exposed picklist VALUES (labels next to each value); without it the op serves no VALUES. It cannot resolve a picklist VALUE the vendor does not expose to this API user (a vendor-withheld picklist value): retrying the catalog will not surface a withheld value; that gap is vendor-side, not a client defect.";
15900
16108
  var MIN_FIELD_CATALOG_MAX_BYTES = 4096;
15901
16109
  var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels", "compact", "maxBytes"];
15902
- function projectFieldRow(raw, labels = false, udf = false) {
15903
- const r = typeof raw === "object" && raw !== null ? raw : {};
15904
- const name = typeof r.name === "string" ? r.name : "";
15905
- const type = typeof r.dataType === "string" ? r.dataType : typeof r.type === "string" ? r.type : "";
15906
- const values = labels && r.isPickList === true && Array.isArray(r.picklistValues) && r.picklistValues.length > 0 ? r.picklistValues : void 0;
15907
- const referenceEntityType = typeof r.referenceEntityType === "string" ? r.referenceEntityType : "";
15908
- return {
15909
- name,
15910
- ...typeof r.label === "string" && r.label !== "" ? { label: r.label } : {},
15911
- type,
15912
- isRequired: r.isRequired === true,
15913
- isReadOnly: r.isReadOnly === true,
15914
- // Issue #219 N7: a UDF row never serves the vendor's isQueryable (it is
15915
- // true for UDFs while a plain filter on a UDF name is refused); it serves
15916
- // the marker the filter actually needs.
15917
- ...udf ? { filterable: "udf-marker" } : { isQueryable: r.isQueryable === true },
15918
- isPickList: r.isPickList === true,
15919
- ...isObjectOrArrayType(type) ? { writeShape: "replace-all" } : {},
15920
- maxLength: typeof r.length === "number" ? r.length : null,
15921
- referenceEntityType,
15922
- ...values !== void 0 ? { picklistValues: values } : {}
15923
- };
15924
- }
15925
- function compactFieldRow(f, udf, keepValues) {
15926
- return {
15927
- name: f.name,
15928
- type: f.type,
15929
- isPickList: f.isPickList,
15930
- isReference: f.referenceEntityType !== "",
15931
- udf,
15932
- ...keepValues && f.picklistValues !== void 0 ? { picklistValues: f.picklistValues } : {}
15933
- };
15934
- }
15935
- function isObjectOrArrayType(type) {
15936
- const t = type.trim().toLowerCase();
15937
- return t === "object" || t === "array" || t === "collection" || t.endsWith("[]");
15938
- }
15939
- function exposesPicklistValues(raw) {
15940
- const r = typeof raw === "object" && raw !== null ? raw : {};
15941
- return Array.isArray(r.picklistValues) && r.picklistValues.length > 0;
15942
- }
15943
- function applyFieldsFilter(projected, filter, row) {
16110
+ function applyFieldsFilter(projected, filter, row, flags) {
15944
16111
  const kept = filter === void 0 ? projected : projected.filter((f) => filter.includes(f.name));
15945
16112
  if (filter !== void 0) {
15946
16113
  const present = new Set(projected.map((f) => f.name));
@@ -15948,10 +16115,19 @@ function applyFieldsFilter(projected, filter, row) {
15948
16115
  row.projected = true;
15949
16116
  }
15950
16117
  row.fields = kept;
15951
- row.required = kept.filter((f) => f.isRequired).map((f) => f.name);
15952
- row.readOnly = kept.filter((f) => f.isReadOnly).map((f) => f.name);
15953
- row.queryable = kept.filter((f) => f.isQueryable).map((f) => f.name);
15954
- row.picklistFields = kept.filter((f) => f.isPickList).map((f) => f.name);
16118
+ if (flags !== void 0) {
16119
+ const present = new Set(kept.map((field) => field.name));
16120
+ row.required = flags.required.filter((name) => present.has(name));
16121
+ row.readOnly = flags.readOnly.filter((name) => present.has(name));
16122
+ row.queryable = flags.queryable.filter((name) => present.has(name));
16123
+ row.picklistFields = flags.picklistFields.filter((name) => present.has(name));
16124
+ } else {
16125
+ const full = kept;
16126
+ row.required = full.filter((field) => field.isRequired).map((field) => field.name);
16127
+ row.readOnly = full.filter((field) => field.isReadOnly).map((field) => field.name);
16128
+ row.queryable = full.filter((field) => field.isQueryable).map((field) => field.name);
16129
+ row.picklistFields = full.filter((field) => field.isPickList).map((field) => field.name);
16130
+ }
15955
16131
  }
15956
16132
  async function capabilitySets() {
15957
16133
  const fieldOps = /* @__PURE__ */ new Map();
@@ -16166,14 +16342,25 @@ function kindFetches(holder, resource) {
16166
16342
  udf: () => holder?.getUdfInfo?.() ?? Promise.reject(new AutotaskError(`fieldCatalog: the client exposes no getUdfInfo read for "${resource}"`, { code: "INVALID_RESPONSE", category: "server" }))
16167
16343
  };
16168
16344
  }
16169
- async function readKind(ctx, resource, kind, fetch2) {
16345
+ function catalogProjector(kind, ctx) {
16346
+ if (ctx.compact) {
16347
+ const keepValues = ctx.labels && ctx.fieldsFilter !== void 0;
16348
+ if (kind === "fields") return keepValues ? compactCatalogLabelledFieldsView : compactCatalogFieldsView;
16349
+ if (kind === "udf") return keepValues ? compactCatalogLabelledUdfView : compactCatalogUdfView;
16350
+ }
16351
+ if (kind === "fields") return ctx.labels ? catalogLabelledFieldsView : catalogFieldsView;
16352
+ if (kind === "udf") return ctx.labels ? catalogLabelledUdfView : catalogUdfView;
16353
+ return void 0;
16354
+ }
16355
+ async function readKind(ctx, resource, kind, fetch2, holder, projector = catalogProjector(kind, ctx)) {
16170
16356
  const cache = ctx.client.http.fieldCache;
16171
16357
  const peek = cache !== void 0 && !ctx.fresh ? cache.peek(fieldKey(resource, kind)) : { hit: false, age: null };
16172
16358
  if (peek.hit && cache !== void 0) {
16173
- return { kind, peek, outcome: { status: "fulfilled", value: cache.get(fieldKey(resource, kind)) } };
16359
+ const value = projector !== void 0 && typeof cache.getProjected === "function" ? cache.getProjected(fieldKey(resource, kind), projector) ?? projector(void 0) : projector === void 0 ? cache.get(fieldKey(resource, kind)) : projector(cache.get(fieldKey(resource, kind)));
16360
+ return { kind, peek, outcome: { status: "fulfilled", value } };
16174
16361
  }
16175
16362
  try {
16176
- const value = await fetch2();
16363
+ const value = projector === void 0 ? await fetch2() : await readMetadataProjection(holder, kind, projector, fetch2);
16177
16364
  return { kind, peek, outcome: { status: "fulfilled", value } };
16178
16365
  } catch (error) {
16179
16366
  if (!isAutotaskError(error) || error.code === "ABORTED") throw error;
@@ -16181,7 +16368,7 @@ async function readKind(ctx, resource, kind, fetch2) {
16181
16368
  }
16182
16369
  }
16183
16370
  async function sweepResource(ctx, resource, tally, reads) {
16184
- const { fieldsFilter, labels } = ctx;
16371
+ const { fieldsFilter } = ctx;
16185
16372
  const fieldOp = ctx.fieldOps.get(resource);
16186
16373
  if (fieldOp === void 0) return void 0;
16187
16374
  const apiEntity = apiEntityFor(fieldOp);
@@ -16200,12 +16387,6 @@ async function sweepResource(ctx, resource, tally, reads) {
16200
16387
  wire: 0,
16201
16388
  error: null
16202
16389
  };
16203
- const projectList = (kind, list) => {
16204
- const projected = list.map((f) => projectFieldRow(f, labels, kind === "udf"));
16205
- if (kind === "fields") applyFieldsFilter(projected, fieldsFilter, row);
16206
- else row.udf = projected;
16207
- for (const f of list) if (exposesPicklistValues(f)) tally.anyPicklistValues = true;
16208
- };
16209
16390
  let allCached = true;
16210
16391
  const ages = [];
16211
16392
  for (const { kind, peek, outcome } of reads) {
@@ -16223,19 +16404,17 @@ async function sweepResource(ctx, resource, tally, reads) {
16223
16404
  if (kind === "info") {
16224
16405
  row.info = value ?? null;
16225
16406
  } else {
16226
- if (!Array.isArray(value)) {
16407
+ const view = value;
16408
+ if (view.rows === null) {
16227
16409
  if (row.error === null) row.error = { code: "INVALID_RESPONSE", message: `fieldCatalog: the ${kind} response for ${resource} was not a list` };
16228
16410
  continue;
16229
16411
  }
16230
- projectList(kind, value);
16412
+ if (kind === "fields") applyFieldsFilter(view.rows, fieldsFilter, row, view.flags);
16413
+ else row.udf = view.rows;
16414
+ if (view.exposesValues) tally.anyPicklistValues = true;
16231
16415
  }
16232
16416
  }
16233
16417
  row.cache = allCached ? { hit: true, age: ages.length > 0 ? Math.max(...ages) : 0 } : { hit: false, age: null };
16234
- if (ctx.compact) {
16235
- const keepValues = labels && fieldsFilter !== void 0;
16236
- if (row.fields !== void 0) row.fields = row.fields.map((f) => compactFieldRow(f, false, keepValues));
16237
- if (Array.isArray(row.udf)) row.udf = row.udf.map((f) => compactFieldRow(f, true, keepValues));
16238
- }
16239
16418
  const declared = await derivedFieldsFor(resource);
16240
16419
  if (declared.length > 0) {
16241
16420
  const byField = new Map(declared.map((d) => [d.field, d]));
@@ -16251,7 +16430,7 @@ async function sweepResource(ctx, resource, tally, reads) {
16251
16430
  }
16252
16431
  return row;
16253
16432
  }
16254
- async function fieldCatalog(client, opts) {
16433
+ async function prepareCatalog(client, opts) {
16255
16434
  validateCatalogOptsShape(opts);
16256
16435
  const { fieldOps, udfCapable, resources: allResources } = await capabilitySets();
16257
16436
  const include = resolveInclude(opts);
@@ -16260,11 +16439,22 @@ async function fieldCatalog(client, opts) {
16260
16439
  const labels = resolveLabels(opts);
16261
16440
  const { compact, maxBytes } = resolveSizeOpts(opts);
16262
16441
  assertWithinWireCap(targets.length, include.length);
16442
+ const ctx = { client, include, fieldsFilter, labels, compact, fresh: opts?.fresh === true, fieldOps, udfCapable };
16443
+ return { ctx, targets, compact, maxBytes };
16444
+ }
16445
+ async function fieldCatalogPicklists(client, resource, fields) {
16446
+ const { ctx } = await prepareCatalog(client, { resources: [resource], labels: true, fields: [...fields] });
16447
+ const holder = client[camelKey(resource)];
16448
+ const [read] = await mapReadTasks(client.http, [resource], () => readKind(ctx, resource, "fields", kindFetches(holder, resource).fields, holder, picklistsView));
16449
+ return read.outcome.status === "fulfilled" ? read.outcome.value : null;
16450
+ }
16451
+ async function fieldCatalog(client, opts) {
16452
+ const { ctx, targets, compact, maxBytes } = await prepareCatalog(client, opts);
16453
+ const { include, labels, fieldOps, udfCapable } = ctx;
16263
16454
  const cache = client.http.fieldCache;
16264
16455
  const zone = client.config.zone ?? "unknown";
16265
16456
  const rows = [];
16266
16457
  const tally = { wireUsed: 0, anyPicklistValues: false };
16267
- const ctx = { client, fieldsFilter, labels, compact, fresh: opts?.fresh === true, fieldOps, udfCapable };
16268
16458
  for (const resource of targets) {
16269
16459
  apiEntityFor(fieldOps.get(resource));
16270
16460
  if (ctx.fresh) cache?.invalidate(`${resource}:`);
@@ -16272,9 +16462,9 @@ async function fieldCatalog(client, opts) {
16272
16462
  const tasks = targets.flatMap((resource) => {
16273
16463
  const holder = client[camelKey(resource)];
16274
16464
  const fetches = kindFetches(holder, resource);
16275
- return include.map((kind) => ({ resource, kind, fetch: fetches[kind] }));
16465
+ return include.map((kind) => ({ resource, kind, fetch: fetches[kind], holder }));
16276
16466
  });
16277
- const reads = await mapReadTasks(client.http, tasks, ({ resource, kind, fetch: fetch2 }) => readKind(ctx, resource, kind, fetch2));
16467
+ const reads = await mapReadTasks(client.http, tasks, ({ resource, kind, fetch: fetch2, holder }) => readKind(ctx, resource, kind, fetch2, holder));
16278
16468
  for (let index = 0; index < targets.length; index += 1) {
16279
16469
  const start = index * include.length;
16280
16470
  const row = await sweepResource(ctx, targets[index], tally, reads.slice(start, start + include.length));
@@ -16876,19 +17066,12 @@ async function resolveCompositeNames(http, plan, opts = {}) {
16876
17066
  };
16877
17067
  });
16878
17068
  }
16879
- const picklists = {};
17069
+ let picklists = null;
16880
17070
  if (plan.labelFields.length > 0) {
16881
17071
  tasks.push(async () => {
16882
17072
  try {
16883
17073
  const labelResource = plan.labelResource ?? "tickets";
16884
- const catalog = await fieldCatalog(client, { resources: [labelResource], labels: true, fields: [...plan.labelFields] });
16885
- const row = catalog.rows.find((r) => r.resource === labelResource);
16886
- if (row !== void 0 && row.error === null && row.fields !== void 0) {
16887
- for (const f of plan.labelFields) {
16888
- const frow = row.fields.find((x) => x.name === f);
16889
- picklists[f] = frow?.picklistValues;
16890
- }
16891
- }
17074
+ picklists = await fieldCatalogPicklists(client, labelResource, plan.labelFields);
16892
17075
  } catch (err) {
16893
17076
  if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
16894
17077
  }
@@ -16924,17 +17107,17 @@ async function resolveCompositeNames(http, plan, opts = {}) {
16924
17107
  recordName: (table, id) => section.rows[`${table}:${id}`]?.name ?? null,
16925
17108
  labelFor: (field, value) => {
16926
17109
  if (value === null || value === void 0) return null;
16927
- const values = picklists[field];
17110
+ const values = picklists?.get(field);
16928
17111
  if (values === void 0) {
16929
17112
  section.reasons[field] = FIELD_CATALOG_HONESTY_NOTE;
16930
17113
  return null;
16931
17114
  }
16932
- const hit = values.find((v) => String(v.value) === String(value));
16933
- if (hit === void 0) {
17115
+ const hit = lookupPicklist(values, value);
17116
+ if (!hit.found) {
16934
17117
  if (String(value) !== "0") section.reasons[field] = PICKLIST_VALUE_NOT_SERVED_NOTE;
16935
17118
  return null;
16936
17119
  }
16937
- return typeof hit.label === "string" ? hit.label : null;
17120
+ return hit.label;
16938
17121
  }
16939
17122
  };
16940
17123
  }
@@ -16996,8 +17179,7 @@ function subscriberError(error, operation) {
16996
17179
  };
16997
17180
  return copyValue(error);
16998
17181
  }
16999
- function cachedRead(http, cache, key, path, operation, request, fresh, shouldStore) {
17000
- if (cache === void 0) return request();
17182
+ function cachedRead(http, cache, key, path, operation, request, fresh, shouldStore, projector) {
17001
17183
  let ownsLoader = false;
17002
17184
  const loader = (signal) => {
17003
17185
  ownsLoader = true;
@@ -17012,11 +17194,21 @@ function cachedRead(http, cache, key, path, operation, request, fresh, shouldSto
17012
17194
  suggestedAction: "The caller aborted; re-issue the call if still needed."
17013
17195
  })
17014
17196
  };
17015
- return cache.load(key, loader, options).catch((error) => {
17197
+ const select = (value) => {
17198
+ if (options.signal?.aborted) throw options.abortError();
17199
+ const selected = projector === void 0 ? value : projectMetadata(value, projector);
17200
+ if (options.signal?.aborted) throw options.abortError();
17201
+ return selected;
17202
+ };
17203
+ if (cache === void 0) return request().then(select);
17204
+ const load = (fresh2) => projector !== void 0 && typeof cache.loadProjected === "function" ? cache.loadProjected(key, loader, projector, { ...options, fresh: fresh2 }) : cache.load(key, loader, { ...options, fresh: fresh2 }).then(select);
17205
+ return load(fresh).catch((error) => {
17016
17206
  if (ownsLoader || !(error instanceof AutotaskError) || error.details?.budgetScope !== "client" || error.notSent !== true) throw error;
17017
17207
  if (options.signal?.aborted) throw options.abortError();
17018
- const warm = cache.get(key);
17019
- return warm !== void 0 ? warm : cache.load(key, loader, { ...options, fresh: true });
17208
+ const projected = projector !== void 0 && typeof cache.getProjected === "function";
17209
+ const warm = projected ? cache.getProjected(key, projector) : cache.get(key);
17210
+ if (options.signal?.aborted) throw options.abortError();
17211
+ return warm !== void 0 ? projected ? warm : select(warm) : load(true);
17020
17212
  }).catch((error) => {
17021
17213
  if (!(error instanceof AutotaskError)) throw error;
17022
17214
  const failure = subscriberError(error, operation);
@@ -17035,7 +17227,7 @@ function cachedRecordGet(http, path, operation, fresh = false) {
17035
17227
  fresh
17036
17228
  );
17037
17229
  }
17038
- function cachedMetadataGet(http, resource, kind, path, operation, unwrap, fresh = false, maxRetries) {
17230
+ function cachedMetadataGet(http, resource, kind, path, operation, unwrap, fresh = false, maxRetries, projector) {
17039
17231
  const cache = http.fieldCache;
17040
17232
  const request = (signal) => {
17041
17233
  return http.request({ method: "GET", path, operation, signal, maxRetries }).then(unwrap).catch((error) => {
@@ -17049,7 +17241,7 @@ function cachedMetadataGet(http, resource, kind, path, operation, unwrap, fresh
17049
17241
  if (value === null || value === void 0) return false;
17050
17242
  if (Array.isArray(value)) return value.length > 0;
17051
17243
  return typeof value !== "object" || Object.keys(value).length > 0;
17052
- });
17244
+ }, projector);
17053
17245
  }
17054
17246
 
17055
17247
  // src/field-sets.ts
@@ -17547,6 +17739,12 @@ function validateWalkBag(walk, prefix, details) {
17547
17739
  return wr;
17548
17740
  }
17549
17741
 
17742
+ // src/operations/query-pages.ts
17743
+ var PREPARE_BOUNDED_QUERY = /* @__PURE__ */ Symbol.for("node-autotask.prepare-bounded-query.v1");
17744
+ function assertPageReadActive(operation) {
17745
+ if (ambientCallerSignal()?.aborted) throw new AutotaskAbortError("Bounded query page consumption aborted by the caller", { operation });
17746
+ }
17747
+
17550
17748
  // src/resources/base/query.ts
17551
17749
  var QueryBase = class {
17552
17750
  httpClient;
@@ -17721,6 +17919,22 @@ var QueryBase = class {
17721
17919
  * Pure read; no mutation paths involved.
17722
17920
  */
17723
17921
  async queryBounded(params) {
17922
+ return this.boundedQueryResult(params);
17923
+ }
17924
+ /** Internal governed consumer hook; all validation and paging stay shared. @internal */
17925
+ [PREPARE_BOUNDED_QUERY]() {
17926
+ const guard = captureReadGuard(this.http, `${this.config.key}.query`);
17927
+ return {
17928
+ guard,
17929
+ consume: async (params, consume) => {
17930
+ guard();
17931
+ const { items, ...summary } = await this.boundedQueryResult(params, consume);
17932
+ guard();
17933
+ return summary;
17934
+ }
17935
+ };
17936
+ }
17937
+ async boundedQueryResult(params, consume) {
17724
17938
  if (Array.isArray(params)) {
17725
17939
  throw new AutotaskConfigError(
17726
17940
  "queryBounded: params must be an object { filter?, limit?, latest?, includeFields? } \u2014 a bare conditions array is not accepted (wrap it: { filter: [...] })"
@@ -17767,13 +17981,28 @@ var QueryBase = class {
17767
17981
  if (latest !== void 0) {
17768
17982
  return this.applyNoteChars(await this.latestWalk(walkParams, Math.max(limit, latest), latest), noteChars);
17769
17983
  }
17770
- const { items, pages: pages2, guard, sliced, cursor, names } = await this.walkBounded(walkParams, cap, limit, labelPages);
17771
- const hasMore = maxRows === void 0 ? (items.length >= cap || guard) && (sliced > 0 || cursor !== null) : guard || sliced > 0 || cursor !== null;
17772
- const result = { items, fetched: items.length, hasMore, pagesWalked: pages2 };
17984
+ let truncatedFields = 0;
17985
+ const sink = consume === void 0 ? void 0 : async (rows, page) => {
17986
+ const projected = this.applyNoteChars({ items: rows, fetched: rows.length, hasMore: false, pagesWalked: 1 }, noteChars);
17987
+ truncatedFields += projected.noteCharsTruncated ?? 0;
17988
+ assertPageReadActive(`${this.config.key}.query`);
17989
+ try {
17990
+ await consume({ items: projected.items, page });
17991
+ } catch (error) {
17992
+ assertPageReadActive(`${this.config.key}.query`);
17993
+ throw error;
17994
+ }
17995
+ assertPageReadActive(`${this.config.key}.query`);
17996
+ };
17997
+ const { items, fetched, pages: pages2, guard, sliced, cursor, names } = await this.walkBounded(walkParams, cap, limit, labelPages, sink);
17998
+ const hasMore = maxRows === void 0 ? (fetched >= cap || guard) && (sliced > 0 || cursor !== null) : guard || sliced > 0 || cursor !== null;
17999
+ const result = { items, fetched, hasMore, pagesWalked: pages2 };
17773
18000
  if (maxRows !== void 0) result.truncated = hasMore;
17774
18001
  if (names !== void 0) result.names = names;
17775
18002
  this.stampEmptyQueryResult(result, params);
17776
- return this.applyNoteChars(result, noteChars);
18003
+ if (consume === void 0) return this.applyNoteChars(result, noteChars);
18004
+ if (truncatedFields > 0) result.noteCharsTruncated = truncatedFields;
18005
+ return result;
17777
18006
  }
17778
18007
  /** Issue #61 (slice A): the noteChars truncation at the SINGLE chokepoint
17779
18008
  * of `queryBounded` — the normal walk and the `latest` paths both
@@ -17802,9 +18031,10 @@ var QueryBase = class {
17802
18031
  * SOFT stop (never a throw). ONE per-walk closure (walks never share
17803
18032
  * state).
17804
18033
  * @internal */
17805
- async walkBounded(p, limit, pageSizeBase, labelPages = false) {
18034
+ async walkBounded(p, limit, pageSizeBase, labelPages = false, consume) {
17806
18035
  const state2 = { cursor: null };
17807
18036
  const items = [];
18037
+ let fetched = 0;
17808
18038
  let pages2 = 0;
17809
18039
  let sliced = 0;
17810
18040
  let guard = false;
@@ -17816,6 +18046,7 @@ var QueryBase = class {
17816
18046
  guard = true;
17817
18047
  break;
17818
18048
  }
18049
+ if (consume !== void 0) assertPageReadActive(`${this.config.key}.query`);
17819
18050
  const page = await this.fetchPage(p, pages2 + 1, pageSize, state2);
17820
18051
  pages2 += 1;
17821
18052
  if (labelPages && this.http.client !== void 0) {
@@ -17826,18 +18057,20 @@ var QueryBase = class {
17826
18057
  Object.assign(nameReasons, labelled.names.reasons);
17827
18058
  }
17828
18059
  }
17829
- const remaining = limit - items.length;
18060
+ const remaining = limit - fetched;
17830
18061
  const take = page.items.slice(0, remaining);
17831
18062
  sliced += Math.max(0, page.items.length - remaining);
17832
- items.push(...take);
17833
- if (items.length >= limit) break;
18063
+ fetched += take.length;
18064
+ if (consume === void 0) items.push(...take);
18065
+ else await consume(take, pages2);
18066
+ if (fetched >= limit) break;
17834
18067
  if (!page.hasMore || page.items.length === 0) break;
17835
18068
  }
17836
18069
  const names = nameNotes.size === 0 ? void 0 : {
17837
18070
  note: [...nameNotes].join("; "),
17838
18071
  ...Object.keys(nameReasons).length === 0 ? {} : { reasons: nameReasons }
17839
18072
  };
17840
- return { items, pages: pages2, guard, sliced, cursor: state2.cursor, ...names === void 0 ? {} : { names } };
18073
+ return { items, fetched, pages: pages2, guard, sliced, cursor: state2.cursor, ...names === void 0 ? {} : { names } };
17841
18074
  }
17842
18075
  /** A walk stop is TRUNCATED when the 1000-page guard fired, or the limit
17843
18076
  * was met with a live next cursor (or a sliced final page): rows exist
@@ -17861,7 +18094,7 @@ var QueryBase = class {
17861
18094
  * speculation).
17862
18095
  * @internal */
17863
18096
  stampEmptyQueryResult(result, params) {
17864
- if (result.items.length !== 0) return;
18097
+ if (result.fetched !== 0) return;
17865
18098
  result.blindSurface = blindStampFor(BLIND_SURFACE_STAMPS[this.config.key]?.query, params?.filter);
17866
18099
  const pinnedReason = normalizedConditions(params?.filter) === void 0 ? EMPTY_REASON_STAMPS[this.config.key]?.query : void 0;
17867
18100
  if (result.blindSurface !== void 0 || pinnedReason !== void 0) {
@@ -18097,7 +18330,7 @@ var QueryBase = class {
18097
18330
  };
18098
18331
 
18099
18332
  // src/resources/base/meta.ts
18100
- var MetaBase = class extends QueryBase {
18333
+ var MetaBase = class _MetaBase extends QueryBase {
18101
18334
  // ------------------------------------------------------------------
18102
18335
  // Single-record reads
18103
18336
  // ------------------------------------------------------------------
@@ -18244,21 +18477,7 @@ var MetaBase = class extends QueryBase {
18244
18477
  * entity's entries via the fieldCache's `invalidate` first — the trio
18245
18478
  * keeps its no-arg surface (the registry/MCP arity pin). */
18246
18479
  async getEntityInfo() {
18247
- return await this.cachedMeta(
18248
- "info",
18249
- `${this.resourcePath}/entityInformation`,
18250
- `${this.config.key}.getEntityInfo`,
18251
- (res) => {
18252
- const body = isRecord2(res) ? res : void 0;
18253
- if (body === void 0 || !isRecord2(body.info)) {
18254
- throw new AutotaskError("Expected the entityInformation envelope { info }; got a different shape", {
18255
- code: "INVALID_RESPONSE",
18256
- category: "server"
18257
- });
18258
- }
18259
- return body.info;
18260
- }
18261
- );
18480
+ return await this.metadataRead("info");
18262
18481
  }
18263
18482
  /** `GET /V1.0/<E>/entityInformation/fields` → `{ fields }` unwrapped.
18264
18483
  * Goes through the field cache when it is present (issue #80:
@@ -18268,12 +18487,7 @@ var MetaBase = class extends QueryBase {
18268
18487
  * entity's entries via the fieldCache's `invalidate` first — the trio
18269
18488
  * keeps its no-arg surface (the registry/MCP arity pin). */
18270
18489
  async getFieldInfo() {
18271
- return await this.cachedMeta(
18272
- "fields",
18273
- `${this.resourcePath}/entityInformation/fields`,
18274
- `${this.config.key}.getFieldInfo`,
18275
- (res) => this.unwrapFields(res, "FieldInformationResultModel")
18276
- );
18490
+ return await this.metadataRead("fields");
18277
18491
  }
18278
18492
  /** `GET /V1.0/<E>/entityInformation/userDefinedFields` → `{ fields }` unwrapped.
18279
18493
  * Goes through the field cache when it is present (issue #80:
@@ -18283,12 +18497,29 @@ var MetaBase = class extends QueryBase {
18283
18497
  * entity's entries via the fieldCache's `invalidate` first — the trio
18284
18498
  * keeps its no-arg surface (the registry/MCP arity pin). */
18285
18499
  async getUdfInfo() {
18286
- return await this.cachedMeta(
18287
- "udf",
18288
- `${this.resourcePath}/entityInformation/userDefinedFields`,
18289
- `${this.config.key}.getUdfInfo`,
18290
- (res) => this.unwrapFields(res, "UserDefinedFieldInformationResultModel")
18291
- );
18500
+ return await this.metadataRead("udf");
18501
+ }
18502
+ /** Capture the owning transport's context; overridden readers keep their original path. @internal */
18503
+ [METADATA_PROJECTION](kind, projector) {
18504
+ const reader = kind === "info" ? "getEntityInfo" : kind === "fields" ? "getFieldInfo" : "getUdfInfo";
18505
+ const guard = captureReadGuard(this.http, `${this.config.key}.${reader}`);
18506
+ guard();
18507
+ if (this[reader] !== _MetaBase.prototype[reader] || this.cachedMeta !== _MetaBase.prototype.cachedMeta) return { guard };
18508
+ return { guard, projected: this.metadataRead(kind, projector) };
18509
+ }
18510
+ metadataRead(kind, projector) {
18511
+ const suffix = kind === "info" ? "" : kind === "fields" ? "/fields" : "/userDefinedFields";
18512
+ const operation = kind === "info" ? "getEntityInfo" : kind === "fields" ? "getFieldInfo" : "getUdfInfo";
18513
+ const path = `${this.resourcePath}/entityInformation${suffix}`;
18514
+ const unwrap = (res) => {
18515
+ if (kind !== "info") return this.unwrapFields(res, kind === "fields" ? "FieldInformationResultModel" : "UserDefinedFieldInformationResultModel");
18516
+ const body = isRecord2(res) ? res : void 0;
18517
+ if (body === void 0 || !isRecord2(body.info)) {
18518
+ throw new AutotaskError("Expected the entityInformation envelope { info }; got a different shape", { code: "INVALID_RESPONSE", category: "server" });
18519
+ }
18520
+ return body.info;
18521
+ };
18522
+ return projector === void 0 ? this.cachedMeta(kind, path, `${this.config.key}.${operation}`, unwrap) : cachedMetadataGet(this.http, this.config.key, kind, path, `${this.config.key}.${operation}`, unwrap, false, void 0, projector);
18292
18523
  }
18293
18524
  /** @internal */
18294
18525
  unwrapFields(body, envelopeName) {
@@ -21105,13 +21336,7 @@ async function liveFieldNames(holder) {
21105
21336
  const reader = holder.getFieldInfo;
21106
21337
  if (typeof reader !== "function") return null;
21107
21338
  try {
21108
- const rows = await reader.call(holder);
21109
- if (!Array.isArray(rows)) return null;
21110
- const names = [];
21111
- for (const row of rows) {
21112
- if (typeof row.name === "string") names.push(row.name);
21113
- }
21114
- return names.length > 0 ? names : null;
21339
+ return await readMetadataProjection(holder, "fields", liveFieldNamesView, () => reader.call(holder));
21115
21340
  } catch (err) {
21116
21341
  if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
21117
21342
  return null;
@@ -21186,7 +21411,7 @@ function readIncludeNames(record, includeFields) {
21186
21411
  return names;
21187
21412
  }
21188
21413
  function resolveAuthority(record, live) {
21189
- if (live !== null) return { known: live, authority: "the tenant's live entity field metadata", hasField: (name) => live.includes(name) };
21414
+ if (live !== null) return { known: live.names, authority: "the tenant's live entity field metadata", hasField: (name) => live.known.has(name) };
21190
21415
  const vendored = MODEL_FIELD_SETS[record.resource];
21191
21416
  const modelHas = modelFieldLookup(record.resource);
21192
21417
  const liveOnlyExempt = Array.isArray(record.metadata?.liveOnlyFields) ? record.metadata.liveOnlyFields : [];
@@ -21251,18 +21476,6 @@ async function findUnknownFieldNames(record, holder, lists) {
21251
21476
  var ASSUMED_CLOSED_STATUS_ID = 5;
21252
21477
  var CLOSED_STATUS_LABELS = ["complete", "completed", "closed", "cancelled", "canceled", "resolved"];
21253
21478
  var OP = "tickets.statusSemantics";
21254
- function picklistOf(fields) {
21255
- if (!Array.isArray(fields)) return [];
21256
- const status = fields.find((f) => typeof f?.name === "string" && f.name.toLowerCase() === "status");
21257
- if (status === void 0 || status.isPickList !== true || !Array.isArray(status.picklistValues)) return [];
21258
- const out = [];
21259
- for (const v of status.picklistValues) {
21260
- const id = Number(v?.value);
21261
- if (!Number.isSafeInteger(id)) continue;
21262
- out.push({ id, label: typeof v.label === "string" ? v.label : "" });
21263
- }
21264
- return out;
21265
- }
21266
21479
  async function readFields(http, fresh) {
21267
21480
  return cachedMetadataGet(http, "tickets", "fields", "/V1.0/Tickets/entityInformation/fields", OP, (res) => {
21268
21481
  const fields = res?.fields;
@@ -21270,7 +21483,7 @@ async function readFields(http, fresh) {
21270
21483
  throw new AutotaskError("Expected the FieldInformationResultModel envelope { fields: [] }; got a different shape", { code: "INVALID_RESPONSE", category: "server" });
21271
21484
  }
21272
21485
  return fields;
21273
- }, fresh, 0);
21486
+ }, fresh, 0, ticketStatusFieldsView);
21274
21487
  }
21275
21488
  function assumed(allowAssumed, operation) {
21276
21489
  if (!allowAssumed) {
@@ -21307,7 +21520,7 @@ async function resolveTicketStatusSemantics(http, opts = {}, operation = OP) {
21307
21520
  if (e instanceof AutotaskError && e.code === "ABORTED") throw e;
21308
21521
  return assumed(allowAssumed, operation);
21309
21522
  }
21310
- const picklist = picklistOf(fields);
21523
+ const picklist = ticketStatusView(fields);
21311
21524
  const closedIds = picklist.filter((v) => CLOSED_STATUS_LABELS.includes(v.label.trim().toLowerCase())).map((v) => v.id);
21312
21525
  if (closedIds.length === 0) return assumed(allowAssumed, operation);
21313
21526
  const labels = picklist.filter((v) => closedIds.includes(v.id)).map((v) => `${v.id} ${v.label}`).join(", ");
@@ -27869,25 +28082,46 @@ async function requireReadBack(record, operation, opts) {
27869
28082
  }
27870
28083
  var PRE_REQUEST_VALIDATORS = [
27871
28084
  (c) => governPreRequest(c.record, c.operation, c.opts),
28085
+ (c) => {
28086
+ if (!c.streaming) return;
28087
+ if (!c.boundedQuery) throw new AutotaskConfigError("invokeReadPages: only primitive query reads support bounded page consumption", { operation: c.operation });
28088
+ const holder = c.holder;
28089
+ const prepare2 = holder[PREPARE_BOUNDED_QUERY];
28090
+ if (typeof prepare2 !== "function") {
28091
+ throw new AutotaskConfigError("invokeReadPages: the resource does not support governed bounded page consumption", { operation: c.operation });
28092
+ }
28093
+ const session = prepare2.call(holder);
28094
+ if (typeof session?.guard !== "function" || typeof session.consume !== "function") throw new AutotaskConfigError("invokeReadPages: the resource has no scoped page consumer", { operation: c.operation });
28095
+ c.pageSession = session;
28096
+ session.guard();
28097
+ },
27872
28098
  (c) => requireReadBack(c.record, c.operation, c.opts),
27873
28099
  (c) => validateDispatchArgs(c.record, c.args),
27874
28100
  (c) => validateParamsBag(c.record, c.args),
27875
28101
  (c) => validateFreshSpelling(c.record, c.args),
28102
+ (c) => {
28103
+ if (!c.streaming) return;
28104
+ const bag = c.args[0];
28105
+ if (bag?.["walk"] === void 0 || bag?.["latest"] !== void 0) {
28106
+ throw new AutotaskConfigError("invokeReadPages: an explicit walk.maxRows query without latest is required", { operation: c.operation });
28107
+ }
28108
+ },
27876
28109
  (c) => c.boundedQuery || c.countedQuery ? validateQueryFieldNames(c.record, c.holder, c.args) : Promise.resolve(void 0)
27877
28110
  ];
27878
28111
  async function runPreRequestPass(ctx) {
27879
28112
  for (const step of PRE_REQUEST_VALIDATORS) await step(ctx);
27880
28113
  }
27881
- async function invokeMode(client, operation, argsIn = [], opts = {}) {
28114
+ async function prepareInvocation(client, operation, argsIn, opts, streaming = false) {
27882
28115
  const record = await resolveRecord(operation);
27883
28116
  const args = resolveDispatchArgs(record, argsIn);
27884
28117
  const boundedQuery = record.kind === "primitive" && record.operation === "query";
27885
28118
  const countedQuery = record.kind === "primitive" && record.operation === "count";
27886
28119
  const holder = resolveHolder(client, record, operation);
27887
- await runPreRequestPass({ record, operation, args, opts, client, holder, boundedQuery, countedQuery });
28120
+ const context = { record, operation, args, opts, client, holder, boundedQuery, countedQuery, streaming };
28121
+ await runPreRequestPass(context);
27888
28122
  const labelQuery = boundedQuery && readNamesOpt(client, args[0]?.["names"], `invoke: "${record.id}" params bag`);
27889
28123
  const methodName = boundedQuery ? "queryBounded" : record.operation;
27890
- const method = holder[methodName];
28124
+ const method = streaming ? context.pageSession?.consume : holder[methodName];
27891
28125
  if (typeof method !== "function") {
27892
28126
  throw new AutotaskConfigError(
27893
28127
  `invoke: "${record.resource}.${methodName}" is not a callable method on the client`,
@@ -27903,6 +28137,10 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
27903
28137
  if (boundedQuery && args[0]?.["acknowledgeUnscoped"] !== true) {
27904
28138
  scopeNote = (await guardUnscopedQueryWalk(holder, record.id, args[0])).note;
27905
28139
  }
28140
+ return { record, args, holder, method, callArgs, labelQuery, scopeNote, pageSession: context.pageSession };
28141
+ }
28142
+ async function invokeMode(client, operation, argsIn = [], opts = {}) {
28143
+ const { record, args, holder, method, callArgs, labelQuery, scopeNote } = await prepareInvocation(client, operation, argsIn, opts);
27906
28144
  const result = await method.apply(holder, callArgs);
27907
28145
  if (labelQuery && args[0]?.["walk"] === void 0 && Array.isArray(result?.items)) {
27908
28146
  const bounded = result;
@@ -27918,6 +28156,15 @@ async function invoke(client, operation, args = [], opts = {}) {
27918
28156
  async function invokeRead(client, operation, args = [], opts = {}) {
27919
28157
  return invokeMode(client, operation, args, { ...opts, mode: "read" });
27920
28158
  }
28159
+ async function invokeReadPages(client, operation, args, onPage, opts = {}) {
28160
+ if (typeof onPage !== "function") throw new AutotaskConfigError("invokeReadPages: onPage must be a function", { operation });
28161
+ const prepared = await prepareInvocation(client, operation, args, { ...opts, mode: "read" }, true);
28162
+ prepared.pageSession.guard();
28163
+ const consume = prepared.method;
28164
+ const result = await consume.call(prepared.holder, prepared.callArgs[0], onPage);
28165
+ prepared.pageSession.guard();
28166
+ return prepared.scopeNote === void 0 ? result : { ...result, scopeNote: prepared.scopeNote };
28167
+ }
27921
28168
  async function invokeWrite(client, operation, args = [], opts = {}) {
27922
28169
  return invokeMode(client, operation, args, { ...opts, mode: "write" });
27923
28170
  }
@@ -28166,6 +28413,7 @@ exports.formatVendorDetail = formatVendorDetail;
28166
28413
  exports.invoke = invoke;
28167
28414
  exports.invokeDelete = invokeDelete;
28168
28415
  exports.invokeRead = invokeRead;
28416
+ exports.invokeReadPages = invokeReadPages;
28169
28417
  exports.invokeWrite = invokeWrite;
28170
28418
  exports.isAutotaskError = isAutotaskError;
28171
28419
  exports.isClosedStatus = isClosedStatus;