@haneullabs/kiosk 0.1.0 → 1.1.3

package/dist/utils.mjs

@@ -0,0 +1,137 @@
+import { Item, Kiosk, Listing, Lock } from "./contracts/0x2/kiosk.mjs";
+import { bcs } from "@haneullabs/haneul/bcs";
+import { normalizeHaneulAddress, normalizeStructTag, parseStructTag } from "@haneullabs/haneul/utils";
+
+//#region src/utils.ts
+async function getKioskObject(client, id) {
+	const { object } = await client.core.getObject({
+		objectId: id,
+		include: { content: true }
+	});
+	if (!object.content) throw new Error(`Kiosk ${id} not found or has no content`);
+	const parsed = Kiosk.parse(object.content);
+	return {
+		id: parsed.id,
+		profits: parsed.profits.value.toString(),
+		owner: parsed.owner,
+		itemCount: parsed.item_count,
+		allowExtensions: parsed.allow_extensions
+	};
+}
+function extractKioskData(data, listings, lockedItemIds, kioskId) {
+	return data.reduce((acc, val) => {
+		const type = val.name.type;
+		const parsedType = parseStructTag(type);
+		const baseType = `${normalizeHaneulAddress(parsedType.address)}::${parsedType.module}::${parsedType.name}`;
+		if (baseType === "0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Item") {
+			const parsed = Item.parse(val.name.bcs);
+			acc.itemIds.push(parsed.id);
+			acc.items.push({
+				objectId: parsed.id,
+				type: val.valueType,
+				isLocked: false,
+				kioskId
+			});
+		}
+		if (baseType === "0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Listing") {
+			const parsed = Listing.parse(val.name.bcs);
+			acc.listingIds.push(val.fieldId);
+			listings.push({
+				objectId: parsed.id,
+				listingId: val.fieldId,
+				isExclusive: parsed.is_exclusive
+			});
+		}
+		if (baseType === "0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Lock") lockedItemIds?.push(Lock.parse(val.name.bcs).id);
+		if (baseType === "0x0000000000000000000000000000000000000000000000000000000000000002::kiosk_extension::ExtensionKey") acc.extensions.push({
+			objectId: val.fieldId,
+			type: normalizeStructTag(parsedType.typeParams[0])
+		});
+		return acc;
+	}, {
+		items: [],
+		itemIds: [],
+		listingIds: [],
+		extensions: []
+	});
+}
+/**
+* A helper that attaches the listing prices to kiosk listings.
+*/
+function attachListingsAndPrices(kioskData, listings, listingObjects) {
+	const itemListings = listings.reduce((acc, item, idx) => {
+		acc[item.objectId] = { ...item };
+		if (listingObjects.length === 0) return acc;
+		const obj = listingObjects[idx];
+		if (obj.content) acc[item.objectId].price = bcs.u64().parse(obj.content).toString();
+		return acc;
+	}, {});
+	kioskData.items.forEach((item) => {
+		item.listing = itemListings[item.objectId] || void 0;
+	});
+}
+/**
+* A helper that attaches object data to kiosk items.
+* Works with core API objects that contain BCS content.
+*/
+function attachObjects(kioskData, objects) {
+	const mapping = objects.reduce((acc, obj) => {
+		acc[obj.objectId] = obj;
+		return acc;
+	}, {});
+	kioskData.items.forEach((item) => {
+		item.data = mapping[item.objectId] || void 0;
+	});
+}
+/**
+* A Helper to attach locked state to items in Kiosk Data.
+*/
+function attachLockedItems(kioskData, lockedItemIds) {
+	const lockedStatuses = lockedItemIds.reduce((acc, item) => {
+		acc[item] = true;
+		return acc;
+	}, {});
+	kioskData.items.forEach((item) => {
+		item.isLocked = lockedStatuses[item.objectId] || false;
+	});
+}
+/**
+* A helper to fetch all dynamic field pages.
+* We need that to fetch the kiosk DFs consistently, until we have
+* RPC calls that allow filtering of Type / batch fetching of spec
+*/
+async function getAllDynamicFields(client, parentId, pagination) {
+	let hasNextPage = true;
+	let cursor = null;
+	const data = [];
+	while (hasNextPage) {
+		const result = await client.core.listDynamicFields({
+			parentId,
+			limit: pagination.limit || void 0,
+			cursor
+		});
+		data.push(...result.dynamicFields);
+		hasNextPage = result.hasNextPage;
+		cursor = result.cursor;
+	}
+	return data;
+}
+/**
+* Converts a number to basis points.
+* Supports up to 2 decimal points.
+* E.g 9.95 -> 995
+* @param percentage A percentage amount in the range [0, 100] including decimals.
+*/
+function percentageToBasisPoints(percentage) {
+	if (percentage < 0 || percentage > 100) throw new Error("Percentage needs to be in the [0,100] range.");
+	return Math.ceil(percentage * 100);
+}
+function getNormalizedRuleType(rule) {
+	const normalizedRuleAddress = rule.split("::");
+	normalizedRuleAddress[0] = normalizeHaneulAddress(normalizedRuleAddress[0]);
+	return normalizedRuleAddress.join("::");
+}
+
+//#endregion
+export { attachListingsAndPrices, attachLockedItems, attachObjects, extractKioskData, getAllDynamicFields, getKioskObject, getNormalizedRuleType, percentageToBasisPoints };
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":["KioskStruct"],"sources":["../src/utils.ts"],"sourcesContent":["// Copyright (c) Mysten Labs, Inc.\n// SPDX-License-Identifier: Apache-2.0\n\nimport { bcs } from '@haneullabs/haneul/bcs';\nimport { PaginationArguments } from '@haneullabs/haneul/jsonRpc';\nimport type { ClientWithCoreApi, HaneulClientTypes } from '@haneullabs/haneul/client';\nimport { normalizeStructTag, normalizeHaneulAddress, parseStructTag } from '@haneullabs/haneul/utils';\n\nimport { Item, Listing, Lock, Kiosk as KioskStruct } from './contracts/0x2/kiosk.js';\nimport type { Kiosk, KioskData, KioskListing, ObjectWithDisplay } from './types/index.js';\n\nexport type DynamicFieldInfo = HaneulClientTypes.ListDynamicFieldsResponse['dynamicFields'][number];\n\nexport async function getKioskObject(client: ClientWithCoreApi, id: string): Promise<Kiosk> {\n\tconst { object } = await client.core.getObject({\n\t\tobjectId: id,\n\t\tinclude: { content: true },\n\t});\n\n\tif (!object.content) {\n\t\tthrow new Error(`Kiosk ${id} not found or has no content`);\n\t}\n\n\tconst parsed = KioskStruct.parse(object.content);\n\n\treturn {\n\t\tid: parsed.id,\n\t\tprofits: parsed.profits.value.toString(),\n\t\towner: parsed.owner,\n\t\titemCount: parsed.item_count,\n\t\tallowExtensions: parsed.allow_extensions,\n\t};\n}\n\n// helper to extract kiosk data from dynamic fields.\nexport function extractKioskData(\n\tdata: DynamicFieldInfo[],\n\tlistings: KioskListing[],\n\tlockedItemIds: string[],\n\tkioskId: string,\n): KioskData {\n\treturn data.reduce<KioskData>(\n\t\t(acc: KioskData, val: DynamicFieldInfo) => {\n\t\t\tconst type = val.name.type;\n\n\t\t\tconst parsedType = parseStructTag(type);\n\t\t\tconst baseType = `${normalizeHaneulAddress(parsedType.address)}::${parsedType.module}::${parsedType.name}`;\n\n\t\t\tif (\n\t\t\t\tbaseType ===\n\t\t\t\t'0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Item'\n\t\t\t) {\n\t\t\t\tconst parsed = Item.parse(val.name.bcs);\n\t\t\t\tacc.itemIds.push(parsed.id);\n\t\t\t\tacc.items.push({\n\t\t\t\t\tobjectId: parsed.id,\n\t\t\t\t\ttype: val.valueType,\n\t\t\t\t\tisLocked: false,\n\t\t\t\t\tkioskId,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\tbaseType ===\n\t\t\t\t'0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Listing'\n\t\t\t) {\n\t\t\t\tconst parsed = Listing.parse(val.name.bcs);\n\n\t\t\t\tacc.listingIds.push(val.fieldId);\n\t\t\t\tlistings.push({\n\t\t\t\t\tobjectId: parsed.id,\n\t\t\t\t\tlistingId: val.fieldId,\n\t\t\t\t\tisExclusive: parsed.is_exclusive,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\tbaseType ===\n\t\t\t\t'0x0000000000000000000000000000000000000000000000000000000000000002::kiosk::Lock'\n\t\t\t) {\n\t\t\t\tlockedItemIds?.push(Lock.parse(val.name.bcs).id);\n\t\t\t}\n\n\t\t\t// Check for ExtensionKey type\n\t\t\tif (\n\t\t\t\tbaseType ===\n\t\t\t\t'0x0000000000000000000000000000000000000000000000000000000000000002::kiosk_extension::ExtensionKey'\n\t\t\t) {\n\t\t\t\tacc.extensions.push({\n\t\t\t\t\tobjectId: val.fieldId,\n\t\t\t\t\ttype: normalizeStructTag(parsedType.typeParams[0]),\n\t\t\t\t});\n\t\t\t}\n\n\t\t\treturn acc;\n\t\t},\n\t\t{ items: [], itemIds: [], listingIds: [], extensions: [] },\n\t);\n}\n\n/**\n * A helper that attaches the listing prices to kiosk listings.\n */\nexport function attachListingsAndPrices(\n\tkioskData: KioskData,\n\tlistings: KioskListing[],\n\tlistingObjects: ObjectWithDisplay[],\n) {\n\tconst itemListings = listings.reduce<Record<string, KioskListing>>(\n\t\t(acc: Record<string, KioskListing>, item, idx) => {\n\t\t\tacc[item.objectId] = { ...item };\n\n\t\t\t// return in case we don't have any listing objects.\n\t\t\t// that's the case when we don't have the `listingPrices` included.\n\t\t\tif (listingObjects.length === 0) return acc;\n\n\t\t\tconst obj = listingObjects[idx];\n\n\t\t\t// Parse BCS content to extract the price (u64 value)\n\t\t\tif (obj.content) {\n\t\t\t\tacc[item.objectId].price = bcs.u64().parse(obj.content).toString();\n\t\t\t}\n\n\t\t\treturn acc;\n\t\t},\n\t\t{},\n\t);\n\n\tkioskData.items.forEach((item) => {\n\t\titem.listing = itemListings[item.objectId] || undefined;\n\t});\n}\n\n/**\n * A helper that attaches object data to kiosk items.\n * Works with core API objects that contain BCS content.\n */\nexport function attachObjects(kioskData: KioskData, objects: ObjectWithDisplay[]) {\n\tconst mapping = objects.reduce<Record<string, ObjectWithDisplay>>(\n\t\t(acc: Record<string, ObjectWithDisplay>, obj) => {\n\t\t\tacc[obj.objectId] = obj;\n\t\t\treturn acc;\n\t\t},\n\t\t{},\n\t);\n\n\tkioskData.items.forEach((item) => {\n\t\titem.data = mapping[item.objectId] || undefined;\n\t});\n}\n\n/**\n * A Helper to attach locked state to items in Kiosk Data.\n */\nexport function attachLockedItems(kioskData: KioskData, lockedItemIds: string[]) {\n\t// map lock status in an array of type { item_id: true }\n\tconst lockedStatuses = lockedItemIds.reduce<Record<string, boolean>>(\n\t\t(acc: Record<string, boolean>, item: string) => {\n\t\t\tacc[item] = true;\n\t\t\treturn acc;\n\t\t},\n\t\t{},\n\t);\n\n\t// parse lockedItemIds and attach their locked status.\n\tkioskData.items.forEach((item) => {\n\t\titem.isLocked = lockedStatuses[item.objectId] || false;\n\t});\n}\n\n/**\n * A helper to fetch all dynamic field pages.\n * We need that to fetch the kiosk DFs consistently, until we have\n * RPC calls that allow filtering of Type / batch fetching of spec\n */\nexport async function getAllDynamicFields(\n\tclient: ClientWithCoreApi,\n\tparentId: string,\n\tpagination: PaginationArguments<string>,\n): Promise<DynamicFieldInfo[]> {\n\tlet hasNextPage = true;\n\tlet cursor: string | null = null;\n\tconst data: DynamicFieldInfo[] = [];\n\n\twhile (hasNextPage) {\n\t\tconst result = await client.core.listDynamicFields({\n\t\t\tparentId,\n\t\t\tlimit: pagination.limit || undefined,\n\t\t\tcursor,\n\t\t});\n\n\t\tdata.push(...result.dynamicFields);\n\n\t\thasNextPage = result.hasNextPage;\n\t\tcursor = result.cursor;\n\t}\n\n\treturn data;\n}\n\n/**\n * Converts a number to basis points.\n * Supports up to 2 decimal points.\n * E.g 9.95 -> 995\n * @param percentage A percentage amount in the range [0, 100] including decimals.\n */\nexport function percentageToBasisPoints(percentage: number) {\n\tif (percentage < 0 || percentage > 100)\n\t\tthrow new Error('Percentage needs to be in the [0,100] range.');\n\treturn Math.ceil(percentage * 100);\n}\n\n// Normalizes the packageId part of a rule's type.\nexport function getNormalizedRuleType(rule: string) {\n\tconst normalizedRuleAddress = rule.split('::');\n\tnormalizedRuleAddress[0] = normalizeHaneulAddress(normalizedRuleAddress[0]);\n\treturn normalizedRuleAddress.join('::');\n}\n"],"mappings":"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"}

