retab 0.1.3 → 0.1.4

data/lib/retab/splits/subdocument.rb

@@ -21,8 +21,8 @@ module Retab
       super()
       hash = self.class.normalize(json)
       @name = hash[:name]
-      @description = hash[:description]
-      @allow_multiple_instances = hash[:allow_multiple_instances]
+      @description = hash[:description].nil? ? "" : hash[:description]
+      @allow_multiple_instances = hash[:allow_multiple_instances].nil? ? false : hash[:allow_multiple_instances]
     end
   end
 end

data/lib/retab/types/trigger_info_type.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# This file is auto-generated by oagen. Do not edit.
+
+module Retab
+  module Types
+    class TriggerInfoType
+      MANUAL = "manual"
+      API = "api"
+      SCHEDULE = "schedule"
+      WEBHOOK = "webhook"
+      EMAIL = "email"
+      CUSTOM = "custom"
+      RESTART = "restart"
+      ALL = [MANUAL, API, SCHEDULE, WEBHOOK, EMAIL, CUSTOM, RESTART].freeze
+    end
+  end
+end

data/lib/retab/types/{workflow_export_payload_request_trigger_types.rb → workflow_export_payload_request_trigger_type.rb}

@@ -4,7 +4,7 @@
 
 module Retab
   module Types
-    class WorkflowExportPayloadRequestTriggerTypes
+    class WorkflowExportPayloadRequestTriggerType
       MANUAL = "manual"
       API = "api"
       SCHEDULE = "schedule"

data/lib/retab/types/workflow_runs_trigger_type.rb

@@ -4,6 +4,6 @@
 
 module Retab
   module Types
-    WorkflowRunsTriggerType = WorkflowExportPayloadRequestTriggerTypes
+    WorkflowRunsTriggerType = WorkflowExportPayloadRequestTriggerType
   end
 end

data/lib/retab/workflow_artifacts/api_call_invocation.rb

@@ -8,7 +8,7 @@ module Retab
     HASH_ATTRS = {
       operation: :operation,
       id: :id,
-      workflow_run_id: :workflow_run_id,
+      run_id: :run_id,
       step_id: :step_id,
       attempts: :attempts,
       error: :error,
@@ -18,7 +18,7 @@ module Retab
     attr_accessor(
       :operation,
       :id,
-      :workflow_run_id,
+      :run_id,
       :step_id,
       :attempts,
       :error,
@@ -28,9 +28,9 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "api_call_invocation" : hash[:operation]
       @id = hash[:id]
-      @workflow_run_id = hash[:workflow_run_id]
+      @run_id = hash[:run_id]
       @step_id = hash[:step_id]
       @attempts = (hash[:attempts] || []).map { |item| item ? Retab::ApiCallAttempt.new(item) : nil }
       @error = hash[:error] ? Retab::ErrorDetails.new(hash[:error]) : nil

data/lib/retab/workflow_artifacts/classification_workflow_artifact.rb

@@ -46,7 +46,7 @@ module Retab
       @consensus = hash[:consensus] ? Retab::ClassificationConsensus.new(hash[:consensus]) : nil
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "classification" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/condition_evaluation_details.rb

@@ -11,7 +11,7 @@ module Retab
       expected: :expected,
       actual: :actual,
       matched: :matched,
-      per_item: :per_item,
+      items: :items,
       sub_conditions: :sub_conditions,
       logical_operator: :logical_operator
     }.freeze
@@ -22,7 +22,7 @@ module Retab
       :expected,
       :actual,
       :matched,
-      :per_item,
+      :items,
       :sub_conditions,
       :logical_operator
     )
@@ -30,12 +30,12 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @path = hash[:path]
-      @operator = hash[:operator]
+      @path = hash[:path].nil? ? "" : hash[:path]
+      @operator = hash[:operator].nil? ? "" : hash[:operator]
       @expected = hash[:expected]
       @actual = hash[:actual]
