buchida 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d5794bc5a7586d8406ceae305adc564b6be4d45937fdf04902ff698757302a8
-  data.tar.gz: 474b68adcfc795011bc1265a21d5b1d6c90738734e36072f807f3741d6028690
+  metadata.gz: 7dbd112ad5d392d35ec62955149963bbec35a8765644c4305939fb42d985b4de
+  data.tar.gz: bee7497ebefacd406ff96a6501e09df13e4b8009b5d814bdcbd79b4edec81aea
 SHA512:
-  metadata.gz: ab08556d489588178b1288a4d009e99c774ecbb50b56b5a6de7337fc8ff659fbe6a410b19986816c52bb1fe48a10994f4bc058907157e7ceba2193dc46596f53
-  data.tar.gz: aaa14a68db35b21bacd69e9010e72e1b1f77a2b1aeb2c9a6e0377f7a5a9093f3e4fe456072920242cbb3b8a0203e98e1ea1382177f35c9f76ca7e927a81da686
+  metadata.gz: 104960ce3956b0c51b243139a74c14fd045eef4d7f391d4b1bf41f0ccbdc290852507391cdd65d278b85b13ce89cea92d35260b6f5a8f6ffb7b80598ca917720
+  data.tar.gz: 814f8c84b3398dd20ba19d852523c946afd8099676db8cade70d9f3fe3c8724ef958fbcce35cd6bc1695c9f388ffd62a54a2dd9a7ed48b0d32da51ca68279553

data/lib/buchida/client.rb

@@ -6,7 +6,7 @@ require "json"
 
 module Buchida
 	class Client
-		DEFAULT_BASE_URL = "https://api.buchida.com"
+		DEFAULT_BASE_URL = "https://api.buchida.com/v1"
 		DEFAULT_TIMEOUT = 30
 
 		attr_reader :emails, :domains, :api_keys, :webhooks, :templates, :metrics
@@ -57,8 +57,32 @@ module Buchida
 			JSON.parse(response.body)
 		end
 
+		# Request returning a single object: unwraps `{ "data" => {...} }` (204 => nil).
+		def request_object(method, path, body = nil)
+			unwrap_object(request(method, path, body))
+		end
+
+		# Request returning a list: unwraps `{ "data" => [...], "cursor" =>, "hasMore" => }`.
+		def request_list(method, path, body = nil)
+			resp = request(method, path, body)
+			if resp.is_a?(Hash)
+				ListResult.new(resp["data"] || [], cursor: resp["cursor"], has_more: resp["hasMore"] || resp["has_more"] || false)
+			elsif resp.is_a?(Array)
+				ListResult.new(resp)
+			else
+				resp
+			end
+		end
+
 		private
 
+		def unwrap_object(resp)
+			return resp unless resp.is_a?(Hash)
+
+			inner = resp.key?("data") ? resp["data"] : resp
+			inner.is_a?(Hash) ? Result[inner] : inner
+		end
+
 		def handle_error(response)
 			body = begin
 				JSON.parse(response.body)
@@ -66,7 +90,14 @@ module Buchida
 				{ "message" => response.message }
 			end
 
-			message = body["message"] || response.message
+			err = body["error"]
+			if err.is_a?(Hash)
+				message = err["message"] || response.message
+				error_code = err["code"]
+			else
+				message = body["message"] || response.message
+				error_code = body["code"]
+			end
 			status = response.code.to_i
 
 			case status
@@ -74,7 +105,7 @@ module Buchida
 			when 404 then raise NotFoundError, message
 			when 422 then raise ValidationError, message
 			when 429 then raise RateLimitError, message
-			else raise Error.new(message, status, body["code"])
+			else raise Error.new(message, status, error_code)
 			end
 		end
 	end

data/lib/buchida/resources/api_keys.rb

@@ -8,11 +8,11 @@ module Buchida
 			end
 
 			def create(name:, permission:)
-				@client.request(:post, "/api-keys", { name: name, permission: permission })
+				@client.request_object(:post, "/api-keys", { name: name, permission: permission })
 			end
 
 			def list
-				@client.request(:get, "/api-keys")
+				@client.request_list(:get, "/api-keys")
 			end
 
 			def delete(id)

data/lib/buchida/resources/domains.rb

@@ -8,19 +8,19 @@ module Buchida
 			end
 
 			def create(name:)
-				@client.request(:post, "/domains", { name: name })
+				@client.request_object(:post, "/domains", { name: name })
 			end
 
 			def list
