doorflow 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f030947a7aa52576b9c64f55b185c888d43ff51c7257099a74db36608d2c14d3
+  data.tar.gz: 94aba11ea4616046c3e92d8a0bc6a71f61e2dc22ef3d229d5de07a3ff5c1aff3
+SHA512:
+  metadata.gz: f1793b621c409beca25bf87f90ff5246c3e1930219f75e57a503d873bf720f00c73e5b46f84c39ae498702a23de3d931c4d652e325a8d5134b410df55e9fcecc
+  data.tar.gz: a6488799e13203486b693ab13087489fedd35e998671133e5cb2956a761ede1f616bfe60a152493aa9f400135728e8929e517ac2d726c6cd9076d627f26dd7a6

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-02-04
+
+### Added
+- Initial release of DoorFlow Ruby SDK for API v3
+- OAuth 2.0 authentication with PKCE support
+- Automatic token refresh with configurable buffer
+- Token storage interface with `FileTokenStorage` reference implementation
+- Stripe-style resource classes: Account, Channel, Credential, CredentialType, Event, Group, GroupReservation, NotificationRule, Person, Reservation, Role, Site
+- Auto-pagination support with `.auto_paging_each`
+- Webhook signature verification and event handling
+- Full support for DoorFlow API v3 endpoints
+- Comprehensive documentation and examples
+
+### Technical
+- Requires Ruby 3.2 or higher
+- Built with OpenAPI Generator 7.18.0
+- Uses Faraday for HTTP requests
+- User-Agent: `doorflow-ruby/1.0.0`
+
+[1.0.0]: https://github.com/doorflow/doorflow-sdk-ruby/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DoorFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,356 @@
+# DoorFlow Ruby Gem
+
+The DoorFlow Ruby gem provides convenient access to the DoorFlow API from
+applications written in Ruby.
+
+## Documentation
+
+See the [DoorFlow API docs](https://developer.doorflow.com/docs) for API documentation.
+
+## Requirements
+
+Ruby 3.2 or later.
+
+## Installation
+
+Install the gem with:
+
+```bash
+gem install doorflow-api
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'doorflow-api'
+```
+
+## Usage
+
+The gem uses OAuth 2.0 for authentication. You'll need to [create an OAuth application](https://developer.doorflow.com/applications)
+in your DoorFlow developer account to get client credentials.
+
+```ruby
+require 'doorflow-api'
+
+# Set up OAuth authentication
+auth = DoorFlow::Auth::DoorFlowAuth.new(
+  client_id: ENV['DOORFLOW_CLIENT_ID'],
+  client_secret: ENV['DOORFLOW_CLIENT_SECRET'],
+  redirect_uri: 'http://localhost:3000/callback',
+  storage: DoorFlow::Auth::FileTokenStorage.new('./tokens.json')
+)
+
+# First run: redirect user to authorize
+unless auth.authenticated?
+  url, state = auth.authorization_url
+  # Store state in session, redirect user to url
+end
+
+# After callback: exchange code for tokens
+auth.handle_callback(code: params[:code], state: params[:state], expected_state: session[:state])
+
+# Create a client with your auth object
+client = DoorFlow::Client.new(auth: auth)
+
+# Now you can use the API
+people = client.people.list
+puts people.data.map { |p| p.email }
+```
+
+### People
+
+```ruby
+# List all people
+people = client.people.list
+
+# With pagination
+people = client.people.list(page: 1, per_page: 50)
+
+# Auto-paginate through all results
+client.people.list.auto_paging_each do |person|
+  puts person.email
+end
+
+# Find by email
+people = client.people.list(email: 'alice@example.com')
+
+# Get a specific person
+person = client.people.retrieve(123)
+
+# Create a person
+person = client.people.create(
+  first_name: 'Alice',
+  last_name: 'Smith',
+  email: 'alice@example.com',
+  group_ids: [1, 2]
+)
+
+# Update a person
+person.update(department: 'Engineering')
+
+# Delete a person
+person.delete
+```
+
+### Channels (Doors)
+
+```ruby
+# List all channels
+channels = client.channels.list
+
+# Get a specific channel
+channel = client.channels.retrieve(123)
+
+# Unlock a door momentarily
+channel.admit
+
+# Unlock for a specific person
+channel.admit_person(person_id)
+```
+
+### Credentials
+
+```ruby
+# List credential types available in your account
+types = client.credential_types.list
+
+# List all credentials
+credentials = client.credentials.list
+
+# Create a card credential
+credential = client.credentials.create(
+  person_id: 123,
+  credential_type_id: 1,
+  value: '12345678'
+)
+
+# Delete a credential
+credential.delete
+```
+
+### Groups
+
+```ruby
+# List all groups
+groups = client.groups.list
+```
+
+### Events
+
+```ruby
+# List recent access events
+events = client.events.list(start_date: (Time.now - 86400).iso8601)
+
+# Auto-paginate through events
+client.events.list.auto_paging_each do |event|
+  puts "#{event.person_name} at #{event.channel_name}"
+end
+```
+
+## OAuth Authorization Flow
+
+The `DoorFlow::Auth::DoorFlowAuth` class handles the OAuth 2.0 authorization code flow:
+
+```ruby
+require 'doorflow-api'
+
+# Create auth instance (typically in an initializer)
+auth = DoorFlow::Auth::DoorFlowAuth.new(
+  client_id: ENV['DOORFLOW_CLIENT_ID'],
+  client_secret: ENV['DOORFLOW_CLIENT_SECRET'],
+  redirect_uri: 'http://localhost:3000/callback',
+  storage: DoorFlow::Auth::FileTokenStorage.new('./tokens.json')
+)
+
+# 1. Generate authorization URL and redirect user
+get '/auth/doorflow' do
+  url, state = auth.authorization_url
+  session[:oauth_state] = state
+  redirect url
+end
+
+# 2. Handle callback after user authorizes
+get '/callback' do
+  auth.handle_callback(
+    code: params[:code],
+    state: params[:state],
+    expected_state: session[:oauth_state]
+  )
+  redirect '/dashboard'
+end
+
+# 3. Use the API - tokens refresh automatically
+get '/dashboard' do
+  client = DoorFlow::Client.new(auth: auth)
+  people = client.people.list
+  erb :dashboard, locals: { people: people }
+end
+```
+
+## Configuration
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `client_id` | Required | Your DoorFlow OAuth client ID |
+| `client_secret` | `nil` | Your OAuth client secret (optional for PKCE) |
+| `redirect_uri` | Required | The redirect URI registered with your OAuth application |
+| `storage` | Required | Token storage implementation |
+| `scopes` | `['account.person', 'account.channel.readonly', 'account.event.access.readonly']` | OAuth scopes to request |
+| `refresh_buffer_seconds` | `300` | Seconds before expiry to trigger automatic token refresh |
+| `base_path` | `'https://api.doorflow.com'` | DoorFlow API base URL |
+
+## Token Storage
+
+The gem includes `FileTokenStorage` for simple file-based token persistence:
+
+```ruby
+storage = DoorFlow::Auth::FileTokenStorage.new('./tokens.json')
+```
+
+For production, subclass `DoorFlow::Auth::TokenStorage` to use your preferred storage:
+
+```ruby
+class DatabaseTokenStorage < DoorFlow::Auth::TokenStorage
+  def initialize(user)
+    @user = user
+  end
+
+  def load
+    return nil unless @user.doorflow_tokens
+    to_stored_tokens(@user.doorflow_tokens)
+  end
+
+  def save(tokens)
+    @user.update!(doorflow_tokens: tokens.to_h)
+  end
+
+  def clear
+    @user.update!(doorflow_tokens: nil)
+  end
+end
+```
+
+## PKCE for Public Clients
+
+For applications that cannot securely store a client secret:
+
+```ruby
+auth = DoorFlow::Auth::DoorFlowAuth.new(
+  client_id: ENV['DOORFLOW_CLIENT_ID'],
+  redirect_uri: 'http://localhost:3000/callback',
+  storage: storage
+)
+
+# Generate authorization URL with PKCE
+url, state, code_verifier = auth.authorization_url(use_pkce: true)
+
+# Store both state and code_verifier
+session[:oauth_state] = state
+session[:oauth_verifier] = code_verifier
+
+# In callback handler
+auth.handle_callback(
+  code: params[:code],
+  state: params[:state],
+  expected_state: session[:oauth_state],
+  code_verifier: session[:oauth_verifier]
+)
+```
+
+## Webhooks
+
+DoorFlow sends webhooks to notify your application of events:
+
+```ruby
+handler = DoorFlow::Webhooks.handler(secret: ENV['DOORFLOW_WEBHOOK_SECRET'])
+
+handler.on('Event.CREATE') do |event|
+  puts "Access event: #{event.resource_id}"
+end
+
+handler.on('PersonCredential.UPDATE') do |event|
+  puts "Credential updated: #{event.resource_id}"
+end
+
+handler.on('*') do |event|
+  # Catch-all for any event type
+  AuditLog.create!(event_data: event.to_h)
+end
+
+# In your Rails controller
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    handler.handle(
+      payload: request.raw_post,
+      signature: request.headers['X-DoorFlow-Signature'],
+      timestamp: request.headers['X-DoorFlow-Timestamp']
+    )
+    head :ok
+  rescue DoorFlow::Webhooks::SignatureError
+    head :unauthorized
+  end
+end
+```
+
+### Event Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `Event.CREATE` | New access event |
+| `Event.UPDATE` | Access event updated |
+| `Event.DELETE` | Access event deleted |
+| `PersonCredential.CREATE` | New credential added |
+| `PersonCredential.UPDATE` | Credential updated |
+| `PersonCredential.DELETE` | Credential deleted |
+| `Person.*` | Any person action |
+| `*` | Catch-all |
+
+## Error Handling
+
+```ruby
+begin
+  person = client.people.retrieve(99999)
+rescue DoorFlow::ApiError => e
+  puts "API Error: #{e.message}"
+  puts "Status: #{e.code}"
+end
+```
+
+## Thread Safety & Multi-Tenant Support
+
+The `DoorFlow::Client` class is designed for thread safety and multi-tenant applications. Each client instance maintains its own configuration and authentication state:
+
+```ruby
+# Each tenant gets their own client instance
+def doorflow_client
+  @doorflow_client ||= DoorFlow::Client.new(auth: current_tenant_auth)
+end
+
+# Or pass auth to each request
+client = DoorFlow::Client.new(auth: current_user.doorflow_auth)
+people = client.people.list
+```
+
+For simple single-tenant applications, you can also use a static access token:
+
+```ruby
+# Using a static token (no auto-refresh)
+client = DoorFlow::Client.new(access_token: 'your_token')
+
+# Or set globally (not recommended for multi-threaded apps)
+DoorFlow.access_token = 'your_token'
+client = DoorFlow::Client.new
+people = client.people.list  # Uses global token
+```
+
+## Documentation
+
+- [DoorFlow API Documentation](https://developer.doorflow.com/api-ref)
+- [DoorFlow Developer Portal](https://developer.doorflow.com)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

data/bin/post-generate

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# Post-generation script to add Stripe-like wrappers
+
+puts "🔧 Running post-generation enhancements..."
+
+# Ensure the wrapper files exist
+wrapper_files = [
+  'lib/doorflow.rb',
+  'lib/doorflow/configuration.rb',
+  'lib/doorflow/client.rb',
+  'lib/doorflow/resource.rb',
+  'lib/doorflow/list_object.rb',
+  'lib/doorflow/resources/account.rb',
+  'lib/doorflow/resources/channel.rb',
+  'lib/doorflow/resources/credential.rb',
+  'lib/doorflow/resources/credential_type.rb',
+  'lib/doorflow/resources/event.rb',
+  'lib/doorflow/resources/group.rb',
+  'lib/doorflow/resources/group_reservation.rb',
+  'lib/doorflow/resources/notification_rule.rb',
+  'lib/doorflow/resources/person.rb',
+  'lib/doorflow/resources/reservation.rb',
+  'lib/doorflow/resources/role.rb',
+  'lib/doorflow/resources/site.rb'
+]
+
+missing_files = wrapper_files.reject { |f| File.exist?(f) }
+
+if missing_files.any?
+  puts "⚠️  Warning: Missing wrapper files:"
+  missing_files.each { |f| puts "  - #{f}" }
+  puts ""
+  puts "These files should be committed to the repository."
+  puts "They provide the Stripe-like API wrapper."
+else
+  puts "✅ All wrapper files present"
+end
+
+# Clean up generated comments if desired
+# Uncomment to remove "Generated by OpenAPI Generator" comments
+# Dir.glob('lib/**/*.rb').each do |file|
+#   content = File.read(file)
+#   cleaned = content.gsub(/^#.*Generated by.*\n/, '')
+#   File.write(file, cleaned) if content != cleaned
+# end
+
+puts "✅ Post-generation complete!"

data/doorflow.gemspec

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+
+=begin
+#DoorFlow API
+
+#Access control and door management API for DoorFlow
+
+The version of the OpenAPI document: 3.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.18.0-SNAPSHOT
+
+=end
+
+$:.push File.expand_path("../lib", __FILE__)
+require "doorflow-api/version"
+
+Gem::Specification.new do |s|
+  s.name        = "doorflow"
+  s.version     = DoorFlow::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["NetNodes Ltd"]
+  s.email       = ["support@netnodes.net"]
+  s.homepage    = "https://www.doorflow.com"
+  s.summary     = "Official Ruby client for DoorFlow API v3"
+  s.description = "Ruby SDK for the DoorFlow Access Control API"
+  s.license     = "MIT"
+  s.required_ruby_version = ">= 3.2"
+  s.metadata    = {
+    "homepage_uri"      => "https://www.doorflow.com",
+    "documentation_uri" => "https://www.doorflow.com/docs",
+    "changelog_uri"     => "https://github.com/doorflow/doorflow-sdk-ruby/blob/main/CHANGELOG.md",
+    "source_code_uri"   => "https://github.com/doorflow/doorflow-sdk-ruby",
+    "bug_tracker_uri"   => "https://github.com/doorflow/doorflow-sdk-ruby/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  s.add_runtime_dependency 'faraday', '>= 1.0.1', '< 3.0'
+  s.add_runtime_dependency 'faraday-multipart', '~> 1.0'
+  s.add_runtime_dependency 'marcel', '~> 1.0'
+  s.add_runtime_dependency 'typhoeus', '~> 1.4'
+
+  s.add_development_dependency 'rspec', '~> 3.6', '>= 3.6.0'
+  s.add_development_dependency 'simplecov', '~> 0.22'
+  s.add_development_dependency 'simplecov-cobertura', '~> 2.1'
+  s.add_development_dependency 'webmock', '~> 3.18'
+  s.add_development_dependency 'vcr', '~> 6.1'
+  s.add_development_dependency 'yard', '~> 0.9'
+  s.add_development_dependency 'rdoc', '~> 6.7'
+
+  s.files         = Dir.glob("{lib,bin}/**/*") + %w[README.md LICENSE CHANGELOG.md doorflow.gemspec]
+  s.test_files    = Dir.glob("spec/**/*")
+  s.executables   = []
+  s.require_paths = ["lib"]
+end