@matech/thebigpos-sdk 3.5.0-stag-2100 → 3.5.1-dev-2413

package/docs/sdk_generation.md

@@ -0,0 +1,149 @@
+# Publishing the POS Typescript SDK
+
+## Prerequisites
+
+1. Clone the repository (if you haven't already):
+
+```bash
+git clone https://github.com/MortgageAutomationTechnologies/thebigpos-sdk-typescript
+cd thebigpos-sdk-typescript
+```
+
+2. Install swagger-typescript-api globally:
+
+```bash
+npm i -g swagger-typescript-api
+```
+
+3. Connect to the MAT VPN
+
+## Step 1: Create a release branch
+
+Create a new branch for the version you're releasing:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b release/X.Y.Z
+```
+
+## Step 2: Generate the SDK
+
+Replace `{version}` with the target API version (e.g., `v2.31.0`):
+
+```bash
+npx swagger-typescript-api generate -p https://api.thebigpos.dev/swagger/{version}/swagger.json -o ./src -n index.ts -r true --axios --enum-names-as-values --generate-union-enums
+```
+
+> **Note:** If generating locally, use `http://localhost:5212/swagger/{version}/swagger.json` due to self-signed cert issues with https.
+
+## Step 3: Apply post-generation fixes
+
+Run the script to fix PATCH methods content type and Operation interface:
+
+```bash
+node scripts/apply-json-patch-content-type.js
+```
+
+This script:
+- Sets all PATCH methods to use `ContentType.JsonPatch`
+- Adds `JsonPatch` to the `ContentType` enum
+- Fixes the `Operation` interface to allow any value type
+
+## Step 4: Update the version
+
+Use npm's version command to update the version in `package.json`:
+
+```bash
+npm version X.Y.Z
+```
+
+**Version conventions:**
+
+- Match the SDK version to the API version being released
+- For release candidates (pre-release), use: `npm version X.Y.Z-rc.N --preid=rc`
+- For patch increments: `npm version patch`
+- For minor increments: `npm version minor`
+
+## Step 5: Build the SDK
+
+```bash
+npm run build
+```
+
+Ensure there are no TypeScript compilation errors.
+
+## Step 6: Merge develop (if needed)
+
+If there are changes in develop that need to be included:
+
+```bash
+git fetch origin develop
+git merge origin/develop
+```
+
+If there are conflicts in `src/index.ts` or `dist/*`, regenerate the SDK (Step 2), apply fixes (Step 3), and rebuild (Step 5) to resolve them.
+
+## Step 7: Commit and push
+
+```bash
+git add .
+git commit -m "X.Y.Z"
+git push -u origin release/X.Y.Z
+```
+
+## Step 8: Publish to NPM
+
+### Authentication
+
+NPM requires a granular access token with publish permissions and 2FA bypass enabled.
+
+1. Go to [npmjs.com](https://www.npmjs.com) > Access Tokens > Generate New Token
+2. Select "Granular Access Token"
+3. Enable "Bypass 2FA for automation"
+4. Set permissions to publish to `@matech/thebigpos-sdk`
+
+Configure the token:
+
+```bash
+npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN
+```
+
+### Publish
+
+**To latest (stable release):**
+
+```bash
+npm publish --access public
+```
+
+**To next (pre-release):**
+
+```bash
+npm publish --tag next
+```
+
+**To a feature tag (for testing):**
+
+```bash
+npm publish --tag feature-name
+```
+
+### Installing the SDK
+
+```bash
+# Latest stable
+yarn add @matech/thebigpos-sdk
+
+# Next pre-release
+yarn add @matech/thebigpos-sdk@next
+
+# Specific version
+yarn add @matech/thebigpos-sdk@X.Y.Z
+```
+
+## Step 9: Clean up
+
+1. **Revoke the NPM token** after publishing for security
+2. **Create a Pull Request** from `release/X.Y.Z` to `develop` and `main`
+3. **Create a GitHub Release** with release notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matech/thebigpos-sdk",
-  "version": "3.5.0-stag-2100",
+  "version": "3.5.1-dev-2413",
   "description": "The Big POS Typescript SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,14 +26,24 @@
     "url": "https://github.com/MortgageAutomationTechnologies/thebigpos-sdk-typescript/issues"
   },
   "homepage": "https://github.com/MortgageAutomationTechnologies/thebigpos-sdk-typescript#readme",
-  "dependencies": {
-    "axios": "^1.7.7"
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "axios": "^1"
   },
   "devDependencies": {
-    "esbuild": "^0.27.0",
+    "axios": "^1.16.1",
+    "esbuild": "^0.28.1",
     "husky": "^9.1.5",
-    "rimraf": "6.1.1",
+    "rimraf": "6.1.3",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
+  },
+  "resolutions": {
+    "diff": "^4.0.4",
+    "brace-expansion": "^5.0.8",
+    "follow-redirects": "^1.16.0",
+    "form-data": "^4.0.6"
   }
 }

package/scripts/apply-json-patch-content-type.js

@@ -1,56 +1,209 @@
-/* 
-  This script is meant to run after the SDK has been generated.
+/*
+  Post-generation fixup for the generated TypeScript SDK.
 
-  - It updates the generated code to ensure that all PATCH methods use ContentType.JsonPatch.
-  - It also ensures that the ContentType enum includes JsonPatch and modifies the Operation interface
-    to allow any value for the `value` property instead of just object or null.
+  swagger-typescript-api does not propagate the `application/json-patch+json`
+  request content type into the generated code, so PATCH methods that use JSON
+  Patch would otherwise go out with the wrong Content-Type. This script restores
+  it by reading the OpenAPI spec the SDK was generated from and, for every
+  generated PATCH method, setting:
 
-  This is necessary because the SDK generation does not currently handle these cases correctly.
+    - ContentType.JsonPatch  -> when the spec's requestBody for that path
+                                advertises application/json-patch+json
+    - ContentType.Json       -> for every other PATCH method
+                                (e.g. updateLoan, which the backend declares as
+                                [Consumes("application/json")])
+
+  The decision is taken entirely from the spec — there is no hard-coded list of
+  endpoints to keep in sync. It also ensures the ContentType enum includes
+  JsonPatch and relaxes the Operation interface `value` to accept any value.
+
+  It additionally teaches `createFormData` to recognise React Native files. The
+  generator assumes a browser and detects file parts with `instanceof Blob ||
+  instanceof File`; in React Native a file is a plain `{ uri, name, type }`
+  object, so without the extra branch every mobile upload is serialised as the
+  string "[object Object]". This used to live as a patch-package patch in
+  pos-mobile-v2, which had to be re-created on every SDK bump.
+
+  Usage (pass the SAME spec given to `swagger-typescript-api -p`):
+    node scripts/apply-json-patch-content-type.js https://api.thebigpos.dev/swagger/<version>/swagger.json
+    node scripts/apply-json-patch-content-type.js ./swagger.json
+    SWAGGER_SPEC=<url-or-file> node scripts/apply-json-patch-content-type.js
+
+  Design notes:
+    - The rewrite is scoped to a single generated method block at a time
+      (anchored on that method's own `...params,`), so it can never bleed across
+      method boundaries.
+    - It sets each method's content type to its target value rather than doing a
+      conditional replace, so it is idempotent and self-healing (it also repairs
+      a previously-seen ContentType.JsonPatchPatch double-application).
+    - If no spec is provided (e.g. a plain commit-hook run), the content-type
+      rewrite is skipped instead of guessing, so it can never silently corrupt
+      the generated output.
 */
 
 const fs = require('fs')
+const nodePath = require('path')
 
-const path = require('path').resolve(__dirname, '../src/index.ts')
+const SRC = nodePath.resolve(__dirname, '../src/index.ts')
 
