@ar.io/sdk 3.5.0-alpha.1 → 3.5.0-alpha.2

package/lib/esm/types/token.test.js

@@ -0,0 +1,81 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { ARIOToken, mARIOToken } from './token.js';
+describe('ARIOToken', () => {
+    it('should throw an error on invalid input', () => {
+        assert.throws(() => new ARIOToken(-1));
+    });
+    it('should round at 6 decimal places', () => {
+        const token = new ARIOToken(1.123456789);
+        assert.strictEqual(token.valueOf(), 1.123457);
+    });
+    it('should convert to mARIOToken', () => {
+        const token = new ARIOToken(1);
+        const mToken = token.toMARIO();
+        assert.strictEqual(mToken.valueOf(), 1000000);
+    });
+    it('should print as a string', () => {
+        const token = new ARIOToken(1);
+        assert.strictEqual(`${token}`, '1');
+    });
+});
+describe('mARIOToken', () => {
+    it('should multiply by a number', () => {
+        const token = new mARIOToken(1);
+        const result = token.multiply(2);
+        assert.strictEqual(result.valueOf(), 2);
+    });
+    it('should multiply by another mARIOToken', () => {
+        const token = new mARIOToken(1);
+        const result = token.multiply(new mARIOToken(2));
+        assert.strictEqual(result.valueOf(), 2);
+    });
+    it('should divide by a number', () => {
+        const token = new mARIOToken(2);
+        const result = token.divide(2);
+        assert.strictEqual(result.valueOf(), 1);
+    });
+    it('should divide by another mARIOToken', () => {
+        const token = new mARIOToken(2);
+        const result = token.divide(new mARIOToken(2));
+        assert.strictEqual(result.valueOf(), 1);
+    });
+    it('should throw an error on division by zero', () => {
+        const token = new mARIOToken(2);
+        assert.throws(() => token.divide(0));
+    });
+    it('should round down on multiplication of a number', () => {
+        const token = new mARIOToken(1);
+        const result = token.multiply(1.5);
+        assert.strictEqual(result.valueOf(), 1);
+    });
+    it('should round down on division with a number', () => {
+        const token = new mARIOToken(2);
+        const result = token.divide(3);
+        assert.strictEqual(result.valueOf(), 0);
+    });
+    it('should round down on division with another mARIOToken', () => {
+        const token = new mARIOToken(2);
+        const result = token.divide(new mARIOToken(3));
+        assert.strictEqual(result.valueOf(), 0);
+    });
+    it('should add', () => {
+        const token = new mARIOToken(1);
+        const result = token.plus(new mARIOToken(1));
+        assert.strictEqual(result.valueOf(), 2);
+    });
+    it('should subtract', () => {
+        const token = new mARIOToken(2);
+        const result = token.minus(new mARIOToken(1));
+        assert.strictEqual(result.valueOf(), 1);
+    });
+    it('should convert to ARIO', () => {
+        const token = new mARIOToken(1000000);
+        const result = token.toARIO();
+        assert.strictEqual(result.valueOf(), 1);
+    });
+    it('should print as a string', () => {
+        const token = new mARIOToken(1);
+        assert.strictEqual(`${token}`, '1');
+    });
+});

package/lib/esm/utils/ant.js

@@ -0,0 +1,38 @@
+/**
+ * Sorts ANT records by priority and then lexicographically.
+ *
+ * Note: javascript guarantees that the order of objects in an object is persistent. Still, adding index to each record is useful for enforcing against undername limits.
+ *
+ * Reference: https://github.com/ar-io/ar-io-node/blob/e0a9ec56559cad1b3e35d668563871afb8649913/docs/madr/003-arns-undername-limits.md
+ *
+ * @param antRecords - The ANT records to sort.
+ */
+export const sortANTRecords = (antRecords) => {
+    const sortedEntries = Object.entries(antRecords).sort(([a, aRecord], [b, bRecord]) => {
+        // '@' is the root name and should be resolved first
+        if (a === '@') {
+            return -1;
+        }
+        if (b === '@') {
+            return 1;
+        }
+        // if a record has a priority, it should be resolved before any other record without a priority
+        if ('priority' in aRecord && !('priority' in bRecord)) {
+            return -1;
+        }
+        if (!('priority' in aRecord) && 'priority' in bRecord) {
+            return 1;
+        }
+        // if both records have a priority, sort by priority and fallback to lexicographic sorting
+        if (aRecord.priority !== undefined && bRecord.priority !== undefined) {
+            if (aRecord.priority === bRecord.priority) {
+                return a.localeCompare(b);
+            }
+            return aRecord.priority - bRecord.priority;
+        }
+        // all other records are sorted lexicographically
+        return a.localeCompare(b);
+    });
+    // now that they are sorted, add the index to each record - this is their position in the sorted list and is used to enforce undername limits
+    return Object.fromEntries(sortedEntries.map(([a, aRecord], index) => [a, { ...aRecord, index }]));
+};

