@codat/lending 6.0.0 → 7.1.0

package/FUNCTIONS.md

@@ -0,0 +1,110 @@
+# 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 { CodatLendingCore } from "@codat/lending/core.js";
+import { companiesList } from "@codat/lending/funcs/companiesList.js";
+import { SDKValidationError } from "@codat/lending/sdk/models/errors/sdkvalidationerror.js";
+
+// Use `CodatLendingCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const codatLending = new CodatLendingCore({
+  authHeader: "Basic BASE_64_ENCODED(API_KEY)",
+});
+
+async function run() {
+  const res = await companiesList(codatLending, {
+    page: 1,
+    pageSize: 100,
+    query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
+    orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
+  });
+
+  switch (true) {
+    case res.ok:
+      // The success case will be handled outside of the switch block
+      break;
+    case res.error instanceof SDKValidationError:
+      // Pretty-print validation errors.
+      return console.log(res.error.pretty());
+    case res.error instanceof Error:
+      return console.log(res.error);
+    default:
+      // TypeScript's type checking will fail on the following line if the above
+      // cases were not exhaustive.
+      res.error satisfies never;
+      throw new Error("Assertion failed: expected error checks to be exhaustive: " + res.error);
+  }
+
+
+  const { value: result } = res;
+
+  // Handle the result
+  console.log(result);
+}
+
+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/README.md

@@ -38,19 +38,24 @@ The Lending API is built on top of the latest accounting, commerce, and banking
 
 <!-- Start Table of Contents [toc] -->
 ## Table of Contents
