keyenv 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b674e0b30a5f7d531fab1e1029ee40fc1706633030c44227e8fbcbd684334b39
+  data.tar.gz: 62d26d5f098f32e81341929bb86204bafb7543d7df22efc883f666b01b3ab182
+SHA512:
+  metadata.gz: b7d130375c1a7b6d275c8dfa9d8cdc82a88e0f593db5ec6253e6d2a0e7040ddfb7a24d516881b795a6ce6accd58d046a43219d1b3680a30ed89d127b8e1015c3
+  data.tar.gz: 6cb4ab4ba2e5b1f2b962c899cbb868b738dab39c80c26ff2796a1527dd1fa59972536179ec1406d14cf50e6f38867645ef4c169fc5dba560413adb2184ec4d62

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 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.2.0](https://github.com/keyenv/ruby-sdk/compare/v1.1.0...v1.2.0) (2026-01-26)
+
+
+### Features
+
+* add integration tests for live API testing ([c4f47c2](https://github.com/keyenv/ruby-sdk/commit/c4f47c2aa94492975a9f50ebd78287f00c2069d7))
+* add tag-based release workflow for RubyGems ([736a6aa](https://github.com/keyenv/ruby-sdk/commit/736a6aa9ce190b0494e1c39c78820feba0e813a6))
+
+
+### Bug Fixes
+
+* correct error message formatting ([dbe213e](https://github.com/keyenv/ruby-sdk/commit/dbe213e2b59788a6189720e6dbb17bde03b13939))
+
+## [1.0.0] - 2025-01-23
+
+### Added
+
+- Initial release
+- `KeyEnv.new(token:)` and `KeyEnv.create(token)` client creation
+- Authentication: `get_current_user`, `validate_token`
+- Projects: `list_projects`, `get_project`, `create_project`, `delete_project`
+- Environments: `list_environments`, `create_environment`, `delete_environment`
+- Secrets: `list_secrets`, `export_secrets`, `export_secrets_as_hash`, `get_secret`
+- Secret management: `create_secret`, `update_secret`, `set_secret`, `delete_secret`
+- Bulk operations: `bulk_import`, `get_secret_history`
+- Utilities: `load_env`, `generate_env_file`, `clear_cache`
+- Permissions: `list_permissions`, `set_permission`, `delete_permission`, `bulk_set_permissions`
+- Permission queries: `get_my_permissions`, `get_project_defaults`, `set_project_defaults`
+- Built-in caching with configurable TTL for serverless environments
+- Typed data classes for all API responses
+- Specific error classes: `AuthenticationError`, `NotFoundError`, `ValidationError`, `RateLimitError`
+- Full RSpec test suite with WebMock

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KeyEnv
+
+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,245 @@
+# KeyEnv Ruby SDK
+
+Official Ruby SDK for [KeyEnv](https://keyenv.dev) - Secure secrets management for development teams.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'keyenv'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install keyenv
+```
+
+## Quick Start
+
+```ruby
+require 'keyenv'
+
+client = KeyEnv.new(token: ENV['KEYENV_TOKEN'])
+
+# Load secrets into ENV
+client.load_env(project_id: 'your-project-id', environment: 'production')
+puts ENV['DATABASE_URL']
+```
+
+## Usage
+
+### Initialize the Client
+
+```ruby
+require 'keyenv'
+
+# Using keyword argument
+client = KeyEnv.new(token: 'your-service-token')
+
+# Alternative syntax
+client = KeyEnv.create('your-service-token')
+
+# With custom timeout and caching
+client = KeyEnv.new(token: 'your-token', timeout: 60, cache_ttl: 300)
+```
+
+### Export Secrets
+
+```ruby
+# Get all secrets as a list
+secrets = client.export_secrets(project_id: 'proj_123', environment: 'production')
+secrets.each do |secret|
+  puts "#{secret.key}=#{secret.value}"
+end
+
+# Get secrets as a hash
+env = client.export_secrets_as_hash(project_id: 'proj_123', environment: 'production')
+puts env['DATABASE_URL']
+
+# Load directly into ENV
+count = client.load_env(project_id: 'proj_123', environment: 'production')
+puts "Loaded #{count} secrets"
+```
+
+### Manage Secrets
+
+```ruby
+# Get a single secret
+secret = client.get_secret(project_id: 'proj_123', environment: 'production', key: 'DATABASE_URL')
+puts secret.value
+
+# Set a secret (creates or updates)
+client.set_secret(
+  project_id: 'proj_123',
+  environment: 'production',
+  key: 'API_KEY',
+  value: 'sk_live_...'
+)
+
+# Delete a secret
+client.delete_secret(project_id: 'proj_123', environment: 'production', key: 'OLD_KEY')
+```
+
+### Bulk Import
+
+```ruby
+result = client.bulk_import(
+  project_id: 'proj_123',
+  environment: 'development',
+  secrets: [
+    KeyEnv::BulkSecretItem.new(key: 'DATABASE_URL', value: 'postgres://localhost/mydb'),
+    KeyEnv::BulkSecretItem.new(key: 'REDIS_URL', value: 'redis://localhost:6379'),
+    { 'key' => 'API_KEY', 'value' => 'sk_test_...' }  # Also accepts hashes
+  ],
+  overwrite: true
+)
+puts "Created: #{result.created}, Updated: #{result.updated}"
+```
+
+### Generate .env File
+
+```ruby
+env_content = client.generate_env_file(project_id: 'proj_123', environment: 'production')
+File.write('.env', env_content)
+```
+
+### List Projects and Environments
+
+```ruby
+# List all projects
+projects = client.list_projects
+projects.each do |project|
+  puts "#{project.name} (#{project.id})"
+end
+
+# Get project with environments
+project = client.get_project(project_id: 'proj_123')
+project.environments.each do |env|
+  puts "  - #{env.name}"
+end
+```
+
+### Service Token Info
+
+```ruby
+# Get current user or service token info
+user = client.get_current_user
+
+if user.auth_type == 'service_token'
+  # Service tokens can access multiple projects
+  puts "Projects: #{user.project_ids}"
+  puts "Scopes: #{user.scopes}"
+end
+```
+
+## Error Handling
+
+```ruby
+require 'keyenv'
+
+begin
+  secret = client.get_secret(project_id: 'proj_123', environment: 'production', key: 'MISSING_KEY')
+rescue KeyEnv::NotFoundError => e
+  puts "Secret not found: #{e.message}"
+rescue KeyEnv::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue KeyEnv::Error => e
+  puts "Error #{e.status}: #{e.message}"
+end
+```
+
+### Error Types
+
+| Error | Description |
+|-------|-------------|
+| `KeyEnv::Error` | Base error class |
+| `KeyEnv::AuthenticationError` | Authentication failed (401) |
+| `KeyEnv::NotFoundError` | Resource not found (404) |
+| `KeyEnv::ValidationError` | Invalid request (422) |
+| `KeyEnv::RateLimitError` | Rate limit exceeded (429) |
+| `KeyEnv::ConnectionError` | Network/connection error |
+| `KeyEnv::TimeoutError` | Request timeout |
+
+## Caching
+
+For serverless environments or high-traffic applications, enable caching to reduce API calls:
+
+```ruby
+# Cache secrets for 5 minutes
+client = KeyEnv.new(token: 'your-token', cache_ttl: 300)
+
+# Or use environment variable
+ENV['KEYENV_CACHE_TTL'] = '300'
+client = KeyEnv.new(token: 'your-token')
+
+# Manually clear cache
+client.clear_cache  # Clear all
+client.clear_cache(project_id: 'proj_123')  # Clear project
+client.clear_cache(project_id: 'proj_123', environment: 'production')  # Clear specific
+```
+
+## API Reference
+
+### `KeyEnv.new(token:, timeout:, cache_ttl:)`
+
+Create a new KeyEnv client.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `token` | `String` | Yes | - | Service token |
+| `timeout` | `Integer` | No | `30` | Request timeout (seconds) |
+| `cache_ttl` | `Integer` | No | `0` | Cache TTL (seconds, 0 = disabled) |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_current_user` | Get current user/token info |
+| `list_projects` | List all accessible projects |
+| `get_project(project_id:)` | Get project with environments |
+| `list_environments(project_id:)` | List environments in a project |
+| `list_secrets(project_id:, environment:)` | List secret keys (no values) |
+| `export_secrets(project_id:, environment:)` | Export secrets with values |
+| `export_secrets_as_hash(project_id:, environment:)` | Export as hash |
+| `get_secret(project_id:, environment:, key:)` | Get single secret |
+| `set_secret(project_id:, environment:, key:, value:)` | Create or update secret |
+| `delete_secret(project_id:, environment:, key:)` | Delete secret |
+| `bulk_import(project_id:, environment:, secrets:)` | Bulk import secrets |
+| `load_env(project_id:, environment:)` | Load secrets into ENV |
+| `generate_env_file(project_id:, environment:)` | Generate .env file content |
+| `list_permissions(project_id:, environment:)` | List permissions |
+| `set_permission(project_id:, environment:, user_id:, role:)` | Set permission |
+| `delete_permission(project_id:, environment:, user_id:)` | Delete permission |
+| `get_my_permissions(project_id:)` | Get current user's permissions |
+
+## Requirements
+
+- Ruby 3.0+
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Generate documentation
+bundle exec rake yard
+```
+
+## License
+
+MIT

data/lib/keyenv/client.rb

@@ -0,0 +1,492 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+module KeyEnv
+  # KeyEnv API client for managing secrets.
+  #
+  # @example Basic usage
+  #   client = KeyEnv::Client.new(token: "your-service-token")
+  #   secrets = client.export_secrets(project_id: "proj_123", environment: "production")
+  #
+  # @example With caching for serverless environments
+  #   client = KeyEnv::Client.new(token: "your-token", cache_ttl: 300)  # 5 minutes
+  #
+  class Client
+    BASE_URL = "https://api.keyenv.dev"
+    DEFAULT_TIMEOUT = 30
+
+    # @param token [String] Service token for authentication
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param cache_ttl [Integer] Cache TTL in seconds (default: 0 = disabled)
+    # @param base_url [String, nil] Custom API base URL (default: https://api.keyenv.dev)
+    def initialize(token:, timeout: DEFAULT_TIMEOUT, cache_ttl: 0, base_url: nil)
+      raise ArgumentError, "KeyEnv token is required" if token.nil? || token.empty?
+
+      @token = token
+      @timeout = timeout
+      @cache_ttl = cache_ttl.positive? ? cache_ttl : ENV.fetch("KEYENV_CACHE_TTL", "0").to_i
+      @base_url = base_url || ENV.fetch("KEYENV_API_URL", BASE_URL)
+      @base_uri = URI.parse(@base_url)
+      @secrets_cache = {}
+    end
+
+    # =========================================================================
+    # Authentication
+    # =========================================================================
+
+    # Get the current user or service token info.
+    #
+    # @return [User] Current user/token info
+    def get_current_user
+      data = request(:get, "/api/v1/users/me")
+      User.new(data)
+    end
+
+    # Validate the token and return user info.
+    #
+    # @return [User] Current user/token info
+    def validate_token
+      get_current_user
+    end
+
+    # =========================================================================
+    # Projects
+    # =========================================================================
+
+    # List all accessible projects.
+    #
+    # @return [Array<Project>] List of projects
+    def list_projects
+      data = request(:get, "/api/v1/projects")
+      (data["projects"] || []).map { |p| Project.new(p) }
+    end
+
+    # Get a project by ID.
+    #
+    # @param project_id [String] Project ID
+    # @return [ProjectWithEnvironments] Project with environments
+    def get_project(project_id:)
+      data = request(:get, "/api/v1/projects/#{project_id}")
+      ProjectWithEnvironments.new(data)
+    end
+
+    # Create a new project.
+    #
+    # @param team_id [String] Team ID
+    # @param name [String] Project name
+    # @return [Project] Created project
+    def create_project(team_id:, name:)
+      data = request(:post, "/api/v1/projects", { team_id: team_id, name: name })
+      Project.new(data)
+    end
+
+    # Delete a project.
+    #
+    # @param project_id [String] Project ID
+    def delete_project(project_id:)
+      request(:delete, "/api/v1/projects/#{project_id}")
+      nil
+    end
+
+    # =========================================================================
+    # Environments
+    # =========================================================================
+
+    # List environments in a project.
+    #
+    # @param project_id [String] Project ID
+    # @return [Array<Environment>] List of environments
+    def list_environments(project_id:)
+      data = request(:get, "/api/v1/projects/#{project_id}/environments")
+      (data["environments"] || []).map { |e| Environment.new(e) }
+    end
+
+    # Create a new environment.
+    #
+    # @param project_id [String] Project ID
+    # @param name [String] Environment name
+    # @param inherits_from [String, nil] Parent environment to inherit from
+    # @return [Environment] Created environment
+    def create_environment(project_id:, name:, inherits_from: nil)
+      payload = { name: name }
+      payload[:inherits_from] = inherits_from if inherits_from
+      data = request(:post, "/api/v1/projects/#{project_id}/environments", payload)
+      Environment.new(data)
+    end
+
+    # Delete an environment.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    def delete_environment(project_id:, environment:)
+      request(:delete, "/api/v1/projects/#{project_id}/environments/#{environment}")
+      nil
+    end
+
+    # =========================================================================
+    # Secrets
+    # =========================================================================
+
+    # List secrets in an environment (keys and metadata only).
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [Array<Secret>] List of secrets
+    def list_secrets(project_id:, environment:)
+      data = request(:get, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets")
+      (data["secrets"] || []).map { |s| Secret.new(s) }
+    end
+
+    # Export all secrets with their decrypted values.
+    # Results are cached when cache_ttl > 0.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [Array<SecretWithValue>] List of secrets with values
+    def export_secrets(project_id:, environment:)
+      cache_key = "#{project_id}:#{environment}"
+
+      # Check cache if TTL > 0
+      if @cache_ttl.positive?
+        cached = @secrets_cache[cache_key]
+        if cached
+          secrets, expires_at = cached
+          return secrets if Time.now.to_f < expires_at
+        end
+      end
+
+      data = request(:get, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/export")
+      secrets = (data["secrets"] || []).map { |s| SecretWithValue.new(s) }
+
+      # Store in cache if TTL > 0
+      if @cache_ttl.positive?
+        @secrets_cache[cache_key] = [secrets, Time.now.to_f + @cache_ttl]
+      end
+
+      secrets
+    end
+
+    # Export secrets as a key-value hash.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [Hash<String, String>] Secrets as key-value pairs
+    def export_secrets_as_hash(project_id:, environment:)
+      secrets = export_secrets(project_id: project_id, environment: environment)
+      secrets.each_with_object({}) { |s, h| h[s.key] = s.value }
+    end
+
+    # Get a single secret with its value.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    # @return [SecretWithValue] Secret with value
+    def get_secret(project_id:, environment:, key:)
+      data = request(:get, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/#{key}")
+      SecretWithValue.new(data["secret"] || data)
+    end
+
+    # Create a new secret.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    # @param value [String] Secret value
+    # @param description [String, nil] Optional description
+    # @return [Secret] Created secret
+    def create_secret(project_id:, environment:, key:, value:, description: nil)
+      payload = { key: key, value: value }
+      payload[:description] = description if description
+      data = request(:post, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets", payload)
+      clear_cache(project_id: project_id, environment: environment)
+      Secret.new(data["secret"] || data)
+    end
+
+    # Update a secret's value.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    # @param value [String] New secret value
+    # @param description [String, nil] Optional new description
+    # @return [Secret] Updated secret
+    def update_secret(project_id:, environment:, key:, value:, description: nil)
+      payload = { value: value }
+      payload[:description] = description unless description.nil?
+      data = request(:put, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/#{key}", payload)
+      clear_cache(project_id: project_id, environment: environment)
+      Secret.new(data["secret"] || data)
+    end
+
+    # Set a secret (create or update).
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    # @param value [String] Secret value
+    # @param description [String, nil] Optional description
+    # @return [Secret] Created or updated secret
+    def set_secret(project_id:, environment:, key:, value:, description: nil)
+      update_secret(project_id: project_id, environment: environment, key: key, value: value, description: description)
+    rescue NotFoundError
+      create_secret(project_id: project_id, environment: environment, key: key, value: value, description: description)
+    end
+
+    # Delete a secret.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    def delete_secret(project_id:, environment:, key:)
+      request(:delete, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/#{key}")
+      clear_cache(project_id: project_id, environment: environment)
+      nil
+    end
+
+    # Get secret version history.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param key [String] Secret key
+    # @return [Array<SecretHistory>] Secret version history
+    def get_secret_history(project_id:, environment:, key:)
+      data = request(:get, "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/#{key}/history")
+      (data["history"] || []).map { |h| SecretHistory.new(h) }
+    end
+
+    # Bulk import secrets.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param secrets [Array<BulkSecretItem, Hash>] List of secrets to import
+    # @param overwrite [Boolean] Whether to overwrite existing secrets
+    # @return [BulkImportResult] Import result
+    def bulk_import(project_id:, environment:, secrets:, overwrite: false)
+      secret_list = secrets.map { |s| s.is_a?(BulkSecretItem) ? s.to_h : s }
+      data = request(
+        :post,
+        "/api/v1/projects/#{project_id}/environments/#{environment}/secrets/bulk",
+        { secrets: secret_list, overwrite: overwrite }
+      )
+      clear_cache(project_id: project_id, environment: environment)
+      BulkImportResult.new(data)
+    end
+
+    # =========================================================================
+    # Utilities
+    # =========================================================================
+
+    # Load secrets into ENV.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [Integer] Number of secrets loaded
+    def load_env(project_id:, environment:)
+      secrets = export_secrets(project_id: project_id, environment: environment)
+      secrets.each { |s| ENV[s.key] = s.value }
+      secrets.size
+    end
+
+    # Generate .env file content from secrets.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [String] .env file content
+    def generate_env_file(project_id:, environment:)
+      secrets = export_secrets(project_id: project_id, environment: environment)
+      lines = [
+        "# Generated by KeyEnv",
+        "# Environment: #{environment}",
+        "# Generated at: #{Time.now.utc.iso8601}",
+        ""
+      ]
+
+      secrets.each do |secret|
+        value = secret.value
+        if value.include?("\n") || value.include?('"') || value.include?("'") || value.include?(" ") || value.include?("$")
+          escaped = value.gsub("\\", "\\\\").gsub('"', '\\"').gsub("\n", "\\n").gsub("$", "\\$")
+          lines << %(#{secret.key}="#{escaped}")
+        else
+          lines << "#{secret.key}=#{value}"
+        end
+      end
+
+      lines.join("\n") + "\n"
+    end
+
+    # Clear the secrets cache.
+    #
+    # @param project_id [String, nil] Clear cache for specific project (optional)
+    # @param environment [String, nil] Clear cache for specific environment (requires project_id)
+    def clear_cache(project_id: nil, environment: nil)
+      if project_id && environment
+        cache_key = "#{project_id}:#{environment}"
+        @secrets_cache.delete(cache_key)
+      elsif project_id
+        @secrets_cache.delete_if { |k, _| k.start_with?("#{project_id}:") }
+      else
+        @secrets_cache.clear
+      end
+    end
+
+    # =========================================================================
+    # Environment Permissions
+    # =========================================================================
+
+    # List permissions for an environment.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @return [Array<EnvironmentPermission>] List of permissions
+    def list_permissions(project_id:, environment:)
+      data = request(:get, "/api/v1/projects/#{project_id}/environments/#{environment}/permissions")
+      (data["permissions"] || []).map { |p| EnvironmentPermission.new(p) }
+    end
+
+    # Set a user's permission for an environment.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param user_id [String] User ID
+    # @param role [String] Role ("none", "read", "write", or "admin")
+    # @return [EnvironmentPermission] Created or updated permission
+    def set_permission(project_id:, environment:, user_id:, role:)
+      data = request(
+        :put,
+        "/api/v1/projects/#{project_id}/environments/#{environment}/permissions/#{user_id}",
+        { role: role }
+      )
+      EnvironmentPermission.new(data)
+    end
+
+    # Delete a user's permission for an environment.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param user_id [String] User ID
+    def delete_permission(project_id:, environment:, user_id:)
+      request(:delete, "/api/v1/projects/#{project_id}/environments/#{environment}/permissions/#{user_id}")
+      nil
+    end
+
+    # Bulk set permissions for an environment.
+    #
+    # @param project_id [String] Project ID
+    # @param environment [String] Environment name
+    # @param permissions [Array<Hash>] List of permission hashes with "user_id" and "role" keys
+    # @return [Array<EnvironmentPermission>] Created or updated permissions
+    def bulk_set_permissions(project_id:, environment:, permissions:)
+      data = request(
+        :put,
+        "/api/v1/projects/#{project_id}/environments/#{environment}/permissions",
+        { permissions: permissions }
+      )
+      (data["permissions"] || []).map { |p| EnvironmentPermission.new(p) }
+    end
+
+    # Get current user's permissions for all environments in a project.
+    #
+    # @param project_id [String] Project ID
+    # @return [Array<(Array<MyPermission>, Boolean)>] Tuple of (permissions, is_team_admin)
+    def get_my_permissions(project_id:)
+      data = request(:get, "/api/v1/projects/#{project_id}/my-permissions")
+      permissions = (data["permissions"] || []).map { |p| MyPermission.new(p) }
+      is_team_admin = data["is_team_admin"] || false
+      [permissions, is_team_admin]
+    end
+
+    # Get default permissions for a project.
+    #
+    # @param project_id [String] Project ID
+    # @return [Array<ProjectDefault>] List of project defaults
+    def get_project_defaults(project_id:)
+      data = request(:get, "/api/v1/projects/#{project_id}/permissions/defaults")
+      (data["defaults"] || []).map { |d| ProjectDefault.new(d) }
+    end
+
+    # Set default permissions for a project.
+    #
+    # @param project_id [String] Project ID
+    # @param defaults [Array<Hash>] List of default hashes with "environment_name" and "default_role" keys
+    # @return [Array<ProjectDefault>] Updated project defaults
+    def set_project_defaults(project_id:, defaults:)
+      data = request(
+        :put,
+        "/api/v1/projects/#{project_id}/permissions/defaults",
+        { defaults: defaults }
+      )
+      (data["defaults"] || []).map { |d| ProjectDefault.new(d) }
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      uri = URI.join(@base_url, path)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = build_request(method, uri, body)
+      response = http.request(request)
+
+      handle_response(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      raise TimeoutError.new("Request timeout", status: 408)
+    rescue SocketError, Errno::ECONNREFUSED => e
+      raise ConnectionError.new(e.message, status: 0)
+    end
+
+    def build_request(method, uri, body)
+      request_class = case method
+                      when :get then Net::HTTP::Get
+                      when :post then Net::HTTP::Post
+                      when :put then Net::HTTP::Put
+                      when :delete then Net::HTTP::Delete
+                      else raise ArgumentError, "Unknown HTTP method: #{method}"
+                      end
+
+      request = request_class.new(uri)
+      request["Authorization"] = "Bearer #{@token}"
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "keyenv-ruby/#{VERSION}"
+      request.body = JSON.generate(body) if body
+
+      request
+    end
+
+    def handle_response(response)
+      return nil if response.code == "204"
+
+      body = response.body
+      data = body && !body.empty? ? JSON.parse(body) : {}
+
+      unless response.is_a?(Net::HTTPSuccess)
+        status = response.code.to_i
+        message = data["error"] || "Unknown error"
+        code = data["code"]
+        details = data["details"]
+
+        error_class = case status
+                      when 401 then AuthenticationError
+                      when 404 then NotFoundError
+                      when 422 then ValidationError
+                      when 429 then RateLimitError
+                      else Error
+                      end
+
+        raise error_class.new(message, status: status, code: code, details: details)
+      end
+
+      data
+    rescue JSON::ParserError
+      raise Error.new(response.body || "Unknown error", status: response.code.to_i)
+    end
+  end
+end

data/lib/keyenv/error.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module KeyEnv
+  # Base error class for KeyEnv API errors.
+  class Error < StandardError
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [String, nil] Error code from API
+    attr_reader :code
+
+    # @return [Hash, nil] Additional error details
+    attr_reader :details
+
+    # @return [String] Original error message
+    attr_reader :original_message
+
+    # @param message [String] Error message
+    # @param status [Integer] HTTP status code (default: 0)
+    # @param code [String, nil] Error code from API
+    # @param details [Hash, nil] Additional error details
+    def initialize(message, status: 0, code: nil, details: nil)
+      @original_message = message
+      @status = status
+      @code = code
+      @details = details || {}
+      super(message)
+    end
+
+    def to_s
+      if status.positive?
+        "KeyEnvError(#{status}): #{@original_message}"
+      else
+        "KeyEnvError: #{@original_message}"
+      end
+    end
+  end
+
+  # Raised when authentication fails.
+  class AuthenticationError < Error; end
+
+  # Raised when a resource is not found.
+  class NotFoundError < Error; end
+
+  # Raised when the request is invalid.
+  class ValidationError < Error; end
+
+  # Raised when rate limited.
+  class RateLimitError < Error; end
+
+  # Raised on network/connection errors.
+  class ConnectionError < Error; end
+
+  # Raised on request timeout.
+  class TimeoutError < Error; end
+end

data/lib/keyenv/types.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module KeyEnv
+  # User or service token info.
+  class User
+    attr_reader :id, :email, :name, :clerk_id, :avatar_url, :auth_type,
+                :team_id, :project_ids, :scopes, :created_at
+
+    def initialize(data)
+      @id = data["id"]
+      @email = data["email"]
+      @name = data["name"]
+      @clerk_id = data["clerk_id"]
+      @avatar_url = data["avatar_url"]
+      @auth_type = data["auth_type"]
+      @team_id = data["team_id"]
+      @project_ids = data["project_ids"]
+      @scopes = data["scopes"]
+      @created_at = data["created_at"]
+    end
+  end
+
+  # Project.
+  class Project
+    attr_reader :id, :team_id, :name, :slug, :description, :created_at
+
+    def initialize(data)
+      @id = data["id"]
+      @team_id = data["team_id"]
+      @name = data["name"]
+      @slug = data["slug"]
+      @description = data["description"]
+      @created_at = data["created_at"]
+    end
+  end
+
+  # Environment.
+  class Environment
+    attr_reader :id, :project_id, :name, :inherits_from, :created_at
+
+    def initialize(data)
+      @id = data["id"]
+      @project_id = data["project_id"]
+      @name = data["name"]
+      @inherits_from = data["inherits_from"]
+      @created_at = data["created_at"]
+    end
+  end
+
+  # Project with environments.
+  class ProjectWithEnvironments < Project
+    attr_reader :environments
+
+    def initialize(data)
+      super(data)
+      envs = data["environments"] || []
+      @environments = envs.map { |e| Environment.new(e) }
+    end
+  end
+
+  # Secret (without value).
+  class Secret
+    attr_reader :id, :environment_id, :key, :type, :version,
+                :description, :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @environment_id = data["environment_id"]
+      @key = data["key"]
+      @type = data["type"] || "string"
+      @version = data["version"]
+      @description = data["description"]
+      @created_at = data["created_at"]
+      @updated_at = data["updated_at"]
+    end
+  end
+
+  # Secret with decrypted value.
+  class SecretWithValue < Secret
+    attr_reader :value, :inherited_from
+
+    def initialize(data)
+      super(data)
+      @value = data["value"] || ""
+      @inherited_from = data["inherited_from"]
+    end
+  end
+
+  # Secret history entry.
+  class SecretHistory
+    attr_reader :id, :secret_id, :value, :version, :changed_by, :changed_at
+
+    def initialize(data)
+      @id = data["id"]
+      @secret_id = data["secret_id"]
+      @value = data["value"]
+      @version = data["version"]
+      @changed_by = data["changed_by"]
+      @changed_at = data["changed_at"]
+    end
+  end
+
+  # Bulk import request item.
+  class BulkSecretItem
+    attr_reader :key, :value, :description
+
+    def initialize(key:, value:, description: nil)
+      @key = key
+      @value = value
+      @description = description
+    end
+
+    def to_h
+      h = { "key" => key, "value" => value }
+      h["description"] = description if description
+      h
+    end
+  end
+
+  # Bulk import result.
+  class BulkImportResult
+    attr_reader :created, :updated, :skipped
+
+    def initialize(data)
+      @created = data["created"] || 0
+      @updated = data["updated"] || 0
+      @skipped = data["skipped"] || 0
+    end
+  end
+
+  # Environment permission for a user.
+  class EnvironmentPermission
+    attr_reader :id, :environment_id, :user_id, :role, :user_email,
+                :user_name, :granted_by, :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @environment_id = data["environment_id"]
+      @user_id = data["user_id"]
+      @role = data["role"]
+      @user_email = data["user_email"]
+      @user_name = data["user_name"]
+      @granted_by = data["granted_by"]
+      @created_at = data["created_at"] || ""
+      @updated_at = data["updated_at"] || ""
+    end
+  end
+
+  # User's own permission for an environment.
+  class MyPermission
+    attr_reader :environment_id, :environment_name, :role,
+                :can_read, :can_write, :can_admin
+
+    def initialize(data)
+      @environment_id = data["environment_id"]
+      @environment_name = data["environment_name"]
+      @role = data["role"]
+      @can_read = data["can_read"]
+      @can_write = data["can_write"]
+      @can_admin = data["can_admin"]
+    end
+  end
+
+  # Default permission for an environment in a project.
+  class ProjectDefault
+    attr_reader :id, :project_id, :environment_name, :default_role, :created_at
+
+    def initialize(data)
+      @id = data["id"]
+      @project_id = data["project_id"]
+      @environment_name = data["environment_name"]
+      @default_role = data["default_role"]
+      @created_at = data["created_at"] || ""
+    end
+  end
+end

data/lib/keyenv/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module KeyEnv
+  VERSION = "1.1.0"
+end

data/lib/keyenv.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# KeyEnv Ruby SDK - Secure secrets management for development teams.
+
+require_relative "keyenv/version"
+require_relative "keyenv/error"
+require_relative "keyenv/types"
+require_relative "keyenv/client"
+
+module KeyEnv
+  class << self
+    # Create a new KeyEnv client.
+    #
+    # @param token [String] Service token for authentication
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param cache_ttl [Integer] Cache TTL in seconds (default: 0 = disabled)
+    # @param base_url [String, nil] Custom API base URL (default: https://api.keyenv.dev)
+    # @return [Client] KeyEnv client instance
+    #
+    # @example
+    #   client = KeyEnv.new(token: "your-service-token")
+    #   secrets = client.export_secrets(project_id: "proj_123", environment: "production")
+    #
+    def new(token:, timeout: 30, cache_ttl: 0, base_url: nil)
+      Client.new(token: token, timeout: timeout, cache_ttl: cache_ttl, base_url: base_url)
+    end
+
+    # Create a new KeyEnv client (alternative syntax).
+    #
+    # @param token [String] Service token for authentication
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param cache_ttl [Integer] Cache TTL in seconds (default: 0 = disabled)
+    # @param base_url [String, nil] Custom API base URL (default: https://api.keyenv.dev)
+    # @return [Client] KeyEnv client instance
+    #
+    # @example
+    #   client = KeyEnv.create("your-service-token")
+    #   secret = client.get_secret(project_id: "proj_123", environment: "production", key: "API_KEY")
+    #
+    def create(token, timeout: 30, cache_ttl: 0, base_url: nil)
+      Client.new(token: token, timeout: timeout, cache_ttl: cache_ttl, base_url: base_url)
+    end
+  end
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: keyenv
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- KeyEnv
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: KeyEnv Ruby SDK provides a simple interface for managing secrets in your
+  Ruby applications. Fetch, create, and manage environment variables securely.
+email:
+- support@keyenv.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/keyenv.rb
+- lib/keyenv/client.rb
+- lib/keyenv/error.rb
+- lib/keyenv/types.rb
+- lib/keyenv/version.rb
+homepage: https://keyenv.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://keyenv.dev
+  source_code_uri: https://github.com/keyenv/ruby-sdk
+  changelog_uri: https://github.com/keyenv/ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://keyenv.dev/docs/sdks/ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for KeyEnv - Secure secrets management
+test_files: []