evo360-types 1.3.709 → 1.3.711

package/dist/apps/evo-notifications/zod-schemas.d.ts

@@ -1021,6 +1021,61 @@ export declare const zNotificationAttachmentSchema: z.ZodObject<{
     content_type: z.ZodString;
     content_base64: z.ZodString;
 }, z.ZodTypeAny, "passthrough">>;
+export declare const NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT = 10;
+export declare const NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES: number;
+/** Inline (base64) continua limitado a 1 por mensagem: ele vive no doc da task e da mensagem. */
+export declare const NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT = 1;
+export declare const zNotificationAttachmentRefSchema: z.ZodObject<{
+    filename: z.ZodString;
+    content_type: z.ZodString;
+    size_bytes: z.ZodOptional<z.ZodNumber>;
+    gcs_uri: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    filename: string;
+    gcs_uri: string;
+    content_type: string;
+    size_bytes?: number | undefined;
+}, {
+    filename: string;
+    gcs_uri: string;
+    content_type: string;
+    size_bytes?: number | undefined;
+}>;
+/** Item de `attachments[]` do envio: inline legado OU referência (`gcs_uri`). */
+export declare const zNotificationAttachmentInputSchema: z.ZodUnion<[z.ZodObject<{
+    filename: z.ZodString;
+    content_type: z.ZodString;
+    size_bytes: z.ZodOptional<z.ZodNumber>;
+    gcs_uri: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    filename: string;
+    gcs_uri: string;
+    content_type: string;
+    size_bytes?: number | undefined;
+}, {
+    filename: string;
+    gcs_uri: string;
+    content_type: string;
+    size_bytes?: number | undefined;
+}>, z.ZodObject<{
+    filename: z.ZodString;
+    content_type: z.ZodString;
+    content_base64: z.ZodString;
+} & {
+    gcs_uri: z.ZodOptional<z.ZodUndefined>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    filename: z.ZodString;
+    content_type: z.ZodString;
+    content_base64: z.ZodString;
+} & {
+    gcs_uri: z.ZodOptional<z.ZodUndefined>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    filename: z.ZodString;
+    content_type: z.ZodString;
+    content_base64: z.ZodString;
+} & {
+    gcs_uri: z.ZodOptional<z.ZodUndefined>;
+}, z.ZodTypeAny, "passthrough">>]>;
 export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
     tenant: z.ZodString;
     kind: z.ZodLiteral<"notification.send">;
@@ -1245,19 +1300,40 @@ export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
         expires_at: z.ZodOptional<z.ZodDate>;
         url_secret: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">>;
-    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        filename: z.ZodString;
+        content_type: z.ZodString;
+        size_bytes: z.ZodOptional<z.ZodNumber>;
+        gcs_uri: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }>, z.ZodObject<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     tenant: z.ZodString;
     kind: z.ZodLiteral<"notification.send">;
@@ -1482,19 +1558,40 @@ export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
         expires_at: z.ZodOptional<z.ZodDate>;
         url_secret: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">>;
-    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        filename: z.ZodString;
+        content_type: z.ZodString;
+        size_bytes: z.ZodOptional<z.ZodNumber>;
+        gcs_uri: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }>, z.ZodObject<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     tenant: z.ZodString;
     kind: z.ZodLiteral<"notification.send">;
@@ -1719,19 +1816,40 @@ export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
         expires_at: z.ZodOptional<z.ZodDate>;
         url_secret: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">>;
-    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        filename: z.ZodString;
+        content_type: z.ZodString;
+        size_bytes: z.ZodOptional<z.ZodNumber>;
+        gcs_uri: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }>, z.ZodObject<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">>;
 }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
     tenant: z.ZodString;
     kind: z.ZodLiteral<"notification.send">;
@@ -1956,19 +2074,40 @@ export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
         expires_at: z.ZodOptional<z.ZodDate>;
         url_secret: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">>;
-    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        filename: z.ZodString;
+        content_type: z.ZodString;
+        size_bytes: z.ZodOptional<z.ZodNumber>;
+        gcs_uri: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }>, z.ZodObject<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     tenant: z.ZodString;
     kind: z.ZodLiteral<"notification.send">;
