Skip to content

Commit

Permalink
add v3.0 upgrade docs, update README usage instructions
Browse files Browse the repository at this point in the history 
Signed-off-by: Bruno Vieira <[email protected]>
  • Loading branch information
Bruno Vieira committed Nov 7, 2023
1 parent 51bc5c0 commit ed16452
Show file tree
Hide file tree
Showing 3 changed files with 84 additions and 63 deletions.
40 changes: 40 additions & 0 deletions 3.0-Upgrade.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Upgrading to chartmogul-node 3.0.0

This new version replaces the existing pagination for the `.all()` endpoints that used a combination
of `page` and `per_page` parameters, and instead uses a `cursor` based pagination. So to list
(as an example) Plans you now can:

```js
const ChartMogul = require('chartmogul-node');

const config = new ChartMogul.Config('apiKey');

// Getting the first page
plans = ChartMogul.Plan.all(config, { per_page: 12 })
```

This will return an array of plans (if available), and a cursor + has_more fields:

```json
{
"plans": [
{
"uuid": "some_uuid",
"data_source_uuid": "some_uuid",
"name": "Master Plan"
}
],
"has_more": true,
"cursor": "MjAyMy0wNy0yOFQwODowOToyMi4xNTQyMDMwMDBaJjk0NDQ0Mg=="
}
```

```js
// You can get other pages passing a cursor
if (plans.has_more) {
more_plans = ChartMogul.Plan.all(config, { per_page: 3, cursor: plans.cursor })
}
```

If you have existing code that relies on the `page` parameter, those requests will now throw an error
alerting you of their deprecation.
105 changes: 43 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,11 @@ You need to pass this config object as the first argument to each request.


### Test your authentication

```js
ChartMogul.Ping.ping(config)
.then(res => console.log(res))
.catch(err => console.error(err))
.then(res => console.log(res))
.catch(err => console.error(err))
```

## Usage
Expand Down Expand Up @@ -77,7 +78,6 @@ ChartMogul.Customer.create(config, {
console.log(res);
})
.catch(e => console.error(e.message, e.httpStatus, e.response));

```

**Using with a callback**
Expand All @@ -88,7 +88,7 @@ const ChartMogul = require('chartmogul-node');
const config = new ChartMogul.Config('apiKey');

ChartMogul.Customer.create(config, data, (err, res) => {
if(err){
if(err) {
console.error(err.message, err.httpStatus, err.response)
}
console.log(res);
Expand All @@ -103,7 +103,7 @@ Available methods in Import API:

```js
ChartMogul.DataSource.create(config, data)
ChartMogul.DataSource.retrieve(config, uuid)
ChartMogul.DataSource.retrieve(config, dataSourceUuid)
ChartMogul.DataSource.all(config, query)
ChartMogul.DataSource.destroy(config, dataSourceUuid)
```
Expand All @@ -112,31 +112,39 @@ ChartMogul.DataSource.destroy(config, dataSourceUuid)

```js
ChartMogul.Customer.create(config, data)
ChartMogul.Customer.retrieve(config, customerUuid)
ChartMogul.Customer.all(config, { per_page: 20 })
ChartMogul.Customer.modify(config, customerUuid, data)
ChartMogul.Customer.destroy(config, customerUuid)
ChartMogul.Customer.merge(config, {
"from": {"customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"},
"into": {"customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"}
})

ChartMogul.Customer.contacts(config, customerUuid, { per_page: 10, cursor: 'aabbcc...' })
ChartMogul.Customer.contacts(config, customerUuid, { per_page: 10, cursor: 'cursor==' })
ChartMogul.Customer.createContact(config, customerUuid, data)
```

#### [Contacts](https://dev.chartmogul.com/docs/contacts)

```js
ChartMogul.Contact.create(config, data)
ChartMogul.Contact.all(config, { per_page: 10, cursor: 'aabbcc...' })
ChartMogul.Contact.retrieve(config, contactUuid)
ChartMogul.Contact.modify(config, contactUuid)
ChartMogul.Contact.destroy(config, contactUuid)
ChartMogul.Contact.merge(config, intoUuid, fromUuid);
ChartMogul.Contact.all(config, { per_page: 10, cursor: 'cursor==' })

```

#### [Plans](https://dev.chartmogul.com/docs/plans)

```js
ChartMogul.Plan.create(config, data)
ChartMogul.Plan.retrieve(config, uuid)
ChartMogul.Plan.modify(config, uuid, {
name: "new name"
})
ChartMogul.Plan.all(config, query)
ChartMogul.Plan.modify(config, uuid, { name: "new name" })
ChartMogul.Plan.destroy(config, uuid)
ChartMogul.Plan.all(config, query)
```

#### [Plan Groups](https://dev.chartmogul.com/docs/plan_groups)
Expand All @@ -145,18 +153,28 @@ ChartMogul.Plan.destroy(config, uuid)
ChartMogul.PlanGroup.create(config, data)
ChartMogul.PlanGroup.retrieve(config, planGroupUuid)
ChartMogul.PlanGroup.modify(config, planGroupUuid, data)
ChartMogul.PlanGroup.destroy(config, planGroupUuid)
ChartMogul.PlanGroup.all(config, query)
ChartMogul.PlanGroup.all(config, planGroupUuid, query)
ChartMogul.PlanGroup.destroy(config, planGroupUuid)
```

