@propxchain/core-client 0.1.0-canary.3

package/src/mock.ts

@@ -0,0 +1,120 @@
+import { Principal } from "@dfinity/principal";
+import type {
+  IPropXchainClient,
+  TransactionManagerService,
+  DocumentStorageService,
+  UserManagementService,
+  LedgerManagerService,
+} from "./types.js";
+import {
+  createAuditTrailStub,
+  createAgentHarnessStub,
+  type AuditTrailStub,
+  type AgentHarnessStub,
+} from "./stubs.js";
+
+export const MOCK_ENV_FLAG = "NEXT_PUBLIC_USE_MOCK";
+
+const MOCK_PRINCIPAL = Principal.fromText("2vxsx-fae");
+const NOW = 1_735_689_600_000_000_000n; // 2026-01-01 as ns bigint for determinism
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+/**
+ * Build a Proxy that returns a deterministic mock for any method call.
+ * Specific methods listed in `overrides` take precedence. Anything else
+ * returns a harmless default matching typical Candid shapes.
+ */
+function mockService<T extends object>(
+  overrides: Partial<Record<keyof T, AnyFn>>,
+): T {
+  return new Proxy({} as T, {
+    get(_target, prop: string | symbol) {
+      const override = (overrides as Record<string | symbol, AnyFn>)[prop];
+      if (typeof override === "function") return override;
+      return async () => ({ ok: null });
+    },
+  });
+}
+
+export function createMockTransactionManager(): TransactionManagerService {
+  return mockService<TransactionManagerService>({
+    getMyTransactions: async () => [],
+    getAllTransactions: async () => [],
+    getCycles: async () => 1_000_000_000_000n,
+    getTransaction: async (id: unknown) =>
+      typeof id === "string" && id === "mock-tx-001"
+        ? [{
+            id: "mock-tx-001",
+            propertyAddress: "1 Mock Street, Sandy, SG19 0AA",
+            buyer: MOCK_PRINCIPAL,
+            seller: MOCK_PRINCIPAL,
+            price: 350_000n,
+            status: { pending: null },
+            createdAt: NOW,
+          }] as never
+        : [],
+    doesTransactionExist: async (id: unknown) =>
+      id === "mock-tx-001",
+    getUnreadNotificationCount: async () => 0n,
+    getMyNotifications: async () => [],
+  });
+}
+
+export function createMockDocumentStorage(): DocumentStorageService {
+  return mockService<DocumentStorageService>({
+    getCycles: async () => 500_000_000_000n,
+    getStorageStats: async () => ({
+      averageFileSizeBytes: 0n,
+      totalSizeBytes: 0n,
+      verifiedDocuments: 0n,
+      totalDocuments: 0n,
+    }),
+    getTransactionDocuments: async () => [],
+    getAuditLogs: async () => [],
+  });
+}
+
+export function createMockUserManagement(): UserManagementService {
+  return mockService<UserManagementService>({
+    getCycles: async () => 400_000_000_000n,
+  });
+}
+
+export function createMockLedgerManager(): LedgerManagerService {
+  return mockService<LedgerManagerService>({
+    getCycles: async () => 600_000_000_000n,
+  });
+}
+
+export class MockPropXchainClient implements IPropXchainClient {
+  readonly transactionManager: TransactionManagerService;
+  readonly documentStorage: DocumentStorageService;
+  readonly userManagement: UserManagementService;
+  readonly ledgerManager: LedgerManagerService;
+  readonly auditTrail: AuditTrailStub;
+  readonly agentHarness: AgentHarnessStub;
+
+  constructor() {
+    this.transactionManager = createMockTransactionManager();
+    this.documentStorage = createMockDocumentStorage();
+    this.userManagement = createMockUserManagement();
+    this.ledgerManager = createMockLedgerManager();
+    this.auditTrail = createAuditTrailStub();
+    this.agentHarness = createAgentHarnessStub();
+  }
+}
+
+/**
+ * True when NEXT_PUBLIC_USE_MOCK is set to "true" (case-insensitive).
+ * Consumers decide at construction time which client to use.
+ */
+export function isMockEnabled(env: Record<string, string | undefined> = readEnv()): boolean {
+  const raw = env[MOCK_ENV_FLAG];
+  return typeof raw === "string" && raw.toLowerCase() === "true";
+}
+
+function readEnv(): Record<string, string | undefined> {
+  if (typeof process !== "undefined" && process.env) return process.env;
+  return {};
+}

package/src/retry.ts

