calmlens 0.21.0 → 0.22.0

data/sig/calmlens.rbs

@@ -31,6 +31,7 @@ module CalmLens
                      ?headers: Hash[String, String], ?request_id: String?) -> void
     # Whole seconds from the `Retry-After` header.
     def retry_after: () -> Integer?
+    def local?: () -> bool
     def not_found?: () -> bool
     def retryable?: () -> bool
     def self.build: (String code, ?String? message, ?status: Integer?, ?details: Hash[String, json_value]?,
@@ -122,6 +123,9 @@ module CalmLens
     attr_reader events: Events
     attr_reader cdn: CDN
     attr_reader lenses: Lenses
+    attr_reader upload_presets: UploadPresets
+    attr_reader project_settings: ProjectSettings
+    attr_reader metadata_fields: MetadataFields
     attr_reader project_id: String
     attr_reader base_url: String
     attr_reader cdn_base_url: String
@@ -237,6 +241,25 @@ module CalmLens
     def delete: (lens_id_options options) -> nil
   end
 
+  class UploadPresets < Resource
+    def list: (?list_upload_presets_options options) -> upload_preset_page
+    def each: (?list_upload_presets_options options) { (upload_preset) -> void } -> nil
+            | (?list_upload_presets_options options) -> Enumerator[upload_preset, nil]
+    def ensure: (ensure_upload_presets_options options) -> ensure_upload_presets_response
+    def delete: (upload_preset_id_options options) -> nil
+  end
+
+  class ProjectSettings < Resource
+    def get: (?request_only_options options) -> project_settings_resource
+    def update: (update_project_settings_options options) -> project_settings_resource
+  end
+
+  class MetadataFields < Resource
+    def list: (?request_only_options options) -> metadata_fields_resource
+    def ensure: (ensure_metadata_fields_options options) -> metadata_fields_resource
+    def delete: (delete_metadata_field_options options) -> nil
+  end
+
   class UploadTokens < Resource
     TOKEN_PREFIX: String
     SIGNING_CONTEXT: String
@@ -379,6 +402,8 @@ module CalmLens
       # The HTTP status the mock answered with; nil when the request failed without a response.
       attr_accessor status: Integer?
       def json: () -> json_value
+      # An upload form's `options` (parsed) and `file` (its bytes); nil for any other body.
+      def form: () -> { 'options' => Hash[String, json_value], 'file' => String }?
     end
 
     interface _Clock

data/sig/error_codes.rbs

@@ -37,12 +37,14 @@ module CalmLens
     PERMISSION_DENIED: String
     UPLOAD_TOO_LARGE: String
     DOCUMENT_TOO_MANY_ITEMS: String
+    MEDIA_DURATION_LIMIT: String
     INVALID_IMAGE: String
     IMAGE_TOO_LARGE: String
     FREE_UPLOADS_EXHAUSTED: String
     UPLOADS_PAUSED: String
     UNSUPPORTED_UPLOAD_TYPE: String
     INVALID_UPLOAD_PAYLOAD: String
+    UPLOAD_OPTIONS_IN_QUERY: String
     USE_UPLOAD_PART: String
     UPLOAD_NOT_OPEN: String
     INVALID_UPLOAD_PART_NUMBER: String
@@ -99,6 +101,14 @@ module CalmLens
     UPLOAD_PRESET_DAILY_LIMIT_REACHED: String
     UPLOAD_PRESET_ORIGIN_NOT_ALLOWED: String
     UPLOAD_PRESET_FIELD_NOT_ALLOWED: String
+    UPLOAD_PRESET_REVISION_CONFLICT: String
+    UPLOAD_PRESET_KEY_TAKEN: String
+    UPLOAD_PRESET_DAILY_LIMIT_REQUIRED: String
+    UPLOAD_PRESET_INVALID_FOLDER: String
+    UPLOAD_PRESET_INVALID_POLICY: String
+    PROJECT_SETTINGS_REVISION_CONFLICT: String
+    SEARCH_ESTIMATE_CHANGED: String
+    METADATA_FIELD_NOT_FOUND: String
     UPLOAD_TOKEN_INVALID: String
     UPLOAD_TOKEN_EXPIRED: String
     UPLOAD_TOKEN_USED: String

data/sig/types.rbs

@@ -103,6 +103,7 @@ module CalmLens
   # 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_hls_status = { "status" => String, "reason" => String? }
   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.
@@ -193,13 +194,32 @@ module CalmLens
   # 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"
+  # The policy that made a decision: its ID, its revision then and, for a policy from a preset, the
+  # preset release it used.
+  type decision_policy = {
+    "id" => String,
+    "revision" => Integer,
+    "preset" => { "id" => String, "version" => Integer }?
+  }
+  # A review the human review queue is waiting for: when the asset joined it (Unix milliseconds),
+  # why, and the categories that made the decision uncertain.
+  type asset_pending_review = {
+    "requestedAt" => Integer,
+    "reason" => "sampled" | "uncertain",
+    "uncertainCategories" => Array[String]
+  }
   # Every field but `status`, `manualReviews`, `flaggedCategories`, `regions` and `timeline` is `nil`
-  # until moderation decides.
+  # until moderation decides; `pendingReview` is `nil` when no review is waiting.
   type asset_moderation = {
     "manualReviews" => Array[asset_review],
     "status" => asset_moderation_status,
     # The policy's original decision; a reviewer's decision can change `status` without changing it.
     "automatedStatus" => asset_moderation_decision?,
+    # The policy that made the automated decision, as it was then.
+    "policy" => decision_policy?,
+    # The review the human review queue is waiting for, set with the automated decision that
+    # joined the queue; `nil` when no review is waiting.
+    "pendingReview" => asset_pending_review?,
     "source" => moderation_source?,
     # The mandatory rule that decided, when `source` is `mandatory-rule`; otherwise `nil`.
     "rule" => String?,
@@ -242,6 +262,7 @@ module CalmLens
     # 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?,
+    "hlsStatus" => asset_hls_status?,
     "preview" => asset_preview?
   }
 
@@ -249,6 +270,8 @@ module CalmLens
     "id" => String,
     "projectId" => String,
     ?"parentId" => String?,
+    # The pages of the parent document a child shows, from 1; empty when unknown or not a child.
+    ?"parentPages" => Array[Integer],
     ?"folderId" => String?,
     ?"uploadPresetId" => String?,
     "createdAt" => Integer,
@@ -276,6 +299,9 @@ module CalmLens
   type likelihood = "very-unlikely" | "unlikely" | "possible" | "likely" | "very-likely"
   # not-supported: this processing path cannot assess the signal; unavailable: assessment failed.
   type not_evaluated_reason = "not-supported" | "unavailable"
+  # A processing feature's reason, which adds in-children: a document's or website's images are each
+  # a child asset with its own result (`assets.list_children`).
+  type feature_not_evaluated_reason = not_evaluated_reason | "in-children"
   type classification_category = "sexual" | "violence" | "self-harm" | "harassment" | "hate" | "criminal-activity"
 
   # `status: "evaluated"` carries `someScore`, `likelihood` and optionally `allScore`;
@@ -324,13 +350,13 @@ module CalmLens
   type person_detection_result = {
     "status" => "evaluated" | "not-evaluated",
     ?"people" => Array[detected_person],
-    ?"reason" => not_evaluated_reason
+    ?"reason" => feature_not_evaluated_reason
   }
   # `status: "evaluated"` carries `faces`; `"not-evaluated"` carries `reason`.
   type face_detection_result = {
     "status" => "evaluated" | "not-evaluated",
     ?"faces" => Array[detected_face],
-    ?"reason" => not_evaluated_reason
+    ?"reason" => feature_not_evaluated_reason
   }
   type detected_qr_code = { "value" => String, "box" => bounding_box }
   # A web link found in a QR code or in the text OCR extracted.
@@ -340,7 +366,7 @@ module CalmLens
     "status" => "evaluated" | "not-evaluated",
     ?"qrCodes" => Array[detected_qr_code],
     ?"links" => Array[detected_link],
-    ?"reason" => not_evaluated_reason
+    ?"reason" => feature_not_evaluated_reason
   }
   # Link safety (preview, LinkSafety.ts).
   # What a link's destination is: `safe` when every reputation check passed, `adult` or `gambling`
