@toshicloud/sdk 0.5.1 → 0.6.0

package/README.md

@@ -147,9 +147,16 @@ method for each call (`create`, `get`, `list`, `update`, `delete`, `wait`,
 `watch`, and `cancel` on a job, `execute`, `start` and `stop` on a sandbox,
 `start`, `stop`, `setMode`, `listRuns`, `wake`, `hold`, `release`,
 `listRevisions`, `getRevision`, `rollback` and `listActivations` on a
-service). The calls that
+service). A service's alarms are `setAlarm`, `getAlarm`, `listAlarms`
+(every alarm in one answer, with no page token), `deleteAlarm`,
+`pauseAlarm`, `resumeAlarm` and `runAlarmNow`, and its sign-ins are
+`startSignIn`, which hands back the sign-in's stream as the server sends
+it, `answerSignIn`, `cancelSignIn` and `getSignInStatus`. The calls that
 span the three types sit on `workload` itself: `listEvents`, `watchEvents`,
-`getOperation` and `waitOperation`. `run` sits at the top of the client, as
+`emitEvent`, `holdWorkload`, `releaseWorkload`, `getOperation` and
+`waitOperation`. `holdWorkload` and `releaseWorkload` are operator-only and
+need the operator's headers, which the caller adds with an interceptor
+(see Operator calls). `run` sits at the top of the client, as
 `toshi run` sits at the top of the CLI.
 
 <!-- examples/client-shape.ts -->
@@ -160,6 +167,49 @@ const { job } = await toshi.workload.jobs.get({ id: jobs[0].id });
 console.log(job?.id);
 ```
 
+### Operator calls
+
+An operator's token sends its reason in `Toshi-Operator-Reason` and the
+workspace it acts on in `Toshi-Workspace` on every Workspace API call; the
+server refuses one without them. Both belong to the client rather than to a
+call, so the caller sets them with an interceptor of its own: the `transport`
+option receives the client's interceptors, and the caller adds the one that
+writes the headers. `workload.holdWorkload` places an operator's hold on a
+sandbox or service, stopping it if it runs, and `workload.releaseWorkload`
+lifts the hold and starts nothing; only an operator may make either call.
+
+<!-- examples/operator-reason.ts -->
+
+```ts
+import type { Interceptor } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-node";
+
+import { createToshiClient } from "@toshicloud/sdk/node";
+
+const baseUrl = "https://toshi.example.com";
+
+// An operator's token, the reason its calls carry and the workspace they
+// act on.
+declare const token: string;
+
+const operator: Interceptor = (next) => (req) => {
+  req.header.set("Toshi-Operator-Reason", "investigating a report");
+  req.header.set("Toshi-Workspace", "acme");
+  return next(req);
+};
+
+export const toshi = createToshiClient({
+  transport: (interceptors) =>
+    createConnectTransport({
+      baseUrl,
+      httpVersion: "2",
+      interceptors: [...interceptors, operator],
+    }),
+  token,
+  project: "default",
+});
+```
+
 ### Lists
 
 `workload.jobs.all`, `workload.sandboxes.all`,
@@ -407,6 +457,10 @@ for await (const chunk of run) {
 await run.wait();
 ```
 
+The fake also keeps a service's alarms: `setAlarm`, `getAlarm`, `listAlarms`,
+`deleteAlarm`, `pauseAlarm`, `resumeAlarm` and `runAlarmNow` answer from its
+state machine.
+
 `fake.on(method, impl)` replaces the state machine for one method with a hook
 typed by that method: one call for unary, server-stream and bidirectional
 methods alike. `fake.calls()` returns every call the fake received, oldest
@@ -423,8 +477,9 @@ in `proto/toshi/workspace/v1` of the
 only `@bufbuild/protobuf`, so installing the package needs no generator.
 
 `pin.env` names the toshi-api commit the code is generated from:
