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

package/src/funcs/webhooksDeleteWebhookEndpoint.ts

@@ -28,13 +28,13 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Deletes the webhook endpoint with the given ID.
+ * Deletes the webhook endpoint with the given ID
  *
  * @remarks
  * Stops the deliveries and removes the endpoint together with its delivery history.
  *
- * Endpoints are also removed on your behalf when the marketplace app installation they were
- * registered under is narrowed or uninstalled, so an integration never keeps receiving
+ * The server also removes endpoints on your behalf when someone narrows or uninstalls the marketplace app installation they were
+ * registered under. An integration therefore never keeps receiving
  * events for entities it lost access to.
  *
  * Requires the `webhook` / `delete` permission.

package/src/funcs/webhooksGetWebhookEndpoint.ts

@@ -28,13 +28,13 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Retrieves the webhook endpoint with the given ID.
+ * Retrieves the webhook endpoint with the given ID
  *
  * @remarks
  * Returns the definition of a webhook endpoint by ID. `secrets` is not included: the signing
  * secret is only returned by `POST /webhooks`.
  *
- * An endpoint you cannot see is reported as `404`, so an ID belonging to somebody else is
+ * The API reports an endpoint you cannot see as `404`, so an ID belonging to somebody else is
  * indistinguishable from one that does not exist.
  *
  * Requires the `webhook` / `view` permission.

package/src/funcs/webhooksUpdatesTheWebhookEndpointWithTheGivenId.ts

@@ -28,32 +28,32 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Updates the webhook endpoint with the given ID.
+ * Updates the webhook endpoint with the given ID
  *
  * @remarks
- * Changes the URL, the events, their expansion scopes or the consumers of an endpoint.
+ * Changes the URL, the events, their expansion scopes, or the consumers of an endpoint.
  * Anything you leave out keeps its current value.
  *
- * Two properties replace rather than merge: naming any consumer clears the others, and
- * `subscriptions` replaces every event, so an event you do not list again is dropped along
+ * Two properties replace instead of merging. Naming any consumer clears the others, and
+ * `subscriptions` replaces every event, so the API drops any event you do not list again along
  * with its scopes. `expand` on its own, without `subscriptions`, re-scopes the events the
- * endpoint already receives — each one takes the scopes that name its own entity, so an
+ * endpoint already receives. Each one takes the scopes that name its own entity, so an
  * endpoint receiving two models can be re-scoped in a single request (send `[]` to clear every
- * scope). A scope naming an entity the endpoint does not receive applies to nothing and is
- * rejected. New consumers are re-authorized against your own access, so an endpoint cannot be
- * pointed at an entity you could not have registered it for in the first place.
+ * scope). A scope naming an entity the endpoint does not receive applies to nothing, so the API
+ * rejects it. The API re-authorizes consumers against your own access, so you cannot
+ * point an endpoint at an entity you could not have registered it for.
  *
- * Changing `webhook_url` is reserved to whoever registered the endpoint, and to admins.
- * Deliveries are filtered by the registering user's access, so a new destination would receive
- * whatever that access reaches — if you did not register it, register your own instead.
+ * Only whoever registered the endpoint, and administrators, can change `webhook_url`.
+ * The registering user's access filters deliveries, so another destination would receive
+ * whatever that access reaches. If you did not register it, register your own instead.
  *
  * Changing the URL or the consumers withdraws the deliveries still queued for this endpoint.
- * Their payloads were serialized for the previous configuration, so they would otherwise
- * arrive at the new destination describing the old one. Changing only `subscriptions` or
+ * The server serialized their payloads for the previous configuration, so they would otherwise
+ * arrive at the changed destination describing the old one. Changing only `subscriptions` or
  * `expand` leaves queued deliveries alone.
  *
- * The signing secret cannot be rotated here, and `id`, `signature_algo` and `secrets` are
- * ignored if you send them back.
+ * You cannot rotate the signing secret here, and the API ignores `id`, `signature_algo`, and `secrets`
+ * if you send them back.
  *
  * Requires the `webhook` / `edit` permission.
  *

