@mysten/kiosk 0.5.3 → 0.7.0

package/dist/types/kiosk.d.ts

@@ -1,4 +1,4 @@
-import { PaginatedObjectsResponse } from '@mysten/sui.js/client';
+import { PaginatedObjectsResponse, SuiObjectData, SuiObjectDataOptions } from '@mysten/sui.js/client';
 import { TransactionArgument } from '@mysten/sui.js/transactions';
 import { ObjectArgument } from '.';
 /** The Kiosk module. */
@@ -82,6 +82,10 @@ export type KioskItem = {
     isLocked: boolean;
     /** Optional listing */
     listing?: KioskListing;
+    /** The ID of the kiosk the item is placed in */
+    kioskId: string;
+    /** Optional Kiosk Data */
+    data?: SuiObjectData;
 };
 /**
  * Aggregated data from the Kiosk.
@@ -99,16 +103,41 @@ export type PagedKioskData = {
     hasNextPage: boolean;
 };
 export type FetchKioskOptions = {
+    /** Include the base kiosk object, which includes the profits, the owner and the base fields. */
     withKioskFields?: boolean;
+    /** Include the listing prices. */
     withListingPrices?: boolean;
+    /** Include the objects for the Items in the kiosk. Defaults to `display` only. */
+    withObjects?: boolean;
+    /** Pass the data options for the objects, when fetching, in case you want to query other details. */
+    objectOptions?: SuiObjectDataOptions;
 };
 export type OwnedKiosks = {
     kioskOwnerCaps: KioskOwnerCap[];
     kioskIds: string[];
 } & Omit<PaginatedObjectsResponse, 'data'>;
 export type KioskOwnerCap = {
+    isPersonal?: boolean;
     objectId: string;
     kioskId: string;
     digest: string;
     version: string;
 };
+export type PurchaseOptions = {
+    extraArgs?: Record<string, any>;
+};
+export type ItemId = {
+    itemType: string;
+    itemId: string;
+};
+export type ItemReference = {
+    itemType: string;
+    item: ObjectArgument;
+};
+export type ItemValue = {
+    itemType: string;
+    item: TransactionArgument;
+};
+export type Price = {
+    price: string | bigint;
+};

package/dist/types/transfer-policy.d.ts

@@ -1,14 +1,26 @@
-import { ObjectOwner } from '@mysten/sui.js/client';
+import { type ObjectOwner } from '@mysten/sui.js/client';
+import { TransactionArgument, type TransactionBlock } from '@mysten/sui.js/transactions';
+import { ObjectArgument } from '.';
 /** The Transfer Policy module. */
 export declare const TRANSFER_POLICY_MODULE = "0x2::transfer_policy";
 /** Name of the event emitted when a TransferPolicy for T is created. */
 export declare const TRANSFER_POLICY_CREATED_EVENT: string;
 /** The Transfer Policy Type */
 export declare const TRANSFER_POLICY_TYPE: string;
+/** The Transfer Policy Cap Type */
+export declare const TRANSFER_POLICY_CAP_TYPE: string;
 /** The Kiosk Lock Rule */
 export declare const KIOSK_LOCK_RULE = "kiosk_lock_rule::Rule";
 /** The Royalty rule */
 export declare const ROYALTY_RULE = "royalty_rule::Rule";
