didww-v3 5.0.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a712d25c5bdfa402c73df24b8529f0e001e97256cf7d84cdfbb8d492af4dcd
-  data.tar.gz: f3fdb4186c6821dd1d9c93744515e0a3eb6d0d1b3da3c1da4d0449dd8d726512
+  metadata.gz: df4c6143fca0f8b1f6c6d5c4e43fc89a71a4a9fcc5b63b3b63c3bb9ab03ce102
+  data.tar.gz: dd9ad527373290850d9555f1117aa097aa534497668115fdcbb9dd2f2323f783
 SHA512:
-  metadata.gz: de07093d853e4576ea5e18552786f3bb88d3013456a75f2efdaae56a3dbbb2560384d11bd22d1cd42f3cd739c0baf531e190dc70e700fba23bd46e3309861d16
-  data.tar.gz: 2a434cb0c3a17840b8b7490b45078f66bb835f5656241fb98a6f629f6c7ee7305cfe6015366c7b9fbfb47233c02dbfe3292e0408deaf8f80e116b089524f5c0c
+  metadata.gz: 32dc4dc452c8ef98f1855ec47aee83cd7959f9abc3c3ade68489610d71600a8bcf1e232cb4a4e3a76ffae9a5b68adb19d133b8788d6d4ba7711dff36141c96b4
+  data.tar.gz: e759ef5119ea80accac264b297e4730f9391e774adc47d7dca853b0c9d79f6c1d2af4a61562e849af04c4a4ba476213a18696a9e88c7f8ee92b811c68059a09e

data/.github/workflows/tests.yml

@@ -5,6 +5,11 @@ on:
     branches:
       - master
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -23,3 +28,55 @@ jobs:
           bundler-cache: true
       - name: Run tests
         run: bundle exec rake
+
+      - name: Generate badge.json
+        if: matrix.ruby == '3.4' && matrix.rails == '~> 8.1'
+        run: |
+          LAST_RUN="coverage/.last_run.json"
+          if [ ! -f "$LAST_RUN" ]; then
+            mkdir -p badge
+            echo '{"schemaVersion":1,"label":"coverage","message":"unknown","color":"lightgrey"}' > badge/badge.json
+            exit 0
+          fi
+          PERCENT=$(ruby -rjson -e "puts JSON.parse(File.read('$LAST_RUN')).dig('result','line').round(1)")
+          PERCENT_NUM=$(ruby -rjson -e "puts JSON.parse(File.read('$LAST_RUN')).dig('result','line')")
+          if ruby -e "exit(($PERCENT_NUM >= 90) ? 0 : 1)"; then COLOR="brightgreen"
+          elif ruby -e "exit(($PERCENT_NUM >= 75) ? 0 : 1)"; then COLOR="green"
+          elif ruby -e "exit(($PERCENT_NUM >= 60) ? 0 : 1)"; then COLOR="yellow"
+          else COLOR="red"; fi
+          mkdir -p badge
+          echo "{\"schemaVersion\":1,\"label\":\"coverage\",\"message\":\"${PERCENT}%\",\"color\":\"${COLOR}\"}" > badge/badge.json
+
+      - name: Upload badge artifact
+        if: matrix.ruby == '3.4' && matrix.rails == '~> 8.1'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-badge
+          path: badge
+
+  deploy-coverage:
+    needs: test
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Download coverage badge
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-badge
+          path: coverage
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: coverage
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/README.md

