arctic-vendor 0.2.2 → 0.2.3

data/documentation/lib/multilang.rb

@@ -0,0 +1,16 @@
+module Multilang
+  def block_code(code, full_lang_name)
+    if full_lang_name
+      parts = full_lang_name.split('--')
+      rouge_lang_name = (parts) ? parts[0] : "" # just parts[0] here causes null ref exception when no language specified
+      super(code, rouge_lang_name).sub("highlight #{rouge_lang_name}") do |match|
+        match + " tab-" + full_lang_name
+      end
+    else
+      super(code, full_lang_name)
+    end
+  end
+end
+
+require 'middleman-core/renderers/redcarpet'
+Middleman::Renderers::MiddlemanRedcarpetHTML.send :include, Multilang

data/documentation/lib/nesting_unique_head.rb

@@ -0,0 +1,22 @@
+# Nested unique header generation
+require 'middleman-core/renderers/redcarpet'
+
+class NestingUniqueHeadCounter < Middleman::Renderers::MiddlemanRedcarpetHTML
+  def initialize
+    super
+    @@headers_history = {} if !defined?(@@headers_history)
+  end
+
+  def header(text, header_level)
+    friendly_text = text.parameterize
+    @@headers_history[header_level] = text.parameterize
+
+    if header_level > 1
+      for i in (header_level - 1).downto(1)
+        friendly_text.prepend("#{@@headers_history[i]}-") if @@headers_history.key?(i)
+      end
+    end
+
+    return "<h#{header_level} id='#{friendly_text}'>#{text}</h#{header_level}>"
+  end
+end

data/documentation/lib/toc_data.rb

@@ -0,0 +1,30 @@
+require 'nokogiri'
+
+def toc_data(page_content)
+  html_doc = Nokogiri::HTML::DocumentFragment.parse(page_content)
+
+  # get a flat list of headers
+  headers = []
+  html_doc.css('h1, h2, h3').each do |header|
+    headers.push({
+      id: header.attribute('id').to_s,
+      content: header.children,
+      level: header.name[1].to_i,
+      children: []
+    })
+  end
+
+  [3,2].each do |header_level|
+    header_to_nest = nil
+    headers = headers.reject do |header|
+      if header[:level] == header_level
+        header_to_nest[:children].push header if header_to_nest
+        true
+      else
+        header_to_nest = header if header[:level] < header_level
+        false
+      end
+    end
+  end
+  headers
+end

data/documentation/lib/unique_head.rb

@@ -0,0 +1,24 @@
+# Unique header generation
+require 'middleman-core/renderers/redcarpet'
+require 'digest'
+class UniqueHeadCounter < Middleman::Renderers::MiddlemanRedcarpetHTML
+  def initialize
+    super
+    @head_count = {}
+  end
+  def header(text, header_level)
+    friendly_text = text.gsub(/<[^<]+>/,"").parameterize
+    if friendly_text.strip.length == 0
+      # Looks like parameterize removed the whole thing! It removes many unicode
+      # characters like Chinese and Russian. To get a unique URL, let's just
+      # URI escape the whole header
+      friendly_text = Digest::SHA1.hexdigest(text)[0,10]
+    end
+    @head_count[friendly_text] ||= 0
+    @head_count[friendly_text] += 1
+    if @head_count[friendly_text] > 1
+      friendly_text += "-#{@head_count[friendly_text]}"
+    end
+    return "<h#{header_level} id='#{friendly_text}'>#{text}</h#{header_level}>"
+  end
+end

