calmlens 0.18.2 → 0.19.0

data/sig/calmlens.rbs

@@ -109,10 +109,14 @@ module CalmLens
     RETRY_MAX_DELAY: Integer
     RETRY_AFTER_MAX: Integer
     DEFAULT_MAX_RESPONSE_BYTES: Integer
+    DEFAULT_PART_SIZE_BYTES: Integer
+    MIN_PART_SIZE_BYTES: Integer
+    MAX_PART_SIZE_BYTES: Integer
     ENSURE_LENSES_MAX_PER_REQUEST: Integer
     attr_reader assets: Assets
     attr_reader folders: Folders
     attr_reader hash_lists: HashLists
+    attr_reader policies: Policies
     attr_reader text: Text
     attr_reader upload_tokens: UploadTokens
     attr_reader events: Events
@@ -122,7 +126,7 @@ module CalmLens
     attr_reader cdn_base_url: String
     def initialize: (api_key: String, project_id: String, ?base_url: String, ?cdn_base_url: String, ?timeout: number,
                      ?open_timeout: number, ?upload_timeout: number?, ?max_retries: Integer, ?retry_base_delay: number,
-                     ?max_response_bytes: Integer, ?transport: Transport::_Transport?) -> void
+                     ?max_response_bytes: Integer, ?part_size_bytes: Integer, ?transport: Transport::_Transport?) -> void
     def close: () -> nil
     def ensure_lenses: (ensure_lenses_options options) -> Array[lens]
     def ensure_lens: (ensure_lens_options options) -> lens
@@ -200,6 +204,17 @@ module CalmLens
     def remove_entry: (hash_list_entry_id_options options) -> nil
   end
 
+  class Policies < Resource
+    def list: (?list_policies_options options) -> policy_list
+    def retrieve: (policy_id_options options) -> policy
+    def create: (create_policy_options options) -> policy
+    def update: (update_policy_options options) -> policy
+    def apply_preset: (apply_policy_preset_options options) -> policy
+    def set_automatic_updates: (set_policy_automatic_updates_options options) -> policy
+    def delete: (policy_id_options options) -> nil
+    def assign: (assign_policy_options options) -> policy
+  end
+
   class UploadTokens < Resource
     TOKEN_PREFIX: String
     SIGNING_CONTEXT: String
@@ -338,7 +353,7 @@ module CalmLens
     def initialize: (?project_id: String, ?api_key: String, ?base_url: String, ?cdn_base_url: String, ?now: _Clock, ?create_id: _IdFactory,
                      ?moderate: _Moderate?, ?timeout: number,
                      ?open_timeout: number, ?upload_timeout: number?, ?max_retries: Integer, ?retry_base_delay: number,
-                     ?max_response_bytes: Integer) -> void
+                     ?max_response_bytes: Integer, ?part_size_bytes: Integer) -> void
     # Replaces the mock API key's grants for later requests; the key stays the same.
     def api_key_grants=: (Array[Hash[Symbol | String, untyped]] grants) -> Array[Hash[Symbol | String, untyped]]
     # Fails the next request (or the next one `operation` sends) with `transport-error`, `timeout`, an
@@ -398,5 +413,45 @@ module CalmLens
   module MockClassification
     CATEGORIES: Array[String]
     QUALIFIERS: Hash[String, Array[String]]
