zinc-collective / compensated Goto Github PK

Currently, the core compensated library holds a lot of useful code around the fixtures for testing responses from Stripe and Apple Pay. Moving them into a separate library (ideally compensated-spec) will allow any other Compensated gem to use them and share changes upstream. This can be also be used by other projects that want to test how Compensated responds to particular events.

Feature Definition

Feature: Spec Fixtures
  In order to more easily test how payment processor events will impact my system
  As a Client Developer
  I want to be able to apply payment gateway event fixtures in my automated test suite

This Issue May Be Closed When

• There is a compensated-spec module that is packaged as it's own gem.
• One Consuming project uses compensated-spec to test their integration.
• compensated-ruby uses compensated-spec for all its fixtures
  • spec/stripe - #83
  • spec/apple_iap - #84
  • spec/gumroad
• compensated-proxy uses compensated-spec for all its fixtures - #83
• compensated-rails uses compensated-spec for all its fixtures
• We have released the new gem in a release candidate.
• We have updated the CHANGELOG.md to indicate this new feature.
• We have written a guide to testing your Compensated integration using compensated-spec and published it at www.zinc.coop/compensated/testing-your-integration
• We have announced the new library.

Originally posted by @zspencer in https://github.com/zinc-collective/compensated/issues/50#issuecomment-605694538

Issues labeled "enhancement" are the "inner loop" of a double-loop learning system. They exist to take the higher-order design considerations and turn them into changes to the underlying documentation, designs, or code. Issues labeled "request for comment" are for the outer-loop.

This ensures people who want to focus on "what to build" don't have to wade through long conversations to get to the mockups/use cases/acceptance tests; and ensures that people who want the broad, overarching philosophy can have those conversations as well.

1. Someone to document the various labels that have been setup and what that means when contributing.
2. Double bonus, work out a competency level which allows one to practice using the labels, in line with a badgebot
3. For a real DesignNinga, write a compensated bot that affirms the Coop's values of a warm neighbourhood and Code of Conduct.

In Order to Use Compensated in Systems that are not written in Ruby
As a Client Developer
I would like to be able to use Compensated to forward the normalized events.

This Issue May Be Closed When

• There is a compensated-proxy ruby gem that can be installed
• The features/forwarding-proxy.feature file is created and fleshed out with the happy path (but not necessarily wired in)
• The use case described has been tested by a Client Developer or a Maintainer

Scenarios

Scenario: Forwarding proxy forwards all events to Downstream Server
  Given there is a Downstream Listener running
  And I am running `compensated-proxy` with the following command line arguments:
  | argument | value |
  | --forward-to | {{ downstreamListener.compensatedEventHandlerURI }}|
  When each our Source Event Fixtures are delivered to the running compensated proxy
  Then the Downstream Listener receives each of our Standardized Event Fixtures

Context

Because compensated is currently only written in Ruby; and we are getting requests from folks who want to use it in python, node, and other languages we may want to provide a micro-service version of compensated that can listen for events from upstream payment processors; normalize their data; and forward the normalized data down.

Ideally, this would be done by executing a few simple commands; such as gem install compensated-proxy && compensated-proxy --forward-to=https://your-other-app.example.com/compensated_events or a Kubernetes/docker equivalent.

We'll probably want to rely on puma for the ruby webserver side of things; or it may be possible to package it up as a boring rack app. The Traveling Ruby package may give us what we need for packaging the full executable up. Or we can assume they can manage their own ruby and rely on executables in our gemspec.

So, right now the contributing guide doesn’t tell anyone how to actually contribute; it just tells them we own their shit

We probably should rework this to be actually helpful for contributors and include things like:

0. Affirmation that we value non-code contributions (bug reports, documentation fixes, design proposals, etc)
1. Links to the help-wanted and good-first-issue issues
2. A link to Zinc’s “pathway to ownership” document (that is yet to be written)
3. Reframing to a more gentle explanation for why we need to own the code. and laying out commercial collaboration terms

