Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

21.6 KB
Raw Blame
import { match, P } from 'ts-pattern';
import { v7 as uuidv7 } from 'uuid';
import type {
  BookingTarget,
  CellValue,
  EntityKind,
  FilterGroup,
  FilterNode,
  FilterTest,
  FormDetail,
  FormLayout,
  FormPublicationProblem,
  ResponseStatus,
  SharePermissionV2,
  SubmissionOutcome,
  UnlockedBooking,
  UpdateForm,
  UpdateSharePermissionRequestV2,
  Widget,
  FormSection as WireFormSection,
} from '../../../generated/storage/types.gen';
import { MacroError, unwrap } from '../../utils';
import type { MacroClient } from '../../utils/client';
import type { DatabaseColumn } from '../databases/column';
import { Database } from '../databases/database';
import { DatabaseRow } from '../databases/row';
import { DatabaseTable } from '../databases/table';
import { MacroEntity } from '../entity';
import { User } from '../users/user';
import { FormOption, FormQuestion } from './question';
import { FormResponse } from './response';
import { FormSection } from './section';

/** An entity handle used in a reference answer or rule. */
export interface FormEntityHandle {
  /** The entity's identifier. */
  readonly id: string;
}

/** A typed reference read from a form answer, without fetching the referenced entity. */
export class FormReference implements FormEntityHandle {
  private constructor(
    /** The referenced entity's kind. */
    readonly entityType: EntityKind,
    /** The referenced entity's identifier. */
    readonly id: string,
  ) {}

  /** Construct a reference when its kind and identifier are known. */
  static byId(entityType: EntityKind, id: string): FormReference {
    return new FormReference(entityType, id);
  }
}

/** An answer value; references use handles, and scalar values keep their cell representation. */
export type FormAnswerValue =
  | Exclude<CellValue, { type: 'rows' | 'options' | 'entities' }>
  | { type: 'rows'; value: DatabaseRow[] }
  | { type: 'options'; value: FormOption[] }
  | {
      type: 'entities';
      value: { entityType: EntityKind; entity: FormEntityHandle }[];
    };

/** One question and its answer. */
export type FormAnswer = { question: FormQuestion; value: FormAnswerValue };

/** A form rule, with option and entity references represented by handles. */
export type FormRuleTest =
  | Exclude<FilterTest, { kind: 'options' | 'entities' }>
  | {
      kind: 'options';
      operator: Extract<FilterTest, { kind: 'options' }>['operator'];
      options: FormOption[];
    }
  | {
      kind: 'entities';
      operator: Extract<FilterTest, { kind: 'entities' }>['operator'];
      entities: FormEntityHandle[];
    };

/** Conditions over columns asked in earlier sections. */
export type FormRules = {
  conjunction: FilterGroup['conjunction'];
  conditions: (
    | { kind: 'condition'; column: DatabaseColumn; test: FormRuleTest }
    | ({ kind: 'group' } & FormRules)
  )[];
};

/** A question placement in a layout replacement. Omit question to mint a new stable question. */
export type FormQuestionPlacement = {
  question?: FormQuestion;
  column: DatabaseColumn;
  helpText?: string;
  required?: boolean;
  widget?: Widget;
};

/** A section in a layout replacement. Omit section to mint a new stable section. */
export type FormSectionPlacement = {
  section?: FormSection;
  title: string;
  description?: string;
} & (
  | { kind: 'questions'; questions: FormQuestionPlacement[] }
  | { kind: 'gate'; rules: FormRules; message: string }
  | { kind: 'booking'; target: BookingTarget }
);

/** A saved layout and any reason it is not yet visible to respondents. */
export type FormLayoutResult = {
  form: Form;
  publicationError?: FormPublicationProblem;
};

/** The public Macro booking destination selected by a form editor. */
export type FormBookingTarget = BookingTarget;

/** A booking step released after the form accepts the caller's answers. */
export type FormBookingStep = Omit<UnlockedBooking, 'section'> & {
  section: FormSection;
};

/** The result of submitting or editing a response. A stopped submission has no row. */
export type FormSubmissionOutcome =
  | {
      outcome: 'submitted';
      response: FormResponse;
      row: DatabaseRow;
      booking?: FormBookingStep;
    }
  | { outcome: 'stopped'; section: FormSection; message: string };

/**
 * The caller's receipt and current answers, read without access to other
 * responses. On an anonymous form the caller only learns that they
 * responded: nothing links them to their response.
 */
export type MyFormResponse = SavedFormResponse | { kind: 'anonymous' };

/** The caller's saved response to a form that isn't anonymous. */
export type SavedFormResponse = {
  kind: 'saved';
  booking?: FormBookingStep;
  response: FormResponse;
  status: ResponseStatus;
  stoppedAtSection?: FormSection;
  row?: DatabaseRow;
  submittedAt: string;
  updatedAt: string;
  answers: FormAnswer[];
};

/** Counts from the response ledger and its linked table. */
export type FormResponseSummary = {
  submitted: number;
  stopped: number;
  stoppedBySection: { section: FormSection; count: number }[];
  rows: number;
};

/** A question's public tally. Options with no votes are retained. */
export type FormQuestionTally = {
  question: FormQuestion;
  responses: number;
  buckets: {
    value:
      | { kind: 'option'; option: FormOption }
      | { kind: 'checkbox'; checked: boolean };
    count: number;
  }[];
};

/**
 * A form over a database table. Viewers can read its questions and submit;
 * editors can build it and read responses; owners control its audience.
 */
export class Form extends MacroEntity<FormDetail> {
  protected async fetch(): Promise<FormDetail> {
    return unwrap(await this.client.storage.getForm({ path: { id: this.id } }));
  }

  /** A form handle with details loaded on demand. */
  static byId(client: MacroClient, id: string): Form {
    return new Form(client, id);
  }

  /** Create a form, optionally over a table of a database the caller owns. */
  static async create(
    client: MacroClient,
    options: { name: string; table?: DatabaseTable },
  ): Promise<Form> {
    const detail = unwrap(
      await client.storage.createForm({
        body: {
          name: options.name,
          source: options.table
            ? {
                kind: 'table',
                databaseId: options.table.database.id,
                tableId: options.table.id,
              }
            : { kind: 'new' },
        },
      }),
    );
    return new Form(client, detail.form.id, detail);
  }

  /** Forms shared with the caller, or live forms over a specified database. */
  static async list(client: MacroClient, database?: Database): Promise<Form[]> {
    if (!database) {
      const listed = unwrap(await client.storage.listAccessibleForms());
      return listed.map(({ form }) => new Form(client, form.id));
    }
    const forms = unwrap(
      await client.storage.listForms({ query: { databaseId: database.id } }),
    );
    return forms.map((form) => new Form(client, form.id));
  }

  /** The form's presentation and column facts; this never contains response rows. */
  schema(): Promise<FormDetail> {
    return this.detail.get();
  }

  /** The form's display name. */
  readonly name = this.mappedField('form', (form) => form.name);
  /** Introductory text shown to respondents. */
  readonly description = this.mappedField('form', (form) => form.description);
  /** The owning user. */
  readonly owner = this.mappedField('form', (form) =>
    User.byId(this.client, form.ownerId),
  );
  /** The response database. Reading its contents requires separate access. */
  readonly database = this.mappedField('form', (form) =>
    Database.byId(this.client, form.databaseId),
  );
  /** The linked table, without fetching its contents. */
  readonly table = this.mappedField('form', (form) =>
    DatabaseTable.byId(
      Database.byId(this.client, form.databaseId),
      form.tableId,
    ),
  );
  /** Who may respond. */
  readonly audience = this.mappedField('form', (form) => form.audience);
  /** Whether submissions are currently enabled. A closing time can also close the form. */
  readonly status = this.mappedField('form', (form) => form.status);
  /** Scheduled closing time, when set. */
  readonly closesAt = this.mappedField(
    'form',
    (form) => form.closesAt ?? undefined,
  );
  /** The caller's access level. */
  readonly access = this.field('access');

