calmlens 0.20.0 → 0.21.0

data/sig/types.rbs

@@ -27,8 +27,10 @@ module CalmLens
 
   # ---- Assets (Asset.ts) ----------------------------------------------------------------------
 
-  # Where the asset is in the pipeline.
-  type asset_classification_status = "pending" | "processing" | "completed" | "failed"
+  # Where the asset is in the pipeline: `queued` while it waits for its content (a multipart upload
+  # still receiving parts) or its turn, `processing`, then `completed` or `failed`. The asset is
+  # settled once it is `completed` or `failed`.
+  type asset_classification_status = "queued" | "processing" | "completed" | "failed"
   # A moderation decision, which also decides delivery: served to anyone with access (`allowed`),
   # served like `allowed` but marked so your app reduces its reach (`limited`), only through signed
   # URLs or API keys (`age-restricted`), not served (`blocked`), or not served with the stored
@@ -41,7 +43,7 @@ module CalmLens
   type asset_content_status = "temporary" | "stored" | "removed"
   type asset_content_removal_reason = "policy" | "retention" | "requested" | "parent-removed" | "disposed"
   # Why processing failed, while the classification status is `failed`.
-  type asset_classification_failure_reason = "file-too-large" | "duration-limit" | "resolution-limit" | "unsupported-format" | "undecodable-content" | "multiple-tracks" | "type-mismatch" | "free-upload-limit" | "child-failed" | "processing-error"
+  type asset_classification_failure_reason = "file-too-large" | "duration-limit" | "resolution-limit" | "unsupported-format" | "undecodable-content" | "multiple-tracks" | "type-mismatch" | "free-uploads-exhausted" | "media-limit" | "uploads-paused" | "too-many-items" | "processing-error"
   type asset_type = "image" | "video" | "audio" | "plaintext-document" | "multimedia-document" | "website" | "file"
   type asset_visibility = "public" | "private"
   # FLAGGED_CONTENT_ACTION_SCHEMA in PolicyRule.ts.
@@ -66,7 +68,11 @@ module CalmLens
     ?ocr: { enabled: bool }?,
     ?person_detection: { enabled: bool }?,
     ?face_detection: { enabled: bool, ?age_estimation: bool }?,
-    ?link_detection: { enabled: bool }?
+    ?link_detection: { enabled: bool }?,
+    # Preview. Prepares an adaptive stream (HLS) of audio or video, served at the `hls` resource and
+    # played by the `embed` resource; needs `keep_content_after_processing`. Left out, the project's
+    # streaming setting decides.
+    ?streaming: { enabled: bool }?
   }
   type processing_options_input = {
     ?keep_content_after_processing: bool?,
@@ -76,20 +82,6 @@ module CalmLens
     ?features: processing_features_input?
   }
 
-  type processing_features = {
-    ?"ocr" => { "enabled" => bool }?,
-    ?"personDetection" => { "enabled" => bool }?,
-    ?"faceDetection" => { "enabled" => bool, ?"ageEstimation" => bool }?,
-    ?"linkDetection" => { "enabled" => bool }?,
-    ?"aiGeneratedDetection" => { "enabled" => bool }?
-  }
-  # The processing options an asset was uploaded with.
-  type processing_options = {
-    ?"keepContentAfterProcessing" => bool?,
-    ?"storeSensitiveMetadata" => bool?,
-    ?"features" => processing_features?
-  }
-
   type checksums = {
     ?"md5" => String?,
     ?"sha1" => String?,
@@ -97,20 +89,42 @@ module CalmLens
     ?"sha384" => String?,
     ?"sha512" => String?
   }
-  # The picture served at the rendered resource; it remains after the content is removed.
-  type asset_image = {
+  # One rendition of an adaptive stream: `video` for a picture size (video renditions carry no sound;
+  # they play with the `audio` rendition), or `audio`. `bandwidth` is the peak bit rate in bits per
+  # second, counting the audio a video rendition plays with; `codecs` are RFC 6381 names.
+  type asset_hls_rendition = {
+    "kind" => "video" | "audio",
+    "width" => Integer?,
+    "height" => Integer?,
+    "bandwidth" => Integer,
+    "codecs" => String
+  }
+  # Preview. The adaptive stream of audio or video: HLS with fragmented MP4 (CMAF) segments, served
+  # at the CDN's `hls` resource (`hls/index.m3u8`) and played by its `embed` resource. Renditions list
+  # video from the largest down, then audio.
+  type asset_hls = { "renditions" => Array[asset_hls_rendition] }
+  type asset_rendered_kind = "image" | "pdf" | "video" | "audio"
+  # The asset's one displayable file, as the CDN's `rendered` resource serves it: an image, a PDF, or
+  # browser-safe video or audio. `peaks` is an audio waveform's normalised peaks.
+  type asset_rendered = {
+    "kind" => asset_rendered_kind,
+    "format" => String,
+    "width" => Integer?,
+    "height" => Integer?,
+    ?"peaks" => Array[Float]
+  }
+  # The still image that stands for the asset, as the CDN's `preview` resource serves it; the
+  # `placeholder` resource is its ThumbHash as a small blurred PNG.
+  type asset_preview = {
     "width" => Integer?,
     "height" => Integer?,
     "thumbhash" => String?,
-    "averageColor" => String?,
-    "perceptualHash" => String?,
-    # How much detail `perceptualHash` captured, from 0 to 100; hashes below 50 match unrelated pictures.
-    "perceptualHashQuality" => Integer?
+    "averageColor" => String?
   }
   type safety_hold = { "placedAt" => Integer, "reason" => "suspected-illegal-content", ?"disposedAt" => Integer? }
   # `type: "string"` carries the text in `content`; `type: "document"` stores it under `id`.
   type extracted_text = { "type" => "string" | "document", ?"content" => String, ?"id" => String }
-  # Descriptive metadata embedded in an uploaded image. `capturedAt` is ISO 8601, with a UTC offset
+  # Descriptive metadata embedded in an uploaded file. `capturedAt` is ISO 8601, with a UTC offset
   # only when the file records one. `digitalSourceType` is the IPTC code the file declares, such as
   # `digitalCapture`. `containsLocation` says whether the uploaded file embedded GPS coordinates;
   # `creator` and `location` are sensitive and recorded only when `storeSensitiveMetadata` is on.
@@ -129,48 +143,76 @@ module CalmLens
   }
 
   type asset_upload = { "status" => "uploading" | "completed", "updatedAt" => Integer?, "partsReceived" => Integer? }
