paygate_pk 0.2.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dafac109de3aec799f0269fdd9f1d8ccd0990b0f435ed293d98b6b2c8c309ec
-  data.tar.gz: 04c5136a8bd15c6a24d7deb399e514aeb823423497ddeca8068512eb292ae47c
+  metadata.gz: dd62d57ff115a50c39bc303dbc2713554f220d64e7bfa262f5973851ccbef217
+  data.tar.gz: 9e459c21d4d178b2601c5ccc37b245defce997995e31bf85e82b5f08ceed9758
 SHA512:
-  metadata.gz: 1e1a50ea78bc7f9a58e6fb9ea3da2c8601ef26d3b5a4540fe7f4d29f2450c04da387e2510c8adc592e35d43108b887ee172512d8435cdbcde17bd18d72d5fe2a
-  data.tar.gz: 9c2bafce8c59fc7b0ae56950646de26a3ab58fd167269a14e5f15859f99b46b94753107b4c0f3fc807b53adb83591a161f8cd8c5b38bdb0b6f5daf3063d779b9
+  metadata.gz: 6ad4cb08e2ced98d4daaad9bf4f519615b773dacdca507b9e5eaeee0b03cc9f4cb29eb87e62aee815cfb99c99167e71176c63362d3fa8e20b0d1a82dfe8ac112
+  data.tar.gz: fd859b7d8ef82f97e4a34b02dcd3b7b077b6cf5f479069d75194dd2bbd9587beb629cad6bf9e7d8573a0ce4cde4c1e80965d868fcb8489f4eddfb8eb3baf09b5

data/.rubocop.yml

@@ -1,5 +1,11 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "coverage/**/*"
+    - "vendor/**/*"
+    - "*.gemspec"
 
 Style/StringLiterals:
   Enabled: true
@@ -9,16 +15,41 @@ Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
+Style/Documentation:
+  Enabled: false
+
 Layout/LineLength:
   Max: 120
 
 Metrics/MethodLength:
-  Max: 20 # Example: Set maximum method length to 15 lines
+  Max: 25
   CountAsOne:
     - array
     - hash
     - heredoc
     - method_call
+  Exclude:
+    - "test/**/*"
 
 Metrics/AbcSize:
-  Max: 20
+  Max: 25
+  Exclude:
+    - "test/**/*"
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 150
+
+# PayFast field names use ADDRESS_1, ADDRESS_2 -- mirror them in the
+# option hashes so it's obvious how each key maps to the wire format.
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Exclude:
+    - "test/**/*"

data/CHANGELOG.md

@@ -1,5 +1,218 @@
 # Changelog
 
