txt: ## dist_cpan-SACOMO-Magento.md
  # Magento [build status](https://travis-ci.org/scmorrison/perl6-Magento)
  
  Perl 6 Magento 2 API client module.
  
  * [Features](#features)
  * [Getting started](#getting-started)
  * [Module usage](#module-usage)
    * [Response format](#response-format)
    * [Error messages](#error-messages)
    * [Search critera](#search-criteria)
    * [Custom API endpoints](#custom-api-endpoints)
    * [Custom API endpoints](#custom-api-endpoints)
  * [CLI usage](#cli-usage)
  * [Config](#config)
    * [Config variables](#config-variables)
  * [Installation](#installation)
  * [Todo](#todo)
  * [Requirements](#requirements)
  * [Troubleshooting](#troubleshooting)
  * [Authors](#authors)
  * [License](#license)
  * [See also](#see-also)
  
  # Features
  
  * **Magento 2 compatable**: Works with the latest Magento 2 API
  * **Integration token support**: Can utilize Integration tokens for authentication
  * **Admin & Customer token support**: Supports username / password authentication for access token generation
  * **Use Perl 6 hash for search critera**: Write complex search criteria queries as Perl 6 Hash
  
  # Getting started
  
  For long-use Integration Access Token usage use the `6mag init` command:
  
  ```
  6mag init
  
  ```
  
  Enter your Magento installation base URL (e.g. <https://my.magento>), store identifier (e.g. default), and Integration Access Token (generated in Magento > System > Integrations).
  
  By default this will generate the file `~/.6mag/config.yml`:
  
  ```
  ---
  host: "https://my.magento"
  store: default
  access_token: ********************************
  
  ```
  
  # Module Usage
  
  All subroutines are documented in <docs/Subroutines.md>.
  
  Using long-use Integration Access Token from `~/.6mag/config.yml`:
  
  ```
  use Magento::Config;
  use Magento::Customer;
  
  my %config = Magento::Config::from-file;
  
  #GET    /V1/customers/:customerId
  say customers %config, id => 1;
  
  ```
  
  Using pre-generated Access Token without `~/.6mag/config.yml`:
  
  ```
  use Magento::Customer;
  
  my $host   = 'https://my.magento';
  my %config = %{
      host         => $host,
      access_token => '********************************',
      store        => 'default'
  }
  
  #GET    /V1/customers/:customerId
  say customers %config, id => 1;
  
  ```
  
  Using password authentication as Admin:
  
  ```
  use Magento::Auth;
  use Magento::Customer;
  
  my $host   = 'https://my.magento';
  my %config = %{
      host         => $host,
      access_token => request-access-token(username => 'admin', password => '****', :$host),
      store        => 'default'
  }
  
  #GET    /V1/customers/:customerId
  say customers %config, id => 1;
  
  ```
  
  Using password authentication as Customer:
  
  ```
  use Magento::Auth;
  use Magento::Customer;
  
  my $host         = 'https://my.magento';
  my $access_token = 
      request-access-token(
          :$host,
          username  => 'customer@emailaddy.magento',
          password  => '****',
          user_type => 'customer');
  
  my %config = %{:$host, :$access_key, store => 'default'};
  
  #GET    /V1/customers/me
  say customers-me %config;
  
  ```
  
  ### Response format
  
  By default, all responses are returned as `Perl 6` variables. To return the raw `json` or `xml` body add the following to your config Hash:
  
  ```
  my %config = %{
      host         => $host,
      access_token => '********************************',
      store        => 'default',
      format       => 'json',
      # or
      format       => 'xml'
  }
  
  ```
  
  ### Error messages
  
  For a successful request only the relevant data will be returned from the server response. For example, only the `cart_id` value will be returned when a new cart is successfully created on the server.
  
  When an error occurs, the response will return a `Perl 6` Hash with a `message` and `status` pair, like this:
  
  ```
  %{
      message => 'Cannot assign customer to the given cart. Customer already has active cart.',
      status  => 400
  }
  
  ```
  
  ### Search criteria
  
  Use a `Perl 6` Hash to define search criteria:
  
  ```
  use Magento::Config;
  use Magento::Customer;
  
  my %config = Magento::Config::from-file;
  
  my %customer_search_criteria = %{
      searchCriteria => %{
          filterGroups => [
              {
                  filters => [
                      {
                          field => 'email',
                          value => 'customer@myemail.somewhere',
                          condition_type => 'eq'
                      },
                  ]
              },
          ],
          current_page => 1,
          page_size    => 10
      }
  }
  
  # Do a customer search using the search criteria hash
  say customers-search %config, search_criteria => %customer_search_criteria;
  
  ```
  
  #### search-criteria Helper routine
  
  In addition to the `Hash` approach above, you can also use the `search-critera` helper routine from `Magento::Utils`. This creates a search criteria `Hash` using more condensed notation.
  
  Only the initial `Array` is required. The `conditions` named argument is optional.
  
  ```
  use Magento::Utils;
  
  # Single filter
  my %critera = search-critera
      # field   value                      condition_type
      ['email', 'p6magento@fakeemail.com', 'eq'],
      conditions => %{
          current_page => 1,
          page_size    => 10
      }
  
  # Logical AND filter
  my %criteria = search-critera
      [
          ['email', 'p6magento@fakeemail.com', 'eq'],
          ['email', 'p6magento23@fakeemail.com', 'eq'],
      ],
      conditions => %{
          current_page => 1,
          page_size    => 10
      }
  
  # Logical OR
  my %criteria = search-critera
      [
          [
              ['email', 'p6magento@fakeemail.com', 'eq'],
              ['email', 'p6magento23@fakeemail.com', 'eq'],
          ],
          [
              ['email', 'fakeuser1@p6magento.com', 'eq'],
              ['email', 'fakeuser2@p6magehto.com', 'eq'],
          ],
      ],
      conditions => %{
          current_page => 1,
          page_size    => 10
      }
  
  
  ```
  
  ### Custom API endpoints
  
  You can use the `request` subroutine directly to make requests against custom API endpoints:
  
  ```
  use Magento::HTTP;
  use JSON::Fast;
  
  # GET
  Magento::HTTP::request
      method  => 'GET',
      config  => %config,
      uri     => "myCustom/endpoint/123";
  
  # POST/PUT/DELETE
  Magento::HTTP::request
      method  => 'POST', # or PUT / DELETE
      config  => %config,
      uri     => "myCustom/endpoint",
      content => to-json %content-hash;
  
  ```
  
  # CLI Usage
  
  ```
  Usage:
    6mag init         - Generate Integration token based config
    6mag print-config - Print Integration token config
    6mag version      - Print 6mag version and exit
  
  Optional arguments:
    
    --config=         - Specify a custom config file location
                        Default is `~/.6mag/config.yml`
  
    e.g. 6mag --config=path/to/config.yml init 
  
  ```
  
  # Config
  
  Each project has its own `config.yml` which uses the following format:
  
  ```
  ---
  host: "https://my.magento"
  store: default
  access_token: ********************************
  format: json
  version: V1
  
  ```
  
  ### Config variables
  
  Config variables are defined in `config.yml`:
  
  #### Required
  
  * `host`: Magento base URL
  * `access_token`: Magento access token. For long-use configurations, integrations, use an Integration Access Token.
  
  #### Optional
  
  * `format`: By default all results are returned as `Perl 6` variables. You can specify `json` or `xml` with this variable to return the raw response body in either format.
  * `store`: Store identifier, defaults to `default`.
  * `version`: Magento API version, defaults to `V1`.
  
  # Installation
  
  ```
  git clone https://github.com/scmorrison/perl6-Magento.git
  cd perl6-Magento/
  zef install .
  
  ```
  
  Installation issue? See [Troubleshooting](#troubleshooting).
  
  # Todo
  
  * More tests
  * More API endpoints
  
  # Requirements
  
  * [Perl 6](http://perl6.org/)
  
  # Troubleshooting
  
  * **Errors installing from previous version:**
  
    Remove the zef tmp / store perl6-Magento.git directories:
  
    ```
    # Delete these folders from your zef install 
    # directory.
    rm -rf ~/.zef/store/perl6-Magento.git ~/.zef/tmp/perl6-Magento.git 
  
    ```
  
    In some instances it might help to delete your local `~/.perl6/precomp` directory.
  
  # Authors
  
  * [Sam Morrison](@samcns)
  
  # License
  
  This Perl 6 Magento module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. (Note that, unlike the Artistic License 1.0, version 2.0 is GPL compatible by itself, hence there is no benefit to having an Artistic 2.0 / GPL disjunction.) See the file LICENSE for details.
  
  # See also
  
  * [Magento](https://magento.com/)
  