data/documentation/source/fonts/slate.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" >
+<svg xmlns="http://www.w3.org/2000/svg">
+<metadata>Generated by IcoMoon</metadata>
+<defs>
+<font id="slate" horiz-adv-x="1024">
+<font-face units-per-em="1024" ascent="960" descent="-64" />
+<missing-glyph horiz-adv-x="1024" />
+<glyph unicode="&#x20;" d="" horiz-adv-x="512" />
+<glyph unicode="&#xe600;" d="M438.857 877.714q119.429 0 220.286-58.857t159.714-159.714 58.857-220.286-58.857-220.286-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857zM512 165.143v108.571q0 8-5.143 13.429t-12.571 5.429h-109.714q-7.429 0-13.143-5.714t-5.714-13.143v-108.571q0-7.429 5.714-13.143t13.143-5.714h109.714q7.429 0 12.571 5.429t5.143 13.429zM510.857 361.714l10.286 354.857q0 6.857-5.714 10.286-5.714 4.571-13.714 4.571h-125.714q-8 0-13.714-4.571-5.714-3.429-5.714-10.286l9.714-354.857q0-5.714 5.714-10t13.714-4.286h105.714q8 0 13.429 4.286t6 10z" />
+<glyph unicode="&#xe602;" d="M585.143 164.571v91.429q0 8-5.143 13.143t-13.143 5.143h-54.857v292.571q0 8-5.143 13.143t-13.143 5.143h-182.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h54.857v-182.857h-54.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h256q8 0 13.143 5.143t5.143 13.143zM512 676.571v91.429q0 8-5.143 13.143t-13.143 5.143h-109.714q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h109.714q8 0 13.143 5.143t5.143 13.143zM877.714 438.857q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" />
+<glyph unicode="&#xe606;" d="M733.714 531.428q0 16-10.286 26.286l-52 51.429q-10.857 10.857-25.714 10.857t-25.714-10.857l-233.143-232.571-129.143 129.143q-10.857 10.857-25.714 10.857t-25.714-10.857l-52-51.429q-10.286-10.286-10.286-26.286 0-15.429 10.286-25.714l206.857-206.857q10.857-10.857 25.714-10.857 15.429 0 26.286 10.857l310.286 310.286q10.286 10.286 10.286 25.714zM877.714 438.857q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" />
+<glyph unicode="&#xe607;" d="M658.286 475.428q0 105.714-75.143 180.857t-180.857 75.143-180.857-75.143-75.143-180.857 75.143-180.857 180.857-75.143 180.857 75.143 75.143 180.857zM950.857 0q0-29.714-21.714-51.429t-51.429-21.714q-30.857 0-51.429 21.714l-196 195.429q-102.286-70.857-228-70.857-81.714 0-156.286 31.714t-128.571 85.714-85.714 128.571-31.714 156.286 31.714 156.286 85.714 128.571 128.571 85.714 156.286 31.714 156.286-31.714 128.571-85.714 85.714-128.571 31.714-156.286q0-125.714-70.857-228l196-196q21.143-21.143 21.143-51.429z" horiz-adv-x="951" />
+</font></defs></svg>

data/documentation/source/includes/_errors.md

@@ -0,0 +1,17 @@
+# Errors
+
+> Example error response
+
+```json
+{
+  "error": "Unauthorized",
+  "description": "Invalid or missing Bearer token Authentication header"
+}
+```
+
+The Arctic Core API uses the [HTTP status codes](httpstatuses.com) list. Here is some additional explenations for some of the HTTP status codes.
+
+Error Code | Meaning
+---------- | -------
+401 | Unauthorized -- Your Vendor token is incorrect or missing.
+403 | Forbidden -- Your Vendor token doesn't have the proper permissions for the action.

data/documentation/source/index.html.md

