@toshicloud/sdk 0.5.0 → 0.5.1

package/dist/errors.js

@@ -79,29 +79,58 @@ function describe(cause) {
 }
 /** The reasons a call is refused for a product. */
 export const ProductReason = {
-    /** The deployment's build does not include the product; the code is Unimplemented. */
-    NotInstalled: "PRODUCT_NOT_INSTALLED",
-    /** The deployment turned the product off; the code is FailedPrecondition. */
-    Disabled: "PRODUCT_DISABLED",
-    /** The workspace's entitlements leave the product out; the code is PermissionDenied. */
-    NotEntitled: "PRODUCT_NOT_ENTITLED",
     /**
-     * The workspace's settings turn the product off, or an outside product's
-     * installation is turned off; the code is FailedPrecondition.
+     * The product is off for the workspace; the code is FailedPrecondition, and
+     * `cause` says which input turned it off.
      */
-    TurnedOff: "PRODUCT_TURNED_OFF",
-    /**
-     * Turning an outside product on installs it, and the call did not accept the
-     * access it asks for; the code is FailedPrecondition.
-     */
-    AccessNotAccepted: "ACCESS_NOT_ACCEPTED",
+    Unavailable: "PRODUCT_UNAVAILABLE",
+};
+/** The inputs that turn a product off. */
+export const ProductCause = {
+    /** The deployment's build does not include the product. */
+    Build: "build",
+    /** The deployment's config turns the product off. */
+    Operator: "operator",
+    /** The workspace's plan leaves the product out. */
+    Plan: "plan",
+    /** The workspace's settings turn the product off. */
+    Workspace: "workspace",
 };
 const productReasons = new Set(Object.values(ProductReason));
-// The ErrorInfo domain of a product's refusal.
-const productErrorDomain = "toshi.run";
+/** The reasons the API names on a refusal that is not a product's. */
+export const RefusalReason = {
+    /** The Windows VM takes no display input; the code is FailedPrecondition. */
+    DisplayInputNotEnabled: "DISPLAY_INPUT_NOT_ENABLED",
+    /** The image already has a build running; the code is FailedPrecondition. */
+    ImageBuildInProgress: "IMAGE_BUILD_IN_PROGRESS",
+    /** The registry of the revision's image could not say whether it serves the digest; the code is FailedPrecondition. */
+    ImageCheckFailed: "IMAGE_CHECK_FAILED",
+    /** A workload or a service revision still uses the image; the code is FailedPrecondition. */
+    ImageInUse: "IMAGE_IN_USE",
+    /** Another live image of the workspace has the name; the code is AlreadyExists. */
+    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. */
+    ImageNotReady: "IMAGE_NOT_READY",
+    /** The revision's registry answered that it does not serve the image digest; the code is FailedPrecondition. */
+    ImageNotServed: "IMAGE_NOT_SERVED",
+    /** The call would remove the caller's last identity; the code is FailedPrecondition. */
+    LastIdentity: "LAST_IDENTITY",
+    /** The call would remove the workspace's last member; the code is FailedPrecondition. */
+    LastMember: "LAST_MEMBER",
+    /** The call would leave the workspace without an owner; the code is FailedPrecondition. */
+    LastOwner: "LAST_OWNER",
+    /** A role change names a permission the caller does not hold where the role applies; the code is PermissionDenied. */
+    PermissionMissing: "PERMISSION_MISSING",
+    /** The workspace's plan does not include images; the code is FailedPrecondition. */
+    PlanExcludesImages: "PLAN_EXCLUDES_IMAGES",
+    /** A Windows job Toshi licenses opens no display session; the code is FailedPrecondition. */
+    ToshiLicensedWindows: "TOSHI_LICENSED_WINDOWS",
+};
+const refusalReasons = new Set(Object.values(RefusalReason));
+// The ErrorInfo domain of the API's refusals.
+const errorInfoDomain = "toshi.run";
 /**
- * The API's refusal of a call for a product: one that is off for the
- * workspace, or an outside product whose access the call did not accept.
+ * 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
@@ -111,12 +140,10 @@ export class ProductError extends ConnectError {
     /** The product's ID, such as `runners`. */
     product;
     reason;
-    /** The setting that turns the product on, such as `runners.enabled`; empty for ACCESS_NOT_ACCEPTED. */
-    feature;
-    /** How far a product the deployment disables has wound down: `no_new_work`, `draining` or `stopped`; empty otherwise. */
+    /** The input that turned the product off, the refusal's `cause` metadata: `build`, `operator`, `plan` or `workspace`. */
+    productCause;
+    /** How far a product the deployment turns off has wound down: `no_new_work`, `draining` or `stopped`; empty otherwise. */
     state;