-      @matched = hash[:matched]
-      @per_item = (hash[:per_item] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
+      @matched = hash[:matched].nil? ? false : hash[:matched]
+      @items = (hash[:items] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
       @sub_conditions = (hash[:sub_conditions] || []).map { |item|
         item ? Retab::ConditionEvaluationSubCondition.new(item) : nil
       }

data/lib/retab/workflow_artifacts/condition_evaluation_per_item.rb

@@ -25,7 +25,7 @@ module Retab
       @index = hash[:index]
       @indices = (hash[:indices] || [])
       @actual = hash[:actual]
-      @matched = hash[:matched]
+      @matched = hash[:matched].nil? ? false : hash[:matched]
     end
   end
 end

data/lib/retab/workflow_artifacts/condition_evaluation_result.rb

@@ -14,7 +14,7 @@ module Retab
       matched: :matched,
       branch_name: :branch_name,
       logical_operator: :logical_operator,
-      per_item: :per_item,
+      items: :items,
       sub_evaluations: :sub_evaluations,
       details: :details
     }.freeze
@@ -28,7 +28,7 @@ module Retab
       :matched,
       :branch_name,
       :logical_operator,
-      :per_item,
+      :items,
       :sub_evaluations,
       :details
     )
@@ -37,14 +37,14 @@ module Retab
       super()
       hash = self.class.normalize(json)
       @condition_id = hash[:condition_id]
-      @path = hash[:path]
-      @operator = hash[:operator]
+      @path = hash[:path].nil? ? "" : hash[:path]
+      @operator = hash[:operator].nil? ? "" : hash[:operator]
       @expected = hash[:expected]
       @actual = hash[:actual]
-      @matched = hash[:matched]
-      @branch_name = hash[:branch_name]
+      @matched = hash[:matched].nil? ? false : hash[:matched]
+      @branch_name = hash[:branch_name].nil? ? "exit" : hash[:branch_name]
       @logical_operator = hash[:logical_operator]