package/lib/esm/utils/ant.test.js

@@ -0,0 +1,67 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { sortANTRecords } from './ant.js';
+describe('sortANTRecordsByPriority', () => {
+    it('should sort records by priority and then lexicographically', () => {
+        const records = {
+            undername1: { priority: 1, transactionId: 'test', ttlSeconds: 1 },
+            undername2: { priority: 2, transactionId: 'test', ttlSeconds: 1 },
+            undername3: { priority: 3, transactionId: 'test', ttlSeconds: 1 }, // colliding priorities default to lexicographic sorting
+            undername4: { priority: 3, transactionId: 'test', ttlSeconds: 1 },
+            undername5: { priority: 100, transactionId: 'test', ttlSeconds: 1 }, // priority does not represent the index or position of the record, just the order of resolution relative to other records
+            noPriority: { transactionId: 'test', ttlSeconds: 1 },
+            '@': { transactionId: 'test', ttlSeconds: 1 }, // always first, even if no priority
+        };
+        const sorted = sortANTRecords(records);
+        assert.deepStrictEqual(sorted, {
+            '@': { transactionId: 'test', ttlSeconds: 1, index: 0 }, // always first, even if no priority
+            undername1: {
+                priority: 1,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 1,
+            },
+            undername2: {
+                priority: 2,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 2,
+            },
+            undername3: {
+                priority: 3,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 3,
+            },
+            undername4: {
+                priority: 3,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 4,
+            },
+            undername5: {
+                priority: 100,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 5,
+            },
+            noPriority: { transactionId: 'test', ttlSeconds: 1, index: 6 },
+        });
+    });
+    it('should always return @ as the first record, regardless of priority', () => {
+        const records = {
+            '@': { priority: 5, transactionId: 'test', ttlSeconds: 1 }, //  priorities set on '@' are ignored, they are always first
+            undername1: { priority: 2, transactionId: 'test', ttlSeconds: 1 },
+        };
+        const sorted = sortANTRecords(records);
+        assert.deepStrictEqual(sorted, {
+            '@': { priority: 5, transactionId: 'test', ttlSeconds: 1, index: 0 },
+            undername1: {
+                priority: 2,
+                transactionId: 'test',
+                ttlSeconds: 1,
+                index: 1,
+            },
+        });
+    });
+});

package/lib/esm/utils/b64.test.js

@@ -0,0 +1,70 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { fromB64Url, getRandomText, toB64Url } from './base64.js';
+describe('b64utils', () => {
+    it('should convert various strings to base64url and back', () => {
+        const testStrings = [
+            'Hello, World!',
+            'Test123!@#',
+            'Base64URLEncoding',
+            'Special_Chars+/',
+            '',
+            'A',
+            '1234567890',
+        ];
+        for (const str of testStrings) {
+            const encoded = toB64Url(Buffer.from(str));
+            const decoded = fromB64Url(encoded);
+            assert.deepStrictEqual(decoded, Buffer.from(str), `Failed for string: ${str}`);
+        }
+    });
+    it('should convert various buffers to base64url and back', () => {
+        const testBuffers = [
+            Buffer.from('Hello, World!'),
+            Buffer.from([0, 1, 2, 3, 4, 5]),
+            Buffer.from('Test123!@#'),
+            Buffer.from('Base64URLEncoding'),
+            Buffer.from('Special_Chars+/'),
+            Buffer.alloc(0),
+            Buffer.from('A'),
+            Buffer.from('1234567890'),
+        ];
+        for (const buf of testBuffers) {
+            const encoded = toB64Url(buf);
+            const decoded = fromB64Url(encoded);
+            assert.deepStrictEqual(decoded, buf, `Failed for buffer: ${buf.toString()}`);
+        }
+    });
+    it('should handle edge cases for base64url conversion', () => {
+        const edgeCases = [
+            '',
+            'A',
+            'AA',
+            'AAA',
+            '====',
+            '===',
+            '==',
+            '=',
+            'A===',
+            'AA==',
+            'AAA=',
+        ];
+        for (const testCase of edgeCases) {
+            const encoded = toB64Url(Buffer.from(testCase));
+            const decoded = Buffer.from(fromB64Url(encoded)).toString();
+            assert.strictEqual(decoded, testCase, `Failed for edge case: ${testCase}`);
+        }
+    });
+    it('should generate random text', () => {
+        const randomText = getRandomText();
+        const randomText2 = getRandomText();
+        assert.strictEqual(randomText.length, 32);
+        assert.strictEqual(randomText2.length, 32);
+        assert.notStrictEqual(randomText, randomText2);
+        const smallRandomText = getRandomText(16);
+        const smallRandomText2 = getRandomText(16);
+        assert.strictEqual(smallRandomText.length, 16);
+        assert.strictEqual(smallRandomText2.length, 16);
+        assert.notStrictEqual(smallRandomText, smallRandomText2);
+    });
+});

