aftermath-ts-sdk 1.2.63 → 1.2.64-docs.1

package/dist/packages/auth/auth.js

@@ -12,42 +12,95 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Auth = void 0;
 const caller_1 = require("../../general/utils/caller");
 const utils_1 = require("../../general/utils");
+/**
+ * The `Auth` class manages creation and refreshing of access tokens
+ * to obtain higher rate limits on the Aftermath API. It includes methods
+ * to initialize authorization either by a direct callback-based approach
+ * or by importing a local Sui keystore. Optionally, administrative functions
+ * are provided for creating specialized auth accounts.
+ *
+ * @example
+ * ```typescript
+ * const auth = new Auth();
+ * const stopAuth = await auth.init({
+ *   walletAddress: "0x<address>",
+ *   signMessageCallback: async ({ message }) => {
+ *     // sign message
+ *   },
+ * });
+ * // ... make authenticated requests ...
+ * stopAuth(); // stop auto refresh
+ * ```
+ */
 class Auth extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
+    /**
+     * Creates a new `Auth` instance for token-based rate limit increases.
+     *
+     * @param config - Optional caller configuration, including network and access token.
+     */
     constructor(config) {
         super(config, "auth");
         // =========================================================================
         //  Private Class Members
         // =========================================================================
+        /**
+         * Holds the timer reference for scheduled token refreshes.
+         */
         this.refreshTimer = null;
+        /**
+         * Indicates whether the user has canceled auto token refresh.
+         */
         this.isCanceled = false;
     }
     // =========================================================================
     //  User-Facing
     // =========================================================================
+    /**
+     * Initializes the auth system by fetching an access token for the provided wallet address.
+     * After obtaining the token, it automatically schedules periodic refresh calls until stopped.
+     *
+     * @param inputs - An object containing the user's `walletAddress` and a `signMessageCallback` function
+     *  for cryptographically signing messages.
+     *
+     * @returns A function that, when called, cancels further token refresh attempts.
+     *
+     * @example
+     * ```typescript
+     * const auth = new Auth();
+     * const stopAuth = await auth.init({
+     *   walletAddress: "0x<address>",
+     *   signMessageCallback: async ({ message }) => {
+     *     // sign the message with your private key / keypair
+     *   },
+     * });
+     *
+     * // ... make authorized calls ...
+     *
+     * stopAuth(); // Cancel further token refreshes
+     * ```
+     */
     init(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Step 1: Mark as "not canceled" before the new run
-            this.isCanceled = false;
-            // Step 2: Define a function that does the “work” + schedules next call
+            this.isCanceled = false; // Mark as active
             const startRefresh = () => __awaiter(this, void 0, void 0, function* () {
-                // If canceled at the time we enter, don’t do anything
                 if (this.isCanceled)
-                    return;
+                    return; // No-op if canceled
                 const { accessToken, expirationTimestamp } = yield this.getAccessToken(inputs);
                 this.setAccessToken(accessToken);
                 if (this.isCanceled)
-                    return; // double-check before scheduling next timer
+                    return; // Double-check after token fetch
+                // Provide a margin by refreshing before actual expiration
                 const TIMEOUT_REDUCTION_RATIO = 0.9;
                 const interval = (expirationTimestamp - Date.now()) * TIMEOUT_REDUCTION_RATIO;
-                // Store the timer so we can cancel it later
+                // Schedule next refresh
                 this.refreshTimer = setTimeout(startRefresh, interval);
             });
-            // Step 3: Kick off the first refresh
+            // Kick off first refresh
             yield startRefresh();
-            // Step 4: Return a function that cancels further refreshes
+            // Return cancellation function
             return () => {
                 this.isCanceled = true;
                 if (this.refreshTimer) {
@@ -56,26 +109,48 @@ class Auth extends caller_1.Caller {
             };
         });
     }
+    /**
+     * Initializes the auth system by reading a local Sui keystore file (on the server side),
+     * using the private keys matching a provided address to sign messages for token creation.
+     * After the token is obtained, it automatically schedules periodic refresh calls until stopped.
+     *
+     * @param inputs - An object containing the target `walletAddress` and an optional path to the `.keystore`.
+     *  If `path` is not provided, it defaults to `~/.sui/sui_config/sui.keystore`.
+     * @returns A function that, when called, cancels further token refresh attempts.
+     *
+     * @throws If this method is called in a browser environment (client-side).
+     *
+     * @example
+     * ```typescript
+     * // On server:
+     * const stopAuth = await auth.initFromSuiKeystore({
+     *   walletAddress: "0x<address>",
+     *   path: "/custom/path/to/keystore.json",
+     * });
+     * // authorized calls...
+     * stopAuth();
+     * ```
+     */
     // public async initFromSuiKeystore(inputs: {
     // 	walletAddress: SuiAddress;
     // 	path?: string;
     // }): Promise<() => void> {
     // 	const { walletAddress, path: pathStr } = inputs;
     // 	if (typeof window === "undefined") {