@@ -404,7 +430,7 @@ module CalmLens
     "status" => "evaluated" | "not-evaluated",
     ?"provenance" => "ai-generated" | "ai-edited" | "unknown",
     ?"signals" => Array[provenance_signal],
-    ?"reason" => not_evaluated_reason
+    ?"reason" => feature_not_evaluated_reason
   }
   # Where OCR found text in an image, and whether it is personal information.
   type text_region = { "box" => bounding_box, "personalInformation" => bool }
@@ -413,7 +439,7 @@ module CalmLens
   type ocr_result = {
     "status" => "evaluated" | "not-evaluated",
     ?"textRegions" => Array[text_region],
-    ?"reason" => not_evaluated_reason
+    ?"reason" => feature_not_evaluated_reason
   }
 
   # How strongly each assessed category meets the policy and what the policy does with it.
@@ -424,7 +450,7 @@ module CalmLens
   # 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] }
+                                { "kind" => "allowance" | "restriction", "indexes" => Array[Integer], "conditionScore" => Float }
   type category_policy_settings_snapshot = {
     "action" => flagged_content_action,
     "allowances" => Array[policy_rule_snapshot], "restrictions" => Array[policy_rule_snapshot]
@@ -636,6 +662,81 @@ module CalmLens
     "nextCursor" => String?
   }
 