@@ -0,0 +1,44 @@
+import { CoreClientError, wrapAgentError } from "./errors.js";
+
+export interface RetryOptions {
+  retries?: number;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  factor?: number;
+  shouldRetry?: (err: CoreClientError, attempt: number) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const defaultShouldRetry = (err: CoreClientError) =>
+  err.code === "NETWORK" || err.code === "TIMEOUT";
+
+const defaultSleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    retries = 3,
+    initialDelayMs = 200,
+    maxDelayMs = 2000,
+    factor = 2,
+    shouldRetry = defaultShouldRetry,
+    sleep = defaultSleep,
+  } = options;
+
+  let attempt = 0;
+  let delay = initialDelayMs;
+  while (true) {
+    try {
+      return await fn();
+    } catch (raw) {
+      const err = wrapAgentError(raw);
+      if (attempt >= retries || !shouldRetry(err, attempt)) throw err;
+      await sleep(delay);
+      delay = Math.min(delay * factor, maxDelayMs);
+      attempt += 1;
+    }
+  }
+}

package/src/stubs.ts

@@ -0,0 +1,60 @@
+import { CoreClientError } from "./errors.js";
+
+/**
+ * Audit trail canister is not yet deployed. This stub exists so consumers can
+ * depend on a stable surface area now; real methods land when the canister ships.
+ */
+export interface AuditTrailStub {
+  readonly __stub: true;
+  append(event: AuditEvent): Promise<never>;
+  query(filter: AuditFilter): Promise<never>;
+}
+
+export interface AuditEvent {
+  transactionId: string;
+  actor: string;
+  action: string;
+  timestamp: bigint;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AuditFilter {
+  transactionId?: string;
+  actor?: string;
+  since?: bigint;
+  until?: bigint;
+}
+
+/**
+ * Agent harness is a sandboxed interface for AI agents. Stubbed per A2 scope;
+ * the real harness lands in Phase 5+.
+ */
+export interface AgentHarnessStub {
+  readonly __stub: true;
+  listCapabilities(): Promise<never>;
+  invoke(capability: string, payload: unknown): Promise<never>;
+}
+
+const notImplemented = (name: string): Promise<never> =>
+  Promise.reject(
+    new CoreClientError(
+      "UNKNOWN",
+      `${name} is stubbed in @propxchain/core-client v0.1.0 — canister not yet deployed`,
+    ),
+  );
+
+export function createAuditTrailStub(): AuditTrailStub {
+  return {
+    __stub: true,
+    append: () => notImplemented("AuditTrail.append"),
+    query: () => notImplemented("AuditTrail.query"),
+  };
+}
+
+export function createAgentHarnessStub(): AgentHarnessStub {
+  return {
+    __stub: true,
+    listCapabilities: () => notImplemented("AgentHarness.listCapabilities"),
+    invoke: () => notImplemented("AgentHarness.invoke"),
+  };
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+import type { HttpAgent, Identity } from "@dfinity/agent";
+import type { TransactionManagerService } from "./canisters/transaction_manager/index.js";
+import type { DocumentStorageService } from "./canisters/document_storage/index.js";
+import type { UserManagementService } from "./canisters/user_management/index.js";
+import type { LedgerManagerService } from "./canisters/ledger_manager/index.js";
+import type { AuditTrailStub, AgentHarnessStub } from "./stubs.js";
+
+export interface CanisterIds {
+  transactionManager: string;
+  documentStorage: string;
+  userManagement: string;
+  ledgerManager: string;
+}
+
+export const MAINNET_CANISTER_IDS: CanisterIds = {
+  transactionManager: "llj73-cqaaa-aaaaa-qcwwa-cai",
+  documentStorage: "646az-pqaaa-aaaaa-qczja-cai",
+  userManagement: "lmizp-piaaa-aaaaa-qcwwq-cai",
+  ledgerManager: "hty74-maaaa-aaaaa-qcxza-cai",
+};
+
+export interface PropXchainClientOptions {
+  canisterIds?: Partial<CanisterIds>;
+  host?: string;
+  agent?: HttpAgent;
+  identity?: Identity;
+  fetchRootKey?: boolean;
+}
+
+export interface IPropXchainClient {
+  readonly transactionManager: TransactionManagerService;
+  readonly documentStorage: DocumentStorageService;
+  readonly userManagement: UserManagementService;
+  readonly ledgerManager: LedgerManagerService;
+  readonly auditTrail: AuditTrailStub;
+  readonly agentHarness: AgentHarnessStub;
+}
+
+export type {
+  TransactionManagerService,
+  DocumentStorageService,
+  UserManagementService,
+  LedgerManagerService,
+};