Add tutorial documentation

Author: maria-robobug

_code-samples/issue-credentials/js/.env

@@ -1,2 +1,2 @@
-ISSUER_ACCOUNT_SEED="<your_issuer_account_seed>"
+ISSUER_ACCOUNT_SEED=<your-seed-goes-here>
 PORT=3005

_code-samples/issue-credentials/js/accept_credential.js

@@ -4,7 +4,9 @@ import dotenv from "dotenv";
 import inquirer from "inquirer";
 import { Client, Wallet } from "xrpl";
 import { lookUpCredentials } from "./look_up_credentials.js";
-import { decodeHex } from "./utils.js";
+import { decodeHex } from "./decode_hex.js";
+
+const XRPL_SERVER = "wss://s.devnet.rippletest.net:51233"
 
 dotenv.config();
 
@@ -19,28 +21,27 @@ async function initWallet() {
         validate: (input) => (input ? true : "Please specify the subject's master seed"),
       },
     ]);
-
     seed = seedInput;
   }
 
   return Wallet.fromSeed(seed);
 }
 
 async function main() {
-  const XRPL_SERVER = "wss://s.devnet.rippletest.net:51233"
   const client = new Client(XRPL_SERVER);
   await client.connect();    
 
   const wallet = await initWallet();
 
-  const pendingCredentials = await lookUpCredentials(client, "", wallet.address, "no");
-  if (pendingCredentials.length === 0) {
-    console.log("No pending credentials to accept");
-    process.exit(0);
-  }
+  const pendingCredentials = await lookUpCredentials(
+    client,
+    "",
+    wallet.address,
+    "no"
+  );
 
   const choices = pendingCredentials.map((cred, i) => ({
-    name: `${i+1})'${decodeHex(cred.CredentialType)}' issued by ${cred.Issuer}`,
+    name: `${i+1}) '${decodeHex(cred.CredentialType)}' issued by ${cred.Issuer}`,
     value: i,
   }));
   choices.unshift({ name: "0) No, quit.", value: -1 });

_code-samples/issue-credentials/js/credential.js

@@ -1,12 +1,11 @@
 import {
-  strToHex,
-  decodeHex,
-  datetimeToRippleTime,
-  rippleTimeToDatetime,
-} from "./utils.js";
-
-import { isValidClassicAddress } from "xrpl";
+  isoTimeToRippleTime,
+  rippleTimeToISOTime,
+  isValidClassicAddress,
+} from "xrpl";
+import { stringToHex } from "@xrplf/isomorphic/dist/utils/index.js";
 
+import { decodeHex } from "./decode_hex.js";
 import { ValueError } from "./errors.js";
 
 // Regex constants
@@ -15,7 +14,6 @@ const URI_REGEX = /^[A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]{1,256}$/;
 
 /**
  * Validate credential request.
- *
  * This function performs parameter validation. Validated fields:
  *   - subject (required): the subject of the credential, as a classic address
  *   - credential (required): the credential type, in human-readable (ASCII) chars
@@ -35,19 +33,16 @@ export function validateCredentialRequest({ subject, credential, uri, expiration
   if (typeof credential !== "string") {
     throw new ValueError("Must provide a string 'credential' field");
   }
-
-  /* 
-  Checks if the specified credential type is one that this service issues. 
-
-  XRPL credential types can be any binary data; this service issues
-  any credential that can be encoded from the following ASCII chars:
-  alphanumeric characters, underscore, period, and dash.
-  (min length 1, max 64)
-
-  You might want to further limit the credential types, depending on your 
-  use case; for example, you might only issue one specific credential type.
-  */
   if (!CREDENTIAL_REGEX.test(credential)) {
+    /**
+     * Checks if the specified credential type is one that this service issues.
+     * XRPL credential types can be any binary data; this service issues
+     * any credential that can be encoded from the following ASCII chars:
+     * alphanumeric characters, underscore, period, and dash. (min length 1, max 64)
+     *
+     * You might want to further limit the credential types, depending on your
+     * use case; for example, you might only issue one specific credential type.
+     */
     throw new ValueError(`credential not allowed: '${credential}'.`);
   }
 
