agentmail 0.5.44 → 0.5.46

package/dist/esm/api/resources/files/types/CreateFileResponse.d.mts

@@ -0,0 +1,7 @@
+import type * as AgentMail from "../../../index.mjs";
+/**
+ * The created file. A pending file carries `upload`; a create that returns an existing `ready` file does not.
+ */
+export interface CreateFileResponse extends AgentMail.File_ {
+    upload?: AgentMail.FileUpload;
+}

package/dist/esm/api/resources/files/types/CreateFileResponse.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileContentType.d.mts

@@ -0,0 +1,4 @@
+/**
+ * The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`.
+ */
+export type FileContentType = string;

package/dist/esm/api/resources/files/types/FileContentType.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileExpiresAt.d.mts

@@ -0,0 +1,5 @@
+/**
+ * When the file expires. After it, the file is gone from get and list and its path is free; its bytes are
+ * deleted soon after. Absent for a file that never expires.
+ */
+export type FileExpiresAt = Date;

package/dist/esm/api/resources/files/types/FileExpiresAt.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileId.d.mts

@@ -0,0 +1,4 @@
+/**
+ * ID of the file. A UUID.
+ */
+export type FileId = string;

package/dist/esm/api/resources/files/types/FileId.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileItem.d.mts

@@ -0,0 +1,20 @@
+import type * as AgentMail from "../../../index.mjs";
+/**
+ * A file, as a list returns it.
+ */
+export interface FileItem {
+    fileId: AgentMail.FileId;
+    inboxId: AgentMail.inboxes.InboxId;
+    email: AgentMail.inboxes.Email;
+    path: AgentMail.FilePath;
+    name: AgentMail.FileName;
+    size: AgentMail.FileSize;
+    contentType: AgentMail.FileContentType;
+    sha256: AgentMail.FileSha256;
+    status: AgentMail.FileStatus;
+    /** When the file was created. */
+    createdAt: Date;
+    /** When the file last changed, such as when its upload was completed. */
+    updatedAt: Date;
+    expiresAt?: AgentMail.FileExpiresAt;
+}

package/dist/esm/api/resources/files/types/FileItem.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileName.d.mts

@@ -0,0 +1,4 @@
+/**
+ * The path's last segment. A download saves under this name.
+ */
+export type FileName = string;

package/dist/esm/api/resources/files/types/FileName.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FilePath.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Where the file lives in its inbox's drive, such as `reports/q3.pdf`. Unique within the inbox. Segments are
+ * separated by `/`, with no leading or trailing `/`, no empty, `.` or `..` segment, no `\` and no control or
+ * invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two
+ * spellings of one name are one path. Case is kept.
+ */
+export type FilePath = string;

package/dist/esm/api/resources/files/types/FilePath.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileSha256.d.mts

@@ -0,0 +1,5 @@
+/**
+ * The base64 encoding of the file's 32-byte SHA-256 digest, as S3's `x-amz-checksum-sha256` takes it (44
+ * characters, ending in `=`). S3 refuses an upload whose bytes don't match.
+ */
+export type FileSha256 = string;

package/dist/esm/api/resources/files/types/FileSha256.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileSize.d.mts

@@ -0,0 +1,4 @@
+/**
+ * Size of the file in bytes. At most 104,857,600 (100 MiB).
+ */
+export type FileSize = number;

package/dist/esm/api/resources/files/types/FileSize.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/FileStatus.d.mts

@@ -0,0 +1,9 @@
+/**
+ * `pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a
+ * download URL. A pending file is deleted if it isn't completed within a day.
+ */
+export declare const FileStatus: {
+    readonly Pending: "pending";
+    readonly Ready: "ready";
+};
+export type FileStatus = (typeof FileStatus)[keyof typeof FileStatus];

package/dist/esm/api/resources/files/types/FileStatus.mjs

@@ -0,0 +1,9 @@
+// This file was auto-generated by Fern from our API Definition.
+/**
+ * `pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a
+ * download URL. A pending file is deleted if it isn't completed within a day.
+ */
+export const FileStatus = {
+    Pending: "pending",
+    Ready: "ready",
+};

