sg-widgets-core 0.1.0

package/dist/client-DwN_-UuF.mjs

@@ -0,0 +1,1015 @@
+//#region src/field-types.ts
+/**
+* Field data types and their filter vocabularies.
+*
+* Every list here is what a live Flow Production Tracking site answered when a
+* probe sent it an unknown operator: the 400 names the legal set. Source:
+* sg-groundtruth corpus, `findings/field_types/*.md` and `findings/017_filter_operators.md`.
+*/
+const DATA_TYPES = [
+	"text",
+	"number",
+	"float",
+	"percent",
+	"duration",
+	"timecode",
+	"currency",
+	"checkbox",
+	"date",
+	"date_time",
+	"list",
+	"status_list",
+	"entity",
+	"multi_entity",
+	"entity_type",
+	"color",
+	"image",
+	"url",
+	"jsonb",
+	"serializable",
+	"uuid",
+	"calculated",
+	"summary",
+	"password",
+	"pivot_column",
+	"footage",
+	"tag_list"
+];
+const OPERATORS = [
+	"is",
+	"is_not",
+	"in",
+	"not_in",
+	"contains",
+	"not_contains",
+	"starts_with",
+	"ends_with",
+	"greater_than",
+	"less_than",
+	"between",
+	"in_last",
+	"not_in_last",
+	"in_next",
+	"not_in_next",
+	"in_calendar_day",
+	"in_calendar_week",
+	"in_calendar_month",
+	"in_calendar_year",
+	"name_is",
+	"name_contains",
+	"name_not_contains",
+	"type_is",
+	"type_is_not"
+];
+const TIME_UNITS = [
+	"HOUR",
+	"DAY",
+	"WEEK",
+	"MONTH",
+	"YEAR"
+];
+const EQUALITY = [
+	"is",
+	"is_not",
+	"in",
+	"not_in"
+];
+const TEXT = [
+	"contains",
+	"not_contains",
+	"is",
+	"is_not",
+	"starts_with",
+	"ends_with",
+	"in",
+	"not_in"
+];
+const NUMERIC = [
+	"is",
+	"is_not",
+	"greater_than",
+	"less_than",
+	"between",
+	"in",
+	"not_in"
+];
+const TEMPORAL = [
+	"is",
+	"is_not",
+	"greater_than",
+	"less_than",
+	"in_last",
+	"not_in_last",
+	"in_next",
+	"not_in_next",
+	"in_calendar_week",
+	"in_calendar_month",
+	"in_calendar_day",
+	"in_calendar_year",
+	"between",
+	"in",
+	"not_in"
+];
+const LINK = [
+	"is",
+	"is_not",
+	"name_contains",
+	"name_not_contains",
+	"name_is",
+	"type_is",
+	"type_is_not",
+	"in",
+	"not_in"
+];
+const NONE = [];
+/**
+* Operators each data type accepts in a `_search` filter. An empty list means the
+* type "cannot be used in a filter" and the API 400s on every operator.
+*/
+const OPERATORS_BY_TYPE = {
+	text: TEXT,
+	number: NUMERIC,
+	float: NUMERIC,
+	percent: NUMERIC,
+	duration: NUMERIC,
+	timecode: NUMERIC,
+	currency: NUMERIC,
+	footage: NUMERIC,
+	checkbox: ["is", "is_not"],
+	date: TEMPORAL,
+	date_time: TEMPORAL,
+	list: EQUALITY,
+	status_list: EQUALITY,
+	entity_type: EQUALITY,
+	color: EQUALITY,
+	uuid: EQUALITY,
+	entity: LINK,
+	multi_entity: LINK,
+	tag_list: LINK,
+	image: ["is", "is_not"],
+	jsonb: [
+		"is",
+		"is_not",
+		"contains",
+		"not_contains"
+	],
+	url: NONE,
+	serializable: NONE,
+	calculated: NONE,
+	summary: NONE,
+	password: NONE,
+	pivot_column: NONE
+};
+const VALUE_SHAPE = {
+	is: "scalar",
+	is_not: "scalar",
+	in: "list",
+	not_in: "list",
+	contains: "scalar",
+	not_contains: "scalar",
+	starts_with: "scalar",
+	ends_with: "scalar",
+	greater_than: "scalar",
+	less_than: "scalar",
+	between: "range",
+	in_last: "relative",
+	not_in_last: "relative",
+	in_next: "relative",
+	not_in_next: "relative",
+	in_calendar_day: "calendar",
+	in_calendar_week: "calendar",
+	in_calendar_month: "calendar",
+	in_calendar_year: "calendar",
+	name_is: "string",
+	name_contains: "string",
+	name_not_contains: "string",
+	type_is: "string",
+	type_is_not: "string"
+};
+/**
+* Operators whose result set includes rows where the field is null.
+* `is_not X` is not the complement of `is X` on Flow PT: every negating operator
+* matches unset rows, while comparisons exclude them.
+*/
+const NEGATING_OPERATORS = /* @__PURE__ */ new Set([
+	"is_not",
+	"not_in",
+	"not_contains",
+	"not_in_last",
+	"not_in_next",
+	"name_not_contains",
+	"type_is_not"
+]);
+function isDataType(value) {
+	return DATA_TYPES.includes(value);
+}
+function isOperator(value) {
+	return OPERATORS.includes(value);
+}
+/** Operators legal for a data type. Unknown types get the equality set, the smallest one the API prints. */
+function operatorsFor(dataType) {
+	return isDataType(dataType) ? OPERATORS_BY_TYPE[dataType] : EQUALITY;
+}
+function isFilterable(dataType) {
+	return operatorsFor(dataType).length > 0;
+}
+function supportsOperator(dataType, operator) {
+	return operatorsFor(dataType).includes(operator);
+}
+/** Types whose scalar value is a `{type, id}` entity hash. */
+function isLinkType(dataType) {
+	return dataType === "entity" || dataType === "multi_entity" || dataType === "tag_list";
+}
+/** Types whose scalar value is a number (integer unless noted). */
+function isNumericType(dataType) {
+	return [
+		"number",
+		"float",
+		"percent",
+		"duration",
+		"timecode",
+		"currency",
+		"footage"
+	].includes(dataType);
+}
+function isTemporalType(dataType) {
+	return dataType === "date" || dataType === "date_time";
+}
+//#endregion
+//#region src/filter.ts
+/**
+* The filter array `entity_types` wants, `[]` for no filter
+* (post_entity_text_search). The array form is `and` only and cannot express a
+* nested group, so one is refused here rather than sent and guessed at.
+*/
+function toFilterArray(filter) {
+	if (!filter) return [];
+	if (Array.isArray(filter)) return filter;
+	if (filter.logical_operator !== "and") throw new Error("A '_text_search' filter is an array of conditions, which is 'and' only.");
+	return filter.conditions.map((c) => {
+		if (!Array.isArray(c)) throw new Error("A '_text_search' filter is an array of conditions and cannot nest a group.");
+		return c;
+	});
+}
+function group(logicalOperator, conditions = []) {
+	return {
+		kind: "group",
+		logicalOperator,
+		conditions
+	};
+}
+function condition(path, operator, value) {
+	return {
+		kind: "condition",
+		path,
+		operator,
+		value
+	};
+}
+function emptyFilter() {
+	return group("and");
+}
+/**
+* A condition is blank when it has no path, or when its operator needs a value
+* and none was given. Blank conditions are dropped on serialisation rather than
+* sent as a degenerate filter.
+*/
+function isBlankCondition(c) {
+	if (!c.path) return true;
+	const shape = VALUE_SHAPE[c.operator];
+	const v = c.value;
+	switch (shape) {
+		case "scalar":
+		case "string": return v === void 0 || v === "";
+		case "list": return !Array.isArray(v) || v.length === 0;
+		case "range": return !Array.isArray(v) || v.length !== 2 || v[0] == null || v[1] == null;
+		case "relative": return !Array.isArray(v) || v.length !== 2 || typeof v[0] !== "number" || v[0] <= 0 || !v[1];
+		case "calendar": return typeof v !== "number";
+		case "none": return false;
+	}
+}
+/** True when serialisation would produce no conditions at all. */
+function isEmptyFilter(node) {
+	if (node.kind === "condition") return isBlankCondition(node);
+	return node.conditions.every(isEmptyFilter);
+}
+function stripName(v) {
+	if (v !== null && typeof v === "object") return {
+		type: v.type,
+		id: v.id
+	};
+	return v;
+}
+function serializeValue(c) {
+	const shape = VALUE_SHAPE[c.operator];
+	const v = c.value;
+	if (shape === "list" || shape === "range") return v.map(stripName);
+	if (shape === "relative" || shape === "calendar" || shape === "none") return v;
+	return stripName(v);
+}
+/**
+* Serialise a tree to the `api3_hash` `filters` value. Blank conditions and
+* groups that end up empty are dropped. Returns `null` when nothing remains,
+* so callers can omit `filters` rather than send `[]` (which matches every
+* row on the site).
+*/
+function toApi3Hash(node) {
+	const out = serializeNode(node);
+	if (out === null) return null;
+	if (Array.isArray(out)) return {
+		logical_operator: "and",
+		conditions: [out]
+	};
+	return out;
+}
+function serializeNode(node) {
+	if (node.kind === "condition") {
+		if (isBlankCondition(node)) return null;
+		return [
+			node.path,
+			node.operator,
+			serializeValue(node)
+		];
+	}
+	const conditions = node.conditions.map(serializeNode).filter((c) => c !== null);
+	if (conditions.length === 0) return null;
+	return {
+		logical_operator: node.logicalOperator,
+		conditions
+	};
+}
+/** Parse a wire group (or a flat `api3_array` list) back into the editor tree. */
+function fromWire(wire) {
+	if (Array.isArray(wire)) return group("and", wire.map(fromWireCondition));
+	return group(wire.logical_operator, wire.conditions.map((c) => Array.isArray(c) ? fromWireCondition(c) : fromWire(c)));
+}
+function fromWireCondition([path, operator, value]) {
+	return condition(path, operator, value);
+}
+/** Depth-first walk, useful for collecting referenced paths or validating against a schema. */
+function* walk(node) {
+	yield node;
+	if (node.kind === "group") for (const child of node.conditions) yield* walk(child);
+}
+function referencedPaths(node) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const n of walk(node)) if (n.kind === "condition" && n.path) paths.add(n.path);
+	return [...paths];
+}
+//#endregion
+//#region src/entity-path.ts
+/** How a type is spelled in a url. Internal: nothing outside this package addresses the API by path. */
+function pluralPath(entityType) {
+	const snake = entityType.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+	if (snake.endsWith("s")) return `${snake}es`;
+	if (snake.endsWith("y") && !/[aeiou]y$/.test(snake)) return `${snake.slice(0, -1)}ies`;
+	return `${snake}s`;
+}
+//#endregion
+//#region src/schema.ts
+/**
+* Fields the schema types one way and the API answers another, keyed
+* `<Type>.<field>`. `Note.read_by_current_user` holds the codes `unread` and
+* `read`, never a boolean, so every control derived from it is a list and not a
+* checkbox (067_notes_in_the_stream, entity_types/Note).
+*
+* An entry carries the whole field, because a site may leave it out of the schema
+* and still answer it on the row: `GET /schema/Note/fields` answers 33 fields and
+* no `read_by_current_user` among them, while `GET /schema/Note/fields/read_by_current_user`
+* answers 200 with `data: null`, which is what an undeclared field reads as and a
+* name that is nothing at all answers 404 (068_note_read_state). `normalizeFields`
+* adds what the schema left out. A site that declares the field keeps its own
+* display name and editability and is corrected on the data type, the values and
+* the operators alone.
+*
+* `operators` is the set the API evaluates, which is not always the set it
+* advertises. `read_by_current_user` names `is`, `is_not`, `in` and `not_in` in its
+* own `Valid relations`, and evaluates only the first two: `in`, `not_in` and an
+* `is` value outside the vocabulary all answer 200 with the caller's unread rows
+* whatever the list holds, in `_search` and in `_summarize`, under both body shapes
+* (068_note_read_state).
+*
+* The value is per person: a person's `PUT` answers 200 and the re-read follows it,
+* so the field is editable. A script has no read state, and its own write answers
+* 200 and stores nothing (068_note_read_state).
+*/
+const FIELD_SCHEMA_OVERRIDES = { "Note.read_by_current_user": {
+	displayName: "Read by Current User",
+	dataType: "list",
+	validValues: ["unread", "read"],
+	operators: ["is", "is_not"],
+	editable: true,
+	mandatory: false,
+	unique: false
+} };
+/** The part of an override that corrects a declaring site. */
+const PATCHED_KEYS = [
+	"dataType",
+	"validValues",
+	"operators"
+];
+/** What a declared field's schema has to be corrected to, when it is one of those. */
+function fieldSchemaOverride(entityType, name) {
+	const whole = FIELD_SCHEMA_OVERRIDES[`${entityType}.${name}`];
+	if (!whole) return void 0;
+	const patch = {};
+	for (const key of PATCHED_KEYS) if (whole[key] !== void 0) Object.assign(patch, { [key]: whole[key] });
+	return patch;
+}
+/** The whole field, for a site whose schema does not declare it; undefined when it is not one of those. */
+function undeclaredField(entityType, name) {
+	const whole = FIELD_SCHEMA_OVERRIDES[`${entityType}.${name}`];
+	return whole ? {
+		name,
+		entityType,
+		...whole
+	} : void 0;
+}
+function prop(props, key) {
+	const p = props?.[key];
+	return p ? p.value : void 0;
+}
+function normalizeField(name, raw) {
+	const props = raw.properties;
+	const field = {
+		name,
+		displayName: raw.name.value,
+		entityType: raw.entity_type.value,
+		dataType: raw.data_type.value,
+		editable: raw.editable.value,
+		mandatory: raw.mandatory.value,
+		unique: raw.unique.value
+	};
+	const validTypes = prop(props, "valid_types");
+	if (validTypes) field.validTypes = validTypes;
+	const validValues = prop(props, "valid_values");
+	if (validValues) field.validValues = validValues;
+	const displayValues = prop(props, "display_values");
+	if (displayValues) field.displayValues = displayValues;
+	const hiddenValues = prop(props, "hidden_values");
+	if (hiddenValues) field.hiddenValues = hiddenValues;
+	const defaultValue = prop(props, "default_value");
+	if (defaultValue !== void 0) field.defaultValue = defaultValue;
+	const description = prop(props, "description");
+	if (description) field.description = description;
+	return {
+		...field,
+		...fieldSchemaOverride(field.entityType, name)
+	};
+}
+/**
+* Every field of a type, with the fields an override declares and the schema omitted.
+*
+* `entityType` is only needed for a response with no fields at all; otherwise the
+* fields name their own type.
+*/
+function normalizeFields(response, entityType) {
+	const out = {};
+	for (const [name, raw] of Object.entries(response.data)) out[name] = normalizeField(name, raw);
+	const type = entityType ?? Object.values(out)[0]?.entityType;
+	if (!type) return out;
+	for (const key of Object.keys(FIELD_SCHEMA_OVERRIDES)) {
+		const at = key.indexOf(".");
+		const name = key.slice(at + 1);
+		if (key.slice(0, at) !== type || out[name]) continue;
+		const whole = undeclaredField(type, name);
+		if (whole) out[name] = whole;
+	}
+	return out;
+}
+/**
+* The field name a type's own status lives under. Project's is `sg_status`, a plain
+* `list` with the four values a bid goes through and no Status row behind it
+* (probe 018, entity_types/Project).
+*/
+function statusFieldNameFor(entityType) {
+	return entityType === "Project" ? "sg_status" : "sg_status_list";
+}
+/**
+* The status field of an entity type. Every type but Project uses `sg_status_list`
+* (data type `status_list`); Project's is `sg_status`, a plain `list`. Prefer the
+* schema when you have it; the name guess is the fallback.
+*
+* The conventional name wins over any other `status_list` field on the type. A site
+* is free to add its own — a client status, a delivery status — and a schema read
+* answers them in no order the caller controls, so picking the first one found makes
+* a type's status whichever field the response happened to list first.
+*/
+function statusFieldFor(entityType, fields) {
+	const name = statusFieldNameFor(entityType);
+	if (fields) {
+		const own = fields[name];
+		if (own) return own;
+		const status = Object.values(fields).find((f) => f.dataType === "status_list");
+		if (status) return status;
+	}
+	return name;
+}
+/**
+* The fields Flow PT conventionally uses as a row's human label, in order.
+* `cached_display_name` is the server's own copy, the same string an entity dict
+* carries as its `name`, and wins when present (060_entity_dict_name).
+*/
+const DISPLAY_NAME_FIELDS = [
+	"cached_display_name",
+	"code",
+	"name",
+	"title",
+	"content",
+	"subject"
+];
+function displayNameOf(attributes, fallback = "") {
+	if (!attributes) return fallback;
+	for (const key of DISPLAY_NAME_FIELDS) {
+		const v = attributes[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
+	return fallback;
+}
+//#endregion
+//#region src/client.ts
+/**
+* Client adapter.
+*
+* Widgets talk to a `SgClient` and nothing else. Browser code rarely calls the
+* Flow PT REST API directly (credentials, CORS), so most apps implement this
+* against their own proxy. `RestClient` is the reference implementation against
+* the REST API itself, for tests, tools and apps that can hold a token.
+*/
+/** The row a node stands for, or null when it stands for a type or nothing. */
+function hierarchyEntity(ref) {
+	if (!ref || ref.kind !== "entity" || ref.value === null || typeof ref.value !== "object") return null;
+	return ref.value;
+}
+/**
+* The cut the event log takes, as the `and` group `_search` wants. Nothing here
+* touches `meta`: it takes no filter (025_event_log).
+*/
+function eventLogFilters(options = {}) {
+	const conditions = [];
+	if (options.projectId !== void 0) conditions.push([
+		"project",
+		"is",
+		{
+			type: "Project",
+			id: options.projectId
+		}
+	]);
+	if (options.entity) conditions.push([
+		"entity",
+		"is",
+		{
+			type: options.entity.type,
+			id: options.entity.id
+		}
+	]);
+	if (options.eventType !== void 0) conditions.push(Array.isArray(options.eventType) ? [
+		"event_type",
+		"in",
+		options.eventType
+	] : [
+		"event_type",
+		"is",
+		options.eventType
+	]);
+	if (options.attributeName !== void 0) conditions.push([
+		"attribute_name",
+		"is",
+		options.attributeName
+	]);
+	if (options.since !== void 0) conditions.push([
+		"created_at",
+		"greater_than",
+		options.since
+	]);
+	if (options.until !== void 0) conditions.push([
+		"created_at",
+		"less_than",
+		options.until
+	]);
+	return {
+		logical_operator: "and",
+		conditions
+	};
+}
+/**
+* What an event is read with. `audit_trail` is never returned even when it is
+* named, so it is not asked for (025_event_log).
+*/
+const EVENT_LOG_FIELDS = [
+	"event_type",
+	"attribute_name",
+	"description",
+	"created_at",
+	"meta",
+	"entity",
+	"project",
+	"user"
+];
+/**
+* Normalise one node and the level below it.
+*
+* The sample response gives a child a `label`, a `ref` and `has_children` but not
+* always a `path`, so a child without one is addressed by appending its ref to the
+* parent's path (post_hierarchy_expand).
+*/
+function normalizeHierarchyNode(raw, path) {
+	const ref = {
+		kind: String(raw.ref?.kind ?? "empty"),
+		value: raw.ref?.value ?? null
+	};
+	const own = raw.path ?? path;
+	return {
+		label: String(raw.label ?? ""),
+		ref,
+		path: own,
+		parentPath: raw.parent_path ?? null,
+		hasChildren: raw.has_children ?? false,
+		children: uniqueByPath((raw.children ?? []).map((child) => normalizeHierarchyNode(child, childPath(own, child))))
+	};
+}
+/**
+* Children keyed by path, first occurrence kept. `_expand` repeats the "no <field>"
+* bucket (`.../Sequence/__none__`) once after every group on a grouped level, and the
+* repeats are the same node (post_hierarchy_expand, 064_hierarchy_expand_buckets).
+*/
+function uniqueByPath(nodes) {
+	const seen = /* @__PURE__ */ new Set();
+	return nodes.filter((node) => seen.has(node.path) ? false : (seen.add(node.path), true));
+}
+function childPath(parentPath, child) {
+	if (typeof child.path === "string") return child.path;
+	const value = child.ref?.value;
+	if (child.ref?.kind === "entity_type" && typeof value === "string") return `${parentPath}/${value}`;
+	if (child.ref?.kind === "entity" && value !== null && typeof value === "object") return `${parentPath}/id/${value.id}`;
+	return parentPath;
+}
+var SgApiError = class extends Error {
+	status;
+	body;
+	constructor(status, body, message) {
+		super(message ?? `Flow PT API error ${status}`);
+		this.status = status;
+		this.body = body;
+		this.name = "SgApiError";
+	}
+};
+const API3_HASH = "application/vnd+shotgun.api3_hash+json";
+function toHashGroup(filter) {
+	if (!filter) return {
+		logical_operator: "and",
+		conditions: []
+	};
+	if (Array.isArray(filter)) return {
+		logical_operator: "and",
+		conditions: filter
+	};
+	return filter;
+}
+var RestClient = class {
+	options;
+	base;
+	siteRoot;
+	fetchFn;
+	constructor(options) {
+		this.options = options;
+		this.siteRoot = options.siteUrl.replace(/\/+$/, "");
+		this.base = this.siteRoot + "/api/v1";
+		this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	async request(method, path, body, params, contentType = API3_HASH) {
+		const url = new URL(this.base + path);
+		for (const [k, v] of Object.entries(params ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+		const headers = {
+			Accept: "application/json",
+			Authorization: `Bearer ${await this.options.token()}`
+		};
+		if (body !== void 0) headers["Content-Type"] = contentType;
+		const init = {
+			method,
+			headers
+		};
+		if (body !== void 0) init.body = JSON.stringify(body);
+		const res = await this.fetchFn(url, init);
+		const text = await res.text();
+		const json = text ? JSON.parse(text) : null;
+		if (!res.ok) {
+			const title = json?.errors?.[0]?.title;
+			throw new SgApiError(res.status, json, title);
+		}
+		return json;
+	}
+	async entityTypes() {
+		const res = await this.request("GET", "/schema");
+		return Object.entries(res.data).map(([name, v]) => ({
+			name,
+			displayName: v.name.value
+		}));
+	}
+	async fields(entityType, projectId) {
+		return normalizeFields(await this.request("GET", `/schema/${entityType}/fields`, void 0, { project_id: projectId }), entityType);
+	}
+	async fieldWithProject(entityType, field, projectId) {
+		const res = await this.request("GET", `/schema/${entityType}/fields/${field}`, void 0, { project_id: projectId });
+		if (res.data) return normalizeField(field, res.data);
+		const known = undeclaredField(entityType, field);
+		if (known) return known;
+		throw new SgApiError(200, res, `Field '${entityType}.${field}' is not in the schema.`);
+	}
+	async search(entityType, options) {
+		const size = options.page?.size ?? 50;
+		const body = {
+			filters: options.filters ?? {
+				logical_operator: "and",
+				conditions: []
+			},
+			page: {
+				size,
+				number: options.page?.number ?? 1
+			}
+		};
+		if (options.fields) body["fields"] = options.fields.join(",");
+		if (options.sort) body["sort"] = options.sort;
+		const res = await this.request("POST", `/entity/${pluralPath(entityType)}/_search`, body);
+		return {
+			data: res.data,
+			hasMore: res.data.length === size
+		};
+	}
+	async textSearch(text, entityTypes, page) {
+		const types = {};
+		for (const [t, f] of Object.entries(entityTypes)) types[t] = toHashGroup(f);
+		const body = {
+			text,
+			entity_types: types,
+			page: {
+				size: Math.min(page?.size ?? 25, 25),
+				number: page?.number ?? 1
+			}
+		};
+		return (await this.request("POST", "/entity/_text_search", body)).data.map(toTextSearchRow);
+	}
+	async update(entityType, id, patch) {
+		return (await this.request("PUT", `/entity/${pluralPath(entityType)}/${id}`, patch, void 0, "application/json")).data;
+	}
+	async create(entityType, body) {
+		return (await this.request("POST", `/entity/${pluralPath(entityType)}`, body, void 0, "application/json")).data;
+	}
+	async upload(entityType, id, file) {
+		const field = file.field === void 0 ? "" : `/${file.field}`;
+		const ticket = await this.request("GET", `/entity/${pluralPath(entityType)}/${id}${field}/_upload`, void 0, { filename: file.filename });
+		const stored = await this.fetchFn(ticket.links.upload, {
+			method: "PUT",
+			body: file.data
+		});
+		if (!stored.ok) throw new SgApiError(stored.status, await stored.text(), "The presigned upload refused the bytes");
+		const completed = await this.fetchFn(new URL(ticket.links.complete_upload, this.siteRoot).toString(), {
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${await this.options.token()}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				upload_info: ticket.data,
+				upload_data: {}
+			})
+		});
+		if (!completed.ok) {
+			const text = await completed.text();
+			let parsed = text;
+			try {
+				parsed = text ? JSON.parse(text) : null;
+			} catch {
+				parsed = text;
+			}
+			const title = parsed?.errors?.[0]?.title;
+			throw new SgApiError(completed.status, parsed, title);
+		}
+		return {
+			uploadType: String(ticket.data["upload_type"] ?? ""),
+			uploadInfo: ticket.data,
+			etag: stored.headers.get("ETag")?.replace(/"/g, "") ?? null
+		};
+	}
+	async summarize(entityType, options = {}) {
+		const body = {
+			filters: options.filters ?? {
+				logical_operator: "and",
+				conditions: []
+			},
+			summary_fields: options.summaryFields ?? [{
+				field: "id",
+				type: "count"
+			}]
+		};
+		if (options.grouping) body["grouping"] = options.grouping.map((g) => ({
+			field: g.field,
+			type: g.type ?? "exact",
+			direction: g.direction ?? "asc"
+		}));
+		return normalizeSummarize(await this.request("POST", `/entity/${pluralPath(entityType)}/_summarize`, body));
+	}
+	async threadContents(noteId, entityFields) {
+		const params = {};
+		for (const [type, names] of Object.entries(entityFields ?? {})) params[`entity_fields[${type}]`] = names.join(",");
+		return (await this.request("GET", `/entity/notes/${noteId}/thread_contents`, void 0, params)).data.map(toThreadRow);
+	}
+	async eventLog(options = {}) {
+		const size = options.page?.size ?? 50;
+		const body = {
+			filters: eventLogFilters(options),
+			fields: EVENT_LOG_FIELDS.join(","),
+			sort: "-id",
+			page: {
+				size,
+				number: options.page?.number ?? 1
+			}
+		};
+		const res = await this.request("POST", "/entity/event_log_entries/_search", body);
+		return {
+			data: res.data.map(normalizeEventLogEntry),
+			hasMore: res.data.length === size
+		};
+	}
+	async following(userId, options = {}) {
+		return (await this.request("GET", `/entity/human_users/${userId}/following`, void 0, {
+			entity: options.entity,
+			project_id: options.projectId
+		})).data.map((row) => ({
+			type: String(row.type),
+			id: Number(row.id)
+		}));
+	}
+	async hierarchyExpand(path) {
+		return normalizeHierarchyNode((await this.request("POST", "/hierarchy/_expand", { path }, void 0, "application/json")).data, path);
+	}
+	async hierarchySearch(rootPath, entity) {
+		const body = {
+			root_path: rootPath,
+			search_criteria: { entity: {
+				type: entity.type,
+				id: entity.id
+			} }
+		};
+		return (await this.request("POST", "/hierarchy/_search", body, void 0, "application/json")).data.map(toHierarchyPath);
+	}
+	async statuses() {
+		const res = await this.request("GET", "/entity/statuses", void 0, {
+			fields: "code,name,bg_color,icon",
+			"page[size]": 500
+		});
+		const iconIds = /* @__PURE__ */ new Set();
+		for (const row of res.data) {
+			const icon = row.relationships["icon"]?.data;
+			if (icon) iconIds.add(icon.id);
+		}
+		const icons = /* @__PURE__ */ new Map();
+		if (iconIds.size > 0) {
+			const iconRes = await this.request("POST", "/entity/icons/_search", {
+				filters: {
+					logical_operator: "and",
+					conditions: [[
+						"id",
+						"in",
+						[...iconIds]
+					]]
+				},
+				fields: "display_type,image_map_key,url,html,image_data",
+				page: {
+					size: 500,
+					number: 1
+				}
+			});
+			for (const i of iconRes.data) icons.set(i.id, i);
+		}
+		return res.data.map((row) => {
+			const iconRef = row.relationships["icon"]?.data;
+			const icon = iconRef ? icons.get(iconRef.id) : void 0;
+			return {
+				id: row.id,
+				code: String(row.attributes["code"] ?? ""),
+				name: String(row.attributes["name"] ?? ""),
+				bgColor: row.attributes["bg_color"] ?? null,
+				icon: icon ? toStatusIcon(icon.attributes) : null
+			};
+		});
+	}
+};
+/** A grouped call wraps the answer in `data`; an ungrouped one does not (020_summarize). */
+function normalizeSummarize(res) {
+	const raw = res.data ?? res;
+	return {
+		summaries: raw.summaries ?? {},
+		groups: (raw.groups ?? []).map((g) => ({
+			groupName: String(g.group_name ?? ""),
+			groupValue: g.group_value ?? null,
+			summaries: g.summaries ?? {}
+		}))
+	};
+}
+function toTextSearchRow(row) {
+	const links = row.attributes?.links;
+	const pair = Array.isArray(links) ? [String(links[0] ?? ""), String(links[1] ?? "")] : ["", ""];
+	return {
+		type: String(row.type),
+		id: Number(row.id),
+		name: String(row.attributes?.name ?? ""),
+		links: pair,
+		status: row.attributes?.status ?? null
+	};
+}
+function toThreadAuthor(value) {
+	if (value === null || typeof value !== "object") return null;
+	const hash = value;
+	if (typeof hash.type !== "string" || typeof hash.id !== "number") return null;
+	const author = {
+		type: hash.type,
+		id: hash.id
+	};
+	if (typeof hash.name === "string") author.name = hash.name;
+	if (hash.image !== void 0) author.image = hash.image ?? null;
+	return author;
+}
+/**
+* The author key follows the row type: `created_by` on a Note and an Attachment,
+* `user` on a Reply (get_entity_notes_id_thread_contents). A Note widened with
+* `user` still names its author under `created_by`.
+*/
+function toThreadRow(row) {
+	const author = toThreadAuthor(row.type === "Reply" ? row["user"] : row["created_by"]);
+	return {
+		type: String(row.type),
+		id: Number(row.id),
+		createdAt: row["created_at"] ?? null,
+		content: row["content"] ?? null,
+		author,
+		fields: row
+	};
+}
+function entityRefOf(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const ref = value;
+	return typeof ref.name === "string" ? {
+		type: ref.type,
+		id: ref.id,
+		name: ref.name
+	} : {
+		type: ref.type,
+		id: ref.id
+	};
+}
+/** One `_search` row of `EventLogEntry`, with `meta` decoded as the API returns it. */
+function normalizeEventLogEntry(row) {
+	const a = row.attributes;
+	const meta = a["meta"] ?? null;
+	return {
+		id: row.id,
+		eventType: a["event_type"] ?? null,
+		attributeName: a["attribute_name"] ?? null,
+		description: a["description"] ?? null,
+		createdAt: a["created_at"] ?? null,
+		entity: entityRefOf(row.relationships["entity"]?.data),
+		project: entityRefOf(row.relationships["project"]?.data),
+		user: entityRefOf(row.relationships["user"]?.data),
+		meta,
+		oldValue: meta?.["old_value"] ?? null,
+		newValue: meta?.["new_value"] ?? null
+	};
+}
+function toHierarchyPath(row) {
+	return {
+		label: String(row.label ?? ""),
+		pathLabel: String(row.path_label ?? ""),
+		incrementalPath: row.incremental_path ?? [],
+		ref: {
+			type: row.ref.type,
+			id: row.ref.id
+		},
+		projectId: row.project_id ?? null
+	};
+}
+function toStatusIcon(a) {
+	switch (a["display_type"]) {
+		case "image_map": return {
+			displayType: "image_map",
+			imageMapKey: String(a["image_map_key"] ?? "")
+		};
+		case "image": {
+			const url = String(a["url"] ?? "").replace(/\s+/g, "");
+			const data = String(a["image_data"] ?? "").replace(/\s+/g, "");
+			const dataUrl = url || (data ? `data:image/png;base64,${data}` : "");
+			return dataUrl ? {
+				displayType: "image",
+				dataUrl
+			} : null;
+		}
+		case "html": return {
+			displayType: "html",
+			html: String(a["html"] ?? "")
+		};
+		default: return null;
+	}
+}
+//#endregion
+export { OPERATORS as A, operatorsFor as B, isEmptyFilter as C, walk as D, toFilterArray as E, isFilterable as F, isLinkType as I, isNumericType as L, TIME_UNITS as M, VALUE_SHAPE as N, DATA_TYPES as O, isDataType as P, isOperator as R, isBlankCondition as S, toApi3Hash as T, supportsOperator as V, pluralPath as _, hierarchyEntity as a, fromWire as b, DISPLAY_NAME_FIELDS as c, fieldSchemaOverride as d, normalizeField as f, undeclaredField as g, statusFieldNameFor as h, eventLogFilters as i, OPERATORS_BY_TYPE as j, NEGATING_OPERATORS as k, FIELD_SCHEMA_OVERRIDES as l, statusFieldFor as m, RestClient as n, normalizeEventLogEntry as o, normalizeFields as p, SgApiError as r, normalizeHierarchyNode as s, EVENT_LOG_FIELDS as t, displayNameOf as u, condition as v, referencedPaths as w, group as x, emptyFilter as y, isTemporalType as z };