@greensecurity/javascript-sdk 0.45.0 → 0.46.0-beta.10

package/src/models/components/pager.ts

@@ -14,28 +14,31 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
  */
 export type Pager = {
   /**
-   * Url path of where to fetch this or other pages of the same objects
+   * Url path of where to fetch this or other pages of the same objects.
    */
   baseUrl: string;
   /**
-   * A comma-separated list of column names signifying which columns the `items` are sorted by.
+   * A comma-separated list of column names the server uses to sort the `items`.
    */
   sort: string;
   /**
-   * `0` signifies the items are sorted in ascending order, `1` signifies the items are sorted in descending order
+   * `0` means the server sorts the items in ascending order, `1` means the server sorts the items in descending order.
    */
   desc: number;
   /**
-   * Number of total items for all pages
+   * Number of total items for all pages.
    */
   itemCount: number;
+  /**
+   * The maximum number of items on each page.
+   */
   itemsPerPage: number;
   /**
-   * The page represented by the current `items` list. Pages are 1-based for easy display to the user.
+   * The page represented by the current `items` list. Page numbers start at 1.
    */
   page: number;
   /**
-   * When `true`, the following fields may be updated by adding query string parameters to the request (via GET)
+   * When true, you can change the following fields by adding query string parameters to the request (with a GET request)
    *
    * @remarks
    *
@@ -45,6 +48,15 @@ export type Pager = {
    * - items_per_page
    */
   useUrlParams: boolean;
+  /**
+   * How the server narrowed the list to your tenant, when it did, or `null`. Only some
+   *
+   * @remarks
+   * list endpoints return it, such as `GET /apps/secrets` and
+   * `GET /marketplace/apps/{id}/developers`; the others omit the field. Don't rely on
+   * its contents.
+   */
+  scope?: Array<any> | null | undefined;
 };
 
 /** @internal */
@@ -57,6 +69,7 @@ export const Pager$inboundSchema: z.ZodType<Pager, z.ZodTypeDef, unknown> = z
     items_per_page: types.number(),
     page: types.number(),
     use_url_params: types.boolean(),
+    scope: z.nullable(z.array(z.any())).optional(),
   }).transform((v) => {
     return remap$(v, {
       "base_url": "baseUrl",

package/src/models/components/passwordnotsetresponse.ts

@@ -10,17 +10,23 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * The response is sent when the user exists but has no password set. Redirect the user to redirect_url to complete the forgot-password flow.
+ * The server sends this response when the user exists but has no password set. Redirect the user to `redirect_url` to complete the forgot-password flow.
  */
 export type PasswordNotSetResponse = {
+  /**
+   * The action the caller must take to sign in, always `password_reset`.
+   */
   requires: "password_reset";
+  /**
+   * Whether the request succeeded.
+   */
   success: boolean;
   /**
-   * User exists but has no password set (e.g. newly invited company manager).
+   * User exists but has no password set (for example, newly invited company manager).
    */
   error: string;
   /**
-   * URL to redirect the user to set their password (forgot password flow). Carries the `return_url` and `sso_state` query params when those were provided on the request, because the browser follows this redirect and leaves the JSON body behind.
+   * URL to redirect the user to set their password (forgot password flow). Carries the `return_url` and `sso_state` query params when the request provided them because the browser follows this redirect and leaves the JSON body behind.
    */
   redirectUrl: string;
   /**
@@ -28,28 +34,28 @@ export type PasswordNotSetResponse = {
    *
    * @remarks
    * provider starts a "Login with Green Security" SAML flow at
-   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
-   * string parameter and must pass it back, byte for byte, on every call to
-   * this endpoint for the remainder of the login journey — including the
+   * `/saml/idp/sso`. The sign-in screen receives it as the `sso_state` query
+   * string parameter. The screen must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey—including the
    * second call that carries an `mfa_code`.
    *
    * The blob is signed, not encrypted, and it expires five minutes after the
    * service provider's request arrives. Do not parse it, shorten it, decode
    * it, or re-encode it.
    *
-   * **An invalid blob does not fail the login.** This is the opposite of what
-   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * **An invalid blob does not fail the login.** This behavior is the opposite of what
+   * most integrators assume. A forged, edited
    * or expired `sso_state` is silently discarded, and the request then
    * proceeds as an ordinary login. Valid credentials still authenticate and
-   * still return `200` — just with no `sso` object, leaving the user signed in
+   * still return `200` with no `sso` object. The user remains signed in
    * to Green Security with no way back to the service provider that sent them.
    * Never treat a `200` as proof that the SSO hand-off survived; check for
    * `sso` explicitly.
    *
    * Every `202` response echoes the *verified* blob back in its own
-   * `sso_state` field. Always send back the value from the response you just
-   * received rather than the one you started with, so that a blob the server
-   * has already rejected is never resent, and so a client does not have to
+   * `sso_state` field. Always send back the value from the response you
+   * received instead of the one you started with. That way, a blob the server
+   * has already rejected is never resent. A client does not have to
    * hold state of its own across the login journey.
    *
    * Omit this field entirely for an ordinary login that did not originate

package/src/models/components/passwordrequiredresponse.ts

@@ -10,13 +10,19 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * The response is sent when the email address provided requires a password (no SAML login).
+ * The server sends this response when the email address provided requires a password instead of Security Assertion Markup Language (SAML) sign-in.
  */
 export type PasswordRequiredResponse = {
+  /**
+   * The step required to finish signing in, which is always `password`.
+   */
   requires: "password";
+  /**
+   * Whether the sign-in completed. This value is false when a password is required.
+   */
   success: boolean;
   /**
-   * Error describing the exact condition of what further steps are needed to finish the login process.
+   * Error describing the exact condition and the further steps the user needs to finish the sign-in process.
    */
   error: string;
   /**
@@ -24,28 +30,28 @@ export type PasswordRequiredResponse = {
    *
    * @remarks
    * provider starts a "Login with Green Security" SAML flow at
-   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
-   * string parameter and must pass it back, byte for byte, on every call to
-   * this endpoint for the remainder of the login journey — including the
+   * `/saml/idp/sso`. The sign-in screen receives it as the `sso_state` query
+   * string parameter. The screen must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey—including the
    * second call that carries an `mfa_code`.
    *
    * The blob is signed, not encrypted, and it expires five minutes after the
    * service provider's request arrives. Do not parse it, shorten it, decode
    * it, or re-encode it.
    *
-   * **An invalid blob does not fail the login.** This is the opposite of what
-   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * **An invalid blob does not fail the login.** This behavior is the opposite of what
+   * most integrators assume. A forged, edited
    * or expired `sso_state` is silently discarded, and the request then
    * proceeds as an ordinary login. Valid credentials still authenticate and
-   * still return `200` — just with no `sso` object, leaving the user signed in
+   * still return `200` with no `sso` object. The user remains signed in
    * to Green Security with no way back to the service provider that sent them.
    * Never treat a `200` as proof that the SSO hand-off survived; check for
    * `sso` explicitly.
    *
    * Every `202` response echoes the *verified* blob back in its own
-   * `sso_state` field. Always send back the value from the response you just
-   * received rather than the one you started with, so that a blob the server
-   * has already rejected is never resent, and so a client does not have to
+   * `sso_state` field. Always send back the value from the response you
+   * received instead of the one you started with. That way, a blob the server
+   * has already rejected is never resent. A client does not have to
    * hold state of its own across the login journey.
    *
    * Omit this field entirely for an ordinary login that did not originate

package/src/models/components/paymentprofile.ts

@@ -15,11 +15,29 @@ export type PaymentProfile22 = {};
 export type PaymentProfile2 = number | PaymentProfile22;
 
 export type PaymentProfile3 = {
+  /**
+   * The unique ID of the payment profile.
+   */
   id?: number | undefined;
+  /**
+   * Whether the payment profile is valid. `null` when unknown.
+   */
   isValid?: boolean | null | undefined;
+  /**
+   * The card brand, for example, `Visa`. `null` when unknown.
+   */
   cardType?: string | null | undefined;
+  /**
+   * The last four digits of the card number. `null` when unknown.
+   */
   cardLast4?: string | null | undefined;
+  /**
+   * Whether the payment profile is a placeholder that has no real payment method. `null` when unknown.
+   */
   isDummy?: boolean | null | undefined;
+  /**
+   * The type of the payment profile. `null` when unknown.
+   */
   profileType?: string | null | undefined;
 };
 

package/src/models/components/paymentprofileinfo.ts

@@ -14,15 +14,15 @@ import {
 } from "./paymentprofile.js";
 
 /**
- * Payment profile information for the logged-in user. This is account-level data, not invoice-specific.
+ * Payment profile information for the logged-in user. This data is account-level, not invoice-specific.
  */
 export type PaymentProfileInfo = {
   /**
-   * Credit balance for the logged in user (vendor or company manager)
+   * Credit balance for the signed in user (vendor or company manager)
    */
   creditBalance: number | null;
   /**
-   * Payment profile for the logged in user (vendor or company manager)
+   * Payment profile for the signed in user (vendor or company manager)
    */
   paymentProfile: PaymentProfile | null;
 };

package/src/models/components/product.ts

@@ -9,11 +9,20 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Reduced list of attributes of Product record
+ * Reduced list of attributes of product record
  */
 export type Product = {
+  /**
+   * The unique ID of the product.
+   */
   id?: number | undefined;
+  /**
+   * The title of the product. `null` if not set.
+   */
   title?: string | null | undefined;
+  /**
+   * A description of the product. `null` if not set.
+   */
   description?: string | null | undefined;
 };
 

package/src/models/components/productvariant.ts

@@ -25,11 +25,20 @@ export const Recurrence = {
 export type Recurrence = OpenEnum<typeof Recurrence>;
 
 /**
- * Reduced list of attributes of Variant record
+ * Reduced list of attributes of variant record
  */
 export type ProductVariant = {
+  /**
+   * The ID of the product variant.
+   */
   id?: number | undefined;
+  /**
+   * The price of the variant, as an integer amount.
+   */
   price?: number | undefined;
+  /**
+   * The title of the variant, or `null` if none is set.
+   */
   title?: string | null | undefined;
   /**
    * Subscription interval of variant, if any.

package/src/models/components/samlloginrequiredresponse.ts

@@ -10,22 +10,31 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * The email address provided must complete SAML authentication at the provided `sso_url` which encodes the `return_url` that was sent as part of the request.
+ * The email address provided must complete SAML authentication at the provided `sso_url` which encodes the `return_url` from the request.
  *
  * @remarks
  *
- * The user will complete their SAML login at the external IdP and the browser will be redirected to your selected `return_url` with an extra query string parameter called `user_token`. That token is equivalent to the user login and can be used in the `/users/me` endpoint to get user details.
+ * The user completes their SAML sign-in at the external identity provider, and the browser redirects to your selected `return_url` with an extra query string parameter called `user_token`. That token is equivalent to the user login and can be used in the `/users/me` endpoint to get user details.
  */
 export type SamlLoginRequiredResponse = {
+  /**
+   * The step required to finish signing in, which is always `saml_login`.
+   */
   requires: "saml_login";
+  /**
+   * Whether the sign-in completed. This value is false when SAML sign-in is required.
+   */
   success: boolean;
+  /**
+   * A message describing why sign-in did not complete.
+   */
   error: string;
   /**
-   * Instructions that should be displayed to a user in case the SAML flow determines that the account is valid but this is a registration of a brand new user.
+   * Instructions to show a user when the SAML flow determines that the account is valid but the user is registering for the first time.
    */
   ssoInstructions?: string | undefined;
   /**
-   * This is the URL that should be opened to initiate the SAML login flow
+   * The URL to open to start the SAML sign-in flow.
    */
   ssoUrl: string;
   /**
@@ -33,28 +42,28 @@ export type SamlLoginRequiredResponse = {
    *
    * @remarks
    * provider starts a "Login with Green Security" SAML flow at
-   * `/saml/idp/sso`. The login screen receives it as the `sso_state` query
-   * string parameter and must pass it back, byte for byte, on every call to
-   * this endpoint for the remainder of the login journey — including the
+   * `/saml/idp/sso`. The sign-in screen receives it as the `sso_state` query
+   * string parameter. The screen must pass it back, byte for byte, on every call to
+   * this endpoint for the remainder of the login journey—including the
    * second call that carries an `mfa_code`.
    *
    * The blob is signed, not encrypted, and it expires five minutes after the
    * service provider's request arrives. Do not parse it, shorten it, decode
    * it, or re-encode it.
    *
-   * **An invalid blob does not fail the login.** This is the opposite of what
-   * most integrators assume, so it is worth stating plainly: a forged, edited
+   * **An invalid blob does not fail the login.** This behavior is the opposite of what
+   * most integrators assume. A forged, edited
    * or expired `sso_state` is silently discarded, and the request then
    * proceeds as an ordinary login. Valid credentials still authenticate and
-   * still return `200` — just with no `sso` object, leaving the user signed in
+   * still return `200` with no `sso` object. The user remains signed in
    * to Green Security with no way back to the service provider that sent them.
    * Never treat a `200` as proof that the SSO hand-off survived; check for
    * `sso` explicitly.
    *
    * Every `202` response echoes the *verified* blob back in its own
-   * `sso_state` field. Always send back the value from the response you just
-   * received rather than the one you started with, so that a blob the server
-   * has already rejected is never resent, and so a client does not have to
+   * `sso_state` field. Always send back the value from the response you
+   * received instead of the one you started with. That way, a blob the server
+   * has already rejected is never resent. A client does not have to
    * hold state of its own across the login journey.
    *
    * Omit this field entirely for an ordinary login that did not originate

package/src/models/components/scantype.ts

@@ -6,7 +6,7 @@ import * as z from "zod/v3";
 import { ClosedEnum } from "../../types/enums.js";
 
 /**
- * Search for objects in the same scan_type as the search string
+ * Search for objects in the same `scan_type` as the search string
  */
 export const ScanType = {
   In: "In",
@@ -14,7 +14,7 @@ export const ScanType = {
   Check: "Check",
 } as const;
 /**
- * Search for objects in the same scan_type as the search string
+ * Search for objects in the same `scan_type` as the search string
  */
 export type ScanType = ClosedEnum<typeof ScanType>;
 

package/src/models/components/screeninganswer.ts

@@ -32,10 +32,16 @@ export type ScreeningAnswerAnswerType = OpenEnum<
 >;
 
 /**
- * Reduced list of attributes of ScreeningAnswer records
+ * Reduced list of attributes of `ScreeningAnswer` records
  */
 export type ScreeningAnswer = {
+  /**
+   * The unique ID of the screening answer option.
+   */
   id: number;
+  /**
+   * The ID of the screening question this answer option belongs to, or `null` if not set.
+   */
   screeningQuestionId?: number | null | undefined;
   /**
    * The content of the screening answer option.
@@ -50,22 +56,28 @@ export type ScreeningAnswer = {
    */
   answerTitle?: string | null | undefined;
   /**
-   * Whether or not to allow an empty answer for this option.
+   * Whether to allow an empty answer for this option.
    */
   allowEmptyAnswer: boolean;
   /**
-   * The error message to display if an empty answer is submitted when not allowed.
+   * The error message to display if a respondent submits an empty answer when not allowed.
    */
   emptyAnswerErrorMessage?: string | null | undefined;
   /**
-   * Whether or not to show a confirmation prompt when this answer is selected.
+   * Whether to show a confirmation prompt when this answer is selected.
    */
   showConfirmation: boolean;
   /**
    * The text to display in the confirmation prompt.
    */
   confirmationText?: string | null | undefined;
+  /**
+   * The display order of the answer option relative to its siblings, or `null` if not set.
+   */
   priority?: number | null | undefined;
+  /**
+   * The screening questions associated with this answer option, or `null` if there are none.
+   */
   screeningQuestions?: Array<ScreeningQuestion> | null | undefined;
 };
 

package/src/models/components/screeningansweractionsummary.ts

@@ -20,13 +20,13 @@ export type ScreeningAnswerActionSummary = {
    */
   explanation?: string | null | undefined;
   /**
-   * Indicates whether further screening questions should be stopped as a result of this action.
+   * Whether this action stops further screening questions.
    *
    * @remarks
    */
   stopQuestions?: boolean | undefined;
   /**
-   * Indicates whether further check-ins should be stopped as a result of this action.
+   * Whether this action stops further check-ins.
    *
    * @remarks
    */

package/src/models/components/screeningquestion.ts

@@ -34,24 +34,36 @@ export type ScreeningQuestionPresetDisplayAs = OpenEnum<
 >;
 
 /**
- * Reduced list of attributes of ScreeningQuestion record
+ * Reduced list of attributes of `ScreeningQuestion` record
  */
 export type ScreeningQuestion = {
+  /**
+   * The unique ID of the screening question.
+   */
   id: number;
+  /**
+   * The ID of the screening question series the question belongs to.
+   */
   screeningQuestionSeriesId: number;
+  /**
+   * The ID of the answer selected for this question, or `null` if none has been selected.
+   */
   screeningAnswerId?: number | null | undefined;
   /**
-   * The order for displaying the question relative to other questions in the same series. Questions with lower priority values should be shown first.
+   * The order for displaying the question relative to other questions in the same series. Questions with lower priority values appear first.
    */
   priority?: number | null | undefined;
   /**
-   * The content of the screening question to be presented.
+   * The content of the screening question.
    */
   question?: string | null | undefined;
   /**
    * The display format for the question.
    */
   presetDisplayAs?: ScreeningQuestionPresetDisplayAs | null | undefined;
+  /**
+   * The preset answers a respondent can choose from for this question.
+   */
   screeningAnswers?: Array<ScreeningAnswer> | undefined;
 };
 

package/src/models/components/screeningresponse.ts

@@ -10,19 +10,52 @@ import * as types from "../../types/primitives.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Reduced list of attributes of ScreeningResponse record
+ * Reduced list of attributes of the `ScreeningResponse` record
  */
 export type ScreeningResponse = {
+  /**
+   * The unique ID of the screening response.
+   */
   id?: number | undefined;
+  /**
+   * The ID of the vendor who gave the response, or `null` if the response was not given by a vendor.
+   */
   vendorId?: number | null | undefined;
+  /**
+   * The ID of the vendor scan during which the vendor answered the question, or `null` if not tied to a scan.
+   */
   vendorScanId?: number | null | undefined;
+  /**
+   * The ID of the answered screening question, or `null` if not set.
+   */
   screeningQuestionId?: number | null | undefined;
+  /**
+   * The ID of the answer that was selected, or `null` for a custom or multiple answer.
+   */
   screeningAnswerId?: number | null | undefined;
+  /**
+   * The date and time of the answer, or `null` if not set.
+   */
   dateAnswered?: string | null | undefined;
+  /**
+   * The free-text answer the respondent typed, or `null` if a preset answer was selected.
+   */
   customAnswer?: string | null | undefined;
+  /**
+   * A comma-separated list of the IDs of the answers that were selected when the question allows several, or `null` otherwise.
+   */
   multipleVendorAnswerIds?: string | null | undefined;
+  /**
+   * The ID of the visitor check-in the response belongs to, or `null` if not tied to a check-in.
+   */
   visitorCheckinId?: number | null | undefined;
+  /**
+   * The ID of the contact who gave the response, or `null` if the response was not given by a contact.
+   */
   contactId?: number | null | undefined;
+  /**
+   * The ID of the visit request the response belongs to, or `null` if not tied to a visit request.
+   */
   visitRequestId?: number | null | undefined;
 };
 

package/src/models/components/ssocontinuation.ts

@@ -16,12 +16,12 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
  *
  * 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`.
  */
 export type SsoContinuation = {
@@ -29,18 +29,18 @@ export type SsoContinuation = {
    * An absolute, single-use URL on Green Security's domain. Navigate the
    *
    * @remarks
-   * browser to it (a full page navigation, not `fetch`); it answers with a
+   * browser to it (a full page navigation, not `fetch`). It answers with a
    * self-submitting form that POSTs the signed `SAMLResponse` and the
    * original `RelayState` to the service provider's assertion consumer
    * service URL.
    *
-   * The `token` in this URL is a separate **one-time** token that is
-   * consumed the first time the URL is followed, so the URL is good for
+   * The `token` in this URL is a separate **one-time** token that the server consumes
+   * the first time someone follows the URL. The URL works for
    * exactly one navigation. It is not the caller's permanent token, which
-   * is returned unchanged in `user_token`. Treat the URL as a secret:
+   * the response returns unchanged in `user_token`. Treat the URL as a secret:
    * whoever follows it first receives that user's assertion.
    *
-   * Never fetch this URL from your own back end: the response is meant for
+   * Never fetch this URL from your own back end. The response is meant for
    * the user's browser, and posting the assertion from anywhere else
    * breaks the flow.
    */

package/src/models/components/subscription.ts

@@ -27,25 +27,52 @@ import {
 } from "./productvariant.js";
 
 /**
- * Reduced list of attributes of the Subscription record
+ * Reduced list of attributes of the subscription record
  */
 export type Subscription = {
+  /**
+   * The unique ID of the subscription, or `null` if the vendor has no subscription.
+   */
   id?: number | null | undefined;
+  /**
+   * The date and time the subscription started, in ISO 8601 format, or `null` if not set.
+   */
   dateStarted?: string | null | undefined;
+  /**
+   * The date and time the subscription ends, in ISO 8601 format, or `null` if it has no end date.
+   */
   dateEnds?: string | null | undefined;
+  /**
+   * The status of the subscription, or `null` if not set.
+   */
   status?: string | null | undefined;
+  /**
+   * Whether the subscription is locked, or `null` if not set.
+   */
   locked?: boolean | null | undefined;
+  /**
+   * The title of the product variant the subscription is for.
+   */
   variantTitle?: string | undefined;
   /**
-   * Reduced list of attributes of the Invoice line item record
+   * Reduced list of attributes of the invoice line item record
    */
   currentLineItem?: InvoiceItem | null | undefined;
   /**
-   * Reduced list of attributes of the Invoice line item record
+   * Reduced list of attributes of the invoice line item record
    */
   nextLineItem?: InvoiceItem | null | undefined;
+  /**
+   * The payment status of an invoice or subscription item.
+   */
   currentFinancialStatus?: FinancialStatus | null | undefined;
+  /**
+   * The payment status of an invoice or subscription item.
+   */
   nextFinancialStatus?: FinancialStatus | null | undefined;
+  /**
+   * The product variant offered to the vendor as an expedited upgrade, or `null` if no offer is available.
+   */
   expeditedOffer?: ProductVariant | null | undefined;
 };
 

package/src/models/components/supervisor.ts

@@ -12,8 +12,17 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
  * list of the vendor supervisor attributes
  */
 export type Supervisor = {
+  /**
+   * The full name of the vendor's supervisor, or `null` if not set.
+   */
   name?: string | null | undefined;
+  /**
+   * The email address of the vendor's supervisor, or `null` if not set.
+   */
   email?: string | null | undefined;
+  /**
+   * The phone number of the vendor's supervisor, or `null` if not set.
+   */
   phone?: string | null | undefined;
 };