nahook 0.1.0

data/lib/nahook/resources/applications.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for managing applications via the Management API.
+    #
+    # Applications group endpoints for multi-tenant use cases.
+    # Each application can have its own set of endpoints and a developer portal.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   mgmt.applications.list("ws_abc123", limit: 10)
+    #   mgmt.applications.create("ws_abc123", name: "Acme Corp")
+    class Applications
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List applications in a workspace with optional pagination.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param limit [Integer, nil] maximum number of results
+      # @param offset [Integer, nil] number of results to skip
+      # @return [Hash] response with "data" key containing an array of applications
+      def list(workspace_id, limit: nil, offset: nil)
+        query = {}
+        query["limit"]  = limit  if limit
+        query["offset"] = offset if offset
+
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications",
+          query: query.empty? ? nil : query
+        )
+        { "data" => data }
+      end
+
+      # Create a new application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param name [String] the application name
+      # @param external_id [String, nil] an external identifier for your system
+      # @param metadata [Hash, nil] arbitrary key-value metadata
+      # @return [Hash] the created application
+      def create(workspace_id, name:, external_id: nil, metadata: nil)
+        body = { "name" => name }
+        body["externalId"] = external_id if external_id
+        body["metadata"]   = metadata    if metadata
+
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications",
+          body: body
+        )
+      end
+
+      # Get a single application by ID.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the application public ID
+      # @return [Hash] the application
+      def get(workspace_id, id)
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(id)}"
+        )
+      end
+
+      # Update an existing application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the application public ID
+      # @param name [String, nil] updated name
+      # @param metadata [Hash, nil] updated metadata
+      # @return [Hash] the updated application
+      def update(workspace_id, id, name: nil, metadata: nil)
+        body = {}
+        body["name"]     = name     unless name.nil?
+        body["metadata"] = metadata unless metadata.nil?
+
+        @http.request(
+          method: :patch,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(id)}",
+          body: body
+        )
+      end
+
+      # Delete an application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the application public ID
+      # @return [nil]
+      def delete(workspace_id, id)
+        @http.request(
+          method: :delete,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(id)}"
+        )
+      end
+
+      # List endpoints belonging to an application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param app_id [String] the application public ID
+      # @return [Hash] response with "data" key containing an array of endpoints
+      def list_endpoints(workspace_id, app_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(app_id)}/endpoints"
+        )
+        { "data" => data }
+      end
+
+      # Create an endpoint within an application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param app_id [String] the application public ID
+      # @param url [String] the endpoint URL
+      # @param type [String, nil] endpoint type ("webhook" or "slack")
+      # @param description [String, nil] human-readable description
+      # @param metadata [Hash, nil] arbitrary key-value metadata
+      # @param config [Hash, nil] endpoint-specific configuration
+      # @return [Hash] the created endpoint
+      def create_endpoint(workspace_id, app_id, url:, type: nil, description: nil, metadata: nil, config: nil)
+        body = { "url" => url }
+        body["type"]        = type        if type
+        body["description"] = description if description
+        body["metadata"]    = metadata    if metadata
+        body["config"]      = config      if config
+
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(app_id)}/endpoints",
+          body: body
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/resources/endpoints.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for managing webhook endpoints via the Management API.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   mgmt.endpoints.list("ws_abc123")
+    #   mgmt.endpoints.create("ws_abc123", url: "https://example.com/webhook")
+    class Endpoints
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all endpoints in a workspace.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @return [Hash] response with "data" key containing an array of endpoints
+      def list(workspace_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints"
+        )
+        { "data" => data }
+      end
+
+      # Create a new endpoint.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param url [String] the endpoint URL
+      # @param type [String, nil] endpoint type ("webhook" or "slack")
+      # @param description [String, nil] human-readable description
+      # @param metadata [Hash, nil] arbitrary key-value metadata
+      # @param config [Hash, nil] endpoint-specific configuration
+      # @param auth_username [String, nil] basic auth username
+      # @param auth_password [String, nil] basic auth password
+      # @return [Hash] the created endpoint
+      def create(workspace_id, url:, type: nil, description: nil, metadata: nil, config: nil,
+                 auth_username: nil, auth_password: nil)
+        body = { "url" => url }
+        body["type"]         = type         if type
+        body["description"]  = description  if description
+        body["metadata"]     = metadata     if metadata
+        body["config"]       = config       if config
+        body["authUsername"]  = auth_username if auth_username
+        body["authPassword"] = auth_password if auth_password
+
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints",
+          body: body
+        )
+      end
+
+      # Get a single endpoint by ID.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the endpoint public ID
+      # @return [Hash] the endpoint
+      def get(workspace_id, id)
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(id)}"
+        )
+      end
+
+      # Update an existing endpoint.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the endpoint public ID
+      # @param url [String, nil] updated URL
+      # @param description [String, nil] updated description
+      # @param metadata [Hash, nil] updated metadata
+      # @param is_active [Boolean, nil] whether the endpoint is active
+      # @return [Hash] the updated endpoint
+      def update(workspace_id, id, url: nil, description: nil, metadata: nil, is_active: nil)
+        body = {}
+        body["url"]         = url         unless url.nil?
+        body["description"] = description unless description.nil?
+        body["metadata"]    = metadata    unless metadata.nil?
+        body["isActive"]    = is_active   unless is_active.nil?
+
+        @http.request(
+          method: :patch,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(id)}",
+          body: body
+        )
+      end
+
+      # Delete an endpoint.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the endpoint public ID
+      # @return [nil]
+      def delete(workspace_id, id)
+        @http.request(
+          method: :delete,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(id)}"
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/resources/environments.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for managing environments via the Management API.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   mgmt.environments.list("ws_abc123")
+    #   mgmt.environments.create("ws_abc123", name: "Staging", slug: "staging")
+    class Environments
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all environments in a workspace.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @return [Hash] response with "data" key containing an array of environments
+      def list(workspace_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments"
+        )
+        { "data" => data }
+      end
+
+      # Create a new environment.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param name [String] the environment name
+      # @param slug [String] the environment slug
+      # @return [Hash] the created environment
+      def create(workspace_id, name:, slug:)
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments",
+          body: { "name" => name, "slug" => slug }
+        )
+      end
+
+      # Get a single environment by ID.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the environment ID
+      # @return [Hash] the environment
+      def get(workspace_id, id)
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments/#{e(id)}"
+        )
+      end
+
+      # Update an existing environment.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the environment ID
+      # @param name [String, nil] the updated name
+      # @return [Hash] the updated environment
+      def update(workspace_id, id, name: nil)
+        body = {}
+        body["name"] = name unless name.nil?
+        @http.request(
+          method: :patch,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments/#{e(id)}",
+          body: body
+        )
+      end
+
+      # Delete an environment.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the environment ID
+      # @return [nil]
+      def delete(workspace_id, id)
+        @http.request(
+          method: :delete,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments/#{e(id)}"
+        )
+      end
+
+      # List event type visibility for an environment.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param env_id [String] the environment ID
+      # @return [Hash] response with "data" key containing an array of event type visibility entries
+      def list_event_type_visibility(workspace_id, env_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments/#{e(env_id)}/event-types"
+        )
+        { "data" => data }
+      end
+
+      # Set event type visibility for an environment.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param env_id [String] the environment ID
+      # @param event_type_id [String] the event type ID
+      # @param published [Boolean] whether the event type is published in this environment
+      # @return [Hash] the updated visibility entry
+      def set_event_type_visibility(workspace_id, env_id, event_type_id, published:)
+        @http.request(
+          method: :put,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/environments/#{e(env_id)}/event-types/#{e(event_type_id)}/visibility",
+          body: { "published" => published }
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/resources/event_types.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for managing event types via the Management API.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   mgmt.event_types.list("ws_abc123")
+    #   mgmt.event_types.create("ws_abc123", name: "order.paid")
+    class EventTypes
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List all event types in a workspace.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @return [Hash] response with "data" key containing an array of event types
+      def list(workspace_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/event-types"
+        )
+        { "data" => data }
+      end
+
+      # Create a new event type.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param name [String] the event type name (e.g. "order.paid")
+      # @param description [String, nil] human-readable description
+      # @return [Hash] the created event type
+      def create(workspace_id, name:, description: nil)
+        body = { "name" => name }
+        body["description"] = description if description
+
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/event-types",
+          body: body
+        )
+      end
+
+      # Get a single event type by ID.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the event type public ID
+      # @return [Hash] the event type
+      def get(workspace_id, id)
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/event-types/#{e(id)}"
+        )
+      end
+
+      # Update an existing event type.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the event type public ID
+      # @param description [String, nil] updated description
+      # @return [Hash] the updated event type
+      def update(workspace_id, id, description: nil)
+        body = {}
+        body["description"] = description unless description.nil?
+
+        @http.request(
+          method: :patch,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/event-types/#{e(id)}",
+          body: body
+        )
+      end
+
+      # Delete an event type.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param id [String] the event type public ID
+      # @return [nil]
+      def delete(workspace_id, id)
+        @http.request(
+          method: :delete,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/event-types/#{e(id)}"
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/resources/portal_sessions.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for creating developer portal sessions via the Management API.
+    #
+    # Portal sessions generate short-lived URLs that grant your customers
+    # access to a self-service endpoint management portal.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   session = mgmt.portal_sessions.create("ws_abc123", "app_def456")
+    #   puts session["url"] # => "https://portal.nahook.com/..."
+    class PortalSessions
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # Create a portal session for an application.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param app_id [String] the application public ID
+      # @param metadata [Hash, nil] optional metadata for the session
+      # @return [Hash] session with "url", "code", and "expiresAt" keys
+      def create(workspace_id, app_id, metadata: nil)
+        body = {}
+        body["metadata"] = metadata if metadata
+
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/applications/#{e(app_id)}/portal",
+          body: body
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/resources/subscriptions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  module Resources
+    # Resource for managing endpoint subscriptions via the Management API.
+    #
+    # Subscriptions link event types to endpoints, controlling which
+    # events are delivered to which endpoint.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #   mgmt.subscriptions.list("ws_abc123", "ep_def456")
+    #   mgmt.subscriptions.create("ws_abc123", "ep_def456", event_type_ids: ["evt_ghi789"])
+    class Subscriptions
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List subscriptions for an endpoint.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param endpoint_id [String] the endpoint public ID
+      # @return [Hash] response with "data" key containing an array of subscriptions
+      def list(workspace_id, endpoint_id)
+        data = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(endpoint_id)}/subscriptions"
+        )
+        { "data" => data }
+      end
+
+      # Subscribe an endpoint to one or more event types.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param endpoint_id [String] the endpoint public ID
+      # @param event_type_ids [Array<String>] event type public IDs to subscribe to
+      # @return [Hash] response with "subscribed" count
+      def create(workspace_id, endpoint_id, event_type_ids:)
+        @http.request(
+          method: :post,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(endpoint_id)}/subscriptions",
+          body: { "eventTypeIds" => Array(event_type_ids) }
+        )
+      end
+
+      # Delete a subscription.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param endpoint_id [String] the endpoint public ID
+      # @param event_type_id [String] the event type public ID to unsubscribe
+      # @return [nil]
+      def delete(workspace_id, endpoint_id, event_type_id)
+        @http.request(
+          method: :delete,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(endpoint_id)}/subscriptions/#{e(event_type_id)}"
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/version.rb

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

data/lib/nahook.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "nahook/version"
+require_relative "nahook/errors"
+require_relative "nahook/http_client"
+require_relative "nahook/client"
+require_relative "nahook/management"
+require_relative "nahook/resources/endpoints"
+require_relative "nahook/resources/event_types"
+require_relative "nahook/resources/applications"
+require_relative "nahook/resources/subscriptions"
+require_relative "nahook/resources/portal_sessions"
+require_relative "nahook/resources/environments"
+
+# Official Ruby SDK for the Nahook webhook platform.
+#
+# Nahook provides two main entry points:
+#
+# - {Nahook::Client} for sending webhook payloads (ingestion API)
+# - {Nahook::Management} for managing resources (management API)
+#
+# @example Sending a webhook
+#   client = Nahook::Client.new("nhk_us_your_api_key")
+#   client.send("ep_abc123", payload: { order_id: "12345" })
+#
+# @example Managing endpoints
+#   mgmt = Nahook::Management.new("nhm_your_token")
+#   mgmt.endpoints.list("ws_abc123")
+module Nahook; end