@spec authorization_from_api_key(String.t() | nil) :: String.t() | nil

Converts an API key string to a Bearer authorization header value.

@spec build_credential(String.t(), map()) :: {GRPC.Credential.t() | nil, [String.t()]}

Builds a GRPC.Credential for TLS/mTLS, along with a list of temporary PEM file paths to clean up on shutdown.

Returns {credential | nil, temp_pem_file_paths}.

@spec cleanup_temp_pem_files([String.t()]) :: :ok

Removes temporary PEM files created during mTLS setup.

@spec format_connect_error(term()) :: String.t()

Formats a gRPC connection error into a human-readable string.

@spec grpc_connect_opts(String.t(), map()) :: {keyword(), [String.t()]}

Builds the base gRPC connection options including adapter opts and retry config.

Returns {connect_opts, temp_pem_file_paths}.

@spec normalize_server_address(String.t()) :: String.t()

Normalizes a server address, auto-prepending https:// for known Temporal Cloud domains.

Examples

iex> normalize_server_address("my-ns.tmprl.cloud:7233")
"https://my-ns.tmprl.cloud:7233"

iex> normalize_server_address("localhost:7233")
"localhost:7233"

iex> normalize_server_address("https://custom.host:7233")
"https://custom.host:7233"

@spec request_metadata(String.t() | nil, String.t() | nil) :: map()

Builds gRPC request metadata map from namespace and authorization.

@spec resolve_client_mtls_files(map()) ::
  {String.t() | nil, String.t() | nil, [String.t()]}

Resolves mTLS client certificate and key from base64-encoded config values.

Writes decoded PEM data to temporary files and returns their paths.

Returns {cert_path | nil, key_path | nil, temp_file_paths}.