-`2184ae8440834bb5b91991b3e4d62d14ce9dd15a` today, the commit of the
-release tag `v0.4.1`. `mise.toml` pins the versions of Node, pnpm and `buf`;
+`5474559e89f7faf4b718fd5f1d64ff7457657477` today, the commit of the
+release tag `v0.5.0`.
+`mise.toml` pins the versions of Node, pnpm and `buf`;
 `package.json` pins `protoc-gen-es` at the same version as the
 `@bufbuild/protobuf` development dependency.
 

package/dist/client.d.ts

@@ -26,10 +26,10 @@ import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
 import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.js";
 import { CreatePreviewShareLinkRequestSchema, ListPreviewShareLinksRequestSchema, RevokePreviewShareLinkRequestSchema, StartSandboxRequestSchema, StopSandboxRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import type { CreatePreviewShareLinkResponse, ListPreviewShareLinksResponse, RevokePreviewShareLinkResponse, StartSandboxResponse, StopSandboxResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema } from "./gen/toshi/workspace/v1/workloads_pb.js";
-import type { CancelJobResponse, CreateJobResponse, CreateSandboxResponse, CreateServiceResponse, DeleteJobResponse, DeleteSandboxResponse, DeleteServiceResponse, GetJobResponse, GetSandboxResponse, GetServiceResponse, ListJobsResponse, ListSandboxesResponse, ListServicesResponse, UpdateJobResponse, UpdateSandboxResponse, UpdateServiceResponse, WaitJobResponse, WaitSandboxResponse, WaitServiceResponse, WatchJobsResponse, WatchSandboxesResponse, WatchServicesResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
-import { ExecuteStartSchema, GetOperationRequestSchema, GetServiceRevisionRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import type { Event, GetOperationResponse, GetServiceRevisionResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceActivationsResponse, ListServiceRevisionsResponse, ListServiceRunsResponse, Operation, PreviewShareLink, ReleaseServiceResponse, RollbackServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceAlarmRequestSchema, DeleteServiceRequestSchema, EmitWorkloadEventRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceAlarmRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServiceAlarmsRequestSchema, ListServicesRequestSchema, PauseServiceAlarmRequestSchema, ResumeServiceAlarmRequestSchema, RunServiceAlarmNowRequestSchema, SetServiceAlarmRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import type { CancelJobResponse, CreateJobResponse, CreateSandboxResponse, CreateServiceResponse, DeleteJobResponse, DeleteSandboxResponse, DeleteServiceAlarmResponse, DeleteServiceResponse, EmitWorkloadEventResponse, GetJobResponse, GetSandboxResponse, GetServiceAlarmResponse, GetServiceResponse, ListJobsResponse, ListSandboxesResponse, ListServiceAlarmsResponse, ListServicesResponse, PauseServiceAlarmResponse, ResumeServiceAlarmResponse, RunServiceAlarmNowResponse, SetServiceAlarmResponse, UpdateJobResponse, UpdateSandboxResponse, UpdateServiceResponse, WaitJobResponse, WaitSandboxResponse, WaitServiceResponse, WatchJobsResponse, WatchSandboxesResponse, WatchServicesResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { AnswerServiceSignInRequestSchema, CancelServiceSignInRequestSchema, ExecuteStartSchema, GetOperationRequestSchema, GetServiceRevisionRequestSchema, GetServiceSignInStatusRequestSchema, HoldServiceRequestSchema, HoldWorkloadRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, ReleaseWorkloadRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StartServiceSignInRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { AnswerServiceSignInResponse, CancelServiceSignInResponse, Event, GetOperationResponse, GetServiceRevisionResponse, GetServiceSignInStatusResponse, HoldServiceResponse, HoldWorkloadResponse, Job, ListEventsResponse, ListServiceActivationsResponse, ListServiceRevisionsResponse, ListServiceRunsResponse, Operation, PreviewShareLink, ReleaseServiceResponse, ReleaseWorkloadResponse, RollbackServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StartServiceSignInResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import type { RetryPolicy } from "./retry.js";
 /** How the client is configured; the caller builds the transport. */
 export interface ToshiOptions {
@@ -97,6 +97,22 @@ export interface WorkloadClient {
     /** Yields every event listEvents lists, following the page token from one page to the next. */
     allEvents(req: MessageInitShape<typeof ListEventsRequestSchema>, opts?: CallOptions): AsyncIterable<Event>;
     watchEvents(req: MessageInitShape<typeof WatchEventsRequestSchema>, opts?: CallOptions): Promise<EventWatch>;
+    /**
+     * Appends an event of type EMITTED, with the name and data given, to a job's, sandbox's or
+     * service's event log, as its guest emits one, and returns it; the workload need not be running.
+     */
+    emitEvent(req: MessageInitShape<typeof EmitWorkloadEventRequestSchema>, opts?: CallOptions): Promise<EmitWorkloadEventResponse>;
+    /**
+     * Places an operator's hold on a sandbox or service, stopping it if it runs. Only an
+     * operator may call it; the caller sets the operator's reason in the Toshi-Operator-Reason
+     * header with an interceptor, since the client sends none itself.
+     */
+    holdWorkload(req: MessageInitShape<typeof HoldWorkloadRequestSchema>, opts?: CallOptions): Promise<HoldWorkloadResponse>;
+    /**
+     * Lifts an operator's hold and starts nothing. Only an operator may call it; the caller
+     * sets the operator's reason in the Toshi-Operator-Reason header with an interceptor.
+     */
+    releaseWorkload(req: MessageInitShape<typeof ReleaseWorkloadRequestSchema>, opts?: CallOptions): Promise<ReleaseWorkloadResponse>;
     /** Returns one operation: the id a long call hands back, asked for again. */
     getOperation(req: MessageInitShape<typeof GetOperationRequestSchema>, opts?: CallOptions): Promise<GetOperationResponse>;
 }
@@ -162,6 +178,58 @@ export interface ServicesClient {
     rollback(req: MessageInitShape<typeof RollbackServiceRequestSchema>, opts?: CallOptions): Promise<RollbackServiceResponse>;
     /** Returns a service's activations, oldest first. */
     listActivations(req: MessageInitShape<typeof ListServiceActivationsRequestSchema>, opts?: CallOptions): Promise<ListServiceActivationsResponse>;
+    /**
+     * Creates or replaces the service's alarm with this name and returns it: at each instant of its
+     * schedule the alarm publishes its event, with its data, on one of the service's event channels.
+     */
+    setAlarm(req: MessageInitShape<typeof SetServiceAlarmRequestSchema>, opts?: CallOptions): Promise<SetServiceAlarmResponse>;
+    /** Returns one alarm and its most recent occurrences, newest first. */
+    getAlarm(req: MessageInitShape<typeof GetServiceAlarmRequestSchema>, opts?: CallOptions): Promise<GetServiceAlarmResponse>;
+    /**
+     * Returns all of a service's alarms, by name, in one answer: the call has no page token, so
+     * there is no `allAlarms`.
+     */
+    listAlarms(req: MessageInitShape<typeof ListServiceAlarmsRequestSchema>, opts?: CallOptions): Promise<ListServiceAlarmsResponse>;
+    /** Removes an alarm and its occurrences; messages it already published stay on the channel. */
+    deleteAlarm(req: MessageInitShape<typeof DeleteServiceAlarmRequestSchema>, opts?: CallOptions): Promise<DeleteServiceAlarmResponse>;
+    /** Stops an alarm publishing until it is resumed; pausing a paused alarm changes nothing. */
+    pauseAlarm(req: MessageInitShape<typeof PauseServiceAlarmRequestSchema>, opts?: CallOptions): Promise<PauseServiceAlarmResponse>;
+    /**
+     * Starts a paused alarm again from the next instant of its schedule; instants that passed while
+     * it was paused are not published.
+     */
+    resumeAlarm(req: MessageInitShape<typeof ResumeServiceAlarmRequestSchema>, opts?: CallOptions): Promise<ResumeServiceAlarmResponse>;
+    /**
+     * Publishes the alarm's event once, now, paused or not, and returns the occurrence; it does not
+     * move the alarm's next instant. It takes a request key, so a retried call is applied once.
+     */
+    runAlarmNow(req: MessageInitShape<typeof RunServiceAlarmNowRequestSchema>, opts?: CallOptions): Promise<RunServiceAlarmNowResponse>;
+    /**
+     * Runs one of the service's recipe's sign_in programs and hands back its stream as the server
+     * sends it. The caller reads the started message first, which names the sign-in; then the
+     * output messages, the program's standard output and standard error; answers the program with
+     * `answerSignIn` or ends it early with `cancelSignIn`; and reads the ended message last, which
+     * says how it ended. A sign-in may run for 15 minutes.
+     *
+     * The stream is not retried or resumed: a sign-in has no cursor. Its stream ending for another
+     * reason, as a client that leaves, also ends it, cancelled; the caller starts a new one.
+     */
+    startSignIn(req: MessageInitShape<typeof StartServiceSignInRequestSchema>, opts?: CallOptions): AsyncIterable<StartServiceSignInResponse>;
+    /**
+     * Writes one line, of at most 4 KiB and with no newline in it, to a running sign-in's standard
+     * input; the sign-in's program reads it.
+     */
+    answerSignIn(req: MessageInitShape<typeof AnswerServiceSignInRequestSchema>, opts?: CallOptions): Promise<AnswerServiceSignInResponse>;
+    /**
+     * Ends a running sign-in: its program is cancelled and its stream ends CANCELLED. It returns
+     * once the cancel is asked for, not once the sign-in has ended.
+     */
+    cancelSignIn(req: MessageInitShape<typeof CancelServiceSignInRequestSchema>, opts?: CallOptions): Promise<CancelServiceSignInResponse>;
+    /**
+     * Runs the status commands of the service's recipe and reports, for each sign_in program,
+     * whether it is signed in and what its status command wrote.
+     */
+    getSignInStatus(req: MessageInitShape<typeof GetServiceSignInStatusRequestSchema>, opts?: CallOptions): Promise<GetServiceSignInStatusResponse>;
 }
 /** A live stream of a job's changes. */
 export interface JobWatch extends AsyncIterable<WatchJobsResponse> {

package/dist/client.js

@@ -26,8 +26,8 @@ import { VolumeService } from "./gen/toshi/workspace/v1/volumes_pb.js";
 import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
 import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.js";
 import { CreatePreviewShareLinkRequestSchema, ListPreviewShareLinksRequestSchema, RevokePreviewShareLinkRequestSchema, StartSandboxRequestSchema, StopSandboxRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema, WorkloadService, } from "./gen/toshi/workspace/v1/workloads_pb.js";
-import { ExecuteStartSchema, GetOperationRequestSchema, GetServiceRevisionRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceAlarmRequestSchema, DeleteServiceRequestSchema, EmitWorkloadEventRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceAlarmRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServiceAlarmsRequestSchema, ListServicesRequestSchema, PauseServiceAlarmRequestSchema, ResumeServiceAlarmRequestSchema, RunServiceAlarmNowRequestSchema, SetServiceAlarmRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema, WorkloadService, } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { AnswerServiceSignInRequestSchema, CancelServiceSignInRequestSchema, ExecuteStartSchema, GetOperationRequestSchema, GetServiceRevisionRequestSchema, GetServiceSignInStatusRequestSchema, HoldServiceRequestSchema, HoldWorkloadRequestSchema, ListEventsRequestSchema, ListServiceActivationsRequestSchema, ListServiceRevisionsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, ReleaseWorkloadRequestSchema, RollbackServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StartServiceSignInRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import { openOutputWatch } from "./output.js";
 import { paginate } from "./paginate.js";
 import { authInterceptor, keyInterceptor, refusalInterceptor, retryInterceptor, scopeInterceptor, } from "./interceptors.js";
@@ -118,11 +118,25 @@ export function createToshiClient(options) {
                 getRevision: (req, opts) => workloadService.getServiceRevision(req, opts),
                 rollback: (req, opts) => workloadService.rollbackService(req, opts),
                 listActivations: (req, opts) => workloadService.listServiceActivations(req, opts),
+                setAlarm: (req, opts) => workloadService.setServiceAlarm(req, opts),
+                getAlarm: (req, opts) => workloadService.getServiceAlarm(req, opts),
+                listAlarms: (req, opts) => workloadService.listServiceAlarms(req, opts),
+                deleteAlarm: (req, opts) => workloadService.deleteServiceAlarm(req, opts),
+                pauseAlarm: (req, opts) => workloadService.pauseServiceAlarm(req, opts),
+                resumeAlarm: (req, opts) => workloadService.resumeServiceAlarm(req, opts),
+                runAlarmNow: (req, opts) => workloadService.runServiceAlarmNow(req, opts),
+                startSignIn: (req, opts) => workloadService.startServiceSignIn(req, opts),
+                answerSignIn: (req, opts) => workloadService.answerServiceSignIn(req, opts),
+                cancelSignIn: (req, opts) => workloadService.cancelServiceSignIn(req, opts),
+                getSignInStatus: (req, opts) => workloadService.getServiceSignInStatus(req, opts),
             },
             waitOperation: (req, opts) => waitOperation(workloadService, create(WaitOperationRequestSchema, req), opts),
             listEvents: (req, opts) => workloadService.listEvents(req, opts),
             allEvents: (req, opts) => paginate(req, workloadService.listEvents, (resp) => resp.events, opts),
             watchEvents: (req, opts) => openEventWatch(workloadService, retry, create(WatchEventsRequestSchema, req), opts),
+            emitEvent: (req, opts) => workloadService.emitWorkloadEvent(req, opts),
+            holdWorkload: (req, opts) => workloadService.holdWorkload(req, opts),
+            releaseWorkload: (req, opts) => workloadService.releaseWorkload(req, opts),
             getOperation: (req, opts) => workloadService.getOperation(req, opts),
         },
         run: (req, opts) => runJob(workloadService, retry, create(CreateJobRequestSchema, req), opts),

package/dist/gen/toshi/workspace/v1/connections_pb.d.ts

@@ -20,15 +20,15 @@ export type Connection = Message<"toshi.workspace.v1.Connection"> & {
      */
     kind: ConnectionKind;
     /**
-     * Unique among the workspace's WEBHOOK connections; for GITHUB, the
-     * login of the account the App is installed on.
+     * Unique among the workspace's live connections of its kind, WEBHOOK or
+     * MAIL; for GITHUB, the login of the account the App is installed on.
      *
      * @generated from field: string name = 3;
      */
     name: string;
     /**
-     * The project and environment a WEBHOOK connection's events belong to;
-     * empty for GITHUB, whose events belong to their repository's project.
+     * The project and environment a WEBHOOK or MAIL connection's events belong
+     * to; empty for GITHUB, whose events belong to their repository's project.
      *
      * @generated from field: string project = 4;
      */
@@ -64,8 +64,8 @@ export type Connection = Message<"toshi.workspace.v1.Connection"> & {
     /**
      * The inbound address a WEBHOOK connection's sender POSTs to: the
      * deployment's public address and /ingress/ with the connection's
-     * address token. Empty for GITHUB, and when the deployment names no
-     * public address.
+     * address token. Empty for GITHUB and MAIL, and when the deployment names
+     * no public address.
      *
      * @generated from field: string ingress_url = 11;
      */
@@ -100,6 +100,13 @@ export type Connection = Message<"toshi.workspace.v1.Connection"> & {
      * @generated from field: string manifest_origin = 15;
      */
     manifestOrigin: string;
+    /**
+     * Where a MAIL connection receives mail and where it sends it; unset for
+     * the other kinds.
+     *
+     * @generated from field: toshi.workspace.v1.MailConnection mail = 16;
+     */
+    mail?: MailConnection | undefined;
 };
 /**
  * Connection is one source of a workspace's events.
@@ -116,15 +123,15 @@ export type ConnectionJson = {
      */
     kind?: ConnectionKindJson;
     /**
-     * Unique among the workspace's WEBHOOK connections; for GITHUB, the
-     * login of the account the App is installed on.
+     * Unique among the workspace's live connections of its kind, WEBHOOK or
+     * MAIL; for GITHUB, the login of the account the App is installed on.
      *
      * @generated from field: string name = 3;
      */
     name?: string;
     /**
-     * The project and environment a WEBHOOK connection's events belong to;
-     * empty for GITHUB, whose events belong to their repository's project.
+     * The project and environment a WEBHOOK or MAIL connection's events belong
+     * to; empty for GITHUB, whose events belong to their repository's project.
      *
      * @generated from field: string project = 4;
      */
@@ -160,8 +167,8 @@ export type ConnectionJson = {
     /**
      * The inbound address a WEBHOOK connection's sender POSTs to: the
      * deployment's public address and /ingress/ with the connection's
-     * address token. Empty for GITHUB, and when the deployment names no
-     * public address.
+     * address token. Empty for GITHUB and MAIL, and when the deployment names
+     * no public address.
      *
      * @generated from field: string ingress_url = 11;
      */
@@ -196,6 +203,13 @@ export type ConnectionJson = {
      * @generated from field: string manifest_origin = 15;
      */
     manifestOrigin?: string;
+    /**
+     * Where a MAIL connection receives mail and where it sends it; unset for
+     * the other kinds.
+     *
+     * @generated from field: toshi.workspace.v1.MailConnection mail = 16;
+     */
+    mail?: MailConnectionJson;
 };
 /**
  * Describes the message toshi.workspace.v1.Connection.
@@ -204,6 +218,83 @@ export type ConnectionJson = {
 export declare const ConnectionSchema: GenMessage<Connection, {
     jsonType: ConnectionJson;
 }>;
+/**
+ * MailConnection is where a MAIL connection receives mail and where it
+ * sends it.
+ *
+ * @generated from message toshi.workspace.v1.MailConnection
+ */
+export type MailConnection = Message<"toshi.workspace.v1.MailConnection"> & {
+    /**
+     * Output only. The address mail is received at: the connection's name,
+     * "@", the workspace's ID and the deployment's inbound mail domain, all
+     * lowercase.
+     *
+     * @generated from field: string address = 1;
+     */
+    address: string;
+    /**
+     * The service, by its ID, whose event channel the mail goes to.
+     *
+     * @generated from field: string service = 2;
+     */
+    service: string;
+    /**
+     * The name of that service's event channel.
+     *
+     * @generated from field: string channel = 3;
+     */
+    channel: string;
+    /**
+     * Output only. The mail provider that receives for the address, such as
+     * "ses".
+     *
+     * @generated from field: string provider = 4;
+     */
+    provider: string;
+};
+/**
+ * MailConnection is where a MAIL connection receives mail and where it
+ * sends it.
+ *
+ * @generated from message toshi.workspace.v1.MailConnection
+ */
+export type MailConnectionJson = {
+    /**
+     * Output only. The address mail is received at: the connection's name,
+     * "@", the workspace's ID and the deployment's inbound mail domain, all
+     * lowercase.
+     *
+     * @generated from field: string address = 1;
+     */
+    address?: string;
+    /**
+     * The service, by its ID, whose event channel the mail goes to.
+     *
+     * @generated from field: string service = 2;
+     */
+    service?: string;
+    /**
+     * The name of that service's event channel.
+     *
+     * @generated from field: string channel = 3;
+     */
+    channel?: string;
+    /**
+     * Output only. The mail provider that receives for the address, such as
+     * "ses".
+     *
+     * @generated from field: string provider = 4;
+     */
+    provider?: string;
+};
+/**
+ * Describes the message toshi.workspace.v1.MailConnection.
+ * Use `create(MailConnectionSchema)` to create a new message.
+ */
+export declare const MailConnectionSchema: GenMessage<MailConnection, {
+    jsonType: MailConnectionJson;
+}>;
 /**
  * ConnectionTarget is the URL a WEBHOOK connection's deliveries are posted
  * to: each delivery's event, as the event log would hold it, signed as
@@ -410,7 +501,8 @@ export declare const GetConnectionResponseSchema: GenMessage<GetConnectionRespon
  */
 export type CreateConnectionRequest = Message<"toshi.workspace.v1.CreateConnectionRequest"> & {
     /**
-     * WEBHOOK; no other kind is created here.
+     * The kind to create: WEBHOOK or MAIL. Installing the GitHub App creates
+     * a GITHUB connection.
      *
      * @generated from field: toshi.workspace.v1.ConnectionKind kind = 1;
      */
@@ -422,6 +514,10 @@ export type CreateConnectionRequest = Message<"toshi.workspace.v1.CreateConnecti
      */
     name: string;
     /**
+     * The project and environment the connection's events belong to. Both
+     * are required for WEBHOOK. For MAIL they are optional, and when set must
+     * be the service's.
+     *
      * @generated from field: string project = 3;
      */
     project: string;
@@ -433,13 +529,22 @@ export type CreateConnectionRequest = Message<"toshi.workspace.v1.CreateConnecti
      * @generated from field: string request_key = 5;
      */
     requestKey: string;
+    /**
+     * The mail address and where its mail goes, for a MAIL connection; unset
+     * for WEBHOOK. service and channel are required; address and provider are
+     * output only, and ignored on input.
+     *
+     * @generated from field: toshi.workspace.v1.MailConnection mail = 6;
+     */
+    mail?: MailConnection | undefined;
 };
 /**
  * @generated from message toshi.workspace.v1.CreateConnectionRequest
  */
 export type CreateConnectionRequestJson = {
     /**
-     * WEBHOOK; no other kind is created here.
+     * The kind to create: WEBHOOK or MAIL. Installing the GitHub App creates
+     * a GITHUB connection.
      *
      * @generated from field: toshi.workspace.v1.ConnectionKind kind = 1;
      */
@@ -451,6 +556,10 @@ export type CreateConnectionRequestJson = {
      */
     name?: string;
     /**
+     * The project and environment the connection's events belong to. Both
+     * are required for WEBHOOK. For MAIL they are optional, and when set must
+     * be the service's.
+     *
      * @generated from field: string project = 3;
      */
     project?: string;
@@ -462,6 +571,14 @@ export type CreateConnectionRequestJson = {
      * @generated from field: string request_key = 5;
      */
     requestKey?: string;
+    /**
+     * The mail address and where its mail goes, for a MAIL connection; unset
+     * for WEBHOOK. service and channel are required; address and provider are
+     * output only, and ignored on input.
+     *
+     * @generated from field: toshi.workspace.v1.MailConnection mail = 6;
+     */
+    mail?: MailConnectionJson;
 };
 /**
  * Describes the message toshi.workspace.v1.CreateConnectionRequest.
@@ -480,7 +597,8 @@ export type CreateConnectionResponse = Message<"toshi.workspace.v1.CreateConnect
     connection?: Connection | undefined;
     /**
      * The signing secret in its whsec_ form, for the sender to sign its
-     * requests with. Shown only in this answer and an identical retry's.
+     * requests with; empty for a MAIL connection. Shown only in this answer
+     * and an identical retry's.
      *
      * @generated from field: string secret = 2;
      */
@@ -496,7 +614,8 @@ export type CreateConnectionResponseJson = {
     connection?: ConnectionJson;
     /**
      * The signing secret in its whsec_ form, for the sender to sign its
-     * requests with. Shown only in this answer and an identical retry's.
+     * requests with; empty for a MAIL connection. Shown only in this answer
+     * and an identical retry's.
      *
      * @generated from field: string secret = 2;
      */
@@ -1266,14 +1385,22 @@ export declare enum ConnectionKind {
      *
      * @generated from enum value: CONNECTION_KIND_WEBHOOK = 2;
      */
-    WEBHOOK = 2
+    WEBHOOK = 2,
+    /**
+     * An inbound mail address. The deployment's mail provider receives the
+     * messages; each is stored as a receipt before it goes to a service's
+     * event channel.
+     *
+     * @generated from enum value: CONNECTION_KIND_MAIL = 3;
+     */
+    MAIL = 3
 }
 /**
  * ConnectionKind is the kind of source a connection receives events from.
  *
  * @generated from enum toshi.workspace.v1.ConnectionKind
  */
-export type ConnectionKindJson = "CONNECTION_KIND_UNSPECIFIED" | "CONNECTION_KIND_GITHUB" | "CONNECTION_KIND_WEBHOOK";
+export type ConnectionKindJson = "CONNECTION_KIND_UNSPECIFIED" | "CONNECTION_KIND_GITHUB" | "CONNECTION_KIND_WEBHOOK" | "CONNECTION_KIND_MAIL";
 /**
  * Describes the enum toshi.workspace.v1.ConnectionKind.
  */
@@ -1330,7 +1457,10 @@ export declare const ConnectionDeliveryStateSchema: GenEnum<ConnectionDeliverySt
  * GITHUB, which installing the App creates and removing it deletes; the
  * calls here list it and cannot create or delete it. A WEBHOOK connection
  * receives events from a sender that signs its requests as Standard
- * Webhooks does, with a secret the connection keeps.
+ * Webhooks does, with a secret the connection keeps. A MAIL connection
+ * receives mail at an address the deployment's inbound mail provider
+ * serves; each message is stored as a receipt before it goes to a
+ * service's event channel.
  *
  * The caller's credential names the workspace, as for WorkloadService.
  * CreateConnection and RotateConnectionSecret require a request_key, which
@@ -1367,11 +1497,15 @@ export declare const ConnectionService: GenService<{
         output: typeof GetConnectionResponseSchema;
     };
     /**
-     * CreateConnection creates a WEBHOOK connection whose events belong to a
-     * project's environment, and returns it with its signing secret. A kind
-     * other than WEBHOOK fails with INVALID_ARGUMENT, a name a live
-     * connection of the workspace has with ALREADY_EXISTS, and an
-     * environment the project does not have with NOT_FOUND.
+     * CreateConnection creates a WEBHOOK or MAIL connection. A WEBHOOK
+     * connection's events belong to a project's environment, and the call
+     * returns it with its signing secret. A MAIL connection receives mail at
+     * an address the deployment's inbound mail provider serves and sends each
+     * message to a service's event channel; it has no secret. A kind other
+     * than WEBHOOK or MAIL fails with INVALID_ARGUMENT, as does a missing
+     * required field, a name a live connection of the workspace has with
+     * ALREADY_EXISTS, and an environment the project does not have with
+     * NOT_FOUND.
      *
      * @generated from rpc toshi.workspace.v1.ConnectionService.CreateConnection
      */
@@ -1381,11 +1515,12 @@ export declare const ConnectionService: GenService<{
         output: typeof CreateConnectionResponseSchema;
     };
     /**
-     * DeleteConnection deletes a WEBHOOK connection: its events are no longer
-     * received. A GITHUB connection fails with FAILED_PRECONDITION, as only
-     * removing the GitHub App deletes it, as does one that live triggers match
-     * events from, naming them as project/name, and one the workspace does
-     * not have with NOT_FOUND.
+     * DeleteConnection deletes a WEBHOOK or MAIL connection: its events are no
+     * longer received, and a mail connection's address takes no more mail. A
+     * GITHUB connection fails with FAILED_PRECONDITION, as only removing the
+     * GitHub App deletes it, as does one that live triggers match events from,
+     * naming them as project/name, and one the workspace does not have with
+     * NOT_FOUND.
      *
      * @generated from rpc toshi.workspace.v1.ConnectionService.DeleteConnection
      */