From 158e86ddbd88ff957ab4ff2977ece1a9bad97365 Mon Sep 17 00:00:00 2001 From: Hans Crypto Date: Wed, 13 Dec 2023 11:31:39 +0100 Subject: [PATCH] detailed usage-example --- README.md | 67 +++++++++++++++++++++++++++++++++++---- package-lock.json | 38 ++++++++++++++++++++++ package.json | 25 ++++++++++----- src/usage-example.spec.ts | 40 +++++++++++++++++++++++ 4 files changed, 155 insertions(+), 15 deletions(-) create mode 100644 src/usage-example.spec.ts diff --git a/README.md b/README.md index 6e5947d..013f56e 100644 --- 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: [...] + 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 index b976caa..92afd31 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,6 +11,7 @@ "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", @@ -1458,6 +1459,17 @@ "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", "dev": true }, + "node_modules/axios": { + "version": "1.6.2", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.6.2.tgz", + "integrity": "sha512-7i24Ri4pmDRfJTR7LDBhsOTtcm+9kjX5WiY1X3wIisx6G9So3pfMkEiU7emUBe46oceVImccTEM3k6C5dbVW8A==", + "dev": true, + "dependencies": { + "follow-redirects": "^1.15.0", + "form-data": "^4.0.0", + "proxy-from-env": "^1.1.0" + } + }, "node_modules/babel-jest": { "version": "29.7.0", "resolved": "https://registry.npmjs.org/babel-jest/-/babel-jest-29.7.0.tgz", @@ -2195,6 +2207,26 @@ "node": ">=8" } }, + "node_modules/follow-redirects": { + "version": "1.15.3", + "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.3.tgz", + "integrity": "sha512-1VzOtuEM8pC9SFU1E+8KfTjZyMztRsgEfwQl44z8A25uy13jSzTj6dyK2Df52iV0vgHCfBwLhDWevLn95w5v6Q==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/RubenVerborgh" + } + ], + "engines": { + "node": ">=4.0" + }, + "peerDependenciesMeta": { + "debug": { + "optional": true + } + } + }, "node_modules/foreground-child": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.1.1.tgz", @@ -3842,6 +3874,12 @@ "node": ">= 6" } }, + "node_modules/proxy-from-env": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", + "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", + "dev": true + }, "node_modules/psl": { "version": "1.9.0", "resolved": "https://registry.npmjs.org/psl/-/psl-1.9.0.tgz", diff --git a/package.json b/package.json index 2e78ec1..ad52eee 100644 --- 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 new file mode 100644 index 0000000..4b75b1e --- /dev/null +++ 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: [...] + // 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(""); + expect(parsedInscription?.getDataUri()).toBe('data:text/html;charset=utf-8;base64,PGh0bWw+PCEtLWN1YmVzLmhhdXNob3BwZS5hcnQtLT48Ym9keT48c2NyaXB0PnQ9J2FiMmY0ZTlkY2UwNTgzMjY0MDc4NDI4YTkxYWE5MDM3ZGEwZTc1ZjkwZGM3N2ZlM2NiYTdjZjUzMjBhZDAwM2RpMHxkZGE3NDcwYjZkNWJiZWVhNjU2MGExNjdmNTZhMDQ4YWEyOWNlNzFmNTdlZGM3YjcxY2Y1ZGYzNjVkZGJkZGFlaTB8ZGRhNzQ3MGI2ZDViYmVlYTY1NjBhMTY3ZjU2YTA0OGFhMjljZTcxZjU3ZWRjN2I3MWNmNWRmMzY1ZGRiZGRhZWkwfGRkYTc0NzBiNmQ1YmJlZWE2NTYwYTE2N2Y1NmEwNDhhYTI5Y2U3MWY1N2VkYzdiNzFjZjVkZjM2NWRkYmRkYWVpMHxkZGE3NDcwYjZkNWJiZWVhNjU2MGExNjdmNTZhMDQ4YWEyOWNlNzFmNTdlZGM3YjcxY2Y1ZGYzNjVkZGJkZGFlaTB8ZGRhNzQ3MGI2ZDViYmVlYTY1NjBhMTY3ZjU2YTA0OGFhMjljZTcxZjU3ZWRjN2I3MWNmNWRmMzY1ZGRiZGRhZWkwJzwvc2NyaXB0PjxzY3JpcHQgc3JjPS9jb250ZW50Lzk0NzVhYThkZjU1OWQ1NjlmNzI4NGNlNTllOTcwMTRmMjhiZTc1OGU4MzJlMjEyZmRiYmEwMjAyNjk5ZGQwMzVpMD48L3NjcmlwdD4='); + }); +});