@toshicloud/sdk 0.4.0 → 0.5.1

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,13 +138,16 @@ 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` and `storageProvider`, 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). 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
 `toshi run` sits at the top of the CLI.
@@ -156,7 +162,8 @@ console.log(job?.id);
 
 ### 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 +197,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 +209,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.
@@ -305,6 +332,57 @@ await run.wait(); // rejects with JobExitError on a non-zero exit
 Stopping the loop stops only the output stream: the job keeps running,
 and `workload.jobs.cancel` ends it.
 
+## Products that are off
+
+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.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";
+
+import { toshi } from "./client.js";
+
+// Turn a product on for the workspace.
+const enable = { id: "acme_ci", enabled: true };
+try {
+  await toshi.product.updateProduct(enable);
+} catch (err) {
+  if (!isProductError(err)) {
+    throw err;
+  }
+  // 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,
@@ -340,17 +418,21 @@ first, with the procedure, the request and the headers.
 [`protoc-gen-es`](https://github.com/bufbuild/protobuf-es) from the protos
 in `proto/toshi/workspace/v1` of the
 [toshi-api](https://github.com/toshicloud/toshi-api) repository, one
-`*_pb.ts` file per proto. The generated code is committed and imports
+`*_pb.ts` file per proto, and `src/gen/toshi/permission_pb.ts` from
+`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:
+`2184ae8440834bb5b91991b3e4d62d14ce9dd15a` today, the commit of the
+release tag `v0.4.1`. `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
 ```
 
