@parity/product-sdk 0.0.0-dev.312.0

package/src/core/createApp.ts

@@ -0,0 +1,408 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * createApp - Main entry point for the Product SDK
+ *
+ * Creates an App instance with wallet, storage, chain, and cloud storage APIs.
+ */
+
+import type { ChainDefinition } from "polkadot-api";
+import type {
+    App,
+    AppConfig,
+    WalletApi,
+    ChainApi,
+    Account,
+    CloudStorageApi,
+    LocalStorageApi,
+} from "./types.js";
+import { configure, createLogger } from "@parity/product-sdk-logger";
+import { createLocalKvStore } from "@parity/product-sdk-local-storage";
+import { SignerManager } from "@parity/product-sdk-signer";
+import {
+    CloudStorageClient,
+    ProductCloudStorageError,
+    calculateCid,
+    createLazySigner,
+} from "@parity/product-sdk-cloud-storage";
+import { err, ok } from "@parity/result";
+import {
+    createChainClient,
+    getClient,
+    isConnected,
+    destroyAll,
+} from "@parity/product-sdk-chain-client";
+import { accountIdBytes } from "@parity/product-sdk-address";
+import { getAccountsProvider } from "@parity/product-sdk-host";
+import {
+    accountIdBytesToHex,
+    type PeopleUsernameQueryApi,
+    resolvePeopleUsernameOwner,
+} from "../identity/dotns.js";
+
+const log = createLogger("app");
+
+/**
+ * Create a new Product SDK app instance
+ *
+ * @param config - Application configuration
+ * @returns App instance with all APIs
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@parity/product-sdk';
+ *
+ * // Default: cloud storage enabled with paseo environment
+ * const app = await createApp({
+ *   name: 'my-app',
+ *   logLevel: 'info',
+ * });
+ *
+ * // Custom cloud storage environment
+ * const prodApp = await createApp({
+ *   name: 'my-app',
+ *   cloudStorage: { environment: 'polkadot' },
+ * });
+ *
+ * // Disable cloud storage entirely
+ * const noCloudStorageApp = await createApp({
+ *   name: 'my-app',
+ *   cloudStorage: false,
+ * });
+ *
+ * // Connect wallet
+ * const { accounts } = await app.wallet.connect();
+ *
+ * // Use storage
+ * await app.localStorage.set('key', 'value');
+ *
+ * // Use cloud storage (check for null if it might be disabled)
+ * if (app.cloudStorage) {
+ *   const cid = await app.cloudStorage.upload('hello world');
+ * }
+ * ```
+ */
+export async function createApp(config: AppConfig): Promise<App> {
+    // Set log level if specified
+    if (config.logLevel) {
+        configure({ level: config.logLevel });
+    }
+
+    log.info("Creating Product SDK app", { name: config.name });
+
+    // Initialize storage (container-only - will throw if not in container)
+    const localKvStore = await createLocalKvStore({ prefix: config.name });
+
+    // Initialize signer manager
+    const signerManager = new SignerManager({
+        dappName: config.name,
+    });
+
+    // Initialize cloud storage client (configurable, defaults to paseo).
+    //
+    // The signer is wrapped lazily so the cloud storage client can be built before
+    // an account is selected. Uploads will throw a clear error if no signer
+    // is available at submission time. Reads (fetch / fetchJson) don't need
+    // a signer, so they work regardless of whether an account is selected --
+    // but they are container-only and throw CloudStorageHostUnavailableError
+    // outside a host container (no IPFS-gateway fallback).
+    const cloudStorageEnabled = config.cloudStorage !== false;
+    const cloudStorageEnvironment =
+        typeof config.cloudStorage === "object" ? config.cloudStorage.environment : "paseo";
+    const cloudStorageClient = cloudStorageEnabled
+        ? await CloudStorageClient.create({
+              environment: cloudStorageEnvironment,
+              signer: createLazySigner(() => signerManager.getSigner()),
+          })
+        : null;
+
+    if (cloudStorageEnabled) {
+        log.debug("Cloud Storage client (Bulletin) initialized", {
+            environment: cloudStorageEnvironment,
+        });
+    } else {
+        log.debug("Cloud Storage client disabled");
+    }
+
+    // Create storage API adapter
+    const localStorageApi: LocalStorageApi = {
+        get: (key) => localKvStore.get(key),
+        set: (key, value) => localKvStore.set(key, value),
+        getJSON: <T>(key: string) => localKvStore.getJSON<T>(key),
+        setJSON: <T>(key: string, value: T) => localKvStore.setJSON(key, value),
+        remove: (key) => localKvStore.remove(key),
+        clear: async () => {
+            // LocalKvStore doesn't have clear - this is a no-op
+            log.debug("clear() is not supported in container storage mode");
+        },
+    };
+
+    // Create wallet API adapter
+    const walletApi = createWalletApi(signerManager);
+
+    // Create chain API
+    const chainApi: ChainApi = {
+        getClient(descriptor) {
+            log.debug("getClient called", { genesis: descriptor.genesis });
+            const client = getClient(descriptor);
+            return client.getTypedApi(descriptor);
+        },
+
+        getRawClient(descriptor) {
+            log.debug("getRawClient called", { genesis: descriptor.genesis });
+            return getClient(descriptor);
+        },
+
+        async connect<T extends Record<string, ChainDefinition>>(chains: T) {
+            log.debug("connect called", { chains: Object.keys(chains) });
+            return createChainClient({ chains });
+        },
+
+        isConnected(descriptor) {
+            return isConnected(descriptor);
+        },
+
+        destroyAll() {
+            log.debug("destroyAll called");
+            destroyAll();
+        },
+    };
+
+    // Create Cloud Storage API adapter (null if disabled)
+    const cloudStorageApi: CloudStorageApi | null = cloudStorageClient
+        ? {
+              upload: async (data) => {
+                  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                  try {
+                      // Explicitly request a DAG-PB manifest so chunked uploads always
+                      // resolve to a single root CID. Without this, AsyncBulletinClient
+                      // can return `result.cid: undefined` for chunked-without-manifest
+                      // uploads — but app consumers expect a CID they can hand to
+                      // `fetch(cid)`, so treat a missing CID as an error.
+                      const uploaded = await cloudStorageClient
+                          .store(bytes)
+                          .withManifest(true)
+                          .send();
+                      if (!uploaded.cid) {
+                          return err(
+                              new ProductCloudStorageError(
+                                  "Cloud storage upload returned no CID despite .withManifest(true). Upstream contract may have shifted — file an issue.",
+                              ),
+                          );
+                      }
+                      return ok(uploaded.cid.toString());
+                  } catch (cause) {
+                      const message = cause instanceof Error ? cause.message : String(cause);
+                      return err(new ProductCloudStorageError(message, { cause }));
+                  }
+              },
+              fetch: (cid) => cloudStorageClient.fetchBytes(cid),
+              computeCid: async (data) => {
+                  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                  const cid = await calculateCid(bytes);
+                  return cid.toString();
+              },
+          }
+        : null;
+
+    log.info("Product SDK app created", {
+        name: config.name,
+        cloudStorage: cloudStorageEnabled ? cloudStorageEnvironment : "disabled",
+    });
+
+    return {
+        wallet: walletApi,
+        localStorage: localStorageApi,
+        chain: chainApi,
+        cloudStorage: cloudStorageApi,
+        getAppInfo: () => ({ ...config }),
+    };
+}
+
+/**
+ * Create wallet API adapter using SignerManager from leaf package
+ */
+function createWalletApi(signerManager: SignerManager): WalletApi {
+    // Track account change subscribers
+    const accountChangeSubscribers = new Set<(account: Account | null) => void>();
+
+    // Subscribe to signer manager state changes
+    signerManager.subscribe((state) => {
+        const account = state.selectedAccount
+            ? {
+                  address: state.selectedAccount.address,
+                  name: state.selectedAccount.name ?? undefined,
+                  source: state.selectedAccount.source,
+              }
+            : null;
+        for (const callback of accountChangeSubscribers) {
+            try {
+                callback(account);
+            } catch (e) {
+                log.warn("Account change callback threw", { error: e });
+            }
+        }
+    });
+
+    return {
+        async connect(): Promise<{ accounts: Account[] }> {
+            const result = await signerManager.connect();
+            if (!result.ok) {
+                throw new Error(result.error.message);
+            }
+            return {
+                accounts: result.value.map((a) => ({
+                    address: a.address,
+                    name: a.name ?? undefined,
+                    source: a.source,
+                })),
+            };
+        },
+
+        async disconnect(): Promise<void> {
+            signerManager.disconnect();
+        },
+
+        getAccounts(): Account[] {
+            return signerManager.getState().accounts.map((a) => ({
+                address: a.address,
+                name: a.name ?? undefined,
+                source: a.source,
+            }));
+        },
+
+        getSelectedAccount(): Account | null {
+            const selected = signerManager.getState().selectedAccount;
+            if (!selected) return null;
+            return {
+                address: selected.address,
+                name: selected.name ?? undefined,
+                source: selected.source,
+            };
+        },
+
+        selectAccount(address: string): void {
+            signerManager.selectAccount(address);
+        },
+
+        async signMessage(message: string | Uint8Array): Promise<Uint8Array> {
+            const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+            const result = await signerManager.signRaw(bytes);
+            if (!result.ok) {
+                throw new Error(result.error.message);
+            }
+            return result.value;
+        },
+
+        async signMessageWithDotNsIdentity(args) {
+            const message =
+                typeof args.message === "string"
+                    ? new TextEncoder().encode(args.message)
+                    : args.message;
+            const accountsProvider = await getHostAccountsProvider();
+            const username = args.username ?? (await getPrimaryUsername(accountsProvider));
+
+            // Reuse an already-connected People chain when the caller has
+            // wired one up via `app.chain.connect({ ..., <name>: peopleChain })`.
+            // Fall back to opening a transient connection so first-time users
+            // don't have to think about chain lifecycles. The chain-client
+            // module caches by genesis fingerprint, so subsequent
+            // signMessageWithDotNsIdentity calls share whichever connection
+            // got established first.
+            const peopleClient = isConnected(args.peopleChain)
+                ? getClient(args.peopleChain)
+                : await createChainClient({ chains: { people: args.peopleChain } }).then(
+                      (c) => c.raw.people,
+                  );
+            // PAPI's `TypedApi.query.X.Y.getValue` is variadic
+            // (`...args: [...WithCallOptions<Args>]`) so it's not assignable
+            // to our deliberately-narrow `(key) => Promise<...>` shape. The
+            // resolver only ever passes the storage key; the cast adapts the
+            // wider PAPI surface to the minimum we depend on.
+            const peopleApi = peopleClient.getTypedApi(
+                args.peopleChain,
+            ) as unknown as PeopleUsernameQueryApi;
+            const owner = await resolvePeopleUsernameOwner(username, peopleApi);
+            if (!owner) {
+                throw new Error(`No account owns DotNS username "${username}"`);
+            }
+
+            const publicKey = accountIdBytes(owner);
+            // This field is hex, not the SS58 the resolver now returns. Converted
+            // here and not in the try, so an address failure is not reported as a
+            // signing failure.
+            const accountId = accountIdBytesToHex(publicKey);
+            const signer = accountsProvider.getLegacyAccountSigner({ publicKey, name: username });
+
+            try {
+                return {
+                    username,
+                    accountId,
+                    signature: await signer.signBytes(message),
+                };
+            } catch (cause) {
+                throw new Error(
+                    `Failed to sign with DotNS username "${username}": ${
+                        cause instanceof Error ? cause.message : String(cause)
+                    }`,
+                    { cause },
+                );
+            }
+        },
+
+        onAccountChange(callback: (account: Account | null) => void): () => void {
+            accountChangeSubscribers.add(callback);
+            return () => accountChangeSubscribers.delete(callback);
+        },
+
+        getProductAccount(): Account | null {
+            // Product accounts require async call - this sync API can't support it properly
+            // Users should use SignerManager.getProductAccount() directly
+            log.warn(
+                "getProductAccount() is deprecated - use SignerManager.getProductAccount() directly",
+            );
+            return null;
+        },
+
+        getAnonymousAlias(): string | null {
+            // Anonymous aliases require async call - this sync API can't support it properly
+            // Users should use SignerManager.getProductAccountAlias() directly
+            log.warn(
+                "getAnonymousAlias() is deprecated - use SignerManager.getProductAccountAlias() directly",
+            );
+            return null;
+        },
+
+        async createProof(_message: Uint8Array): Promise<Uint8Array> {
+            // Ring VRF proofs require SignerManager.createRingVRFProof() directly
+            throw new Error(
+                "createProof() is not implemented in the App API. " +
+                    "Use SignerManager.createRingVRFProof() directly.",
+            );
+        },
+    };
+}
+
+type HostAccountsProvider = NonNullable<Awaited<ReturnType<typeof getAccountsProvider>>>;
+
+async function getHostAccountsProvider(): Promise<HostAccountsProvider> {
+    const provider = await getAccountsProvider();
+    if (!provider) {
+        throw new Error("Host accounts provider is not available");
+    }
+    return provider;
+}
+
+async function getPrimaryUsername(accountsProvider: HostAccountsProvider): Promise<string> {
+    const result = await accountsProvider.getUserId().match(
+        (value) => value,
+        (err) => {
+            throw err;
+        },
+    );
+    const username = result.primaryUsername.trim();
+    if (!username) {
+        throw new Error("Host identity did not provide a primary DotNS username");
+    }
+    return username;
+}