+  # How many sections of long audio or video are analysed so far.
+  type classification_progress = { "completedSections" => Integer, "totalSections" => Integer }
   type asset_classification = {
     "status" => asset_classification_status,
     # `null` unless `status` is `failed`.
     "failureReason" => asset_classification_failure_reason?,
     "updatedAt" => Integer?,
     "completedAt" => Integer?,
+    # While long audio or video is analysed in sections and `status` is `processing`: how many of its
+    # sections are done. `nil` otherwise.
+    "progress" => classification_progress?,
+    # Whether the results came from one of the project's test inputs rather than analysing the
+    # content. Never use test results, such as age ranges, for real decisions.
+    "testInput" => bool,
     "moderation" => asset_moderation,
-    ?"personDetection" => person_detection_result,
-    ?"faceDetection" => face_detection_result,
-    ?"linkDetection" => link_detection_result,
-    # Preview. Where the asset's links lead; present when the project's policy acts on links.
-    ?"linkSafety" => link_safety_result,
-    ?"aiGeneratedDetection" => ai_generated_detection_result,
-    # Where OCR found text, and personal information within it; redaction transforms blur these regions.
-    ?"textRegions" => Array[text_region],
-    ?"labels" => Array[classification_label]?
-  }
+    # OCR's result for an image processed with OCR turned on; `nil` when OCR didn't run.
+    "ocr" => ocr_result?,
+    # Link detection's result for an image; `nil` when it didn't run.
+    "linkDetection" => link_detection_result?,
+    # Preview. Person and face detection's results; `nil` when they didn't run.
+    ?"personDetection" => person_detection_result?,
+    ?"faceDetection" => face_detection_result?,
+    # Preview. Where the asset's links lead when the project's policy acts on links; otherwise `nil`.
+    ?"linkSafety" => link_safety_result?,
+    ?"aiGeneratedDetection" => ai_generated_detection_result?
+  }
+  # Who made a review: a person (`user`, also when an assistant's key acts for one) or an API key
+  # (`api-key`), with the user's or API key's ID, `nil` only when it was not recorded.
+  type review_actor = { "type" => "user" | "api-key", "id" => String? }
   type asset_review = {
     "id" => String,
     "decision" => asset_moderation_decision,
     "note" => String?,
-    ?"reviewerName" => String?,
-    ?"reviewerEmail" => String?,
+    "decidedBy" => review_actor,
     "reviewedAt" => Integer,
-    "appliedToAsset" => bool
-  }
-  type regional_decision = { "region" => String, "action" => String, "rule" => String, ?"category" => String }
-  type test_regional_action = { "region" => String, "action" => String }
+    # Whether the decision was applied to the asset; `false` for a review queue decision recorded
+    # without changing the asset's status.
+    "applied" => bool
+  }
+  # A stricter delivery decision in one region the project serves: the status in force there, the
+  # mandatory rule that sets it and the category whose findings it acted on, when it acts on one.
+  type regional_decision = {
+    "region" => String,
+    "status" => "limited" | "age-restricted" | "blocked" | "purged",
+    "rule" => String,
+    ?"category" => String
+  }
+  # What decided the automated status: the `policy`'s categories, the asset's `children`, a
+  # `hash-list` match, a `mandatory-rule` or `link-safety`.
+  type moderation_source = "policy" | "children" | "hash-list" | "mandatory-rule" | "link-safety"
+  # Every field but `status`, `manualReviews`, `flaggedCategories`, `regions` and `timeline` is `nil`
+  # until moderation decides.
   type asset_moderation = {
-    ?"testCategoryActions" => Hash[String, String],
-    ?"testRegionalActions" => Array[test_regional_action],
     "manualReviews" => Array[asset_review],
     "status" => asset_moderation_status,
-    ?"automatedAction" => flagged_content_action,
-    ?"source" => String, ?"rule" => String,
+    # The policy's original decision; a reviewer's decision can change `status` without changing it.
+    "automatedStatus" => asset_moderation_decision?,
+    "source" => moderation_source?,
+    # The mandatory rule that decided, when `source` is `mandatory-rule`; otherwise `nil`.
+    "rule" => String?,
     "flaggedCategories" => Array[String], "regions" => Array[regional_decision],
-    ?"explanationComplete" => bool,
-    ?"categories" => Hash[String, category_policy_score],
-    # Preview. What the policy's link-safety section made of the asset's links; absent when the
+    "explanationComplete" => bool?,
+    "categories" => Hash[String, category_policy_score]?,
+    # Preview. What the policy's link-safety section made of the asset's links; `nil` when the
     # policy doesn't act on links.
-    ?"linkSafety" => link_safety_decision,
-    ?"raw" => moderation_raw
+    ?"linkSafety" => link_safety_decision?,
+    # An audio or video asset's findings timeline: how many segments `assets.list_timeline` lists.
+    # `null` for other assets and media without findings.
+    "timeline" => moderation_timeline?,
+    "raw" => moderation_raw?
   }
   # ASSET_CONTENT_SCHEMA. `format` is the MIME type.
   type asset_content = {
@@ -182,11 +224,25 @@ module CalmLens
     "extension" => String?,
     "sizeInBytes" => Integer?,
     "checksums" => checksums?,
-    "image" => asset_image?,
+    # The file's own size, length and page count, where they apply; `null` when unknown.
+    "width" => Integer?,
+    "height" => Integer?,
+    "durationSeconds" => Float?,
+    "pageCount" => Integer?,
+    "perceptualHash" => String?,
+    # How much detail `perceptualHash` captured, from 0 to 100; hashes below 50 match unrelated pictures.
+    "perceptualHashQuality" => Integer?,
+    # Metadata embedded in the uploaded file; `null` when it declares none, once the content is
+    # removed and while the asset is held.
+    "metadata" => file_metadata?,
     "extractedText" => extracted_text?,
-    # Metadata embedded in an uploaded image; `null` when it declares none, for other asset types,
-    # once the content is removed and while the asset is held.
-    "fileMetadata" => file_metadata?
+    # `null` until processing makes it, for text, spreadsheets and other files, once the content is
+    # removed and while the asset is held.
+    "rendered" => asset_rendered?,
+    # Preview. The adaptive stream once streaming has prepared one for audio or video; `nil` for
+    # other assets, until then, once the content is removed and while the asset is held.
+    "hls" => asset_hls?,
+    "preview" => asset_preview?
   }
 
   type asset = {
@@ -202,13 +258,14 @@ module CalmLens
     ?"externalId" => String?,
     ?"externalUrl" => String?,
     "type" => asset_type,
-    ?"metadata" => Array[metadata_item]?,
+    # Empty when the asset has none.
+    "metadata" => Array[metadata_item],
     ?"authorId" => String?,
     # The earlier posts CalmLens used; null once the content is removed.
     ?"context" => moderation_context?,
-    ?"tags" => Array[String]?,
-    ?"processingOptions" => processing_options?,
-    ?"visibility" => asset_visibility?,
+    # Empty when the asset has none.
+    "tags" => Array[String],
+    "visibility" => asset_visibility,
     "upload" => asset_upload,
     "classification" => asset_classification,
     "content" => asset_content
@@ -234,14 +291,12 @@ module CalmLens
 
   # `status: "evaluated"` or `"partial"` carries `likelihood` and `score`; `"not-evaluated"`
   # carries `reason`.
-  type policy_condition_result = { "status" => "evaluated" | "not-evaluated", ?"score" => number, ?"reason" => not_evaluated_reason }
   type category_report = {
     "status" => "evaluated" | "partial" | "not-evaluated",
     ?"likelihood" => likelihood,
     ?"score" => number,
     ?"reason" => not_evaluated_reason,
-    ?"qualifiers" => qualifier_results,
-    ?"policyConditions" => Hash[String, policy_condition_result]
+    ?"qualifiers" => qualifier_results
   }
   type classification_categories = {
     "sexual" => category_report,
@@ -253,44 +308,27 @@ module CalmLens
     "personal-information" => category_report,
     "profanity" => category_report
   }
-  type classification_label = {
-    "description" => String,
-    "score" => number,
-    ?"topicalityScore" => number?,
-    "likelihood" => likelihood,
-    ?"knowledgeBaseId" => String?
-  }
   type media_segment = {
     "source" => "frame" | "speech" | "frame-text" | "clip",
     "startSeconds" => number,
     "endSeconds" => number,
     "categories" => classification_categories
   }
-  type media_report = {
-    "durationSeconds" => number,
-    ?"frameIntervalSeconds" => number,
-    "sampledFrames" => Integer,
-    "audioTranscribed" => bool,
-    "segments" => Array[media_segment]
-  }
 
   # Position and size as fractions of the image width and height, from 0 to 1.
   type bounding_box = { "left" => number, "top" => number, "width" => number, "height" => number }
   type age_range = { "low" => Integer, "high" => Integer }
   type detected_person = { "box" => bounding_box, "confidence" => number }
   type detected_face = { "box" => bounding_box, "confidence" => number, ?"ageRange" => age_range }
-  type processing_feature_stage = "beta" | "ga"
   # `status: "evaluated"` carries `people`; `"not-evaluated"` carries `reason`.
   type person_detection_result = {
     "status" => "evaluated" | "not-evaluated",
-    "stage" => processing_feature_stage,
     ?"people" => Array[detected_person],
     ?"reason" => not_evaluated_reason
   }
   # `status: "evaluated"` carries `faces`; `"not-evaluated"` carries `reason`.
   type face_detection_result = {
     "status" => "evaluated" | "not-evaluated",
-    "stage" => processing_feature_stage,
     ?"faces" => Array[detected_face],
     ?"reason" => not_evaluated_reason
   }
@@ -300,7 +338,6 @@ module CalmLens
   # `status: "evaluated"` carries `qrCodes` and `links`; `"not-evaluated"` carries `reason`.
   type link_detection_result = {
     "status" => "evaluated" | "not-evaluated",
-    "stage" => processing_feature_stage,
     ?"qrCodes" => Array[detected_qr_code],
     ?"links" => Array[detected_link],
     ?"reason" => not_evaluated_reason
@@ -338,7 +375,6 @@ module CalmLens
   # Preview. `status: "evaluated"` carries `links`; `"not-evaluated"` carries `reason`.
   type link_safety_result = {
     "status" => "evaluated" | "not-evaluated",
-    "stage" => processing_feature_stage,
     ?"links" => Array[checked_link],
     ?"reason" => not_evaluated_reason
   }
@@ -355,66 +391,71 @@ module CalmLens
     },
     ?"offPlatformLinks" => { "action" => "limit" | "age-restrict" | "block", "allowedDomains" => Array[String] }
   }
