detailed usage-example

ordpool-space · Dec 13, 2023 · 158e86d · 158e86d
1 parent 6931fab
commit 158e86d
Show file tree

Hide file tree

Showing 4 changed files with 155 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -5,11 +5,63 @@ The compiled code has zero dependencies and works in the Browser and in Node.js
 
 The latest version of this script is used by https://ordpool.space
 
-## Prerequisites
 
-Node.js (Version 20 or later) to test & compile the TypeScript code to JavaScript.
+## 🚀 Usage
+
+This package has zero dependencies and should "just work". First, install it:
+
+```
+npm install ordpool-parser
+```
+
+Then, you can use the parser in your project. 
+It expects a transaction from the Mempool API:
+
+```ts
+import axios from 'axios';
+import { InscriptionParserService } from 'ordpool-parser';
+
+async function getInscription(txId) {
+
+  const response = await axios.get(`https://mempool.space/api/tx/${txId}`);
+  const transaction = response.data;
+
+  const parser = new InscriptionParserService();
+  const parsedInscription = parser.parseInscription(transaction);
+
+  return parsedInscription;
+}
+
+const parsedInscription = await getInscription('f1997166547da9784a3e7419d2b248551565211811d4f5e705b685efa244451f');
 
-## Contribute
+if (!parsedInscription) {
+  console.log('No inscription found!');
+} else {
+  // Output: text/html;charset=utf-8
+  console.log(parsedInscription.contentType);
+
+  // UTF-8 encoded string (not intended for binary content like images or videos)
+  // Output: <html><!--cubes.haushoppe.art--><body> [...]
+  console.log(parsedInscription.getContentString());
+
+  // Base64 encoded data URI that can be displayed in an iframe
+  // Output: data:text/html;charset=utf-8;base64,PGh0bWw+PCEtLWN1YmVzLmhhdXNob3BwZS5hcnQtLT48Ym9keT4 [...]
+  console.log(parsedInscription.getDataUri());
+}
+
+```
+
+This example uses `axios`, a popular HTTP client for both browser and Node.js environments. 
+You can install it via `npm install axios`. Of course, any other compatible HTTP client will also work.
+
+**Note:** This is a simplified example! Make sure to handle errors when making HTTP requests, as network issues can occur.
+
+
+## 🧡 Contribute
+
+### Prerequisites
+
+Node.js (Version 20 or later) to test & compile the TypeScript code to JavaScript.
 
 First, install Node.js version 20. 
 Then, install the NPM dependencies and execute the tests with the following commands:
@@ -23,7 +75,7 @@ Every feature must be tested in the browser and in the node environment!
 Use a mainnet transaction to create a test scenario. 
 The goal of this parser is to parse byte-perfect inscriptions that are identical to [ord](https://github.com/ordinals/ord).
 
-Steps:
+### Steps
 
 1. **Fetch Transaction Test Data**: Save the raw transaction JSON to the `testdata` folder.
     ```bash
@@ -40,9 +92,9 @@ Steps:
 
 3. **Contribute:** Add your new feature, include meaningful tests, and submit a pull request if all tests pass.
 
-**Hint:** Debug the unit tests using VS Code. The `launch.json` file is already prepared for this purpose.
+4. **Hint:** Debug the unit tests using VS Code. The `launch.json` file is already prepared for this purpose.
 
-## Build
+### Build
 
 To build a version without the tests:
 
