Class: RubyClaude::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_claude/client.rb

Overview

Composes a Command and a Runner to execute queries and build Response and Event objects.

A client holds an immutable Configuration and a stateless runner, builds fresh argv/env per call, and never mutates shared state — so one instance is safe to reuse and to call concurrently from many threads.

Constant Summary collapse

AUTH_PATTERNS =

Heuristic patterns in stderr/result text that indicate an auth problem. Deliberately specific: bare “authentication” / “api key” / “credit balance” match too much benign text and would misclassify ordinary execution and billing failures as authentication errors.

Regexp.union(
  /invalid api key/i,
  /authentication[ _](?:failed|error|required)/i,
  /unauthorized/i,
  /not logged ?in/i,
  %r{/login}i,
  /oauth/i,
  /log ?in to claude/i
).freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(runner: Runner.new, **overrides) ⇒ Client

Returns a new instance of Client.

Parameters:

  • runner (#run, #stream) (defaults to: Runner.new) —

    subprocess runner (injectable for tests)

  • overrides (Hash) —

    per-instance RubyClaude::Configuration overrides

Raises:

  • (ArgumentError) —

    on an unknown configuration option



33
34
35
36
 
# File 'lib/ruby_claude/client.rb', line 33

def initialize(runner: Runner.new, **overrides)
  @config = RubyClaude.configuration.merge(overrides)
  @runner = runner
end

Instance Attribute Details

#config ⇒ Configuration (readonly)

Returns the effective configuration for this client.

Returns:

  • (Configuration) —

    the effective configuration for this client



28
29
30
 
# File 'lib/ruby_claude/client.rb', line 28

def config
  @config
end

Instance Method Details

#query(prompt, resume: nil) ⇒ Response Also known as: ask

Run a one-shot query and return its Response.

Parameters:

  • prompt (String)
  • resume (String, nil) (defaults to: nil) —

    a session id to resume

Returns:

Raises:



45
46
47
48
49
 
# File 'lib/ruby_claude/client.rb', line 45

def query(prompt, resume: nil)
  argv, env = Command.new(@config).build(stream: false, resume: resume)
  result = @runner.run(**run_args(argv, env, prompt))
  interpret(result)
end

#session(id: nil) ⇒ Session

Start a multi-turn Session backed by this client.

Parameters:

  • id (String, nil) (defaults to: nil) —

    an existing session id to resume

Returns:



78
79
80
 
# File 'lib/ruby_claude/client.rb', line 78

def session(id: nil)
  Session.new(self, id: id)
end

#stream(prompt, resume: nil) {|event| ... } ⇒ Response

Stream a query, yielding Events as they arrive.

Parameters:

  • prompt (String)
  • resume (String, nil) (defaults to: nil) —

    a session id to resume

Yield Parameters:

Returns:

  • (Response) —

    the final result, built from the result event

Raises:



60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/ruby_claude/client.rb', line 60

def stream(prompt, resume: nil)
  argv, env = Command.new(@config).build(stream: true, resume: resume)
  final = nil
  result = @runner.stream(**run_args(argv, env, prompt)) do |line|
    data = try_parse(line)
    next unless data

    final = data if data["type"] == "result"
    yield Event.from_hash(data) if block_given?
  end
  check_stream_result!(final, result)
  Response.from_result(final)
end