-  # Preview. The strongest action the asset's links take, the indexes into
-  # `classification.linkSafety.links` of the links that take it, and the settings in force.
+  # Preview. The strongest action the asset's links take, the checked links that take it, and the
+  # settings in force.
   type link_safety_decision = {
     "action" => link_safety_action,
-    "links" => Array[Integer],
+    "links" => Array[checked_link],
     "settings" => link_safety_settings
   }
   type provenance_signal = { "kind" => "c2pa" | "iptc-digital-source-type" | "generator-metadata", "value" => String }
   # `status: "evaluated"` carries `provenance` and `signals`; `"not-evaluated"` carries `reason`.
   type ai_generated_detection_result = {
     "status" => "evaluated" | "not-evaluated",
-    "stage" => processing_feature_stage,
     ?"provenance" => "ai-generated" | "ai-edited" | "unknown",
     ?"signals" => Array[provenance_signal],
     ?"reason" => not_evaluated_reason
   }
   # Where OCR found text in an image, and whether it is personal information.
   type text_region = { "box" => bounding_box, "personalInformation" => bool }
-  # Results of the features requested in `processingOptions.features`. OCR stores extracted text on the image
-  # asset instead of a result here.
-  type processing_feature_results = {
-    ?"personDetection" => person_detection_result,
-    ?"faceDetection" => face_detection_result,
-    ?"linkDetection" => link_detection_result,
-    ?"linkSafety" => link_safety_result,
-    ?"aiGeneratedDetection" => ai_generated_detection_result
+  # `status: "evaluated"` carries `textRegions`, where OCR found text (redaction transforms blur
+  # these regions); `"not-evaluated"` carries `reason`. The text itself is `content.extractedText`.
+  type ocr_result = {
+    "status" => "evaluated" | "not-evaluated",
+    ?"textRegions" => Array[text_region],
+    ?"reason" => not_evaluated_reason
   }
 
   # How strongly each assessed category meets the policy and what the policy does with it.
   type policy_rule_snapshot = {
     "when" => Array[String], "action" => flagged_content_action,
-    ?"name" => String, ?"match" => "all", ?"unless" => Array[String]
+    ?"name" => String, ?"unless" => Array[String]
   }
-  type category_policy_source = { "kind" => String, ?"index" => Integer, ?"indexes" => Array[Integer] }
+  # What decided a category's action: its `default` action, a policy score `below-threshold`, or the
+  # `allowance` or `restriction` rules listed by `indexes` (at least one, the decisive rule first).
+  type category_policy_source = { "kind" => "default" | "below-threshold" } |
+                                { "kind" => "allowance" | "restriction", "indexes" => Array[Integer] }
   type category_policy_settings_snapshot = {
-    "categoryAction" => flagged_content_action,
+    "action" => flagged_content_action,
     "allowances" => Array[policy_rule_snapshot], "restrictions" => Array[policy_rule_snapshot]
   }
   type category_policy_score = {
     "score" => number, "action" => flagged_content_action,
     ?"source" => category_policy_source, ?"settings" => category_policy_settings_snapshot
   }
+  type moderation_timeline = { "segmentCount" => Integer }
   type moderation_raw = {
     "categories" => classification_categories,
-    ?"timeline" => media_report,
-    ?"hashMatches" => Array[hash_match]
+    # Empty when the image matched no hash list entry.
+    "hashMatches" => Array[hash_match]
   }
 
   # ---- Pages and search (Page.ts, AssetSearch.ts) --------------------------------------------
 
-  type order_direction = "asc" | "desc"
-  type order_input = { field: String, direction: order_direction }
-  type order = { "field" => String, "direction" => order_direction }
+  # A list's sort: comma-separated fields, each ascending unless prefixed with `-`, such as
+  # `-createdAt,id`.
+  type sort = String
 
   type asset_page = {
     "items" => Array[asset],
     "hasMore" => bool,
-    "nextCursor" => String?,
-    "pageSize" => Integer,
-    "ordering" => Array[order]
+    "nextCursor" => String?
+  }
+  # One page of an audio or video asset's findings timeline, in time order.
+  type asset_timeline_page = {
+    "items" => Array[media_segment],
+    "hasMore" => bool,
+    "nextCursor" => String?
   }
 
   type asset_search_mode = "keyword" | "semantic" | "hybrid"
@@ -428,8 +469,32 @@ module CalmLens
   }
 
   type asset_batch_operation = "delete" | "remove-content"
