@toshicloud/sdk 0.5.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ A TypeScript client for the Toshi Workspace API, `toshi.workspace.v1`,
 published as ES modules with type declarations.
 
 ```sh
-npm install @toshicloud/sdk @connectrpc/connect
+npm install @toshicloud/sdk @bufbuild/protobuf @connectrpc/connect
 ```
 
 The browser entry needs a transport such as `@connectrpc/connect-web`; the
@@ -68,13 +68,16 @@ entry reads `TOSHI_SERVER`, `TOSHI_TOKEN`, `TOSHI_TOKEN_FILE` and
   `environment` fields when they are empty. A value in the request wins.
   `environment` is left empty on a request with `shared: true`.
 - `retry`: `{ maxAttempts, initialBackoffMs, maxBackoffMs }`, by default
-  5, 200 ms and 10 s, with full jitter. `retry: false` turns off retries
-  and watch reconnects.
+  5, 200 ms and 10 s, with full jitter. Reads, and the calls whose request
+  takes a `request_key`, are retried; a stream and every other call is not.
+  `retry: false` turns off retries and watch reconnects.
 - `defaultTimeoutMs`: bounds each unary call except the Wait calls,
   which their request's timeout bounds; streams ignore it.
 
 A call may set `timeoutMs` instead: it bounds the whole call, retries
 included, and on a watch it bounds the open. It composes with `signal`.
+`ToshiOptions` is the object the client takes, and `CallOptions` the second
+argument of each call, which carries `signal` and `timeoutMs`.
 
 ### Node options
 
@@ -135,15 +138,25 @@ picked up without a new client.
 The client has one field per Workspace API service: `project`, `secret`,
 `webhook`, `display`, `channel`, `recording`, `volume`, `artifact`,
 `artifactUpload`, `workspace`, `hostJob`, `host`, `token`, `auditEvent`,
-`filler`, `storageProvider`, `product` and `discovery`, each holding that
-service's generated client.
+`filler`, `grant`, `storageProvider`, `product`, `discovery`, `connection`,
+`role`, `trigger`, `account`, `image` and `domain`, each holding that service's
+generated client.
 `workload` holds `WorkloadService`'s calls, grouped by the type they
 name: `workload.jobs`, `workload.sandboxes` and `workload.services`, one