@@ -0,0 +1,150 @@
+---
+title: API Reference
+
+language_tabs: # must be one of https://git.io/vQNgJ
+  - ruby
+
+toc_footers:
+  - <a href='https://arctic-project.dk/vendor/register' target="_blank">Register a Vendor</a>
+  - <a href='https://arctic-project.io' target="_blank">Core API documentation</a>
+  - <a href='https://github.com/YouWeApS/arctic-vendor/issues' target="_blank">Found a bug?</a>
+
+includes:
+  - errors
+
+search: true
+---
+
+# Introduction
+
+The Arctic Vendor project is a wrapper around the [Arcic Core API](https://arctic-project.io).
+
+An Arctic Vendor is an application that connects a marketplace to the Arctic platform.
+
+This project looks to simplify setting up these vendors and thus simplifying the onboarding of new marketplaces for the merchangs on the Arctic platform.
+
+An Arctic Vendor has two aspects to it: Collection and distribution.
+
+**Collecting products** means tranforming (possibly) unstructured product data
+from the marketplace into structured data.
+
+**Distributing products** means sending structured products onto the connected
+marketplace.
+
+# Setup
+
+> To install in your project
+
+```ruby
+gem 'arctic-vendor', '~> 2.2'
+```
+
+First you must [register your Vendor](https://arctic-project.dk/vendor/register)
+with the Core API to obtain a Vendor Token.
+
+In order to connect to the Arctici Core API, you need to have a Vendor Token,
+and you need to store this token in the `ARCTIC_CORE_API_TOKEN` environment
+variable.
+
+If you need to run your application against another environment you can override
+the URL by setting the `ARCTIC_CORE_API_URL` environment variable.
+
+# Object descriptions
+
+### Shop
+
+A single object.
+
+Parameter | Description
+--------- | -----------
+id | Shop ID
+name | Human friendly shop name
+synced_at | [ISO 8601 HTTP date](https://en.wikipedia.org/wiki/ISO_8601)
+auth_config | Sensitive marketplace authentication information
+config | Non-sensitive, general configuration set for the shop
+format_config | JSON formatting instructions
+
+<aside class="notice">
+All <code>*config</code> fields are filled or enhanced by the merchant when
+configuring the Vendor to distribute products through the Vendor's marketplace.
+When registering the vendor with the Core API, JSON schema definitions for these
+fields must be supplied by the Vendor developer.
+</aside>
+
+### Products
+
+An array of product objects.
+
+Parameter | Description
+--------- | -----------
+id | Product ID
+characteristics | Normalized product characteristics
+master | Product is master. Will have a Product ID value if this product is a variant of another.
+state | Last known product state. Can be <code>created</code>, <code>updated</code>, or <code>deleted</code>
+
+### Product characteristics
+
+Name | Description
+---- | -----------
+name | Human readable product name
+description | Human readable description of the product
+color | Color
+size | Size
+ean | EAN number
+price | Price without currency
+currency | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code
+stock | Stock count
+images | Array of image URLs
+
+# Collecting products
+
+> Collect products from the marketplace
+
+```ruby
+Arctic::Vendor.collect_products do |shop|
+  # 1. Connect to the marketplace and retrieve the products for the shop
+
+  # 2. Format each of the products according to the shop's format_config
+end
+```
+
+First, initialize the `Vendor.collect_products` method to receive each of the
+shops that your vendor should process.
+
+Then retrieve the products for that shop, and return them to the block, and the
+Vendor Project will send them to the Core API.
+
+The products you return to the block should be a JSON array of products, each
+formatted according to the `shop`s `format_config` block.
+
+# Distributing products
+
+> Distribute products to the marketplace
+
+```ruby
+Arctic::Vendor.distribute_products(batch_size: 300) do |shop, product_batch|
+  # 1. Connect to the marketplace and publish the products to the shop
+  product_batch.each do |product|
+    # 2. As each of the products are published, update the state
+    product.update_state 'created'
+  end
+end
+```
+
+First, initialize the `Vendor.distribute_products` method to receive each of the
+shops and batches of related products to distribute to the marketplace.
+
+Then connect to the marketplace and distribute the products to the shop.
+
+<aside class="notice">
+<code>Arctic::Vendor.distribute_products</code> returns products in batches of 100 by default.
+</aside>
+
+# Going live
+
+When you have fully developed your Vendor, you will have to go through a
+verification and testing process with the Arctic Team.
+
+Once you pass this verification process your Vendor will be released into
+production and merchants can distribute their products through your Vendor to
+the marketplace.

data/documentation/source/javascripts/all.js

@@ -0,0 +1,2 @@
+//= require ./all_nosearch
+//= require ./app/_search

data/documentation/source/javascripts/all_nosearch.js

@@ -0,0 +1,16 @@
+//= require ./lib/_energize
+//= require ./app/_toc
+//= require ./app/_lang
+
+$(function() {
+  loadToc($('#toc'), '.toc-link', '.toc-list-h2', 10);
+  setupLanguages($('body').data('languages'));
+  $('.content').imagesLoaded( function() {
+    window.recacheHeights();
+    window.refreshToc();
+  });
+});
+
+window.onpopstate = function() {
+  activateLanguage(getLanguageFromQueryString());
+};

data/documentation/source/javascripts/app/_lang.js

@@ -0,0 +1,164 @@
+//= require ../lib/_jquery
+
+/*
+Copyright 2008-2013 Concur Technologies, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+*/
+;(function () {
+  'use strict';
+
+  var languages = [];
+
+  window.setupLanguages = setupLanguages;
+  window.activateLanguage = activateLanguage;
+  window.getLanguageFromQueryString = getLanguageFromQueryString;
+
+  function activateLanguage(language) {
+    if (!language) return;
+    if (language === "") return;
+
+    $(".lang-selector a").removeClass('active');
+    $(".lang-selector a[data-language-name='" + language + "']").addClass('active');
+    for (var i=0; i < languages.length; i++) {
+      $(".highlight.tab-" + languages[i]).hide();
+      $(".lang-specific." + languages[i]).hide();
+    }
+    $(".highlight.tab-" + language).show();
+    $(".lang-specific." + language).show();
+
+    window.recacheHeights();
+
+    // scroll to the new location of the position
+    if ($(window.location.hash).get(0)) {
+      $(window.location.hash).get(0).scrollIntoView(true);
+    }
+  }
+
+  // parseURL and stringifyURL are from https://github.com/sindresorhus/query-string
+  // MIT licensed
+  // https://github.com/sindresorhus/query-string/blob/7bee64c16f2da1a326579e96977b9227bf6da9e6/license
+  function parseURL(str) {
+    if (typeof str !== 'string') {
+      return {};
+    }
+
+    str = str.trim().replace(/^(\?|#|&)/, '');
+
+    if (!str) {
+      return {};
+    }
+
+    return str.split('&').reduce(function (ret, param) {
+      var parts = param.replace(/\+/g, ' ').split('=');
+      var key = parts[0];
+      var val = parts[1];
+
+      key = decodeURIComponent(key);
+      // missing `=` should be `null`:
+      // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters
+      val = val === undefined ? null : decodeURIComponent(val);
+
+      if (!ret.hasOwnProperty(key)) {
+        ret[key] = val;
+      } else if (Array.isArray(ret[key])) {
+        ret[key].push(val);
+      } else {
+        ret[key] = [ret[key], val];
+      }
+
+      return ret;
+    }, {});
+  };
+
+  function stringifyURL(obj) {
+    return obj ? Object.keys(obj).sort().map(function (key) {
+      var val = obj[key];
+
+      if (Array.isArray(val)) {
+        return val.sort().map(function (val2) {
+          return encodeURIComponent(key) + '=' + encodeURIComponent(val2);
+        }).join('&');
+      }
+
+      return encodeURIComponent(key) + '=' + encodeURIComponent(val);
+    }).join('&') : '';
+  };
+
+  // gets the language set in the query string
+  function getLanguageFromQueryString() {
+    if (location.search.length >= 1) {
+      var language = parseURL(location.search).language;
+      if (language) {
+        return language;
+      } else if (jQuery.inArray(location.search.substr(1), languages) != -1) {
+        return location.search.substr(1);
+      }
+    }
+
+    return false;
+  }
+
+  // returns a new query string with the new language in it
+  function generateNewQueryString(language) {
+    var url = parseURL(location.search);
+    if (url.language) {
+      url.language = language;
+      return stringifyURL(url);
+    }
+    return language;
+  }
+
+  // if a button is clicked, add the state to the history
+  function pushURL(language) {
+    if (!history) { return; }
+    var hash = window.location.hash;
+    if (hash) {
+      hash = hash.replace(/^#+/, '');
+    }
+    history.pushState({}, '', '?' + generateNewQueryString(language) + '#' + hash);
+
+    // save language as next default
+    localStorage.setItem("language", language);
+  }
+
+  function setupLanguages(l) {
+    var defaultLanguage = localStorage.getItem("language");
+
+    languages = l;
+
+    var presetLanguage = getLanguageFromQueryString();
+    if (presetLanguage) {
+      // the language is in the URL, so use that language!
+      activateLanguage(presetLanguage);
+
+      localStorage.setItem("language", presetLanguage);
+    } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) {
+      // the language was the last selected one saved in localstorage, so use that language!
+      activateLanguage(defaultLanguage);
+    } else {
+      // no language selected, so use the default
+      activateLanguage(languages[0]);
+    }
+  }
+
+  // if we click on a language tab, activate that language
+  $(function() {
+    $(".lang-selector a").on("click", function() {
+      var language = $(this).data("language-name");
+      pushURL(language);
+      activateLanguage(language);
+      return false;
+    });
+  });
+})();