@@ -1,7 +1,9 @@
 Ruby client for DIDWW API v3.
 
 ![Tests](https://github.com/didww/didww-v3-ruby/workflows/Tests/badge.svg)
+![Coverage](https://img.shields.io/endpoint?url=https://didww.github.io/didww-v3-ruby/badge.json)
 [![Gem Version](https://badge.fury.io/rb/didww-v3.svg)](https://badge.fury.io/rb/didww-v3)
+![Ruby](https://img.shields.io/badge/ruby-3.3%2B-blue)
 
 About DIDWW API v3
 -----
@@ -10,8 +12,12 @@ The DIDWW API provides a simple yet powerful interface that allows you to fully
 
 The DIDWW API v3 is a fully compliant implementation of the [JSON API specification](http://jsonapi.org/format/).
 
+This SDK uses [json_api_client](https://github.com/JsonApiClient/json_api_client) for JSON:API serialization and deserialization.
+
 Read more https://doc.didww.com/api
 
+This SDK sends the `X-DIDWW-API-Version: 2022-05-10` header with every request by default.
+
 Gem Versions **4.X.X** and branch [master](https://github.com/didww/didww-v3-ruby) are intended to use with DIDWW API 3 version [2022-05-10](https://doc.didww.com/api3/2022-05-10/index.html).
 
 Gem Versions **3.X.X** and branch [release-3](https://github.com/didww/didww-v3-ruby/tree/release-3) are intended to use with DIDWW API 3 version [2021-12-15](https://doc.didww.com/api3/2021-12-15/index.html).
@@ -36,27 +42,217 @@ Or install it yourself as:
 
     $ gem install didww-v3
 
-## Usage
+## Requirements
+
+- Ruby 3.3+
+
+## Quick Start
 
 ```ruby
 require 'didww'
 
-client = DIDWW::Client.configure do |config|
-  config.api_key  = '34ffe988432b980f4ba19432539b704f'
+DIDWW::Client.configure do |config|
+  config.api_key  = 'YOUR_API_KEY'
   config.api_mode = :sandbox
 end
 
-client.balance
+# Check balance
+balance = DIDWW::Client.balance
+puts "Balance: #{balance.total_balance}"
+
+# List DID groups with stock keeping units
+did_groups = DIDWW::Client.did_groups.all(
+  include: 'stock_keeping_units',
+  filter: { area_name: 'Acapulco' }
+)
+
+puts "DID groups: #{did_groups.count}"
+```
+
+For details on obtaining your API key please visit https://doc.didww.com/api3/configuration.html
+
+## Examples
+
+- Rails integration sample: https://github.com/didww/didww-v3-rails-sample
+
+## Configuration
+
+```ruby
+require 'didww'
+
+# Sandbox
+DIDWW::Client.configure do |config|
+  config.api_key  = 'YOUR_API_KEY'
+  config.api_mode = :sandbox
+end
+
+# Production
+DIDWW::Client.configure do |config|
+  config.api_key  = 'YOUR_API_KEY'
+  config.api_mode = :production
+end
+```
+
+### Environments
+
+| Environment | Base URL |
+|-------------|----------|
+| `:production` | `https://api.didww.com/v3/` |
+| `:sandbox` | `https://sandbox-api.didww.com/v3/` |
+
+### API Version
+
+The SDK sends `X-DIDWW-API-Version: 2022-05-10` by default. You can override it per block:
+
+```ruby
+DIDWW::Client.with_api_version('2022-05-10') do
+  DIDWW::Client.countries.all
+end
+```
+
+## Resources
+
+### Read-Only Resources
+
+```ruby
+# Countries
+countries = DIDWW::Client.countries.all
+country = DIDWW::Client.countries.find('uuid')
+
+# Regions, Cities, Areas, POPs
+regions = DIDWW::Client.regions.all
+cities = DIDWW::Client.cities.all
+areas = DIDWW::Client.areas.all
+pops = DIDWW::Client.pops.all
+
+# DID Group Types
+types = DIDWW::Client.did_group_types.all
+
+# DID Groups (with stock keeping units)
+did_groups = DIDWW::Client.did_groups.all(include: 'stock_keeping_units')
+
+# Available DIDs (with DID group and stock keeping units)
+available_dids = DIDWW::Client.available_dids.all(include: 'did_group.stock_keeping_units')
+
+# Public Keys
+public_keys = DIDWW::Client.public_keys.all
+
+# Requirements
+requirements = DIDWW::Client.requirements.all
+
+# Balance (singleton)
+balance = DIDWW::Client.balance
+```
+
+### DIDs
+
+```ruby
+# List DIDs
+dids = DIDWW::Client.dids.all
+
+# Update DID
+did = DIDWW::Client.dids.find('uuid')
+did.description = 'Updated'
+did.capacity_limit = 20
+did.save
 ```
 
-For details on obtaining your API key please visit https://doc.didww.com/api#introduction-api-keys
+### Voice In Trunks
 
-See integration example at https://github.com/didww/didww-v3-rails-sample
+```ruby
+trunk = DIDWW::Client.voice_in_trunks.new(
+  name: 'My SIP Trunk',
+  configuration: {
+    type: 'sip_configurations',
+    username: '{DID}',
+    host: 'sip.example.com',
+    port: 5060
+  }
+)
+
+trunk.save
+```
+
+### Orders
+
+```ruby
+order = DIDWW::Client.orders.new(
+  items: [
+    {
+      type: 'did_order_items',
+      sku_id: 'sku-uuid',
+      qty: 2
+    }
+  ]
+)
+
+order.save
+```
+
+## Date and Datetime Fields
+
+The SDK distinguishes between date-only and datetime fields:
+
+- **Datetime fields** — deserialized as `Time`:
+  - All `created_at` fields — present on most resources (`EncryptedFile` has no `created_at`)
+  - Expiry fields: `Did#expires_at`, `DidReservation#expire_at`, `Proof#expires_at`, `EncryptedFile#expire_at`
+- **Date-only fields** — deserialized as `Date`:
+  - `Identity#birth_date`
+- **Date-only fields kept as strings** (`CapacityPool#renew_date`) remain as `String`.
+
+```ruby
+did = DIDWW::Client.dids.find("uuid").first
+puts did.created_at   # => 2024-01-15 10:00:00 UTC  (Time)
+puts did.expires_at   # => nil or 2025-01-15 10:00:00 UTC  (Time)
+
+identity = DIDWW::Client.identities.find("uuid").first
+puts identity.birth_date  # => 1990-05-20  (Date)
+```
 
 ## Resource Relationships
 
 See [docs/resource_relationships.md](docs/resource_relationships.md) for a Mermaid ER diagram showing all `has_one`, `has_many`, and `belongs_to` relationships between resources.
 
+## Webhook Signature Validation
+
+Validate incoming webhook callbacks from DIDWW using HMAC-SHA1 signature verification.
+
+```ruby
+require 'didww/callback/request_validator'
+
+validator = DIDWW::Callback::RequestValidator.new("YOUR_API_KEY")
+
+# In your webhook handler:
+valid = validator.validate(
+  request_url,    # full original URL
+  payload_params, # Hash of payload key-value pairs
+  signature       # value of X-DIDWW-Signature header
+)
+```
+
+The signature header name is available as the constant `DIDWW::Callback::RequestValidator::HEADER`.
+
+### Rails Example
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    validator = DIDWW::Callback::RequestValidator.new("YOUR_API_KEY")
+    signature = request.headers[DIDWW::Callback::RequestValidator::HEADER]
+    params_hash = request.POST
+
+    if validator.validate(request.original_url, params_hash, signature)
+      # Process the webhook
+      head :ok
+    else
+      head :forbidden
+    end
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/README.md

@@ -0,0 +1,86 @@
+# Examples
+
+All examples read the API key from the `DIDWW_API_KEY` environment variable.
+
+## Prerequisites
+
+- Ruby 3.3+
+- Bundler
+- DIDWW API key for sandbox account
+
+## Environment variables
+
+- `DIDWW_API_KEY` (required): your DIDWW API key
+
+## Install
+
+```bash
+cd examples && bundle install
+```
+
+## Run an example
+
+```bash
+DIDWW_API_KEY=your_api_key ruby examples/orders_nanpa.rb
+```
+
+## Available examples
+
+### Core Resources
+| Script | Description |
+|---|---|
+| [`balance.rb`](balance.rb) | Fetches and prints current account balance and credit. |
+| [`countries.rb`](countries.rb) | Lists countries, demonstrates filtering, and fetches one country by ID. |
+| [`regions.rb`](regions.rb) | Lists regions with filters/includes and fetches a specific region. |
+| [`did_groups.rb`](did_groups.rb) | Fetches DID groups with included SKUs and shows group details. |
+| [`dids.rb`](dids.rb) | Updates DID routing/capacity by assigning trunk and capacity pool. |
+| [`exports.rb`](exports.rb) | Lists CDR exports and their details. |
+
+### Voice In (Inbound)
+| Script | Description |
+|---|---|
+| [`voice_in_trunks.rb`](voice_in_trunks.rb) | Lists voice in trunks and their configurations. |
+| [`voice_in_trunk_groups.rb`](voice_in_trunk_groups.rb) | CRUD for trunk groups with trunk relationships. |
+
+### Voice Out (Outbound)
+| Script | Description |
+|---|---|
+| [`voice_out_trunks.rb`](voice_out_trunks.rb) | CRUD for voice out trunks (requires account config). |
+
+### Capacity Management
+| Script | Description |
+|---|---|
+| [`capacity_pools.rb`](capacity_pools.rb) | Lists capacity pools with included shared capacity groups. |
+| [`shared_capacity_groups.rb`](shared_capacity_groups.rb) | Creates a shared capacity group in a capacity pool. |
+
+### Orders - Basic
+| Script | Description |
+|---|---|
+| [`orders.rb`](orders.rb) | Lists orders and creates/cancels a DID order using live SKU lookup. |
+| [`orders_nanpa.rb`](orders_nanpa.rb) | Orders a DID number by NPA/NXX prefix. |
+| [`orders_by_sku.rb`](orders_by_sku.rb) | Creates a DID order by SKU resolved from DID groups. |
+| [`orders_capacity.rb`](orders_capacity.rb) | Purchases capacity by creating a capacity order item. |
+
+### Orders - Advanced
+| Script | Description |
+|---|---|
+| [`orders_available_dids.rb`](orders_available_dids.rb) | Orders an available DID using included DID group SKU. |
+| [`orders_reservation_dids.rb`](orders_reservation_dids.rb) | Reserves a DID and then places an order from that reservation. |
+| [`orders_all_item_types.rb`](orders_all_item_types.rb) | Creates a DID order with all item types: by SKU, available DID, and reservation. |
+
+### DID Management
+| Script | Description |
+|---|---|
+| [`did_reservations.rb`](did_reservations.rb) | Lists DID reservations and available DIDs. |
+| [`did_trunk_assignment.rb`](did_trunk_assignment.rb) | Demonstrates exclusive trunk/trunk group assignment on DIDs. |
+
+### Compliance & Verification
+| Script | Description |
+|---|---|
+| [`identities_and_proofs.rb`](identities_and_proofs.rb) | Creates identities, addresses, and demonstrates proof workflow. |
+
+## Troubleshooting
+
+If `DIDWW_API_KEY` is missing, examples fail fast with:
+
+`Please set DIDWW_API_KEY`

data/examples/balance.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# Fetches and prints current account balance and credit.
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/balance.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+balance = DIDWW::Client.balance
+puts "Total Balance: #{balance.total_balance}"
+puts "Balance: #{balance.balance}"
+puts "Credit: #{balance.credit}"

data/examples/capacity_pools.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# Lists capacity pools with included shared capacity groups.
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/capacity_pools.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# List capacity pools with included shared capacity groups
+puts '=== Capacity Pools ==='
+capacity_pools = DIDWW::Client.capacity_pools
+                  .includes(:shared_capacity_groups)
+                  .all
+
+puts "Found #{capacity_pools.size} capacity pools"
+
+capacity_pools.each do |pool|
+  puts "\nCapacity Pool: #{pool.name}"
+  puts "  Total channels: #{pool.total_channels_count}"
+  puts "  Assigned channels: #{pool.assigned_channels_count}"
+  puts "  Monthly price: #{pool.monthly_price}"
+  puts "  Metered rate: #{pool.metered_rate}"
+
+  if pool.shared_capacity_groups && !pool.shared_capacity_groups.empty?
+    puts '  Shared Capacity Groups:'
+    pool.shared_capacity_groups.each do |group|
+      puts "    - #{group.name} (#{group.shared_channels_count} channels)"
+    end
+  end
+end

data/examples/countries.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# Lists countries, demonstrates filtering, and fetches one country by ID.
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/countries.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# List all countries
+puts '=== All Countries ==='
+countries = DIDWW::Client.countries.all
+countries.first(5).each do |country|
+  puts "#{country.name} (+#{country.prefix}) [#{country.iso}]"
+end
+
+# Filter countries by name
+puts "\n=== Filtered Countries (United States) ==="
+filtered = DIDWW::Client.countries.where(name: 'United States').all
+puts "Found: #{filtered.size} countries"
+filtered.each do |country|
+  puts "#{country.name} (+#{country.prefix})"
+end
+
+# Find a specific country
+if !filtered.empty?
+  puts "\n=== Specific Country ==="
+  country = DIDWW::Client.countries.find(filtered.first.id).first
+  puts "Found: #{country.name}"
+end

data/examples/did_groups.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# Fetches DID groups with included SKUs and shows group details.
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/did_groups.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# Fetch DID groups with included stock_keeping_units
+puts '=== DID Groups with SKUs ==='
+did_groups = DIDWW::Client.did_groups
+              .includes(:stock_keeping_units)
+              .all
+
+puts "Found #{did_groups.size} DID groups"
+
+did_groups.first(3).each do |did_group|
+  puts "\nDID Group: #{did_group.id}"
+  puts "  Area: #{did_group.area_name}"
+  puts "  Prefix: #{did_group.prefix}"
+  puts "  Metered: #{did_group.is_metered}"
+  puts "  Features: #{did_group.features_human}"
+
+  if did_group.stock_keeping_units && !did_group.stock_keeping_units.empty?
+    puts '  SKUs:'
+    did_group.stock_keeping_units.each do |sku|
+      puts "    - #{sku.id} (monthly: #{sku.monthly_price})"
+    end
+  end
+end
+
+# Find a specific DID group
+if !did_groups.empty?
+  puts "\n=== Specific DID Group ==="
+  did_group = DIDWW::Client.did_groups
+               .includes(:stock_keeping_units)
+               .find(did_groups.first.id)
+               .first
+  puts "Found: #{did_group.area_name} (prefix: #{did_group.prefix})"
+end

data/examples/did_reservations.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# Lists DID reservations and available DIDs.
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/did_reservations.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# List DID reservations
+puts '=== Existing DID Reservations ==='
+reservations = DIDWW::Client.did_reservations
+                .includes(:available_did)
+                .all
+
+puts "Found #{reservations.size} DID reservations"
+reservations.first(10).each do |reservation|
+  did_number = reservation.available_did ? reservation.available_did.number : 'unknown'
+  puts "#{reservation.id}"
+  puts "  DID: #{did_number}"
+  puts "  Expires: #{reservation.expire_at}"
+  puts "  Created: #{reservation.created_at}"
+  puts ''
+end
+
+# List available DIDs
+puts "\n=== Available DIDs ==="
+available_dids = DIDWW::Client.available_dids
+                  .includes(:did_group)
+                  .all
+
+puts "Found #{available_dids.size} available DIDs"
+available_dids.first(10).each do |available_did|
+  puts "#{available_did.number}"
+  if available_did.did_group
+    puts "  Group: #{available_did.did_group.area_name}"
+    puts "  Prefix: #{available_did.did_group.prefix}"
+  end
+  puts ''
+end
+
+# Find a specific reservation if available
+if !reservations.empty?
+  puts "\n=== Specific Reservation Details ==="
+  specific_reservation = DIDWW::Client.did_reservations
+                         .find(reservations.first.id)
+                         .first
+  puts "Reservation: #{specific_reservation.id}"
+  puts "  Expires at: #{specific_reservation.expire_at}"
+  puts "  Created at: #{specific_reservation.created_at}"
+end