temper-rb 0.5.1

data/lib/temper/generated.rb

@@ -0,0 +1,402 @@
+=begin
+#Temper Cloud API
+
+#Knowledge base management API for temper cloud
+
+The version of the OpenAPI document: 0.5.1
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.23.0
+
+=end
+
+# Common files
+require 'temper/generated/api_client'
+require 'temper/generated/api_error'
+require 'temper/generated/api_model_base'
+require 'temper/generated/version'
+require 'temper/generated/configuration'
+
+# Models
+require 'temper/generated/models/accept_invitation_response'
+require 'temper/generated/models/act_input'
+require 'temper/generated/models/act_invocation'
+require 'temper/generated/models/act_name'
+require 'temper/generated/models/act_quantity'
+require 'temper/generated/models/act_refusal'
+require 'temper/generated/models/actor_authority'
+require 'temper/generated/models/add_member_request'
+require 'temper/generated/models/advance_watermark_ack'
+require 'temper/generated/models/advance_watermark_request'
+require 'temper/generated/models/agent_authorship'
+require 'temper/generated/models/anchor_address_resolution'
+require 'temper/generated/models/anchor_address_resolution_one_of'
+require 'temper/generated/models/anchor_address_resolution_one_of1'
+require 'temper/generated/models/anchor_address_resolution_one_of2'
+require 'temper/generated/models/anchor_shape'
+require 'temper/generated/models/anchor_verdict'
+require 'temper/generated/models/append_block_payload'
+require 'temper/generated/models/artifact_commit_request'
+require 'temper/generated/models/artifact_commit_response'
+require 'temper/generated/models/artifact_view'
+require 'temper/generated/models/assert_relationship_request'
+require 'temper/generated/models/atlas_edge'
+require 'temper/generated/models/atlas_entry'
+require 'temper/generated/models/atlas_home'
+require 'temper/generated/models/atlas_node'
+require 'temper/generated/models/atlas_subgraph'
+require 'temper/generated/models/audit_citation'
+require 'temper/generated/models/audit_sweep_row'
+require 'temper/generated/models/auditor_dispatch_tick_request'
+require 'temper/generated/models/auditor_dispatch_tick_response'
+require 'temper/generated/models/auditor_job_complete_ack'
+require 'temper/generated/models/bind_team_outcome'
+require 'temper/generated/models/bind_team_request'
+require 'temper/generated/models/blob_commit_response'
+require 'temper/generated/models/blob_delete_ack'
+require 'temper/generated/models/blob_relation_ack'
+require 'temper/generated/models/blob_relation_assert_request'
+require 'temper/generated/models/blob_relation_direction'
+require 'temper/generated/models/blob_relation_edge_direction'
+require 'temper/generated/models/blob_relation_row'
+require 'temper/generated/models/blob_summary'
+require 'temper/generated/models/blob_upload_begin_request'
+require 'temper/generated/models/blob_upload_begin_response'
+require 'temper/generated/models/blob_upload_finalize_request'
+require 'temper/generated/models/blob_upload_progress'
+require 'temper/generated/models/blob_upload_segment_info'
+require 'temper/generated/models/block_chunk_ref'
+require 'temper/generated/models/block_fold_disposition'
+require 'temper/generated/models/block_fold_disposition_one_of'
+require 'temper/generated/models/block_fold_disposition_one_of1'
+require 'temper/generated/models/block_fold_disposition_one_of2'
+require 'temper/generated/models/block_provenance_row'
+require 'temper/generated/models/block_read'
+require 'temper/generated/models/block_read_one_of'
+require 'temper/generated/models/block_read_one_of1'
+require 'temper/generated/models/block_read_one_of2'
+require 'temper/generated/models/block_successor'
+require 'temper/generated/models/blocks_response'
+require 'temper/generated/models/body_storage'
+require 'temper/generated/models/bridge'
+require 'temper/generated/models/bulk_reassign_ack'
+require 'temper/generated/models/bulk_reassign_request'
+require 'temper/generated/models/change_role_request'
+require 'temper/generated/models/charter_block'
+require 'temper/generated/models/charter_disposition'
+require 'temper/generated/models/citation_audit_request'
+require 'temper/generated/models/citation_audit_row'
+require 'temper/generated/models/claimed_audit_job'
+require 'temper/generated/models/claimed_job'
+require 'temper/generated/models/close_invocation_request'
+require 'temper/generated/models/cogmap_analytics_row'
+require 'temper/generated/models/cogmap_detail'
+require 'temper/generated/models/cogmap_foundation_row'
+require 'temper/generated/models/cogmap_grant_body'
+require 'temper/generated/models/cogmap_region_metrics_row'
+require 'temper/generated/models/cogmap_region_row'
+require 'temper/generated/models/cogmap_regulation_row'
+require 'temper/generated/models/cogmap_revoke_body'
+require 'temper/generated/models/cogmap_row'
+require 'temper/generated/models/cogmap_staleness'
+require 'temper/generated/models/combine_node'
+require 'temper/generated/models/combine_op'
+require 'temper/generated/models/composition'
+require 'temper/generated/models/composition_trace'
+require 'temper/generated/models/confidence_band'
+require 'temper/generated/models/content_response'
+require 'temper/generated/models/context_create_request'
+require 'temper/generated/models/context_owner_ref'
+require 'temper/generated/models/context_owner_ref_one_of'
+require 'temper/generated/models/context_owner_ref_one_of1'
+require 'temper/generated/models/context_panorama'
+require 'temper/generated/models/context_row'
+require 'temper/generated/models/context_row_with_counts'
+require 'temper/generated/models/create_cogmap_outcome'
+require 'temper/generated/models/create_cogmap_request'
+require 'temper/generated/models/create_invitation_request'
+require 'temper/generated/models/create_request_body'
+require 'temper/generated/models/create_review_body'
+require 'temper/generated/models/deactivated'
+require 'temper/generated/models/delete_response'
+require 'temper/generated/models/denied'
+require 'temper/generated/models/device_overrides'
+require 'temper/generated/models/discouraged_open_meta_key'
+require 'temper/generated/models/dispatch_tick_request'
+require 'temper/generated/models/dispatch_tick_response'
+require 'temper/generated/models/disposition'
+require 'temper/generated/models/doc_type_description'
+require 'temper/generated/models/doc_type_summary'
+require 'temper/generated/models/drift_sweep_row'
+require 'temper/generated/models/edge_facet_row'
+require 'temper/generated/models/edge_facet_set_request'
+require 'temper/generated/models/edge_facets_response'
+require 'temper/generated/models/edge_filter'
+require 'temper/generated/models/edge_kind'
+require 'temper/generated/models/element_event'
+require 'temper/generated/models/element_kind'
+require 'temper/generated/models/embed_dispatch_summary'
+require 'temper/generated/models/enforcement_mode'
+require 'temper/generated/models/entitlements'
+require 'temper/generated/models/entry_bounds'
+require 'temper/generated/models/error_body'
+require 'temper/generated/models/error_detail'
+require 'temper/generated/models/error_details'
+require 'temper/generated/models/event_cursor_response'
+require 'temper/generated/models/event_trail'
+require 'temper/generated/models/exact_arm'
+require 'temper/generated/models/exact_hit'
+require 'temper/generated/models/extent'
+require 'temper/generated/models/extent_one_of'
+require 'temper/generated/models/extent_one_of1'
+require 'temper/generated/models/extent_one_of2'
+require 'temper/generated/models/facet_ack'
+require 'temper/generated/models/facet_predicate'
+require 'temper/generated/models/facet_retract_ack'
+require 'temper/generated/models/facet_set_request'
+require 'temper/generated/models/finalize_payload'
+require 'temper/generated/models/fold_relationship_request'
+require 'temper/generated/models/grant_outcome'
+require 'temper/generated/models/graph_edge_row'
+require 'temper/generated/models/group_key_meta'
+require 'temper/generated/models/health_response'
+require 'temper/generated/models/home_cogmap'
+require 'temper/generated/models/home_context'
+require 'temper/generated/models/id_kind'
+require 'temper/generated/models/id_provenance'
+require 'temper/generated/models/id_provenance_one_of'
+require 'temper/generated/models/id_provenance_one_of1'
+require 'temper/generated/models/id_set'
+require 'temper/generated/models/idp_revocation'
+require 'temper/generated/models/illegal_transition'
+require 'temper/generated/models/ingest_create_response'
+require 'temper/generated/models/ingest_delta'
+require 'temper/generated/models/ingest_payload'
+require 'temper/generated/models/ingest_state'
+require 'temper/generated/models/inherited_read_grant'
+require 'temper/generated/models/inherited_share'
+require 'temper/generated/models/input_source'
+require 'temper/generated/models/input_source_one_of'
+require 'temper/generated/models/input_source_one_of1'
+require 'temper/generated/models/input_source_one_of2'
+require 'temper/generated/models/insufficient_authority'
+require 'temper/generated/models/intention'
+require 'temper/generated/models/invitation_status'
+require 'temper/generated/models/invitation_token_request'
+require 'temper/generated/models/invitee_invitation'
+require 'temper/generated/models/invocation_ack'
+require 'temper/generated/models/invocation_act_row'
+require 'temper/generated/models/invocation_close_ack'
+require 'temper/generated/models/invocation_summary'
+require 'temper/generated/models/invocation_view'
+require 'temper/generated/models/join_request'
+require 'temper/generated/models/join_request_status'
+require 'temper/generated/models/kind_owner_input'
+require 'temper/generated/models/kind_owner_input_one_of'
+require 'temper/generated/models/kind_owner_input_one_of1'
+require 'temper/generated/models/lineage_node'
+require 'temper/generated/models/managed_meta'
+require 'temper/generated/models/match_location'
+require 'temper/generated/models/materialize_ack'
+require 'temper/generated/models/materialize_delta'
+require 'temper/generated/models/materialize_request'
+require 'temper/generated/models/merge_policy'
+require 'temper/generated/models/meta_update_payload'
+require 'temper/generated/models/narrowed_by'
+require 'temper/generated/models/no_prior_standing'
+require 'temper/generated/models/no_standing'
+require 'temper/generated/models/node_home'
+require 'temper/generated/models/open_invocation_request'
+require 'temper/generated/models/open_meta_convention'
+require 'temper/generated/models/ord_op'
+require 'temper/generated/models/orphan_node'
+require 'temper/generated/models/outcome_declaration'
+require 'temper/generated/models/pending_invitation_counts'
+require 'temper/generated/models/plan_refusal'
+require 'temper/generated/models/plan_refusal_details'
+require 'temper/generated/models/polarity'
+require 'temper/generated/models/profile'
+require 'temper/generated/models/profile_auth_link'
+require 'temper/generated/models/profile_update_request'
+require 'temper/generated/models/profile_with_entitlements'
+require 'temper/generated/models/property_op'
+require 'temper/generated/models/property_op_one_of'
+require 'temper/generated/models/property_op_one_of1'
+require 'temper/generated/models/property_op_one_of2'
+require 'temper/generated/models/property_predicate'
+require 'temper/generated/models/provenance_source'
+require 'temper/generated/models/provenance_source_one_of'
+require 'temper/generated/models/provenance_source_one_of1'
+require 'temper/generated/models/provenance_source_one_of2'
+require 'temper/generated/models/public_system_settings'
+require 'temper/generated/models/quantity_scale'
+require 'temper/generated/models/quantity_scale_one_of'
+require 'temper/generated/models/quantity_scale_one_of1'
+require 'temper/generated/models/quantity_scale_one_of2'
+require 'temper/generated/models/query_response'
+require 'temper/generated/models/reassign_ack'
+require 'temper/generated/models/reassign_context_outcome'
+require 'temper/generated/models/reassign_context_request'
+require 'temper/generated/models/reassign_resource_request'
+require 'temper/generated/models/reblock_candidate'
+require 'temper/generated/models/reblock_outcome'
+require 'temper/generated/models/reblock_outcome_one_of'
+require 'temper/generated/models/reblock_outcome_one_of1'
+require 'temper/generated/models/reblock_outcome_one_of1_in_progress'
+require 'temper/generated/models/reblock_outcome_one_of2'
+require 'temper/generated/models/reblock_outcome_one_of3'
+require 'temper/generated/models/reblock_outcome_one_of4'
+require 'temper/generated/models/reblock_outcome_one_of4_error'
+require 'temper/generated/models/reblock_outcome_one_of_reblocked'
+require 'temper/generated/models/reblock_receipt'
+require 'temper/generated/models/reblock_request'
+require 'temper/generated/models/reblock_scope'
+require 'temper/generated/models/reblock_scope_one_of'
+require 'temper/generated/models/reblock_scope_one_of1'
+require 'temper/generated/models/reblock_summary'
+require 'temper/generated/models/reconcile_cogmap_request'
+require 'temper/generated/models/reconcile_edge'
+require 'temper/generated/models/reconcile_edge_tombstone'
+require 'temper/generated/models/reconcile_entry'
+require 'temper/generated/models/reconcile_outcome'
+require 'temper/generated/models/reconcile_telos'
+require 'temper/generated/models/reconcile_telos_block'
+require 'temper/generated/models/reconcile_tombstone'
+require 'temper/generated/models/refusal'
+require 'temper/generated/models/refusal_reason'
+require 'temper/generated/models/region_disclosure'
+require 'temper/generated/models/region_hit'
+require 'temper/generated/models/relationship_ack'
+require 'temper/generated/models/relationship_target'
+require 'temper/generated/models/remove_member_outcome'
+require 'temper/generated/models/rename_context_outcome'
+require 'temper/generated/models/rename_context_request'
+require 'temper/generated/models/requested'
+require 'temper/generated/models/residual_bucket'
+require 'temper/generated/models/residual_context'
+require 'temper/generated/models/residual_groups'
+require 'temper/generated/models/residual_owned_reach'
+require 'temper/generated/models/resource_annotate_request'
+require 'temper/generated/models/resource_create_request'
+require 'temper/generated/models/resource_facet_row'
+require 'temper/generated/models/resource_facets'
+require 'temper/generated/models/resource_facets_response'
+require 'temper/generated/models/resource_filter'
+require 'temper/generated/models/resource_grant_body'
+require 'temper/generated/models/resource_hit'
+require 'temper/generated/models/resource_lineage'
+require 'temper/generated/models/resource_list_response'
+require 'temper/generated/models/resource_revoke_body'
+require 'temper/generated/models/resource_section'
+require 'temper/generated/models/resource_sort_field'
+require 'temper/generated/models/resource_update_request'
+require 'temper/generated/models/resource_view'
+require 'temper/generated/models/restore_context_outcome'
+require 'temper/generated/models/retire_context_outcome'
+require 'temper/generated/models/return_spec'
+require 'temper/generated/models/retype_relationship_request'
+require 'temper/generated/models/revoke_outcome'
+require 'temper/generated/models/revoked'
+require 'temper/generated/models/reweight_relationship_request'
+require 'temper/generated/models/score_kind'
+require 'temper/generated/models/scoring'
+require 'temper/generated/models/search_params'
+require 'temper/generated/models/search_reason'
+require 'temper/generated/models/search_response'
+require 'temper/generated/models/search_result_row'
+require 'temper/generated/models/search_scope'
+require 'temper/generated/models/search_scope_info'
+require 'temper/generated/models/segment_info'
+require 'temper/generated/models/segmented_begin'
+require 'temper/generated/models/segmented_begin_response'
+require 'temper/generated/models/shape_declare_request'
+require 'temper/generated/models/shape_emptiness'
+require 'temper/generated/models/shape_view'
+require 'temper/generated/models/share_context_outcome'
+require 'temper/generated/models/share_context_request'
+require 'temper/generated/models/slack_disconnect_request'
+require 'temper/generated/models/slack_disconnect_response'
+require 'temper/generated/models/slack_disconnected_principal'
+require 'temper/generated/models/slice_request'
+require 'temper/generated/models/sort_order'
+require 'temper/generated/models/stage_disposition'
+require 'temper/generated/models/stage_input'
+require 'temper/generated/models/stage_input_one_of'
+require 'temper/generated/models/stage_input_one_of1'
+require 'temper/generated/models/stage_input_trace'
+require 'temper/generated/models/stage_node'
+require 'temper/generated/models/stage_output'
+require 'temper/generated/models/stage_output_one_of'
+require 'temper/generated/models/stage_output_one_of1'
+require 'temper/generated/models/stage_relation'
+require 'temper/generated/models/stage_result'
+require 'temper/generated/models/stage_trace'
+require 'temper/generated/models/standing'
+require 'temper/generated/models/standing_shape'
+require 'temper/generated/models/subscription'
+require 'temper/generated/models/subscription_override'
+require 'temper/generated/models/system_access_details'
+require 'temper/generated/models/team_create_request'
+require 'temper/generated/models/team_detail'
+require 'temper/generated/models/team_invitation'
+require 'temper/generated/models/team_member_detail'
+require 'temper/generated/models/team_member_row'
+require 'temper/generated/models/team_member_source'
+require 'temper/generated/models/team_role'
+require 'temper/generated/models/team_row'
+require 'temper/generated/models/team_update_request'
+require 'temper/generated/models/territory'
+require 'temper/generated/models/territory_kind'
+require 'temper/generated/models/territory_overview'
+require 'temper/generated/models/unbind_team_outcome'
+require 'temper/generated/models/unrecognized_standing'
+require 'temper/generated/models/unshare_context_outcome'
+require 'temper/generated/models/vault_config'
+require 'temper/generated/models/via_entry'
+require 'temper/generated/models/wide_arm'
+require 'temper/generated/models/wide_hit'
+
+# APIs
+require 'temper/generated/api/access_api'
+require 'temper/generated/api/auditor_api'
+require 'temper/generated/api/blobs_api'
+require 'temper/generated/api/cognitive_maps_api'
+require 'temper/generated/api/contexts_api'
+require 'temper/generated/api/data_artifact_shapes_api'
+require 'temper/generated/api/data_artifacts_api'
+require 'temper/generated/api/events_api'
+require 'temper/generated/api/facets_api'
+require 'temper/generated/api/graph_api'
+require 'temper/generated/api/health_api'
+require 'temper/generated/api/ingest_api'
+require 'temper/generated/api/invitations_api'
+require 'temper/generated/api/invocations_api'
+require 'temper/generated/api/meta_api'
+require 'temper/generated/api/profile_api'
+require 'temper/generated/api/query_api'
+require 'temper/generated/api/reblocking_api'
+require 'temper/generated/api/relationships_api'
+require 'temper/generated/api/resources_api'
+require 'temper/generated/api/schema_api'
+require 'temper/generated/api/search_api'
+require 'temper/generated/api/slack_link_api'
+require 'temper/generated/api/steward_api'
+require 'temper/generated/api/teams_api'
+
+module Temper::Generated
+  class << self
+    # Customize default settings for the SDK using block.
+    #   Temper::Generated.configure do |config|
+    #     config.username = "xxx"
+    #     config.password = "xxx"
+    #   end
+    # If no block given, return the default Configuration object.
+    def configure
+      if block_given?
+        yield(Configuration.default)
+      else
+        Configuration.default
+      end
+    end
+  end
+end

