sg-widgets-core 0.3.0 → 0.4.0

package/dist/{client-izKszX7l.mjs → schema-write-D_WfMYW8.mjs}

@@ -236,6 +236,36 @@ function isTemporalType(dataType) {
 	return dataType === "date" || dataType === "date_time";
 }
 //#endregion
+//#region src/field-name.ts
+/** The prefix the server puts in front of every custom field it creates. */
+const CUSTOM_FIELD_PREFIX = "sg_";
+/**
+* Whether a display name holds a character outside ASCII. The server discards such a name
+* whole when it derives the programmatic name (findings/117_field_types_and_names).
+*/
+function hasNonAscii(displayName) {
+	return /[^\u0000-\u007F]/u.test(displayName);
+}
+/**
+* The programmatic name the server derives from a display name, or null when it cannot be
+* predicted: a blank display name, or a non-ASCII one without its data type.
+*
+* An ASCII display name gives the prefix, then the name lowercased with each character
+* outside `[a-z0-9_]` replaced by one underscore. Nothing is trimmed, collapsed or cut, a
+* leading digit stays, and a prefix already there is doubled (findings/019_create_fields,
+* findings/117_field_types_and_names).
+*
+* One non-ASCII character anywhere and the server ignores the display name: the field is
+* `sg_<data_type>`. That is measured on a `currency` field and inferred for the other types.
+* A name already taken comes back suffixed `_1`, `_2`, and a name a retired field holds is
+* refused; neither is predicted here.
+*/
+function predictFieldName(displayName, dataType) {
+	if (displayName.trim() === "") return null;
+	if (hasNonAscii(displayName)) return dataType ? "sg_" + dataType : null;
+	return "sg_" + displayName.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+}
+//#endregion
 //#region src/filter.ts
 /**
 * The filter array `entity_types` wants, `[]` for no filter
@@ -450,7 +480,7 @@ function normalizeField(name, raw) {
 	if (hiddenValues) field.hiddenValues = hiddenValues;
 	const defaultValue = prop(props, "default_value");
 	if (defaultValue !== void 0) field.defaultValue = defaultValue;
-	const description = prop(props, "description");
+	const description = raw.description?.value;
 	if (description) field.description = description;
 	if (raw.visible) field.hideable = raw.visible.editable;
 	return {
@@ -1053,4 +1083,356 @@ function toStatusIcon(a) {
 	}
 }
 //#endregion
-export { NEGATING_OPERATORS as A, isTemporalType as B, isBlankCondition as C, toFilterArray as D, toApi3Hash as E, isDataType as F, supportsOperator as H, isFilterable as I, isLinkType as L, OPERATORS_BY_TYPE as M, TIME_UNITS as N, walk as O, VALUE_SHAPE as P, isNumericType as R, group as S, referencedPaths as T, operatorsFor as V, undeclaredField as _, eventLogFilters as a, emptyFilter as b, normalizeHierarchyNode as c, displayNameOf as d, fieldSchemaOverride as f, statusFieldNameFor as g, statusFieldFor as h, batchResults as i, OPERATORS as j, DATA_TYPES as k, DISPLAY_NAME_FIELDS as l, normalizeFields as m, RestClient as n, hierarchyEntity as o, normalizeField as p, SgApiError as r, normalizeEventLogEntry as s, EVENT_LOG_FIELDS as t, FIELD_SCHEMA_OVERRIDES as u, pluralPath as v, isEmptyFilter as w, fromWire as x, condition as y, isOperator as z };
+//#region src/schema-write.ts
+function toSchemaProperties(properties) {
+	if (!properties) return [];
+	if (Array.isArray(properties)) return properties;
+	return Object.entries(properties).map(([property_name, value]) => ({
+		property_name,
+		value
+	}));
+}
+function firstError(body) {
+	if (body === null || typeof body !== "object") return {};
+	const errors = body.errors;
+	const first = Array.isArray(errors) ? errors[0] : null;
+	return first !== null && typeof first === "object" ? first : {};
+}
+/** The strings a `source` holds, e.g. `{"revive": ["revive is missing"]}`. */
+function sourceMessages(source) {
+	if (source === null || typeof source !== "object") return [];
+	return Object.values(source).flat().filter((value) => typeof value === "string");
+}
+/**
+* A refusal from a schema call, as the server sent it: `status` and `body` whole,
+* and the first error's `code`, `title`, `detail` and `source` lifted out.
+*
+* `message` is the `detail` where there is one and the `title` otherwise, followed
+* by whatever only the `source` says. A 404 is titled `Not Found` and says which
+* name is wrong in its `detail` (002_schema).
+*/
+var SchemaApiError = class extends SgApiError {
+	code;
+	title;
+	detail;
+	source;
+	constructor(status, body, message) {
+		const first = firstError(body);
+		const title = typeof first.title === "string" ? first.title : null;
+		const detail = typeof first.detail === "string" ? first.detail : null;
+		const said = detail ?? title;
+		const composed = [said, ...sourceMessages(first.source).filter((text) => !said?.includes(text))].filter((text) => text).join(" ");
+		super(status, body, message ?? (composed || `Flow PT API error ${status}`));
+		this.name = "SchemaApiError";
+		this.code = typeof first.code === "number" ? first.code : null;
+		this.title = title;
+		this.detail = detail;
+		this.source = first.source ?? null;
+	}
+};
+/** The one 404 that means the field is absent; an unknown type's 404 says `Entity type` (get_schema_type_fields_field). */
+const FIELD_MISSING = /^Field '.*' does not exist/;
+function isMissingField(error) {
+	return error.status === 404 && FIELD_MISSING.test(error.detail ?? error.title ?? error.message);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* A wrapped record as a `FieldSchema`. The record is left as it came; a key the
+* response leaves out is read as its default, with the type taken from the path.
+*/
+function fieldFromRaw(entityType, name, raw) {
+	const fixed = (value) => ({
+		value,
+		editable: false
+	});
+	const loose = raw;
+	return normalizeField(name, {
+		...raw,
+		name: loose.name ?? fixed(name),
+		entity_type: loose.entity_type ?? fixed(entityType),
+		data_type: loose.data_type ?? fixed(""),
+		editable: loose.editable ?? fixed(false),
+		mandatory: loose.mandatory ?? fixed(false),
+		unique: loose.unique ?? fixed(false),
+		properties: loose.properties ?? {}
+	});
+}
+function fieldPath(entityType, field) {
+	const base = `/schema/${encodeURIComponent(entityType)}/fields`;
+	return field === void 0 ? base : `${base}/${encodeURIComponent(field)}`;
+}
+var RestSchemaClient = class {
+	options;
+	base;
+	fetchFn;
+	constructor(options) {
+		this.options = options;
+		this.base = options.siteUrl.replace(/\/+$/, "") + "/api/v1";
+		this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	async request(method, path, body, projectId) {
+		const url = new URL(this.base + path);
+		if (projectId !== void 0) url.searchParams.set("project_id", String(projectId));
+		const headers = {
+			Accept: "application/json",
+			Authorization: `Bearer ${await this.options.token()}`
+		};
+		const init = {
+			method,
+			headers
+		};
+		if (body !== void 0) {
+			headers["Content-Type"] = "application/json";
+			init.body = JSON.stringify(body);
+		}
+		const res = await this.fetchFn(url, init);
+		const text = await res.text();
+		let parsed = null;
+		try {
+			parsed = text ? JSON.parse(text) : null;
+		} catch {
+			parsed = text;
+		}
+		if (!res.ok) throw new SchemaApiError(res.status, parsed);
+		return {
+			status: res.status,
+			body: parsed
+		};
+	}
+	async readField(entityType, field, projectId) {
+		let reply;
+		try {
+			reply = await this.request("GET", fieldPath(entityType, field), void 0, projectId);
+		} catch (error) {
+			if (error instanceof SchemaApiError && isMissingField(error)) return {
+				status: "missing",
+				message: error.message
+			};
+			throw error;
+		}
+		const raw = isRecord(reply.body) ? reply.body["data"] : null;
+		if (!isRecord(raw)) return { status: "undeclared" };
+		const record = raw;
+		return {
+			status: "found",
+			field: fieldFromRaw(entityType, field, record),
+			raw: record
+		};
+	}
+	async readRawFields(entityType, projectId) {
+		const reply = await this.request("GET", fieldPath(entityType), void 0, projectId);
+		const data = isRecord(reply.body) ? reply.body["data"] : null;
+		return isRecord(data) ? data : {};
+	}
+	async createField(entityType, input) {
+		const body = {
+			data_type: input.dataType,
+			properties: [{
+				property_name: "name",
+				value: input.displayName
+			}, ...toSchemaProperties(input.properties)]
+		};
+		const reply = await this.request("POST", fieldPath(entityType), body);
+		const envelope = isRecord(reply.body) ? reply.body : {};
+		const links = envelope["links"];
+		const self = isRecord(links) && typeof links["self"] === "string" ? links["self"] : "";
+		const name = decodeURIComponent(self.split("?")[0]?.split("/").filter(Boolean).pop() ?? "");
+		if (!name) throw new SchemaApiError(reply.status, reply.body, "The create answered no links.self, so the name of the field is unknown");
+		const data = envelope["data"];
+		return {
+			name,
+			self,
+			raw: isRecord(data) ? data : null
+		};
+	}
+	async updateField(entityType, field, properties, projectId) {
+		const body = { properties: toSchemaProperties(properties) };
+		if (projectId !== void 0) body["project_id"] = projectId;
+		const reply = await this.request("PUT", fieldPath(entityType, field), body);
+		const data = isRecord(reply.body) ? reply.body["data"] : null;
+		return isRecord(data) ? data : null;
+	}
+	async retireField(entityType, field) {
+		await this.request("DELETE", fieldPath(entityType, field));
+	}
+	async reviveField(entityType, field) {
+		try {
+			await this.request("POST", fieldPath(entityType, field), { revive: true });
+			return { revived: true };
+		} catch (error) {
+			if (error instanceof SchemaApiError && isDeclined(error.status)) return {
+				revived: false,
+				status: error.status,
+				message: error.message
+			};
+			throw error;
+		}
+	}
+};
+/** A refusal of the revive itself, as against a refused sign-in, a missing right or a fault. */
+function isDeclined(status) {
+	return status >= 400 && status < 500 && status !== 401 && status !== 403;
+}
+/** The schema methods the proxy protocol carries, one POST each, beside `PROXY_METHODS`. */
+const SCHEMA_PROXY_METHODS = [
+	"readField",
+	"readRawFields",
+	"createField",
+	"updateField",
+	"retireField",
+	"reviveField"
+];
+function isSchemaProxyMethod(value) {
+	return SCHEMA_PROXY_METHODS.includes(value);
+}
+var BadRequest = class extends Error {};
+function str(value, name) {
+	if (typeof value !== "string" || value.length === 0) throw new BadRequest(`'${name}' must be a non-empty string`);
+	return value;
+}
+function optionalNum(value, name) {
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new BadRequest(`'${name}' must be a number`);
+	return value;
+}
+/** A list of `{property_name, value}` or a record; the API names what is wrong inside one. */
+function properties(value, name) {
+	if (Array.isArray(value)) {
+		for (const [i, item] of value.entries()) if (!isRecord(item) || typeof item["property_name"] !== "string") throw new BadRequest(`'${name}[${i}]' must be a {property_name, value} object`);
+		return value;
+	}
+	if (!isRecord(value)) throw new BadRequest(`'${name}' must be a list or a JSON object`);
+	return value;
+}
+function createInput(value) {
+	if (!isRecord(value)) throw new BadRequest("'input' must be a JSON object");
+	const input = {
+		dataType: str(value["dataType"], "input.dataType"),
+		displayName: str(value["displayName"], "input.displayName")
+	};
+	if (value["properties"] !== void 0 && value["properties"] !== null) input.properties = properties(value["properties"], "input.properties");
+	return input;
+}
+function fail(status, message, body = null) {
+	return {
+		status,
+		body: { error: {
+			status,
+			message,
+			body
+		} }
+	};
+}
+function call(client, method, p) {
+	const entityType = str(p["entityType"], "entityType");
+	switch (method) {
+		case "readField": return client.readField(entityType, str(p["field"], "field"), optionalNum(p["projectId"], "projectId"));
+		case "readRawFields": return client.readRawFields(entityType, optionalNum(p["projectId"], "projectId"));
+		case "createField": return client.createField(entityType, createInput(p["input"]));
+		case "updateField": return client.updateField(entityType, str(p["field"], "field"), properties(p["properties"], "properties"), optionalNum(p["projectId"], "projectId"));
+		case "retireField": return client.retireField(entityType, str(p["field"], "field")).then(() => null);
+		case "reviveField": return client.reviveField(entityType, str(p["field"], "field"));
+	}
+}
+/**
+* The server half of `ProxySchemaClient`, in the protocol of `createProxyHandler`.
+* It answers 404 to a method that is not a schema one, so a host routes on
+* `isSchemaProxyMethod`, or hands the schema client to `createProxyHandler`.
+*
+* These calls change the site's schema for everyone: expose them only to the
+* people who may.
+*/
+function createSchemaProxyHandler(client) {
+	return async function handle(method, body) {
+		if (!isSchemaProxyMethod(method)) return fail(404, `Unknown method '${method}'`);
+		if (body !== void 0 && body !== null && !isRecord(body)) return fail(400, "Body must be a JSON object");
+		try {
+			return {
+				status: 200,
+				body: { data: await call(client, method, body ?? {}) }
+			};
+		} catch (error) {
+			if (error instanceof BadRequest) return fail(400, error.message);
+			if (error instanceof SgApiError) return fail(error.status, error.message, error.body);
+			return fail(500, error instanceof Error ? error.message : String(error));
+		}
+	};
+}
+/** A `SchemaClient` over the host app's own endpoints: one POST per method under `basePath`. */
+var ProxySchemaClient = class {
+	options;
+	base;
+	fetchFn;
+	constructor(options) {
+		this.options = options;
+		this.base = options.basePath.replace(/\/+$/, "");
+		this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	async post(method, body) {
+		const supplied = typeof this.options.headers === "function" ? await this.options.headers() : this.options.headers ?? {};
+		const res = await this.fetchFn(`${this.base}/${method}`, {
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				"Content-Type": "application/json",
+				...supplied
+			},
+			body: JSON.stringify(body)
+		});
+		const text = await res.text();
+		let payload = null;
+		try {
+			payload = text ? JSON.parse(text) : null;
+		} catch {
+			throw new SchemaApiError(res.status, text, `Proxy returned a non-JSON body for '${method}'`);
+		}
+		const envelope = isRecord(payload) ? payload : {};
+		const error = envelope["error"];
+		if (isRecord(error) && typeof error["status"] === "number" && typeof error["message"] === "string") throw new SchemaApiError(error["status"], error["body"] ?? null, error["message"]);
+		if (!res.ok) throw new SchemaApiError(res.status, payload, `Proxy error ${res.status} for '${method}'`);
+		return envelope["data"] ?? null;
+	}
+	readField(entityType, field, projectId) {
+		return this.post("readField", {
+			entityType,
+			field,
+			projectId: projectId ?? null
+		});
+	}
+	readRawFields(entityType, projectId) {
+		return this.post("readRawFields", {
+			entityType,
+			projectId: projectId ?? null
+		});
+	}
+	createField(entityType, input) {
+		return this.post("createField", {
+			entityType,
+			input
+		});
+	}
+	updateField(entityType, field, properties, projectId) {
+		return this.post("updateField", {
+			entityType,
+			field,
+			properties,
+			projectId: projectId ?? null
+		});
+	}
+	async retireField(entityType, field) {
+		await this.post("retireField", {
+			entityType,
+			field
+		});
+	}
+	reviveField(entityType, field) {
+		return this.post("reviveField", {
+			entityType,
+			field
+		});
+	}
+};
+//#endregion
+export { supportsOperator as $, group as A, DATA_TYPES as B, statusFieldFor as C, condition as D, pluralPath as E, toFilterArray as F, VALUE_SHAPE as G, OPERATORS as H, walk as I, isLinkType as J, isDataType as K, CUSTOM_FIELD_PREFIX as L, isEmptyFilter as M, referencedPaths as N, emptyFilter as O, toApi3Hash as P, operatorsFor as Q, hasNonAscii as R, normalizeFields as S, undeclaredField as T, OPERATORS_BY_TYPE as U, NEGATING_OPERATORS as V, TIME_UNITS as W, isOperator as X, isNumericType as Y, isTemporalType as Z, DISPLAY_NAME_FIELDS as _, createSchemaProxyHandler as a, fieldSchemaOverride as b, toSchemaProperties as c, SgApiError as d, batchResults as f, normalizeHierarchyNode as g, normalizeEventLogEntry as h, SchemaApiError as i, isBlankCondition as j, fromWire as k, EVENT_LOG_FIELDS as l, hierarchyEntity as m, RestSchemaClient as n, fieldFromRaw as o, eventLogFilters as p, isFilterable as q, SCHEMA_PROXY_METHODS as r, isSchemaProxyMethod as s, ProxySchemaClient as t, RestClient as u, FIELD_SCHEMA_OVERRIDES as v, statusFieldNameFor as w, normalizeField as x, displayNameOf as y, predictFieldName as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sg-widgets-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Headless, framework-agnostic model of Flow Production Tracking (ShotGrid) fields, filters, statuses and a client adapter, for building widgets.",
   "keywords": [
     "shotgrid",