feat: initial spike on referrals service

[travis]

extracted from original implementation in storacha/console#142

This is a very simple REST service built as a Cloudflare worker. I've extracted it from its original implementation because I need to to be a scheduler as well, and that isn't well supported by the next-on-pages deployment style we're using in Next.js.

Users can create "refcodes" by email, look up "refcodes" and "referredby" by email and look up "referrals" by refcode. There is no authorization - this allows the service to work for unauthenticated users, but does mean that anyone can look up refcodes, referrals and referredBy for any email address - we only ever leak lists of refcodes and metadata about them, so I don't think this is too serious a leak, and some level of anonymous interaction is required to meet product requirements, but I do think we should move some of this into an authenticated context (ie, behind UCAN invocations) if we decide to keep scaling this functionality out.

Referral System Database Design

Two tables are used: users and referrals. users is used to store refcodes for users (identified by email address). referrals is used to record the refcode used by a user (identified by email address) during signup. Separate tables are used to avoid mutating rows in the database - a simple, immutable system is generally easier to maintain and reason about and while immutability of database tables isn't a hard requirement, it is a property this design strives to maintain.

Operational Notes

We also introduce a set of scripts prefixed with db:local that make it relatively simple to maintain a local D1 database for development.

TODO

• add GitHub workflow files to push to Cloudflare
• configure production (and staging?) environment(s)
• finish "credits and conversions" cronjob

[alanshaw]

I don't understand the plan for what happens when a user actually logs in and selects a payment plan? Where do they add the refcode? How do we verify the refcode is correct and apply the discount?

I'm concerned that this actually needs to be integrated with w3infra rather than a separate thing...

[alanshaw]

How does this work - is there some external process that's updating it?

[travis]

yep exactly - I have the beginnings of a cronjob in this PR that will go look at Stripe and update these referrals after we've granted the referrer credits.

[travis]

ah right sorry, should have documented this better:

I don't understand the plan for what happens when a user actually logs in and selects a payment plan?

We're using Stripe "Free Trials" (particularly for their handling of local regulatory issues around "free trials") to give people a discount. This means that all we need to do to give them a discount is to show them a different pricing table with free trials enabled

Where do they add the refcode?

It's attached to the referral URL and we grab it from there. I'm also going to add a form on the pricing page that lets them manually enter a code.

How do we verify the refcode is correct and apply the discount?

At the moment we don't verify the refcode is correct, but we can check it and probably should once we add a form on the pricing page. The thing is, if a user wants to generate a refcode they can just go use a fake email address to do that, so checking doesn't really improve our security posture at all, it just makes it a tiny bit harder to get a free trial in this case. From a user experience perspective I think it's weird to just let people type anything into the form on the pricing page, so I will definitely check it there, but I'm not sure it provides much tangible benefit otherwise.

One thing we could do in the short term is make refcode a foreign key in the referrals field to prevent people from creating referrals with invalid refcodes. We already only show the free trial UI to users with an actual "referral" in the DB, so this would just work as expected once we made the DB change (and probably a corresponding API-level change to get the error codes right)

[travis]

I'm going to merge this to get it to staging so we can test the other two pieces of this, but I would like to come back to this review before we ship to prod!