accessgrid 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab77e5bbf4a0a163fb5990dd7a0c6872c31bdbeb750bd7906b394d0d86e70d59
-  data.tar.gz: 2e6dff141d2eb8bd4c605c5363b12d0494e587cd4bcd1dc7e8a856d745dfa4ef
+  metadata.gz: 5370a4fedb6bf2bb2dc99ec4a8b28148f1caca417aca9f2401192c06a5fd49f9
+  data.tar.gz: fbe42537ec52fef71f1cd9806f2d91896c65e8e2ae4ad08aa8b9b864c52cf6aa
 SHA512:
-  metadata.gz: 2516e380d23a8b0e0bc988c5fb47c322707c0f2b98e5d82f1df4cfb500353bb56b131347e4bb9f899aa853d93d3acd6512edabe70f8c06b35d7a893804b3b1cb
-  data.tar.gz: 94cd560394836b1be4b73541557715867dc3f92979563778448c93e26994a3ea93d2681a6704d01f1c585b7d5ffa8b8380a00efb2a25913cdb7a42da90ed5415
+  metadata.gz: c98e6d776bd2eede74712e6a6a08d0b87c67cc2161dc18748d84db28f34273b69aa6f8f2ce4d6bdb0a5f02c6a68a60cf1b043bed9a785402a373a3296e72521e
+  data.tar.gz: 6d8c089a3071b4064a5902823cfd8f88393fd0d60d80215a72860dd6e139d1a790b4a8a5b410a3311d54915b6a6c1fe94c7c3cc023d33c0a74691e2c886c1a1d

data/README.md

@@ -1,6 +1,6 @@
-# AccessGrid SDK
+# ![AccessGrid Logo](accessgrid.png)
 
