@novasamatech/host-api-wrapper 0.9.4 → 0.10.0

package/README.md

@@ -402,6 +402,17 @@ const config = await storage.readJSON('config');
 
 // Clear a key
 await storage.clear('key');
+
+// Subscribe to a key. The callback fires with the current value right away,
+// then on every later write or clear. `undefined` means the key is absent.
+const sub = storage.subscribeBytes('key', (bytes) => {
+  console.log('key changed:', bytes);
+});
+storage.subscribeString('greeting', (text) => console.log(text));
+storage.subscribeJSON('config', (value) => console.log(value));
+
+// Stop receiving updates
+sub.unsubscribe();
 ```
 
 ### Derive Entropy
@@ -509,3 +520,37 @@ const statusSub = payments.subscribePaymentStatus(receipt.id, status => {
   if (status.type === 'failed') console.log('Payment failed:', status.reason);
 });
 ```
+
+### Coin payment (RFC 0017)
+
+Firewalled purses, cheques, and receivables. The long-running operations
+(rebalance, delete, deposit, refund, listen) stream clearing status through a
+callback and return a `Subscription`; `onInterrupt` fires with a
+`CoinPaymentErr` if the host tears the stream down.
+
+```ts
+import { createCoinPayment } from '@novasamatech/host-api-wrapper';
+
+const coinPayment = createCoinPayment();
+
+// Create a purse and read it back
+const purse = await coinPayment.createPurse('Terminal purse');
+const info = await coinPayment.queryPurse(purse);
+console.log('balance:', info.balance);
+
+// Pay a receivable with a cheque
+const receivable = await coinPayment.createReceivable(purse);
+const cheque = await coinPayment.createCheque(purse, receivable, 1000);
+
+// Claim the cheque, watching the coins clear
+const sub = coinPayment.deposit(cheque, status => {
+  if (status.tag === 'Done') console.log('cleared:', status.value.cleared);
+  if (status.tag === 'Failed') console.log('failed:', status.value.error);
+});
+sub.onInterrupt(err => console.log('deposit interrupted:', err));
+
+// Wait for a cheque delivered over a standard channel
+coinPayment.listenForPayment(receivable, item => {
+  if (item.tag === 'Cheque') console.log('received cheque:', item.value.amount);
+});
+```

package/dist/coinPayment.d.ts