Feature: Cross-Platform Product and Service Pricing
  In order to maximize my income streams by selling products or services across channels
  I want to programmatically manage a plethora of sales channels


  Scenario: Developer Creates Products and Prices in Stripe
  Given Compensated is configured with a clean Stripe account
  And there is a compensated.json with the following data:
  """
  {
    "products": [
      {
        "name": "Robot Delivery",
        "prices": [
          { "nickname": "Small month-to-month", "amount": 10_00, "currency": "usd", "interval": "monthly" },
          { "nickname": "Small full-year", "amount": 100_00, "currency": "usd", "interval": "annual" },
          { "nickname": "Medium month-to-month", "amount": 20_00, "currency": "usd", "interval": "monthly" },
          { "nickname": "Medium full-year", "amount": 200_00, "currency": "usd", "interval": "annual" },
          { "nickname": "Large month-to-month", "amount": 40_00, "currency": "usd", "interval": "monthly" },
          { "nickname": "Large full-year", "amount": 400_00, "currency": "usd", "interval": "annual" }
        ]
      }
    ]
  }
  """
  When I run `compensated apply`
  Then a "Robot Delivery" Product is created in Stripe
  And the "Robot Delivery" Product has a "Small month-to-month" Price of $10 USD billed monthly in Stripe
  And the "Robot Delivery" Product has a "Small full-year" Price of $100 USD billed annually in Stripe
  And the "Robot Delivery" Product has a "Medium month-to-month" Price of $20 USD billed monthly in Stripe
  And the "Robot Delivery" Product has a "Medium full-year" Price of $200 USD billed annually in Stripe
  And the "Robot Delivery" Product has a "Large month-to-month" Price of $40 USD billed monthly in Stripe
  And the "Robot Delivery" Product has a "Large full-year" Price of $400 USD billed annually in Stripe

Dev Notes

• You can see how I have done this in plain Ruby here: zinc-collective/convene#26

A great point @drllau made is that a sandbox environment (and useful instructions for setting up a sandbox for those without access) would be super useful for people as they evaluate how to use the system.

We could maybe rely on the code in examples/compensated-rails-5 for this; but it needs some documentation updates and some UI work.

Part of the goal with Compensated (and @zinc-collective in general) is to demonstrate that we can create socioeconomically restorative organizations through cooperatively owned and operated digital products and services.

To do so, we want to be careful about the usage rights we want to grant people and organizations to "curb" some of the most egregious violations of human rights that are currently encouraged due to insufficient regional and national legislation.

While these restrictions will by definition slow adoption of Compensated; we believe that's a reasonable price to pay in order to stop the cycle of exploitation, surveillance, incarceration, and war being used to enrich the few at the cost of the many.

I'm seeing consensus emerge is that licensing is unlikely to be an effective mechanism to restrict usage rights along ethical grounds; as once a license is granted they are difficult (if not impossible) to revoke. As a result; we may want to investigate requiring licensees to agree to terms of use which revoke their license(s).

I propose we restrict the following usage:

1. Child labor
2. Weapon production and distribution
3. Surveillance capitalism
4. War
5. Incarceration
6. Fossil fuel extraction
7. Creation or distribution of hate speech

Thoughts?

The copyright for Compensated is wholly owned by Zinc Cooperative; a ~6 person worker-cooperative based out of the United States. We have a value that our source code be used first and foremost in a way that does not hurt other people, including extracting disproportionate value from the people who contribute their intellectual property.

This indicates that we want to ensure that substantive contributors have a right to use the project for whatever their own purposes are; so long as they do not violate the ethical terms we would like to set forward.

I've been doing a bit of work with the ethical source working group to figure out the intersection between open source licenses and ethical licenses, but at present, they do not seem "baked" enough to use. Meanwhile, the Prosperity Public License attempts to limit everyone who has not acquired a license (even contributors) to personal use.

I think the "easiest" way to do this would be to be generous in handing out commercial use licenses to the individual contributors who do contribute; while requiring corporations to purchase a license.

An Example:

1. Jan works for Red Hat and submits a patch to improve Compensated 0.X. Thanks, Jan!
2. Zinc issues Jan a permissive license for compensated 0.X
3. Jan makes an app using Compensated that is owned and operated by Jan. This is allowed!
4. Red Hat makes an app using Compensated. Red Hat must purchase a license as they are a distinct legal entity from Jan.
5. Jan decides to incorporate for liability protection reasons. Jan must acquire a license for Compensated for the new legal entity.