+    # Qualifiers the input type sets, which a TestInputs scenario cannot list.
+    INPUT_QUALIFIERS: Array[String]
+  end
+
+  # Signed test inputs: text codes, test images and media phrases signed with a project's secret
+  # test input key from the portal.
+  module TestInputs
+    type action = "allow" | "limit" | "age-restrict" | "block"
+    type region = "DE" | "AT" | "FR" | "GB" | "EU" | "AU" | "BR"
+    type regional_action = { "region" => region, "action" => "limit" | "age-restrict" | "block" }
+    # One qualifying instance; set an action on every instance or on none.
+    type test_instance = { "category" => classification_category, ?"score" => number, ?"action" => action, "qualifiers" => Array[String] }
+    # A scenario with String keys; Symbol and snake_case keys are accepted as a plain Hash.
+    type scenario = { ?"regionalActions" => Array[regional_action], ?"unassessedCategories" => Array[classification_category],
+                      "instances" => Array[test_instance] }
+    type signal = classification_category | "sexual.involving-minors" | "harassment.insult" | "sexual.adult"
+                | "hate.regional-symbol" | "violence.graphic"
+    type media_signal = classification_category | "violence.graphic"
+    type input = scenario | Hash[String | Symbol, untyped] | signal
+
+    # A painted test image: width by height pixels of 8-bit RGBA in the binary String `rgba`, and
+    # the same image as binary PNG bytes in `png`.
+    class Image < Struct[untyped]
+      attr_accessor width: Integer
+      attr_accessor height: Integer
+      attr_accessor rgba: String
+      attr_accessor png: String
+      def initialize: (width: Integer, height: Integer, rgba: String, png: String) -> void
+    end
+
+    REGIONS: Array[region]
+    SIGNALS: Array[signal]
+    MEDIA_SIGNALS: Array[media_signal]
+    # clean, limited, adult_image, adult_text, regional_delivery, germany and mixed (deeply frozen).
+    PRESETS: Hash[Symbol, scenario]
+
+    def self.for_signal: (signal signal, ?("text" | "image") kind) -> scenario
+    def self.generate_text_code: (input input, String test_input_key) -> String
+    def self.paint_image: (input input, String test_input_key) -> Image
+    def self.generate_media_code: (media_signal signal, String test_input_key) -> String
   end
 end

data/sig/error_codes.rbs

@@ -7,6 +7,8 @@ module CalmLens
     INVALID_VIEWER_REGION: String
     VIEWER_REGION_REQUIRED: String
     REGIONAL_EVIDENCE_REQUIRED: String
+    SIGNED_URL_EXPIRED: String
+    SIGNED_URL_INVALID: String
     INVALID_TYPE: String
     TOO_SMALL: String
     TOO_BIG: String
@@ -34,9 +36,11 @@ module CalmLens
     API_KEY_NOT_ACCEPTED: String
     PERMISSION_DENIED: String
     FILE_TOO_LARGE: String
-    MULTIPART_IMAGE_TOO_SMALL: String
     MULTIPART_IMAGE_TOO_LARGE: String
     IMAGE_EXCEEDED_MAX_DIMENSIONS: String
+    IMAGE_INVALID_INPUT: String
+    IMAGE_UNSUPPORTED_FORMAT: String
+    IMAGE_INPUT_LIMIT: String
     UPLOAD_LIMIT_EXCEEDED: String
     SPEND_LIMIT_REACHED: String
     INVALID_UPLOAD_MIME_TYPE: String
@@ -77,6 +81,15 @@ module CalmLens
     HASH_LIST_LIMIT_REACHED: String
     HASH_LIST_ENTRY_LIMIT_REACHED: String
     HASH_LIST_ASSET_NOT_HASHED: String
+    POLICY_NOT_FOUND: String
+    POLICY_REVISION_CONFLICT: String
+    POLICY_PROJECTS_CHANGED: String
+    POLICY_IN_USE: String
+    POLICY_USED_BY_ANOTHER_PROJECT: String
+    POLICY_NO_PRESET: String
+    POLICY_PRESET_VERSION_CONFLICT: String
+    POLICY_PRESET_UPDATE_UNAVAILABLE: String
+    POLICY_AUTOMATIC_UPDATES_UNAVAILABLE: String
     UPLOAD_PRESET_NOT_FOUND: String
     UPLOAD_PRESET_DISABLED: String
     UPLOAD_PRESET_TOKEN_REQUIRED: String

data/sig/types.rbs

@@ -60,8 +60,8 @@ module CalmLens
   # Earlier posts to send, oldest first; only the posts CalmLens uses are sent.
   type moderation_context_input = { items: Array[moderation_context_item_input] }
 
-  # ProcessingFeatures.ts: optional analyses to run, keyed by feature. Every feature is off unless
-  # `enabled` is true.
+  # ProcessingFeatures.ts: optional analyses to run, keyed by feature. Link detection runs unless
+  # `enabled` is false; every other feature is off unless `enabled` is true.
   type processing_features_input = {
     ?ocr: { enabled: bool }?,
     ?person_detection: { enabled: bool }?,
@@ -139,6 +139,8 @@ module CalmLens
     ?"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],
@@ -165,6 +167,9 @@ module CalmLens
     "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
+    # policy doesn't act on links.
+    ?"linkSafety" => link_safety_decision,
     ?"raw" => moderation_raw
   }
   # ASSET_CONTENT_SCHEMA. `format` is the MIME type.
@@ -300,6 +305,63 @@ module CalmLens
     ?"links" => Array[detected_link],
     ?"reason" => not_evaluated_reason
   }