package/src/funcs/zonesGetSecurityZone.ts

@@ -31,17 +31,17 @@ import { Result } from "../types/fp.js";
  * Get security zone details
  *
  * @remarks
- * Get security zone details
+ * Gets security zone details
  *
  * **Permissions.** Requires the `zones.view` permission.
  *
- * Available `expand` scopes are:
+ * The `expand` parameter accepts the following scopes:
  *
  * - `zone.facility`
  * - `zone.department`
  * - `zone.rules`
  *
- * Unrecognised values are ignored.
+ * The server ignores unrecognized values.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */

package/src/funcs/zonesListOrSearchSecurityZones.ts

@@ -36,7 +36,7 @@ import {
  * List or search security zones
  *
  * @remarks
- * List or search security zones
+ * Lists or searches security zones
  *
  * **Permissions.** Requires the `zones.view` permission.
  *

package/src/funcs/zonesSecurityZoneCheckin.ts

@@ -27,12 +27,12 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Security zone checkin request
+ * Security zone check-in request
  *
  * @remarks
- * Security zone checkin request
+ * Requests a check-in to a security zone.
  *
- * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission - the caller's role and their relationship to the record decide what is returned.
+ * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission: the caller's role and their relationship to the record determine what the response contains.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */

package/src/index.extras.ts

@@ -40,6 +40,8 @@ import { smartBadgeGetPsks } from "./admin-funcs/smartBadgeGetPsks.js";
 import { smartBadgeReportVerifiedPsk } from "./admin-funcs/smartBadgeReportVerifiedPsk.js";
 
 import { notifyVendorCredentialFileUploaded } from "./admin-funcs/notifyVendorCredentialFileUploaded.js";
+import { vendorCredentialGetFormLineItems } from "./admin-funcs/vendorCredentialGetFormLineItems.js";
+import { vendorCredentialCreateFormQuote } from "./admin-funcs/vendorCredentialCreateFormQuote.js";
 import { companyManagerGetPaymentForm } from "./admin-funcs/companyManagerGetPaymentForm.js";
 import { vendorGetPaymentForm } from "./admin-funcs/vendorGetPaymentForm.js";
 import { vendorGetSystemsRequiringSmartBadge } from "./admin-funcs/vendorGetSystemsRequiringSmartBadge.js";
@@ -54,12 +56,12 @@ import { kioskCreateEvent } from "./admin-funcs/kioskCreateEvent.js";
 import { kioskHeartbeat } from "./admin-funcs/kioskHeartbeat.js";
 import { listCommunications } from "./admin-funcs/listCommunications.js";
 import { dismissCommunication } from "./admin-funcs/dismissCommunication.js";
+import { appsListInstalledApps } from "./admin-funcs/appsListInstalledApps.js";
+import { appsExchangeToken } from "./admin-funcs/appsExchangeToken.js";
+import { appsApproveDevice } from "./admin-funcs/appsApproveDevice.js";
 
-import { networksList } from "./admin-funcs/networksList.js";
-import { networksGet } from "./admin-funcs/networksGet.js";
-import { networksCreate } from "./admin-funcs/networksCreate.js";
-import { zoneDevicesList } from "./admin-funcs/zoneDevicesList.js";
-import { zoneDevicesGet } from "./admin-funcs/zoneDevicesGet.js";
+// Third-party app platform contract (surfaces, manifest, host/sandbox protocol, components).
+export * as apps from "./apps/index.js";
 
 export const __internal = {
   getInternalCore,
@@ -120,11 +122,24 @@ export const __internal = {
     notifyUploaded: notifyVendorCredentialFileUploaded
   },
 
+  vendorCredential: {
+    getFormLineItems: vendorCredentialGetFormLineItems,
+    createFormQuote: vendorCredentialCreateFormQuote
+  },
+
   communications: {
     list: listCommunications,
     dismiss: dismissCommunication
   },
 
+  // Third-party app platform host (web-mobile-client, docs/third-party-apps/plan.md C8).
+  apps: {
+    listInstalledApps: appsListInstalledApps,
+    exchangeToken: appsExchangeToken,
+    // C16: the CLI device-login approval screen.
+    approveDevice: appsApproveDevice
+  },
+
   companyManager: {
     getPaymentForm: companyManagerGetPaymentForm,
   },
@@ -145,18 +160,5 @@ export const __internal = {
     createZoneDevice: kioskCreateZoneDevice,
     createEvent: kioskCreateEvent,
     heartbeat: kioskHeartbeat
-  },
-
-  // Gatekeeper provisioning: the network a facility's devices join, and the
-  // inventory of the devices themselves.
-  networks: {
-    list: networksList,
-    get: networksGet,
-    create: networksCreate
-  },
-
-  zoneDevices: {
-    list: zoneDevicesList,
-    get: zoneDevicesGet
   }
 };

package/src/lib/config.ts

@@ -80,8 +80,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "0.45.0",
-  sdkVersion: "0.46.0-beta.5",
+  sdkVersion: "0.46.0-beta.7",
   genVersion: "2.941.0",
   userAgent:
-    "speakeasy-sdk/typescript 0.46.0-beta.5 2.941.0 0.45.0 @greensecurity/javascript-sdk",
+    "speakeasy-sdk/typescript 0.46.0-beta.7 2.941.0 0.45.0 @greensecurity/javascript-sdk",
 } as const;

package/src/models/components/alert.ts

@@ -11,6 +11,9 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
+/**
+ * The category of the alert, which determines how it appears. `null` if not set.
+ */
 export const Type = {
   Error: "Error",
   Warning: "Warning",
@@ -18,46 +21,112 @@ export const Type = {
   WebNotification: "Web Notification",
   SmartBadgeScreeningQuestions: "Smart Badge Screening Questions",
 } as const;
+/**
+ * The category of the alert, which determines how it appears. `null` if not set.
+ */
 export type Type = OpenEnum<typeof Type>;
 
+/**
+ * The action that a smart badge follow-up alert asks the user to take. `null` if not applicable.
+ */
 export const FollowUpType = {
   CompleteCheckin: "complete_checkin",
   AskScreeningQuestions: "ask_screening_questions",
 } as const;
+/**
+ * The action that a smart badge follow-up alert asks the user to take. `null` if not applicable.
+ */
 export type FollowUpType = OpenEnum<typeof FollowUpType>;
 
 /**
- * Context data for the alert. Smart badge follow-ups carry the check-in fields, and credential paid alerts carry vendor_credential_id.
+ * Context data for the alert. Smart badge follow-ups carry the check-in fields, and credential paid alerts carry `vendor_credential_id`.
  */
 export type AlertContext = {
+  /**
+   * The ID of the facility the alert relates to. `null` if not applicable.
+   */
   facilityId?: number | null | undefined;
+  /**
+   * The ID of the handoff the alert relates to. `null` if not applicable.
+   */
   handoffId?: number | null | undefined;
+  /**
+   * The QR code value of the smart badge the alert relates to. `null` if not applicable.
+   */
   qrCode?: string | null | undefined;
+  /**
+   * The ID of the security zone the alert relates to. `null` if not applicable.
+   */
   zoneId?: number | null | undefined;
+  /**
+   * The ID of the vendor scan the alert relates to. `null` if not applicable.
+   */
   vendorScanId?: number | null | undefined;
+  /**
+   * The ID of the vendor scan that the follow-up rechecks. `null` if not applicable.
+   */
   recheckVendorScanId?: number | null | undefined;
+  /**
+   * The action that a smart badge follow-up alert asks the user to take. `null` if not applicable.
+   */
   followUpType?: FollowUpType | null | undefined;
+  /**
+   * The ID of the vendor credential the alert relates to. `null` if not applicable.
+   */
   vendorCredentialId?: number | null | undefined;
 };
 
 /**
- * A simplified representation of a Alert, typically used in list views.
+ * A simplified representation of an alert, typically used in list views.
  */
 export type Alert = {
+  /**
+   * The unique ID of the alert.
+   */
   id?: number | undefined;
+  /**
+   * The ID of the alert target that delivers this alert to the user. `null` if not set.
+   */
   alertTargetId?: number | null | undefined;
+  /**
+   * The date and time when the system created the alert. `null` if not set.
+   */
   dateAdded?: string | null | undefined;
+  /**
+   * The date and time the alert becomes visible. `null` if the alert starts immediately.
+   */
   dateStarts?: string | null | undefined;
+  /**
+   * The alert message body, which can contain HTML markup. `null` if not set.
+   */
   message?: string | null | undefined;
+  /**
+   * The delivery status of the alert. `null` if not set.
+   */
   status?: string | null | undefined;
+  /**
+   * The category of the alert, which determines how it appears. `null` if not set.
+   */
   type?: Type | null | undefined;
+  /**
+   * The title of the alert. `null` if not set.
+   */
   title?: string | null | undefined;
+  /**
+   * The alert message as plain text with markup removed. `null` if not set.
+   */
   plainText?: string | null | undefined;
   /**
-   * Context data for the alert. Smart badge follow-ups carry the check-in fields, and credential paid alerts carry vendor_credential_id.
+   * Context data for the alert. Smart badge follow-ups carry the check-in fields, and credential paid alerts carry `vendor_credential_id`.
    */
   alertContext?: AlertContext | null | undefined;
+  /**
+   * Whether the user has viewed the alert. `null` if unknown.
+   */
   viewed?: boolean | null | undefined;
+  /**
+   * The date and time the user viewed the alert. `null` if the user has not viewed it.
+   */
   dateViewed?: string | null | undefined;
 };
 

package/src/models/components/appointmentsummary.ts

@@ -10,10 +10,16 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * A reduced Event object returned when the `vendor_scan.appointment` expand scope is requested.
+ * A reduced `Event` object returned when the request includes the `vendor_scan.appointment` expand scope.
  */
 export type AppointmentSummary = {
+  /**
+   * The unique ID of the appointment.
+   */
   id: number;
+  /**
+   * The title of the appointment. `null` if not set.
+   */
   title?: string | null | undefined;
   /**
    * Event start datetime (ISO 8601).
@@ -23,8 +29,17 @@ export type AppointmentSummary = {
    * Event end datetime (ISO 8601).
    */
   end?: string | null | undefined;
+  /**
+   * Whether the appointment lasts all day. `null` if not set.
+   */
   allDay?: boolean | null | undefined;
+  /**
+   * Whether the appointment is a standing appointment. `null` if not set.
+   */
   standingAppt?: boolean | null | undefined;
+  /**
+   * The status of the appointment. `null` if not set.
+   */
   status?: string | null | undefined;
 };
 

package/src/models/components/authenticatesuccessresponse.ts

@@ -20,57 +20,72 @@ import { UserDetails, UserDetails$inboundSchema } from "./userdetails.js";
 import { Vendor, Vendor$inboundSchema } from "./vendor.js";
 
 /**
- * A `permanent` user token can be used to access any API endpoint as the logged in user. A `one time` token is used to authenticate the user once.
+ * A `permanent` user token can be used to access any API endpoint as the signed in user. A `one time` token is used to authenticate the user once. Defaults to `permanent`.
  */
 export const AuthenticateSuccessResponseTokenType = {
   Permanent: "permanent",
   OneTime: "one time",
 } as const;
 /**
- * A `permanent` user token can be used to access any API endpoint as the logged in user. A `one time` token is used to authenticate the user once.
+ * A `permanent` user token can be used to access any API endpoint as the signed in user. A `one time` token is used to authenticate the user once. Defaults to `permanent`.
  */
 export type AuthenticateSuccessResponseTokenType = OpenEnum<
   typeof AuthenticateSuccessResponseTokenType
 >;
 
+/**
+ * The token to use for authenticating requests as the signed-in user.
+ */
 export type AuthenticateSuccessResponseUserToken = {
   /**
-   * This token can be passed in authorization headers for this user.
+   * You can pass this token in authorization headers for this user.
    */
   token: string;
   /**
-   * A `permanent` user token can be used to access any API endpoint as the logged in user. A `one time` token is used to authenticate the user once.
+   * A `permanent` user token can be used to access any API endpoint as the signed in user. A `one time` token is used to authenticate the user once. Defaults to `permanent`.
    */
   tokenType: AuthenticateSuccessResponseTokenType;
 };
 
+/**
+ * The inventory manager profile of the user, if the user has one.
+ */
 export type AuthenticateSuccessResponseInventoryManager = {};
 
 /**
- * A completed login. Identical to the `User` object returned everywhere
+ * A completed login. It matches the `User` object returned everywhere
  *
  * @remarks
- * else, plus an `sso` object when the request carried a valid `sso_state`
+ * else. It adds an `sso` object when the request carried a valid `sso_state`
  * and the login therefore has a SAML flow waiting to be finished.
  */
 export type AuthenticateSuccessResponse = {
   /**
-   * A `gatekeeper` is a special type of service user. This type of service user is assigned to Kiosks and Apps to verify Vendors using APIs that have some access to facility data.
+   * Whether the user is a `gatekeeper`, a special type of service user assigned to Kiosks and Apps to verify vendors using APIs that have some access to facility data.
    */
   isGatekeeper?: boolean | undefined;
+  /**
+   * Whether the request was successful.
+   */
   success: boolean;
   /**
    * Core user profile fields returned by user detail and update endpoints.
    */
   user: UserDetails;
+  /**
+   * The token to use for authenticating requests as the signed-in user.
+   */
   userToken: AuthenticateSuccessResponseUserToken;
   /**
    * Vendor details
    */
   vendor?: Vendor | undefined;
+  /**
+   * The inventory manager profile of the user, if the user has one.
+   */
   inventoryManager?: AuthenticateSuccessResponseInventoryManager | undefined;
   /**
-   * This object represents a contact at the system or facility level. Use it to verify vendors, create appointments, or check in visitors.
+   * Describes a contact at the system or facility level. Use it to verify vendors, create appointments, or check in visitors.
    */
   contact?: Contact | null | undefined;
   /**
@@ -84,12 +99,12 @@ export type AuthenticateSuccessResponse = {
    *
    * Present on a `200` from `POST /users/authenticate` only when the request
    * carried a valid, unexpired `sso_state`. Its absence means the login
-   * succeeded but the SAML flow did not resume — treat the login as an
-   * ordinary one rather than retrying.
+   * succeeded but the SAML flow did not resume—treat the login as an
+   * ordinary one instead of retrying.
    *
-   * This object is additive. The login itself is unaffected by it: the
-   * caller's own permanent token is in `user_token` exactly as it would be on
-   * any other successful authentication, and it is not the token embedded in
+   * This object is additive. It does not change the login. The
+   * caller's own permanent token is in `user_token` exactly as it is on
+   * any other successful authentication. It is not the token embedded in
    * `continue_url`.
    */
   sso?: SsoContinuation | undefined;

package/src/models/components/backgroundcheckresult.ts

@@ -13,6 +13,9 @@ import { smartUnion } from "../../types/smartUnion.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import { Invoice, Invoice$inboundSchema } from "./invoice.js";
 
+/**
+ * The current status of the background check result.
+ */
 export const BackgroundCheckResultStatus = {
   Pending: "Pending",
   Requested: "Requested",
@@ -23,36 +26,90 @@ export const BackgroundCheckResultStatus = {
   Denied: "Denied",
   Approved: "Approved",
 } as const;
+/**
+ * The current status of the background check result.
+ */
 export type BackgroundCheckResultStatus = OpenEnum<
   typeof BackgroundCheckResultStatus
 >;
 
 export type PdfUris = {
+  /**
+   * The URL of the PDF report, or `null` if not available.
+   */
   uri?: string | null | undefined;
+  /**
+   * The type of the PDF report, or `null` if not specified.
+   */
   reportType?: string | null | undefined;
 };
 
+/**
+ * The delivery method for the background check report, either `email` or `mail`, or `null` if not set.
+ */
 export const DeliveryMethod = {
   Email: "email",
   Mail: "mail",
 } as const;
+/**
+ * The delivery method for the background check report, either `email` or `mail`, or `null` if not set.
+ */
 export type DeliveryMethod = OpenEnum<typeof DeliveryMethod>;
 
+/**
+ * The invoice for the background check. Returns the full invoice object when expanded, otherwise the invoice ID, or `null` if there is no invoice.
+ */
 export type BackgroundCheckResultInvoice = Invoice | number;
 
+/**
+ * Details of the background check order placed with the screening provider.
+ */
 export type Bcp = {
+  /**
+   * The ID of the background check order, or `null` if there is no order.
+   */
   orderId?: number | null | undefined;
+  /**
+   * The status of the background check order as reported by the screening provider, or `null` if not available.
+   */
   orderStatus?: string | null | undefined;
+  /**
+   * Notes recorded for the background check order, or `null` if there are none.
+   */
   notes?: string | null | undefined;
+  /**
+   * The date the background check order was sent, or `null` if it has not been sent.
+   */
   dateSent?: string | null | undefined;
+  /**
+   * The date the background check results were received, or `null` if they have not been received.
+   */
   dateReceived?: string | null | undefined;
 };
 
+/**
+ * The mailing address that receives the background check report when `delivery_method` is `mail`, or `null` if not set.
+ */
 export type BackgroundCheckResultLocation = {
+  /**
+   * The first line of the street address, or `null` if not set.
+   */
   address1?: string | null | undefined;
+  /**
+   * The second line of the street address, or `null` if not set.
+   */
   address2?: string | null | undefined;
+  /**
+   * The city of the address, or `null` if not set.
+   */
   city?: string | null | undefined;
+  /**
+   * The state of the address, or `null` if not set.
+   */
   state?: string | null | undefined;
+  /**
+   * The ZIP code of the address, or `null` if not set.
+   */
   zip?: string | null | undefined;
 };
 
@@ -60,13 +117,37 @@ export type BackgroundCheckResultLocation = {
  * Reduced list of attributes of Background Check Result record
  */
 export type BackgroundCheckResult = {
+  /**
+   * The ID of the background check result, or `null` if none exists yet.
+   */
   id?: number | null | undefined;
+  /**
+   * The current status of the background check result.
+   */
   status?: BackgroundCheckResultStatus | undefined;
+  /**
+   * The PDF reports available for this background check, or `null` if none are available.
+   */
   pdfUris?: Array<PdfUris> | null | undefined;
+  /**
+   * The delivery method for the background check report, either `email` or `mail`, or `null` if not set.
+   */
   deliveryMethod?: DeliveryMethod | null | undefined;
+  /**
+   * The invoice for the background check. Returns the full invoice object when expanded, otherwise the invoice ID, or `null` if there is no invoice.
+   */
   invoice?: Invoice | number | null | undefined;
+  /**
+   * The email address that receives the background check report, or `null` if none is set.
+   */
   email?: string | null | undefined;
+  /**
+   * Details of the background check order placed with the screening provider.
+   */
   bcp?: Bcp | undefined;
+  /**
+   * The mailing address that receives the background check report when `delivery_method` is `mail`, or `null` if not set.
+   */
   location?: BackgroundCheckResultLocation | null | undefined;
 };