paygate_pk 0.2.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2736cc49f2b203095fdacfdecba63406ee29e6d1bd5672f910bf3826478d3310
-  data.tar.gz: 40d83470713f8cead797d7e6aac1ca0127c8d18672882a2883a6c3cfc1ad43a2
+  metadata.gz: 9705a5a01a864f4d8e318e11448540887091d6ef3d7294c1abaeb00df24a4cba
+  data.tar.gz: d0408482c432003735671608da1a46e71f1bae509c8b7f455d7dcbd1dd99865e
 SHA512:
-  metadata.gz: 4c7bd5fc036b0f16b293dd2347d2a13f305ac6f6d8d1c0b3f9a5b41bf1d283be4d3e0742948ad26609e9fa5c6db203130751d4cf6c22f759ab8bd3ca98437f73
-  data.tar.gz: d6591bd6735779a9ac1bb4eaf4e30b3e80c71a7ed59a75097253b30714e4f2ffb5818921c53a247dc37b5c3db4d90b572c24b761839483d528d75765c047dd30
+  metadata.gz: 95ff08faf44d5d6bb64311e24b02ce077ac0e19c28b33ce322acd647f1728cd3702b5af08f42bf89dd9d80f1378ccff424ad510e60e30c78de264d2b580acebb
+  data.tar.gz: 43e241ecdaa260a068e5224f0a560845b09a07de9f61cb2cef667796e8611697b50070d55f7d6ddee6a66b431794444ad748bb63128ac498272a86e9cb7a569d

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,38 @@ 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
+
+# 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,131 @@
 # Changelog
 
