opentrust 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31a232efbd35fb3655663acd558ed31ce7593925761fbae6b04f83c88dc407f8
-  data.tar.gz: 3d14f0051077e2aa3f7d8b1ffda27e4307080ade525f42f334de8fe9f4ec6eb5
+  metadata.gz: 810e3839ac5fe409bc140e8bf26e34bafaf795ee9f3cc5601f64d616c5774b60
+  data.tar.gz: 5c828d92c69579e6e191629ef860d0404179dd410f20b8c9f9aba13330c972c0
 SHA512:
-  metadata.gz: d2c9f85cf69fb252ae1658764444764544d5dd95be76340ae3ef7e2d49951ac5db6d14a44f1a2a162b4a51f5892651d3948b56c8172677884ad9842b6fea8d22
-  data.tar.gz: c63e013d5d85d07adf22b96364e851cc2d32988780119ab1ec54d2ea802ffe08bf11e56fe07fec2a06bedf89477cf8a378b04e902fb189cbd32d65597d502c0f
+  metadata.gz: 55bbf1b388e709db9e4d7676cd47eebdef55e06a2d9b0a0ab81beabd788b7a424f70e8b899c6e5a8f142f76e247d686eb06d71c918d921554e94a8b39b424cf9
+  data.tar.gz: 765c55288178d3c0780c981b8042e469fcbb0eef305c6e0d8a1319829c2f5098191a8bca61f46ff5e690a770d1be0f6b0a5ad57128750ef21300e73993492e68

data/README.md