-  type batch_assets_response = { "queued" => bool }
-  type signed_url = { "url" => String, "expiresAt" => Integer }
+  # `batchId` is named by the `batch-id` fact of the events the batch causes.
+  type batch_assets_response = { "batchId" => String, "status" => "queued", "assetCount" => Integer }
+  # A signed asset URL, with any resource, selector and viewer claims appended, and when it expires
+  # (milliseconds since the Unix epoch).
+  type signed_asset_url = { "url" => String, "expiresAt" => Integer }
+  # Whether the viewer an asset URL's claims describe can see the content now.
+  type asset_availability = "available" | "age-restricted" | "unavailable"
+  # ASSET_INFO_SCHEMA: what the CDN's `info` resource returns, an allowlist of the asset's public
+  # fields plus the viewer's `availability`.
+  type asset_info = {
+    "id" => String,
+    "projectId" => String,
+    "type" => asset_type,
+    "externalUrl" => String?,
+    "content" => {
+      "format" => String?,
+      "width" => Integer?,
+      "height" => Integer?,
+      "durationSeconds" => Float?,
+      "pageCount" => Integer?,
+      "rendered" => asset_rendered?,
+      "preview" => asset_preview?,
+      "hls" => asset_hls?
+    },
+    "availability" => asset_availability
+  }
 
   # ---- Transforms and lenses (AssetTransform.ts, Lens.ts) -------------------------------------
 
