@financeable/aggregation 0.13.3 → 0.14.0

package/.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/images/tree/main/src/typescript-node
+{
+    "name": "TypeScript",
+    "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bullseye",
+    // Features to add to the dev container. More info: https://containers.dev/features.
+    // "features": {},
+    // Use 'forwardPorts' to make a list of ports inside the container available locally.
+    // "forwardPorts": [],
+    // Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": "sudo chmod +x ./.devcontainer/setup.sh && ./.devcontainer/setup.sh",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-vscode.vscode-typescript-tslint-plugin",
+                "esbenp.prettier-vscode",
+                "github.vscode-pull-request-github"
+            ],
+            "settings": {
+                "files.eol": "\n",
+                "editor.formatOnSave": true,
+                "typescript.tsc.autoDetect": "on",
+                "typescript.updateImportsOnFileMove.enabled": "always",
+                "typescript.preferences.importModuleSpecifier": "relative",
+                "[typescript]": {
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": true
+                    }
+                },
+                "[typescriptreact]": {
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": true
+                    }
+                }
+            }
+        },
+        "codespaces": {
+            "openFiles": [
+                ".devcontainer/README.md"
+            ]
+        }
+    }
+    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+    // "remoteUser": "root"
+}

package/FUNCTIONS.md

@@ -0,0 +1,240 @@
+# Standalone Functions
+
+> [!NOTE]
+> This section is useful if you are using a bundler and targetting browsers and
+> runtimes where the size of an application affects performance and load times. 
+
+Every method in this SDK is also available as a standalone function. This
+alternative API is suitable when targetting the browser or serverless runtimes
+and using a bundler to build your application since all unused functionality
+will be tree-shaken away. This includes code for unused methods, Zod schemas,
+encoding helpers and response handlers. The result is dramatically smaller
+impact on the application's final bundle size which grows very slowly as you use
+more and more functionality from this SDK.
+
+Calling methods through the main SDK class remains a valid and generally more
+more ergonomic option. Standalone functions represent an optimisation for a
+specific category of applications.
+
+## Example
+
+```typescript
+import { FinanceableCore } from "@financeable/aggregation/core.js";
+import { applicationsCreate } from "@financeable/aggregation/funcs/applicationsCreate.js";
+
+// Use `FinanceableCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const financeable = new FinanceableCore({
+  clientCredentials: process.env["FINANCEABLE_CLIENT_CREDENTIALS"] ?? "",
+});
+
+async function run() {
+  const res = await applicationsCreate(financeable, {
+    data: {
+      type: "entities",
+      attributes: {
+        applicationType: "consumerSecured",
+        associatedBrokerEmail: "<value>",
+      },
+      relationships: {
+        customers: {
+          data: [
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+        asset: {
+          data: {
+            type: "assets",
+            attributes: {
+              id: "12345678901",
+              ageOfAsset: 3,
+              ageOfAssetAtEnd: 8,
+              condition: "USED",
+              assetType: "CARAVAN",
+              assetValue: "35000.00",
+              make: "Toyota",
+              assetModel: "Camry",
+              registrationNumber: "ABC123",
+              registrationState: "VIC",
+              vin: "1HGCM82633A123456",
+              supplierName: "Mr and Mrs Smith",
+              supplierABN: "12345678901",
+              supplierAddress: "123 Car Street, Melbourne VIC 3000",
+              supplierPhone: "0412345678",
+              supplierContactName: "John Smith",
+              supplierEmail: "john.smith@mrandmrssmith.com.au",
+              privateSale: false,
+              typeOfSale: "AUTHORISED_SELLER",
+              description: "2020 Toyota Camry Hybrid SL, Silver, 45,000km",
+              netAssetValue: "32000.00",
+              isLuxury: false,
+              additionalFees: "995.00",
+              additionalTaxes: "0.00",
+            },
+          },
+        },
+      },
+    },
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("applicationsCreate failed:", res.error);
+  }
+}
+
+run();
+```
+
+## Result types
+
+Standalone functions differ from SDK methods in that they return a
+`Result<Value, Error>` type to capture _known errors_ and document them using
+the type system. By avoiding throwing errors, application code maintains clear
+control flow and error-handling become part of the regular flow of application
+code.
+
+> We use the term "known errors" because standalone functions, and JavaScript
+> code in general, can still throw unexpected errors such as `TypeError`s,
+> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
+> something this SDK addresses in the future. Nevertheless, there is still a lot
+> of benefit from capturing most errors and turning them into values.
+
+The second reason for this style of programming is because these functions will
+typically be used in front-end applications where exception throwing is
+sometimes discouraged or considered unidiomatic. React and similar ecosystems
+and libraries tend to promote this style of programming so that components
+render useful content under all states (loading, success, error and so on).
+
+The general pattern when calling standalone functions looks like this:
+
+```typescript
+import { Core } from "<sdk-package-name>";
+import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
+
+const client = new Core();
+
+async function run() {
+  const result = await fetchSomething(client, { id: "123" });
+  if (!result.ok) {
+    // You can throw the error or handle it. It's your choice now.
+    throw result.error;
+  }
+
+  console.log(result.value);
+}
+
+run();
+```
+
+Notably, `result.error` above will have an explicit type compared to a try-catch
+variation where the error in the catch block can only be of type `unknown` (or
+`any` depending on your TypeScript settings).

package/RUNTIMES.md

@@ -0,0 +1,48 @@
+# Supported JavaScript runtimes
+
+This SDK is intended to be used in JavaScript runtimes that support ECMAScript 2020 or newer. The SDK uses the following features:
+
+- [Web Fetch API][web-fetch]
+- [Web Streams API][web-streams] and in particular `ReadableStream`
+- [Async iterables][async-iter] using `Symbol.asyncIterator`
+
+[web-fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+[web-streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+[async-iter]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+
+Runtime environments that are explicitly supported are:
+
+- Evergreen browsers which include: Chrome, Safari, Edge, Firefox
+- Node.js active and maintenance LTS releases
+  - Currently, this is v18 and v20
+- Bun v1 and above
+- Deno v1.39
+  - Note that Deno does not currently have native support for streaming file uploads backed by the filesystem ([issue link][deno-file-streaming])
+
+[deno-file-streaming]: https://github.com/denoland/deno/issues/11018
+
+## Recommended TypeScript compiler options
+
+The following `tsconfig.json` options are recommended for projects using this
+SDK in order to get static type support for features like async iterables,
+streams and `fetch`-related APIs ([`for await...of`][for-await-of],
+[`AbortSignal`][abort-signal], [`Request`][request], [`Response`][response] and
+so on):
+
+[for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+[abort-signal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+[request]: https://developer.mozilla.org/en-US/docs/Web/API/Request
+[response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2020", // or higher
+    "lib": ["es2020", "dom", "dom.iterable"]
+  }
+}
+```
+
+While `target` can be set to older ECMAScript versions, it may result in extra,
+unnecessary compatibility code being generated if you are not targeting old
+runtimes.

package/core.js

@@ -0,0 +1,17 @@
+"use strict";
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FinanceableCore = void 0;
+const sdks_js_1 = require("./lib/sdks.js");
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+class FinanceableCore extends sdks_js_1.ClientSDK {
+}
+exports.FinanceableCore = FinanceableCore;
+//# sourceMappingURL=core.js.map

package/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["src/core.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,2CAA0C;AAE1C;;;;;GAKG;AACH,MAAa,eAAgB,SAAQ,mBAAS;CAAG;AAAjD,0CAAiD"}

package/examples/applicationsCreate.example.ts

@@ -0,0 +1,179 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import dotenv from "dotenv";
+dotenv.config();
+/**
+ * Example usage of the @financeable/aggregation SDK
+ *
+ * To run this example from the examples directory:
+ * npm run build && npx tsx applicationsCreate.example.ts
+ */
+
+import { Financeable } from "@financeable/aggregation";
+
+const financeable = new Financeable({
+  clientCredentials: process.env["FINANCEABLE_CLIENT_CREDENTIALS"] ?? "",
+});
+
+async function main() {
+  const result = await financeable.applications.create({
+    data: {
+      type: "entities",
+      attributes: {
+        applicationType: "consumerSecured",
+        associatedBrokerEmail: "<value>",
+      },
+      relationships: {
+        customers: {
+          data: [
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+            {
+              type: "customers",
+              attributes: {
+                title: "Mr",
+                firstName: "Courtney",
+                lastName: "Greenfelder",
+                dateOfBirth: "1981-06-22",
+                idExpiryDate: "<value>",
+              },
+              relationships: {
+                addresses: {
+                  data: [
+                    {
+                      type: "addresses",
+                      attributes: {
+                        id: "12345678901",
+                        addressType: "residential",
+                        fullAddress: "42 Wallaby Way, Sydney NSW 2000",
+                        city: "Sydney",
+                        postCode: "2000",
+                        streetAddress: "42 Wallaby Way",
+                        addressLine2: "",
+                        streetNumber: "42",
+                        streetType: "Way",
+                        street: "Wallaby",
+                        state: "NSW",
+                        country: "Australia",
+                        status: "current",
+                        monthsAt: 24,
+                        yearsAt: 2,
+                      },
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+        asset: {
+          data: {
+            type: "assets",
+            attributes: {
+              id: "12345678901",
+              ageOfAsset: 3,
+              ageOfAssetAtEnd: 8,
+              condition: "USED",
+              assetType: "CARAVAN",
+              assetValue: "35000.00",
+              make: "Toyota",
+              assetModel: "Camry",
+              registrationNumber: "ABC123",
+              registrationState: "VIC",
+              vin: "1HGCM82633A123456",
+              supplierName: "Mr and Mrs Smith",
+              supplierABN: "12345678901",
+              supplierAddress: "123 Car Street, Melbourne VIC 3000",
+              supplierPhone: "0412345678",
+              supplierContactName: "John Smith",
+              supplierEmail: "john.smith@mrandmrssmith.com.au",
+              privateSale: false,
+              typeOfSale: "AUTHORISED_SELLER",
+              description: "2020 Toyota Camry Hybrid SL, Silver, 45,000km",
+              netAssetValue: "32000.00",
+              isLuxury: false,
+              additionalFees: "995.00",
+              additionalTaxes: "0.00",
+            },
+          },
+        },
+      },
+    },
+  });
+
+  console.log(result);
+}
+
+main().catch(console.error);