@@ -2193,19 +2332,40 @@ export declare const zDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
         expires_at: z.ZodOptional<z.ZodDate>;
         url_secret: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">>;
-    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        filename: z.ZodString;
+        content_type: z.ZodString;
+        size_bytes: z.ZodOptional<z.ZodNumber>;
+        gcs_uri: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }, {
+        filename: string;
+        gcs_uri: string;
+        content_type: string;
+        size_bytes?: number | undefined;
+    }>, z.ZodObject<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         filename: z.ZodString;
         content_type: z.ZodString;
         content_base64: z.ZodString;
-    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    } & {
+        gcs_uri: z.ZodOptional<z.ZodUndefined>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">>;
 }, z.ZodTypeAny, "passthrough">>;
 export declare const zNexusDirectSendPayloadSchema: z.ZodEffects<z.ZodObject<{
     kind: z.ZodLiteral<"notification.send">;

package/dist/apps/evo-notifications/zod-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zNexusDirectSendPayloadSchema = exports.zDirectSendPayloadSchema = exports.zNotificationAttachmentSchema = exports.NOTIFICATION_ATTACHMENT_MAX_BASE64_BYTES = exports.zNotificationDirectSendSchema = exports.zNotificationLogSchema = exports.zNotificationAttemptSchema = exports.zNotificationMessageSchema = exports.zEmailSmtpConfigSchema = exports.EMAIL_ATTACHMENT_TOTAL_MAX_BYTES = exports.zNotificationEmailContentSchema = exports.zNotificationErrorSchema = exports.zNotificationProviderMetaSchema = exports.zNotificationTemplateRefSchema = exports.zNotificationChannelRefSchema = exports.zNotificationRecipientSchema = exports.zNotificationLogLevelSchema = exports.zNotificationRecipientKindSchema = exports.zNotificationAttemptStatusSchema = exports.zNotificationMessageStatusSchema = exports.zNotificationChannelTypeSchema = void 0;
+exports.zNexusDirectSendPayloadSchema = exports.zDirectSendPayloadSchema = exports.zNotificationAttachmentInputSchema = exports.zNotificationAttachmentRefSchema = exports.NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT = exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES = exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT = exports.zNotificationAttachmentSchema = exports.NOTIFICATION_ATTACHMENT_MAX_BASE64_BYTES = exports.zNotificationDirectSendSchema = exports.zNotificationLogSchema = exports.zNotificationAttemptSchema = exports.zNotificationMessageSchema = exports.zEmailSmtpConfigSchema = exports.EMAIL_ATTACHMENT_TOTAL_MAX_BYTES = exports.zNotificationEmailContentSchema = exports.zNotificationErrorSchema = exports.zNotificationProviderMetaSchema = exports.zNotificationTemplateRefSchema = exports.zNotificationChannelRefSchema = exports.zNotificationRecipientSchema = exports.zNotificationLogLevelSchema = exports.zNotificationRecipientKindSchema = exports.zNotificationAttemptStatusSchema = exports.zNotificationMessageStatusSchema = exports.zNotificationChannelTypeSchema = void 0;
 const zod_1 = require("zod");
 const zod_schemas_1 = require("../shared/zod-schemas");
 const zod_schemas_2 = require("../evo-task/zod-schemas");
@@ -186,6 +186,37 @@ exports.zNotificationAttachmentSchema = zod_1.z
     content_base64: zod_1.z.string().min(1).max(exports.NOTIFICATION_ATTACHMENT_MAX_BASE64_BYTES),
 })
     .passthrough();
