@codat/lending 7.0.0 → 7.2.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();
@@ -251,6 +259,7 @@ run();
 
 * [list](docs/sdks/companies/README.md#list) - List companies
 * [create](docs/sdks/companies/README.md#create) - Create company
+* [replace](docs/sdks/companies/README.md#replace) - Replace company
 * [update](docs/sdks/companies/README.md#update) - Update company
 * [delete](docs/sdks/companies/README.md#delete) - Delete a company
 * [get](docs/sdks/companies/README.md#get) - Get company
@@ -351,6 +360,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)
@@ -551,6 +561,7 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`companiesDelete`](docs/sdks/companies/README.md#delete) - Delete a company
 - [`companiesGet`](docs/sdks/companies/README.md#get) - Get company
 - [`companiesList`](docs/sdks/companies/README.md#list) - List companies
+- [`companiesReplace`](docs/sdks/companies/README.md#replace) - Replace company
 - [`companiesUpdate`](docs/sdks/companies/README.md#update) - Update company
 - [`companyInfoGetAccountingProfile`](docs/sdks/companyinfo/README.md#getaccountingprofile) - Get company accounting profile
 - [`companyInfoGetCommerceProfile`](docs/sdks/companyinfo/README.md#getcommerceprofile) - Get company commerce profile
@@ -593,6 +604,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 +708,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 +754,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 +769,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 +797,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 +818,7 @@ async function run() {
         return;
       }
       default: {
+        // Other errors such as network errors, see HTTPClientErrors for more details
         throw err;
       }
     }
@@ -822,7 +829,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 +862,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 +948,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/companies/README.md

@@ -9,6 +9,7 @@ Create and manage your SMB users' companies.
 
 * [list](#list) - List companies
 * [create](#create) - Create company
+* [replace](#replace) - Replace company
 * [update](#update) - Update company
 * [delete](#delete) - Delete a company
 * [get](#get) - Get company
@@ -20,6 +21,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 +49,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 +79,7 @@ async function run() {
     pageSize: 100,
     query: "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
     orderBy: "-modifiedDate",
+    tags: "region=uk && team=invoice-finance",
   });
 
   if (!res.ok) {
@@ -183,9 +199,9 @@ run();
 | errors.ErrorMessage               | 400, 401, 402, 403, 429, 500, 503 | application/json                  |
 | errors.SDKError                   | 4XX, 5XX                          | \*/\*                             |
 
-## update
+## replace
 
-Use the *Update company* endpoint to update both the name and description of the company. 
+Use the *Replace company* endpoint to replace the existing name, description, and tags of the company. Calling the endpoint will replace existing values even if new values haven't been defined in the payload.
 
 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.
@@ -200,11 +216,10 @@ const codatLending = new CodatLending({
 });
 
 async function run() {
-  const result = await codatLending.companies.update({
+  const result = await codatLending.companies.replace({
     companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
     companyRequestBody: {
       name: "New Name",
-      description: "Requested early access to the new financing scheme.",
     },
   });
 
@@ -221,7 +236,7 @@ The standalone function version of this method:
 
 ```typescript
 import { CodatLendingCore } from "@codat/lending/core.js";
-import { companiesUpdate } from "@codat/lending/funcs/companiesUpdate.js";
+import { companiesReplace } from "@codat/lending/funcs/companiesReplace.js";
 
 // Use `CodatLendingCore` for best tree-shaking performance.
 // You can create one instance of it to use across an application.
@@ -230,11 +245,101 @@ const codatLending = new CodatLendingCore({
 });
 
 async function run() {
-  const res = await companiesUpdate(codatLending, {
+  const res = await companiesReplace(codatLending, {
     companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
     companyRequestBody: {
       name: "New Name",
-      description: "Requested early access to the new financing scheme.",
+    },
+  });
+
+  if (!res.ok) {
+    throw res.error;
+  }
+
+  const { value: result } = res;
+
+  // Handle the result
+  console.log(result);
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [operations.ReplaceCompanyRequest](../../sdk/models/operations/replacecompanyrequest.md)                                                                                       | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[shared.Company](../../sdk/models/shared/company.md)\>**
+
+### Errors
+
+| Error Type                        | Status Code                       | Content Type                      |
+| --------------------------------- | --------------------------------- | --------------------------------- |
+| errors.ErrorMessage               | 401, 402, 403, 404, 429, 500, 503 | application/json                  |
+| errors.SDKError                   | 4XX, 5XX                          | \*/\*                             |
+
+## update
+
+Use the *Update company* endpoint to update the name, description, or tags of the company.
+
+The *Update company* endpoint doesn't have any required fields. If any of the fields provided are `null` or not provided, they won't be included in the update.  
+
+A [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.
+
+### Example Usage
+
+```typescript
+import { CodatLending } from "@codat/lending";
+
+const codatLending = new CodatLending({
+  authHeader: "Basic BASE_64_ENCODED(API_KEY)",
+});
+
+async function run() {
+  const result = await codatLending.companies.update({
+    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
+    companyUpdateRequest: {
+      tags: {
+        "refrence": "new reference",
+      },
+    },
+  });
+
+  // Handle the result
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { CodatLendingCore } from "@codat/lending/core.js";
+import { companiesUpdate } from "@codat/lending/funcs/companiesUpdate.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 companiesUpdate(codatLending, {
+    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
+    companyUpdateRequest: {
+      tags: {
+        "refrence": "new reference",
+      },
     },
   });