@novasamatech/host-api 0.5.0-9 → 0.5.1

package/README.md

@@ -1,9 +1,111 @@
 # @novasamatech/host-api
 
-Protocol and transport implementation for host <=> product interaction inside Polkadot ecosystem. 
+A protocol designed to connect Products and Host applications by providing a set of methods for communication.
 
 ## Installation
 
 ```shell
 npm install @novasamatech/host-api --save -E
 ```
+
+## Usage
+
+The Host API package is composed of four main parts:
+* **Protocol** — JAM codecs according to [proposal](https://hackmd.io/@zhuravlev-novasama-1337/B1kW0RWmbg);
+* **Provider** — IPC interface, depends on environment;
+* **Transport** — wrapper around protocol for making actual calls;
+* **Host API** — wrapper around transport for direct usage of business methods.
+
+### Provider
+
+Provider is an interface for IPC communication.
+You can find the definition [here](./src/provider.ts).
+The main goal is to abstract actual message send/receive logic from API.
+Products should not implement their own providers, it should be done inside SDKs.
+
+### Transport
+
+Transport is a low-level wrapper around protocol and provider.
+It encapsulates serialization/deserialization and request/subscription logic.
+
+```typescript
+import { createTransport, okResult } from '@novasamatech/host-api';
+import { provider } from './custom-provider.js';
+
+const transport = createTransport(provider);
+
+// requesting by consumer
+
+const response = await transport.request('storage_read', payload);
+
+// handling request on provider side
+
+const stop = transport.handleRequest('storage_read', async (payload) => {
+  try {
+    const result = await readFromStorage(payload);
+    return okResult(result);
+  } catch (e) {
+    return errResult(e);
+  }
+});
+
+// subscribing by consumer
+
+const subscription = await transport.subscribe('chat_action_subscribe', params, (payload) => {
+  console.log('action received:', payload);
+});
+
+subscription.onInterrupt(() => {
+  console.log('subscription interrupted');
+});
+
+subscription.unsubscribe();
+
+// handling subscription on provider side
+
+transport.handleSubscription('chat_action_subscribe', (params, send, interrupt) => {
+  const unsubscribe = subscribeToChatActions(params, (err, action) => {
+    if (err) {
+      interrupt(err);
+    } else {
+      send(action);
+    }
+  });
+  
+  return unsubscribe;
+});
+```
+
+### Host API
+
+Host API is a wrapper around transport that provides convenient methods for calling methods and subscribing to events.
+It can be used by products directly or indirectly via SDK. All requests return a `ResultAsync` struct from the [neverthrow](https://github.com/Microsoft/neverthrow) library.
+
+```typescript
+import { createHostApi, createTransport } from '@novasamatech/host-api';
+import { provider } from './custom-provider.js';
+
+const transport = createTransport(provider);
+const hostApi = createHostApi(transport);
+
+// requesting data
+
+const storageValue = hostApi.storage_read(payload);
+
+storageValue.match(
+  (data) => console.log('success:', data),
+  (err) => console.log('error:', err)
+);
+
+// subscribing to events
+
+const subscription = hostApi.chat_action_subscribe(params, (action) => {
+  console.log('action received:', action);
+});
+
+subscription.onInterrupt(() => {
+  console.log('subscription interrupted');
+});
+
+subscription.unsubscribe();
+```

package/dist/constants.d.ts

@@ -1 +1,3 @@
+export declare const JAM_CODEC_PROTOCOL_ID = 1;
 export declare const HANDSHAKE_INTERVAL = 50;
+export declare const HANDSHAKE_TIMEOUT = 10000;

package/dist/constants.js

@@ -1 +1,3 @@
+export const JAM_CODEC_PROTOCOL_ID = 1;
 export const HANDSHAKE_INTERVAL = 50;
+export const HANDSHAKE_TIMEOUT = 10_000;

package/dist/helpers.d.ts

@@ -1,3 +1,6 @@
+import type { ResultPayload } from 'scale-ts';
+import type { ComposeMessageAction } from './protocol/messageCodec.js';
+import type { HexString } from './protocol/types.js';
 export declare function delay(ttl: number): Promise<void>;
 type PromiseWithResolvers<T> = {
     promise: Promise<T>;
@@ -5,4 +8,34 @@ type PromiseWithResolvers<T> = {
     reject: (reason: unknown) => void;
 };
 export declare const promiseWithResolvers: <const T>() => PromiseWithResolvers<T>;
+export declare function unwrapResultOrThrow<Ok, Err>(response: ResultPayload<Ok, Err>, toError: (e: Err) => Error): Ok;
+export declare function okResult<const T>(value: T): {
+    success: true;
+    value: T;
+};
+export declare function errResult<const T>(e: T): {
+    success: false;
+    value: T;
+};
+export declare function enumValue<const Tag extends string, const Value>(tag: Tag, value: Value): {
+    tag: Tag;
+    value: Value;
+};
+export declare function isEnumVariant<const Enum extends {
+    tag: string;
+    value: unknown;
+}, const Tag extends Enum['tag']>(v: Enum, tag: Tag): v is Extract<Enum, {
+    tag: Tag;
+}>;
+export declare function assertEnumVariant<const Enum extends {
+    tag: string;
+    value: unknown;
+}, const Tag extends Enum['tag']>(v: Enum, tag: Tag, message: string): asserts v is Extract<Enum, {
+    tag: Tag;
+}>;
+export declare function composeAction<const Method extends string, const Suffix extends string>(method: Method, suffix: Suffix): ComposeMessageAction<Method, Suffix>;
+export declare function createRequestId(): string;
+export declare function extractErrorMessage(err: unknown): string;
+export declare function toHex(value: Uint8Array): HexString;
+export declare function fromHex(value: string): Uint8Array;
 export {};

package/dist/helpers.js

@@ -1,3 +1,5 @@
+import { fromHex as papiFromHex, toHex as papiToHex } from '@polkadot-api/utils';
+import { nanoid } from 'nanoid';
 export function delay(ttl) {
     return new Promise(resolve => setTimeout(resolve, ttl));
 }
@@ -11,3 +13,47 @@ export const promiseWithResolvers = () => {
     // @ts-expect-error before assign
     return { promise, resolve, reject };
 };
+export function unwrapResultOrThrow(response, toError) {
+    if (response.success) {
+        return response.value;
+    }
+    throw toError(response.value);
+}
+export function okResult(value) {
+    return { success: true, value };
+}
+export function errResult(e) {
+    return { success: false, value: e };
+}
+export function enumValue(tag, value) {
+    return { tag, value };
+}
+export function isEnumVariant(v, tag) {
+    return v.tag === tag;
+}
+export function assertEnumVariant(v, tag, message) {
+    if (!isEnumVariant(v, tag)) {
+        throw new Error(message);
+    }
+}
+export function composeAction(method, suffix) {
+    return `${method}_${suffix}`;
+}
+export function createRequestId() {
+    return nanoid(8);
+}
+export function extractErrorMessage(err) {
+    if (err instanceof Error) {
+        return err.toString();
+    }
+    if (err) {
+        return err.toString();
+    }
+    return 'Unknown error occurred.';
+}
+export function toHex(value) {
+    return papiToHex(value);
+}
+export function fromHex(value) {
+    return papiFromHex(value);
+}

package/dist/hostApi.d.ts

@@ -0,0 +1,31 @@
+import type { ResultAsync } from 'neverthrow';
+import type { Codec, CodecType } from 'scale-ts';
+import type { HostApiProtocol, VersionedProtocolRequest, VersionedProtocolSubscription } from './protocol/impl.js';
+import type { Subscription, Transport } from './types.js';
+type Value<T extends Codec<any> | Codec<never>> = T extends Codec<any> ? CodecType<T> : unknown;
+type UnwrapVersionedResult<T> = T extends {
+    tag: infer Tag;
+    value: infer Value;
+} ? ResultAsync<{
+    tag: Tag;
+    value: SuccessResponse<Value>;
+}, {
+    tag: Tag;
+    value: ErrorResponse<Value>;
+}> : never;
+type SuccessResponse<T> = T extends {
+    success: true;
+    value: infer U;
+} ? U : never;
+type ErrorResponse<T> = T extends {
+    success: false;
+    value: infer U;
+} ? U : never;
+type InferRequestMethod<Method extends VersionedProtocolRequest> = (args: Value<Method['request']>) => UnwrapVersionedResult<Value<Method['response']>>;
+type InferSubscribeMethod<Method extends VersionedProtocolSubscription> = (args: Value<Method['start']>, callback: (payload: Value<Method['receive']>) => void) => Subscription;
+type InferMethod<Method extends VersionedProtocolRequest | VersionedProtocolSubscription> = Method extends VersionedProtocolRequest ? InferRequestMethod<Method> : Method extends VersionedProtocolSubscription ? InferSubscribeMethod<Method> : never;
+type HostApi = {
+    [K in keyof HostApiProtocol]: InferMethod<HostApiProtocol[K]>;
+};
+export declare function createHostApi(transport: Transport): HostApi;
+export {};

package/dist/hostApi.js

@@ -0,0 +1,345 @@
+import { errAsync, fromPromise, okAsync } from 'neverthrow';
+import { extractErrorMessage } from './helpers.js';
+import { GenericError } from './protocol/commonCodecs.js';
+import { CreateProofErr, RequestCredentialsErr } from './protocol/v1/accounts.js';
+import { ChatContactRegistrationErr, ChatMessagePostingErr } from './protocol/v1/chat.js';
+import { CreateTransactionErr } from './protocol/v1/createTransaction.js';
+import { HandshakeErr } from './protocol/v1/handshake.js';
+import { PermissionErr } from './protocol/v1/permission.js';
+import { SigningErr } from './protocol/v1/sign.js';
+import { StatementProofErr } from './protocol/v1/statementStore.js';
+import { StorageErr } from './protocol/v1/storage.js';
+export function createHostApi(transport) {
+    return {
+        handshake(payload) {
+            const response = fromPromise(transport.request('handshake', payload), e => ({
+                tag: payload.tag,
+                value: new HandshakeErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        feature(payload) {
+            const response = fromPromise(transport.request('feature', payload), e => ({
+                tag: payload.tag,
+                value: new GenericError({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        permission_request(payload) {
+            const response = fromPromise(transport.request('permission_request', payload), e => ({
+                tag: payload.tag,
+                value: new PermissionErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        storage_read(payload) {
+            const response = fromPromise(transport.request('storage_read', payload), e => ({
+                tag: payload.tag,
+                value: new StorageErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        storage_write(payload) {
+            const response = fromPromise(transport.request('storage_write', payload), e => ({
+                tag: payload.tag,
+                value: new StorageErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        storage_clear(payload) {
+            const response = fromPromise(transport.request('storage_clear', payload), e => ({
+                tag: payload.tag,
+                value: new StorageErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        account_get(payload) {
+            const response = fromPromise(transport.request('account_get', payload), e => ({
+                tag: payload.tag,
+                value: new RequestCredentialsErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        account_get_alias(payload) {
+            const response = fromPromise(transport.request('account_get_alias', payload), e => ({
+                tag: payload.tag,
+                value: new RequestCredentialsErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        account_create_proof(payload) {
+            const response = fromPromise(transport.request('account_create_proof', payload), e => ({
+                tag: payload.tag,
+                value: new CreateProofErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        get_non_product_accounts(payload) {
+            const response = fromPromise(transport.request('get_non_product_accounts', payload), e => ({
+                tag: payload.tag,
+                value: new RequestCredentialsErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        create_transaction(payload) {
+            const response = fromPromise(transport.request('create_transaction', payload), e => ({
+                tag: payload.tag,
+                value: new CreateTransactionErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        create_transaction_with_non_product_account(payload) {
+            const response = fromPromise(transport.request('create_transaction_with_non_product_account', payload), e => ({
+                tag: payload.tag,
+                value: new CreateTransactionErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        sign_raw(payload) {
+            const response = fromPromise(transport.request('sign_raw', payload), e => ({
+                tag: payload.tag,
+                value: new SigningErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        sign_payload(payload) {
+            const response = fromPromise(transport.request('sign_payload', payload), e => ({
+                tag: payload.tag,
+                value: new SigningErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        chat_create_contact(payload) {
+            const response = fromPromise(transport.request('chat_create_contact', payload), e => ({
+                tag: payload.tag,
+                value: new ChatContactRegistrationErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        chat_post_message(payload) {
+            const response = fromPromise(transport.request('chat_post_message', payload), e => ({
+                tag: payload.tag,
+                value: new ChatMessagePostingErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        chat_action_subscribe(args, callback) {
+            return transport.subscribe('chat_action_subscribe', args, callback);
+        },
+        statement_store_create_proof(payload) {
+            const response = fromPromise(transport.request('statement_store_create_proof', payload), e => ({
+                tag: payload.tag,
+                value: new StatementProofErr.Unknown({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        jsonrpc_message_send(payload) {
+            const response = fromPromise(transport.request('jsonrpc_message_send', payload), e => ({
+                tag: payload.tag,
+                value: new GenericError({ reason: extractErrorMessage(e) }),
+            }));
+            return response.andThen(response => {
+                if (response.value.success) {
+                    return okAsync({
+                        tag: response.tag,
+                        value: response.value.value,
+                    });
+                }
+                return errAsync({
+                    tag: response.tag,
+                    value: response.value.value,
+                });
+            });
+        },
+        jsonrpc_message_subscribe(args, callback) {
+            return transport.subscribe('jsonrpc_message_subscribe', args, callback);
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,19 @@
-export { messageEncoder, unwrapResponseOrThrow } from './messageEncoder.js';
-export { type MessagePayloadSchema, type MessageType, type PickMessagePayload, type PickMessagePayloadValue, } from './messageEncoder.js';
-export { createTransport } from './createTransport.js';
-export type { ConnectionStatus, HexString, Logger, Transport, TransportProvider } from './types.js';
+export type { ConnectionStatus, Logger, Transport } from './types.js';
+export type { Provider } from './provider.js';
+export { assertEnumVariant, createRequestId, enumValue, errResult, fromHex, isEnumVariant, okResult, toHex, unwrapResultOrThrow, } from './helpers.js';
+export type { HexString } from './protocol/types.js';
+export { createHostApi } from './hostApi.js';
+export { createTransport } from './transport.js';
 export { createDefaultLogger } from './logger.js';
-export { type InjectedAccountSchema } from './interactions/accounts.js';
-export { type TxPayloadV1 } from './interactions/sign.js';
-export { signPayloadCodec } from './interactions/sign.js';
+export type { HostApiProtocol, VersionedProtocolRequest, VersionedProtocolSubscription } from './protocol/impl.js';
+export { hostApiProtocol } from './protocol/impl.js';
+export type { Codec, CodecType } from 'scale-ts';
+export { GenericError } from './protocol/commonCodecs.js';
+export { CreateTransactionErr, VersionedPublicTxPayload } from './protocol/v1/createTransaction.js';
+export { Account, AccountId, CreateProofErr, ProductAccountId, RequestCredentialsErr } from './protocol/v1/accounts.js';
+export { ChatContactRegistrationErr, ChatContactRegistrationStatus, ChatMessage, ChatMessagePostingErr, ReceivedChatAction, } from './protocol/v1/chat.js';
+export { HandshakeErr } from './protocol/v1/handshake.js';
+export { PermissionErr } from './protocol/v1/permission.js';
+export { SigningErr } from './protocol/v1/sign.js';
+export { StatementProofErr } from './protocol/v1/statementStore.js';
+export { StorageErr } from './protocol/v1/storage.js';

package/dist/index.js

@@ -1,7 +1,15 @@
-export { messageEncoder, unwrapResponseOrThrow } from './messageEncoder.js';
-export {} from './messageEncoder.js';
-export { createTransport } from './createTransport.js';
+export { assertEnumVariant, createRequestId, enumValue, errResult, fromHex, isEnumVariant, okResult, toHex, unwrapResultOrThrow, } from './helpers.js';
+export { createHostApi } from './hostApi.js';
+export { createTransport } from './transport.js';
 export { createDefaultLogger } from './logger.js';
-export {} from './interactions/accounts.js';
-export {} from './interactions/sign.js';
-export { signPayloadCodec } from './interactions/sign.js';
+export { hostApiProtocol } from './protocol/impl.js';
+// Codecs
+export { GenericError } from './protocol/commonCodecs.js';
+export { CreateTransactionErr, VersionedPublicTxPayload } from './protocol/v1/createTransaction.js';
+export { Account, AccountId, CreateProofErr, ProductAccountId, RequestCredentialsErr } from './protocol/v1/accounts.js';
+export { ChatContactRegistrationErr, ChatContactRegistrationStatus, ChatMessage, ChatMessagePostingErr, ReceivedChatAction, } from './protocol/v1/chat.js';
+export { HandshakeErr } from './protocol/v1/handshake.js';
+export { PermissionErr } from './protocol/v1/permission.js';
+export { SigningErr } from './protocol/v1/sign.js';
+export { StatementProofErr } from './protocol/v1/statementStore.js';
+export { StorageErr } from './protocol/v1/storage.js';