archetypes ⍟ [![NPM version][npm-badge-image]][npm-url]

![Business archetypes logo][business-archetypes-logo-image]

[![License][license-image]][license-url] [![Dependencies' licenses][fossa-badge-image]][fossa-url] [![NSP Status][nsp-badge-image]][nsp-url] [![Synk Vulnerabilities][snyk-vulnerabilities-badge-image]][snyk-vulnerabilities-url]<br> [![StackShare][stack-share-badge-image]][stack-share-url] [![Dependency Status][david-dm-badge-image]][daviddm-url] [![devDependencies Status][david-dm-dev-badge-image]][daviddm-dev-url] <br> [![Build Status][travis-badge-image]][travis-url] [![Coverage percentage][coveralls-badge-image]][coveralls-url] [![Codacy quality][codacy-badge-image]][codacy-url]

![quote][octicon-quote] A business archetype is a primordial thing that occurs consistently and universally in business domains and business software systems.

(Arlow & Neustadt, [Enterprise patterns and MDA: building better software with archetype patterns and UML][mda-book-url], 2006, p. 5)

commonality/archetypes provides universal, rule-based business collaboration APIs for e-commerce and customer relationship management (CRM). commonality/archetypes specifies semantically-rich models of universally recurring business entities, events, and relationships with OpenAPI 2.0.

What are archetypes?

archetypes model how Parties—People and Companies—exchange Products and Services with Payments (normally Money or other Locale-based Currencies like gift-cards). The exchanges are recorded from beginning to end as Orders and managed as Customer Relationships (CRM) between buyers and sellers (with PartyRelationships). When necessary, Rules constrain and determine the types of relationships allowed; how products can be packaged; and whether discounts can be applied.

These business archetypes are expressed as models in open, vendor-neutral OpenAPI/Swagger specifications, which provide:

1. A common vocabulary and operating framework for how Parties—People and Companies—exchange goods and services for Money (with Locale-based Currencies), as well as managing these relationships as Customers (CRM).
2. Executable documentation that articulates these models and how they interact.
3. Open-source tools that automatically generate microservice "stubs" and client SDKs.

Table of contents

<!-- toc -->

• 1. Security
• 2. Installation
  • 2.1. Generating servers and clients
  • 2.2. Editing OpenAPI specs
• 3. Usage: API HTTP responses
  • 3.1. curl
  • 3.2. Swagger-UI
• 4. Party API :package:
  • 4.1. Standards compliance
  • 4.2. Resources
  • 4.3. OpenAPI 2.0 Specs
  • 4.4. API and SDK documentation
  • 4.5. Usage example
• 5. Quantity API :package:
  • 5.1. Standards compliance
  • 5.2. OpenAPI 2.0 Specs
  • 5.3. API and SDK documentation
  • 5.4. Usage example
• 6. Money API :package:
  • 6.1. Standards compliance
  • 6.2. OpenAPI 2.0 Specs
  • 6.3. API documentation
  • 6.4. Usage examples
• 7. PartyRelationship API
  • Roadmap
• 8. Rule API
  • Roadmap
• 9. Customer relationship management (CRM) API
  • Roadmap
• 10. Product API
  • Roadmap
• 11. Inventory API
  • Roadmap
• 12. Order API
  • Roadmap
• 13. Product development and delivery
  • 13.1. Built With
  • 13.2. Prerequisite
  • 13.3. Set up a development environment
  • 13.4. npm-scripts
• 14. DevSecOps
  • 14.1. Builds
  • 14.2. Tests and quality gates
    • 14.2.1. Swagger validation
    • 14.2.2. Linting
    • 14.3.3. Spec (unit test) execution and code coverage
  • 14.3.4. Deploy/Publish
    • 14.3.4.1. Prerequisites
    • 14.3.4.2. Publish on npm
• 15. Style guides
  • 15.1. JavaScript source code
  • 15.2. Color palette
• 16. Semantic version and CHANGELOG
• 17. Contributing to commonality/archetypes
  • 17.1. Contribution workflows summarized
  • 17.2. Contributors
• 18. Licenses

<!-- tocstop -->

1. Security

commonality/archetypes provide model-driven OpenAPI specifications for pervasive business patterns. Some of these models contain sensitive personal or company data that require access control and privacy safeguards.

None of commonality/archetypes' specifications come with OpenAPI securityDefinitions. Before exposing any data, please apply the [principle of least privilege][least-privilege-url] with your own securityDefinitions as appropriate. You must secure how sensitive data are stored and shared.

2. Installation

Open a Terminal and run this command:

npm install --save archetypes

If your team prefers Yarn:

yarn add archetypes

2.1. Generating servers and clients

![quote][octicon-quote] [swagger-api/swagger-codegen][swagger-codegen-url] contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.

Cheng, W., & Tam, T. (2011, August 15). swagger-api/swagger-codegen. Retrieved August 27, 2017, from https://github.com/swagger-api/swagger-codegen

[Swagger Codegen][swagger-codegen-url] will generate servers and clients in many different languages and frameworks.

Follow the [Installation][swagger-codegen-installation-url] and [Getting Starting][swagger-codegen-getting-started-url] instructions to generate and build servers and clients from workstations, CI-services, or Docker containers.

2.2. Editing OpenAPI specs

1. Go to https://editor.swagger.io/.
2. Copy the /archetypes/v1/{archetype}/{archetype}.yaml specification of interest.
3. Paste the *.yaml source into the editor pane.
4. Select "Generate Server" or "Generate Client" and choose an option.
5. If successful, you will prompted to download the ZIPped source code.

3. Usage: API HTTP responses

3.1. curl

The simplest way to test against mock objects at http://api.swindle.net/archetypes/v1/parties with curl in a Terminal.

$ curl \
  -X GET "http://api.swindle.net/archetypes/v1/parties/2e908e75-69a9-47e2-83ae-0c3cc52da84c" \
  -H "accept: application/json"

3.2. Swagger-UI

Go to the api.swindle.net Swagger-UI's "About" section and "Explore" the available Swagger Specs.

The following sections summarize all twelve business archetype patterns as they are released.

4. Party API :package:

![REST API][rest-api-image]

![quote][octicon-quote] The Party archetype represents an identifiable, addressable entity that may have a legal status and that normally has autonomous control over (at least some of) its actions.

Arlow, J., & Neustadt, I. (2006). Party archetype pattern. In [Enterprise patterns and MDA: building better software with archetype patterns and UML][mda-book-url] (p. 122). Boston: Addison-Wesley.

4.1. Standards compliance

| Standard | Contents | | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | OMG Party Management Facility Specification | A standard that supports party management. | | ISO 3166 | Two- and three-letter country codes and country names. | | ISO/IEC 5218:2004 | Codes for the representation of human sexes. | | ITU-T Recommendations | Telecommunication numbering plan. |

4.2. Resources

| Proposal | Contents | | ------------------------------------------- | --------------------------------------------------------------------------------------------------- | | 63 Genders | A proposal for describing Gender as a combination of Physical, Personality and Preferential groups. |

4.3. OpenAPI 2.0 Specs

[![Party's Swagger validity][swagger-validity-party-badge-image]][swagger-validity-party-url] YAML (Content-Type: `applicati