-				@client.request(:get, "/domains")
+				@client.request_list(:get, "/domains")
 			end
 
 			def get(id)
-				@client.request(:get, "/domains/#{id}")
+				@client.request_object(:get, "/domains/#{id}")
 			end
 
 			def verify(id)
-				@client.request(:post, "/domains/#{id}/verify")
+				@client.request_object(:post, "/domains/#{id}/verify")
 			end
 		end
 	end

data/lib/buchida/resources/emails.rb

@@ -7,40 +7,47 @@ module Buchida
 				@client = client
 			end
 
-			def send(from:, to:, subject:, html: nil, text: nil, reply_to: nil, cc: nil, bcc: nil, tags: nil, scheduled_at: nil)
+			def send(from:, to:, subject:, html: nil, text: nil, reply_to: nil, cc: nil, bcc: nil, tags: nil, scheduled_at: nil, from_name: nil)
 				body = { from: from, to: to, subject: subject }
+				body[:from_name] = from_name if from_name
 				body[:html] = html if html
 				body[:text] = text if text
-				body[:replyTo] = reply_to if reply_to
+				body[:reply_to] = reply_to if reply_to
 				body[:cc] = cc if cc
 				body[:bcc] = bcc if bcc
 				body[:tags] = tags if tags
-				body[:scheduledAt] = scheduled_at if scheduled_at
-				@client.request(:post, "/emails", body)
+				body[:scheduled_at] = scheduled_at if scheduled_at
+				@client.request_object(:post, "/emails", body)
 			end
 
 			def get(id)
-				@client.request(:get, "/emails/#{id}")
+				@client.request_object(:get, "/emails/#{id}")
 			end
 
-			def list(cursor: nil, limit: nil, status: nil, from: nil, to: nil)
+			# +from+ / +to+ filter by sender / recipient ADDRESS (not dates).
+			# +from_date+ / +to_date+ (ISO 8601) filter by creation date;
+			# +direction+ is "inbound" or "outbound".
+			def list(cursor: nil, limit: nil, status: nil, from: nil, to: nil, from_date: nil, to_date: nil, direction: nil)
 				params = {}
 				params[:cursor] = cursor if cursor
 				params[:limit] = limit if limit
 				params[:status] = status if status
 				params[:from] = from if from
 				params[:to] = to if to
+				params[:from_date] = from_date if from_date
+				params[:to_date] = to_date if to_date
+				params[:direction] = direction if direction
 				qs = URI.encode_www_form(params) unless params.empty?
 				path = qs ? "/emails?#{qs}" : "/emails"
-				@client.request(:get, path)
+				@client.request_list(:get, path)
 			end
 
 			def cancel(id)
-				@client.request(:post, "/emails/#{id}/cancel")
+				@client.request_object(:post, "/emails/#{id}/cancel")
 			end
 
 			def send_batch(emails)
-				@client.request(:post, "/emails/batch", emails)
+				@client.request_list(:post, "/emails/batch", emails)
 			end
 		end
 	end

data/lib/buchida/resources/metrics.rb

@@ -8,10 +8,11 @@ module Buchida
 			end
 
 			def get(from:, to:, granularity: nil)
-				params = { from: from, to: to }
+				# The API filters on from_date/to_date; plain from/to were silently ignored.
+				params = { from_date: from, to_date: to }
 				params[:granularity] = granularity if granularity
 				qs = URI.encode_www_form(params)
-				@client.request(:get, "/metrics?#{qs}")
+				@client.request_object(:get, "/metrics?#{qs}")
 			end
 		end
 	end

data/lib/buchida/resources/templates.rb

@@ -7,12 +7,17 @@ module Buchida
 				@client = client
 			end
 
-			def list
-				@client.request(:get, "/templates")
+			# +status+ is "draft" or "published"; +search+ matches name/subject.
+			def list(status: nil, search: nil)
+				params = {}
+				params[:status] = status if status
+				params[:search] = search if search
+				path = params.empty? ? "/templates" : "/templates?#{URI.encode_www_form(params)}"
+				@client.request_list(:get, path)
 			end
 
 			def get(id)
-				@client.request(:get, "/templates/#{id}")
+				@client.request_object(:get, "/templates/#{id}")
 			end
 		end
 	end

data/lib/buchida/resources/webhooks.rb

@@ -8,11 +8,11 @@ module Buchida
 			end
 
 			def create(url:, events:)
-				@client.request(:post, "/webhooks", { url: url, events: events })
+				@client.request_object(:post, "/webhooks", { url: url, events: events })
 			end
 
 			def list