package/dist/esm/api/resources/files/types/FileUpload.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Where to upload a pending file's bytes: one HTTP `PUT` to `url` with exactly `headers` and the file's bytes as
+ * the body. Every header is signed, so S3 refuses the upload if any is missing or different, and refuses bytes
+ * whose size or SHA-256 doesn't match the file. Then call Complete File.
+ */
+export interface FileUpload {
+    /** Always `PUT`. */
+    method: "PUT";
+    /** The presigned S3 URL. No API key is needed to use it. */
+    url: string;
+    /** The headers to send with the `PUT`, exactly as given. */
+    headers: Record<string, string>;
+    /** When `url` stops working, at most an hour after it was issued. Send the identical create request again for a fresh one. */
+    expiresAt: Date;
+}

package/dist/esm/api/resources/files/types/FileUpload.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/File_.d.mts

@@ -0,0 +1,14 @@
+import type * as AgentMail from "../../../index.mjs";
+/**
+ * A file. A `ready` file returned to a caller with the `file_read` permission carries a signed `download_url`.
+ */
+export interface File_ extends AgentMail.FileItem {
+    /**
+     * A signed URL that downloads the file's bytes, named by `name`. No API key is needed to use it, so treat it
+     * as a secret. It works until `download_expires_at`, at most an hour, even after the file is deleted. Get the
+     * file again for a fresh one.
+     */
+    downloadUrl?: string;
+    /** When `download_url` stops working. Never after the file's own expiry. */
+    downloadExpiresAt?: Date;
+}

package/dist/esm/api/resources/files/types/File_.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/ListFilesResponse.d.mts

@@ -0,0 +1,8 @@
+import type * as AgentMail from "../../../index.mjs";
+export interface ListFilesResponse {
+    count: AgentMail.Count;
+    limit: AgentMail.Limit;
+    nextPageToken?: AgentMail.PageToken;
+    /** The inbox's files in path order. A list has no download URLs; get a file for one. */
+    files: AgentMail.FileItem[];
+}

package/dist/esm/api/resources/files/types/ListFilesResponse.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/files/types/index.d.mts

@@ -0,0 +1,14 @@
+export * from "./CreateFileRequest.mjs";
+export * from "./CreateFileResponse.mjs";
+export * from "./File_.mjs";
+export * from "./FileContentType.mjs";
+export * from "./FileExpiresAt.mjs";
+export * from "./FileId.mjs";
+export * from "./FileItem.mjs";
+export * from "./FileName.mjs";
+export * from "./FilePath.mjs";
+export * from "./FileSha256.mjs";
+export * from "./FileSize.mjs";
+export * from "./FileStatus.mjs";
+export * from "./FileUpload.mjs";
+export * from "./ListFilesResponse.mjs";

package/dist/esm/api/resources/files/types/index.mjs

@@ -0,0 +1,14 @@
+export * from "./CreateFileRequest.mjs";
+export * from "./CreateFileResponse.mjs";
+export * from "./File_.mjs";
+export * from "./FileContentType.mjs";
+export * from "./FileExpiresAt.mjs";
+export * from "./FileId.mjs";
+export * from "./FileItem.mjs";
+export * from "./FileName.mjs";
+export * from "./FilePath.mjs";
+export * from "./FileSha256.mjs";
+export * from "./FileSize.mjs";
+export * from "./FileStatus.mjs";
+export * from "./FileUpload.mjs";
+export * from "./ListFilesResponse.mjs";

package/dist/esm/api/resources/inboxes/client/Client.d.mts

@@ -7,6 +7,7 @@ import { ApiKeysClient } from "../resources/apiKeys/client/Client.mjs";
 import { CalendarClient } from "../resources/calendar/client/Client.mjs";
 import { DraftsClient } from "../resources/drafts/client/Client.mjs";
 import { EventsClient } from "../resources/events/client/Client.mjs";
+import { FilesClient } from "../resources/files/client/Client.mjs";
 import { ListsClient } from "../resources/lists/client/Client.mjs";
 import { MessagesClient } from "../resources/messages/client/Client.mjs";
 import { MetricsClient } from "../resources/metrics/client/Client.mjs";
