d4h_api 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90ba7bf33fc815fbea860ba872f991052c3bf4057383275cffeca1212c1c53af
-  data.tar.gz: 4f37a538b43e1162fe706c229004a469b744a9521c5ea54df0c543baa802b28f
+  metadata.gz: 2aa8bae136f351de1c996f430d2f20aa781ca4a44a99475efe661e2828bfd9ed
+  data.tar.gz: bed47fee1b00ca08c2a404efad96458093984f4f5887fc644409af66ae8affc5
 SHA512:
-  metadata.gz: e5a6ff0f16ca0cddc34e344a0bc9b31d347002885de3d7c8133cc78248b24bbd84d922ad6a68907b481a7e15a441a9f30ec06823797fd2a7e84a6bec1205aced
-  data.tar.gz: ada411f80bc829d3e582a0200b55569dc634daf580b58802e70d55c048b33559eec12ee2c89b1ac6f4f2f7fe78fb78b9a11fefe4b7e3ab2042b90283c9e52d03
+  metadata.gz: 9810b27605cd21faeebbc3b15eb36d4a45c1f3d6f06948f1e3db69b13d39b70b202603a19c9245a42f5d5a106ff1080bc323eb40f6fddaa598b16146a02becc9
+  data.tar.gz: 722d42a916aaf25acf3ad13206e94a7400c76f37a00ec61fbbcc73c9e58459ad22e94743f08ef0a4ceaddcd985baee928833a26cf7cf0a58c58ece15eb68a888

data/README.md

@@ -32,15 +32,17 @@ gem install d4h_api
 ```ruby
 require "d4h"
 
+# Discover your identity (no context_id needed)
+client = D4H::API::Client.new(api_key: ENV.fetch("D4H_TOKEN"))
+me = client.whoami.show
+puts "#{me.name} (#{me.email})"
+
+# Use context_id for all other resources
 client = D4H::API::Client.new(
   api_key:    ENV.fetch("D4H_TOKEN"),
   context_id: ENV.fetch("D4H_TEAM_ID").to_i,
 )
 
-# Who am I?
-me = client.whoami.show
-puts "#{me.name} (#{me.email})"
-
 # List all operational members
 members = client.member.list(status: "OPERATIONAL")
 members.each { |m| puts m.name }
@@ -54,9 +56,13 @@ puts "#{team.title} — #{team.country}"
 
 ### Client Initialization
 
-The client requires an `api_key` and a `context_id` (your D4H team ID). The `context` defaults to `"team"` but can be set to `"organisation"` for organisation-scoped API calls.
+The client requires an `api_key`. The `context_id` (your D4H team or organisation ID) is optional — it is required for all resources except `whoami`, which can be used to discover your context. The `context` defaults to `"team"` but can be set to `"organisation"` for organisation-scoped API calls.
 
 ```ruby
