File Coverage

blib/lib/Slovo/Plugin/Prodan.pm

Criterion	Covered	Total	%
statement	80	80	100.0
branch	1	2	50.0
condition	9	18	50.0
subroutine	11	11	100.0
pod	1	1	100.0
total	102	112	91.0

package Slovo::Plugin::Prodan;
use feature ':5.26';
use Mojo::Base 'Mojolicious::Plugin', -signatures;
use Mojo::JSON qw(true false);

our $AUTHORITY = 'cpan:BEROV';
our $VERSION   = '0.05';

has app => sub { Slovo->new }, weak => 1;

sub register ($self, $app, $conf) {
  $self->app($app);

  # Prepend class
  unshift @{$app->renderer->classes}, __PACKAGE__;
  unshift @{$app->static->classes},   __PACKAGE__;
  $app->stylesheets('/css/cart.css');
  $app->javascripts('/js/cart.js');
  $app->config->{consents}{gdpr_url}
    = $conf->{consents}{gdpr_url} || '/ѿносно/условия.bg.html';
  $app->config->{consents}{phone_url} = $conf->{consents}{phone_url} || '[phone]';
  $app->config->{consents}{delivery_prices_url} ||= '/ѿносно/цени-доставка.bg.html';

  # $app->log->debug(join $/, sort keys %INC);
  # $app->debug('Prodan $config', $conf);
  # Set this flag, when we have changes to the tables to be applied.
  $self->_migrate($app, $conf) if $conf->{migrate};

  my $spec = $app->openapi_spec;
  %{$spec->{definitions}} = (%{$spec->{definitions}}, $self->_definitions);
  %{$spec->{paths}}       = (%{$spec->{paths}},       $self->_paths);

  # Add new data_type for celina. Now a corresponding partial template can be
  # used to render the new data_type.
  push @{$spec->{parameters}{data_type}{enum}}, '_consents';
  $app->plugin(OpenAPI => {spec => $spec});

  # $app->debug($spec);
  # Generate helpers for instantiating Slovo::Model classes just like
  # Slovo::PLugin::MojoDBx
  for my $t ('poruchki', 'products') {
    my $T     = Mojo::Util::camelize($t);
    my $class = "Slovo::Model::$T";
    $app->load_class($class);
    $app->helper(
      $t => sub ($c) {
        my $m = $class->new(dbx => $c->dbx, c => $c);
        Scalar::Util::weaken $m->{c};
        return $m;
      });
  }

  # configure deliverers
  $self->_configure_deliverers($conf);
  return $self;
}

sub _paths {
  return (
    '/poruchki' => {
      post => {
        description => 'Create a new order',
        'x-mojo-to' => 'poruchki#store',
        parameters  => [{
            required => true,
            in       => 'body',
            name     => 'Poruchka',
            schema   => {'$ref' => '#/definitions/Poruchka'}
          },
        ],
        responses => {
          201 => {
            description => 'Order created successfully!',
            schema      => {'$ref' => '#/definitions/Poruchka'}

          },
          default => {'$ref' => '#/definitions/ErrorResponse'}}}
    },

    '/poruchka/:deliverer/:deliverer_id' => {
      put => {
        description => 'show an order by given :deliverer and :id with that deliverer. ',
        'x-mojo-to' => 'poruchki#show',
        parameters  => [{
            name        => 'deliverer_id',
            in          => 'path',
            description => 'Id of the order in deliverer\'s system',
            type        => 'integer',
            required    => true,

          },
          {
            name        => 'deliverer',
            in          => 'path',
            description => 'A string which denotes the deliverer. Example: "email". ',
            type        => 'string',
            enum        => [qw(email econt)],
            required    => true,
          },
          {
            name        => 'id',
            in          => 'formData',
            description =>
              '"id" property, found in the order structure. Generated by the Econt delivery confirmation form',
            type     => 'string',
            required => true,

          },
        ],
        responses => {
          200 => {
            description =>
              'Show eventually updated order from :deliverer with :deliverer_id',
            schema => {'$ref' => '#/definitions/Poruchka'}

          },
          default => {'$ref' => '#/definitions/ErrorResponse'}}}
    },
    '/shop' => {
      get => {
        description => 'Provides data for the shop',
        'x-mojo-to' => 'poruchki#shop',
        responses   => {default => {'$ref' => '#/definitions/ErrorResponse'}}}
    },
    '/consents' => {
      get => {
        description => 'Page URL for GDPR concent',
        'x-mojo-to' => 'poruchki#consents',
        responses   => {
          200 => {
            description => 'The URL to the detailed usage conditions, GDPR, cookies.',
            schema      => {'$ref' => '#/definitions/Consents'}
          },
          default => {'$ref' => '#/definitions/ErrorResponse'}}}
    },
  );
}

