This document is still in flux.

Internal APIs are used by the (web) application. They are used by users (authenticated or not). These are strictly between the NextJS backend and the NodeJS backend. These should not be visible from outside.

Pagination. Use one implementation. Avoid infinite scrolling everywhere.
Sort order:
- default: latest first (descending order)
- param to change
Use user auth status + community settings on the Node backend to determine the response.

Grouping the Internal APIs

There are two major ways to group:

pages (landing, dashboard, register, login, etc) when a "page" is a complete unit that makes sense to read and update at the same time
lists (users, posts) that might be needed on multiple pages, but makes logical sense to single them out

Don't Provide Access To Settings

Don't provide api access to the settings table. Instead use the necessary fields in the appropriate page api (for example theme data or identity data)

Pages and features

auth:
- register
- login
- logout
- password
profile
signing key???
terms
gates???
admin
- identity <-- no direct access to settings!
- theme
- visibility
- about
- gate !!!
- membership-type
- members --> can it redirect to users?
- card --> only in terms of design and settings, not as a list of cards
- badges --> list!
- tiers
- categories
- posts + comments (do we need a separate list for all comments?)
- payments
- donation addresses
- api keys
- onboarding

Lists

users
posts
- comments ???
api keys
communities
leaderboards

Pages

Auth

Register, login, logout, forgot password. Note: the "passwordless" login now called "random-id" across the board

POST /api/internal/v2/auth/register/email
POST /api/internal/v2/auth/register/random-id

POST /api/internal/v2/auth/login/email
POST /api/internal/v2/auth/login/random-id

POST /api/internal/v2/auth/password/forgot
POST /api/internal/v2/auth/password/reset

POST /api/internal/v2/auth/logout

Register With Email

POST /api/internal/v2/auth/register/email

Auth: Public

Request Body:
  - email
  - password
  - name

Register With Random Id

POST /api/internal/v2/auth/register/random-id

Log In With Email

POST /api/internal/v2/auth/login/email

Payload

key description email user's email password user's password

Log In With Random Id

POST /api/internal/v2/auth/login/random-id

key description randomId random id account

Request Password Reset

POST /api/internal/v2/auth/password/forgot

Reset Password

POST /api/internal/v2/auth/password/reset

Log Out

POST /api/internal/v2/logout

Profile

Get and set current user's profile. Only email and name for now.

GET   /api/internal/v2/profile
PATCH /api/internal/v2/profile

Get Active Signing Key

Ignore this for now. Don't implement this in V2 until we need it.

Terms

Terms and conditions should get its own tab + page under "community settings"

I suggest the following structure:

Every time the t&c is updated, save that in a table called "terms_versions". This table will have an auto-increment id.

Once there, we should not allow updating the record. Each change will have a new version with a new version id.

When a user accepts the terms, we record the version_id they accepted. This way we will know which user accepted what version.

The current version is not straightforward:

GET  /api/internal/v2/terms/current
POST /api/internal/v2/terms/accept
GET  /api/internal/v2/terms/status

What happens if the user accepts version 1 of the t&c, then the t&c changes to version 2? What will the "status" return? true or false?

If true, does it mean that the user accepted this version or an older version? If false, did the user accept an older version or no version at all?

TODO we need to record the version of the terms the user accepted.

I suggest the following solution:

GET  /api/internal/v2/terms/current
POST /api/internal/v2/terms/accept

GET  /api/internal/v2/users/{user_id}/last_term_accepted

the "current" api returns the current text and the version number.
"accept" makes the current user accept the version number and records that version in the user's data.
"accept" also makes a log entry ("terms accepted")
The last call queries the users record and returns the last term id that was accepted by the user. This allows us to check if the user has accepted the last terms or we need to prompt them to accept the new terms.
the fact that the user accepted a specific version should be in the logs table.

QUESTION: the current implementation shows x-api-key requried for accepting and getting acceptance status. This seems wrong, since users don't have api keys.

Gates

This needs a major rework.

Remove "Payment Gate" and "kyc gate" from this page. This should only be about the extra fields. The payment gate setting should go under "Tiers".
KYC should get its own page once ready.
Terms and conditions should get its own tab + page under "community settings"
? What is "is-suspended"? The user? If so, then that should be under "users", and should not need a separate api key, just a data field.

Rename the rest to "extra data collection"