-      @per_item = (hash[:per_item] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
+      @items = (hash[:items] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
       @sub_evaluations = (hash[:sub_evaluations] || []).map { |item|
         item ? Retab::ConditionEvaluationSubCondition.new(item) : nil
       }

data/lib/retab/workflow_artifacts/condition_evaluation_sub_condition.rb

@@ -12,7 +12,7 @@ module Retab
       expected: :expected,
       actual: :actual,
       matched: :matched,
-      per_item: :per_item
+      items: :items
     }.freeze
 
     attr_accessor(
@@ -22,19 +22,19 @@ module Retab
       :expected,
       :actual,
       :matched,
-      :per_item
+      :items
     )
 
     def initialize(json)
       super()
       hash = self.class.normalize(json)
       @sub_condition_id = hash[:sub_condition_id]
-      @path = hash[:path]
-      @operator = hash[:operator]
+      @path = hash[:path].nil? ? "" : hash[:path]
+      @operator = hash[:operator].nil? ? "" : hash[:operator]
       @expected = hash[:expected]
       @actual = hash[:actual]
-      @matched = hash[:matched]
-      @per_item = (hash[:per_item] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
+      @matched = hash[:matched].nil? ? false : hash[:matched]
+      @items = (hash[:items] || []).map { |item| item ? Retab::ConditionEvaluationPerItem.new(item) : nil }
     end
   end
 end

data/lib/retab/workflow_artifacts/conditional_evaluation.rb

@@ -8,7 +8,7 @@ module Retab
     HASH_ATTRS = {
       operation: :operation,
       id: :id,
-      workflow_run_id: :workflow_run_id,
+      run_id: :run_id,
       step_id: :step_id,
       evaluations: :evaluations,
       selected_handles: :selected_handles,
@@ -20,7 +20,7 @@ module Retab
     attr_accessor(
       :operation,
       :id,
-      :workflow_run_id,
+      :run_id,
       :step_id,
       :evaluations,
       :selected_handles,
@@ -32,9 +32,9 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "conditional_evaluation" : hash[:operation]
       @id = hash[:id]
-      @workflow_run_id = hash[:workflow_run_id]
+      @run_id = hash[:run_id]
       @step_id = hash[:step_id]
       @evaluations = (hash[:evaluations] || []).map { |item| item ? Retab::ConditionEvaluationResult.new(item) : nil }
       @selected_handles = (hash[:selected_handles] || [])

data/lib/retab/workflow_artifacts/edit_workflow_artifact.rb

@@ -46,7 +46,7 @@ module Retab
       @filled_document_ref = hash[:filled_document_ref] ? Retab::FileRef.new(hash[:filled_document_ref]) : nil
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "edit" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/extraction_workflow_artifact.rb

@@ -52,7 +52,7 @@ module Retab
       @metadata = hash[:metadata] || {}
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "extraction" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/function_invocation.rb

@@ -8,7 +8,7 @@ module Retab
     HASH_ATTRS = {
       operation: :operation,
       id: :id,
-      workflow_run_id: :workflow_run_id,
+      run_id: :run_id,
       step_id: :step_id,
       inputs: :inputs,
       output: :output,
@@ -20,7 +20,7 @@ module Retab
     attr_accessor(
       :operation,
       :id,
-      :workflow_run_id,
+      :run_id,
       :step_id,
       :inputs,
       :output,
@@ -32,9 +32,9 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "function_invocation" : hash[:operation]
       @id = hash[:id]
-      @workflow_run_id = hash[:workflow_run_id]
+      @run_id = hash[:run_id]
       @step_id = hash[:step_id]
       @inputs = hash[:inputs] || {}
       @output = hash[:output]

data/lib/retab/workflow_artifacts/parse_workflow_artifact.rb

@@ -43,7 +43,7 @@ module Retab
       @output = hash[:output] ? Retab::ParseOutput.new(hash[:output]) : nil
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "parse" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/partition_workflow_artifact.rb

@@ -44,12 +44,12 @@ module Retab
       @key = hash[:key]
       @instructions = hash[:instructions]
       @n_consensus = hash[:n_consensus]
-      @allow_overlap = hash[:allow_overlap]
+      @allow_overlap = hash[:allow_overlap].nil? ? true : hash[:allow_overlap]
       @output = (hash[:output] || []).map { |item| item ? Retab::PartitionChunk.new(item) : nil }
       @consensus = hash[:consensus] ? Retab::PartitionConsensus.new(hash[:consensus]) : nil
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "partition" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/review_evaluation.rb

@@ -8,7 +8,7 @@ module Retab
     HASH_ATTRS = {
       operation: :operation,
       id: :id,
-      workflow_run_id: :workflow_run_id,
+      run_id: :run_id,
       step_id: :step_id,
       evaluations: :evaluations,
       selected_handles: :selected_handles,
@@ -26,7 +26,7 @@ module Retab
     attr_accessor(
       :operation,
       :id,
-      :workflow_run_id,
+      :run_id,
       :step_id,
       :evaluations,
       :selected_handles,
@@ -44,19 +44,19 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "review_trigger_evaluation" : hash[:operation]
       @id = hash[:id]
-      @workflow_run_id = hash[:workflow_run_id]
+      @run_id = hash[:run_id]
       @step_id = hash[:step_id]
       @evaluations = (hash[:evaluations] || []).map { |item| item ? Retab::ConditionEvaluationResult.new(item) : nil }
       @selected_handles = (hash[:selected_handles] || [])
       @matched_branch_id = hash[:matched_branch_id]
       @matched_condition_ids = (hash[:matched_condition_ids] || [])
-      @requires_human_review = hash[:requires_human_review]
+      @requires_human_review = hash[:requires_human_review].nil? ? false : hash[:requires_human_review]
       @reviewer_id = hash[:reviewer_id]
       @review_decision = hash[:review_decision]
       @review_notes = hash[:review_notes]
-      @requested_revision = hash[:requested_revision]
+      @requested_revision = hash[:requested_revision].nil? ? false : hash[:requested_revision]
       @reviewed_at = hash[:reviewed_at]
       @created_at = hash[:created_at]
     end

data/lib/retab/workflow_artifacts/split_workflow_artifact.rb

@@ -46,7 +46,7 @@ module Retab
       @consensus = hash[:consensus] ? Retab::SplitConsensus.new(hash[:consensus]) : nil
       @usage = hash[:usage] ? Retab::RetabUsage.new(hash[:usage]) : nil
       @created_at = hash[:created_at]
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "split" : hash[:operation]
     end
   end
 end

data/lib/retab/workflow_artifacts/while_loop_termination.rb

@@ -8,7 +8,7 @@ module Retab
     HASH_ATTRS = {
       operation: :operation,
       id: :id,
-      workflow_run_id: :workflow_run_id,
+      run_id: :run_id,
       step_id: :step_id,
       termination_reason: :termination_reason,
       evaluations: :evaluations,
@@ -18,7 +18,7 @@ module Retab
     attr_accessor(
       :operation,
       :id,
-      :workflow_run_id,
+      :run_id,
       :step_id,
       :termination_reason,
       :evaluations,
@@ -28,9 +28,9 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @operation = hash[:operation]
+      @operation = hash[:operation].nil? ? "while_loop_termination" : hash[:operation]
       @id = hash[:id]
-      @workflow_run_id = hash[:workflow_run_id]
+      @run_id = hash[:run_id]
       @step_id = hash[:step_id]
       @termination_reason = hash[:termination_reason]
       @evaluations = (hash[:evaluations] || []).map { |item| item ? Retab::ConditionEvaluationResult.new(item) : nil }

data/lib/retab/workflow_artifacts.rb

@@ -10,31 +10,14 @@ module Retab
       @client = client
     end
 
-    # Get Workflow Artifact By Id
-    # @param artifact_id [String]
-    # @param request_options [Hash] (see Retab::Types::RequestOptions)
-    # @return [Retab::ExtractionWorkflowArtifact, Retab::SplitWorkflowArtifact, Retab::ClassificationWorkflowArtifact, Retab::ParseWorkflowArtifact, Retab::EditWorkflowArtifact, Retab::PartitionWorkflowArtifact, Retab::ConditionalEvaluation, Retab::ReviewEvaluation, Retab::WhileLoopTermination, Retab::ApiCallInvocation, Retab::FunctionInvocation]
-    def get(
-      artifact_id:,
-      request_options: {}
-    )
-      response = @client.request(
-        method: :get,
-        path: "/v1/workflows/artifacts/#{Retab::Util.encode_path(artifact_id)}",
-        auth: true,
-        request_options: request_options
-      )
-      JSON.parse(response.body)
-    end
-
     # List Workflow Artifacts
-    # @param run_id [String, nil] Workflow run ID whose artifacts should be listed. Required unless ``step_id`` is provided.
+    # @param run_id [String, nil] Workflow run ID whose artifacts should be listed. Required unless `step_id` is provided.
     # @param operation [Retab::Types::WorkflowArtifactsOperation, nil] Optional artifact operation filter
     # @param block_id [String, nil] Optional block_id or step_id filter
-    # @param step_id [String, nil] Optional step id filter. When provided, returns the single artifact attached to that step (or an empty list if the step has no artifact). ``run_id`` is not required when ``step_id`` is set — it is resolved from the step record.
-    # @param before [String, nil] Step id cursor: return the page before this step (mutually exclusive with ``after``). Ignored when ``step_id`` is set.
-    # @param after [String, nil] Step id cursor: return the page after this step (mutually exclusive with ``before``). Ignored when ``step_id`` is set.
-    # @param limit [Integer, nil] Maximum number of artifacts to return per page (1-200). Ignored when ``step_id`` is set (that path returns the single attached artifact).
+    # @param step_id [String, nil] Optional step id filter. When provided, returns the single artifact attached to that step (or an empty list if the step has no artifact). `run_id` is not required when `step_id` is set — it is resolved from the step record.
+    # @param before [String, nil] Step id cursor: return the page before this step (mutually exclusive with `after`). Ignored when `step_id` is set.
+    # @param after [String, nil] Step id cursor: return the page after this step (mutually exclusive with `before`). Ignored when `step_id` is set.
+    # @param limit [Integer, nil] Maximum number of artifacts to return per page (1-200). Ignored when `step_id` is set (that path returns the single attached artifact).
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [Retab::PaginatedList<Retab::WorkflowArtifact>]
     def list(
@@ -89,5 +72,22 @@ module Retab
         fetch_next: fetch_next
       )
     end
+
+    # Get Workflow Artifact By Id
+    # @param artifact_id [String]
+    # @param request_options [Hash] (see Retab::Types::RequestOptions)
+    # @return [Retab::ExtractionWorkflowArtifact, Retab::SplitWorkflowArtifact, Retab::ClassificationWorkflowArtifact, Retab::ParseWorkflowArtifact, Retab::EditWorkflowArtifact, Retab::PartitionWorkflowArtifact, Retab::ConditionalEvaluation, Retab::ReviewEvaluation, Retab::WhileLoopTermination, Retab::ApiCallInvocation, Retab::FunctionInvocation]
+    def get(
+      artifact_id:,
+      request_options: {}
+    )
+      response = @client.request(
+        method: :get,
+        path: "/v1/workflows/artifacts/#{Retab::Util.encode_path(artifact_id)}",
+        auth: true,
+        request_options: request_options
+      )
+      JSON.parse(response.body)
+    end
   end
 end

data/lib/retab/workflow_block_executions/completed_block_execution_lifecycle.rb

@@ -14,7 +14,7 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @status = hash[:status]
+      @status = hash[:status].nil? ? "completed" : hash[:status]
     end
   end
 end

data/lib/retab/workflow_block_executions/create_block_execution_request.rb

@@ -28,7 +28,7 @@ module Retab
       @block_id = hash[:block_id]
       @step_id = hash[:step_id]
       @n_consensus = hash[:n_consensus]
-      @check_eligibility = hash[:check_eligibility]
+      @check_eligibility = hash[:check_eligibility].nil? ? true : hash[:check_eligibility]
     end
   end
 end

data/lib/retab/workflow_block_executions/error_block_execution_lifecycle.rb

@@ -18,7 +18,7 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @status = hash[:status]
+      @status = hash[:status].nil? ? "error" : hash[:status]
       @message = hash[:message]
     end
   end

data/lib/retab/workflow_block_executions/skipped_block_execution_lifecycle.rb

@@ -18,7 +18,7 @@ module Retab
     def initialize(json)
       super()
       hash = self.class.normalize(json)
-      @status = hash[:status]
+      @status = hash[:status].nil? ? "skipped" : hash[:status]
       @reason = hash[:reason]
     end
   end

data/lib/retab/workflow_block_executions/stored_block_execution.rb

@@ -15,7 +15,7 @@ module Retab
       handle_inputs: :handle_inputs,
       artifact: :artifact,
       handle_outputs: :handle_outputs,
-      routing_decision: :routing_decision,
+      routing_decisions: :routing_decisions,
       duration_ms: :duration_ms,
       created_at: :created_at,
       block_config: :block_config,
@@ -33,7 +33,7 @@ module Retab
       :handle_inputs,
       :artifact,
       :handle_outputs,
-      :routing_decision,
+      :routing_decisions,
       :duration_ms,
       :created_at,
       :block_config,
@@ -64,7 +64,7 @@ module Retab
       @handle_inputs = hash[:handle_inputs] || {}
       @artifact = hash[:artifact] ? Retab::StepArtifactRef.new(hash[:artifact]) : nil
       @handle_outputs = hash[:handle_outputs] || {}
-      @routing_decision = (hash[:routing_decision] || [])
+      @routing_decisions = (hash[:routing_decisions] || [])
       @duration_ms = hash[:duration_ms]
       @created_at = hash[:created_at]
       @block_config = hash[:block_config] || {}

data/lib/retab/workflow_block_executions.rb

@@ -65,7 +65,7 @@ module Retab
     # Create Block Execution
     # @param run_id [String] Workflow run id that owns the step.
     # @param block_id [String] Workflow block id to execute.
-    # @param step_id [String, nil] Optional concrete step id whose inputs should be used. When omitted, the block id is used as the canonical step lookup key.
+    # @param step_id [String, nil] Optional concrete step id whose inputs should be used. When omitted, the block id is used to look up the step.
     # @param n_consensus [Integer, nil] Optional override for n_consensus on extract / split / classifier blocks. Must be 3, 5, or 7.
     # @param check_eligibility [Boolean, nil] Whether to verify the upstream subgraph hasn't drifted since the source run. Disable only for explicit force-rerun flows.
     # @param request_options [Hash] (see Retab::Types::RequestOptions)

data/lib/retab/workflow_blocks/workflow_block.rb

@@ -41,7 +41,7 @@ module Retab
       @id = hash[:id]
       @workflow_id = hash[:workflow_id]
       @type = hash[:type]
-      @label = hash[:label]
+      @label = hash[:label].nil? ? "" : hash[:label]
       @position_x = hash[:position_x]
       @position_y = hash[:position_y]
       @width = hash[:width]

data/lib/retab/workflow_blocks/workflow_block_create_request.rb

@@ -37,7 +37,7 @@ module Retab
       @workflow_id = hash[:workflow_id]
       @id = hash[:id]
       @type = hash[:type]
-      @label = hash[:label]
+      @label = hash[:label].nil? ? "" : hash[:label]
       @position_x = hash[:position_x]
       @position_y = hash[:position_y]
       @width = hash[:width]

data/lib/retab/workflow_blocks.rb

@@ -16,8 +16,8 @@ module Retab
 
     # List Blocks
     # @param workflow_id [String]
-    # @param before [String, nil] Block id cursor: return the page before this id (mutually exclusive with ``after``).
-    # @param after [String, nil] Block id cursor: return the page after this id (mutually exclusive with ``before``).
+    # @param before [String, nil] Block id cursor: return the page before this id (mutually exclusive with `after`).
+    # @param after [String, nil] Block id cursor: return the page after this id (mutually exclusive with `before`).
     # @param limit [Integer, nil] Maximum number of blocks to return per page (1-200).
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [Retab::PaginatedList<Retab::WorkflowBlock>]
@@ -60,7 +60,7 @@ module Retab
 
     # Create Block
     # @param workflow_id [String] Workflow to create the block in.
-    # @param id [String, nil] Opaque block ID. Omit to let the server generate one. Block IDs are unique per ORGANIZATION (not per workflow) — reusing a human-friendly id like 'block_extract' across multiple workflows in the same org will fail with 409. Prefer the server-generated ``blk_<nanoid>`` form for predictability.
+    # @param id [String, nil] Block ID. Omit to let the server generate one (recommended). Block IDs must be unique across your organization, not just within a workflow — reusing a custom id like 'block_extract' in more than one workflow fails with 409.
     # @param type [Retab::Types::WorkflowBlockCreateRequestType] Block type
     # @param label [String, nil] Display label
     # @param position_x [Float, nil] X position
@@ -114,7 +114,7 @@ module Retab
 
     # Get Block
     # @param block_id [String]
-    # @param workflow_id [String, nil] Optional disambiguator for legacy duplicate block IDs. Required only when the block id is not unique within the org — in that case the unqualified call returns 409 listing the colliding workflow_ids. Newly-created blocks use server-generated opaque IDs and never need this.
+    # @param workflow_id [String, nil] Disambiguates a block id that is shared by more than one workflow. Required only when the block id is not unique within your organization — otherwise the call returns 409 listing the colliding workflow_ids. Server-generated block IDs are always unique and never need this.
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [Retab::WorkflowBlock]
     def get(
@@ -150,8 +150,8 @@ module Retab
     # @param height [Float, nil]
     # @param config [Hash{String => Object}, nil]
     # @param parent_id [String, nil]
-    # @param config_mode [Retab::Types::UpdateWorkflowBlockRequestConfigMode, nil] How to apply the ``config`` field. 'merge' (default) deep-merges the patch into the existing config with null-as-delete; 'replace' uses the patch as the full new config. Not persisted.
-    # @param workflow_id [String, nil] Optional disambiguator for legacy duplicate block IDs. See ``GET /blocks/{block_id}`` for the full rationale.
+    # @param config_mode [Retab::Types::UpdateWorkflowBlockRequestConfigMode, nil] How to apply the `config` field. 'merge' (default) deep-merges the patch into the existing config with null-as-delete; 'replace' uses the patch as the full new config.
+    # @param workflow_id [String, nil] Disambiguates a block id that is shared by more than one workflow. Required only when the block id is not unique within your organization.
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [Retab::WorkflowBlock]
     def update(
@@ -199,7 +199,7 @@ module Retab
 
     # Delete Block
     # @param block_id [String]
-    # @param workflow_id [String, nil] Optional disambiguator for legacy duplicate block IDs. See ``GET /blocks/{block_id}`` for the full rationale.
+    # @param workflow_id [String, nil] Disambiguates a block id that is shared by more than one workflow. Required only when the block id is not unique within your organization.
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [void]
     def delete(

data/lib/retab/workflow_edges.rb

@@ -14,8 +14,8 @@ module Retab
     # @param workflow_id [String]
     # @param source_block [String, nil] Filter by source block ID
     # @param target_block [String, nil] Filter by target block ID
-    # @param before [String, nil] Edge id cursor: return the page before this id (mutually exclusive with ``after``).
-    # @param after [String, nil] Edge id cursor: return the page after this id (mutually exclusive with ``before``).
+    # @param before [String, nil] Edge id cursor: return the page before this id (mutually exclusive with `after`).
+    # @param after [String, nil] Edge id cursor: return the page after this id (mutually exclusive with `before`).
     # @param limit [Integer, nil] Maximum number of edges to return per page (1-200).
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
     # @return [Retab::PaginatedList<Retab::WorkflowEdgeDoc>]
@@ -70,7 +70,7 @@ module Retab
 
     # Create Edge
     # @param workflow_id [String] Workflow to create the edge in.
-    # @param id [String, nil] Opaque edge ID. Omit to let the server generate one.
+    # @param id [String, nil] Edge ID. Omit to let the server generate one (recommended).
     # @param source_block [String] Source block ID
     # @param target_block [String] Target block ID
     # @param source_handle [String, nil] Output handle