data/lib/temper/refs.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Temper
+  # A hyphenated UUID. Deliberately narrower than Rust's `Uuid::parse_str`, which
+  # also accepts the simple (unhyphenated), braced, and URN forms: this gem only
+  # ever hands the string straight back to the caller to put in a URL, so widening
+  # the accept set would mean emitting a non-canonical id. Narrower is safe --
+  # it rejects only inputs the server would have accepted.
+  UUID_PATTERN = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+  private_constant :UUID_PATTERN
+
+  # Resolve a ref to its UUID. Accepts a bare UUID or the decorated
+  # `sluggify(title)-<uuid>` form; resolution is trailing-UUID-only, so a stale
+  # slug half is harmless. No fuzzy matching -- unparseable input is an error,
+  # never a guess.
+  #
+  # A pure port of temper_workflow::operations::parse_ref. There is no by-slug
+  # lookup, so this never touches the network. The gem does NOT port `sluggify`:
+  # the server derives the slug from the title.
+  def self.parse_ref(ref)
+    raise ArgumentError, 'ref must be a String' unless ref.is_a?(String)
+
+    ref = ref.strip
+    return ref if ref.match?(UUID_PATTERN)
+
+    # A UUID contains four internal hyphens, so it is the last five
+    # hyphen-delimited groups. Walk from the right.
+    parts = ref.split('-')
+    if parts.length >= 5
+      tail = parts.last(5).join('-')
+      return tail if tail.match?(UUID_PATTERN)
+    end
+
+    raise ArgumentError, "not a ref (expected a UUID or `slug-<uuid>`): #{ref.inspect}"
+  end
+end

