Enhance the re-design register method (#630)

* fix: update error handling and documentation for IP asset registration

* docs: enhance IP asset registration documentation with detailed usage examples and clarify license terms and royalty shares handling

* test: update error messages and add tests for optional parameters in IP asset registration

* test: refactor and enhance integration tests for IP asset registration with minted NFTs

* fix: update documentation for royaltyShares in RegisterIpAssetRequest to clarify association with revenue distribution

Author: bonnie57

packages/core-sdk/src/resources/ipAsset.ts

@@ -1667,22 +1667,64 @@ export class IPAssetClient {
     }
   }
   /**
-   * Register an IP asset, supporting both minted and mint-on-demand NFTs, with optional license terms and royalty shares.
-   * Supports the following workflows:
-   * - {@link registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens}
-   * - {@link registerIpAndAttachPilTerms}
-   * - {@link register}
-   * - {@link mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens}
-   * - {@link mintAndRegisterIpAssetWithPilTerms}
-   * - {@link mintAndRegisterIp}
+   * Register an IP asset, supporting both minted and mint-on-demand NFTs, with optional `licenseTermsData` and `royaltyShares`.
    *
-   * The method supports automatic token handling for minting fees:
+   * This method automatically selects and calls the appropriate workflow from 6 available methods based on your input parameters.
+   * Here are three common usage patterns:
+   *
+   * **1. Minted NFT with License Terms and Royalty Distribution:**
+   * ```typescript
+   * const result = await client.ipAsset.registerIpAsset({
+   *   nft: { type: "minted", nftContract: "0x...", tokenId: 1n },
+   *   licenseTermsData: [
+   *     {
+   *       terms: PILFlavor.commercialRemix({
+   *         defaultMintingFee: 10000n,
+   *         commercialRevShare: 100,
+   *         currency: "0x..."
+   *       })
+   *     }
+   *   ],
+   *   royaltyShares: [
+   *     { recipient: "0x...", percentage: 100 }
+   *   ]
+   * });
+   * ```
+   *
+   * **2. Minted NFT with Basic License Terms:**
+   * ```typescript
+   * const result = await client.ipAsset.registerIpAsset({
+   *   nft: { type: "minted", nftContract: "0x...", tokenId: 1n },
+   *   licenseTermsData: [
+   *     {
+   *       terms: PILFlavor.nonCommercialSocialRemixing()
+   *     }
+   *   ]
+   * });
+   * ```
+   *
+   * **3. Mint NFT with IP Asset:**
+   * ```typescript
+   * const result = await client.ipAsset.registerIpAsset({
+   *   nft: { type: "mint", spgNftContract: "0x...", recipient: "0x...", allowDuplicates: false },
+   * });
+   * ```
+   *
+   * **Supported Workflows (6 methods automatically selected based on parameters):**
+   * - {@link registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens} - Register IP with license terms and royalty distribution
+   * - {@link registerIpAndAttachPilTerms} - Register IP with license terms
+   * - {@link register} - Register basic IP asset
+   * - {@link mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens} - Mint NFT and register IP with license terms and royalty distribution
+   * - {@link mintAndRegisterIpAssetWithPilTerms} - Mint NFT and register IP with license terms
+   * - {@link mintAndRegisterIp} - Mint NFT and register basic IP asset
+   *
+   * **Automatic Token Handling:**
    * - If the wallet's IP token balance is insufficient to cover minting fees, it automatically wraps native IP tokens into WIP tokens.
    * - It checks allowances for all required spenders and automatically approves them if their current allowance is lower than needed.
    * - These automatic processes can be configured through the `wipOptions` parameter to control behavior like multicall usage and approval settings.
    *
    * @throws {Error} If the NFT type is invalid.
-   * @throws {Error} If royalty shares are required when registering IP with license terms data.
+   * @throws {Error} If `licenseTermsData` is not provided when `royaltyShares` are specified.
    *
    */
   public async registerIpAsset<T extends RegisterIpAssetRequest<MintedNFT | MintNFT>>(
@@ -1693,7 +1735,7 @@ export class IPAssetClient {
 
       // Validate royalty shares without license terms
       if (royaltyShares && !licenseTermsData) {
-        throw new Error("Royalty shares are required when registering IP with license terms data.");
+        throw new Error("License terms data must be provided when royalty shares are specified.");
       }
 
       if (nft.type === "minted") {

packages/core-sdk/src/types/resources/ipAsset.ts

@@ -611,11 +611,86 @@ export type MintedNFT = {
   nftContract: Address;
   tokenId: TokenIdInput;
 };
+/**
+ * Request configuration for registering IP assets with flexible licensing and royalty options.
+ *
+ * @template T - The NFT type (MintNFT and MintedNFT)
+ *
+ * @example
+ * **Basic IP Registration:**
+ * ```typescript
+ * const request: RegisterIpAssetRequest<MintedNFT> = {
+ *   nft: {
+ *     type: "minted",
+ *     nftContract: "0x1234567890123456789012345678901234567890",
+ *     tokenId: 1n
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * **IP Registration with License Terms:**
+ * ```typescript
+ * const request: RegisterIpAssetRequest<MintedNFT> = {
+ *   nft: {
+ *     type: "minted",
+ *     nftContract: "0x1234567890123456789012345678901234567890",
+ *     tokenId: 1n
+ *   },
+ *   licenseTermsData: [
+ *     {
+ *       terms: PILFlavor.commercialUse({
+ *         defaultMintingFee: 10000n,
+ *         currency: WIP_TOKEN_ADDRESS
+ *       })
+ *     }
+ *   ]
+ * };
+ * ```
+ * @example
+ * **Mint New NFT and with License Terms and Royalty Distribution:**
+ * ```typescript
+ * const request: RegisterIpAssetRequest<MintNFT> = {
+ *   nft: {
+ *     type: "mint",
+ *     spgNftContract: "0x1234567890123456789012345678901234567890",
+ *     recipient: "0xRecipient...",
+ *     allowDuplicates: false
+ *   },
+ *   licenseTermsData: [
+ *     {
+ *       terms: PILFlavor.nonCommercialSocialRemixing()
+ *     }
+ *   ],
+ *  royaltyShares: [
+ *     { recipient: "0xArtist...", percentage: 70 },
+ *     { recipient: "0xCollaborator...", percentage: 30 }
+ *   ],
+ * };
+ * ```
+ */
 export type RegisterIpAssetRequest<T extends MintNFT | MintedNFT> = WithWipOptions &
   WithIpMetadata & {
+    /** The NFT to be registered as an IP asset. */
     nft: T;
+
+    /**
+     * License terms and configuration to be attached to the IP asset.
+     *
+     * @remarks
+     * Can be specified independently or together with `royaltyShares` for revenue distribution.
+     */
     licenseTermsData?: LicenseTermsDataInput[];
+
+    /**
+     * Authors of the IP and their shares of the royalty tokens.
+     *
+     * @remarks
+     * Can only be specified when `licenseTermsData` is also provided, ensuring
+     * that distribute royalty.
+     */
     royaltyShares?: RoyaltyShare[];
+
     /**
      * The deadline for the signature in seconds.
      * @default 1000
@@ -624,6 +699,26 @@ export type RegisterIpAssetRequest<T extends MintNFT | MintedNFT> = WithWipOptio
     txOptions?: Omit<TxOptions, "encodedTxDataOnly">;
   };
 
+/**
+ * Response type for IP asset registration with conditional return types based on input parameters.
+ *
+ * @template T - The request type extending `RegisterIpAssetRequest`
+ *
+ * @remarks
+ * The response structure varies based on the registration type:
+ *
+ * **Full Registration (with license terms + royalty shares):**
+ * - Returns detailed response with royalty vault information
+ * - Includes transaction hashes for both registration and royalty distribution
+ *
+ * **License Terms Only:**
+ * - Returns response with license terms IDs
+ * - Includes IP registration details
+ *
+ * **Basic Registration:**
+ * - Returns minimal response with IP ID and transaction hash
+ *
+ */
 export type RegisterIpAssetResponse<T extends RegisterIpAssetRequest<MintedNFT | MintNFT>> =
   T extends { licenseTermsData: LicenseTermsDataInput[]; royaltyShares: RoyaltyShare[] }
     ? T extends { nft: { type: "minted" } }