@greensecurity/javascript-sdk 0.46.0-beta.7 → 0.46.0-beta.9

package/src/funcs/oauthCreateToken.ts

@@ -0,0 +1,219 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Issue an access, app or developer token
+ *
+ * @remarks
+ * The OAuth 2.0 token endpoint. It issues four kinds of short-lived token, chosen by
+ * `grant_type`:
+ *
+ * | Grant | Authenticate with | Issues |
+ * | --- | --- | --- |
+ * | `urn:ietf:params:oauth:grant-type:token-exchange` | The user's session token, as `subject_token` | An app user token (`gsu_`) or an app installation token (`gsi_`), 15 minutes |
+ * | `client_credentials` with `activation_id` | The app service account's `client_id` and `client_secret`, or its permanent token as `Authorization: Bearer` | An app installation token (`gsi_`), 15 minutes |
+ * | `client_credentials` without `activation_id` | An API service account's `client_id` and `client_secret`, or its permanent token as `Authorization: Bearer` | A plain API access token, 15 minutes |
+ * | `refresh_token` (service account) | The service account's `client_id` and `client_secret`, and a `refresh_token` | A plain API access token, 15 minutes, and a new refresh token |
+ * | `refresh_token` (apps CLI) | A `gsdr_` refresh token and `client_id=greensecurity-apps-cli`, no secret | A new developer CLI token (`gsd_`), 15 minutes, and a new `gsdr_` refresh token |
+ * | `urn:ietf:params:oauth:grant-type:device_code` | The `device_code` from `POST /oauth/device_authorization` | A developer CLI token (`gsd_`), 15 minutes, and a `gsdr_` refresh token |
+ *
+ * Token exchange is what the Green Security app does when it opens an app's views: the user
+ * must be covered by an activation of the app named in `audience`. `client_credentials` with
+ * `activation_id` is for the app's own backend. Without `activation_id`, `client_credentials`
+ * and a service account's `refresh_token` are the API service account flows: the response is
+ * a plain access token with no `issued_token_type` and no `activation_id` (see
+ * `TokenResponse`). An app token can never be used to obtain another token.
+ *
+ * The apps CLI logs in with the device grant and then renews its 15-minute developer token
+ * with the public-client `refresh_token` grant. Refresh tokens rotate and are single-use;
+ * presenting a spent one revokes the whole login, except for a retry within 30 seconds whose
+ * replacement is still unused. A login lasts at most 90 days from its device authorization.
+ * See `OAuthCliRefreshTokenGrant`.
+ *
+ * Every grant takes an optional `scope`, which can only narrow the token: it gets what was
+ * requested intersected with what the client is allowed, and if that is empty the request
+ * fails with `invalid_scope`. A refreshed token is never wider than the one it replaces.
+ *
+ * The request body may be JSON or `application/x-www-form-urlencoded`, and every parameter
+ * must be in the body: one sent in the query string is refused with `invalid_request`. Errors
+ * follow RFC 6749 and use `OAuthError` rather than the usual error envelope, including a
+ * body that fails validation (`400` `invalid_request`, never `422`). For the device grant,
+ * `authorization_pending` and `slow_down` mean "poll again later", not failure.
+ *
+ * Only `client_credentials` reads `Authorization`, and only when the body carries neither
+ * `client_id` nor `client_secret`. It accepts only the service account's permanent token
+ * there: a short-lived token (including one this endpoint issued), a narrowed token or an app
+ * token (`gsu_`, `gsi_`, `gsd_`) is answered `401` `invalid_client`, so a token can never be
+ * renewed or widened by presenting it. The other grants ignore the header.
+ *
+ * A narrowed `subject_token` is refused with `invalid_grant`, and a locked service account
+ * gets `401` `invalid_client` on `client_credentials` and `refresh_token`.
+ *
+ * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+ * (RFC 6749 section 5.1), so no cache keeps a token or code.
+ *
+ * **Permissions.** No named permission.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function oauthCreateToken(
+  client: GreenSecurityCore,
+  request: components.OAuthTokenRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    components.TokenResponse,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: components.OAuthTokenRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      components.TokenResponse,
+      | errors.OAuthError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => components.OAuthTokenRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/oauth/token")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "createToken",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    components.TokenResponse,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, components.TokenResponse$inboundSchema),
+    M.jsonErr([400, 401, 429], errors.OAuthError$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/oauthIntrospectToken.ts

@@ -0,0 +1,197 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Check an app token
+ *
+ * @remarks
+ * RFC 7662 token introspection, for your app's backend. When your app's UI calls your own
+ * API it sends the app user token it was given; call this endpoint to confirm the token is
+ * live and find out which user, app and activation it belongs to before you act on it.
+ *
+ * A back-end-only app (a manifest with no `ui_extensions`) has no UI, so no user token
+ * ever reaches it, and the installation tokens it uses it mints itself with
+ * `client_credentials`. It needs this endpoint only to check an app token that another
+ * party sends it.
+ *
+ * Only app user and app installation tokens issued to your own app are reported as
+ * `active`. Any other token, whether unknown, expired, revoked, another app's, a developer
+ * CLI token, or one whose user has since been locked, returns `{"active": false}` with a
+ * `200`, never an error.
+ *
+ * The request body may be JSON or `application/x-www-form-urlencoded`.
+ *
+ * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+ * (RFC 6749 section 5.1), so no cache keeps a token or code.
+ *
+ * **Permissions.** Only your app service account's permanent token is accepted, as
+ * `Authorization: Bearer`. A short-lived or narrowed token (including one from
+ * `client_credentials`), a locked service account's token, or a token of a user who is not
+ * an API service account is refused with `401` `invalid_client`. Every app token is refused
+ * the same way, and that includes installation tokens (`gsi_`): the host also hands those to
+ * your app's sandboxed UI, so accepting them here would let code running in the UI introspect
+ * tokens. Keep the service account token on your backend.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function oauthIntrospectToken(
+  client: GreenSecurityCore,
+  request: components.TokenIntrospectionRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    components.TokenIntrospection,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: components.TokenIntrospectionRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      components.TokenIntrospection,
+      | errors.OAuthError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => components.TokenIntrospectionRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/oauth/introspect")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "introspectToken",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    components.TokenIntrospection,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, components.TokenIntrospection$inboundSchema),
+    M.jsonErr([400, 401], errors.OAuthError$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/oauthRevokeToken.ts

@@ -0,0 +1,201 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Revoke a token
+ *
+ * @remarks
+ * RFC 7009 token revocation. Revokes an app user, app installation or developer CLI token,
+ * or an apps CLI refresh token, immediately. Revoking any token of an apps CLI login (its
+ * `gsd_` developer token or its `gsdr_` refresh token) revokes every token of that login.
+ * `apps-cli logout` sends its refresh token this way.
+ *
+ * Once the caller is authenticated the response is `200` with `{}`, whether or not anything
+ * was revoked, so it cannot be used to probe for valid tokens. A token the caller may not
+ * revoke is left alone.
+ *
+ * The request body may be JSON or `application/x-www-form-urlencoded`.
+ *
+ * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+ * (RFC 6749 section 5.1), so no cache keeps a token or code.
+ *
+ * **Permissions.** For an apps CLI refresh token, send `token=gsdr_…` with
+ * `client_id=greensecurity-apps-cli` and no `Authorization` (RFC 7009 public client). It
+ * always answers `200`.
+ *
+ * Otherwise send one of these as `Authorization: Bearer`:
+ *
+ * - the token being revoked, which may revoke itself (a `gsd_` token may also revoke any
+ *   token of its own login), and no other token;
+ * - an unscoped token (session, permanent, or an access token issued without `scope`) of the
+ *   token's subject, or of the user whose view caused it to be issued;
+ * - an unscoped token of the service account of the app it was issued for.
+ *
+ * A narrowed token (an access token issued with `scope`) is refused with `401`
+ * `invalid_client`: its scope says nothing about revoking the caller's other tokens. So is
+ * the token of a locked user.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function oauthRevokeToken(
+  client: GreenSecurityCore,
+  request: components.TokenRevocationRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.RevokeTokenRevokeTokenOk,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: components.TokenRevocationRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.RevokeTokenRevokeTokenOk,
+      | errors.OAuthError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => components.TokenRevocationRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/oauth/revoke")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "revokeToken",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.RevokeTokenRevokeTokenOk,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.RevokeTokenRevokeTokenOk$inboundSchema),
+    M.jsonErr([400, 401], errors.OAuthError$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/organizationsGetFacility.ts

@@ -43,6 +43,7 @@ import { Result } from "../types/fp.js";
  * - `facility.system`
  * - `facility.contacts`
  * - `facility.vendor_counts`
+ * - `facility.device_counts` (also requires `zone_devices.view`)
  * - `facility.appointment_policy`
  * - `facility.vendor_policy`
  * - `facility.vendor_guest_policy`

package/src/funcs/organizationsListOrSearchFacilities.ts

@@ -45,6 +45,7 @@ import {
  * - `facility.system`
  * - `facility.contacts`
  * - `facility.vendor_counts`
+ * - `facility.device_counts` (also requires `zone_devices.view`)
  * - `facility.appointment_policy`
  * - `facility.vendor_policy`
  * - `facility.vendor_guest_policy`

package/src/funcs/validateWebhook.ts

@@ -24,6 +24,9 @@ export async function validateWebhook(client: GreenSecurityCore, {
     | webhooks.SendFullReportCreatedRequest
     | webhooks.SendFullReportUpdatedRequest
     | webhooks.SendFullReportDestroyedRequest
+    | webhooks.SendMarketplaceAppActivationCreatedRequest
+    | webhooks.SendMarketplaceAppActivationUpdatedRequest
+    | webhooks.SendMarketplaceAppActivationDestroyedRequest
     | webhooks.SendVendorCreatedRequest
     | webhooks.SendVendorUpdatedRequest
     | webhooks.SendVendorDestroyedRequest
@@ -49,6 +52,9 @@ export async function validateWebhook(client: GreenSecurityCore, {
     webhooks.sendFullReportCreatedRequestFromJSON,
     webhooks.sendFullReportUpdatedRequestFromJSON,
     webhooks.sendFullReportDestroyedRequestFromJSON,
+    webhooks.sendMarketplaceAppActivationCreatedRequestFromJSON,
+    webhooks.sendMarketplaceAppActivationUpdatedRequestFromJSON,
+    webhooks.sendMarketplaceAppActivationDestroyedRequestFromJSON,
     webhooks.sendVendorCreatedRequestFromJSON,
     webhooks.sendVendorUpdatedRequestFromJSON,
     webhooks.sendVendorDestroyedRequestFromJSON,

package/src/funcs/vendorsAddVendorManagedByCompany.ts

@@ -30,9 +30,19 @@ import { Result } from "../types/fp.js";
  * Add vendor managed by company
  *
  * @remarks
- * Adds a company as a manager of the vendor.
+ * Adds a company as a manager of the vendor. The new company starts with every access right
+ * turned off. The company must be on the same site as the vendor. Otherwise, the API returns
+ * `404`.
  *
- * **Permissions.** Requires the `vendors.edit` permission.
+ * The company the vendor belongs to can't be added, because it already has full rights over the
+ * vendor. The API returns `400`, as it does for a company that already manages the vendor.
+ *
+ * **Permissions.** Requires the `vendors.edit` permission. Only these callers can change which
+ * companies manage the vendor: the vendor, a company manager at the company the vendor belongs to,
+ * a Green Security administrator, or an app whose API token can update the vendor (an app
+ * installed for the vendor's whole site, for the company the vendor belongs to, or by the vendor).
+ * A company manager whose company manages the vendor through a managed-by-company link, rather
+ * than owning the vendor, gets a `403`, and so do facility and system users.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */

package/src/funcs/vendorsCreateVendorCompany.ts

@@ -32,7 +32,13 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Creates vendor company
  *
- * **Permissions.** Requires the `companies.add` permission.
+ * **Permissions.** Requires the `companies.add` permission. Only these callers can move the vendor
+ * into a new company: the vendor, a company manager at the company the vendor belongs to, a Green
+ * Security administrator, or an app installed for the vendor's whole site. An app needs a
+ * site-wide installation because only a site-wide installation can create companies. An app
+ * installed only for a company or by a user gets a `403`, even when its API token can update the
+ * vendor. A company manager whose company manages the vendor through a managed-by-company link,
+ * rather than owning the vendor, gets a `403`, and so do facility and system users.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */