fix(sdk): fix generate docs (#2730)

Co-authored-by: Claude <[email protected]>

Author: thephez

packages/wasm-sdk/AI_REFERENCE.md

@@ -757,29 +757,61 @@ const result = await sdk.{transition_name}(identityHex, ...params, privateKeyHex
 **Identity Create** - `identityCreate`
 *Create a new identity with initial credits*
 
-Parameters (in addition to identity/key):
-- `seedPhrase` (textarea, required) - Seed Phrase
-  - Example: `Enter seed phrase (12-24 words) or click Generate`
-- `generateSeedButton` (button, optional) - Generate New Seed
-- `identityIndex` (number, required) - Identity Index
-- `keySelectionMode` (select, required) - Key Selection Mode
-- `keyPreview` (keyPreview, optional) - Keys to be added
+Parameters:
+- `assetLockProof` (string, required) - Asset Lock Proof
+  - Hex-encoded JSON asset lock proof
+- `assetLockProofPrivateKey` (string, required) - Asset Lock Proof Private Key
+  - WIF format private key
+- `publicKeys` (string, required) - Public Keys
+  - JSON array of public keys
+
+Example:
+```javascript
+// Asset lock proof is a hex-encoded JSON object
+const assetLockProof = "a9147d3b... (hex-encoded)";
+const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+
+// Public keys array with proper key types
+const publicKeys = JSON.stringify([
+  {
+    id: 0,
+    type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2
+    purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc.
+    securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3
+    data: "A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ", // Base64-encoded public key
+    readOnly: false
+  },
+  {
+    id: 1,
+    type: 0,
+    purpose: 0,
+    securityLevel: 2,
+    data: "AnotherBase64EncodedPublicKeyHere", // Base64-encoded public key
+    readOnly: false
+  }
+]);
 
-Example:
-```javascript
-const result = await sdk.identityCreate(identityHex, /* params */, privateKeyHex);
+const result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys);
 ```
 
 **Identity Top Up** - `identityTopUp`
 *Add credits to an existing identity*
 
-Parameters (in addition to identity/key):
-- `identityId` (text, required) - Identity ID
-  - Example: `Enter the identity ID to top up (base58)`
+Parameters:
+- `identityId` (string, required) - Identity ID
+  - Base58 format identity ID
+- `assetLockProof` (string, required) - Asset Lock Proof
+  - Hex-encoded JSON asset lock proof
+- `assetLockProofPrivateKey` (string, required) - Asset Lock Proof Private Key
+  - WIF format private key
 
 Example:
 ```javascript
-const result = await sdk.identityTopUp(identityHex, /* params */, privateKeyHex);
+const identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58
+const assetLockProof = "a9147d3b... (hex-encoded)";
+const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+
+const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);
 ```
 
 **Identity Update** - `identityUpdate`

packages/wasm-sdk/api-definitions.json

@@ -1235,7 +1235,31 @@
               "label": "Keys to be added",
               "help": "These keys will be added to your new identity"
             }
-          ]
+          ],
+          "sdk_params": [
+            {
+              "name": "assetLockProof",
+              "type": "string",
+              "label": "Asset Lock Proof",
+              "required": true,
+              "description": "Hex-encoded JSON asset lock proof"
+            },
+            {
+              "name": "assetLockProofPrivateKey",
+              "type": "string",
+              "label": "Asset Lock Proof Private Key",
+              "required": true,
+              "description": "WIF format private key"
+            },
+            {
+              "name": "publicKeys",
+              "type": "string",
+              "label": "Public Keys",
+              "required": true,
+              "description": "JSON array of public keys"
+            }
+          ],
+          "sdk_example": "// Asset lock proof is a hex-encoded JSON object\nconst assetLockProof = \"a9147d3b... (hex-encoded)\";\nconst assetLockProofPrivateKey = \"XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1\"; // WIF format\n\n// Public keys array with proper key types\nconst publicKeys = JSON.stringify([\n  {\n    id: 0,\n    type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2\n    purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc.\n    securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3\n    data: \"A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ\", // Base64-encoded public key\n    readOnly: false\n  },\n  {\n    id: 1,\n    type: 0,\n    purpose: 0,\n    securityLevel: 2,\n    data: \"AnotherBase64EncodedPublicKeyHere\", // Base64-encoded public key\n    readOnly: false\n  }\n]);\n\nconst result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys);"
         },
         "identityTopUp": {
           "label": "Identity Top Up",
@@ -1249,7 +1273,31 @@
               "placeholder": "Enter the identity ID to top up (base58)",
               "help": "The identity ID that will receive the credits from the asset lock proof"
             }
-          ]
+          ],
+          "sdk_params": [
+            {
+              "name": "identityId",
+              "type": "string",
+              "label": "Identity ID",
+              "required": true,
+              "description": "Base58 format identity ID"
+            },
+            {
+              "name": "assetLockProof",
+              "type": "string",
+              "label": "Asset Lock Proof",
+              "required": true,
+              "description": "Hex-encoded JSON asset lock proof"
+            },
+            {
+              "name": "assetLockProofPrivateKey",
+              "type": "string",
+              "label": "Asset Lock Proof Private Key",
+              "required": true,
+              "description": "WIF format private key"
+            }
+          ],
+          "sdk_example": "const identityId = \"5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk\"; // base58\nconst assetLockProof = \"a9147d3b... (hex-encoded)\";\nconst assetLockProofPrivateKey = \"XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1\"; // WIF format\n\nconst result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);"
         },
         "identityUpdate": {
           "label": "Identity Update",

packages/wasm-sdk/docs.css

@@ -270,6 +270,8 @@ h3 {
     font-size: 0.9em;
     margin-bottom: 10px;
     position: relative;
+    white-space: pre-wrap;
+    overflow-x: auto;
 }
 
 .run-button {

packages/wasm-sdk/docs.html

@@ -1952,37 +1952,52 @@ <h4 id="transition-identityCreate">Identity Create</h4>
             <div class="parameters">
                 <h5>Parameters:</h5>
                 <div class="parameter">
-                    <span class="param-name">Seed Phrase</span>
-                    <span class="param-type">textarea</span>
+                    <span class="param-name">Asset Lock Proof</span>
+                    <span class="param-type">string</span>
                     <span class="param-required">(required)</span>
-                    <br><small>Example: Enter seed phrase (12-24 words) or click Generate</small>
-                </div>
-                <div class="parameter">
-                    <span class="param-name">Generate New Seed</span>
-                    <span class="param-type">button</span>
-                    <span class="param-optional">(optional)</span>
+                    <br><small>Hex-encoded JSON asset lock proof</small>
                 </div>
                 <div class="parameter">
-                    <span class="param-name">Identity Index</span>
-                    <span class="param-type">number</span>
+                    <span class="param-name">Asset Lock Proof Private Key</span>
+                    <span class="param-type">string</span>
                     <span class="param-required">(required)</span>
+                    <br><small>WIF format private key</small>
                 </div>
                 <div class="parameter">
-                    <span class="param-name">Key Selection Mode</span>
-                    <span class="param-type">select</span>
+                    <span class="param-name">Public Keys</span>
+                    <span class="param-type">string</span>
                     <span class="param-required">(required)</span>
-                    <br><small>Options: Default (Recommended), Advanced</small>
-                </div>
-                <div class="parameter">
-                    <span class="param-name">Keys to be added</span>
-                    <span class="param-type">keyPreview</span>
-                    <span class="param-optional">(optional)</span>
+                    <br><small>JSON array of public keys</small>
                 </div>
             </div>
 
             <div class="example-container">
                 <h5>Example</h5>
-                <div class="example-code">const result = await sdk.identityCreate(identityHex, /* params */, privateKeyHex);</div>            </div>
+                <div class="example-code">// Asset lock proof is a hex-encoded JSON object
+const assetLockProof = "a9147d3b... (hex-encoded)";
+const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+
+// Public keys array with proper key types
+const publicKeys = JSON.stringify([
+  {
+    id: 0,
+    type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2
+    purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc.
+    securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3
+    data: "A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ", // Base64-encoded public key
+    readOnly: false
+  },
+  {
+    id: 1,
+    type: 0,
+    purpose: 0,
+    securityLevel: 2,
+    data: "AnotherBase64EncodedPublicKeyHere", // Base64-encoded public key
+    readOnly: false
+  }
+]);
+
+const result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys);</div>            </div>
         </div>
         <div class="operation">
             <h4 id="transition-identityTopUp">Identity Top Up</h4>
@@ -1992,15 +2007,31 @@ <h4 id="transition-identityTopUp">Identity Top Up</h4>
                 <h5>Parameters:</h5>
                 <div class="parameter">
                     <span class="param-name">Identity ID</span>
-                    <span class="param-type">text</span>
+                    <span class="param-type">string</span>
+                    <span class="param-required">(required)</span>
+                    <br><small>Base58 format identity ID</small>
+                </div>
+                <div class="parameter">
+                    <span class="param-name">Asset Lock Proof</span>
+                    <span class="param-type">string</span>
                     <span class="param-required">(required)</span>
-                    <br><small>Example: Enter the identity ID to top up (base58)</small>
+                    <br><small>Hex-encoded JSON asset lock proof</small>
+                </div>
+                <div class="parameter">
+                    <span class="param-name">Asset Lock Proof Private Key</span>
+                    <span class="param-type">string</span>
+                    <span class="param-required">(required)</span>
+                    <br><small>WIF format private key</small>
                 </div>
             </div>
 
             <div class="example-container">
                 <h5>Example</h5>
-                <div class="example-code">const result = await sdk.identityTopUp(identityHex, /* params */, privateKeyHex);</div>            </div>
+                <div class="example-code">const identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58
+const assetLockProof = "a9147d3b... (hex-encoded)";
+const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+
+const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);</div>            </div>
         </div>
         <div class="operation">
             <h4 id="transition-identityUpdate">Identity Update</h4>

packages/wasm-sdk/docs_manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2025-08-18T16:09:12.996174+00:00",
+  "generated_at": "2025-08-18T19:21:21.062910+00:00",
   "queries": {
     "getIdentity": {
       "category": "identity",

packages/wasm-sdk/generate_docs.py

@@ -245,11 +245,15 @@ def generate_operation_entry(operation_key, operation, type_prefix):
                 <h5>Parameters:</h5>
 '''
 
+    # Use sdk_params if available (for state transitions), otherwise use inputs
+    sdk_params = operation.get('sdk_params', [])
     inputs = operation.get('inputs', [])
-    if not inputs:
+    params_to_use = sdk_params if sdk_params else inputs
+    
+    if not params_to_use:
         html_content += '                <p class="param-optional">No parameters required</p>'
     else:
-        for param in inputs:
+        for param in params_to_use:
             html_content += generate_parameter_entry(param)
 
     html_content += '''            </div>
@@ -297,7 +301,7 @@ def generate_operation_entry(operation_key, operation, type_prefix):
         html_content += f'\n                <div class="example-result" id="result-{operation_key}"></div>'
     else:
         # State transitions don't have run buttons
-        html_content += f'                <div class="example-code">{generate_transition_example(operation_key)}</div>'
+        html_content += f'                <div class="example-code">{generate_transition_example(operation_key, operation)}</div>'
 
     html_content += '''            </div>
         </div>
@@ -312,7 +316,9 @@ def generate_parameter_entry(param):
                     <span class="param-type">{param.get('type', 'text')}</span>
                     {required_text}
 '''
-    if param.get('placeholder'):
+    if param.get('description'):
+        html_content += f'                    <br><small>{html_lib.escape(param.get("description"))}</small>\n'
+    elif param.get('placeholder'):
         html_content += f'                    <br><small>Example: {html_lib.escape(param.get("placeholder"))}</small>\n'
     elif param.get('name') == 'limit' and not param.get('required', False):
         html_content += '                    <br><small>Default: 100 (maximum items returned if not specified)</small>\n'
@@ -324,8 +330,12 @@ def generate_parameter_entry(param):
     html_content += '                </div>\n'
     return html_content
 
-def generate_transition_example(trans_key):
+def generate_transition_example(trans_key, transition=None):
     """Generate example code for state transitions"""
+    # Check if there's a custom sdk_example
+    if transition and transition.get('sdk_example'):
+        return transition.get('sdk_example')
+    
     if trans_key == 'documentCreate':
         return '''const result = await sdk.document_create(
     identityHex,
@@ -1670,27 +1680,40 @@ def generate_ai_reference_md(query_defs, transition_defs):
             md_content += f"\n**{transition.get('label', trans_key)}** - `{trans_key}`\n"
             md_content += f"*{transition.get('description', 'No description')}*\n\n"
 
-            # Parameters
+            # Parameters - use sdk_params if available, otherwise fall back to inputs
+            sdk_params = transition.get('sdk_params', [])
             inputs = transition.get('inputs', [])
-            if inputs:
+            params_to_use = sdk_params if sdk_params else inputs
+            
+            # Adjust parameter section header based on whether we're using SDK params
+            if sdk_params:
+                md_content += "Parameters:\n"
+            elif inputs:
                 md_content += "Parameters (in addition to identity/key):\n"
-                for param in inputs:
+            
+            if params_to_use:
+                for param in params_to_use:
                     req = "required" if param.get('required', False) else "optional"
                     md_content += f"- `{param.get('name', 'unknown')}` ({param.get('type', 'text')}, {req})"
 
                     if param.get('label') and param.get('label') != param.get('name'):
                         md_content += f" - {param.get('label')}"
 
-                    if param.get('placeholder'):
+                    if param.get('description'):
+                        md_content += f"\n  - {param.get('description')}"
+                    elif param.get('placeholder'):
                         md_content += f"\n  - Example: `{param.get('placeholder')}`"
 
                     md_content += "\n"
 
             # Example
             md_content += f"\nExample:\n```javascript\n"
 
-            # Generate specific examples
-            if trans_key == 'documentCreate':
+            # Check if there's a custom sdk_example
+            sdk_example = transition.get('sdk_example')
+            if sdk_example:
+                md_content += sdk_example
+            elif trans_key == 'documentCreate':
                 md_content += '''const result = await sdk.document_create(
     identityHex,
     contractId,