+  # ---- Configuration as data (UploadPreset.ts, ProjectConfiguration.ts) --------------------------
+
+  type upload_preset_access = "token" | "anyone"
+  # An upload preset's processing options, as the API returns them.
+  type upload_preset_processing_options = {
+    ?"keepContentAfterProcessing" => bool?,
+    ?"storeSensitiveMetadata" => bool?,
+    ?"features" => {
+      ?"ocr" => { "enabled" => bool }?,
+      ?"personDetection" => { "enabled" => bool }?,
+      ?"faceDetection" => { "enabled" => bool, ?"ageEstimation" => bool? }?,
+      ?"linkDetection" => { "enabled" => bool }?,
+      ?"streaming" => { "enabled" => bool }?
+    }?
+  }
+  # The rules for uploads made from browsers and apps. `key` is unique in its project; `revision`
+  # counts changes, starting at 1. Send it back with a change.
+  type upload_preset = {
+    "id" => String,
+    "projectId" => String,
+    ?"createdByUserId" => String?,
+    "key" => String,
+    "revision" => Integer,
+    "name" => String,
+    "access" => upload_preset_access,
+    "enabled" => bool,
+    ?"allowedContentTypes" => Array[String]?,
+    ?"maxSizeInBytes" => Integer?,
+    ?"folderId" => String?,
+    ?"policyId" => String?,
+    "visibility" => asset_visibility,
+    ?"processingOptions" => upload_preset_processing_options?,
+    "revealDecision" => bool,
+    ?"dailyUploadLimit" => Integer?,
+    ?"allowedOrigins" => Array[String]?,
+    "createdAt" => Integer,
+    "updatedAt" => Integer
+  }
+  type upload_preset_page = { "items" => Array[upload_preset], "hasMore" => bool, "nextCursor" => String? }
+  type ensure_upload_presets_response = { "uploadPresets" => Array[upload_preset] }
+
+  type remote_url_rule = { "mode" => "allow" | "deny", "domains" => Array[String] }
+  type human_review_settings = {
+    "allowedSamplePercent" => number,
+    "restrictedSamplePercent" => number,
+    "uncertaintyMarginPercent" => number,
+    "reviewMissingEvidence" => bool
+  }
+  type public_project_settings = {
+    "optOutJurisdictions" => Array[String],
+    "blockUnmoderatedAssets" => bool,
+    "storeSensitiveMetadata" => bool,
+    "streamingEnabled" => bool,
+    "aiMediaSearchEnabled" => bool,
+    "remoteUrlRule" => remote_url_rule?,
+    "websiteSubmissionsPerMinute" => Integer?,
+    "humanReview" => human_review_settings
+  }
+  # The project's settings, with defaults filled in. `revision` counts changes to the settings and
+  # metadata fields, starting at 1. Send it back with a change.
+  type project_settings_resource = { "projectId" => String, "revision" => Integer, "settings" => public_project_settings }
+
+  type metadata_field_type = "string" | "number" | "boolean" | "date" | "url"
+  type metadata_field_icon = "tag" | "hash" | "user" | "folder" | "layers" | "photo" | "link"
+  # A metadata field the portal shows and filters by. `color` is `#rrggbb`.
+  type metadata_field = {
+    "id" => String,
+    "title" => String,
+    ?"description" => String,
+    "type" => metadata_field_type,
+    "icon" => metadata_field_icon,
+    "color" => String
+  }
+  type metadata_fields_resource = { "projectId" => String, "revision" => Integer, "fields" => Array[metadata_field] }
+
   # ---- Folders (Folder.ts) --------------------------------------------------------------------
 
   type folder = {
@@ -1087,6 +1188,64 @@ module CalmLens
     ?request_options: request_options
   }
 
