@remit/backend 0.0.142 → 0.0.144

package/dist/src/handlers/calendar.js

@@ -0,0 +1,330 @@
+import { DEFAULT_CALENDAR_URL_SEGMENT, isResolvableZone, prepareCalendarObject, provisionDefaultCalendar, readCalendarFeed, readSubscriptionUrl, writeCalendarFeed, } from "@remit/calendar-service";
+import { normalizeCalendarUrlSegment } from "@remit/data-ports/id";
+import { CalendarSource } from "@remit/domain-enums";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { defaultErrorCode } from "../error.js";
+import { getClient } from "../service/data-client.js";
+export const refuseCalendar = (code, message) => ({ ok: false, error: { code, message } });
+/**
+ * `CalendarRefusal.code` is this module's and `@remit/calendar-service`'s own
+ * routing token, in PascalCase; the API's `code` vocabulary is snake_case
+ * (issue #371). Derived rather than mapped by hand, so a refusal added to
+ * either producer reaches the wire under its own name instead of silently
+ * collapsing into the status-class code.
+ */
+const wireCode = (code) => code.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+/**
+ * A 400 keeps the refusal's own code — `unknown_time_zone` and
+ * `url_segment_taken` are what a client branches on, and the status class alone
+ * would not distinguish them. A 404 and a 412 have nothing to add to their
+ * status, so they take the shared token.
+ */
+export const badRequest = (error) => ({
+    statusCode: 400,
+    body: { code: wireCode(error.code), message: error.message },
+});
+export const notFound = (message) => ({
+    statusCode: 404,
+    body: { code: defaultErrorCode(404), message },
+});
+export const preconditionFailed = (message) => ({
+    statusCode: 412,
+    body: { code: defaultErrorCode(412), message },
+});
+/** The calendar half of the client, named so a handler takes only what it uses. */
+export const calendarDepsOf = (client) => ({
+    calendarCollection: client.calendarCollection,
+    calendarObject: client.calendarObject,
+    calendarEventIndex: client.calendarEventIndex,
+    calendarFeedToken: client.calendarFeedToken,
+    calendarStore: client.calendarStore,
+});
+const toCalendarResponse = (item) => ({
+    calendarId: item.calendarId,
+    accountConfigId: item.accountConfigId,
+    urlSegment: item.urlSegment,
+    displayName: item.displayName,
+    color: item.color,
+    componentSet: item.componentSet,
+    source: item.source,
+    timezone: item.timezone,
+    syncSequence: item.syncSequence,
+    subscriptionUrl: item.subscriptionUrl,
+    subscriptionEnabled: item.subscriptionEnabled,
+    subscriptionCheckedAt: item.subscriptionCheckedAt,
+    subscriptionFetchedAt: item.subscriptionFetchedAt,
+    subscriptionError: item.subscriptionError,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+});
+/**
+ * Every collection the account config holds, provisioning the default one when
+ * it holds none.
+ *
+ * Safe to race with itself: `calendarId` is derived from the account config and
+ * the URL segment, so two first reads arriving together write the same row
+ * rather than two, and the loser's write is a no-op instead of a second
+ * calendar nobody asked for.
+ */
+export const listCalendarsFor = async (deps, accountConfigId) => {
+    const existing = await deps.calendarCollection.listByAccountConfig(accountConfigId);
+    if (existing.length > 0)
+        return existing;
+    await provisionDefaultCalendar(deps.calendarStore, accountConfigId);
+    return deps.calendarCollection.listByAccountConfig(accountConfigId);
+};
+/** One of the caller's collections, or a refusal naming the one they asked for. */
+export const findCalendarFor = async (deps, accountConfigId, calendarId) => {
+    const collections = await deps.calendarCollection.listByAccountConfig(accountConfigId);
+    const found = collections.find((collection) => collection.calendarId === calendarId);
+    if (!found) {
+        return refuseCalendar("NotFound", `no calendar ${calendarId} on this account`);
+    }
+    return { ok: true, value: found };
+};
+/**
+ * One of the caller's collections that a person may write events into. A
+ * subscribed collection holds what its feed holds: an edit made here would be
+ * overwritten by the next refresh, so it is refused rather than accepted and
+ * silently lost.
+ */
+export const findWritableCalendarFor = async (deps, accountConfigId, calendarId) => {
+    const found = await findCalendarFor(deps, accountConfigId, calendarId);
+    if (!found.ok)
+        return found;
+    if (found.value.source === CalendarSource.Subscribed) {
+        return refuseCalendar("ReadOnlyCalendar", `"${found.value.displayName}" is subscribed to a feed and is read-only — change the event where the feed comes from`);
+    }
+    return found;
+};
+/**
+ * A collection's timezone is what every floating time in it is read in, so a
+ * name this server cannot resolve is not a cosmetic setting — it silently moves
+ * every all-day and unzoned event in the calendar. A Windows zone name, which
+ * is what a client that has not normalised its input sends, is refused here
+ * rather than stored and quietly read as UTC.
+ */
+export const readCollectionTimezone = (timezone) => {
+    if (timezone === undefined || timezone === "")
+        return { ok: true, value: "" };
+    if (!isResolvableZone(timezone)) {
+        return refuseCalendar("UnknownTimeZone", `"${timezone}" is not a time zone this server can resolve — use an IANA name such as "Europe/Amsterdam"`);
+    }
+    return { ok: true, value: timezone };
+};
+/**
+ * Creates a collection subscribed to a feed. The feed is read before anything
+ * is written, so an address that cannot be fetched leaves no empty calendar
+ * behind; its events then land through the one write path, in the same unit as
+ * the collection itself.
+ */
+const createSubscribedCalendarFor = async (deps, accountConfigId, input, collection, fetcher, now) => {
+    const url = readSubscriptionUrl(input.subscriptionUrl);
+    if (!url.ok)
+        return url;
+    const feed = await readCalendarFeed(url.value, fetcher);
+    if (!feed.ok) {
+        return refuseCalendar("SubscriptionUnreachable", `the calendar was not created: ${feed.reason}`);
+    }
+    const { repos } = deps.calendarStore;
+    const made = await repos.calendarCollection.createExclusive({
+        accountConfigId,
+        urlSegment: collection.urlSegment,
+        displayName: input.displayName,
+        color: input.color,
+        timezone: collection.timezone,
+        source: CalendarSource.Subscribed,
+        subscriptionUrl: url.value,
+        subscriptionEnabled: true,
+    });
+    if (!made) {
+        return refuseCalendar("UrlSegmentTaken", `"${collection.urlSegment}" already addresses a calendar on this account — pick another`);
+    }
+    // A separate step from the create: a collection the feed write never
+    // reached is enabled and never checked, so the scheduled refresh takes it
+    // on its next pass and fills it from the same feed.
+    await writeCalendarFeed(deps.calendarStore, { accountConfigId, calendarId: made.calendarId }, feed.value, now);
+    return {
+        ok: true,
+        value: await repos.calendarCollection.get(accountConfigId, made.calendarId),
+    };
+};
+export const createCalendarFor = async (deps, accountConfigId, input, fetcher = fetch, now = Date.now()) => {
+    const urlSegment = normalizeCalendarUrlSegment(input.urlSegment);
+    if (urlSegment === "") {
+        return refuseCalendar("InvalidUrlSegment", "a calendar needs a url segment to be addressed by");
+    }
+    const timezone = readCollectionTimezone(input.timezone);
+    if (!timezone.ok)
+        return timezone;
+    const { subscriptionUrl } = input;
+    if (subscriptionUrl !== undefined) {
+        return createSubscribedCalendarFor(deps, accountConfigId, { ...input, subscriptionUrl }, { urlSegment, timezone: timezone.value }, fetcher, now);
+    }
+    // The write decides, not a prior read: two creates of one segment arriving
+    // together would both find it free, and the loser would silently be handed
+    // the winner's calendar to write into.
+    const created = await deps.calendarStore.repos.calendarCollection.createExclusive({
+        accountConfigId,
+        urlSegment,
+        displayName: input.displayName,
+        color: input.color,
+        timezone: timezone.value,
+        source: CalendarSource.UserCreated,
+    });
+    if (!created) {
+        return refuseCalendar("UrlSegmentTaken", `"${urlSegment}" already addresses a calendar on this account — pick another`);
+    }
+    return { ok: true, value: created };
+};
+/**
+ * Removes a collection with everything in it, in one unit.
+ *
+ * The default collection stays: it is where an accepted invitation and a first
+ * event land, and an account config with no calendar has nowhere to put one.
+ */
+export const deleteCalendarFor = async (deps, accountConfigId, calendarId) => {
+    const collection = await findCalendarFor(deps, accountConfigId, calendarId);
+    if (!collection.ok)
+        return collection;
+    if (collection.value.source === CalendarSource.Default) {
+        return refuseCalendar("DefaultCalendarUndeletable", `"${DEFAULT_CALENDAR_URL_SEGMENT}" is the calendar this account files events into and cannot be removed`);
+    }
+    await deps.calendarStore.commit([
+        { kind: "DeleteCollection", accountConfigId, calendarId },
+    ]);
+    return { ok: true, value: null };
+};
+/**
+ * Reduce a PATCH body to the fields a collection update may set. `urlSegment`
+ * is deliberately absent: it is the collection's identity and the path a client
+ * has bookmarked, so moving it is making a different calendar.
+ */
+export const pickCalendarUpdate = (body) => {
+    const patch = {};
+    if (Object.hasOwn(body, "displayName"))
+        patch.displayName = body.displayName;
+    if (Object.hasOwn(body, "color"))
+        patch.color = body.color;
+    if (Object.hasOwn(body, "timezone"))
+        patch.timezone = body.timezone;
+    if (Object.hasOwn(body, "subscriptionEnabled")) {
+        patch.subscriptionEnabled = body.subscriptionEnabled;
+    }
+    return patch;
+};
+/**
+ * Applies a collection patch, rewriting what the collection's timezone decides.
+ *
+ * The timezone is not a label. Every floating and all-day time in the
+ * collection is read in it, so changing it moves every occurrence row those
+ * resources produced — and a row left at the old zone is an event drawn hours
+ * from where the calendar now says it is. Each resource is therefore written
+ * again from its own stored bytes, which re-projects and re-expands it and
+ * bumps the collection's sequence so a syncing client sees the change. The
+ * whole set is one unit: a half-converted calendar is worse than either zone.
+ */
+export const updateCalendarFor = async (deps, accountConfigId, calendarId, body) => {
+    const current = await findCalendarFor(deps, accountConfigId, calendarId);
+    if (!current.ok)
+        return current;
+    const patch = pickCalendarUpdate(body);
+    if (patch.subscriptionEnabled !== undefined &&
+        current.value.source !== CalendarSource.Subscribed) {
+        return refuseCalendar("NotSubscribed", `"${current.value.displayName}" is not subscribed to a feed, so there is no refresh to turn on or off`);
+    }
+    if (patch.timezone !== undefined) {
+        const timezone = readCollectionTimezone(patch.timezone);
+        if (!timezone.ok)
+            return timezone;
+        patch.timezone = timezone.value;
+    }
+    const rezone = patch.timezone !== undefined && patch.timezone !== current.value.timezone;
+    const { repos } = deps.calendarStore;
+    const rewrites = [];
+    if (rezone) {
+        const zone = { timezone: patch.timezone ?? current.value.timezone };
+        for (const object of await repos.calendarObject.listByCalendar(calendarId)) {
+            const rewritten = await prepareCalendarObject(zone, {
+                accountConfigId,
+                calendarId,
+                resourceName: object.resourceName,
+                icalData: object.icalData,
+            });
+            if (!rewritten.ok) {
+                throw new Error(`stored calendar object ${object.calendarObjectId} was refused on re-expansion: ${rewritten.error.code}`);
+            }
+            rewrites.push({
+                ...rewritten.value,
+                kind: "ReprojectObject",
+                readEtag: object.etag,
+            });
+        }
+    }
+    await deps.calendarStore.commit([
+        { kind: "UpdateCollection", accountConfigId, calendarId, patch },
+        ...rewrites,
+    ]);
+    return {
+        ok: true,
+        value: await repos.calendarCollection.get(accountConfigId, calendarId),
+    };
+};
+export const CalendarOperations = {
+    CalendarOperations_listCalendars: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const deps = calendarDepsOf(await getClient());
+        const items = await listCalendarsFor(deps, accountConfigId);
+        return { items: items.map(toCalendarResponse) };
+    },
+    CalendarOperations_createCalendar: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const input = context.request.requestBody;
+        const deps = calendarDepsOf(await getClient());
+        const created = await createCalendarFor(deps, accountConfigId, input);
+        if (!created.ok)
+            return badRequest(created.error);
+        return toCalendarResponse(created.value);
+    },
+};
+export const CalendarDetailOperations = {
+    CalendarDetailOperations_getCalendar: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { calendarId } = context.request.params;
+        const deps = calendarDepsOf(await getClient());
+        const found = await findCalendarFor(deps, accountConfigId, calendarId);
+        if (!found.ok)
+            return notFound(found.error.message);
+        return toCalendarResponse(found.value);
+    },
+    CalendarDetailOperations_updateCalendar: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { calendarId } = context.request.params;
+        const body = context.request.requestBody;
+        const deps = calendarDepsOf(await getClient());
+        const updated = await updateCalendarFor(deps, accountConfigId, calendarId, body);
+        if (!updated.ok) {
+            return updated.error.code === "NotFound"
+                ? notFound(updated.error.message)
+                : badRequest(updated.error);
+        }
+        return toCalendarResponse(updated.value);
+    },
+    CalendarDetailOperations_deleteCalendar: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const { calendarId } = context.request.params;
+        const deps = calendarDepsOf(await getClient());
+        const removed = await deleteCalendarFor(deps, accountConfigId, calendarId);
+        if (!removed.ok) {
+            return removed.error.code === "NotFound"
+                ? notFound(removed.error.message)
+                : badRequest(removed.error);
+        }
+        return { statusCode: 204 };
+    },
+};