+## [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.2)
+    paygate_pk (1.0.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!

data/README.md

@@ -1,118 +1,229 @@
 # PaygatePk
 
-Unified Ruby wrapper for PayFast (and soon Easypaisa) payments in Pakistan.
+Unified Ruby/Rails client for Pakistani payment gateways.
 
-This gem provides a clean, provider-agnostic interface to obtain access tokens and create hosted checkouts with PayFast. It wraps HTTP details, validates required fields, and exposes simple, Ruby-friendly objects. Rails-friendly configuration is included; IPN verification and recurring/tokenized flows are on the roadmap.
+**1.0 ships:** PayFast hosted-checkout (redirection flow) and callback verification, with a one-line Rails view helper.
+**1.1 will ship:** Easypaisa REST APIs (Mobile Account, OTC voucher, Inquiry).
+**1.2 will ship:** PayFast tokenization / saved-instrument charge.
+
+The gem wraps every PayFast field documented in *Merchant Integration Guide v2.3*, validates required inputs, normalises dates and amounts, and returns plain Struct value objects you can pass around your Rails app.
 
 ## Requirements
 
 - Ruby ≥ 3.1
-- Faraday (runtime, included by gemspec)
-- Nokogiri (runtime, for HTML redirect parsing, included)
-- (Dev) Byebug, SimpleCov, RuboCop — optional
+- Faraday ≥ 2.7
+- (Rails apps) ActionView ≥ 7.0 for the view helper
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add "paygate_pk", "~> 0.2.0"
-
-If bundler is not being used to manage dependencies, install the gem by executing:
+```sh
+bundle add paygate_pk
+```
 
-    $ gem install "paygate_pk", "~> 0.2.0"
+Or in a Gemfile:
 
-## Usage
+```ruby
+gem "paygate_pk", "~> 1.0"
+```
 
-# Initializer
+## Configure
 
 ```ruby
 # config/initializers/paygate_pk.rb
-
 PaygatePk.configure do |c|
   c.default_currency = "PKR"
-  c.user_agent = "paygate_pk/#{PaygatePk::VERSION}"
 
-  # PayFast base host only; endpoints include /Ecommerce/api internally
-
-  c.pay_fast.base_url = "https://ipguat.apps.net.pk"
-  c.pay_fast.merchant_id = ENV.fetch("PAYFAST_MERCHANT_ID")
-  c.pay_fast.secured_key = ENV.fetch("PAYFAST_SECURED_KEY")
-  c.pay_fast.api_base_url = "https://api.getfrompayfast.com"
-
-  # Optional: tune timeouts & retries
-
-  c.timeouts = { open_timeout: 5, read_timeout: 10 }
-  c.retry = { max: 2, interval: 0.2, backoff_factor: 2.0, retry_statuses: [429, 500, 502, 503, 504] }
+  c.pay_fast.environment   = Rails.env.production? ? :production : :sandbox
+  c.pay_fast.merchant_id   = Rails.application.credentials.dig(:pay_fast, :merchant_id)
+  c.pay_fast.secured_key   = Rails.application.credentials.dig(:pay_fast, :secured_key)
+  c.pay_fast.merchant_name = "Acme Store"
+  c.pay_fast.store_id      = Rails.application.credentials.dig(:pay_fast, :store_id)  # optional
 end
 ```
 
-## QuickStart
+Sandbox URL is built in. If PayFast hands you a bespoke staging or production host, override with `c.pay_fast.base_url = "https://..."`.
 
-# 1) Get Access Token (PayFast)
+After the block runs the config is deep-frozen for the lifetime of the process. Use `PaygatePk.reset_config!` in console/tests to start over.
 
-```ruby
+## Take a one-time payment via PayFast redirect
 
-client = PaygatePk::Providers::PayFast::Auth.new
+### 1. Build the redirect
 
-token_obj = auth.get_access_token(
-basket_id: "B-1001",
-amount: 1500
+```ruby
+class Subscription::PaymentsController < ApplicationController
+  def create
+    @redirect = PaygatePk::PayFast::Redirect.build(
+      basket_id:    "sp-#{payment.id}",
+      amount:       1500,                                # rupees
+      description:  "Pro plan — monthly",
+      customer:     {
+        mobile: current_user.mobile,                     # real 03xx mobile (mandatory)
+        email:  current_user.email,
+        name:   current_user.name                        # optional
+      },
+      success_url:  success_subscription_payments_url,
+      failure_url:  failed_subscription_payments_url,
+      checkout_url: webhooks_pay_fast_url,               # optional backend IPN ping
+      recurring:    false
+    )
+  end
+end
+```
 
-# currency: "PKR", # optional; defaults to PaygatePk.config.default_currency
+### 2. Render the auto-submitting form
 
-# endpoint: "/Ecommerce/api/Transaction/GetAccessToken" # optional override
+```erb
+<%# app/views/subscription/payments/create.html.erb %>
+<%= paygate_pk_redirect_form(@redirect, autosubmit: true) %>
+```
 
-)
+The customer's browser is now on PayFast. They pick a bank/card/wallet, enter their OTP, and PayFast redirects them back to your `success_url` (or `failure_url`).
 
-puts token_obj.token # => "ACCESS_TOKEN_STRING"
+### 3. Verify the return / IPN
 
+```ruby
+class Subscription::PaymentsController < ApplicationController
+  def success
+    event = PaygatePk::PayFast::Callback.verify!(request.parameters)
+    if event.approved?
+      payment = SubscriptionPayment.find_by(basket_id: event.basket_id)
+      payment&.mark_completed!(transaction_id: event.transaction_id, amount: event.amount)
+      redirect_to dashboard_path, notice: "Payment received."
+    else
+      redirect_to dashboard_path, alert: "Payment failed: #{event.message}"
+    end
+  rescue PaygatePk::SignatureError
+    head :bad_request
+  end
+end
 ```
 
-# 2) Verify IPN
+For the server-to-server IPN (PayFast also POSTs to `CHECKOUT_URL`), wire the same call into your webhook controller — it's the more reliable source of truth (it doesn't depend on the customer's browser making it back).
 
-```ruby
-verified_data  = client.verify_ipn!(request.params)
-
-:provider,          # Symbol e.g., :payfast
-:transaction_id,    # String or nil
-:basket_id,         # String
-:order_date,        # String (YYYY-MM-DD) or Time/Date if you coerce later
-:approved,          # Boolean (true if err_code == "000")
-:code,              # Provider code, e.g., "000"
-:message,           # Human-readable message
-:amount,            # String/Integer (as received)
-:currency,          # String "PKR" etc.
-:instrument_token,  # String or nil (for tokenized flows)
-:recurring,         # Boolean
-:raw,               # Original params Hash (unmodified input)
+## All redirect options
 
+```ruby
+PaygatePk::PayFast::Redirect.build(
+  basket_id:    "B-1001",
+  amount:       1500,
+  description:  "Order #1001",
+  customer:     { mobile: "03001234567", email: "buyer@x.com", name: "Talha" },
+  success_url:  "https://app/success",
+  failure_url:  "https://app/failure",
+
+  # — optional —
+  currency:               "PKR",            # defaults to config.default_currency
+  order_date:             Date.today,       # Date / Time / String, coerced to YYYY-MM-DD
+  checkout_url:           "https://app/ipn",
+  store_id:               "102-ABC",        # overrides config.pay_fast.store_id
+  recurring:              false,
+  tran_type:              "ECOMM_PURCHASE", # overrides config.pay_fast.tran_type
+  processing_type:        "HYBRID_TOKEN",
+  instrument_token:       "tok-from-saved-card",
+  transaction_instrument: 3,                # 1=bank, 2=UnionPay, 3=card, 4=wallet
+
+  items: [
+    { sku: "SKU-1", name: "Widget", price: 100, qty: 2 },
+    { sku: "SKU-2", name: "Gizmo",  price: 50,  qty: 1 }
+  ],
+
+  shipping: {
+    name: "Talha", address_1: "House 9", address_2: "St 4",
+    state: "Punjab", city: "Lahore", postal_code: "54000", method: "Courier"
+  },
+  billing:  { name: "Talha", city: "Lahore", address_1: "House 9" },
+
+  country:              "PK",
+  customer_ip:          request.remote_ip,
+  merchant_customer_id: current_user.id.to_s,
+  merchant_user_agent:  request.user_agent,
+
+  extra_fields:         { "CUSTOM_X" => "value" }  # forward-compatible passthrough
+)
 ```
 
-# Error handling
+## Contracts
+
+### `Contracts::RedirectRequest`
+
+What `Redirect.build` returns, what the view helper consumes.
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:pay_fast` |
+| `action_url` | `String` | Where the browser POSTs |
+| `http_method` | `Symbol` | `:post` |
+| `fields` | `Hash<String,String>` | Every PayFast form field |
+| `basket_id` | `String` | Echo |
+| `amount` | `String` | Echo |
+| `token` | `String` | The access token |
+| `raw` | `Hash` | Raw token-API response |
+
+### `Contracts::CallbackEvent`
+
+What `Callback.verify!` returns.
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:pay_fast` |
+| `transaction_id` | `String?` |  |
+| `basket_id` | `String` |  |
+| `order_date` | `String` | `YYYY-MM-DD` |
+| `approved` / `approved?` | `Boolean` | `true` iff `err_code == "000"` |
+| `code` | `String` | PayFast `err_code` |
+| `message` | `String` | PayFast `err_msg` |
+| `amount` | `String` | `transaction_amount` |
+| `merchant_amount` | `String` |  |
+| `discounted_amount` | `String` |  |
+| `currency` | `String` |  |
+| `payment_method` | `String` | "card", "account", "wallet" |
+| `instrument_token` | `String?` |  |
+| `recurring` | `Boolean` |  |
+| `raw` | `Hash` | Original params, unmodified |
+
+## Errors
+
+All errors inherit from `PaygatePk::Error`:
+
+| Class | Raised when |
+|---|---|
+| `ConfigurationError` | Required config is missing (e.g. `merchant_id`) |
+| `ValidationError` | A required method argument is missing or blank (see `#details[:missing]`) |
+| `HTTPError` | Non-2xx response from the gateway (carries `#status`, `#body`) |
+| `TimeoutError` | Network timeout (subclass of `HTTPError`) |
+| `ConnectionError` | DNS / SSL / refused connection (subclass of `HTTPError`) |
+| `AuthError` | Token endpoint returned 2xx but the body had no `ACCESS_TOKEN` |
+| `SignatureError` | Callback `validation_hash` mismatch or required field missing |
+| `CapabilityNotSupported` | Provider asked for a flow it doesn't implement (1.1+) |
+| `ProviderError` | Provider business-rule failure (carries `#code`, `#response`) |
+
+## Non-Rails apps
+
+The view helper is the only Rails-specific piece — and it's autoloaded only if `Rails::Railtie` is present. Everything else works in plain Ruby / Sinatra / Hanami:
 
-All errors inherit from PaygatePk::Error:
-
-- PaygatePk::ConfigurationError — missing/invalid configuration (e.g., merchant_id, secured_key, or base_url).
-- PaygatePk::ValidationError — missing required method arguments or required form fields.
-- PaygatePk::HTTPError — network/HTTP failure (wraps response status & body).
-- PaygatePk::AuthError — auth call succeeded at HTTP level but token missing/invalid in body.
-- PaygatePk::SignatureError — reserved for webhook/IPN verification (upcoming).
-- PaygatePk::ProviderError — reserved for provider business-rule failures.
+```ruby
+redirect = PaygatePk::PayFast::Redirect.build(...)
+# Render redirect.fields as <input type="hidden"> in your own template.
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+bin/setup
+bundle exec rake test            # 76 examples, 200 assertions, 0 failures
+bundle exec rubocop
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Roadmap
+
+- **1.1** — Easypaisa: Mobile Account, OTC voucher, Inquiry, IPN. New helper `paygate_pk_otc_voucher`. Adds `c.easy_paisa.*` config block.
+- **1.2** — PayFast tokenization: bearer-token auth (`/api/token`), saved instruments (`/api/user/instruments`), charge-against-saved-instrument.
+- **1.x+** — Additional Pakistani gateways (JazzCash, HBL, SafePay) under the same `Contracts::RedirectRequest`/`CallbackEvent` shape so host code stays unchanged.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/paygate_pk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/paygate_pk/blob/master/CODE_OF_CONDUCT.md).
+Issues and PRs at <https://github.com/qbitechs/paygate_pk>.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the PaygatePk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/paygate_pk/blob/master/CODE_OF_CONDUCT.md).
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/paygate_pk/coercions.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "date"
+
+module PaygatePk
+  # Small set of input normalisers shared across providers.
+  # All methods are pure and side-effect-free.
+  module Coercions
+    module_function
+
+    DATE_ISO = "%Y-%m-%d"
+
+    # Returns "YYYY-MM-DD" (PayFast's ORDER_DATE format) for Date/Time/DateTime
+    # or a String already in that shape. nil-tolerant.
+    def to_iso_date(value)
+      return nil if value.nil?
+      return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+      case value
+      when Date, Time, DateTime then value.strftime(DATE_ISO)
+      when String               then Date.parse(value).strftime(DATE_ISO)
+      else
+        raise ArgumentError, "cannot coerce #{value.inspect} to ISO date"
+      end
+    end
+
+    # Render a numeric amount as a non-scientific decimal String. PayFast
+    # accepts TXNAMT as a string; 1500 → "1500", 1500.5 → "1500.5".
+    def to_amount_string(value)
+      return nil if value.nil?
+
+      case value
+      when Float, Rational, BigDecimal then format("%g", value)
+      else value.to_s
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+  end
+end