+  # `sort` is `createdAt` and `id`, `createdAt` (oldest first) by default.
+  type list_upload_presets_options = { ?cursor: String, ?page_size: Integer, ?sort: sort, ?request_options: request_options }
+  # One preset's whole definition, by `key`; fields left out take their defaults. Send the `revision`
+  # you read (0 for a preset that must not exist yet) to refuse a change made since.
+  type upload_preset_definition = {
+    key: String,
+    name: String,
+    ?revision: Integer,
+    ?access: upload_preset_access,
+    ?enabled: bool,
+    ?allowed_content_types: Array[String]?,
+    ?max_size_in_bytes: Integer?,
+    ?folder_id: String?,
+    ?policy_id: String?,
+    ?visibility: asset_visibility,
+    ?processing_options: processing_options_input?,
+    ?reveal_decision: bool,
+    ?daily_upload_limit: Integer?,
+    ?allowed_origins: Array[String]?
+  }
+  type ensure_upload_presets_options = { upload_presets: Array[upload_preset_definition], ?request_options: request_options }
+  type upload_preset_id_options = { upload_preset_id: String, ?request_options: request_options }
+  # The complete settings: those left out return to their defaults.
+  type project_settings_input = {
+    ?opt_out_jurisdictions: Array[String],
+    ?block_unmoderated_assets: bool,
+    ?store_sensitive_metadata: bool,
+    ?streaming_enabled: bool,
+    ?ai_media_search_enabled: bool,
+    ?remote_url_rule: { mode: "allow" | "deny", domains: Array[String] }?,
+    ?website_submissions_per_minute: Integer?,
+    ?human_review: {
+      ?allowed_sample_percent: number,
+      ?restricted_sample_percent: number,
+      ?uncertainty_margin_percent: number,
+      ?review_missing_evidence: bool
+    }
+  }
+  # Send the `revision` you read to refuse settings changed since. `search_indexing_budget_units` is
+  # needed when turning on `ai_media_search_enabled`.
+  type update_project_settings_options = {
+    ?revision: Integer,
+    settings: project_settings_input,
+    ?search_indexing_budget_units: number,
+    ?request_options: request_options
+  }
+  type metadata_field_input = {
+    id: String,
+    title: String,
+    ?description: String,
+    type: metadata_field_type,
+    icon: metadata_field_icon,
+    color: String
+  }
+  # Fields to create or replace by ID; other fields are kept.
+  type ensure_metadata_fields_options = { ?revision: Integer, fields: Array[metadata_field_input], ?request_options: request_options }
+  type delete_metadata_field_options = { field_id: String, ?revision: Integer, ?request_options: request_options }
+
   type asset_url_options = {
     # Exactly one of `asset_id` and `external_id`.
     ?asset_id: String,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - CalmLens
@@ -32,6 +32,7 @@ files:
 - lib/calmlens/moderation_context.rb
 - lib/calmlens/option_keys.rb
 - lib/calmlens/policies.rb
+- lib/calmlens/project_configuration.rb
 - lib/calmlens/resource.rb
 - lib/calmlens/response.rb
 - lib/calmlens/server_client.rb