@@ -544,20 +609,18 @@ module CalmLens
   type transform_input = String | image_transform_options_input
 
   type lens_type = "image" | "video" | "audio" | "document" | "website"
-  # ENSURE_LENS_BODY_SCHEMA. Changing a saved lens needs a greater `version` (default 1).
+  # ENSURE_LENS_BODY_SCHEMA: a lens definition, which the CDN serves once it is saved.
   type lens_definition = {
     identifier: String,
     name: String,
     type: lens_type,
     active: bool,
     ?description: String?,
-    ?version: Integer,
     ?transform: image_transform_options_input?
   }
   type lens = {
     "id" => String,
     ?"projectId" => String?,
-    "version" => Integer,
     "identifier" => String,
     "name" => String,
     ?"description" => String?,
@@ -567,6 +630,11 @@ module CalmLens
     "createdAt" => Integer,
     ?"updatedAt" => Integer
   }
+  type lens_page = {
+    "items" => Array[lens],
+    "hasMore" => bool,
+    "nextCursor" => String?
+  }
 
   # ---- Folders (Folder.ts) --------------------------------------------------------------------
 
@@ -597,8 +665,8 @@ module CalmLens
   # picture); `action` is `block` when the match was close enough for a block list to block.
   type hash_match = {
     "source" => "hash-list",
-    "listId" => String,
-    "entryId" => String,
+    "hashListId" => String,
+    "hashListEntryId" => String,
     "distance" => Integer,
     "action" => hash_list_action
   }
@@ -610,73 +678,85 @@ module CalmLens
     "hash" => String,
     "quality" => number?,
     ?"label" => String?,
-    ?"sourceAssetId" => String?,
+    # The asset the hash was taken from, when the entry was added from an asset.
+    ?"assetId" => String?,
     "createdAt" => Integer
   }
 
   type hash_list_entry_page = {
     "items" => Array[hash_list_entry],
     "hasMore" => bool,
-    "nextCursor" => String?,
-    "pageSize" => Integer,
-    "ordering" => Array[order]
+    "nextCursor" => String?
   }
 
   # ---- Policies (Policy.ts) ---------------------------------------------------------------------
 
   type policy_preset_id = "general-community" | "children-platform" | "education-support" | "wholesome-community"
-  # What a policy does with one category: `action` when its policy score reaches 0.5 (default
-  # `block`), allowances that let covered content through or act on it more softly, and
-  # restrictions, which outweigh allowances.
+  # What a policy does with one category: `action` when its policy score reaches 0.5, allowances
+  # that let covered content through or act on it more softly, and restrictions, which outweigh
+  # allowances.
   type category_policy_settings = {
-    ?"action" => flagged_content_action,
-    ?"allowances" => Array[policy_rule_snapshot],
-    ?"restrictions" => Array[policy_rule_snapshot]
+    "action" => flagged_content_action,
+    "allowances" => Array[policy_rule_snapshot],
+    "restrictions" => Array[policy_rule_snapshot]
   }
-  # Settings by category (`sexual`, `violence`, ...), and optionally link safety.
+  # Settings for every category, and optionally link safety.
   type policy_settings = {
-    "categorySettings" => Hash[String, category_policy_settings],
+    "categorySettings" => {
+      "sexual" => category_policy_settings,
+      "violence" => category_policy_settings,
+      "self-harm" => category_policy_settings,
+      "harassment" => category_policy_settings,
+      "hate" => category_policy_settings,
+      "criminal-activity" => category_policy_settings,
+      "personal-information" => category_policy_settings,
+      "profanity" => category_policy_settings
+    },
     ?"linkSafety" => link_safety_settings
   }
+  # How a policy relates to its preset: `live` follows the latest release (the organisation's own
+  # preset policy with automatic updates on), `pinned` is the organisation's own preset policy held
+  # at one release, and `copy` is a policy made from a preset.
+  type policy_preset_mode = "live" | "pinned" | "copy"
   # Where a policy started from a built-in preset. `version` is the release it is pinned to,
-  # `latestVersion` the newest; `own` is whether this is the organisation's own policy for the preset
-  # rather than a copy made from it. An organisation has at most one per preset, and only it can
-  # follow automatic updates.
+  # `latestVersion` the newest.
   type policy_preset_origin = {
     "id" => policy_preset_id,
     "version" => Integer,
     "latestVersion" => Integer,
-    "own" => bool
+    "mode" => policy_preset_mode
   }
-  # A moderation policy. Policies belong to the project's organisation and its projects share them.
-  # Send `revision` with each change; a policy changed since is refused with `policy/revision-conflict`.
+  # A moderation policy. Policies belong to the organisation and its projects share them. Send
+  # `revision` with each change; a policy changed since is refused with `policy/revision-conflict`.
   type policy = {
     "id" => String,
     "name" => String,
     "description" => String,
     "settings" => policy_settings,
     "revision" => Integer,
-    "automaticUpdates" => bool,
     "preset" => policy_preset_origin?,
     "projectIds" => Array[String],
     "createdAt" => Integer,
     "updatedAt" => Integer
   }
-  # Every policy of the project's organisation, oldest first, and the one the project moderates with.
-  type policy_list = { "policies" => Array[policy], "projectPolicyId" => String }
+  # A page of the organisation's policies, oldest first unless `sort` says otherwise.
+  type policy_page = { "items" => Array[policy], "hasMore" => bool, "nextCursor" => String? }
 
   # ---- Events and webhooks (Event.ts, EventCatalog.ts, WebhookPayload.ts) ----------------------
 
   # EVENT_TYPES in EventCatalog.ts. Ignore types your code does not handle. Webhook, Slack and email
   # deliveries and the public events feed leave out facts that hold personal or account data.
