Feat/parse invitation

source/invitation/parser.ts

@@ -0,0 +1,27 @@
+import type { XOInvitation } from '@xo-cash/types';
+import { buildErrorDescription } from '../errors.ts';
+import { InvitationInvalidError } from './errors.ts';
+import { xoInvitationSchema } from './schemas.ts';
+
+/**
+ * Validates an untyped value against the XOInvitation schema and returns it as a typed invitation.
+ *
+ * The schema parser returns a rebuilt copy whose keys follow the schema order. Commit signatures cover the JSON text of
+ * each commit's data, and that text depends on key order, so a rebuilt copy no longer matches its signatures. Only the
+ * value that was received keeps the order it was signed with.
+ *
+ * The received value itself is returned, not a copy, so the key order its commit signatures were made over is kept.
+ *
+ * @param {unknown} invitationValue - Value to validate, such as the output of Extended JSON parsing.
+ * @returns {XOInvitation} - The validated invitation, as the same object that was passed in.
+ * @throws {@link InvitationInvalidError} - When any field is missing, has the wrong type, or is not part of the invitation type.
+ */
+export const parseInvitation = (invitationValue: unknown): XOInvitation => {
+    const parseResult = xoInvitationSchema.safeParse(invitationValue);
+
+    if (parseResult.success === false) {
+        throw new InvitationInvalidError(buildErrorDescription(parseResult.error.issues));
+    }
+
+    return invitationValue as XOInvitation;
+};