-				@client.request(:get, "/webhooks")
+				@client.request_list(:get, "/webhooks")
 			end
 
 			def delete(id)

data/lib/buchida/response.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Buchida
+	# Deprecation helper for the pre-0.2 raw-envelope access (`res["data"]`).
+	module Legacy
+		@warned = false
+
+		def self.warn_once(what)
+			return if @warned
+
+			@warned = true
+			Kernel.warn("[buchida] DEPRECATION: #{what} is deprecated. Since buchida 0.2 the SDK " \
+				"returns the unwrapped payload; use the result directly.")
+		end
+
+		def self.data_key?(key)
+			key == "data" || key == :data
+		end
+	end
+
+	# An unwrapped single-object response (a Hash with String keys, as before).
+	# `result["data"]` / `result[:data]` still return the same object, with a one-time
+	# deprecation warning, so code written against the raw `{ "data" => {...} }` envelope keeps working.
+	# No self-reference is stored, so `to_json` / `JSON.generate` are unaffected.
+	class Result < Hash
+		REAL_KEY = Hash.instance_method(:key?)
+
+		def [](key)
+			if Legacy.data_key?(key) && !REAL_KEY.bind(self).call("data")
+				Legacy.warn_once("result[\"data\"]")
+				return self
+			end
+			super
+		end
+
+		def key?(key)
+			Legacy.data_key?(key) || super
+		end
+		alias_method :has_key?, :key?
+		alias_method :include?, :key?
+		alias_method :member?, :key?
+
+		def fetch(key, *args, &block)
+			if Legacy.data_key?(key) && !REAL_KEY.bind(self).call("data")
+				Legacy.warn_once("result.fetch(\"data\")")
+				return self
+			end
+			super
+		end
+
+		def dig(key, *rest)
+			value = self[key]
+			rest.empty? || value.nil? ? value : value.dig(*rest)
+		end
+	end
+
+	# An unwrapped list response: an Array of items plus `cursor` and `has_more`.
+	# The old envelope keys (`res["data"]`, `res["cursor"]`, `res["hasMore"]`) still work, with a
+	# one-time deprecation warning.
+	class ListResult < Array
+		attr_reader :cursor, :has_more
+
+		def initialize(items = [], cursor: nil, has_more: false)
+			super(items)
+			@cursor = cursor
+			@has_more = has_more
+		end
+
+		def data
+			self
+		end
+
+		def has_more?
+			@has_more ? true : false
+		end
+
+		LEGACY_KEYS = %w[data cursor hasMore has_more].freeze
+
+		def self.legacy_key?(key)
+			(key.is_a?(String) || key.is_a?(Symbol)) && LEGACY_KEYS.include?(key.to_s)
+		end
+
+		def key?(key)
+			ListResult.legacy_key?(key)
+		end
+		alias_method :has_key?, :key?
+
+		def include?(item)
+			ListResult.legacy_key?(item) || super
+		end
+
+		def fetch(key, *args, &block)
+			return self[key] if ListResult.legacy_key?(key)
+
+			super
+		end
+
+		def dig(key, *rest)
+			if ListResult.legacy_key?(key)
+				value = self[key]
+				return rest.empty? || value.nil? ? value : value.dig(*rest)
+			end
+
+			super
+		end
+
+		def [](*args)
+			key = args.first
+			if args.length == 1 && (key.is_a?(String) || key.is_a?(Symbol))
+				case key.to_s
+				when "data" then (Legacy.warn_once("list[\"data\"]"); return self)
+				when "cursor" then (Legacy.warn_once("list[\"cursor\"]"); return @cursor)
+				when "hasMore", "has_more" then (Legacy.warn_once("list[\"hasMore\"]"); return @has_more)
+				end
+				return nil
+			end
+			super
+		end
+	end
+end

data/lib/buchida/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Buchida
-	VERSION = "0.1.0"
+	VERSION = "0.2.1"
 end

data/lib/buchida.rb

@@ -2,6 +2,7 @@
 
 require_relative "buchida/version"
 require_relative "buchida/errors"
+require_relative "buchida/response"
 require_relative "buchida/client"
 require_relative "buchida/resources/emails"
 require_relative "buchida/resources/domains"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: buchida
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - buchida
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -54,6 +54,7 @@ files:
 - lib/buchida/resources/metrics.rb
 - lib/buchida/resources/templates.rb
 - lib/buchida/resources/webhooks.rb
+- lib/buchida/response.rb
 - lib/buchida/version.rb
 homepage: https://github.com/Vyblor/buchida-ruby
 licenses: