@mysten/kiosk 0.5.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mysten/kiosk
 
+## 0.7.0
+
+### Minor Changes
+
+- 5ee8c24f1: Introduces BREAKING CHANGES. Migration guide and explanation: https://sui-typescript-docs.vercel.app/kiosk/from-v1
+
+## 0.6.0
+
+### Minor Changes
+
+- fd8589806: Remove uses of deprecated imports from @mysten/sui.js
+
+### Patch Changes
+
+- Updated dependencies [fd8589806]
+  - @mysten/sui.js@0.42.0
+
 ## 0.5.3
 
 ### Patch Changes

package/README.md

@@ -1,293 +1,8 @@
 # Kiosk SDK
 
-> **This package is still in active development. Use at your own risk**.
-
 This Kiosk SDK library provides different utilities to interact/create/manage a
 [Kiosk](https://github.com/MystenLabs/sui/tree/main/kiosk).
 
-## Installation
-
-To install, add `@mysten/kiosk` package to your project
-
-```
-npm i @mysten/kiosk
-```
-
-You can also use your preferred package manager, such as yarn or pnpm.
-
-## Examples
-
-Here are some indicative examples on how to use the kiosk SDK.
-
-<details>
-<summary>Find the kiosks owned by an address</summary>
-
-```typescript
-import { getOwnedKiosks } from '@mysten/kiosk';
-import { SuiClient } from '@mysten/sui.js/client';
-
-const client = new SuiClient(
-  url: 'https://fullnode.testnet.sui.io:443',
-);
-
-
-// You could use these to fetch the contents for each kiosk, or use the `kioskOwnerCap` data for other actions.
-const getUserKiosks = async () => {
-	const address = `0xAddress`;
-	const { data } = await getOwnedKiosks(client, address);
-	console.log(data); // kioskOwnerCaps:[], kioskIds: []
-};
-```
-
-</details>
-
-<details>
-<summary>Getting the listings & items by the kiosk's ID</summary>
-
-```typescript
-import { fetchKiosk } from '@mysten/kiosk';
-import { SuiClient } from '@mysten/sui.js/client';
-
-const client = new SuiClient(
-	url: 'https://fullnode.testnet.sui.io:443',
-);
-
-const getKiosk = async () => {
-	const kioskAddress = `0xSomeKioskAddress`;
-
-	const { data } = await fetchKiosk(
-		client,
-		kioskAddress,
-		{}, // empty pagination, currently disabled.
-		{ withListingPrices: true, withKioskFields: true },
-	);
-
-	console.log(data); // { items: [],  itemIds: [],  listingIds: [], kiosk: {...} }
-};
-```
-
-</details>
-
-<details>
-<summary>Purchasing an item (currently supports royalty rule, kiosk_lock_rule, no rules, (combination works too))</summary>
-
-```typescript
-import { queryTransferPolicy, purchaseAndResolvePolicies, place, testnetEnvironment } from '@mysten/kiosk';
-import { SuiClient } from '@mysten/sui.js/client';
-
-const client = new SuiClient(
-  url: 'https://fullnode.testnet.sui.io:443',
-);
-
- // the kiosk we're purchasing from
-const kioskId = `0xSomeKioskAddress`;
-// a sample item retrieved from `fetchKiosk` function (or hard-coded)
-const item = {
-  isLocked: false,
-  objectId: "0xb892d61a9992a10c9453efcdbd14ca9720d7dc1000a2048224209c9e544ed223"
-  type: "0x52852c4ba80040395b259c641e70b702426a58990ff73cecf5afd31954429090::test::TestItem",
-  listing: {
-    isExclusive: false,
-    listingId: "0x368b512ff2514dbea814f26ec9a3d41198c00e8ed778099961e9ed22a9f0032b",
-    price: "20000000000" // in MIST
-  }
-}
-const ownedKiosk = `0xMyKioskAddress`;
-const ownedKioskCap = `0xMyKioskOwnerCap`;
-
-const purchaseItem = async (item, kioskId) => {
-
-  // fetch the policy of the item (could be an array, if there's more than one transfer policy)
-  const policies = await queryTransferPolicy(client, item.type);
-  // selecting the first one for simplicity.
-  const policyId = policy[0]?.id;
-  // initialize tx block.
-  const tx = new TransactionBlock();
-
-  // Both are required if you there is a `kiosk_lock_rule`.
-  // Optional otherwise. Function will throw an error if there's a kiosk_lock_rule and these are missing.
-  const extraParams = {
-    ownedKiosk,
-    ownedKioskCap
-  }
-  // Define the environment.
-  // To use a custom package address for rules, you could call:
-  // const environment = customEnvironment('<PackageAddress>');
-  const environment = testnetEnvironment;
-
-  // Extra params. Optional, but required if the user tries to resolve a `kiosk_lock_rule`.
-  // Purchases the item. Supports `kiosk_lock_rule`, `royalty_rule` (accepts combination too).
-  const result = purchaseAndResolvePolicies(tx, item.type, item.listing.price, kioskId, item.objectId, policy[0], environment, extraParams);
-
-  // result = {item: <the_purchased_item>, canTransfer: true/false // depending on whether there was a kiosk lock rule }
-  // if the item didn't have a kiosk_lock_rule, we need to do something with it.
-  // for e..g place it in our own kiosk. (demonstrated below)
-  if(result.canTransfer) place(tx, item.type, ownedKiosk, ownedKioskCap , result.item);
-
-  // ...finally, sign PTB & execute it.
-
-};
-```
-
-</details>
-
-<details>
-<summary>Create a kiosk, share it and get transfer the `kioskOwnerCap` to the wallet's address</summary>
-
-```typescript
-import { createKioskAndShare } from '@mysten/kiosk';
-import { TransactionBlock } from '@mysten/sui.js/transactions';
-
-const createKiosk = async () => {
-	const accountAddress = '0xSomeSuiAddress';
-
-	const tx = new TransactionBlock();
-	const kiosk_cap = createKioskAndShare(tx);
-
-	tx.transferObjects([kiosk_cap], tx.pure(accountAddress, 'address'));
-
-	// ... continue to sign and execute the transaction
-	// ...
-};
-```
-
-</details>
-
-<details>
-<summary>Place an item and list it for sale in the kiosk</summary>
-
-```typescript
-import { placeAndList } from '@mysten/kiosk';
-import { TransactionBlock } from '@mysten/sui.js/transactions';
-
-const placeAndListToKiosk = async () => {
-	const kiosk = 'SomeKioskId';
-	const kioskCap = 'KioskCapObjectId';
-	const itemType = '0xItemAddr::some:ItemType';
-	const item = 'SomeItemId';
-	const price = '100000';
-
-	const tx = new TransactionBlock();
-
-	placeAndList(tx, itemType, kiosk, kioskCap, item, price);
-
-	// ... continue to sign and execute the transaction
-	// ...
-};
-```
-
-</details>
-
-<details>
-<summary>Withdraw profits from your kiosk</summary>
-
-```typescript
-import { withdrawFromKiosk } from '@mysten/kiosk';
-import { TransactionBlock } from '@mysten/sui.js/transactions';
-
-const withdraw = async () => {
-	const kiosk = 'SomeKioskId';
-	const kioskCap = 'KioskCapObjectId';
-	const address = '0xSomeAddressThatReceivesTheFunds';
-	const amount = '100000';
-
-	const tx = new TransactionBlock();
-
-	withdrawFromKiosk(tx, kiosk, kioskCap, amount);
-
-	// transfer the Coin to self or any other address.
-	tx.transferObjects([coin], tx.pure(address, 'address'));
-
-	// ... continue to sign and execute the transaction
-	// ...
-};
-```
-
-</details>
-
-<details>
-
-<summary>Create a Transfer Policy for a Type</summary>
-
-You can create a TransferPolicy only for packages for which you own the `publisher` object.
-
-As a best practice, you should use a single Transfer policy per type (T). If you use more than one
-policy for a type, and the rules for each differ, anyone that meets the conditions for any of the
-attached policies can purchase an asset from a kiosk. You can't specify which policy applies to a
-specific asset for the type when there is more than one policy attached. When someone meets the
-conditions that are easiest to meet, they are allowed to purchase and transfer the asset.
-
-Before you create a transfer policy, you can use the `queryTransferpolicy` function to check the
-transfer policy associated with a type. This is similar to the `purchaseAndResolvePolicies` example
-above.
-
-```typescript
-import { createTransferPolicy } from '@mysten/kiosk';
-import { TransactionBlock } from '@mysten/sui.js';
-
-const createPolicyForType = async () => {
-	const type = 'SomePackageId::type::MyType'; // the Type for which we're creating a Transfer Policy.
-	const publisher = 'publisherObjectId'; // the publisher object id that you got when claiming the package that defines the Type.
-	const address = 'AddressToReceiveTheCap';
-
-	const tx = new TransactionBlock();
-	// create transfer policy
-	let transferPolicyCap = createTransferPolicy(tx, type, publisher);
-	// transfer the Cap to the address.
-	tx.transferObjects([transferPolicyCap], tx.pure(address, 'address'));
-
-	// ... continue to sign and execute the transaction
-	// ...
-};
-```
-
-</details>
-
-<details>
-
-<summary>Attach Royalty and Lock rules to a Transfer policy</summary>
-
-```typescript
-import {
-	createTransferPolicy,
-	attachKioskLockRule,
-	attachRoyaltyRule,
-	testnetEnvironment,
-	percentageToBasisPoints,
-} from '@mysten/kiosk';
-import { TransactionBlock } from '@mysten/sui.js';
-
-// Attaches a royalty rule of 1% or 0.1 SUI (whichever is bigger)
-// as well as a kiosk lock, making the objects trade-able only from/to a kiosk.
-const attachStrongRoyalties = async () => {
-	const type = 'SomePackageId::type::MyType'; // the Type for which we're attaching rules.
-	const policyId = 'policyObjectId'; // the transfer Policy ID that was created for that Type.
-	const transferPolicyCap = 'transferPolicyCapId'; // the transferPolicyCap for that policy.
-
-	// royalties configuration.
-	const percentage = 2.55; // 2.55%
-	const minAmount = 100_000_000; // 0.1 SUI.
-
-	// the environment on which we're referecing the rules package.
-	// use `mainnetEnvironment` for mainnet.
-	const enviroment = testnetEnvironment;
-
-	const tx = new TransactionBlock();
-
-	attachKioskLockRule(tx, type, policyId, policyCapId, enviroment);
-	attachRoyaltyRule(
-		tx,
-		type,
-		policyId,
-		policyCapId,
-		percentageToBasisPoints(percentage),
-		minAmount,
-		enviroment,
-	);
-
-	// ... continue to sign and execute the transaction
-	// ...
-};
-```
+[You can read the documentation and see examples by clicking here.](https://sui-typescript-docs.vercel.app/kiosk)
 
-</details>
+[If you are migrating from `0.6.x`, you can follow these instructions](https://sui-typescript-docs.vercel.app/kiosk/from-v1)

package/dist/client/kiosk-client.d.ts

@@ -0,0 +1,64 @@
+import { type SuiClient } from '@mysten/sui.js/client';
+import { type BaseRulePackageIds, type TransferPolicyRule } from '../constants';
+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 declare class KioskClient {
+    client: SuiClient;
+    network: Network;
+    rules: TransferPolicyRule[];
+    packageIds?: BaseRulePackageIds;
+    constructor(options: KioskClientOptions);
+    /**
+     * 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.
+     */
+    getOwnedKiosks({ address }: {
+        address: string;
+    }): Promise<OwnedKiosks>;
+    /**
+     * Fetches the kiosk contents.
+     * @param kioskId The ID of the kiosk to fetch.
+     * @param options Optioal
+     * @returns
+     */
+    getKiosk({ id, options }: {
+        id: string;
+        options?: FetchKioskOptions;
+    }): Promise<KioskData>;
+    /**
+     * Query the Transfer Policy(ies) for type `T`.
+     * @param type The Type we're querying for (E.g `0xMyAddress::hero::Hero`)
+     */
+    getTransferPolicies({ type }: {
+        type: string;
+    }): Promise<import("../types").TransferPolicy[]>;
+    /**
+     * 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.
+     */
+    getOwnedTransferPolicies({ address }: {
+        address: string;
+    }): Promise<import("../types").TransferPolicyCap[] | undefined>;
+    /**
+     * 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.
+     */
+    getOwnedTransferPoliciesByType({ type, address }: {
+        type: string;
+        address: string;
+    }): Promise<import("../types").TransferPolicyCap[]>;
+    addRuleResolver(rule: TransferPolicyRule): void;
+    /**
+     * A convenient helper to get the packageIds for our supported ruleset,
+     * based on `kioskClient` configuration.
+     */
+    getRulePackageId(rule: 'kioskLockRulePackageId' | 'royaltyRulePackageId' | 'personalKioskRulePackageId' | 'floorPriceRulePackageId'): string;
+}

package/dist/client/kiosk-transaction.d.ts

@@ -0,0 +1,207 @@
+import { type TransactionArgument, type TransactionBlock } from '@mysten/sui.js/transactions';
+import { ItemId, ItemReference, ItemValue, KioskOwnerCap, ObjectArgument, Price, PurchaseOptions } from '../types';
+import { type KioskClient } from './kiosk-client';
+export type KioskTransactionParams = {
+    /** The TransactionBlock for this run */
+    transactionBlock: TransactionBlock;
+    /**
+     * You can create a new KioskClient by calling `new KioskClient()`
+     */
+    kioskClient: KioskClient;
+    /**
+     * You can optionally pass in the `cap` as returned
+     * from `kioskClient.getOwnedKiosks` when initializing the client
+     * Otherwise, you can set it by calling `kioskTransaction.setCap()`
+     */
+    cap?: KioskOwnerCap;
+};
+/**
+ * A helper for building transactions that involve kiosk.
+ */
+export declare class KioskTransaction {
+    #private;
+    transactionBlock: TransactionBlock;
+    kioskClient: KioskClient;
+    kiosk?: TransactionArgument;
+    kioskCap?: TransactionArgument;
+    constructor({ transactionBlock, kioskClient, cap }: KioskTransactionParams);
+    /**
+     * Creates a kiosk and saves `kiosk` and `kioskOwnerCap` in state.
+     * Helpful if we want to chain some actions before sharing + transferring the cap to the specified address.
+     * @param borrow If true, the `kioskOwnerCap` is borrowed from the `PersonalKioskCap` to be used in next transactions.
+     */
+    create(): this;
+    /**
+     * Creates a personal kiosk & shares it.
+     * The `PersonalKioskCap` is transferred to the signer.
+     * @param borrow If true, the `kioskOwnerCap` is borrowed from the `PersonalKioskCap` to be used in next transactions.
+     */
+    createPersonal(borrow?: boolean): this;
+    /**
+     * Converts a kiosk to a Personal (Soulbound) Kiosk.
+     * Requires initialization by either calling `ktxb.create()` or `ktxb.setCap()`.
+     */
+    convertToPersonal(borrow?: boolean): this;
+    /**
+     * Single function way to create a kiosk, share it and transfer the cap to the specified address.
+     */
+    createAndShare(address: string): void;
+    /**
+     * Shares the kiosk.
+     */
+    share(): void;
+    /**
+     * Should be called only after `create` is called.
+     * It shares the kiosk & transfers the cap to the specified address.
+     */
+    shareAndTransferCap(address: string): void;
+    /**
+     * A function to borrow an item from a kiosk & execute any function with it.
+     * Example: You could borrow a Fren out of a kiosk, attach an accessory (or mix), and return it.
+     */
+    borrowTx({ itemType, itemId }: ItemId, callback: (item: TransactionArgument) => void): void;
+    /**
+     * Borrows an item from the kiosk.
+     * This will fail if the item is listed for sale.
+     *
+     * Requires calling `return`.
+     */
+    borrow({ itemType, itemId }: ItemId): [TransactionArgument, TransactionArgument];
+    /**
+     * Returns the item back to the kiosk.
+     * Accepts the parameters returned from the `borrow` function.
+     */
+    return({ itemType, item, promise }: ItemValue & {
+        promise: TransactionArgument;
+    }): this;
+    /**
+     * A function to withdraw from kiosk
+     * @param address Where to trasnfer the coin.
+     * @param amount The amount we aim to withdraw.
+     */
+    withdraw(address: string, amount?: string | bigint | number): this;
+    /**
+     * A function to place an item in the kiosk.
+     * @param itemType The type `T` of the item
+     * @param item The ID or Transaction Argument of the item
+     */
+    place({ itemType, item }: ItemReference): this;
+    /**
+     * A function to place an item in the kiosk and list it for sale in one transaction.
+     * @param itemType The type `T` of the item
+     * @param item The ID or Transaction Argument of the item
+     * @param price The price in MIST
+     */
+    placeAndList({ itemType, item, price }: ItemReference & Price): this;
+    /**
+     * A function to list an item in the kiosk.
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     * @param price The price in MIST
+     */
+    list({ itemType, itemId, price }: ItemId & {
+        price: string | bigint;
+    }): this;
+    /**
+     * A function to delist an item from the kiosk.
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     */
+    delist({ itemType, itemId }: ItemId): this;
+    /**
+     * A function to take an item from the kiosk. The transaction won't succeed if the item is listed or locked.
+
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     */
+    take({ itemType, itemId }: ItemId): TransactionArgument;
+    /**
+     * Transfer a non-locked/non-listed item to an address.
+     *
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     * @param address The destination address
+     */
+    transfer({ itemType, itemId, address }: ItemId & {
+        address: string;
+    }): this;
+    /**
+     * A function to take lock an item in the kiosk.
+
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     * @param policy The Policy ID or Transaction Argument for item T
+     */
+    lock({ itemType, itemId, policy }: ItemId & {
+        policy: ObjectArgument;
+    }): this;
+    /**
+     * Purchase an item from a seller's kiosk.
+     * Returns [item, transferRequest]
+     * Can be called like: `const [item, transferRequest] = kioskTx.purchase({...})`
+     * @param itemType The type `T` of the item
+     * @param itemId The ID of the item
+     * @param price The price in MIST
+     * @param sellerKiosk The kiosk which is selling the item. Can be an id or an object argument.
+     */
+    purchase({ itemType, itemId, price, sellerKiosk, }: ItemId & Price & {
+        sellerKiosk: ObjectArgument;
+    }): [TransactionArgument, TransactionArgument];
+    /**
+     * A function to purchase and resolve a transfer policy.
+     * If the transfer policy has the `lock` rule, the item is locked in the kiosk.
+     * Otherwise, the item is placed in the kiosk.
+     * @param itemType The type of the item
+     * @param itemId The id of the item
+     * @param price The price of the specified item
+     * @param sellerKiosk The kiosk which is selling the item. Can be an id or an object argument.
+     * @param extraArgs Used to pass arguments for custom rule resolvers.
+     */
+    purchaseAndResolve({ itemType, itemId, price, sellerKiosk, extraArgs, }: ItemId & Price & {
+        sellerKiosk: ObjectArgument;
+    } & PurchaseOptions): Promise<this>;
+    /**
+     * A function to setup the client using an existing `ownerCap`,
+     * as return from the `kioskClient.getOwnedKiosks` function.
+     * @param cap `KioskOwnerCap` object as returned from `getOwnedKiosks` SDK call.
+     */
+    setCap(cap: KioskOwnerCap): this | undefined;
+    /**
+     *	A function that ends up the kiosk building txb & returns the `kioskOwnerCap` back to the
+     *  `PersonalKioskCap`, in case we are operating on a personal kiosk.
+     * 	It will also share the `kiosk` if it's not shared, and finalize the transfer of the personal cap if it's pending.
+     */
+    finalize(): void;
+    setKioskCap(cap: TransactionArgument): this;
+    setKiosk(kiosk: TransactionArgument): this;
+    getKiosk(): {
+        kind: "Input";
+        index: number;
+        type?: "object" | "pure" | undefined;
+        value?: any;
+    } | {
+        kind: "GasCoin";
+    } | {
+        kind: "Result";
+        index: number;
+    } | {
+        kind: "NestedResult";
+        index: number;
+        resultIndex: number;
+    };
+    getKioskCap(): {
+        kind: "Input";
+        index: number;
+        type?: "object" | "pure" | undefined;
+        value?: any;
+    } | {
+        kind: "GasCoin";
+    } | {
+        kind: "Result";
+        index: number;
+    } | {
+        kind: "NestedResult";
+        index: number;
+        resultIndex: number;
+    };
+}