-if (!fs.existsSync(path)) {
-	console.error(`Error: File not found at path "${path}". Please ensure the SDK has been generated.`)
-	process.exit(1)
+async function loadSpec(source) {
+	if (!source) return null
+	if (/^https?:\/\//i.test(source)) {
+		const res = await fetch(source)
+		if (!res.ok) throw new Error(`Failed to fetch spec from "${source}": HTTP ${res.status}`)
+		return res.json()
+	}
+	return JSON.parse(fs.readFileSync(nodePath.resolve(source), 'utf8'))
 }
-let content
-try {
-	content = fs.readFileSync(path, 'utf8')
-} catch (err) {
-	console.error(`Error: Unable to read file at path "${path}". Details: ${err.message}`)
-	process.exit(1)
+
+// Collapse spec ("{id}") and generated ("${id}") path params to a common token
+// so generated paths can be matched against spec paths regardless of param names.
+function normalizePath(p) {
+	return p.replace(/\$\{[^}]+\}/g, '{}').replace(/\{[^}]+\}/g, '{}')
+}
+
+function jsonPatchPaths(spec) {
+	const set = new Set()
+	for (const [route, ops] of Object.entries(spec.paths || {})) {
+		const content = ops && ops.patch && ops.patch.requestBody && ops.patch.requestBody.content
+		if (content && Object.prototype.hasOwnProperty.call(content, 'application/json-patch+json')) {
+			set.add(normalizePath(route))
+		}
+	}
+	return set
 }
 
-// Update PATCH methods to use ContentType.JsonPatch
-content = content.replace(
-	/(method:\s*"PATCH"[\s\S]+?)type:\s*ContentType\.Json/g,
-	(match) => match.replace('ContentType.Json', 'ContentType.JsonPatch')
-)
+function setContentType(block, member) {
+	const target = `type: ContentType.${member}`
+	if (/type:\s*ContentType\.\w+/.test(block)) return block.replace(/type:\s*ContentType\.\w+/, target)
+	if (/type:\s*"[^"]*"/.test(block)) return block.replace(/type:\s*"[^"]*"/, target)
+	if (/\n(\s*)format:/.test(block)) return block.replace(/\n(\s*)format:/, `\n$1${target},\n$1format:`)
+	return block.replace(/\n(\s*)\.\.\.params,/, `\n$1${target},\n$1...params,`)
+}
 
-// Ensure JsonPatch is included in the ContentType enum
-content = content.replace(
-	/export enum ContentType\s*{([\s\S]*?)}/,
-	(match, enumBody) => {
+function ensureJsonPatchEnum(content) {
+	return content.replace(/export enum ContentType\s*{([\s\S]*?)}/, (match, enumBody) => {
 		if (enumBody.includes('JsonPatch')) return match
-		const insertion = `  JsonPatch = "application/json-patch+json",\n  `
-		return `export enum ContentType {\n${insertion}${enumBody.trim()}\n}`
-	}
-)
+		return `export enum ContentType {\n  JsonPatch = "application/json-patch+json",\n  ${enumBody.trim()}\n}`
+	})
+}
 