  /** Sections in display order. */
  async sections(): Promise<FormSection[]> {
    return (await this.detail.get()).sections.map((section) =>
      FormSection.byId(this, section.id),
    );
  }

  /** All questions in display order, skipping gates. */
  async questions(): Promise<FormQuestion[]> {
    return (await this.detail.get()).sections.flatMap((section) =>
      section.kind === 'questions'
        ? section.questions.map((question) =>
            FormQuestion.byId(this, question.id),
          )
        : [],
    );
  }

  /** Update presentation or owner-controlled settings; null explicitly clears the closing time. */
  async update(updates: UpdateForm): Promise<this> {
    await this.mutate((client) =>
      client.storage.updateForm({ path: { id: this.id }, body: updates }),
    );
    return this;
  }

  private assertOwns(part: { form: Form }): void {
    if (part.form.id !== this.id)
      throw new MacroError(
        `question or section does not belong to form ${this.id}`,
      );
  }

  /**
   * Save a replacement in the shared draft. Existing handles retain identity;
   * omitted handles mint sections or questions. Column facts use the database API.
   * A publicationError means the draft was saved but respondents still see the last
   * valid version. Repair the reported problem or reload to retry publication.
   */
  async replaceLayout(
    sections: FormSectionPlacement[],
  ): Promise<FormLayoutResult> {
    const table = await this.table();
    const ownColumn = (column: DatabaseColumn): string => {
      if (
        column.table.id !== table.id ||
        column.table.database.id !== table.database.id
      ) {
        throw new MacroError(
          `column does not belong to form ${this.id}'s table`,
        );
      }
      return column.id;
    };
    const rules = (group: FormRules): FilterGroup => ({
      conjunction: group.conjunction,
      conditions: group.conditions.map(
        (node): FilterNode =>
          match(node)
            .with({ kind: 'group' }, (nested) => ({
              kind: 'group' as const,
              ...rules(nested),
            }))
            .with({ kind: 'condition' }, (condition) => ({
              kind: 'condition' as const,
              column: ownColumn(condition.column),
              test: match(condition.test)
                .with({ kind: 'options' }, (test) => ({
                  ...test,
                  options: test.options.map((option) => option.id),
                }))
                .with({ kind: 'entities' }, (test) => ({
                  ...test,
                  entities: test.entities.map((entity) => entity.id),
                }))
                .with(
                  {
                    kind: P.union(
                      'presence',
                      'text',
                      'number',
                      'date',
                      'dateRange',
                      'checkbox',
                    ),
                  },
                  (test) => test,
                )
                .exhaustive(),
            }))
            .exhaustive(),
      ),
    });
    const body: FormLayout = {
      sections: sections.map((section): WireFormSection => {
        if (section.section) this.assertOwns(section.section);
        const common = {
          id: section.section?.id ?? uuidv7(),
          title: section.title,
          description: section.description ?? '',
        };
        return match(section)
          .with({ kind: 'booking' }, (booking) => ({
            ...common,
            kind: 'booking' as const,
            target: booking.target,
          }))
          .with({ kind: 'gate' }, (gate) => ({
            ...common,
            kind: 'gate' as const,
            rules: rules(gate.rules),
            message: gate.message,
          }))
          .with({ kind: 'questions' }, (group) => ({
            ...common,
            kind: 'questions' as const,
            questions: group.questions.map((question) => {
              if (question.question) this.assertOwns(question.question);
              return {
                id: question.question?.id ?? uuidv7(),
                column: ownColumn(question.column),
                helpText: question.helpText ?? '',
                required: question.required ?? false,
                widget: question.widget ?? null,
              };
            }),
          }))
          .exhaustive();
      }),
    };
    const saved = await this.mutate((client) =>
      client.storage.putFormLayout({ path: { id: this.id }, body }),
    );
    return { form: this, publicationError: saved.publicationError };
  }