+// ---- feat-254 B1: anexo de e-mail por referência (gcs_uri) ----
+//
+// O front sobe o arquivo pelo `POST /media/upload` do hub-waba (mesmo caminho
+// da mídia do WhatsApp) e manda só a referência. O backend baixa do bucket de
+// mídia do tenant (`gs://<bucket>/tenants/<tenant>/...`), valida tipo/extensão
+// contra a allowlist do e-mail e aplica os limites abaixo. O formato é
+// discriminado pela presença de `gcs_uri`; o inline legado continua valendo.
+exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT = 10;
+exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** Inline (base64) continua limitado a 1 por mensagem: ele vive no doc da task e da mensagem. */
+exports.NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT = 1;
+exports.zNotificationAttachmentRefSchema = zod_1.z
+    .object({
+    filename: zod_1.z.string().min(1).max(200),
+    content_type: zod_1.z.string().min(1).max(200),
+    size_bytes: zod_1.z.number().int().positive().max(exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES).optional(),
+    gcs_uri: zod_1.z
+        .string()
+        .max(1024)
+        .regex(/^gs:\/\/[^/]+\/.+$/u, "gcs_uri deve ter o formato gs://<bucket>/<caminho>"),
+})
+    .strict();
+/** Inline legado sem `gcs_uri`: um item com os dois formatos ao mesmo tempo é ambíguo. */
+const zNotificationAttachmentInlineOnlySchema = exports.zNotificationAttachmentSchema.extend({
+    gcs_uri: zod_1.z.undefined().optional(),
+});
+/** Item de `attachments[]` do envio: inline legado OU referência (`gcs_uri`). */
+exports.zNotificationAttachmentInputSchema = zod_1.z.union([
+    exports.zNotificationAttachmentRefSchema,
+    zNotificationAttachmentInlineOnlySchema,
+]);
 // ---- HTTP direct send (INotificationSendPayload + tenant + externalLinks) ----
 exports.zDirectSendPayloadSchema = zod_1.z
     .object({
@@ -216,11 +247,33 @@ exports.zDirectSendPayloadSchema = zod_1.z
     force_send: zod_1.z.boolean().optional(),
     externalLinks: zod_1.z.array(zod_schemas_2.zExternalLinkSchema).optional(),
     quick_reply_actions: zod_1.z.array(zod_schemas_3.zQuickReplyActionIntentSchema).optional(),
-    // feat-160 R6 / F31 — só o canal de e-mail honra; 1 anexo por mensagem.
-    attachments: zod_1.z.array(exports.zNotificationAttachmentSchema).max(1).optional(),
+    // feat-160 R6 / F31 — só o canal de e-mail honra.
+    // feat-254 B1 — até 10 itens no e-mail (por referência `gcs_uri`); inline
+    // continua no máximo 1 e os demais canais continuam com 1 (ignorado).
+    // Tamanho real e total do canal são validados no backend ao baixar.
+    attachments: zod_1.z
+        .array(exports.zNotificationAttachmentInputSchema)
+        .max(exports.NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT)
+        .optional(),
 })
     .passthrough()
     .superRefine((data, ctx) => {
+    const attachments = data.attachments ?? [];
+    if (data.channel.type !== "email" && attachments.length > 1) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "Só o canal de e-mail aceita mais de um anexo.",
+            path: ["attachments"],
+        });
+    }
+    const inlineCount = attachments.filter((a) => !a.gcs_uri).length;
+    if (inlineCount > exports.NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `No máximo ${exports.NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT} anexo inline (base64); envie os demais por referência (gcs_uri).`,
+            path: ["attachments"],
+        });
+    }
     if (data.channel.type !== "whatsapp")
         return;
     const hasTemplate = Boolean(data.template?.template_id?.trim());

package/dist/apps/evo-notifications/zod-schemas.ts

@@ -207,6 +207,41 @@ export const zNotificationAttachmentSchema = z
   })
   .passthrough();
 
