isds 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5f6c4b4643e4f08410bb292d56afe96a75db717055ec20579dafea9da1dbadd
+  data.tar.gz: 7658f9a652173800354c7b8b2f5ce5d305d5c2d850237514df18027eccb86fa2
+SHA512:
+  metadata.gz: 8682b7e75cd0e581350ae9c000f43a323e914acb5224a8501f88f706f9d227c99eb51cdfcc958898c8368c9c940c269fd9a4ef0be85a206e5b64088daa20f152
+  data.tar.gz: 662f41fd534dca323546dbe80e3d20984eac614e160c8193cba1af8bf9b36a8cf92d6c11c26497507cdc48eb748378573f95a6c0cf0df55be8e98ef8d842836d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,44 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+    - "pkg/**/*"
+    - "*.md"
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Layout/LineLength:
+  Max: 120
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/integration/**/*"

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Segfault Labs
+
+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,346 @@
+# ISDS
+
+Ruby client for the Czech Data Box system (ISDS -- Informacni system datovych schranek).
+
+Provides an idiomatic Ruby interface to the [ISDS SOAP web services](https://www.datoveschranky.info/) for sending and receiving official data messages, searching databoxes, managing users, and handling large messages (VoDZ).
+
+## Requirements
+
+- Ruby >= 3.1
+- Active ISDS account (production or [test environment on czebox.cz](https://www.czebox.cz/))
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'isds'
+```
+
+Then run `bundle install`.
+
+## Quick start
+
+```ruby
+require 'isds'
+
+client = ISDS::Client.new(ISDS::Configuration.new(
+  environment: :test,       # :test (czebox.cz) or :production (mojedatovaschranka.cz)
+  auth_method: :basic,
+  username: 'your_username',
+  password: 'your_password'
+))
+
+client.authenticate!
+puts client.owner_info
+```
+
+## Configuration
+
+### Global configuration
+
+```ruby
+ISDS.configure do |config|
+  config.environment = :production
+  config.auth_method = :basic
+  config.username = ENV.fetch('ISDS_USERNAME')
+  config.password = ENV.fetch('ISDS_PASSWORD')
+  config.timeout = 30
+  config.request_timeout = 120
+  config.enable_request_logging = false
+end
+
+client = ISDS::Client.new
+```
+
+### Per-client configuration
+
+```ruby
+config = ISDS::Configuration.new(
+  environment: :test,
+  auth_method: :basic,
+  username: 'user',
+  password: 'pass'
+)
+
+client = ISDS::Client.new(config)
+```
+
+### Authentication methods
+
+**Basic authentication** (username + password):
+
+```ruby
+ISDS::Configuration.new(auth_method: :basic, username: 'user', password: 'pass')
+```
+
+**Certificate authentication**:
+
+```ruby
+ISDS::Configuration.new(
+  auth_method: :certificate,
+  certificate_path: '/path/to/cert.pem',
+  private_key_path: '/path/to/key.pem',
+  key_password: 'optional_key_password'
+)
+```
+
+### SSL options
+
+```ruby
+ISDS::Configuration.new(
+  ssl_verify_peer: true,
+  ssl_ca_file: '/path/to/ca-bundle.crt',
+  ssl_version: :TLSv1_2
+)
+```
+
+### Custom endpoints
+
+Override default endpoints if needed:
+
+```ruby
+ISDS::Configuration.new(
+  endpoints: {
+    ws_url: 'https://custom-proxy.example.com/soap',
+    ws2_url: 'https://custom-proxy.example.com/vdz_ws/'
+  }
+)
+```
+
+## Usage
+
+### Messages
+
+**Send a message:**
+
+```ruby
+attachment = ISDS::Attachment.new(
+  filename: 'document.pdf',
+  file_path: '/path/to/document.pdf'
+)
+
+message_id = client.send_message(
+  'abc1234',                    # recipient databox ID
+  subject: 'Test message',
+  attachments: [attachment],
+  personal_delivery: true,      # optional
+  to_hands: 'Jan Novak'        # optional
+)
+```
+
+**List received messages:**
+
+```ruby
+messages = client.receive_messages(limit: 50, unread_only: true)
+
+messages.each do |msg|
+  puts "#{msg.id}: #{msg.subject} from #{msg.sender}"
+  puts "  Delivered: #{msg.delivered?}, Read: #{msg.read?}"
+end
+```
+
+**List sent messages:**
+
+```ruby
+messages = client.sent_messages(limit: 20)
+```
+
+**Download a specific message with attachments:**
+
+```ruby
+message = client.find_message('12345678')
+message.download_all_attachments('/tmp/attachments')
+```
+
+**Mark messages as read:**
+
+```ruby
+client.mark_messages_read(['12345678', '12345679'])
+```
+
+### Databox search
+
+**Search by name:**
+
+```ruby
+results = client.search_databoxes('Ministerstvo')
+results.each do |databox|
+  puts "#{databox.id}: #{databox.name} (#{databox.type})"
+end
+```
+
+**Find by databox ID:**
+
+```ruby
+databox = client.find_databox('abc1234')
+puts databox.name if databox
+```
+
+**Advanced search:**
+
+```ruby
+# Search by ICO
+ISDS::Search.by_ico('12345678', connection: client.connection)
+
+# Search by name with exact matching
+ISDS::Search.by_name('Exact Name s.r.o.', connection: client.connection, exact: true)
+
+# Search by type (FO, PFO, PO, OVM)
+ISDS::Search.by_type(:ovm, connection: client.connection, query: 'Praha')
+
+# Search OVM only
+ISDS::Search.ovm_only(connection: client.connection, query: 'Ministerstvo')
+
+# Search by address
+ISDS::Search.by_address(connection: client.connection, city: 'Praha', zip_code: '11000')
+
+# Paginated search
+page = ISDS::Search.paginated_search('Test', connection: client.connection, page: 1, per_page: 50)
+page[:results].each { |db| puts db.name }
+```
+
+**Check databox status:**
+
+```ruby
+status = client.check_databox_status('abc1234')
+puts status[:active] # => true/false
+```
+
+### Databox info
+
+```ruby
+info = client.owner_info
+password_info = client.password_info
+```
+
+### User management
+
+```ruby
+# List users
+users = ISDS::User.list(connection: client.connection)
+
+# Add user
+ISDS::User.add(
+  connection: client.connection,
+  databox_id: 'abc1234',
+  first_name: 'Jan',
+  last_name: 'Novak'
+)
+
+# Remove user
+ISDS::User.remove(connection: client.connection, user_id: '123')
+```
+
+### Attachments
+
+```ruby
+# From file
+attachment = ISDS::Attachment.new(filename: 'doc.pdf', file_path: '/path/to/doc.pdf')
+
+# From content
+attachment = ISDS::Attachment.new(filename: 'doc.pdf', content: pdf_bytes)
+
+# Properties
+attachment.size          # => byte size
+attachment.mime_type     # => 'application/pdf' (auto-detected)
+attachment.encoded_content  # => Base64-encoded string
+```
+
+Standard message attachments are limited to 20 MB. Large messages (VoDZ) support up to 100 MB.
+
+## Error handling
+
+All ISDS errors inherit from `ISDS::Error`:
+
+```ruby
+begin
+  client.authenticate!
+  client.send_message('abc1234', subject: 'Test', attachments: [])
+rescue ISDS::InvalidCredentialsError => e
+  puts "Auth failed: #{e.message}"
+rescue ISDS::DataboxNotFoundError => e
+  puts "Databox not found: #{e.message}"
+rescue ISDS::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+rescue ISDS::NetworkError => e
+  puts "Network issue: #{e.message}"
+rescue ISDS::Error => e
+  puts "ISDS error [#{e.code}]: #{e.message}"
+end
+```
+
+Error hierarchy:
+
+```
+ISDS::Error
+  ConfigurationError
+  NetworkError
+    TimeoutError
+    ConnectionError
+  AuthenticationError
+    InvalidCredentialsError
+    CertificateError
+  DataboxNotFoundError
+  MessageNotFoundError
+  PermissionDeniedError
+  InvalidMessageError
+  ServiceUnavailableError
+  TemporaryUnavailableError
+  QuotaExceededError
+  AttachmentError
+    FileSizeExceededError
+    UnsupportedFormatError
+```
+
+ISDS status codes are mapped automatically:
+
+| Code | Error class |
+|------|-------------|
+| 0001 | `InvalidCredentialsError` |
+| 0002 | `PermissionDeniedError` |
+| 0003 | `DataboxNotFoundError` |
+| 0004 | `MessageNotFoundError` |
+| 0005 | `InvalidMessageError` |
+| 0006 | `QuotaExceededError` |
+| 9999 | `ServiceUnavailableError` |
+
+## Endpoints
+
+The gem uses the official ISDS SOAP endpoints:
+
+| Environment | Standard operations | Large messages (VoDZ) |
+|-------------|--------------------|-----------------------|
+| Production | `https://ws1.mojedatovaschranka.cz/soap` | `https://ws1.mojedatovaschranka.cz/vdz_ws/` |
+| Test | `https://www.czebox.cz/soap` | `https://www.czebox.cz/vdz_ws/` |
+
+All standard services (operations, info, search, access, supplementary) are routed through the single `/soap` endpoint. Large message operations use the `/vdz_ws/` endpoint.
+
+## Development
+
+```bash
+# Run unit tests
+bundle exec rspec
+
+# Run rubocop
+bundle exec rubocop
+
+# Run integration tests (requires czebox.cz credentials)
+ISDS_USERNAME=your_user ISDS_PASSWORD=your_pass bundle exec rake integration
+```
+
+Integration tests run against the [czebox.cz](https://www.czebox.cz/) test environment and are excluded from the default test suite.
+
+## ISDS specification references
+
+- [Provozni rad ISDS (PDF)](https://www.datoveschranky.info/documents/1744842/1746058/Provozni_rad_ISDS.pdf) -- official operational rules
+- [ISDS web services documentation](https://www.datoveschranky.info/documents/1744842/1746058/WS_ISDS_Manipulace_s_datovymi_zpravami.pdf) -- SOAP API for message operations
+- [ISDS WSDL definitions](https://www.czebox.cz/static/wsdl/v20/) -- WSDL schemas (test environment)
+- [datoveschranky.info](https://www.datoveschranky.info/) -- official ISDS portal with full documentation
+- [czebox.cz](https://www.czebox.cz/) -- ISDS test environment
+
+The gem implements the ISDS v20 namespace (`http://isds.czechpoint.cz/v20`).
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.rspec_opts = '--tag integration'
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/isds/attachment.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'mime/types'
+
+module ISDS
+  class Attachment
+    MAX_FILE_SIZE = 20 * 1024 * 1024 # 20MB per attachment (standard messages)
+    LARGE_MAX_FILE_SIZE = 100 * 1024 * 1024 # 100MB for VoDZ
+
+    attr_reader :filename, :mime_type, :content, :meta_type, :description
+
+    # rubocop:disable Metrics/ParameterLists -- all params are keyword args with sensible defaults
+    def initialize(filename:, content: nil, file_path: nil, mime_type: nil, meta_type: 'main', description: nil)
+      @filename = filename
+      @content = content || (file_path ? File.binread(file_path) : nil)
+      @mime_type = mime_type || detect_mime_type(filename)
+      @meta_type = meta_type
+      @description = description || filename
+      validate!
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def size
+      content&.bytesize || 0
+    end
+
+    def encoded_content
+      Base64.strict_encode64(content)
+    end
+
+    def self.build_soap_element(attachment)
+      attachment = from_hash(attachment) if attachment.is_a?(Hash)
+
+      {
+        'isds:dmMimeType' => attachment.mime_type,
+        'isds:dmFileMetaType' => attachment.meta_type,
+        'isds:dmFileDescr' => attachment.description,
+        'isds:dmEncodedContent' => attachment.encoded_content
+      }
+    end
+
+    def self.from_hash(hash)
+      new(
+        filename: hash[:filename] || hash[:file_path]&.then { |p| File.basename(p) },
+        file_path: hash[:file_path],
+        content: hash[:content],
+        mime_type: hash[:mime_type],
+        meta_type: hash[:meta_type] || 'main',
+        description: hash[:description]
+      )
+    end
+
+    private
+
+    def validate!
+      raise AttachmentError, 'Content is required' if content.nil? || content.empty?
+      raise FileSizeExceededError, 'File exceeds maximum size of 20MB' if size > MAX_FILE_SIZE
+    end
+
+    def detect_mime_type(filename)
+      types = MIME::Types.type_for(filename)
+      types.first&.content_type || 'application/octet-stream'
+    end
+  end
+end

data/lib/isds/authentication/access_interface.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ISDS
+  module Authentication
+    class AccessInterface < Base
+      def apply(savon_options)
+        savon_options[:basic_auth] = [configuration.username, configuration.password]
+        savon_options[:headers] = (savon_options[:headers] || {}).merge(
+          'X-ISDS-Access-Interface' => '1'
+        )
+        savon_options
+      end
+
+      def valid?
+        !configuration.username.nil? && !configuration.username.empty? &&
+          !configuration.password.nil? && !configuration.password.empty?
+      end
+    end
+  end
+end

data/lib/isds/authentication/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ISDS
+  module Authentication
+    class Base
+      attr_reader :configuration
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def apply(savon_options)
+        raise NotImplementedError, "#{self.class}#apply must be implemented"
+      end
+
+      def valid?
+        raise NotImplementedError, "#{self.class}#valid? must be implemented"
+      end
+
+      def self.build(configuration)
+        case configuration.auth_method
+        when :basic
+          Basic.new(configuration)
+        when :certificate
+          Certificate.new(configuration)
+        when :access_interface
+          AccessInterface.new(configuration)
+        else
+          raise ConfigurationError, "Unknown auth method: #{configuration.auth_method}"
+        end
+      end
+    end
+  end
+end

data/lib/isds/authentication/basic.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ISDS
+  module Authentication
+    class Basic < Base
+      def apply(savon_options)
+        savon_options[:basic_auth] = [configuration.username, configuration.password]
+        savon_options
+      end
+
+      def valid?
+        !configuration.username.nil? && !configuration.username.empty? &&
+          !configuration.password.nil? && !configuration.password.empty?
+      end
+    end
+  end
+end

data/lib/isds/authentication/certificate.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module ISDS
+  module Authentication
+    class Certificate < Base
+      def apply(savon_options)
+        savon_options[:ssl_cert_file] = configuration.certificate_path
+        savon_options[:ssl_cert_key_file] = configuration.private_key_path
+        savon_options[:ssl_cert_key_password] = configuration.key_password if configuration.key_password
+        savon_options
+      end
+
+      def valid?
+        certificate_exists? && key_exists? && certificate_readable?
+      end
+
+      def certificate
+        @certificate ||= OpenSSL::X509::Certificate.new(File.read(configuration.certificate_path))
+      end
+
+      def expires_at
+        certificate.not_after
+      end
+
+      def expired?
+        expires_at < Time.now
+      end
+
+      def subject_info
+        certificate.subject.to_s
+      end
+
+      def self.from_p12(p12_path, password)
+        p12 = OpenSSL::PKCS12.new(File.read(p12_path), password)
+        { certificate: p12.certificate, key: p12.key }
+      end
+
+      private
+
+      def certificate_exists?
+        !configuration.certificate_path.nil? && File.exist?(configuration.certificate_path)
+      end
+
+      def key_exists?
+        !configuration.private_key_path.nil? && File.exist?(configuration.private_key_path)
+      end
+
+      def certificate_readable?
+        OpenSSL::X509::Certificate.new(File.read(configuration.certificate_path))
+        true
+      rescue OpenSSL::X509::CertificateError, Errno::ENOENT
+        false
+      end
+    end
+  end
+end