# Returns description as a perl structure of objects defined for the json API
# to be added to the /definitions of our OpenAPI
sub _definitions {
  return (
    ListOfPoruchki => {
      description => 'An array of Poruchka items.',
      items       => {'$ref' => '#/definitions/Poruchka', type => 'array',}
    },
    Poruchka => {
      properties => {
        deliverer_id => {
          description =>
            'Id of the order as given by Econt, returned with the response to the user-agent(browser)',
          type => 'integer',
        },
        name        => {maxLength => 100, type      => 'string',},
        email       => {maxLength => 100, minLength => 0, type => 'string',},
        phone       => {maxLength => 20,                            type => 'string',},
        deliverer   => {maxLength => 100,                           type => 'string',},
        city_name   => {maxLength => 55,                            type => 'string'},
        address     => {maxLength => 155,                           type => 'string'},
        notes       => {maxLength => 255,                           type => 'string'},
        items       => {'$ref'    => '#/definitions/OrderProducts', type => 'array',},
        way_bill_id => {
          description =>
            'Id at the deliverer site, returned by their system after we created the way-bill at their site.',
          maxLength => 40,
          type      => 'string'
        },
        executed => {
          type        => 'integer',
          minimum     => 0,
          maximum     => 9,
          description => 'Level of execution of the order.0:registered',
        }
      },
    },
    OrderProducts => {
      description => 'An array of OrderProduct items in an order.',
      items       => {
        '$ref' => '#/definitions/OrderProduct',
        type   => 'array',

      }
    },
    OrderProduct => {
      description => 'An item in an order (cart): sku, title, quantity, price',
      properties  => {
        sku      => {maxLength => 40,  type => 'string'},
        title    => {maxLength => 155, type => 'string'},
        quantity => {type      => 'integer'},
        weight   => {type      => 'number'},
        price    => {type      => 'number'},
      }
    },
    Consents => {
      properties => {
        ihost               => {type => 'string'},
        gdpr_url            => {type => 'string'},
        delivery_prices_url => {type => 'string'}
      },
      required => [qw(gdpr_url ihost delivery_prices_url)],
    },
  );
}

# Create tables in the database on the very first run if they do not exist.
sub _migrate ($self, $app, $conf) {
  $app->dbx->migrations->migrate;
  $app->dbx->migrations->name('prodan')
    ->from_data(__PACKAGE__, 'resources/data/prodan_migrations.sql')->migrate();
  return $self;
}

# Deliverers are companies which deliver goods to users of our online shop.
# Such delivereres in Bulgaria are Econt, Speedy, Bulgarian Posts and others.
# Currently we integrate only Econt
my sub DELIVERERS {
  return qw(econt);
}

sub _configure_deliverers ($self, $conf) {
  for my $d (DELIVERERS) {
    my $d_sub = '_configure_' . $d;
    $self->$d_sub($conf);
  }
  return;
}

# The keys in the $conf hash reference are named after the examples given at
# http://delivery.econt.com/services/
sub _configure_econt ($self, $conf) {
  my $eco = $conf->{econt};

  # ID на магазина в "Достави с Еконт"
  $eco->{shop_id} //= 'demo';

  # Код за свързване
  $eco->{private_key} //= 'demo';

  # валута на магазина (валута на наложения платеж)
  $eco->{shop_currency} //= 'BGN';

  # URL визуализиращ форма за доставка
  $eco->{shippment_calc_url} //= 'https://delivery-demo.econt.com/customer_info.php';

  # Ендпойнта на услугата за създаване или редактиране на поръчка
  $eco->{crupdate_order_endpoint}
    //= 'https://delivery-demo.econt.com/services/OrdersService.updateOrder.json';

  # Ендпойнта на услугата за създаване или редактиране на товарителница
  $eco->{create_awb_endpoint}
    //= 'https://delivery-demo.econt.com/services/OrdersService.createAWB.json';

  # $self->app->debug($conf);
  $self->app->config->{shop} = $eco;
  return;
}

1;


=encoding utf8

=head1 NAME

Slovo::Plugin::Prodan - Make and manage sales in your Slovo-based site

=head1 SYNOPSIS

  # In slovo.conf
  load_plugins => [
    #...
    'Themes::Malka',
    {
      Prodan => {
        migrate  => 1,
        consents => {
          gdpr_url    => '/ѿносно/условия.bg.html',
          phone_url           => $ENV{SLOVO_PRODAN_PHONE_URL},
          delivery_prices_url => '/ѿносно/цени-доставки.bg.html',
        },
        econt => {
          shop_id                 => $ENV{SLOVO_PRODAN_SHOP_ID},
          private_key             => $ENV{SLOVO_PRODAN_PRIVATE_KEY},
          shippment_calc_url      => 'https://delivery.econt.com/customer_info.php',
          crupdate_order_endpoint =>
            'https://delivery.econt.com/services/OrdersService.updateOrder.json',
          create_awb_endpoint =>
            'https://delivery.econt.com/services/OrdersService.createAWB.json'
        }}
    },
    #...
  ],

=head1 DESCRIPTION

The word про̀дан (прода̀жба) in Bulgarian means sale. Roots are found in Old
Common Slavic (Old Bulgarian) I<проданьѥ>. Here is an exerpt from Codex
Suprasliensis(331.27) where this word was witnessed: I<сꙑнъ божии. вол҄еѭ
на сьпасьнѫѭ страсть съ вами придетъ. и на B<продании> станетъ.
искѹпѹѭштааго животворьноѭ кръвьѭ. своеѭ миръ.>

