@matech/thebigpos-sdk 3.13.0 → 3.14.0-dev-5757

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.13.0",
+  "version": "3.14.0-dev-5757",
   "description": "The Big POS Typescript SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,15 +26,25 @@
     "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"
   },
-  "swaggerSha256": "7a7f47904bbeecbbf9f6239ccbdd0e7917880c676001af3af544ac8a28bf53d5"
+  "resolutions": {
+    "diff": "^4.0.4",
+    "brace-expansion": "^5.0.8",
+    "follow-redirects": "^1.16.0",
+    "form-data": "^4.0.6"
+  },
+  "swaggerSha256": "d9b9ac4dc50745500a24d9a2d32a2f8250a03f8ed1bbbbbe0179da9614e8f335"
 }

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)
+})