In both cases, we will want clear terms-of-use that indicate the limitations of use based upon ethical grounds. A co-conspirator suggested the NPL. I believe we could adopt a dual license strategy with the NPL which allows us to freely grant a license to cooperative organizations and individuals; while the prosperity license or a similar proprietary source-available license is used to grant rights to non-profits, government entities, and corporations.

Does this seem like a reasonable path forward that puts rights in the hands of the people while protecting the cooperative from labor exploitation?

After lots of very informative posts by @drllau; I'm beginning to think that taking the time to understand what we want to allow from a "sublicensing" perspective.

At present, we do not have any language around sub-licensing; beyond allowing anyone to do anything with the code without worrying about them violating our copyright or patent rights. I think (And @drllau / @maximegalon5 correct me if I'm wrong) this means that anyone who buys a license can grant others sub-licenses?

As a result, someone could buy a license, name their project "womp-womp-ensated" and distribute it under a much more permissive license; thus preventing us from making Compensated socioeconomically sustainable.

I believe (and, again, am probably wrong) that the way to resolve this is to adjust the license to explicitly reserve sublicensing rights while making exceptions for particular use cases.

This seems time and attention expensive, and I do not feel qualified to make the decisions about that. @maximegalon5 - Would you be willing to take point on thinking through whether or not this is a risk worth mitigating at this time; determining a reasonable course of action, and facilitating the discussion around it, and then a proposal for how we could move forward?

In order to feel confident when I build on top of Compensated
As a contributor
I would like a spec that defines the data structures that are emitted from Compensated on compensated.zinc.coop

This issue May Be Closed When

1. The spec from docs/README.md is hosted online
2. The compensated landing page at [www.zinc.coop/compensated/] includes a link to the developer documentation

Currently, we support about half of the Apple In App Purchase notification types - https://developer.apple.com/documentation/appstoreservernotifications/notification_type

To start, we will want to add the remaining items to the Compensated::AppleIAP::EventParser::SUPPORTED_TYPES constant; and if we have example payloads add them to spec/apple_iap/fixtures and flesh out the expected data in the apple_iap/event_parser_spec

At present, we have an event parser for Gumroad, Stripe, and Apple; however we don't have a way of knowing which pieces of data they each provide.

Taking the time to audit and document a feature matrix on a per-payment provider basis would help us see where the gaps in implementation are that are worth resolving.

CONTRIBUTING.md is really well written so far, but there are a couple dead links leading to design/README.md and design/ARCHITECTURE.md.

Stripe, by design, has a method for signing and verifying messages sent to its API. This kind of security should be applied to the proxy when receiving messages and (perhaps also sending messages to the forwarded event listener endpoint).

Feature Definition

There are two scenarios in play here, one is for the Operator of the Compensated Proxy, and the other is for a Client Developer.

Here's the one for the Proxy

Scenario:  Proxy Rejects Unsigned Incoming Stripe Webhooks Events
  Given the Compensated Proxy is configured to validate Stripe events
  And the Compensated Proxy is forwarding events to a Downstream Listener
  When the proxy receives an Unsigned Stripe Event shaped like Stripe's payment events
  Then the proxy responds with an Unauthorized status code
  And the proxy does not forward the response to the Downstream Listener

And here's one for the Core library:

Scenario: Event Handler rejects Unsigned Stripe Webhook Events
  Given the Compensated Gem is configured to validate Stripe Events
  When an Unsigned Stripe Event is passed to the Request Handler
  Then the Request Handler raises an UnsignedEventError

We may want to split this into two issues; so that it's easier to close; or we can leave it as one big issue with as many patches as it takes to get this across the finish line.

This Issue May Be Closed When

• The compensated-ruby library can verify incoming Stripe Event's Signature
  • There is a feature test with reasonable scenarios in place
    • The feature file exists
    • The steps are wired in
    • The feature passes in CI
  • And the compensated-ruby/CHANGELOG.md indicates that this feature exists
  • And it has been tested by a maintainer in a production-like capacity
  • And there has been a release of the compensated-ruby library.
• The compensated-proxy application can verify incoming Stripe Event's signature
  • There is a feature test with reasonable scenarios in place
  • And the compensated-proxy/CHANGELOG.md indicates that this feature exists
  • And it has been tested by a maintainer in a production-like capacity
  • And there has been a release of the compensated-proxy application

Ideally, this would include something like the setup-matrix and test-matrix from informed, which ensures that we are running the tests against a wide variety of ruby versions.

I ran some bin executables within this repo and found that, within the bin/setup-matrix script, the ActiveSupport gem requires a higher version of Ruby. Currently, it's listed as 2.4.9. Do you know how to gauge which version of Ruby to bump it up to? Is it by the current stable version as determined by Ruby maintainers or are there other factors at play?

Since it seems like a minor change, I could try to tackle that but wanted to see what the process for the change (if accepted) would be.

In order to begin acquiring contributions to and selling licenses for

Core Goals

• Get a static site hostable on github-pages which describes the core value proposition of the library (Reduce bugs by standardizing application behavior across payment processors)
• Link to the issue tracker for bug reporting
• Include a way for them to begin buying the license (for now, asking them to email [email protected] or an embedded airtable form is probably OK)

Stretch

• Include API docs for the ruby gem from YARD!

Tech Suggestions

• Use the gh-pages library to deploy
• Configure PostCSS with Tailwind or Tachyons for styling

As we worked on fleshing out support for the remaining IAP notification types (#23), we realized that we don't have payloads for most of them. We put in our best guesses, but I wanted to put a ticket in case anyone in the community has access to anonymized versions of the notification payload fixtures marked GUESS so we can make them play nicely.

Now that we've gotten 3~4 implementations within Rails apps; it seems like a reasonable next step will be to create a Rails Engine that encourages a domain model.

Suggested Steps:

• Sprout a compensated-rails gem that is a sibling to compensated-ruby;
• Ensure that compensated-rails test suite gets executed across Ruby versions within CI
• Ensure that the compensated-rails test suite gets executed across Rails versions within CI
• Create a Compensated::Rails::Event resource and supporting migrations
• Create Compensated::Rails::Customer and Compensated::Rails::PaymentProfile resources so that we can associate events with the payments provider and the customer the events relate to.
• Update the compensated-rails-5-example to use the engine

I'm comfortable merging this into 0.X in small steps or one big PR; so long as it's not making significant changes to the compensated-ruby directory.

Apple has deprecated the latest_receipt and receipt_info fields in the server-to-server notifications that we listen to in favor of a unified_receipt field. We will want to update the AppleIap::EventParser to prioritize the unified_receipt and fall-back to the previous fields if it does not exist so that consumers of apple payment events do not have to worry about that change:

Important
The following top-level objects are scheduled for deprecation: latest_receipt, latest_receipt_info, latest_expired_receipt, and latest_expired_receipt_info. Update any existing code to rely on the following objects in unified_receipt instead: latest_receipt and latest_receipt_info.

See: https://developer.apple.com/documentation/appstoreservernotifications/unified_receipt

Note: We don't have any example payloads of a unified_receipt yet, so this may actually be a tough ticket to tackle unless you are using example data from an existing server that is getting unified_receipt payloads; or we can make it up from the spec Apple providers.

At present, people have to either A) read the source or B) read the docs to understand what is available on an event normalized by Compensated. This adds significant cognitive overhead; and reduces adoption.

To mitigate that, we could sprout a Compensated::Event class and ensure that each of our adapters return an instance of it from their #normalize method; while ensuring it can be accessed using the standard event[:foo] syntax that our existing clients use.

This should include YARDoc for the data structures we're exposing on the event, so that tools like Solargraph and ctags can make reasonable suggestions for autocompletion.

This should not include changes to the underlying data structure, for now.

At the moment, we have one commercial user who has a license granted due to existing revenue share agreements with the collective. However, there's another client that is evaluating the use of compensated for their own purposes.

The thoughts in my head are:

1. Is there a a minimum annual cost?
2. What about a percentage of gross revenue?
3. How can we ensure that cost isn't a significant factor in adoption decisions while still making sure it's enough to keep the project sustainable?
4. Do we offer discounts for multi-year licenses?

For reference, some pricing tables for proprietary, privately sourced subscription management platforms:

• MoonClerk: https://www.moonclerk.com/pricing/
• Recurly: https://recurly.com/plans/
• Gumroad: https://gumroad.com/features/pricing