@parity/product-sdk 0.1.0

package/src/core/createApp.ts

@@ -0,0 +1,284 @@
+/**
+ * createApp - Main entry point for the Product SDK
+ *
+ * Creates an App instance with wallet, storage, chain, and bulletin APIs.
+ */
+
+import type { ChainDefinition } from "polkadot-api";
+import type {
+    App,
+    AppConfig,
+    WalletApi,
+    StorageApi,
+    ChainApi,
+    BulletinApi,
+    Account,
+} from "./types.js";
+import { configure, createLogger } from "@parity/product-sdk-logger";
+import { createKvStore } from "@parity/product-sdk-storage";
+import { SignerManager } from "@parity/product-sdk-signer";
+import { BulletinClient, computeCid } from "@parity/product-sdk-bulletin";
+import {
+    createChainClient,
+    getClient,
+    isConnected,
+    destroyAll,
+} from "@parity/product-sdk-chain-client";
+
+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: bulletin enabled with paseo environment
+ * const app = await createApp({
+ *   name: 'my-app',
+ *   logLevel: 'info',
+ * });
+ *
+ * // Custom bulletin environment
+ * const prodApp = await createApp({
+ *   name: 'my-app',
+ *   bulletin: { environment: 'polkadot' },
+ * });
+ *
+ * // Disable bulletin entirely
+ * const noBulletinApp = await createApp({
+ *   name: 'my-app',
+ *   bulletin: false,
+ * });
+ *
+ * // Connect wallet
+ * const { accounts } = await app.wallet.connect();
+ *
+ * // Use storage
+ * await app.storage.set('key', 'value');
+ *
+ * // Use bulletin (check for null if it might be disabled)
+ * if (app.bulletin) {
+ *   const cid = await app.bulletin.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 kvStore = await createKvStore({ prefix: config.name });
+
+    // Initialize signer manager
+    const signerManager = new SignerManager({
+        dappName: config.name,
+    });
+
+    // Initialize bulletin client (configurable, defaults to paseo)
+    const bulletinEnabled = config.bulletin !== false;
+    const bulletinEnvironment =
+        typeof config.bulletin === "object" ? config.bulletin.environment : "paseo";
+    const bulletinClient = bulletinEnabled
+        ? await BulletinClient.create(bulletinEnvironment)
+        : null;
+
+    if (bulletinEnabled) {
+        log.debug("Bulletin client initialized", { environment: bulletinEnvironment });
+    } else {
+        log.debug("Bulletin client disabled");
+    }
+
+    // Create storage API adapter
+    const storageApi: StorageApi = {
+        get: (key) => kvStore.get(key),
+        set: (key, value) => kvStore.set(key, value),
+        getJSON: <T>(key: string) => kvStore.getJSON<T>(key),
+        setJSON: <T>(key: string, value: T) => kvStore.setJSON(key, value),
+        remove: (key) => kvStore.remove(key),
+        clear: async () => {
+            // KvStore 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) });
+            // Build empty rpcs object (required by API but unused - host routes connections)
+            const rpcs = Object.fromEntries(
+                Object.keys(chains).map((k) => [k, [] as readonly string[]]),
+            ) as { [K in keyof T]: readonly string[] };
+            return createChainClient({ chains, rpcs });
+        },
+
+        isConnected(descriptor) {
+            return isConnected(descriptor);
+        },
+
+        destroyAll() {
+            log.debug("destroyAll called");
+            destroyAll();
+        },
+    };
+
+    // Create bulletin API adapter (null if disabled)
+    const bulletinApi: BulletinApi | null = bulletinClient
+        ? {
+              upload: async (data) => {
+                  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                  const result = await bulletinClient.upload(bytes);
+                  return result.cid;
+              },
+              fetch: (cid) => bulletinClient.fetchBytes(cid),
+              computeCid: (data) => {
+                  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                  return computeCid(bytes);
+              },
+          }
+        : null;
+
+    log.info("Product SDK app created", {
+        name: config.name,
+        bulletin: bulletinEnabled ? bulletinEnvironment : "disabled",
+    });
+
+    return {
+        wallet: walletApi,
+        storage: storageApi,
+        chain: chainApi,
+        bulletin: bulletinApi,
+        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;
+        },
+
+        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.",
+            );
+        },
+    };
+}

package/src/core/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @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,13 @@
+/**
+ * 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,155 @@
+/**
+ * Core types for @parity/product-sdk
+ */
+
+import type { LogLevel } from "@parity/product-sdk-logger";
+import type { Environment as BulletinEnvironment } from "@parity/product-sdk-bulletin";
+import type { ChainClient } from "@parity/product-sdk-chain-client";
+import type { ChainDefinition, TypedApi, PolkadotClient } from "polkadot-api";
+
+export type { LogLevel };
+export type { ChainClient };
+
+/** Bulletin configuration options */
+export interface BulletinConfig {
+    /** Bulletin environment to connect to */
+    environment: BulletinEnvironment;
+}
+
+/** 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;
+    /**
+     * Bulletin Chain configuration.
+     * - Omit or pass config object to enable (default: { environment: "paseo" })
+     * - Pass `false` to disable bulletin initialization
+     */
+    bulletin?: BulletinConfig | 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>;
+    /** 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 StorageApi {
+    /** 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 `createInkSdk` from `@polkadot-api/sdk-ink`.
+     *
+     * @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;
+}
+
+/** Bulletin Chain API exposed by the SDK */
+export interface BulletinApi {
+    /** Upload data to Bulletin Chain */
+    upload(data: string | Uint8Array): Promise<string>;
+    /** Fetch data by CID */
+    fetch(cid: string): Promise<Uint8Array>;
+    /** Compute CID for data without uploading */
+    computeCid(data: string | Uint8Array): string;
+}
+
+/** The main App instance returned by createApp */
+export interface App {
+    /** Wallet/signing operations */
+    wallet: WalletApi;
+    /** Key-value storage operations */
+    storage: StorageApi;
+    /** Chain interaction operations */
+    chain: ChainApi;
+    /** Bulletin Chain operations (null if disabled via config) */
+    bulletin: BulletinApi | 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 (extension name, host, etc.) */
+    source: string;
+}
+
+// Re-export ChainDefinition from polkadot-api for convenience
+export type { ChainDefinition, TypedApi, PolkadotClient } from "polkadot-api";

package/src/crypto/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @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,6 @@
+/**
+ * @parity/product-sdk/host
+ *
+ * Re-exports from @parity/product-sdk-host.
+ */
+export * from "@parity/product-sdk-host";

package/src/identity/dotns.ts

@@ -0,0 +1,96 @@
+/**
+ * DotNS (Polkadot Name Service) utilities
+ *
+ * Provides name resolution for .dot domains
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+import type { DotNsRecord } from "./types.js";
+
+const log = createLogger("identity");
+
+/**
+ * Check if a string is a valid DotNS name
+ *
+ * @param name - Name to validate
+ * @returns True if valid DotNS name
+ */
+export function isValidDotNsName(name: string): boolean {
+    // Basic validation: alphanumeric, hyphens, ends with .dot
+    if (!name.endsWith(".dot")) return false;
+    const label = name.slice(0, -4);
+    if (label.length < 3 || label.length > 63) return false;
+    return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(label);
+}
+
+/**
+ * Normalize a DotNS name (lowercase, trim whitespace)
+ *
+ * @param name - Name to normalize
+ * @returns Normalized name
+ */
+export function normalizeDotNsName(name: string): string {
+    let normalized = name.toLowerCase().trim();
+    if (!normalized.endsWith(".dot")) {
+        normalized += ".dot";
+    }
+    return normalized;
+}
+
+/**
+ * Resolve a DotNS name to an address
+ *
+ * @param name - DotNS name (e.g., "alice.dot")
+ * @returns Resolved record or null if not found
+ *
+ * @example
+ * ```ts
+ * const record = await resolveDotNs('alice.dot');
+ * if (record) {
+ *   console.log('Address:', record.address);
+ * }
+ * ```
+ */
+export async function resolveDotNs(name: string): Promise<DotNsRecord | null> {
+    const normalized = normalizeDotNsName(name);
+
+    if (!isValidDotNsName(normalized)) {
+        log.warn("Invalid DotNS name", { name });
+        return null;
+    }
+
+    log.debug("Resolving DotNS name", { name: normalized });
+
+    // TODO: Implement via PAPI query to DotNS pallet
+    throw new Error(
+        "resolveDotNs() is not yet implemented. " +
+            "This is a skeleton for the Product SDK structure.",
+    );
+}
+
+/**
+ * Reverse resolve an address to a DotNS name
+ *
+ * @param address - SS58 address
+ * @returns Primary name or null if none set
+ */
+export async function reverseDotNs(address: string): Promise<string | null> {
+    log.debug("Reverse resolving address", { address });
+
+    // TODO: Implement via PAPI query to DotNS pallet
+    throw new Error(
+        "reverseDotNs() is not yet implemented. " +
+            "This is a skeleton for the Product SDK structure.",
+    );
+}
+
+/**
+ * Check if a DotNS name is available for registration
+ *
+ * @param name - Name to check
+ * @returns True if available
+ */
+export async function isDotNsAvailable(name: string): Promise<boolean> {
+    const record = await resolveDotNs(name).catch(() => null);
+    return record === null;
+}

package/src/identity/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @parity/product-sdk/identity
+ *
+ * Identity utilities including DotNS name resolution,
+ * product account derivation, and Ring VRF anonymous aliases.
+ */
+
+// DotNS utilities
+export {
+    isValidDotNsName,
+    normalizeDotNsName,
+    resolveDotNs,
+    reverseDotNs,
+    isDotNsAvailable,
+} from "./dotns.js";
+
+// Product account utilities
+export {
+    deriveProductAccount,
+    verifyProductAccount,
+    deriveAnonymousAlias,
+    createRingProof,
+    verifyRingProof,
+} from "./product-account.js";
+
+// Types
+export type {
+    DotNsRecord,
+    ProductAccountInfo,
+    AnonymousAliasInfo,
+    RingLocation,
+    VerificationResult,
+    OnChainIdentity,
+} from "./types.js";