@@ -364,7 +446,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,24 +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 { 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, 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 { 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 type { RetryPolicy } from "./retry.js";
 /** How the client is configured; the caller builds the transport. */
 export interface ToshiOptions {
@@ -63,7 +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. */
@@ -103,9 +123,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 {
@@ -127,6 +154,14 @@ 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>;
 }
 /** A live stream of a job's changes. */
 export interface JobWatch extends AsyncIterable<WatchJobsResponse> {
@@ -181,8 +216,9 @@ export interface JobRun extends AsyncIterable<OutputChunk> {
     wait(): Promise<void>;
 }
 /**
- * Creates the client: one normalized retry setting, the scope, key, retry and
- * auth interceptors (scope outermost, auth innermost, so no interceptor sees
+ * Creates the client: one normalized retry setting, the product, scope, key,
+ * retry and auth interceptors (product outermost, so a product's refusal
+ * reaches the caller as a ProductError; auth innermost, so no interceptor sees
  * the Authorization header), one transport for every client and helper.
  *
  * Since 0.2.0 the workload calls are grouped by the type they name under

package/dist/client.js

@@ -1,34 +1,45 @@
 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 { 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, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_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 { openOutputWatch } from "./output.js";
 import { paginate } from "./paginate.js";
-import { authInterceptor, keyInterceptor, 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";
 import { runJob } from "./run.js";
 import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 /**
- * Creates the client: one normalized retry setting, the scope, key, retry and
- * auth interceptors (scope outermost, auth innermost, so no interceptor sees
+ * Creates the client: one normalized retry setting, the product, scope, key,
+ * retry and auth interceptors (product outermost, so a product's refusal
+ * reaches the caller as a ProductError; auth innermost, so no interceptor sees
  * the Authorization header), one transport for every client and helper.
  *
  * Since 0.2.0 the workload calls are grouped by the type they name under
@@ -38,6 +49,7 @@ import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 export function createToshiClient(options) {
     const retry = normalizeRetry(options.retry);
     const interceptors = [
+        refusalInterceptor(),
         scopeInterceptor(options.project ?? "", options.environment ?? ""),
         keyInterceptor(),
         retryInterceptor(retry),
@@ -75,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),
@@ -96,6 +114,10 @@ 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),
             },
             waitOperation: (req, opts) => waitOperation(workloadService, create(WaitOperationRequestSchema, req), opts),
             listEvents: (req, opts) => workloadService.listEvents(req, opts),
@@ -110,6 +132,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),
     };
 }

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { ConnectError } from "@connectrpc/connect";
 import type { ExecutionExit, OutputEnd } from "./gen/toshi/workspace/v1/workspace_pb.js";
 /** A command that ended non-zero, or was cancelled before it had a status (errors.go:9-26). */
 export declare class ExitError extends Error {
@@ -26,3 +27,101 @@ export declare class StreamLostError extends Error {
     readonly requestKey: string;
     constructor(executionId: string, requestKey: string, cause?: unknown);
 }
+/** Why the API refused a call for a product: the reason of the refusal's ErrorInfo detail. */
+export type ProductReason = "PRODUCT_UNAVAILABLE";
+/** The reasons a call is refused for a product. */
+export declare const ProductReason: {
+    /**
+     * The product is off for the workspace; the code is FailedPrecondition, and
+     * `cause` says which input turned it off.
+     */
+    readonly Unavailable: "PRODUCT_UNAVAILABLE";
+};
+/** The input that turned a product off: a ProductError's `cause`. */
+export type ProductCause = "build" | "operator" | "plan" | "workspace";
+/** The inputs that turn a product off. */
+export declare const ProductCause: {
+    /** The deployment's build does not include the product. */
+    readonly Build: "build";
+    /** The deployment's config turns the product off. */
+    readonly Operator: "operator";
+    /** The workspace's plan leaves the product out. */
+    readonly Plan: "plan";
+    /** The workspace's settings turn the product off. */
+    readonly Workspace: "workspace";
+};
+/**
+ * Why the API refused a call and named the reason: the reason of the
+ * refusal's ErrorInfo detail, for a refusal that is not a product's.
+ */
+export type RefusalReason = "DISPLAY_INPUT_NOT_ENABLED" | "IMAGE_BUILD_IN_PROGRESS" | "IMAGE_CHECK_FAILED" | "IMAGE_IN_USE" | "IMAGE_NAME_TAKEN" | "IMAGE_NOT_READY" | "IMAGE_NOT_SERVED" | "LAST_IDENTITY" | "LAST_MEMBER" | "LAST_OWNER" | "PERMISSION_MISSING" | "PLAN_EXCLUDES_IMAGES" | "TOSHI_LICENSED_WINDOWS";
+/** The reasons the API names on a refusal that is not a product's. */
+export declare const RefusalReason: {
+    /** The Windows VM takes no display input; the code is FailedPrecondition. */
+    readonly DisplayInputNotEnabled: "DISPLAY_INPUT_NOT_ENABLED";
+    /** The image already has a build running; the code is FailedPrecondition. */
+    readonly ImageBuildInProgress: "IMAGE_BUILD_IN_PROGRESS";
+    /** The registry of the revision's image could not say whether it serves the digest; the code is FailedPrecondition. */
+    readonly ImageCheckFailed: "IMAGE_CHECK_FAILED";
+    /** A workload or a service revision still uses the image; the code is FailedPrecondition. */
+    readonly ImageInUse: "IMAGE_IN_USE";
+    /** Another live image of the workspace has the name; the code is AlreadyExists. */
+    readonly ImageNameTaken: "IMAGE_NAME_TAKEN";
+    /** A workspace image named by a job, a sandbox or a service revision has no ready version; the code is FailedPrecondition. */
+    readonly ImageNotReady: "IMAGE_NOT_READY";
+    /** The revision's registry answered that it does not serve the image digest; the code is FailedPrecondition. */
+    readonly ImageNotServed: "IMAGE_NOT_SERVED";
+    /** The call would remove the caller's last identity; the code is FailedPrecondition. */
+    readonly LastIdentity: "LAST_IDENTITY";
+    /** The call would remove the workspace's last member; the code is FailedPrecondition. */
+    readonly LastMember: "LAST_MEMBER";
+    /** The call would leave the workspace without an owner; the code is FailedPrecondition. */
+    readonly LastOwner: "LAST_OWNER";
+    /** A role change names a permission the caller does not hold where the role applies; the code is PermissionDenied. */
+    readonly PermissionMissing: "PERMISSION_MISSING";
+    /** The workspace's plan does not include images; the code is FailedPrecondition. */
+    readonly PlanExcludesImages: "PLAN_EXCLUDES_IMAGES";
+    /** A Windows job Toshi licenses opens no display session; the code is FailedPrecondition. */
+    readonly ToshiLicensedWindows: "TOSHI_LICENSED_WINDOWS";
+};
+/**
+ * The API's refusal of a call for a product that is off for the workspace.
+ * Every call the client makes throws it in place of the ConnectError, wait,
+ * watch and execute included. It is a ConnectError, so `instanceof
+ * ConnectError` and `code` read as before; test for it with
+ * {@link isProductError}.
+ */
+export declare class ProductError extends ConnectError {
+    /** The product's ID, such as `runners`. */
+    readonly product: string;
+    readonly reason: ProductReason;
+    /** The input that turned the product off, the refusal's `cause` metadata: `build`, `operator`, `plan` or `workspace`. */
+    readonly productCause: ProductCause;
+    /** How far a product the deployment turns off has wound down: `no_new_work`, `draining` or `stopped`; empty otherwise. */
+    readonly state: string;
+    constructor(err: ConnectError, reason: ProductReason, metadata: ReadonlyMap<string, string>);
+    static [Symbol.hasInstance](v: unknown): boolean;
+}
+/** Reports whether err is a product's refusal. */
+export declare function isProductError(err: unknown): err is ProductError;
+/**
+ * The API's refusal that names a reason: an image still in use, a plan
+ * without images, a last identity, a rollback whose revision's image is gone,
+ * and the rest of {@link RefusalReason}. Every call the client makes throws
+ * it in place of the ConnectError. It is a ConnectError, so `instanceof
+ * ConnectError` and `code` read as before; test for it with
+ * {@link isRefusalError}.
+ */
+export declare class RefusalError extends ConnectError {
+    readonly reason: RefusalReason;
+    constructor(err: ConnectError, reason: RefusalReason);
+    static [Symbol.hasInstance](v: unknown): boolean;
+}
+/** Reports whether err is a refusal that names a reason this module knows. */
+export declare function isRefusalError(err: unknown): err is RefusalError;
+/** err as a ProductError when it is a product's refusal, and err unchanged otherwise. */
+export declare function asProductError(err: unknown): unknown;
+/** err as a RefusalError when it is a refusal that names a reason this module knows, and err unchanged otherwise. */
+export declare function asRefusalError(err: unknown): unknown;
+/** err as one of this module's typed errors when the API's ErrorInfo detail names a reason it knows, and err unchanged otherwise. */
+export declare function asTypedError(err: unknown): unknown;