  private wireAnswers(
    answers: FormAnswer[],
  ): { question: string; value: CellValue }[] {
    return answers.map(({ question, value }) => {
      this.assertOwns(question);
      const cell: CellValue = match(value)
        .with({ type: 'rows' }, (answer) => ({
          type: 'rows' as const,
          value: answer.value.map((row) => row.id),
        }))
        .with({ type: 'options' }, (answer) => ({
          type: 'options' as const,
          value: answer.value.map((option) => {
            if (
              option.question.id !== question.id ||
              option.question.form.id !== this.id
            ) {
              throw new MacroError(
                'option does not belong to the answered question',
              );
            }
            return { id: option.id };
          }),
        }))
        .with({ type: 'entities' }, (answer) => ({
          type: 'entities' as const,
          value: answer.value.map(({ entityType, entity }) => ({
            entityType,
            entityId: entity.id,
          })),
        }))
        .with(
          {
            type: P.union(
              'text',
              'number',
              'boolean',
              'date',
              'date_range',
              'link',
              'clear',
            ),
          },
          (answer) => answer,
        )
        .exhaustive();
      return { question: question.id, value: cell };
    });
  }

  private unlockedBooking(
    booking: UnlockedBooking | undefined,
  ): FormBookingStep | undefined {
    return booking
      ? { ...booking, section: FormSection.byId(this, booking.section) }
      : undefined;
  }

  private async outcome(
    result: SubmissionOutcome,
    answers: FormAnswer[],
  ): Promise<FormSubmissionOutcome> {
    return match(result)
      .with({ outcome: 'stopped' }, (stopped) => ({
        ...stopped,
        section: FormSection.byId(this, stopped.section),
      }))
      .with({ outcome: 'submitted' }, async (submitted) => {
        const row = DatabaseRow.byId(await this.table(), submitted.row);
        const booking = this.unlockedBooking(submitted.booking);
        return {
          outcome: 'submitted' as const,
          response: FormResponse.byId(this, submitted.response, {
            status: 'submitted',
            row,
            answers,
            booking,
          }),
          row,
          ...(booking ? { booking } : {}),
        };
      })
      .exhaustive();
  }

  /** Submit answers. Signed-in respondents get at most one response; use editResponse afterwards. */
  async submit(answers: FormAnswer[]): Promise<FormSubmissionOutcome> {
    const body = { answers: this.wireAnswers(answers) };
    return this.outcome(
      unwrap(
        await this.client.storage.submitFormResponse({
          path: { id: this.id },
          body,
        }),
      ),
      answers,
    );
  }

  /** Replace the caller's answers while the form is open; gates are evaluated again. */
  async editResponse(answers: FormAnswer[]): Promise<FormSubmissionOutcome> {
    const body = { answers: this.wireAnswers(answers) };
    return this.outcome(
      unwrap(
        await this.client.storage.editMyFormResponse({
          path: { id: this.id },
          body,
        }),
      ),
      answers,
    );
  }