data/lib/temper/resources.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Temper
+  # The resource surface. Returns generated model instances directly -- the skin
+  # does not re-wrap them (D14).
+  class Resources
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /api/ingest -> 200 IngestCreateResponse.
+    #
+    # The seven act keys ride as top-level body fields (`#[serde(flatten)] pub
+    # act: ActInput`), which the generated IngestPayload already models as plain
+    # attributes because the contract expresses it as allOf: [ActInput, {...}].
+    #
+    # chunks_packed and content_hash are deliberately never sent: both are Option
+    # on IngestPayload and the server computes them. Ruby never embeds (D9).
+    def create(title:, context_ref:, doc_type_name:, content:, origin_uri: '', act: nil, **opts)
+      payload = Generated::IngestPayload.new(
+        { title: title, context_ref: context_ref, doc_type_name: doc_type_name,
+          content: content, origin_uri: origin_uri }.merge(opts).merge(act_hash(act))
+      )
+      @client.call { |api| Generated::IngestApi.new(api).create_ingest(payload) }
+    end
+
+    # GET /api/resources/{id} takes no query parameters at all, so `edges` is a
+    # separate operation rather than a flag, and `meta_only` is a different
+    # endpoint entirely.
+    def show(ref, meta_only: false)
+      id = Temper.parse_ref(ref)
+      @client.call(idempotent: true) do |api|
+        next Generated::MetaApi.new(api).get_meta(id) if meta_only
+
+        Generated::ResourcesApi.new(api).get_resource(id)
+      end
+    end
+
+    def edges(ref)
+      id = Temper.parse_ref(ref)
+      @client.call(idempotent: true) { |api| Generated::ResourcesApi.new(api).list_resource_edges(id) }
+    end
+
+    def update(ref, act: nil, **fields)
+      id = Temper.parse_ref(ref)
+      body = Generated::ResourceUpdateRequest.new(fields.merge(act_hash(act)))
+      @client.call { |api| Generated::ResourcesApi.new(api).update_resource(id, body) }
+    end
+
+    # DELETE /api/resources/{id} takes Query<ActInput>: the same seven keys, on
+    # the query string rather than in a body. The generated delete_resource reads
+    # them straight off `opts`, so Act#to_h passes through unchanged.
+    def delete(ref, act: nil)
+      id = Temper.parse_ref(ref)
+      @client.call { |api| Generated::ResourcesApi.new(api).delete_resource(id, act_hash(act)) }
+    end
+
+    def list(**filters)
+      @client.call(idempotent: true) { |api| Generated::ResourcesApi.new(api).list_resources(filters) }
+    end
+
+    private
+
+    def act_hash(act)
+      act.nil? ? {} : act.to_h
+    end
+  end
+end

