@stacknet/keyutils 0.4.8 → 0.6.0

package/dist/types/index.d.cts

@@ -72,14 +72,17 @@ interface DirectTransferResult {
     transferredAt: number;
 }
 type FilingStatus = 'submitted' | 'validated' | 'paid' | 'failed';
+type PayoutMethod = 'usdc' | 'stripe';
 interface FilingResult {
     keyId: string;
+    filingId: string;
     fileHash: string;
     txSignature?: string;
     paperAmount: number;
     status: FilingStatus;
     beneficiary: string;
     filedAt: string;
+    payoutMethod?: PayoutMethod;
 }
 interface FilingHistoryEntry extends FilingResult {
     proofPda?: string;
@@ -89,6 +92,124 @@ interface FilingHistoryEntry extends FilingResult {
 type EligibleKey = NodeKeyInfo & {
     paperWork: string;
 };
+type PayoutAccountMethod = 'stripe' | 'solana';
+/**
+ * The user's saved payout config in the context of one stack.
+ *
+ * Stripe Connect is per-(user, stack) — each stack runs its own platform
+ * under its own secret, so a given user has independent connected accounts
+ * across stacks. The `stripe` field reflects the connection for the SCOPE
+ * stack only; query other stacks via `useUserStripeStacks()` or by passing
+ * a different `stackId` to `usePayoutAccount`.
+ *
+ * The Solana wallet is global (one verified address services every stack).
+ *
+ * `method` records the user's preferred rail. The active filing flow
+ * verifies the chosen rail is configured for the key's originating stack
+ * and falls back to a clear error if not.
+ */
+interface PayoutAccount {
+    /** Which method is currently configured. `null` when nothing is set up. */
+    method: PayoutAccountMethod | null;
+    stripe?: {
+        /** acct_*. Masked for display. */
+        accountIdMasked: string;
+        /** Stripe-reported flags from `accounts.retrieve`. */
+        chargesEnabled: boolean;
+        payoutsEnabled: boolean;
+        detailsSubmitted: boolean;
+        /** When non-null, the user needs to finish onboarding at this URL. */
+        pendingOnboardingUrl?: string | null;
+        /** Stack whose Stripe platform credentials are driving this connection. */
+        stackId: string;
+        updatedAt: string;
+    };
+    solana?: {
+        addressMasked: string;
+        /** Full address — safe to expose since the proof of control is on the
+         *  server (we verified the signature). The client uses this to display. */
+        address: string;
+        verifiedAt: string;
+    };
+}
+/**
+ * One stack the user has a Stripe Connect account on. Returned by
+ * `useUserStripeStacks()` for the multi-stack settings view.
+ */
+interface StripeStackPayout {
+    stackId: string;
+    accountIdMasked: string;
+    chargesEnabled: boolean;
+    payoutsEnabled: boolean;
+    detailsSubmitted: boolean;
+    pendingOnboardingUrl?: string | null;
+    updatedAt: string;
+}
+interface CryptoNonceResponse {
+    nonce: string;
+    /** Canonical message the wallet must sign — includes the nonce. */
+    message: string;
+    expiresAt: string;
+}
+interface StripeConnectStartResponse {
+    accountIdMasked: string;
+    /** Hosted Stripe AccountLink URL — redirect the user here. */
+    onboardingUrl: string;
+}
+/**
+ * Per-stack payout configuration, as resolved by stacknet from the stack's
+ * config + secrets. Drives the payout-method picker and locks the destination.
+ */
+interface StackPayoutCapabilities {
+    stackId: string;
+    stackName: string;
+    stripe: {
+        enabled: boolean;
+        /** Human-readable reason when disabled (rendered as "disabled by {stackName} stack" UX). */
+        disabledReason?: string;
+        /** Masked / display-only descriptor — never the raw account id. */
+        destinationLabel?: string;
+    };
+    usdc: {
+        enabled: boolean;
+        disabledReason?: string;
+        /** Resolved on-chain payout address from the stack config. */
+        defaultDestination: string;
+    };
+}
+type FilingTrackerStep = 'sent' | 'routed' | 'confirmed' | 'finalized' | 'filed';
+type FilingTrackerStatus = 'pending' | 'current' | 'done' | 'failed';
+interface FilingTrackerState {
+    id: FilingTrackerStep;
+    label: string;
+    status: FilingTrackerStatus;
+    timestampMs: number | null;
+    detail: string | null;
+    approvalsCount?: number;
+    approvalsThreshold?: number;
+    /** Optional outbound link (Solscan / Stripe dashboard). */
+    externalUrl?: string;
+}
+interface FilingDetail extends FilingResult {
+    payoutMethod: PayoutMethod;
+    /** Server-supplied; not editable from the client. */
+    memo: string;
+    /** Server-supplied; not editable from the client. USDC raw units (string to avoid bigint loss). */
+    amountUsdc: string;
+    tokensUsed: string;
+    tracker: FilingTrackerState[];
+    proofPda?: string;
+    intentHashHex?: string;
+    stripePaymentIntentId?: string;
+    failureReason?: string;
+    /**
+     * The Solana wallet recorded as the intent's beneficiary on-chain. For
+     * usdc filings this matches `beneficiary`; for stripe filings the
+     * `beneficiary` is the off-chain Stripe account id and this is the
+     * wallet the resolver uses to look up the credentials mapping.
+     */
+    onchainBeneficiary?: string;
+}
 type Platform = 'ios' | 'android' | 'windows' | 'mac' | 'linux';
 interface PlatformDownload {
     platform: Platform;
@@ -125,4 +246,4 @@ interface KeyUtilsCallbacks {
     onFilingError?: (error: Error) => void;
 }
 
-export type { DirectTransferResult, EligibleKey, FilingHistoryEntry, FilingResult, FilingStatus, KeyListing, KeyUtilsCallbacks, KeyUtilsConfig, KeyWidgetTab, LedgerEntry, ListingResult, MintResult, NodeKeyInfo, PaymentMethod, Platform, PlatformDownload, PricingInfo };
+export type { CryptoNonceResponse, DirectTransferResult, EligibleKey, FilingDetail, FilingHistoryEntry, FilingResult, FilingStatus, FilingTrackerState, FilingTrackerStatus, FilingTrackerStep, KeyListing, KeyUtilsCallbacks, KeyUtilsConfig, KeyWidgetTab, LedgerEntry, ListingResult, MintResult, NodeKeyInfo, PaymentMethod, PayoutAccount, PayoutAccountMethod, PayoutMethod, Platform, PlatformDownload, PricingInfo, StackPayoutCapabilities, StripeConnectStartResponse, StripeStackPayout };

package/dist/types/index.d.ts

@@ -72,14 +72,17 @@ interface DirectTransferResult {
     transferredAt: number;
 }
 type FilingStatus = 'submitted' | 'validated' | 'paid' | 'failed';
+type PayoutMethod = 'usdc' | 'stripe';
 interface FilingResult {
     keyId: string;
+    filingId: string;
     fileHash: string;
     txSignature?: string;
     paperAmount: number;
     status: FilingStatus;
     beneficiary: string;
     filedAt: string;
+    payoutMethod?: PayoutMethod;
 }
 interface FilingHistoryEntry extends FilingResult {
     proofPda?: string;
@@ -89,6 +92,124 @@ interface FilingHistoryEntry extends FilingResult {
 type EligibleKey = NodeKeyInfo & {
     paperWork: string;
 };
+type PayoutAccountMethod = 'stripe' | 'solana';
+/**
+ * The user's saved payout config in the context of one stack.
+ *
+ * Stripe Connect is per-(user, stack) — each stack runs its own platform
+ * under its own secret, so a given user has independent connected accounts
+ * across stacks. The `stripe` field reflects the connection for the SCOPE
+ * stack only; query other stacks via `useUserStripeStacks()` or by passing
+ * a different `stackId` to `usePayoutAccount`.
+ *
+ * The Solana wallet is global (one verified address services every stack).
+ *
+ * `method` records the user's preferred rail. The active filing flow
+ * verifies the chosen rail is configured for the key's originating stack
+ * and falls back to a clear error if not.
+ */
+interface PayoutAccount {
+    /** Which method is currently configured. `null` when nothing is set up. */
+    method: PayoutAccountMethod | null;
+    stripe?: {
+        /** acct_*. Masked for display. */
+        accountIdMasked: string;
+        /** Stripe-reported flags from `accounts.retrieve`. */
+        chargesEnabled: boolean;
+        payoutsEnabled: boolean;
+        detailsSubmitted: boolean;
+        /** When non-null, the user needs to finish onboarding at this URL. */
+        pendingOnboardingUrl?: string | null;
+        /** Stack whose Stripe platform credentials are driving this connection. */
+        stackId: string;
+        updatedAt: string;
+    };
+    solana?: {
+        addressMasked: string;
+        /** Full address — safe to expose since the proof of control is on the
+         *  server (we verified the signature). The client uses this to display. */
+        address: string;
+        verifiedAt: string;
+    };
+}
+/**
+ * One stack the user has a Stripe Connect account on. Returned by
+ * `useUserStripeStacks()` for the multi-stack settings view.
+ */
+interface StripeStackPayout {
+    stackId: string;
+    accountIdMasked: string;
+    chargesEnabled: boolean;
+    payoutsEnabled: boolean;
+    detailsSubmitted: boolean;
+    pendingOnboardingUrl?: string | null;
+    updatedAt: string;
+}
+interface CryptoNonceResponse {
+    nonce: string;
+    /** Canonical message the wallet must sign — includes the nonce. */
+    message: string;
+    expiresAt: string;
+}
+interface StripeConnectStartResponse {
+    accountIdMasked: string;
+    /** Hosted Stripe AccountLink URL — redirect the user here. */
+    onboardingUrl: string;
+}
+/**
+ * Per-stack payout configuration, as resolved by stacknet from the stack's
+ * config + secrets. Drives the payout-method picker and locks the destination.
+ */
+interface StackPayoutCapabilities {
+    stackId: string;
+    stackName: string;
+    stripe: {
+        enabled: boolean;
+        /** Human-readable reason when disabled (rendered as "disabled by {stackName} stack" UX). */
+        disabledReason?: string;
+        /** Masked / display-only descriptor — never the raw account id. */
+        destinationLabel?: string;
+    };
+    usdc: {
+        enabled: boolean;
+        disabledReason?: string;
+        /** Resolved on-chain payout address from the stack config. */
+        defaultDestination: string;
+    };
+}
+type FilingTrackerStep = 'sent' | 'routed' | 'confirmed' | 'finalized' | 'filed';
+type FilingTrackerStatus = 'pending' | 'current' | 'done' | 'failed';
+interface FilingTrackerState {
+    id: FilingTrackerStep;
+    label: string;
+    status: FilingTrackerStatus;
+    timestampMs: number | null;
+    detail: string | null;
+    approvalsCount?: number;
+    approvalsThreshold?: number;
+    /** Optional outbound link (Solscan / Stripe dashboard). */
+    externalUrl?: string;
+}
+interface FilingDetail extends FilingResult {
+    payoutMethod: PayoutMethod;
+    /** Server-supplied; not editable from the client. */
+    memo: string;
+    /** Server-supplied; not editable from the client. USDC raw units (string to avoid bigint loss). */
+    amountUsdc: string;
+    tokensUsed: string;
+    tracker: FilingTrackerState[];
+    proofPda?: string;
+    intentHashHex?: string;
+    stripePaymentIntentId?: string;
+    failureReason?: string;
+    /**
+     * The Solana wallet recorded as the intent's beneficiary on-chain. For
+     * usdc filings this matches `beneficiary`; for stripe filings the
+     * `beneficiary` is the off-chain Stripe account id and this is the
+     * wallet the resolver uses to look up the credentials mapping.
+     */
+    onchainBeneficiary?: string;
+}
 type Platform = 'ios' | 'android' | 'windows' | 'mac' | 'linux';
 interface PlatformDownload {
     platform: Platform;
@@ -125,4 +246,4 @@ interface KeyUtilsCallbacks {
     onFilingError?: (error: Error) => void;
 }
 
-export type { DirectTransferResult, EligibleKey, FilingHistoryEntry, FilingResult, FilingStatus, KeyListing, KeyUtilsCallbacks, KeyUtilsConfig, KeyWidgetTab, LedgerEntry, ListingResult, MintResult, NodeKeyInfo, PaymentMethod, Platform, PlatformDownload, PricingInfo };
+export type { CryptoNonceResponse, DirectTransferResult, EligibleKey, FilingDetail, FilingHistoryEntry, FilingResult, FilingStatus, FilingTrackerState, FilingTrackerStatus, FilingTrackerStep, KeyListing, KeyUtilsCallbacks, KeyUtilsConfig, KeyWidgetTab, LedgerEntry, ListingResult, MintResult, NodeKeyInfo, PaymentMethod, PayoutAccount, PayoutAccountMethod, PayoutMethod, Platform, PlatformDownload, PricingInfo, StackPayoutCapabilities, StripeConnectStartResponse, StripeStackPayout };

package/dist/utils/index.cjs

@@ -1 +1 @@
-'use strict';var clsx=require('clsx'),tailwindMerge=require('tailwind-merge');function i(){if(typeof document>"u")return {};let r=document.cookie.match(/(?:^|;\s*)__csrf=([^;]*)/);return r?{"x-csrf-token":r[1]}:{}}var s=500;function o(r,e){if(typeof r!="string"||r.length===0)return e;let t=r.replace(/[\u0000-\u001F\u007F]/g," ");return t.length>500?t.slice(0,500)+"\u2026":t}async function u(r,e){try{let t=await r.json();if(t&&typeof t=="object"&&"error"in t)return o(t.error,e)}catch{}return e}function f(r,e="#"){if(!r||typeof r!="string")return e;let t=r.trim();if(t===""||t==="#")return e;if(t.startsWith("/")||t.startsWith("./")||t.startsWith("../"))return t;try{let n=new URL(t);if(n.protocol==="http:"||n.protocol==="https:")return n.toString()}catch{}return e}function _(...r){return tailwindMerge.twMerge(clsx.clsx(r))}function x(r){return r==null?"0":r>=1e9?`${(r/1e9).toFixed(1)}B`:r>=1e6?`${(r/1e6).toFixed(1)}M`:r>=1e3?`${(r/1e3).toFixed(1)}K`:r.toLocaleString()}function h(r,e){return e<=0?0:Math.min(100,Math.round(r/e*100))}function y(r){return r>=70?"bg-green-500":r>=30?"bg-yellow-500":"bg-red-500"}function R(r){if(r==null||r==="")return "";let e=typeof r=="string"&&/^\d+$/.test(r)?Number(r):r,t=new Date(e);return isNaN(t.getTime())?"":t.toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric"})}function E(){if(typeof navigator>"u")return "mac";let r=navigator.userAgent.toLowerCase();return /iphone|ipad|ipod/.test(r)?"ios":/android/.test(r)?"android":/win/.test(r)?"windows":/linux/.test(r)?"linux":"mac"}exports.MAX_ERROR_LEN=s;exports.calculateBalancePercentage=h;exports.clampErrorMessage=o;exports.cn=_;exports.csrfHeaders=i;exports.detectPlatform=E;exports.formatDate=R;exports.formatTokens=x;exports.getBalanceColor=y;exports.readErrorMessage=u;exports.safeUrl=f;
+'use strict';var clsx=require('clsx'),tailwindMerge=require('tailwind-merge');var d=false;function _(){if(typeof document>"u")return {};let e=document.cookie.match(/(?:^|;\s*)__csrf=([^;]*)/);if(!e)return d||(d=true,console.warn("[keyutils] __csrf cookie not found; mutations will be sent without a CSRF token")),{};let n=e[1];try{n=decodeURIComponent(n);}catch{}return {"x-csrf-token":n}}var b=500;function g(e,n){if(typeof e!="string"||e.length===0)return n;let t=e.replace(/[\u0000-\u001F\u007F]/g," ");return t.length>500?t.slice(0,500)+"\u2026":t}async function R(e,n){try{let t=await e.json();if(t&&typeof t=="object"&&"error"in t)return g(t.error,n)}catch{}return n}function F(e,n="#"){if(!e||typeof e!="string")return n;let t=e.trim();if(t===""||t==="#")return n;if(t.startsWith("/")||t.startsWith("./")||t.startsWith("../"))return t;try{let o=new URL(t);if(o.protocol==="http:"||o.protocol==="https:")return o.toString()}catch{}return n}var c={sent:"sent",routed:"routed",confirmed:"confirmed",finalized:"finalized",filed:"filed"},u={sent:{pending:"sent",progressing:"sending",done:"sent"},routed:{pending:"routed",progressing:"routing",done:"routed"},confirmed:{pending:"confirmed",progressing:"confirming",done:"confirmed"},finalized:{pending:"finalized",progressing:"finalizing",done:"finalized"},filed:{pending:"filed",progressing:"filing",done:"filed"}},k=["sent","routed","confirmed","finalized","filed"];function T(e){let n=new Map;(e??[]).forEach(r=>n.set(r.id,r));let t=k.map(r=>{let i=n.get(r);return i?{...i,label:i.label||c[r]}:{id:r,label:c[r],status:"pending",timestampMs:null,detail:null}}),o=t.reduce((r,i,a)=>i.status==="done"||i.status==="failed"?a:r,-1);if(o>0)for(let r=0;r<o;r++)t[r].status!=="failed"&&(t[r]={...t[r],status:"done"});if(!t.some(r=>r.status==="failed")){let r=t.findIndex(i=>i.status!=="done");if(r>=0){let i=t[r];i.status!=="current"&&(t[r]={...i,status:"current"});}}return t}function p(e){return e.find(n=>n.status==="current")??null}function m(e){return e.length>0&&e.every(n=>n.status==="done")}function x(e){return e.some(n=>n.status==="failed")}function E(e,n){if(!n)return {text:"loading",playing:true,stepId:"sent"};if(x(e))return {text:"failed",playing:false,stepId:"filed"};if(m(e))return {text:u.filed.done,playing:false,stepId:"filed"};let o=p(e)?.id??"sent";return {text:u[o].progressing,playing:true,stepId:o}}function v(...e){return tailwindMerge.twMerge(clsx.clsx(e))}function P(e){return e==null?"0":e>=1e9?`${(e/1e9).toFixed(1)}B`:e>=1e6?`${(e/1e6).toFixed(1)}M`:e>=1e3?`${(e/1e3).toFixed(1)}K`:e.toLocaleString()}function z(e,n){return n<=0?0:Math.min(100,Math.round(e/n*100))}function U(e){return e>=70?"bg-green-500":e>=30?"bg-yellow-500":"bg-red-500"}function K(e,n={}){let t=n.withSymbol!==false,o=Math.max(0,Math.min(6,n.maxDecimals??2));if(e==null||e==="")return t?"$0.00":"0.00";let s;try{if(typeof e=="bigint")s=e;else if(typeof e=="number")s=BigInt(Math.trunc(e));else {let l=String(e).trim().replace(/^\+/,"");if(/^-?\d+$/.test(l))s=BigInt(l);else {let f=Number(l);if(!Number.isFinite(f))return t?"$0.00":"0.00";s=BigInt(Math.trunc(f));}}}catch{return t?"$0.00":"0.00"}let r=s<0n,i=r?-s:s,a=i/1000000n,S=(i%1000000n).toString().padStart(6,"0").slice(0,o),h=a.toLocaleString("en-US"),y=o>0?`.${S}`:"";return `${r?"-":""}${t?"$":""}${h}${y}`}function O(e){if(e==null||e==="")return "";let n=typeof e=="string"&&/^\d+$/.test(e)?Number(e):e,t=new Date(n);return isNaN(t.getTime())?"":t.toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric"})}function H(){if(typeof navigator>"u")return "mac";let e=navigator.userAgent.toLowerCase();return /iphone|ipad|ipod/.test(e)?"ios":/android/.test(e)?"android":/win/.test(e)?"windows":/linux/.test(e)?"linux":"mac"}exports.MAX_ERROR_LEN=b;exports.TRACKER_LABELS=c;exports.TRACKER_VERBS=u;exports.calculateBalancePercentage=z;exports.clampErrorMessage=g;exports.cn=v;exports.csrfHeaders=_;exports.currentState=p;exports.deriveTrackerStates=T;exports.detectPlatform=H;exports.formatDate=O;exports.formatPaperUsd=K;exports.formatTokens=P;exports.getBalanceColor=U;exports.hasFailed=x;exports.isAllDone=m;exports.pickHeadline=E;exports.readErrorMessage=R;exports.safeUrl=F;

package/dist/utils/index.d.cts

@@ -1,7 +1,20 @@
 import { ClassValue } from 'clsx';
-import { Platform } from '../types/index.cjs';
+import { FilingTrackerStep, FilingTrackerState, Platform } from '../types/index.cjs';
 
-/** Read __csrf cookie and return as x-csrf-token header for mutations */
+/**
+ * Read the `__csrf` cookie and return it as the `x-csrf-token` header for
+ * mutating requests.
+ *
+ * Returns `{}` outside the browser (so native callers can use the same
+ * helper as a no-op). In the browser, returns `{}` when the cookie is
+ * missing — the server is the trust boundary and must reject — but logs
+ * a one-time warning so the missing token surfaces in the dev console
+ * rather than failing silently.
+ *
+ * The cookie value is `decodeURIComponent`'d to match the encoding the
+ * server applies when setting it; without this, tokens containing `+`,
+ * `=`, or `%` would desync between client and server.
+ */
 declare function csrfHeaders(): Record<string, string>;
 
 /**
@@ -30,11 +43,53 @@ declare function readErrorMessage(res: Response, fallback: string): Promise<stri
  */
 declare function safeUrl(url: string | undefined | null, fallback?: string): string;
 
+declare const TRACKER_LABELS: Record<FilingTrackerStep, string>;
+/**
+ * Verb tenses per state. `pending` is the neutral noun used when the row
+ * hasn't been entered yet; `progressing` is the gerund shown while the step
+ * is in-flight (terminal typing animation); `done` is the past-tense label
+ * used once the step completes. All lowercase by design.
+ */
+declare const TRACKER_VERBS: Record<FilingTrackerStep, {
+    pending: string;
+    progressing: string;
+    done: string;
+}>;
+/** Pure normalization of a server-shaped tracker. Cascade-forward + current pointer. */
+declare function deriveTrackerStates(raw: FilingTrackerState[] | null | undefined): FilingTrackerState[];
+declare function currentState(states: FilingTrackerState[]): FilingTrackerState | null;
+declare function isAllDone(states: FilingTrackerState[]): boolean;
+declare function hasFailed(states: FilingTrackerState[]): boolean;
+/** Pick the headline word for the big typing-text animation. */
+declare function pickHeadline(states: FilingTrackerState[], loaded: boolean): {
+    text: string;
+    playing: boolean;
+    stepId: FilingTrackerStep;
+};
+
 declare function cn(...inputs: ClassValue[]): string;
 declare function formatTokens(amount: number | undefined | null): string;
 declare function calculateBalancePercentage(current: number, max: number): number;
 declare function getBalanceColor(percentage: number): string;
+/**
+ * Format a paperwork USD amount for display.
+ *
+ * Stacknet stores `paper_work` as a 6-decimal fixed-point integer string —
+ * so `'1500000'` means $1.50. Pass any of (string | number | bigint | null
+ * | undefined) and get back a plain dollar string. By default, returns
+ * with 2 decimals + `$` prefix; pass `{ withSymbol: false }` for a bare
+ * decimal number, or `{ maxDecimals: 6 }` to surface sub-cent precision.
+ *
+ *   formatPaperUsd('0')        → '$0.00'
+ *   formatPaperUsd('1500000')  → '$1.50'
+ *   formatPaperUsd('1234567')  → '$1.23'
+ *   formatPaperUsd('1234567', { maxDecimals: 6 }) → '$1.234567'
+ */
+declare function formatPaperUsd(raw: string | number | bigint | null | undefined, opts?: {
+    withSymbol?: boolean;
+    maxDecimals?: number;
+}): string;
 declare function formatDate(dateString: string | number | null | undefined): string;
 declare function detectPlatform(): Platform;
 
-export { MAX_ERROR_LEN, calculateBalancePercentage, clampErrorMessage, cn, csrfHeaders, detectPlatform, formatDate, formatTokens, getBalanceColor, readErrorMessage, safeUrl };
+export { MAX_ERROR_LEN, TRACKER_LABELS, TRACKER_VERBS, calculateBalancePercentage, clampErrorMessage, cn, csrfHeaders, currentState, deriveTrackerStates, detectPlatform, formatDate, formatPaperUsd, formatTokens, getBalanceColor, hasFailed, isAllDone, pickHeadline, readErrorMessage, safeUrl };

package/dist/utils/index.d.ts

@@ -1,7 +1,20 @@
 import { ClassValue } from 'clsx';
-import { Platform } from '../types/index.js';
+import { FilingTrackerStep, FilingTrackerState, Platform } from '../types/index.js';
 
-/** Read __csrf cookie and return as x-csrf-token header for mutations */
+/**
+ * Read the `__csrf` cookie and return it as the `x-csrf-token` header for
+ * mutating requests.
+ *
+ * Returns `{}` outside the browser (so native callers can use the same
+ * helper as a no-op). In the browser, returns `{}` when the cookie is
+ * missing — the server is the trust boundary and must reject — but logs
+ * a one-time warning so the missing token surfaces in the dev console
+ * rather than failing silently.
+ *
+ * The cookie value is `decodeURIComponent`'d to match the encoding the
+ * server applies when setting it; without this, tokens containing `+`,
+ * `=`, or `%` would desync between client and server.
+ */
 declare function csrfHeaders(): Record<string, string>;
 
 /**
@@ -30,11 +43,53 @@ declare function readErrorMessage(res: Response, fallback: string): Promise<stri
  */
 declare function safeUrl(url: string | undefined | null, fallback?: string): string;
 
+declare const TRACKER_LABELS: Record<FilingTrackerStep, string>;
+/**
+ * Verb tenses per state. `pending` is the neutral noun used when the row
+ * hasn't been entered yet; `progressing` is the gerund shown while the step
+ * is in-flight (terminal typing animation); `done` is the past-tense label
+ * used once the step completes. All lowercase by design.
+ */
+declare const TRACKER_VERBS: Record<FilingTrackerStep, {
+    pending: string;
+    progressing: string;
+    done: string;
+}>;
+/** Pure normalization of a server-shaped tracker. Cascade-forward + current pointer. */
+declare function deriveTrackerStates(raw: FilingTrackerState[] | null | undefined): FilingTrackerState[];
+declare function currentState(states: FilingTrackerState[]): FilingTrackerState | null;
+declare function isAllDone(states: FilingTrackerState[]): boolean;
+declare function hasFailed(states: FilingTrackerState[]): boolean;
+/** Pick the headline word for the big typing-text animation. */
+declare function pickHeadline(states: FilingTrackerState[], loaded: boolean): {
+    text: string;
+    playing: boolean;
+    stepId: FilingTrackerStep;
+};
+
 declare function cn(...inputs: ClassValue[]): string;
 declare function formatTokens(amount: number | undefined | null): string;
 declare function calculateBalancePercentage(current: number, max: number): number;
 declare function getBalanceColor(percentage: number): string;
+/**
+ * Format a paperwork USD amount for display.
+ *
+ * Stacknet stores `paper_work` as a 6-decimal fixed-point integer string —
+ * so `'1500000'` means $1.50. Pass any of (string | number | bigint | null
+ * | undefined) and get back a plain dollar string. By default, returns
+ * with 2 decimals + `$` prefix; pass `{ withSymbol: false }` for a bare
+ * decimal number, or `{ maxDecimals: 6 }` to surface sub-cent precision.
+ *
+ *   formatPaperUsd('0')        → '$0.00'
+ *   formatPaperUsd('1500000')  → '$1.50'
+ *   formatPaperUsd('1234567')  → '$1.23'
+ *   formatPaperUsd('1234567', { maxDecimals: 6 }) → '$1.234567'
+ */
+declare function formatPaperUsd(raw: string | number | bigint | null | undefined, opts?: {
+    withSymbol?: boolean;
+    maxDecimals?: number;
+}): string;
 declare function formatDate(dateString: string | number | null | undefined): string;
 declare function detectPlatform(): Platform;
 
-export { MAX_ERROR_LEN, calculateBalancePercentage, clampErrorMessage, cn, csrfHeaders, detectPlatform, formatDate, formatTokens, getBalanceColor, readErrorMessage, safeUrl };
+export { MAX_ERROR_LEN, TRACKER_LABELS, TRACKER_VERBS, calculateBalancePercentage, clampErrorMessage, cn, csrfHeaders, currentState, deriveTrackerStates, detectPlatform, formatDate, formatPaperUsd, formatTokens, getBalanceColor, hasFailed, isAllDone, pickHeadline, readErrorMessage, safeUrl };

package/dist/utils/index.js

@@ -1 +1 @@
-import {clsx}from'clsx';import {twMerge}from'tailwind-merge';function i(){if(typeof document>"u")return {};let r=document.cookie.match(/(?:^|;\s*)__csrf=([^;]*)/);return r?{"x-csrf-token":r[1]}:{}}var s=500;function o(r,e){if(typeof r!="string"||r.length===0)return e;let t=r.replace(/[\u0000-\u001F\u007F]/g," ");return t.length>500?t.slice(0,500)+"\u2026":t}async function u(r,e){try{let t=await r.json();if(t&&typeof t=="object"&&"error"in t)return o(t.error,e)}catch{}return e}function f(r,e="#"){if(!r||typeof r!="string")return e;let t=r.trim();if(t===""||t==="#")return e;if(t.startsWith("/")||t.startsWith("./")||t.startsWith("../"))return t;try{let n=new URL(t);if(n.protocol==="http:"||n.protocol==="https:")return n.toString()}catch{}return e}function _(...r){return twMerge(clsx(r))}function x(r){return r==null?"0":r>=1e9?`${(r/1e9).toFixed(1)}B`:r>=1e6?`${(r/1e6).toFixed(1)}M`:r>=1e3?`${(r/1e3).toFixed(1)}K`:r.toLocaleString()}function h(r,e){return e<=0?0:Math.min(100,Math.round(r/e*100))}function y(r){return r>=70?"bg-green-500":r>=30?"bg-yellow-500":"bg-red-500"}function R(r){if(r==null||r==="")return "";let e=typeof r=="string"&&/^\d+$/.test(r)?Number(r):r,t=new Date(e);return isNaN(t.getTime())?"":t.toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric"})}function E(){if(typeof navigator>"u")return "mac";let r=navigator.userAgent.toLowerCase();return /iphone|ipad|ipod/.test(r)?"ios":/android/.test(r)?"android":/win/.test(r)?"windows":/linux/.test(r)?"linux":"mac"}export{s as MAX_ERROR_LEN,h as calculateBalancePercentage,o as clampErrorMessage,_ as cn,i as csrfHeaders,E as detectPlatform,R as formatDate,x as formatTokens,y as getBalanceColor,u as readErrorMessage,f as safeUrl};
+import {clsx}from'clsx';import {twMerge}from'tailwind-merge';var d=false;function _(){if(typeof document>"u")return {};let e=document.cookie.match(/(?:^|;\s*)__csrf=([^;]*)/);if(!e)return d||(d=true,console.warn("[keyutils] __csrf cookie not found; mutations will be sent without a CSRF token")),{};let n=e[1];try{n=decodeURIComponent(n);}catch{}return {"x-csrf-token":n}}var b=500;function g(e,n){if(typeof e!="string"||e.length===0)return n;let t=e.replace(/[\u0000-\u001F\u007F]/g," ");return t.length>500?t.slice(0,500)+"\u2026":t}async function R(e,n){try{let t=await e.json();if(t&&typeof t=="object"&&"error"in t)return g(t.error,n)}catch{}return n}function F(e,n="#"){if(!e||typeof e!="string")return n;let t=e.trim();if(t===""||t==="#")return n;if(t.startsWith("/")||t.startsWith("./")||t.startsWith("../"))return t;try{let o=new URL(t);if(o.protocol==="http:"||o.protocol==="https:")return o.toString()}catch{}return n}var c={sent:"sent",routed:"routed",confirmed:"confirmed",finalized:"finalized",filed:"filed"},u={sent:{pending:"sent",progressing:"sending",done:"sent"},routed:{pending:"routed",progressing:"routing",done:"routed"},confirmed:{pending:"confirmed",progressing:"confirming",done:"confirmed"},finalized:{pending:"finalized",progressing:"finalizing",done:"finalized"},filed:{pending:"filed",progressing:"filing",done:"filed"}},k=["sent","routed","confirmed","finalized","filed"];function T(e){let n=new Map;(e??[]).forEach(r=>n.set(r.id,r));let t=k.map(r=>{let i=n.get(r);return i?{...i,label:i.label||c[r]}:{id:r,label:c[r],status:"pending",timestampMs:null,detail:null}}),o=t.reduce((r,i,a)=>i.status==="done"||i.status==="failed"?a:r,-1);if(o>0)for(let r=0;r<o;r++)t[r].status!=="failed"&&(t[r]={...t[r],status:"done"});if(!t.some(r=>r.status==="failed")){let r=t.findIndex(i=>i.status!=="done");if(r>=0){let i=t[r];i.status!=="current"&&(t[r]={...i,status:"current"});}}return t}function p(e){return e.find(n=>n.status==="current")??null}function m(e){return e.length>0&&e.every(n=>n.status==="done")}function x(e){return e.some(n=>n.status==="failed")}function E(e,n){if(!n)return {text:"loading",playing:true,stepId:"sent"};if(x(e))return {text:"failed",playing:false,stepId:"filed"};if(m(e))return {text:u.filed.done,playing:false,stepId:"filed"};let o=p(e)?.id??"sent";return {text:u[o].progressing,playing:true,stepId:o}}function v(...e){return twMerge(clsx(e))}function P(e){return e==null?"0":e>=1e9?`${(e/1e9).toFixed(1)}B`:e>=1e6?`${(e/1e6).toFixed(1)}M`:e>=1e3?`${(e/1e3).toFixed(1)}K`:e.toLocaleString()}function z(e,n){return n<=0?0:Math.min(100,Math.round(e/n*100))}function U(e){return e>=70?"bg-green-500":e>=30?"bg-yellow-500":"bg-red-500"}function K(e,n={}){let t=n.withSymbol!==false,o=Math.max(0,Math.min(6,n.maxDecimals??2));if(e==null||e==="")return t?"$0.00":"0.00";let s;try{if(typeof e=="bigint")s=e;else if(typeof e=="number")s=BigInt(Math.trunc(e));else {let l=String(e).trim().replace(/^\+/,"");if(/^-?\d+$/.test(l))s=BigInt(l);else {let f=Number(l);if(!Number.isFinite(f))return t?"$0.00":"0.00";s=BigInt(Math.trunc(f));}}}catch{return t?"$0.00":"0.00"}let r=s<0n,i=r?-s:s,a=i/1000000n,S=(i%1000000n).toString().padStart(6,"0").slice(0,o),h=a.toLocaleString("en-US"),y=o>0?`.${S}`:"";return `${r?"-":""}${t?"$":""}${h}${y}`}function O(e){if(e==null||e==="")return "";let n=typeof e=="string"&&/^\d+$/.test(e)?Number(e):e,t=new Date(n);return isNaN(t.getTime())?"":t.toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric"})}function H(){if(typeof navigator>"u")return "mac";let e=navigator.userAgent.toLowerCase();return /iphone|ipad|ipod/.test(e)?"ios":/android/.test(e)?"android":/win/.test(e)?"windows":/linux/.test(e)?"linux":"mac"}export{b as MAX_ERROR_LEN,c as TRACKER_LABELS,u as TRACKER_VERBS,z as calculateBalancePercentage,g as clampErrorMessage,v as cn,_ as csrfHeaders,p as currentState,T as deriveTrackerStates,H as detectPlatform,O as formatDate,K as formatPaperUsd,P as formatTokens,U as getBalanceColor,x as hasFailed,m as isAllDone,E as pickHeadline,R as readErrorMessage,F as safeUrl};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacknet/keyutils",
-  "version": "0.4.8",
+  "version": "0.6.0",
   "description": "Reusable components for buying and managing StackNet node keys",
   "type": "module",
   "main": "./dist/index.cjs",