-// Fix the Operation interface to allow any value
-content = content.replace(
-	/export interface Operation\s*{([\s\S]*?)}/,
-	(match, body) => {
+function relaxOperationValue(content) {
+	return content.replace(/export interface Operation\s*{([\s\S]*?)}/, (match, body) => {
 		const updated = body.replace(
 			/value\?:\s*object\s*\|?\s*null?;/,
 			'value?: string | number | boolean | null | object;'
 		)
 		return `export interface Operation {\n  ${updated.trim()}\n}`
+	})
+}
+
+const RN_FILE_MARKER = 'isReactNativeFile'
+
+// swagger-typescript-api assumes a browser: it detects multipart file parts with
+// `instanceof Blob || instanceof File`. React Native has neither in a usable form —
+// a file there is a plain `{ uri, name, type }` object. Without this branch those
+// objects fall through to `stringifyFormItem` and every upload from the mobile app
+// goes out as the string "[object Object]".
+//
+// The React Native check runs first so the `instanceof` operands are never even
+// evaluated on that path.
+//
+// The pattern is deliberately whitespace-tolerant instead of matching one exact
+// line. As generated today that statement is exactly 80 characters wide, which is
+// Prettier's default printWidth — so the moment the generator nests it one level
+// deeper, or renames `formItem`, Prettier reflows it across two lines. Anchoring
+// on the single-line form would then quietly stop matching.
+const GENERATED_FILE_CHECK =
+	/^([ \t]*)const isFileType\s*=\s*formItem instanceof Blob\s*\|\|\s*formItem instanceof File;/m
+
+function applyReactNativeFileSupport(content) {
+	if (content.includes(RN_FILE_MARKER)) return content
+
+	// Never fail open. A silent no-op here ships an SDK where every React Native
+	// upload is serialised as "[object Object]", with nothing in the build to
+	// suggest anything went wrong.
+	if (!GENERATED_FILE_CHECK.test(content)) {
+		throw new Error(
+			'applyReactNativeFileSupport: could not find the generated `isFileType` check in ' +
+				'createFormData.\n' +
+				'swagger-typescript-api has most likely changed its output. Update ' +
+				'GENERATED_FILE_CHECK in this script — do not skip this step, or React Native ' +
+				'file uploads will break with no visible error.'
+		)
+	}
+
+	return content.replace(
+		GENERATED_FILE_CHECK,
+		(match, indent) =>
+			[
+				`${indent}// React Native files are plain { uri, name, type } objects, not Blob/File.`,
+				`${indent}const ${RN_FILE_MARKER} =`,
+				`${indent}  !!formItem &&`,
+				`${indent}  typeof formItem === "object" &&`,
+				`${indent}  "uri" in formItem &&`,
+				`${indent}  "name" in formItem &&`,
+				`${indent}  "type" in formItem;`,
+				`${indent}const isFileType =`,
+				`${indent}  ${RN_FILE_MARKER} || formItem instanceof Blob || formItem instanceof File;`,
+			].join('\n')
+	)
+}
+
+function applyContentTypes(content, patchPaths) {
+	// Heal any earlier double-application (ContentType.JsonPatchPatch...).
+	content = content.replace(/ContentType\.JsonPatch(?:Patch)+\b/g, 'ContentType.JsonPatch')
+
+	const METHOD_BLOCK = /[a-zA-Z0-9_]+:\s*\([\s\S]*?\)\s*=>\s*this\.request<[^>]*>\(\{[\s\S]*?\.\.\.params,/g
+	return content.replace(METHOD_BLOCK, (block) => {
+		if (!/method:\s*"PATCH"/.test(block)) {
+			// Non-PATCH methods must never be JSON Patch.
+			return /type:\s*ContentType\.JsonPatch\b/.test(block)
+				? block.replace(/type:\s*ContentType\.JsonPatch\b/, 'type: ContentType.Json')
+				: block
+		}
+		const routeMatch = block.match(/path:\s*`([^`]*)`/)
+		const route = routeMatch ? normalizePath(routeMatch[1]) : ''
+		return setContentType(block, patchPaths.has(route) ? 'JsonPatch' : 'Json')
+	})
+}
+
+;(async () => {
+	if (!fs.existsSync(SRC)) {
+		console.error(`Error: File not found at "${SRC}". Generate the SDK first.`)
+		process.exit(1)
 	}
-)
 
-fs.writeFileSync(path, content)
-console.log('SDK patch complete: All PATCH methods now use ContentType.JsonPatch.')
+	const source = process.argv[2] || process.env.SWAGGER_SPEC || process.env.SWAGGER_URL
+	let spec
+	try {
+		spec = await loadSpec(source)
+	} catch (err) {
+		console.error(`Error loading OpenAPI spec: ${err.message}`)
+		process.exit(1)
+	}
+
+	let content = fs.readFileSync(SRC, 'utf8')
+	content = ensureJsonPatchEnum(content)
+	content = relaxOperationValue(content)
+	content = applyReactNativeFileSupport(content)
+
+	if (!spec) {
+		console.warn(
+			'No OpenAPI spec provided (argument / SWAGGER_SPEC / SWAGGER_URL) — skipping PATCH content-type rewrite.\n' +
+				'Re-run with the spec used for generation to apply it, e.g.:\n' +
+				'  node scripts/apply-json-patch-content-type.js https://api.thebigpos.dev/swagger/<version>/swagger.json'
+		)
+		fs.writeFileSync(SRC, content)
+		return
+	}
+
+	const patchPaths = jsonPatchPaths(spec)
+	content = applyContentTypes(content, patchPaths)
+
+	fs.writeFileSync(SRC, content)
+	console.log(`SDK patch complete: PATCH content types set from the OpenAPI spec (${patchPaths.size} json-patch endpoint(s)).`)
+})().catch((err) => {
+	console.error(err)
+	process.exit(1)
+})

package/src/index.ts

@@ -402,6 +402,8 @@ export type LoanDocumentType =
   | "AiGeneratedDocument"
   | "Unidentified";
 
+export type LoanDocumentFolderScope = "Any" | "Assigned" | "Unassigned";
+
 export type LoanDocumentFolderPermissionLevel =
   | "None"
   | "Read"
@@ -3139,6 +3141,13 @@ export interface GuidPatchOperation {
   from?: string | null;
 }
 
+export interface HttpError {
+  logId?: string | null;
+  message?: string | null;
+  errorCode?: string | null;
+  errors?: string[] | null;
+}
+
 export interface IPAddress {
   addressFamily: IpAddressAddressFamilyEnum;
   /** @format int64 */
@@ -3762,6 +3771,8 @@ export interface LoanBorrowerEmploymentCurrentGrossIncome {
   /** @format double */
   hourlyRate?: number | null;
   /** @format double */
+  annualBasePay?: number | null;
+  /** @format double */
   other?: number | null;
   /** @format double */
   bonus?: number | null;
@@ -4361,6 +4372,8 @@ export interface LoanDocument {
   losStatus: string;
   contents?: string | null;
   failoverDocumentPath?: string | null;
+  /** @format int64 */
+  fileSizeBytes?: number | null;
   /** @format date-time */
   sensitiveDataPurgedOn?: string | null;
   observedDocumentType?: LoanDocumentType | null;
@@ -4437,6 +4450,7 @@ export interface LoanDocumentFolderWithCount {
   isActive: boolean;
   /** @format int32 */
   documentCount: number;
+  isUnassigned: boolean;
 }
 
 export interface LoanDocumentPreviewsRequest {
@@ -4477,6 +4491,7 @@ export interface LoanDocumentSearchCriteria {
   bucket?: string | null;
   /** @format uuid */
   folderID?: string | null;
+  folderScope?: LoanDocumentFolderScope | null;
   /** @format uuid */
   userID?: string | null;
   documentIDs?: string[] | null;
@@ -8580,7 +8595,15 @@ export class HttpClient<SecurityDataType = unknown> {
         property instanceof Array ? property : [property];
 
       for (const formItem of propertyContent) {
-        const isFileType = formItem instanceof Blob || formItem instanceof File;
+        // React Native files are plain { uri, name, type } objects, not Blob/File.
+        const isReactNativeFile =
+          !!formItem &&
+          typeof formItem === "object" &&
+          "uri" in formItem &&
+          "name" in formItem &&
+          "type" in formItem;
+        const isFileType =
+          isReactNativeFile || formItem instanceof Blob || formItem instanceof File;
         formData.append(
           key,
           isFileType ? formItem : this.stringifyFormItem(formItem),
@@ -8642,7 +8665,7 @@ export class HttpClient<SecurityDataType = unknown> {
 
 /**
  * @title The Big POS API
- * @version v3.5.0
+ * @version v3.5.1
  * @termsOfService https://www.thebigpos.com/terms-of-use/
  * @contact Mortgage Automation Technologies <support@thebigpos.com> (https://www.thebigpos.com/terms-of-use/)
  */
@@ -14388,10 +14411,11 @@ export class Api<
      * @request POST:/api/listings
      * @secure
      * @response `201` `Listing` Created
-     * @response `403` `ProblemDetails` Forbidden
+     * @response `401` `HttpError` Unauthorized
+     * @response `403` `HttpError` Forbidden
      */
     createListing: (data: ListingRequest, params: RequestParams = {}) =>
-      this.request<Listing, ProblemDetails>({
+      this.request<Listing, HttpError>({
         path: `/api/listings`,
         method: "POST",
         body: data,
@@ -14448,14 +14472,15 @@ export class Api<
      * @request PUT:/api/listings/{id}
      * @secure
      * @response `200` `Listing` OK
-     * @response `403` `ProblemDetails` Forbidden
+     * @response `401` `HttpError` Unauthorized
+     * @response `403` `HttpError` Forbidden
      */
     replaceListing: (
       id: string,
       data: ListingRequest,
       params: RequestParams = {},
     ) =>
-      this.request<Listing, ProblemDetails>({
+      this.request<Listing, HttpError>({
         path: `/api/listings/${id}`,
         method: "PUT",
         body: data,
@@ -15046,7 +15071,7 @@ export class Api<
       }),
 
     /**
-     * @description Returns each folder that holds at least one document the caller can read, with the document count per folder. Documents that are not assigned to a folder are returned as a synthetic 'Unassigned' folder (ID = empty GUID).
+     * @description Returns each folder that holds at least one document the caller can read, with the document count per folder. Documents that are not assigned to a folder are returned as a synthetic 'Unassigned' folder (ID = empty GUID, isUnassigned = true); filter to its documents with searchLoanDocuments folderScope 'Unassigned' rather than by echoing that ID.
      *
      * @tags LoanDocumentFoldersForSingleLoan
      * @name ListLoanDocumentFolders
@@ -15151,7 +15176,7 @@ export class Api<
       }),
 
     /**
-     * No description
+     * @description Filters the loan's readable documents. Pass folderID to filter to one folder, or folderScope 'Unassigned' for the documents that have no folder (the synthetic folder listLoanDocumentFolders reports with isUnassigned true); the two cannot be combined.
      *
      * @tags LoanDocuments
      * @name SearchLoanDocuments
@@ -15159,6 +15184,7 @@ export class Api<
      * @request POST:/api/loans/{loanId}/documents/search
      * @secure
      * @response `200` `LoanDocumentSearchPaginated` OK
+     * @response `422` `UnprocessableEntity` Unprocessable Content
      */
     searchLoanDocuments: (
       loanId: string,
@@ -15173,7 +15199,7 @@ export class Api<
       },
       params: RequestParams = {},
     ) =>
-      this.request<LoanDocumentSearchPaginated, any>({
+      this.request<LoanDocumentSearchPaginated, UnprocessableEntity>({
         path: `/api/loans/${loanId}/documents/search`,
         method: "POST",
         query: query,
@@ -16462,6 +16488,7 @@ export class Api<
      * @secure
      * @response `201` `TaskComment` Created
      * @response `404` `ProblemDetails` Not Found
+     * @response `422` `UnprocessableEntity` Unprocessable Content
      */
     createLoanTaskComment: (
       loanId: string,
@@ -16469,7 +16496,7 @@ export class Api<
       data: TaskCommentRequest,
       params: RequestParams = {},
     ) =>
-      this.request<TaskComment, ProblemDetails>({
+      this.request<TaskComment, ProblemDetails | UnprocessableEntity>({
         path: `/api/loans/${loanId}/tasks/${userLoanTaskId}/comments`,
         method: "POST",
         body: data,
@@ -16489,6 +16516,7 @@ export class Api<
      * @secure
      * @response `200` `TaskComment` OK
      * @response `404` `ProblemDetails` Not Found
+     * @response `422` `UnprocessableEntity` Unprocessable Content
      */
     replaceLoanTaskComment: (
       loanId: string,
@@ -16497,7 +16525,7 @@ export class Api<
       data: TaskCommentRequest,
       params: RequestParams = {},
     ) =>
-      this.request<TaskComment, ProblemDetails>({
+      this.request<TaskComment, ProblemDetails | UnprocessableEntity>({
         path: `/api/loans/${loanId}/tasks/${userLoanTaskId}/comments/${commentId}`,
         method: "PUT",
         body: data,