pobo-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7068813d4efd25d36f69d12e135071e73c78b66203af1b022fc0e8665ab7405
+  data.tar.gz: ffe2ef8bc23b2b34149b559d19f6c15f8c11a7e1d3639fcc732c0ba599109e2c
+SHA512:
+  metadata.gz: 03d8fe0cf48b5c02db8e18d0122bff36ffdcbe99751b68182e5145436d7021490e289859ee535173134143d3f68364e5de3f27500b7294282e4499a7b4820a6f
+  data.tar.gz: aa250e2d7a3e4e995ca342fc63dead8ffdb5eb12b96b8ef6a77b27f502eb86b84c6fe592d83242ea16190218c16848d66da35105ab4216f41a5fba9f0d9a5f51

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pobo
+
+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,345 @@
+# Pobo Ruby SDK
+
+Official Ruby SDK for [Pobo API V2](https://api.pobo.space) - product content management and webhooks.
+
+## Requirements
+
+- Ruby 3.0+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pobo-sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pobo-sdk
+```
+
+## Quick Start
+
+### API Client
+
+```ruby
+require 'pobo'
+
+client = Pobo::Client.new(
+  api_token: 'your-api-token',
+  base_url: 'https://api.pobo.space', # optional
+  timeout: 30 # optional, in seconds
+)
+```
+
+## Import
+
+### Import Order
+
+```
+1. Parameters (no dependencies)
+2. Categories (no dependencies)
+3. Products (depends on categories and parameters)
+4. Blogs (no dependencies)
+```
+
+### Import Parameters
+
+```ruby
+parameters = [
+  Pobo::DTO::Parameter.new(
+    id: 1,
+    name: 'Color',
+    values: [
+      Pobo::DTO::ParameterValue.new(id: 1, value: 'Red'),
+      Pobo::DTO::ParameterValue.new(id: 2, value: 'Blue')
+    ]
+  ),
+  Pobo::DTO::Parameter.new(
+    id: 2,
+    name: 'Size',
+    values: [
+      Pobo::DTO::ParameterValue.new(id: 3, value: 'S'),
+      Pobo::DTO::ParameterValue.new(id: 4, value: 'M')
+    ]
+  )
+]
+
+result = client.import_parameters(parameters)
+puts "Imported: #{result.imported}, Values: #{result.values_imported}"
+```
+
+### Import Categories
+
+```ruby
+categories = [
+  Pobo::DTO::Category.new(
+    id: 'CAT-001',
+    is_visible: true,
+    name: Pobo::DTO::LocalizedString.create('Electronics')
+      .with_translation(Pobo::Language::CS, 'Elektronika')
+      .with_translation(Pobo::Language::SK, 'Elektronika'),
+    url: Pobo::DTO::LocalizedString.create('https://example.com/electronics')
+      .with_translation(Pobo::Language::CS, 'https://example.com/cs/elektronika')
+      .with_translation(Pobo::Language::SK, 'https://example.com/sk/elektronika'),
+    description: Pobo::DTO::LocalizedString.create('<p>All electronics</p>')
+      .with_translation(Pobo::Language::CS, '<p>Veškerá elektronika</p>')
+      .with_translation(Pobo::Language::SK, '<p>Všetka elektronika</p>'),
+    images: ['https://example.com/images/electronics.jpg']
+  )
+]
+
+result = client.import_categories(categories)
+puts "Imported: #{result.imported}, Updated: #{result.updated}"
+```
+
+### Import Products
+
+```ruby
+products = [
+  Pobo::DTO::Product.new(
+    id: 'PROD-001',
+    is_visible: true,
+    name: Pobo::DTO::LocalizedString.create('iPhone 15')
+      .with_translation(Pobo::Language::CS, 'iPhone 15')
+      .with_translation(Pobo::Language::SK, 'iPhone 15'),
+    url: Pobo::DTO::LocalizedString.create('https://example.com/iphone-15')
+      .with_translation(Pobo::Language::CS, 'https://example.com/cs/iphone-15')
+      .with_translation(Pobo::Language::SK, 'https://example.com/sk/iphone-15'),
+    short_description: Pobo::DTO::LocalizedString.create('Latest iPhone model')
+      .with_translation(Pobo::Language::CS, 'Nejnovější model iPhone'),
+    images: ['https://example.com/images/iphone-1.jpg'],
+    categories_ids: ['CAT-001', 'CAT-002'],
+    parameters_ids: [1, 2]
+  )
+]
+
+result = client.import_products(products)
+
+if result.has_errors?
+  result.errors.each do |error|
+    puts "Error: #{error['errors'].join(', ')}"
+  end
+end
+```
+
+### Import Blogs
+
+```ruby
+blogs = [
+  Pobo::DTO::Blog.new(
+    id: 'BLOG-001',
+    is_visible: true,
+    name: Pobo::DTO::LocalizedString.create('New Product Launch')
+      .with_translation(Pobo::Language::CS, 'Uvedení nového produktu')
+      .with_translation(Pobo::Language::SK, 'Uvedenie nového produktu'),
+    url: Pobo::DTO::LocalizedString.create('https://example.com/blog/new-product')
+      .with_translation(Pobo::Language::CS, 'https://example.com/cs/blog/novy-produkt')
+      .with_translation(Pobo::Language::SK, 'https://example.com/sk/blog/novy-produkt'),
+    category: 'news',
+    description: Pobo::DTO::LocalizedString.create('<p>We are excited to announce...</p>')
+      .with_translation(Pobo::Language::CS, '<p>S radostí oznamujeme...</p>'),
+    images: ['https://example.com/images/blog-1.jpg']
+  )
+]
+
+result = client.import_blogs(blogs)
+puts "Imported: #{result.imported}, Updated: #{result.updated}"
+```
+
+## Export
+
+### Export Products
+
+```ruby
+response = client.get_products(page: 1, per_page: 50)
+
+response.data.each do |product|
+  puts "#{product.id}: #{product.name.default}"
+end
+
+puts "Page #{response.current_page} of #{response.total_pages}"
+
+# Iterate through all products (handles pagination automatically)
+client.each_product do |product|
+  puts "#{product.id}: #{product.name.default}"
+end
+
+# Filter by last update time
+since = Time.new(2024, 1, 1)
+response = client.get_products(last_update_from: since)
+
+# Filter only edited products
+response = client.get_products(is_edited: true)
+```
+
+### Export Categories
+
+```ruby
+response = client.get_categories
+
+response.data.each do |category|
+  puts "#{category.id}: #{category.name.default}"
+end
+
+# Iterate through all categories
+client.each_category do |category|
+  process_category(category)
+end
+```
+
+### Export Blogs
+
+```ruby
+response = client.get_blogs
+
+response.data.each do |blog|
+  puts "#{blog.id}: #{blog.name.default}"
+end
+
+# Iterate through all blogs
+client.each_blog do |blog|
+  process_blog(blog)
+end
+```
+
+## Content (HTML/Marketplace)
+
+Products, categories, and blogs include a `content` field with generated HTML content:
+
+```ruby
+client.each_product do |product|
+  next unless product.content
+
+  # Get HTML content for web
+  html_cs = product.content.get_html(Pobo::Language::CS)
+  html_sk = product.content.get_html(Pobo::Language::SK)
+
+  # Get content for marketplace
+  marketplace_cs = product.content.get_marketplace(Pobo::Language::CS)
+
+  # Get default content
+  html_default = product.content.html_default
+  marketplace_default = product.content.marketplace_default
+end
+```
+
+## Webhook Handler
+
+### Basic Usage (Rails)
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def pobo
+    handler = Pobo::WebhookHandler.new(webhook_secret: ENV['POBO_WEBHOOK_SECRET'])
+
+    begin
+      payload = handler.handle_request(request)
+
+      case payload.event
+      when Pobo::WebhookEvent::PRODUCTS_UPDATE
+        SyncProductsJob.perform_later
+      when Pobo::WebhookEvent::CATEGORIES_UPDATE
+        SyncCategoriesJob.perform_later
+      end
+
+      render json: { status: 'ok' }
+    rescue Pobo::WebhookError => e
+      render json: { error: e.message }, status: :unauthorized
+    end
+  end
+end
+```
+
+### Manual Handling
+
+```ruby
+payload = handler.handle(
+  payload: request.raw_post,
+  signature: request.headers['X-Webhook-Signature']
+)
+```
+
+### Webhook Payload
+
+```ruby
+payload.event     # String: "products.update" or "categories.update"
+payload.timestamp # Time
+payload.eshop_id  # Integer
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.import_products(products)
+rescue Pobo::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue Pobo::ApiError => e
+  puts "API error (#{e.http_code}): #{e.message}"
+  puts e.response_body
+end
+```
+
+## Localized Strings
+
+```ruby
+# Create with default value
+name = Pobo::DTO::LocalizedString.create('Default Name')
+
+# Add translations using fluent interface
+name = name
+  .with_translation(Pobo::Language::CS, 'Czech Name')
+  .with_translation(Pobo::Language::SK, 'Slovak Name')
+  .with_translation(Pobo::Language::EN, 'English Name')
+
+# Get values
+name.default                      # => 'Default Name'
+name.get(Pobo::Language::CS)      # => 'Czech Name'
+name.to_hash                      # => { 'default' => '...', 'cs' => '...', ... }
+```
+
+### Supported Languages
+
+| Code      | Language           |
+|-----------|--------------------|
+| `default` | Default (required) |
+| `cs`      | Czech              |
+| `sk`      | Slovak             |
+| `en`      | English            |
+| `de`      | German             |
+| `pl`      | Polish             |
+| `hu`      | Hungarian          |
+
+## API Methods
+
+| Method                                                            | Description                      |
+|-------------------------------------------------------------------|----------------------------------|
+| `import_products(products)`                                       | Bulk import products (max 100)   |
+| `import_categories(categories)`                                   | Bulk import categories (max 100) |
+| `import_parameters(parameters)`                                   | Bulk import parameters (max 100) |
+| `import_blogs(blogs)`                                             | Bulk import blogs (max 100)      |
+| `get_products(page:, per_page:, last_update_from:, is_edited:)`   | Get products page                |
+| `get_categories(page:, per_page:, last_update_from:, is_edited:)` | Get categories page              |
+| `get_blogs(page:, per_page:, last_update_from:, is_edited:)`      | Get blogs page                   |
+| `each_product(last_update_from:, is_edited:)`                     | Iterate all products             |
+| `each_category(last_update_from:, is_edited:)`                    | Iterate all categories           |
+| `each_blog(last_update_from:, is_edited:)`                        | Iterate all blogs                |
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/pobo/client.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Pobo
+  class Client
+    DEFAULT_BASE_URL = "https://api.pobo.space"
+    MAX_BULK_ITEMS = 100
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :api_token, :base_url, :timeout
+
+    def initialize(api_token:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @api_token = api_token
+      @base_url = base_url
+      @timeout = timeout
+    end
+
+    # Import methods
+
+    def import_products(products)
+      validate_bulk_size!(products)
+      payload = products.map { |p| p.respond_to?(:to_hash) ? p.to_hash : p }
+      response = request(:post, "/api/v2/rest/products", payload)
+      DTO::ImportResult.from_hash(response)
+    end
+
+    def import_categories(categories)
+      validate_bulk_size!(categories)
+      payload = categories.map { |c| c.respond_to?(:to_hash) ? c.to_hash : c }
+      response = request(:post, "/api/v2/rest/categories", payload)
+      DTO::ImportResult.from_hash(response)
+    end
+
+    def import_parameters(parameters)
+      validate_bulk_size!(parameters)
+      payload = parameters.map { |p| p.respond_to?(:to_hash) ? p.to_hash : p }
+      response = request(:post, "/api/v2/rest/parameters", payload)
+      DTO::ImportResult.from_hash(response)
+    end
+
+    def import_blogs(blogs)
+      validate_bulk_size!(blogs)
+      payload = blogs.map { |b| b.respond_to?(:to_hash) ? b.to_hash : b }
+      response = request(:post, "/api/v2/rest/blogs", payload)
+      DTO::ImportResult.from_hash(response)
+    end
+
+    # Export methods
+
+    def get_products(page: nil, per_page: nil, last_update_from: nil, is_edited: nil)
+      query = build_query_params(page, per_page, last_update_from, is_edited)
+      response = request(:get, "/api/v2/rest/products#{query}")
+      DTO::PaginatedResponse.from_hash(response, DTO::Product)
+    end
+
+    def get_categories(page: nil, per_page: nil, last_update_from: nil, is_edited: nil)
+      query = build_query_params(page, per_page, last_update_from, is_edited)
+      response = request(:get, "/api/v2/rest/categories#{query}")
+      DTO::PaginatedResponse.from_hash(response, DTO::Category)
+    end
+
+    def get_blogs(page: nil, per_page: nil, last_update_from: nil, is_edited: nil)
+      query = build_query_params(page, per_page, last_update_from, is_edited)
+      response = request(:get, "/api/v2/rest/blogs#{query}")
+      DTO::PaginatedResponse.from_hash(response, DTO::Blog)
+    end
+
+    # Iterator methods
+
+    def each_product(last_update_from: nil, is_edited: nil, &block)
+      return enum_for(:each_product, last_update_from: last_update_from, is_edited: is_edited) unless block_given?
+
+      page = 1
+      loop do
+        response = get_products(page: page, per_page: MAX_BULK_ITEMS, last_update_from: last_update_from, is_edited: is_edited)
+        response.data.each(&block)
+        break unless response.more_pages?
+
+        page += 1
+      end
+    end
+
+    def each_category(last_update_from: nil, is_edited: nil, &block)
+      return enum_for(:each_category, last_update_from: last_update_from, is_edited: is_edited) unless block_given?
+
+      page = 1
+      loop do
+        response = get_categories(page: page, per_page: MAX_BULK_ITEMS, last_update_from: last_update_from, is_edited: is_edited)
+        response.data.each(&block)
+        break unless response.more_pages?
+
+        page += 1
+      end
+    end
+
+    def each_blog(last_update_from: nil, is_edited: nil, &block)
+      return enum_for(:each_blog, last_update_from: last_update_from, is_edited: is_edited) unless block_given?
+
+      page = 1
+      loop do
+        response = get_blogs(page: page, per_page: MAX_BULK_ITEMS, last_update_from: last_update_from, is_edited: is_edited)
+        response.data.each(&block)
+        break unless response.more_pages?
+
+        page += 1
+      end
+    end
+
+    private
+
+    def validate_bulk_size!(items)
+      raise ValidationError.empty_payload if items.empty?
+      raise ValidationError.too_many_items(items.size, MAX_BULK_ITEMS) if items.size > MAX_BULK_ITEMS
+    end
+
+    def build_query_params(page, per_page, last_update_from, is_edited)
+      params = {}
+      params[:page] = page if page
+      params[:per_page] = [per_page, MAX_BULK_ITEMS].min if per_page
+      params[:last_update_time_from] = last_update_from.strftime("%Y-%m-%d %H:%M:%S") if last_update_from
+      params[:is_edited] = is_edited.to_s if is_edited != nil
+
+      return "" if params.empty?
+
+      "?" + URI.encode_www_form(params)
+    end
+
+    def request(method, endpoint, data = nil)
+      response = connection.send(method) do |req|
+        req.url endpoint
+        if data
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(data)
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |f|
+        f.request :url_encoded
+        f.adapter Faraday.default_adapter
+        f.options.timeout = @timeout
+        f.options.open_timeout = 10
+        f.headers["Authorization"] = "Bearer #{@api_token}"
+        f.headers["Accept"] = "application/json"
+      end
+    end
+
+    def handle_response(response)
+      body = response.body.empty? ? {} : JSON.parse(response.body)
+
+      case response.status
+      when 200..299
+        body
+      when 401
+        raise ApiError.unauthorized
+      else
+        raise ApiError.from_response(response.status, body)
+      end
+    rescue JSON::ParserError
+      raise ApiError.new("Invalid JSON response", http_code: response.status, response_body: response.body)
+    end
+  end
+end

data/lib/pobo/dto/blog.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Pobo
+  module DTO
+    class Blog
+      attr_reader :id, :is_visible, :name, :url, :category, :description,
+                  :seo_title, :seo_description, :content, :images, :is_loaded,
+                  :created_at, :updated_at
+
+      def initialize(
+        id:,
+        is_visible:,
+        name:,
+        url:,
+        category: nil,
+        description: nil,
+        seo_title: nil,
+        seo_description: nil,
+        content: nil,
+        images: [],
+        is_loaded: nil,
+        created_at: nil,
+        updated_at: nil
+      )
+        @id = id
+        @is_visible = is_visible
+        @name = name
+        @url = url
+        @category = category
+        @description = description
+        @seo_title = seo_title
+        @seo_description = seo_description
+        @content = content
+        @images = images
+        @is_loaded = is_loaded
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def self.from_hash(hash)
+        new(
+          id: hash["id"] || hash[:id],
+          is_visible: hash["is_visible"] || hash[:is_visible],
+          name: LocalizedString.from_hash(hash["name"] || hash[:name]),
+          url: LocalizedString.from_hash(hash["url"] || hash[:url]),
+          category: hash["category"] || hash[:category],
+          description: LocalizedString.from_hash(hash["description"] || hash[:description]),
+          seo_title: LocalizedString.from_hash(hash["seo_title"] || hash[:seo_title]),
+          seo_description: LocalizedString.from_hash(hash["seo_description"] || hash[:seo_description]),
+          content: Content.from_hash(hash["content"] || hash[:content]),
+          images: hash["images"] || hash[:images] || [],
+          is_loaded: hash["is_loaded"] || hash[:is_loaded],
+          created_at: parse_time(hash["created_at"] || hash[:created_at]),
+          updated_at: parse_time(hash["updated_at"] || hash[:updated_at])
+        )
+      end
+
+      def to_hash
+        data = {
+          "id" => @id,
+          "is_visible" => @is_visible,
+          "name" => @name&.to_hash,
+          "url" => @url&.to_hash
+        }
+
+        data["category"] = @category if @category
+        data["description"] = @description.to_hash if @description
+        data["seo_title"] = @seo_title.to_hash if @seo_title
+        data["seo_description"] = @seo_description.to_hash if @seo_description
+        data["images"] = @images unless @images.empty?
+
+        data
+      end
+
+      alias to_h to_hash
+
+      private
+
+      def self.parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end