xero-kiwi 0.1.0

data/docs/retries-and-rate-limits.md

@@ -0,0 +1,224 @@
+# Retries and rate limits
+
+This doc explains how XeroKiwi handles transient failures: rate limiting, server
+errors, and network blips. Most of the time you don't need to know any of
+this — the defaults are sensible. Read on if you need to tune the retry
+policy or you want to understand what's happening when a request mysteriously
+takes 4 seconds.
+
+## Xero's rate limits
+
+Xero enforces three separate rate limits, all returned with HTTP 429:
+
+| Limit | Default | Header indicator |
+|-------|---------|------------------|
+| Per-minute (per tenant) | 60 calls | `X-Rate-Limit-Problem: minute` |
+| Daily (per tenant) | 5,000 calls | `X-Rate-Limit-Problem: day` |
+| Per-app per-minute | 10,000 calls | `X-Rate-Limit-Problem: appminute` |
+| Concurrent | 10 simultaneous requests | (no specific problem header) |
+
+Plus a `Retry-After` header on every 429 telling you how many seconds to
+wait before trying again.
+
+## What XeroKiwi does automatically
+
+XeroKiwi sets up a `faraday-retry` middleware that handles transient failures
+without any code from you. The default retry policy:
+
+| Setting | Default | Why |
+|---------|---------|-----|
+| `max` | 4 retries | High enough to ride out most rate-limit pauses, low enough to fail fast on real outages. |
+| `interval` | 0.5 s | Initial wait. |
+| `backoff_factor` | 2 | Exponential backoff. So waits are roughly 0.5s, 1s, 2s, 4s. |
+| `interval_randomness` | 0.5 | ±50% jitter on each wait, so a herd of clients doesn't refresh in lockstep. |
+| `retry_statuses` | `[429, 502, 503, 504]` | Statuses that get retried. |
+| `methods` | All HTTP methods | Including POST/PUT/DELETE. (Xero's idempotency makes this safe.) |
+| `exceptions` | `Faraday::ConnectionFailed`, `Faraday::TimeoutError`, `Faraday::RetriableResponse`, `Errno::ETIMEDOUT` | Transport-level failures that get retried. |
+
+### Retry-After is honoured
+
+`faraday-retry` automatically respects the `Retry-After` header on 429
+responses. So if Xero says "wait 30 seconds," XeroKiwi waits 30 seconds before
+retrying — not the exponential backoff schedule. This is the whole reason
+to use a real retry middleware instead of rolling your own.
+
+### Which 5xx are retried
+
+XeroKiwi retries `502 Bad Gateway`, `503 Service Unavailable`, and `504 Gateway
+Timeout`. These are the canonical "the upstream is having a temporary
+problem" statuses.
+
+**500 Internal Server Error is deliberately NOT retried.** A 500 usually
+means Xero hit a real bug in handling your request — retrying the same
+request will give the same 500. If you want to retry 500s in your own
+code, catch `XeroKiwi::ServerError` and handle it explicitly.
+
+### What happens after retries are exhausted
+
+| Scenario | Final exception |
+|----------|-----------------|
+| All retries returned 429 | `XeroKiwi::RateLimitError` (with `retry_after` and `problem` attributes) |
+| All retries returned 502/503/504 | `XeroKiwi::ServerError` |
+| All retries failed at the transport level | The underlying `Faraday::ConnectionFailed` / `Faraday::TimeoutError` |
+
+The retried request count includes the original attempt, so `max: 4` means
+**up to 5 total HTTP requests** before giving up.
+
+## Customising the retry policy
+
+Pass `retry_options:` to `XeroKiwi::Client.new`. The hash is merged into XeroKiwi's
+defaults, so you only specify what you want to change:
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  retry_options: {
+    max:      8,    # try up to 8 retries
+    interval: 1.0   # initial 1s wait instead of 0.5s
+  }
+)
+```
+
+### Common customisations
+
+**Aggressive retries for batch jobs that can wait:**
+
+```ruby
+retry_options: {
+  max:            10,
+  interval:       2.0,
+  backoff_factor: 2
+}
+# Waits up to ~17 minutes total (2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 seconds)
+```
+
+**No retries (e.g. for tests):**
+
+```ruby
+retry_options: { max: 0 }
+```
+
+**Tight retries with no jitter (also for tests):**
+
+```ruby
+retry_options: {
+  max:                 2,
+  interval:            0,
+  interval_randomness: 0,
+  backoff_factor:      1
+}
+```
+
+This is what XeroKiwi's own test suite uses to keep specs deterministic and
+fast.
+
+**Adding 500 to the retry list** (against my advice, but sometimes you
+have a known-flaky upstream):
+
+```ruby
+retry_options: {
+  retry_statuses: [429, 500, 502, 503, 504]
+}
+```
+
+### One thing you must NOT remove
+
+XeroKiwi's default `exceptions:` list includes `Faraday::RetriableResponse`,
+which is the *internal* signal `faraday-retry` uses to flag a status-code
+retry. **It must stay in the list**, or the retry middleware can't catch
+its own retry signal and 429s/503s will never be retried — they'll bubble
+straight up as raw `Faraday::RetriableResponse` exceptions.
+
+If you override `exceptions:`, make sure to include the four defaults:
+
+```ruby
+retry_options: {
+  exceptions: [
+    Faraday::ConnectionFailed,
+    Faraday::TimeoutError,
+    Faraday::RetriableResponse, # ← critical
+    Errno::ETIMEDOUT,
+    MyOwnException               # add your own
+  ]
+}
+```
+
+In practice, you almost never need to override this list — the defaults
+cover everything Xero will throw at you.
+
+## How the middleware stack is wired
+
+The order of Faraday middleware matters and was the source of one nasty
+bug during development. The chain looks like this:
+
+```
+ResponseHandler  ← outermost, catches errors AFTER retries are exhausted
+↓
+Retry           ← retries 429/503/etc on the way back, respects Retry-After
+↓
+JSON            ← parses response bodies
+↓
+Adapter         ← actually makes the HTTP call
+```
+
+The trick is putting **`ResponseHandler` outside `Retry`**. If they were the
+other way round, a 429 would go: adapter returns env → JSON parses →
+ResponseHandler raises `RateLimitError` → Retry catches the exception →
+needs to know about `RateLimitError` to know to retry it. That's brittle.
+
+By putting Retry on the inside, the retry middleware sees raw HTTP envs
+with status 429 and uses its own `retry_statuses` config to decide what to
+do. ResponseHandler only sees the *final* env (after retries are done) and
+maps it to a XeroKiwi exception.
+
+You don't need to think about any of this — it's the gem's job — but if
+you ever subclass the client or insert your own middleware, this is the
+ordering to preserve.
+
+## Token refresh on 401
+
+Token refresh isn't part of the retry middleware — it's handled separately
+by `XeroKiwi::Client#with_authenticated_request` (see [Client — request
+lifecycle](client.md#the-request-lifecycle)). The two systems compose
+cleanly:
+
+1. Client wraps the call in `with_authenticated_request`.
+2. The retry middleware retries 429/503 inside the wrapper.
+3. If retries are exhausted with a 401, ResponseHandler raises
+   `AuthenticationError`.
+4. `with_authenticated_request` catches it, refreshes the token, and
+   retries the *outer* call exactly once.
+
+Crucially, step 4 retries the **whole call**, including the retry
+middleware. So a single API call can trigger up to `max + 1` HTTP attempts
+*twice*: once before the refresh, once after.
+
+## Concurrency notes
+
+The retry middleware is per-request, not per-client, so multiple concurrent
+requests on the same `XeroKiwi::Client` each get their own retry budget. Two
+threads racing on a rate-limited tenant will each see independent
+retry/backoff schedules — they won't coordinate.
+
+If you need cross-thread coordination (e.g. "all threads should pause when
+any one of them hits a 429"), build it at the application level using a
+shared semaphore or rate limiter. XeroKiwi doesn't ship one, because the right
+shape depends entirely on your traffic patterns.
+
+## Things the retry layer deliberately does NOT do
+
+- **No retry on 500.** 500s are usually persistent. If you want them
+  retried, add to `retry_statuses` explicitly.
+- **No retry on 4xx (other than 429).** 4xx means the client did something
+  wrong; retrying won't fix it. The exception is 429 (rate limit), which is
+  classified as 4xx but is fundamentally a "wait and try again" signal.
+- **No global rate limiter.** XeroKiwi reacts to 429s as they happen but
+  doesn't proactively throttle — it'll happily fire 100 concurrent requests
+  and rely on Xero's 429s to slow things down. If you need proactive
+  throttling, do it at your job-queue level.
+- **No retry budget across calls.** Each `client.connections` (or any
+  other call) gets a fresh `max` retries. There's no concept of "this client
+  has had too many retries today and should stop trying."
+- **No automatic Sidekiq integration.** When `RateLimitError` raises, it's
+  up to your job to re-enqueue using the `retry_after` value. XeroKiwi exposes
+  it; what you do with it is your call.

data/docs/tokens.md

@@ -0,0 +1,339 @@
+# Tokens
+
+This doc covers everything about token *state* in XeroKiwi: the `XeroKiwi::Token`
+value object, how the client refreshes tokens automatically, the persistence
+callback, manual refresh, revocation, and the gotchas around token rotation.
+
+For the OAuth *protocol* (building authorise URLs, exchanging codes), see
+[OAuth](oauth.md).
+
+## The `XeroKiwi::Token` value object
+
+A `XeroKiwi::Token` is an immutable bundle of OAuth state — the access/refresh
+pair plus all the metadata Xero returns at refresh time:
+
+```ruby
+token = XeroKiwi::Token.new(
+  access_token:  "ya29...",
+  refresh_token: "1//...",
+  expires_at:    Time.now + 1800,
+  token_type:    "Bearer",
+  id_token:      "eyJhbG...",
+  scope:         "openid offline_access accounting.transactions"
+)
+```
+
+You usually don't construct one by hand — it's what `OAuth#exchange_code` and
+`OAuth#refresh_token` (via `TokenRefresher`) return, and what
+`XeroKiwi::Client#token` exposes.
+
+### Constructor options
+
+| Option | Type | Default | Required |
+|--------|------|---------|----------|
+| `access_token:` | `String` | — | Yes |
+| `refresh_token:` | `String` | `nil` | No |
+| `expires_at:` | `Time` | `nil` | No |
+| `token_type:` | `String` | `"Bearer"` | No |
+| `id_token:` | `String` | `nil` | No |
+| `scope:` | `String` | `nil` | No |
+
+### Building from a Xero OAuth response
+
+`Token.from_oauth_response` converts a Xero token-endpoint payload (which
+returns `expires_in` as seconds-from-now) into a Token with an absolute
+`expires_at`:
+
+```ruby
+payload = {
+  "access_token"  => "...",
+  "refresh_token" => "...",
+  "expires_in"    => 1800,
+  "token_type"    => "Bearer",
+  "scope"         => "openid offline_access ...",
+  "id_token"      => "..."
+}
+
+token = XeroKiwi::Token.from_oauth_response(payload)
+# expires_at is computed as Time.now + 1800
+
+# You can also pin the anchor time, which is useful for tests:
+token = XeroKiwi::Token.from_oauth_response(payload, requested_at: some_time)
+```
+
+This method accepts both string-keyed and symbol-keyed payloads.
+
+## Expiry helpers
+
+| Method | What it returns |
+|--------|-----------------|
+| `token.expired?(now: Time.now)` | `true` if `expires_at` is in the past. **Returns `false` when `expires_at` is nil** — without an expiry we have no signal to act on. |
+| `token.expiring_soon?(within: 60, now: Time.now)` | `true` if `expires_at` falls within `within` seconds of `now`. The default 60s window is what `XeroKiwi::Client` uses for its proactive refresh. |
+| `token.valid?(now: Time.now)` | `true` if the access token is non-empty AND not expired. |
+| `token.refreshable?` | `true` if a non-empty refresh token is present. |
+
+The `now:` keyword arg lets you inject a fixed time for testing.
+
+### Why `expired?` returns false on nil `expires_at`
+
+If you don't know when the token expires (e.g. you loaded a credential from
+storage that was created before you tracked expiry), XeroKiwi treats it as
+"unknown" and assumes valid. The fallback is reactive — your first 401 will
+trigger a refresh.
+
+Set `expires_at:` whenever you can; it's strictly better than relying on
+reactive refresh, which costs you a wasted API call before the refresh fires.
+
+## Refreshing the token
+
+There are two ways the client refreshes tokens for you:
+
+### Automatic (preferred)
+
+If you constructed the client with refresh credentials, every API call goes
+through these checks:
+
+1. **Proactive** — before the request fires, if `token.expiring_soon?`
+   returns true, the client refreshes first.
+2. **Reactive** — if the request returns 401 anyway, the client refreshes
+   and retries the request once.
+
+You don't have to do anything to opt in — it's the default behaviour. Just
+make sure to provide all the refresh ingredients at construction time:
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token:     credential.access_token,
+  refresh_token:    credential.refresh_token,
+  expires_at:       credential.expires_at,
+  client_id:        ENV.fetch("XERO_CLIENT_ID"),
+  client_secret:    ENV.fetch("XERO_CLIENT_SECRET"),
+  on_token_refresh: ->(token) { credential.update!(token.to_h) }
+)
+```
+
+### Manual
+
+If you need to force a refresh outside of an API call:
+
+```ruby
+new_token = client.refresh_token!
+# or just:
+client.refresh_token!
+client.token # the new token
+```
+
+`refresh_token!` raises `XeroKiwi::TokenRefreshError` if:
+
+- The client has no refresh credentials (`client_id`/`client_secret` missing).
+- The current token has no `refresh_token`.
+- Xero rejects the refresh (e.g. `invalid_grant` because the refresh token
+  was already rotated by another process — see
+  [the rotation gotcha](#refresh-token-rotation) below).
+
+### `client.can_refresh?`
+
+True if and only if all the ingredients are in place: client credentials *and*
+a non-empty refresh token. Use this to check before calling `refresh_token!`
+explicitly:
+
+```ruby
+if client.can_refresh?
+  client.refresh_token!
+else
+  # surface a "needs re-auth" state
+end
+```
+
+## The `on_token_refresh` callback
+
+This is the most important integration point in the gem. Every time the
+client refreshes the token — proactively, reactively, or via a manual
+`refresh_token!` — it calls your callback with the new `XeroKiwi::Token`:
+
+```ruby
+on_token_refresh: ->(token) { credential.update!(token.to_h) }
+```
+
+The callback fires from inside the refresh mutex, so by the time it runs,
+the new token is the canonical in-memory state. If you don't persist it,
+the next process to load the credential will use the now-invalid old refresh
+token and fail.
+
+### Persistence patterns
+
+Different applications store credentials differently. The callback works the
+same in all of them — XeroKiwi just hands you the new token and trusts you to
+put it somewhere:
+
+```ruby
+# Rails / ActiveRecord
+on_token_refresh: ->(token) { credential.update!(access_token: token.access_token, refresh_token: token.refresh_token, expires_at: token.expires_at) }
+
+# Sequel
+on_token_refresh: ->(token) { DB[:credentials].where(id: id).update(token.to_h) }
+
+# Local CLI tool with a JSON file
+on_token_refresh: ->(token) { File.write("~/.xero", JSON.dump(token.to_h)) }
+
+# Background sync architecture: write through a queue so persistence
+# happens in a single-writer worker (avoids the rotation race below)
+on_token_refresh: ->(token) { TokenWriter.enqueue(tenant_id, token.to_h) }
+```
+
+The callback receives a `XeroKiwi::Token`, so you can call `.to_h` to get a
+plain hash, or pick fields off it directly.
+
+## Refresh token rotation
+
+**Xero rotates refresh tokens on every use.** When you successfully refresh,
+Xero returns a *new* refresh token alongside the new access token, and the
+old refresh token is immediately invalidated. There is no way to recover it.
+
+This is the source of the most common production bug with OAuth-based
+integrations:
+
+> **Two workers race.** Worker A and Worker B both load the same credential
+> row from the database, both notice the token is expiring, and both try to
+> refresh. Worker A wins, gets a new refresh token, persists it. Worker B
+> tries to use the old refresh token (which it loaded before A persisted)
+> and gets `invalid_grant`. From Worker B's perspective, the credential
+> looks dead — but it's not, A just rotated it.
+
+XeroKiwi mitigates this in two ways:
+
+1. **Single-process safety.** A `Mutex` around refresh, with a double-check
+   inside, prevents multiple threads in the *same process* from racing.
+2. **Single-process safety only.** The mutex doesn't help across processes.
+
+### Multi-process refresh
+
+If you have multiple processes sharing one credential (e.g. Sidekiq workers,
+multiple Rails servers behind a load balancer), the in-process mutex doesn't
+protect you. Options:
+
+#### Option A — Single-writer architecture
+
+Funnel all refreshes through one process. When a worker notices a token is
+expiring, it enqueues a "please refresh this credential" job to a single
+worker that handles refresh exclusively. The worker that requested the
+refresh waits for the result (or just retries with the freshly-loaded
+credential).
+
+This is the cleanest approach but requires architecture work.
+
+#### Option B — Catch the race and reload
+
+When `XeroKiwi::TokenRefreshError` fires, the most common cause is "another
+process already refreshed." Reload the credential from the database — if
+the refresh token has changed, use the new one and retry. If it's the
+same, the credential is genuinely dead and you need to re-authorise.
+
+```ruby
+def with_xero_client
+  credential = XeroCredential.find(id)
+  client = build_client(credential)
+
+  yield client
+
+rescue XeroKiwi::TokenRefreshError
+  credential.reload
+  if credential.refresh_token != client.token.refresh_token
+    retry # another process refreshed; pick up their new token
+  else
+    credential.update!(needs_reauth: true)
+    raise
+  end
+end
+```
+
+#### Option C — Distributed lock
+
+Use Redis (or Postgres advisory locks, etc.) to take a distributed lock
+keyed by credential ID before refreshing. Slower but more robust than
+Option B.
+
+XeroKiwi doesn't ship any of these — they're application-level decisions that
+depend on your infrastructure. But the existence of `client.token.refreshable?`
+and the explicit `XeroKiwi::TokenRefreshError` give you the building blocks.
+
+## Revoking tokens
+
+Revocation tells Xero "please invalidate this token." Use it for "disconnect
+Xero from my app" / logout flows.
+
+### Via `XeroKiwi::Client`
+
+```ruby
+client.revoke_token!
+credential.destroy! # caller's job
+```
+
+This:
+
+1. POSTs to `https://identity.xero.com/connect/revocation` with the client's
+   current refresh token.
+2. Returns `true` on success.
+3. Raises `XeroKiwi::TokenRefreshError` if the client has no refresh capability,
+   or `XeroKiwi::AuthenticationError` if Xero rejects the revoke.
+
+After revocation, **treat the client as dead.** Subsequent API calls will
+401, and reactive refresh will fail because the refresh token is gone too.
+XeroKiwi doesn't set an internal flag on the client — there's no
+`client.revoked?` predicate — because the right thing for a caller to do
+post-revocation is throw the client away, not keep using it.
+
+### Via `XeroKiwi::OAuth` directly
+
+If you have a refresh token in hand and don't want to construct a Client:
+
+```ruby
+oauth = XeroKiwi::OAuth.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET")
+  # no redirect_uri needed for revoke-only
+)
+
+oauth.revoke_token(refresh_token: stored_refresh_token)
+```
+
+`OAuth#revoke_token` is the protocol-level method; `Client#revoke_token!`
+is a thin convenience over it.
+
+### Why we always pass the refresh token, not the access token
+
+Per RFC 7009 you can revoke either the access token or the refresh token.
+Xero accepts both. **But** revoking the access token only kills that one
+access token — the refresh token stays alive and can mint a new one
+immediately. Revoking the refresh token invalidates the entire chain.
+
+XeroKiwi enforces the refresh-token path: `Client#revoke_token!` raises if you
+don't have a refresh token, rather than silently revoking the access token
+(which would do almost nothing useful). This avoids a foot-gun where users
+think they've logged out but the token is still happily working.
+
+## Inspecting tokens
+
+`XeroKiwi::Token#inspect` redacts the access token so it doesn't accidentally
+end up in logs:
+
+```ruby
+token.inspect
+# => "#<XeroKiwi::Token access_token=[FILTERED] refreshable=true expires_at=2026-04-09 14:30:00 UTC>"
+```
+
+`token.to_h` does NOT redact — it returns the full hash for storage. Don't
+log the full hash.
+
+## Things tokens deliberately do NOT do
+
+- **No automatic expiry from `Time.now`.** Tokens are immutable; their
+  expiry is fixed at construction. The "expiring" predicates are
+  computations against a `now:` parameter, not stateful checks.
+- **No comparison of access token bytes.** `XeroKiwi::Token#==` compares the
+  full hash, which works for "is this the same token?" but isn't a security
+  check. Don't use it for authentication.
+- **No JWT decoding of the access token.** Xero's access tokens are JWTs,
+  but XeroKiwi doesn't peek at their contents. The `id_token` is the OIDC
+  identity assertion you should care about; see [OAuth](oauth.md#id-token-verification)
+  for verifying it.

data/lib/xero_kiwi/accounting/address.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Accounting
+    # A Xero address. Used by Organisation, Contact, and other resources.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/types#addresses
+    class Address
+      ATTRIBUTES = {
+        address_type:   "AddressType",
+        address_line_1: "AddressLine1",
+        address_line_2: "AddressLine2",
+        address_line_3: "AddressLine3",
+        address_line_4: "AddressLine4",
+        city:           "City",
+        region:         "Region",
+        postal_code:    "PostalCode",
+        country:        "Country",
+        attention_to:   "AttentionTo"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def initialize(attrs)
+        attrs           = attrs.transform_keys(&:to_s)
+        @address_type   = attrs["AddressType"]
+        @address_line_1 = attrs["AddressLine1"]
+        @address_line_2 = attrs["AddressLine2"]
+        @address_line_3 = attrs["AddressLine3"]
+        @address_line_4 = attrs["AddressLine4"]
+        @city           = attrs["City"]
+        @region         = attrs["Region"]
+        @postal_code    = attrs["PostalCode"]
+        @country        = attrs["Country"]
+        @attention_to   = attrs["AttentionTo"]
+      end
+
+      def street?   = address_type == "STREET"
+      def pobox?    = address_type == "POBOX"
+      def delivery? = address_type == "DELIVERY"
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(Address) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash = to_h.hash
+
+      def inspect
+        "#<#{self.class} type=#{address_type.inspect} city=#{city.inspect} country=#{country.inspect}>"
+      end
+    end
+  end
+end

data/lib/xero_kiwi/accounting/allocation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "time"
+
+module XeroKiwi
+  module Accounting
+    # Represents an allocation of a credit note, prepayment, or overpayment
+    # against an invoice.
+    #
+    # See: https://developer.xero.com/documentation/api/accounting/overpayments
+    class Allocation
+      ATTRIBUTES = {
+        allocation_id: "AllocationID",
+        amount:        "Amount",
+        date:          "Date",
+        invoice:       "Invoice",
+        is_deleted:    "IsDeleted"
+      }.freeze
+
+      attr_reader(*ATTRIBUTES.keys)
+
+      def initialize(attrs)
+        attrs          = attrs.transform_keys(&:to_s)
+        @allocation_id = attrs["AllocationID"]
+        @amount        = attrs["Amount"]
+        @date          = parse_time(attrs["Date"])
+        @invoice       = attrs["Invoice"] ? Invoice.new(attrs["Invoice"], reference: true) : nil
+        @is_deleted    = attrs["IsDeleted"]
+      end
+
+      def to_h
+        ATTRIBUTES.keys.to_h { |key| [key, public_send(key)] }
+      end
+
+      def ==(other)
+        other.is_a?(Allocation) && other.allocation_id == allocation_id
+      end
+      alias eql? ==
+
+      def hash = [self.class, allocation_id].hash
+
+      def inspect
+        "#<#{self.class} allocation_id=#{allocation_id.inspect} " \
+          "amount=#{amount.inspect}>"
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return nil if str.empty?
+
+        if (match = str.match(%r{\A/Date\((\d+)([+-]\d{4})?\)/\z}))
+          Time.at(match[1].to_i / 1000.0).utc
+        else
+          str = "#{str}Z" unless str.match?(/[Zz]\z|[+-]\d{2}:?\d{2}\z/)
+          Time.iso8601(str)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end