package/dist/src/handlers/config.d.ts

@@ -0,0 +1,43 @@
+import type { SQSClient } from "@aws-sdk/client-sqs";
+import { type StoredCredentialFields } from "@remit/mailbox-service/account-credentials";
+import type { ConfigOperationIds, OperationHandler } from "../types.js";
+type StructuredLog = (fields: Record<string, unknown>, message: string) => void;
+interface ConfigSyncTriggerDeps {
+    sqsClient: SQSClient;
+    queueUrl: string;
+    logger: {
+        info: StructuredLog;
+        error: StructuredLog;
+    };
+}
+/**
+ * Fire-and-forget sync trigger for the accounts surfaced by GET /config.
+ *
+ * GET /config is a READ: its response is already computed and does not depend
+ * on the trigger succeeding. A failure here (the SQS queue unreachable in
+ * smoke/e2e, an IAM/SQS misconfig in prod) must therefore never reach the read
+ * response — but it also silently stops ALL sync, so it has to be loud and
+ * alertable rather than swallowed.
+ *
+ * This helper is fully self-contained: it catches every per-account rejection
+ * internally and resolves to void, so the caller can `void`-fire it with no
+ * chance of an unhandled rejection escaping. The dev/Lambda runtime shares one
+ * event loop, so an escaped rejection lands on whatever request is active when
+ * the deferred SQS retry finally fails — which is how a `/config` enqueue
+ * failure ended up 500-ing unrelated reads like `/outbox` and `/threads`.
+ *
+ * Each failure is logged as a distinct structured error carrying the SDK error
+ * name/code on dedicated fields plus a stable `alert: "sync_trigger_failed"`
+ * discriminator a CloudWatch metric filter / alarm can key off.
+ *
+ * An account storing no credential is not enqueued at all (issue #1120): the
+ * import wizard lands accounts without a password by design, and the client
+ * polls this read while the user is still typing one. The guard is the stored
+ * credential rather than `connectionState`, which stays `credentials_missing`
+ * until a connect succeeds — see `hasStoredCredential`.
+ */
+export declare const triggerConfigLoadSyncs: (accountConfigId: string, accounts: ReadonlyArray<{
+    accountId: string;
+} & StoredCredentialFields>, deps?: ConfigSyncTriggerDeps) => Promise<void>;
+export declare const ConfigOperations: Record<ConfigOperationIds, OperationHandler<ConfigOperationIds>>;
+export {};

