jekyll-baserow-headless-cms 0.1.0

data/docs/templates/github-actions_baserow-sync.yml

@@ -0,0 +1,61 @@
+name: Baserow Sync Workflow
+
+on:
+  workflow_dispatch:
+    inputs:
+      baserow_event:
+        description: 'Type of Baserow event'
+        required: false
+        type: string
+        default: 'webhook'
+      row_id:
+        description: 'Baserow row ID'
+        required: false
+        type: string
+      table_id:
+        description: 'Baserow table ID'
+        required: false
+        type: string
+        default: 'all'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+          BASEROW_TOKEN: ${{ secrets.BASEROW_TOKEN }}
+          BASEROW_SKILLS_TABLE: ${{ secrets.BASEROW_SKILLS_TABLE }}
+          BASEROW_EXPERIENCES_TABLE: ${{ secrets.BASEROW_EXPERIENCES_TABLE }}
+          BASEROW_BLOG_TABLE: ${{ secrets.BASEROW_BLOG_TABLE }}
+          # Add more table secrets as needed
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/lib/jekyll-baserow-headless-cms.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+require_relative 'jekyll_baserow_headless_cms/version'
+require_relative 'jekyll_baserow_headless_cms/baserow_client'
+require_relative 'jekyll_baserow_headless_cms/field_extractors'
+require_relative 'jekyll_baserow_headless_cms/data_organizers'
+require_relative 'jekyll_baserow_headless_cms/generator'
+
+module JekyllBaserowHeadlessCMS
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class APIError < Error; end
+end

data/lib/jekyll_baserow_headless_cms/baserow_client.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module JekyllBaserowHeadlessCMS
+  # Client for interacting with the Baserow REST API
+  class BaserowClient
+    DEFAULT_API_BASE_URL = 'https://api.baserow.io'
+    ROW_PAGE_SIZE = 200
+
+    def initialize(token, base_url: nil)
+      @token = token
+      raise ConfigurationError, 'Baserow token is required' if @token.nil? || @token.empty?
+
+      @base_url = (base_url && !base_url.empty? ? base_url : DEFAULT_API_BASE_URL).chomp('/')
+    end
+
+    # Query a Baserow table and return all rows
+    # @param table_id [String, Integer] The ID of the table to query
+    # @param order_by [String] Optional Baserow order_by expression (e.g. "field_name" or "-field_name")
+    # @param filters [String] Optional Baserow filters expression (raw query string value)
+    # @return [Hash] The API response with results
+    def query_table(table_id, order_by: nil, filters: nil)
+      all_results = []
+      uri = build_rows_uri(table_id, order_by: order_by, filters: filters)
+
+      loop do
+        response = execute_request(uri, build_request(:get, uri))
+        all_results.concat(response['results'])
+
+        break unless response['next']
+
+        uri = URI(response['next'])
+      end
+
+      { 'results' => all_results }
+    end
+
+    # Retrieve a single row
+    # @param table_id [String, Integer] The ID of the table
+    # @param row_id [String, Integer] The ID of the row to retrieve
+    # @return [Hash] The row data
+    def get_row(table_id, row_id)
+      uri = URI("#{@base_url}/api/database/rows/table/#{table_id}/#{row_id}/")
+      uri.query = URI.encode_www_form({ user_field_names: true })
+
+      execute_request(uri, build_request(:get, uri))
+    end
+
+    private
+
+    def build_rows_uri(table_id, order_by:, filters:)
+      uri = URI("#{@base_url}/api/database/rows/table/#{table_id}/")
+      params = { user_field_names: true, size: ROW_PAGE_SIZE }
+      params[:order_by] = order_by if order_by
+      params[:filters] = filters if filters
+      uri.query = URI.encode_www_form(params)
+      uri
+    end
+
+    def build_request(method, uri)
+      request_class = case method
+                      when :get then Net::HTTP::Get
+                      else raise ArgumentError, "Unknown method: #{method}"
+                      end
+
+      request = request_class.new(uri)
+      request['Authorization'] = "Token #{@token}"
+      request['Content-Type'] = 'application/json'
+      request
+    end
+
+    def execute_request(uri, request)
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.request(request)
+      end
+
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPUnauthorized
+        raise APIError, 'Invalid Baserow token (401 Unauthorized)'
+      when Net::HTTPNotFound
+        raise APIError, 'Table or row not found (404 Not Found)'
+      when Net::HTTPTooManyRequests
+        raise APIError, 'Rate limit exceeded (429 Too Many Requests)'
+      else
+        error_message = parse_error_message(response)
+        raise APIError, "Baserow API error: #{response.code} #{error_message}"
+      end
+    end
+
+    def parse_error_message(response)
+      error_json = JSON.parse(response.body)
+      error_json['detail'] || error_json['error'] || response.message
+    rescue JSON::ParserError
+      response.message
+    end
+  end
+end

