Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Ports between the forms service and its adapters, and the service's own
//! contract. Every method of the service takes the receipt proving the
//! caller's access; the service decides everything beyond it.
use chrono::{DateTime, Utc};
use databases::domain::models::Viewer;
use entity_access::domain::models::{
AccessLevel, EditAccessLevel, EntityAccessReceipt, OwnerAccessLevel, ViewAccessLevel,
};
use macro_user_id::user_id::MacroUserIdStr;
use uuid::Uuid;
use crate::domain::models::{
Audience, DatabaseId, ForbiddenWidget, Form, FormDetail, FormError, FormId, FormLayout,
FormResponse, FormResponseId, FormSectionId, FormTally, FormUpdate, LayoutReplacement,
ListedForm, MyResponse, RecordedResponse, ResponseCounts, ResponseSummary, RowId, StoredForm,
StoredImageFile, Submission, SubmissionOutcome, TableId, UpdateForm,
};
/// Where a new form's responses go, with the access the caller proved.
#[derive(Debug, Clone)]
pub enum CreateSource {
/// A new database for the caller.
NewDatabase {
/// Keep the form, and the database made for it, out of Drive.
is_hidden_in_drive: bool,
/// Make the form anonymous, with no Respondent column.
anonymous: bool,
},
/// An existing table of the database the receipt names. Attaching a
/// form to an existing table takes the database's Owner: the form's
/// editors gain Edit on the database through it, which only the
/// database's owner may hand out.
Table {
/// Owner on the table's database.
receipt: EntityAccessReceipt<OwnerAccessLevel>,
/// The table.
table_id: TableId,
},
}
/// Create a form for a caller.
#[derive(Debug, Clone)]
pub struct CreateFormCommand {
/// Its name.
pub name: String,
/// Where its responses go.
pub source: CreateSource,
}
/// The current time, so closing times and ledger stamps are testable.
pub trait Clock: Send + Sync + 'static {
/// Now.
fn now(&self) -> DateTime<Utc>;
}
/// Which forms a user reaches through grants, as `entity_access` answers
/// it: the boundary of the forms catalog. Public forms the user holds no
/// grant on are not reached this way.
pub trait FormAccessDirectory: Send + Sync + 'static {
/// The error type returned by directory operations.
type Error: std::error::Error + Send + Sync + 'static;
/// Every live form the user holds a grant on, at the highest level.
fn accessible_forms(
&self,
user: &MacroUserIdStr<'_>,
) -> impl Future<Output = Result<Vec<(FormId, AccessLevel)>, Self::Error>> + Send;
}
/// Uploaded files, so a form's branding shows only images their uploader
/// chose.
pub trait FormImageFiles: Send + Sync + 'static {
/// The error type returned by lookups.
type Error: std::error::Error + Send + Sync + 'static;
/// The file, or `None` when there is no such file.
fn image_file(
&self,
file: Uuid,
) -> impl Future<Output = Result<Option<StoredImageFile>, Self::Error>> + Send;
}
/// Liveness: tell the form's open pages it changed, so each re-reads what it
/// shows under its own access. The ping names the form and nothing else.
pub trait FormEventPublisher: Send + Sync + 'static {
/// The error type returned by the publisher.
type Error: std::error::Error + Send + Sync + 'static;
/// Announce that the form's facts, layout or responses changed.
fn form_changed(&self, form: FormId) -> impl Future<Output = Result<(), Self::Error>> + Send;
}
/// Persistence of forms, their layouts and the submission ledger.
pub trait FormsRepo: Send + Sync + 'static {
/// The error type returned by repository operations.
type Error: std::error::Error + Send + Sync + 'static;
/// Store a new form with its layout, returning any table or schema conflict.
/// Grant its owner owner access,
/// all or nothing. `name_follows_database` records, for good, that the
/// form created its own database and goes by that database's name; the
/// stored name is then only what it was called at creation.
fn create_form(
&self,
form: &Form,
layout: &FormLayout,
name_follows_database: bool,
) -> impl Future<Output = Result<super::models::FormCreation, Self::Error>> + Send;
/// Whether a form (including one in trash) already reserves this table.
fn table_has_form(
&self,
table: TableId,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
/// A form, trashed or not, if it exists.
fn form(
&self,
id: FormId,
) -> impl Future<Output = Result<Option<StoredForm>, Self::Error>> + Send;
/// The forms of these ids that are not in the trash; missing ids are
/// left out.
fn forms_by_ids(
&self,
ids: &[FormId],
) -> impl Future<Output = Result<Vec<Form>, Self::Error>> + Send;
/// Those of `ids` that go by their database's name, trashed or not.
fn forms_with_database_names(
&self,
ids: &[FormId],
) -> impl Future<Output = Result<Vec<FormId>, Self::Error>> + Send;
/// The forms over a database that are not in the trash, oldest first.
fn forms_for_database(
&self,
database_id: DatabaseId,
) -> impl Future<Output = Result<Vec<Form>, Self::Error>> + Send;
/// A form's layout: its sections and questions in order.
fn layout(&self, id: FormId) -> impl Future<Output = Result<FormLayout, Self::Error>> + Send;
/// Replace a live form's layout as a whole, stamping `updated_at`, all
/// or nothing. With `required_audience`, the write goes through only if
/// the form has that audience when it commits; concurrent writes of the
/// form's facts and layout serialize, so the check holds. A section or
/// question id another form uses refuses the write.
fn replace_layout(
&self,
id: FormId,
layout: &FormLayout,
updated_at: DateTime<Utc>,
required_audience: Option<Audience>,
) -> impl Future<Output = Result<LayoutReplacement, Self::Error>> + Send;
/// Change a live form's facts as `update` says, stamping `updated_at`;
/// what it leaves out stays. With `forbidden_widget`, the change goes
/// through only if no question of the form asks one of its columns with
/// its widget when it commits; concurrent writes of the form's facts and
/// layout serialize, so the check holds. A change of whether the form is
/// anonymous goes through only while it has no accepted response.
fn update_form(
&self,
id: FormId,
update: &UpdateForm,
updated_at: DateTime<Utc>,
forbidden_widget: Option<ForbiddenWidget>,
) -> impl Future<Output = Result<FormUpdate, Self::Error>> + Send;
/// Rename a live form; `None` when it is gone or trashed.
fn rename_form(
&self,
id: FormId,
name: &str,
updated_at: DateTime<Utc>,
) -> impl Future<Output = Result<Option<Form>, Self::Error>> + Send;
/// Stamp a live form's `updated_at` and nothing else, for a change of
/// the form kept elsewhere (its database's name); `None` when it is
/// gone or trashed.
fn touch_form(
&self,
id: FormId,
updated_at: DateTime<Utc>,
) -> impl Future<Output = Result<Option<Form>, Self::Error>> + Send;
/// Move a form to the trash; `false` when it is gone.
fn trash_form(
&self,
id: FormId,
trashed_at: DateTime<Utc>,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
/// Bring a form back from the trash; `false` when it is gone.
fn restore_form(&self, id: FormId) -> impl Future<Output = Result<bool, Self::Error>> + Send;
/// File a live form in a folder, or at the root when `project_id` is
/// `None`, swapping the grants it inherits from folders to match;
/// `false` when it is trashed or gone.
fn move_form(
&self,
id: FormId,
project_id: Option<&str>,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
/// Remove a form, its layout, ledger and grants.
fn delete_form(&self, id: FormId) -> impl Future<Output = Result<(), Self::Error>> + Send;
/// A signed-in respondent's ledger entry, if any.
fn response_of(
&self,
form: FormId,
respondent: &MacroUserIdStr<'_>,
) -> impl Future<Output = Result<Option<FormResponse>, Self::Error>> + Send;
/// Record that a gate stopped a signed-in respondent: their entry
/// becomes (or stays) a stop at `section`, unless it holds an accepted
/// response, which is kept as it is.
fn record_stop(
&self,
form: FormId,
respondent: &MacroUserIdStr<'_>,
section: FormSectionId,
at: DateTime<Utc>,
) -> impl Future<Output = Result<(), Self::Error>> + Send;
/// Record a response whose row is written: a new entry for an anonymous
/// respondent; for a signed-in one, their entry on the one-per-person
/// key, replacing a stop. When that key already holds an accepted
/// response the entry is left alone and this answers
/// [`RecordedResponse::AlreadySubmitted`].
fn record_submission(
&self,
form: FormId,
respondent: Option<&MacroUserIdStr<'_>>,
row: RowId,
at: DateTime<Utc>,
) -> impl Future<Output = Result<RecordedResponse, Self::Error>> + Send;
/// Record a response to an anonymous form whose row is written, in one
/// transaction: a signed-in voter's receipt, which names no response,
/// and a ledger entry that names nobody, with a random id and stamped
/// `day`. A voter who already holds a receipt answers
/// [`RecordedResponse::AlreadySubmitted`] and nothing is written.
fn record_anonymous_submission(
&self,
form: FormId,
voter: Option<&MacroUserIdStr<'_>>,
row: RowId,
day: DateTime<Utc>,
) -> impl Future<Output = Result<RecordedResponse, Self::Error>> + Send;
/// Whether a signed-in person holds a receipt for responding to an
/// anonymous form.
fn holds_receipt(
&self,
form: FormId,
voter: &MacroUserIdStr<'_>,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
/// Point an entry at a new row, for a response whose row was deleted
/// and written again.
fn repoint_response(
&self,
response: FormResponseId,
row: RowId,
at: DateTime<Utc>,
) -> impl Future<Output = Result<(), Self::Error>> + Send;
/// Stamp an entry whose answers were edited.
fn touch_response(
&self,
response: FormResponseId,
at: DateTime<Utc>,
) -> impl Future<Output = Result<(), Self::Error>> + Send;
/// A form's ledger counts.
fn response_counts(
&self,
form: FormId,
) -> impl Future<Output = Result<ResponseCounts, Self::Error>> + Send;
/// Who submitted each row: the signed-in respondents of accepted
/// responses that still point at a row, in submission order.
fn respondents_by_row(
&self,
form: FormId,
) -> impl Future<Output = Result<Vec<(RowId, MacroUserIdStr<'static>)>, Self::Error>> + Send;
}
/// The forms domain service.
pub trait FormsService: Send + Sync + 'static {
/// Initialize the editor-only Loro surface and publish its latest valid
/// layout. Invalid drafts remain editable and return a publication error.
fn collaborate_form(
&self,
receipt: EntityAccessReceipt<EditAccessLevel>,
) -> impl Future<Output = Result<models_forms::FormCollaboration, FormError>> + Send;
/// Create a form over a new database or an existing table.
fn create_form(
&self,
creator: Viewer,
command: CreateFormCommand,
) -> impl Future<Output = Result<FormDetail, FormError>> + Send;
/// Every live form the viewer holds a grant on, with their level, newest
/// first. Public forms reached only by link are not listed.
fn accessible_forms(
&self,
viewer: Viewer,
) -> impl Future<Output = Result<Vec<ListedForm>, FormError>> + Send;
/// The live forms over the receipt's database.
fn forms_for_database(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> impl Future<Output = Result<Vec<Form>, FormError>> + Send;
/// A form with its layout, each question joined with its column.
fn get_form(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> impl Future<Output = Result<FormDetail, FormError>> + Send;
/// Change a form's facts; who responds, its status, closing time and
/// tallies take its owner.
fn update_form(
&self,
receipt: EntityAccessReceipt<EditAccessLevel>,
update: UpdateForm,
) -> impl Future<Output = Result<Form, FormError>> + Send;
/// Save a whole layout in the shared document. A successful response includes
/// its publication result: a saved draft can need repair or a retry before
/// respondents see it. Refused requests have not changed the draft.
fn put_layout(
&self,
receipt: EntityAccessReceipt<EditAccessLevel>,
layout: FormLayout,
) -> impl Future<Output = Result<models_forms::FormCollaboration, FormError>> + Send;
/// Respond: validate, run the gates, write the row, record the response.
fn submit_response(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
submission: Submission,
) -> impl Future<Output = Result<SubmissionOutcome, FormError>> + Send;
/// The signed-in caller's own response, with the row's current cells.
fn my_response(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> impl Future<Output = Result<MyResponse, FormError>> + Send;
/// Replace the signed-in caller's answers while the form is open.
fn edit_my_response(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
submission: Submission,
) -> impl Future<Output = Result<SubmissionOutcome, FormError>> + Send;
/// Response counts for the form's editors.
fn response_summary(
&self,
receipt: EntityAccessReceipt<EditAccessLevel>,
) -> impl Future<Output = Result<ResponseSummary, FormError>> + Send;
/// Option counts of the form's choice questions: for respondents when
/// the owner shows them, for editors always.
fn tally(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> impl Future<Output = Result<FormTally, FormError>> + Send;
/// Rename a form. A form that created its own database goes by that
/// database's name, so renaming it renames the database; a form over an
/// existing table keeps a name of its own.
fn rename_form(
&self,
receipt: EntityAccessReceipt<EditAccessLevel>,
name: String,
) -> impl Future<Output = Result<Form, FormError>> + Send;
/// Move a form to the trash. Its database stays.
fn trash_form(
&self,
receipt: EntityAccessReceipt<OwnerAccessLevel>,
) -> impl Future<Output = Result<(), FormError>> + Send;
/// Bring a form back from the trash.
fn restore_form(
&self,
receipt: EntityAccessReceipt<OwnerAccessLevel>,
) -> impl Future<Output = Result<(), FormError>> + Send;
/// Remove a form and its ledger for good. Its database and rows stay.
fn delete_form_permanently(
&self,
receipt: EntityAccessReceipt<OwnerAccessLevel>,
) -> impl Future<Output = Result<(), FormError>> + Send;
}