@@ -29,6 +30,7 @@ export declare class InboxesClient {
     protected _apiKeys: ApiKeysClient | undefined;
     protected _accounts: AccountsClient | undefined;
     protected _calendar: CalendarClient | undefined;
+    protected _files: FilesClient | undefined;
     constructor(options?: InboxesClient.Options);
     get threads(): ThreadsClient;
     get messages(): MessagesClient;
@@ -40,6 +42,7 @@ export declare class InboxesClient {
     get apiKeys(): ApiKeysClient;
     get accounts(): AccountsClient;
     get calendar(): CalendarClient;
+    get files(): FilesClient;
     /**
      * **CLI:**
      * ```bash

package/dist/esm/api/resources/inboxes/client/Client.mjs

@@ -21,6 +21,7 @@ import { ApiKeysClient } from "../resources/apiKeys/client/Client.mjs";
 import { CalendarClient } from "../resources/calendar/client/Client.mjs";
 import { DraftsClient } from "../resources/drafts/client/Client.mjs";
 import { EventsClient } from "../resources/events/client/Client.mjs";
+import { FilesClient } from "../resources/files/client/Client.mjs";
 import { ListsClient } from "../resources/lists/client/Client.mjs";
 import { MessagesClient } from "../resources/messages/client/Client.mjs";
 import { MetricsClient } from "../resources/metrics/client/Client.mjs";
@@ -70,6 +71,10 @@ export class InboxesClient {
         var _a;
         return ((_a = this._calendar) !== null && _a !== void 0 ? _a : (this._calendar = new CalendarClient(this._options)));
     }
+    get files() {
+        var _a;
+        return ((_a = this._files) !== null && _a !== void 0 ? _a : (this._files = new FilesClient(this._options)));
+    }
     /**
      * **CLI:**
      * ```bash

package/dist/esm/api/resources/inboxes/resources/files/client/Client.d.mts

@@ -0,0 +1,156 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../../../BaseClient.mjs";
+import { type NormalizedClientOptionsWithAuth } from "../../../../../../BaseClient.mjs";
+import * as core from "../../../../../../core/index.mjs";
+import * as AgentMail from "../../../../../index.mjs";
+export declare namespace FilesClient {
+    type Options = BaseClientOptions;
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+export declare class FilesClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<FilesClient.Options>;
+    constructor(options?: FilesClient.Options);
+    /**
+     * @beta This endpoint is in pre-release and may change.
+     *
+     * Starts an upload: creates a pending file at `path` and returns an `upload` to `PUT` its bytes to. The bytes go
+     * straight to storage, not through the API. Then call Complete File to make the file `ready`.
+     *
+     * Retry-safe: sending the identical request again (same `path`, `size`, `sha256`, `content_type` and
+     * `expires_at`) returns the existing file with `200` instead of `201`: a pending one with a fresh `upload`, or
+     * a `ready` one without. If its bytes were uploaded but the upload was never completed, it is completed then. A
+     * different request at a path whose file is still pending and has no bytes replaces that file; at any other
+     * taken path it returns `409`.
+     *
+     * The file counts against the organization's Drive quota from creation, pending or not: 1 GiB and 10,000 files
+     * by default. A file that doesn't fit returns `403` with code `limit_exceeded`. Deleting a file frees its
+     * space within seconds. Expired files count until a create needs their space: a create that doesn't fit first
+     * gives back what expired files hold, a batch at a time, so retry a refusal while many expired files remain.
+     *
+     * Requires the `file_create` permission, which an unverified organization's keys don't have at any scope until
+     * it completes agent verification. A key without `file_read` can still create files, but gets the plain `409` at
+     * any taken path, even for an identical request at a file it didn't create.
+     *
+     * Agent Drive is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet in EU
+     * production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+     *
+     * @param {AgentMail.inboxes.InboxId} inbox_id
+     * @param {AgentMail.inboxes.CreateFileRequestWrapper} request
+     * @param {FilesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link AgentMail.ValidationError}
+     * @throws {@link AgentMail.FileForbiddenError}
+     * @throws {@link AgentMail.NotFoundError}
+     * @throws {@link AgentMail.ConflictError}
+     *
+     * @example
+     *     await client.inboxes.files.create("reports@agentmail.to", {
+     *         path: "reports/q3.pdf",
+     *         size: 48213,
+     *         sha256: "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
+     *         contentType: "application/pdf"
+     *     })
+     */
+    create(inbox_id: AgentMail.inboxes.InboxId, request: AgentMail.inboxes.CreateFileRequestWrapper, requestOptions?: FilesClient.RequestOptions): core.HttpResponsePromise<AgentMail.CreateFileResponse>;
+    private __create;
+    /**
+     * @beta This endpoint is in pre-release and may change.
+     *
+     * Makes a pending file `ready` once its bytes are uploaded, and returns it, with its `download_url` if the key
+     * has `file_read`. Calling it on a file that is already `ready` returns the file.
+     *
+     * Returns `409` if the bytes haven't been uploaded yet, or if what was uploaded doesn't match the file's `size`
+     * and `sha256`. Returns `404` for a file that has expired or was deleted, including a pending file not
+     * completed within a day of its creation.
+     *
+     * Requires the `file_create` permission. Only a key with `file_read`, or the key that created the file, can
+     * complete it; any other key gets `404`.
+     *
+     * @param {AgentMail.inboxes.InboxId} inbox_id
+     * @param {AgentMail.FileId} file_id
+     * @param {FilesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link AgentMail.ValidationError}
+     * @throws {@link AgentMail.FileForbiddenError}
+     * @throws {@link AgentMail.NotFoundError}
+     * @throws {@link AgentMail.ConflictError}
+     *
+     * @example
+     *     await client.inboxes.files.complete("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f")
+     */
+    complete(inbox_id: AgentMail.inboxes.InboxId, file_id: AgentMail.FileId, requestOptions?: FilesClient.RequestOptions): core.HttpResponsePromise<AgentMail.File_>;
+    private __complete;
+    /**
+     * @beta This endpoint is in pre-release and may change.
+     *
+     * Gets a file. A `ready` file comes with a fresh `download_url`, valid for up to an hour.
+     *
+     * A get reads the region that serves the request, so for about a second after a delete it can still return
+     * the deleted file. A file that has expired returns `404` at once.
+     *
+     * Requires the `file_read` permission.
+     *
+     * @param {AgentMail.inboxes.InboxId} inbox_id
+     * @param {AgentMail.FileId} file_id
+     * @param {FilesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link AgentMail.ValidationError}
+     * @throws {@link AgentMail.FileForbiddenError}
+     * @throws {@link AgentMail.NotFoundError}
+     *
+     * @example
+     *     await client.inboxes.files.get("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f")
+     */
+    get(inbox_id: AgentMail.inboxes.InboxId, file_id: AgentMail.FileId, requestOptions?: FilesClient.RequestOptions): core.HttpResponsePromise<AgentMail.File_>;
+    private __get;
+    /**
+     * @beta This endpoint is in pre-release and may change.
+     *
+     * Lists the inbox's files in path order, pending ones included, optionally only those whose path starts with
+     * `path_prefix`. A prefix matches characters, not whole segments: `reports/q` matches `reports/q3.pdf`. Items
+     * carry no download URL; get a file for one.
+     *
+     * The list is read in the region that serves the request, so a file created or deleted a moment ago may not
+     * show yet. Expired files never show.
+     *
+     * Requires the `file_read` permission.
+     *
+     * @param {AgentMail.inboxes.InboxId} inbox_id
+     * @param {AgentMail.inboxes.ListFilesRequest} request
+     * @param {FilesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link AgentMail.ValidationError}
+     * @throws {@link AgentMail.FileForbiddenError}
+     * @throws {@link AgentMail.NotFoundError}
+     *
+     * @example
+     *     await client.inboxes.files.list("reports@agentmail.to", {
+     *         pathPrefix: "reports/"
+     *     })
+     */
+    list(inbox_id: AgentMail.inboxes.InboxId, request?: AgentMail.inboxes.ListFilesRequest, requestOptions?: FilesClient.RequestOptions): core.HttpResponsePromise<AgentMail.ListFilesResponse>;
+    private __list;
+    /**
+     * @beta This endpoint is in pre-release and may change.
+     *
+     * Deletes a file, pending or `ready`, and frees its path at once. Its bytes are deleted, and its space given
+     * back to the organization's quota, within seconds. A download URL signed before the delete keeps working
+     * until it expires, at most an hour. Deleting a file that is already gone returns `404`.
+     *
+     * Requires the `file_delete` permission. Only a key with `file_read`, or the key that created the file, can
+     * delete it; any other key gets `404`.
+     *
+     * @param {AgentMail.inboxes.InboxId} inbox_id
+     * @param {AgentMail.FileId} file_id
+     * @param {FilesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link AgentMail.ValidationError}
+     * @throws {@link AgentMail.FileForbiddenError}
+     * @throws {@link AgentMail.NotFoundError}
+     *
+     * @example
+     *     await client.inboxes.files.delete("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f")
+     */
+    delete(inbox_id: AgentMail.inboxes.InboxId, file_id: AgentMail.FileId, requestOptions?: FilesClient.RequestOptions): core.HttpResponsePromise<void>;
+    private __delete;
+}