@iota/kiosk 0.0.0-dev-20251015065834

package/dist/cjs/client/kiosk-client.js

@@ -0,0 +1,126 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var kiosk_client_exports = {};
+__export(kiosk_client_exports, {
+  KioskClient: () => KioskClient
+});
+module.exports = __toCommonJS(kiosk_client_exports);
+var import_client = require("@iota/iota-sdk/client");
+var import_constants = require("../constants.js");
+var import_kiosk = require("../query/kiosk.js");
+var import_transfer_policy = require("../query/transfer-policy.js");
+class KioskClient {
+  constructor(options) {
+    this.client = options.client;
+    this.network = options.network;
+    this.rules = import_constants.rules;
+    this.packageIds = options.packageIds;
+    if (options.packageIds) this.rules.push(...(0, import_constants.getBaseRules)(options.packageIds));
+  }
+  /// Querying
+  /**
+   * Get an addresses's owned kiosks.
+   * @param address The address for which we want to retrieve the kiosks.
+   * @param pagination Optional pagination arguments.
+   * @returns An Object containing all the `kioskOwnerCap` objects as well as the kioskIds.
+   */
+  async getOwnedKiosks({
+    address,
+    pagination
+  }) {
+    const personalPackageId = this.packageIds?.personalKioskRulePackageId || (0, import_client.getNetwork)(this.network).kiosk?.personalKioskRulePackageId || "";
+    return (0, import_kiosk.getOwnedKiosks)(this.client, address, {
+      pagination,
+      personalKioskType: personalPackageId ? `${personalPackageId}::personal_kiosk::PersonalKioskCap` : ""
+    });
+  }
+  /**
+   * Fetches the kiosk contents.
+   * @param id The ID of the kiosk to fetch.
+   * @param options Optional to control the fetch behavior.
+   * @returns
+   */
+  async getKiosk({
+    id,
+    options
+  }) {
+    return (await (0, import_kiosk.fetchKiosk)(
+      this.client,
+      id,
+      {
+        limit: 1e3
+      },
+      options || {}
+    )).data;
+  }
+  /**
+   * Fetch the extension data (if any) for a kiosk, by type
+   * @param kioskId The ID of the kiosk to lookup
+   * @param extensionType The Type of the extension (can be used from by using the type returned by `getKiosk()`)
+   */
+  async getKioskExtension({ kioskId, type }) {
+    return (0, import_kiosk.fetchKioskExtension)(this.client, kioskId, type);
+  }
+  /**
+   * Query the Transfer Policy(ies) for type `T`.
+   * @param type The Type we're querying for (E.g `0xMyAddress::hero::Hero`)
+   */
+  async getTransferPolicies({ type }) {
+    return (0, import_transfer_policy.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 }) {
+    return (0, import_transfer_policy.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 }) {
+    return (0, import_transfer_policy.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) {
+    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) {
+    const rules2 = this.packageIds || {};
+    const network = this.network;
+    const networkKiosk = (0, import_client.getNetwork)(network).kiosk;
+    const rulePackageId = rules2[rule] || networkKiosk?.[rule];
+    if (!rulePackageId) {
+      throw new Error(`Missing packageId for rule ${rule}`);
+    }
+    return rulePackageId;
+  }
+}
+//# sourceMappingURL=kiosk-client.js.map

package/dist/cjs/client/kiosk-client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/client/kiosk-client.ts"],
+  "sourcesContent": ["// Copyright (c) Mysten Labs, Inc.\n// Modifications Copyright (c) 2024 IOTA Stiftung\n// SPDX-License-Identifier: Apache-2.0\n\nimport type { NetworkId } from '@iota/iota-sdk/client';\nimport { getNetwork } from '@iota/iota-sdk/client';\nimport type { PaginationArguments, IotaClient } from '@iota/iota-sdk/client';\n\nimport { getBaseRules, rules } from '../constants.js';\nimport type { BaseRulePackageIds, TransferPolicyRule } from '../constants.js';\nimport { fetchKiosk, fetchKioskExtension, getOwnedKiosks } from '../query/kiosk.js';\nimport {\n    queryOwnedTransferPolicies,\n    queryTransferPolicy,\n    queryTransferPolicyCapsByType,\n} from '../query/transfer-policy.js';\nimport type {\n    FetchKioskOptions,\n    KioskClientOptions,\n    KioskData,\n    OwnedKiosks,\n} from '../types/index.js';\n\n/**\n * A Client that allows you to interact with kiosk.\n * Offers utilities to query kiosk, craft transactions to edit your own kiosk,\n * purchase, manage transfer policies, create new kiosks etc.\n * If you pass packageIds, all functionality will be managed using these packages.\n */\nexport class KioskClient {\n    client: IotaClient;\n    network: NetworkId;\n    rules: TransferPolicyRule[];\n    packageIds?: BaseRulePackageIds;\n\n    constructor(options: KioskClientOptions) {\n        this.client = options.client;\n        this.network = options.network;\n        this.rules = rules; // add all the default rules.\n        this.packageIds = options.packageIds;\n\n        // Add the custom Package Ids too on the rule list.\n        // Only adds the rules that are passed in the packageId object.\n        if (options.packageIds) this.rules.push(...getBaseRules(options.packageIds));\n    }\n\n    /// Querying\n\n    /**\n     * Get an addresses's owned kiosks.\n     * @param address The address for which we want to retrieve the kiosks.\n     * @param pagination Optional pagination arguments.\n     * @returns An Object containing all the `kioskOwnerCap` objects as well as the kioskIds.\n     */\n    async getOwnedKiosks({\n        address,\n        pagination,\n    }: {\n        address: string;\n        pagination?: PaginationArguments<string>;\n    }): Promise<OwnedKiosks> {\n        const personalPackageId =\n            this.packageIds?.personalKioskRulePackageId ||\n            getNetwork(this.network).kiosk?.personalKioskRulePackageId ||\n            '';\n\n        return getOwnedKiosks(this.client, address, {\n            pagination,\n            personalKioskType: personalPackageId\n                ? `${personalPackageId}::personal_kiosk::PersonalKioskCap`\n                : '',\n        });\n    }\n\n    /**\n     * Fetches the kiosk contents.\n     * @param id The ID of the kiosk to fetch.\n     * @param options Optional to control the fetch behavior.\n     * @returns\n     */\n    async getKiosk({\n        id,\n        options,\n    }: {\n        id: string;\n        options?: FetchKioskOptions;\n    }): Promise<KioskData> {\n        return (\n            await fetchKiosk(\n                this.client,\n                id,\n                {\n                    limit: 1000,\n                },\n                options || {},\n            )\n        ).data;\n    }\n\n    /**\n     * Fetch the extension data (if any) for a kiosk, by type\n     * @param kioskId The ID of the kiosk to lookup\n     * @param extensionType The Type of the extension (can be used from by using the type returned by `getKiosk()`)\n     */\n    async getKioskExtension({ kioskId, type }: { kioskId: string; type: string }) {\n        return fetchKioskExtension(this.client, kioskId, type);\n    }\n\n    /**\n     * Query the Transfer Policy(ies) for type `T`.\n     * @param type The Type we're querying for (E.g `0xMyAddress::hero::Hero`)\n     */\n    async getTransferPolicies({ type }: { type: string }) {\n        return queryTransferPolicy(this.client, type);\n    }\n\n    /**\n     * Query all the owned transfer policies for an address.\n     * Returns `TransferPolicyCap` which uncludes `policyId, policyCapId, type`.\n     * @param address The address we're searching the owned transfer policies for.\n     */\n    async getOwnedTransferPolicies({ address }: { address: string }) {\n        return queryOwnedTransferPolicies(this.client, address);\n    }\n\n    /**\n     * Query the Transfer Policy Cap for type `T`, owned by `address`\n     * @param type The Type `T` for the object\n     * @param address The address that owns the cap.\n     */\n    async getOwnedTransferPoliciesByType({ type, address }: { type: string; address: string }) {\n        return queryTransferPolicyCapsByType(this.client, address, type);\n    }\n\n    // Someone would just have to create a `kiosk-client.ts` file in their project, initialize a KioskClient\n    // and call the `addRuleResolver` function. Each rule has a `resolve` function.\n    // The resolve function is automatically called on `purchaseAndResolve` function call.\n    addRuleResolver(rule: TransferPolicyRule) {\n        if (this.rules.find((x) => x.rule === rule.rule))\n            throw new Error(`Rule ${rule.rule} resolver already exists.`);\n        this.rules.push(rule);\n    }\n\n    /**\n     * A convenient helper to get the packageIds for our supported ruleset,\n     * based on `kioskClient` configuration.\n     */\n    getRulePackageId(\n        rule:\n            | 'kioskLockRulePackageId'\n            | 'royaltyRulePackageId'\n            | 'personalKioskRulePackageId'\n            | 'floorPriceRulePackageId',\n    ) {\n        const rules = this.packageIds || {};\n        const network = this.network;\n\n        const networkKiosk = getNetwork(network).kiosk;\n\n        const rulePackageId = rules[rule] || networkKiosk?.[rule];\n\n        /// Check existence of rule throw an error if it's not found.\n        if (!rulePackageId) {\n            throw new Error(`Missing packageId for rule ${rule}`);\n        }\n\n        return rulePackageId;\n    }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,oBAA2B;AAG3B,uBAAoC;AAEpC,mBAAgE;AAChE,6BAIO;AAcA,MAAM,YAAY;AAAA,EAMrB,YAAY,SAA6B;AACrC,SAAK,SAAS,QAAQ;AACtB,SAAK,UAAU,QAAQ;AACvB,SAAK,QAAQ;AACb,SAAK,aAAa,QAAQ;AAI1B,QAAI,QAAQ,WAAY,MAAK,MAAM,KAAK,OAAG,+BAAa,QAAQ,UAAU,CAAC;AAAA,EAC/E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,eAAe;AAAA,IACjB;AAAA,IACA;AAAA,EACJ,GAGyB;AACrB,UAAM,oBACF,KAAK,YAAY,kCACjB,0BAAW,KAAK,OAAO,EAAE,OAAO,8BAChC;AAEJ,eAAO,6BAAe,KAAK,QAAQ,SAAS;AAAA,MACxC;AAAA,MACA,mBAAmB,oBACb,GAAG,iBAAiB,uCACpB;AAAA,IACV,CAAC;AAAA,EACL;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS;AAAA,IACX;AAAA,IACA;AAAA,EACJ,GAGuB;AACnB,YACI,UAAM;AAAA,MACF,KAAK;AAAA,MACL;AAAA,MACA;AAAA,QACI,OAAO;AAAA,MACX;AAAA,MACA,WAAW,CAAC;AAAA,IAChB,GACF;AAAA,EACN;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,kBAAkB,EAAE,SAAS,KAAK,GAAsC;AAC1E,eAAO,kCAAoB,KAAK,QAAQ,SAAS,IAAI;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,oBAAoB,EAAE,KAAK,GAAqB;AAClD,eAAO,4CAAoB,KAAK,QAAQ,IAAI;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,yBAAyB,EAAE,QAAQ,GAAwB;AAC7D,eAAO,mDAA2B,KAAK,QAAQ,OAAO;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,+BAA+B,EAAE,MAAM,QAAQ,GAAsC;AACvF,eAAO,sDAA8B,KAAK,QAAQ,SAAS,IAAI;AAAA,EACnE;AAAA;AAAA;AAAA;AAAA,EAKA,gBAAgB,MAA0B;AACtC,QAAI,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI;AAC3C,YAAM,IAAI,MAAM,QAAQ,KAAK,IAAI,2BAA2B;AAChE,SAAK,MAAM,KAAK,IAAI;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,iBACI,MAKF;AACE,UAAMA,SAAQ,KAAK,cAAc,CAAC;AAClC,UAAM,UAAU,KAAK;AAErB,UAAM,mBAAe,0BAAW,OAAO,EAAE;AAEzC,UAAM,gBAAgBA,OAAM,IAAI,KAAK,eAAe,IAAI;AAGxD,QAAI,CAAC,eAAe;AAChB,YAAM,IAAI,MAAM,8BAA8B,IAAI,EAAE;AAAA,IACxD;AAEA,WAAO;AAAA,EACX;AACJ;",
+  "names": ["rules"]
+}

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

@@ -0,0 +1,185 @@
+import type { Transaction, TransactionArgument, TransactionObjectArgument } from '@iota/iota-sdk/transactions';
+import type { ItemId, ItemReference, ItemValue, KioskOwnerCap, ObjectArgument, Price, PurchaseOptions } from '../types/index.js';
+import type { KioskClient } from './kiosk-client.js';
+export type KioskTransactionParams = {
+    /** The Transaction for this run */
+    transaction: Transaction;
+    /** @deprecated use transaction instead */
+    transactionBlock?: Transaction;
+    /**
+     * 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;
+    transaction: Transaction;
+    kioskClient: KioskClient;
+    kiosk?: TransactionObjectArgument;
+    kioskCap?: TransactionObjectArgument;
+    constructor({ transactionBlock, transaction, 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.
+     */
+    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 transfer 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 NANOS
+     */
+    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 NANOS
+     */
+    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): TransactionObjectArgument;
+    /**
+     * 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 item The ID or Transaction Argument of the item
+     * @param itemId The ID of the item - Deprecated: Use `item` instead.
+     * @param policy The Policy ID or Transaction Argument for item T
+     */
+    lock({ itemType, item, itemId, policy, }: ItemReference & {
+        policy: ObjectArgument;
+        itemId?: string;
+    }): 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 NANOS
+     * @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;
+    }): [
+        TransactionObjectArgument,
+        TransactionObjectArgument
+    ];
+    /**
+     * 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 tx & 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: TransactionObjectArgument): this;
+    setKiosk(kiosk: TransactionObjectArgument): this;
+    getKiosk(): TransactionObjectArgument;
+    getKioskCap(): TransactionObjectArgument;
+}