@greensecurity/javascript-sdk 0.46.0 → 0.47.0-beta.1

package/src/react-query/oauthIntrospectToken.ts

@@ -0,0 +1,135 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  MutationKey,
+  useMutation,
+  UseMutationResult,
+} from "@tanstack/react-query";
+import { GreenSecurityCore } from "../core.js";
+import { oauthIntrospectToken } from "../funcs/oauthIntrospectToken.js";
+import { combineSignals } from "../lib/primitives.js";
+import { RequestOptions } from "../lib/sdks.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 { unwrapAsync } from "../types/fp.js";
+import { useGreenSecurityContext } from "./_context.js";
+import { MutationHookOptions } from "./_types.js";
+
+export type OauthIntrospectTokenMutationVariables = {
+  request: components.TokenIntrospectionRequest;
+  options?: RequestOptions;
+};
+
+export type OauthIntrospectTokenMutationData = components.TokenIntrospection;
+
+export type OauthIntrospectTokenMutationError =
+  | errors.OAuthError
+  | GreenSecurityError
+  | ResponseValidationError
+  | ConnectionError
+  | RequestAbortedError
+  | RequestTimeoutError
+  | InvalidRequestError
+  | UnexpectedClientError
+  | SDKValidationError;
+
+/**
+ * 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.
+ */
+export function useOauthIntrospectTokenMutation(
+  options?: MutationHookOptions<
+    OauthIntrospectTokenMutationData,
+    OauthIntrospectTokenMutationError,
+    OauthIntrospectTokenMutationVariables
+  >,
+): UseMutationResult<
+  OauthIntrospectTokenMutationData,
+  OauthIntrospectTokenMutationError,
+  OauthIntrospectTokenMutationVariables
+> {
+  const client = useGreenSecurityContext();
+  return useMutation({
+    ...buildOauthIntrospectTokenMutation(client, options),
+    ...options,
+  });
+}
+
+export function mutationKeyOauthIntrospectToken(): MutationKey {
+  return ["@greensecurity/javascript-sdk", "oauth", "introspectToken"];
+}
+
+export function buildOauthIntrospectTokenMutation(
+  client$: GreenSecurityCore,
+  hookOptions?: RequestOptions,
+): {
+  mutationKey: MutationKey;
+  mutationFn: (
+    variables: OauthIntrospectTokenMutationVariables,
+  ) => Promise<OauthIntrospectTokenMutationData>;
+} {
+  return {
+    mutationKey: mutationKeyOauthIntrospectToken(),
+    mutationFn: function oauthIntrospectTokenMutationFn({
+      request,
+      options,
+    }): Promise<OauthIntrospectTokenMutationData> {
+      const mergedOptions = {
+        ...hookOptions,
+        ...options,
+        fetchOptions: {
+          ...hookOptions?.fetchOptions,
+          ...options?.fetchOptions,
+          signal: combineSignals(
+            hookOptions?.fetchOptions?.signal,
+            options?.fetchOptions?.signal,
+          ),
+        },
+      };
+      return unwrapAsync(oauthIntrospectToken(
+        client$,
+        request,
+        mergedOptions,
+      ));
+    },
+  };
+}

package/src/react-query/oauthRevokeToken.ts

@@ -0,0 +1,139 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  MutationKey,
+  useMutation,
+  UseMutationResult,
+} from "@tanstack/react-query";
+import { GreenSecurityCore } from "../core.js";
+import { oauthRevokeToken } from "../funcs/oauthRevokeToken.js";
+import { combineSignals } from "../lib/primitives.js";
+import { RequestOptions } from "../lib/sdks.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 { unwrapAsync } from "../types/fp.js";
+import { useGreenSecurityContext } from "./_context.js";
+import { MutationHookOptions } from "./_types.js";
+
+export type OauthRevokeTokenMutationVariables = {
+  request: components.TokenRevocationRequest;
+  options?: RequestOptions;
+};
+
+export type OauthRevokeTokenMutationData = operations.RevokeTokenRevokeTokenOk;
+
+export type OauthRevokeTokenMutationError =
+  | errors.OAuthError
+  | GreenSecurityError
+  | ResponseValidationError
+  | ConnectionError
+  | RequestAbortedError
+  | RequestTimeoutError
+  | InvalidRequestError
+  | UnexpectedClientError
+  | SDKValidationError;
+
+/**
+ * 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.
+ */
+export function useOauthRevokeTokenMutation(
+  options?: MutationHookOptions<
+    OauthRevokeTokenMutationData,
+    OauthRevokeTokenMutationError,
+    OauthRevokeTokenMutationVariables
+  >,
+): UseMutationResult<
+  OauthRevokeTokenMutationData,
+  OauthRevokeTokenMutationError,
+  OauthRevokeTokenMutationVariables
+> {
+  const client = useGreenSecurityContext();
+  return useMutation({
+    ...buildOauthRevokeTokenMutation(client, options),
+    ...options,
+  });
+}
+
+export function mutationKeyOauthRevokeToken(): MutationKey {
+  return ["@greensecurity/javascript-sdk", "oauth", "revokeToken"];
+}
+
+export function buildOauthRevokeTokenMutation(
+  client$: GreenSecurityCore,
+  hookOptions?: RequestOptions,
+): {
+  mutationKey: MutationKey;
+  mutationFn: (
+    variables: OauthRevokeTokenMutationVariables,
+  ) => Promise<OauthRevokeTokenMutationData>;
+} {
+  return {
+    mutationKey: mutationKeyOauthRevokeToken(),
+    mutationFn: function oauthRevokeTokenMutationFn({
+      request,
+      options,
+    }): Promise<OauthRevokeTokenMutationData> {
+      const mergedOptions = {
+        ...hookOptions,
+        ...options,
+        fetchOptions: {
+          ...hookOptions?.fetchOptions,
+          ...options?.fetchOptions,
+          signal: combineSignals(
+            hookOptions?.fetchOptions?.signal,
+            options?.fetchOptions?.signal,
+          ),
+        },
+      };
+      return unwrapAsync(oauthRevokeToken(
+        client$,
+        request,
+        mergedOptions,
+      ));
+    },
+  };
+}