+## [1.1.0] - 2026-05-12
+
+### Overview
+
+Easypaisa lands — three new REST endpoints + a Rails OTC voucher helper.
+Pure addition; nothing in 1.0 changes shape, no breaking changes.
+
+### Public API (new)
+
+```ruby
+# Mobile Account: customer authorises via OTP push to their Easypaisa wallet
+result  = PaygatePk::EasyPaisa::MobileAccount.charge(
+  order_id:          "lawzo-#{payment.id}",
+  amount:            1500,
+  mobile_account_no: "03001234567",
+  email:             "client@example.com"
+)
+result.success?       # response_code == "0000"
+result.transaction_id # Ericsson EWP ID
+
+# OTC voucher: customer pays cash at any Easypaisa shop
+voucher = PaygatePk::EasyPaisa::OTC.create(
+  order_id:     "lawzo-#{payment.id}",
+  amount:       1500,
+  msisdn:       "03001234567",
+  email:        "client@example.com",
+  token_expiry: 7.days.from_now
+)
+voucher.payment_token   # "40933012" -- show this to the customer
+voucher.expires_at      # Time
+
+# Inquiry: poll status until PAID
+status = PaygatePk::EasyPaisa::Inquiry.fetch(
+  order_id:    "lawzo-...",
+  account_num: PaygatePk.config.easy_paisa.account_num
+)
+status.paid?
+status.pending?
+```
+
+Rails OTC voucher helper:
+
+```erb
+<%= paygate_pk_otc_voucher(@voucher) %>
+```
+
+### Added
+
+- `PaygatePk::EasyPaisa::MobileAccount.charge` — `initiate-ma-transaction`.
+- `PaygatePk::EasyPaisa::OTC.create` — `initiate-otc-transaction`. Accepts
+  Date/Time/DateTime/String for `token_expiry`, formats to
+  `"yyyymmdd HHmmss"` internally, validates future-dated up-front.
+- `PaygatePk::EasyPaisa::Inquiry.fetch` — `inquire-transaction`. Returns
+  `InquiryResult` with `paid?` / `failed?` / `pending?` / `expired?` /
+  `blocked?` / `reversed?` predicates covering every documented
+  `transactionStatus` value.
+- `PaygatePk::EasyPaisa::Endpoints` — sandbox URL baked in;
+  `c.easy_paisa.base_url = "..."` override for production (Easypaisa
+  hands the host out at go-live).
+- `Contracts::ChargeResult` — universal value object for any REST-style
+  "take a payment" call. Carries `success?`, `failed?`, `otc?`,
+  `mobile_account?` predicates.
+- `Contracts::InquiryResult` — universal value object for status lookups.
+- `Config::EasyPaisaConfig` — `environment` / `username` / `password` /
+  `store_id` / `account_num` / `base_url` override.
+- `Util::Credentials.basic(user, pass)` — `Base64.strict_encode64`
+  helper for Easypaisa's `Credentials` HTTP header.
+- `Coercions.to_easypaisa_timestamp` — formats Date/Time to the
+  `"yyyymmdd HHmmss"` format `tokenExpiry` demands.
+- `PaygatePk::Rails::ViewHelpers#paygate_pk_otc_voucher(charge_result)`
+  — prints a styled voucher (token, amount, mobile, expiry, order id,
+  instructions). Renders a failure card with `response_message` when
+  the upstream call returned a non-`0000` `responseCode`, never a fake
+  token.
+
+### Deferred to 1.2
+
+- `EasyPaisa::Callback.verify!` — Easypaisa's integration guide mentions
+  IPN configuration in the merchant portal but does not ship the full
+  wire spec. Until that's published, host apps should poll
+  `Inquiry.fetch` after issuing an OTC voucher.
+
+### Not changed
+
+- Nothing in the PayFast surface; 1.0's contracts and call sites are
+  unchanged.
+
+## [1.0.0] - 2026-05-12
+
+### Overview
+
+Complete rewrite focused on **PayFast hosted-checkout (redirection)**.
+The gem now ships everything needed to take a one-time payment in three
+files — initializer, controller, and a one-line ERB. The 0.x server-to-
+server `Checkout` class that POSTed to `PostTransaction` has been removed;
+that endpoint is browser-side per PayFast's Merchant Integration Guide,
+and the 0.x implementation was architecturally wrong.
+
+### Public API (new)
+
+```ruby
+PaygatePk::PayFast::Redirect.build(...)   # → Contracts::RedirectRequest
+PaygatePk::PayFast::Callback.verify!(p)   # → Contracts::CallbackEvent
+```
+
+Rails view helper:
+
+```erb
+<%= paygate_pk_redirect_form(@redirect, autosubmit: true) %>
+```
+
+### Added
+
+- `PaygatePk::PayFast::Redirect` — fetches an access token, then assembles
+  every mandatory + optional PayFast form field documented in Merchant
+  Integration Guide v2.3 §3.2. Handles `items[]` arrays, shipping/billing
+  blocks, recurring flag, store override, currency override, and
+  free-form `extra_fields` passthrough.
+- `PaygatePk::PayFast::Callback` — replaces the 0.x `Webhook` class.
+  Down-cases all incoming param keys once at entry so PayFast's
+  mixed-case `Recurring_txn`/`Instrument_token`/`PaymentName` and
+  lower-snake `basket_id`/`err_code`/`validation_hash` all work without
+  caller intervention.
+- `PaygatePk::PayFast::Endpoints` — URL map keyed by environment
+  (`:sandbox`, `:production`); `c.pay_fast.base_url=` override still
+  supported for custom staging hosts.
+- `PaygatePk::Rails::ViewHelpers#paygate_pk_redirect_form` —
+  auto-submitting form helper with CSP-nonce support, autoloaded via
+  a Railtie when the gem boots inside a Rails app.
+- `Contracts::RedirectRequest` — `{ provider, action_url, http_method,
+  fields, basket_id, amount, token, raw }`.
+- `Contracts::CallbackEvent` — universal IPN/return shape with
+  `approved?` predicate. Future Easypaisa callbacks will return the
+  same struct.
+- `PaygatePk::Coercions` — `to_iso_date`, `to_amount_string`,
+  `blank?`/`present?`.
+- `Config::PayFastConfig#environment` toggle, validated setter.
+- `Config::PayFastConfig#merchant_name` (was hardcoded to `""` in 0.x).
+- `HTTP::Client`: full Faraday error mapping (`TimeoutError`,
+  `ConnectionError`, `HTTPError` cover-all), memoised connection,
+  log redaction for `SECURED_KEY`/`Authorization`/`Credentials`.
+- `Errors::CapabilityNotSupported`, `Errors::TimeoutError`,
+  `Errors::ConnectionError`, `Errors::ProviderError`.
+
+### Changed
+
+- Public namespace flattened from `PaygatePk::Providers::PayFast::*`
+  to `PaygatePk::PayFast::*`.
+- `Util::Signature::Payfast` renamed to `Util::Signature::PayFast`.
+- `Config#frozen?` renamed to `Config#configured?`. `Config#freeze!`
+  now actually deep-freezes (was a no-op `@frozen = true` boolean).
+- `Contracts::AccessToken#token` is now an alias for `#value`; the
+  primary field name is `value` to stay consistent with future
+  bearer/charge tokens.
+- Required Ruby version: `>= 3.1.0` (matches the 0.x README claim;
+  gemspec used to say `>= 2.6.0` despite Faraday 2 effectively needing
+  3.1).
+- `spec.require_paths` reduced from `%w[lib test]` to `["lib"]` so
+  test helpers are no longer shipped on the gem load path.
+- `nokogiri` removed from runtime deps (no longer parsing HTML
+  responses now that `Checkout` is gone).
+- Test suite rewritten end-to-end. 76 tests / 200 assertions /
+  96 % line coverage / 77 % branch coverage.
+
+### Removed
+
+- `Providers::PayFast::Client`              — dual facade/base-class
+  identity replaced by namespace module + `Endpoints`.
+- `Providers::PayFast::Checkout`            — server-to-server POST
+  to `PostTransaction` was wrong for the redirection flow.
+- `Providers::PayFast::Webhook`             — renamed to `Callback`.
+- `Providers::PayFast::Tokenization::Token`/`Instrument` — deferred
+  to 1.2 alongside the saved-instrument charge endpoint. Source
+  preserved in git history.
+- `Util::Html`                              — no longer needed.
+- `Contracts::HostedCheckout`               — replaced by
+  `RedirectRequest`.
+- `Contracts::WebhookEvent`                 — renamed to
+  `CallbackEvent` with broader field coverage and an `approved?`
+  predicate.
+- `Contracts::BearerToken`/`Instrument`     — deferred to 1.2.
+
+### Fixed
+
+- Callback key-casing bug. The 0.x `Webhook#verify!` only aliased
+  two specific PascalCase keys; in production PayFast sends a mix of
+  lower-snake and PascalCase keys that the old code couldn't read.
+- `ORDER_DATE` is now coerced to `YYYY-MM-DD` per spec; the 0.x
+  flow let timestamped strings through silently.
+- `SIGNATURE` is generated fresh per call (PayFast doc: "A random
+  string value"). The 0.x integration in office-management was
+  shipping the literal demo string `"SOMERANDOM-STRING"` to
+  production.
+- `CURRENCY_CODE` is now plumbed through `Redirect.build`; the 0.x
+  `Checkout` read the global `PaygatePk.config.default_currency` and
+  ignored per-call values, silently mismatching auth and checkout.
+- All `Faraday::Error` subclasses (timeout, connection failure, 5xx,
+  SSL) now surface as typed `PaygatePk` errors instead of escaping
+  as raw `Faraday::*` exceptions.
+- `SECURED_KEY` no longer leaks into Rails logs when a debug logger
+  is wired up.
+- `Config#freeze!` is now a real deep-freeze.
+
+### Migration from 0.x
+
+| 0.x | 1.0 |
+|-----|-----|
+| `PaygatePk::Providers::PayFast::Auth.new.get_access_token(...)` | `PaygatePk::PayFast::Redirect.build(...)` calls `Auth` internally — you usually don't need it directly. |
+| `PaygatePk::Providers::PayFast::Checkout.new.create!(opts: {...})` | `PaygatePk::PayFast::Redirect.build(...)` (kwargs, no `opts:` wrapper). |
+| `PaygatePk::Providers::PayFast::Webhook.new.verify!(params)` | `PaygatePk::PayFast::Callback.verify!(params)` |
+| `c.pay_fast.base_url = "..."` (hand-typed sandbox host) | `c.pay_fast.environment = :sandbox` (override only when PayFast hands you a custom staging URL). |
+| Hand-built 18-field hidden form ERB | `<%= paygate_pk_redirect_form(@redirect) %>` |
+
 ## [0.2.0] - 2025-10-10
 
 - Added: IPN verification, Tokenization 3.1 & 3.15.

data/Gemfile.lock

@@ -1,24 +1,49 @@
 PATH
   remote: .
   specs:
-    paygate_pk (0.2.3)
+    paygate_pk (1.1.0)
       faraday (>= 2.7)
       faraday-retry (>= 2.0)
       json
-      nokogiri (>= 1.16, < 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionview (8.1.3)
+      activesupport (= 8.1.3)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
+    base64 (0.3.0)
     bigdecimal (3.2.3)
+    builder (3.3.0)
     byebug (12.0.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
     crack (1.0.0)
       bigdecimal
       rexml
+    crass (1.0.6)
     docile (1.4.1)
+    drb (2.2.3)
+    erubi (1.13.1)
     faraday (2.13.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
@@ -28,16 +53,21 @@ GEM
     faraday-retry (2.3.2)
       faraday (~> 2.0)
     hashdiff (1.2.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
     json (2.12.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
     minitest (5.25.5)
     net-http (0.6.0)
       uri
-    nokogiri (1.18.9-x86_64-darwin)
+    nokogiri (1.19.3-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-linux-gnu)
+    nokogiri (1.19.3-x86_64-linux-gnu)
       racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.8.0)
@@ -46,6 +76,13 @@ GEM
     prism (1.5.1)
     public_suffix (6.0.2)
     racc (1.8.1)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
     rainbow (3.1.1)
     rake (13.3.0)
     regexp_parser (2.10.0)
@@ -65,16 +102,19 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
-    uri (1.0.3)
+    uri (1.1.1)
     webmock (3.25.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -85,6 +125,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  actionview (>= 7.0)
   byebug
   minitest (~> 5.0)
   paygate_pk!