+  # Link safety (preview, LinkSafety.ts).
+  # What a link's destination is: `safe` when every reputation check passed, `adult` or `gambling`
+  # from its domain's content categories, `phishing` or `malware` from a threat list or the domain's
+  # security risks, and `unresolved` when a short link or redirect chain could not be followed or a
+  # check failed. Every address on a link's way is checked, and the most severe verdict is the
+  # link's.
+  type link_safety_verdict = "safe" | "adult" | "gambling" | "phishing" | "malware" | "unresolved"
+  # The verdicts a policy can act on.
+  type flagged_link_verdict = "phishing" | "malware" | "adult" | "gambling" | "unresolved"
+  # What a link does to its asset, weakest first. Purging content over a link is never offered.
+  type link_safety_action = "allow" | "limit" | "age-restrict" | "block"
+  # One reputation check of a link, every address it redirects through and its destination: their
+  # domain categories, or a threat-list lookup of their URLs. `failed` makes the link `unresolved`;
+  # `labels` is what the check reported for any of the addresses.
+  type link_safety_evidence = {
+    "check" => "domain-categories" | "threat-lists",
+    "status" => "checked" | "failed",
+    "labels" => Array[String]
+  }
+  # A link in the asset and what its destination is. `finalUrl` is where it leads after `redirects`
+  # redirects, or `null` when a short link or redirect chain could not be
+  # followed.
+  type checked_link = {
+    "url" => String,
+    "finalUrl" => String?,
+    "redirects" => Integer,
+    "source" => "qr-code" | "text",
+    "verdict" => link_safety_verdict,
+    "evidence" => Array[link_safety_evidence]
+  }
+  # 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
+  }
+  # Preview. LINK_SAFETY_SETTINGS_SCHEMA: the action for an asset with a link of each verdict (a
+  # verdict left out is allowed), and optionally an action for every link whose destination is
+  # outside `allowedDomains` (bare lowercase domains, which also cover their subdomains).
+  type link_safety_settings = {
+    "verdictActions" => {
+      ?"phishing" => link_safety_action,
+      ?"malware" => link_safety_action,
+      ?"adult" => link_safety_action,
+      ?"gambling" => link_safety_action,
+      ?"unresolved" => link_safety_action
+    },
+    ?"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.
+  type link_safety_decision = {
+    "action" => link_safety_action,
+    "links" => Array[Integer],
+    "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 = {
@@ -317,6 +379,7 @@ module CalmLens
     ?"personDetection" => person_detection_result,
     ?"faceDetection" => face_detection_result,
     ?"linkDetection" => link_detection_result,
+    ?"linkSafety" => link_safety_result,
     ?"aiGeneratedDetection" => ai_generated_detection_result
   }
 
@@ -391,7 +454,8 @@ module CalmLens
     ?blur: number,
     ?redact: {
       ?text: bool,
-      ?personalInformation: bool
+      ?personalInformation: bool,
+      ?faces: bool
     },
     ?border: {
       ?color: String,
@@ -437,7 +501,8 @@ module CalmLens
     ?"blur" => number,
     ?"redact" => {
       ?"text" => bool,
-      ?"personalInformation" => bool
+      ?"personalInformation" => bool,
+      ?"faces" => bool
     },
     ?"border" => {
       ?"color" => String,
@@ -474,12 +539,9 @@ module CalmLens
   }
   # </generated: image-transform-options>
 
-  # One structured transform step. `imageTransform` is the only transform type.
-  type transform_step_input = { type: "imageTransform", ?options: image_transform_options_input }
-  type transform_step = { "type" => "imageTransform", ?"options" => image_transform_options }
-  # A selector String with one step per path segment, such as `fit=cover,width=1024/blur=12`, or
-  # structured steps, which the SDK serializes into a selector.
-  type transform_input = String | transform_step_input | Array[transform_step_input]
+  # Transform options applied in one pass: a selector String such as `width=1024,fit=cover`, or
+  # structured options, which the SDK serializes into a selector.
+  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).
@@ -490,7 +552,7 @@ module CalmLens
     active: bool,
     ?description: String?,
     ?version: Integer,
-    ?transforms: Array[transform_step_input]?
+    ?transform: image_transform_options_input?
   }
   type lens = {
     "id" => String,
@@ -501,7 +563,7 @@ module CalmLens
     ?"description" => String?,
     "type" => lens_type,
     "active" => bool,
-    ?"transforms" => Array[transform_step]?,
+    ?"transform" => image_transform_options?,
     "createdAt" => Integer,
     ?"updatedAt" => Integer
   }