package/dist/src/handlers/config.js

@@ -0,0 +1,176 @@
+import { importConfig, pendingImportOf, readConfigForExport, } from "@remit/config-transfer";
+import { ConfigNotEmptyError, NotFoundError } from "@remit/data-ports/errors";
+import { logger } from "@remit/logger";
+import { hasStoredCredential, } from "@remit/mailbox-service/account-credentials";
+import { env } from "expect-env";
+import { getAccountConfigIdFromEvent, getSubFromEvent } from "../auth.js";
+import { getClient } from "../service/data-client.js";
+import { exportIdentity } from "../service/export-identity.js";
+import { fireAndForget } from "../service/fire-and-forget.js";
+import { sqsClient } from "../service/sqs.js";
+import { triggerAccountSync } from "../service/trigger-sync.js";
+import { toAccountResponse } from "./account-guards.js";
+import { groupAccountOverrides, } from "./account-overrides.js";
+import { groupSignaturesByAccount, } from "./account-signature.js";
+import { groupFolderAppointmentsByAccount, resolveFolderAppointments, writeFolderRoleAppointment, } from "./folder-role-appointments.js";
+const defaultConfigSyncTriggerDeps = () => ({
+    sqsClient,
+    queueUrl: env.SQS_QUEUE_URL,
+    logger,
+});
+/**
+ * Fire-and-forget sync trigger for the accounts surfaced by GET /config.
+ *
+ * GET /config is a READ: its response is already computed and does not depend
+ * on the trigger succeeding. A failure here (the SQS queue unreachable in
+ * smoke/e2e, an IAM/SQS misconfig in prod) must therefore never reach the read
+ * response — but it also silently stops ALL sync, so it has to be loud and
+ * alertable rather than swallowed.
+ *
+ * This helper is fully self-contained: it catches every per-account rejection
+ * internally and resolves to void, so the caller can `void`-fire it with no
+ * chance of an unhandled rejection escaping. The dev/Lambda runtime shares one
+ * event loop, so an escaped rejection lands on whatever request is active when
+ * the deferred SQS retry finally fails — which is how a `/config` enqueue
+ * failure ended up 500-ing unrelated reads like `/outbox` and `/threads`.
+ *
+ * Each failure is logged as a distinct structured error carrying the SDK error
+ * name/code on dedicated fields plus a stable `alert: "sync_trigger_failed"`
+ * discriminator a CloudWatch metric filter / alarm can key off.
+ *
+ * An account storing no credential is not enqueued at all (issue #1120): the
+ * import wizard lands accounts without a password by design, and the client
+ * polls this read while the user is still typing one. The guard is the stored
+ * credential rather than `connectionState`, which stays `credentials_missing`
+ * until a connect succeeds — see `hasStoredCredential`.
+ */
+export const triggerConfigLoadSyncs = async (accountConfigId, accounts, deps = defaultConfigSyncTriggerDeps()) => {
+    await Promise.all(accounts.filter(hasStoredCredential).map(({ accountId }) => fireAndForget(async () => {
+        const { eventId } = await triggerAccountSync({
+            sqsClient: deps.sqsClient,
+            queueUrl: deps.queueUrl,
+            accountId,
+        });
+        deps.logger.info({ accountId, eventId }, "Sync triggered on config load");
+    }, {
+        source: "config_load",
+        message: "Failed to trigger account sync on config load",
+        ids: { accountId, accountConfigId },
+        logger: deps.logger,
+    })));
+};
+const toAccountConfigResponse = (config) => ({
+    accountConfigId: config.accountConfigId,
+    userId: config.userId,
+    name: config.name,
+    state: (config.state ??
+        "active"),
+    createdAt: config.createdAt,
+    updatedAt: config.updatedAt,
+});
+const buildCommit = () => process.env.REMIT_WORKER_SHA || process.env.GITHUB_SHA || "dev";
+/**
+ * Returned by GET /config when no AccountConfig row exists yet for this user.
+ * GET must never mutate state, so instead of creating a row we synthesize a
+ * stable, empty shape the frontend can render as a "no accounts yet" state.
+ * The POST account-creation flow will materialize the real row when the user
+ * adds their first account.
+ */
+const emptyConfigResponse = (accountConfigId, event) => {
+    const now = Date.now();
+    const userId = getSubFromEvent(event) ?? accountConfigId;
+    return {
+        accountConfig: {
+            accountConfigId,
+            userId,
+            state: "active",
+            createdAt: now,
+            updatedAt: now,
+        },
+        accounts: [],
+        buildCommit: buildCommit(),
+    };
+};
+export const ConfigOperations = {
+    ConfigOperations_getConfig: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const client = await getClient();
+        const description = await client.accountConfig
+            .describe(accountConfigId)
+            .catch((err) => {
+            if (err instanceof NotFoundError)
+                return undefined;
+            throw err;
+        });
+        if (!description || description.accountConfig.length === 0) {
+            return emptyConfigResponse(accountConfigId, event);
+        }
+        const accountConfig = description.accountConfig[0];
+        if (!accountConfig) {
+            return emptyConfigResponse(accountConfigId, event);
+        }
+        // Filter out deleted accounts (tombstone pattern)
+        const activeAccounts = description.account.filter((acc) => acc.deletedAt === undefined);
+        // Signatures and the display-name/mute overrides are stored per-account in
+        // AccountSetting rows (RFC 032). Load the whole set for this config once and
+        // key both by accountId so the account mapping below surfaces each without
+        // an N+1. The per-account folder-role map (RFC 032
+        // exclusive-folder-appointment, #976) rides the same settings rows, grouped
+        // the same way.
+        const allSettings = await client.accountSetting.listByAccountConfig(accountConfigId);
+        const signaturesByAccount = groupSignaturesByAccount(allSettings);
+        const overridesByAccount = groupAccountOverrides(allSettings);
+        const appointmentsByAccount = groupFolderAppointmentsByAccount(allSettings);
+        const signatureOf = (accountId) => signaturesByAccount.get(accountId) ?? {};
+        const overridesOf = (accountId) => overridesByAccount.get(accountId) ?? {};
+        // One mailbox list per account, fetched in parallel: `findFolderForRole`
+        // needs each account's folders to fill any role the user hasn't appointed
+        // yet (RFC 032: "the map is never empty for a normal provider").
+        const mailboxesByAccount = new Map(await Promise.all(activeAccounts.map(async (acc) => [
+            acc.accountId,
+            await client.mailbox.listAllByAccount(acc.accountId),
+        ])));
+        // Fire-and-forget: a failed sync enqueue must never fail this read.
+        // triggerConfigLoadSyncs swallows nothing — it logs each failure loudly
+        // with an alertable structured field — but it also never rejects, so the
+        // `void` here cannot leak an unhandled rejection into a later request.
+        void triggerConfigLoadSyncs(accountConfigId, activeAccounts);
+        // An import that named folders IMAP had not produced yet rides the config
+        // read rather than a route of its own, so nothing has to poll for it.
+        const pendingImport = pendingImportOf(await client.configImport.listByAccountConfig(accountConfigId));
+        return {
+            accountConfig: toAccountConfigResponse(accountConfig),
+            ...(pendingImport ? { pendingImport } : {}),
+            buildCommit: buildCommit(),
+            accounts: activeAccounts.map((acc) => toAccountResponse(acc, signatureOf(acc.accountId), overridesOf(acc.accountId), resolveFolderAppointments(appointmentsByAccount.get(acc.accountId) ?? new Map(), mailboxesByAccount.get(acc.accountId) ?? []))),
+        };
+    },
+    ConfigOperations_exportConfig: async (_context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const client = await getClient();
+        const document = await readConfigForExport(client, accountConfigId, exportIdentity());
+        return { schemaVersion: document.schemaVersion, document };
+    },
+    ConfigOperations_importConfig: async (context, ...args) => {
+        const event = args[0];
+        const accountConfigId = getAccountConfigIdFromEvent(event);
+        const body = (context.request.requestBody ?? {});
+        const client = await getClient();
+        const outcome = await importConfig({
+            repositories: client,
+            appointFolderRole: (configId, accountId, role, mailboxId, lastKnownPath) => writeFolderRoleAppointment(client.accountSetting, configId, accountId, role, mailboxId, lastKnownPath),
+        }, {
+            accountConfigId,
+            userId: getSubFromEvent(event) ?? accountConfigId,
+            document: body.document,
+            mode: body.mode ?? "validate",
+            onExisting: body.onExisting ?? "abort",
+        });
+        if (outcome.outcome === "conflict") {
+            throw new ConfigNotEmptyError(outcome.conflict.message, outcome.conflict.details);
+        }
+        return outcome.report;
+    },
+};

package/dist/src/handlers/ensure-account-config.d.ts

@@ -0,0 +1,9 @@
+import type { IAccountConfigRepository } from "@remit/data-ports";
+/**
+ * Ensure an AccountConfig row exists for the given id. A first-time caller
+ * coming from Cognito will not yet have one; subsequent calls are idempotent.
+ *
+ * We attempt a read first to avoid relying on a race on `create()` — the
+ * deterministic id (derived from Cognito `sub`) makes both paths safe.
+ */
+export declare const ensureAccountConfig: (accountConfig: IAccountConfigRepository, accountConfigId: string) => Promise<void>;

package/dist/src/handlers/ensure-account-config.js

@@ -0,0 +1,27 @@
+import { ConflictError, NotFoundError } from "@remit/data-ports/errors";
+/**
+ * Ensure an AccountConfig row exists for the given id. A first-time caller
+ * coming from Cognito will not yet have one; subsequent calls are idempotent.
+ *
+ * We attempt a read first to avoid relying on a race on `create()` — the
+ * deterministic id (derived from Cognito `sub`) makes both paths safe.
+ */
+export const ensureAccountConfig = async (accountConfig, accountConfigId) => {
+    const existing = await accountConfig.get(accountConfigId).catch((err) => {
+        if (err instanceof NotFoundError)
+            return undefined;
+        throw err;
+    });
+    if (existing)
+        return;
+    await accountConfig
+        .create({
+        accountConfigId,
+        userId: accountConfigId,
+    })
+        .catch((err) => {
+        if (err instanceof ConflictError)
+            return;
+        throw err;
+    });
+};

package/dist/src/handlers/filter.d.ts

@@ -0,0 +1,3 @@
+import type { FilterDetailOperationIds, FilterOperationIds, OperationHandler } from "../types.js";
+export declare const FilterOperations: Record<FilterOperationIds, OperationHandler<FilterOperationIds>>;
+export declare const FilterDetailOperations: Record<FilterDetailOperationIds, OperationHandler<FilterDetailOperationIds>>;