-method for each call (`create`, `get`, `list`, `update`, `delete`,
-`wait`, `watch`, and `cancel` on a job, `execute` on a sandbox, `start`,
-`stop`, `setMode`, `listRuns`, `wake`, `hold` and `release` on a service). The calls that
+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). 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 -->
@@ -154,9 +167,53 @@ 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`, `workload.services.all`,
+`workload.jobs.all`, `workload.sandboxes.all`,
+`workload.sandboxes.allPreviewShareLinks`, `workload.services.all`,
 `workload.services.allRuns` and `workload.allEvents` take the request their
 `list` method takes and yield every item, one page after another. Each
 response's `nextPageToken` becomes the next request's `pageToken`, and a
@@ -190,6 +247,9 @@ for await (const project of paginate(
 fields. Every page is a call of its own, so `opts` goes to each one, and
 `timeoutMs` bounds a page and not the whole iteration. An error throws once
 and ends the iteration; leaving the loop sends no further request.
+`PageRequest` is a list request, which may name the page to read first with
+`pageToken`, and `PageResponse` a list response, which names the page after
+it with `nextPageToken`.
 
 ### Retries
 
@@ -199,18 +259,35 @@ connection reset or destroyed stream that `@connectrpc/connect-node`
 reports, or a stream the server refused before reading it
 (`REFUSED_STREAM`). A write that takes a request key gets a random one when the
 request has none, so the server applies a retried write once. Other
-writes are never retried. An error the server sends, including
-`Aborted`, `InvalidArgument` and `ResourceExhausted`, reaches the caller
-unchanged. So does any connection failure the client cannot tell apart
-from a server error.
+writes are never retried.
+
+A `ResourceExhausted` refusal that names how long to wait, as the API's
+rate limit does, is retried the same way. The wait comes from its
+`google.rpc.RetryInfo` detail, else from its `Retry-After` header. So is an
+HTTP 429 with a `Retry-After`, which reaches the client as `Unavailable`.
+The client waits the longer of that wait and the backoff, never more than
+`maxBackoffMs`, and stops when the call's signal aborts. A
+`ResourceExhausted` that names no wait, such as a plan's limit, reaches the
+caller unchanged, as do every other error the server sends, including
+`Aborted` and `InvalidArgument`, and any connection failure the client
+cannot tell apart from a server error.
+
+`RetryPolicy` says how often and how long a call is retried, `maxAttempts`
+counting the first try; `defaultRetryPolicy` is the default — five
+attempts, a 200 ms initial backoff and a 10 s cap.
 
 ### Waiting and watching
 
 - `workload.jobs.wait(req)`, `workload.sandboxes.wait(req)` and
   `workload.services.wait(req)` ask again until the workload reaches the
-  state; `workload.waitOperation(req)` asks until the operation is done.
+  state; `workload.waitOperation(req)` asks until the operation is done. A
+  call starts at least a second, and at most 1.2 seconds, after the start of
+  the one before, and a signal ends a pause with its own error.
 - `workload.getOperation(req)` returns one operation by id: a call that
   takes long hands one back, and this asks for it again.
+- An event's payload says what happened: a trigger's `TriggerResult` names
+  the key's `reason` and its workload, and with `process_exited` or
+  `setup_failed` it carries the sandbox's `exitCode` and `message`.
 - `workload.listEvents(req)` returns the events after a cursor, oldest
   first, a page at a time, for a client that polls or catches up after
   downtime; `workload.watchEvents(req)` is the live form.
@@ -307,44 +384,55 @@ and `workload.jobs.cancel` ends it.
 
 ## Products that are off
 
-A call for a product that is off for the workspace, or that turns on an
-outside product without accepting the access it asks for, rejects with a
+A call for a product that is off for the workspace rejects with a
 `ProductError`, `wait`, the watches and `execute` included.
 `isProductError(err)` tells it apart. It is still a `ConnectError` with the
 same `code`, and it has the product's ID (`product`), the `reason`
-(`ProductReason.NotInstalled`, `Disabled`, `NotEntitled`, `TurnedOff` or
-`AccessNotAccepted`), the setting that turns the product on (`feature`,
-such as `runners.enabled`), how far a product the deployment disables has
-wound down (`state`) and, for `AccessNotAccepted`, the access to accept
-(`access`).
+(`ProductReason.Unavailable`), the input that turned the product off
+(`productCause`: `build`, `operator`, `plan` or `workspace`) and, for a
+product the deployment turns off, how far it has wound down (`state`:
+`no_new_work`, `draining` or `stopped`).
 
 <!-- examples/product-error.ts -->
 
 ```ts
+import { isProductError } from "@toshicloud/sdk";
 