-  type event_type = "asset.uploaded" | "asset.classified" | "asset.allowed" | "asset.limited" |
-                    "asset.age-restricted" | "asset.blocked" | "asset.purged" | "asset.failed" | "asset.deleted" | "asset.content-removed" | "asset.retried" |
-                    "asset.review-requested" | "asset.hash-matched" | "usage.limit-reached" | "usage.spend-limit-reached" |
+  type event_type = "asset.uploaded" | "asset.classified" | "asset.region-restricted" | "asset.allowed" | "asset.limited" |
+                    "asset.age-restricted" | "asset.blocked" | "asset.purged" | "asset.failed" | "asset.progress-updated" |
+                    "asset.deleted" | "asset.content-removed" | "asset.retried" | "asset.rerun-requested" | "asset.review-requested" |
+                    "asset.hash-matched" | "asset.link-flagged" | "usage.free-uploads-exhausted" | "usage.uploads-paused" |
                     "upload-preset.daily-limit-reached" | "project.member-joined" | "project.member-removed" |
-                    "project.member-role-changed" | "project.invitation-sent" | "api-key.created" |
-                    "api-key.revoked" | "connector.failing" | "appeal.submitted" | "appeal.resolved"
+                    "project.member-left" | "project.member-role-changed" | "project.invitation-sent" |
+                    "project.transferred" | "api-key.created" | "api-key.revoked" | "api-key.deleted" |
+                    "connector.disabled" | "appeal.submitted" | "appeal.resolved"
   type event_severity = "low" | "high"
-  # A registered fact's value: text, an enum value, a count, a list of enum values, or null.
+  # A registered fact's value: text, an enum value, a count or a time in milliseconds (such as
+  # `resumes-at`), a list of enum values (such as `flagged-categories`), or null.
   # Test sends carry `{ "key" => "test", "value" => true }`.
   type event_fact_value = String | Integer | bool | Array[String] | nil
   # A registered fact. `key` is a kebab-case key registered for the event's type, such as
@@ -690,18 +770,31 @@ module CalmLens
     ?"uploadPresetId" => String?,
     ?"externalId" => String?,
     "upload" => { "status" => "uploading" | "completed" },
-    "classification" => { "status" => asset_classification_status, "moderation" => { "status" => asset_moderation_status } },
+    # `testInput`: whether the results came from one of the project's test inputs rather than
+    # analysing the content. Never use test results, such as age ranges, for real decisions.
+    "classification" => { "status" => asset_classification_status, "testInput" => bool,
+                          "moderation" => { "status" => asset_moderation_status } },
     "content" => { "status" => asset_content_status }
   }