package/lib/esm/utils/index.js

@@ -19,3 +19,4 @@ export * from './base64.js';
 export * from './json.js';
 export * from './processes.js';
 export * from './schema.js';
+export * from './ant.js';

package/lib/esm/utils/utils.test.js

@@ -0,0 +1,104 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { pruneTags } from './arweave.js';
+import { errorMessageFromOutput } from './index.js';
+describe('pruneTags', () => {
+    it('should remove tags with undefined values', () => {
+        const tags = [
+            { name: 'Tag1', value: 'value1' },
+            { name: 'Tag2', value: undefined },
+            { name: 'Tag3', value: 'value3' },
+            { name: 'Tag4', value: undefined },
+        ];
+        const prunedTags = pruneTags(tags);
+        assert.deepEqual(prunedTags, [
+            { name: 'Tag1', value: 'value1' },
+            { name: 'Tag3', value: 'value3' },
+        ]);
+    });
+    it('should return empty array when all tags have undefined values', () => {
+        const tags = [
+            { name: 'Tag1', value: undefined },
+            { name: 'Tag2', value: undefined },
+        ];
+        const prunedTags = pruneTags(tags);
+        assert.deepEqual(prunedTags, []);
+    });
+    it('should return same array when no tags have undefined values', () => {
+        const tags = [
+            { name: 'Tag1', value: 'value1' },
+            { name: 'Tag2', value: 'value2' },
+        ];
+        const prunedTags = pruneTags(tags);
+        assert.deepEqual(prunedTags, tags);
+    });
+    it('should return empty array with no tags', () => {
+        const tags = [];
+        const prunedTags = pruneTags(tags);
+        assert.deepEqual(prunedTags, []);
+    });
+});
+describe('errorMessageFromOutput', () => {
+    it('should return error message from Error field', () => {
+        const output = {
+            Error: 'Error message',
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Error message');
+    });
+    it('should return error message from Error tag', () => {
+        const output = {
+            Messages: [
+                {
+                    Tags: [{ name: 'Error', value: 'Error message' }],
+                },
+            ],
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Error message');
+    });
+    it('should return error message from Error tag if Error field is undefined', () => {
+        const output = {
+            Messages: [
+                {
+                    Tags: [{ name: 'Error', value: 'Error message' }],
+                },
+            ],
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Error message');
+    });
+    it('should return undefined if no error message is present', () => {
+        const output = {
+            Messages: [
+                {
+                    Tags: [{ name: 'Tag1', value: 'value1' }],
+                },
+            ],
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, undefined);
+    });
+    it('should return error message with line number', () => {
+        const output = {
+            Error: '[string "aos"]:123: Error message',
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Error message (line 123)');
+    });
+    it('should return error message with line number and remove unicode', () => {
+        const output = {
+            Error: '[string "aos"]:123: Error message\u001b[0m',
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Error message (line 123)');
+    });
+    const knownErrorMessages = '\u001b[31mError\u001b[90m handling message with Action = Register\u001b[0m\n\u001b[32m[string ".handlers"]:723: [string "aos"]:128: Already registered\u001b[0m\n\n\u001b[90mstack traceback:\n\t[string ".process"]:871: in function \'.process.handle\'\u001b[0m\n\n\u001b[31merror:\n\u001b[0m[string ".handlers"]:723: [string "aos"]:128: Already registered';
+    it('should display a clean error for a known error message', () => {
+        const output = {
+            Error: knownErrorMessages,
+        };
+        const errorMessage = errorMessageFromOutput(output);
+        assert.equal(errorMessage, 'Already registered (line 128)');
+    });
+});

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '3.5.0-alpha.1';
+export const version = '3.5.0-alpha.2';

package/lib/types/types/ant.d.ts

@@ -34,23 +34,34 @@ export declare const AntKeywordsSchema: z.ZodArray<z.ZodString, "many">;
 export declare const AntRecordSchema: z.ZodObject<{
     transactionId: z.ZodEffects<z.ZodString, string, string>;
     ttlSeconds: z.ZodNumber;
+    priority: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
     ttlSeconds: number;
+    priority?: number | undefined;
 }, {
     transactionId: string;
     ttlSeconds: number;
+    priority?: number | undefined;
 }>;
 export type AoANTRecord = z.infer<typeof AntRecordSchema>;
+export type ANTRecords = Record<string, AoANTRecord>;
+export type SortedANTRecord = AoANTRecord & {
+    index: number;
+};
+export type SortedANTRecords = Record<string, SortedANTRecord>;
 export declare const AntRecordsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     transactionId: z.ZodEffects<z.ZodString, string, string>;
     ttlSeconds: z.ZodNumber;
+    priority: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
     ttlSeconds: number;
+    priority?: number | undefined;
 }, {
     transactionId: string;
     ttlSeconds: number;
+    priority?: number | undefined;
 }>>;
 export declare const AntControllersSchema: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
 export declare const AntBalancesSchema: z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodNumber>;
@@ -65,12 +76,15 @@ export declare const AntStateSchema: z.ZodObject<{
     Records: z.ZodRecord<z.ZodString, z.ZodObject<{
         transactionId: z.ZodEffects<z.ZodString, string, string>;
         ttlSeconds: z.ZodNumber;
+        priority: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         transactionId: string;
         ttlSeconds: number;
+        priority?: number | undefined;
     }, {
         transactionId: string;
         ttlSeconds: number;
+        priority?: number | undefined;
     }>>;
     Balances: z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodNumber>;
     Logo: z.ZodEffects<z.ZodString, string, string>;
@@ -87,6 +101,7 @@ export declare const AntStateSchema: z.ZodObject<{
     Records: Record<string, {
         transactionId: string;
         ttlSeconds: number;
+        priority?: number | undefined;
     }>;
     Balances: Record<string, number>;
     Logo: string;
@@ -103,6 +118,7 @@ export declare const AntStateSchema: z.ZodObject<{
     Records: Record<string, {
         transactionId: string;
         ttlSeconds: number;
+        priority?: number | undefined;
     }>;
     Balances: Record<string, number>;
     Logo: string;
@@ -167,7 +183,7 @@ export interface AoANTRead {
     getRecord({ undername }: {
         undername: string;
     }, opts?: AntReadOptions): Promise<AoANTRecord | undefined>;
-    getRecords(opts?: AntReadOptions): Promise<Record<string, AoANTRecord>>;
+    getRecords(opts?: AntReadOptions): Promise<ANTRecords>;
     getOwner(opts?: AntReadOptions): Promise<WalletAddress>;
     getControllers(): Promise<WalletAddress[]>;
     getTicker(opts?: AntReadOptions): Promise<string>;
@@ -191,6 +207,7 @@ export interface AoANTWrite extends AoANTRead {
     }>;
     /** @deprecated Use setUndernameRecord instead for undernames, and setBaseNameRecord instead for the top level name (e.g. "@") */
     setRecord: AoWriteAction<AoANTSetUndernameRecordParams>;
+    /** @deprecated Use removeUndernameRecord instead for undernames */
     removeRecord: AoWriteAction<{
         undername: string;
     }>;
@@ -237,6 +254,7 @@ export interface AoANTWrite extends AoANTRead {
 export type AoANTSetBaseNameRecordParams = {
     transactionId: string;
     ttlSeconds: number;
+    priority?: number;
 };
 export type AoANTSetUndernameRecordParams = AoANTSetBaseNameRecordParams & {
     undername: string;

package/lib/types/types/ant.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/types/token.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/utils/ant.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ANTRecords, SortedANTRecords } from '../types/ant.js';
+/**
+ * Sorts ANT records by priority and then lexicographically.
+ *
+ * Note: javascript guarantees that the order of objects in an object is persistent. Still, adding index to each record is useful for enforcing against undername limits.
+ *
+ * Reference: https://github.com/ar-io/ar-io-node/blob/e0a9ec56559cad1b3e35d668563871afb8649913/docs/madr/003-arns-undername-limits.md
+ *
+ * @param antRecords - The ANT records to sort.
+ */
+export declare const sortANTRecords: (antRecords: ANTRecords) => SortedANTRecords;

package/lib/types/utils/ant.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/utils/b64.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/utils/index.d.ts

@@ -19,3 +19,4 @@ export * from './base64.js';
 export * from './json.js';
 export * from './processes.js';
 export * from './schema.js';
+export * from './ant.js';

package/lib/types/utils/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "3.4.1";
+export declare const version = "3.5.0-alpha.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.5.0-alpha.1",
+  "version": "3.5.0-alpha.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -72,7 +72,7 @@
     "test:cjs": "yarn build:cjs && yarn link && cd ./tests/e2e/cjs && yarn && yarn test",
     "test:esm": "yarn build:esm && yarn link && cd ./tests/e2e/esm && yarn && yarn test",
     "test:web": "yarn build:esm && yarn link && cd ./tests/e2e/web && yarn && yarn test",
-    "test:unit": "NODE_OPTIONS=\"--import=./register.mjs\" node --test tests/unit/**.test.ts",
+    "test:unit": "NODE_OPTIONS=\"--import=./register.mjs\" node --test src/**/**.test.ts",
     "test:link": "yarn build && yarn link",
     "test:e2e": "yarn test:cjs && yarn test:esm && yarn test:web",
     "prepare": "husky install",