@snaha/swarm-id 0.0.1

package/src/utils/ttl.ts

@@ -0,0 +1,129 @@
+/**
+ * TTL (Time To Live) calculation and formatting utilities for postage stamps
+ */
+
+/**
+ * Gnosis Chain block time in seconds
+ */
+export const GNOSIS_BLOCK_TIME = 5
+
+/**
+ * Time constants
+ */
+const SECONDS_PER_MINUTE = 60
+const SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE
+const SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR
+const SECONDS_PER_MONTH = 30 * SECONDS_PER_DAY // 2,592,000
+
+/**
+ * Swarm constants
+ */
+const PLUR_PER_BZZ = 1e16
+const CHUNK_SIZE_BYTES = 4096
+const BYTES_PER_GB = 1024 * 1024 * 1024
+const CHUNKS_PER_GB = Math.floor(BYTES_PER_GB / CHUNK_SIZE_BYTES) // 262144
+
+/**
+ * Swarmscan API URL for price data
+ */
+export const SWARMSCAN_STATS_URL =
+  "https://api.swarmscan.io/v1/postage-stamps/stats"
+
+/**
+ * Fetches current price from Swarmscan.
+ * @returns pricePerGBPerMonth in BZZ
+ */
+export async function fetchSwarmPrice(): Promise<number> {
+  const response = await fetch(SWARMSCAN_STATS_URL)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Swarmscan stats: ${response.status}`)
+  }
+  const data = await response.json()
+  return data.pricePerGBPerMonth
+}
+
+/**
+ * Calculates TTL in seconds from stamp amount and Swarmscan price.
+ *
+ * @param amount - Stamp amount in PLUR (smallest BZZ unit)
+ * @param pricePerGBPerMonth - Price from Swarmscan (in BZZ)
+ * @returns TTL in seconds
+ */
+export function calculateTTLSeconds(
+  amount: bigint | number | string,
+  pricePerGBPerMonth: number,
+): number {
+  const amountBigInt = BigInt(amount)
+  // Cost per chunk per month in PLUR
+  const perChunkPerMonthCost =
+    (pricePerGBPerMonth * PLUR_PER_BZZ) / CHUNKS_PER_GB
+  // TTL in months
+  const ttlMonths = Number(amountBigInt) / perChunkPerMonthCost
+  // TTL in seconds
+  return ttlMonths * SECONDS_PER_MONTH
+}
+
+/**
+ * Formats a TTL value (in seconds) to a human-readable string.
+ * Returns "Xd Yh" format (e.g., "30d 14h").
+ *
+ * @param ttlSeconds - TTL in seconds
+ * @returns Human-readable TTL string, or "N/A" if undefined/invalid
+ */
+export function formatTTL(ttlSeconds: number | undefined): string {
+  if (ttlSeconds === undefined || ttlSeconds <= 0) {
+    return "N/A"
+  }
+
+  const days = Math.floor(ttlSeconds / SECONDS_PER_DAY)
+  const hours = Math.floor((ttlSeconds % SECONDS_PER_DAY) / SECONDS_PER_HOUR)
+
+  return `${days}d ${hours}h`
+}
+
+/**
+ * Fetches block timestamp from Gnosis RPC.
+ *
+ * @param rpcUrl - Gnosis RPC URL
+ * @param blockNumber - Block number to get timestamp for
+ * @returns Block timestamp in seconds (Unix timestamp)
+ */
+export async function getBlockTimestamp(
+  rpcUrl: string,
+  blockNumber: number,
+): Promise<number> {
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method: "eth_getBlockByNumber",
+      params: [`0x${blockNumber.toString(16)}`, false],
+      id: 1,
+    }),
+  })
+
+  const data = await response.json()
+  if (data.error) {
+    throw new Error(`RPC error: ${data.error.message}`)
+  }
+  if (!data.result) {
+    throw new Error(`Block ${blockNumber} not found`)
+  }
+
+  return parseInt(data.result.timestamp, 16)
+}
+
+/**
+ * Calculates expiry timestamp for a postage stamp.
+ *
+ * @param blockTimestamp - Timestamp when stamp was created (from blockNumber)
+ * @param ttlSeconds - TTL in seconds
+ * @returns Expiry timestamp in seconds (Unix timestamp)
+ */
+export function calculateExpiryTimestamp(
+  blockTimestamp: number,
+  ttlSeconds: number,
+): number {
+  return blockTimestamp + ttlSeconds
+}

package/src/utils/url.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest"
+import { buildAuthUrl } from "./url"
+
+describe("buildAuthUrl", () => {
+  it("should build URL with origin only", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+    )
+
+    expect(url).toBe(
+      "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com",
+    )
+  })
+
+  it("should build URL with origin and minimal metadata", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      {
+        name: "Test App",
+      },
+    )
+
+    expect(url).toBe(
+      "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com&appName=Test+App",
+    )
+  })
+
+  it("should build URL with origin and full metadata", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      {
+        name: "Test App",
+        description: "A test application",
+        icon: "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiPjwvc3ZnPg==",
+      },
+    )
+
+    const expectedUrl =
+      "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com&appName=Test+App&appDescription=A+test+application&appIcon=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiPjwvc3ZnPg%3D%3D"
+    expect(url).toBe(expectedUrl)
+  })
+
+  it("should properly encode URL parameters", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://my-app.example.com/path?query=value",
+      {
+        name: "My App & Co.",
+        description: "An app with special chars: äöü",
+      },
+    )
+
+    expect(url).toContain(
+      "origin=https%3A%2F%2Fmy-app.example.com%2Fpath%3Fquery%3Dvalue",
+    )
+    expect(url).toContain("appName=My+App+%26+Co.")
+    expect(url).toContain(
+      "appDescription=An+app+with+special+chars%3A+%C3%A4%C3%B6%C3%BC",
+    )
+  })
+
+  it("should handle empty description and icon", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      {
+        name: "Test App",
+        description: "",
+        icon: "",
+      },
+    )
+
+    // URLSearchParams omits empty strings, so only origin and appName should be included
+    expect(url).toBe(
+      "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com&appName=Test+App",
+    )
+  })
+
+  it("should include agent parameter when option is true", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      { name: "Test App" },
+      { agent: true },
+    )
+
+    expect(url).toContain("agent=")
+  })
+
+  it("should not include agent parameter when option is false", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      { name: "Test App" },
+      { agent: false },
+    )
+
+    expect(url).not.toContain("agent")
+  })
+
+  it("should include challenge and agent when both options are set", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      { name: "Test App" },
+      { agent: true, challenge: "test-challenge-123" },
+    )
+
+    expect(url).toContain("challenge=test-challenge-123")
+    expect(url).toContain("agent=")
+  })
+
+  it("should include challenge when provided", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      { name: "Test App" },
+      { challenge: "test-challenge-123" },
+    )
+
+    expect(url).toContain("challenge=test-challenge-123")
+  })
+
+  it("should not include challenge when not provided", () => {
+    const url = buildAuthUrl(
+      "https://swarm-id.example.com",
+      "https://myapp.example.com",
+      { name: "Test App" },
+    )
+
+    expect(url).not.toContain("challenge")
+  })
+})

package/src/utils/url.ts

@@ -0,0 +1,71 @@
+import type { AppMetadata } from "../types"
+
+/**
+ * Configuration options for building the authentication URL.
+ */
+export interface BuildAuthUrlOptions {
+  /**
+   * When true, shows the agent sign-up option on the connect page.
+   * Agents are automated services that can perform operations on behalf of users.
+   */
+  agent?: boolean
+  /**
+   * Challenge string for storage partitioning detection. When present, the popup checks
+   * if it can read this challenge from localStorage to determine whether
+   * storage is partitioned.
+   */
+  challenge?: string
+}
+
+/**
+ * Build the authentication URL for connecting to Swarm ID
+ *
+ * This function creates the same URL format as used by SwarmIdProxy.openAuthPopup()
+ * to ensure consistency across the library.
+ *
+ * @param baseUrl - The base URL where the authentication page is hosted
+ * @param origin - The origin of the parent application requesting authentication
+ * @param metadata - Optional application metadata to display during authentication
+ * @param options - Optional configuration for the auth URL
+ * @returns The complete authentication URL with hash parameters
+ *
+ * @example
+ * ```typescript
+ * const url = buildAuthUrl(
+ *   "https://swarm-id.example.com",
+ *   "https://myapp.example.com",
+ *   { name: "My App", description: "A decentralized application" }
+ * )
+ * // Returns: "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com&appName=My+App&appDescription=A+decentralized+application"
+ * ```
+ */
+export function buildAuthUrl(
+  baseUrl: string,
+  origin: string,
+  metadata?: AppMetadata,
+  options?: BuildAuthUrlOptions,
+): string {
+  // Build URL with hash parameters (avoids re-renders in SPA)
+  const params = new URLSearchParams()
+  params.set("origin", origin)
+
+  if (metadata) {
+    params.set("appName", metadata.name)
+    if (metadata.description) {
+      params.set("appDescription", metadata.description)
+    }
+    if (metadata.icon) {
+      params.set("appIcon", metadata.icon)
+    }
+  }
+
+  if (options?.challenge) {
+    params.set("challenge", options.challenge)
+  }
+
+  if (options?.agent) {
+    params.set("agent", "")
+  }
+
+  return `${baseUrl}/connect#${params.toString()}`
+}

package/src/utils/versioned-storage.ts

@@ -0,0 +1,323 @@
+/**
+ * Generic Versioned Storage Utility
+ *
+ * Provides a framework-agnostic way to store and retrieve versioned data
+ * with automatic migration support.
+ */
+
+import { z } from "zod"
+
+// ============================================================================
+// Types & Schemas
+// ============================================================================
+
+/**
+ * Versioned storage wrapper schema
+ * Used to check if data is in versioned format
+ */
+export const VersionedStorageSchema = z.object({
+  version: z.number().int().nonnegative(),
+  data: z.unknown(),
+})
+
+export type VersionedStorage = z.infer<typeof VersionedStorageSchema>
+
+/**
+ * Storage adapter interface - allows different storage backends
+ */
+export interface StorageAdapter {
+  getItem(key: string): string | undefined
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+
+/**
+ * Version parser function - handles migration from one version to another
+ */
+export type VersionParser<T> = (data: unknown, version: number) => T[]
+
+/**
+ * Serializer function - converts data to JSON-serializable format
+ */
+export type Serializer<T> = (data: T) => Record<string, unknown>
+
+/**
+ * Listener function for storage change events
+ */
+export type StorageChangeListener<T> = (data: T[]) => void
+
+/**
+ * Options for versioned storage
+ */
+export interface VersionedStorageOptions<T> {
+  /** Storage key */
+  key: string
+
+  /** Current version number */
+  currentVersion: number
+
+  /** Storage adapter (e.g., localStorage) */
+  storage: StorageAdapter
+
+  /** Version parsers - map of version to parser function */
+  parsers: Record<number, VersionParser<T>>
+
+  /** Optional serializer for complex types */
+  serializer?: Serializer<T>
+
+  /** Logger name for error messages */
+  loggerName?: string
+}
+
+// ============================================================================
+// Browser Storage Adapters
+// ============================================================================
+
+/**
+ * LocalStorage adapter for browser environments
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+  getItem(key: string): string | undefined {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return undefined
+    }
+    return window.localStorage.getItem(key) ?? undefined
+  }
+
+  setItem(key: string, value: string): void {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return
+    }
+    window.localStorage.setItem(key, value)
+  }
+
+  removeItem(key: string): void {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return
+    }
+    window.localStorage.removeItem(key)
+  }
+}
+
+/**
+ * In-memory storage adapter (for testing or non-browser environments)
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private storage = new Map<string, string>()
+
+  getItem(key: string): string | undefined {
+    return this.storage.get(key)
+  }
+
+  setItem(key: string, value: string): void {
+    this.storage.set(key, value)
+  }
+
+  removeItem(key: string): void {
+    this.storage.delete(key)
+  }
+
+  clear(): void {
+    this.storage.clear()
+  }
+}
+
+// ============================================================================
+// Core Versioned Storage Class
+// ============================================================================
+
+/**
+ * Generic versioned storage manager
+ */
+export class VersionedStorageManager<T> {
+  private options: VersionedStorageOptions<T>
+  private listeners: Set<StorageChangeListener<T>> = new Set()
+  private boundStorageHandler: ((event: StorageEvent) => void) | undefined
+
+  constructor(options: VersionedStorageOptions<T>) {
+    this.options = options
+  }
+
+  /**
+   * Subscribe to storage change events from other windows/tabs
+   * The browser's storage event fires when localStorage changes in OTHER windows,
+   * making this useful for cross-window synchronization.
+   *
+   * @param listener - Callback function that receives the updated data
+   * @returns Unsubscribe function to remove the listener
+   */
+  subscribe(listener: StorageChangeListener<T>): () => void {
+    this.listeners.add(listener)
+
+    // Set up storage event listener on first subscription
+    if (!this.boundStorageHandler) {
+      this.setupStorageEventListener()
+    }
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners.delete(listener)
+      if (this.listeners.size === 0) {
+        this.cleanupStorageEventListener()
+      }
+    }
+  }
+
+  /**
+   * Set up the browser storage event listener
+   * Only listens for changes to this manager's specific key
+   */
+  private setupStorageEventListener(): void {
+    if (typeof window === "undefined") return
+
+    this.boundStorageHandler = (event: StorageEvent) => {
+      // Only handle events for our specific key
+      if (event.key !== this.options.key) return
+
+      // Reload data and notify listeners
+      const data = this.load()
+      this.notifyListeners(data)
+    }
+
+    window.addEventListener("storage", this.boundStorageHandler)
+  }
+
+  /**
+   * Clean up the storage event listener when no more subscribers
+   */
+  private cleanupStorageEventListener(): void {
+    if (this.boundStorageHandler && typeof window !== "undefined") {
+      window.removeEventListener("storage", this.boundStorageHandler)
+      this.boundStorageHandler = undefined
+    }
+  }
+
+  /**
+   * Notify all listeners of data changes
+   */
+  private notifyListeners(data: T[]): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(data)
+      } catch (e) {
+        console.error(
+          `[${this.options.loggerName ?? "Storage"}] Listener error:`,
+          e,
+        )
+      }
+    }
+  }
+
+  /**
+   * Load data from storage
+   */
+  load(): T[] {
+    const stored = this.options.storage.getItem(this.options.key)
+
+    if (!stored) {
+      return []
+    }
+
+    try {
+      const parsed: unknown = JSON.parse(stored)
+      return this.parse(parsed)
+    } catch (e) {
+      console.error(`[${this.options.loggerName ?? "Storage"}] Load failed:`, e)
+      return []
+    }
+  }
+
+  /**
+   * Parse versioned data and migrate if needed
+   */
+  private parse(parsed: unknown): T[] {
+    // Try to parse as versioned data
+    const versioned = VersionedStorageSchema.safeParse(parsed)
+    const version = versioned.success ? versioned.data.version : 0
+    const data = versioned.success ? versioned.data.data : parsed
+
+    // Find appropriate parser
+    const parser = this.options.parsers[version]
+
+    if (!parser) {
+      console.error(
+        `[${this.options.loggerName ?? "Storage"}] No parser for version ${version}`,
+      )
+      return []
+    }
+
+    return parser(data, version)
+  }
+
+  /**
+   * Save data to storage
+   */
+  save(data: T[]): void {
+    try {
+      // Apply serializer if provided
+      const serialized = this.options.serializer
+        ? data.map(this.options.serializer)
+        : data
+
+      const wrapped: VersionedStorage = {
+        version: this.options.currentVersion,
+        data: serialized,
+      }
+
+      this.options.storage.setItem(this.options.key, JSON.stringify(wrapped))
+    } catch (e) {
+      console.error(`[${this.options.loggerName ?? "Storage"}] Save failed:`, e)
+    }
+  }
+
+  /**
+   * Clear data from storage
+   */
+  clear(): void {
+    this.options.storage.removeItem(this.options.key)
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Create a versioned storage manager with localStorage
+ */
+export function createLocalStorageManager<T>(
+  options: Omit<VersionedStorageOptions<T>, "storage">,
+): VersionedStorageManager<T> {
+  return new VersionedStorageManager({
+    ...options,
+    storage: new LocalStorageAdapter(),
+  })
+}
+
+/**
+ * Create a versioned storage manager with memory storage
+ */
+export function createMemoryStorageManager<T>(
+  options: Omit<VersionedStorageOptions<T>, "storage">,
+): VersionedStorageManager<T> {
+  return new VersionedStorageManager({
+    ...options,
+    storage: new MemoryStorageAdapter(),
+  })
+}
+
+/**
+ * Create a simple Zod-based parser for a single version
+ */
+export function createZodParser<T>(schema: z.ZodType<T[]>): VersionParser<T> {
+  return (data: unknown) => {
+    const result = schema.safeParse(data)
+
+    if (!result.success) {
+      console.error("Parse failed:", result.error.format())
+      return []
+    }
+
+    return result.data
+  }
+}