  /** Read the caller's receipt and answers without reading anyone else's responses. */
  async myResponse(): Promise<MyFormResponse> {
    const mine = unwrap(
      await this.client.storage.getMyFormResponse({ path: { id: this.id } }),
    );
    if (mine.kind === 'anonymous') return { kind: 'anonymous' };
    const table = await this.table();
    const answers = await Promise.all(
      mine.answers.map(async (answer): Promise<FormAnswer> => {
        const question = FormQuestion.byId(this, answer.question);
        const value = await match(answer.value)
          .with({ type: 'options' }, (cell) => ({
            type: 'options' as const,
            value: cell.value.map((option) => {
              if (!('id' in option))
                throw new MacroError(
                  'stored form answers must reference options by id',
                );
              return FormOption.byId(question, option.id);
            }),
          }))
          .with({ type: 'entities' }, (cell) => ({
            type: 'entities' as const,
            value: cell.value.map((entity) => ({
              entityType: entity.entityType,
              entity: FormReference.byId(entity.entityType, entity.entityId),
            })),
          }))
          .with({ type: 'rows' }, async (cell) => {
            const detail = await question.detail();
            if (detail.kind.type !== 'relation')
              throw new MacroError('row answer requires a relation question');
            const related = DatabaseTable.byId(
              Database.byId(this.client, detail.kind.database),
              detail.kind.table,
            );
            return {
              type: 'rows' as const,
              value: cell.value.map((row) => DatabaseRow.byId(related, row)),
            };
          })
          .with(
            {
              type: P.union(
                'text',
                'number',
                'boolean',
                'date',
                'date_range',
                'link',
                'clear',
              ),
            },
            (cell) => cell,
          )
          .exhaustive(() => {
            throw new MacroError(
              `answer to question ${question.id} has a type this SDK doesn't know`,
            );
          });
        return { question, value };
      }),
    );
    const row = mine.response.row
      ? DatabaseRow.byId(table, mine.response.row)
      : undefined;
    const booking = this.unlockedBooking(mine.booking);
    return {
      kind: 'saved',
      ...(booking ? { booking } : {}),
      response: FormResponse.byId(this, mine.response.id, {
        status: mine.response.status,
        row,
        answers,
        booking,
      }),
      status: mine.response.status,
      stoppedAtSection: mine.response.stoppedAtSection
        ? FormSection.byId(this, mine.response.stoppedAtSection)
        : undefined,
      row,
      submittedAt: mine.response.submittedAt,
      updatedAt: mine.response.updatedAt,
      answers,
    };
  }

  /** Ledger counts and total table rows; requires edit access. */
  async responseSummary(): Promise<FormResponseSummary> {
    const summary = unwrap(
      await this.client.storage.getFormResponseSummary({
        path: { id: this.id },
      }),
    );
    return {
      ...summary,
      stoppedBySection: summary.stoppedBySection.map((count) => ({
        section: FormSection.byId(this, count.section),
        count: count.count,
      })),
    };
  }

  /** Choice and checkbox counts, available to viewers when tally visibility is enabled. */
  async tally(): Promise<FormQuestionTally[]> {
    const tally = unwrap(
      await this.client.storage.getFormTally({ path: { id: this.id } }),
    );
    return tally.questions.map((entry) => {
      const question = FormQuestion.byId(this, entry.question);
      return {
        question,
        responses: entry.responses,
        buckets: entry.buckets.flatMap((bucket): FormQuestionTally['buckets'] =>
          match(bucket.value)
            .with({ kind: 'option' }, (value) => [
              {
                count: bucket.count,
                value: {
                  kind: 'option' as const,
                  option: FormOption.byId(question, value.option),
                },
              },
            ])
            .with({ kind: 'checkbox' }, (value) => [
              { count: bucket.count, value },
            ])
            .exhaustive((unknown) => {
              console.warn('macro sdk: unknown form tally bucket', unknown);
              return [];
            }),
        ),
      };
    });
  }

  /** Read the form's sharing grants. Requires ownership. */
  async sharePermissions(): Promise<SharePermissionV2> {
    return unwrap(
      await this.client.storage.getFormPermissions({ path: { id: this.id } }),
    );
  }

  /** Update grants. Public responding is controlled by audience, not link sharing. */
  updateSharePermissions(
    request: UpdateSharePermissionRequestV2,
  ): Promise<SharePermissionV2> {
    return this.mutate((client) =>
      client.storage.updateFormPermissions({
        path: { id: this.id },
        body: request,
      }),
    );
  }

  /** Open the form's builder in Macro. */
  webUrl(): string {
    return `${this.client.webAppUrl}/app/form/${this.id}`;
  }

  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
  override toJSON() {
    return { ...super.toJSON(), url: this.webUrl() };
  }

  /** The respondent page, which public forms also expose without signing in. */
  respondUrl(): string {
    return `${this.client.webAppUrl}/app/form/${this.id}/respond`;
  }
}