sg-widgets-core 0.1.0

package/dist/client-BhHppzTV.d.mts

@@ -0,0 +1,740 @@
+//#region src/field-types.d.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`.
+ */
+declare const DATA_TYPES: readonly ['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'];
+type DataType = (typeof DATA_TYPES)[number];
+declare const OPERATORS: readonly ['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'];
+type Operator = (typeof OPERATORS)[number];
+declare const TIME_UNITS: readonly ['HOUR', 'DAY', 'WEEK', 'MONTH', 'YEAR'];
+type TimeUnit = (typeof TIME_UNITS)[number];
+/**
+ * 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.
+ */
+declare const OPERATORS_BY_TYPE: Readonly<Record<DataType, readonly Operator[]>>;
+/** Shape of the value an operator expects on the wire. */
+type ValueShape = 'scalar' | 'list' | 'range' | 'relative' | 'calendar' | 'string' | 'none';
+declare const VALUE_SHAPE: Readonly<Record<Operator, ValueShape>>;
+/**
+ * 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.
+ */
+declare const NEGATING_OPERATORS: ReadonlySet<Operator>;
+declare function isDataType(value: string): value is DataType;
+declare function isOperator(value: string): value is Operator;
+/** Operators legal for a data type. Unknown types get the equality set, the smallest one the API prints. */
+declare function operatorsFor(dataType: string): readonly Operator[];
+declare function isFilterable(dataType: string): boolean;
+declare function supportsOperator(dataType: string, operator: Operator): boolean;
+/** Types whose scalar value is a `{type, id}` entity hash. */
+declare function isLinkType(dataType: string): boolean;
+/** Types whose scalar value is a number (integer unless noted). */
+declare function isNumericType(dataType: string): boolean;
+declare function isTemporalType(dataType: string): boolean;
+//#endregion
+//#region src/filter.d.ts
+type LogicalOperator = 'and' | 'or';
+interface EntityRef {
+  type: string;
+  id: number;
+  /** `cached_display_name` of the target when known. Never sent to the API. */
+  name?: string;
+}
+type Scalar = string | number | boolean | null | EntityRef;
+type ConditionValue = Scalar | Scalar[] | [Scalar, Scalar] | [number, TimeUnit];
+interface FilterCondition {
+  kind: 'condition';
+  /** Dotted path such as `entity.Shot.code`. */
+  path: string;
+  operator: Operator;
+  value: ConditionValue;
+}
+interface FilterGroup {
+  kind: 'group';
+  logicalOperator: LogicalOperator;
+  conditions: FilterNode[];
+}
+type FilterNode = FilterGroup | FilterCondition;
+/** Wire shapes. */
+type WireCondition = [string, Operator, unknown];
+interface WireGroup {
+  logical_operator: LogicalOperator;
+  conditions: Array<WireCondition | WireGroup>;
+}
+/**
+ * What one type's entry in `_text_search`'s `entity_types` map accepts: a filter
+ * array, or a group this converts to one.
+ */
+type TextSearchFilter = WireGroup | WireCondition[] | null | undefined;
+/**
+ * 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.
+ */
+declare function toFilterArray(filter: TextSearchFilter): WireCondition[];
+declare function group(logicalOperator: LogicalOperator, conditions?: FilterNode[]): FilterGroup;
+declare function condition(path: string, operator: Operator, value: ConditionValue): FilterCondition;
+declare function emptyFilter(): FilterGroup;
+/**
+ * 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.
+ */
+declare function isBlankCondition(c: FilterCondition): boolean;
+/** True when serialisation would produce no conditions at all. */
+declare function isEmptyFilter(node: FilterNode): boolean;
+/**
+ * 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).
+ */
+declare function toApi3Hash(node: FilterNode): WireGroup | null;
+/** Parse a wire group (or a flat `api3_array` list) back into the editor tree. */
+declare function fromWire(wire: WireGroup | WireCondition[]): FilterGroup;
+/** Depth-first walk, useful for collecting referenced paths or validating against a schema. */
+declare function walk(node: FilterNode): Generator<FilterNode>;
+declare function referencedPaths(node: FilterNode): string[];
+//#endregion
+//#region src/schema.d.ts
+/** One property as the API returns it. */
+interface RawProperty<T = unknown> {
+  value: T;
+  editable: boolean;
+}
+interface RawFieldSchema {
+  name: RawProperty<string>;
+  entity_type: RawProperty<string>;
+  data_type: RawProperty<string>;
+  editable: RawProperty<boolean>;
+  mandatory: RawProperty<boolean>;
+  unique: RawProperty<boolean>;
+  properties: Record<string, RawProperty<unknown>>;
+}
+type RawFieldsResponse = {
+  data: Record<string, RawFieldSchema>;
+};
+interface FieldSchema {
+  /** Programmatic name, e.g. `sg_status_list`. */
+  name: string;
+  /** Human label, e.g. `Status`. */
+  displayName: string;
+  entityType: string;
+  dataType: DataType | string;
+  editable: boolean;
+  mandatory: boolean;
+  unique: boolean;
+  /** For `entity` and `multi_entity`: the types the field may link to. Advisory on most fields. */
+  validTypes?: string[];
+  /** For `list` and `status_list`: the site-wide vocabulary of codes. */
+  validValues?: string[];
+  /** For `status_list`: code to label map. Absent when labels equal codes. */
+  displayValues?: Record<string, string>;
+  /** For `list` and `status_list`, only when read with `project_id`. May contain codes outside `validValues`. */
+  hiddenValues?: string[];
+  /**
+   * The operators the API evaluates on this field, where they are fewer than the
+   * vocabulary it advertises. Absent means the whole vocabulary.
+   */
+  operators?: Operator[];
+  defaultValue?: unknown;
+  description?: string;
+}
+/**
+ * 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).
+ */
+declare const FIELD_SCHEMA_OVERRIDES: Readonly<Record<string, Readonly<Omit<FieldSchema, 'name' | 'entityType'>>>>;
+/** What a declared field's schema has to be corrected to, when it is one of those. */
+declare function fieldSchemaOverride(entityType: string, name: string): Readonly<Partial<FieldSchema>> | undefined;
+/** The whole field, for a site whose schema does not declare it; undefined when it is not one of those. */
+declare function undeclaredField(entityType: string, name: string): FieldSchema | undefined;
+declare function normalizeField(name: string, raw: RawFieldSchema): FieldSchema;
+/**
+ * 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.
+ */
+declare function normalizeFields(response: RawFieldsResponse, entityType?: string): Record<string, FieldSchema>;
+/**
+ * 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).
+ */
+declare function statusFieldNameFor(entityType: string): string;
+/**
+ * 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.
+ */
+declare function statusFieldFor(entityType: string, fields?: Record<string, FieldSchema>): FieldSchema | string;
+/**
+ * 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).
+ */
+declare const DISPLAY_NAME_FIELDS: readonly ['cached_display_name', 'code', 'name', 'title', 'content', 'subject'];
+declare function displayNameOf(attributes: Record<string, unknown> | null | undefined, fallback?: string): string;
+//#endregion
+//#region src/status-icons.d.ts
+/**
+ * Stock status icons.
+ *
+ * A status with an `image_map` icon names a CSS class such as `icon_apr`. The image
+ * behind it is one sprite the web app serves unauthenticated at
+ * `/images/sg_icon_image_map.png`, positioned by rules in
+ * `/dist/production/stylesheets/login.css` (probe 010). Neither is in the REST API.
+ * The offsets below are those rules, read once. The data URLs are the sprite cells of
+ * every icon the status picker offers (`icon_type: permanent_status`, 94 on the probed
+ * site), so a badge renders any stock status icon with no site access.
+ *
+ * A shipped status is a row with no `created_by`. `system` marks a subset of them
+ * (act, dis, ip, na, cfrm, pndng) and no schema flag marks the set; a site may
+ * have retired some of the shipped rows (probe 061).
+ */
+interface SpriteCell {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/** Path of the stock sprite on any site. The stylesheet appends a cache-busting query; the bare path answers 200. */
+declare const STOCK_SPRITE_PATH = "/images/sg_icon_image_map.png";
+interface NativeStatus {
+  code: string;
+  name: string;
+  /** `image_map_key` of the shipped icon. `act` has an html icon and no key. */
+  imageMapKey: string | null;
+  /** Locked by the system: cannot be deleted. */
+  system: boolean;
+}
+/** Shipped statuses the probed site keeps live, in id order (probe 061). */
+declare const NATIVE_STATUSES: readonly NativeStatus[];
+/** Sprite cell per `image_map_key`, from the site stylesheet. Covers every stock icon a status may use. */
+declare const STOCK_ICON_CELLS: Readonly<Record<string, SpriteCell>>;
+/** Every stock status icon as a PNG data URL, keyed by `image_map_key`. */
+declare const STOCK_ICON_DATA_URLS: Readonly<Record<string, string>>;
+/**
+ * The keys the status picker offers, in the site's order. Annotated pure, so a
+ * bundle that imports something else from this module drops the icon data with it.
+ */
+declare const STOCK_ICON_KEYS: readonly string[];
+declare function isNativeStatus(code: string): boolean;
+declare function nativeStatus(code: string): NativeStatus | undefined;
+/** How to draw a stock icon: a bundled image, the site's sprite for a key outside the status set, or nothing. */
+type StockIconSource = {
+  kind: 'data';
+  src: string;
+  cell: SpriteCell;
+} | {
+  kind: 'sprite';
+  src: string;
+  cell: SpriteCell;
+} | {
+  kind: 'none';
+};
+/**
+ * Resolve an `image_map_key`. Status icons come from the bundle. A key outside the
+ * status set is still a sprite cell, so it draws only when `siteUrl` is given.
+ */
+declare function stockIconSource(imageMapKey: string | null | undefined, siteUrl?: string): StockIconSource;
+/** Inline style for a sprite-backed icon element sized to its cell. */
+declare function spriteStyle(source: Extract<StockIconSource, {
+  kind: 'sprite';
+}>): Record<string, string>;
+//#endregion
+//#region src/status.d.ts
+interface StatusOption {
+  code: string;
+  label: string;
+}
+/** Codes a picker should offer for the project the schema was read with. */
+declare function usableStatuses(field: Pick<FieldSchema, 'validValues' | 'hiddenValues' | 'displayValues'>): StatusOption[];
+/** Codes usable in every one of several projects: the intersection of their usable sets, in the first schema's order. */
+declare function intersectStatuses(fields: Array<Pick<FieldSchema, 'validValues' | 'hiddenValues' | 'displayValues'>>): StatusOption[];
+declare function statusLabel(field: Pick<FieldSchema, 'displayValues'>, code: string): string;
+/**
+ * Status entity as `GET /entity/statuses?fields=code,name,bg_color,icon` returns it,
+ * flattened. `bg_color` is comma-separated decimal RGB (`"25,118,27"`), never hex.
+ */
+interface StatusRecord {
+  id: number;
+  code: string;
+  name: string;
+  bgColor: string | null;
+  icon: StatusIcon | null;
+}
+/** Icon entity. `displayType` picks one of three renderings (probe 010). */
+type StatusIcon = {
+  displayType: 'image_map';
+  imageMapKey: string;
+} | {
+  displayType: 'image';
+  dataUrl: string;
+} | {
+  displayType: 'html';
+  html: string;
+};
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+/** Parse `"25,118,27"` into channels. Returns null for anything else, including hex. */
+declare function parseBgColor(value: string | null | undefined): Rgb | null;
+declare function rgbToCss({ r, g, b }: Rgb): string;
+/** WCAG relative luminance, for choosing a readable foreground on a status badge. */
+declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** Black or white, whichever contrasts more with the given colour. */
+declare function foregroundFor(rgb: Rgb): 'black' | 'white';
+/**
+ * What a status paints with: its own `bg_color` and a readable ink on it. Null when
+ * the status carries no colour, which is every option of a plain `list` field.
+ */
+interface StatusPaint {
+  background: string;
+  foreground: string;
+}
+declare function statusPaint(status: Pick<StatusRecord, 'bgColor'> | null | undefined): StatusPaint | null;
+/**
+ * What a status draws as its glyph (010_status_icons). `image` is a self-contained
+ * data URI; `cell` is a bundled sprite cell and `sprite` one the site serves, both
+ * sized by that cell; `html` is the label itself, so it replaces the text rather than
+ * preceding it; `dot` stands in for a stock key this client has no cell for, and
+ * `none` is a status naming no icon at all.
+ */
+type StatusGlyph = {
+  kind: 'none';
+} | {
+  kind: 'html';
+  html: string;
+} | {
+  kind: 'image';
+  src: string;
+} | {
+  kind: 'cell';
+  imageMapKey: string;
+  src: string;
+  cell: SpriteCell;
+} | {
+  kind: 'sprite';
+  imageMapKey: string;
+  style: Record<string, string>;
+} | {
+  kind: 'dot';
+  imageMapKey: string;
+};
+/** The glyph a status draws, from its icon and whichever sprite can serve it. */
+declare function statusGlyph(status: Pick<StatusRecord, 'icon'> | null | undefined, siteUrl?: string): StatusGlyph;
+//#endregion
+//#region src/client.d.ts
+interface SearchOptions {
+  filters?: WireGroup | null;
+  fields?: string[];
+  sort?: string;
+  page?: {
+    size?: number;
+    number?: number;
+  };
+}
+/** One row of a `_search` response, kept in the API's shape. */
+interface EntityRow {
+  type: string;
+  id: number;
+  attributes: Record<string, unknown>;
+  relationships: Record<string, {
+    data: EntityRef | EntityRef[] | null;
+  }>;
+}
+interface SearchResult {
+  data: EntityRow[];
+  /** True when another page exists. Computed from data length, not `links.next`, which is emitted on empty pages too (probe 006). */
+  hasMore: boolean;
+}
+/**
+ * Row of `_text_search`, which is flattened and not the `_search` shape. There is
+ * no `fields` parameter: every row is name, links and status whatever the type, so
+ * a caller that needs a thumbnail or a project re-reads with `search`
+ * (post_entity_text_search).
+ */
+interface TextSearchRow {
+  type: string;
+  id: number;
+  name: string;
+  /** The linked row's type and name, `['', '']` when it links to nothing. Two bare strings, not a reference. */
+  links: [string, string];
+  /** Status code, never a label. */
+  status: string | null;
+}
+/**
+ * What a navigation node stands for. `entity` carries a `{type, id}`, `entity_type`
+ * a bare schema name; other kinds are passed through as the site sends them.
+ */
+interface HierarchyRef {
+  kind: string;
+  value: EntityRef | string | null;
+}
+/** One level of the navigation tree the web interface draws (post_hierarchy_expand). */
+interface HierarchyNode {
+  label: string;
+  ref: HierarchyRef;
+  /** The path to pass back to `hierarchyExpand` to open this node. */
+  path: string;
+  parentPath: string | null;
+  /** False when expanding this node would return nothing. */
+  hasChildren: boolean;
+  /** One level only: a child's own children come from its own call. */
+  children: HierarchyNode[];
+}
+/** Where one row sits in the navigation tree, as `POST /hierarchy/_search` answers it. */
+interface HierarchyPath {
+  /** The row's own display name. */
+  label: string;
+  /** The same breadcrumb rendered for a person. The project is not in it. */
+  pathLabel: string;
+  /** One path per level, root first; the last entry is the row itself. */
+  incrementalPath: string[];
+  ref: EntityRef;
+  projectId: number | null;
+}
+/** The row a node stands for, or null when it stands for a type or nothing. */
+declare function hierarchyEntity(ref: HierarchyRef | null | undefined): EntityRef | null;
+/**
+ * The aggregates `_summarize` offers. The endpoint prints the whole set in the 400 it
+ * answers a bogus one (020_summarize).
+ */
+type SummaryType = 'record_count' | 'count' | 'sum' | 'maximum' | 'minimum' | 'average' | 'earliest' | 'latest' | 'percentage' | 'status_percentage' | 'status_percentage_as_float' | 'status_list' | 'checked' | 'unchecked';
+interface SummaryField {
+  field: string;
+  type: SummaryType;
+}
+interface SummaryGrouping {
+  field: string;
+  /** Default `exact`, one group per distinct value. */
+  type?: string;
+  direction?: 'asc' | 'desc';
+}
+interface SummarizeOptions {
+  filters?: WireGroup | null;
+  /** Default `[{field: 'id', type: 'count'}]`. One type per field per call: the last entry wins (020_summarize). */
+  summaryFields?: SummaryField[];
+  grouping?: SummaryGrouping[];
+}
+interface SummaryGroup {
+  /** The server's render of the value, for display. Not unique. */
+  groupName: string;
+  /** What the grouping was computed on. Key on this (020_summarize). */
+  groupValue: unknown;
+  summaries: Record<string, number>;
+}
+interface SummarizeResult {
+  /** Keyed by field name. A field that cannot be summarized answers 200 with the key absent. */
+  summaries: Record<string, number>;
+  groups: SummaryGroup[];
+}
+interface EntityTypeInfo {
+  name: string;
+  displayName: string;
+}
+/**
+ * Who wrote a thread row. A Reply's hash carries a fourth key, `image`, a
+ * presigned avatar re-signed on every read; the `created_by` hash on a Note and
+ * an Attachment has none (get_entity_notes_id_thread_contents).
+ */
+interface ThreadAuthor extends EntityRef {
+  image?: string | null;
+}
+/** One row of a note thread, flat and not the `_search` shape. */
+interface ThreadRow {
+  /** `Note`, `Attachment` or `Reply`. */
+  type: string;
+  id: number;
+  createdAt: string | null;
+  /** The body. An Attachment row has none. */
+  content: string | null;
+  author: ThreadAuthor | null;
+  /** The row as it arrived, including whatever `entityFields` widened it by. */
+  fields: Record<string, unknown>;
+}
+/**
+ * Which rows the event log answers. `meta` holds what changed and takes neither a
+ * filter nor a sort, so the cut is made on these and `meta` is read off the row
+ * (025_event_log).
+ */
+interface EventLogOptions {
+  projectId?: number;
+  /**
+   * The row the events are about. It is null on an event whose target has been
+   * deleted, so a deleted row's history is reachable by `eventType` and dates alone.
+   */
+  entity?: EntityRef;
+  /** One event type or several, e.g. `Shotgun_Shot_Change`. */
+  eventType?: string | string[];
+  /** The field that changed. Site-wide on its own, so pair it with `entity` or `eventType`. */
+  attributeName?: string;
+  /** Keep events after this `date_time`, as `created_at greater_than`. */
+  since?: string;
+  /** Keep events before this `date_time`, as `created_at less_than`. */
+  until?: string;
+  page?: {
+    size?: number;
+    number?: number;
+  };
+}
+/**
+ * The cut the event log takes, as the `and` group `_search` wants. Nothing here
+ * touches `meta`: it takes no filter (025_event_log).
+ */
+declare function eventLogFilters(options?: EventLogOptions): WireGroup;
+/**
+ * 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).
+ */
+declare const EVENT_LOG_FIELDS: readonly ['event_type', 'attribute_name', 'description', 'created_at', 'meta', 'entity', 'project', 'user'];
+/** One event, `meta` decoded, with the two values an attribute change carries lifted out. */
+interface EventLogEntry {
+  id: number;
+  eventType: string | null;
+  attributeName: string | null;
+  /** The rendered English sentence the server writes. */
+  description: string | null;
+  createdAt: string | null;
+  /** Null once the row the event is about is deleted; `meta` still names it. */
+  entity: EntityRef | null;
+  project: EntityRef | null;
+  user: EntityRef | null;
+  /** The whole decoded `meta`. Its keys follow `meta.type`. */
+  meta: Record<string, unknown> | null;
+  /** `meta.old_value`, present on an `attribute_change` and nowhere else. */
+  oldValue: unknown;
+  /** `meta.new_value`, present on an `attribute_change` and nowhere else. */
+  newValue: unknown;
+}
+interface EventLogResult {
+  data: EventLogEntry[];
+  /** True when another page exists. Read from the row count, as on `search` (probe 006). */
+  hasMore: boolean;
+}
+/** Bytes to put on a row, and where they land. */
+interface UploadFile {
+  /** The name the bytes are stored under. Its extension decides the upload type. */
+  filename: string;
+  /** The bytes themselves. From a browser `File`, `new Uint8Array(await file.arrayBuffer())`. */
+  data: Uint8Array;
+  /**
+   * The field in the path, which picks the kind: `image` is a Thumbnail, another
+   * field an Attachment on that field, and no field at all a generic Attachment on
+   * `attachment_links` (recipes/001).
+   */
+  field?: string;
+}
+/** What the handshake answered. The Attachment it made is visible only on the parent row. */
+interface UploadResult {
+  /** `Thumbnail` on `image`, `Attachment` on any other form. Nothing in the request names it. */
+  uploadType: string;
+  /** The whole `upload_info` the ticket carried and the third call sent back. */
+  uploadInfo: Record<string, unknown>;
+  /** The storage's `ETag`, when it exposes one; the `PUT` status is the receipt (put_links_upload). */
+  etag: string | null;
+}
+/** The two cuts `following` takes. Both are made server-side. */
+interface FollowingOptions {
+  /** One type to keep. The schema name and the snake_case plural both work. */
+  entity?: string;
+  projectId?: number;
+}
+interface SgClient {
+  /** Enabled entity types on the site with their display names. */
+  entityTypes(): Promise<EntityTypeInfo[]>;
+  /** All fields of a type. Pass `projectId` to get `hiddenValues` on status and list fields. */
+  fields(entityType: string, projectId?: number): Promise<Record<string, FieldSchema>>;
+  /**
+   * One field at project scope, 1.2KB against 48KB for the whole type (probe 002).
+   * Only `hiddenValues` differs from the site-scope read (probe 009).
+   */
+  fieldWithProject(entityType: string, field: string, projectId: number): Promise<FieldSchema>;
+  search(entityType: string, options: SearchOptions): Promise<SearchResult>;
+  /**
+   * Free-text search across several types at once. Every word must match, each as
+   * a case-insensitive substring of the row's name or of the linked row's name
+   * (probe 053). Page size is 1 to 25 and 25 is also the default; there is no
+   * `links`, so page until the answer is empty.
+   */
+  textSearch(text: string, entityTypes: Record<string, TextSearchFilter>, page?: {
+    size?: number;
+    number?: number;
+  }): Promise<TextSearchRow[]>;
+  /** Status entities with colour and icon. */
+  statuses(): Promise<StatusRecord[]>;
+  /**
+   * Change the named fields of one row and answer the whole record.
+   *
+   * A key left out of `patch` is unchanged, not cleared, and an empty patch is a
+   * no-op (put_entity_type_id). The answer never resolves a dotted path, so a
+   * caller that shows one re-reads the row (024_read_after_write).
+   */
+  update(entityType: string, id: number, patch: Record<string, unknown>): Promise<EntityRow>;
+  /**
+   * One level of the site's navigation tree. `path` is `/Project/<id>` at the root
+   * and a child's own `path` below it (post_hierarchy_expand).
+   */
+  hierarchyExpand(path: string): Promise<HierarchyNode>;
+  /**
+   * Where a row sits in the navigation tree, under `rootPath` (`/Project/<id>`).
+   * The search criteria takes the literal key `entity` and nothing else: any other
+   * key answers `search_criteria size must be 1`, which counts the keys it
+   * recognises rather than the ones sent (post_hierarchy_search).
+   */
+  hierarchySearch(rootPath: string, entity: EntityRef): Promise<HierarchyPath[]>;
+  /**
+   * Aggregate rows without paging them. One `grouping` returns a field's distinct
+   * values and their counts (020_summarize).
+   */
+  summarize(entityType: string, options?: SummarizeOptions): Promise<SummarizeResult>;
+  /**
+   * Create one row and answer it.
+   *
+   * `project` is the create contract on a project-scoped type and the schema's
+   * `mandatory` flags are not it: the identity field is flagged mandatory, is
+   * optional, and is generated by the server when it is left out (012_create_version).
+   * An entity link is a `{type, id}` hash; a bare id 400s. Nothing is unique on any
+   * type measured, so two creates of the same body make two rows: key on `id`.
+   */
+  create(entityType: string, body: Record<string, unknown>): Promise<EntityRow>;
+  /**
+   * Put a file on a row, in the three calls the API takes.
+   *
+   * A ticket, a `PUT` of the bytes to presigned storage, and a completing `POST`.
+   * The 201 the third answers proves the handshake and not that bytes exist:
+   * skipping the second is undetectable, and the row it leaves reads the same
+   * (039_upload_silent_failures). A media field is not readable straight after: it
+   * returns a placeholder under `/images/status/transient/` until the transcode
+   * lands (recipes/001).
+   */
+  upload(entityType: string, id: number, file: UploadFile): Promise<UploadResult>;
+  /**
+   * A Note, its Attachments and its Replies as one list in time order.
+   *
+   * It replaces a `_search` on each of the three types and orders them together.
+   * `entityFields` widens a row type, one entry per type; it is accepted and
+   * changes nothing for Reply, whose extra fields need a `_search` on replies
+   * (get_entity_notes_id_thread_contents).
+   */
+  threadContents(noteId: number, entityFields?: Record<string, string[]>): Promise<ThreadRow[]>;
+  /**
+   * What changed, newest first.
+   *
+   * This is the change log, not the activity stream: a status change written over
+   * the API was on no stream 430s later (067_notes_in_the_stream). Rows are sorted
+   * `-id`; `id` and `created_at` are the two orders the type answers, and ids at the
+   * head are sparse and fill in later, so a cursor on `max(id)` drops events: re-scan
+   * behind the head or drive the feed from `created_at` and deduplicate on `id`
+   * (025_event_log).
+   */
+  eventLog(options?: EventLogOptions): Promise<EventLogResult>;
+  /**
+   * Everything one person follows, in one unpaged body.
+   *
+   * Each row is a type and an id: neither the record's name nor the date the
+   * follow started is returned, so a display list costs a `_search` on the ids.
+   * The user must be a HumanUser; a script cannot ask what it follows
+   * (get_entity_human_users_id_following).
+   */
+  following(userId: number, options?: FollowingOptions): Promise<EntityRef[]>;
+}
+/** The node shape `/hierarchy/_expand` answers, before normalising. */
+interface RawHierarchyNode {
+  label?: string;
+  ref?: {
+    kind?: string;
+    value?: unknown;
+  };
+  path?: string;
+  parent_path?: string | null;
+  has_children?: boolean;
+  children?: RawHierarchyNode[];
+}
+/**
+ * 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).
+ */
+declare function normalizeHierarchyNode(raw: RawHierarchyNode, path: string): HierarchyNode;
+interface RestClientOptions {
+  /** Site root, e.g. `https://studio.shotgrid.autodesk.com`. */
+  siteUrl: string;
+  /** Returns a bearer token. Called per request so callers can refresh. */
+  token: () => Promise<string> | string;
+  fetch?: typeof fetch;
+}
+declare class SgApiError extends Error {
+  status: number;
+  body: unknown;
+  constructor(status: number, body: unknown, message?: string);
+}
+declare class RestClient implements SgClient {
+  private readonly options;
+  private readonly base;
+  private readonly siteRoot;
+  private readonly fetchFn;
+  constructor(options: RestClientOptions);
+  private request;
+  entityTypes(): Promise<EntityTypeInfo[]>;
+  fields(entityType: string, projectId?: number): Promise<Record<string, FieldSchema>>;
+  fieldWithProject(entityType: string, field: string, projectId: number): Promise<FieldSchema>;
+  search(entityType: string, options: SearchOptions): Promise<SearchResult>;
+  textSearch(text: string, entityTypes: Record<string, TextSearchFilter>, page?: {
+    size?: number;
+    number?: number;
+  }): Promise<TextSearchRow[]>;
+  update(entityType: string, id: number, patch: Record<string, unknown>): Promise<EntityRow>;
+  create(entityType: string, body: Record<string, unknown>): Promise<EntityRow>;
+  upload(entityType: string, id: number, file: UploadFile): Promise<UploadResult>;
+  summarize(entityType: string, options?: SummarizeOptions): Promise<SummarizeResult>;
+  threadContents(noteId: number, entityFields?: Record<string, string[]>): Promise<ThreadRow[]>;
+  eventLog(options?: EventLogOptions): Promise<EventLogResult>;
+  following(userId: number, options?: FollowingOptions): Promise<EntityRef[]>;
+  hierarchyExpand(path: string): Promise<HierarchyNode>;
+  hierarchySearch(rootPath: string, entity: EntityRef): Promise<HierarchyPath[]>;
+  statuses(): Promise<StatusRecord[]>;
+}
+/** One `_search` row of `EventLogEntry`, with `meta` decoded as the API returns it. */
+declare function normalizeEventLogEntry(row: EntityRow): EventLogEntry;
+//#endregion
+export { STOCK_SPRITE_PATH as $, isOperator as $t, hierarchyEntity as A, emptyFilter as At, intersectStatuses as B, DataType as Bt, SummaryType as C, FilterNode as Ct, UploadFile as D, WireCondition as Dt, ThreadRow as E, TextSearchFilter as Et, StatusIcon as F, referencedPaths as Ft, statusLabel as G, TIME_UNITS as Gt, relativeLuminance as H, OPERATORS as Ht, StatusOption as I, toApi3Hash as It, NATIVE_STATUSES as J, ValueShape as Jt, statusPaint as K, TimeUnit as Kt, StatusPaint as L, toFilterArray as Lt, normalizeHierarchyNode as M, group as Mt, Rgb as N, isBlankCondition as Nt, UploadResult as O, WireGroup as Ot, StatusGlyph as P, isEmptyFilter as Pt, STOCK_ICON_KEYS as Q, isNumericType as Qt, StatusRecord as R, walk as Rt, SummaryGrouping as S, FilterGroup as St, ThreadAuthor as T, Scalar as Tt, rgbToCss as U, OPERATORS_BY_TYPE as Ut, parseBgColor as V, NEGATING_OPERATORS as Vt, statusGlyph as W, Operator as Wt, STOCK_ICON_CELLS as X, isFilterable as Xt, NativeStatus as Y, isDataType as Yt, STOCK_ICON_DATA_URLS as Z, isLinkType as Zt, SgClient as _, statusFieldNameFor as _t, EventLogOptions as a, stockIconSource as at, SummaryField as b, EntityRef as bt, HierarchyNode as c, FieldSchema as ct, RawHierarchyNode as d, RawProperty as dt, isTemporalType as en, SpriteCell as et, RestClient as f, displayNameOf as ft, SgApiError as g, statusFieldFor as gt, SearchResult as h, normalizeFields as ht, EventLogEntry as i, spriteStyle as it, normalizeEventLogEntry as j, fromWire as jt, eventLogFilters as k, condition as kt, HierarchyPath as l, RawFieldSchema as lt, SearchOptions as m, normalizeField as mt, EntityRow as n, supportsOperator as nn, isNativeStatus as nt, EventLogResult as o, DISPLAY_NAME_FIELDS as ot, RestClientOptions as p, fieldSchemaOverride as pt, usableStatuses as q, VALUE_SHAPE as qt, EntityTypeInfo as r, nativeStatus as rt, FollowingOptions as s, FIELD_SCHEMA_OVERRIDES as st, EVENT_LOG_FIELDS as t, operatorsFor as tn, StockIconSource as tt, HierarchyRef as u, RawFieldsResponse as ut, SummarizeOptions as v, undeclaredField as vt, TextSearchRow as w, LogicalOperator as wt, SummaryGroup as x, FilterCondition as xt, SummarizeResult as y, ConditionValue as yt, foregroundFor as z, DATA_TYPES as zt };