-// Turning an outside product on installs it, and the API asks the caller to
-// accept the access it wants first.
-const enable = { id: "acme_ci", enabled: true, acceptedAccess: [] as string[] };
+import { toshi } from "./client.js";
+
+// Turn a product on for the workspace.
+const enable = { id: "acme_ci", enabled: true };
 try {
-  try {
-    await toshi.product.updateProduct(enable);
-  } catch (err) {
-    if (!isProductError(err) || err.reason !== ProductReason.AccessNotAccepted) {
-      throw err;
-    }
-    console.log(err.product, err.reason, err.access);
-    // Accept exactly the access the product asks for.
-    await toshi.product.updateProduct({ ...enable, acceptedAccess: err.access });
-  }
+  await toshi.product.updateProduct(enable);
 } catch (err) {
   if (!isProductError(err)) {
     throw err;
   }
-  // Off for the workspace: say which product and why.
-  console.log(err.product, err.reason, err.feature);
+  // Off for the workspace: which product, the input that turns it off, and,
+  // for the deployment's config, how far it has wound down.
+  console.log(err.product, err.productCause, err.state);
 }
 ```
 
+## Refusals with a reason
+
+A refusal that is not a product's rejects with a `RefusalError`;
+`isRefusalError(err)` tells it apart. It is still a `ConnectError` with the
+same `code`, and its `reason` is one of `RefusalReason`:
+`RefusalReason.ImageInUse` when an image a workload or a revision still uses
+cannot be deleted, `RefusalReason.ImageNotReady` when a job, a sandbox or a
+service revision names a workspace image with no ready version,
+`RefusalReason.PlanExcludesImages` when the plan has no images, `RefusalReason.LastIdentity` when the caller's last identity cannot
+be unlinked, and so on for images, volumes, roles and display sessions.
+
+`workload.services.rollback` asks the revision's registry whether it still
+serves the revision's image before it selects it, and refuses with
+`RefusalReason.ImageNotServed` when the registry answered that it does not
+serve the image, or `RefusalReason.ImageCheckFailed` when it could not say.
+A revision's `imageCheck` carries the last answer: its `outcome`, the
+registry's `status` and `message`, and when it was asked, `checkedAt`.
+Reading a revision asks no registry.
+
 ## Testing with `@toshicloud/sdk/test`
 
 `createFake()` serves the whole Workspace API in memory: no server, no port,
@@ -369,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
@@ -384,14 +476,18 @@ in `proto/toshi/workspace/v1` of the
 `proto/toshi/permission.proto`, which they import. The generated code is committed and imports
 only `@bufbuild/protobuf`, so installing the package needs no generator.
 
-`pin.env` names the toshi-api commit (or, once one exists, the release
-tag) the code is generated from. `mise.toml` pins the versions of Node,
-pnpm, `buf` and `protoc-gen-es`.
+`pin.env` names the toshi-api commit the code is generated from:
+`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.
 
 To regenerate:
 
 ```sh
 mise install
+pnpm install --frozen-lockfile
 mise exec -- scripts/generate.sh
 ```
 
@@ -405,7 +501,8 @@ and fails if the result differs from what is committed
 The package's major version follows the API's: `1.x` will serve
 `toshi.workspace.v1`, and a `toshi.workspace.v2` gets a new major
 version. Until a Toshi release serves the API, the package stays at
-`0.x` and is generated from a pinned commit.
+`0.x` and is generated from a pinned commit. `VERSION` is the package
+version, the one `package.json` carries.
 
 ## Publishing
 

package/dist/client.d.ts

@@ -1,26 +1,35 @@
 import type { MessageInitShape } from "@bufbuild/protobuf";
 import type { Client, Interceptor, Transport } from "@connectrpc/connect";
+import { AccountService } from "./gen/toshi/workspace/v1/account_pb.js";
 import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
 import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
 import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
+import { ConnectionService } from "./gen/toshi/workspace/v1/connections_pb.js";
 import { DiscoveryService } from "./gen/toshi/workspace/v1/discovery_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
+import { DomainService } from "./gen/toshi/workspace/v1/domains_pb.js";
 import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
+import { GrantService } from "./gen/toshi/workspace/v1/grants_pb.js";
+import { ImageService } from "./gen/toshi/workspace/v1/images_pb.js";
 import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
 import { ProductService } from "./gen/toshi/workspace/v1/products_pb.js";
 import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
 import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
+import { RoleService } from "./gen/toshi/workspace/v1/roles_pb.js";
 import { SecretService } from "./gen/toshi/workspace/v1/secrets_pb.js";
 import { StorageProviderService } from "./gen/toshi/workspace/v1/storage_providers_pb.js";
 import { TokenService } from "./gen/toshi/workspace/v1/tokens_pb.js";