+<!-- $toc-max-depth=2 -->
+* [Lending](#lending)
+  * [Endpoints](#endpoints)
+  * [SDK Installation](#sdk-installation)
+  * [Example Usage](#example-usage)
+  * [Requirements](#requirements)
+  * [SDK Example Usage](#sdk-example-usage)
+  * [Available Resources and Operations](#available-resources-and-operations)
+  * [Standalone functions](#standalone-functions)
+  * [File uploads](#file-uploads)
+  * [Retries](#retries)
+  * [Error Handling](#error-handling)
+  * [Server Selection](#server-selection)
+  * [Custom HTTP Client](#custom-http-client)
+  * [Authentication](#authentication)
+  * [Debugging](#debugging)
+  * [Support](#support)
 
-* [SDK Installation](#sdk-installation)
-* [Requirements](#requirements)
-* [SDK Example Usage](#sdk-example-usage)
-* [Available Resources and Operations](#available-resources-and-operations)
-* [Standalone functions](#standalone-functions)
-* [File uploads](#file-uploads)
-* [Retries](#retries)
-* [Error Handling](#error-handling)
-* [Server Selection](#server-selection)
-* [Custom HTTP Client](#custom-http-client)
-* [Authentication](#authentication)
-* [Debugging](#debugging)
 <!-- End Table of Contents [toc] -->
 
 <!-- Start SDK Installation [installation] -->
@@ -101,20 +106,23 @@ For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).
 ```typescript
 import { CodatLending } from "@codat/lending";
 
-const codatLending = new CodatLending({
-  authHeader: "Basic BASE_64_ENCODED(API_KEY)",
-});
+const codatLending = new CodatLending();
 
 async function run() {
-  const result = await codatLending.companies.list({
-    page: 1,
-    pageSize: 100,
-    query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
-    orderBy: "-modifiedDate",
+  await codatLending.accountCategoriesUpdated({
+    clientId: "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
+    clientName: "Bank of Dave",
+    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
+    dataConnectionId: "2e9d2c44-f675-40ba-8049-353bfcb5e171",
+    ruleId: "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
+    ruleType: "Account Categories Updated",
+    alertId: "a9367074-b5c3-42c4-9be4-be129f43577e",
+    message:
+      "Account categories updated for company f1c35bdc-1546-41b9-baf4-3f31135af968.",
+    data: {
+      modifiedDate: "2022-10-23",
+    },
   });
-
-  // Handle the result
-  console.log(result);
 }
 
 run();
@@ -351,6 +359,7 @@ run();
 #### [loanWriteback.sourceAccounts](docs/sdks/sourceaccounts/README.md)
 
 * [create](docs/sdks/sourceaccounts/README.md#create) - Create source account
+* [listMappings](docs/sdks/sourceaccounts/README.md#listmappings) - List bank feed account mappings
 * [createMapping](docs/sdks/sourceaccounts/README.md#createmapping) - Create bank feed account mapping
 
 #### [loanWriteback.suppliers](docs/sdks/codatlendingsuppliers/README.md)
@@ -593,6 +602,7 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`loanWritebackPaymentsGetCreateModel`](docs/sdks/codatlendingloanwritebackpayments/README.md#getcreatemodel) - Get create payment model
 - [`loanWritebackSourceAccountsCreate`](docs/sdks/sourceaccounts/README.md#create) - Create source account
 - [`loanWritebackSourceAccountsCreateMapping`](docs/sdks/sourceaccounts/README.md#createmapping) - Create bank feed account mapping
+- [`loanWritebackSourceAccountsListMappings`](docs/sdks/sourceaccounts/README.md#listmappings) - List bank feed account mappings
 - [`loanWritebackSuppliersCreate`](docs/sdks/codatlendingsuppliers/README.md#create) - Create supplier
 - [`loanWritebackSuppliersGetCreateUpdateModel`](docs/sdks/codatlendingsuppliers/README.md#getcreateupdatemodel) - Get create/update supplier model
 - [`loanWritebackTransfersCreate`](docs/sdks/codatlendingtransfers/README.md#create) - Create transfer
@@ -696,6 +706,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   }, {
     retries: {
       strategy: "backoff",
@@ -741,6 +752,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   // Handle the result
@@ -755,25 +767,15 @@ run();
 <!-- Start Error Handling [errors] -->
 ## Error Handling
 
-All SDK methods return a response object or throw an error. By default, an API error will throw a `errors.SDKError`.
-
-If a HTTP request fails, an operation my also throw an error from the `sdk/models/errors/httpclienterrors.ts` module:
-
-| HTTP Client Error                                    | Description                                          |
-| ---------------------------------------------------- | ---------------------------------------------------- |
-| RequestAbortedError                                  | HTTP request was aborted by the client               |
-| RequestTimeoutError                                  | HTTP request timed out due to an AbortSignal signal  |
-| ConnectionError                                      | HTTP client was unable to make a request to a server |
-| InvalidRequestError                                  | Any input used to create a request is invalid        |
-| UnexpectedClientError                                | Unrecognised or unexpected error                     |
-
-In addition, when custom error responses are specified for an operation, the SDK may throw their associated Error type. You can refer to respective *Errors* tables in SDK docs for more details on possible error types for each operation. For example, the `list` method may throw the following errors:
+Some methods specify known errors which can be thrown. All the known errors are enumerated in the `sdk/models/errors/errors.ts` module. The known errors for a method are documented under the *Errors* tables in SDK docs. For example, the `list` method may throw the following errors:
 
 | Error Type          | Status Code                            | Content Type     |
 | ------------------- | -------------------------------------- | ---------------- |
 | errors.ErrorMessage | 400, 401, 402, 403, 404, 429, 500, 503 | application/json |
 | errors.SDKError     | 4XX, 5XX                               | \*/\*            |
 
+If the method throws an error and it is not captured by the known errors, it will default to throwing a `SDKError`.
+
 ```typescript
 import { CodatLending } from "@codat/lending";
 import {
@@ -793,14 +795,16 @@ async function run() {
       pageSize: 100,
       query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
       orderBy: "-modifiedDate",
+      tags: "region=uk && team=invoice-finance",
     });
 
     // Handle the result
     console.log(result);
   } catch (err) {
     switch (true) {
+      // The server response does not match the expected SDK schema
       case (err instanceof SDKValidationError): {
-        // Validation errors can be pretty-printed
+        // Pretty-print will provide a human-readable multi-line error message
         console.error(err.pretty());
         // Raw value may also be inspected
         console.error(err.rawValue);
@@ -812,6 +816,7 @@ async function run() {
         return;
       }
       default: {
+        // Other errors such as network errors, see HTTPClientErrors for more details
         throw err;
       }
     }
@@ -822,7 +827,17 @@ run();
 
 ```
 
-Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.
+Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted multi-line string since validation errors can list many issues and the plain error string may be difficult read when debugging.
+
+In some rare cases, the SDK can fail to get a response from the server or even make the request due to unexpected circumstances such as network conditions. These types of errors are captured in the `sdk/models/errors/httpclienterrors.ts` module:
+
+| HTTP Client Error                                    | Description                                          |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| RequestAbortedError                                  | HTTP request was aborted by the client               |
+| RequestTimeoutError                                  | HTTP request timed out due to an AbortSignal signal  |
+| ConnectionError                                      | HTTP client was unable to make a request to a server |
+| InvalidRequestError                                  | Any input used to create a request is invalid        |
+| UnexpectedClientError                                | Unrecognised or unexpected error                     |
 <!-- End Error Handling [errors] -->
 
 <!-- Start Server Selection [server] -->
@@ -845,6 +860,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   // Handle the result
@@ -930,6 +946,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   // Handle the result

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/docs/sdks/accountspayable/README.md

@@ -1,2 +1,6 @@
 # AccountsPayable
-(*accountsPayable*)
+(*accountsPayable*)
+
+## Overview
+
+### Available Operations

package/docs/sdks/accountsreceivable/README.md

@@ -1,2 +1,6 @@
 # AccountsReceivable
-(*accountsReceivable*)
+(*accountsReceivable*)
+
+## Overview
+
+### Available Operations

package/docs/sdks/banking/README.md

@@ -1,2 +1,6 @@
 # Banking
-(*banking*)
+(*banking*)
+
+## Overview
+
+### Available Operations

package/docs/sdks/codatlending/README.md

@@ -28,4 +28,6 @@ The Lending API is built on top of the latest accounting, commerce, and banking
 | Manage data | Control how data is retrieved from an integration. |
 | File upload | Endpoints to manage uploaded files. |
 | Loan writeback | Implement the [loan writeback](https://docs.codat.io/lending/guides/loan-writeback/introduction) procedure in your lending process to maintain an accurate position of a loan during the entire lending cycle. |
-<!-- End Codat Tags Table -->
+<!-- End Codat Tags Table -->
+
+### Available Operations

package/docs/sdks/codatlendingdirectcosts/README.md

@@ -151,16 +151,6 @@ async function run() {
               name: "Class 1",
             },
           ],
-          tracking: {
-            recordRefs: [
-              {
-                dataType: "trackingCategories",
-              },
-            ],
-            invoiceTo: {
-              dataType: "accountTransaction",
-            },
-          },
         },
       ],
       paymentAllocations: [
@@ -172,12 +162,10 @@ async function run() {
               id: "80000028-1671794219",
               name: "Bank Account 1",
             },
-            currency: "USD",
             paidOnDate: "2023-01-28T10:19:52.223Z",
             totalAmount: new Decimal("54"),
           },
           allocation: {
-            currency: "GBP",
             currencyRate: new Decimal("0"),
             allocatedOnDate: "2023-01-29T10:19:52.223Z",
             totalAmount: new Decimal("88"),
@@ -249,16 +237,6 @@ async function run() {
               name: "Class 1",
             },
           ],
-          tracking: {
-            recordRefs: [
-              {
-                dataType: "trackingCategories",
-              },
-            ],
-            invoiceTo: {
-              dataType: "accountTransaction",
-            },
-          },
         },
       ],
       paymentAllocations: [
@@ -270,12 +248,10 @@ async function run() {
               id: "80000028-1671794219",
               name: "Bank Account 1",
             },
-            currency: "USD",
             paidOnDate: "2023-01-28T10:19:52.223Z",
             totalAmount: new Decimal("54"),
           },
           allocation: {
-            currency: "GBP",
             currencyRate: new Decimal("0"),
             allocatedOnDate: "2023-01-29T10:19:52.223Z",
             totalAmount: new Decimal("88"),

package/docs/sdks/companies/README.md

@@ -20,6 +20,19 @@ Create and manage your SMB users' companies.
 A [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.
 Each company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.
 
+## Filter by tags
+
+The *List companies* endpoint supports the filtering of companies using [tags](https://docs.codat.io/using-the-api/managing-companies#add-metadata-to-a-company). It supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying):
+
+- equals (`=`)
+- not equals (`!=`)
+- contains (`~`)
+
+For example, you can use the querying to filter companies tagged with a specific foreign key, region, or owning team: 
+- Foreign key: `uid = {yourCustomerId}`
+- Region: `region != uk`
+- Owning team and region: `region = uk && owningTeam = invoice-finance`
+
 ### Example Usage
 
 ```typescript
@@ -35,6 +48,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   // Handle the result
@@ -64,6 +78,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   if (!res.ok) {

package/docs/sdks/financialstatements/README.md

@@ -1,2 +1,6 @@
 # FinancialStatements
-(*financialStatements*)
+(*financialStatements*)
+
+## Overview
+
+### Available Operations

package/docs/sdks/loanwriteback/README.md

@@ -1,2 +1,6 @@
 # LoanWriteback
-(*loanWriteback*)
+(*loanWriteback*)
+
+## Overview
+
+### Available Operations

package/docs/sdks/sales/README.md

@@ -1,2 +1,6 @@
 # Sales
-(*sales*)
+(*sales*)
+
+## Overview
+
+### Available Operations