opentrust 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31a232efbd35fb3655663acd558ed31ce7593925761fbae6b04f83c88dc407f8
-  data.tar.gz: 3d14f0051077e2aa3f7d8b1ffda27e4307080ade525f42f334de8fe9f4ec6eb5
+  metadata.gz: 1be8ac1901adb4eba6e169948dd6172743d816f582c73beb84a6665757cec2ab
+  data.tar.gz: d0f5877799fb975d2f9d34601bf86103d4f5109ce1e031e6b6daf3f6b745d4c4
 SHA512:
-  metadata.gz: d2c9f85cf69fb252ae1658764444764544d5dd95be76340ae3ef7e2d49951ac5db6d14a44f1a2a162b4a51f5892651d3948b56c8172677884ad9842b6fea8d22
-  data.tar.gz: c63e013d5d85d07adf22b96364e851cc2d32988780119ab1ec54d2ea802ffe08bf11e56fe07fec2a06bedf89477cf8a378b04e902fb189cbd32d65597d502c0f
+  metadata.gz: c0a3d367db5b5697fbf9de7618c6cb29d29e4ea5ddd3628f1aca17befa00812622a52e44ccbc498bbf07ca428d63467848f568e0a95098976f3436e353a9d81e
+  data.tar.gz: b416321fcf6e6c13fc299148d668dfdab3fbae2def6bc1671594f237c8012d8b5fb604210a5e12ca174eadd98f643947d998ab72dc39c8a90938104307bed34e

data/README.md

@@ -15,12 +15,21 @@ client = OpenTrust::Client.new(api_key: ENV["OPENTRUST_API_KEY"]) # or just set
 result = client.lookup("98765 43210")   # uses 1 check
 result.reported?       # => true / false
 result.report_count    # => 2
-result.reports.each { |r| puts "#{r.reason_code}: #{r.notes}" }
+result.reports.each { |r| puts "#{r.reason_code} (#{r.incident_at}): #{r.notes}" }  # other merchants' reports only
+result.own_report?     # => true if you have shared this number yourself
 result.notice          # keep this in front of anyone who sees the result
 result.checks_remaining
 
 client.lookup_many(%w[9876543210 9000000001])          # up to 100, all or nothing
-client.report(phone: "9876543210", reason_code: "cod_refusal", notes: "Refused 3 COD orders in March")
+client.report(phone: "9876543210", reason_code: "cod_refusal", notes: "Refused 3 COD orders in March", incident_at: Date.new(2026, 3, 14),
+              confirmed_by: "bank", evidence_ref: "your-ticket-123")   # optional: who confirmed it (shown to others), and a private reference
+
+# up to 100 at once; one bad row never stops the rest
+results = client.report_many([{ phone: "9876543210", reason_code: "chargeback", incident_at: "2026-08-14" }, { phone: "9812345678", reason_code: "fake_order" }])
+results.reject(&:recorded?).each { |r| warn "row #{r.index}: #{r.status} #{r.error_code}" }
+
+client.withdraw_report("9876543210")                    # take your own report back (raises NotFoundError if there is none)
+client.reason_codes                                     # => [#<struct code="chargeback", group=..., label=..., description=...>, ...]
 client.me                                               # => { "checks_remaining" => ..., ... }
 ```
 
@@ -37,7 +46,7 @@ rescue OpenTrust::Error => e
 end
 ```
 
-Errors: `AuthenticationError` (401), `NoChecksError` (402, write to us and we'll raise your limit), `NotApprovedError` (403), `DuplicateReportError` (409), `InvalidRequestError` (422), `RateLimitError` (429), `ServerError` (5xx), `ConnectionError` (network/timeout). All inherit from `OpenTrust::Error` and carry `status` and `code`.
+Errors: `AuthenticationError` (401), `NoChecksError` (402, write to us and we'll raise your limit), `NotApprovedError` (403), `NotFoundError` (404, withdrawing a report you don't have), `DuplicateReportError` (409), `InvalidRequestError` (422), `RateLimitError` (429), `ServerError` (5xx), `ConnectionError` (network/timeout). All inherit from `OpenTrust::Error` and carry `status` and `code`.
 
 Timeout defaults to 5 seconds (`timeout:`). Docs: https://opentrust.in/docs
 

data/lib/opentrust/client.rb

@@ -3,18 +3,42 @@ require "net/http"
 require "uri"
 
 module OpenTrust
-  Report = Struct.new(:reason_code, :reason, :notes, :reported_at, :reporter_verified, keyword_init: true)
+  Report = Struct.new(:reason_code, :reason, :notes, :incident_at, :confirmed_by, :reported_at, :reporter_verified, keyword_init: true)
 
   # The result of checking one number. Reports are unverified observations from individual merchants,
   # not a finding about anyone. Use them as one input among others.
-  Lookup = Struct.new(:phone_last4, :report_count, :reports, :notice, :checks_remaining, keyword_init: true) do
+  #
+  # `reports` and `report_count` only hold OTHER merchants' reports. `own_report` says whether you have shared this number yourself.
+  Lookup = Struct.new(:phone_last4, :report_count, :reports, :own_report, :notice, :checks_remaining, keyword_init: true) do
     def reported?
       report_count.to_i.positive?
     end
+
+    def own_report?
+      own_report == true
+    end
   end
 
   Receipt = Struct.new(:id, :phone_last4, keyword_init: true)
 
+  # One row of a bulk report. `status` is "recorded", "duplicate" (you already shared it; treat as done) or "invalid".
+  BatchResult = Struct.new(:index, :status, :id, :phone_last4, :error_code, :error_message, keyword_init: true) do
+    def recorded?
+      status == "recorded"
+    end
+
+    def duplicate?
+      status == "duplicate"
+    end
+
+    def invalid?
+      status == "invalid"
+    end
+  end
+
+  Withdrawal = Struct.new(:phone_last4, :status, keyword_init: true)
+  ReasonCode = Struct.new(:code, :group, :label, :description, :use_when, :not_when, keyword_init: true)
+
   class Client
     DEFAULT_BASE_URL = "https://opentrust.in/api/v1".freeze
 
@@ -40,11 +64,39 @@ module OpenTrust
     end
 
     # Share an experience with a number. Optional, and doesn't change your allowance.
-    def report(phone:, reason_code:, notes: nil)
-      body = request(:post, "/reports", { phone: phone, reason_code: reason_code, notes: notes }.compact)
+    # incident_at: when it happened (a Date, a Time or an ISO 8601 string); can't be in the future.
+    # confirmed_by: "bank", "payment_gateway" or "law_enforcement", only if they told you the activity was confirmed (shown to other
+    # merchants, not verified). evidence_ref: a private reference for administrators, never shown; needs confirmed_by.
+    def report(phone:, reason_code:, notes: nil, incident_at: nil, confirmed_by: nil, evidence_ref: nil)
+      body = request(:post, "/reports", report_payload(phone: phone, reason_code: reason_code, notes: notes, incident_at: incident_at,
+                                                       confirmed_by: confirmed_by, evidence_ref: evidence_ref))
       Receipt.new(id: body["id"], phone_last4: body["phone_last4"])
     end
 
+    # Share up to 100 experiences at once. Each is handled on its own, so one bad row never stops the rest: the result is a
+    # BatchResult per report, in order. reports: [{ phone:, reason_code:, notes:, incident_at: }, ...]
+    def report_many(reports)
+      list = Array(reports)
+      raise ArgumentError, "report_many takes 1 to 100 reports" unless list.size.between?(1, 100)
+
+      body = request(:post, "/reports/batch", reports: list.map { |r| report_payload(**r.transform_keys(&:to_sym)) })
+      body.fetch("results").map do |r|
+        BatchResult.new(index: r["index"], status: r["status"], id: r["id"], phone_last4: r["phone_last4"],
+                        error_code: r.dig("error", "code"), error_message: r.dig("error", "message"))
+      end
+    end
+
+    # Withdraw your own report for a number. Raises NotFoundError if you have no active report for it.
+    def withdraw_report(phone)
+      body = request(:delete, "/reports", phone: phone)
+      Withdrawal.new(phone_last4: body["phone_last4"], status: body["status"])
+    end
+
+    # The reason codes with their labels and descriptions.
+    def reason_codes
+      request(:get, "/reason_codes").fetch("reason_codes").map { |c| ReasonCode.new(code: c["code"], group: c["group"], label: c["label"], description: c["description"], use_when: c["use_when"], not_when: c["not_when"]) }
+    end
+
     # Your remaining checks and usage, as a Hash.
     def me
       request(:get, "/me")
@@ -52,10 +104,17 @@ module OpenTrust
 
     private
 
+    def report_payload(phone:, reason_code:, notes: nil, incident_at: nil, confirmed_by: nil, evidence_ref: nil)
+      incident_at = incident_at.iso8601 if incident_at.respond_to?(:iso8601)
+      { phone: phone, reason_code: reason_code, notes: notes, incident_at: incident_at, confirmed_by: confirmed_by, evidence_ref: evidence_ref }.compact
+    end
+
     def lookup_from(h)
       Lookup.new(
-        phone_last4: h["phone_last4"], report_count: h["report_count"], notice: h["notice"], checks_remaining: h["checks_remaining"],
-        reports: Array(h["reports"]).map { |r| Report.new(reason_code: r["reason_code"], reason: r["reason"], notes: r["notes"], reported_at: r["reported_at"], reporter_verified: r["reporter_verified"]) }
+        phone_last4: h["phone_last4"], report_count: h["report_count"], own_report: h["own_report"], notice: h["notice"], checks_remaining: h["checks_remaining"],
+        reports: Array(h["reports"]).map do |r|
+          Report.new(reason_code: r["reason_code"], reason: r["reason"], notes: r["notes"], incident_at: r["incident_at"], confirmed_by: r["confirmed_by"], reported_at: r["reported_at"], reporter_verified: r["reporter_verified"])
+        end
       )
     end
 
@@ -72,7 +131,7 @@ module OpenTrust
       return @adapter.call(verb, url, headers, body) if @adapter
 
       uri = URI(url)
-      klass = verb == :get ? Net::HTTP::Get : Net::HTTP::Post
+      klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, delete: Net::HTTP::Delete }.fetch(verb)
       req = klass.new(uri, headers)
       req.body = body if body
       res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
@@ -88,6 +147,7 @@ module OpenTrust
               when 401 then AuthenticationError
               when 402 then NoChecksError
               when 403 then NotApprovedError
+              when 404 then NotFoundError
               when 409 then DuplicateReportError
               when 422 then InvalidRequestError
               when 429 then RateLimitError

data/lib/opentrust/errors.rb

@@ -14,6 +14,7 @@ module OpenTrust
   class AuthenticationError < Error; end    # 401: missing or invalid API key
   class NoChecksError < Error; end          # 402: allowance used up
   class NotApprovedError < Error; end       # 403: account not approved or suspended
+  class NotFoundError < Error; end          # 404: no active report of yours for that number (withdrawing)
   class DuplicateReportError < Error; end   # 409: you already shared this number
   class InvalidRequestError < Error; end    # 422: bad number, reason code or note
   class RateLimitError < Error; end         # 429

data/lib/opentrust/version.rb

@@ -1,3 +1,3 @@
 module OpenTrust
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentrust
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - ParityCube
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies: []
 description: Check mobile numbers against experiences shared by other Indian merchants,
   and share your own. A small, dependency-free client for https://opentrust.in.