@greensecurity/javascript-sdk 0.45.0-beta.16 → 0.45.0-beta.18

package/dist/esm/sdk/users.d.ts

@@ -100,6 +100,43 @@ export declare class Users extends ClientSDK {
      * 3. Site redirects to your selected `return_url`
      * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
      * 5. Fetch the user object from `/users/me` using the token
+     *
+     * ## Finishing a "Login with Green Security" flow
+     *
+     * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+     * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+     * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+     * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+     *
+     * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+     * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+     * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+     * `mfa_code`.
+     *
+     * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+     * value from the response you just received rather than the one you started with. The two are normally the same
+     * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+     * you to hold login state you would otherwise not need.
+     *
+     * 1. Read `sso_state` from the query string of the login screen you were sent to
+     * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+     *    the next request from the previous `202` response
+     * 3. On the `200` response, read `sso.continue_url`
+     * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+     *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+     *    provider
+     * 5. The service provider validates the assertion and the user is signed in on their side
+     *
+     * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+     * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+     * the login still need has to ride the URL. Preserve the query string exactly as given.
+     *
+     * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+     * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+     * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+     * same blob; the user has to start again from the service provider. See the
+     * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+     * guide for the service provider half of this flow.
      */
     postAuthenticate(request: operations.PostAuthenticateRequestBody, options?: RequestOptions): Promise<operations.PostAuthenticateResponse>;
     /**

package/dist/esm/sdk/users.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/sdk/users.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAG5D,qBAAa,KAAM,SAAQ,SAAS;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;;;;;;OAaG;IACG,WAAW,CACf,OAAO,EAAE,UAAU,CAAC,kBAAkB,EACtC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,UAAU,CACd,OAAO,EAAE,UAAU,CAAC,iBAAiB,EACrC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,sBAAsB,CAAC;IAQ7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,gBAAgB,CACpB,OAAO,EAAE,UAAU,CAAC,2BAA2B,EAC/C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,wBAAwB,CAAC;IAQ/C;;;;;OAKG;IACG,YAAY,CAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,0BAA0B,CAAC;IAOjD;;;;;;;;;;;;OAYG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,8BAA8B,CAAC;IAQrD;;;;;OAKG;IACG,aAAa,CACjB,OAAO,EAAE,UAAU,CAAC,wBAAwB,EAC5C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC;IAQhD;;;;;OAKG;IACG,SAAS,CACb,OAAO,EAAE,UAAU,CAAC,oBAAoB,EACxC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC;IAQ3C;;;;;OAKG;IACG,oBAAoB,CACxB,OAAO,EAAE,UAAU,CAAC,+BAA+B,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,0CAA0C,CAAC;IAQjE;;;;;;OAMG;IACG,QAAQ,CACZ,OAAO,EAAE,UAAU,CAAC,mBAAmB,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC;IAQzC;;;;;OAKG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,8BAA8B,CAAC;IAQrD;;;;;OAKG;IACG,wBAAwB,CAC5B,OAAO,EAAE,UAAU,CAAC,+BAA+B,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,kDAAkD,CAAC;CAO1E"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/sdk/users.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAC;AAG5D,qBAAa,KAAM,SAAQ,SAAS;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;;;;;;OAaG;IACG,WAAW,CACf,OAAO,EAAE,UAAU,CAAC,kBAAkB,EACtC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,UAAU,CACd,OAAO,EAAE,UAAU,CAAC,iBAAiB,EACrC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,sBAAsB,CAAC;IAQ7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwEG;IACG,gBAAgB,CACpB,OAAO,EAAE,UAAU,CAAC,2BAA2B,EAC/C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,wBAAwB,CAAC;IAQ/C;;;;;OAKG;IACG,YAAY,CAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,0BAA0B,CAAC;IAOjD;;;;;;;;;;;;OAYG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,8BAA8B,CAAC;IAQrD;;;;;OAKG;IACG,aAAa,CACjB,OAAO,EAAE,UAAU,CAAC,wBAAwB,EAC5C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC;IAQhD;;;;;OAKG;IACG,SAAS,CACb,OAAO,EAAE,UAAU,CAAC,oBAAoB,EACxC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC;IAQ3C;;;;;OAKG;IACG,oBAAoB,CACxB,OAAO,EAAE,UAAU,CAAC,+BAA+B,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,0CAA0C,CAAC;IAQjE;;;;;;OAMG;IACG,QAAQ,CACZ,OAAO,EAAE,UAAU,CAAC,mBAAmB,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC;IAQzC;;;;;OAKG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,CAAC,qBAAqB,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,8BAA8B,CAAC;IAQrD;;;;;OAKG;IACG,wBAAwB,CAC5B,OAAO,EAAE,UAAU,CAAC,+BAA+B,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,kDAAkD,CAAC;CAO1E"}

package/dist/esm/sdk/users.js

@@ -120,6 +120,43 @@ export class Users extends ClientSDK {
      * 3. Site redirects to your selected `return_url`
      * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
      * 5. Fetch the user object from `/users/me` using the token
+     *
+     * ## Finishing a "Login with Green Security" flow
+     *
+     * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+     * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+     * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+     * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+     *
+     * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+     * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+     * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+     * `mfa_code`.
+     *
+     * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+     * value from the response you just received rather than the one you started with. The two are normally the same
+     * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+     * you to hold login state you would otherwise not need.
+     *
+     * 1. Read `sso_state` from the query string of the login screen you were sent to
+     * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+     *    the next request from the previous `202` response
+     * 3. On the `200` response, read `sso.continue_url`
+     * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+     *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+     *    provider
+     * 5. The service provider validates the assertion and the user is signed in on their side
+     *
+     * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+     * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+     * the login still need has to ride the URL. Preserve the query string exactly as given.
+     *
+     * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+     * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+     * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+     * same blob; the user has to start again from the service provider. See the
+     * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+     * guide for the service provider half of this flow.
      */
     async postAuthenticate(request, options) {
         return unwrapAsync(usersPostAuthenticate(this, request, options));

package/dist/esm/sdk/users.js.map

@@ -1 +1 @@
-{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../src/sdk/users.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../src/sdk/users.ts"],"names":[],"mappings":"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"}

package/jsr.json

@@ -2,7 +2,7 @@
 
 {
   "name": "@greensecurity/javascript-sdk",
-  "version": "0.45.0-beta.16",
+  "version": "0.45.0-beta.18",
   "exports": {
     ".": "./src/index.ts",    
     "./models/errors": "./src/models/errors/index.ts",    

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@greensecurity/javascript-sdk",
-  "version": "0.45.0-beta.16",
+  "version": "0.45.0-beta.18",
   "author": "Green Security LLC",
   "type": "module",
   "tshy": {

package/src/__tests__/vendors.test.ts

@@ -121,7 +121,7 @@ test("Vendors List Vendor Credits", async () => {
       page: 1,
       useUrlParams: false,
     },
-    creditBalance: 6030.32,
+    creditBalance: 3532.73,
   });
 });
 

package/src/__tests__/webhooks.test.ts

@@ -20,7 +20,7 @@ test("Webhooks List All Webhook Endpoints", async () => {
   const testWebhookListForVendorUserResult = await greenSecurity.webhooks
     .listAllWebhookEndpoints({
       itemsPerPage: 25,
-      desc: true,
+      desc: 0,
       sort: "",
     });
   expect(testWebhookListForVendorUserResult).toBeDefined();

package/src/__tests__/zones.test.ts

@@ -39,14 +39,7 @@ test("Zones List Or Search Security Zones", async () => {
         facility: {},
       },
       {
-        facility: {
-          contacts: null,
-          vendorGuestPolicy: {
-            enabled: true,
-            vendorGuestLimitAndOr: "and",
-            vendorGuestRequireEmail: false,
-          },
-        },
+        facility: {},
       },
     ],
   });
@@ -65,7 +58,7 @@ test("Zones Security Zone Checkin", async () => {
 
   const result = await greenSecurity.zones.securityZoneCheckin({
     qrCode: "<value>",
-    zoneId: 679291,
+    zoneId: 997849,
   });
   expect(result).toBeDefined();
   expect(result).toEqual({});

package/src/funcs/usersPostAuthenticate.ts

@@ -60,6 +60,43 @@ import { Result } from "../types/fp.js";
  * 3. Site redirects to your selected `return_url`
  * 4. The `user_token` will be appended as a query string parameter to your `return_url` - you must parse this token and store it
  * 5. Fetch the user object from `/users/me` using the token
+ *
+ * ## Finishing a "Login with Green Security" flow
+ *
+ * Green Security is also a SAML2 **identity provider**. When a third-party service provider sends a user to
+ * `/saml/idp/sso` to sign in with their Green Security account, the user lands on a Green Security login screen
+ * carrying an `sso_state` query string parameter. That parameter is a signed, five-minute record of which service
+ * provider is waiting, where its assertion consumer service lives, and what `RelayState` it sent.
+ *
+ * Authentication itself is unchanged - the user may still need a password, an MFA code, a magic link or a round trip
+ * to their own SAML IdP, and every `requires` value above applies as normal. The only difference is that you must
+ * echo `sso_state` back on **every** call in the sequence, unchanged, including the follow-up that carries the
+ * `mfa_code`.
+ *
+ * Each `202` response carries the verified blob back to you in its own top-level `sso_state` field. Send back the
+ * value from the response you just received rather than the one you started with. The two are normally the same
+ * string, but re-sending your original copy is how a blob the server has already rejected gets resent, and it forces
+ * you to hold login state you would otherwise not need.
+ *
+ * 1. Read `sso_state` from the query string of the login screen you were sent to
+ * 2. Run the login exactly as you would otherwise, adding `sso_state` to each request body and taking the value for
+ *    the next request from the previous `202` response
+ * 3. On the `200` response, read `sso.continue_url`
+ * 4. Navigate the browser to `sso.continue_url` - a full page navigation, not a background fetch. It answers with a
+ *    self-submitting form that delivers the signed `SAMLResponse` and the original `RelayState` to the service
+ *    provider
+ * 5. The service provider validates the assertion and the user is signed in on their side
+ *
+ * On the `password_reset` leg the blob is **also** appended to `redirect_url` as a query parameter, alongside
+ * `return_url`. The browser follows that redirect and leaves the JSON body behind, so anything the remaining legs of
+ * the login still need has to ride the URL. Preserve the query string exactly as given.
+ *
+ * An invalid `sso_state` never fails a login. A forged, edited or expired blob is silently dropped and the request is
+ * then treated as an ordinary login, so valid credentials still return `200` - just with no `sso` object. Check for
+ * `sso` explicitly rather than reading `200` as proof the hand-off survived. When it is absent, do not retry with the
+ * same blob; the user has to start again from the service provider. See the
+ * [Login with Green Security](https://greensecurity.apidocumentation.com/guides/sso-login-with-green-security)
+ * guide for the service provider half of this flow.
  */
 export function usersPostAuthenticate(
   client: GreenSecurityCore,

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.45.0-beta.16",
+  sdkVersion: "0.45.0-beta.18",
   genVersion: "2.935.1",
   userAgent:
-    "speakeasy-sdk/typescript 0.45.0-beta.16 2.935.1 0.45.0 @greensecurity/javascript-sdk",
+    "speakeasy-sdk/typescript 0.45.0-beta.18 2.935.1 0.45.0 @greensecurity/javascript-sdk",
 } as const;

package/src/models/components/authenticatesuccessresponse.ts

@@ -0,0 +1,189 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
+import { safeParse } from "../../lib/schemas.js";
+import * as openEnums from "../../types/enums.js";
+import { OpenEnum } from "../../types/enums.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import * as types from "../../types/primitives.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+import { Company, Company$inboundSchema } from "./company.js";
+import { Contact, Contact$inboundSchema } from "./contact.js";
+import {
+  SsoContinuation,
+  SsoContinuation$inboundSchema,
+} from "./ssocontinuation.js";
+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.
+ */
+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.
+ */
+export type AuthenticateSuccessResponseTokenType = OpenEnum<
+  typeof AuthenticateSuccessResponseTokenType
+>;
+
+export type AuthenticateSuccessResponseUserToken = {
+  /**
+   * This token can be passed 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.
+   */
+  tokenType: AuthenticateSuccessResponseTokenType;
+};
+
+export type AuthenticateSuccessResponseInventoryManager = {};
+
+/**
+ * A completed login. Identical to the `User` object returned everywhere
+ *
+ * @remarks
+ * else, plus 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.
+   */
+  isGatekeeper?: boolean | undefined;
+  success: boolean;
+  /**
+   * Core user profile fields returned by user detail and update endpoints.
+   */
+  user: UserDetails;
+  userToken: AuthenticateSuccessResponseUserToken;
+  /**
+   * Vendor details
+   */
+  vendor?: Vendor | undefined;
+  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.
+   */
+  contact?: Contact | null | undefined;
+  /**
+   * A simplified representation of a Company, typically used in list views.
+   */
+  company?: Company | null | undefined;
+  /**
+   * Where to send the browser to finish a "Login with Green Security" flow.
+   *
+   * @remarks
+   *
+   * 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.
+   *
+   * 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
+   * `continue_url`.
+   */
+  sso?: SsoContinuation | undefined;
+};
+
+/** @internal */
+export const AuthenticateSuccessResponseTokenType$inboundSchema: z.ZodType<
+  AuthenticateSuccessResponseTokenType,
+  z.ZodTypeDef,
+  unknown
+> = openEnums.inboundSchema(AuthenticateSuccessResponseTokenType);
+
+/** @internal */
+export const AuthenticateSuccessResponseUserToken$inboundSchema: z.ZodType<
+  AuthenticateSuccessResponseUserToken,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  token: types.string(),
+  token_type: AuthenticateSuccessResponseTokenType$inboundSchema.default(
+    "permanent",
+  ),
+}).transform((v) => {
+  return remap$(v, {
+    "token_type": "tokenType",
+  });
+});
+
+export function authenticateSuccessResponseUserTokenFromJSON(
+  jsonString: string,
+): SafeParseResult<AuthenticateSuccessResponseUserToken, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      AuthenticateSuccessResponseUserToken$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'AuthenticateSuccessResponseUserToken' from JSON`,
+  );
+}
+
+/** @internal */
+export const AuthenticateSuccessResponseInventoryManager$inboundSchema:
+  z.ZodType<
+    AuthenticateSuccessResponseInventoryManager,
+    z.ZodTypeDef,
+    unknown
+  > = z.object({});
+
+export function authenticateSuccessResponseInventoryManagerFromJSON(
+  jsonString: string,
+): SafeParseResult<
+  AuthenticateSuccessResponseInventoryManager,
+  SDKValidationError
+> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      AuthenticateSuccessResponseInventoryManager$inboundSchema.parse(
+        JSON.parse(x),
+      ),
+    `Failed to parse 'AuthenticateSuccessResponseInventoryManager' from JSON`,
+  );
+}
+
+/** @internal */
+export const AuthenticateSuccessResponse$inboundSchema: z.ZodType<
+  AuthenticateSuccessResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  is_gatekeeper: types.optional(types.boolean()),
+  success: types.boolean(),
+  user: UserDetails$inboundSchema,
+  user_token: z.lazy(() => AuthenticateSuccessResponseUserToken$inboundSchema),
+  vendor: types.optional(Vendor$inboundSchema),
+  inventory_manager: types.optional(
+    z.lazy(() => AuthenticateSuccessResponseInventoryManager$inboundSchema),
+  ),
+  contact: z.nullable(Contact$inboundSchema).optional(),
+  company: z.nullable(Company$inboundSchema).optional(),
+  sso: types.optional(SsoContinuation$inboundSchema),
+}).transform((v) => {
+  return remap$(v, {
+    "is_gatekeeper": "isGatekeeper",
+    "user_token": "userToken",
+    "inventory_manager": "inventoryManager",
+  });
+});
+
+export function authenticateSuccessResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<AuthenticateSuccessResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => AuthenticateSuccessResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'AuthenticateSuccessResponse' from JSON`,
+  );
+}

package/src/models/components/index.ts

@@ -5,6 +5,7 @@
 export * from "./activestatus.js";
 export * from "./alert.js";
 export * from "./appointmentsummary.js";
+export * from "./authenticatesuccessresponse.js";
 export * from "./backgroundcheckresult.js";
 export * from "./company.js";
 export * from "./companycredentiallistitem.js";
@@ -89,6 +90,7 @@ export * from "./screeningansweractionsummary.js";
 export * from "./screeningquestion.js";
 export * from "./screeningresponse.js";
 export * from "./security.js";
+export * from "./ssocontinuation.js";
 export * from "./standingappointment.js";
 export * from "./state.js";
 export * from "./subscription.js";

package/src/models/components/loginemailandpassword.ts

@@ -21,6 +21,39 @@ export type LoginEmailAndPassword = {
    * Password as entered by the user
    */
   password: string;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @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
+   * 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
+   * 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
+   * 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
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
@@ -28,6 +61,7 @@ export type LoginEmailAndPassword$Outbound = {
   email: string;
   mfa_code?: string | undefined;
   password: string;
+  sso_state?: string | undefined;
 };
 
 /** @internal */
@@ -39,9 +73,11 @@ export const LoginEmailAndPassword$outboundSchema: z.ZodType<
   email: z.string(),
   mfaCode: z.string().optional(),
   password: z.string(),
+  ssoState: z.string().optional(),
 }).transform((v) => {
   return remap$(v, {
     mfaCode: "mfa_code",
+    ssoState: "sso_state",
   });
 });
 

package/src/models/components/loginrequirementsfromemail.ts

@@ -17,12 +17,46 @@ export type LoginRequirementsFromEmail = {
    * A proper URI where the user should be sent after completing a SAML login. This is encoded into the response you will get if the user requires a SAML login.
    */
   returnUrl: string;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @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
+   * 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
+   * 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
+   * 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
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
 export type LoginRequirementsFromEmail$Outbound = {
   email: string;
   return_url: string;
+  sso_state?: string | undefined;
 };
 
 /** @internal */
@@ -33,9 +67,11 @@ export const LoginRequirementsFromEmail$outboundSchema: z.ZodType<
 > = z.object({
   email: z.string(),
   returnUrl: z.string(),
+  ssoState: z.string().optional(),
 }).transform((v) => {
   return remap$(v, {
     returnUrl: "return_url",
+    ssoState: "sso_state",
   });
 });
 

package/src/models/components/mfarequiredresponse.ts

@@ -36,6 +36,39 @@ export type MfaRequiredResponse = {
    */
   mobilePhone?: string | undefined;
   mfaMethod?: MfaMethod | undefined;
+  /**
+   * Opaque, signed state that Green Security issues when a third-party service
+   *
+   * @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
+   * 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
+   * 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
+   * 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
+   * hold state of its own across the login journey.
+   *
+   * Omit this field entirely for an ordinary login that did not originate
+   * from a service provider.
+   */
+  ssoState?: string | undefined;
 };
 
 /** @internal */
@@ -56,10 +89,12 @@ export const MfaRequiredResponse$inboundSchema: z.ZodType<
   error: types.string(),
   mobile_phone: types.optional(types.string()),
   mfa_method: types.optional(MfaMethod$inboundSchema),
+  sso_state: types.optional(types.string()),
 }).transform((v) => {
   return remap$(v, {
     "mobile_phone": "mobilePhone",
     "mfa_method": "mfaMethod",
+    "sso_state": "ssoState",
   });
 });