+/**
+ * The Transfer Policy Cap in a consumable way.
+ */
+export type TransferPolicyCap = {
+    policyId: string;
+    policyCapId: string;
+    type: string;
+};
 /** The `TransferPolicy` object */
 export type TransferPolicy = {
     id: string;
@@ -21,3 +33,17 @@ export type TransferPolicy = {
 export type TransferPolicyCreated = {
     id: string;
 };
+export type RuleResolvingParams = {
+    transactionBlock: TransactionBlock;
+    itemType: string;
+    itemId: string;
+    price: string;
+    policyId: ObjectArgument;
+    sellerKiosk: ObjectArgument;
+    kiosk: ObjectArgument;
+    kioskCap: ObjectArgument;
+    transferRequest: TransactionArgument;
+    purchasedItem: TransactionArgument;
+    packageId: string;
+    extraArgs: Record<string, any>;
+};

package/dist/utils.d.ts

@@ -1,44 +1,53 @@
 import { SharedObjectRef } from '@mysten/sui.js/bcs';
-import { SuiObjectRef, SuiObjectResponse } from '@mysten/sui.js/client';
-import { TransactionBlock, TransactionArgument } from '@mysten/sui.js/transactions';
-import { type DynamicFieldInfo } from '@mysten/sui.js/client';
-import { Kiosk, KioskData, KioskListing, RulesEnvironmentParam } from './types';
-import { SuiClient, PaginationArguments } from '@mysten/sui.js/client';
-export declare const rulesPackageAddresses: {
-    mainnet: string;
-    testnet: string;
-    devnet: string;
-    custom: null;
-};
+import { PaginationArguments, SuiClient, SuiObjectData, SuiObjectDataFilter, SuiObjectDataOptions, SuiObjectRef, SuiObjectResponse, type DynamicFieldInfo } from '@mysten/sui.js/client';
+import { TransactionArgument, TransactionBlock } from '@mysten/sui.js/transactions';
+import { Kiosk, KioskData, KioskListing, TransferPolicyCap } from './types';
 /**
  * Convert any valid input into a TransactionArgument.
  *
- * @param tx The transaction to use for creating the argument.
+ * @param txb The Transaction Block
  * @param arg The argument to convert.
  * @returns The converted TransactionArgument.
  */
-export declare function objArg(tx: TransactionBlock, arg: string | SharedObjectRef | SuiObjectRef | TransactionArgument): TransactionArgument;
+export declare function objArg(txb: TransactionBlock, arg: string | SharedObjectRef | SuiObjectRef | TransactionArgument): TransactionArgument;
 export declare function getKioskObject(client: SuiClient, id: string): Promise<Kiosk>;
-export declare function extractKioskData(data: DynamicFieldInfo[], listings: KioskListing[], lockedItemIds: string[]): KioskData;
+export declare function extractKioskData(data: DynamicFieldInfo[], listings: KioskListing[], lockedItemIds: string[], kioskId: string): KioskData;
 export declare function getTypeWithoutPackageAddress(type: string): string;
 /**
  * A helper that attaches the listing prices to kiosk listings.
  */
 export declare function attachListingsAndPrices(kioskData: KioskData, listings: KioskListing[], listingObjects: SuiObjectResponse[]): void;
 /**
- * A Helper to attach locked state to items in Kiosk Data.
+ * A helper that attaches the listing prices to kiosk listings.
  */
-export declare function attachLockedItems(kioskData: KioskData, lockedItemIds: string[]): void;
+export declare function attachObjects(kioskData: KioskData, objects: SuiObjectData[]): void;
 /**
- * A helper to get a rule's environment address.
+ * A Helper to attach locked state to items in Kiosk Data.
  */
-export declare function getRulePackageAddress(environment: RulesEnvironmentParam): string;
+export declare function attachLockedItems(kioskData: KioskData, lockedItemIds: string[]): void;
 /**
  * A helper to fetch all DF pages.
  * We need that to fetch the kiosk DFs consistently, until we have
  * RPC calls that allow filtering of Type / batch fetching of spec
  */
 export declare function getAllDynamicFields(client: SuiClient, parentId: string, pagination: PaginationArguments<string>): Promise<DynamicFieldInfo[]>;
+/**
+ * A helper to fetch all objects that works with pagination.
+ * It will fetch all objects in the array, and limit it to 50/request.
+ * Requests are sent using `Promise.all`.
+ */
+export declare function getAllObjects(client: SuiClient, ids: string[], options: SuiObjectDataOptions, limit?: number): Promise<SuiObjectResponse[]>;
+/**
+ * A helper to return all owned objects, with an optional filter.
+ * It parses all the pages and returns the data.
+ */
+export declare function getAllOwnedObjects({ client, owner, filter, limit, options, }: {
+    client: SuiClient;
+    owner: string;
+    filter?: SuiObjectDataFilter;
+    options?: SuiObjectDataOptions;
+    limit?: number;
+}): Promise<SuiObjectResponse[]>;
 /**
  * Converts a number to basis points.
  * Supports up to 2 decimal points.
@@ -46,3 +55,8 @@ export declare function getAllDynamicFields(client: SuiClient, parentId: string,
  * @param percentage A percentage amount in the range [0, 100] including decimals.
  */
 export declare function percentageToBasisPoints(percentage: number): number;
+/**
+ * A helper to parse a transfer policy Cap into a usable object.
+ */
+export declare function parseTransferPolicyCapObject(item: SuiObjectResponse): TransferPolicyCap | undefined;
+export declare function getNormalizedRuleType(rule: string): string;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@mysten/kiosk",
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui Kiosk library",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -24,11 +24,17 @@
     }
   },
   "dependencies": {
-    "@mysten/sui.js": "0.41.2"
+    "@mysten/sui.js": "0.42.0"
   },
   "devDependencies": {
+    "cross-env": "^7.0.3",
+    "tmp": "^0.2.1",
+    "ts-retry-promise": "^0.7.0",
     "tsup": "^7.1.0",
-    "typescript": "^5.1.6"
+    "typescript": "^5.1.6",
+    "vite": "^4.4.4",
+    "vitest": "^0.33.0",
+    "wait-on": "^7.0.1"
   },
   "scripts": {
     "build": "pnpm build:types && pnpm build:tsup",
@@ -41,6 +47,8 @@
     "eslint:check": "eslint --max-warnings=0 .",
     "eslint:fix": "pnpm run eslint:check --fix",
     "lint": "pnpm run eslint:check && pnpm run prettier:check",
-    "lint:fix": "pnpm run eslint:fix && pnpm run prettier:fix"
+    "lint:fix": "pnpm run eslint:fix && pnpm run prettier:fix",
+    "test:e2e": "wait-on http://127.0.0.1:9123 -l --timeout 120000 && vitest run e2e",
+    "prepare:e2e": "cargo build --bin sui-test-validator --bin sui --profile dev && cross-env RUST_LOG=info,sui=error,anemo_tower=warn,consensus=off cargo run --bin sui-test-validator"
   }
 }

