REST API input channel

[tttp]

We are going to provide at least two channels for the supporters (well, the tools used by the NGOs that run the campaigns) to send a message to a politician:

1. REST API: this is assuming there is another tool allowing the supporters to take action that will call this API

2. email: detailled on issue Stalwart WEBHOOK #3

for the API, what schema should we go with?

OpenAPI or GraphQL?

for proca we are using graphql, I don't have a strong preference either way, do you?

mutation:

"email add"

• messageid* any uuid, the provider needs to give a unique id, email is fine for that
• sender name*
• sender email* (where we need to send the reply from the politician)
• subject*
• message*
• timestamp*
• campaign_name (?) to be discussed, if the campaign provider knows it, they can provide it, it will help quite a bit the classification ;) assume empty
  for MVP, no extra options, eg no image, voice...

returns a status OK/try later/error
--> to be fleshed out

Authentication:
token ?

oauth for after MVP

[debiB]

question:
The REST API needs to know which politician the message is for. Is recipient_email (the politician's email) the mandatory field for this?
For the MVP "token" approach, would you like a simple API Key mechanism (e.g., checking an X-API-KEY header against an environment variable or database table)?
Should processMessage simply return a DUPLICATE status, allowing the caller (REST API ) to decide the response (e.g., REST API returns 409 Conflict)?

[debiB]

• Core Logic :

  1. Politician Lookup : Verify the politician exists using recipient_email . Return POLITICIAN_NOT_FOUND if missing.
  2. Duplicate Check : Check external_id via db.checkExternalIdExists . Return DUPLICATE if exists.
  3. Embedding : Generate vector embedding using env.AI (moved from messages.ts ).
  4. Classification : Call db.classifyMessage with the embedding and optional campaign_hint .
  5. Storage : Hash the sender email, calculate duplicate_rank , and insert the record via db.insertMessage .
  6. Return : A standardized result object (status, message_id, campaign info). Step 2: Refactor src/messages.ts
     We will convert the existing REST API endpoint into a thin wrapper around the new processor.

• Schema : Keep the existing Zod schemas ( MessageInputSchema , MessageResponseSchema ) as they define the public API contract.

• Logic :

  • Remove the inline processing logic (embedding, DB calls).
  • Call processMessage(c.env, c.get('db'), validatedBody) .
  • Map Results to HTTP Responses :
    • PROCESSED -> 200 OK (with JSON body)
    • POLITICIAN_NOT_FOUND -> 404 Not Found
    • DUPLICATE -> 409 Conflict
    • ERROR -> 500 Internal Server Error

Step 3: Authentication (MVP)

• If you agree to the API Key approach, we will add a simple middleware or check in src/messages.ts to verify an authorization header before processing.

[tttp]

we need to choose how we handle errors. either as return error or a exceptions.

I prefer to handle "real errors" as exceptions, eg if there is a missing env variable or anything that shouldn't happen, let's throw an error

Return POLITICIAN_NOT_FOUND if missing.

so that should be an error thrown, not a return

Return DUPLICATE if exists.

this one is trickier, it isn't really a "proper" error, returning duplicate rank (0 by default) might be enough, because a duplicate will have the campaign info returned (same as the original message)

the duplicate is mostly a trick to avoid classifying the same thing again and again. in the future, it might be useful to send a different reply message ("hey, we noticed you the first 10 times you wrote, no need to continue" ;)

As for the campaign classification, #5 I think we are missing something, we need two things:

1. finding the campaign
2. finding how much the message is a copy paste of a template vs. something unique

may be return a proximity/uniqueness as well a the campaign?