@greensecurity/javascript-sdk 0.44.0-beta.56 → 0.44.0-beta.58

package/src/__tests__/reports.test.ts

@@ -0,0 +1,57 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { expect, test } from "vitest";
+import { GreenSecurity } from "../index.js";
+import { createTestHTTPClient } from "./testclient.js";
+
+test("Reports Initiate Scheduled Report", async () => {
+  const testHttpClient = createTestHTTPClient("initiateScheduledReport");
+
+  const greenSecurity = new GreenSecurity({
+    serverURL: process.env["TEST_SERVER_URL"] ?? "https://localhost:3000/api",
+    httpClient: testHttpClient,
+    security: {
+      token: process.env["GREEN_SECURITY_TOKEN"] ?? "value",
+    },
+  });
+
+  const result = await greenSecurity.reports.initiateScheduledReport({
+    scheduledReportId: 298326,
+  });
+  expect(result).toBeDefined();
+  expect(result).toEqual({
+    pollUrl: "https://vivid-spring.info/",
+    success: true,
+  });
+});
+
+test("Reports Get Full Report", async () => {
+  const testHttpClient = createTestHTTPClient("getFullReport");
+
+  const greenSecurity = new GreenSecurity({
+    serverURL: process.env["TEST_SERVER_URL"] ?? "https://localhost:3000/api",
+    httpClient: testHttpClient,
+    security: {
+      token: process.env["GREEN_SECURITY_TOKEN"] ?? "value",
+    },
+  });
+
+  const result = await greenSecurity.reports.getFullReport({
+    fullReportId: 350249,
+  });
+  expect(result).toBeDefined();
+  expect(result).toEqual({
+    fullReport: {
+      id: 833364,
+      reportClass: "<value>",
+      dataType: "blob",
+      dateSubmitted: new Date("2025-11-10T00:32:20.213Z"),
+      userId: 751048,
+      status: "completed",
+      reportUrl: "https://upright-litter.info/",
+    },
+    success: true,
+  });
+});

package/src/__tests__/smartBadgeGetPsks.test.ts

@@ -0,0 +1,76 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// The parameters are declared, rather than `vi.fn(() => ...)`, so that mock.calls is typed as the
+// argument tuple. Without them it is typed `[][]`, destructuring `[route]` off it is a TS2493 error, and
+// tshy compiles this directory even though tsconfig.json excludes it — so it breaks SDK generation
+// rather than anything a local `tsc -p tsconfig.json` or `npm run lint` would report.
+const { doGetSingleMock } = vi.hoisted(() => ({
+  doGetSingleMock: vi.fn((_route: string, _options: unknown) =>
+    Promise.resolve([{ ok: true }, { status: "complete" }])
+  ),
+}));
+
+vi.mock("../admin-funcs/doAdmin.js", () => ({
+  $doGetSingle: doGetSingleMock,
+}));
+
+import { smartBadgeGetPsks } from "../admin-funcs/smartBadgeGetPsks.js";
+
+describe("smartBadgeGetPsks", () => {
+  beforeEach(() => {
+    doGetSingleMock.mockClear();
+  });
+
+  it("calls the badge-specific PSK endpoint with no query parameters", () => {
+    const request = smartBadgeGetPsks("c3000083ba4d");
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/smart-badges/c3000083ba4d/psks", {});
+    expect(request).toBeDefined();
+  });
+
+  // The MAC address is what scopes the response, so it has to reach the path rather than being
+  // dropped or sent as a query parameter. Percent-encoded, because this is interpolated into the path
+  // rather than passed through pathToFunc.
+  it("puts the MAC address in the path, percent-encoded", () => {
+    smartBadgeGetPsks("C3:00:00:83:BA:4D");
+
+    expect(doGetSingleMock).toHaveBeenLastCalledWith("/smart-badges/C3%3A00%3A00%3A83%3ABA%3A4D/psks", {});
+  });
+
+  // Encoding alone did not close this. `.` is in encodeURIComponent's unreserved set, so a bare `..`
+  // passed through untouched and _createRequest's `new URL(path, baseURL)` then canonicalized
+  // `/api/smart-badges/../psks` down to `/api/psks` — off the route entirely, before the backend saw
+  // anything. `.` collapsed to `/api/smart-badges/psks` the same way. Hence validation, not encoding.
+  it.each([["..", "dot-dot"], [".", "single dot"], ["../badge-firmware?x=", "traversal with query"], ["", "empty"]])(
+    "refuses to build a route from %s (%s)",
+    (macAddress) => {
+      expect(() => smartBadgeGetPsks(macAddress)).toThrow(/Invalid smart badge MAC address/);
+      expect(doGetSingleMock).not.toHaveBeenCalled();
+    }
+  );
+
+  it("refuses a MAC address with mixed separators", () => {
+    expect(() => smartBadgeGetPsks("c3:00-00:83:ba:4d")).toThrow(/Invalid smart badge MAC address/);
+  });
+
+  // The dot-separated form normalize_mac_address accepts, which cannot survive a Rails path segment.
+  it("refuses the dot-separated form", () => {
+    expect(() => smartBadgeGetPsks("c300.0083.ba4d")).toThrow(/Invalid smart badge MAC address/);
+  });
+
+  // Asserted on the URL the SDK actually requests, not just the argument handed to the helper, because
+  // the canonicalization that caused this happens in `new URL(path, baseURL)` rather than here.
+  it("survives URL resolution unchanged for every accepted form", () => {
+    const base = new URL("https://api.example.com/api/");
+
+    for (const mac of ["c3000083ba4d", "C3:00:00:83:BA:4D", "c3-00-00-83-ba-4d"]) {
+      doGetSingleMock.mockClear();
+      smartBadgeGetPsks(mac);
+      const [route] = doGetSingleMock.mock.calls.at(-1) ?? [];
+
+      const resolved = new URL(`/api${route}`, base);
+      expect(resolved.pathname).toBe(`/api/smart-badges/${encodeURIComponent(mac)}/psks`);
+      expect(resolved.pathname).toContain("/smart-badges/");
+    }
+  });
+});

