@wildo-ai/external-connectors-models 1.1.5 → 1.1.6

package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts

@@ -0,0 +1,229 @@
+import { z } from "zod";
+/**
+ * One authentication method's result, as a receiving server records it in `Authentication-Results`.
+ *
+ * The union of the results the three methods define, so one vocabulary serves SPF, DKIM and DMARC.
+ * Two members go beyond what a DMARC result can be — `SOFTFAIL` (SPF only) and `POLICY` (DKIM and
+ * SPF) — and are here because mapping them onto a neighbour would record a result the receiver did
+ * not report: a softfail is neither a fail nor neutral.
+ *
+ * spec-cite: RFC 8601 §2.7.1 (DKIM results: none, pass, fail, policy, neutral, temperror, permerror)
+ * and §2.7.2 (SPF results: none, pass, fail, softfail, neutral, temperror, permerror, plus policy
+ * from §2.4); DMARC results per RFC 7489 §11.2 (none, pass, fail, temperror, permerror). Fetched 2026-09-27.
+ */
+export declare enum EmailAuthenticationVerdict {
+    PASS = "pass",
+    FAIL = "fail",
+    SOFTFAIL = "softfail",
+    NEUTRAL = "neutral",
+    NONE = "none",
+    POLICY = "policy",
+    TEMPERROR = "temperror",
+    PERMERROR = "permerror"
+}
+/**
+ * What the receiving provider concluded about a message's origin.
+ *
+ * `dmarcAligned` is kept beside the DMARC verdict rather than folded into it because it is the fact
+ * sender assurance is built on: DMARC authenticates the `From` DOMAIN by requiring that it align with
+ * an identifier SPF or DKIM authenticated. A provider that reports DMARC `pass` has already required
+ * alignment, so for most vendors `dmarcAligned` equals `dmarc === PASS`; it is a separate field so a
+ * vendor that reports the two independently is not forced to invent one from the other.
+ */
+export declare const StandardInboundEmail_AuthenticationSchema: z.ZodObject<{
+    spf: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+    dkim: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+    dmarc: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+    dmarcAligned: z.ZodBoolean;
+}, z.core.$strip>;
+export type StandardInboundEmail_Authentication = z.infer<typeof StandardInboundEmail_AuthenticationSchema>;
+export declare const StandardInboundEmail_AddressSchema: z.ZodObject<{
+    address: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StandardInboundEmail_Address = z.infer<typeof StandardInboundEmail_AddressSchema>;
+/** How a MIME part asks to be presented (`Content-Disposition`). spec-cite: RFC 2183 §2.1 (`inline`) and §2.2 (`attachment`). */
+export declare enum EmailAttachmentDisposition {
+    ATTACHMENT = "attachment",
+    INLINE = "inline"
+}
+/** One attachment as the provider describes it. The bytes are fetched through `openAttachment`, never inlined. */
+export declare const StandardInboundEmail_AttachmentSchema: z.ZodObject<{
+    ref: z.ZodString;
+    filename: z.ZodString;
+    contentType: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    contentId: z.ZodOptional<z.ZodString>;
+    disposition: z.ZodOptional<z.ZodEnum<typeof EmailAttachmentDisposition>>;
+}, z.core.$strip>;
+export type StandardInboundEmail_Attachment = z.infer<typeof StandardInboundEmail_AttachmentSchema>;
+/**
+ * What a provider's notification says, parsed. Small on purpose: a notification tells the engine
+ * THAT a message arrived and where to fetch it, and nothing past this point trusts it for more.
+ */
+export declare const StandardInboundEmail_NotificationSchema: z.ZodObject<{
+    providerMessageId: z.ZodString;
+    receivedFor: z.ZodArray<z.ZodString>;
+    receivedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+export type StandardInboundEmail_Notification = z.infer<typeof StandardInboundEmail_NotificationSchema>;
+/**
+ * One received message, provider-neutral.
+ *
+ * The threading headers are separated out because the engine correlates threads from them;
+ * `headers` carries the rest, for a channel record that chooses to keep an allow-listed subset.
+ */
+export declare const StandardInboundEmail_MessageSchema: z.ZodObject<{
+    providerMessageId: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
+    inReplyTo: z.ZodOptional<z.ZodString>;
+    references: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    from: z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    to: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    cc: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    replyTo: z.ZodOptional<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    receivedFor: z.ZodArray<z.ZodString>;
+    subject: z.ZodDefault<z.ZodString>;
+    textBody: z.ZodOptional<z.ZodString>;
+    htmlBody: z.ZodOptional<z.ZodString>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    authentication: z.ZodObject<{
+        spf: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+        dkim: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+        dmarc: z.ZodEnum<typeof EmailAuthenticationVerdict>;
+        dmarcAligned: z.ZodBoolean;
+    }, z.core.$strip>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        filename: z.ZodString;
+        contentType: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        contentId: z.ZodOptional<z.ZodString>;
+        disposition: z.ZodOptional<z.ZodEnum<typeof EmailAttachmentDisposition>>;
+    }, z.core.$strip>>>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    receivedAt: z.ZodCoercedDate<unknown>;
+    rawRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StandardInboundEmail_Message = z.infer<typeof StandardInboundEmail_MessageSchema>;
+/** The bytes of one attachment. */
+export interface StandardInboundEmail_OpenedAttachment {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+    readonly filename: string;
+}
+/** The original bytes of a message, exactly as the provider serves them. */
+export interface StandardInboundEmail_OpenedRaw {
+    readonly bytes: Uint8Array;
+}
+/** Where a domain stands AT THE PROVIDER — distinct from the organization's own status, which also records ownership proof. */
+export declare enum EmailProviderDomainStatus {
+    /** The provider has not verified the domain's records yet (not started, pending, or a temporary failure it will retry). */
+    PENDING = "pending",
+    /** The provider verified the domain's records. */
+    VERIFIED = "verified",
+    /** The provider gave up verifying the records. */
+    FAILED = "failed"
+}
+/** One DNS record the provider asks to be published. */
+export declare const StandardEmailDomain_DnsRecordSchema: z.ZodObject<{
+    purpose: z.ZodString;
+    type: z.ZodString;
+    name: z.ZodString;
+    value: z.ZodString;
+    priority: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StandardEmailDomain_DnsRecord = z.infer<typeof StandardEmailDomain_DnsRecordSchema>;
+/** A domain as the provider describes it. */
+export declare const StandardEmailDomainSchema: z.ZodObject<{
+    providerDomainId: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<typeof EmailProviderDomainStatus>;
+    sending: z.ZodBoolean;
+    receiving: z.ZodBoolean;
+    records: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        purpose: z.ZodString;
+        type: z.ZodString;
+        name: z.ZodString;
+        value: z.ZodString;
+        priority: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type StandardEmailDomain = z.infer<typeof StandardEmailDomainSchema>;
+/**
+ * What an EMAIL_INBOUND provider implements to host an organization's own domain. Every tenant shares one
+ * provider account, so the ENGINE proves the organization owns the domain before it ever calls `createDomain`.
+ */
+export interface StandardEmailDomains_Interface {
+    createDomain(input: {
+        readonly name: string;
+        readonly sending: boolean;
+        readonly receiving: boolean;
+    }): Promise<StandardEmailDomain>;
+    getDomain(providerDomainId: string): Promise<StandardEmailDomain | null>;
+    /** Start the provider's (asynchronous) verification. */
+    verifyDomain(providerDomainId: string): Promise<void>;
+    deleteDomain(providerDomainId: string): Promise<void>;
+}
+/**
+ * What an EMAIL_INBOUND provider implements. Built by the provider module's adapter factory with the
+ * credential the engine resolved, exactly as a billing adapter is — the module never reads a secret
+ * itself.
+ */
+export interface StandardInboundEmail_Interface {
+    /** Map the verified notification body onto the standard notification. Pure; refuses an unknown shape by throwing. */
+    parseNotification(body: unknown): StandardInboundEmail_Notification;
+    /** Fetch the whole message the notification announced. */
+    fetchMessage(providerMessageId: string): Promise<StandardInboundEmail_Message>;
+    /** Fetch one attachment's bytes, by the `ref` the message listed. */
+    openAttachment(ref: string): Promise<StandardInboundEmail_OpenedAttachment>;
+    /** Fetch the original message bytes, by the message's `rawRef`. */
+    openRaw(rawRef: string): Promise<StandardInboundEmail_OpenedRaw>;
+}
+/**
+ * One request a provider module asks the engine to make on its behalf.
+ *
+ * `path` is appended to the contract's `baseUrl`. A provider that serves bytes from ANOTHER host (a
+ * signed download URL) returns `url` instead, and the engine admits it only against the hosts the
+ * contract declares — a provider-supplied URL is never fetched merely because a provider named it.
+ */
+export type InboundEmailProviderRequest = {
+    readonly path: string;
+    readonly method?: EmailProviderHttpMethod;
+    readonly jsonBody?: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+} | {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/**
+ * The methods a provider's `path` request may use. A `url` request (a signed download link) is always a GET.
+ * Absent means GET.
+ */
+export declare enum EmailProviderHttpMethod {
+    GET = "GET",
+    POST = "POST",
+    PATCH = "PATCH",
+    DELETE = "DELETE"
+}
+/** A provider's HTTP answer, as the engine hands it to the provider's parser. */
+export interface InboundEmailProviderResponseInput {
+    readonly status: number;
+    /** The JSON body, or `undefined` when the answer was not JSON. */
+    readonly body: unknown;
+}
+//# sourceMappingURL=email-inbound.standard-interface.schemas.d.ts.map

package/dist/esm/protocols/email-inbound.standard-interface.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-inbound.standard-interface.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/email-inbound.standard-interface.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/protocols/email-inbound.standard-interface.schemas.js

@@ -0,0 +1,160 @@
+import { z } from "zod";
+// ===============================================================
+// Standard Inbound Email Interface (#1630)
+// --------
+// The canonical shape of a message an EMAIL_INBOUND provider RECEIVED for the application, and the
+// three calls the engine makes on the provider to get it. Provider-agnostic: a vendor's module maps
+// its own notification and message payloads onto these schemas, and nothing past that mapping ever
+// sees a vendor field.
+//
+// There is deliberately NO `verify` here. The notification reaches the application through the
+// provider's `WEBHOOK_ORIGINATOR` endpoint (the `inbound-email` key, capability `EMAIL_INBOUND`), and
+// that endpoint is verified by the ENGINE-owned scheme its `signatureConfig` names (#1596). A
+// provider that verified its own notifications would put the one fail-closed decision of the inbound
+// path in vendor code, where nothing checks it.
+// ===============================================================
+/**
+ * One authentication method's result, as a receiving server records it in `Authentication-Results`.
+ *
+ * The union of the results the three methods define, so one vocabulary serves SPF, DKIM and DMARC.
+ * Two members go beyond what a DMARC result can be — `SOFTFAIL` (SPF only) and `POLICY` (DKIM and
+ * SPF) — and are here because mapping them onto a neighbour would record a result the receiver did
+ * not report: a softfail is neither a fail nor neutral.
+ *
+ * spec-cite: RFC 8601 §2.7.1 (DKIM results: none, pass, fail, policy, neutral, temperror, permerror)
+ * and §2.7.2 (SPF results: none, pass, fail, softfail, neutral, temperror, permerror, plus policy
+ * from §2.4); DMARC results per RFC 7489 §11.2 (none, pass, fail, temperror, permerror). Fetched 2026-09-27.
+ */
+export var EmailAuthenticationVerdict;
+(function (EmailAuthenticationVerdict) {
+    EmailAuthenticationVerdict["PASS"] = "pass";
+    EmailAuthenticationVerdict["FAIL"] = "fail";
+    EmailAuthenticationVerdict["SOFTFAIL"] = "softfail";
+    EmailAuthenticationVerdict["NEUTRAL"] = "neutral";
+    EmailAuthenticationVerdict["NONE"] = "none";
+    EmailAuthenticationVerdict["POLICY"] = "policy";
+    EmailAuthenticationVerdict["TEMPERROR"] = "temperror";
+    EmailAuthenticationVerdict["PERMERROR"] = "permerror";
+})(EmailAuthenticationVerdict || (EmailAuthenticationVerdict = {}));
+/**
+ * What the receiving provider concluded about a message's origin.
+ *
+ * `dmarcAligned` is kept beside the DMARC verdict rather than folded into it because it is the fact
+ * sender assurance is built on: DMARC authenticates the `From` DOMAIN by requiring that it align with
+ * an identifier SPF or DKIM authenticated. A provider that reports DMARC `pass` has already required
+ * alignment, so for most vendors `dmarcAligned` equals `dmarc === PASS`; it is a separate field so a
+ * vendor that reports the two independently is not forced to invent one from the other.
+ */
+export const StandardInboundEmail_AuthenticationSchema = z.object({
+    spf: z.enum(EmailAuthenticationVerdict),
+    dkim: z.enum(EmailAuthenticationVerdict),
+    dmarc: z.enum(EmailAuthenticationVerdict),
+    dmarcAligned: z.boolean(),
+});
+export const StandardInboundEmail_AddressSchema = z.object({
+    address: z.string().min(1),
+    name: z.string().optional(),
+});
+/** How a MIME part asks to be presented (`Content-Disposition`). spec-cite: RFC 2183 §2.1 (`inline`) and §2.2 (`attachment`). */
+export var EmailAttachmentDisposition;
+(function (EmailAttachmentDisposition) {
+    EmailAttachmentDisposition["ATTACHMENT"] = "attachment";
+    EmailAttachmentDisposition["INLINE"] = "inline";
+})(EmailAttachmentDisposition || (EmailAttachmentDisposition = {}));
+/** One attachment as the provider describes it. The bytes are fetched through `openAttachment`, never inlined. */
+export const StandardInboundEmail_AttachmentSchema = z.object({
+    /** Opaque to the engine; handed back to `openAttachment`. */
+    ref: z.string().min(1),
+    filename: z.string(),
+    contentType: z.string(),
+    sizeBytes: z.number().int().nonnegative(),
+    /** The `Content-ID` of an inline part, without angle brackets. */
+    contentId: z.string().optional(),
+    disposition: z.enum(EmailAttachmentDisposition).optional(),
+});
+/**
+ * What a provider's notification says, parsed. Small on purpose: a notification tells the engine
+ * THAT a message arrived and where to fetch it, and nothing past this point trusts it for more.
+ */
+export const StandardInboundEmail_NotificationSchema = z.object({
+    /** The provider's id for the message — what `fetchMessage` takes, and the dedup key of the channel delivery. */
+    providerMessageId: z.string().min(1),
+    /** The addresses the message was delivered FOR (the SMTP envelope recipients), which routing reads. */
+    receivedFor: z.array(z.string().min(1)).min(1),
+    receivedAt: z.coerce.date(),
+});
+/**
+ * One received message, provider-neutral.
+ *
+ * The threading headers are separated out because the engine correlates threads from them;
+ * `headers` carries the rest, for a channel record that chooses to keep an allow-listed subset.
+ */
+export const StandardInboundEmail_MessageSchema = z.object({
+    providerMessageId: z.string().min(1),
+    /** The RFC 5322 `Message-ID`, angle brackets included, or absent when the sender set none. */
+    messageId: z.string().optional(),
+    inReplyTo: z.string().optional(),
+    references: z.array(z.string()).default([]),
+    from: StandardInboundEmail_AddressSchema,
+    to: z.array(StandardInboundEmail_AddressSchema).default([]),
+    cc: z.array(StandardInboundEmail_AddressSchema).default([]),
+    replyTo: StandardInboundEmail_AddressSchema.optional(),
+    receivedFor: z.array(z.string().min(1)).min(1),
+    subject: z.string().default(""),
+    textBody: z.string().optional(),
+    htmlBody: z.string().optional(),
+    headers: z.record(z.string(), z.string()).default({}),
+    authentication: StandardInboundEmail_AuthenticationSchema,
+    attachments: z.array(StandardInboundEmail_AttachmentSchema).default([]),
+    sizeBytes: z.number().int().nonnegative().optional(),
+    receivedAt: z.coerce.date(),
+    /**
+     * Where the ORIGINAL message bytes are, when the provider keeps them (#1600). Opaque to the engine; handed
+     * to `openRaw`. Absent when the provider offers no raw copy — the engine then keeps no raw MIME.
+     */
+    rawRef: z.string().min(1).optional(),
+});
+// ===============================================================
+// Receiving domains (#1600)
+// ===============================================================
+/** Where a domain stands AT THE PROVIDER — distinct from the organization's own status, which also records ownership proof. */
+export var EmailProviderDomainStatus;
+(function (EmailProviderDomainStatus) {
+    /** The provider has not verified the domain's records yet (not started, pending, or a temporary failure it will retry). */
+    EmailProviderDomainStatus["PENDING"] = "pending";
+    /** The provider verified the domain's records. */
+    EmailProviderDomainStatus["VERIFIED"] = "verified";
+    /** The provider gave up verifying the records. */
+    EmailProviderDomainStatus["FAILED"] = "failed";
+})(EmailProviderDomainStatus || (EmailProviderDomainStatus = {}));
+/** One DNS record the provider asks to be published. */
+export const StandardEmailDomain_DnsRecordSchema = z.object({
+    /** What it is for, as the provider names it (DKIM, SPF, MX, Receiving…). */
+    purpose: z.string(),
+    type: z.string(),
+    name: z.string(),
+    value: z.string(),
+    priority: z.number().int().optional(),
+    status: z.string().optional(),
+});
+/** A domain as the provider describes it. */
+export const StandardEmailDomainSchema = z.object({
+    providerDomainId: z.string().min(1),
+    name: z.string().min(1),
+    status: z.enum(EmailProviderDomainStatus),
+    sending: z.boolean(),
+    receiving: z.boolean(),
+    records: z.array(StandardEmailDomain_DnsRecordSchema).default([]),
+});
+/**
+ * The methods a provider's `path` request may use. A `url` request (a signed download link) is always a GET.
+ * Absent means GET.
+ */
+export var EmailProviderHttpMethod;
+(function (EmailProviderHttpMethod) {
+    EmailProviderHttpMethod["GET"] = "GET";
+    EmailProviderHttpMethod["POST"] = "POST";
+    EmailProviderHttpMethod["PATCH"] = "PATCH";
+    EmailProviderHttpMethod["DELETE"] = "DELETE";
+})(EmailProviderHttpMethod || (EmailProviderHttpMethod = {}));
+//# sourceMappingURL=email-inbound.standard-interface.schemas.js.map

package/dist/esm/protocols/email-inbound.standard-interface.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-inbound.standard-interface.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/email-inbound.standard-interface.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\n// ===============================================================\n// Standard Inbound Email Interface (#1630)\n// --------\n// The canonical shape of a message an EMAIL_INBOUND provider RECEIVED for the application, and the\n// three calls the engine makes on the provider to get it. Provider-agnostic: a vendor's module maps\n// its own notification and message payloads onto these schemas, and nothing past that mapping ever\n// sees a vendor field.\n//\n// There is deliberately NO `verify` here. The notification reaches the application through the\n// provider's `WEBHOOK_ORIGINATOR` endpoint (the `inbound-email` key, capability `EMAIL_INBOUND`), and\n// that endpoint is verified by the ENGINE-owned scheme its `signatureConfig` names (#1596). A\n// provider that verified its own notifications would put the one fail-closed decision of the inbound\n// path in vendor code, where nothing checks it.\n// ===============================================================\n\n/**\n * One authentication method's result, as a receiving server records it in `Authentication-Results`.\n *\n * The union of the results the three methods define, so one vocabulary serves SPF, DKIM and DMARC.\n * Two members go beyond what a DMARC result can be — `SOFTFAIL` (SPF only) and `POLICY` (DKIM and\n * SPF) — and are here because mapping them onto a neighbour would record a result the receiver did\n * not report: a softfail is neither a fail nor neutral.\n *\n * spec-cite: RFC 8601 §2.7.1 (DKIM results: none, pass, fail, policy, neutral, temperror, permerror)\n * and §2.7.2 (SPF results: none, pass, fail, softfail, neutral, temperror, permerror, plus policy\n * from §2.4); DMARC results per RFC 7489 §11.2 (none, pass, fail, temperror, permerror). Fetched 2026-09-27.\n */\nexport enum EmailAuthenticationVerdict {\n  PASS = \"pass\",\n  FAIL = \"fail\",\n  SOFTFAIL = \"softfail\",\n  NEUTRAL = \"neutral\",\n  NONE = \"none\",\n  POLICY = \"policy\",\n  TEMPERROR = \"temperror\",\n  PERMERROR = \"permerror\",\n}\n\n/**\n * What the receiving provider concluded about a message's origin.\n *\n * `dmarcAligned` is kept beside the DMARC verdict rather than folded into it because it is the fact\n * sender assurance is built on: DMARC authenticates the `From` DOMAIN by requiring that it align with\n * an identifier SPF or DKIM authenticated. A provider that reports DMARC `pass` has already required\n * alignment, so for most vendors `dmarcAligned` equals `dmarc === PASS`; it is a separate field so a\n * vendor that reports the two independently is not forced to invent one from the other.\n */\nexport const StandardInboundEmail_AuthenticationSchema = z.object({\n  spf: z.enum(EmailAuthenticationVerdict),\n  dkim: z.enum(EmailAuthenticationVerdict),\n  dmarc: z.enum(EmailAuthenticationVerdict),\n  dmarcAligned: z.boolean(),\n});\n\nexport type StandardInboundEmail_Authentication = z.infer<typeof StandardInboundEmail_AuthenticationSchema>;\n\nexport const StandardInboundEmail_AddressSchema = z.object({\n  address: z.string().min(1),\n  name: z.string().optional(),\n});\n\nexport type StandardInboundEmail_Address = z.infer<typeof StandardInboundEmail_AddressSchema>;\n\n/** How a MIME part asks to be presented (`Content-Disposition`). spec-cite: RFC 2183 §2.1 (`inline`) and §2.2 (`attachment`). */\nexport enum EmailAttachmentDisposition {\n  ATTACHMENT = \"attachment\",\n  INLINE = \"inline\",\n}\n\n/** One attachment as the provider describes it. The bytes are fetched through `openAttachment`, never inlined. */\nexport const StandardInboundEmail_AttachmentSchema = z.object({\n  /** Opaque to the engine; handed back to `openAttachment`. */\n  ref: z.string().min(1),\n  filename: z.string(),\n  contentType: z.string(),\n  sizeBytes: z.number().int().nonnegative(),\n  /** The `Content-ID` of an inline part, without angle brackets. */\n  contentId: z.string().optional(),\n  disposition: z.enum(EmailAttachmentDisposition).optional(),\n});\n\nexport type StandardInboundEmail_Attachment = z.infer<typeof StandardInboundEmail_AttachmentSchema>;\n\n/**\n * What a provider's notification says, parsed. Small on purpose: a notification tells the engine\n * THAT a message arrived and where to fetch it, and nothing past this point trusts it for more.\n */\nexport const StandardInboundEmail_NotificationSchema = z.object({\n  /** The provider's id for the message — what `fetchMessage` takes, and the dedup key of the channel delivery. */\n  providerMessageId: z.string().min(1),\n  /** The addresses the message was delivered FOR (the SMTP envelope recipients), which routing reads. */\n  receivedFor: z.array(z.string().min(1)).min(1),\n  receivedAt: z.coerce.date(),\n});\n\nexport type StandardInboundEmail_Notification = z.infer<typeof StandardInboundEmail_NotificationSchema>;\n\n/**\n * One received message, provider-neutral.\n *\n * The threading headers are separated out because the engine correlates threads from them;\n * `headers` carries the rest, for a channel record that chooses to keep an allow-listed subset.\n */\nexport const StandardInboundEmail_MessageSchema = z.object({\n  providerMessageId: z.string().min(1),\n  /** The RFC 5322 `Message-ID`, angle brackets included, or absent when the sender set none. */\n  messageId: z.string().optional(),\n  inReplyTo: z.string().optional(),\n  references: z.array(z.string()).default([]),\n  from: StandardInboundEmail_AddressSchema,\n  to: z.array(StandardInboundEmail_AddressSchema).default([]),\n  cc: z.array(StandardInboundEmail_AddressSchema).default([]),\n  replyTo: StandardInboundEmail_AddressSchema.optional(),\n  receivedFor: z.array(z.string().min(1)).min(1),\n  subject: z.string().default(\"\"),\n  textBody: z.string().optional(),\n  htmlBody: z.string().optional(),\n  headers: z.record(z.string(), z.string()).default({}),\n  authentication: StandardInboundEmail_AuthenticationSchema,\n  attachments: z.array(StandardInboundEmail_AttachmentSchema).default([]),\n  sizeBytes: z.number().int().nonnegative().optional(),\n  receivedAt: z.coerce.date(),\n  /**\n   * Where the ORIGINAL message bytes are, when the provider keeps them (#1600). Opaque to the engine; handed\n   * to `openRaw`. Absent when the provider offers no raw copy — the engine then keeps no raw MIME.\n   */\n  rawRef: z.string().min(1).optional(),\n});\n\nexport type StandardInboundEmail_Message = z.infer<typeof StandardInboundEmail_MessageSchema>;\n\n/** The bytes of one attachment. */\nexport interface StandardInboundEmail_OpenedAttachment {\n  readonly bytes: Uint8Array;\n  readonly contentType: string;\n  readonly filename: string;\n}\n\n/** The original bytes of a message, exactly as the provider serves them. */\nexport interface StandardInboundEmail_OpenedRaw {\n  readonly bytes: Uint8Array;\n}\n\n// ===============================================================\n// Receiving domains (#1600)\n// ===============================================================\n\n/** Where a domain stands AT THE PROVIDER — distinct from the organization's own status, which also records ownership proof. */\nexport enum EmailProviderDomainStatus {\n  /** The provider has not verified the domain's records yet (not started, pending, or a temporary failure it will retry). */\n  PENDING = \"pending\",\n  /** The provider verified the domain's records. */\n  VERIFIED = \"verified\",\n  /** The provider gave up verifying the records. */\n  FAILED = \"failed\",\n}\n\n/** One DNS record the provider asks to be published. */\nexport const StandardEmailDomain_DnsRecordSchema = z.object({\n  /** What it is for, as the provider names it (DKIM, SPF, MX, Receiving…). */\n  purpose: z.string(),\n  type: z.string(),\n  name: z.string(),\n  value: z.string(),\n  priority: z.number().int().optional(),\n  status: z.string().optional(),\n});\n\nexport type StandardEmailDomain_DnsRecord = z.infer<typeof StandardEmailDomain_DnsRecordSchema>;\n\n/** A domain as the provider describes it. */\nexport const StandardEmailDomainSchema = z.object({\n  providerDomainId: z.string().min(1),\n  name: z.string().min(1),\n  status: z.enum(EmailProviderDomainStatus),\n  sending: z.boolean(),\n  receiving: z.boolean(),\n  records: z.array(StandardEmailDomain_DnsRecordSchema).default([]),\n});\n\nexport type StandardEmailDomain = z.infer<typeof StandardEmailDomainSchema>;\n\n/**\n * What an EMAIL_INBOUND provider implements to host an organization's own domain. Every tenant shares one\n * provider account, so the ENGINE proves the organization owns the domain before it ever calls `createDomain`.\n */\nexport interface StandardEmailDomains_Interface {\n  createDomain(input: { readonly name: string; readonly sending: boolean; readonly receiving: boolean }): Promise<StandardEmailDomain>;\n  getDomain(providerDomainId: string): Promise<StandardEmailDomain | null>;\n  /** Start the provider's (asynchronous) verification. */\n  verifyDomain(providerDomainId: string): Promise<void>;\n  deleteDomain(providerDomainId: string): Promise<void>;\n}\n\n/**\n * What an EMAIL_INBOUND provider implements. Built by the provider module's adapter factory with the\n * credential the engine resolved, exactly as a billing adapter is — the module never reads a secret\n * itself.\n */\nexport interface StandardInboundEmail_Interface {\n  /** Map the verified notification body onto the standard notification. Pure; refuses an unknown shape by throwing. */\n  parseNotification(body: unknown): StandardInboundEmail_Notification;\n  /** Fetch the whole message the notification announced. */\n  fetchMessage(providerMessageId: string): Promise<StandardInboundEmail_Message>;\n  /** Fetch one attachment's bytes, by the `ref` the message listed. */\n  openAttachment(ref: string): Promise<StandardInboundEmail_OpenedAttachment>;\n  /** Fetch the original message bytes, by the message's `rawRef`. */\n  openRaw(rawRef: string): Promise<StandardInboundEmail_OpenedRaw>;\n}\n\n// ===============================================================\n// What a provider module DECLARES (pure functions; the engine owns the transport)\n// ===============================================================\n\n/**\n * One request a provider module asks the engine to make on its behalf.\n *\n * `path` is appended to the contract's `baseUrl`. A provider that serves bytes from ANOTHER host (a\n * signed download URL) returns `url` instead, and the engine admits it only against the hosts the\n * contract declares — a provider-supplied URL is never fetched merely because a provider named it.\n */\nexport type InboundEmailProviderRequest =\n  | { readonly path: string; readonly method?: EmailProviderHttpMethod; readonly jsonBody?: unknown; readonly headers?: Readonly<Record<string, string>> }\n  | { readonly url: string; readonly headers?: Readonly<Record<string, string>> };\n\n/**\n * The methods a provider's `path` request may use. A `url` request (a signed download link) is always a GET.\n * Absent means GET.\n */\nexport enum EmailProviderHttpMethod {\n  GET = \"GET\",\n  POST = \"POST\",\n  PATCH = \"PATCH\",\n  DELETE = \"DELETE\",\n}\n\n/** A provider's HTTP answer, as the engine hands it to the provider's parser. */\nexport interface InboundEmailProviderResponseInput {\n  readonly status: number;\n  /** The JSON body, or `undefined` when the answer was not JSON. */\n  readonly body: unknown;\n}\n"]}

package/dist/esm/protocols/file-storage.standard-interface.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Standard File Storage Adapter Interface (#1674)
+ * --------
+ * The contract a PROVIDER implements so a file storage whose bytes live at a vendor — a person's
+ * OneDrive, an organization's SharePoint library, a Dropbox folder — can be contributed by a package
+ * instead of being wired into the engine.
+ *
+ * ## Why it lives here, below the backend library
+ *
+ * The engine's storage contract (`IFileStorageProvider` in `@wildo-ai/saas-backend-lib`) takes the
+ * backend library's `ExecutionContext`. A provider package depends on
+ * `@wildo-ai/external-connectors-private`, which `saas-backend-lib` itself depends on, so a package
+ * could not implement that interface without a dependency edge pointing the wrong way — the same
+ * constraint billing met in #336. This contract sits in `@wildo-ai/external-connectors-models`, below
+ * both sides, and deliberately knows nothing about execution contexts, tenants or stored credentials:
+ * an adapter receives the ACCESS the engine resolved for one call and the file identifiers, and does
+ * the vendor's half of the work.
+ *
+ * The engine wraps every contributed adapter in its own `IFileStorageProvider`, which keeps everything
+ * an adapter must not decide for itself: which grant a file is read through (the person who linked or
+ * uploaded it, or the file's organization), the recorded credential use naming the connection and the
+ * contributing package, input validation and size limits, and the mapping of a vendor failure onto the
+ * application's error vocabulary.
+ *
+ * ## What it rejects, on purpose
+ *
+ * Supersedes #336's decision D10 ("file storage stays a separate registry, revisited when a storage
+ * vendor package is actually wanted"): Microsoft storage is now wanted from a package. The rejected
+ * alternative was #336's billing pattern — a registry of ENGINE-shipped adapters keyed by a declared
+ * name — because it keeps the implementation in the engine and so can never admit a package's adapter.
+ *
+ * The storage VOCABULARY stays closed. An adapter serves a member of `FileStorageAccepted` the engine
+ * already declares; it never adds a member. A declared member nothing serves remains a startup refusal.
+ */
+import type { FileStorageAccepted } from '@wildo-ai/zod-decorators';
+import type { ExternalProvider_Connection_OwnerScope } from '../core/security.external-connectors-models.schemas';
+/** @wildo_source:part:start external-connectors.models.file-storage-adapter facet:kind:api facet:audience:app-developer */
+/**
+ * WHOSE grant a file in this storage is read and written through. A subset of the connection owner
+ * vocabulary, not a new one: a vendor storage is reachable through a person's connection or an
+ * organization's, never through the application's own account (the application's own bytes live in the
+ * framework's storages).
+ *
+ * - `USER` — the person who LINKED or UPLOADED the file (the row's `uploadedBy`). Another reader still
+ *   reads it: the application authorizes the ROW, and the storage reads the BYTES as that person.
+ * - `ORGANIZATION` — the organization the file belongs to (the row's `organizationId`, which only an
+ *   organization-scoped file carries).
+ *
+ * Both are already on the file row, which is what lets erasure and retention reach a file held in
+ * someone's own drive.
+ */
+export type ProviderFileStorageGrantOwner = ExternalProvider_Connection_OwnerScope.USER | ExternalProvider_Connection_OwnerScope.ORGANIZATION;
+/** What removing a file's row does to the bytes at the vendor. */
+export declare enum ProviderFileStorageDeleteBehavior {
+    /** The bytes are the application's, kept at the vendor on its behalf: `delete` removes them. */
+    REMOVES_BYTES = "REMOVES_BYTES",
+    /**
+     * The bytes are the owner's own document (a person's file they linked): `delete` forgets the
+     * reference and never calls the vendor. Deleting someone's document because an application row went
+     * away is an irreversible act that needs a deliberate door of its own.
+     */
+    FORGETS_REFERENCE = "FORGETS_REFERENCE"
+}
+/** Why an adapter could not do what it was asked. The engine maps each to its own error type. */
+export declare enum ProviderFileStorageFailureKind {
+    /** The vendor knows no such file for this grant. */
+    NOT_FOUND = "NOT_FOUND",
+    /** The vendor refused the grant for this file (revoked, insufficient scope, not shared with the owner). */
+    ACCESS_DENIED = "ACCESS_DENIED",
+    /** The reference cannot be a file here (a folder, a vendor-native document with no bytes, a malformed id). */
+    INVALID_REFERENCE = "INVALID_REFERENCE",
+    /** The vendor failed or could not be reached. */
+    VENDOR_FAILURE = "VENDOR_FAILURE"
+}
+/**
+ * The failure an adapter throws. Anything else an adapter throws is treated as `VENDOR_FAILURE`, so a
+ * vendor SDK's own error never reaches a person as an unexplained 500.
+ */
+export declare class ProviderFileStorageFailure extends Error {
+    readonly kind: ProviderFileStorageFailureKind;
+    /**
+     * The HTTP status the vendor answered with, when it answered. Recorded on the outbound record, so a reviewer
+     * can tell a vendor that refused from one that never answered. Leave it out when nothing came back.
+     */
+    readonly status?: number;
+    constructor(kind: ProviderFileStorageFailureKind, message: string, options?: {
+        readonly status?: number;
+    });
+}
+/**
+ * The access the engine resolved for ONE call: the delegated token of the grant the file lives under.
+ * Resolved, recorded as a credential use and handed over per call, so an adapter never holds a
+ * credential between calls and never chooses whose it is.
+ */
+export interface ProviderFileStorageAccess {
+    readonly accessToken: string;
+}
+/** What the vendor says about one file. */
+export interface ProviderFileStorageDescription {
+    /** The vendor's display name for the file. */
+    readonly name: string;
+    readonly contentType: string;
+    /** Size in bytes. A vendor-native document with no bytes cannot be described: throw `INVALID_REFERENCE`. */
+    readonly size: number;
+    readonly etag?: string;
+    readonly lastModified?: Date;
+}
+export interface ProviderFileStorageUploadRequest {
+    readonly access: ProviderFileStorageAccess;
+    /** The application's id for the file — stable, never shown to a person. */
+    readonly fileId: string;
+    /** The name to give the file at the vendor. */
+    readonly fileName: string;
+    readonly contentType: string;
+    /** The size the engine already validated against the application's limit. */
+    readonly size: number;
+    /** The bytes, streamed. Already bounded by the engine. */
+    readonly body: AsyncIterable<Uint8Array>;
+}
+export interface ProviderFileStorageReferenceRequest {
+    readonly access: ProviderFileStorageAccess;
+    /** The vendor's id for the file, as `upload` returned it or a picker linked it. */
+    readonly storageRef: string;
+}
+export interface ProviderFileStorageDownload {
+    readonly body: AsyncIterable<Uint8Array>;
+    readonly contentType: string;
+    readonly size: number;
+    readonly etag?: string;
+    readonly lastModified?: Date;
+}
+/**
+ * A file storage a provider contributes. Declared on the provider's backend module
+ * (`fileStorageAdapters`); the grant it spends is ITS OWN provider's connection — a module cannot
+ * point an adapter at another provider's grant — so a package whose ref belongs to a declared shared
+ * connection (`microsoft`, #1725) stores through that one connection.
+ *
+ * @example
+ * ```ts
+ * export const oneDriveStorage: ProviderFileStorageAdapter = {
+ *   storage: FileStorageAccepted.ONEDRIVE,
+ *   grantOwner: ExternalProvider_Connection_OwnerScope.USER,
+ *   deleteBehavior: ProviderFileStorageDeleteBehavior.FORGETS_REFERENCE,
+ *   acceptsRemoteReferences: true,
+ *   upload: async ({ access, fileName, body }) => ({ storageRef: await putDriveItem(access, fileName, body) }),
+ *   download: async ({ access, storageRef }) => getDriveItemContent(access, storageRef),
+ *   describe: async ({ access, storageRef }) => getDriveItem(access, storageRef),
+ *   delete: async () => undefined,
+ * };
+ * ```
+ */
+export interface ProviderFileStorageAdapter {
+    /**
+     * The declared storage member this adapter serves. Exactly one adapter may serve a member.
+     *
+     * Typed as the member's VALUE (`'onedrive'`) rather than the `@wildo-ai/zod-decorators` enum, so a provider package
+     * names it through the vocabulary it can already reach — `FileStorageAccepted.ONEDRIVE` from `@wildo-ai/saas-models`,
+     * whose members are held equal to the enum's — without taking a dependency on the decorator package. The set stays
+     * closed: the engine refuses a value that is not a member when it admits the adapter.
+     */
+    readonly storage: `${FileStorageAccepted}`;
+    readonly grantOwner: ProviderFileStorageGrantOwner;
+    readonly deleteBehavior: ProviderFileStorageDeleteBehavior;
+    /**
+     * Whether a person may LINK a file that already exists at the vendor (a picker's
+     * `REMOTE_REFERENCE`). When true, the engine describes the reference through the linker's grant
+     * before a row is created — which is also the proof the reference is real and reachable by them.
+     */
+    readonly acceptsRemoteReferences: boolean;
+    upload(request: ProviderFileStorageUploadRequest): Promise<{
+        readonly storageRef: string;
+    }>;
+    download(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDownload>;
+    describe(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDescription>;
+    /** Called only when `deleteBehavior` is `REMOVES_BYTES`. */
+    delete(request: ProviderFileStorageReferenceRequest): Promise<void>;
+}
+/** @wildo_source:part:end external-connectors.models.file-storage-adapter */
+//# sourceMappingURL=file-storage.standard-interface.d.ts.map

package/dist/esm/protocols/file-storage.standard-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage.standard-interface.d.ts","sourceRoot":"","sources":["../../../../src/protocols/file-storage.standard-interface.ts"],"names":[],"mappings":"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"}