@novasamatech/host-chat 0.8.0-1

package/README.md

@@ -0,0 +1,102 @@
+# @novasamatech/host-chat
+
+Account lookup and chat-message codecs for host applications integrating with the Polkadot People chain.
+
+## Overview
+
+`@novasamatech/host-chat` exposes the read side of the chat domain: discovering Polkadot
+accounts by username and resolving their on-chain identity from `Resources.Consumers`. It
+also publishes the SCALE codecs used by the chat wire protocol (messages, attachments,
+local-message envelopes) so host applications can decode statements they receive over the
+statement store.
+
+The package is UI-framework agnostic. The main entry point returns plain async functions
+backed by [`neverthrow`](https://github.com/supermacro/neverthrow) `ResultAsync`, and the
+codec exports are pure SCALE codecs with no runtime side effects.
+
+## Installation
+
+```shell
+npm install @novasamatech/host-chat --save -E
+```
+
+## Getting started
+
+```ts
+import { createAccountService } from '@novasamatech/host-chat';
+import { createLazyClient } from '@novasamatech/statement-store';
+
+const lazyClient = createLazyClient(/* chain provider */);
+const accounts = createAccountService('paseo-next-v2', lazyClient);
+
+// Search the off-chain username index for accounts whose username starts with `alice`.
+const search = await accounts.search('alice', 'ASSIGNED');
+if (search.isOk()) {
+  for (const hit of search.value) {
+    console.log(hit.candidateAccountId, hit.username);
+  }
+}
+
+// Resolve a specific account's on-chain identity.
+const identity = await accounts.getConsumerInfo('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY');
+if (identity.isOk() && identity.value) {
+  console.log(identity.value.fullUsername, identity.value.credibility);
+}
+```
+
+### Networks
+
+`createAccountService` accepts one of:
+
+| Network          | People chain endpoint                  |
+| ---------------- | -------------------------------------- |
+| `stable`         | Polkadot People                        |
+| `preview`        | Westend People                         |
+| `paseo-next`     | Paseo People (V1)                      |
+| `paseo-next-v2`  | Paseo People (V2 multi-device)         |
+
+Each network entry pins both the People chain WebSocket URL (used via `lazyClient`) and
+the off-chain identity-backend REST endpoint that `search` queries.
+
+## API
+
+### `createAccountService(network, lazyClient)`
+
+Returns an object with two methods:
+
+- **`search(query, status)`** — query the off-chain username index. `status` is
+  `'ASSIGNED' | 'PENDING'`. Resolves to a list of `{ candidateAccountId, username, status,
+  onchainData, createdAt, updatedAt }` rows.
+- **`getConsumerInfo(address)`** — resolve a single SS58 address to an `Identity`
+  (`{ accountId, fullUsername, liteUsername, credibility }`) by reading
+  `Resources.Consumers` from the People chain. Returns `null` if the account has no
+  consumer entry. Tolerates both snake_case (V1) and camelCase (V2) runtime field names.
+
+Both methods return `ResultAsync<…, Error>`; call `.isOk()` / `.isErr()` to discriminate.
+
+## Codec subpath exports
+
+The chat wire codecs are exposed under explicit subpaths so they can be tree-shaken
+independently of the main entry point:
+
+```ts
+import {
+  ChatMessage,
+  TextContent,
+  RichTextContent,
+  ChatAcceptedContent,
+  DeviceAddedContent,
+  DeviceRemovedContent,
+} from '@novasamatech/host-chat/codec/message';
+
+import {
+  FileMeta,
+  FileVariant,
+  P2PMixnetFile,
+} from '@novasamatech/host-chat/codec/attachment';
+
+import type { ChatSession } from '@novasamatech/host-chat/session';
+```
+
+These are byte-compatible with the Android / iOS Polkadot Mobile clients — modify with
+care, the indices are pinned by the protocol.

package/dist/accountService.d.ts

@@ -0,0 +1,37 @@
+import type { HexString } from '@novasamatech/scale';
+import type { LazyClient } from '@novasamatech/statement-store';
+import type { ResultAsync } from 'neverthrow';
+type AccountStatus = 'ASSIGNED' | 'PENDING';
+type AccountService = {
+    search(query: string, status: AccountStatus): ResultAsync<SearchResponse, Error>;
+    getConsumerInfo(address: string): ResultAsync<Identity | null, Error>;
+};
+type Network = 'paseo-next' | 'paseo-next-v2' | 'preview' | 'stable';
+type SearchResponse = {
+    candidateAccountId: string;
+    username: string;
+    status: AccountStatus;
+    onchainData: {
+        blockIndex: number;
+        blockNumber: number;
+        blockHash: HexString;
+        eventIndex: number;
+    };
+    createdAt: string;
+    updatedAt: string;
+}[];
+export type Credibility = {
+    type: 'Lite';
+} | {
+    type: 'Person';
+    alias: `0x${string}`;
+    lastUpdate: string;
+};
+export type Identity = {
+    accountId: string;
+    fullUsername: string | null;
+    liteUsername: string;
+    credibility: Credibility;
+};
+export declare const createAccountService: (network: Network, lazyClient: LazyClient) => AccountService;
+export {};

package/dist/accountService.js

@@ -0,0 +1,84 @@
+import { toHex } from '@novasamatech/scale';
+import { AccountId } from '@polkadot-api/substrate-bindings';
+import { errAsync, fromPromise } from 'neverthrow';
+import { toError } from './helpers.js';
+export const createAccountService = (network, lazyClient) => {
+    const networkConfig = NETWORK_CONFIGS[network];
+    return {
+        search(query, status) {
+            // Build query string
+            const params = new URLSearchParams({
+                prefix: query,
+                status,
+            });
+            const request = fromPromise(fetch(`${networkConfig.apiUrl}/usernames?${params}`, {
+                method: 'GET',
+                headers: { Accept: 'application/json' },
+            }), toError);
+            return request.andThen(response => {
+                if (!response.ok) {
+                    return fromPromise(response.text(), toError).andThen(message => errAsync(new Error(`status: ${response.status}, ${message}`)));
+                }
+                return fromPromise(response.json(), toError);
+            });
+        },
+        getConsumerInfo(address) {
+            const textDecoder = new TextDecoder();
+            const accountId = AccountId();
+            const client = lazyClient.getClient();
+            const api = client.getUnsafeApi();
+            const consumerInfo = fromPromise(api.query.Resources?.Consumers?.getValue(address), toError);
+            return consumerInfo.map(typedRaw => {
+                if (!typedRaw)
+                    return null;
+                // Runtime metadata may expose fields in snake_case (V1) or
+                // camelCase (V2 multi-device). Read defensively.
+                const raw = typedRaw;
+                const fullUsername = raw.full_username ?? raw.fullUsername;
+                const liteUsername = raw.lite_username ?? raw.liteUsername;
+                const credibility = raw.credibility.type === 'Lite'
+                    ? {
+                        type: 'Lite',
+                    }
+                    : {
+                        type: 'Person',
+                        alias: raw.credibility.value.alias,
+                        lastUpdate: (raw.credibility.value.last_update ??
+                            raw.credibility.value.lastUpdate).toString(),
+                    };
+                return {
+                    accountId: toHex(accountId.enc(address)),
+                    fullUsername: fullUsername ? textDecoder.decode(fullUsername) : null,
+                    liteUsername: liteUsername ? textDecoder.decode(liteUsername) : '',
+                    credibility: credibility,
+                };
+            });
+        },
+    };
+};
+const NETWORK_CONFIGS = {
+    stable: {
+        id: 'stable',
+        name: 'PoP Stable',
+        wsUrl: 'wss://pop3-testnet.parity-lab.parity.io/people',
+        apiUrl: 'https://polkadot-app.api.polkadotcommunity.foundation/api/v1',
+    },
+    preview: {
+        id: 'preview',
+        name: 'PoP Preview',
+        wsUrl: 'wss://previewnet.substrate.dev/people',
+        apiUrl: 'https://polkadot-app-stg.parity.io/api/v1',
+    },
+    'paseo-next': {
+        id: 'paseo-next',
+        name: 'Paseo Next',
+        wsUrl: 'wss://paseo-people-next-rpc.polkadot.io',
+        apiUrl: 'https://identity-backend.parity-testnet.parity.io/api/v1',
+    },
+    'paseo-next-v2': {
+        id: 'paseo-next-v2',
+        name: 'Paseo Next V2',
+        wsUrl: 'wss://paseo-people-next-system-rpc.polkadot.io',
+        apiUrl: 'https://identity-backend-next.parity-testnet.parity.io/api/v1',
+    },
+};

package/dist/codec/attachment.d.ts

@@ -0,0 +1,108 @@
+export declare const GeneralFileMeta: import("scale-ts").Codec<{
+    mimeType: string;
+    fileSize: number;
+}>;
+export declare const ImageFileMeta: import("scale-ts").Codec<{
+    general: {
+        mimeType: string;
+        fileSize: number;
+    };
+    width: number;
+    height: number;
+}>;
+export declare const VideoFileMeta: import("scale-ts").Codec<{
+    general: {
+        mimeType: string;
+        fileSize: number;
+    };
+    duration: number;
+}>;
+export declare const FileMeta: import("scale-ts").Codec<{
+    tag: "general";
+    value: {
+        mimeType: string;
+        fileSize: number;
+    };
+} | {
+    tag: "image";
+    value: {
+        general: {
+            mimeType: string;
+            fileSize: number;
+        };
+        width: number;
+        height: number;
+    };
+} | {
+    tag: "video";
+    value: {
+        general: {
+            mimeType: string;
+            fileSize: number;
+        };
+        duration: number;
+    };
+}>;
+export declare const P2PMixnetFile: import("scale-ts").Codec<{
+    identifier: Uint8Array<ArrayBufferLike>;
+    claimTicket: Uint8Array<ArrayBufferLike>;
+    meta: {
+        tag: "general";
+        value: {
+            mimeType: string;
+            fileSize: number;
+        };
+    } | {
+        tag: "image";
+        value: {
+            general: {
+                mimeType: string;
+                fileSize: number;
+            };
+            width: number;
+            height: number;
+        };
+    } | {
+        tag: "video";
+        value: {
+            general: {
+                mimeType: string;
+                fileSize: number;
+            };
+            duration: number;
+        };
+    };
+}>;
+export declare const FileVariant: import("scale-ts").Codec<{
+    tag: "p2pMixnet";
+    value: {
+        identifier: Uint8Array<ArrayBufferLike>;
+        claimTicket: Uint8Array<ArrayBufferLike>;
+        meta: {
+            tag: "general";
+            value: {
+                mimeType: string;
+                fileSize: number;
+            };
+        } | {
+            tag: "image";
+            value: {
+                general: {
+                    mimeType: string;
+                    fileSize: number;
+                };
+                width: number;
+                height: number;
+            };
+        } | {
+            tag: "video";
+            value: {
+                general: {
+                    mimeType: string;
+                    fileSize: number;
+                };
+                duration: number;
+            };
+        };
+    };
+}>;

package/dist/codec/attachment.js

@@ -0,0 +1,28 @@
+import { Enum } from '@novasamatech/scale';
+import { Bytes, Struct, str, u32 } from 'scale-ts';
+export const GeneralFileMeta = Struct({
+    mimeType: str,
+    fileSize: u32,
+});
+export const ImageFileMeta = Struct({
+    general: GeneralFileMeta,
+    width: u32,
+    height: u32,
+});
+export const VideoFileMeta = Struct({
+    general: GeneralFileMeta,
+    duration: u32,
+});
+export const FileMeta = Enum({
+    general: GeneralFileMeta,
+    image: ImageFileMeta,
+    video: VideoFileMeta,
+});
+export const P2PMixnetFile = Struct({
+    identifier: Bytes(),
+    claimTicket: Bytes(),
+    meta: FileMeta,
+});
+export const FileVariant = Enum({
+    p2pMixnet: P2PMixnetFile,
+});

package/dist/codec/attachment.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codec/attachment.spec.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { FileMeta, FileVariant, GeneralFileMeta, ImageFileMeta, P2PMixnetFile, VideoFileMeta } from './attachment.js';
+describe('attachment codecs', () => {
+    describe('GeneralFileMeta', () => {
+        it('round-trips', () => {
+            const original = { mimeType: 'application/pdf', fileSize: 1024 };
+            const encoded = GeneralFileMeta.enc(original);
+            const decoded = GeneralFileMeta.dec(encoded);
+            expect(decoded).toEqual(original);
+        });
+    });
+    describe('ImageFileMeta', () => {
+        it('round-trips', () => {
+            const original = {
+                general: { mimeType: 'image/jpeg', fileSize: 500_000 },
+                width: 1920,
+                height: 1080,
+            };
+            const encoded = ImageFileMeta.enc(original);
+            const decoded = ImageFileMeta.dec(encoded);
+            expect(decoded).toEqual(original);
+        });
+    });
+    describe('VideoFileMeta', () => {
+        it('round-trips', () => {
+            const original = {
+                general: { mimeType: 'video/mp4', fileSize: 10_000_000 },
+                duration: 120,
+            };
+            const encoded = VideoFileMeta.enc(original);
+            const decoded = VideoFileMeta.dec(encoded);
+            expect(decoded).toEqual(original);
+        });
+    });
+    describe('FileMeta', () => {
+        it('round-trips all variants', () => {
+            const variants = [
+                { tag: 'general', value: { mimeType: 'application/pdf', fileSize: 1024 } },
+                {
+                    tag: 'image',
+                    value: { general: { mimeType: 'image/png', fileSize: 2048 }, width: 800, height: 600 },
+                },
+                {
+                    tag: 'video',
+                    value: { general: { mimeType: 'video/mp4', fileSize: 4096 }, duration: 60 },
+                },
+            ];
+            for (const original of variants) {
+                const encoded = FileMeta.enc(original);
+                const decoded = FileMeta.dec(encoded);
+                expect(decoded).toEqual(original);
+            }
+        });
+    });
+    describe('P2PMixnetFile', () => {
+        it('round-trips', () => {
+            const original = {
+                identifier: new Uint8Array(32).fill(0xaa),
+                claimTicket: new Uint8Array(32).fill(0xbb),
+                meta: {
+                    tag: 'image',
+                    value: {
+                        general: { mimeType: 'image/jpeg', fileSize: 500_000 },
+                        width: 1920,
+                        height: 1080,
+                    },
+                },
+            };
+            const encoded = P2PMixnetFile.enc(original);
+            const decoded = P2PMixnetFile.dec(encoded);
+            expect(decoded.identifier).toEqual(original.identifier);
+            expect(decoded.claimTicket).toEqual(original.claimTicket);
+            expect(decoded.meta).toEqual(original.meta);
+        });
+    });
+    describe('FileVariant', () => {
+        it('round-trips p2pMixnet variant', () => {
+            const variant = {
+                tag: 'p2pMixnet',
+                value: {
+                    identifier: new Uint8Array(32).fill(0x11),
+                    claimTicket: new Uint8Array(32).fill(0x22),
+                    meta: { tag: 'general', value: { mimeType: 'text/plain', fileSize: 10 } },
+                },
+            };
+            const encoded = FileVariant.enc(variant);
+            const decoded = FileVariant.dec(encoded);
+            expect(decoded).toEqual(variant);
+        });
+    });
+});

package/dist/codec/contact.d.ts

@@ -0,0 +1,9 @@
+export declare const Contact: import("scale-ts").Codec<{
+    username: string;
+    accountId: import("@novasamatech/statement-store").AccountId;
+    publicKey: Uint8Array<ArrayBufferLike>;
+    pin: string | undefined;
+    pushId: string | undefined;
+    pushToken: Uint8Array<ArrayBufferLike> | undefined;
+    lastOwnToken: Uint8Array<ArrayBufferLike> | undefined;
+}>;

package/dist/codec/contact.js

@@ -0,0 +1,11 @@
+import { AccountIdCodec } from '@novasamatech/statement-store';
+import { Bytes, Option, Struct, str } from 'scale-ts';
+export const Contact = Struct({
+    username: str,
+    accountId: AccountIdCodec,
+    publicKey: Bytes(),
+    pin: Option(str),
+    pushId: Option(str),
+    pushToken: Option(Bytes()),
+    lastOwnToken: Option(Bytes()),
+});