+# Minimal client — only whoami is available (no context_id)
+client = D4H::API::Client.new(api_key: ENV.fetch("D4H_TOKEN"))
+me = client.whoami.show
+
 # Team context (default)
 client = D4H::API::Client.new(
   api_key:    ENV.fetch("D4H_TOKEN"),
@@ -85,7 +91,7 @@ The client reads the following environment variables as defaults. All can be ove
 | Variable       | Default                               | Constructor param | Description                                                               |
 |----------------|---------------------------------------|-------------------|---------------------------------------------------------------------------|
 | `D4H_TOKEN`    | *(required)*                          | `api_key:`        | Your D4H API Bearer token. Generate one in your [D4H account settings](https://support.d4h.com/en/articles/2334703-api-access). |
-| `D4H_TEAM_ID`  | *(required)*                          | `context_id:`     | Your D4H team (or organisation) numeric ID. Find it in your D4H URL or via the API. |
+| `D4H_TEAM_ID`  | *(optional)*                          | `context_id:`     | Your D4H team (or organisation) numeric ID. Required for all resources except `whoami`. Find it in your D4H URL or via the `whoami` endpoint. |
 | `D4H_BASE_URL` | `https://api.team-manager.us.d4h.com` | `base_url:`       | Base URL for the D4H API. Change for EU (`https://api.team-manager.eu.d4h.com`) or other regional endpoints. |
 
 A typical `.env` file:
@@ -137,7 +143,7 @@ client.equipment     # => EquipmentResource.new(client)
 client.event         # => EventResource.new(client)
 ```
 
-The client builds a **base path** from the context — `v3/team/42` for team context, `v3/organisation/99` for organisation context — which all resources prepend to their endpoint URLs.
+The client builds a **base path** from the context — `v3/team/42` for team context, `v3/organisation/99` for organisation context — which most resources prepend to their endpoint URLs. The `context_id` is optional; when omitted, only context-free resources like `whoami` (which uses `v3/whoami`) are available. Calling a context-scoped resource without a `context_id` raises `ArgumentError`.
 
 **`D4H::API::Resource`** is the base class for all 56 resource endpoints. It provides five HTTP verb methods (`get_request`, `post_request`, `put_request`, `patch_request`, `delete_request`), each of which injects the Bearer token header and checks the response status. Every subclass defines a `SUB_URL` constant and implements only the CRUD methods the D4H API supports for that resource:
 
@@ -211,7 +217,7 @@ client.event.update(id: 1, title: "Updated Training")
 client.tag.destroy(id: 5)
 ```
 
-Two special cases: `whoami.show` takes no arguments (it returns the authenticated user), and `document.update` uses HTTP PUT instead of PATCH per the D4H API contract.
+Two special cases: `whoami.show` takes no arguments and does not require a `context_id` (it hits `v3/whoami` directly to return the authenticated user), and `document.update` uses HTTP PUT instead of PATCH per the D4H API contract.
 
 ## Usage
 
@@ -351,18 +357,19 @@ If all retries are exhausted, the `RetriableError` propagates to your code so yo
 ### Team & Identity
 
 ```ruby
-# Show your team's info (requires the team's own ID)
+# Show your own profile (no context_id needed)
+client = D4H::API::Client.new(api_key: ENV.fetch("D4H_TOKEN"))
+me = client.whoami.show
+me.name   # => "John Doe"
+me.email  # => "john@example.com"
+
+# Show your team's info (requires context_id)
 team = client.team.show(id: 42)
 team.title       # => "Rocky Mountain Rescue"
 team.timezone    # => "America/Denver"
 team.memberCounts.total        # => 90
 team.memberCounts.operational  # => 85
 
-# Show your own profile
-me = client.whoami.show
-me.name   # => "John Doe"
-me.email  # => "john@example.com"
-
 # Show an organisation
 org = client.organisation.show(id: 5)
 org.title  # => "Colorado SAR"
@@ -738,7 +745,7 @@ Every resource is accessible as a method on the client. The table below shows wh
 | `whoami` | whoami | | x** | | | |
 
 \* Document update uses PUT instead of PATCH.
-\*\* Whoami `show` takes no arguments — it returns the current authenticated user.
+\*\* Whoami `show` takes no arguments and does not require `context_id` — it hits `v3/whoami` directly to return the current authenticated user.
 
 All resources with `list` also support `list_all` for automatic pagination.
 

data/d4h_api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "d4h_api"
-  spec.version = "2.0.0"
+  spec.version = "2.0.1"
   spec.authors = ["Pawel Osiczko"]
   spec.email = ["p.osiczko@tetrapyloctomy.org"]
   spec.homepage = "https://github.com/rockymountainrescue/d4h_api"

data/lib/d4h/api/client.rb

@@ -17,6 +17,10 @@ module D4H
     #
     # Examples
     #
+    #   # Discover your identity (no context needed)
+    #   client = D4H::API::Client.new(api_key: ENV.fetch("D4H_TOKEN"))
+    #   me = client.whoami.show
+    #
     #   # Team context (default)
     #   client = D4H::API::Client.new(
     #     api_key:    ENV.fetch("D4H_TOKEN"),
@@ -44,7 +48,8 @@ module D4H
       #
       # api_key:        - A String Bearer token for API authentication.
       # context:        - The context scope, either "team" (default) or "organisation".
-      # context_id:     - The Integer ID of the team or organisation.
+      # context_id:     - The Integer ID of the team or organisation (optional;
+      #                   required for all resources except whoami).
       # base_url:       - The base URL for the D4H API. Defaults to D4H_BASE_URL env
       #                   var, or "https://api.team-manager.us.d4h.com" if unset.
       #                   Change this for EU or other regional endpoints.
@@ -54,7 +59,7 @@ module D4H
       #                   Set to 0 to disable retries.
       # retry_interval: - Float base interval in seconds between retries (default: 1).
       #                   Set to 0 in tests to avoid sleeping.
-      def initialize(api_key:, context: "team", context_id:,
+      def initialize(api_key:, context: "team", context_id: nil,
         base_url: ENV.fetch("D4H_BASE_URL", DEFAULT_BASE_URL),
         adapter: Faraday.default_adapter,
         max_retries: MAX_RETRIES, retry_interval: RETRY_INTERVAL)
@@ -72,7 +77,11 @@ module D4H
       # Examples
       #
       #   client.base_path  # => "v3/team/42"
+      #
+      # Raises ArgumentError if context_id is nil.
       def base_path
+        raise ArgumentError, "context_id is required for this resource" if context_id.nil?
+
         "v3/#{context}/#{context_id}"
       end
 

data/lib/d4h/api/resource.rb

@@ -128,7 +128,7 @@ module D4H
         return response if (200..299).cover?(response.status)
 
         body = response.body || {}
-        message = [body["error"], body["message"]].compact.join(": ")
+        message = [body["title"], body["detail"], body["error"], body["message"]].compact.uniq.join(": ")
 
         raise RetriableError, message if Client::RETRIABLE_STATUSES.include?(response.status)
 

data/lib/d4h/api/resources/whoami_resource.rb

@@ -6,7 +6,7 @@ module D4H
       SUB_URL = "whoami"
 
       def show
-        Whoami.new(get_request("#{base_path}/#{SUB_URL}").body)
+        Whoami.new(get_request("v3/#{SUB_URL}").body)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: d4h_api
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Pawel Osiczko