@greensecurity/javascript-sdk 0.45.0 → 0.46.0-beta.1

package/src/admin-funcs/doAdmin.ts

@@ -201,11 +201,7 @@ export async function $doGetSingle<T extends object>(
   return [result, { status: "complete", request: req, response }];
 }
 
-export async function $doPost<T extends object>(
-  route: string,
-  postData: T,
-  options?: RequestOptions,
-): Promise<
+type PostResult = Promise<
   [
     Result<
       Json,
@@ -221,21 +217,29 @@ export async function $doPost<T extends object>(
     >,
     APICall,
   ]
-> {
+>;
+
+// Shared by the JSON and multipart posts below: everything except how the body is built and
+// whether we name a Content-Type. A multipart body must NOT carry one, because only fetch can
+// append the boundary it generates.
+async function $doPostBody(
+  route: string,
+  body: BodyInit | undefined,
+  contentTypeHeader: Record<string, string>,
+  options?: RequestOptions,
+): PostResult {
   const client = getInternalCore();
   if (!client) {
     throw new Error("GreenSecurityCore client is not initialized.");
   }
 
-  const body = encodeJSON("body", postData, { 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",
+    ...contentTypeHeader,
     Accept: "application/json",
   }));
 
@@ -297,7 +301,13 @@ export async function $doPost<T extends object>(
     | ConnectionError
   >(
     M.json(200, jsonSchema),
-    M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
+    // A REST create answers 201, which matches none of the cases below — an unmatched status is
+    // an error, so the caller saw a failure for a request the server had accepted.
+    M.json(201, jsonSchema),
+    // 422 is a real answer here, not a surprise: the create returns it for a refused certificate
+    // and for a model validation failure. Left out, it fell through to M.fail("4XX"), which
+    // yields a generic APIError and hides the server's message from the form.
+    M.jsonErr([400, 401, 403, 404, 422], errors.ApiErrorResponse$inboundSchema),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });
@@ -308,6 +318,29 @@ export async function $doPost<T extends object>(
   return [result, { status: "complete", request: req, response }];
 }
 
+export async function $doPost<T extends object>(
+  route: string,
+  postData: T,
+  options?: RequestOptions,
+): PostResult {
+  return $doPostBody(
+    route,
+    encodeJSON("body", postData, { explode: true }),
+    { "Content-Type": "application/json" },
+    options,
+  );
+}
+
+// For a route that takes a file alongside its fields. The caller builds the FormData so it owns
+// the field naming the server expects (`wifi[ssid]`, `facility_ids[]`).
+export async function $doPostForm(
+  route: string,
+  form: FormData,
+  options?: RequestOptions,
+): PostResult {
+  return $doPostBody(route, form, {}, options);
+}
+
 export async function $doPut<T extends object>(
   route: string,
   putData: T,

package/src/admin-funcs/networksCreate.ts

@@ -0,0 +1,101 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, $doPostForm, internalApiResult } from "./doAdmin.js";
+
+export type networkIpConfig = "DHCP" | "Static";
+export type networkEncryptionType = "WPA2-PSK" | "WPA2-EAP";
+export type networkAuthMethod = "EAP-TLS" | "PEAP" | "EAP-TTLS" | "EAP-GTC";
+
+export type networkEthernetSettings = {
+  ip_config?: networkIpConfig;
+  ip_address?: string;
+  netmask?: string;
+  gateway_address?: string;
+};
+
+export type networkWifiSettings = {
+  ssid?: string;
+  identity?: string;
+  password?: string;
+  encryption_type?: networkEncryptionType;
+  pre_shared_key?: string;
+  auth_method?: networkAuthMethod;
+  ip_config?: networkIpConfig;
+  ip_address?: string;
+  netmask?: string;
+  gateway_address?: string;
+};
+
+// A file to send with the create. React Native's FormData takes this shape rather than a Blob.
+export type networksCreateCertificate = {
+  uri: string;
+  name: string;
+  type: string;
+};
+
+// Keys are the wire names rather than camelCase because the object is posted verbatim, the same
+// way subscriptionUpdateFacilitiesRequest is.
+export type networksCreateRequest = {
+  name: string;
+  facility_ids: number[];
+  setup_complete?: boolean;
+  ethernet?: networkEthernetSettings;
+  wifi?: networkWifiSettings;
+};
+
+// Creates a network and links it to the facilities that will use it.
+//
+// Internal for the same reason as networksList: provisioning our own hardware, and this one also
+// carries Wi-Fi credentials. See the public/app-only split in AGENTS.md.
+//
+// The enum-shaped fields are spelled out as unions because the server rejects anything outside
+// them, and a rejected network is worth catching at the call site rather than as a 422. The
+// response is still untyped Json, so this only buys safety on the way in.
+//
+// facility_ids is authorized before anything persists: naming a facility the caller cannot reach
+// fails the whole create rather than silently dropping that link.
+// A certificate turns the request multipart. Without one the JSON path is unchanged, which
+// matters because every existing caller goes through it.
+export function networksCreate(
+  request: networksCreateRequest,
+  certificate?: networksCreateCertificate,
+): internalApiResult {
+  if (!certificate) {
+    return new APIPromise($doPost("/networks", request));
+  }
+
+  const form = new FormData();
+  appendField(form, "name", request.name);
+  request.facility_ids.forEach((id) => form.append("facility_ids[]", String(id)));
+  if (request.setup_complete !== undefined) {
+    appendField(form, "setup_complete", request.setup_complete);
+  }
+  appendSection(form, "ethernet", request.ethernet);
+  appendSection(form, "wifi", request.wifi);
+  // RN's FormData accepts {uri,name,type} where the DOM expects a Blob, hence the cast.
+  form.append("certificate", certificate as unknown as Blob);
+
+  return new APIPromise($doPostForm("/networks", form));
+}
+
+function appendField(form: FormData, key: string, value: string | number | boolean): void {
+  form.append(key, String(value));
+}
+
+// Nested as `wifi[ssid]`, which is the shape Rails parses back into a nested hash — so the
+// handler's payload contract is identical either way. Undefined and empty values are left out:
+// the handler drops empty form values anyway, and omitting a section means "not configured".
+function appendSection(
+  form: FormData,
+  name: string,
+  section: Record<string, string | undefined> | undefined,
+): void {
+  if (!section) {
+    return;
+  }
+
+  Object.entries(section).forEach(([key, value]) => {
+    if (value !== undefined && value !== "") {
+      appendField(form, `${name}[${key}]`, value);
+    }
+  });
+}

package/src/admin-funcs/networksGet.ts

@@ -0,0 +1,13 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+// One network, for the screen that edits it after networksList picked it out.
+//
+// Internal for the same reason as networksList: provisioning our own hardware. See the
+// public/app-only split in AGENTS.md.
+//
+// A network outside the caller's scope answers 404 rather than 403, so a caller cannot use the
+// response to learn that an id it may not reach exists.
+export function networksGet(networkId: number): internalApiResult {
+  return new APIPromise($doGetSingle(`/networks/${networkId}`, {}));
+}

package/src/admin-funcs/networksList.ts

@@ -0,0 +1,56 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+export type networksListSortField =
+  | "id"
+  | "name"
+  | "setup_complete"
+  | "created_at"
+  | "updated_at";
+
+export type networksListRequest = {
+  facilityId?: number;
+  setupComplete?: boolean;
+  page?: number;
+  itemsPerPage?: number;
+  sort?: networksListSortField;
+  desc?: boolean;
+};
+
+// The Wi-Fi/Ethernet configurations a facility hands to its Gatekeeper devices.
+//
+// Internal rather than part of the public spec: a network only means anything to the admin
+// surfaces that provision our own hardware, and it carries the shape of credentials we hold on
+// the operator's behalf — not something a third-party SDK consumer has any use for. See the
+// public/app-only split in AGENTS.md.
+//
+// Every filter is optional and the server answers with the caller's own scope when none is
+// given, so the no-argument call is the safe default rather than a request for everything.
+//
+// setupComplete is checked against undefined rather than for truthiness: `false` is a filter a
+// caller genuinely wants (the networks still being provisioned), not an absent one.
+export function networksList(
+  request: networksListRequest = {},
+): internalApiResult {
+  const query: Record<string, string | number | boolean> = {};
+  if (request.facilityId !== undefined) {
+    query["facility_id"] = request.facilityId;
+  }
+  if (request.setupComplete !== undefined) {
+    query["setup_complete"] = request.setupComplete;
+  }
+  if (request.page !== undefined) {
+    query["page"] = request.page;
+  }
+  if (request.itemsPerPage !== undefined) {
+    query["items_per_page"] = request.itemsPerPage;
+  }
+  if (request.sort !== undefined) {
+    query["sort"] = request.sort;
+  }
+  if (request.desc !== undefined) {
+    query["desc"] = request.desc;
+  }
+
+  return new APIPromise($doGetSingle("/networks", query));
+}

package/src/admin-funcs/zoneDevicesGet.ts

@@ -0,0 +1,13 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+// One zone device (a gateway), for the detail screen zoneDevicesList leads to.
+//
+// Internal for the same reason as zoneDevicesList: our own device inventory. See the
+// public/app-only split in AGENTS.md.
+//
+// Gateways only. The kiosks that zoneDevicesList folds into the same list live in a different
+// table and are not addressable here, so their ids do not belong in this call.
+export function zoneDevicesGet(zoneDeviceId: number): internalApiResult {
+  return new APIPromise($doGetSingle(`/zone-devices/${zoneDeviceId}`, {}));
+}

package/src/admin-funcs/zoneDevicesList.ts

@@ -0,0 +1,47 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+export type zoneDevicesListSortField = "id" | "name";
+
+export type zoneDevicesListRequest = {
+  facilityId?: number;
+  page?: number;
+  itemsPerPage?: number;
+  sort?: zoneDevicesListSortField;
+  desc?: boolean;
+};
+
+// The caller's devices — kiosks and zone gateways alike — grouped by facility.
+//
+// Internal rather than part of the public spec: this is the device inventory behind our own
+// admin surfaces, and it merges two unrelated tables into a shape only those screens read. See
+// the public/app-only split in AGENTS.md.
+//
+// The page is a page of FACILITIES, not of devices: paging the devices would cut a facility in
+// half, so `itemsPerPage` counts facilities and the nested device arrays come back whole. A
+// facility holds a handful of devices, so those arrays stay bounded.
+//
+// Facilities holding no device at all are left out, so an empty response means the caller
+// reaches no device rather than that the filter matched nothing.
+export function zoneDevicesList(
+  request: zoneDevicesListRequest = {},
+): internalApiResult {
+  const query: Record<string, string | number | boolean> = {};
+  if (request.facilityId !== undefined) {
+    query["facility_id"] = request.facilityId;
+  }
+  if (request.page !== undefined) {
+    query["page"] = request.page;
+  }
+  if (request.itemsPerPage !== undefined) {
+    query["items_per_page"] = request.itemsPerPage;
+  }
+  if (request.sort !== undefined) {
+    query["sort"] = request.sort;
+  }
+  if (request.desc !== undefined) {
+    query["desc"] = request.desc;
+  }
+
+  return new APIPromise($doGetSingle("/zone-devices", query));
+}

package/src/funcs/alertsListAlerts.ts

@@ -38,6 +38,8 @@ import {
  * @remarks
  * List alerts for user.
  *
+ * **Permissions.** Requires the `alerts.view` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function alertsListAlerts(

package/src/funcs/alertsUpdateUserAlerts.ts

@@ -32,6 +32,8 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Update user alerts
  *
+ * **Permissions.** Requires the `alerts.edit` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function alertsUpdateUserAlerts(

package/src/funcs/companiesAddCompanyManager.ts

@@ -35,6 +35,8 @@ import { Result } from "../types/fp.js";
  * Requires `company_managers` add permission. Company managers can add to their
  * own company; API users can add to companies in their marketplace app scope.
  *
+ * **Permissions.** Requires the `company_managers.add` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesAddCompanyManager(

package/src/funcs/companiesGetCompany.ts

@@ -33,10 +33,14 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Get company details.
  *
+ * **Permissions.** Requires the `companies.view` permission.
+ *
  * Available `expand` scopes are:
  *
- * company.location
- * company.vendor_type_restrictions
+ * - `company.location`
+ * - `company.vendor_type_restrictions`
+ *
+ * Any other value is rejected with `422 Unprocessable Entity`.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */

package/src/funcs/companiesListCompanyCredentials.ts

@@ -38,6 +38,14 @@ import {
  * @remarks
  * Lists credentials required for the specified company, based on CompanyRequiredCredentials.
  *
+ * **Permissions.** Requires the `vendor_credentials.view` permission. Callers who also hold `vendor_credentials.add` and can update the company trigger a recalculation of the required-credential set; everyone else reads the last computed set.
+ *
+ * Available `expand` scopes are:
+ *
+ * - `vendor_credential.systems`
+ *
+ * Any other value is rejected with `422 Unprocessable Entity`.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesListCompanyCredentials(

package/src/funcs/companiesListCompanyCredits.ts

@@ -38,6 +38,16 @@ import {
  * @remarks
  * Returns a paginated list of credits associated with the specified company, including incoming and outgoing transactions.
  *
+ * **Permissions.** Requires the `company_credits.view` permission.
+ *
+ * Available `expand` scopes are:
+ *
+ * - `entity`
+ * - `from_entity`
+ * - `to_entity`
+ *
+ * Any other value is rejected with `422 Unprocessable Entity`.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesListCompanyCredits(

package/src/funcs/companiesListCompanyManagerContacts.ts

@@ -31,6 +31,7 @@ import { Result } from "../types/fp.js";
  *
  * @remarks
  * Deprecated in favor of `/lookups/company_managers`, which returns the same list. Kept so app builds released before the move keep working.
+ * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission - the caller's role and their relationship to the record decide what is returned.
  *
  * @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
  */

package/src/funcs/companiesListCompanyManagers.ts

@@ -38,6 +38,8 @@ import {
  * @remarks
  * List or search company managers.
  *
+ * **Permissions.** Requires the `company_managers.view` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesListCompanyManagers(

package/src/funcs/companiesListOrSearchCompanies.ts

@@ -38,6 +38,15 @@ import {
  * @remarks
  * List or search companies.
  *
+ * **Permissions.** Requires the `companies.view` permission.
+ *
+ * Available `expand` scopes are:
+ *
+ * - `company.location`
+ * - `company.vendor_type_restrictions`
+ *
+ * Any other value is rejected with `422 Unprocessable Entity`.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesListOrSearchCompanies(

package/src/funcs/companiesLookupCompanies.ts

@@ -38,6 +38,8 @@ import {
  * @remarks
  * List companies available to the caller as minimal lookup summaries for dropdown and typeahead UIs.
  *
+ * **Permissions.** Requires the `companies.view` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function companiesLookupCompanies(

package/src/funcs/dataRequestsAddDataRequestFile.ts

@@ -33,6 +33,8 @@ import * as types$ from "../types/primitives.js";
  * @remarks
  * It will set the vendor credential data request file attributes
  *
+ * **Permissions.** Requires the `vendor-credential-data-requests.view` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function dataRequestsAddDataRequestFile(

package/src/funcs/dataRequestsDeleteDataRequestFile.ts

@@ -33,6 +33,8 @@ import * as types$ from "../types/primitives.js";
  * @remarks
  * It will delete the vendor credential data request file
  *
+ * **Permissions.** Requires the `vendor-credential-data-requests.delete` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function dataRequestsDeleteDataRequestFile(

package/src/funcs/dataRequestsUpdateDataRequest.ts

@@ -33,6 +33,8 @@ import * as types$ from "../types/primitives.js";
  * @remarks
  * It will update the vendor credential data request attributes
  *
+ * **Permissions.** Requires the `vendor-credential-data-requests.view` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function dataRequestsUpdateDataRequest(

package/src/funcs/eventsAcceptInvitation.ts

@@ -32,6 +32,8 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Accept event invitation
  *
+ * **Permissions.** Requires the `events.edit` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function eventsAcceptInvitation(

package/src/funcs/eventsCreateEvent.ts

@@ -32,6 +32,8 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Create a new event for calendar
  *
+ * **Permissions.** Requires the `events.add` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function eventsCreateEvent(
@@ -42,6 +44,7 @@ export function eventsCreateEvent(
   Result<
     operations.CreateEventCreateEventOk,
     | errors.ApiErrorResponse
+    | errors.ApiValidationErrorResponse
     | GreenSecurityError
     | ResponseValidationError
     | ConnectionError
@@ -68,6 +71,7 @@ async function $do(
     Result<
       operations.CreateEventCreateEventOk,
       | errors.ApiErrorResponse
+      | errors.ApiValidationErrorResponse
       | GreenSecurityError
       | ResponseValidationError
       | ConnectionError
@@ -150,6 +154,7 @@ async function $do(
   const [result] = await M.match<
     operations.CreateEventCreateEventOk,
     | errors.ApiErrorResponse
+    | errors.ApiValidationErrorResponse
     | GreenSecurityError
     | ResponseValidationError
     | ConnectionError
@@ -161,6 +166,7 @@ async function $do(
   >(
     M.json(200, operations.CreateEventCreateEventOk$inboundSchema),
     M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
+    M.jsonErr(422, errors.ApiValidationErrorResponse$inboundSchema),
     M.fail("4XX"),
     M.fail([500, "5XX"]),
   )(response, req, { extraFields: responseFields });

package/src/funcs/eventsDeclineInvitation.ts

@@ -32,6 +32,8 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Decline event invitation
  *
+ * **Permissions.** Requires the `events.edit` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function eventsDeclineInvitation(

package/src/funcs/eventsDeleteEvent.ts

@@ -33,6 +33,8 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Delete event for calendar
  *
+ * **Permissions.** Requires the `events.delete` permission.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function eventsDeleteEvent(

package/src/funcs/eventsGetEvent.ts

@@ -11,6 +11,7 @@ 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 * as components from "../models/components/index.js";
 import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
 import {
   ConnectionError,
@@ -32,11 +33,22 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Retrieve a single event by ID.
  *
+ * **Permissions.** Requires the `events.view` permission.
+ *
  * Available `expand` scopes are:
  *
  * - event.facility
  * - event.department
  * - event.invitees
+ * - event.location
+ * - event.attendees
+ * - event.creator
+ *
+ * Unrecognised values are ignored.
+ *
+ * This route always returns the current `Event` shape, whatever SDK version is calling: it was
+ * introduced after the calendar list endpoints and has never served the older string-valued
+ * shape they did.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
@@ -46,7 +58,7 @@ export function eventsGetEvent(
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    operations.GetEventGetEventOk,
+    components.Event,
     | errors.ApiErrorResponse
     | GreenSecurityError
     | ResponseValidationError
@@ -72,7 +84,7 @@ async function $do(
 ): Promise<
   [
     Result<
-      operations.GetEventGetEventOk,
+      components.Event,
       | errors.ApiErrorResponse
       | GreenSecurityError
       | ResponseValidationError
@@ -164,7 +176,7 @@ async function $do(
   };
 
   const [result] = await M.match<
-    operations.GetEventGetEventOk,
+    components.Event,
     | errors.ApiErrorResponse
     | GreenSecurityError
     | ResponseValidationError
@@ -175,7 +187,7 @@ async function $do(
     | UnexpectedClientError
     | SDKValidationError
   >(
-    M.json(200, operations.GetEventGetEventOk$inboundSchema),
+    M.json(200, components.Event$inboundSchema),
     M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
     M.fail("4XX"),
     M.fail([500, "5XX"]),

package/src/funcs/eventsListFeed.ts

@@ -36,7 +36,21 @@ import {
  * List events feed
  *
  * @remarks
- * List events feed
+ * List events feed.
+ *
+ * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission -
+ * the caller's role and their relationship to the record decide what is returned.
+ *
+ * Returns `Event` items with the `event.creator` and `event.invitees` scopes already applied,
+ * so `event_creator`, `event_creator_img_url` and `invitees` are populated — the fields this
+ * feed has always carried. SDK builds below `0.55.0-beta.1` receive the older `Feed` shape
+ * instead, in which `facility` and `department` are name strings rather than ids; the server
+ * chooses by the `X-SDK-User-Agent` header the SDK sends, so an existing client keeps the
+ * shape it was generated against until it is regenerated.
+ *
+ * The boundary is the prerelease build `0.55.0-beta.1`, not the `0.55.0` release, so
+ * `0.55.0-beta.1` itself already receives `Event`. See the `Event` schema for exactly how a
+ * build is compared against it.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */

package/src/funcs/eventsListLocations.ts

@@ -38,6 +38,8 @@ import {
  * @remarks
  * List meeting locations for invitees or an event
  *
+ * **Permissions.** Requires the `events.view` permission. Results are also scoped to the caller's own tenant: `event_id` is resolved through the caller's own event access (organizer, invitee, or the facility/system/company hosting it), and `invitee_user_ids`/`invitee_department_ids` only return labels for facilities the caller may otherwise see.
+ *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.
  */
 export function eventsListLocations(