package/src/__tests__/smartBadgeReportVerifiedPsk.test.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { doPostMock } = vi.hoisted(() => ({
+  doPostMock: vi.fn((_route: string, _body: unknown) => Promise.resolve([{ ok: true }, { status: "complete" }])),
+}));
+
+vi.mock("../admin-funcs/doAdmin.js", () => ({
+  $doPost: doPostMock,
+}));
+
+import { smartBadgeReportVerifiedPsk } from "../admin-funcs/smartBadgeReportVerifiedPsk.js";
+
+describe("smartBadgeReportVerifiedPsk", () => {
+  beforeEach(() => {
+    doPostMock.mockClear();
+  });
+
+  // Sending the key in the body rather than the query string is a security property of this change:
+  // query strings land in access and proxy logs. $doPost is what puts it in the body, so a switch to
+  // $doGetSingle-style query passing has to fail here.
+  it("sends the key in the request body, not the path or query", () => {
+    const psk = "d8e5f864952dfded7125ee61bd1d7925";
+
+    const request = smartBadgeReportVerifiedPsk("c3000083ba4d", { psk });
+
+    expect(doPostMock).toHaveBeenCalledWith("/smart-badges/c3000083ba4d/psk-verified", { psk });
+    expect(request).toBeDefined();
+  });
+
+  // This POST is authenticated, so a MAC that escapes the route redirects a write rather than a read.
+  // `..` is the case encoding could not catch: encodeURIComponent leaves `.` alone and _createRequest's
+  // `new URL(path, baseURL)` then canonicalizes `/api/smart-badges/../psk-verified` to
+  // `/api/psk-verified`.
+  it.each([["..", "dot-dot"], [".", "single dot"], ["../../zones/badge-write-failed", "traversal"], ["", "empty"]])(
+    "refuses to build a route from %s (%s)",
+    (macAddress) => {
+      expect(() => smartBadgeReportVerifiedPsk(macAddress, { psk: "d8e5f864952dfded7125ee61bd1d7925" })).toThrow(
+        /Invalid smart badge MAC address/
+      );
+      expect(doPostMock).not.toHaveBeenCalled();
+    }
+  );
+
+  // Asserted after URL resolution, since that is where the canonicalization happens.
+  it("keeps an accepted MAC address on the badge route through URL resolution", () => {
+    smartBadgeReportVerifiedPsk("c3:00:00:83:ba:4d", { psk: "d8e5f864952dfded7125ee61bd1d7925" });
+
+    const [route] = doPostMock.mock.calls.at(-1) ?? [];
+    const resolved = new URL(`/api${route}`, new URL("https://api.example.com/api/"));
+    expect(resolved.pathname).toBe("/api/smart-badges/c3%3A00%3A00%3A83%3Aba%3A4d/psk-verified");
+  });
+
+  it("does not put the key anywhere in the route", () => {
+    const psk = "d8e5f864952dfded7125ee61bd1d7925";
+
+    smartBadgeReportVerifiedPsk("c3000083ba4d", { psk });
+
+    const [route] = doPostMock.mock.calls.at(-1) ?? [];
+    expect(route).not.toContain(psk);
+  });
+});

package/src/__tests__/vendors.test.ts

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

package/src/__tests__/vendorscans.test.ts

@@ -198,3 +198,53 @@ test("Vendor Scans Download Vendor Scans Export", async () => {
     ),
   ).toEqual(await filesToByteArray(".speakeasy/testfiles/example.file"));
 });