-A Ruby SDK for interacting with the [AccessGrid.com](https://www.accessgrid.com) API. This SDK provides a simple interface for managing NFC key cards and enterprise templates. Full docs at https://www.accessgrid.com/docs
+AccessGrid is a Ruby SDK for interacting with the [AccessGrid.com](https://www.accessgrid.com) API. This SDK provides a simple interface for managing NFC key cards and enterprise templates. Full docs at https://www.accessgrid.com/docs
 
 ## Installation
 
@@ -43,15 +43,25 @@ client = AccessGrid.new(account_id, secret_key)
 card = client.access_cards.issue(
   card_template_id: card_template_id,
   employee_id: "123456789",
-  card_number: "16187",
   tag_id: "DDEADB33FB00B5",
   full_name: "Employee name",
   email: "employee@yourwebsite.com",
   phone_number: "+19547212241",
   classification: "full_time",
-  start_date: "2025-01-31T22:46:25.601Z",
-  expiration_date: "2025-04-30T22:46:25.601Z",
-  employee_photo: "[image_in_base64_encoded_format]"
+  department: "Engineering",
+  location: "San Francisco",
+  site_name: "HQ Building A",
+  workstation: "4F-207",
+  mail_stop: "MS-401",
+  company_address: "123 Main St, San Francisco, CA 94105",
+  start_date: Time.now.utc.iso8601(3),
+  expiration_date: 3.months.from_now.utc.iso8601(3),
+  employee_photo: "[image_in_base64_encoded_format]",
+  title: "Engineering Manager",
+  metadata: {
+    "department": "engineering",
+    "badge_type": "contractor"
+  }
 )
 
 # Provision is an alias for issue (for backwards compatibility)
@@ -127,27 +137,24 @@ client.access_cards.delete("0xc4rd1d")
 
 ```ruby
 template = client.console.create_template(
-  name: "Employee NFC key",
+  name: "Employee Access Pass",
   platform: "apple",
-  use_case: "employee_badge",
+  use_case: "corporate_id",
   protocol: "desfire",
   allow_on_multiple_devices: true,
   watch_count: 2,
   iphone_count: 3,
-  design: {
-    background_color: "#FFFFFF",
-    label_color: "#000000",
-    label_secondary_color: "#333333",
-    background_image: "[image_in_base64_encoded_format]",
-    logo_image: "[image_in_base64_encoded_format]",
-    icon_image: "[image_in_base64_encoded_format]"
-  },
-  support_info: {
-    support_url: "https://help.yourcompany.com",
-    support_phone_number: "+1-555-123-4567",
-    support_email: "support@yourcompany.com",
-    privacy_policy_url: "https://yourcompany.com/privacy",
-    terms_and_conditions_url: "https://yourcompany.com/terms"
+  background_color: "#FFFFFF",
+  label_color: "#000000",
+  label_secondary_color: "#333333",
+  support_url: "https://help.yourcompany.com",
+  support_phone_number: "+1-555-123-4567",
+  support_email: "support@yourcompany.com",
+  privacy_policy_url: "https://yourcompany.com/privacy",
+  terms_and_conditions_url: "https://yourcompany.com/terms",
+  metadata: {
+    version: "2.1",
+    approval_status: "approved"
   }
 )
 ```
@@ -159,7 +166,6 @@ template = client.console.update_template(
   "0xd3adb00b5",
   {
     name: "Updated Employee NFC key",
-    allow_on_multiple_devices: true,
     watch_count: 2,
     iphone_count: 3,
     support_info: {
@@ -179,6 +185,30 @@ template = client.console.update_template(
 template = client.console.read_template("0xd3adb00b5")
 ```
 
+#### Publish a template
+
+```ruby
+result = client.console.publish_template("0xd3adb00b5")
+
+puts result.id      # "0xd3adb00b5"
+puts result.status  # "in-review" (Apple), "ready" (Android), or "publishing" (already in flight)
+```
+
+#### Reveal a SmartTap private key
+
+Fetches the template's SmartTap private key, decrypted client-side. The SDK generates a fresh ephemeral P-256 keypair per call, submits the public half, and decrypts the server's response — you get the plaintext PEM back without touching any crypto.
+
+```ruby
+reveal = client.console.reveal_smart_tap("0xd3adb00b5")
+
+puts "Key version:  #{reveal.key_version}"
+puts "Collector ID: #{reveal.collector_id}"
+puts "Fingerprint:  #{reveal.fingerprint}"
+puts reveal.private_key  # PEM — store in your reader/collector key vault
+```
+
+The server enforces single-use on pubkey fingerprint and rate-limits to 1 per minute per account. The SDK uses a fresh keypair every call, so single-use is satisfied automatically. Errors raised by the crypto path (`AccessGrid::DecryptError`, `AccessGrid::InvalidEnvelopeError`) and the HTTP path (`AccessGrid::AuthenticationError`, `AccessGrid::ResourceNotFoundError`, etc.) all descend from `AccessGrid::Error`.
+
 #### Get event logs
 
 ```ruby
@@ -205,6 +235,199 @@ events = client.console.event_log(
 )
 ```
 
+#### List pass template pairs
+
+```ruby
+response = client.console.list_pass_template_pairs(page: 1, per_page: 20)
+
+response['card_template_pairs'].each do |pair|
+  puts "#{pair.name} (#{pair.id})"
+  puts "  iOS: #{pair.ios_template&.name}"
+  puts "  Android: #{pair.android_template&.name}"
+end
+
+puts response['pagination'] # { "current_page" => 1, "total_pages" => 5, ... }
+```
+
+#### List ledger items
+
+```ruby
+response = client.console.list_ledger_items(
+  page: 1,
+  per_page: 50,
+  start_date: '2025-01-01T00:00:00Z',
+  end_date: '2025-06-30T23:59:59Z'
+)
+
+response['ledger_items'].each do |item|
+  puts "#{item.kind}: #{item.amount} (#{item.created_at})"
+
+  if item.access_pass
+    puts "  Pass: #{item.access_pass.full_name} (#{item.access_pass.state})"
+    if item.access_pass.pass_template
+      puts "  Template: #{item.access_pass.pass_template.name}"
+    end
+  end
+end
+
+puts response['pagination'] # { "current_page" => 1, "total_pages" => 3, ... }
+```
+
+#### iOS In-App Provisioning Preflight
+
+```ruby
+response = client.console.ios_preflight(
+  card_template_id: "0xt3mp14t3-3x1d",
+  access_pass_ex_id: "0xp455-3x1d"
+)
+
+puts "Provisioning Credential ID: #{response.provisioning_credential_identifier}"
+puts "Sharing Instance ID: #{response.sharing_instance_identifier}"
+puts "Card Template ID: #{response.card_template_identifier}"
+puts "Environment ID: #{response.environment_identifier}"
+```
+
+### Webhooks
+
+#### Create a webhook
+
+```ruby
+webhook = client.console.webhooks.create(
+  name: 'Production',
+  url: 'https://example.com/webhooks',
+  subscribed_events: ['ag.access_pass.issued']
+)
+
+puts "Webhook created: #{webhook.id}"
+puts "Private key: #{webhook.private_key}"
+```
+
+#### List webhooks
+
+```ruby
+webhooks = client.console.webhooks.list
+
+webhooks.each do |webhook|
+  puts "ID: #{webhook.id}, Name: #{webhook.name}"
+end
+```
+
+#### Delete a webhook
+
+```ruby
+client.console.webhooks.delete('abc123')
+```
+
+### HID Organizations
+
+#### Create an HID org
+
+```ruby
+org = client.console.hid.orgs.create(
+  name: 'My Org',
+  full_address: '1 Main St, NY NY',
+  phone: '+1-555-0000',
+  first_name: 'Ada',
+  last_name: 'Lovelace'
+)
+
+puts "Created org: #{org.name} (ID: #{org.id})"
+puts "Slug: #{org.slug}"
+```
+
+#### List HID orgs
+
+```ruby
+orgs = client.console.hid.orgs.list
+
+orgs.each do |org|
+  puts "Org ID: #{org.id}, Name: #{org.name}, Slug: #{org.slug}"
+end
+```
+
+#### Activate an HID org
+
+```ruby
+result = client.console.hid.orgs.activate(
+  email: 'admin@example.com',
+  password: 'hid-password-123'
+)
+
+puts "Completed registration for org: #{result.name}"
+puts "Status: #{result.status}"
+```
+
+### Landing Pages
+
+#### List landing pages
+
+```ruby
+landing_pages = client.console.list_landing_pages
+
+landing_pages.each do |page|
+  puts "ID: #{page.id}, Name: #{page.name}, Kind: #{page.kind}"
+  puts "  Password Protected: #{page.password_protected}"
+  puts "  Logo URL: #{page.logo_url}" if page.logo_url
+end
+```
+
+#### Create a landing page
+
+```ruby
+landing_page = client.console.create_landing_page(
+  name: "Miami Office Access Pass",
+  kind: "universal",
+  additional_text: "Welcome to the Miami Office",
+  bg_color: "#f1f5f9",
+  allow_immediate_download: true
+)
+
+puts "Landing page created: #{landing_page.id}"
+puts "Name: #{landing_page.name}, Kind: #{landing_page.kind}"
+```
+
+#### Update a landing page
+
+```ruby
+landing_page = client.console.update_landing_page(
+  landing_page_id: "0xlandingpage1d",
+  name: "Updated Miami Office Access Pass",
+  additional_text: "Welcome! Tap below to get your access pass.",
+  bg_color: "#e2e8f0"
+)
+
+puts "Landing page updated: #{landing_page.id}"
+puts "Name: #{landing_page.name}"
+```
+
+### Credential Profiles
+
+#### List credential profiles
+
+```ruby
+profiles = client.console.credential_profiles.list
+
+profiles.each do |profile|
+  puts "ID: #{profile.id}, Name: #{profile.name}, AID: #{profile.aid}"
+end
+```
+
+#### Create a credential profile
+
+```ruby
+profile = client.console.credential_profiles.create(
+  name: 'Main Office Profile',
+  app_name: 'KEY-ID-main',
+  keys: [
+    { value: 'your_32_char_hex_master_key_here' },
+    { value: 'your_32_char_hex__read_key__here' }
+  ]
+)
+
+puts "Profile created: #{profile.id}"
+puts "AID: #{profile.aid}"
+```
+
 ## Configuration
 
 The SDK can be configured with a custom API endpoint:
@@ -242,7 +465,7 @@ end
 
 ## Requirements
 
-- Ruby 2.6 or higher
+- Ruby 2.19 or higher
 
 ## Security
 
@@ -262,6 +485,40 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/access-grid/accessgrid-rb.
 
+## Feature Matrix
+
+| Endpoint | Method | Supported |
+|---|---|:---:|
+| POST /v1/key-cards | `access_cards.issue()` | Y |
+| GET /v1/key-cards/{id} | `access_cards.get()` | Y |
+| PATCH /v1/key-cards/{id} | `access_cards.update()` | Y |
+| GET /v1/key-cards | `access_cards.list()` | Y |
+| POST /v1/key-cards/{id}/suspend | `access_cards.suspend()` | Y |
+| POST /v1/key-cards/{id}/resume | `access_cards.resume()` | Y |
+| POST /v1/key-cards/{id}/unlink | `access_cards.unlink()` | Y |
+| POST /v1/key-cards/{id}/delete | `access_cards.delete()` | Y |
+| POST /v1/console/card-templates | `console.create_template()` | Y |
+| PUT /v1/console/card-templates/{id} | `console.update_template()` | Y |
+| GET /v1/console/card-templates/{id} | `console.read_template()` | Y |
+| GET /v1/console/card-templates/{id}/logs | `console.get_logs()` / `console.event_log()` | Y |
+| GET /v1/console/card-template-pairs | `console.list_pass_template_pairs()` | Y |
+| POST /v1/console/card-template-pairs | `console.create_pass_template_pair()` | Y |
+| POST /v1/console/card-templates/{id}/ios_preflight | `console.ios_preflight()` | Y |
+| POST /v1/console/card-templates/{id}/publish | `console.publish_template()` | Y |
+| POST /v1/console/card-templates/{id}/smart-tap/reveal | `console.reveal_smart_tap()` | Y |
+| GET /v1/console/ledger-items | `console.list_ledger_items()` / `console.ledger_items()` | Y |
+| GET /v1/console/webhooks | `console.webhooks.list()` | Y |
+| POST /v1/console/webhooks | `console.webhooks.create()` | Y |
+| DELETE /v1/console/webhooks/{id} | `console.webhooks.delete()` | Y |
+| GET /v1/console/landing-pages | `console.list_landing_pages()` | Y |
+| POST /v1/console/landing-pages | `console.create_landing_page()` | Y |
+| PUT /v1/console/landing-pages/{id} | `console.update_landing_page()` | Y |
+| GET /v1/console/credential-profiles | `console.credential_profiles.list()` | Y |
+| POST /v1/console/credential-profiles | `console.credential_profiles.create()` | Y |
+| POST /v1/console/hid/orgs | `console.hid.orgs.create()` | Y |
+| POST /v1/console/hid/orgs/activate | `console.hid.orgs.activate()` | Y |
+| GET /v1/console/hid/orgs | `console.hid.orgs.list()` | Y |
+
 ## License
 
-The gem is available as open source under the terms of the MIT License.
+The gem is available as open source under the terms of the MIT License.

data/lib/accessgrid/access_cards.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 # lib/accessgrid/access_cards.rb
 module AccessGrid
+  # Manages NFC key card lifecycle operations.
   class AccessCards
     def initialize(client)
       @client = client
@@ -9,7 +12,7 @@ module AccessGrid
       response = @client.make_request(:post, '/v1/key-cards', params)
       Card.new(response)
     end
-    
+
     # Alias provision to issue for backward compatibility
     alias provision issue
 
@@ -22,24 +25,15 @@ module AccessGrid
       response = @client.make_request(:patch, "/v1/key-cards/#{card_id}", params)
       Card.new(response)
     end
-    
+
     def list(template_id, state = nil)
       params = { template_id: template_id }
       params[:state] = state if state
-      
+
       response = @client.make_request(:get, '/v1/key-cards', nil, params)
       response.fetch('keys', []).map { |item| Card.new(item) }
     end
 
-    private def manage_state(card_id, action)
-      response = @client.make_request(
-        :post, 
-        "/v1/key-cards/#{card_id}/#{action}", 
-        {}
-      )
-      Card.new(response)
-    end
-
     def suspend(card_id)
       manage_state(card_id, 'suspend')
     end
@@ -51,23 +45,36 @@ module AccessGrid
     def unlink(card_id)
       manage_state(card_id, 'unlink')
     end
-    
+
     def delete(card_id)
       manage_state(card_id, 'delete')
     end
+
+    private
+
+    def manage_state(card_id, action)
+      response = @client.make_request(
+        :post,
+        "/v1/key-cards/#{card_id}/#{action}"
+      )
+      Card.new(response)
+    end
   end
 
+  # Represents an NFC key card with its attributes and state.
   class Card
     attr_reader :id, :state, :url, :install_url, :details, :full_name,
                 :expiration_date, :card_template_id, :card_number, :site_code,
-                :file_data, :direct_install_url, :devices, :metadata
+                :file_data, :direct_install_url, :devices, :metadata, :temporary,
+                :employee_id, :organization_name, :created_at
 
     def initialize(data)
       data ||= {}
+      install_url = data.fetch('install_url', nil)
       @id = data.fetch('id', nil)
       @state = data.fetch('state', nil)
-      @url = data.fetch('install_url', nil)
-      @install_url = data.fetch('install_url', nil)
+      @url = install_url
+      @install_url = install_url
       @details = data.fetch('details', nil)
       @full_name = data.fetch('full_name', nil)
       @expiration_date = data.fetch('expiration_date', nil)
@@ -78,6 +85,10 @@ module AccessGrid
       @direct_install_url = data.fetch('direct_install_url', nil)
       @devices = data.fetch('devices', [])
       @metadata = data.fetch('metadata', {})
+      @temporary = data.fetch('temporary', nil)
+      @employee_id = data.fetch('employee_id', nil)
+      @organization_name = data.fetch('organization_name', nil)
+      @created_at = data.fetch('created_at', nil)
     end
 
     def to_s
@@ -86,4 +97,4 @@ module AccessGrid
 
     alias inspect to_s
   end
-end
+end