-    /** The access an outside product asks for, for ACCESS_NOT_ACCEPTED: accept exactly this list to install it. */
-    access;
     constructor(err, reason, metadata) {
         super(err.rawMessage, err.code, err.metadata, undefined, err);
         // ConnectError's instanceof accepts a subclass only by this name.
@@ -124,10 +151,8 @@ export class ProductError extends ConnectError {
         this.details = err.details;
         this.product = metadata.get("product") ?? "";
         this.reason = reason;
-        this.feature = metadata.get("feature") ?? "";
+        this.productCause = (metadata.get("cause") ?? "");
         this.state = metadata.get("state") ?? "";
-        const access = metadata.get("access") ?? "";
-        this.access = access === "" ? [] : access.split(",");
     }
     // ConnectError's own check would accept any ConnectError.
     static [Symbol.hasInstance](v) {
@@ -138,6 +163,32 @@ export class ProductError extends ConnectError {
 export function isProductError(err) {
     return err instanceof 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 class RefusalError extends ConnectError {
+    reason;
+    constructor(err, reason) {
+        super(err.rawMessage, err.code, err.metadata, undefined, err);
+        // ConnectError's instanceof accepts a subclass only by this name.
+        this.name = "ConnectError";
+        this.details = err.details;
+        this.reason = reason;
+    }
+    // ConnectError's own check would accept any ConnectError.
+    static [Symbol.hasInstance](v) {
+        return Function.prototype[Symbol.hasInstance].call(RefusalError, v);
+    }
+}
+/** Reports whether err is a refusal that names a reason this module knows. */
+export function isRefusalError(err) {
+    return err instanceof RefusalError;
+}
 /** err as a ProductError when it is a product's refusal, and err unchanged otherwise. */
 export function asProductError(err) {
     if (!(err instanceof ConnectError) || err instanceof ProductError) {
@@ -148,13 +199,34 @@ export function asProductError(err) {
             continue;
         }
         const info = decodeErrorInfo(detail.value);
-        if (info === undefined || info.domain !== productErrorDomain || !productReasons.has(info.reason)) {
+        if (info === undefined || info.domain !== errorInfoDomain || !productReasons.has(info.reason)) {
             continue;
         }
         return new ProductError(err, info.reason, info.metadata);
     }
     return err;
 }
+/** err as a RefusalError when it is a refusal that names a reason this module knows, and err unchanged otherwise. */
+export function asRefusalError(err) {
+    if (!(err instanceof ConnectError) || err instanceof RefusalError) {
+        return err;
+    }
+    for (const detail of err.details) {
+        if (!("type" in detail) || detail.type !== "google.rpc.ErrorInfo") {
+            continue;
+        }
+        const info = decodeErrorInfo(detail.value);
+        if (info === undefined || info.domain !== errorInfoDomain || !refusalReasons.has(info.reason)) {
+            continue;
+        }
+        return new RefusalError(err, info.reason);
+    }
+    return err;
+}
+/** 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 function asTypedError(err) {
+    return asRefusalError(asProductError(err));
+}
 /**
  * Reads a google.rpc.ErrorInfo message: reason (1), domain (2) and metadata
  * (3), a map of strings. It reads the wire format itself, so the SDK needs no

package/dist/gen/toshi/permission_pb.d.ts

@@ -1,9 +1,172 @@
-import type { GenExtension, GenFile } from "@bufbuild/protobuf/codegenv2";
-import type { MethodOptions } from "@bufbuild/protobuf/wkt";
+import type { GenExtension, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { FieldOptions, MethodOptions } from "@bufbuild/protobuf/wkt";
+import type { Message } from "@bufbuild/protobuf";
 /**
  * Describes the file toshi/permission.proto.
  */
 export declare const file_toshi_permission: GenFile;
+/**
+ * Audit is the audit event a call records.
+ *
+ * @generated from message toshi.Audit
+ */
+export type Audit = Message<"toshi.Audit"> & {
+    /**
+     * action is "<noun>.<verb>" with the verb in the past tense. Unset, it is
+     * the method's name: CreateSandbox records "sandbox.created". The build
+     * fails a method whose verb it cannot put in the past tense, or whose name
+     * gives the action this field names. "none" records nothing, for a call
+     * no Workspace API caller makes, such as a workload's upload.
+     *
+     * @generated from field: string action = 1;
+     */
+    action: string;
+    /**
+     * target is what the call acts on, as "<kind>:<source>", or "none". Unset,
+     * the kind is the action's noun and the source the response's id for a
+     * call that creates (Create, Reserve, Open) and the request's id
+     * otherwise: "id" or "<kind>_id", or for a create "<kind>.id" of the
+     * response. A source is a request field path, such as "job_id" or
+     * "start.sandbox_id", a response field path after "response.", such as
+     * "response.endpoint.id", "workspace" for the call's workspace, or
+     * "project" for the project the call resolved.
+     *
+     * @generated from field: string target = 2;
+     */
+    target: string;
+};
+/**
+ * Audit is the audit event a call records.
+ *
+ * @generated from message toshi.Audit
+ */
+export type AuditJson = {
+    /**
+     * action is "<noun>.<verb>" with the verb in the past tense. Unset, it is
+     * the method's name: CreateSandbox records "sandbox.created". The build
+     * fails a method whose verb it cannot put in the past tense, or whose name
+     * gives the action this field names. "none" records nothing, for a call
+     * no Workspace API caller makes, such as a workload's upload.
+     *
+     * @generated from field: string action = 1;
+     */
+    action?: string;
+    /**
+     * target is what the call acts on, as "<kind>:<source>", or "none". Unset,
+     * the kind is the action's noun and the source the response's id for a
+     * call that creates (Create, Reserve, Open) and the request's id
+     * otherwise: "id" or "<kind>_id", or for a create "<kind>.id" of the
+     * response. A source is a request field path, such as "job_id" or
+     * "start.sandbox_id", a response field path after "response.", such as
+     * "response.endpoint.id", "workspace" for the call's workspace, or
+     * "project" for the project the call resolved.
+     *
+     * @generated from field: string target = 2;
+     */
+    target?: string;
+};
+/**
+ * Describes the message toshi.Audit.
+ * Use `create(AuditSchema)` to create a new message.
+ */
+export declare const AuditSchema: GenMessage<Audit, {
+    jsonType: AuditJson;
+}>;
+/**
+ * MCP is how a call appears as a tool of the MCP server: each hint that is
+ * set replaces the one the generator's rules give, and exclude leaves the
+ * call out of the tool list.
+ *
+ * @generated from message toshi.MCP
+ */
+export type MCP = Message<"toshi.MCP"> & {
+    /**
+     * read_only is the tool's readOnlyHint: the call changes nothing.
+     *
+     * @generated from field: optional bool read_only = 1;
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * destructive is the tool's destructiveHint: the call may end or remove
+     * something it cannot bring back.
+     *
+     * @generated from field: optional bool destructive = 2;
+     */
+    destructive?: boolean | undefined;
+    /**
+     * idempotent is the tool's idempotentHint: a second call with the same
+     * input changes nothing more.
+     *
+     * @generated from field: optional bool idempotent = 3;
+     */
+    idempotent?: boolean | undefined;
+    /**
+     * open_world is the tool's openWorldHint: the call reaches past the
+     * workspace, such as a workload that reaches what its network policy
+     * allows.
+     *
+     * @generated from field: optional bool open_world = 4;
+     */
+    openWorld?: boolean | undefined;
+    /**
+     * exclude leaves the call out, for a call that makes no sense as a tool,
+     * such as one only a workload's own token may make.
+     *
+     * @generated from field: bool exclude = 5;
+     */
+    exclude: boolean;
+};
+/**
+ * MCP is how a call appears as a tool of the MCP server: each hint that is
+ * set replaces the one the generator's rules give, and exclude leaves the
+ * call out of the tool list.
+ *
+ * @generated from message toshi.MCP
+ */
+export type MCPJson = {
+    /**
+     * read_only is the tool's readOnlyHint: the call changes nothing.
+     *
+     * @generated from field: optional bool read_only = 1;
+     */
+    readOnly?: boolean;
+    /**
+     * destructive is the tool's destructiveHint: the call may end or remove
+     * something it cannot bring back.
+     *
+     * @generated from field: optional bool destructive = 2;
+     */
+    destructive?: boolean;
+    /**
+     * idempotent is the tool's idempotentHint: a second call with the same
+     * input changes nothing more.
+     *
+     * @generated from field: optional bool idempotent = 3;
+     */
+    idempotent?: boolean;
+    /**
+     * open_world is the tool's openWorldHint: the call reaches past the
+     * workspace, such as a workload that reaches what its network policy
+     * allows.
+     *
+     * @generated from field: optional bool open_world = 4;
+     */
+    openWorld?: boolean;
+    /**
+     * exclude leaves the call out, for a call that makes no sense as a tool,
+     * such as one only a workload's own token may make.
+     *
+     * @generated from field: bool exclude = 5;
+     */
+    exclude?: boolean;
+};
+/**
+ * Describes the message toshi.MCP.
+ * Use `create(MCPSchema)` to create a new message.
+ */
+export declare const MCPSchema: GenMessage<MCP, {
+    jsonType: MCPJson;
+}>;
 /**
  * permission names what a caller needs to make the call: an area and a
  * level. "<area>.read" sees what the area holds and "<area>.write" changes
@@ -37,3 +200,45 @@ export declare const permission: GenExtension<MethodOptions, string>;
  * @generated from extension: string scope = 51001;
  */
 export declare const scope: GenExtension<MethodOptions, string>;
+/**
+ * audit names the audit event a call records when its action or target
+ * is not the one its name gives. Every call that changes something
+ * records one event: on the Workspace API a call whose permission's level
+ * is not "read", on the operator API a call whose verb is not a read
+ * (Get, List, Watch, Wait, Summarise, Suggest, Export, Discover). A read
+ * whose option names an action records one too.
+ *
+ * @generated from extension: toshi.Audit audit = 51002;
+ */
+export declare const audit: GenExtension<MethodOptions, Audit>;
+/**
+ * by_field marks an update call that needs no permission of its own: each
+ * field its mask names needs its field group's permission, the field's
+ * field_permission or, for a field without one, the method's permission.
+ * The caller needs at least one of them to make the call, and the
+ * handler checks each field the mask names before it writes; a mask that
+ * names nothing needs any one.
+ *
+ * @generated from extension: bool by_field = 51004;
+ */
+export declare const by_field: GenExtension<MethodOptions, boolean>;
+/**
+ * mcp sets how the call appears as a tool of the MCP server, where the
+ * rules its generator applies give the wrong answer. Without it a call
+ * whose permission's level is "read" is read-only and idempotent, a call
+ * whose name begins with Delete, Cancel, Revoke, Remove, Stop or Rollback
+ * is destructive, and no call reaches outside the workspace.
+ *
+ * @generated from extension: toshi.MCP mcp = 51005;
+ */
+export declare const mcp: GenExtension<MethodOptions, MCP>;
+/**
+ * field_permission names what a caller needs to change the field through
+ * the mask of an update call marked by_field: a field group of its own,
+ * such as "billing.write" for a workspace's spending limits. A field
+ * without it needs the method's permission. The build checks the name's
+ * shape, and the permissions page lists the field groups.
+ *
+ * @generated from extension: string field_permission = 51003;
+ */
+export declare const field_permission: GenExtension<FieldOptions, string>;

package/dist/gen/toshi/permission_pb.js

@@ -1,12 +1,22 @@
 // @generated by protoc-gen-es v2.16.0 with parameter "target=ts,json_types=true,import_extension=js"
 // @generated from file toshi/permission.proto (package toshi, syntax proto3)
 /* eslint-disable */
-import { extDesc, fileDesc } from "@bufbuild/protobuf/codegenv2";
+import { extDesc, fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_descriptor } from "@bufbuild/protobuf/wkt";
 /**
  * Describes the file toshi/permission.proto.
  */
-export const file_toshi_permission = /*@__PURE__*/ fileDesc("ChZ0b3NoaS9wZXJtaXNzaW9uLnByb3RvEgV0b3NoaTpACgpwZXJtaXNzaW9uEh4uZ29vZ2xlLnByb3RvYnVmLk1ldGhvZE9wdGlvbnMYuI4DIAEoCVIKcGVybWlzc2lvbjo2CgVzY29wZRIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGLmOAyABKAlSBXNjb3BlQh5aHGdvLnRvc2hpY2xvdWQuaW8vYXBpL3Rvc2hpcGJiBnByb3RvMw", [file_google_protobuf_descriptor]);
+export const file_toshi_permission = /*@__PURE__*/ fileDesc("ChZ0b3NoaS9wZXJtaXNzaW9uLnByb3RvEgV0b3NoaSInCgVBdWRpdBIOCgZhY3Rpb24YASABKAkSDgoGdGFyZ2V0GAIgASgJIrYBCgNNQ1ASFgoJcmVhZF9vbmx5GAEgASgISACIAQESGAoLZGVzdHJ1Y3RpdmUYAiABKAhIAYgBARIXCgppZGVtcG90ZW50GAMgASgISAKIAQESFwoKb3Blbl93b3JsZBgEIAEoCEgDiAEBEg8KB2V4Y2x1ZGUYBSABKAhCDAoKX3JlYWRfb25seUIOCgxfZGVzdHJ1Y3RpdmVCDQoLX2lkZW1wb3RlbnRCDQoLX29wZW5fd29ybGQ6QAoKcGVybWlzc2lvbhIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGLiOAyABKAlSCnBlcm1pc3Npb246NgoFc2NvcGUSHi5nb29nbGUucHJvdG9idWYuTWV0aG9kT3B0aW9ucxi5jgMgASgJUgVzY29wZTpECgVhdWRpdBIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGLqOAyABKAsyDC50b3NoaS5BdWRpdFIFYXVkaXQ6OwoIYnlfZmllbGQSHi5nb29nbGUucHJvdG9idWYuTWV0aG9kT3B0aW9ucxi8jgMgASgIUgdieUZpZWxkOj4KA21jcBIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGL2OAyABKAsyCi50b3NoaS5NQ1BSA21jcDpKChBmaWVsZF9wZXJtaXNzaW9uEh0uZ29vZ2xlLnByb3RvYnVmLkZpZWxkT3B0aW9ucxi7jgMgASgJUg9maWVsZFBlcm1pc3Npb25CHlocZ28udG9zaGljbG91ZC5pby9hcGkvdG9zaGlwYmIGcHJvdG8z", [file_google_protobuf_descriptor]);
+/**
+ * Describes the message toshi.Audit.
+ * Use `create(AuditSchema)` to create a new message.
+ */
+export const AuditSchema = /*@__PURE__*/ messageDesc(file_toshi_permission, 0);
+/**
+ * Describes the message toshi.MCP.
+ * Use `create(MCPSchema)` to create a new message.
+ */
+export const MCPSchema = /*@__PURE__*/ messageDesc(file_toshi_permission, 1);
 /**
  * permission names what a caller needs to make the call: an area and a
  * level. "<area>.read" sees what the area holds and "<area>.write" changes
@@ -40,3 +50,45 @@ export const permission = /*@__PURE__*/ extDesc(file_toshi_permission, 0);
  * @generated from extension: string scope = 51001;
  */
 export const scope = /*@__PURE__*/ extDesc(file_toshi_permission, 1);
+/**
+ * audit names the audit event a call records when its action or target
+ * is not the one its name gives. Every call that changes something
+ * records one event: on the Workspace API a call whose permission's level
+ * is not "read", on the operator API a call whose verb is not a read
+ * (Get, List, Watch, Wait, Summarise, Suggest, Export, Discover). A read
+ * whose option names an action records one too.
+ *
+ * @generated from extension: toshi.Audit audit = 51002;
+ */
+export const audit = /*@__PURE__*/ extDesc(file_toshi_permission, 2);
+/**
+ * by_field marks an update call that needs no permission of its own: each
+ * field its mask names needs its field group's permission, the field's
+ * field_permission or, for a field without one, the method's permission.
+ * The caller needs at least one of them to make the call, and the
+ * handler checks each field the mask names before it writes; a mask that
+ * names nothing needs any one.
+ *
+ * @generated from extension: bool by_field = 51004;
+ */
+export const by_field = /*@__PURE__*/ extDesc(file_toshi_permission, 3);
+/**
+ * mcp sets how the call appears as a tool of the MCP server, where the
+ * rules its generator applies give the wrong answer. Without it a call
+ * whose permission's level is "read" is read-only and idempotent, a call
+ * whose name begins with Delete, Cancel, Revoke, Remove, Stop or Rollback
+ * is destructive, and no call reaches outside the workspace.
+ *
+ * @generated from extension: toshi.MCP mcp = 51005;
+ */
+export const mcp = /*@__PURE__*/ extDesc(file_toshi_permission, 4);
+/**
+ * field_permission names what a caller needs to change the field through
+ * the mask of an update call marked by_field: a field group of its own,
+ * such as "billing.write" for a workspace's spending limits. A field
+ * without it needs the method's permission. The build checks the name's
+ * shape, and the permissions page lists the field groups.
+ *
+ * @generated from extension: string field_permission = 51003;
+ */
+export const field_permission = /*@__PURE__*/ extDesc(file_toshi_permission, 5);