data/lib/jekyll_baserow_headless_cms/data_organizers.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module JekyllBaserowHeadlessCMS
+  # Module for organizing Baserow data into different structures
+  module DataOrganizers
+    module_function
+
+    # Organize data based on the specified organizer type
+    # @param baserow_data [Hash] Raw data from the Baserow API (rows under 'results')
+    # @param config [Hash] Collection configuration
+    # @return [Hash, Array] Organized data
+    def organize(baserow_data, config)
+      organizer = config['organizer'] || 'simple_list'
+      fields_config = config['fields'] || []
+      sort_by = config['sort_by']
+      sort_order = config['sort_order'] || 'asc'
+
+      case organizer
+      when 'simple_list'
+        organize_simple_list(baserow_data, fields_config, sort_by, sort_order)
+      when 'items_by_category'
+        organize_items_by_category(baserow_data, fields_config)
+      when 'grouped_by'
+        group_field = config['group_by']
+        organize_grouped_by(baserow_data, fields_config, group_field, sort_by, sort_order)
+      when 'nested'
+        parent_field = config['parent_field'] || 'parent_id'
+        organize_nested(baserow_data, fields_config, parent_field, sort_by, sort_order)
+      else
+        organize_simple_list(baserow_data, fields_config, sort_by, sort_order)
+      end
+    end
+
+    # Organize as a simple sorted list
+    # @param baserow_data [Hash] Raw data from the Baserow API
+    # @param fields_config [Array<Hash>] Field configuration
+    # @param sort_by [String] Field to sort by
+    # @param sort_order [String] Sort order ('asc' or 'desc')
+    # @return [Array<Hash>] Sorted list of items
+    def organize_simple_list(baserow_data, fields_config, sort_by, sort_order)
+      items = baserow_data['results'].map do |row|
+        item = FieldExtractors.extract_all(row, fields_config)
+        item['id'] = row['id']
+        item
+      end
+
+      # Filter out items without title
+      items = items.select { |item| item['title'] && !item['title'].to_s.empty? }
+
+      # Sort if sort_by is specified
+      sort_items(items, sort_by, sort_order)
+    end
+
+    # Organize items grouped by category
+    # Useful for skills, products, team members, or any items with category grouping
+    # @param baserow_data [Hash] Raw data from the Baserow API
+    # @param fields_config [Array<Hash>] Field configuration
+    # @return [Hash] Items grouped by category
+    def organize_items_by_category(baserow_data, _fields_config)
+      items_by_category = {}
+
+      baserow_data['results'].each do |row|
+        process_category_row(row, items_by_category)
+      end
+
+      sort_categories_and_items(items_by_category)
+    end
+
+    # Process a single row for category organization
+    def process_category_row(row, items_by_category)
+      name = FieldExtractors.extract(row, 'Name', 'text')
+      return if name.nil? || name.empty?
+
+      category_data = extract_category_data(row)
+      category_name = category_data[:name]
+
+      items_by_category[category_name] ||= build_category_hash(category_data)
+      items_by_category[category_name]['items'] << build_category_item(row, name, category_data)
+    end
+
+    # Extract category-related data from a row (via lookup fields, Baserow's rollup equivalent)
+    def extract_category_data(row)
+      {
+        name: FieldExtractors.extract(row, 'Category', 'lookup') || 'Other',
+        icon: FieldExtractors.extract(row, 'Icon', 'lookup'),
+        color: FieldExtractors.extract(row, 'Color', 'lookup'),
+        order: FieldExtractors.extract(row, 'Category Order', 'lookup')
+      }
+    end
+
+    # Build the category hash structure
+    def build_category_hash(category_data)
+      order = category_data[:order]
+      {
+        'title' => category_data[:name],
+        'category' => category_data[:name],
+        'subcategory' => nil,
+        'icon' => category_data[:icon],
+        'order' => (order.is_a?(Array) ? order.first : order) || 999,
+        'items' => []
+      }
+    end
+
+    # Build an item hash for category organization
+    def build_category_item(row, name, category_data)
+      {
+        'name' => name,
+        'level' => FieldExtractors.extract(row, 'Level', 'number'),
+        'years' => FieldExtractors.extract(row, 'Years', 'number'),
+        'description' => nil,
+        'icon' => nil,
+        'color' => category_data[:color],
+        'featured' => FieldExtractors.extract(row, 'Featured', 'boolean'),
+        'order' => FieldExtractors.extract(row, 'Order', 'number') || 999,
+        'id' => row['id']
+      }
+    end
+
+    # Sort categories and their items
+    def sort_categories_and_items(items_by_category)
+      sorted = items_by_category.sort_by do |_, data|
+        order = data['order']
+        (order.is_a?(Array) ? order.first : order).to_i
+      end.to_h
+
+      sorted.each_value do |data|
+        data['items'].sort_by! { |item| item['order'].to_i }
+      end
+
+      sorted
+    end
+
+    # Organize items grouped by a field
+    # @param baserow_data [Hash] Raw data from the Baserow API
+    # @param fields_config [Array<Hash>] Field configuration
+    # @param group_field [String] Field to group by
+    # @param sort_by [String] Field to sort by within groups
+    # @param sort_order [String] Sort order
+    # @return [Hash] Items grouped by field
+    def organize_grouped_by(baserow_data, fields_config, group_field, sort_by, sort_order)
+      grouped = {}
+
+      baserow_data['results'].each do |row|
+        item = FieldExtractors.extract_all(row, fields_config)
+        item['id'] = row['id']
+
+        next if item['title'].nil? || item['title'].to_s.empty?
+
+        group_key = item[group_field]
+        group_key = group_key.first if group_key.is_a?(Array)
+        group_key ||= 'Other'
+
+        grouped[group_key] ||= []
+        grouped[group_key] << item
+      end
+
+      # Sort within groups
+      grouped.each_value do |items|
+        sort_items(items, sort_by, sort_order)
+      end
+
+      grouped
+    end
+
+    # Organize items in a nested tree structure
+    # @param baserow_data [Hash] Raw data from the Baserow API
+    # @param fields_config [Array<Hash>] Field configuration
+    # @param parent_field [String] Field containing parent reference
+    # @param sort_by [String] Field to sort by
+    # @param sort_order [String] Sort order
+    # @return [Array<Hash>] Nested tree of items
+    def organize_nested(baserow_data, fields_config, parent_field, sort_by, sort_order)
+      items = {}
+      roots = []
+
+      # First pass: extract all items
+      baserow_data['results'].each do |row|
+        item = FieldExtractors.extract_all(row, fields_config)
+        item['id'] = row['id']
+        item['children'] = []
+        items[row['id']] = item
+      end
+
+      # Second pass: build tree structure
+      items.each_value do |item|
+        parent_ids = item[parent_field]
+        parent_id = parent_ids.is_a?(Array) ? parent_ids.first : parent_ids
+
+        if parent_id && items[parent_id]
+          items[parent_id]['children'] << item
+        else
+          roots << item
+        end
+      end
+
+      # Sort at each level
+      sort_nested(roots, sort_by, sort_order)
+
+      roots
+    end
+
+    # Sort items by field
+    # @param items [Array<Hash>] Items to sort
+    # @param sort_by [String] Field to sort by
+    # @param sort_order [String] Sort order ('asc' or 'desc')
+    # @return [Array<Hash>] Sorted items
+    def sort_items(items, sort_by, sort_order)
+      return items unless sort_by && !sort_by.empty?
+
+      items.sort_by! do |item|
+        value = item[sort_by]
+        case value
+        when nil then sort_order == 'desc' ? -Float::INFINITY : Float::INFINITY
+        when Numeric then value
+        when String then value.downcase
+        else value.to_s.downcase
+        end
+      end
+
+      items.reverse! if sort_order == 'desc'
+      items
+    end
+
+    # Recursively sort nested items
+    # @param items [Array<Hash>] Items to sort
+    # @param sort_by [String] Field to sort by
+    # @param sort_order [String] Sort order
+    def sort_nested(items, sort_by, sort_order)
+      sort_items(items, sort_by, sort_order)
+
+      items.each do |item|
+        sort_nested(item['children'], sort_by, sort_order) if item['children']&.any?
+      end
+    end
+
+    # Check if data is present (non-empty)
+    # @param data [Hash, Array] Data to check
+    # @return [Boolean] True if data is present
+    def data_present?(data)
+      return false if data.nil?
+
+      if data.is_a?(Hash)
+        data.size.positive?
+      else
+        data.length.positive?
+      end
+    end
+  end
+end