+import { TriggerService } from "./gen/toshi/workspace/v1/triggers_pb.js";
 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 { 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, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import type { Event, GetOperationResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceRunsResponse, Operation, ReleaseServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_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, 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 {
@@ -65,9 +74,16 @@ export interface ToshiClient {
     readonly token: Client<typeof TokenService>;
     readonly auditEvent: Client<typeof AuditEventService>;
     readonly filler: Client<typeof FillerService>;
+    readonly grant: Client<typeof GrantService>;
     readonly storageProvider: Client<typeof StorageProviderService>;
     readonly product: Client<typeof ProductService>;
     readonly discovery: Client<typeof DiscoveryService>;
+    readonly connection: Client<typeof ConnectionService>;
+    readonly role: Client<typeof RoleService>;
+    readonly trigger: Client<typeof TriggerService>;
+    readonly account: Client<typeof AccountService>;
+    readonly image: Client<typeof ImageService>;
+    readonly domain: Client<typeof DomainService>;
     run(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<JobRun>;
 }
 /** WorkloadService's calls, grouped by the type they name. */
@@ -81,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>;
 }
@@ -107,9 +139,16 @@ export interface SandboxesClient {
     all(req: MessageInitShape<typeof ListSandboxesRequestSchema>, opts?: CallOptions): AsyncIterable<Sandbox>;
     update(req: MessageInitShape<typeof UpdateSandboxRequestSchema>, opts?: CallOptions): Promise<UpdateSandboxResponse>;
     delete(req: MessageInitShape<typeof DeleteSandboxRequestSchema>, opts?: CallOptions): Promise<DeleteSandboxResponse>;
+    stop(req: MessageInitShape<typeof StopSandboxRequestSchema>, opts?: CallOptions): Promise<StopSandboxResponse>;
+    start(req: MessageInitShape<typeof StartSandboxRequestSchema>, opts?: CallOptions): Promise<StartSandboxResponse>;
     wait(req: MessageInitShape<typeof WaitSandboxRequestSchema>, opts?: CallOptions): Promise<WaitSandboxResponse>;
     watch(req: MessageInitShape<typeof WatchSandboxesRequestSchema>, opts?: CallOptions): Promise<SandboxWatch>;
     execute(start: MessageInitShape<typeof ExecuteStartSchema>, opts?: CallOptions): Promise<Process>;
+    createPreviewShareLink(req: MessageInitShape<typeof CreatePreviewShareLinkRequestSchema>, opts?: CallOptions): Promise<CreatePreviewShareLinkResponse>;
+    listPreviewShareLinks(req: MessageInitShape<typeof ListPreviewShareLinksRequestSchema>, opts?: CallOptions): Promise<ListPreviewShareLinksResponse>;
+    /** Yields every share link that matches every filter that is set, following the page token from one page to the next. */
+    allPreviewShareLinks(req: MessageInitShape<typeof ListPreviewShareLinksRequestSchema>, opts?: CallOptions): AsyncIterable<PreviewShareLink>;
+    revokePreviewShareLink(req: MessageInitShape<typeof RevokePreviewShareLinkRequestSchema>, opts?: CallOptions): Promise<RevokePreviewShareLinkResponse>;
 }
 /** A service's calls: one method for each of WorkloadService's service calls. */
 export interface ServicesClient {
@@ -131,6 +170,66 @@ export interface ServicesClient {
     listRuns(req: MessageInitShape<typeof ListServiceRunsRequestSchema>, opts?: CallOptions): Promise<ListServiceRunsResponse>;
     /** Yields every run listRuns returns, the newest first, following the page token from one page to the next. */
     allRuns(req: MessageInitShape<typeof ListServiceRunsRequestSchema>, opts?: CallOptions): AsyncIterable<ServiceRun>;
+    /** Returns a service's revisions, oldest first. */
+    listRevisions(req: MessageInitShape<typeof ListServiceRevisionsRequestSchema>, opts?: CallOptions): Promise<ListServiceRevisionsResponse>;
+    /** Returns one revision of a service. */
+    getRevision(req: MessageInitShape<typeof GetServiceRevisionRequestSchema>, opts?: CallOptions): Promise<GetServiceRevisionResponse>;
+    /** Selects a revision the service already has as its current one. */
+    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

@@ -1,28 +1,36 @@
 import { create } from "@bufbuild/protobuf";
 import { createClient } from "@connectrpc/connect";
 import { executeCommand } from "./execute.js";
+import { AccountService } from "./gen/toshi/workspace/v1/account_pb.js";
 import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
 import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
 import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
+import { ConnectionService } from "./gen/toshi/workspace/v1/connections_pb.js";
 import { DiscoveryService } from "./gen/toshi/workspace/v1/discovery_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
+import { DomainService } from "./gen/toshi/workspace/v1/domains_pb.js";
 import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
+import { GrantService } from "./gen/toshi/workspace/v1/grants_pb.js";
+import { ImageService } from "./gen/toshi/workspace/v1/images_pb.js";
 import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
 import { ProductService } from "./gen/toshi/workspace/v1/products_pb.js";
 import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
 import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
+import { RoleService } from "./gen/toshi/workspace/v1/roles_pb.js";
 import { SecretService } from "./gen/toshi/workspace/v1/secrets_pb.js";
 import { StorageProviderService } from "./gen/toshi/workspace/v1/storage_providers_pb.js";
 import { TokenService } from "./gen/toshi/workspace/v1/tokens_pb.js";
+import { TriggerService } from "./gen/toshi/workspace/v1/triggers_pb.js";
 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 { 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, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { CreatePreviewShareLinkRequestSchema, ListPreviewShareLinksRequestSchema, RevokePreviewShareLinkRequestSchema, StartSandboxRequestSchema, StopSandboxRequestSchema, } 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, productInterceptor, retryInterceptor, scopeInterceptor, } from "./interceptors.js";
+import { authInterceptor, keyInterceptor, refusalInterceptor, retryInterceptor, scopeInterceptor, } from "./interceptors.js";
 import { normalizeRetry } from "./retry.js";
 import { withDefaultUnaryTimeout } from "./timeout.js";
 import { openEventWatch, openJobWatch, openSandboxWatch, openServiceWatch } from "./watch.js";
@@ -41,7 +49,7 @@ import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 export function createToshiClient(options) {
     const retry = normalizeRetry(options.retry);
     const interceptors = [
-        productInterceptor(),
+        refusalInterceptor(),
         scopeInterceptor(options.project ?? "", options.environment ?? ""),
         keyInterceptor(),
         retryInterceptor(retry),
@@ -79,9 +87,15 @@ export function createToshiClient(options) {
                 all: (req, opts) => paginate(req, workloadService.listSandboxes, (resp) => resp.sandboxes, opts),
                 update: (req, opts) => workloadService.updateSandbox(req, opts),
                 delete: (req, opts) => workloadService.deleteSandbox(req, opts),
+                stop: (req, opts) => workloadService.stopSandbox(req, opts),
+                start: (req, opts) => workloadService.startSandbox(req, opts),
                 wait: (req, opts) => waitSandbox(workloadService, create(WaitSandboxRequestSchema, req), opts),
                 watch: (req, opts) => openSandboxWatch(workloadService, retry, create(WatchSandboxesRequestSchema, req), opts),
                 execute: (start, opts) => executeCommand(workloadService, start, opts),
+                createPreviewShareLink: (req, opts) => workloadService.createPreviewShareLink(req, opts),
+                listPreviewShareLinks: (req, opts) => workloadService.listPreviewShareLinks(req, opts),
+                allPreviewShareLinks: (req, opts) => paginate(req, workloadService.listPreviewShareLinks, (resp) => resp.shareLinks, opts),
+                revokePreviewShareLink: (req, opts) => workloadService.revokePreviewShareLink(req, opts),
             },
             services: {
                 create: (req, opts) => workloadService.createService(req, opts),
@@ -100,11 +114,29 @@ export function createToshiClient(options) {
                 hold: (req, opts) => workloadService.holdService(req, opts),
                 listRuns: (req, opts) => workloadService.listServiceRuns(req, opts),
                 allRuns: (req, opts) => paginate(req, workloadService.listServiceRuns, (resp) => resp.runs, opts),
+                listRevisions: (req, opts) => workloadService.listServiceRevisions(req, opts),
+                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),
@@ -114,8 +146,15 @@ export function createToshiClient(options) {
         token: createClient(TokenService, transport),
         auditEvent: createClient(AuditEventService, transport),
         filler: createClient(FillerService, transport),
+        grant: createClient(GrantService, transport),
         storageProvider: createClient(StorageProviderService, transport),
         product: createClient(ProductService, transport),
         discovery: createClient(DiscoveryService, transport),
+        connection: createClient(ConnectionService, transport),
+        role: createClient(RoleService, transport),
+        trigger: createClient(TriggerService, transport),
+        account: createClient(AccountService, transport),
+        image: createClient(ImageService, transport),
+        domain: createClient(DomainService, transport),
     };
 }