package/src/core/index.ts

@@ -0,0 +1,12 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk core module
+ *
+ * Core functionality including createApp, logger, and type definitions.
+ */
+
+export { createApp } from "./createApp.js";
+export { configure, createLogger } from "./logger.js";
+export type { LogEntry, LogHandler, LoggerConfig, Logger } from "./logger.js";
+export * from "./types.js";

package/src/core/logger.ts

@@ -0,0 +1,15 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Logger module for @parity/product-sdk
+ *
+ * Re-exports from @parity/product-sdk-logger.
+ */
+export { configure, createLogger } from "@parity/product-sdk-logger";
+export type {
+    LogLevel,
+    LogEntry,
+    LogHandler,
+    LoggerConfig,
+    Logger,
+} from "@parity/product-sdk-logger";

package/src/core/types.ts

@@ -0,0 +1,233 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Core types for @parity/product-sdk
+ */
+
+import type { LogLevel } from "@parity/product-sdk-logger";
+import type {
+    CloudStorageEnvironment,
+    ProductCloudStorageError,
+} from "@parity/product-sdk-cloud-storage";
+import type { Result } from "@parity/result";
+import type { ChainClient } from "@parity/product-sdk-chain-client";
+import type { PeopleUsernameChain } from "../identity/dotns.js";
+import type { ChainDefinition, TypedApi, PolkadotClient } from "polkadot-api";
+
+export type { LogLevel };
+export type { ChainClient };
+
+/** Cloud Storage configuration options */
+export interface CloudStorageConfig {
+    /** Cloud Storage environment to connect to */
+    environment: CloudStorageEnvironment;
+}
+
+/** Configuration for createApp */
+export interface AppConfig {
+    /** Application name - used to derive product accounts and namespace storage */
+    name: string;
+    /** Log level for SDK operations (default: 'info') */
+    logLevel?: LogLevel;
+    /**
+     * Cloud Storage configuration.
+     * - Omit or pass config object to enable (default: { environment: "paseo" })
+     * - Pass `false` to disable cloud storage initialization
+     */
+    cloudStorage?: CloudStorageConfig | false;
+}
+
+/** Wallet API exposed by the SDK */
+export interface WalletApi {
+    /** Connect to available wallet providers */
+    connect(): Promise<{ accounts: Account[] }>;
+    /** Disconnect from wallet */
+    disconnect(): Promise<void>;
+    /** Get all available accounts */
+    getAccounts(): Account[];
+    /** Get currently selected account */
+    getSelectedAccount(): Account | null;
+    /** Select an account by address */
+    selectAccount(address: string): void;
+    /** Sign an arbitrary message */
+    signMessage(message: string | Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a message with the account that owns a People / People Lite DotNS identity.
+     *
+     * Pass the People / Individuality chain descriptor used for username lookup.
+     * Pass `username` to choose a specific identity. When omitted, the SDK first
+     * asks the host for the user's primary DotNS name and signs with the account
+     * that owns that username.
+     */
+    signMessageWithDotNsIdentity(
+        args: SignMessageWithDotNsIdentityArgs,
+    ): Promise<DotNsIdentitySignature>;
+    /** Subscribe to account changes */
+    onAccountChange(callback: (account: Account | null) => void): () => void;
+    /** Get product-scoped account (container mode only) */
+    getProductAccount(): Account | null;
+    /** Get anonymous alias via Ring VRF (container mode only) */
+    getAnonymousAlias(): string | null;
+    /** Create Ring VRF proof (container mode only) */
+    createProof(message: Uint8Array): Promise<Uint8Array>;
+}
+
+/** Storage API exposed by the SDK */
+export interface LocalStorageApi {
+    /** Get a value by key */
+    get(key: string): Promise<string | null>;
+    /** Set a value by key */
+    set(key: string, value: string): Promise<void>;
+    /** Get a JSON value by key */
+    getJSON<T = unknown>(key: string): Promise<T | null>;
+    /** Set a JSON value by key */
+    setJSON<T = unknown>(key: string, value: T): Promise<void>;
+    /** Remove a value by key */
+    remove(key: string): Promise<void>;
+    /** Clear all values */
+    clear(): Promise<void>;
+}
+
+/** Chain API exposed by the SDK */
+export interface ChainApi {
+    /**
+     * Get a typed PAPI client for a chain.
+     *
+     * Connections are routed through the host provider. The chain must be
+     * connected first via {@link connect}.
+     *
+     * @param descriptor - PAPI chain descriptor (from @parity/product-sdk-descriptors or custom)
+     * @returns Typed API for the chain
+     * @throws If the chain is not connected
+     */
+    getClient<T extends ChainDefinition>(descriptor: T): TypedApi<T>;
+
+    /**
+     * Get the raw PolkadotClient for a chain.
+     *
+     * Use this for advanced APIs like `createContractRuntime` from `@parity/product-sdk-contracts`.
+     *
+     * @param descriptor - PAPI chain descriptor
+     * @returns Raw PolkadotClient instance
+     * @throws If the chain is not connected
+     */
+    getRawClient(descriptor: ChainDefinition): PolkadotClient;
+
+    /**
+     * Connect to one or more chains.
+     *
+     * Connections are routed through the host provider (container-only).
+     * Results are cached - calling with the same descriptors returns existing connections.
+     *
+     * @param chains - Record of named chain descriptors
+     * @returns Connected chain client with typed APIs
+     */
+    connect<T extends Record<string, ChainDefinition>>(chains: T): Promise<ChainClient<T>>;
+
+    /**
+     * Check if a chain is currently connected.
+     */
+    isConnected(descriptor: ChainDefinition): boolean;
+
+    /**
+     * Destroy all chain connections.
+     */
+    destroyAll(): void;
+}
+
+/** Cloud Storage API exposed by the SDK */
+export interface CloudStorageApi {
+    /**
+     * Upload data to the Cloud.
+     *
+     * Requires a wallet to be connected and an account selected.
+     *
+     * @returns A {@link Result}: `ok(cid)` on success, or `err(ProductCloudStorageError)`
+     *   if the upload fails (no signer, network rejection, or no CID returned).
+     */
+    upload(data: string | Uint8Array): Promise<Result<string, ProductCloudStorageError>>;
+    /**
+     * Fetch data by CID.
+     *
+     * @returns A {@link Result}: `ok(bytes)` on success, or `err(ProductCloudStorageError)`.
+     */
+    fetch(cid: string): Promise<Result<Uint8Array, ProductCloudStorageError>>;
+    /**
+     * Compute the CID for data without uploading.
+     *
+     * Async because the underlying hash is computed via Web Crypto. Does not
+     * perform I/O, so it throws on invalid input rather than returning a Result.
+     */
+    computeCid(data: string | Uint8Array): Promise<string>;
+}
+
+/** The main App instance returned by createApp */
+export interface App {
+    /** Wallet/signing operations */
+    wallet: WalletApi;
+    /** Local Key-value storage operations */
+    localStorage: LocalStorageApi;
+    /** Chain interaction operations */
+    chain: ChainApi;
+    /** Cloud Storage operations (null if disabled via config) */
+    cloudStorage: CloudStorageApi | null;
+    /** Get app configuration */
+    getAppInfo(): AppConfig;
+}
+
+/** Account information */
+export interface Account {
+    /** Account address (SS58 format) */
+    address: string;
+    /** Account name/label (if available) */
+    name?: string;
+    /** Source of the account (host, dev signer, etc.) */
+    source: string;
+}
+
+/** Arguments for signing with a DotNS / People username identity. */
+export interface SignMessageWithDotNsIdentityArgs {
+    /**
+     * PAPI descriptor for the People / Individuality chain that exposes
+     * `Resources.UsernameOwnerOf`.
+     *
+     * The SDK reuses an already-connected client when one matches this
+     * descriptor's genesis. For long-running apps, call
+     * `app.chain.connect({ ..., <name>: peopleChain })` once at startup so
+     * every subsequent `signMessageWithDotNsIdentity` call reuses the same
+     * chainHead subscription. When the chain isn't already connected, the
+     * SDK opens a transient connection for the lookup; that connection then
+     * lives in the chain-client cache for the rest of the process.
+     */
+    peopleChain: PeopleUsernameChain;
+    /**
+     * People / People Lite username to resolve before signing.
+     *
+     * If omitted, the SDK fetches the primary DotNS name associated with the
+     * connected user from the host identity API. Note: that fetch triggers a
+     * host identity-permission prompt, so callers who want to avoid the
+     * dialog on a likely-miss should resolve the username themselves first.
+     *
+     * The string is UTF-8 encoded and used as the storage key on
+     * `Resources.UsernameOwnerOf` exactly as supplied — no `.dot` suffix
+     * handling is applied. On paseo-individuality today usernames are
+     * stored as bare strings (e.g. `alice`, not `alice.dot`); pass the
+     * exact value the chain has registered.
+     */
+    username?: string;
+    /** Message to sign. Strings are UTF-8 encoded before signing. */
+    message: string | Uint8Array;
+}
+
+/** Signature produced for a DotNS / People username identity. */
+export interface DotNsIdentitySignature {
+    /** Username used for the lookup. */
+    username: string;
+    /** Raw `AccountId32` owner resolved from `Resources.UsernameOwnerOf`. */
+    accountId: `0x${string}`;
+    /** Signature bytes returned by the host wallet. */
+    signature: Uint8Array;
+}
+
+// Re-export ChainDefinition from polkadot-api for convenience
+export type { ChainDefinition, TypedApi, PolkadotClient } from "polkadot-api";

package/src/crypto/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/crypto
+ *
+ * Re-exports from @parity/product-sdk-crypto.
+ */
+export * from "@parity/product-sdk-crypto";

package/src/host/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/host
+ *
+ * Re-exports from @parity/product-sdk-host.
+ */
+export * from "@parity/product-sdk-host";