@greensecurity/javascript-sdk 0.45.0-beta.13 → 0.45.0-beta.15

package/src/__tests__/kiosk.test.ts

@@ -0,0 +1,163 @@
+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 rather than `[][]` — see smartBadgeGetPsks.test.ts for why that matters for tshy.
+const { doGetSingleMock, doPostMock, doPutMock } = vi.hoisted(() => ({
+  doGetSingleMock: vi.fn((_route: string, _query: unknown, _options?: unknown) =>
+    Promise.resolve([{ ok: true }, { status: "complete" }])
+  ),
+  doPostMock: vi.fn((_route: string, _body: unknown, _options?: unknown) =>
+    Promise.resolve([{ ok: true }, { status: "complete" }])
+  ),
+  doPutMock: vi.fn((_route: string, _body: unknown, _options?: unknown) =>
+    Promise.resolve([{ ok: true }, { status: "complete" }])
+  ),
+}));
+
+vi.mock("../admin-funcs/doAdmin.js", () => ({
+  $doGetSingle: doGetSingleMock,
+  $doPost: doPostMock,
+  $doPut: doPutMock,
+}));
+
+import { kioskPing2 } from "../admin-funcs/kioskPing2.js";
+import { kioskCreateKioskDevice } from "../admin-funcs/kioskCreateKioskDevice.js";
+import { kioskGetKioskDevice } from "../admin-funcs/kioskGetKioskDevice.js";
+import { kioskUpdateKioskDevice } from "../admin-funcs/kioskUpdateKioskDevice.js";
+import { kioskCreateZoneDevice } from "../admin-funcs/kioskCreateZoneDevice.js";
+import { kioskCreateEvent } from "../admin-funcs/kioskCreateEvent.js";
+import { kioskHeartbeat } from "../admin-funcs/kioskHeartbeat.js";
+
+beforeEach(() => {
+  doGetSingleMock.mockClear();
+  doPostMock.mockClear();
+  doPutMock.mockClear();
+});
+
+describe("kioskPing2", () => {
+  it("calls the unauthenticated liveness route with no query parameters", () => {
+    const request = kioskPing2();
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/kiosks/ping2", {}, undefined);
+    expect(request).toBeDefined();
+  });
+
+  // The reachability probe passes a finite timeout so a half-open request cannot hang forever;
+  // that only works if the option actually reaches $doGetSingle.
+  it("forwards request options (e.g. timeoutMs) through to $doGetSingle", () => {
+    kioskPing2({ timeoutMs: 2000 });
+
+    expect(doGetSingleMock).toHaveBeenLastCalledWith("/kiosks/ping2", {}, { timeoutMs: 2000 });
+  });
+});
+
+describe("kioskCreateKioskDevice", () => {
+  it("posts to the unauthenticated device-registration route with the request body", () => {
+    const request = kioskCreateKioskDevice({ apns_token: "abc", sandbox: true });
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/kiosk-devices", { apns_token: "abc", sandbox: true });
+    expect(request).toBeDefined();
+  });
+});
+
+describe("kioskGetKioskDevice", () => {
+  it("builds the device+id+token path and sends no query parameters", () => {
+    kioskGetKioskDevice(42, "sekret");
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/kiosk-devices/42", {});
+  });
+
+  // The security token authenticates the request, so it must reach the path percent-encoded rather
+  // than dropped or sent as a query parameter.
+  it("percent-encodes the security token", () => {
+    kioskGetKioskDevice(42, "tok/en+with special=chars");
+
+    expect(doGetSingleMock).toHaveBeenCalledWith(
+      "/kiosk-api/42/tok%2Fen%2Bwith%20special%3Dchars/kiosk-devices/42",
+      {}
+    );
+  });
+});
+
+describe("kioskUpdateKioskDevice", () => {
+  it("PUTs the update body to the device+id+token path", () => {
+    const request = kioskUpdateKioskDevice(42, "sekret", { apns_token: "xyz" });
+
+    expect(doPutMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/kiosk-devices/42", { apns_token: "xyz" });
+    expect(request).toBeDefined();
+  });
+
+  it("percent-encodes the security token", () => {
+    kioskUpdateKioskDevice(42, "tok en", { apns_token: "xyz" });
+
+    expect(doPutMock).toHaveBeenCalledWith("/kiosk-api/42/tok%20en/kiosk-devices/42", { apns_token: "xyz" });
+  });
+});
+
+describe("kioskCreateZoneDevice", () => {
+  it("posts the zone id in the body, not the path", () => {
+    kioskCreateZoneDevice(42, "sekret", 7);
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/zone-devices", { zone_id: 7 });
+  });
+
+  it("percent-encodes the security token", () => {
+    kioskCreateZoneDevice(42, "tok en", 7);
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/42/tok%20en/zone-devices", { zone_id: 7 });
+  });
+});
+
+describe("kioskCreateEvent", () => {
+  it("posts the event name and value to the events route", () => {
+    kioskCreateEvent(42, "sekret", "print_job_completed", { pages: 1 });
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/events", {
+      name: "print_job_completed",
+      value: { pages: 1 },
+    });
+  });
+
+  // The ObjC fire-and-forget event calls sometimes have no payload; that must survive as an
+  // explicit null rather than being dropped, since it is what distinguishes "no value" from
+  // "value omitted" server-side.
+  it("normalizes an undefined value to null rather than dropping the field", () => {
+    kioskCreateEvent(42, "sekret", "printer_error", undefined);
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/events", {
+      name: "printer_error",
+      value: null,
+    });
+  });
+
+  it("percent-encodes the security token", () => {
+    kioskCreateEvent(42, "tok en", "printer_error", null);
+
+    expect(doPostMock).toHaveBeenCalledWith("/kiosk-api/42/tok%20en/events", {
+      name: "printer_error",
+      value: null,
+    });
+  });
+});
+
+describe("kioskHeartbeat", () => {
+  it("sends printer status, ip and last-notification timestamp as query parameters", () => {
+    const query = {
+      printer_status: "ok",
+      ip: "10.0.0.5",
+      date_received_notification: "2026-08-27T00:00:00Z",
+    };
+
+    kioskHeartbeat(42, "sekret", query);
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/kiosk-api/42/sekret/ping", query);
+  });
+
+  it("percent-encodes the security token", () => {
+    const query = { printer_status: "ok", ip: "10.0.0.5", date_received_notification: "2026-08-27T00:00:00Z" };
+
+    kioskHeartbeat(42, "tok en", query);
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/kiosk-api/42/tok%20en/ping", query);
+  });
+});

