@matech/thebigpos-sdk 3.2.0-stag-881 → 3.2.0

package/README.md

@@ -40,5 +40,44 @@ apiClient.api.getSiteConfiguration().then((response) => {
 });
 ```
 
+## Generate SDK from Swagger
+
+To regenerate the SDK from a specific API version, run:
+
+```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 --enum-style union
+```
+
+Replace `{version}` with the target API version (e.g. `v2.34.0`):
+
+```bash
+npx swagger-typescript-api generate -p https://api.thebigpos.dev/swagger/v2.34.0/swagger.json -o ./src -n index.ts -r true --axios --enum-names-as-values --enum-style union
+```
+
+Then apply the PATCH content-type fixup, passing the **same** spec that was given
+to the generator. The generator does not propagate `application/json-patch+json`,
+so this step sets each PATCH method's content type from the spec (no hard-coded
+endpoint list):
+
+```bash
+node scripts/apply-json-patch-content-type.js https://api.thebigpos.dev/swagger/v2.34.0/swagger.json
+yarn build
+```
+
+## Publishing
+
+1. Update the `version` field in `package.json` before publishing.
+2. Build the project:
+
+```bash
+yarn build
+```
+
+3. Publish to npm:
+
+```bash
+yarn publish
+```
+
 ____
 © 2024 Mortgage Automation Technologies. All rights reserved

package/dist/index.d.ts

@@ -4526,7 +4526,7 @@ export interface NotificationTemplateVersionUpdateRequest {
 }
 export interface Operation {
     op?: string;
-    value?: string | number | boolean | null | object;
+    value?: object | null;
     path?: string;
 }
 export interface OutboundFailureBucket {

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.2.0-stag-881",
+  "version": "3.2.0",
   "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,149 @@
-/* 
-  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.
+
+  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, '{}')
 }
 
-// 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 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
+}
+
+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}`
+	})
+}
+
+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)
+	}
+
+	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)
 	}
-)
 
-fs.writeFileSync(path, content)
-console.log('SDK patch complete: All PATCH methods now use ContentType.JsonPatch.')
+	let content = fs.readFileSync(SRC, 'utf8')
+	content = ensureJsonPatchEnum(content)
+	content = relaxOperationValue(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

@@ -5485,7 +5485,7 @@ export interface NotificationTemplateVersionUpdateRequest {
 
 export interface Operation {
   op?: string;
-  value?: string | number | boolean | null | object;
+  value?: object | null;
   path?: string;
 }