Class: Mailkube::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/mailkube/client.rb,
sig/mailkube/client.rbs

Overview

The API client, and this gem's composition root.

Create one and reuse it. It is frozen after construction and safe to share across threads (and across fibers, where a scheduler is installed); spec/concurrency_spec.rb proves it rather than asserting it.

client = Mailkube.new                      # reads MAILKUBE_API_KEY
email = client.emails.send(
  from: "Acme <hello@yourdomain.com>",
  to: "customer@example.com",
  subject: "Hello world",
  html: "<p>It works!</p>"
)

There are deliberately no built-in retries. A RateLimitError carries retry_after and a ServerError is safe to retry with backoff, so the calling application decides. Pass idempotency_key: to make a retry safe.

This client is synchronous, which is the contract's sync-only case: concurrency here is the caller's concern rather than an API-surface decision. See .rules/SDK_DESIGN.md.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil, user_agent_suffix: nil) ⇒ Client

Create a client, resolving configuration from the arguments then the environment.

Parameters:

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

    the API key; falls back to MAILKUBE_API_KEY.

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

    the API base URL; falls back to MAILKUBE_BASE_URL.

  • timeout (Integer, Float) (defaults to: Config::DEFAULT_TIMEOUT) —

    the per-request open and read timeout in seconds.

  • http (#call, nil) (defaults to: nil) —

    an HTTP adapter to use instead of the built-in NetHttpAdapter. This is the dependency-inversion seam the test suite injects through; when supplied, timeout is the adapter's business rather than this client's.

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

    a name/version token identifying software that wraps this SDK — a CLI, an internal service, a framework integration — appended after this SDK's own token so both are visible. A value containing CR or LF is ignored.

Raises:



42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/mailkube/client.rb', line 42

def initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil,
               user_agent_suffix: nil)
  config = Config.new(
    api_key: api_key, base_url: base_url, timeout: timeout, user_agent_suffix: user_agent_suffix
  )
  transport = Transport.new(config, http || NetHttpAdapter.new(timeout: timeout))

  @config = config
  @emails = Resources::Emails.new(transport)
  @scheduled_emails = Resources::ScheduledEmails.new(transport)
  freeze
end

Instance Attribute Details

#emails ⇒ Resources::Emails (readonly)

Returns the emails namespace.

Returns:



26
27
28
 
# File 'lib/mailkube/client.rb', line 26

def emails
  @emails
end

#scheduled_emails ⇒ Resources::ScheduledEmails (readonly)

Returns the scheduled-emails namespace.

Returns:



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

def scheduled_emails
  @scheduled_emails
end

Instance Method Details

#base_url ⇒ String

Returns the resolved API base URL.

Returns:

  • (String) —

    the resolved API base URL.



56
 
# File 'lib/mailkube/client.rb', line 56

def base_url = @config.base_url