@mindstudio-ai/agent 0.1.108 → 0.1.110

package/dist/index.d.ts

@@ -109,6 +109,13 @@ declare class Store {
     get access(): FileAccess;
     /** Store bytes. Returns a {@link StoredFile} with a ready-to-use `url`. */
     put(content: Buffer | Uint8Array | string, options?: PutOptions): Promise<StoredFile>;
+    /**
+     * Large-content half of {@link put}: mint a presigned POST scoped to exactly
+     * these bytes and send them direct to storage — the JSON transport's body
+     * limit never sees them. Same result contract as the small path; the final
+     * `head` keeps the returned metadata honest (server-observed size/type/time).
+     */
+    private _putPresigned;
     /** Read an object's bytes (backend / trusted context). */
     get(key: string): Promise<Buffer>;
     /** Metadata without downloading. Rejects if the object doesn't exist. */
@@ -2352,7 +2359,7 @@ interface SearchRan {
  * vector, so they take effect on the next call and cost nothing. Anything that
  * would require rebuilding the corpus — chunking, the embedding model, whether
  * chunks are contextualized — is a property of the data source, configured
- * with `mindstudio-prod datasources config` rather than passed here.
+ * with `remy-admin datasources config` rather than passed here.
  *
  * The defaults come from the data source's own configuration, so most callers
  * should pass nothing.
@@ -2862,12 +2869,16 @@ interface Analytics {
 }
 
 /**
- * The `email` namespace: read and manage your app's OWN outbound email.
+ * The `email` namespace: send, read and manage your app's OWN outbound email.
  *
- * Sending is not here — that's the `sendEmail` action
- * (`mindstudio.sendEmail({...})`). This namespace is everything *after* the send:
- * what happened to each message, how a campaign performed, and who has
- * unsubscribed.
+ * `email.send()` is the send path. The older `mindstudio.sendEmail({...})` action
+ * still works and shares exactly the same implementation, so nothing breaks — but
+ * `send()` is the one to reach for: it returns a proper receipt (including the
+ * `batchId` you read stats back with) and it lives alongside everything you do
+ * with the result.
+ *
+ * The rest of the namespace is everything *after* the send: what happened to each
+ * message, how a campaign performed, and who has unsubscribed.
  *
  * The point is that you can build your own email admin screen inside your own app
  * and never open the MindStudio dashboard. So this deliberately includes the
@@ -2875,7 +2886,7 @@ interface Analytics {
  * unsubscribe list, this can do too.
  *
  * Every call is scoped to the executing app by its request token; there is no
- * appId parameter and no way to read another app's mail.
+ * appId parameter and no way to read or send as another app.
  */
 /** Where a message got to. See `EmailMessage.status`. */
 type EmailMessageStatus = 
@@ -3011,7 +3022,149 @@ interface EmailWindowOptions {
     start?: string | Date;
     end?: string | Date;
 }
+/**
+ * How a message body is interpreted.
+ *
+ * `auto` (the default) sniffs it: something that looks like HTML is sent as HTML,
+ * anything else is rendered from Markdown. Every message goes out multipart with a
+ * plain-text alternative derived from the body, which mail providers reward.
+ */
+type EmailBodyType = 'auto' | 'html' | 'markdown' | 'text';
+interface EmailAttachmentInput {
+    url: string;
+    /** Displayed filename. Derived from the URL when omitted. */
+    filename?: string;
+    contentType?: string;
+}
+interface EmailSendOptions {
+    /** Visible recipients. Optional only if you supply `cc` or `bcc`. */
+    to?: string | string[];
+    cc?: string | string[];
+    /**
+     * Hidden recipients. With no `to`/`cc`, the To: header is addressed to your
+     * app's own sender — the standard "undisclosed recipients" pattern — so
+     * recipients can't see each other.
+     */
+    bcc?: string | string[];
+    subject: string;
+    /** Plain text, Markdown, or HTML. See {@link EmailBodyType}. */
+    body: string;
+    bodyType?: EmailBodyType;
+    /** Your own plain-text alternative, instead of the auto-derived one. */
+    text?: string;
+    attachments?: Array<string | EmailAttachmentInput>;
+    /**
+     * Sender handle — only if your app has a custom domain or platform subdomain.
+     * `"support"`, `"support@your-domain.com"`, or `"Name <support@your-domain.com>"`.
+     * The domain must be one your app owns or the send fails.
+     */
+    from?: string;
+    replyTo?: string;
+    /** Message-ID this replies to, for threading in a shared inbox. */
+    inReplyTo?: string;
+    /** Prior Message-IDs in the thread. */
+    references?: string[];
+    /**
+     * **Defaults to `marketing`**, which is the consequential choice here.
+     *
+     * `marketing` attaches a one-click unsubscribe header pointing at your own
+     * domain and skips anyone who previously unsubscribed from your app. Because
+     * that link is per-recipient, a marketing send delivers one separate message per
+     * recipient and `cc`/`bcc` are folded into that list — so they come back empty.
+     *
+     * `transactional` is for receipts, alerts and password resets: no unsubscribe
+     * header, the unsubscribe list is ignored, and `cc`/`bcc` stay on one shared
+     * message. Use it whenever cc/bcc semantics actually matter.
+     */
+    category?: 'transactional' | 'marketing';
+    /**
+     * Groups this send's per-recipient rows into one blast. Pass your own campaign
+     * id (1–64 printable chars) to join our delivery stats onto your own tables with
+     * no mapping; one is generated when omitted, and it's always returned.
+     */
+    batchId?: string;
+}
+interface EmailSendResult {
+    /** Addresses the message went to. */
+    recipients: string[];
+    /** Always empty for a marketing send — see `category`. */
+    cc: string[];
+    /** Always empty for a marketing send — see `category`. */
+    bcc: string[];
+    /** The resolved sender it went out as. */
+    from: string;
+    /**
+     * Recipients skipped because they had unsubscribed from your app. **Not an
+     * error** — the send succeeded and we honoured their opt-out. Always empty for
+     * a transactional send.
+     *
+     * Worth surfacing to whoever triggered the send: "sent to 48 of 50, 2
+     * unsubscribed" is the honest report, and silence here is what makes people
+     * think mail vanished.
+     */
+    suppressed: string[];
+    /** Read stats back with `email.batch(batchId)`. */
+    batchId: string;
+}
+/** Your app's sending allowance for the current window. */
+interface EmailQuota {
+    /** What the numbers count — `recipients`. */
+    unit: string;
+    window: 'day' | 'month' | 'total';
+    /** `null` means unlimited. */
+    limit: number | null;
+    used: number;
+    /** `null` when `limit` is null. */
+    remaining: number | null;
+    /** When `used` resets. */
+    resetsAt: string | null;
+}
 interface Email {
+    /**
+     * Send an email.
+     *
+     * Two things to know before your first call. **`category` defaults to
+     * `marketing`**, which fans a multi-recipient send out into one message each and
+     * empties `cc`/`bcc` — pass `'transactional'` for receipts, alerts and codes.
+     * And a non-empty `suppressed` in the result is a **success**, not a failure: it
+     * lists people who had unsubscribed and were therefore skipped.
+     *
+     * Delivery is synchronous today: this resolves once the mail has been handed to
+     * the provider, so a large marketing list takes a while. Outcomes (delivered,
+     * bounced, complained) arrive later — read them with
+     * `email.messages({ batchId })`.
+     *
+     * @example
+     * ```ts
+     * // A receipt: one message, cc preserved, no unsubscribe header.
+     * await email.send({
+     *   to: 'customer@example.com',
+     *   cc: 'billing@your-co.com',
+     *   subject: 'Your receipt',
+     *   body: '# Thanks!\n\nOrder #1234 is confirmed.',
+     *   category: 'transactional',
+     * });
+     *
+     * // A campaign: per-recipient unsubscribe, your own id for joining stats.
+     * const { suppressed, batchId } = await email.send({
+     *   to: subscribers,
+     *   subject: 'August newsletter',
+     *   body: markdown,
+     *   batchId: 'newsletter-2026-08',
+     * });
+     * console.log(`skipped ${suppressed.length} unsubscribed`);
+     * const stats = await email.batch(batchId);
+     * ```
+     */
+    send(options: EmailSendOptions): Promise<EmailSendResult>;
+    /**
+     * Your app's sending allowance and how much is left.
+     *
+     * Useful before a large send: check `remaining` and split the list rather than
+     * discovering the limit as a failure partway through. Going over throws with
+     * `outbound_daily_cap_exceeded`.
+     */
+    quota(): Promise<EmailQuota>;
     /** Counts, rates and a timeseries over a window (default: last 24h). */
     stats(options?: EmailWindowOptions & {
         buckets?: number;
@@ -3731,13 +3884,25 @@ declare class MindStudioAgent$1 {
      */
     get analytics(): Analytics;
     /**
-     * Outbound email: the per-recipient delivery log, blast stats, and this app's
-     * unsubscribe list. Sending is the `sendEmail` action, not this namespace.
+     * Outbound email: sending, the per-recipient delivery log, blast stats, and
+     * this app's unsubscribe list.
+     *
+     * `email.send()` is the send path — the `sendEmail` action still works and runs
+     * the same code, but `send()` returns a receipt including the `batchId` you read
+     * stats back with. Note `category` defaults to `'marketing'`; see
+     * {@link Email.send}.
      *
      * @example
      * ```ts
      * import { email } from '@mindstudio-ai/agent';
      *
+     * await email.send({
+     *   to: 'a@b.com',
+     *   subject: 'Your receipt',
+     *   body: 'Thanks!',
+     *   category: 'transactional',
+     * });
+     *
      * // A support lookup: did this person get their mail?
      * const { messages } = await email.messages({ recipient: 'a@b.com' });
      *
@@ -11198,11 +11363,15 @@ declare const voice: Voice;
  */
 declare const analytics: Analytics;
 /**
- * Your app's outbound email — the delivery log, blast stats, and the unsubscribe
- * list. Sending is `mindstudio.sendEmail(...)`; this is everything after it.
+ * Your app's outbound email — sending, the delivery log, blast stats, and the
+ * unsubscribe list.
+ *
+ * `email.send()` is the send path. `mindstudio.sendEmail(...)` still works and
+ * runs the same code underneath, but `send()` returns a proper receipt and sits
+ * next to everything you do with the result.
  *
  * Scoped to the executing app by its request token, so there is no appId to pass
- * and no way to read another app's mail.
+ * and no way to read or send as another app.
  *
  * @example
  * ```ts

package/dist/index.js

@@ -2592,6 +2592,7 @@ function toBase64(content) {
     typeof content === "string" ? Buffer.from(content) : content
   ).toString("base64");
 }
+var PRESIGN_THRESHOLD = 4 * 1024 * 1024;
 function extensionFor(filename) {
   if (!filename) {
     return "";
@@ -2619,16 +2620,73 @@ var Store = class {
     const ext = extensionFor(options?.filename);
     const key = options?.key ?? (options?.contentAddressed ? `${createHash("sha256").update(content).digest("hex")}${ext}` : `${randomUUID()}${ext}`);
     const cacheControl = options?.cacheControl ?? (!options?.key && this._access === "public" ? "public, max-age=31536000, immutable" : void 0);
+    const bytes = typeof content === "string" ? Buffer.from(content) : content;
+    if (bytes.byteLength >= PRESIGN_THRESHOLD) {
+      return this._putPresigned(bytes, key, {
+        ...options?.contentType ? { contentType: options.contentType } : {},
+        ...cacheControl ? { cacheControl } : {}
+      });
+    }
     const meta = await this._call("put", {
       store: this._store,
       access: this._access,
       key,
-      body: toBase64(content),
+      body: toBase64(bytes),
       ...options?.contentType ? { contentType: options.contentType } : {},
       ...cacheControl ? { cacheControl } : {}
     });
     return this._toFile(key, meta);
   }
+  /**
+   * Large-content half of {@link put}: mint a presigned POST scoped to exactly
+   * these bytes and send them direct to storage — the JSON transport's body
+   * limit never sees them. Same result contract as the small path; the final
+   * `head` keeps the returned metadata honest (server-observed size/type/time).
+   */
+  async _putPresigned(bytes, key, options) {
+    const res = await this._call("create-upload", {
+      store: this._store,
+      access: this._access,
+      key,
+      maxSize: bytes.byteLength,
+      ...options.contentType ? { contentType: options.contentType } : {},
+      ...options.cacheControl ? { cacheControl: options.cacheControl } : {}
+    });
+    const form = new FormData();
+    for (const [k, v] of Object.entries(
+      res.uploadFields
+    )) {
+      form.append(k, v);
+    }
+    const view = new Uint8Array(
+      bytes.buffer,
+      bytes.byteOffset,
+      bytes.byteLength
+    );
+    form.append(
+      "file",
+      new Blob([view], options.contentType ? { type: options.contentType } : void 0)
+    );
+    const upload = await fetch(res.uploadUrl, {
+      method: "POST",
+      body: form
+    });
+    if (!upload.ok) {
+      const errorText = await upload.text().catch(() => "");
+      throw new MindStudioError(
+        `Upload failed: ${upload.status} ${upload.statusText}${errorText ? ` \u2014 ${errorText.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 200)}` : ""}`,
+        "upload_error",
+        upload.status,
+        errorText || void 0
+      );
+    }
+    const meta = await this._call("head", {
+      store: this._store,
+      access: this._access,
+      key
+    });
+    return this._toFile(key, meta);
+  }
   /** Read an object's bytes (backend / trusted context). */
   async get(key) {
     const res = await this._call("get", {
@@ -2968,6 +3026,12 @@ function createAnalytics(call) {
 var iso = (v) => v === void 0 ? void 0 : v instanceof Date ? v.toISOString() : v;
 function createEmail(call) {
   return {
+    send(options) {
+      return call("send", options);
+    },
+    quota() {
+      return call("quota", {});
+    },
     stats(options) {
       return call("stats", {
         start: iso(options?.start),
@@ -6766,13 +6830,25 @@ var MindStudioAgent = class {
     );
   }
   /**
-   * Outbound email: the per-recipient delivery log, blast stats, and this app's
-   * unsubscribe list. Sending is the `sendEmail` action, not this namespace.
+   * Outbound email: sending, the per-recipient delivery log, blast stats, and
+   * this app's unsubscribe list.
+   *
+   * `email.send()` is the send path — the `sendEmail` action still works and runs
+   * the same code, but `send()` returns a receipt including the `batchId` you read
+   * stats back with. Note `category` defaults to `'marketing'`; see
+   * {@link Email.send}.
    *
    * @example
    * ```ts
    * import { email } from '@mindstudio-ai/agent';
    *
+   * await email.send({
+   *   to: 'a@b.com',
+   *   subject: 'Your receipt',
+   *   body: 'Thanks!',
+   *   category: 'transactional',
+   * });
+   *
    * // A support lookup: did this person get their mail?
    * const { messages } = await email.messages({ recipient: 'a@b.com' });
    *