keinaufwand 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e1378e93d8b47d1745d12b04a20b9022cbc097506e02ab0ecfc13f1c5ef6c41
+  data.tar.gz: 55d31421f07efea09ed4ee2f766cb73ae3f37d038a50aec63135de8c705cb8e8
+SHA512:
+  metadata.gz: 459887568f842948dfc5200138393efb8ba9b07aac95eb0b0105f0b2e547c49854686101cde0c30774d960f6e7db6c0ca8f5cd3bb06aa3acdbfaad138ce7e738
+  data.tar.gz: 4da77f43b1d6f10f4837b0a96302f67357121c169639b8b5de1d668de158dc89bd4573b415dc9139cbc3597f2d2b9383de205bb81bfee7c6986d0348cd08f359

data/README.md

@@ -0,0 +1,28 @@
+# keinaufwand
+
+Ruby client for the [Keinaufwand API](https://keinaufwand.com). Includes the API schema and typed nested records.
+
+```ruby
+gem "keinaufwand", "~> 0.1.0"
+```
+
+```ruby
+require "keinaufwand"
+
+client = Keinaufwand::Api::Client.new(
+  access_token: ENV.fetch("KEINAUFWAND_API_KEY"),
+  version: "2026-07-02"
+)
+
+page = client.retrieve_posts(limit: 100)
+while page
+  page.each { |post| puts post.title }
+  page = page.next
+end
+
+post = client.retrieve_post(123)
+```
+
+Requests require an account API key. Collection methods return an enumerable page with pagination metadata; show methods return one record. HTTP failures raise `Keinaufwand::Api::Client::Error`.
+
+For Rails persistence, local media, delta polling, and signed webhooks, install `keinaufwand-sync` as well.

data/lib/keinaufwand/api/client/error.rb

@@ -0,0 +1,24 @@
+module Keinaufwand
+  module Api
+    class Client
+      class Error < StandardError
+        attr_reader :response
+
+        def initialize(response)
+          @response = response
+          return super(response) if response.is_a?(String)
+
+          message = response.body.presence || "#{response.code} #{response.message}"
+
+          begin
+            parsed = JSON.parse(response.body)
+            message = parsed.dig("error", "message") || message
+          rescue JSON::ParserError, TypeError
+          end
+
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/client/list.rb

@@ -0,0 +1,52 @@
+module Keinaufwand
+  module Api
+    class Client
+      class List
+        include Enumerable
+
+        attr_reader :data, :meta
+
+        def initialize(data:, meta:, client:, request_context:)
+          @data = data
+          @meta = meta || {}
+          @client = client
+          @request_context = request_context
+        end
+
+        def each(&block)
+          data.each(&block)
+        end
+
+        def empty?
+          data.empty?
+        end
+
+        def size
+          data.size
+        end
+
+        alias count size
+        alias length size
+
+        def last
+          data.last
+        end
+
+        def [](index)
+          data[index]
+        end
+
+        def next
+          next_page = meta.dig("pagination", "next")
+          return unless next_page
+
+          current_page = @request_context.dig(:params, :page)
+          raise Error, "Infinite pagination loop detected" if current_page == next_page
+
+          params = @request_context[:params].merge(page: next_page)
+          @client.send(:perform_request, @request_context[:verb], @request_context[:path], params, model_name: @request_context[:model_name])
+        end
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/client/record.rb

@@ -0,0 +1,81 @@
+module Keinaufwand
+  module Api
+    class Client
+      class Record
+        attr_reader :raw_attributes, :model_name, :client, :schema, :server_updated_at
+
+        def initialize(attributes:, model_name:, client:, schema:)
+          @raw_attributes = attributes.with_indifferent_access
+          @model_name = model_name
+          @client = client
+          @schema = schema
+          @server_updated_at = parse_time(@raw_attributes[:updated_at])
+        end
+
+        def id
+          raw_attributes[:id]
+        end
+
+        def [](key)
+          raw_attributes[key]
+        end
+
+        def []=(key, value)
+          raw_attributes[key] = value
+        end
+
+        def method_missing(method, *args, &block)
+          method_name = method.to_s
+
+          if raw_attributes.key?(method_name)
+            return read_value(method_name)
+          end
+
+          return nil if args.empty? && !method_name.end_with?("=")
+
+          super
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          raw_attributes.key?(method.to_s) || super
+        end
+
+        private
+
+        def read_value(name)
+          value = raw_attributes[name]
+          type = schema&.dig("attributes", name)
+
+          if client.schema.association?(model_name, name)
+            return build_association(name, value)
+          end
+
+          case type.to_s
+          when "datetime" then parse_time(value) || value
+          when "date" then Date.parse(value.to_s) rescue value
+          when "amount" then value
+          else value
+          end
+        end
+
+        def build_association(name, value)
+          return if value.nil?
+
+          target_model = client.schema.association_class_name(model_name, name)
+
+          if client.schema.association_collection?(model_name, name)
+            Array(value).map { |attributes| client.build_record(target_model, attributes) }
+          else
+            client.build_record(target_model, value)
+          end
+        end
+
+        def parse_time(value)
+          Time.parse(value.to_s) if value.present?
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/client.rb

@@ -0,0 +1,119 @@
+module Keinaufwand
+  module Api
+    class Client
+      attr_reader :access_token, :endpoint, :version, :schema, :host
+
+      def initialize(access_token:, endpoint: "https://api.keinaufwand.com", version: nil, schema: nil, host: nil)
+        @access_token = access_token
+        @endpoint = endpoint.chomp("/")
+        @version = version || Keinaufwand::Api.configuration.version || "2026-07-02"
+        @host = host
+        @schema = schema || load_schema
+        define_methods_from_schema
+      end
+
+      def build_record(model_name, attributes)
+        Record.new(
+          attributes: attributes || {},
+          model_name: model_name,
+          client: self,
+          schema: schema.for(model_name)
+        )
+      end
+
+      private
+
+      def load_schema
+        Schema.load(Keinaufwand::Api.configuration.schema_path(version))
+      end
+
+      def define_methods_from_schema
+        schema.endpoints.each do |resource, endpoints|
+          endpoints.each do |endpoint_config|
+            path = endpoint_config.fetch("path")
+            verb = endpoint_config.fetch("verb")
+            model_name = resource.singularize.classify
+            method_name = method_name_for(endpoint_config.fetch("action"), resource)
+
+            define_singleton_method(method_name) do |*args|
+              params = args.last.is_a?(Hash) ? args.pop : {}
+              dynamic_path = path.dup
+              dynamic_path.scan(/:(\w+)/).flatten.each do |key|
+                value = params.delete(key.to_sym) || params.delete(key) || args.shift
+                raise ArgumentError, "Missing required path parameter: #{key}" if value.nil?
+
+                dynamic_path = dynamic_path.gsub(":#{key}", value.to_s)
+              end
+
+              perform_request(verb, dynamic_path, params, model_name: model_name)
+            end
+          end
+        end
+      end
+
+      def method_name_for(action, resource)
+        prefix = action == "show" ? "retrieve" : action == "index" ? "retrieve" : action
+        noun = action == "index" ? resource.pluralize : resource.singularize
+        "#{prefix}_#{noun}".to_sym
+      end
+
+      def perform_request(verb, path, params = {}, model_name:)
+        payload = perform_json(verb, path, params)
+        data = payload.is_a?(Hash) && payload.key?("data") ? payload["data"] : payload
+
+        records = if data.is_a?(Array)
+          data.map { |attributes| build_record(model_name, attributes) }
+        elsif data.is_a?(Hash)
+          build_record(model_name, data)
+        else
+          data
+        end
+
+        return records unless records.is_a?(Array)
+
+        List.new(
+          data: records,
+          meta: payload["meta"],
+          client: self,
+          request_context: { verb: verb, path: path, params: params, model_name: model_name }
+        )
+      end
+
+      def perform_json(verb, path, params)
+        uri = URI("#{endpoint}#{path}")
+        if verb == "GET" && params.present?
+          uri.query = encode_query(params)
+        end
+
+        request = request_for(verb, uri)
+        request["Authorization"] = "Token #{access_token}"
+        request["Accept"] = "application/json"
+        request["Content-Type"] = "application/json"
+        request["Host"] = host if host
+        request.body = JSON.generate(params) if verb != "GET" && params.present?
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
+        raise Error.new(response) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      end
+
+      def request_for(verb, uri)
+        Net::HTTP.const_get(verb.to_s.capitalize).new(uri)
+      end
+
+      def encode_query(params, prefix = nil)
+        params.flat_map do |key, value|
+          full_key = prefix ? "#{prefix}[#{key}]" : key.to_s
+          if value.is_a?(Hash)
+            encode_query(value, full_key)
+          elsif value.is_a?(Array)
+            value.map { |item| "#{URI.encode_www_form_component(full_key)}[]=#{URI.encode_www_form_component(item.to_s)}" }
+          else
+            "#{URI.encode_www_form_component(full_key)}=#{URI.encode_www_form_component(value.to_s)}"
+          end
+        end.join("&")
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/configuration.rb

@@ -0,0 +1,23 @@
+module Keinaufwand
+  module Api
+    class Configuration
+      attr_accessor :path
+
+      def initialize(path = nil)
+        @path = path
+      end
+
+      def values
+        @values ||= path && File.exist?(path) ? YAML.load_file(path).with_indifferent_access : {}.with_indifferent_access
+      end
+
+      def version
+        values.dig(:api, :version) || values[:version]
+      end
+
+      def schema_path(version = self.version)
+        File.expand_path("../../../schemas/#{version}.json", __dir__)
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/schema.rb

@@ -0,0 +1,55 @@
+module Keinaufwand
+  module Api
+    class Schema
+      attr_reader :version, :config
+
+      def self.load(path)
+        new(YAML.load_file(path))
+      end
+
+      def initialize(config)
+        @config = config.with_indifferent_access
+        @version = @config.fetch(:version)
+      end
+
+      def for(model_name)
+        config.dig(:models, model_name.to_s)
+      end
+
+      def model_names
+        config.fetch(:models).keys
+      end
+
+      def endpoints
+        config[:endpoints] || {}
+      end
+
+      def association?(model_name, attribute)
+        association_type?(attribute_type(model_name, attribute)) || association_metadata(model_name, attribute).present?
+      end
+
+      def association_type?(type)
+        %w[association has_one has_many belongs_to :has_one :has_many :belongs_to].include?(type.to_s)
+      end
+
+      def attribute_type(model_name, attribute)
+        model = self.for(model_name)
+        model&.dig(:attributes, attribute.to_s)
+      end
+
+      def association_metadata(model_name, attribute)
+        model = self.for(model_name)
+        model&.dig(:associations, attribute.to_s) || {}
+      end
+
+      def association_class_name(model_name, attribute)
+        association_metadata(model_name, attribute)[:class_name] || attribute.to_s.singularize.classify
+      end
+
+      def association_collection?(model_name, attribute)
+        type = association_metadata(model_name, attribute)[:type] || attribute_type(model_name, attribute)
+        type.to_s.include?("many")
+      end
+    end
+  end
+end

data/lib/keinaufwand/api/version.rb

@@ -0,0 +1,5 @@
+module Keinaufwand
+  module Api
+    VERSION = "0.1.0"
+  end
+end

data/lib/keinaufwand/api.rb

@@ -0,0 +1,38 @@
+require "active_support"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/blank"
+require "active_support/inflector"
+require "json"
+require "net/http"
+require "pathname"
+require "time"
+require "uri"
+require "yaml"
+
+require_relative "api/version"
+require_relative "api/configuration"
+require_relative "api/schema"
+require_relative "api/client/error"
+require_relative "api/client/list"
+require_relative "api/client/record"
+require_relative "api/client"
+
+module Keinaufwand
+  module Api
+    class << self
+      def configuration
+        @configuration ||= Configuration.new(default_config_path)
+      end
+
+      def configure
+        yield configuration
+      end
+
+      private
+
+      def default_config_path
+        Rails.root.join("config/keinaufwand.yml") if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      end
+    end
+  end
+end

data/lib/keinaufwand.rb

@@ -0,0 +1 @@
+require_relative "keinaufwand/api"

data/schemas/2026-07-02.json

@@ -0,0 +1,400 @@
+{
+  "version": "2026-07-02",
+  "models": {
+    "Address": {
+      "resource_name": "addresses",
+      "attributes": {
+        "id": "integer",
+        "street": "virtual",
+        "zip": "virtual",
+        "city": "virtual",
+        "country_code": "virtual",
+        "lat": "virtual",
+        "lng": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    },
+    "Contact": {
+      "resource_name": "contacts",
+      "attributes": {
+        "id": "integer",
+        "first_name": "virtual",
+        "last_name": "virtual",
+        "email": "virtual",
+        "phone": "virtual",
+        "url": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    },
+    "Event": {
+      "resource_name": "events",
+      "attributes": {
+        "id": "integer",
+        "event_detail_id": "integer",
+        "canceled": "virtual",
+        "title": "virtual",
+        "price_id": "integer",
+        "open_for_enrollment": "virtual",
+        "enrollment_deadline_at": "datetime",
+        "enrollment_form_url": "virtual",
+        "address_id": "integer",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "event_detail": {
+          "type": "belongs_to",
+          "class_name": "EventDetail",
+          "inline": false
+        },
+        "price": {
+          "type": "belongs_to",
+          "class_name": "Price",
+          "inline": true
+        },
+        "address": {
+          "type": "has_one",
+          "class_name": "Address",
+          "inline": true
+        },
+        "event_parts": {
+          "type": "has_many",
+          "class_name": "EventPart",
+          "inline": true
+        }
+      }
+    },
+    "EventDetail": {
+      "resource_name": "event_details",
+      "attributes": {
+        "id": "integer",
+        "title": "virtual",
+        "body": "virtual",
+        "image_url": "virtual",
+        "slug": "virtual",
+        "event_type": "virtual",
+        "product_ids": "integer_array",
+        "position": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "products": {
+          "type": "has_and_belongs_to_many",
+          "class_name": "Product",
+          "inline": false
+        }
+      }
+    },
+    "EventPart": {
+      "resource_name": "event_parts",
+      "attributes": {
+        "id": "integer",
+        "event_id": "integer",
+        "title": "virtual",
+        "starts_at": "datetime",
+        "ends_at": "datetime",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "event": {
+          "type": "belongs_to",
+          "class_name": "Event",
+          "inline": false
+        }
+      }
+    },
+    "Instructor": {
+      "resource_name": "instructors",
+      "attributes": {
+        "id": "integer",
+        "first_name": "virtual",
+        "last_name": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    },
+    "InstructorDetail": {
+      "resource_name": "instructor_details",
+      "attributes": {
+        "id": "integer",
+        "instructor_id": "integer",
+        "default": "virtual",
+        "name": "virtual",
+        "avatar_url": "virtual",
+        "skills": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "instructor": {
+          "type": "belongs_to",
+          "class_name": "Instructor",
+          "inline": true
+        }
+      }
+    },
+    "InstructorGroup": {
+      "resource_name": "instructor_groups",
+      "attributes": {
+        "id": "integer",
+        "name": "virtual",
+        "position": "virtual",
+        "location_id": "integer",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "location": {
+          "type": "belongs_to",
+          "class_name": "Location",
+          "inline": false
+        },
+        "instructor_group_members": {
+          "type": "has_many",
+          "class_name": "InstructorGroupMember",
+          "inline": true
+        }
+      }
+    },
+    "InstructorGroupMember": {
+      "resource_name": "instructor_group_members",
+      "attributes": {
+        "id": "integer",
+        "instructor_group_id": "integer",
+        "instructor_detail_id": "integer",
+        "position": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "instructor_group": {
+          "type": "belongs_to",
+          "class_name": "InstructorGroup",
+          "inline": false
+        },
+        "instructor_detail": {
+          "type": "belongs_to",
+          "class_name": "InstructorDetail",
+          "inline": true
+        }
+      }
+    },
+    "Location": {
+      "resource_name": "locations",
+      "attributes": {
+        "id": "integer",
+        "archived": "virtual",
+        "address_id": "integer",
+        "contact_id": "integer",
+        "connected": "virtual",
+        "page": "has_one",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "address": {
+          "type": "has_one",
+          "class_name": "Address",
+          "inline": true
+        },
+        "contact": {
+          "type": "has_one",
+          "class_name": "Contact",
+          "inline": true
+        }
+      }
+    },
+    "LocationPage": {
+      "resource_name": "location_pages",
+      "attributes": {
+        "id": "integer",
+        "location_id": "integer",
+        "slug": "virtual",
+        "body": "virtual",
+        "image_url": "virtual",
+        "amenities": "virtual",
+        "published": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "location": {
+          "type": "belongs_to",
+          "class_name": "Location",
+          "inline": false
+        }
+      }
+    },
+    "Post": {
+      "resource_name": "posts",
+      "attributes": {
+        "id": "integer",
+        "title": "virtual",
+        "body": "virtual",
+        "slug": "virtual",
+        "published": "virtual",
+        "published_at": "datetime",
+        "image_url": "virtual",
+        "meta": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    },
+    "Price": {
+      "resource_name": "prices",
+      "attributes": {
+        "id": "integer",
+        "amount": "amount",
+        "currency": "virtual",
+        "description": "virtual",
+        "price_type": "virtual",
+        "interval": "virtual",
+        "interval_count": "virtual",
+        "default": "virtual",
+        "trial": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    },
+    "Product": {
+      "resource_name": "products",
+      "attributes": {
+        "id": "integer",
+        "name": "virtual",
+        "description": "virtual",
+        "min_age": "virtual",
+        "max_age": "virtual",
+        "gender": "virtual",
+        "position": "virtual",
+        "archived": "virtual",
+        "connected": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "associations": {
+        "prices": {
+          "type": "has_many",
+          "class_name": "Price",
+          "inline": true
+        }
+      }
+    },
+    "Session": {
+      "resource_name": "sessions",
+      "attributes": {
+        "id": "integer",
+        "location_id": "integer",
+        "product_id": "integer",
+        "type": "virtual",
+        "day_id": "integer",
+        "start_time": "time",
+        "end_time": "time",
+        "start_date": "date",
+        "end_date": "date",
+        "min_age": "virtual",
+        "max_age": "virtual",
+        "grade": "virtual",
+        "program": "virtual",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      }
+    }
+  },
+  "endpoints": {
+    "schema": [
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/schema"
+      }
+    ],
+    "locations": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/locations"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/locations/:id"
+      }
+    ],
+    "products": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/products"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/products/:id"
+      }
+    ],
+    "sessions": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/sessions"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/sessions/:id"
+      }
+    ],
+    "events": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/events"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/events/:id"
+      }
+    ],
+    "event_details": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/event_details"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/event_details/:id"
+      }
+    ],
+    "posts": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/posts"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/posts/:id"
+      }
+    ],
+    "instructor_groups": [
+      {
+        "action": "index",
+        "verb": "GET",
+        "path": "/2026-07-02/instructor_groups"
+      },
+      {
+        "action": "show",
+        "verb": "GET",
+        "path": "/2026-07-02/instructor_groups/:id"
+      }
+    ]
+  }
+}

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: keinaufwand
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Codegestalt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/keinaufwand.rb
+- lib/keinaufwand/api.rb
+- lib/keinaufwand/api/client.rb
+- lib/keinaufwand/api/client/error.rb
+- lib/keinaufwand/api/client/list.rb
+- lib/keinaufwand/api/client/record.rb
+- lib/keinaufwand/api/configuration.rb
+- lib/keinaufwand/api/schema.rb
+- lib/keinaufwand/api/version.rb
+- schemas/2026-07-02.json
+homepage: https://keinaufwand.com
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+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: Schema-aware Keinaufwand API client
+test_files: []