Add documentation for API events

XRPLF · Nov 19, 2015 · 25d1ac0 · 25d1ac0
1 parent f534baf
commit 25d1ac0
Show file tree

Hide file tree

Showing 5 changed files with 165 additions and 25 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -55,6 +55,9 @@
   - [submit](#submit)
   - [generateAddress](#generateaddress)
   - [computeLedgerHash](#computeledgerhash)
+- [API Events](#api-events)
+  - [ledgerClosed](#ledgerclosed)
+  - [error](#error)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -211,7 +214,7 @@ A *transaction specification* specifies what a transaction should do. Each [Tran
 
 ## Payment
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -264,7 +267,7 @@ paths | string | *Optional* The paths of trustlines and orders to use in executi
 
 ## Trustline
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -295,7 +298,7 @@ ripplingDisabled | boolean | *Optional* If true, payments cannot ripple through
 
 ## Order
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -329,7 +332,7 @@ passive | boolean | *Optional* If enabled, the offer will not consume offers tha
 
 ## Order Cancellation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -345,7 +348,7 @@ orderSequence | [sequence](#account-sequence-number) | The [account sequence num
 
 ## Settings
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -376,7 +379,7 @@ transferRate | number,null | *Optional*  The fee to charge when users transfer t
 
 ## Suspended Payment Creation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -425,7 +428,7 @@ memos[] | object | Memo objects represent arbitrary data that can be included in
 
 ## Suspended Payment Cancellation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -450,7 +453,7 @@ memos[] | object | Memo objects represent arbitrary data that can be included in
 
 ## Suspended Payment Execution
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 Name | Type | Description
 ---- | ---- | -----------
@@ -3306,3 +3309,67 @@ return api.computeLedgerHash(ledger);
 "F4D865D83EB88C1A1911B9E90641919A1314F36E1B099F8E95FE3B7C77BE3349"
 ```
 
+# API Events
+
+## ledgerClosed
+
+This event is emitted whenever a new ledger version is validated on the connected server.
+
+### Return Value
+
+Name | Type | Description
+---- | ---- | -----------
+feeBase | integer | Base fee, in drops.
+feeReference | integer | Cost of the 'reference transaction' in 'fee units'.
+ledgerHash | string | Unique hash of the ledger that was closed, as hex.
+ledgerTimestamp | date-time string | The time at which this ledger closed.
+reserveBase | integer | The minimum reserve, in drops of XRP, that is required for an account.
+reserveIncrement | integer | The increase in account reserve that is added for each item the account owns, such as offers or trust lines.
+transactionCount | integer | Number of new transactions included in this ledger.
+ledgerVersion | integer | Ledger version of the ledger that closed.
+validatedLedgerVersions | string | Range of ledgers that the server has available. This may be discontiguous.
+
+### Example
+
+```javascript
+api.on('ledgerClosed', ledger => {
+  console.log(JSON.stringify(ledger, null, 2));
+});
+```
+
+
+```json
+{
+  "feeBase": 10,
+  "feeReference": 10,
+  "ledgerVersion": 14804627,
+  "ledgerHash": "9141FA171F2C0CE63E609466AF728FF66C12F7ACD4B4B50B0947A7F3409D593A",
+  "ledgerTimestamp": "2015-07-23T05:50:40.000Z",
+  "reserveBase": 20000000,
+  "reserveIncrement": 5000000,
+  "transactionCount": 19,
+  "validatedLedgerVersions": "13983423-14804627"
+}
+```
+
+
+## error
+
+This event is emitted when there is an error on the connection to the server.
+
+### Return Value
+
+The first parameter is a string indicating the error type, which may be `badMessage` (meaning that rippled returned a malformed message), or one of the [rippled Universal Errors](https://ripple.com/build/rippled-apis/#universal-errors). The second parameter is a message explaining the error, or the message that caused the error in the case of `badMessage`.
+
+### Example
+
+```javascript
+api.on('error', (errorCode, errorMessage) => {
+  console.log(errorCode + ': ' + errorMessage);
+});
+```
+
+```
+tooBusy: The server is too busy to help you now.
+```
+
diff --git a/docs/src/events.md.ejs b/docs/src/events.md.ejs
@@ -0,0 +1,39 @@
+# API Events
+
+## ledgerClosed
+
+This event is emitted whenever a new ledger version is validated on the connected server.
+
+### Return Value
+
+<%- renderSchema('output/ledger-closed.json') %>
+
+### Example
+
+```javascript
+api.on('ledgerClosed', ledger => {
+  console.log(JSON.stringify(ledger, null, 2));
+});
+```
+
+<%- renderFixture('responses/ledger-closed.json') %>
+
+## error
+
+This event is emitted when there is an error on the connection to the server.
+
+### Return Value
+
+The first parameter is a string indicating the error type, which may be `badMessage` (meaning that rippled returned a malformed message), or one of the [rippled Universal Errors](https://ripple.com/build/rippled-apis/#universal-errors). The second parameter is a message explaining the error, or the message that caused the error in the case of `badMessage`.
+
+### Example
+
+```javascript
+api.on('error', (errorCode, errorMessage) => {
+  console.log(errorCode + ': ' + errorMessage);
+});
+```
+
+```
+tooBusy: The server is too busy to help you now.
+```
diff --git a/docs/src/index.md.ejs b/docs/src/index.md.ejs
@@ -33,3 +33,4 @@
 <% include submit.md.ejs %>
 <% include generateAddress.md.ejs %>
 <% include computeLedgerHash.md.ejs %>
+<% include events.md.ejs %>
diff --git a/docs/src/specifications.md.ejs b/docs/src/specifications.md.ejs
@@ -4,7 +4,7 @@ A *transaction specification* specifies what a transaction should do. Each [Tran
 
 ## Payment
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/payment.json') %>
 
@@ -14,7 +14,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Trustline
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/trustline.json') %>
 
@@ -24,7 +24,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Order
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/order.json') %>
 
@@ -34,7 +34,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Order Cancellation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/order-cancellation.json') %>
 
@@ -44,7 +44,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Settings
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('output/get-settings.json') %>
 
@@ -54,7 +54,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Suspended Payment Creation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/suspended-payment-creation.json') %>
 
@@ -64,7 +64,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Suspended Payment Cancellation
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/suspended-payment-cancellation.json') %>
 
@@ -74,7 +74,7 @@ See [Transcation Types](#transaction-types) for a description.
 
 ## Suspended Payment Execution
 
-See [Transcation Types](#transaction-types) for a description.
+See [Transaction Types](#transaction-types) for a description.
 
 <%- renderSchema('specifications/suspended-payment-execution.json') %>
 

diff --git a/src/common/schemas/output/ledger-closed.json b/src/common/schemas/output/ledger-closed.json
@@ -4,15 +4,48 @@
   "description": "A ledgerClosed event message",
   "type": "object",
   "properties": {
-    "feeBase": {"type": "integer", "minimum": 0},
-    "feeReference": {"type": "integer", "minimum": 0},
-    "ledgerHash": {"$ref": "hash256"},
-    "ledgerVersion": {"$ref": "ledgerVersion"},
-    "ledgerTimestamp": {"type": "string", "format": "date-time"},
-    "reserveBase": {"type": "integer", "minimum": 0},
-    "reserveIncrement": {"type": "integer", "minimum": 0},
-    "transactionCount": {"type": "integer", "minimum": 0},
-    "validatedLedgerVersions": {"type": "string"}
+    "feeBase": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Base fee, in drops."
+    },
+    "feeReference": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cost of the 'reference transaction' in 'fee units'."
+    },
+    "ledgerHash": {
+      "$ref": "hash256",
+      "description": "Unique hash of the ledger that was closed, as hex."
+    },
+    "ledgerVersion": {
+      "$ref": "ledgerVersion",
+      "description": "Ledger version of the ledger that closed."
+    },
+    "ledgerTimestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The time at which this ledger closed."
+    },
+    "reserveBase": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The minimum reserve, in drops of XRP, that is required for an account."
+    },
+    "reserveIncrement": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The increase in account reserve that is added for each item the account owns, such as offers or trust lines."
+    },
+    "transactionCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of new transactions included in this ledger."
+    },
+    "validatedLedgerVersions": {
+      "type": "string",
+      "description": "Range of ledgers that the server has available. This may be discontiguous."
+    }
   },
   "addtionalProperties": false,
   "required": ["feeBase", "feeReference", "ledgerHash", "ledgerTimestamp",