package/src/react-query/organizationsGetFacility.ts

@@ -69,6 +69,7 @@ export type OrganizationsGetFacilityQueryError =
  * - `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`
@@ -116,6 +117,7 @@ export function useOrganizationsGetFacility(
  * - `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/react-query/organizationsListOrSearchFacilities.ts

@@ -84,6 +84,7 @@ export type OrganizationsListOrSearchFacilitiesQueryError =
  * - `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`
@@ -128,6 +129,7 @@ export function useOrganizationsListOrSearchFacilities(
  * - `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`
@@ -172,6 +174,7 @@ export function useOrganizationsListOrSearchFacilitiesSuspense(
  * - `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`
@@ -230,6 +233,7 @@ export function useOrganizationsListOrSearchFacilitiesInfinite(
  * - `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/react-query/vendorsAddVendorManagedByCompany.ts

@@ -50,9 +50,19 @@ export type VendorsAddVendorManagedByCompanyMutationError =
  * 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.
  */
 export function useVendorsAddVendorManagedByCompanyMutation(
   options?: MutationHookOptions<

package/src/react-query/vendorsCreateVendorCompany.ts

@@ -52,7 +52,13 @@ export type VendorsCreateVendorCompanyMutationError =
  * @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.
  */
 export function useVendorsCreateVendorCompanyMutation(
   options?: MutationHookOptions<

package/src/react-query/vendorsDeleteVendorManagedByCompany.ts

@@ -53,7 +53,15 @@ export type VendorsDeleteVendorManagedByCompanyMutationError =
  * @remarks
  * Removes a company as a manager of the vendor.
  *
- * **Permissions.** Requires the `vendors.edit` permission.
+ * **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 `managed_vendor_id` doesn't belong to this vendor, the API returns `404`, the same response
+ * as for an ID that doesn't exist.
  */
 export function useVendorsDeleteVendorManagedByCompanyMutation(
   options?: MutationHookOptions<

package/src/react-query/vendorsUpdateVendorCustomField.ts

@@ -60,7 +60,9 @@ export type VendorsUpdateVendorCustomFieldMutationError =
  * Accepts a numeric vendor ID, `me` for the authenticated vendor,
  * or an active QR code (format: contains hyphens).
  *
- * **Permissions.** Requires the `vendors.edit` permission.
+ * **Permissions.** Requires the `vendors.edit` permission. A company manager whose company
+ * manages the vendor through a managed-by-company link, rather than owning it, also needs that
+ * link's `may_edit_profile` access right, or the API returns `403`.
  */
 export function useVendorsUpdateVendorCustomFieldMutation(
   options?: MutationHookOptions<

package/src/react-query/vendorsUpdateVendorManagedByCompany.ts

@@ -52,7 +52,16 @@ export type VendorsUpdateVendorManagedByCompanyMutationError =
  * @remarks
  * Updates the access rights that a company has for the vendor it manages.
  *
- * **Permissions.** Requires the `vendors.edit` permission.
+ * **Permissions.** Requires the `vendors.edit` permission. Only these callers can change access
+ * rights: 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`: that company can't change its own access rights or another company's.
+ * Facility and system users get a `403` too.
+ *
+ * If `managed_vendor_id` doesn't belong to this vendor, the API returns `404`, the same response
+ * as for an ID that doesn't exist.
  */
 export function useVendorsUpdateVendorManagedByCompanyMutation(
   options?: MutationHookOptions<

package/src/react-query/zonesGetSecurityZone.ts

@@ -66,6 +66,7 @@ export type ZonesGetSecurityZoneQueryError =
  * - `zone.facility`
  * - `zone.department`
  * - `zone.rules`
+ * - `zone.device_counts` (also requires `zone_devices.view`)
  *
  * The server ignores unrecognized values.
  */
@@ -103,6 +104,7 @@ export function useZonesGetSecurityZone(
  * - `zone.facility`
  * - `zone.department`
  * - `zone.rules`
+ * - `zone.device_counts` (also requires `zone_devices.view`)
  *
  * The server ignores unrecognized values.
  */

package/src/react-query/zonesListOrSearchSecurityZones.core.ts

@@ -82,6 +82,7 @@ export function buildZonesListOrSearchSecurityZonesQuery(
       latitude: request.latitude,
       longitude: request.longitude,
       nameLike: request.nameLike,
+      expand: request.expand,
       contactId: request.contactId,
       facilityId: request.facilityId,
       greenLocationId: request.greenLocationId,
@@ -131,6 +132,7 @@ export function buildZonesListOrSearchSecurityZonesInfiniteQuery(
       latitude: request.latitude,
       longitude: request.longitude,
       nameLike: request.nameLike,
+      expand: request.expand,
       contactId: request.contactId,
       facilityId: request.facilityId,
       greenLocationId: request.greenLocationId,
@@ -178,6 +180,7 @@ export function queryKeyZonesListOrSearchSecurityZones(
     latitude?: number | undefined;
     longitude?: number | undefined;
     nameLike?: string | undefined;
+    expand?: Array<components.Expand> | undefined;
     contactId?: number | undefined;
     facilityId?: number | undefined;
     greenLocationId?: number | undefined;
@@ -200,6 +203,7 @@ export function queryKeyZonesListOrSearchSecurityZonesInfinite(
     latitude?: number | undefined;
     longitude?: number | undefined;
     nameLike?: string | undefined;
+    expand?: Array<components.Expand> | undefined;
     contactId?: number | undefined;
     facilityId?: number | undefined;
     greenLocationId?: number | undefined;

package/src/react-query/zonesListOrSearchSecurityZones.ts

@@ -78,6 +78,8 @@ export type ZonesListOrSearchSecurityZonesQueryError =
  * Lists or searches security zones
  *
  * **Permissions.** Requires the `zones.view` permission.
+ *
+ * The `expand` parameter accepts only `zone.device_counts`, which also requires `zone_devices.view`. The server ignores other values.
  */
 export function useZonesListOrSearchSecurityZones(
   request: operations.ListOrSearchSecurityZonesRequest,
@@ -107,6 +109,8 @@ export function useZonesListOrSearchSecurityZones(
  * Lists or searches security zones
  *
  * **Permissions.** Requires the `zones.view` permission.
+ *
+ * The `expand` parameter accepts only `zone.device_counts`, which also requires `zone_devices.view`. The server ignores other values.
  */
 export function useZonesListOrSearchSecurityZonesSuspense(
   request: operations.ListOrSearchSecurityZonesRequest,
@@ -136,6 +140,8 @@ export function useZonesListOrSearchSecurityZonesSuspense(
  * Lists or searches security zones
  *
  * **Permissions.** Requires the `zones.view` permission.
+ *
+ * The `expand` parameter accepts only `zone.device_counts`, which also requires `zone_devices.view`. The server ignores other values.
  */
 export function useZonesListOrSearchSecurityZonesInfinite(
   request: operations.ListOrSearchSecurityZonesRequest,
@@ -179,6 +185,8 @@ export function useZonesListOrSearchSecurityZonesInfinite(
  * Lists or searches security zones
  *
  * **Permissions.** Requires the `zones.view` permission.
+ *
+ * The `expand` parameter accepts only `zone.device_counts`, which also requires `zone_devices.view`. The server ignores other values.
  */
 export function useZonesListOrSearchSecurityZonesInfiniteSuspense(
   request: operations.ListOrSearchSecurityZonesRequest,
@@ -226,6 +234,7 @@ export function setZonesListOrSearchSecurityZonesData(
       latitude?: number | undefined;
       longitude?: number | undefined;
       nameLike?: string | undefined;
+      expand?: Array<components.Expand> | undefined;
       contactId?: number | undefined;
       facilityId?: number | undefined;
       greenLocationId?: number | undefined;
@@ -252,6 +261,7 @@ export function invalidateZonesListOrSearchSecurityZones(
       latitude?: number | undefined;
       longitude?: number | undefined;
       nameLike?: string | undefined;
+      expand?: Array<components.Expand> | undefined;
       contactId?: number | undefined;
       facilityId?: number | undefined;
       greenLocationId?: number | undefined;