@oxy.so/contracts 4.0.0 → 4.1.0

package/dist/cjs/email/messages.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * Wire contract for the Inbox read API (`/email/*` on oxy-api).
+ *
+ * These schemas describe what a client RECEIVES — the JSON-serialised DTOs of
+ * `packages/api/src/services/email.service.ts` — so every timestamp is an ISO
+ * string and every nullable column is `null`, never absent. oxy-api asserts at
+ * the type level that its DTOs serialise to exactly these shapes, and a
+ * database-backed test parses real responses with them; a client parses with
+ * the same schemas. One declaration, two sides, no drift.
+ *
+ * Why this exists: the Inbox client used to declare its own copy, with
+ * `contentId: z.string().optional()`. oxy-api sends `null` for an attachment
+ * without a Content-ID, the client's parse failed, and the list silently
+ * dropped the whole message — a verification-code mail that appeared for a
+ * second (the realtime placeholder) and then vanished (the refetch).
+ *
+ * Unknown keys are stripped, not rejected, so the server may ADD a field
+ * without breaking an older client. Removing or re-typing one is breaking.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rfcMessageIdSchema = exports.RFC_MESSAGE_ID_PATTERN = exports.emailOutboxSchema = exports.emailContactSchema = exports.emailBundledInboxSchema = exports.emailBundleSchema = exports.emailFilterSchema = exports.emailFilterActionSchema = exports.emailFilterConditionSchema = exports.emailLabelSchema = exports.emailSystemLabelSchema = exports.emailUserLabelSchema = exports.emailMailboxSchema = exports.emailMessageSchema = exports.emailMessageHighlightSchema = exports.emailMessageCardSchema = exports.emailMessageFlagsSchema = exports.emailAttachmentSchema = exports.emailMessageAddressSchema = exports.EMAIL_OUTBOX_STATUSES = exports.EMAIL_FILTER_ACTION_TYPES = exports.EMAIL_FILTER_CONDITION_OPERATORS = exports.EMAIL_FILTER_CONDITION_FIELDS = exports.MESSAGE_CARD_TYPES = void 0;
+const zod_1 = require("zod");
+/** An ISO-8601 instant as `Date.prototype.toJSON` writes it. */
+const isoInstant = zod_1.z.string().datetime();
+// ─── Vocabularies ───────────────────────────────────────────────────
+/** Structured data cards the AI extractor can emit. */
+exports.MESSAGE_CARD_TYPES = ['trip', 'purchase', 'event', 'bill', 'package'];
+/** What a mail-rule condition looks at. */
+exports.EMAIL_FILTER_CONDITION_FIELDS = ['from', 'to', 'subject', 'has-attachment', 'size'];
+/** How a mail-rule condition compares. */
+exports.EMAIL_FILTER_CONDITION_OPERATORS = [
+    'contains',
+    'equals',
+    'not-contains',
+    'starts-with',
+    'ends-with',
+    'greater-than',
+    'less-than',
+];
+/** What a mail rule does. */
+exports.EMAIL_FILTER_ACTION_TYPES = [
+    'move',
+    'label',
+    'star',
+    'mark-read',
+    'archive',
+    'delete',
+    'forward',
+];
+/** Lifecycle of a durable outbound delivery. */
+exports.EMAIL_OUTBOX_STATUSES = ['pending', 'processing', 'sent', 'failed', 'cancelled'];
+// ─── Messages ───────────────────────────────────────────────────────
+/** One addressee. A header without a display name carries `name: ''`. */
+exports.emailMessageAddressSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    address: zod_1.z.string(),
+});
+/**
+ * One attached file. `contentId` is `null` — present, not absent — when the
+ * part had no Content-ID, which is most attachments.
+ */
+exports.emailAttachmentSchema = zod_1.z.object({
+    fileId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    contentType: zod_1.z.string(),
+    size: zod_1.z.number(),
+    contentId: zod_1.z.string().nullable(),
+    isInline: zod_1.z.boolean(),
+});
+exports.emailMessageFlagsSchema = zod_1.z.object({
+    seen: zod_1.z.boolean(),
+    starred: zod_1.z.boolean(),
+    answered: zod_1.z.boolean(),
+    forwarded: zod_1.z.boolean(),
+    draft: zod_1.z.boolean(),
+    pinned: zod_1.z.boolean(),
+});
+/** The AI-extracted card. Every field but `type` may be unknown. */
+exports.emailMessageCardSchema = zod_1.z.object({
+    type: zod_1.z.enum(exports.MESSAGE_CARD_TYPES),
+    data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+    confidence: zod_1.z.number().nullable(),
+    extractedAt: isoInstant.nullable(),
+});
+/** One extracted key/value rendered as a chip. */
+exports.emailMessageHighlightSchema = zod_1.z.object({
+    type: zod_1.z.string(),
+    value: zod_1.z.string(),
+    label: zod_1.z.string(),
+});
+/**
+ * A stored message as every `/email` read returns it.
+ *
+ * `_id` and `id` are the same row id (see the "Wire shapes" note in oxy-api's
+ * email service). `messageId` is the RFC 5322 `Message-ID` header — NOT the row
+ * id — and it is what `inReplyTo` / `references` of a reply must name.
+ */
+exports.emailMessageSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    mailboxId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+    threadId: zod_1.z.string(),
+    from: exports.emailMessageAddressSchema,
+    to: zod_1.z.array(exports.emailMessageAddressSchema),
+    cc: zod_1.z.array(exports.emailMessageAddressSchema),
+    bcc: zod_1.z.array(exports.emailMessageAddressSchema),
+    replyTo: exports.emailMessageAddressSchema.optional(),
+    subject: zod_1.z.string(),
+    attachments: zod_1.z.array(exports.emailAttachmentSchema),
+    flags: exports.emailMessageFlagsSchema,
+    labels: zod_1.z.array(zod_1.z.string()),
+    card: exports.emailMessageCardSchema.optional(),
+    highlights: zod_1.z.array(exports.emailMessageHighlightSchema),
+    encrypted: zod_1.z.boolean(),
+    spamScore: zod_1.z.number().nullable(),
+    spamAction: zod_1.z.string().nullable(),
+    size: zod_1.z.number(),
+    inReplyTo: zod_1.z.string().nullable(),
+    references: zod_1.z.array(zod_1.z.string()),
+    aliasTag: zod_1.z.string().nullable(),
+    snoozedUntil: isoInstant.nullable(),
+    snoozedFromMailbox: zod_1.z.string().nullable(),
+    scheduledAt: isoInstant.nullable(),
+    readReceiptRequested: zod_1.z.boolean(),
+    readReceiptSent: zod_1.z.boolean(),
+    date: isoInstant,
+    receivedAt: isoInstant,
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+    draftRevision: zod_1.z.number().int().min(1),
+    /** Present only on the reads that return bodies (single message, thread). */
+    text: zod_1.z.string().nullable().optional(),
+    html: zod_1.z.string().nullable().optional(),
+    headers: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    senderAvatarPath: zod_1.z.string().nullable().optional(),
+    /** Present only on list reads that walked the thread. */
+    threadCount: zod_1.z.number().int().optional(),
+    threadParticipants: zod_1.z.array(zod_1.z.string()).optional(),
+});
+// ─── Mailboxes and labels ───────────────────────────────────────────
+exports.emailMailboxSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    path: zod_1.z.string(),
+    specialUse: zod_1.z.string().nullable(),
+    retentionDays: zod_1.z.number().int().nullable(),
+    totalMessages: zod_1.z.number().int(),
+    unseenMessages: zod_1.z.number().int(),
+    size: zod_1.z.number(),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+/** A label the user made. */
+exports.emailUserLabelSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    color: zod_1.z.string(),
+    order: zod_1.z.number().int(),
+    system: zod_1.z.literal(false),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+/** One of the product's built-in labels; `_id` is `system:<name>`. */
+exports.emailSystemLabelSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    color: zod_1.z.string(),
+    order: zod_1.z.number().int(),
+    system: zod_1.z.literal(true),
+});
+exports.emailLabelSchema = zod_1.z.discriminatedUnion('system', [exports.emailUserLabelSchema, exports.emailSystemLabelSchema]);
+// ─── Rules, bundles, contacts, outbox ───────────────────────────────
+exports.emailFilterConditionSchema = zod_1.z.object({
+    field: zod_1.z.enum(exports.EMAIL_FILTER_CONDITION_FIELDS),
+    operator: zod_1.z.enum(exports.EMAIL_FILTER_CONDITION_OPERATORS),
+    value: zod_1.z.string(),
+});
+/** `value` is absent for the actions that take none. */
+exports.emailFilterActionSchema = zod_1.z.object({
+    type: zod_1.z.enum(exports.EMAIL_FILTER_ACTION_TYPES),
+    value: zod_1.z.string().optional(),
+});
+exports.emailFilterSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    enabled: zod_1.z.boolean(),
+    matchAll: zod_1.z.boolean(),
+    order: zod_1.z.number().int(),
+    conditions: zod_1.z.array(exports.emailFilterConditionSchema),
+    actions: zod_1.z.array(exports.emailFilterActionSchema),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+exports.emailBundleSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    icon: zod_1.z.string(),
+    color: zod_1.z.string(),
+    matchLabels: zod_1.z.array(zod_1.z.string()),
+    enabled: zod_1.z.boolean(),
+    collapsed: zod_1.z.boolean(),
+    order: zod_1.z.number().int(),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+/** `GET /email/messages?bundled=true` — the inbox split into primary and bundles. */
+exports.emailBundledInboxSchema = zod_1.z.object({
+    primary: zod_1.z.array(exports.emailMessageSchema),
+    bundles: zod_1.z.array(zod_1.z.object({
+        bundle: exports.emailBundleSchema,
+        messages: zod_1.z.array(exports.emailMessageSchema),
+        unreadCount: zod_1.z.number().int(),
+    })),
+    total: zod_1.z.number().int(),
+});
+/** An address-book entry. `company` and `notes` are `null` when unset. */
+exports.emailContactSchema = zod_1.z.object({
+    _id: zod_1.z.string(),
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string(),
+    company: zod_1.z.string().nullable(),
+    notes: zod_1.z.string().nullable(),
+    starred: zod_1.z.boolean(),
+    autoCollected: zod_1.z.boolean(),
+    lastContactedAt: isoInstant.nullable(),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+/**
+ * One durable outbound delivery. `terminal` means no further attempt will
+ * happen on its own — present that differently from "still trying".
+ */
+exports.emailOutboxSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+    status: zod_1.z.enum(exports.EMAIL_OUTBOX_STATUSES),
+    attempts: zod_1.z.number().int(),
+    maxAttempts: zod_1.z.number().int(),
+    terminal: zod_1.z.boolean(),
+    nextAttemptAt: isoInstant,
+    lastError: zod_1.z.string().nullable(),
+    sentAt: isoInstant.nullable(),
+    createdAt: isoInstant,
+    updatedAt: isoInstant,
+});
+// ─── Replies ────────────────────────────────────────────────────────
+/**
+ * One RFC 5322 `msg-id`: `<left@right>`, no whitespace, no nested brackets.
+ *
+ * `In-Reply-To` and `References` carry these and nothing else. A reply that
+ * names a database row id instead (`01a0…` or `<01a0…>`) breaks threading for
+ * every recipient — it happened, which is why it is refused at the edge.
+ */
+exports.RFC_MESSAGE_ID_PATTERN = /^<[^<>\s]+@[^<>\s]+>$/;
+exports.rfcMessageIdSchema = zod_1.z
+    .string()
+    .trim()
+    .regex(exports.RFC_MESSAGE_ID_PATTERN, 'Must be an RFC 5322 Message-ID such as <id@host>');

package/dist/cjs/index.js

@@ -702,3 +702,4 @@ __exportStar(require("./externalIdentity"), exports);
 __exportStar(require("./linkedAccounts"), exports);
 __exportStar(require("./federationInstanceFetch"), exports);
 __exportStar(require("./notifications"), exports);
+__exportStar(require("./email/messages"), exports);