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
import type { DraftAttempt } from '@app/features/email-compose/core/local-draft';
import { DEFAULT_THREAD_MESSAGES_LIMIT } from '@core/constant/pagination';
import {
executeOptimisticMutation,
type OptimisticResponse,
optimisticMutationDispositionOf,
prependUnique,
remove,
select,
update,
} from '@graphql-cache/exchange/optimistic';
import { getUnmaintainedGraphqlSoupRevalidations } from '@queries/soup/graphql/active-queries';
import {
DeleteEmailDraftDocument,
type DeleteEmailDraftMutation,
type DeleteEmailDraftMutationVariables,
EmailThreadPageDocument,
type EmailThreadPageQuery,
type EmailThreadPageQueryVariables,
type SaveEmailDraftContactInput,
SaveEmailDraftDocument,
type SaveEmailDraftInput,
type SaveEmailDraftMutation,
type SaveEmailDraftMutationVariables,
} from '@service-storage/graphql/generated/graphql';
import {
type AnyVariables,
type Client,
CombinedError,
type OperationResult,
} from '@urql/core';
import {
createDraftThread,
type DraftThread,
draftThreadIsEmpty,
removeDraftFromThread,
updateDraftThread,
} from './optimistic-thread';
/**
* Input for a durable GraphQL draft save. `draftId` is the draft's handle —
* a client-minted id (or a server id from a fetched draft) that the server
* resolves through a caller-scoped mapping to a server-minted row, so saves
* queued offline replay as idempotent upserts without the handle ever
* becoming a primary key. `threadDbId` is a stable local handle for new
* standalone drafts, or the existing conversation ID for replies.
*
* Sender email is persisted on the wire as well as the optimistic entity.
* Sender metadata and optimistic-only fields are stripped from the variables.
*/
export type GraphqlSaveEmailDraftArgs = Omit<
SaveEmailDraftInput,
'threadDbId'
> & {
threadDbId: string;
/** Sending inbox id for the optimistic entity's `linkId` — the input's
* `linkId` is deliberately absent when sending from the primary inbox. */
senderLinkId: string;
/** Verified sending address, persisted and used by the optimistic entity. */
senderEmail: string;
/** Plain (non-base64) editor HTML for the optimistic entity's
* `bodyHtmlSanitized` — responses carry that field unencoded. Unsanitized
* until the first commit; own-content only, composed locally. */
optimisticBodyHtml: string | null;
/** Preserve persisted fields this body/envelope save does not modify. */
existingDraft?: OptimisticDraftEntity;
/** Complete cached conversation, when available. */
existingThread?: DraftThread;
/** Present only when this save creates a standalone local thread. */
newThreadOwnerId?: string;
/** Importance of this account's own draft sender. */
senderIsSignal?: boolean;
/** Original queue coalescing key survives adoption of server IDs. */
mutationUuid?: string;
clientMetadata?: DraftAttempt;
localRevision?: number;
};
/** Maps a REST-shaped contact to the mutation's input shape. */
export function draftContactInput(contact: {
email: string;
name?: string | null;
photo_url?: string | null;
}): SaveEmailDraftContactInput {
return {
email: contact.email,
name: contact.name,
photoUrl: contact.photo_url,
};
}
/** Machine-readable failure codes set by the resolver's error taxonomy. */
export type SaveEmailDraftFailureCode =
| 'DRAFT_ALREADY_SENT'
| 'NOT_FOUND'
| 'INBOX_NOT_FOUND'
| 'UNAUTHORIZED'
| 'INVALID'
| 'INVALID_SENDER'
| 'NEEDS_REAUTH'
| 'SEND_AS_UNAVAILABLE'
| 'INTERNAL'
| 'NETWORK';
/**
* Caller-facing outcome of one draft save. Only a committed save carries a
* server-confirmed draft ID — a queued save has not reached the server, and
* its eventual settlement arrives through the cache host, not this promise.
*/
export type SaveEmailDraftOutcome =
| { kind: 'committed'; draftId: string; threadId: string }
| { kind: 'queued'; transactionId: string }
| { kind: 'failed'; code: SaveEmailDraftFailureCode; error: CombinedError };
/** Interpret a server code consistently for foreground and replayed writes. */
export function draftFailureCode(
code: unknown
): Exclude<SaveEmailDraftFailureCode, 'NETWORK'> {
switch (code) {
case 'DRAFT_ALREADY_SENT':
case 'NOT_FOUND':
case 'INBOX_NOT_FOUND':
case 'UNAUTHORIZED':
case 'INVALID':
case 'INVALID_SENDER':
case 'NEEDS_REAUTH':
case 'SEND_AS_UNAVAILABLE':
return code;
default:
return 'INTERNAL';
}
}
/**
* The queued / failed / no-data disposition shared by the draft mutations;
* a resolved payload is the caller's to shape.
*/
function settleDraftMutation<TData, TVariables extends AnyVariables, Payload>(
result: OperationResult<TData, TVariables>,
payload: Payload | null | undefined,
missingDataMessage: string
):
| { kind: 'queued'; transactionId: string }
| { kind: 'failed'; code: SaveEmailDraftFailureCode; error: CombinedError }
| { kind: 'resolved'; payload: Payload } {
const disposition = optimisticMutationDispositionOf(result);
if (disposition?.kind === 'queued') {
return { kind: 'queued', transactionId: disposition.transactionId };
}
if (result.error) {
return {
kind: 'failed',
code: result.error.networkError
? 'NETWORK'
: draftFailureCode(result.error.graphQLErrors[0]?.extensions?.code),
error: result.error,
};
}
if (!payload) {
return {
kind: 'failed',
code: 'INTERNAL',
error: new CombinedError({
graphQLErrors: [new Error(missingDataMessage)],
}),
};
}
return { kind: 'resolved', payload };
}
type OptimisticDraftEntity = SaveEmailDraftMutation['saveEmailDraft']['draft'];
type OptimisticContact = OptimisticDraftEntity['from'];
function optimisticContact(
contact: SaveEmailDraftContactInput
): NonNullable<OptimisticContact> {
return {
email: contact.email,
name: contact.name ?? null,
photoUrl: contact.photoUrl ?? null,
};
}
/**
* Fabricates the draft as a complete message entity for the optimistic
* layer. Completeness is the invariant: the cache serves a query only when
* every selected field of every entity resolves, so a missing field here
* would turn the whole thread-page read into a miss — offline, that shows
* an unloadable thread instead of one with the draft. The mutation document
* selects the same `EmailThreadMessageFields` fragment the thread page
* reads, so fragment drift surfaces as a compile error in this function.
*
* The cache binds the handle to the server identity atomically at settlement,
* rebasing later queued edits and preserving reads through the old handle.
*/
export function optimisticDraftEntity(
args: GraphqlSaveEmailDraftArgs
): OptimisticDraftEntity {
const now = new Date().toISOString();
const existing = args.existingDraft;
return {
__typename: 'GraphqlSoupEmailMessage',
operationStatus: existing?.operationStatus ?? null,
id: String(args.draftId),
providerId: args.providerId ?? existing?.providerId ?? null,
threadId: args.threadDbId,
replyingToId: args.replyingToId != null ? String(args.replyingToId) : null,
linkId: args.senderLinkId,
subject: args.subject,
snippet: args.bodyText?.trim().slice(0, 200) ?? existing?.snippet ?? null,
internalDateTs: existing?.internalDateTs ?? null,
sentAt: existing?.sentAt ?? null,
isRead: true,
isStarred: existing?.isStarred ?? false,
isSent: false,
isDraft: true,
draftGeneration: args.draftGeneration ?? 0,
hasAttachments: existing?.hasAttachments ?? false,
scheduledSendTime: args.sendTime ?? existing?.scheduledSendTime ?? null,
scheduledSendStatus: existing?.scheduledSendStatus ?? null,
bodyText: args.bodyText ?? null,
bodyHtmlSanitized: args.optimisticBodyHtml,
bodyMacro: args.bodyMacro ?? null,
bodyReplyless: null,
calendarInvitations: existing?.calendarInvitations ?? [],
createdAt: existing?.createdAt ?? now,
updatedAt: now,
from: { email: args.senderEmail, name: null, photoUrl: null },
to: (args.to ?? []).map(optimisticContact),
cc: (args.cc ?? []).map(optimisticContact),
bcc: (args.bcc ?? []).map(optimisticContact),
labels: existing?.labels ?? [],
attachments: existing?.attachments ?? [],
attachmentsDraft: existing?.attachmentsDraft ?? [],
attachmentsForwarded: existing?.attachmentsForwarded ?? [],
};
}
/**
* Execute a draft save with a durable optimistic transaction. Offline (or
* behind a blocked queue head) the mutation persists locally and replays on
* reconnect; until it settles, the optimistic layer holds the draft as a
* full message entity spliced into the thread page's message list — so a
* reopened composer (or a relaunched app) sees the draft through the
* ordinary thread read. On commit the layer is replaced by the server's
* records. Soup revalidation reconciles list membership; the thread page
* only needs a separate read when its message list cannot be patched.
*/
export async function executeGraphqlSaveEmailDraft(
client: Client,
args: GraphqlSaveEmailDraftArgs
): Promise<SaveEmailDraftOutcome> {
// Strip the client-only fields; only schema fields may reach the wire.
const {
senderLinkId: _senderLinkId,
optimisticBodyHtml: _optimisticBodyHtml,
existingDraft: _existingDraft,
existingThread: _existingThread,
newThreadOwnerId: _newThreadOwnerId,
senderIsSignal: _senderIsSignal,
mutationUuid: _mutationUuid,
clientMetadata: _clientMetadata,
localRevision: _localRevision,
...input
} = args;
const variables: SaveEmailDraftMutationVariables = { input };
const threadPageVariables: EmailThreadPageQueryVariables = {
threadId: args.threadDbId,
offset: 0,
limit: DEFAULT_THREAD_MESSAGES_LIMIT,
};
const draft = optimisticDraftEntity(args);
// Only a newly minted thread may adopt a server identity. A reply can move
// to another inbox without moving its original conversation with it.
const localThread = args.existingThread
? args.existingThread.cacheProjection === null
: !!args.newThreadOwnerId;
const canPatchThread =
localThread || args.existingThread?.linkId === args.senderLinkId;
// Keep a queued cross-inbox reply reopenable in its source conversation.
// Settlement replaces this layer with the actual destination thread.
const thread = args.existingThread
? updateDraftThread(args.existingThread, draft, args.senderIsSignal ?? true)
: args.newThreadOwnerId
? createDraftThread(
draft,
args.newThreadOwnerId,
args.senderIsSignal ?? true
)
: undefined;
const optimisticData: OptimisticResponse<SaveEmailDraftMutation> = {
saveEmailDraft: {
draftId: String(args.draftId),
draft,
thread,
},
};
const result = await executeOptimisticMutation(
client,
SaveEmailDraftDocument,
variables,
optimisticData,
{
// The draft handle is the coalescing key: a newer save of the same
// draft safely replaces an older queued one (saves are full-state
// snapshots), so an offline typing session holds one queue row per
// draft instead of one per debounce tick. The delete reuses the key —
// a discard supersedes any still-queued save.
uuid: args.mutationUuid ?? String(args.draftId),
clientMetadata: args.clientMetadata,
identityBindings: [
{
localKey: `GraphqlSoupEmailMessage:${args.draftId}`,
responsePath: ['saveEmailDraft', 'draft'],
referenceFields: [
'GraphqlSoupEmailDraftAttachment.draftId',
'GraphqlSoupEmailForwardedAttachment.draftId',
'GraphqlMailPreviewMessage.id',
'GraphqlMailDraftEntry.id',
],
},
{
localKey: `GraphqlSoupEmailThread:${args.threadDbId}`,
// Keep reference-only bindings so already queued local saves still
// rebase through a preceding save's durable alias.
responsePath: localThread ? ['saveEmailDraft', 'thread'] : [],
referenceFields: ['GraphqlSoupEmailMessage.threadId'],
revalidationVariables: ['threadId'],
},
],
// Splice the optimistic entity into the thread page's message list so
// draftMap sees it. Idempotent; reapplied at commit; a non-resolving
// path is skipped and recovered by the revalidation below.
// A different sending inbox can create a new conversation. Never splice
// its committed draft back into the existing source conversation.
updates: canPatchThread
? [
update(
select<EmailThreadPageQuery, EmailThreadPageQueryVariables>(
EmailThreadPageDocument,
threadPageVariables
)
.field('user')
.field('emailThread')
.field('messages'),
prependUnique({
__typename: 'GraphqlSoupEmailMessage',
id: String(args.draftId),
})
),
]
: [],
// The returned draft and thread records update every list the cache
// maintains; the rest are read again. Refetch the thread page only
// when a missing snapshot or an inbox move prevents the message-list
// patch; otherwise a save can reset the open thread.
revalidations: [
...getUnmaintainedGraphqlSoupRevalidations(),
...(canPatchThread
? []
: [
{
document: EmailThreadPageDocument,
variables: threadPageVariables,
},
]),
],
}
).toPromise();
const settled = settleDraftMutation(
result,
result.data?.saveEmailDraft,
'draft save returned no data'
);
if (settled.kind !== 'resolved') return settled;
return {
kind: 'committed',
draftId: settled.payload.draftId,
threadId: settled.payload.thread.id,
};
}
/** Input for a durable GraphQL draft delete. */
export type GraphqlDeleteEmailDraftArgs = {
draftGeneration?: number;
/** The draft to delete, by its client-generated id. */
draftId: string;
/** Thread the draft lives in — targets the optimistic removal from the
* thread page's message list and the post-commit revalidation. */
threadDbId: string;
existingThread?: DraftThread;
mutationUuid?: string;
clientMetadata?: DraftAttempt;
};
/**
* Caller-facing outcome of one draft delete. `committed.deleted` is false
* when the server found nothing to delete — the delete is idempotent, so
* that is success, not an error.
*/
export type DeleteEmailDraftOutcome =
| { kind: 'committed'; deleted: boolean; threadDeleted: boolean }
| { kind: 'queued'; transactionId: string }
| { kind: 'failed'; code: SaveEmailDraftFailureCode; error: CombinedError };
/**
* Execute a draft delete with a durable optimistic transaction. Offline the
* mutation persists locally and replays on reconnect — strictly after any
* queued saves of the same draft, so save-then-discard converges to no
* draft. Until it settles, the optimistic layer removes the draft from the
* thread page's message list, so a reopened thread (or relaunched app) no
* longer shows it. The server delete is idempotent: replaying after the
* draft is already gone succeeds as a no-op.
*/
export async function executeGraphqlDeleteEmailDraft(
client: Client,
args: GraphqlDeleteEmailDraftArgs
): Promise<DeleteEmailDraftOutcome> {
const variables: DeleteEmailDraftMutationVariables = {
input: {
draftId: args.draftId,
draftGeneration: args.draftGeneration ?? 0,
},
};
const threadPageVariables: EmailThreadPageQueryVariables = {
threadId: args.threadDbId,
offset: 0,
limit: DEFAULT_THREAD_MESSAGES_LIMIT,
};
const thread = args.existingThread
? removeDraftFromThread(args.existingThread, args.draftId)
: undefined;
const optimisticData: OptimisticResponse<DeleteEmailDraftMutation> = {
deleteEmailDraft: {
draftId: args.draftId,
deleted: true,
threadDeleted: thread ? draftThreadIsEmpty(thread) : false,
threadId: args.threadDbId,
thread,
},
};
const result = await executeOptimisticMutation(
client,
DeleteEmailDraftDocument,
variables,
optimisticData,
{
// Same coalescing key as the draft's saves: a discard supersedes any
// still-queued save of this draft — the replaced entry never replays,
// and the delete itself is an idempotent no-op if nothing was created.
uuid: args.mutationUuid ?? args.draftId,
clientMetadata: args.clientMetadata,
identityBindings: [
{
localKey: `GraphqlSoupEmailMessage:${args.draftId}`,
responsePath: [],
deleteRecord: true,
referenceFields: [
'GraphqlMailPreviewMessage.id',
'GraphqlMailDraftEntry.id',
],
},
{
localKey: `GraphqlSoupEmailThread:${args.threadDbId}`,
responsePath: [],
referenceFields: ['GraphqlSoupEmailMessage.threadId'],
revalidationVariables: ['threadId'],
},
],
// Drop the draft from the thread page's message list so draftMap
// stops seeing it. Idempotent; reapplied at commit; a non-resolving
// path is skipped and recovered by the revalidation below.
updates: [
update(
select<EmailThreadPageQuery, EmailThreadPageQueryVariables>(
EmailThreadPageDocument,
threadPageVariables
)
.field('user')
.field('emailThread')
.field('messages'),
remove({
__typename: 'GraphqlSoupEmailMessage',
id: args.draftId,
})
),
],
revalidations: [
...getUnmaintainedGraphqlSoupRevalidations(),
{
document: EmailThreadPageDocument,
variables: threadPageVariables,
},
],
}
).toPromise();
const settled = settleDraftMutation(
result,
result.data?.deleteEmailDraft,
'draft delete returned no data'
);
if (settled.kind !== 'resolved') return settled;
return {
kind: 'committed',
deleted: settled.payload.deleted,
threadDeleted: settled.payload.threadDeleted,
};
}