ninja_van_api 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 843ddd6bb3f503a339f4ddd36a94cdbd5a7eeeb5214f0d30f1f62e1266811d87
-  data.tar.gz: 9bf87a0c781468e3bf164f75cd0df6e335f712ec2505bebbd913bbc84e193cd8
+  metadata.gz: 481484b7c6723678a26c7bbc898baf4e3a300a81881640d1eddeaa1b936a6fd0
+  data.tar.gz: d3e660f1ba15957e07441519d73d56239c7a7221515072e3ff0d4ee1cfc15902
 SHA512:
-  metadata.gz: c2c922a28328fbdbe55884fd488cb60c7d857126db67403826d8f66c08e3a9f0a0d8af1e7ffe91a56af040c1872afa42f918fd76eba1ffe220f81070fe3bae99
-  data.tar.gz: b5081a80188e4cc2ed5a5aed876db03483dab512032bc2db024395b12282a87d6d98693db0ed86070ef9bd61a7f59ba8c61478757b121f13ef0e178d875ffd5e
+  metadata.gz: 100f124aac939de091834aa5a0ad8d37d8210e050ef0b714503c1c291765979d5c3325aa265c6a0be8df305c3aad002ef11f741ecfa0675123170692ebd8fa15
+  data.tar.gz: bf7c08e8f3d9de76a5d1875365761f9826ee9297d0aecf376507c0ce2cacb9ba0d0973a712fbe42f61dcf7d4b157451d0fc06d617969875863d2ee361cb50b53

data/README.md

@@ -183,13 +183,109 @@ The webhook endpoints will be available at your specified paths (e.g., `/ninja_v
 
 ## Development
 
+### Setup
+
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Environment Variables
+
+For development purposes only, create a `.env` file in the root directory with a NinjaVan API access token:
+
+```
+NINJAVAN_API_ACCESS_TOKEN=00000000000
+```
+
+This token is used exclusively in development to prevent hitting NinjaVan's API request limits. When the token expires:
+
+1. Open the console:
+
+   ```
+   bin/console
+   ```
+
+2. Refresh the token:
+
+   ```ruby
+   # Intialize the client
+   client = NinjaVanApi::Client.new(
+     client_id: ENV["CLIENT_ID"],
+     client_secret: ENV["CLIENT_SECRET"],
+     country_code: "SG",
+     test_mode: true,
+   )
+
+   # Refresh the token
+   client.refresh_access_token # => "new_access_token"
+   ```
+
+3. Update your `.env` file with the new token
+
+4. Restart your application
+
+Note: These environment variables are automatically loaded when you run `bin/console`. For production, ensure your client credentials (CLIENT_ID and CLIENT_SECRET) are securely set in your deployment environment.
+
+### Authorization Issues
+
+The gem handles token management automatically, including:
+
+- Initial token acquisition
+- Automatic token refresh when expired
+- Retry mechanisms for failed requests
+
+If you encounter authorization issues:
+
+1. Verify your credentials:
+
+   - Check if CLIENT_ID and CLIENT_SECRET are correct
+   - Ensure credentials haven't been revoked by NinjaVan
+
+2. Debug token issues:
+
+   - The gem automatically refreshes expired tokens
+   - Check your application logs for token-related errors
+   - Verify your system clock is synchronized (important for token validation)
+
+3. Environment-specific troubleshooting:
+   - Development: Update your .env file with new credentials if needed
+   - Production: Safely update credentials in your environment
+   - Always restart your application after credential updates
+
+### Testing
+
+When testing your integration, it's recommended to stub the API requests. Here's an example using RSpec and WebMock:
+
+```ruby
+require 'webmock/rspec'
+
+RSpec.describe YourService do
+  let(:client) { NinjaVanApi::Client.new(client_id: 'test', client_secret: 'test', country_code: 'SG', test_mode: true) }
+
+  before do
+    # Stub authentication request
+    stub_request(:post, "https://api.ninjavan.co/SG/2.0/oauth/access_token")
+      .to_return(status: 200, body: { access_token: 'test_token' }.to_json)
+
+    # Stub API request
+    stub_request(:post, "https://api-sandbox.ninjavan.co/SG/4.2/orders")
+      .with(headers: { 'Authorization' => 'Bearer test_token', 'Content-Type' => 'application/json' })
+      .to_return(status: 200, body: { tracking_number: 'TEST123' }.to_json, headers: { 'Content-Type' => 'application/json' })
+  end
+
+  it 'retrieves order information' do
+    order_params = {}
+    response = client.orders.create(order_params)
+    expect(response.tracking_number).to eq('TEST123')
+  end
+end
+```
+
+### Installation
+
 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).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ninja_van_api. 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]/ninja_van_api/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/PostCo/ninja_van_api. 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]/ninja_van_api/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/ninja_van_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NinjaVanApi
-  VERSION = "0.3.4"
+  VERSION = "0.3.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ninja_van_api
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Jane Trang Mai Nguyen