@@ -76,12 +71,10 @@ export function validateCredentialRequest({ subject, credential, uri, expiration
   // Validate and parse expiration
   let parsedExpiration;
   if (expiration !== undefined) {
-    if (typeof expiration === "string") {
-      parsedExpiration = new Date(expiration);
-    } else {
+    if (typeof expiration !== "string") {
       throw new ValueError(`Unsupported expiration format: ${typeof expiration}`);
     }
-
+    parsedExpiration = new Date(expiration);
     if (isNaN(parsedExpiration.getTime())) {
       throw new ValueError(`Invalid expiration date: ${expiration}`);
     }
@@ -95,20 +88,41 @@ export function validateCredentialRequest({ subject, credential, uri, expiration
   };
 }
 
-/**
- * As a credential issuer, you typically need to verify some information
- * about someone before you issue them a credential. For this example,
- * the user passes relevant information in a documents field of the API request.
- * The documents are kept confidential, off-chain.
- */
-export function verifyDocuments({documents}) {
-  /* 
-    This is where you would check the user's documents to see if you
-    should issue the requested Credential to them.
-    Depending on the type of credentials your service needs, you might
-    need to implement different types of checks here.
+// Convert an XRPL ledger entry into a usable credential object
+export function credentialFromXrpl(entry) {
+  const { Subject, CredentialType, URI, Expiration, Flags } = entry;
+  return {
+    subject: Subject,
+    credential: decodeHex(CredentialType),
+    uri: URI ? decodeHex(URI) : undefined,
+    expiration: Expiration ? rippleTimeToISOTime(Expiration) : undefined,
+    accepted: Boolean(Flags & 0x00010000), // lsfAccepted
+  };
+}
+
+// Convert to an object in a format closer to the XRP Ledger representation
+export function credentialToXrpl(cred) {
+   // Credential type and URI are hexadecimal;
+   // Expiration, if present, is in seconds since the Ripple Epoch.
+  return {
+    subject: cred.subject,
+    credential: stringToHex(cred.credential),
+    uri: cred.uri ? stringToHex(cred.uri) : undefined,
+    expiration: cred.expiration
+      ? isoTimeToRippleTime(cred.expiration)
+      : undefined,
+  };
+}
+
+
+export function verifyDocuments({ documents }) {
+ /**
+  * This is where you would check the user's documents to see if you
+  * should issue the requested Credential to them.
+  * Depending on the type of credentials your service needs, you might
+  * need to implement different types of checks here.
   */
-  if (typeof documents !== 'object' || Object.keys(documents).length === 0) {
+  if (typeof documents !== "object" || Object.keys(documents).length === 0) {
     throw new ValueError("you must provide a non-empty 'documents' field");
   }
 
@@ -123,50 +137,3 @@ export function verifyDocuments({documents}) {
     throw new ValueError("reason must include 'please'");
   }
 }
-
-/**
- * Convert to a Credential object in a format closer to the XRP Ledger representation.
- * Credential type and URI are hexadecimal;
- * Expiration, if present, is in seconds since the Ripple Epoch.
- */
-export function credentialToXrpl(cred) {
-  return {
-    subject: cred.subject,
-    credential: strToHex(cred.credential),
-    uri: cred.uri ? strToHex(cred.uri) : undefined,
-    expiration: cred.expiration ? datetimeToRippleTime(cred.expiration) : undefined,
-  };
-}
-
-// Convert an XRPL ledger entry into a usable  credential object
-export function parseCredentialFromXrpl(entry) {
-  const { Subject, CredentialType, URI, Expiration, Flags } = entry;
-
-  if (!Subject || !CredentialType) {
-    throw new Error("Missing required fields from XRPL credential entry");
-  }
-
-  return {
-    subject: Subject,
-    credential: decodeHex(CredentialType),
-    uri: URI ? decodeHex(URI) : undefined,
-    expiration: Expiration ? rippleTimeToDatetime(Expiration) : undefined,
-    accepted: Boolean(Flags & 0x00010000), // lsfAccepted
-  };
-}
-
-/**
- * Convert a credential object into API-friendly JSON
- */
-export function serializeCredential(cred) {
-  const result = {
-    subject: cred.subject,
-    credential: cred.credential,
-  };
-
-  if (cred.uri) result.uri = cred.uri;
-  if (cred.expiration) result.expiration = cred.expiration.toISOString();
-  if (cred.accepted !== undefined) result.accepted = cred.accepted;
-
-  return result;
-}

_code-samples/issue-credentials/js/decode_hex.js

@@ -0,0 +1,14 @@
+export function decodeHex(sHex) {
+  /**
+   * Try decoding a hex string as ASCII; return the decoded string on success,
+   * or the un-decoded string prefixed by '(BIN) ' on failure.
+   */
+  try {
+    const buffer = Buffer.from(sHex, "hex");
+    return buffer.toString("ascii");
+    // Could use utf-8 instead, but it has more edge cases.
+    // Optionally, sanitize the string for display before returning
+  } catch (err) {
+    return "(BIN) " + sHex;
+  }
+}