+
+test("Vendor Scans Vendor Scan Gps Checkout Config", async () => {
+  const testHttpClient = createTestHTTPClient("vendorScanGpsCheckoutConfig");
+
+  const greenSecurity = new GreenSecurity({
+    serverURL: process.env["TEST_SERVER_URL"] ?? "https://localhost:3000/api",
+    httpClient: testHttpClient,
+    security: {
+      token: process.env["GREEN_SECURITY_TOKEN"] ?? "value",
+    },
+  });
+
+  const result = await greenSecurity.vendorScans.vendorScanGpsCheckoutConfig({
+    id: 603032,
+  });
+  expect(result).toBeDefined();
+  expect(result).toEqual({
+    enabled: true,
+    level: "facility",
+    latitude: 6011.7,
+    longitude: 1303.03,
+    radiusFt: 569907,
+    locationName: "<value>",
+  });
+});
+
+test("Vendor Scans Vendor Scan Gps Scan Out", async () => {
+  const testHttpClient = createTestHTTPClient("vendorScanGpsScanOut");
+
+  const greenSecurity = new GreenSecurity({
+    serverURL: process.env["TEST_SERVER_URL"] ?? "https://localhost:3000/api",
+    httpClient: testHttpClient,
+    security: {
+      token: process.env["GREEN_SECURITY_TOKEN"] ?? "value",
+    },
+  });
+
+  const result = await greenSecurity.vendorScans.vendorScanGpsScanOut({
+    id: 818416,
+    requestBody: {
+      latitude: 9788.59,
+      longitude: 5803.63,
+    },
+  });
+  expect(result).toBeDefined();
+  expect(result).toEqual({
+    success: true,
+    outcome: "possibly_left",
+  });
+});

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: 0,
+      desc: true,
       sort: "",
     });
   expect(testWebhookListForVendorUserResult).toBeDefined();

package/src/__tests__/zones.test.ts

@@ -35,40 +35,37 @@ test("Zones List Or Search Security Zones", async () => {
       useUrlParams: false,
     },
     items: [
-      {
-        facility: {},
-      },
       {
         facility: {
           contacts: {
-            contact: {
-              status: "Active",
-              department: 123,
-            },
+            contact: null,
             adminContact: {
-              status: "Active",
+              status: "Inactive",
               department: 123,
             },
             techContact: {
-              status: "Inactive",
+              status: "Deleted",
               department: 123,
             },
             greenSecurityCsm: {
               status: "Active",
-              department: 123,
+              department: null,
             },
             accountManager: {
-              status: "Inactive",
+              status: "Active",
               department: 123,
             },
           },
           vendorGuestPolicy: {
-            enabled: false,
+            enabled: true,
             vendorGuestLimitAndOr: "and",
             vendorGuestRequireEmail: false,
           },
         },
       },
+      {
+        facility: {},
+      },
     ],
   });
 });
@@ -85,9 +82,9 @@ test("Zones Security Zone Checkin", async () => {
   });
 
   const result = await greenSecurity.zones.securityZoneCheckin({
-    longitude: 6436.85,
-    latitude: 6346.87,
-    zoneId: 138233,
+    longitude: 4275.84,
+    latitude: 5120.17,
+    zoneId: 673216,
   });
   expect(result).toBeDefined();
   expect(result).toEqual({});

package/src/admin-funcs/smartBadgeGetPsks.ts

@@ -0,0 +1,23 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+import { smartBadgeMacAddressPathSegment } from "./smartBadgeMacAddress.js";
+
+// The pre-shared keys to try when writing to a smart badge, in the order worth trying.
+//
+// Badges from the two production runs carry different keys and only the badge can say which one it
+// holds, so the backend derives the candidates and the client works through them. This exists so
+// clients do not have to hold any key in code.
+//
+// macAddress may be bare hex, colon-separated or dash-separated, and the backend normalizes it. Not
+// the dot-separated form: Rails treats a dot in a path segment as a format separator, so
+// `c300.0083.ba4d` would not reach this route at all.
+//
+// Validated and encoded before it reaches the path, rather than interpolated raw: this builds the route
+// directly instead of going through pathToFunc, which is what applies charEncoding for generated
+// operations. See smartBadgeMacAddress for why encoding alone is not enough.
+export function smartBadgeGetPsks(macAddress: string): internalApiResult {
+  return new APIPromise($doGetSingle(
+      `/smart-badges/${smartBadgeMacAddressPathSegment(macAddress)}/psks`,
+      {}
+  ));
+}

package/src/admin-funcs/smartBadgeMacAddress.ts