package/src/__tests__/lookups.test.ts

@@ -27,3 +27,27 @@ test("Lookups List Lookup Systems", async () => {
     systems: [],
   });
 });
+
+test("Lookups Lookup Postal Code", async () => {
+  const testHttpClient = createTestHTTPClient("lookupPostalCode");
+
+  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.lookups.lookupPostalCode({
+    postalCode: "12383-0520",
+    state: "Rhode Island",
+    country: "Belgium",
+  });
+  expect(result).toBeDefined();
+  expect(result).toEqual({
+    status: "mismatch",
+    expectedStates: [],
+    error: "<value>",
+  });
+});

package/src/__tests__/vendors.test.ts

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

package/src/__tests__/webhooks.test.ts

@@ -62,10 +62,11 @@ test("Webhooks Updates The Webhook Endpoint With The Given Id", async () => {
       id: 220782,
       webhookEndpointUpdate: {
         webhookUrl: "https://example.com/webhook/incoming",
-        subscriptions: [
-          "Vendor.updated",
-          "Vendor.created",
-        ],
+        subscriptions: {
+          model: "Vendor",
+          action: "updated",
+          expands: "vendor.company,vendor.user",
+        },
         consumers: {
           systemId: 1,
           facilityId: 1,

package/src/__tests__/zones.test.ts

@@ -35,6 +35,9 @@ test("Zones List Or Search Security Zones", async () => {
       useUrlParams: false,
     },
     items: [
+      {
+        facility: {},
+      },
       {
         facility: {
           contacts: {
@@ -43,26 +46,26 @@ test("Zones List Or Search Security Zones", async () => {
               department: 123,
             },
             adminContact: {
-              status: "Active",
+              status: "Inactive",
               department: 123,
             },
             techContact: {
-              status: "Inactive",
+              status: "Active",
+              department: 123,
+            },
+            greenSecurityCsm: {
+              status: "Active",
               department: 123,
             },
-            greenSecurityCsm: null,
             accountManager: null,
           },
           vendorGuestPolicy: {
-            enabled: true,
+            enabled: false,
             vendorGuestLimitAndOr: "and",
-            vendorGuestRequireEmail: false,
+            vendorGuestRequireEmail: true,
           },
         },
       },
-      {
-        facility: {},
-      },
     ],
   });
 });
@@ -80,7 +83,7 @@ test("Zones Security Zone Checkin", async () => {
 
   const result = await greenSecurity.zones.securityZoneCheckin({
     qrCode: "<value>",
-    zoneId: 891667,
+    zoneId: 776072,
   });
   expect(result).toBeDefined();
   expect(result).toEqual({});

package/src/admin-funcs/dismissCommunication.ts

@@ -0,0 +1,20 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+
+// Records that the caller dismissed a communication (GSSD-7336).
+//
+// Internal for the same reason as listCommunications: it only means anything to our own portal.
+//
+// The durable half of a two-layer dismissal — the client suppresses locally straight away so a
+// banner does not flash back while this is in flight, and this row is what makes the timed
+// rules ("after a week", "after a month") hold on a second device. Whether a past dismissal
+// still suppresses anything is decided server-side on the next list call.
+//
+// The server re-checks the caller's audience before writing, so dismissing a communication that
+// was never aimed at you answers 404 rather than creating a row.
+export function dismissCommunication(communicationId: number): internalApiResult {
+  return new APIPromise($doPost(
+    `/communications/${communicationId}/dismiss`,
+    {},
+  ));
+}

package/src/admin-funcs/doAdmin.ts

@@ -308,6 +308,113 @@ export async function $doPost<T extends object>(
   return [result, { status: "complete", request: req, response }];
 }
 
+export async function $doPut<T extends object>(
+  route: string,
+  putData: T,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Json,
+      | errors.ApiErrorResponse
+      | GreenSecurityError
+      | ResponseValidationError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const client = getInternalCore();
+  if (!client) {
+    throw new Error("GreenSecurityCore client is not initialized.");
+  }
+
+  const body = encodeJSON("body", putData, { explode: true });
+
+  // Extract the path parameters from the request object
+  const pathParams = {}; //extractRouteParameters(route, request);
+
+  const path = pathToFunc(route)(pathParams);
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    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: "internalApiRoutes",
+    oAuth2Scopes: [],
+
+    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: "PUT",
+    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, {
+    ...buildDoOptions(context, context.retryConfig, 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<
+    Json,
+    | errors.ApiErrorResponse
+    | GreenSecurityError
+    | ResponseValidationError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json(200, jsonSchema),
+    M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}
+
 export function hashToQueryString(hash: Record<string, any>): string {
   const params = [];
   for (const key in hash) {

package/src/admin-funcs/kioskCreateEvent.ts

@@ -0,0 +1,18 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+
+// Logs a kiosk event (print jobs, printer errors, vending requests, phone
+// home profiles, ...). `value` may be any JSON value or null.
+export function kioskCreateEvent(
+  kioskDeviceId: number,
+  securityToken: string,
+  name: string,
+  value: unknown,
+): internalApiResult {
+  return new APIPromise(
+    $doPost(
+      `/kiosk-api/${kioskDeviceId}/${encodeURIComponent(securityToken)}/events`,
+      { name, value: value ?? null },
+    )
+  );
+}

package/src/admin-funcs/kioskCreateKioskDevice.ts

@@ -0,0 +1,17 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+
+export type KioskCreateKioskDeviceRequest = {
+  apns_token?: string;
+  sandbox?: boolean;
+};
+
+// Registers a new kiosk device. Unauthenticated; the response contains the
+// device id and security token used by all subsequent kiosk-api calls.
+export function kioskCreateKioskDevice(
+  request: KioskCreateKioskDeviceRequest,
+): internalApiResult {
+  return new APIPromise(
+    $doPost(`/kiosk-api/kiosk-devices`, request)
+  );
+}

package/src/admin-funcs/kioskCreateZoneDevice.ts

@@ -0,0 +1,17 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+
+// Registers a zone device for the kiosk's zone. The response includes the
+// zone device id and a base64 PKCS#12 AWS IoT client certificate.
+export function kioskCreateZoneDevice(
+  kioskDeviceId: number,
+  securityToken: string,
+  zoneId: number,
+): internalApiResult {
+  return new APIPromise(
+    $doPost(
+      `/kiosk-api/${kioskDeviceId}/${encodeURIComponent(securityToken)}/zone-devices`,
+      { zone_id: zoneId },
+    )
+  );
+}

package/src/admin-funcs/kioskGetKioskDevice.ts

@@ -0,0 +1,16 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+// Fetches the kiosk device (including its kiosk/zone assignment).
+// Kiosk-api routes authenticate via the device id + security token in the path.
+export function kioskGetKioskDevice(
+  kioskDeviceId: number,
+  securityToken: string,
+): internalApiResult {
+  return new APIPromise(
+    $doGetSingle(
+      `/kiosk-api/${kioskDeviceId}/${encodeURIComponent(securityToken)}/kiosk-devices/${kioskDeviceId}`,
+      {},
+    )
+  );
+}

package/src/admin-funcs/kioskHeartbeat.ts

@@ -0,0 +1,23 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+export type KioskHeartbeatQuery = {
+  printer_status: string;
+  ip: string;
+  date_received_notification: string;
+};
+
+// 60-second keep-alive ping carrying printer status, local IP and the last
+// APNS heartbeat timestamp.
+export function kioskHeartbeat(
+  kioskDeviceId: number,
+  securityToken: string,
+  query: KioskHeartbeatQuery,
+): internalApiResult {
+  return new APIPromise(
+    $doGetSingle(
+      `/kiosk-api/${kioskDeviceId}/${encodeURIComponent(securityToken)}/ping`,
+      query,
+    )
+  );
+}

package/src/admin-funcs/kioskPing2.ts

@@ -0,0 +1,10 @@
+import { APIPromise } from "../types/async.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+// Unauthenticated server liveness probe used by the kiosk before setup.
+export function kioskPing2(options?: RequestOptions): internalApiResult {
+  return new APIPromise(
+    $doGetSingle(`/kiosks/ping2`, {}, options)
+  );
+}

package/src/admin-funcs/kioskUpdateKioskDevice.ts

@@ -0,0 +1,23 @@
+import { APIPromise } from "../types/async.js";
+import { $doPut, internalApiResult } from "./doAdmin.js";
+
+export type KioskUpdateKioskDeviceRequest = {
+  apns_token?: string;
+  kiosk_id?: number;
+  user_id?: number;
+  sandbox?: boolean;
+} & Record<string, unknown>;
+
+// Updates kiosk device fields (e.g. the APNS push token after registration).
+export function kioskUpdateKioskDevice(
+  kioskDeviceId: number,
+  securityToken: string,
+  request: KioskUpdateKioskDeviceRequest,
+): internalApiResult {
+  return new APIPromise(
+    $doPut(
+      `/kiosk-api/${kioskDeviceId}/${encodeURIComponent(securityToken)}/kiosk-devices/${kioskDeviceId}`,
+      request,
+    )
+  );
+}

package/src/admin-funcs/listCommunications.ts

@@ -0,0 +1,29 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, hashToQueryString, internalApiResult } from "./doAdmin.js";
+
+// The banners, pop-ups and in-app notifications aimed at the signed-in user (GSSD-7336).
+//
+// Internal rather than part of the public spec: "the adverts for whoever is holding this token"
+// is only meaningful to our own portal, and a third-party SDK consumer has no use for it. See
+// the public/app-only split in AGENTS.md.
+//
+// The response is already filtered and ordered by the server — audience matched per caller,
+// page matched, anything still suppressed by a dismissal removed, and sorted by priority — so a
+// caller renders the list as it arrives.
+//
+// pageKey narrows to the communications configured for one page. Omitting it returns every
+// communication for the user, which is what a caller that does its own page matching wants.
+export function listCommunications(
+  pageKey?: string | null,
+  itemsPerPage: number = 100,
+): internalApiResult {
+  const query: Record<string, string | number> = { items_per_page: itemsPerPage };
+  if (pageKey) {
+    query["page_key"] = pageKey;
+  }
+
+  return new APIPromise($doGetSingle(
+    `/communications?${hashToQueryString(query)}`,
+    {},
+  ));
+}