@@ -56,7 +108,8 @@ To publish a new version to NPM:
 npm run publish
 ```
 
-## Learn More
+## 📙 Learn More
 
+- Ordpool: https://ordpool.space
 - What is an Inscription "envelope"?: https://blog.ordinalhub.com/what-is-an-envelope/
 - The Cursed Inscriptions Rabbithole: https://youtu.be/cpAh5_KhvMg
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -2,19 +2,23 @@
   "name": "ordpool-parser",
   "version": "0.0.1",
   "description": "The parsing engine that detects inscriptions in Bitcoin transactions.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haushoppe/ordpool-parser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/haushoppe/ordpool-parser/issues"
+  },
   "main": "dist/index.js",
   "scripts": {
     "clean": "rimraf dist",
-    "build": "npm run clean && tsc tsconfig.build.json",
+    "build": "npm run clean && tsc --project tsconfig.build.json",
     "start": "npm run test",
     "test": "npm run test:node && npm run test:browser",
-
-    "test:node":          "npm run clean && jest --config jest.config.node.js",
-    "test:node:watch":    "npm run clean && jest --config jest.config.node.js --watch ",
-
-    "test:browser":       "npm run clean && jest --config jest.config.js",
+    "test:node": "npm run clean && jest --config jest.config.node.js",
+    "test:node:watch": "npm run clean && jest --config jest.config.node.js --watch ",
+    "test:browser": "npm run clean && jest --config jest.config.js",
     "test:browser:watch": "npm run clean && jest --config jest.config.js --watch ",
-
     "fetch-tx-testdata": "node fetch-tx-testdata.js",
     "fetch-inscription-testdata": "node fetch-inscription-testdata.js",
     "prepublishOnly": "npm run test && npm run build"
@@ -33,11 +37,16 @@
   "devDependencies": {
     "@types/jest": "^29.5.11",
     "@types/node": "^20.10.4",
+    "axios": "^1.6.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "mime-types": "^2.1.35",
     "rimraf": "^5.0.5",
     "ts-jest": "^29.1.1",
     "typescript": "^5.3.3"
-  }
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
 }
diff --git a/src/usage-example.spec.ts b/src/usage-example.spec.ts
@@ -0,0 +1,40 @@
+import axios from 'axios';
+import { InscriptionParserService } from './inscription-parser.service';
+
+
+describe('Real data usage example (see README)', () => {
+  it('shows you how to use the parser with axios', async () => {
+
+    async function getInscription(txId: string) {
+
+      const response = await axios.get(`https://mempool.space/api/tx/${txId}`);
+      const transaction = response.data;
+
+      const parser = new InscriptionParserService();
+      const parsedInscription = parser.parseInscription(transaction);
+
+      return parsedInscription;
+    }
+
+    const parsedInscription = await getInscription('f1997166547da9784a3e7419d2b248551565211811d4f5e705b685efa244451f');
+
+    if (!parsedInscription) {
+      console.log('No inscription found!');
+    } else {
+      // Output: text/html;charset=utf-8
+      // console.log(parsedInscription.contentType);
+
+      // UTF-8 encoded string (not intended for binary content like images or videos)
+      // Output: <html><!--cubes.haushoppe.art--><body> [...]
+      // console.log(parsedInscription.getContentString());
+
+      // Base64 encoded data URI that can be displayed in an iframe
+      // Output: data:text/html;charset=utf-8;base64,PGh0bWw+PCEtLWN1YmVzLmhhdXNob3BwZS5hcnQtLT48Ym9keT4 [...]
+      // console.log(parsedInscription.getDataUri());
+    }
+
+    expect(parsedInscription?.contentType).toBe('text/html;charset=utf-8');
+    expect(parsedInscription?.getContentString()).toBe("<html><!--cubes.haushoppe.art--><body><script>t='ab2f4e9dce0583264078428a91aa9037da0e75f90dc77fe3cba7cf5320ad003di0|dda7470b6d5bbeea6560a167f56a048aa29ce71f57edc7b71cf5df365ddbddaei0|dda7470b6d5bbeea6560a167f56a048aa29ce71f57edc7b71cf5df365ddbddaei0|dda7470b6d5bbeea6560a167f56a048aa29ce71f57edc7b71cf5df365ddbddaei0|dda7470b6d5bbeea6560a167f56a048aa29ce71f57edc7b71cf5df365ddbddaei0|dda7470b6d5bbeea6560a167f56a048aa29ce71f57edc7b71cf5df365ddbddaei0'</script><script src=/content/9475aa8df559d569f7284ce59e97014f28be758e832e212fdbba0202699dd035i0></script>");
+    expect(parsedInscription?.getDataUri()).toBe('data:text/html;charset=utf-8;base64,PGh0bWw+PCEtLWN1YmVzLmhhdXNob3BwZS5hcnQtLT48Ym9keT48c2NyaXB0PnQ9J2FiMmY0ZTlkY2UwNTgzMjY0MDc4NDI4YTkxYWE5MDM3ZGEwZTc1ZjkwZGM3N2ZlM2NiYTdjZjUzMjBhZDAwM2RpMHxkZGE3NDcwYjZkNWJiZWVhNjU2MGExNjdmNTZhMDQ4YWEyOWNlNzFmNTdlZGM3YjcxY2Y1ZGYzNjVkZGJkZGFlaTB8ZGRhNzQ3MGI2ZDViYmVlYTY1NjBhMTY3ZjU2YTA0OGFhMjljZTcxZjU3ZWRjN2I3MWNmNWRmMzY1ZGRiZGRhZWkwfGRkYTc0NzBiNmQ1YmJlZWE2NTYwYTE2N2Y1NmEwNDhhYTI5Y2U3MWY1N2VkYzdiNzFjZjVkZjM2NWRkYmRkYWVpMHxkZGE3NDcwYjZkNWJiZWVhNjU2MGExNjdmNTZhMDQ4YWEyOWNlNzFmNTdlZGM3YjcxY2Y1ZGYzNjVkZGJkZGFlaTB8ZGRhNzQ3MGI2ZDViYmVlYTY1NjBhMTY3ZjU2YTA0OGFhMjljZTcxZjU3ZWRjN2I3MWNmNWRmMzY1ZGRiZGRhZWkwJzwvc2NyaXB0PjxzY3JpcHQgc3JjPS9jb250ZW50Lzk0NzVhYThkZjU1OWQ1NjlmNzI4NGNlNTllOTcwMTRmMjhiZTc1OGU4MzJlMjEyZmRiYmEwMjAyNjk5ZGQwMzVpMD48L3NjcmlwdD4=');
+  });
+});