agentmail 0.5.44 → 0.5.46

package/dist/cjs/api/resources/inboxes/resources/files/client/Client.d.ts

@@ -0,0 +1,156 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth } from "../../../../../../BaseClient.js";
+import * as core from "../../../../../../core/index.js";
+import * as AgentMail from "../../../../../index.js";
+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;
+}