package/src/bcs.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { bcs } from '@mysten/sui.js/bcs';
+
 import {
 	KIOSK_PURCHASE_CAP,
 	KIOSK_TYPE,

package/src/client/kiosk-client.ts

@@ -0,0 +1,156 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { type SuiClient } from '@mysten/sui.js/client';
+
+import {
+	FLOOR_PRICE_RULE_ADDRESS,
+	getBaseRules,
+	KIOSK_LOCK_RULE_ADDRESS,
+	PERSONAL_KIOSK_RULE_ADDRESS,
+	ROYALTY_RULE_ADDRESS,
+	rules,
+	type BaseRulePackageIds,
+	type TransferPolicyRule,
+} from '../constants';
+import { fetchKiosk, getOwnedKiosks } from '../query/kiosk';
+import {
+	queryOwnedTransferPolicies,
+	queryTransferPolicy,
+	queryTransferPolicyCapsByType,
+} from '../query/transfer-policy';
+import {
+	Network,
+	type FetchKioskOptions,
+	type KioskClientOptions,
+	type KioskData,
+	type OwnedKiosks,
+} from '../types';
+
+/**
+ * A Client that allows you to interact with kiosk.
+ * Offers utilities to query kiosk, craft transactions to edit your own kiosk,
+ * purchase, manage transfer policies, create new kiosks etc.
+ * If you pass packageIds, all functionality will be managed using these packages.
+ */
+export class KioskClient {
+	client: SuiClient;
+	network: Network;
+	rules: TransferPolicyRule[];
+	packageIds?: BaseRulePackageIds;
+
+	constructor(options: KioskClientOptions) {
+		this.client = options.client;
+		this.network = options.network;
+		this.rules = rules; // add all the default rules.
+		this.packageIds = options.packageIds;
+
+		// Add the custom Package Ids too on the rule list.
+		// Only adds the rules that are passed in the packageId object.
+		if (options.packageIds) this.rules.push(...getBaseRules(options.packageIds));
+	}
+
+	/// Querying
+
+	/**
+	 * Get an addresses's owned kiosks.
+	 * @param address The address for which we want to retrieve the kiosks.
+	 * @returns An Object containing all the `kioskOwnerCap` objects as well as the kioskIds.
+	 */
+	async getOwnedKiosks({ address }: { address: string }): Promise<OwnedKiosks> {
+		const personalPackageId =
+			this.packageIds?.personalKioskRulePackageId || PERSONAL_KIOSK_RULE_ADDRESS[this.network];
+
+		return getOwnedKiosks(this.client, address, {
+			personalKioskType: personalPackageId
+				? `${personalPackageId}::personal_kiosk::PersonalKioskCap`
+				: '',
+		});
+	}
+
+	/**
+	 * Fetches the kiosk contents.
+	 * @param kioskId The ID of the kiosk to fetch.
+	 * @param options Optioal
+	 * @returns
+	 */
+	async getKiosk({ id, options }: { id: string; options?: FetchKioskOptions }): Promise<KioskData> {
+		return (
+			await fetchKiosk(
+				this.client,
+				id,
+				{
+					limit: 1000,
+				},
+				options || {},
+			)
+		).data;
+	}
+
+	/**
+	 * Query the Transfer Policy(ies) for type `T`.
+	 * @param type The Type we're querying for (E.g `0xMyAddress::hero::Hero`)
+	 */
+	async getTransferPolicies({ type }: { type: string }) {
+		return queryTransferPolicy(this.client, type);
+	}
+
+	/**
+	 * Query all the owned transfer policies for an address.
+	 * Returns `TransferPolicyCap` which uncludes `policyId, policyCapId, type`.
+	 * @param address The address we're searching the owned transfer policies for.
+	 */
+	async getOwnedTransferPolicies({ address }: { address: string }) {
+		return queryOwnedTransferPolicies(this.client, address);
+	}
+
+	/**
+	 * Query the Transfer Policy Cap for type `T`, owned by `address`
+	 * @param type The Type `T` for the object
+	 * @param address The address that owns the cap.
+	 */
+	async getOwnedTransferPoliciesByType({ type, address }: { type: string; address: string }) {
+		return queryTransferPolicyCapsByType(this.client, address, type);
+	}
+
+	// Someone would just have to create a `kiosk-client.ts` file in their project, initialize a KioskClient
+	// and call the `addRuleResolver` function. Each rule has a `resolve` function.
+	// The resolve function is automatically called on `purchaseAndResolve` function call.
+	addRuleResolver(rule: TransferPolicyRule) {
+		if (this.rules.find((x) => x.rule === rule.rule))
+			throw new Error(`Rule ${rule.rule} resolver already exists.`);
+		this.rules.push(rule);
+	}
+
+	/**
+	 * A convenient helper to get the packageIds for our supported ruleset,
+	 * based on `kioskClient` configuration.
+	 */
+	getRulePackageId(
+		rule:
+			| 'kioskLockRulePackageId'
+			| 'royaltyRulePackageId'
+			| 'personalKioskRulePackageId'
+			| 'floorPriceRulePackageId',
+	) {
+		const rules = this.packageIds || {};
+		const network = this.network;
+
+		/// Check existence of rule based on network and throw an error if it's not found.
+		/// We always have a fallback for testnet or mainnet.
+		if (!rules[rule] && network !== Network.MAINNET && network !== Network.TESTNET) {
+			throw new Error(`Missing packageId for rule ${rule}`);
+		}
+
+		switch (rule) {
+			case 'kioskLockRulePackageId':
+				return rules[rule] || KIOSK_LOCK_RULE_ADDRESS[network];
+			case 'royaltyRulePackageId':
+				return rules[rule] || ROYALTY_RULE_ADDRESS[network];
+			case 'personalKioskRulePackageId':
+				return rules[rule] || PERSONAL_KIOSK_RULE_ADDRESS[network];
+			case 'floorPriceRulePackageId':
+				return rules[rule] || FLOOR_PRICE_RULE_ADDRESS[network];
+		}
+	}
+}