@greensecurity/javascript-sdk 0.45.0-beta.2 → 0.45.0-beta.20

package/src/funcs/invoicesConvertQuote.ts

@@ -0,0 +1,190 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeSimple } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Convert a quote into an invoice
+ *
+ * @remarks
+ * Converts a quote into the real invoice its caller will be charged for, and
+ * returns the new invoice with its calculated totals. Any `VendorCredential`
+ * linked to the quote is re-pointed at the new invoice.
+ *
+ * The operation is idempotent: converting a quote that has already been
+ * processed returns the invoice previously created from it rather than
+ * creating a second one, so a retried request is safe.
+ *
+ * The referenced invoice must actually be a quote — a non-quote invoice id
+ * responds `400`. Requires a caller whose access scope permits creating
+ * invoices; a caller allowed to create the invoice but not to update the
+ * linked `VendorCredential` responds `401`.
+ *
+ * Takes no request body.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function invoicesConvertQuote(
+  client: GreenSecurityCore,
+  request: operations.ConvertQuoteRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.ConvertQuoteConvertQuoteOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: operations.ConvertQuoteRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.ConvertQuoteConvertQuoteOk,
+      | errors.ApiErrorResponse
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => operations.ConvertQuoteRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = null;
+
+  const pathParams = {
+    id: encodeSimple("id", payload.id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/invoices/{id}/convert")(pathParams);
+
+  const headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "convertQuote",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.ConvertQuoteConvertQuoteOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.ConvertQuoteConvertQuoteOk$inboundSchema),
+    M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/lookupsLookupPostalCode.ts

@@ -0,0 +1,193 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Check a postal code against a state and country
+ *
+ * @remarks
+ * Cross-checks a postal code against a state/province and country, the same check
+ * every write path that stores a US or Canadian address enforces server-side (e.g.
+ * `PUT /users/{id}`, `PUT /vendors/{vendor_id_or_me}`). Useful for validating an
+ * address before submitting it elsewhere.
+ *
+ * `status` is one of:
+ * - `ok` — the postal code belongs to the given state/province.
+ * - `invalid` — the postal code is not shaped like a real one for the given country.
+ * - `mismatch` — the postal code is well-formed but belongs to a different state or
+ *   province. `expected_states` names the state(s) it actually maps to.
+ * - `unknown` — nothing to check against (an unsupported country, or a postal code
+ *   absent from the US ZIP dataset). Treated as acceptable by every write path that
+ *   uses this check.
+ *
+ * Only the US and Canada have a real code-to-subdivision map; every other country
+ * always returns `unknown`.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function lookupsLookupPostalCode(
+  client: GreenSecurityCore,
+  request: operations.LookupPostalCodeRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.LookupPostalCodeLookupPostalCodeOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: operations.LookupPostalCodeRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.LookupPostalCodeLookupPostalCodeOk,
+      | errors.ApiErrorResponse
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => operations.LookupPostalCodeRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = null;
+
+  const path = pathToFunc("/lookups/postal-code")();
+
+  const query = encodeFormQuery({
+    "country": payload.country,
+    "postal_code": payload.postal_code,
+    "state": payload.state,
+  });
+
+  const headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "lookupPostalCode",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    query: query,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.LookupPostalCodeLookupPostalCodeOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.LookupPostalCodeLookupPostalCodeOk$inboundSchema),
+    M.jsonErr([400, 401, 422], errors.ApiErrorResponse$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/organizationsExportCompanyTargetFacilities.ts

@@ -3,7 +3,7 @@
  */
 
 import { GreenSecurityCore } from "../core.js";
-import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { encodeFormQuery, encodeSimple, queryJoin } from "../lib/encodings.js";
 import { matchStatusCode } from "../lib/http.js";
 import * as M from "../lib/matchers.js";
 import { compactMap } from "../lib/primitives.js";
@@ -111,20 +111,25 @@ async function $do(
     pathParams,
   );
 
-  const query = encodeFormQuery({
-    "address_like": payload.address_like,
-    "city_like": payload.city_like,
-    "desc": payload.desc,
-    "facility_name_like": payload.facility_name_like,
-    "has_active_individual": payload.has_active_individual,
-    "has_individual": payload.has_individual,
-    "items_per_page": payload.items_per_page,
-    "search_like": payload.search_like,
-    "sort": payload.sort,
-    "state_like": payload.state_like,
-    "status": payload.status,
-    "system_name_like": payload.system_name_like,
-  });
+  const query = queryJoin(
+    encodeFormQuery({
+      "system_ids": payload.system_ids,
+    }, { explode: false }),
+    encodeFormQuery({
+      "address_like": payload.address_like,
+      "city_like": payload.city_like,
+      "desc": payload.desc,
+      "facility_name_like": payload.facility_name_like,
+      "has_active_individual": payload.has_active_individual,
+      "has_individual": payload.has_individual,
+      "items_per_page": payload.items_per_page,
+      "search_like": payload.search_like,
+      "sort": payload.sort,
+      "state_like": payload.state_like,
+      "status": payload.status,
+      "system_name_like": payload.system_name_like,
+    }),
+  );
 
   const headers = new Headers(compactMap({
     Accept: "application/json",

package/src/funcs/organizationsListCompanyTargetFacilities.ts

@@ -136,6 +136,7 @@ async function $do(
   const query = queryJoin(
     encodeFormQuery({
       "expand": payload.expand,
+      "system_ids": payload.system_ids,
     }, { explode: false }),
     encodeFormQuery({
       "address_like": payload.address_like,

package/src/funcs/reportsGetFullReport.ts

@@ -45,9 +45,9 @@ import { Result } from "../types/fp.js";
  * | `404` | No such run, or it is outside your access scope. | Stop. |
  * | `403` | Your account is locked, or lacks the `scheduled_reports` view permission. | Stop. |
  *
- * **Bound your polling.** A `409` is not a promise that the run will finish. Report
- * generation has no terminal failure state today, so a run whose generation crashed part way
- * through stays in `processing` and keeps answering `409` indefinitely. Apply your own
+ * **Bound your polling.** A `409` is not a promise that the run will finish. A run that fails
+ * while generating is now recorded as `failed` and answers `422`, but a run whose worker died
+ * outright still stays in `processing` and keeps answering `409` indefinitely. Apply your own
  * timeout or maximum attempt count and treat exhaustion as a failure; do not retry forever.
  *
  * Access control: the URL's `full_report_id` must be in the caller's read scope for

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/funcs/usersUpdateUser.ts

@@ -37,6 +37,12 @@ import { Result } from "../types/fp.js";
  * Only submitted fields are applied — unrecognised fields are silently ignored.
  * Changing `email` automatically resets `bounced_email` to `false`.
  *
+ * Submitting `zip`, `state`, or `country` cross-checks the postal code against the
+ * resulting state/country (using the existing value for any of the three left out
+ * of the request). A code that is not shaped like a real postal code, or that
+ * provably belongs to a different state, is rejected with `422` naming the correct
+ * state.
+ *
  * Each subkey of `email_preferences` is independently optional; sending
  * `{ "email_preferences": { "send_weekly_summary_email": true } }` flips
  * only that flag and leaves the others unchanged.

package/src/funcs/validateWebhook.ts

@@ -21,6 +21,9 @@ export async function validateWebhook(client: GreenSecurityCore, {
   secret: string;
 }): Promise<
   Result<
+    | webhooks.SendFullReportCreatedRequest
+    | webhooks.SendFullReportUpdatedRequest
+    | webhooks.SendFullReportDestroyedRequest
     | webhooks.SendVendorCreatedRequest
     | webhooks.SendVendorUpdatedRequest
     | webhooks.SendVendorDestroyedRequest
@@ -43,6 +46,9 @@ export async function validateWebhook(client: GreenSecurityCore, {
   }
   const jsonString = await request.text();
   const knownSchemas = [
+    webhooks.sendFullReportCreatedRequestFromJSON,
+    webhooks.sendFullReportUpdatedRequestFromJSON,
+    webhooks.sendFullReportDestroyedRequestFromJSON,
     webhooks.sendVendorCreatedRequestFromJSON,
     webhooks.sendVendorUpdatedRequestFromJSON,
     webhooks.sendVendorDestroyedRequestFromJSON,

package/src/funcs/vendorsCreateVendor.ts

@@ -36,6 +36,10 @@ import { Result } from "../types/fp.js";
  * All other callers must provide `company_id`. The caller must have access to the
  * specified company (verified via scoped access policy) and the `vendors:add` permission.
  *
+ * `zip` is cross-checked against `state`: a code that is not shaped like a real postal
+ * code, or that provably belongs to a different state, is rejected with `422` naming
+ * the correct state.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function vendorsCreateVendor(

package/src/funcs/vendorsGetVendorCredentialDetails.ts

@@ -36,6 +36,7 @@ import { Result } from "../types/fp.js";
  *   - vendor_credential.credential
  *   - vendor_credential.vendor
  *   - vendor_credential.invoice
+ *   - vendor_credential.quote
  *   - vendor_credential.vendor_credential_files
  *   - vendor_credential.latest_vendor_credential_id
  *   - vendor_credential.previously_approved