#### [Subscriptions](https://dev.chartmogul.com/docs/subscriptions)

```js
ChartMogul.Subscription.all(config, customerUuid, query)
ChartMogul.Subscription.cancel(config, subscriptionUuid, { cancelled_at: "" })
ChartMogul.Subscription.modify(config, subscriptionUuid, { cancellation_dates: [] })
```

#### [Invoices](https://dev.chartmogul.com/docs/invoices)

```js
ChartMogul.Invoice.create(config, customerUuid, data)
ChartMogul.Invoice.retrieve(config, invoiceUuid)
ChartMogul.Invoice.destroy(config, invoiceUuid)
ChartMogul.Invoice.all(config, customerUuid, query)
ChartMogul.Invoice.all(config, query)
ChartMogul.Invoice.retrieve(config, invoiceUuid)
ChartMogul.Invoice.destroy_all(config, dataSourceUuid, customerUuid)
```

#### [Transactions](https://dev.chartmogul.com/docs/transactions)
Expand All @@ -165,17 +183,9 @@ ChartMogul.Invoice.retrieve(config, invoiceUuid)
ChartMogul.Transaction.create(config, invoiceUuid, data)
```

#### [Subscriptions](https://dev.chartmogul.com/docs/subscriptions)

```js
ChartMogul.Subscription.all(config, customerUuid, query)
ChartMogul.Subscription.cancel(config, subscriptionUuid, {cancelled_at: ""})
ChartMogul.Subscription.modify(config, subscriptionUuid, {cancellation_dates: []})
```

#### [Subscription events](https://dev.chartmogul.com/reference/subscription-events)

```js
ChartMogul.SubscriptionEvent.all(config, query)
ChartMogul.SubscriptionEvent.create(config, {
subscription_event: {
event_type: 'subscription_cancelled',
Expand All @@ -197,43 +207,17 @@ ChartMogul.SubscriptionEvent.deleteWithParams(config, {
id: 1
}
})
ChartMogul.SubscriptionEvent.all(config, query)
```

### Enrichment API

Available methods in Enrichment API:


#### [Customers](https://dev.chartmogul.com/docs/retrieve-customer)

```js
ChartMogul.Customer.retrieve(config, customerUuid)
ChartMogul.Customer.all(config, query)
ChartMogul.Customer.search(config, {
email: '[email protected]'
})

ChartMogul.Customer.merge(config, {
"from": {"customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"},
"into": {"customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"}
})

ChartMogul.Customer.modify(config, "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb", {
"lead_created_at": "2015-01-01 00:00:00",
"free_trial_started_at": "2015-06-13 15:45:13"
})

ChartMogul.Customer.connectSubscriptions(config, "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb", {
"subscriptions": [{
"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
"external_id": "d1c0c885-add0-48db-8fa9-0bdf5017d6b0"
},
{
"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
"external_id": "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4"
}
]
})
ChartMogul.Customer.search(config, { email: '[email protected]' })
```

#### [Customer Attributes](https://dev.chartmogul.com/docs/customer-attributes)
Expand All @@ -246,30 +230,29 @@ ChartMogul.Customer.attributes(config, customerUuid)

```js
ChartMogul.Tag.add(config, customerUuid, {
"tags": ["important", "Prio1"]
'tags': ['important', 'Prio1']
});
ChartMogul.Tag.add(config, {
"email": '[email protected]',
"tags": ["important", "Prio1"]
});
'email': '[email protected]',
'tags': ['important', 'Prio1']
})'
ChartMogul.Tag.remove(config, customerUuid, {
"tags": ["Prio1", "discountable"]
'tags': ['Prio1', 'discountable']
});
```

#### [Custom Attributes](https://dev.chartmogul.com/docs/custom-attributes)
```js
ChartMogul.CustomAttribute.add(config, customerUuid, {
'custom': [
{'type': 'Integer', 'key': 'age', 'value': 8}
{ 'type': 'Integer', 'key': 'age', 'value': 8 }
]
});
ChartMogul.CustomAttribute.add(config, {
'email': 'adam@smith.com',
'email': "adam@example.com",
'custom': [
{'type': 'Integer', 'key': 'age', 'value': 8}
{ 'type': 'Integer', 'key': 'age', 'value': 8 }
]
});
ChartMogul.CustomAttribute.update(config, customerUuid, {
Expand All @@ -283,12 +266,10 @@ ChartMogul.CustomAttribute.remove(config, customerUuid, {
});
```

### [Metrics API](https://dev.chartmogul.com/docs/introduction-metrics-api)
Available methods in Metrics API:

```js
ChartMogul.Metrics.all(config, {
'start-date': '2015-01-01',
Expand Down Expand Up @@ -320,7 +301,6 @@ Available methods:
ChartMogul.Account.retrieve(config)
```

### Errors
The library throws following error objects.
Expand Down Expand Up @@ -371,6 +351,7 @@ To work on the library:
Bug reports and pull requests are welcome on GitHub at https://github.com/chartmogul/chartmogul-node.

## Releasing

1. You need an authorized account on npmjs.com
2. Bump up the version in `package.json` & tag on GitHub
3. `npm test`
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "chartmogul-node",
"version": "3.0.0",
"version": "3.0.1",
"description": "Official Chartmogul API Node.js Client",
"main": "lib/chartmogul.js",
"scripts": {
Expand Down

0 comments on commit ed16452

Please sign in to comment.