package/docs/advanced-examples.md

@@ -0,0 +1,100 @@
+# Advanced Examples
+
+> Advanced Kiosk SDK usage patterns and examples
+
+# Some extended examples
+
+For these examples, assume you have the following data and functions available:
+
+```typescript
+// a constant for bullshark's type.
+const bullsharkType = `${packageId}::haneulfrens::HaneulFren<${packageId}::bullshark::Bullshark>`;
+// a constant for capy's type.
+const capyType = `${packageId}::haneulfrens::HaneulFren<${packageId}::capy::Capy>`;
+
+// initialize the client with the kiosk extension.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+```
+
+## Minting a HaneulFren
+
+This example demonstrates how to mint a HaneulFren.
+
+```typescript
+async function mintFren(address: string) {
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address });
+
+	// Choose the first kiosk for simplicity. We could have extra logic here (e.g. let the user choose, pick a personal one, etc).
+	const cap = kioskOwnerCaps[0];
+
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+	// We're mixing the logic here. If the cap is undefined, we create a new kiosk.
+	if (!cap) kioskTx.create();
+
+	// Let's mint a capy here into the kiosk (either a new or an existing one).
+	tx.moveCall({
+		target: `${packageId}::haneulfrens::mint_app::mint`,
+		arguments: [kioskTx.getKiosk(), kioskTx.getKioskCap()],
+		typeArguments: [capyType],
+	});
+
+	// If we don't have a cap, that means we create a new kiosk for the user in this flow.
+	if (!cap) kioskTx.shareAndTransferCap(address);
+
+	kioskTx.finalize();
+
+	// sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+}
+```
+
+## Mixing two Haneulfrens
+
+This example demonstrates how to use the Kiosk SDK to mix two `bullsharks`.
+
+```typescript
+// We're mixing two frens.
+async function mixFrens(firstFrenObjectId: string, secondFrenObjectId: string, cap: KioskOwnerCap) {
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+	// borrow both frens.
+	const [fren1, promise1] = kioskTx.borrow({
+		itemType: bullsharkType,
+		itemId: firstFrenObjectId,
+	});
+
+	const [fren2, promise2] = kioskTx.borrow({
+		itemType: bullsharkType,
+		itemId: secondFrenObjectId,
+	});
+
+	// Let's call the mix function. We skip any payment related stuff here.
+	tx.moveCall({
+		target: `${packageId}::mix_app::mix`,
+		arguments: [fren1, fren2, kioskTx.getKiosk(), kioskTx.getKioskCap()],
+		typeArguments: [bullsharkType],
+	});
+
+	kioskTx
+		.return({
+			itemType: bullsharkType,
+			item: fren1,
+			promise: promise1,
+		})
+		.return({
+			itemType: bullsharkType,
+			item: fren2,
+			promise: promise2,
+		})
+		.finalize();
+
+	// sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+}
+```