+    // 		// Node environment, proceed with reading a keystore
     // 		const fs = require("fs");
     // 		const path = require("path");
     // 		const os = require("os");
     // 		const keystorePath = pathStr
     // 			? path.join(pathStr)
     // 			: (() => {
-    // 					// Locate the user’s home directory
+    // 					// Default to ~/.sui/sui_config/sui.keystore
     // 					const homeDir = os.homedir();
     // 					if (!homeDir) {
     // 						throw new Error(
     // 							"cannot obtain home directory path"
     // 						);
     // 					}
-    // 					// Construct the path: ~/.sui/sui_config/sui.keystore
     // 					return path.join(
     // 						homeDir,
     // 						".sui",
@@ -83,7 +158,7 @@ class Auth extends caller_1.Caller {
     // 						"sui.keystore"
     // 					);
     // 			  })();
-    // 		// Read the JSON file from `keystorePath`
+    // 		// Read JSON with an array of private keys
     // 		let privateKeys: string[];
     // 		try {
     // 			const fileContent = fs.readFileSync(keystorePath, "utf-8");
@@ -99,6 +174,7 @@ class Auth extends caller_1.Caller {
     // 		if (privateKeys.length <= 0) {
     // 			throw new Error(`Empty keystore file`);
     // 		}
+    // 		// Find the matching key for the requested walletAddress
     // 		const foundKeypair = privateKeys
     // 			.map((privateKey) => Helpers.keypairFromPrivateKey(privateKey))
     // 			.find(
@@ -112,6 +188,7 @@ class Auth extends caller_1.Caller {
     // 				`No private key found in keystore file for ${walletAddress}`
     // 			);
     // 		}
+    // 		// Initialize with sign callback
     // 		return this.init({
     // 			walletAddress,
     // 			signMessageCallback: async ({ message }) =>
@@ -123,10 +200,24 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Admin
     // =========================================================================
-    // NOTE: admin only (should add docs)
+    /**
+     * **Admin-only**: Creates a new auth account with specific rate limits for a given
+     * `accountWalletAddress`. The `walletAddress` performing this action must have
+     * admin privileges, or the call will fail. Use this to create custom sub-accounts
+     * with limited scope or usage rates.
+     *
+     * @param inputs - Contains:
+     *  - `walletAddress`: The admin's wallet address
+     *  - `signMessageCallback`: The admin's signing callback
+     *  - `accountName`: A short name or identifier for the account
+     *  - `accountWalletAddress`: The Sui address representing this sub-account
+     *  - `rateLimits`: An array specifying the rate limits (method-based) for the sub-account
+     * @returns A promise resolving to `true` if successful, otherwise throws or returns `false`.
+     */
     adminCreateAuthAccount(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { walletAddress, signMessageCallback, accountName, accountWalletAddress, rateLimits, } = inputs;
+            // Prepare the data to sign
             const serializedJson = Auth.createSerializedJson("AccountCreate", {
                 sub: accountName,
                 wallet_address: utils_1.Helpers.addLeadingZeroesToType(accountWalletAddress),
@@ -144,9 +235,17 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Private
     // =========================================================================
+    /**
+     * Requests a new access token from the API by sending a signed message
+     * indicating the user wants a token.
+     *
+     * @param inputs - Contains the user's `walletAddress` and `signMessageCallback`.
+     * @returns A response object that includes the `accessToken` and an `expirationTimestamp`.
+     */
     getAccessToken(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { walletAddress, signMessageCallback } = inputs;
+            // Prepare signable data
             const serializedJson = Auth.createSerializedJson("GetAccessToken", {});
             const message = new TextEncoder().encode(serializedJson);
             const { signature } = yield signMessageCallback({ message });
@@ -160,14 +259,29 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Private Static
     // =========================================================================
+    /**
+     * Creates a JSON string with a standard format:
+     * ```json
+     * {
+     *   "date": <epoch-seconds>,
+     *   "nonce": <random_number>,
+     *   "method": <method_string>,
+     *   "value": <passed_value>
+     * }
+     * ```
+     *
+     * @param method - A short method name describing the action ("GetAccessToken", "AccountCreate", etc.).
+     * @param value - The data object to embed under the `value` field.
+     * @returns A JSON-serialized string for signing.
+     */
     static createSerializedJson(method, value) {
         const timestampSeconds = Math.floor(Date.now() / 1000);
         const random = Math.floor(Math.random() * 1024 * 1024);
         const data = {
             date: timestampSeconds,
             nonce: random,
-            method: method,
-            value: value,
+            method,
+            value,
         };
         return JSON.stringify(data);
     }

package/dist/packages/auth/authTypes.d.ts

@@ -1,6 +1,23 @@
 import { SuiAddress, Timestamp } from "../../types";
+/**
+ * Interface specifying allowable rate limits for an auth account.
+ * The `p` field indicates the path or endpoint (e.g., "/pools"),
+ * while `m` indicates the method-based limits (GET or POST, or both).
+ */
 export interface RateLimit {
+    /**
+     * The path or endpoint to be rate-limited, e.g. "/pools" or "/router/trade".
+     */
     p: string;
+    /**
+     * The method-based limit specification.
+     * For example:
+     * ```
+     * { GET: { l: 100 } }
+     * { POST: { l: 50 } }
+     * { GET: { l: 100 }, POST: { l: 100 } }
+     * ```
+     */
     m: {
         GET: {
             l: number;
@@ -18,19 +35,68 @@ export interface RateLimit {
         };
     };
 }
+/**
+ * The request body for creating a new auth account, typically
+ * reserved for admin usage. The admin signs a JSON containing
+ * an "AccountCreate" `method` plus desired sub-account data.
+ */
 export interface ApiCreateAuthAccountBody {
+    /**
+     * The admin's Sui address, zero-padded if necessary.
+     */
     walletAddress: SuiAddress;
+    /**
+     * The signature of the serialized JSON data, from the admin's private key.
+     */
     signature: string;
+    /**
+     * The JSON string that was signed, containing the method and sub-account details.
+     */
     serializedJson: string;
 }
+/**
+ * The request body for obtaining or refreshing an access token. The user signs
+ * a "GetAccessToken" method message plus any relevant fields.
+ */
 export interface ApiGetAccessTokenBody {
+    /**
+     * The user's Sui address, zero-padded if needed.
+     */
     walletAddress: SuiAddress;
+    /**
+     * The signature over the JSON-serialized request data (nonce, date, etc.).
+     */
     signature: string;
+    /**
+     * The actual JSON string that was signed, e.g.:
+     * ```
+     * {
+     *   "date": 1234567890,
+     *   "nonce": 512,
+     *   "method": "GetAccessToken",
+     *   "value": {}
+     * }
+     * ```
+     */
     serializedJson: string;
 }
+/**
+ * The response returned when a user obtains or refreshes an access token,
+ * containing the token string, the HTTP header name (usually "Authorization"),
+ * and the token's expiration timestamp in milliseconds.
+ */
 export interface ApiGetAccessTokenResponse {
+    /**
+     * The newly issued access token to be used in `Authorization` headers.
+     */
     accessToken: string;
+    /**
+     * The header key that should contain `accessToken` (e.g., "Authorization").
+     */
     header: string;
+    /**
+     * The UNIX timestamp (milliseconds) after which the token is invalid.
+     */
     expirationTimestamp: Timestamp;
 }
 //# sourceMappingURL=authTypes.d.ts.map

package/dist/packages/auth/authTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/auth/authTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUpD,MAAM,WAAW,SAAS;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EACE;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACtB;QAAE,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACvB;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAMD,MAAM,WAAW,wBAAwB;IACxC,aAAa,EAAE,UAAU,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,aAAa,EAAE,UAAU,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,SAAS,CAAC;CAC/B"}
+{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/auth/authTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;;;;;;OAQG;IACH,CAAC,EACE;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACtB;QAAE,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACvB;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAMD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;OAUG;IACH,cAAc,EAAE,MAAM,CAAC;CACvB;AAMD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACzC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,mBAAmB,EAAE,SAAS,CAAC;CAC/B"}

package/dist/packages/coin/api/coinApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coinApi.d.ts","sourceRoot":"","sources":["../../../../src/packages/coin/api/coinApi.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,yBAAyB,EACzB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAY,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,UAAU,EAAkB,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,qBAAa,OAAO;IAKP,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAM5C,qBAAqB,WAAkB;QAC7C,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;QACnC,aAAa,EAAE,UAAU,CAAC;QAC1B,QAAQ,EAAE,QAAQ,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,aAAa,CAAC,EAAE,OAAO,CAAC;KACxB,KAAG,QAAQ,yBAAyB,CAAC,CAcpC;IAEK,sBAAsB,WAAkB;QAC9C,EAAE,EAAE,WAAW,CAAC;QAChB,aAAa,EAAE,UAAU,CAAC;QAC1B,SAAS,EAAE,QAAQ,EAAE,CAAC;QACtB,WAAW,EAAE,OAAO,EAAE,CAAC;QACvB,aAAa,CAAC,EAAE,OAAO,CAAC;KACxB,KAAG,QAAQ,yBAAyB,EAAE,CAAC,CA8BtC;IAGK,aAAa,WAAkB;QACrC,aAAa,EAAE,UAAU,CAAC;QAC1B,QAAQ,EAAE,QAAQ,CAAC;KAEnB,KAAG,QAAQ,UAAU,EAAE,CAAC,CAiCvB;IAMF,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAyE7B;CACF"}
+{"version":3,"file":"coinApi.d.ts","sourceRoot":"","sources":["../../../../src/packages/coin/api/coinApi.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,yBAAyB,EACzB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAY,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,UAAU,EAAkB,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,qBAAa,OAAO;IAKP,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAM5C,qBAAqB,WAAkB;QAC7C,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;QACnC,aAAa,EAAE,UAAU,CAAC;QAC1B,QAAQ,EAAE,QAAQ,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,aAAa,CAAC,EAAE,OAAO,CAAC;KACxB,KAAG,QAAQ,yBAAyB,CAAC,CAcpC;IAEK,sBAAsB,WAAkB;QAC9C,EAAE,EAAE,WAAW,CAAC;QAChB,aAAa,EAAE,UAAU,CAAC;QAC1B,SAAS,EAAE,QAAQ,EAAE,CAAC;QACtB,WAAW,EAAE,OAAO,EAAE,CAAC;QACvB,aAAa,CAAC,EAAE,OAAO,CAAC;KACxB,KAAG,QAAQ,yBAAyB,EAAE,CAAC,CA8BtC;IAGK,aAAa,WAAkB;QACrC,aAAa,EAAE,UAAU,CAAC;QAC1B,QAAQ,EAAE,QAAQ,CAAC;KAEnB,KAAG,QAAQ,UAAU,EAAE,CAAC,CAiCvB;IAMF,OAAO,CAAC,MAAM,CAAC,gBAAgB,CA+E7B;CACF"}

package/dist/packages/coin/api/coinApi.js

@@ -107,31 +107,39 @@ CoinApi.coinWithAmountTx = (inputs) => {
     const coinObjectIds = coinData.map((data) => data.coinObjectId);
     const mergedCoinObjectId = coinObjectIds[0];
     if (coinObjectIds.length > 1) {
-        // tx.mergeCoins(tx.object(mergedCoinObjectId), [
-        // 	...coinObjectIds.slice(1).map((coinId) => tx.object(coinId)),
-        // ]);
         // TODO: fix this (v1)
-        tx.add({
-            $kind: "MergeCoins",
-            MergeCoins: {
-                destination: tx.object(mergedCoinObjectId),
-                sources: [
-                    ...coinObjectIds
-                        .slice(1)
-                        .map((coinId) => tx.object(coinId)),
-                ],
-            },
-        });
+        if (isSponsoredTx) {
+            tx.add({
+                $kind: "MergeCoins",
+                MergeCoins: {
+                    destination: tx.object(mergedCoinObjectId),
+                    sources: [
+                        ...coinObjectIds
+                            .slice(1)
+                            .map((coinId) => tx.object(coinId)),
+                    ],
+                },
+            });
+        }
+        else {
+            tx.mergeCoins(tx.object(mergedCoinObjectId), [
+                ...coinObjectIds
+                    .slice(1)
+                    .map((coinId) => tx.object(coinId)),
+            ]);
+        }
     }
     // return tx.add({
     // 	kind: "SplitCoins",
     // 	coin: tx.object(mergedCoinObjectId),
     // 	amounts: [tx.pure(coinAmount)],
     // });
-    return transactionsApiHelpers_1.TransactionsApiHelpers.splitCoinTx({
-        tx,
-        coinId: mergedCoinObjectId,
-        amount: coinAmount,
-        coinType,
-    });
+    return isSponsoredTx
+        ? transactionsApiHelpers_1.TransactionsApiHelpers.splitCoinTx({
+            tx,
+            coinId: mergedCoinObjectId,
+            amount: coinAmount,
+            coinType,
+        })
+        : tx.splitCoins(mergedCoinObjectId, [coinAmount]);
 };