feat(upload): silent-by-default, opt-in notify.recipients/notify.sender

Closes #40.

Today `sealed.upload` always triggered Cryptify's per-recipient
notification email — there was no client-side opt-out. The
existing `notify` block only customized mail content; the docstring
even claimed `notify` *enabled* the recipient mail, which was the
opposite of reality. That made the upload pipeline unsuitable for any
caller delivering the encrypted payload through another channel
(e.g. an email add-in delivering the message from the user's own
mailbox), where the Cryptify mail arrived as a duplicate.

Redesigns `UploadOptions['notify']` to a symmetric, silent-by-default
shape:

```ts
sealed.upload({
  notify: {
    recipients: true,      // opt-in (default false)
    sender: true,          // opt-in (default false; was confirmToSender)
    message: 'See you...', // unencrypted body for any mails sent
    language: 'EN',
  },
});
```

`pg.email.createEnvelope` forwards `notify` to the underlying upload
for tier 2/3 envelopes. The SDK now always sends the wire-level
`notifyRecipients` field with explicit `false` when omitted, so older
Cryptify deployments (which default `notifyRecipients` to true) get
overridden to the SDK's silent-by-default semantics.

Coordinated server-side change: encryption4all/cryptify#135.

BREAKING: `notify.confirmToSender` renamed to `notify.sender` for
symmetry with `notify.recipients`. Per upstream guidance there are
no production consumers of `@e4a/pg-js` yet, so we ship the cleaner
name rather than alias the old one. Downstream consumers (the
website fileshare, the sveltekit example) need to switch from
`confirmToSender: true` to `recipients: true, sender: true` to keep
emitting both mails — those updates land separately.

Also fixes the misleading `Sealed.upload` docstring.

Author: rubenhensen

src/api/cryptify.ts

@@ -9,7 +9,16 @@ export interface InitUploadOptions {
   recipient: string;
   mailContent?: string;
   mailLang?: 'EN' | 'NL';
+  /** Send a confirmation email to the sender. Default false. Maps to
+   *  the wire-level `confirm` field. */
   confirm?: boolean;
+  /** Send a notification email to each recipient. Default false in the
+   *  SDK (overrides Cryptify's server-side default of true for clients
+   *  that don't send the field, so callers get a silent upload by
+   *  default). Requires cryptify ≥ the release that added the
+   *  `notifyRecipients` field; older servers ignore it and continue to
+   *  email recipients. */
+  notifyRecipients?: boolean;
   signal?: AbortSignal;
 }
 
@@ -27,6 +36,10 @@ export async function initUpload(
       recipient: options.recipient,
       mailContent: options.mailContent ?? '',
       mailLang: options.mailLang ?? 'EN',
+      // Always send the field so older Cryptify deployments (default
+      // notifyRecipients: true) get explicitly overridden to the SDK's
+      // silent-by-default semantics.
+      notifyRecipients: options.notifyRecipients ?? false,
     }),
   });
 

src/crypto/encrypt.ts