package/docs/from-v1.md

@@ -0,0 +1,314 @@
+# Migrating from Kiosk SDK V1
+
+> Migrate from Kiosk SDK v1 to the current version
+
+The original version of Kiosk SDK provided basic experimentation with the Kiosk API. The new version
+of the SDK (0.7+) provides a more robust experience for building kiosk/transfer policy transactions.
+
+The new SDK offers a builder-pattern API, which provides better autocomplete capabilities, and also
+makes code more readable.
+
+While a one-to-one mapping between the old and new SDK is not possible, the following examples
+should help you get started.
+
+> An important benefit of the new SDK is that it works seamlessly with Personal Kiosk, which was not
+> the case with the previous SDK (you would always have to wrap the transaction with `borrow_cap` /
+> `return_cap` calls depending on whether the kiosk is personal or not).
+
+## Placing an item to kiosk and listing it for sale
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+const placeAndListToKiosk = async () => {
+	const kiosk = 'SomeKioskId';
+	const kioskCap = 'KioskCapObjectId';
+	const itemType = '0xItemAddr::some:ItemType';
+	const item = 'SomeItemId';
+	const price = '100000';
+
+	const tx = new Transaction();
+
+	placeAndList(tx, itemType, kiosk, kioskCap, item, price);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const placeAndListToKiosk = async () => {
+	// Assume you have saved the user's preferred kiosk Cap somewhere in your app's state.
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xSomeAddress' });
+
+	const tx = new Transaction();
+
+	// Assume you use the first owned kiosk.
+	new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap: kioskOwnerCaps[0] })
+		.placeAndList({
+			itemType: '0xItemAddr::some:ItemType',
+			item: 'SomeItemId',
+			price: '100000',
+		})
+		.finalize();
+
+	// ... continue to sign and execute the transaction
+};
+```
+
+## Create a new kiosk
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+const createKiosk = async () => {
+	const accountAddress = '0xSomeHaneulAddress';
+
+	const tx = new Transaction();
+	const kiosk_cap = createKioskAndShare(tx);
+
+	tx.transferObjects([kiosk_cap], accountAddress);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const createKiosk = async () => {
+	const tx = new Transaction();
+
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
+
+	kioskTx.create().shareAndTransferCap('0xSomeHaneulAddress').finalize();
+
+	// ... continue to sign and execute the transaction
+};
+```
+
+## Purchasing an item and resolving rules
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+
+	queryTransferPolicy,
+	purchaseAndResolvePolicies,
+	place,
+	testnetEnvironment,
+} from '@haneullabs/kiosk';
+
+const client = new HaneulJsonRpcClient({
+	url: 'https://fullnode.testnet.haneul.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 GEUNHWA
+	},
+};
+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 transaction.
+	const tx = new Transaction();
+
+	// Both are required if there is a `kiosk_lock_rule`.
+	// Optional otherwise. Function throws 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, you need to do something with it.
+	// For example, place it in your own kiosk. (demonstrated below)
+	if (result.canTransfer) place(tx, item.type, ownedKiosk, ownedKioskCap, result.item);
+
+	// ...finally, sign PTB & execute it.
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+> This works with both personal and non-personal kiosks.
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+// An Item as returned from `client.kiosk.getKiosk()` call.
+const item = {
+	isLocked: false,
+	objectId: '0xb892d61a9992a10c9453efcdbd14ca9720d7dc1000a2048224209c9e544ed223',
+	type: '0x52852c4ba80040395b259c641e70b702426a58990ff73cecf5afd31954429090::test::TestItem',
+	kioskId: '0xSomeKioskAddress',
+	listing: {
+		isExclusive: false,
+		listingId: '0x368b512ff2514dbea814f26ec9a3d41198c00e8ed778099961e9ed22a9f0032b',
+		price: '20000000000', // in GEUNHWA
+	},
+};
+
+const purchase = async () => {
+	// Assume you have saved the user's preferred kiosk Cap somewhere in your app's state.
+	// You wouldn't need to query this for every purchase.
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xSomeAddress' });
+
+	const tx = new Transaction();
+
+	const kioskTx = new KioskTransaction({
+		transaction: tx,
+		kioskClient: client.kiosk,
+		cap: kioskOwnerCaps[0],
+	});
+
+	// Purchase the item and resolve the rules.
+	await kioskTx.purchaseAndResolve({
+		itemType: item.type,
+		itemId: item.objectId,
+		price: item.listing.price,
+		sellerKiosk: item.kioskId,
+	});
+
+	kioskTx.finalize();
+};
+```
+
+## Attach rules to transfer policy
+
+The following example was taken from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+
+	attachKioskLockRule,
+	attachRoyaltyRule,
+	createTransferPolicy,
+	percentageToBasisPoints,
+	testnetEnvironment,
+} from '@haneullabs/kiosk';
+
+// Attaches a royalty rule of 1% or 0.1 HANEUL (whichever is bigger)
+// as well as a kiosk lock, making the objects tradeable 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 HANEUL.
+
+	// The environment on which we're referencing the rules package.
+	// Use `mainnetEnvironment` for mainnet.
+	const environment = testnetEnvironment;
+
+	const tx = new Transaction();
+
+	attachKioskLockRule(tx, type, policyId, policyCapId, environment);
+	attachRoyaltyRule(
+		tx,
+		type,
+		policyId,
+		policyCapId,
+		percentageToBasisPoints(percentage),
+		minAmount,
+		environment,
+	);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+On the new SDK, the same transaction can be built as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const adjustPolicy = async () => {
+	const tx = new Transaction();
+
+	// You could have more than one cap, since you can create more than one transfer policy.
+	const policyCaps = await client.kiosk.getOwnedTransferPoliciesByType({
+		type: `SomePackageId::type::MyType`,
+		address: '0xOwnerAddress',
+	});
+
+	new TransferPolicyTransaction({ transaction: tx, kioskClient: client.kiosk, cap: policyCaps[0] })
+		.addRoyaltyRule(percentageToBasisPoints(2.55), 100_000_000)
+		.addLockRule();
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```

