@sundaeswap/sprinkles 0.4.0 → 0.6.0

package/src/Sprinkle/tx-dialog.ts

@@ -0,0 +1,100 @@
+/**
+ * Transaction dialog helper utilities.
+ * Functions for working with transaction signatures and display.
+ */
+
+import { Core, HotWallet } from "@blaze-cardano/sdk";
+import { CborSet, VkeyWitness, blake2b_256 } from "@blaze-cardano/core";
+
+/**
+ * Get the payment key hash from a HotWallet's first address.
+ */
+export async function getWalletPaymentKeyHash(
+  wallet: HotWallet,
+): Promise<string | null> {
+  try {
+    const addresses = await wallet.getUsedAddresses();
+    const address = addresses[0];
+    if (!address) return null;
+    const paymentCredential = address.asBase()?.getPaymentCredential();
+    return paymentCredential?.hash?.toString() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count the number of vkey signatures in a transaction's witness set.
+ */
+export function countSignatures(tx: Core.Transaction): number {
+  const vkeys = tx.witnessSet().vkeys();
+  return vkeys ? vkeys.size() : 0;
+}
+
+/**
+ * Check if a specific public key has already signed the transaction.
+ * Compares by vkey (public key bytes).
+ */
+export function hasVkeySigned(tx: Core.Transaction, vkeyHex: string): boolean {
+  const vkeys = tx.witnessSet().vkeys();
+  if (!vkeys) return false;
+  const vkeyArray = vkeys.toCore();
+  return vkeyArray.some(([vkey]) => vkey === vkeyHex);
+}
+
+/**
+ * Get the list of required signer key hashes from the transaction body.
+ */
+export function getRequiredSigners(tx: Core.Transaction): string[] {
+  const requiredSigners = tx.body().requiredSigners();
+  if (!requiredSigners) return [];
+  return Array.from(requiredSigners.values()).map((s) => s.toString());
+}
+
+/**
+ * Compute the transaction body hash for display.
+ */
+export function getTxBodyHash(tx: Core.Transaction): string {
+  const bodyCbor = tx.body().toCbor();
+  return blake2b_256(bodyCbor);
+}
+
+/**
+ * Format a hash for display: first 8 chars + ... + last 8 chars.
+ */
+export function formatHash(hash: string): string {
+  if (hash.length <= 20) return hash;
+  return `${hash.slice(0, 8)}...${hash.slice(-8)}`;
+}
+
+/**
+ * Merge signatures from source transaction into target transaction.
+ * Prevents duplicate signatures by comparing vkey (public key).
+ * Returns the count of newly added signatures.
+ */
+export function mergeSignatures(
+  target: Core.Transaction,
+  source: Core.Transaction,
+): number {
+  const targetWs = target.witnessSet();
+  const sourceWs = source.witnessSet();
+
+  const targetVkeys = targetWs.vkeys()?.toCore() ?? [];
+  const sourceVkeys = sourceWs.vkeys()?.toCore() ?? [];
+
+  // Find vkeys in source that aren't in target (by comparing public key)
+  const existingPubKeys = new Set(targetVkeys.map(([vkey]) => vkey));
+  const newVkeys = sourceVkeys.filter(([vkey]) => !existingPubKeys.has(vkey));
+
+  if (newVkeys.length === 0) {
+    return 0;
+  }
+
+  // Merge the new vkeys into target
+  targetWs.setVkeys(
+    CborSet.fromCore([...targetVkeys, ...newVkeys], VkeyWitness.fromCore),
+  );
+  target.setWitnessSet(targetWs);
+
+  return newVkeys.length;
+}

package/src/Sprinkle/type-guards.ts

@@ -0,0 +1,93 @@
+/**
+ * Type guard utilities for TypeBox schema types.
+ * These are internal helpers used by FillInStruct, encryption, and other modules.
+ */
+
+import {
+  Kind,
+  type TBigInt,
+  type TLiteral,
+  type TNull,
+  type TObject,
+  type TSchema,
+  type TString,
+  type TTuple,
+  type TUnion,
+  type TArray,
+  type TThis,
+  type TRef,
+  type TImport,
+  type TOptional,
+  type Static,
+  OptionalKind,
+} from "@sinclair/typebox";
+
+export const isOptional = <T extends TSchema>(t: T): t is TOptional<T> =>
+  t[OptionalKind] === "Optional";
+
+export const isImport = (t: TSchema): t is TImport => t[Kind] === "Import";
+
+export const isArray = (t: TSchema): t is TArray => t[Kind] === "Array";
+
+export const isBigInt = (t: TSchema): t is TBigInt => t[Kind] === "BigInt";
+
+export const isLiteral = (t: TSchema): t is TLiteral => t[Kind] === "Literal";
+
+export const isObject = (t: TSchema): t is TObject => t[Kind] === "Object";
+
+export const isRef = (t: TSchema): t is TRef => t[Kind] === "Ref";
+
+export const isString = (t: TSchema): t is TString => t[Kind] === "String";
+
+export const isThis = (t: TSchema): t is TThis => t[Kind] === "This";
+
+export const isTuple = (t: TSchema): t is TTuple => t[Kind] === "Tuple";
+
+export const isUnion = (t: TSchema): t is TUnion => t[Kind] === "Union";
+
+/**
+ * Check if a schema field is marked as sensitive.
+ * Sensitive fields are encrypted when saved and masked when displayed.
+ */
+export const isSensitive = (t: TSchema): boolean =>
+  isString(t) && t.sensitive === true;
+
+/**
+ * Check if a schema is a Null type.
+ */
+export const isNull = (t: TSchema): t is TNull => t[Kind] === "Null";
+
+/**
+ * Check if a schema allows null values.
+ * Returns true for TNull or unions containing TNull.
+ */
+export const isNullable = (t: TSchema): boolean => {
+  if (isNull(t)) return true;
+  if (isUnion(t)) return t.anyOf.some((member) => isNull(member));
+  return false;
+};
+
+/**
+ * Unwrap a nullable type to get the non-null inner type.
+ * For unions with Null, returns the union without the Null member.
+ * For single non-null member unions, returns just that type.
+ */
+export const unwrapNullable = (t: TSchema): TSchema => {
+  if (isUnion(t)) {
+    const nonNull = t.anyOf.filter((member) => !isNull(member));
+    if (nonNull.length === 1) return nonNull[0]!;
+    return { ...t, anyOf: nonNull } as TSchema;
+  }
+  return t;
+};
+
+/**
+ * Check if a schema has a default value defined.
+ */
+export const hasDefault = (t: TSchema): boolean => "default" in t;
+
+/**
+ * Get the default value from a schema, if defined.
+ */
+export const getDefault = <T extends TSchema>(t: T): Static<T> | undefined =>
+  t.default as Static<T> | undefined;

package/src/Sprinkle/types.ts

@@ -0,0 +1,116 @@
+import { Core } from "@blaze-cardano/sdk";
+import type { Static, TSchema } from "@sinclair/typebox";
+
+/**
+ * Utility type to extract the static type from a TypeBox schema.
+ */
+export type TExact<T> = T extends TSchema ? Static<T> : T;
+
+/**
+ * Options for encrypting/decrypting sensitive fields in settings.
+ */
+export interface IEncryptionOptions {
+  encrypt: (plaintext: string) => string;
+  decrypt: (ciphertext: string) => Promise<string>;
+}
+
+/**
+ * Options for configuring a Sprinkle instance.
+ */
+export interface ISprinkleOptions {
+  encryption?: IEncryptionOptions;
+}
+
+/**
+ * Metadata for a profile.
+ */
+export interface IProfileMeta {
+  name: string;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Current profile information including ID.
+ */
+export interface ICurrentProfile extends IProfileMeta {
+  id: string;
+}
+
+/**
+ * Profile entry as returned by scanProfiles().
+ */
+export interface IProfileEntry {
+  id: string;
+  meta: IProfileMeta;
+}
+
+/**
+ * Result of the TxDialog interaction.
+ */
+export interface TxDialogResult {
+  action: "submitted" | "signed" | "cancelled";
+  txId?: string; // present only if action === 'submitted'
+  tx: Core.Transaction; // the (potentially signed) transaction
+}
+
+/**
+ * Options for TxDialog.
+ */
+export interface TxDialogOptions {
+  beforeSign?: () => Promise<void>;
+}
+
+/**
+ * Error thrown when user cancels a prompt via Escape key.
+ */
+export class UserCancelledError extends Error {
+  constructor(message: string = "User cancelled the operation") {
+    super(message);
+    this.name = "UserCancelledError";
+  }
+}
+
+// --- Menu-based FillInStruct types ---
+
+/**
+ * State tracking for a single field during menu-based editing.
+ */
+export type FieldState<T = unknown> =
+  | { status: "unset" }
+  | { status: "set"; value: T }
+  | { status: "null" }; // explicitly set to null
+
+/**
+ * Result of counting required fields in a schema.
+ */
+export interface RequiredFieldCount {
+  total: number;
+  filled: number;
+}
+
+/**
+ * Result from field menu interaction.
+ */
+export type FieldMenuResult<T = unknown> =
+  | { action: "edit" }
+  | { action: "view" }
+  | { action: "clear" }
+  | { action: "setNull" }
+  | { action: "reset"; defaultValue: T }
+  | { action: "back" };
+
+/**
+ * Result from object menu interaction.
+ */
+export type ObjectMenuResult<T = unknown> =
+  | { action: "submit"; value: T }
+  | { action: "cancel" };
+
+/**
+ * Result from array menu interaction.
+ */
+export type ArrayMenuResult<T = unknown> =
+  | { action: "done"; value: T[] }
+  | { action: "back" };

package/src/Sprinkle/utils/field-utils.ts

@@ -0,0 +1,158 @@
+/**
+ * Field utilities for menu-based struct editing.
+ * Provides required field counting and label building.
+ */
+
+import type { TObject, TSchema } from "@sinclair/typebox";
+import type { FieldState, RequiredFieldCount } from "../types.js";
+import {
+  isOptional,
+  isNullable,
+  hasDefault,
+  getDefault,
+  isLiteral,
+} from "../type-guards.js";
+import { formatValuePreview } from "./formatting.js";
+
+/**
+ * Count required fields in an object schema and how many are filled.
+ *
+ * @param type - The object schema
+ * @param state - Map of field names to their current state
+ * @returns Count of total required fields and how many are filled
+ */
+export function countRequiredFields(
+  type: TObject,
+  state: Map<string, FieldState>,
+): RequiredFieldCount {
+  const fields = type.properties as Record<string, TSchema>;
+  let total = 0;
+  let filled = 0;
+
+  for (const [fieldName, fieldType] of Object.entries(fields)) {
+    // Skip optional fields - they're not required
+    if (isOptional(fieldType)) {
+      continue;
+    }
+
+    // Non-nullable fields with defaults don't require user input
+    if (hasDefault(fieldType) && !isNullable(fieldType)) {
+      continue;
+    }
+
+    // Literal fields auto-fill, so they're not required from the user
+    if (isLiteral(fieldType)) {
+      continue;
+    }
+
+    // This is a required field
+    total++;
+
+    // Check if it's filled
+    const fieldState = state.get(fieldName);
+    if (fieldState?.status === "set" || fieldState?.status === "null") {
+      filled++;
+    }
+  }
+
+  return { total, filled };
+}
+
+/**
+ * Determine if a field is required (must have a value to submit).
+ *
+ * @param fieldType - The field's schema
+ * @returns true if the field is required
+ */
+export function isFieldRequired(fieldType: TSchema): boolean {
+  // Optional fields are not required
+  if (isOptional(fieldType)) {
+    return false;
+  }
+
+  // Literal fields auto-fill, so they're not required from the user
+  if (isLiteral(fieldType)) {
+    return false;
+  }
+
+  // Non-nullable fields with defaults are not required (default will be used)
+  if (hasDefault(fieldType) && !isNullable(fieldType)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Build a display label for a field in the menu.
+ *
+ * @param fieldName - The field name
+ * @param fieldType - The field's schema
+ * @param state - The current state of the field
+ * @returns Formatted label string
+ */
+export function buildFieldLabel(
+  fieldName: string,
+  fieldType: TSchema,
+  state: FieldState,
+): string {
+  const required = isFieldRequired(fieldType);
+  const requiredMarker = required ? " *" : "";
+
+  switch (state.status) {
+    case "unset": {
+      // Check for default value
+      if (hasDefault(fieldType)) {
+        const defaultVal = getDefault(fieldType);
+        const preview = formatValuePreview(defaultVal, 30);
+        return `${fieldName}: [default: ${preview}]${requiredMarker}`;
+      }
+      return `${fieldName}: [not set]${requiredMarker}`;
+    }
+
+    case "null":
+      return `${fieldName}: null${requiredMarker}`;
+
+    case "set": {
+      const preview = formatValuePreview(state.value, 40);
+      return `${fieldName}: ${preview}${requiredMarker}`;
+    }
+  }
+}
+
+/**
+ * Get the initial FieldState for a field based on its type and any existing value.
+ *
+ * @param _fieldType - The field's schema (reserved for future logic)
+ * @param existingValue - Existing value if editing
+ * @returns Initial FieldState
+ */
+export function getInitialFieldState<T>(
+  _fieldType: TSchema,
+  existingValue?: T,
+): FieldState<T> {
+  if (existingValue === undefined) {
+    return { status: "unset" };
+  }
+
+  if (existingValue === null) {
+    return { status: "null" };
+  }
+
+  return { status: "set", value: existingValue };
+}
+
+/**
+ * Check if all required fields are filled in the state map.
+ *
+ * @param type - The object schema
+ * @param state - Map of field names to their current state
+ * @returns true if all required fields have values
+ */
+export function allRequiredFieldsFilled(
+  type: TObject,
+  state: Map<string, FieldState>,
+): boolean {
+  const { total, filled } = countRequiredFields(type, state);
+  return filled >= total;
+}

package/src/Sprinkle/utils/formatting.ts

@@ -0,0 +1,127 @@
+/**
+ * Formatting utilities for menu-based struct editing.
+ * Provides value preview, path formatting, and breadcrumb generation.
+ */
+
+/**
+ * Format a value for display in a menu item.
+ * Truncates long values and provides type-appropriate previews.
+ *
+ * @param value - The value to format
+ * @param maxLength - Maximum length before truncation (default 40)
+ * @returns Formatted string representation
+ */
+export function formatValuePreview(value: unknown, maxLength = 40): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (value === undefined) {
+    return "[not set]";
+  }
+
+  if (typeof value === "string") {
+    const escaped = JSON.stringify(value);
+    if (escaped.length <= maxLength) {
+      return escaped;
+    }
+    // Truncate inside the quotes (guard against negative maxLength from recursion)
+    return `"${value.slice(0, Math.max(0, maxLength - 5))}..."`;
+  }
+
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  }
+
+  if (typeof value === "object") {
+    // For objects, try to show a meaningful preview
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return "{}";
+    }
+
+    // If object has a single key (like union type), show it
+    if (keys.length === 1) {
+      const key = keys[0]!;
+      const innerValue = (value as Record<string, unknown>)[key];
+      const innerPreview = formatValuePreview(innerValue, maxLength - key.length - 6);
+      const preview = `{ ${key}: ${innerPreview} }`;
+      if (preview.length <= maxLength) {
+        return preview;
+      }
+      return `{ ${key}: ... }`;
+    }
+
+    // Multiple keys - show abbreviated
+    const firstKey = keys[0]!;
+    return `{ ${firstKey}: ..., +${keys.length - 1} }`;
+  }
+
+  return String(value).slice(0, maxLength);
+}
+
+/**
+ * Format a path array for display, stripping the "root" prefix.
+ *
+ * @param path - Array of path segments (e.g., ["root", "settings", "name"])
+ * @returns Formatted path string (e.g., "settings.name")
+ */
+export function formatPath(path: string[]): string {
+  // Filter out "root" prefix
+  const filtered = path.filter((segment) => segment !== "root");
+  if (filtered.length === 0) {
+    return "";
+  }
+  return filtered.join(".");
+}
+
+/**
+ * Format a path as a breadcrumb trail for nested navigation.
+ * Truncates from the left if too long.
+ *
+ * @param path - Array of path segments
+ * @param maxLength - Maximum total length (default 50)
+ * @returns Breadcrumb string (e.g., "settings → permissions → mint")
+ */
+export function formatBreadcrumb(path: string[], maxLength = 50): string {
+  // Filter out "root" prefix
+  const filtered = path.filter((segment) => segment !== "root");
+  if (filtered.length === 0) {
+    return "";
+  }
+
+  const separator = " \u2192 "; // Unicode right arrow
+  const joined = filtered.join(separator);
+
+  if (joined.length <= maxLength) {
+    return joined;
+  }
+
+  // Truncate from left, keeping most recent segments
+  const ellipsis = "...";
+  let result = "";
+  for (let i = filtered.length - 1; i >= 0; i--) {
+    const segment = filtered[i]!;
+    const candidate = i === filtered.length - 1 ? segment : segment + separator + result;
+    if (candidate.length + ellipsis.length + separator.length > maxLength && i < filtered.length - 1) {
+      return ellipsis + separator + result;
+    }
+    result = candidate;
+  }
+
+  // Safety clamp: if we still exceeded maxLength (e.g., last segment alone is too long),
+  // fall back to just the ellipsis to honor the maxLength contract.
+  if (result.length > maxLength) {
+    return ellipsis;
+  }
+
+  return result;
+}

package/src/Sprinkle/utils/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility functions for menu-based struct editing.
+ */
+
+export {
+  formatValuePreview,
+  formatPath,
+  formatBreadcrumb,
+} from "./formatting.js";
+
+export {
+  countRequiredFields,
+  isFieldRequired,
+  buildFieldLabel,
+  getInitialFieldState,
+  allRequiredFieldsFilled,
+} from "./field-utils.js";