data/lib/jekyll_baserow_headless_cms/field_extractors.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module JekyllBaserowHeadlessCMS
+  # Module for extracting values from Baserow field types
+  #
+  # Unlike Notion, Baserow returns row data as a flat hash (with
+  # `user_field_names=true`) where each key is already the field's value in
+  # its natural JSON shape. The declared +field_type+ tells us how to
+  # interpret that shape.
+  module FieldExtractors
+    module_function
+
+    # Extract a field value based on its type
+    # @param row [Hash] A row hash from the Baserow API
+    # @param field_name [String] The name of the field
+    # @param field_type [String] The expected type of the field
+    # @return [Object] The extracted value
+    def extract(row, field_name, field_type)
+      return nil unless row.key?(field_name)
+
+      value = row[field_name]
+
+      case field_type
+      when 'text', 'long_text'
+        extract_text(value)
+      when 'number', 'rating', 'count'
+        extract_number(value)
+      when 'boolean'
+        extract_boolean?(value)
+      when 'date', 'created_on', 'last_modified'
+        extract_date(value)
+      when 'single_select'
+        extract_single_select(value)
+      when 'multi_select'
+        extract_multi_select(value)
+      when 'url'
+        extract_url(value)
+      when 'email'
+        extract_email(value)
+      when 'phone_number'
+        extract_phone_number(value)
+      when 'link_row'
+        extract_link_row(value)
+      when 'lookup', 'formula_array'
+        extract_lookup(value)
+      when 'formula'
+        extract_formula(value)
+      when 'file'
+        extract_file(value)
+      end
+    end
+
+    # Extract all fields from a Baserow row based on configuration
+    # @param row [Hash] A row hash from the Baserow API
+    # @param fields_config [Array<Hash>] Configuration for each field
+    # @return [Hash] Extracted fields with normalized keys
+    def extract_all(row, fields_config)
+      item = {}
+
+      fields_config.each do |field_config|
+        field_name = field_config['name']
+        field_type = field_config['type']
+        field_key = field_config['key'] || normalize_key(field_name)
+
+        value = extract(row, field_name, field_type)
+        item[field_key] = value
+      end
+
+      # Use 'title' as the main identifier, fall back to 'name'
+      item['title'] ||= item['name']
+
+      item
+    end
+
+    # Normalize a field name to a valid key
+    # @param name [String] The field name
+    # @return [String] The normalized key
+    def normalize_key(name)
+      name.downcase.gsub(/\s+/, '_')
+    end
+
+    # Text / long text field
+    def extract_text(value)
+      return nil if value.nil? || value == ''
+
+      value.to_s
+    end
+
+    # Number / rating / count field (Baserow may return decimal numbers as strings)
+    def extract_number(value)
+      return nil if value.nil?
+
+      case value
+      when Numeric
+        value
+      when String
+        value.include?('.') ? value.to_f : value.to_i
+      end
+    end
+
+    # Boolean field
+    def extract_boolean?(value)
+      value == true
+    end
+
+    # Date / created on / last modified field (returned as an ISO 8601 string)
+    def extract_date(value)
+      return nil if value.nil? || value == ''
+
+      value.to_s
+    end
+
+    # Single select field: { "id" => 1, "value" => "Backend", "color" => "blue" }
+    def extract_single_select(value)
+      return nil unless value.is_a?(Hash)
+
+      value['value']
+    end
+
+    # Multiple select field: array of { "id" => .., "value" => .., "color" => .. }
+    def extract_multi_select(value)
+      return [] unless value.is_a?(Array)
+
+      value.map { |option| option['value'] }.compact
+    end
+
+    # URL field
+    def extract_url(value)
+      return nil if value.nil? || value == ''
+
+      value.to_s
+    end
+
+    # Email field
+    def extract_email(value)
+      return nil if value.nil? || value == ''
+
+      value.to_s
+    end
+
+    # Phone number field
+    def extract_phone_number(value)
+      return nil if value.nil? || value == ''
+
+      value.to_s
+    end
+
+    # Link to table field: array of { "id" => .., "value" => .. }
+    def extract_link_row(value)
+      return [] unless value.is_a?(Array)
+
+      value.map do |linked_row|
+        { 'id' => linked_row['id'], 'name' => linked_row['value'] }.compact
+      end
+    end
+
+    # Lookup field, or a formula field returning an array: array of { "id" => .., "value" => .. }
+    # Mirrors Notion rollups: returns a single value if only one, otherwise an array
+    def extract_lookup(value)
+      return nil unless value.is_a?(Array)
+
+      values = value.map { |item| item.is_a?(Hash) ? item['value'] : item }.compact
+      return nil if values.empty?
+
+      values.length == 1 ? values.first : values
+    end
+
+    # Formula field returning a scalar value (string, number, boolean or date)
+    def extract_formula(value)
+      value
+    end
+
+    # File field: array of { "url" => .., "name" => .., "mime_type" => .., ... }
+    def extract_file(value)
+      return [] unless value.is_a?(Array)
+
+      value.map do |file|
+        { 'name' => file['name'], 'url' => file['url'], 'type' => file['mime_type'] }.compact
+      end
+    end
+  end
+end