+// ---- feat-254 B1: anexo de e-mail por referência (gcs_uri) ----
+//
+// O front sobe o arquivo pelo `POST /media/upload` do hub-waba (mesmo caminho
+// da mídia do WhatsApp) e manda só a referência. O backend baixa do bucket de
+// mídia do tenant (`gs://<bucket>/tenants/<tenant>/...`), valida tipo/extensão
+// contra a allowlist do e-mail e aplica os limites abaixo. O formato é
+// discriminado pela presença de `gcs_uri`; o inline legado continua valendo.
+export const NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT = 10;
+export const NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** Inline (base64) continua limitado a 1 por mensagem: ele vive no doc da task e da mensagem. */
+export const NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT = 1;
+
+export const zNotificationAttachmentRefSchema = z
+  .object({
+    filename: z.string().min(1).max(200),
+    content_type: z.string().min(1).max(200),
+    size_bytes: z.number().int().positive().max(NOTIFICATION_EMAIL_ATTACHMENT_MAX_BYTES).optional(),
+    gcs_uri: z
+      .string()
+      .max(1024)
+      .regex(/^gs:\/\/[^/]+\/.+$/u, "gcs_uri deve ter o formato gs://<bucket>/<caminho>"),
+  })
+  .strict();
+
+/** Inline legado sem `gcs_uri`: um item com os dois formatos ao mesmo tempo é ambíguo. */
+const zNotificationAttachmentInlineOnlySchema = zNotificationAttachmentSchema.extend({
+  gcs_uri: z.undefined().optional(),
+});
+
+/** Item de `attachments[]` do envio: inline legado OU referência (`gcs_uri`). */
+export const zNotificationAttachmentInputSchema = z.union([
+  zNotificationAttachmentRefSchema,
+  zNotificationAttachmentInlineOnlySchema,
+]);
+
 // ---- HTTP direct send (INotificationSendPayload + tenant + externalLinks) ----
 
 export const zDirectSendPayloadSchema = z
@@ -238,11 +273,33 @@ export const zDirectSendPayloadSchema = z
     force_send: z.boolean().optional(),
     externalLinks: z.array(zExternalLinkSchema).optional(),
     quick_reply_actions: z.array(zQuickReplyActionIntentSchema).optional(),
-    // feat-160 R6 / F31 — só o canal de e-mail honra; 1 anexo por mensagem.
-    attachments: z.array(zNotificationAttachmentSchema).max(1).optional(),
+    // feat-160 R6 / F31 — só o canal de e-mail honra.
+    // feat-254 B1 — até 10 itens no e-mail (por referência `gcs_uri`); inline
+    // continua no máximo 1 e os demais canais continuam com 1 (ignorado).
+    // Tamanho real e total do canal são validados no backend ao baixar.
+    attachments: z
+      .array(zNotificationAttachmentInputSchema)
+      .max(NOTIFICATION_EMAIL_ATTACHMENT_MAX_COUNT)
+      .optional(),
   })
   .passthrough()
   .superRefine((data, ctx) => {
+    const attachments = data.attachments ?? [];
+    if (data.channel.type !== "email" && attachments.length > 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Só o canal de e-mail aceita mais de um anexo.",
+        path: ["attachments"],
+      });
+    }
+    const inlineCount = attachments.filter((a) => !a.gcs_uri).length;
+    if (inlineCount > NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `No máximo ${NOTIFICATION_ATTACHMENT_MAX_INLINE_COUNT} anexo inline (base64); envie os demais por referência (gcs_uri).`,
+        path: ["attachments"],
+      });
+    }
     if (data.channel.type !== "whatsapp") return;
     const hasTemplate = Boolean(data.template?.template_id?.trim());
     /** Texto de sessão sem HSM: campo dedicado ou `variables.text` (string) quando não há template. */

package/dist/types/evo-notifications/index.d.ts

@@ -137,6 +137,28 @@ export interface INotificationAttachment {
     /** Conteúdo em base64. <= 64 KB já codificado. */
     content_base64: string;
 }
