v1.0.2

Changelog

• Added new URL of SDK's source code
• Replaces instances of PaymentRails with Trolley
• Updated package metadata

v1.0.1

Changelog

• Minor fix of typo in installation & usage instruction in README
• New version push fixes NPM package error with /dist folder

v1.0.0

Trolley Javascript SDK Major Update (May 1, 2023)

With this update we're making some important changes to our Javascript SDK.
This update covers all the API endpoints our SDK didn't cover before. We are also renaming all classes to Trolley to complete our rebranding.

To mark this milestone we're moving to our first major version 1.0.0, and are releasing this version under a new name.

Please read this Update Guide to understand what changed and how to adopt these changes.

Breaking Changes

1. New package on NPM

Our Javascript SDK is now available under a new namespace on NPM, which is as per our new name 'Trolley' : https://www.npmjs.com/package/trolleyhq

With this update, you'll have to make changes to how Trolley SDK is referenced and used in your code:

• The command you used to install the SDK now changes:

Old Installation	New Installation
npm i paymentrails	npm i trolleyhq

• If you're adding the package directly in your package.json you'll need to replace it with the new package name:

Old Package	New Package
"paymentrails": "^0.11.0"	"trolleyhq": "^1.0.0"

• You'll also need to update the gem import in your code:

Old Package	New Package
const paymentrails = require("paymentrails");	const paymentrails = require("trolley");
import paymentrails from "paymentrails";	import trolley from "trolley";

2. All “PaymentRails” classes rebranded to “Trolley”

To complete our rebranding, all the classes called PaymentRails are now called Trolley. You'll need to rename all the class usage in your code.

Old usage

const pr_trolley = require('paymentrails');

const client = pr_trolley.connect({
  key: "ACCESS-KEY",
  secret: "ACCESS-SECRET",
  environment: "production",
});

const recipient = await client.recipient.find("R-1234567abcdefg");
console.log(recipient.id);

New usage

const trolley = require('trolley');

const client = trolley.connect({
  key: "ACCESS-KEY",
  secret: "ACCESS-SECRET"
});

const recipient = await client.recipient.find("R-1234567abcdefg");
console.log(recipient.id);

A simple find-and-replace should be helpful in replacing the class names.

3. No need to specify environment now

The SDK now defaults to the production URL i.e. api.trolley.com.
Even while setting up a proxy you no longer need to provide an environment.

Old way

const client = pr_trolley.connect({
  key: "ACCESS-KEY",
  secret: "ACCESS-SECRET",
  environment: "production",
});

New way

const client = trolley.connect({
  key: "ACCESS-KEY",
  secret: "ACCESS-SECRET"
});

4. Type of Amount.value is now a String

Amount.value in Invoice and InvoiceLine items used to be a number, now its a string.
If you’re using this field as a number, you’ll now have to update your code.

5. Exceptions are now called Errors

To conform with JS standards, Exceptions are now called Errors.
Rest everything remains the same.

So if you were using try/catch and were catching Trolley related Exceptions, all you need to do is replace the word Exceptions with Errors.

Usage

...
catch (error: any) {
console.debug(error.validationErrors);
}
...

Updates to Existing Methods

1. Support for Errors as Arrays

The API returns errors in a JSON array. To support this, we have added a way for you to access the errors as an Array as well.
This should make it easier for you to iterate through the array and process the errors.

The error can be accessed through validationErrors variable.

Example: Consuming error Array

...
catch (error: any) {
      console.log(error.validationErrors.length);
      console.log(error.validationErrors[0].code);
      console.log(error.validationErrors[0].field);
      console.log(error.validationErrors[0].message);
}
...

You don't need to make any code changes, your old code will still work.
This just gives more options to you to process error messages should you want.

2. Delete multiple recipients with Recipient.remove()

Now, you can provide a set of recipeintIds[] as an array to delete multiple recipients.

Old Usage

const deletedRecipient = await client.recipient.remove(recipient.id);

New Usage

// Delete single recipient
const deletedRecipient = await client.recipient.remove(recipient.id);

// Delete multiple recipients
const deletedRecipients = await client.recipient.remove([ recipient1.id, recipient2.id, ...]);

3. Delete multiple batches with Batch.remove()

Now, you can provide a set of batchIds[] as array to delete multiple batches.

Old Usage

const deletedBatch = await client.batch.remove(batch.id);

New Usage

// Delete single batch
const deletedBatch = await client.batch.remove(batch.id);

// Delete multiple batches
const deletedBatches = await client.batch.remove.remove([ batch1.id, batch2.id, ...]);

4. Improvements to Pagination

We have made improvements to how our SDK handles pagination.
Now you can paginate easily through index functions such as Search.
View an example below.

Example: Paginating through results

const recipients = await client.recipient.search();

// Iterate over all recipients and print email
    for (page = 1; page <= recipients.meta.pages; page++) {
      const recipients = await client.recipient.search(page);
      recipients.map((recipient) => {
        console.log(recipient.email);
      });
    }

New Methods/API Coverage

We have added support for more API endpoints that our Javascript SDK wasn't supporting earlier. Here's a rundown of the new API endpoints covered:

1. Recipient.findLogs() - Get all Recipient logs

const logs = await client.recipient.findLogs(recipient.id);

2. Recipient.findPayments() - Get all payments of a Recipient

const payments = await client.recipient.findPayments(recipient.id);

3. Recipient.findOfflinePayments() - Get all Offline Payments of a Recipient

const offlinePayments = await client.recipient.findOfflinePayments(recipient.id);

4. InvoicePayment.create() - Create a new InvoicePayment

const invoicePayment = client.invoicePayment.create({
                ids: [
                    {
                        invoiceId: invoice.id,
                        amount: {
                            currency: "USD",
                            value: "100",
                        },
                    },
                ],
            },
        );

5. InvoicePayment.update() - Update an InvoicePayment

const updatedInvoicePayment = await client.invoicePayment.update(
          { paymentId: paymentId,
              invoiceLineId: invoiceLineId,
              amount: {
                  currency: "USD",
                  value: "200",
              },
          },
        );

6. InvoicePayment.delete() - Delete an InvoicePayment

const deletedInvoicePayment = await client.invoicePayment.delete(
          { paymentId: paymentId,
              invoiceLineIds: [invoiceLineId1, invoiceLineId1, ...]
          },
        );

7. InvoicePayment.search()- Search through Invoice Payments

const searchResults = await client.invoicePayment.search(
          { invoiceIds: [invoice.id] },
        );

Housekeeping updates

Apart form covering new APIs, we also updated the dependencies to improve the functionality and security of the SDK:

1. request - ~2.48.1 -> ^2.88.0
2. tslint - ~5.12.1 -> ^6.0.0
3. typedoc - ~0.14.2 -> ^0.23.0
4. typedoc-plugin-markdown - ~1.1.26 -> ^3.0.0
5. typescript - ~3.3.3 -> ^4.6.0

---

We hope these new updates help you build Trolley integration faster and more reliably.
If you have any questions or find any bugs, please open an issue or reach out to us at developers@trolley.com
Collaborations and PRs are welcome.

v1.0.0-dev

v1.0.0 is released, update guides are here: https://github.com/PaymentRails/javascript-sdk/releases/tag/1.0.0

v0.11.1

v0.11.1 Changelog

---

1. Rebranded non-class elements to Trolley
2. Added tests for routeMinimum
3. Added Trolley-Source header