cadenya 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dff0947b39a815faaea2a4f68747c1d0117318d8f2aee08f8bca4cab40b69f7
-  data.tar.gz: ec5c0bb41033ed07ab07d33fd24dac1853b9ec65280dc8493902646d62e5eb03
+  metadata.gz: e7f15c89788992e84faa1b1a059033314f7c115317be1f0fdba0e49793bc0aa6
+  data.tar.gz: d56587810401e084e8b5497254d6a6680fc22b3eff1bf70af6bc20461a3b19e1
 SHA512:
-  metadata.gz: 146f613ac26f3669be288789e44d5727defcbf3373b5fe74c0b5cd11352476be830358a4def179cddb144192629ad7e14c798cb25ac48907c7379879e6ce5a60
-  data.tar.gz: 553296baa57d871c6f99976e480f3f67c60cb1afc6fda396816a4a3c4f263e3ceb588ebb64f9ce2070a53cbf1ecf03ba14c0b90d9f0ef48773786715ea3c04e2
+  metadata.gz: c696765a5ffb6e7c97c6b3cb729b711fe424626b45e6e0732ef37a5dc9b56bde28f8ca54d0db305657bf459b4e3dfa3081f905e26a17a6e503b3b5709b82ef38
+  data.tar.gz: 9f178edbcaf810c598ccf931ee62bc8c68479f41128c63143852a255b673dcd69e1306706407cf7c0bb7f2ced5c8c581be9d45be426d04ab0306e3ce13e934cc

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 (2026-06-07)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/cadenya/cadenya-ruby/compare/v0.3.0...v0.4.0)
+
+### Features
+
+* Add AI Provider CRUD endpoints ([91caf5c](https://github.com/cadenya/cadenya-ruby/commit/91caf5c762a8e75460076b4a9a864c9a34345720))
+
 ## 0.3.0 (2026-06-05)
 
 Full Changelog: [v0.2.0...v0.3.0](https://github.com/cadenya/cadenya-ruby/compare/v0.2.0...v0.3.0)

data/README.md

@@ -26,7 +26,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "cadenya", "~> 0.3.0"
+gem "cadenya", "~> 0.4.0"
 ```
 
 <!-- x-release-please-end -->
@@ -53,15 +53,15 @@ List methods in the Cadenya API are paginated.
 This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
 
 ```ruby
-page = cadenya.agents.list
+page = cadenya.ai_provider_keys.list
 
 # Fetch single item from page.
-agent = page.items[0]
-puts(agent.metadata)
+ai_provider_key = page.items[0]
+puts(ai_provider_key.metadata)
 
 # Automatically fetches more pages as needed.
-page.auto_paging_each do |agent|
-  puts(agent.metadata)
+page.auto_paging_each do |ai_provider_key|
+  puts(ai_provider_key.metadata)
 end
 ```
 

data/lib/cadenya/client.rb

@@ -21,6 +21,9 @@ module Cadenya
     # @return [String, nil]
     attr_reader :webhook_key
 
+    # @return [Cadenya::Resources::AIProviderKeys]
+    attr_reader :ai_provider_keys
+
     # Manage the authenticated account. Accounts are the top-level organizational unit
     # and contain one or more workspaces.
     # @return [Cadenya::Resources::Account]
@@ -163,6 +166,7 @@ module Cadenya
         headers: headers
       )
 
+      @ai_provider_keys = Cadenya::Resources::AIProviderKeys.new(client: self)
       @account = Cadenya::Resources::Account.new(client: self)
       @agents = Cadenya::Resources::Agents.new(client: self)
       @objectives = Cadenya::Resources::Objectives.new(client: self)

data/lib/cadenya/internal/cursor_pagination.rb

@@ -10,8 +10,8 @@ module Cadenya
     #   end
     #
     # @example
-    #   cursor_pagination.auto_paging_each do |agent|
-    #     puts(agent)
+    #   cursor_pagination.auto_paging_each do |ai_provider_key|
+    #     puts(ai_provider_key)
     #   end
     class CursorPagination
       include Cadenya::Internal::Type::BasePage

data/lib/cadenya/models/ai_provider_key.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#create
+    class AIProviderKey < Cadenya::Internal::Type::BaseModel
+      # @!attribute metadata
+      #   Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+      #
+      #   @return [Cadenya::Models::ResourceMetadata]
+      required :metadata, -> { Cadenya::ResourceMetadata }
+
+      # @!attribute spec
+      #
+      #   @return [Cadenya::Models::AIProviderKeySpec]
+      required :spec, -> { Cadenya::AIProviderKeySpec }
+
+      # @!method initialize(metadata:, spec:)
+      #   Some parameter documentations has been truncated, see
+      #   {Cadenya::Models::AIProviderKey} for more details.
+      #
+      #   AIProviderKey is a customer-provided (BYOK) credential for an AI provider,
+      #   scoped to a workspace. The secret value is never returned in responses.
+      #
+      #   @param metadata [Cadenya::Models::ResourceMetadata] Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+      #
+      #   @param spec [Cadenya::Models::AIProviderKeySpec]
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_create_params.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#create
+    class AIProviderKeyCreateParams < Cadenya::Internal::Type::BaseModel
+      extend Cadenya::Internal::Type::RequestParameters::Converter
+      include Cadenya::Internal::Type::RequestParameters
+
+      # @!attribute workspace_id
+      #
+      #   @return [String]
+      required :workspace_id, String
+
+      # @!attribute metadata
+      #   CreateResourceMetadata contains the user-provided fields for creating a
+      #   workspace-scoped resource. Read-only fields (id, account_id, workspace_id,
+      #   profile_id, created_at) are excluded since they are set by the server.
+      #
+      #   @return [Cadenya::Models::CreateResourceMetadata]
+      required :metadata, -> { Cadenya::CreateResourceMetadata }
+
+      # @!attribute spec
+      #
+      #   @return [Cadenya::Models::AIProviderKeySpec]
+      required :spec, -> { Cadenya::AIProviderKeySpec }
+
+      # @!method initialize(workspace_id:, metadata:, spec:, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Cadenya::Models::AIProviderKeyCreateParams} for more details.
+      #
+      #   @param workspace_id [String]
+      #
+      #   @param metadata [Cadenya::Models::CreateResourceMetadata] CreateResourceMetadata contains the user-provided fields for creating
+      #
+      #   @param spec [Cadenya::Models::AIProviderKeySpec]
+      #
+      #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_delete_params.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#delete
+    class AIProviderKeyDeleteParams < Cadenya::Internal::Type::BaseModel
+      extend Cadenya::Internal::Type::RequestParameters::Converter
+      include Cadenya::Internal::Type::RequestParameters
+
+      # @!attribute workspace_id
+      #
+      #   @return [String]
+      required :workspace_id, String
+
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!method initialize(workspace_id:, id:, request_options: {})
+      #   @param workspace_id [String]
+      #   @param id [String]
+      #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_list_params.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#list
+    class AIProviderKeyListParams < Cadenya::Internal::Type::BaseModel
+      extend Cadenya::Internal::Type::RequestParameters::Converter
+      include Cadenya::Internal::Type::RequestParameters
+
+      # @!attribute workspace_id
+      #
+      #   @return [String]
+      required :workspace_id, String
+
+      # @!attribute cursor
+      #   Pagination cursor from previous response
+      #
+      #   @return [String, nil]
+      optional :cursor, String
+
+      # @!attribute limit
+      #   Maximum number of results to return
+      #
+      #   @return [Integer, nil]
+      optional :limit, Integer
+
+      # @!attribute prefix
+      #   Filter expression (query param: prefix)
+      #
+      #   @return [String, nil]
+      optional :prefix, String
+
+      # @!attribute query
+      #   Free-form search query
+      #
+      #   @return [String, nil]
+      optional :query, String
+
+      # @!attribute sort_order
+      #   Sort order for results (asc or desc by creation time)
+      #
+      #   @return [String, nil]
+      optional :sort_order, String
+
+      # @!method initialize(workspace_id:, cursor: nil, limit: nil, prefix: nil, query: nil, sort_order: nil, request_options: {})
+      #   @param workspace_id [String]
+      #
+      #   @param cursor [String] Pagination cursor from previous response
+      #
+      #   @param limit [Integer] Maximum number of results to return
+      #
+      #   @param prefix [String] Filter expression (query param: prefix)
+      #
+      #   @param query [String] Free-form search query
+      #
+      #   @param sort_order [String] Sort order for results (asc or desc by creation time)
+      #
+      #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_retrieve_params.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#retrieve
+    class AIProviderKeyRetrieveParams < Cadenya::Internal::Type::BaseModel
+      extend Cadenya::Internal::Type::RequestParameters::Converter
+      include Cadenya::Internal::Type::RequestParameters
+
+      # @!attribute workspace_id
+      #
+      #   @return [String]
+      required :workspace_id, String
+
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!method initialize(workspace_id:, id:, request_options: {})
+      #   @param workspace_id [String]
+      #   @param id [String]
+      #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    class AIProviderKeySpec < Cadenya::Internal::Type::BaseModel
+      # @!attribute api_key
+      #   The provider credential. Accepted on create/update; never populated in responses
+      #   (the server returns an empty value to avoid leaking it).
+      #
+      #   @return [String, nil]
+      optional :api_key, String, api_name: :apiKey
+
+      # @!attribute provider
+      #   The AI provider this key authenticates against. Currently "openrouter".
+      #
+      #   @return [String, nil]
+      optional :provider, String
+
+      # @!attribute region
+      #   The provider region. "us" or "eu". Defaults to "us".
+      #
+      #   @return [String, nil]
+      optional :region, String
+
+      # @!method initialize(api_key: nil, provider: nil, region: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Cadenya::Models::AIProviderKeySpec} for more details.
+      #
+      #   @param api_key [String] The provider credential. Accepted on create/update; never populated in
+      #
+      #   @param provider [String] The AI provider this key authenticates against. Currently "openrouter".
+      #
+      #   @param region [String] The provider region. "us" or "eu". Defaults to "us".
+    end
+  end
+end

data/lib/cadenya/models/ai_provider_key_update_params.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Models
+    # @see Cadenya::Resources::AIProviderKeys#update
+    class AIProviderKeyUpdateParams < Cadenya::Internal::Type::BaseModel
+      extend Cadenya::Internal::Type::RequestParameters::Converter
+      include Cadenya::Internal::Type::RequestParameters
+
+      # @!attribute workspace_id
+      #
+      #   @return [String]
+      required :workspace_id, String
+
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute metadata
+      #   UpdateResourceMetadata contains the user-provided fields for updating a
+      #   workspace-scoped resource. Read-only fields (id, account_id, workspace_id,
+      #   profile_id, created_at) are excluded since they are set by the server.
+      #
+      #   @return [Cadenya::Models::UpdateResourceMetadata, nil]
+      optional :metadata, -> { Cadenya::UpdateResourceMetadata }
+
+      # @!attribute spec
+      #
+      #   @return [Cadenya::Models::AIProviderKeySpec, nil]
+      optional :spec, -> { Cadenya::AIProviderKeySpec }
+
+      # @!attribute update_mask
+      #   Fields to update.
+      #
+      #   @return [String, nil]
+      optional :update_mask, String, api_name: :updateMask
+
+      # @!method initialize(workspace_id:, id:, metadata: nil, spec: nil, update_mask: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Cadenya::Models::AIProviderKeyUpdateParams} for more details.
+      #
+      #   @param workspace_id [String]
+      #
+      #   @param id [String]
+      #
+      #   @param metadata [Cadenya::Models::UpdateResourceMetadata] UpdateResourceMetadata contains the user-provided fields for updating
+      #
+      #   @param spec [Cadenya::Models::AIProviderKeySpec]
+      #
+      #   @param update_mask [String] Fields to update.
+      #
+      #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/cadenya/models.rb

@@ -75,6 +75,20 @@ module Cadenya
 
   AgentVariationEntry = Cadenya::Models::AgentVariationEntry
 
+  AIProviderKey = Cadenya::Models::AIProviderKey
+
+  AIProviderKeyCreateParams = Cadenya::Models::AIProviderKeyCreateParams
+
+  AIProviderKeyDeleteParams = Cadenya::Models::AIProviderKeyDeleteParams
+
+  AIProviderKeyListParams = Cadenya::Models::AIProviderKeyListParams
+
+  AIProviderKeyRetrieveParams = Cadenya::Models::AIProviderKeyRetrieveParams
+
+  AIProviderKeySpec = Cadenya::Models::AIProviderKeySpec
+
+  AIProviderKeyUpdateParams = Cadenya::Models::AIProviderKeyUpdateParams
+
   APIKey = Cadenya::Models::APIKey
 
   APIKeyCreateParams = Cadenya::Models::APIKeyCreateParams

data/lib/cadenya/resources/ai_provider_keys.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Cadenya
+  module Resources
+    class AIProviderKeys
+      # Some parameter documentations has been truncated, see
+      # {Cadenya::Models::AIProviderKeyCreateParams} for more details.
+      #
+      # Creates a new customer-provided AI provider key in the workspace
+      #
+      # @overload create(workspace_id, metadata:, spec:, request_options: {})
+      #
+      # @param workspace_id [String] The workspace that will own this key.
+      #
+      # @param metadata [Cadenya::Models::CreateResourceMetadata] CreateResourceMetadata contains the user-provided fields for creating
+      #
+      # @param spec [Cadenya::Models::AIProviderKeySpec]
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cadenya::Models::AIProviderKey]
+      #
+      # @see Cadenya::Models::AIProviderKeyCreateParams
+      def create(workspace_id, params)
+        parsed, options = Cadenya::AIProviderKeyCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["v1/workspaces/%1$s/ai_provider_keys", workspace_id],
+          body: parsed,
+          model: Cadenya::AIProviderKey,
+          options: options
+        )
+      end
+
+      # Retrieves an AI provider key by ID from the workspace
+      #
+      # @overload retrieve(id, workspace_id:, request_options: {})
+      #
+      # @param id [String] The key to retrieve.
+      #
+      # @param workspace_id [String] The workspace the key belongs to.
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cadenya::Models::AIProviderKey]
+      #
+      # @see Cadenya::Models::AIProviderKeyRetrieveParams
+      def retrieve(id, params)
+        parsed, options = Cadenya::AIProviderKeyRetrieveParams.dump_request(params)
+        workspace_id =
+          parsed.delete(:workspace_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["v1/workspaces/%1$s/ai_provider_keys/%2$s", workspace_id, id],
+          model: Cadenya::AIProviderKey,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Cadenya::Models::AIProviderKeyUpdateParams} for more details.
+      #
+      # Updates an AI provider key's name or key value in the workspace
+      #
+      # @overload update(id, workspace_id:, metadata: nil, spec: nil, update_mask: nil, request_options: {})
+      #
+      # @param id [String] Path param: The key to update.
+      #
+      # @param workspace_id [String] Path param: The workspace the key belongs to.
+      #
+      # @param metadata [Cadenya::Models::UpdateResourceMetadata] Body param: UpdateResourceMetadata contains the user-provided fields for updatin
+      #
+      # @param spec [Cadenya::Models::AIProviderKeySpec] Body param
+      #
+      # @param update_mask [String] Body param: Fields to update.
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cadenya::Models::AIProviderKey]
+      #
+      # @see Cadenya::Models::AIProviderKeyUpdateParams
+      def update(id, params)
+        parsed, options = Cadenya::AIProviderKeyUpdateParams.dump_request(params)
+        workspace_id =
+          parsed.delete(:workspace_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :patch,
+          path: ["v1/workspaces/%1$s/ai_provider_keys/%2$s", workspace_id, id],
+          body: parsed,
+          model: Cadenya::AIProviderKey,
+          options: options
+        )
+      end
+
+      # Lists all customer-provided AI provider keys in the workspace
+      #
+      # @overload list(workspace_id, cursor: nil, limit: nil, prefix: nil, query: nil, sort_order: nil, request_options: {})
+      #
+      # @param workspace_id [String] The workspace whose keys will be listed.
+      #
+      # @param cursor [String] Pagination cursor from previous response
+      #
+      # @param limit [Integer] Maximum number of results to return
+      #
+      # @param prefix [String] Filter expression (query param: prefix)
+      #
+      # @param query [String] Free-form search query
+      #
+      # @param sort_order [String] Sort order for results (asc or desc by creation time)
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cadenya::Internal::CursorPagination<Cadenya::Models::AIProviderKey>]
+      #
+      # @see Cadenya::Models::AIProviderKeyListParams
+      def list(workspace_id, params = {})
+        parsed, options = Cadenya::AIProviderKeyListParams.dump_request(params)
+        query = Cadenya::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["v1/workspaces/%1$s/ai_provider_keys", workspace_id],
+          query: query.transform_keys(sort_order: "sortOrder"),
+          page: Cadenya::Internal::CursorPagination,
+          model: Cadenya::AIProviderKey,
+          options: options
+        )
+      end
+
+      # Deletes an AI provider key from the workspace
+      #
+      # @overload delete(id, workspace_id:, request_options: {})
+      #
+      # @param id [String] The key to delete.
+      #
+      # @param workspace_id [String] The workspace the key belongs to.
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Cadenya::Models::AIProviderKeyDeleteParams
+      def delete(id, params)
+        parsed, options = Cadenya::AIProviderKeyDeleteParams.dump_request(params)
+        workspace_id =
+          parsed.delete(:workspace_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :delete,
+          path: ["v1/workspaces/%1$s/ai_provider_keys/%2$s", workspace_id, id],
+          model: NilClass,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Cadenya::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/cadenya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cadenya
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/cadenya.rb

@@ -108,6 +108,13 @@ require_relative "cadenya/models/agent_schedule_entry"
 require_relative "cadenya/models/agent_spec"
 require_relative "cadenya/models/agent_update_params"
 require_relative "cadenya/models/agent_variation_entry"
+require_relative "cadenya/models/ai_provider_key"
+require_relative "cadenya/models/ai_provider_key_create_params"
+require_relative "cadenya/models/ai_provider_key_delete_params"
+require_relative "cadenya/models/ai_provider_key_list_params"
+require_relative "cadenya/models/ai_provider_key_retrieve_params"
+require_relative "cadenya/models/ai_provider_key_spec"
+require_relative "cadenya/models/ai_provider_key_update_params"
 require_relative "cadenya/models/api_key"
 require_relative "cadenya/models/api_key_create_params"
 require_relative "cadenya/models/api_key_delete_params"
@@ -309,6 +316,7 @@ require_relative "cadenya/resources/agents/feedback"
 require_relative "cadenya/resources/agents/schedules"
 require_relative "cadenya/resources/agents/variations"
 require_relative "cadenya/resources/agents/webhook_deliveries"
+require_relative "cadenya/resources/ai_provider_keys"
 require_relative "cadenya/resources/api_keys"
 require_relative "cadenya/resources/api_keys/access"
 require_relative "cadenya/resources/bulk_workspace_resources"

data/rbi/cadenya/client.rbi

@@ -16,6 +16,9 @@ module Cadenya
     sig { returns(T.nilable(String)) }
     attr_reader :webhook_key
 
+    sig { returns(Cadenya::Resources::AIProviderKeys) }
+    attr_reader :ai_provider_keys
+
     # Manage the authenticated account. Accounts are the top-level organizational unit
     # and contain one or more workspaces.
     sig { returns(Cadenya::Resources::Account) }

data/rbi/cadenya/models/ai_provider_key.rbi

@@ -0,0 +1,51 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    class AIProviderKey < Cadenya::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Cadenya::AIProviderKey, Cadenya::Internal::AnyHash)
+        end
+
+      # Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+      sig { returns(Cadenya::ResourceMetadata) }
+      attr_reader :metadata
+
+      sig { params(metadata: Cadenya::ResourceMetadata::OrHash).void }
+      attr_writer :metadata
+
+      sig { returns(Cadenya::AIProviderKeySpec) }
+      attr_reader :spec
+
+      sig { params(spec: Cadenya::AIProviderKeySpec::OrHash).void }
+      attr_writer :spec
+
+      # AIProviderKey is a customer-provided (BYOK) credential for an AI provider,
+      # scoped to a workspace. The secret value is never returned in responses.
+      sig do
+        params(
+          metadata: Cadenya::ResourceMetadata::OrHash,
+          spec: Cadenya::AIProviderKeySpec::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+        metadata:,
+        spec:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            metadata: Cadenya::ResourceMetadata,
+            spec: Cadenya::AIProviderKeySpec
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end