+/**
+ * feat-254 B1 — anexo de e-mail por referência a um objeto já no storage.
+ *
+ * O front sobe o arquivo por `POST /media/upload` (hub-waba, devolve
+ * `gcs_uri`) e manda só a referência. O backend aceita apenas
+ * `gs://<bucket de mídia>/tenants/<tenant do envio>/...`, valida tipo/extensão
+ * contra a allowlist do e-mail (a mesma dos anexos recebidos) e aplica
+ * 10 arquivos, 10 MiB por arquivo e o total do canal. Falha vira envio
+ * `failed_final` com `attachment_invalid` ou `attachment_limit_exceeded`.
+ */
+export interface INotificationAttachmentRef {
+    /** Nome apresentado ao destinatário; a extensão precisa casar com `content_type`. */
+    filename: string;
+    /** MIME da allowlist do e-mail. Ex.: 'application/pdf'. */
+    content_type: string;
+    /** Tamanho informado pelo front (o backend confere o tamanho real do objeto). */
+    size_bytes?: number;
+    /** `gs://<bucket>/tenants/<tenant>/...` devolvido pelo upload de mídia. */
+    gcs_uri: string;
+}
+/** Item de `attachments[]` do envio: inline legado OU referência (discriminado por `gcs_uri`). */
+export type INotificationAttachmentInput = INotificationAttachment | INotificationAttachmentRef;
 /** Campos compartilhados pelo conteúdo de email novo e de resposta. */
 interface INotificationEmailContentBase {
     /** Versões textuais do corpo livre. */
@@ -185,9 +207,11 @@ export interface INotificationSendPayload {
     quick_reply_actions?: IQuickReplyActionIntent[];
     /**
      * Anexos (feat-160 R6 / F31). Honrado SÓ no canal de e-mail; ignorado pelos
-     * demais providers. 1 anexo, <= 64 KB em base64 — ver `INotificationAttachment`.
+     * demais providers. Inline: 1 anexo, <= 64 KB em base64 — ver
+     * `INotificationAttachment`. feat-254 B1: no e-mail, até 10 itens por
+     * referência (`INotificationAttachmentRef`, 10 MiB cada, total do canal).
      */
-    attachments?: INotificationAttachment[];
+    attachments?: INotificationAttachmentInput[];
     routine?: {
         id: string;
         version?: number | string;

package/dist/types/evo-notifications/index.ts

@@ -222,6 +222,30 @@ export interface INotificationAttachment {
   content_base64: string;
 }
 
+/**
+ * feat-254 B1 — anexo de e-mail por referência a um objeto já no storage.
+ *
+ * O front sobe o arquivo por `POST /media/upload` (hub-waba, devolve
+ * `gcs_uri`) e manda só a referência. O backend aceita apenas
+ * `gs://<bucket de mídia>/tenants/<tenant do envio>/...`, valida tipo/extensão
+ * contra a allowlist do e-mail (a mesma dos anexos recebidos) e aplica
+ * 10 arquivos, 10 MiB por arquivo e o total do canal. Falha vira envio
+ * `failed_final` com `attachment_invalid` ou `attachment_limit_exceeded`.
+ */
+export interface INotificationAttachmentRef {
+  /** Nome apresentado ao destinatário; a extensão precisa casar com `content_type`. */
+  filename: string;
+  /** MIME da allowlist do e-mail. Ex.: 'application/pdf'. */
+  content_type: string;
+  /** Tamanho informado pelo front (o backend confere o tamanho real do objeto). */
+  size_bytes?: number;
+  /** `gs://<bucket>/tenants/<tenant>/...` devolvido pelo upload de mídia. */
+  gcs_uri: string;
+}
+
+/** Item de `attachments[]` do envio: inline legado OU referência (discriminado por `gcs_uri`). */
+export type INotificationAttachmentInput = INotificationAttachment | INotificationAttachmentRef;
+
 /** Campos compartilhados pelo conteúdo de email novo e de resposta. */
 interface INotificationEmailContentBase {
   /** Versões textuais do corpo livre. */
@@ -285,9 +309,11 @@ export interface INotificationSendPayload {
 
   /**
    * Anexos (feat-160 R6 / F31). Honrado SÓ no canal de e-mail; ignorado pelos
-   * demais providers. 1 anexo, <= 64 KB em base64 — ver `INotificationAttachment`.
+   * demais providers. Inline: 1 anexo, <= 64 KB em base64 — ver
+   * `INotificationAttachment`. feat-254 B1: no e-mail, até 10 itens por
+   * referência (`INotificationAttachmentRef`, 10 MiB cada, total do canal).
    */
-  attachments?: INotificationAttachment[];
+  attachments?: INotificationAttachmentInput[];
 
   // Optional business context
   routine?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.709",
+  "version": "1.3.711",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",