+  # Who caused an event: a `user` (a person in the portal, or an assistant acting for one), an
+  # `api-key`, `automated` moderation or CalmLens itself (`system`). `id` is the user's or API key's
+  # ID, nil for `automated` and `system` and when it was not recorded.
+  type actor_type = "user" | "api-key" | "automated" | "system"
+  type actor = { "type" => actor_type, "id" => String? }
+  type actor_input = { type: actor_type, id: String? }
+
   # An `events.list` item, and the body of its webhook delivery.
   type event = {
     "id" => String,
     "projectId" => String,
+    "actor" => actor,
     "type" => event_type,
     "severity" => event_severity,
     "title" => String,
     "description" => String?,
     "assetId" => String?,
+    # Increases with each event about the same asset; nil for events not about an asset.
+    "assetSequence" => Integer?,
     "asset" => event_asset?,
     "facts" => Array[event_fact],
     "createdAt" => Integer
@@ -726,23 +819,31 @@ module CalmLens
   type asset_search_options = {
     query: String,
     ?mode: asset_search_mode,
-    ?limit: Integer,
+    # How many results, 1 to 20 (default 10).
+    ?page_size: Integer,
     ?request_options: request_options
   }
   type list_assets_options = {
     ?cursor: String,
     ?page_size: Integer,
-    ?ordering: Array[order_input],
-    # An RSQL filter such as `classification.moderation.status==allowed`.
+    # `createdAt` and `id`; `-createdAt` by default.
+    ?sort: sort,
+    # An RSQL filter such as `classification.moderation.status==allowed`; `folderId==fldr_…` lists
+    # one folder's assets.
     ?filter: String?,
-    ?folder_id: String?,
     ?request_options: request_options
   }
   type list_asset_children_options = {
     asset_id: String,
     ?cursor: String,
     ?page_size: Integer,
-    ?ordering: Array[order_input],
+    ?sort: sort,
+    ?request_options: request_options
+  }
+  type list_asset_timeline_options = {
+    asset_id: String,
+    ?cursor: String,
+    ?page_size: Integer,
     ?request_options: request_options
   }
   type update_asset_options = {
@@ -767,15 +868,21 @@ module CalmLens
     ?confirm_purge: bool,
     ?request_options: request_options
   }
-  type create_signed_url_options = {
-    ?viewer_claims: viewer_claims,
-    asset_id: String,
-    # Defaults to `rendered` on the server; `original` takes no lens or transform.
-    ?resource: "original" | "rendered",
-    ?expires_in_seconds: Integer,
-    # Transform options replace the lens's options of the same name.
+  # The resources beneath an asset URL ({CalmLens::CDN::RESOURCES}).
+  type cdn_resource = "original" | "rendered" | "preview" | "hls" | "embed" | "placeholder" | "info"
+  type sign_asset_url_options = {
+    # Exactly one of `asset_id` and `external_id`.
+    ?asset_id: String,
+    ?external_id: String,
+    ?project_id: String,
+    # Whole seconds from 1 to 86400; 900 by default.
+    ?expires_in: Integer,
+    # Whether the URL also serves `original`; false by default.
+    ?original: bool,
+    ?resource: cdn_resource,
     ?lens: String,
     ?transform: transform_input,
+    ?viewer_claims: viewer_claims,
     ?request_options: request_options
   }
 
@@ -802,6 +909,8 @@ module CalmLens
                           ?description: String?,
                           ?visibility: asset_visibility?,
                           ?metadata: Array[metadata_item_input]?,
+                          # Tags for the asset, such as `['catalogue', 'backpacks']`.
+                          ?tags: Array[String]?,
                           ?author_id: String,
                           ?context: moderation_context_input,
                           ?external_id: String?,
@@ -818,6 +927,8 @@ module CalmLens
                           ?description: String?,
                           ?visibility: asset_visibility?,
                           ?metadata: Array[metadata_item_input]?,
+                          # Tags for the asset, such as `['catalogue', 'backpacks']`.
+                          ?tags: Array[String]?,
                           ?author_id: String,
                           ?context: moderation_context_input,
                           ?external_id: String?,
@@ -833,6 +944,8 @@ module CalmLens
                           ?description: String?,
                           ?visibility: asset_visibility?,
                           ?metadata: Array[metadata_item_input]?,
+                          # Tags for the asset, such as `['catalogue', 'backpacks']`.
+                          ?tags: Array[String]?,
                           ?author_id: String,
                           ?context: moderation_context_input,
                           ?external_id: String?,
@@ -842,7 +955,8 @@ module CalmLens
                           ?processing_options: processing_options_input?,
                           ?request_options: request_options
                         }
-  type upload_part_options = { asset_id: String, part: upload_part, ?queue: bool, ?request_options: request_options }
+  # `wait` overrides whether the final part waits for the decision, chosen when the upload started.
+  type upload_part_options = { asset_id: String, part: upload_part, ?wait: bool, ?request_options: request_options }
 
   # Options of {Text#classify}: the text, with the shared asset fields. `name` defaults to `text`.
   type moderate_text_options = {
@@ -851,6 +965,7 @@ module CalmLens
     ?description: String?,
     ?visibility: asset_visibility?,
     ?metadata: Array[metadata_item_input]?,
+    ?tags: Array[String]?,
     ?author_id: String,
     ?context: moderation_context_input,
     ?external_id: String?,
@@ -865,19 +980,19 @@ module CalmLens
   type sign_upload_token_options = {
     upload_preset_id: String,
     ?external_id: String,
-    ?expires_in_seconds: Integer,
+    # Seconds the token can start an upload, 1 to 3600; 600 by default.
+    ?expires_in: Integer,
     ?request_options: request_options
   }
   type signed_upload_token = { "token" => String, "expiresAt" => Integer }
 
-  type folder_order_input = { field: "name" | "createdAt", direction: order_direction }
   type list_folders_options = {
     ?parent_id: String,
     ?cursor: String,
     # 1 to 100, default 50.
     ?page_size: Integer,
-    # At most one entry; the default is `name` ascending.
-    ?ordering: Array[folder_order_input],
+    # `name` (the default) or `createdAt`, descending when prefixed with `-`.
+    ?sort: sort,
     ?search: String,
     ?request_options: request_options
   }
@@ -885,39 +1000,36 @@ module CalmLens
     "items" => Array[folder],
     "ancestors" => Array[folder],
     "hasMore" => bool,
-    "nextCursor" => String?,
-    "pageSize" => Integer,
-    "ordering" => Array[order]
+    "nextCursor" => String?
   }
   type folder_id_options = { folder_id: String, ?request_options: request_options }
   type create_folder_options = { name: String, ?parent_id: String?, ?request_options: request_options }
   type update_folder_options = { folder_id: String, ?name: String, ?request_options: request_options }
   type move_folder_options = { folder_id: String, parent_id: String?, ?request_options: request_options }
-  # 1 to 100 lists per page, default 50.
-  type list_hash_lists_options = { ?cursor: String, ?page_size: Integer, ?request_options: request_options }
+  # 1 to 100 lists per page, default 50; `sort` is `createdAt` and `id`, `-createdAt` by default.
+  type list_hash_lists_options = { ?cursor: String, ?page_size: Integer, ?sort: sort, ?request_options: request_options }
   type hash_list_page = {
     "items" => Array[hash_list],
     "hasMore" => bool,
-    "nextCursor" => String?,
-    "pageSize" => Integer,
-    "ordering" => Array[order]
+    "nextCursor" => String?
   }
   type hash_list_id_options = { hash_list_id: String, ?request_options: request_options }
   type create_hash_list_options = { name: String, action: hash_list_action, ?description: String?, ?request_options: request_options }
   type update_hash_list_options = { hash_list_id: String, ?name: String, ?description: String?, ?action: hash_list_action,
                                     ?request_options: request_options }
-  type list_hash_list_entries_options = { hash_list_id: String, ?cursor: String, ?page_size: Integer,
+  type list_hash_list_entries_options = { hash_list_id: String, ?cursor: String, ?page_size: Integer, ?sort: sort,
                                           ?request_options: request_options }
   type add_hash_list_entry_options = { hash_list_id: String, ?hash: String, ?quality: number, ?asset_id: String, ?label: String,
                                        ?request_options: request_options }
   type hash_list_entry_id_options = { entry_id: String, ?request_options: request_options }
 
   # Policy settings as options: snake_case Symbol keys, or a policy's `settings` as the API returned it.
-  type policy_rule_input = { when: Array[String], action: flagged_content_action, ?name: String, ?match: "all", ?unless: Array[String] }
+  type policy_rule_input = { when: Array[String], action: flagged_content_action, ?name: String, ?unless: Array[String] }
+  # Every category needs its `action`, `allowances` and `restrictions`.
   type category_policy_settings_input = {
-    ?action: flagged_content_action,
-    ?allowances: Array[policy_rule_input],
-    ?restrictions: Array[policy_rule_input]
+    action: flagged_content_action,
+    allowances: Array[policy_rule_input],
+    restrictions: Array[policy_rule_input]
   }
   type link_safety_settings_input = {
     verdict_actions: Hash[String | Symbol, link_safety_action],
@@ -927,7 +1039,9 @@ module CalmLens
     category_settings: Hash[String | Symbol, category_policy_settings_input],
     ?link_safety: link_safety_settings_input
   }
-  type list_policies_options = { ?request_options: request_options }
+  # `sort` is `createdAt` and `id`, `createdAt` (oldest first) by default.
+  type list_policies_options = { ?cursor: String, ?page_size: Integer, ?sort: sort, ?request_options: request_options }
+  type request_only_options = { ?request_options: request_options }
   type policy_id_options = { policy_id: String, ?request_options: request_options }
   # Send `settings` (defining every category) with a `name`, or `preset_id` to copy the latest
   # release of a built-in preset, named after it unless you give a `name`.
@@ -935,16 +1049,18 @@ module CalmLens
                                  ?preset_id: policy_preset_id, ?request_options: request_options }
   type update_policy_options = { policy_id: String, revision: Integer, ?name: String, ?description: String,
                                  ?settings: policy_settings_input, ?request_options: request_options }
-  # `reset` restores the pinned preset version (send `preset.version`); `update` moves an unchanged
-  # copy to the latest release (send `preset.latestVersion`).
-  type apply_policy_preset_options = { policy_id: String, operation: "reset" | "update", revision: Integer,
-                                       preset_version: Integer, ?request_options: request_options }
+  # `reset` restores the pinned release (send `preset.version`); `upgrade` moves an unchanged
+  # `pinned` or `copy` policy to the latest release (send `preset.latestVersion`).
+  type restore_policy_options = { policy_id: String, revision: Integer, preset_version: Integer,
+                                  ?request_options: request_options }
   type set_policy_automatic_updates_options = { policy_id: String, enabled: bool, revision: Integer,
                                                 preset_version: Integer, ?request_options: request_options }
   type assign_policy_options = { policy_id: String, ?request_options: request_options }
 
-  # `page_size` is 1 to 100, default 50.
-  type list_events_options = { ?cursor: String, ?page_size: Integer, ?request_options: request_options }
+  # `page_size` is 1 to 100, default 50. `types` and `asset_id` narrow the feed; a cursor belongs to
+  # the filters it was issued with.
+  type list_events_options = { ?cursor: String, ?page_size: Integer, ?types: Array[event_type], ?asset_id: String,
+                               ?request_options: request_options }
 
   type ensure_lenses_options = { lenses: Array[lens_definition], ?request_options: request_options }
   type ensure_lens_options = {
@@ -953,28 +1069,49 @@ module CalmLens
     type: lens_type,
     active: bool,
     ?description: String?,
-    ?version: Integer,
+    ?transform: image_transform_options_input?,
+    ?request_options: request_options
+  }
+  # `sort` is `createdAt` and `id`, `-createdAt` (newest first) by default.
+  type list_lenses_options = { ?cursor: String, ?page_size: Integer, ?sort: sort, ?request_options: request_options }
+  type lens_id_options = { lens_id: String, ?request_options: request_options }
+  # The identifier must be new to the project.
+  type create_lens_options = ensure_lens_options
+  type update_lens_options = {
+    lens_id: String,
+    ?name: String,
+    ?description: String?,
+    ?type: lens_type,
+    ?active: bool,
     ?transform: image_transform_options_input?,
     ?request_options: request_options
   }
 
   type asset_url_options = {
-    ?viewer_claims: viewer_claims,
-    # The asset ID or external ID.
-    asset_identifier: String,
-    # `rendered` is the default. `original` takes no lens or transform; `placeholder` is a small blurred PNG
-    # that takes no lens or transform.
-    ?resource: "original" | "rendered" | "placeholder",
-    # Transform options replace the lens's options of the same name.
+    # Exactly one of `asset_id` and `external_id`.
+    ?asset_id: String,
+    ?external_id: String,
+    # The client's project by default.
+    ?project_id: String,
+    # Without one, the URL is the asset URL itself. `original`, `hls` (the HLS master playlist),
+    # `embed` (the page that shows the asset), `placeholder` (a small blurred PNG) and `info` take no
+    # lens or transform; `preview` takes them, and `rendered` does when it is an image.
+    ?resource: cdn_resource,
+    # Transform options replace the lens's options of the same name; both need a resource.
     ?lens: String,
     ?transform: transform_input,
-    # Appends `?ageConfirmed=true`, so a public `age-restricted` asset is served from this URL. Set it
-    # only where your app has already decided the viewer may see age-restricted content.
+    # Unsigned viewer assertions, sent as the `viewerClaims` query without the defaults. Set
+    # `age_confirmed` only where your app has already decided the viewer may see age-restricted content.
+    ?viewer_claims: viewer_claims,
+    ?request_options: request_options
   }
   type serve_options = {
+    ?asset_id: String,
+    ?external_id: String,
+    ?project_id: String,
     ?viewer_claims: viewer_claims,
-    asset_identifier: String,
-    ?resource: "original" | "rendered" | "placeholder",
+    # `rendered` by default.
+    ?resource: cdn_resource,
     ?lens: String,
     ?transform: transform_input,
     ?init: { ?method: "GET" | "HEAD", ?headers: Hash[String, String] },
@@ -986,6 +1123,8 @@ module CalmLens
     type: event_type,
     ?id: String,
     ?project_id: String,
+    # The mock API key (`{ 'type' => 'api-key', 'id' => nil }`) when omitted.
+    ?actor: actor_input,
     ?severity: event_severity,
     ?title: String,
     ?description: String?,