input-output-hk · hrajchert · Sep 26, 2023 · Sep 6, 2023 · Sep 6, 2023 · Sep 6, 2023
diff --git a/.gitignore b/.gitignore
@@ -18,9 +18,11 @@ source
 dist
 test-dist
 
+.cache
+.local
 package-lock.json
 yarn.lock
 # nixago: ignore-linked-files
 /lefthook.yml
 /.editorconfig
-/treefmt.toml
+/treefmt.toml
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}
diff --git a/Readme.md b/Readme.md
@@ -1,5 +1,5 @@
 <div align="left">
-    <img src="./doc/image/logo.svg" alt="Logo" width="100" height="100"> 
+    <img src="./doc/image/logo.svg" alt="Logo" width="100" height="100">
 </div>
 
 Official Links
@@ -14,68 +14,41 @@ Official Links
 
 # Overview
 
-`marlowe-ts-sdk` is a suite of **TypeScript/JavaScript** libraries for Web Cardano Dapp Development using Marlowe Technologies.
-
-It is composed of the following [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces) :
-
-- Language
-  - [@marlowe.io/language-core-v1](./packages/language/core/v1/)
-    - Marlowe Core V1 constructs
-    - JSON Codec
-- Cardano Wallet
-  - [@marlowe.io/wallet](./packages/runtime/core/)
-    - Wallet Extension Capabalities (Browser / CIP-30)
-    - Single Wallet Address Capabalities(NodeJS / Version used for e2e tests only)
-- Runtime
-  - [@marlowe.io/runtime-lifecycle](./packages/runtime/lifecycle/) : Entry Point for Running remotely Marlowe Contracts over a backend instance of the runtime using a connected wallet.
-    - Marlowe Tx Commands
-      - Create
-      - Applying Inputs
-      - Withdraws
-    - Query capabilities for supporting these commands
-  - [@marlowe.io/runtime-core](./packages/runtime/core/) : core concepts used throughout the runtime libraries.
-  - [@marlowe.io/runtime-rest-client](./packages/runtime/client/rest/) : client of the runtime rest api.
-- Infrastruture Supporting SubDomains
-  - [@marlowe.io/adapter](./packages/adapter) : supporting set of libraries for Marlowe and Runtime Core Domains.
-
-# Get Started
+The **Marlowe TS-SDK** is a suite of _TypeScript/JavaScript_ libraries for developing Web-Dapp in the Cardano Blockchain using Marlowe Technologies.
+
+It is composed of several npm packages documented in the [API reference](https://input-output-hk.github.io/marlowe-ts-sdk/) page.
 
 ## Prerequesites
 
-- Runtime instance available : How to ? (TODO)
-- Wallet Extension installed : (TODO)
+In order to start working with the Marlowe SDK you need to have a URL to a running instance of the Marlowe Runtime and one of the supported wallet extensions installed in your browser.
+
+To get a running instance of the Runtime, it is recommended to check out the instructions on the [Marlowe Starter Kit](https://github.com/input-output-hk/marlowe-starter-kit)
 
 ## Wallet Extensions
 
 ### Compatible
 
-- Nami
-- Eternl
+- [Nami](https://namiwallet.io/)
+- [Eternl](https://eternl.io/)
 
-### Non Compatiible
+### Non Compatible
 
-- Lace
+- Lace: TODO: add github issue with the current problem
 
 ### Non Tested
 
 - TODO
 
-## NPM
-
-```bash
-npm install @marlowe.io/adapter @marlowe.io/wallet @marlowe.io/language-core-v1 @marlowe.io/runtime @marlowe.io/runtime-core @marlowe.io/runtime-rest-client
-```
-
 ## Examples
 
-- TODO
+Inside the [pocs folder](./pocs/Readme.md) you can find a set of minimal examples on how to use different packages of the SDK.
+
+- [wallet flow](./pocs/wallet-flow.html): Simple example on how to use the `@marlowe.io/wallet` package to connect to a wallet extension and get basic info.
 
-## Basic usage
+More elaborate examples can be found in the following repositories:
 
-```
-TODO
-```
+- [marlowe-payouts](https://github.com/input-output-hk/marlowe-payouts)
 
 # Development
 
-see documentation [here](./doc/howToDevelop.md).
+To help in the development of this SDK, please refer to [this document](./doc/howToDevelop.md).
diff --git a/changelog.d/20230905_171509_hrajchert_PLT_7420_add_prettier_precommit.md b/changelog.d/20230905_171509_hrajchert_PLT_7420_add_prettier_precommit.md
@@ -1,3 +1,3 @@
-### Changed
+### General
 
 - Reformat code with [prettier](https://prettier.io/) and [alejandra](https://github.com/kamadorueda/alejandra) using the [treefmt](https://github.com/numtide/treefmt-nix) tool
diff --git a/changelog.d/20230906_120715_hrajchert_PLT_7308_remove_fpts_wallet_api.md b/changelog.d/20230906_120715_hrajchert_PLT_7308_remove_fpts_wallet_api.md
@@ -0,0 +1,4 @@
+### @marlowe.io/wallet
+
+- Added typedoc documentation.
+- Renamed the `pocs/runtimeCIP30Flow.html` to `pocs/wallet-flow.html` and modified it to highlight the wallet capabilities.
diff --git a/changelog.d/20230907_174927_hrajchert_PLT_7308_remove_fp_ts_from_wallet.md b/changelog.d/20230907_174927_hrajchert_PLT_7308_remove_fp_ts_from_wallet.md
@@ -0,0 +1,4 @@
+### @marlowe.io/wallet
+
+- **BREAKING CHANGE:** Removed `fp-ts` from the user facing API.
+- **BREAKING CHANGE:** In the browser module `getExtensionInstance` was renamed to `createBrowserWallet`
diff --git a/changelog.d/20230908_172649_hrajchert_PLT_7308_remove_fp_ts_from_wallet.md b/changelog.d/20230908_172649_hrajchert_PLT_7308_remove_fp_ts_from_wallet.md
@@ -0,0 +1,3 @@
+### @marlowe.io/runtime-lifecycle
+
+- **BREAKING CHANGE:** Removed `fp-ts` from the user facing API
diff --git a/changelog.d/20230915_134506_hrajchert_PLT_7498_improve_sdk_import.md b/changelog.d/20230915_134506_hrajchert_PLT_7498_improve_sdk_import.md
@@ -0,0 +1,3 @@
+### General
+
+- Improved the way the SDK gets imported in the browser by the use of importmaps. Included import documentation in each package.
diff --git a/changelog.d/20230925_144650_nicolas.henin.md b/changelog.d/20230925_144650_nicolas.henin.md
@@ -0,0 +1,7 @@
+### @marlowe.io/wallet
+
+- renamed renamed createBrowserWallet to mkBrowserWallet
+
+### @marlowe.io/runtime-lifecycle
+
+- Fixed `this undefined` issues when calling `mkRuntimeLifecycle`
diff --git a/changelog.d/20230925_203338_hrajchert_PLT_7501_remove_fpts_from_rest_client.md b/changelog.d/20230925_203338_hrajchert_PLT_7501_remove_fpts_from_rest_client.md
@@ -0,0 +1,3 @@
+### @marlowe.io/runtime-rest-client
+
+- BREAKING CHANGE: Replaced mkRestClient interface for a flat API that resembles the backend documentation structure.
diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini
@@ -1,3 +1,3 @@
 [scriv]
 format = md
-version = 1.0.0.0
+categories = General, @marlowe.io/wallet, @marlowe.io/adapter, @marlowe.io/language-core-v1, @marlowe.io/runtime-rest-client, @marlowe.io/runtime-core, @marlowe.io/runtime-lifecycle
diff --git a/doc/howToDevelop.md b/doc/howToDevelop.md
@@ -94,3 +94,61 @@ $ scriv create
 ```
 
 edit the new file with appropriate content for your PR and commit it. Read [the documentation for scriv](https://scriv.readthedocs.io/en) to learn more about how to use this tool.
+
+To collect all changelog entries into a single file, execute `std` from the nix shell and run the `build-changelog` script. This command will delete all entries from the `changelog.d` folder and update the `CHANGELOG.md` file.
+
+## Publish
+
+For the moment the SDK is manually published to npm. Task PLT-6939 captures the work to automate this process through the CI.
+
+Before publishing it is convinient to check that the artifacts works as expected :
+
+- Clean & Build
+
+```bash
+$ npm run clean && npm run build
+```
+
+- Test
+
+```bash
+$ npm t && npm run test:e2e
+```
+
+- Check the packages
+  To test this you can pack all the different packages into tarballs using
+
+```bash
+$ npm --workspaces pack --pack-destination dist
+```
+
+And in a separate project you can install the tarballs using a file url when declaring the dependency
+
+```json
+{
+  "dependencies": {
+    "@marlowe.io/runtime-lifecycle": "file:<path-to-dist>/marlowe.io-runtime-lifecycle-0.2.0-alpha-3.tgz",
+    "@marlowe.io/runtime-rest-client": "file:<path-to-dist>/marlowe.io-runtime-rest-client-0.2.0-alpha-3.tgz",
+    "@marlowe.io/adapter": "file:<path-to-dist>/marlowe.io-adapter-0.2.0-alpha-3.tgz",
+    "@marlowe.io/runtime-core": "file:<path-to-dist>/marlowe.io-runtime-core-0.2.0-alpha-3.tgz",
+    "@marlowe.io/language-core-v1": "file:<path-to-dist>/marlowe.io-language-core-v1-0.2.0-alpha-3.tgz",
+    "@marlowe.io/wallet": "file:<path-to-dist>/marlowe.io-wallet-0.2.0-alpha-3.tgz"
+  }
+}
+```
+
+TODO [[Publish pre-check]] Local map and this pack instructions
+TODO instructions on how to manually publish
+In order to check that the export/import mechanism works on the browser using import maps you can:
+
+1. Create a testing branch in a fork of the repo
+1. Clean and build the project `npm run clean && npm run build`
+1. Remove `dist` from `.gitignore`
+1. Commit the `dist` folders of the different packages
+1. Get the full git hash of the commit using `git rev-parse HEAD`
+1. Publish the branch in your fork
+1. Modify `rollup/config.mjs` and set the correct `owner` and `version` when we build the import map for jsdelivr-gh.
+1. Rebuild the project `npm run build`
+1. Modify the html in the `pocs` folder to use `/dist/jsdelivr-gh-importmap.js`
+1. From the root folder run `npx http-server --port 1337 -c-1  -o ./`
+1. Verify that each poc example works properly.
diff --git a/doc/modules-system.md b/doc/modules-system.md
@@ -0,0 +1,27 @@
+# Modules System
+
+Javascript didn't have an official module support until ESM was introduced in 2015, in 2020 all the major browsers implemented it. By 2023, the community is still in the process of migrating from CommonJS, UMD, etc to ESM, and different tools and libraries have varying support for it.
+
+## ESM
+
+The Marlowe SDK is built using ESM modules but one of its dependencies (fp-ts) doesn't [correctly implement it](https://github.com/gcanti/fp-ts/issues/1777) in its current version. For that reason, we use [rollup](https://rollupjs.org/) to generate a ESM bundle that includes fp-ts. To ease development, we also generate [import maps](https://github.com/WICG/import-maps#import-maps) that tell the browser where to find the different modules.
+
+In most packages documentation you'll find something like:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/input-output-hk/marlowe-ts-sdk/jsdelivr-npm-importmap.js"></script>
+<script type="module">
+  import * as wallet from "@marlowe.io/wallet";
+  // ...
+</script>
+```
+
+If you are using a bundler you don't need the import map as each `package.json`` correctly points to a module using the [exports property](https://webpack.js.org/guides/package-exports/).
+
+> NOTE: Because of how `fp-ts` is bundled, it is included (and tree-shaked) in all the SDK bundled packages, so using your own bundling step can help you reduce the size of the downloaded code.
+
+## CommonJS
+
+> NOTE: [[CommonJS exports problem]]
+
+This repository configures how to be imported using `ESM` and `CJS` modules, but the latter is currently not working because one of the dependencies [does not support CJS](https://github.com/spacebudz/lucid#compatibility). We need to re-assess if we can use an alternative that does support CJS so that it is easier to import the SDK from older setups.
diff --git a/flake.lock b/flake.lock
diff --git a/flake.nix b/flake.nix
@@ -16,24 +16,13 @@
   } @ inputs:
     std.growOn {
       inherit inputs;
-      # 1. Each folder inside `cellsFrom` becomes a "Cell"
-      #    Run for example: 'mkdir nix/mycell'
-      # 2. Each <block>.nix or <block>/default.nix within it becomes a "Cell Block"
-      #    Run for example: '$EDITOR nix/mycell/packages.nix' - see example content below
       cellsFrom = ./nix;
-      # 3. Only blocks with these names [here: "packages" & "shells"] are picked up by Standard
-      #    It's a bit like the output type system of your flake project (hint: CLI & TUI!!)
       cellBlocks = with std.blockTypes; [
-        (installables "packages" {ci.build = true;})
+        (runnables "scripts")
         (nixago "configs")
         (devshells "shells" {ci.build = true;})
       ];
     }
-    # 4. Run 'nix run github:divnix/std'
-    # 'growOn' ... Soil:
-    #  - here, compat for the Nix CLI
-    #  - but can use anything that produces flake outputs (e.g. flake-parts or flake-utils)
-    # 5. Run: nix run .
     {
       devShells = std.harvest self ["ts-sdk" "shells"];
       packages = std.harvest self ["ts-sdk" "packages"];

diff --git a/jsdelivr-npm-importmap.js b/jsdelivr-npm-importmap.js
@@ -0,0 +1,63 @@
+const importMap = {
+  imports: {
+    "@marlowe.io/adapter":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/adapter.js",
+    "@marlowe.io/adapter/codec":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/codec.js",
+    "@marlowe.io/adapter/file":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/file.js",
+    "@marlowe.io/adapter/fp-ts":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/fp-ts.js",
+    "@marlowe.io/adapter/http":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/http.js",
+    "@marlowe.io/adapter/time":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/adapter@0.2.0-alpha-3/dist/bundled/esm/time.js",
+    "@marlowe.io/language-core-v1":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/language-core-v1.js",
+    "@marlowe.io/language-core-v1/environment":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/environment.js",
+    "@marlowe.io/language-core-v1/examples":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/examples.js",
+    "@marlowe.io/language-core-v1/next":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/next.js",
+    "@marlowe.io/language-core-v1/state":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/state.js",
+    "@marlowe.io/language-core-v1/token":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/token.js",
+    "@marlowe.io/language-core-v1/tokenValue":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/tokenValue.js",
+    "@marlowe.io/language-core-v1/version":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/language-core-v1@0.2.0-alpha-3/dist/bundled/esm/version.js",
+    "@marlowe.io/token-metadata-client":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/token-metadata-client@0.2.0-alpha-3/dist/bundled/esm/token-metadata-client.js",
+    "@marlowe.io/wallet":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/wallet@0.2.0-alpha-3/dist/bundled/esm/wallet.js",
+    "@marlowe.io/wallet/api":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/wallet@0.2.0-alpha-3/dist/bundled/esm/api.js",
+    "@marlowe.io/wallet/browser":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/wallet@0.2.0-alpha-3/dist/bundled/esm/browser.js",
+    "@marlowe.io/wallet/nodejs":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/wallet@0.2.0-alpha-3/dist/bundled/esm/nodejs.js",
+    "@marlowe.io/runtime-rest-client":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-rest-client@0.2.0-alpha-3/dist/bundled/esm/runtime-rest-client.js",
+    "@marlowe.io/runtime-rest-client/transaction":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-rest-client@0.2.0-alpha-3/dist/bundled/esm/transaction.js",
+    "@marlowe.io/runtime-rest-client/withdrawal":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-rest-client@0.2.0-alpha-3/dist/bundled/esm/withdrawal.js",
+    "@marlowe.io/runtime-core":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-core@0.2.0-alpha-3/dist/bundled/esm/runtime-core.js",
+    "@marlowe.io/runtime-lifecycle":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-lifecycle@0.2.0-alpha-3/dist/bundled/esm/runtime-lifecycle.js",
+    "@marlowe.io/runtime-lifecycle/api":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-lifecycle@0.2.0-alpha-3/dist/bundled/esm/api.js",
+    "@marlowe.io/runtime-lifecycle/browser":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-lifecycle@0.2.0-alpha-3/dist/bundled/esm/browser.js",
+    "@marlowe.io/runtime-lifecycle/generic":
+      "https:/cdn.jsdelivr.net/npm/@marlowe.io/runtime-lifecycle@0.2.0-alpha-3/dist/bundled/esm/generic.js",
+    "lucid-cardano": "https://unpkg.com/lucid-cardano@0.10.7/web/mod.js",
+  },
+};
+const im = document.createElement("script");
+im.type = "importmap";
+im.textContent = JSON.stringify(importMap);
+document.currentScript.after(im);
diff --git a/nix/ts-sdk/configs.nix b/nix/ts-sdk/configs.nix
@@ -100,5 +100,4 @@ A: (1) dotfile proliferation
       };
     };
   };
-
 }
diff --git a/nix/ts-sdk/packages.nix b/nix/ts-sdk/packages.nix
diff --git a/nix/ts-sdk/scripts.nix b/nix/ts-sdk/scripts.nix
@@ -0,0 +1,19 @@
+{
+  inputs,
+  cell,
+}: let
+  pkgs = inputs.nixpkgs;
+in {
+  build-changelog = inputs.std.lib.ops.mkOperable {
+    package = pkgs.scriv;
+    runtimeScript = ''
+      VERSION=$(jq ".version" package.json)
+      echo "Writting changelog for version $VERSION"
+      scriv collect --version "$VERSION"
+    '';
+    runtimeInputs = [inputs.nixpkgs.jq];
+    meta = {
+      description = "Makes a changelog release from the changelog.d fragments";
+    };
+  };
+}
diff --git a/nix/ts-sdk/shells.nix b/nix/ts-sdk/shells.nix
@@ -30,13 +30,9 @@
         package = nixpkgs.nodePackages.prettier;
         category = "JavaScript";
       }
-      {
-        package = nixpkgs.treefmt;
-        category = "std";
-      }
       {
         package = std.cli.default;
-        category = "std";
+        category = "general commands";
       }
     ];
   };