chore: remove beta tag, add fn docs, and improve addReflectorEntries testing

Author: mootz12

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@blend-capital/blend-sdk",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Javascript SDK for the Blend Protocol",
   "type": "module",
   "scripts": {
@@ -18,7 +18,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "repository": {
     "type": "git",

package.json

@@ -16,17 +16,25 @@ const REFLECTOR_ORACLE_ADDRESSES = [
   'CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN',
 ];
 
-interface ReflectorEntry {
-  contract: xdr.ScAddress;
-  key: number;
-  roundTimestamp: bigint;
-}
-
 export interface PriceData {
+  /**
+   * The price as a fixed point number with the oracle's decimals.
+   */
   price: bigint;
+  /**
+   * The timestamp of the price in seconds
+   */
   timestamp: number;
 }
 
+/**
+ * Fetch the `lastprice` from an oracle contract for the given token.
+ * @param network - The network to use
+ * @param oracle_id - The oracle contract ID
+ * @param token_id - The token contract ID to fetch the price for
+ * @returns The PriceData
+ * @throws Will throw an error if `None` is returned or if the simulation fails.
+ */
 export async function getOraclePrice(
   network: Network,
   oracle_id: string,
@@ -55,7 +63,7 @@ export async function getOraclePrice(
           // eslint-disable-next-line
           // @ts-ignore
           price: scValToNative(price_result[0]?.val()),
-          timestamp: scValToNative(price_result[1]?.val()),
+          timestamp: Number(scValToNative(price_result[1]?.val())),
         };
       }
     }
@@ -65,6 +73,13 @@ export async function getOraclePrice(
   }
 }
 
+/**
+ * Fetch the `decimals` from an oracle contract.
+ * @param network - The network to use
+ * @param oracle_id - The oracle contract ID
+ * @returns The decimals and latest ledger number
+ * @throws Will throw an error if the simulation fails.
+ */
 export async function getOracleDecimals(
   network: Network,
   oracle_id: string
@@ -90,6 +105,20 @@ export async function getOracleDecimals(
   }
 }
 
+/**
+ * Add future Reflector oracle entries to the read-only footprint of a transaction.
+ * This ensures that if a future oracle round occurs before the transaction is executed,
+ * the future oracle round will still be included in the footprint.
+ * 
+ * This only works for Reflector based oracles as it makes assumptions based on how the 
+ * oracle contracts keys are structured.
+ * 
+ * If more than 100 entries are added to the read-only footprint, it will stop adding. The priority
+ * is given to the oracle contracts seen first, and the indexes for the contract that are seen first.
+ * 
+ * @param tx - The transaction to add the reflector entries to.
+ * @returns A new transaction object with the reflector entries added to the read-only footprint if necessary.
+ */
 export function addReflectorEntries(tx: Transaction): Transaction {
   if (tx.toEnvelope().switch() !== xdr.EnvelopeType.envelopeTypeTx()) {
     return tx;