L is a L that extends a
Slovo-based site and turns it into an online shop.

=head1 FEATURES

In this edition of L we implement the following features:

=head2 A Shopping cart

A jQuery and localStorage based shopping cart. Two static files contain
the implementation and they can be inflated. The files are
C and C. You should inflate these files into
your public forlder C for the domain on which you
will use it. Even not inflated these will be referred from any page of the
site. The site layout C includes automatically these
two static files if this plugin is loaded.

  # Inflate new static files from Slovo::Plugin::Prodan
  bin/slovo inflate --class Slovo::Plugin::Prodan -p --path domove/xn--b1arjbl.xn--90ae/public

To add a product to your cart and make an order, you need a button, containing
the product data. For example:


        title="книжно издание" data-sku="9786199169001"
        data-title="Житие на света Петка Българска от свети патриарх Евтимий"
        data-weight="0.5" data-price="7.00">
        src="/css/malka/book-open-page-variant-outline.svg">


See "A template..." below.

=head2 Delivery of sold goods

A "Pay on delivery" integration with Bulgarian currier L
Bulgarian)|https://www.econt.com/developers/43-kakvo-e-dostavi-s-ekont.html>.

=head2 Products

Products - a products SQL table to populate your pages with products. You
create a page with several articles (celini) in it. These celini will be the
web-pages for the products. You prepare a YAML file with products. Each product
C property must match exactly the celina C and C on
wich this product will be placed. See C and
C for examples. See L
on how to add and update products.

=head2 Products template for books

A template for displaying products within a C. You can modify this
template as you wish to display other types of products - not just books as it
is now. See C inlined in this file's C<__DATA__>
section. It of course can be inflated using
L. The template produces the HTML from the
products table, including the button mentioned above already.

  # Add the template form Prodan
  bin/slovo inflate --class Slovo::Plugin::Prodan \
    -t --path domove/xn--b1arjbl.xn--90ae/templates/themes/malka


=head2 Consents

A section in the Prodan configuration for different settings - only urls for
now. C<$app-Econfig('consents')> may contain any settings needed for the
client side of the plugin not related dierctly to integration with deliverers
or payment providers.

=head3 GDPR and Cookies consent

A GDPR and cookies consent alert in the footer which upon click leads to the
page (celina) where all conditions on using the site can be described. When the
user clicks on the link to the I page a flag in C is put
so the alert is not shown any more. This flag disappears if the user clears any
site data and the alert will appear again if the user vists the site again.
The Consent celina is created automatically in the localhost domain as an
example. Search for C in the source of this module to see how it
is implemented.

Settings:

    Keys        Default Values
    --------------------------------------------
    gdpr_url    '/ѿносно/условия.bg.html'
    ihost       punycode_decode(ed) current host

=head3 Delivery prices URL

This is just a setting for this plugin - C. Defaults to
'/ѿносно/цени-доставка.bg.html'. This is a place where the prices for delivery
are described. The link is displayed at the bottom of the shopping cart widget.
It is created automatically for localhost as the C

=head3 phone_url

Currently displayed as a link in the _footer_right.html.ep template.


=head2 TODO some day

=over 1

=item Invoices - generate an invoice in PDF via headless LibreOffice instance
on your server.

=item Merchants - a merchants SQL table with Open API to manage and
automatically populate invoices.

=item Other "Pay on Delivery" providers. Feel free to contibute yours.

=item Other types of Payments and/or Online Payment Providers like online POS
Terminals etc.

=back

=head1 METHODS

The usual method is implemented.

=head2 register

Prepends the class to renderer and static classes. Adds some REST API routes,
configures the deliverer.

=head1 EMBEDDED FILES

    @@ css/cart.css
    @@ js/cart.js
    @@ img/arrow-collapse-all.svg
    @@ img/cart-arrow-right.svg
    @@ img/cart.svg
    @@ img/cart-check.svg
    @@ img/cart-off.svg
    @@ img/cart-minus.svg
    @@ img/cart-plus-white.svg
    @@ img/cart-plus.svg
    @@ img/cart-remove.svg
    @@ img/econt.svg
    @@ partials/_footer_right.html.ep
    @@ partials/_consents.html.ep
    @@ partials/_kniga.html.ep
    @@ resources/data/prodan_migrations.sql

=head1 SEE ALSO

L,
L,
L,
L,
L,
L,
L

=head1 AUTHOR

    Красимир Беров
    CPAN ID: BEROV
    berov на cpan точка org
    http://слово.бг

=head1 CONTRIBUTORS

Ordered by time of first commit.

=over

=item * Your Name

=item * Someone Else

=item * Another Contributor

=back

=head1 COPYRIGHT

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

The full text of the license can be found in the
LICENSE file included with this module.

This distribution contains icons from L and
may contain other free software which belongs to their respective authors.

=cut

__DATA__