data/lib/temper/validate.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'uri'
+
+module Temper
+  # What this gem is willing to put a secret on, checked once, at the seam.
+  #
+  # Two URLs arrive from a caller and then carry credentials on every use: the
+  # configured base URL -- every request puts the bearer token on it -- and the
+  # token URL, where every mint puts the client_secret on the wire. For both,
+  # the scheme is not cosmetic: plaintext http off the loopback interface puts
+  # the credential in the clear, readable by anything on the path.
+  #
+  # Checked at CONSTRUCTION, not at first use -- the same discipline the sibling
+  # clients state (temper-py's temper/_validate.py, temper-client's endpoint.rs,
+  # temper-ts's validate.ts): a URL validated when a request is built would
+  # surface its error several layers and possibly several minutes from the
+  # configuration that caused it.
+  module Validate
+    module_function
+
+    # Hostnames that are the local machine by definition. `.localhost` is
+    # reserved for exactly this by RFC 6761 6.3, and Docker/CI setups do use
+    # `foo.localhost`.
+    LOOPBACK_NAMES = ['localhost'].freeze
+
+    # An absolute http(s) origin this gem is willing to put a secret on.
+    # Returns the parsed URI.
+    #
+    # `allow_insecure_http` is the deliberate opt-out for the case this check
+    # cannot see -- a private network where TLS terminates elsewhere. It is a
+    # keyword a caller has to write, which is the whole point: it must not be a
+    # typo away.
+    def require_endpoint(value, name:, allow_insecure_http: false)
+      ensure_non_empty_string(value, name)
+      refuse_control_characters(value, name)
+      uri = parse(value, name)
+      ensure_http_scheme(uri, value, name)
+      refuse_userinfo(uri, name)
+      refuse_query_or_fragment(uri, name)
+      refuse_plaintext(uri, name, allow_insecure_http)
+      uri
+    end
+
+    # Whether `hostname` names this machine, by literal address or by reserved
+    # name. URI#host keeps the brackets on an IPv6 literal, so they are stripped
+    # before IPAddr sees the address -- it covers the whole 127.0.0.0/8 block,
+    # not just 127.0.0.1.
+    def loopback?(hostname)
+      host = hostname.to_s.delete_prefix('[').delete_suffix(']').downcase.delete_suffix('.')
+      begin
+        return IPAddr.new(host).loopback?
+      rescue IPAddr::InvalidAddressError
+        nil
+      end
+      LOOPBACK_NAMES.include?(host) || host.end_with?('.localhost')
+    end
+
+    def ensure_non_empty_string(value, name)
+      return if value.is_a?(String) && !value.empty?
+
+      raise ArgumentError, "#{name} must be a non-empty String"
+    end
+
+    # URI.parse refuses most malformed input; ASCII whitespace and control
+    # characters are refused up front (with the parser catching anything
+    # non-ASCII) rather than normalized -- silently cleaning a URL hides the
+    # mistake its author needs to see.
+    def refuse_control_characters(value, name)
+      return unless value.match?(/[\s[:cntrl:]]/)
+
+      raise ArgumentError, "#{name} must not contain whitespace or control characters"
+    end
+
+    def parse(value, name)
+      uri = URI.parse(value)
+      # Ruby's URI accepts a port outside 0..65535 without complaint; such an
+      # address is not usable, so it meets the same message as a parse failure.
+      port_usable = uri.port.to_i.between?(0, 65_535)
+      raise ArgumentError, "#{name} is not a parseable URL: #{value.inspect}" unless port_usable
+
+      uri
+    rescue URI::InvalidURIError, URI::InvalidComponentError, URI::BadURIError
+      raise ArgumentError, "#{name} is not a parseable URL: #{value.inspect}"
+    end
+
+    # URI.parse hands back URI::FTP, URI::MailTo and friends just as happily;
+    # only the two schemes that can protect a credential are accepted, and
+    # only with a host.
+    def ensure_http_scheme(uri, value, name)
+      return if (uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)) && !uri.host.to_s.empty?
+
+      raise ArgumentError, "#{name} must be an absolute http(s) URL, got #{value.inspect}"
+    end
+
+    # `uri.user` is nil for `host:port`, so this catches only a real userinfo
+    # section. Refused rather than dropped: a caller who wrote credentials
+    # into the URL meant them to authenticate something, and quietly
+    # discarding them would produce a 401 whose cause is invisible.
+    def refuse_userinfo(uri, name)
+      return unless uri.user || uri.password
+
+      raise ArgumentError,
+            "#{name} must not carry userinfo (user:password@); pass credentials to ClientCredentials instead"
+    end
+
+    def refuse_query_or_fragment(uri, name)
+      return unless uri.query || uri.fragment
+
+      raise ArgumentError,
+            "#{name} must be an origin (optionally with a path prefix), not a URL with a query or fragment"
+    end
+
+    # The rule and its opt-out, named in the message so the refusal teaches
+    # both ways out.
+    def refuse_plaintext(uri, name, allow_insecure_http)
+      return unless uri.scheme == 'http'
+      return if allow_insecure_http || loopback?(uri.host)
+
+      raise ArgumentError,
+            "#{name} is plaintext http to a non-loopback host, which would put the bearer token " \
+            'and client_secret on the wire in the clear; use https, or pass ' \
+            'allow_insecure_http: true to accept that deliberately'
+    end
+  end
+end

data/lib/temper/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Temper
+  # The gem's own SemVer. Independent of the API contract by design (D16):
+  # a gem version and an API version answer different questions.
+  #
+  # This file is loaded by temper-rb.gemspec via require_relative, so it must
+  # stand alone: no reference to Temper::Generated, which is not loaded then.
+  # CONTRACT_VERSION is defined in lib/temper.rb, after the generated core.
+  VERSION = '0.5.1'
+end