@@ -21,9 +21,12 @@ export interface EncryptPipelineOptions {
   /** Size (in bytes) of each chunk sent during upload. Defaults to 5 000 000 (5 MB). */
   uploadChunkSize?: number;
   delivery?: {
+    /** Send a notification email to each recipient. Default false. */
+    recipients?: boolean;
+    /** Send a confirmation email to the sender. Default false. */
+    sender?: boolean;
     message?: string;
     language?: 'EN' | 'NL';
-    confirmToSender?: boolean;
   };
   headers?: HeadersInit;
   /** Pre-resolved signing keys (skips Yivi/API key resolution if provided) */
@@ -80,7 +83,8 @@ export async function encryptPipeline(options: EncryptPipelineOptions): Promise<
     recipient: recipientEmails,
     mailContent: delivery?.message,
     mailLang: delivery?.language,
-    confirm: delivery?.confirmToSender,
+    confirm: delivery?.sender,
+    notifyRecipients: delivery?.recipients,
     abortSignal: effectiveSignal,
     onProgress: (uploaded, last) => {
       if (onProgress) {

src/email/envelope.ts

@@ -33,7 +33,7 @@ const DEFAULT_WEBSITE_URL = 'https://postguard.eu';
  *  Outlook's 1 M-char setAsync limit and was redundant with the
  *  attachment / fragment link. */
 export async function createEnvelope(options: CreateEnvelopeOptions): Promise<EnvelopeResult> {
-  const { sealed, from, unencryptedMessage, senderAttributes } = options;
+  const { sealed, from, unencryptedMessage, senderAttributes, notify } = options;
   const websiteUrl = options.websiteUrl ?? DEFAULT_WEBSITE_URL;
   const uploadToCryptify = options.uploadToCryptify ?? true;
   const logoUrl = `${websiteUrl}/pg_logo.png`;
@@ -59,7 +59,7 @@ export async function createEnvelope(options: CreateEnvelopeOptions): Promise<En
 
     if (tryUpload) {
       try {
-        const result = await sealed.upload();
+        const result = await sealed.upload(notify ? { notify } : undefined);
         uploadUuid = result.uuid;
       } catch {
         // Network / CORS / Cryptify-unavailable. Fall through to

src/sealed.ts

@@ -71,7 +71,11 @@ export class Sealed {
   }
 
   /** Encrypt and upload to Cryptify (streams internally for efficiency).
-   *  Pass `notify` to have Cryptify send email notifications to recipients. */
+   *  Silent by default — pass `notify.recipients = true` to have
+   *  Cryptify email each recipient a download link, and/or
+   *  `notify.sender = true` for a confirmation back to the sender.
+   *  `notify.message` adds an optional unencrypted body shared by both
+   *  mails. */
   async upload(opts?: UploadOptions): Promise<UploadResult> {
     if (!this.config.cryptifyUrl) {
       throw new Error('cryptifyUrl is required for upload');

src/types.ts

@@ -76,11 +76,25 @@ export interface EncryptInput {
 
 /** Options for sealed.upload() */
 export interface UploadOptions {
-  /** If provided, Cryptify sends email notifications to recipients */
+  /** Cryptify notification settings. Both recipient and sender mails
+   *  are opt-in: omit `notify` (or omit the `recipients` / `sender`
+   *  fields) and the upload is silent. Use this when the encrypted
+   *  payload is being delivered through another channel (e.g. an email
+   *  client) — pass an explicit toggle when Cryptify itself should
+   *  email anyone. */
   notify?: {
+    /** Send a notification email to each recipient with a download
+     *  link. Default false. */
+    recipients?: boolean;
+    /** Send a confirmation email back to the sender. Default false.
+     *  Independent of `recipients`. */
+    sender?: boolean;
+    /** Optional unencrypted message body included in any notification
+     *  email(s) sent — both the per-recipient mail and the sender
+     *  confirmation, when those are enabled. */
     message?: string;
+    /** Notification email template language. Default 'EN'. */
     language?: 'EN' | 'NL';
-    confirmToSender?: boolean;
   };
 }
 
@@ -208,6 +222,12 @@ export interface CreateEnvelopeOptions {
    *  Tier 2; Tier 3 (over `PG_MAX_ATTACHMENT_SIZE`) always uploads because
    *  there is no attachment fallback. */
   uploadToCryptify?: boolean;
+  /** Notification settings for the underlying Cryptify upload. Same
+   *  shape as `Sealed.upload`'s `notify`. Silent by default — set
+   *  `notify.recipients = true` to opt into per-recipient mails, etc.
+   *  Has no effect on Tier 1 (no upload happens) or when
+   *  `uploadToCryptify: false` already skipped the upload. */
+  notify?: UploadOptions['notify'];
 }
 
 /** Which tier the envelope falls into based on encrypted payload size.