Once saved, create a version number for it. Every time it is saved, create a version number, and when a user submits the data, save that version number in the user's records. In this way we will easily know which is the latest version a particular user submitted.

We will use the logs table to record both the gate versions and user completion as well.

GET  /api/internal/v2/gates/status
GET  /api/internal/v2/gates/is-suspended
POST /api/internal/v2/gates/data-collection

If you need a specific call for it, move is-suspended to the users list:

GET /api/internal/v2/users/{user_id}/is-suspended
GET /api/internal/v2/users/{user_id}/gate-completed

is-suspended is a boolean, but I don't understand why it is here.

gate-accepted is either a version id or False (zero is acceptable instead of false)

Community

change readiness to status

GET /api/internal/v2/community/status

Get community readiness states

Get public community settings

These three seem to be redundant to me. They return the same data, but in different formats. I suggest we merge them under settings: From:

GET /api/v1/community/readiness
GET /api/v1/community/settings/public
GET /api/v1/community/settings

merge to:

GET /api/internal/v2/community/settings

Current data structure:

{
  "name": "My Community",
  "slug": "my-community",
  "description": "A digital community",
  "mode": "community",
  "initialized": true,
  "registrationOpen": true,
  "visibility": "PRIVATE",
  "startPage": "ENTRANCE",
  "hasCardDesign": true,
  "hasPublishedLayers": true,
  "isDesignReady": true,
  "memberCount": 42,
  "communityState": "READY_FOR_MEMBERS",
  "heroSubtitle": "Welcome to our community",
  "theme": {
    "primaryColor": "#3B82F6"
  },
  "logoUrl": "https://cdn.example.com/logo.webp",
  "backgroundImageUrl": "https://cdn.example.com/bg.webp",
  "carouselImages": [
    {
      "id": 1,
      "url": "https://cdn.example.com/carousel/hero.webp",
      "order": 0
    }
  ],
  "aboutBody": "## About Us",
  "statsConfig": [
    "string"
  ],
  "gateTermsContent": "By joining you agree to our community guidelines...",
  "gatePaymentEnabled": false,
  "hostName": "community.example.com",
  "donationBtcAddress": "3A8osTtKZ6a5b3NwNtZ8yjQJ3A8osTtKZ6",
  "donationEthAddress": "0x3A8osTtKZ6a5b3NwNtZ8yjQJ3A8osTtKZ6",
  "donationMessage": "Thanks for your support!"
}

I have several questions with the above structure though.

mode: community. What other modes are there?
hasCardDesign, hasPublishedLayers,IsDesignready seems redundant?
communityState should be just state, but what are the other valid states?
theme seems to be weird with that one single color
carouselImages could be just a list of urls? Why do we need id AND order? We can just order them. And the order is the id?
what is statsConfig?
gate* fileds misplaced here?
putting the donation addresses int the settings seem not a good choice. They are only needed in a specific component.
what is gatePaymentEnabled?

The diffirence between the "authenticated" and the "public" version seem random:

the "auth" has "ownerId", while the "public" has "hasCardDesign" (probably one call was updated and the other werent)
gateKycEnabled is in "auth"
hostName only in "public"

Recommendation: drop the "auth" version all together.

If "ownerId" considered sensitive, then make that a different call.

We shouldn't use this call, instead we should break it up to separate calls, as the pages require it, as seen below.

Dashboard

GET /api/internal/v2/settings/dashboard

I think we only need GET.

Identity

GET /api/internal/v2/settings/identity
PUT /api/internal/v2/settings/identity

Name + description

Theme

GET /api/internal/v2/settings/theme
PUT /api/internal/v2/settings/theme

Theme json. I don't thing we need "patch", do we?

Visibility

GET /api/internal/v2/settings/visibility
PUT /api/internal/v2/settings/visibility

I suggest we move "start page" to its own page, because it is not related to visibility at all.

Start Page

GET /api/internal/v2/settings/start-page
PUT /api/internal/v2/settings/start-page

I suggest we move "start page" to its own page, because it is not related to visibility at all.

LIST APIs

logs

The logs table has three fields:

id
log_type (text)
payload (json)
created_at (timestamp)

Log types so far:

terms changed (payload is full t&c+version id)
terms accepted (payload is user_id)
gates changed (payload is full gates json + version id)
gates submitted (payload is user_id)

Davinci Space Feature Proposals