package/docs/index.md

@@ -0,0 +1,22 @@
+# Kiosk SDK
+
+> TypeScript SDK for interacting with Haneul Kiosk on-chain commerce
+
+Kiosk SDK is a tool to interact with Haneul/Haneullabs Kiosk. You can use it to query kiosk related
+data, build transactions to interact, and extend Kiosk to support custom rules.
+
+## Installation
+
+```sh npm2yarn
+npm i @haneullabs/kiosk
+```
+
+## About
+
+The Kiosk SDK exports a client extension that integrates with Haneul clients. Add it to your client
+using `$extend(kiosk())` to access kiosk functionality via `client.kiosk`.
+
+> **Note:** The Kiosk SDK requires `HaneulJsonRpcClient` or `HaneulGraphQLClient`. It does not work
+> with `HaneulGrpcClient` because it uses event queries that are not available in gRPC.
+
+- [Read more about setting up the Kiosk client extension](/kiosk/kiosk-client/introduction)

package/docs/kiosk-client/introduction.md

@@ -0,0 +1,50 @@
+# Kiosk Client
+
+> Introduction to the KioskClient for querying and managing kiosks
+
+The Kiosk SDK exports a client extension that provides all Kiosk functionality.
+
+> We recommend you keep only one client instance throughout your dApp or script. For example, in
+> React, you'd use a context to provide the client.
+
+> **Note:** The Kiosk SDK requires `HaneulJsonRpcClient` or `HaneulGraphQLClient`. It does not work
+> with `HaneulGrpcClient` because it uses event queries that are not available in gRPC.
+
+## Setting up the kiosk extension
+
+Add the kiosk extension to your Haneul client using `$extend()`. The extension currently supports
+`mainnet` and `testnet`. See the next section for usage on other networks.
+
+_Haneullabs Kiosk rules and extensions are not supported in Devnet due to network wipes (that would
+require constantly changing the package IDs)._
+
+```typescript
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('testnet'),
+	network: 'testnet',
+}).$extend(kiosk());
+
+// Now you can use client.kiosk for all kiosk operations
+const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0x...' });
+```
+
+### Using the kiosk extension on devnet or localnet
+
+To use all the functionality of Kiosk SDK outside of `mainnet` and `testnet`, pass the `packageIds`
+for the rules and extensions you want to use.
+
+```typescript
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('devnet'),
+	network: 'devnet',
+}).$extend(
+	kiosk({
+		packageIds: {
+			kioskLockRulePackageId: '0x...',
+			royaltyRulePackageId: '0x...',
+			personalKioskRulePackageId: '0x...',
+			floorPriceRulePackageId: '0x...',
+		},
+	}),
+);
+```