@greensecurity/javascript-sdk 0.44.0-beta.57 → 0.44.0-beta.59

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 }];
+}

package/src/funcs/reportsInitiateScheduledReport.ts

@@ -0,0 +1,205 @@
+/*
+ * 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";
+
+/**
+ * Generate a scheduled report now
+ *
+ * @remarks
+ * Immediately generates a new report run for a scheduled report, independent of its
+ * configured schedule. Returns a `poll_url` for the generated `FullReport`.
+ *
+ * Generation is asynchronous. Poll `GET /reports/{full_report_id}` on the **status code**,
+ * not on a status field: while the run is pending or processing that endpoint returns `409`
+ * with an error envelope and no `status` to read. Retry the `409` until it turns into `200`,
+ * which carries the `full_report` payload and the signed download URL. `409` is the only
+ * retryable status — a canceled or failed run returns `422`, so no error-message matching is
+ * needed to decide when to give up.
+ *
+ * Bound the retries with your own timeout or attempt limit. Report generation has no terminal
+ * failure state today, so a run whose generation crashed stays in `processing` and answers
+ * `409` indefinitely rather than turning into a `422`.
+ *
+ * Access control: the URL's `scheduled_report_id` must be in the caller's read scope
+ * for `ScheduledReport` — the facility or system it belongs to, a scheduled report the
+ * caller is an explicit recipient of, or a scheduled report whose app is activated for
+ * the API user. Callers outside that scope receive `404 Scheduled report not found`.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function reportsInitiateScheduledReport(
+  client: GreenSecurityCore,
+  request: operations.InitiateScheduledReportRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.InitiateScheduledReportInitiateScheduledReportOk,
+    | 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.InitiateScheduledReportRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.InitiateScheduledReportInitiateScheduledReportOk,
+      | errors.ApiErrorResponse
+      | errors.UnprocessableEntityOrValidationError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      operations.InitiateScheduledReportRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = null;
+
+  const pathParams = {
+    scheduled_report_id: encodeSimple(
+      "scheduled_report_id",
+      payload.scheduled_report_id,
+      { explode: false, charEncoding: "percent" },
+    ),
+  };
+  const path = pathToFunc("/scheduled-reports/{scheduled_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: "initiateScheduledReport",
+    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.InitiateScheduledReportInitiateScheduledReportOk,
+    | errors.ApiErrorResponse
+    | errors.UnprocessableEntityOrValidationError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(
+      200,
+      operations.InitiateScheduledReportInitiateScheduledReportOk$inboundSchema,
+    ),
+    M.jsonErr([400, 401, 403, 404], 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 }];
+}

package/src/funcs/vendorScansVendorScanGpsCheckoutConfig.ts

@@ -0,0 +1,180 @@
+/*
+ * 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";
+
+/**
+ * Automatic GPS check-out configuration
+ *
+ * @remarks
+ * Returns the geofence a client should arm to detect that the vendor has left the location this scan belongs to. A facility that has automatic GPS check-out configured owns the geofence for every one of its zones; only when it does not does the zone's own setting apply.
+ */
+export function vendorScansVendorScanGpsCheckoutConfig(
+  client: GreenSecurityCore,
+  request: operations.VendorScanGpsCheckoutConfigRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.VendorScanGpsCheckoutConfigVendorScanGpsCheckoutConfigOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: operations.VendorScanGpsCheckoutConfigRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.VendorScanGpsCheckoutConfigVendorScanGpsCheckoutConfigOk,
+      | errors.ApiErrorResponse
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      operations.VendorScanGpsCheckoutConfigRequest$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("/vendor-scans/{id}/gps-checkout-config")(pathParams);
+
+  const headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "vendorScanGpsCheckoutConfig",
+    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.VendorScanGpsCheckoutConfigVendorScanGpsCheckoutConfigOk,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(
+      200,
+      operations
+        .VendorScanGpsCheckoutConfigVendorScanGpsCheckoutConfigOk$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 }];
+}