@@ -15,15 +15,37 @@ 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: "chargeback", notes: "Disputed 3 card payments 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" => ..., ... }
 ```
 
+## Send hashes instead of phone numbers
+
+Pass `hash_numbers: true` and the library sends the SHA-256 of each number instead of the number, so OpenTrust never receives it. It also sends `phone_length`, the length of the text it hashed (always 13), which OpenTrust checks to catch a hash of a differently written number. A report also sends the last four digits, so merchants and admins have something to recognise it by.
+
+```ruby
+client = OpenTrust::Client.new(hash_numbers: true)
+client.lookup("98765 43210")           # sends only the hash and its length (always 13)
+OpenTrust.hash_phone("98765 43210")    # => "f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90e"
+client.verify_hashing("98765 43210")   # development aid: asks OpenTrust to compare (sends the number: use a test number)
+```
+
+The format is exact, and a hash computed from a differently written number just finds nothing, so use the helper instead of hashing by hand. It is tested against the shared [test vectors](https://github.com/parity/opentrust/blob/main/sdks/phone-hash-vectors.json). A hash of a phone number can in principle be reversed by trying every possible number: this limits what is sent and stored, it does not make a number anonymous.
+
 ## Please don't block checkout on OpenTrust
 
 Results are unverified observations from individual merchants. Use them as one input, have a person review decisions that matter, and fail open if OpenTrust is unreachable:
@@ -37,7 +59,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,59 +3,139 @@ 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.
+  # `phone_sha256` is set when the number was sent as a hash (then `phone_last4` is empty: we never saw the number).
+  Lookup = Struct.new(:phone_last4, :phone_sha256, :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
 
+    # hash_numbers: send the SHA-256 of each number (see OpenTrust::Phone) instead of the number, so OpenTrust never receives it.
+    # A hash can in principle be reversed by brute force, so this limits what is sent; it does not make a number anonymous.
     # adapter: optional callable (method, url, headers, body) -> [status, body_string], mainly for tests.
-    def initialize(api_key: ENV["OPENTRUST_API_KEY"], base_url: ENV.fetch("OPENTRUST_BASE_URL", DEFAULT_BASE_URL), timeout: 5, adapter: nil)
+    def initialize(api_key: ENV["OPENTRUST_API_KEY"], base_url: ENV.fetch("OPENTRUST_BASE_URL", DEFAULT_BASE_URL), timeout: 5, adapter: nil, hash_numbers: false)
       raise ArgumentError, "api_key is required (or set OPENTRUST_API_KEY)" if api_key.to_s.empty?
 
       @api_key = api_key
       @base_url = base_url.chomp("/")
       @timeout = timeout
       @adapter = adapter
+      @hash_numbers = hash_numbers
     end
 
     # Check one number. Uses one check from your allowance.
     def lookup(phone)
-      lookup_from(request(:post, "/lookups", phone: phone))
+      lookup_from(request(:post, "/lookups", number_fields(phone)))
     end
 
     # Check up to 100 numbers. All or nothing: if you don't have enough checks, none are used.
     def lookup_many(phones)
-      body = request(:post, "/lookups/batch", phones: Array(phones))
+      list = Array(phones)
+      payload = @hash_numbers ? { phone_sha256s: list.map { |p| Phone.sha256(p) }, phone_length: Phone::HASHED_LENGTH } : { phones: list }
+      body = request(:post, "/lookups/batch", payload)
       body.fetch("results").map { |r| lookup_from(r.merge("notice" => body["notice"], "checks_remaining" => body["checks_remaining"])) }
     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", number_fields(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")
     end
 
+    # A development aid: asks OpenTrust whether it computes the same SHA-256 as this library for a number. Use a test number, not a
+    # customer's: it sends the number. Returns a Hash with "match" (true or false). It costs no checks.
+    def verify_hashing(test_phone)
+      request(:post, "/phone_hash/check", phone: test_phone, phone_sha256: Phone.sha256(test_phone))
+    end
+
     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)
+      number_fields(phone, with_last4: true).merge(reason_code: reason_code, notes: notes, incident_at: incident_at, confirmed_by: confirmed_by, evidence_ref: evidence_ref).compact
+    end
+
+    # The number, or (with hash_numbers) its SHA-256 and, for a report, its last four digits.
+    def number_fields(phone, with_last4: false)
+      return { phone: phone } unless @hash_numbers
+
+      fields = { phone_sha256: Phone.sha256(phone), phone_length: Phone.hashed_length(phone) }
+      fields[:phone_last4] = Phone.last4(phone) if with_last4
+      fields
+    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"], phone_sha256: h["phone_sha256"], 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 +152,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 +168,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

@@ -10,10 +10,14 @@ module OpenTrust
     end
   end
 
+  # Raised before anything is sent: the number is not an Indian mobile number, so it cannot be checked or hashed.
+  class InvalidPhoneError < ArgumentError; end
+
   class ConnectionError < Error; end        # network failure or timeout
   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/phone.rb

@@ -0,0 +1,48 @@
+require "digest"
+
+module OpenTrust
+  # The one place the number format is defined. OpenTrust accepts either a phone number or its SHA-256, and a hash only matches
+  # if it is computed exactly like this:
+  #
+  #   1. keep the digits, drop a leading 91 (12 digits) or 0 (11 digits), leaving 10 digits starting 6, 7, 8 or 9
+  #   2. prefix "+91", for example "+919876543210"
+  #   3. SHA-256 of that text, as 64 lowercase hex characters
+  #
+  # A hash that does not match simply finds nothing, so use this helper (and the shared test vectors) rather than hashing by hand.
+  module Phone
+    HASHED_LENGTH = 13 # +91 and ten digits
+
+    module_function
+
+    # "+91" followed by the ten digits. Raises InvalidPhoneError for anything that is not an Indian mobile number.
+    def normalize(raw)
+      digits = raw.to_s.gsub(/\D/, "")
+      digits = digits[2..-1] if digits.length == 12 && digits.start_with?("91")
+      digits = digits[1..-1] if digits.length == 11 && digits.start_with?("0")
+      raise InvalidPhoneError, "not a valid Indian mobile number" unless digits.match?(/\A[6-9]\d{9}\z/)
+
+      "+91#{digits}"
+    end
+
+    # The 64 lowercase hex characters OpenTrust expects as phone_sha256.
+    def sha256(raw)
+      Digest::SHA256.hexdigest(normalize(raw))
+    end
+
+    # The length of the text that is hashed (13), sent as phone_length. OpenTrust refuses any other value, which catches hashes of a
+    # differently written number (10 = just the digits, 11 = leading 0, 12 = 91 without the +).
+    def hashed_length(raw)
+      normalize(raw).length
+    end
+
+    # The last four digits, sent with a hashed report so merchants and admins have something to recognise it by.
+    def last4(raw)
+      normalize(raw)[-4..-1]
+    end
+  end
+
+  # Hash a number the way OpenTrust expects. Same as Phone.sha256.
+  def self.hash_phone(raw)
+    Phone.sha256(raw)
+  end
+end

data/lib/opentrust/version.rb

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

data/lib/opentrust.rb

@@ -1,3 +1,4 @@
 require_relative "opentrust/version"
 require_relative "opentrust/errors"
+require_relative "opentrust/phone"
 require_relative "opentrust/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentrust
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - ParityCube
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-14 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.
@@ -22,6 +22,7 @@ files:
 - lib/opentrust.rb
 - lib/opentrust/client.rb
 - lib/opentrust/errors.rb
+- lib/opentrust/phone.rb
 - lib/opentrust/version.rb
 homepage: https://opentrust.in/docs
 licenses: