@greensecurity/javascript-sdk 0.45.0-beta.9 → 0.45.0

package/src/models/components/fullreport.ts

@@ -0,0 +1,193 @@
+/*
+ * 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 { ClosedEnum } 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";
+
+/**
+ * Where the run ended up. A delivery of `FullReport.created` only ever carries a
+ *
+ * @remarks
+ * terminal value; the others are states a run passes through.
+ */
+export const FullReportStatus = {
+  Pending: "pending",
+  Processing: "processing",
+  Completed: "completed",
+  Canceled: "canceled",
+  Failed: "failed",
+} as const;
+/**
+ * Where the run ended up. A delivery of `FullReport.created` only ever carries a
+ *
+ * @remarks
+ * terminal value; the others are states a run passes through.
+ */
+export type FullReportStatus = ClosedEnum<typeof FullReportStatus>;
+
+/**
+ * One run of a report, generated on request or by a schedule. Carries the run's own state
+ *
+ * @remarks
+ * plus which report it was and a short-lived signed link to the file it produced.
+ */
+export type FullReport = {
+  id: number;
+  /**
+   * Where the run ended up. A delivery of `FullReport.created` only ever carries a
+   *
+   * @remarks
+   * terminal value; the others are states a run passes through.
+   */
+  status: FullReportStatus;
+  /**
+   * The report that was run, e.g. `Reports::SqlQueryReport`.
+   */
+  reportClass: string;
+  /**
+   * The subject line of the schedule that produced this run. Null for a run that was
+   *
+   * @remarks
+   * generated on request rather than by a schedule.
+   */
+  name?: string | null | undefined;
+  /**
+   * Signed download link, valid for 2 hours from the moment the delivery was built and
+   *
+   * @remarks
+   * minted fresh for each delivery. Null when the run produced no file, which is every
+   * non-`completed` status.
+   */
+  reportUrl?: string | null | undefined;
+  dateSubmitted?: Date | null | undefined;
+  /**
+   * When the run started generating.
+   */
+  dateCreated?: Date | null | undefined;
+  /**
+   * When the run reached a terminal state. Stamping this is what delivers `created`.
+   */
+  dateCompleted?: Date | null | undefined;
+  /**
+   * Milliseconds spent generating.
+   */
+  durationMs?: number | null | undefined;
+  rowCount?: number | null | undefined;
+  /**
+   * Size of the generated file in bytes.
+   */
+  fileSize?: number | null | undefined;
+  /**
+   * Why a `failed` run failed. Null on every other status.
+   */
+  errorMessage?: string | null | undefined;
+};
+
+/** @internal */
+export const FullReportStatus$inboundSchema: z.ZodNativeEnum<
+  typeof FullReportStatus
+> = z.nativeEnum(FullReportStatus);
+/** @internal */
+export const FullReportStatus$outboundSchema: z.ZodNativeEnum<
+  typeof FullReportStatus
+> = FullReportStatus$inboundSchema;
+
+/** @internal */
+export const FullReport$inboundSchema: z.ZodType<
+  FullReport,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: types.number(),
+  status: FullReportStatus$inboundSchema,
+  report_class: types.string(),
+  name: z.nullable(types.string()).optional(),
+  report_url: z.nullable(types.string()).optional(),
+  date_submitted: z.nullable(types.date()).optional(),
+  date_created: z.nullable(types.date()).optional(),
+  date_completed: z.nullable(types.date()).optional(),
+  duration_ms: z.nullable(types.number()).optional(),
+  row_count: z.nullable(types.number()).optional(),
+  file_size: z.nullable(types.number()).optional(),
+  error_message: z.nullable(types.string()).optional(),
+}).transform((v) => {
+  return remap$(v, {
+    "report_class": "reportClass",
+    "report_url": "reportUrl",
+    "date_submitted": "dateSubmitted",
+    "date_created": "dateCreated",
+    "date_completed": "dateCompleted",
+    "duration_ms": "durationMs",
+    "row_count": "rowCount",
+    "file_size": "fileSize",
+    "error_message": "errorMessage",
+  });
+});
+/** @internal */
+export type FullReport$Outbound = {
+  id: number;
+  status: string;
+  report_class: string;
+  name?: string | null | undefined;
+  report_url?: string | null | undefined;
+  date_submitted?: string | null | undefined;
+  date_created?: string | null | undefined;
+  date_completed?: string | null | undefined;
+  duration_ms?: number | null | undefined;
+  row_count?: number | null | undefined;
+  file_size?: number | null | undefined;
+  error_message?: string | null | undefined;
+};
+
+/** @internal */
+export const FullReport$outboundSchema: z.ZodType<
+  FullReport$Outbound,
+  z.ZodTypeDef,
+  FullReport
+> = z.object({
+  id: z.number().int(),
+  status: FullReportStatus$outboundSchema,
+  reportClass: z.string(),
+  name: z.nullable(z.string()).optional(),
+  reportUrl: z.nullable(z.string()).optional(),
+  dateSubmitted: z.nullable(z.date().transform(v => v.toISOString()))
+    .optional(),
+  dateCreated: z.nullable(z.date().transform(v => v.toISOString())).optional(),
+  dateCompleted: z.nullable(z.date().transform(v => v.toISOString()))
+    .optional(),
+  durationMs: z.nullable(z.number().int()).optional(),
+  rowCount: z.nullable(z.number().int()).optional(),
+  fileSize: z.nullable(z.number().int()).optional(),
+  errorMessage: z.nullable(z.string()).optional(),
+}).transform((v) => {
+  return remap$(v, {
+    reportClass: "report_class",
+    reportUrl: "report_url",
+    dateSubmitted: "date_submitted",
+    dateCreated: "date_created",
+    dateCompleted: "date_completed",
+    durationMs: "duration_ms",
+    rowCount: "row_count",
+    fileSize: "file_size",
+    errorMessage: "error_message",
+  });
+});
+
+export function fullReportToJSON(fullReport: FullReport): string {
+  return JSON.stringify(FullReport$outboundSchema.parse(fullReport));
+}
+export function fullReportFromJSON(
+  jsonString: string,
+): SafeParseResult<FullReport, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => FullReport$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'FullReport' from JSON`,
+  );
+}

package/src/models/components/index.ts

@@ -5,11 +5,13 @@
 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";
 export * from "./companylookup.js";
 export * from "./companymanager.js";
+export * from "./companymanagerlookup.js";
 export * from "./companytargetfacility.js";
 export * from "./companyvendorfield.js";
 export * from "./companyvendortyperestriction.js";
@@ -44,6 +46,7 @@ export * from "./fhirconfigcreate.js";
 export * from "./fhirconfigpartialupdate.js";
 export * from "./fhirextraentities.js";
 export * from "./financialstatus.js";
+export * from "./fullreport.js";
 export * from "./handoff.js";
 export * from "./imageset.js";
 export * from "./invitee.js";
@@ -87,11 +90,13 @@ 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";
 export * from "./supervisor.js";
 export * from "./supportarticle.js";
+export * from "./system.js";
 export * from "./systemsummary.js";
 export * from "./targetfacilitystatuschange.js";
 export * from "./uploadhistoryitem.js";
@@ -120,6 +125,7 @@ export * from "./vendorscanscreeningresponse.js";
 export * from "./vendorscrubdetails.js";
 export * from "./vendorscrubpurchase.js";
 export * from "./vendortargetfacility.js";
+export * from "./vendortargetfacilityscreeningresponse.js";
 export * from "./vendortype.js";
 export * from "./visitorcheckin.js";
 export * from "./webhookconsumers.js";

package/src/models/components/invoice.ts

@@ -69,9 +69,6 @@ export type InvoiceType = OpenEnum<typeof InvoiceType>;
  *
  * This is used exclusively to control the visibility of the "Make Payment" button in the UI.
  * It is not used for any other invoice logic or backend decision-making.
- *
- * Frontend should compare the logged-in user's ID (for vendors) or company_id (for company managers)
- * with these arrays to determine if the payment button should be shown.
  */
 export type MayPayInvoice = {
   /**
@@ -84,6 +81,16 @@ export type MayPayInvoice = {
   companies?: Array<number> | undefined;
 };
 
+export type AssociatedCredentials = {
+  id: number;
+  vendorId: number | null;
+  companyId: number | null;
+  /**
+   * True when the credential's invoice is paid but its required info has not been submitted yet.
+   */
+  awaitingSubmission: boolean;
+};
+
 /**
  * A simplified representation of an Invoice
  */
@@ -131,11 +138,15 @@ export type Invoice = {
    *
    * This is used exclusively to control the visibility of the "Make Payment" button in the UI.
    * It is not used for any other invoice logic or backend decision-making.
-   *
-   * Frontend should compare the logged-in user's ID (for vendors) or company_id (for company managers)
-   * with these arrays to determine if the payment button should be shown.
    */
   mayPayInvoice?: MayPayInvoice | null | undefined;
+  /**
+   * Credentials this invoice pays for, including those on its child invoices, limited to the ones the caller can read. Only included when `invoice.associated_credentials` is requested in the expand parameter.
+   *
+   * @remarks
+   * Frontend should compare the logged-in user's ID (for vendors) or company_id (for company managers) with these arrays to determine if the payment button should be shown.
+   */
+  associatedCredentials?: Array<AssociatedCredentials> | null | undefined;
 };
 
 /** @internal */
@@ -243,6 +254,66 @@ export function mayPayInvoiceFromJSON(
   );
 }
 
+/** @internal */
+export const AssociatedCredentials$inboundSchema: z.ZodType<
+  AssociatedCredentials,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: types.number(),
+  vendor_id: types.nullable(types.number()),
+  company_id: types.nullable(types.number()),
+  awaiting_submission: types.boolean(),
+}).transform((v) => {
+  return remap$(v, {
+    "vendor_id": "vendorId",
+    "company_id": "companyId",
+    "awaiting_submission": "awaitingSubmission",
+  });
+});
+/** @internal */
+export type AssociatedCredentials$Outbound = {
+  id: number;
+  vendor_id: number | null;
+  company_id: number | null;
+  awaiting_submission: boolean;
+};
+
+/** @internal */
+export const AssociatedCredentials$outboundSchema: z.ZodType<
+  AssociatedCredentials$Outbound,
+  z.ZodTypeDef,
+  AssociatedCredentials
+> = z.object({
+  id: z.number().int(),
+  vendorId: z.nullable(z.number().int()),
+  companyId: z.nullable(z.number().int()),
+  awaitingSubmission: z.boolean(),
+}).transform((v) => {
+  return remap$(v, {
+    vendorId: "vendor_id",
+    companyId: "company_id",
+    awaitingSubmission: "awaiting_submission",
+  });
+});
+
+export function associatedCredentialsToJSON(
+  associatedCredentials: AssociatedCredentials,
+): string {
+  return JSON.stringify(
+    AssociatedCredentials$outboundSchema.parse(associatedCredentials),
+  );
+}
+export function associatedCredentialsFromJSON(
+  jsonString: string,
+): SafeParseResult<AssociatedCredentials, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => AssociatedCredentials$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'AssociatedCredentials' from JSON`,
+  );
+}
+
 /** @internal */
 export const Invoice$inboundSchema: z.ZodType<Invoice, z.ZodTypeDef, unknown> =
   z.object({
@@ -269,6 +340,9 @@ export const Invoice$inboundSchema: z.ZodType<Invoice, z.ZodTypeDef, unknown> =
     invoice_type: types.optional(InvoiceType$inboundSchema),
     may_pay_invoice: z.nullable(z.lazy(() => MayPayInvoice$inboundSchema))
       .optional(),
+    associated_credentials: z.nullable(
+      z.array(z.lazy(() => AssociatedCredentials$inboundSchema)),
+    ).optional(),
   }).transform((v) => {
     return remap$(v, {
       "invoice_number": "invoiceNumber",
@@ -282,6 +356,7 @@ export const Invoice$inboundSchema: z.ZodType<Invoice, z.ZodTypeDef, unknown> =
       "custom_fields": "customFields",
       "invoice_type": "invoiceType",
       "may_pay_invoice": "mayPayInvoice",
+      "associated_credentials": "associatedCredentials",
     });
   });
 /** @internal */
@@ -305,6 +380,10 @@ export type Invoice$Outbound = {
   representative?: string | null | undefined;
   invoice_type?: string | undefined;
   may_pay_invoice?: MayPayInvoice$Outbound | null | undefined;
+  associated_credentials?:
+    | Array<AssociatedCredentials$Outbound>
+    | null
+    | undefined;
 };
 
 /** @internal */
@@ -335,6 +414,9 @@ export const Invoice$outboundSchema: z.ZodType<
   invoiceType: InvoiceType$outboundSchema.optional(),
   mayPayInvoice: z.nullable(z.lazy(() => MayPayInvoice$outboundSchema))
     .optional(),
+  associatedCredentials: z.nullable(
+    z.array(z.lazy(() => AssociatedCredentials$outboundSchema)),
+  ).optional(),
 }).transform((v) => {
   return remap$(v, {
     invoiceNumber: "invoice_number",
@@ -348,6 +430,7 @@ export const Invoice$outboundSchema: z.ZodType<
     customFields: "custom_fields",
     invoiceType: "invoice_type",
     mayPayInvoice: "may_pay_invoice",
+    associatedCredentials: "associated_credentials",
   });
 });
 

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",
   });
 });
 

package/src/models/components/passwordnotsetresponse.ts

@@ -20,9 +20,42 @@ export type PasswordNotSetResponse = {
    */
   error: string;
   /**
-   * URL to redirect the user to set their password (forgot password flow). Includes return_url query param when provided in the request.
+   * 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.
    */
   redirectUrl: 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 */
@@ -35,9 +68,11 @@ export const PasswordNotSetResponse$inboundSchema: z.ZodType<
   success: types.boolean(),
   error: types.string(),
   redirect_url: types.string(),
+  sso_state: types.optional(types.string()),
 }).transform((v) => {
   return remap$(v, {
     "redirect_url": "redirectUrl",
+    "sso_state": "ssoState",
   });
 });
 

package/src/models/components/passwordrequiredresponse.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
 import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import * as types from "../../types/primitives.js";
@@ -18,6 +19,39 @@ export type PasswordRequiredResponse = {
    * Error describing the exact condition of what further steps are needed to finish the login process.
    */
   error: 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 */
@@ -29,6 +63,11 @@ export const PasswordRequiredResponse$inboundSchema: z.ZodType<
   requires: types.literal("password"),
   success: types.boolean(),
   error: types.string(),
+  sso_state: types.optional(types.string()),
+}).transform((v) => {
+  return remap$(v, {
+    "sso_state": "ssoState",
+  });
 });
 
 export function passwordRequiredResponseFromJSON(