@@ -0,0 +1,35 @@
+import type { CodecType, CoinPaymentCheque, CoinPaymentErr, CoinPaymentListenForItem, CoinPaymentPurseInfo, CoinPaymentStatus, HexString, Subscription, Transport } from '@novasamatech/host-api';
+/** Purse identifier (RFC 0017). `0xffffffff` is the well-known main purse. */
+export type PurseId = number;
+/** Receivable public key, as a 0x-prefixed 32-byte hex string. */
+export type Receivable = HexString;
+export type PurseInfo = CodecType<typeof CoinPaymentPurseInfo>;
+export type Cheque = CodecType<typeof CoinPaymentCheque>;
+/** Clearing status streamed by rebalance, delete, deposit, and refund. */
+export type ClearingStatus = CodecType<typeof CoinPaymentStatus>;
+/** Item streamed by `listenForPayment`: a delivery channel, then the cheque. */
+export type PaymentDelivery = CodecType<typeof CoinPaymentListenForItem>;
+type CoinPaymentInterrupt = CodecType<typeof CoinPaymentErr>;
+export declare const createCoinPayment: (transport?: Transport) => {
+    createPurse(name: string): Promise<PurseId>;
+    queryPurse(purse: PurseId): Promise<PurseInfo>;
+    createReceivable(into: PurseId): Promise<Receivable>;
+    createCheque(from: PurseId, to: Receivable, amount: number): Promise<Cheque>;
+    rebalancePurse(from: PurseId, to: PurseId, amount: number, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    deletePurse(target: PurseId, drainInto: PurseId, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    deposit(cheque: Cheque, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    refund(receivable: Receivable, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    listenForPayment(receivable: Receivable, onDelivery: (item: PaymentDelivery) => void): Subscription<CoinPaymentInterrupt>;
+};
+export declare const hostCoinPayment: {
+    createPurse(name: string): Promise<PurseId>;
+    queryPurse(purse: PurseId): Promise<PurseInfo>;
+    createReceivable(into: PurseId): Promise<Receivable>;
+    createCheque(from: PurseId, to: Receivable, amount: number): Promise<Cheque>;
+    rebalancePurse(from: PurseId, to: PurseId, amount: number, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    deletePurse(target: PurseId, drainInto: PurseId, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    deposit(cheque: Cheque, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    refund(receivable: Receivable, onStatus: (status: ClearingStatus) => void): Subscription<CoinPaymentInterrupt>;
+    listenForPayment(receivable: Receivable, onDelivery: (item: PaymentDelivery) => void): Subscription<CoinPaymentInterrupt>;
+};
+export {};

package/dist/coinPayment.js

@@ -0,0 +1,67 @@
+import { createHostApi, enumValue } from '@novasamatech/host-api';
+import { resultToPromise, unwrapVersionedResult } from './helpers.js';
+import { sandboxTransport } from './sandboxTransport.js';
+export const createCoinPayment = (transport = sandboxTransport) => {
+    const hostApi = createHostApi(transport);
+    const version = 'v1';
+    function stream(subscriber) {
+        return {
+            unsubscribe: subscriber.unsubscribe,
+            onInterrupt: cb => subscriber.onInterrupt(v => cb(v.value)),
+        };
+    }
+    return {
+        // Create a new firewalled purse and resolve with its assigned id.
+        createPurse(name) {
+            return resultToPromise(unwrapVersionedResult(version, hostApi.coinPaymentCreatePurse(enumValue(version, { name })))).then(({ purse }) => purse);
+        },
+        // Query product-visible metadata and balance for a purse.
+        queryPurse(purse) {
+            return resultToPromise(unwrapVersionedResult(version, hostApi.coinPaymentQueryPurse(enumValue(version, { purse })))).then(({ info }) => info);
+        },
+        // Create a fresh receivable public key for depositing into a purse.
+        createReceivable(into) {
+            return resultToPromise(unwrapVersionedResult(version, hostApi.coinPaymentCreateReceivable(enumValue(version, { into })))).then(({ receivable }) => receivable);
+        },
+        // Create a cheque paying from a local purse to a receivable.
+        createCheque(from, to, amount) {
+            return resultToPromise(unwrapVersionedResult(version, hostApi.coinPaymentCreateCheque(enumValue(version, { from, to, amount })))).then(({ cheque }) => cheque);
+        },
+        // Transfer balance between local purses, streaming clearing status.
+        rebalancePurse(from, to, amount, onStatus) {
+            return stream(hostApi.coinPaymentRebalancePurse(enumValue(version, { from, to, amount }), payload => {
+                if (payload.tag === version)
+                    onStatus(payload.value);
+            }));
+        },
+        // Delete a purse after draining its balance into another local purse.
+        deletePurse(target, drainInto, onStatus) {
+            return stream(hostApi.coinPaymentDeletePurse(enumValue(version, { target, drainInto }), payload => {
+                if (payload.tag === version)
+                    onStatus(payload.value);
+            }));
+        },
+        // Claim coins from a cheque into the receivable's purse.
+        deposit(cheque, onStatus) {
+            return stream(hostApi.coinPaymentDeposit(enumValue(version, { cheque }), payload => {
+                if (payload.tag === version)
+                    onStatus(payload.value);
+            }));
+        },
+        // Attempt to return coins associated with a receivable.
+        refund(receivable, onStatus) {
+            return stream(hostApi.coinPaymentRefund(enumValue(version, { receivable }), payload => {
+                if (payload.tag === version)
+                    onStatus(payload.value);
+            }));
+        },
+        // Listen for a cheque delivered through a standard transmission channel.
+        listenForPayment(receivable, onDelivery) {
+            return stream(hostApi.coinPaymentListenForPayment(enumValue(version, { receivable }), payload => {
+                if (payload.tag === version)
+                    onDelivery(payload.value);
+            }));
+        },
+    };
+};
+export const hostCoinPayment = createCoinPayment();

package/dist/index.d.ts

@@ -13,6 +13,9 @@ export { accounts, createAccountsProvider, ringVrfKeyHandle } from './accounts.j
 export type { ThemeMode } from './theme.js';
 export { createThemeProvider } from './theme.js';
 export { createLocalStorage, hostLocalStorage } from './localStorage.js';
+export { createWorker, hostWorker } from './worker.js';
+export type { Cheque, ClearingStatus, PaymentDelivery, PurseInfo, Receivable } from './coinPayment.js';
+export { createCoinPayment, hostCoinPayment } from './coinPayment.js';
 export type { NotificationId, PushNotificationInput } from './notification.js';
 export { createNotificationManager, notificationManager } from './notification.js';
 export { createPreimageManager, preimageManager } from './preimage.js';

package/dist/index.js

@@ -9,6 +9,8 @@ export { createStatementStore } from './statementStore.js';
 export { accounts, createAccountsProvider, ringVrfKeyHandle } from './accounts.js';
 export { createThemeProvider } from './theme.js';
 export { createLocalStorage, hostLocalStorage } from './localStorage.js';
+export { createWorker, hostWorker } from './worker.js';
+export { createCoinPayment, hostCoinPayment } from './coinPayment.js';
 export { createNotificationManager, notificationManager } from './notification.js';
 export { createPreimageManager, preimageManager } from './preimage.js';
 export { createPaymentManager, paymentManager } from './payments.js';

package/dist/localStorage.d.ts

@@ -1,3 +1,4 @@
+import type { Subscription } from '@novasamatech/host-api';
 export declare const createLocalStorage: (transport?: import("@novasamatech/host-api").Transport) => {
     clear(key: string): Promise<undefined>;
     readBytes(key: string): Promise<Uint8Array<ArrayBufferLike> | undefined>;
@@ -6,6 +7,9 @@ export declare const createLocalStorage: (transport?: import("@novasamatech/host
     writeString(key: string, value: string): Promise<undefined>;
     readJSON(key: string): Promise<any>;
     writeJSON(key: string, value: unknown): Promise<undefined>;
+    subscribeBytes(key: string, callback: (value: Uint8Array | undefined) => void): Subscription<void>;
+    subscribeString(key: string, callback: (value: string | undefined) => void): Subscription<void>;
+    subscribeJSON(key: string, callback: (value: unknown) => void): Subscription<void>;
 };
 export declare const hostLocalStorage: {
     clear(key: string): Promise<undefined>;
@@ -15,4 +19,7 @@ export declare const hostLocalStorage: {
     writeString(key: string, value: string): Promise<undefined>;
     readJSON(key: string): Promise<any>;
     writeJSON(key: string, value: unknown): Promise<undefined>;
+    subscribeBytes(key: string, callback: (value: Uint8Array | undefined) => void): Subscription<void>;
+    subscribeString(key: string, callback: (value: string | undefined) => void): Subscription<void>;
+    subscribeJSON(key: string, callback: (value: unknown) => void): Subscription<void>;
 };

package/dist/localStorage.js

@@ -15,6 +15,17 @@ export const createLocalStorage = (transport = sandboxTransport) => {
     function clearKey(key) {
         return resultToPromise(unwrapVersionedResult(supportedVersion, hostApi.localStorageClear(enumValue(supportedVersion, key))));
     }
+    function subscribeBytes(key, callback) {
+        const subscriber = hostApi.localStorageSubscribe(enumValue(supportedVersion, { key }), item => {
+            if (item.tag === supportedVersion) {
+                callback(item.value.value);
+            }
+        });
+        return {
+            unsubscribe: subscriber.unsubscribe,
+            onInterrupt: cb => subscriber.onInterrupt(v => cb(v.value)),
+        };
+    }
     return {
         async clear(key) {
             return clearKey(key);
@@ -40,6 +51,17 @@ export const createLocalStorage = (transport = sandboxTransport) => {
         async writeJSON(key, value) {
             return writeBytes(key, textEncoder.encode(JSON.stringify(value)));
         },
+        // Emits the current value immediately, then on every later write or clear
+        // of the key. `undefined` means the key was cleared or is absent.
+        subscribeBytes(key, callback) {
+            return subscribeBytes(key, callback);
+        },
+        subscribeString(key, callback) {
+            return subscribeBytes(key, bytes => callback(bytes === undefined ? undefined : textDecoder.decode(bytes)));
+        },
+        subscribeJSON(key, callback) {
+            return subscribeBytes(key, bytes => callback(bytes === undefined || bytes.length === 0 ? undefined : JSON.parse(textDecoder.decode(bytes))));
+        },
     };
 };
 export const hostLocalStorage = createLocalStorage();

package/dist/papiProvider.js

@@ -1,4 +1,4 @@
-import { createHostApi, enumValue, unwrapResultOrThrow } from '@novasamatech/host-api';
+import { createHostApi, enumValue, isCallErrorFailure, unwrapResultOrThrow } from '@novasamatech/host-api';
 import { getSyncProvider } from '@polkadot-api/json-rpc-provider-proxy';
 import { sandboxTransport } from './sandboxTransport.js';
 export function createPapiProvider(genesisHash, 
@@ -311,6 +311,8 @@ __fallback, internal) {
                 .then(payload => {
                 switch (payload.tag) {
                     case 'v1': {
+                        if (isCallErrorFailure(payload.value))
+                            return false;
                         return unwrapResultOrThrow(payload.value, e => new Error(e.payload.reason));
                     }
                     default:

package/dist/worker.d.ts

@@ -0,0 +1,9 @@
+import type { Transport } from '@novasamatech/host-api';
+export declare const createWorker: (transport?: Transport) => {
+    beginOperation(label?: string): Promise<number>;
+    endOperation(id: number): Promise<void>;
+};
+export declare const hostWorker: {
+    beginOperation(label?: string): Promise<number>;
+    endOperation(id: number): Promise<void>;
+};

package/dist/worker.js

@@ -0,0 +1,22 @@
+import { createHostApi, enumValue } from '@novasamatech/host-api';
+import { resultToPromise, unwrapVersionedResult } from './helpers.js';
+import { sandboxTransport } from './sandboxTransport.js';
+export const createWorker = (transport = sandboxTransport) => {
+    const supportedVersion = 'v1';
+    const hostApi = createHostApi(transport);
+    return {
+        // Begin a pending operation. The host keeps this worker alive while it has
+        // at least one open operation, so a background task runs to completion even
+        // after the product's surface goes away. Returns the operation id.
+        async beginOperation(label) {
+            const { id } = await resultToPromise(unwrapVersionedResult(supportedVersion, hostApi.workerBeginOperation(enumValue(supportedVersion, { label }))));
+            return id;
+        },
+        // End a pending operation. Idempotent: an unknown or already-ended id
+        // still resolves.
+        async endOperation(id) {
+            return resultToPromise(unwrapVersionedResult(supportedVersion, hostApi.workerEndOperation(enumValue(supportedVersion, { id }))));
+        },
+    };
+};
+export const hostWorker = createWorker();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-api-wrapper",
   "type": "module",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Host API wrapper: integrate and run your product inside Polkadot browser.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "@polkadot/extension-inject": "^0.63.1",
     "@polkadot-api/json-rpc-provider-proxy": "^0.4.0",
     "@polkadot-api/substrate-bindings": "^0.20.3",
-    "@novasamatech/host-api": "0.9.4",
+    "@novasamatech/host-api": "0.10.0",
     "polkadot-api": ">=2",
     "neverthrow": "^8.2.0"
   },