@@ -0,0 +1,25 @@
+// Turns a badge MAC address into a path segment for the smart badge routes.
+//
+// Validated rather than only encoded. encodeURIComponent leaves `.` untouched — it is in the unreserved
+// set — and GreenSecurityCore._createRequest resolves the finished route with `new URL(path, baseURL)`
+// (lib/sdks.ts:136), which canonicalizes dot segments. So a macAddress of `..` survives encoding intact
+// and turns `/api/smart-badges/../psks` into `/api/psks`, leaving the intended route before the backend
+// validates anything; `.` collapses to `/api/smart-badges/psks` the same way. Encoding cannot close
+// that, because there is nothing to encode. Rejecting anything that is not a MAC address can.
+//
+// The accepted forms are bare hex, colon-separated and dash-separated, matching what the backend's
+// VendorScan.normalize_mac_address handles minus the dot-separated form: Rails treats a dot in a path
+// segment as a format separator, so that form never reaches these routes anyway. The backreference
+// keeps the separator consistent, so `c3:00-00:83:ba:4d` is not accepted either.
+const MAC_ADDRESS = /^(?:[0-9a-fA-F]{12}|[0-9a-fA-F]{2}([:-])(?:[0-9a-fA-F]{2}\1){4}[0-9a-fA-F]{2})$/;
+
+export function smartBadgeMacAddressPathSegment(macAddress: string): string {
+  if (!MAC_ADDRESS.test(macAddress)) {
+    throw new Error(
+      "Invalid smart badge MAC address: expected 12 hex digits, optionally colon- or dash-separated, " +
+        `got ${JSON.stringify(macAddress)}`
+    );
+  }
+
+  return encodeURIComponent(macAddress);
+}

package/src/admin-funcs/smartBadgeReportVerifiedPsk.ts

@@ -0,0 +1,25 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+import { smartBadgeMacAddressPathSegment } from "./smartBadgeMacAddress.js";
+
+export type smartBadgeReportVerifiedPskRequest = {
+  psk: string;
+};
+
+// Records which pre-shared key a badge actually accepted, so the next write to it goes straight to
+// that key instead of paying for a rejected handshake and a reconnect.
+//
+// The key travels in the body rather than the query string to keep it out of access and proxy logs.
+//
+// macAddress is validated and encoded for the same reason as in smartBadgeGetPsks, and it matters more
+// here: this request is an authenticated POST, so a value that escapes the route redirects that rather
+// than a read.
+export function smartBadgeReportVerifiedPsk(
+  macAddress: string,
+  request: smartBadgeReportVerifiedPskRequest
+): internalApiResult {
+  return new APIPromise($doPost(
+      `/smart-badges/${smartBadgeMacAddressPathSegment(macAddress)}/psk-verified`,
+      request
+  ));
+}

package/src/funcs/reportsGetFullReport.ts

@@ -0,0 +1,204 @@
+/*
+ * 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";
+
+/**
+ * Get a generated report's status and download URL
+ *
+ * @remarks
+ * Returns a completed report run and a short-lived signed `report_url` (valid 5 minutes).
+ *
+ * Only a completed run returns the `full_report` payload. A run that has not finished does
+ * **not** come back with a `status` field to inspect — it returns an error envelope. Poll on
+ * the status code alone; `409` is the only retryable outcome, so no error-message matching is
+ * needed:
+ *
+ * | Status | Meaning | What to do |
+ * | --- | --- | --- |
+ * | `200` | The run finished. | Download `full_report.report_url` within 5 minutes. |
+ * | `409` | Still pending or processing. | Retry, but bound it — see below. |
+ * | `422` | Terminal: the run was canceled or failed, or the id is not a positive integer. | Stop. |
+ * | `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
+ * 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
+ * `FullReport` — the facility or system it was run for, a recipient of the schedule that
+ * produced it, or a report whose app is activated for the API user. Callers outside that
+ * scope receive `404 Full report not found`.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function reportsGetFullReport(
+  client: GreenSecurityCore,
+  request: operations.GetFullReportRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.GetFullReportGetFullReportOk,
+    | errors.ApiErrorResponse
+    | errors.UnprocessableEntityOrValidationError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: operations.GetFullReportRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.GetFullReportGetFullReportOk,
+      | errors.ApiErrorResponse
+      | errors.UnprocessableEntityOrValidationError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => operations.GetFullReportRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = null;
+
+  const pathParams = {
+    full_report_id: encodeSimple("full_report_id", payload.full_report_id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/reports/{full_report_id}")(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: "getFullReport",
+    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,
+    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.GetFullReportGetFullReportOk,
+    | errors.ApiErrorResponse
+    | errors.UnprocessableEntityOrValidationError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.GetFullReportGetFullReportOk$inboundSchema),
+    M.jsonErr([400, 401, 403, 404, 409], errors.ApiErrorResponse$inboundSchema),
+    M.jsonErr(422, errors.UnprocessableEntityOrValidationError$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 }];
+}