@@ -560,6 +622,47 @@ module CalmLens
     "ordering" => Array[order]
   }
 
+  # ---- 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.
+  type category_policy_settings = {
+    ?"action" => flagged_content_action,
+    ?"allowances" => Array[policy_rule_snapshot],
+    ?"restrictions" => Array[policy_rule_snapshot]
+  }
+  # Settings by category (`sexual`, `violence`, ...), and optionally link safety.
+  type policy_settings = {
+    "categorySettings" => Hash[String, category_policy_settings],
+    ?"linkSafety" => link_safety_settings
+  }
+  # Where a policy started from a built-in preset. `version` is the release it is pinned to,
+  # `latestVersion` the newest; `projectId` is the project whose preset policy it is, or nil for a copy.
+  type policy_preset_origin = {
+    "id" => policy_preset_id,
+    "version" => Integer,
+    "latestVersion" => Integer,
+    "projectId" => String?
+  }
+  # 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`.
+  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 }
+
   # ---- 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
@@ -602,7 +705,14 @@ module CalmLens
     "createdAt" => Integer
   }
   # Unlike other lists, `nextCursor` is never nil: keep it to receive later events.
-  type events_page = { "items" => Array[event], "nextCursor" => String, "hasMore" => bool }
+  # `excludedTypes` are the event types the feed never includes, because the API key lacks the permission
+  # to see them.
+  type events_page = {
+    "items" => Array[event],
+    "nextCursor" => String,
+    "hasMore" => bool,
+    "excludedTypes" => Array[event_type]
+  }
 
   # ---- Method options -------------------------------------------------------------------------
 
@@ -661,7 +771,7 @@ module CalmLens
     # Defaults to `rendered` on the server; `original` takes no lens or transform.
     ?resource: "original" | "rendered",
     ?expires_in_seconds: Integer,
-    # A lens runs before any additional transforms.
+    # Transform options replace the lens's options of the same name.
     ?lens: String,
     ?transform: transform_input,
     ?request_options: request_options
@@ -800,6 +910,37 @@ module CalmLens
                                        ?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 category_policy_settings_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],
+    ?off_platform_links: { action: "limit" | "age-restrict" | "block", allowed_domains: Array[String] }
+  }
+  type policy_settings_input = policy_settings | {
+    category_settings: Hash[String | Symbol, category_policy_settings_input],
+    ?link_safety: link_safety_settings_input
+  }
+  type list_policies_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`.
+  type create_policy_options = { ?name: String, ?description: String, ?settings: policy_settings_input,
+                                 ?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 }
+  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 }
 
@@ -811,7 +952,7 @@ module CalmLens
     active: bool,
     ?description: String?,
     ?version: Integer,
-    ?transforms: Array[transform_step_input]?,
+    ?transform: image_transform_options_input?,
     ?request_options: request_options
   }
 
@@ -822,7 +963,7 @@ module CalmLens
     # `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",
-    # A lens runs before any additional transforms.
+    # Transform options replace the lens's options of the same name.
     ?lens: String,
     ?transform: transform_input,
     # Appends `?ageConfirmed=true`, so a public `age-restricted` asset is served from this URL. Set it

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calmlens
 version: !ruby/object:Gem::Version
-  version: 0.18.2
+  version: 0.19.0
 platform: ruby
 authors:
 - CalmLens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies: []
 description: 'Server-side client for the CalmLens API: moderation, uploads, events,
   webhooks and CDN delivery.'
@@ -30,6 +30,8 @@ files:
 - lib/calmlens/internal.rb
 - lib/calmlens/lenses.rb
 - lib/calmlens/moderation_context.rb
+- lib/calmlens/option_keys.rb
+- lib/calmlens/policies.rb
 - lib/calmlens/resource.rb
 - lib/calmlens/response.rb
 - lib/calmlens/server_client.rb
@@ -39,6 +41,9 @@ files:
 - lib/calmlens/testing/fake_api.rb
 - lib/calmlens/testing/mock_decision.rb
 - lib/calmlens/testing/placeholder.rb
+- lib/calmlens/testing/test_image_grid.rb
+- lib/calmlens/testing/test_input_scenario.rb
+- lib/calmlens/testing/test_inputs.rb
 - lib/calmlens/text.rb
 - lib/calmlens/transforms.rb
 - lib/calmlens/transport.rb