@decentrys/ui-sdk 0.1.0

package/src/copy.test.ts

@@ -0,0 +1,214 @@
+/**
+ * The language guard.
+ *
+ * These components are where a risk model becomes sentences, and a sentence is
+ * far easier to get wrong than a type. One careless "verified" or "safe" in a
+ * default string undoes the argument the whole product is built on — and it
+ * would ship, because nothing else in the stack would notice.
+ *
+ * So every string this package authors is walked here. The exception, stated
+ * explicitly below, is the strings it *quotes* from `@decentrys/protect`: the
+ * risk-level and history meanings are the model's own words, they legitimately
+ * contain "assurance of safety" and "verified against evidence", and rendering
+ * them verbatim is the correct behaviour.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  HISTORY_STATUS_MEANING, RISK_LEVELS, RISK_LEVEL_MEANING,
+  type Evidence, type ThreatSignal, type UnknownReason,
+} from '@decentrys/protect';
+import { DEFAULT_COPY, resolveCopy, type UiCopy } from './copy';
+import {
+  RISK_LEVEL_LABEL, approvalPresentation, capabilityPresentation, decisionPresentation,
+  historyPresentation, hopPresentation, kindPresentation, levelPresentation, signalPresentation,
+  unknownPresentation,
+} from './presentation';
+
+/**
+ * Words that must never appear in a string this package writes.
+ *
+ *  - `safe` / `safety` — a claim no analysis can support.
+ *  - `scam` / `fraud` — accusations that need evidence, and that the model
+ *    deliberately refuses to make even at its top level.
+ *  - `trusted` / `verified` / `certified` / `approved` — they imply a registry
+ *    a project can join, which is the pay-to-verify model this product exists
+ *    to refuse.
+ *  - `legitimate`, `dangerous` — verdicts rather than observations.
+ */
+const BANNED = [
+  'safe', 'safely', 'safety', 'unsafe',
+  'scam', 'scammer', 'fraud', 'fraudulent',
+  'trusted', 'untrusted', 'trustworthy',
+  'verified', 'verify', 'verification', 'certified',
+  'whitelisted', 'blacklisted', 'legitimate', 'legit',
+  'dangerous', 'guaranteed',
+];
+
+const BANNED_RE = new RegExp(`\\b(${BANNED.join('|')})\\b`, 'i');
+
+const EXAMPLE_EVIDENCE = (analystVerified: boolean): Evidence => ({
+  id: 'ev_example_1',
+  type: 'ADDRESS_ATTRIBUTION',
+  source: 'Decentrys',
+  observedAt: '2026-09-05T18:22:04.000Z',
+  confidence: 0.9,
+  analystVerified,
+});
+
+const EXAMPLE_SIGNAL = (overrides: Partial<ThreatSignal> = {}): ThreatSignal => ({
+  type: 'ATTRIBUTED_COUNTERPARTY',
+  severity: 'HIGH',
+  confidence: 0.8,
+  explanation: 'Example explanation supplied by the API, not authored here.',
+  hops: 1,
+  evidence: [EXAMPLE_EVIDENCE(false)],
+  status: 'ACTIVE',
+  createdAt: '2026-09-01T00:00:00.000Z',
+  lastSeen: '2026-09-05T00:00:00.000Z',
+  ...overrides,
+});
+
+/** Every string this package authors, as opposed to quotes from the model. */
+function authoredStrings(): string[] {
+  const out: string[] = [...Object.values(DEFAULT_COPY)];
+
+  out.push(...Object.values(RISK_LEVEL_LABEL));
+  for (const level of RISK_LEVELS) out.push(levelPresentation(level).label);
+
+  for (const status of ['ESTABLISHED', 'MODERATE', 'LIMITED', 'NONE'] as const) {
+    out.push(historyPresentation(status).label);
+  }
+
+  for (const hops of [0, 1, 2, 5]) {
+    const hop = hopPresentation(hops, 'token');
+    out.push(hop.label, hop.statement);
+  }
+
+  for (const action of ['allow', 'inform', 'warn', 'warn_strong', 'require_confirmation', 'block'] as const) {
+    const d = decisionPresentation({ action, reason: 'example reason from the API' });
+    out.push(d.label, d.statement);
+  }
+
+  for (const kind of ['fact', 'capability', 'signal', 'unknown'] as const) {
+    out.push(kindPresentation(kind, DEFAULT_COPY).label);
+  }
+
+  for (const severity of ['INFO', 'NOTABLE', 'SIGNIFICANT'] as const) {
+    out.push(capabilityPresentation({
+      type: 'MINT_AUTHORITY_ACTIVE', severity, statement: 'Example statement from the API.',
+    }).severityLabel);
+  }
+
+  for (const reason of ['UNKNOWN', 'INSUFFICIENT_DATA', 'PROVIDER_UNAVAILABLE', 'NOT_APPLICABLE'] as UnknownReason[]) {
+    out.push(unknownPresentation({
+      field: 'example', reason, statement: 'Example statement from the API.',
+    }).reasonLabel);
+  }
+
+  for (const signal of [
+    EXAMPLE_SIGNAL(),
+    EXAMPLE_SIGNAL({ status: 'STALE' }),
+    EXAMPLE_SIGNAL({ status: 'DISPUTED_FACT' }),
+    EXAMPLE_SIGNAL({ confidence: 0.2 }),
+    EXAMPLE_SIGNAL({ evidence: [EXAMPLE_EVIDENCE(true)] }),
+  ]) {
+    const p = signalPresentation(signal, DEFAULT_COPY, { subjectNoun: 'address' });
+    out.push(p.severityLabel, p.statusLabel, p.hopLabel, p.hopStatement, p.attribution);
+    if (p.inertStatement) out.push(p.inertStatement);
+  }
+
+  for (const approval of [
+    { token: '0xtoken', symbol: 'USDC', decimals: 6, spender: '0xspender', amount: 'unlimited' },
+    { token: '0xtoken', symbol: 'USDC', decimals: 6, spender: '0xspender', amount: '1000000' },
+    { token: '0xtoken', spender: '0xspender', amount: '1000000' },
+    { token: '0xtoken', spender: '0xspender' },
+  ]) {
+    const p = approvalPresentation(approval);
+    out.push(p.scopeLabel, p.statement, p.amountLabel);
+  }
+
+  return out;
+}
+
+describe('default copy', () => {
+  it('has a non-empty string for every key', () => {
+    for (const [key, value] of Object.entries(DEFAULT_COPY)) {
+      expect(typeof value, key).toBe('string');
+      expect(value.trim().length, key).toBeGreaterThan(0);
+    }
+  });
+
+  it('names the four kinds with four distinct words', () => {
+    const labels = [
+      DEFAULT_COPY.factLabel, DEFAULT_COPY.capabilityLabel,
+      DEFAULT_COPY.signalLabel, DEFAULT_COPY.unknownLabel,
+    ];
+    expect(new Set(labels).size).toBe(4);
+  });
+
+  it('merges an integrator’s overrides without losing the rest', () => {
+    const merged: UiCopy = resolveCopy({ factLabel: 'Beobachtung' });
+    expect(merged.factLabel).toBe('Beobachtung');
+    expect(merged.signalLabel).toBe(DEFAULT_COPY.signalLabel);
+  });
+
+  it('returns the defaults untouched when nothing is overridden', () => {
+    expect(resolveCopy()).toBe(DEFAULT_COPY);
+  });
+
+  it('carries an override through into a signal’s attribution', () => {
+    const copy = resolveCopy({ notAnalystConfirmed: 'Automatisch erkannt.' });
+    const p = signalPresentation(EXAMPLE_SIGNAL(), copy);
+    expect(p.attribution).toBe('Automatisch erkannt.');
+  });
+});
+
+describe('language rules', () => {
+  it('uses none of the banned words in any string it authors', () => {
+    const offenders = authoredStrings().filter((text) => BANNED_RE.test(text));
+    expect(offenders).toEqual([]);
+  });
+
+  it('quotes the model’s own meanings rather than paraphrasing them', () => {
+    // These *do* contain "assurance of safety" and "verified against evidence",
+    // and that is correct: they are the model's definitions of its own levels,
+    // and rewording them here would let the SDK and the UI drift apart.
+    for (const level of RISK_LEVELS) {
+      expect(levelPresentation(level).meaning).toBe(RISK_LEVEL_MEANING[level]);
+    }
+    for (const status of ['ESTABLISHED', 'MODERATE', 'LIMITED', 'NONE'] as const) {
+      expect(historyPresentation(status).statement).toBe(HISTORY_STATUS_MEANING[status]);
+    }
+  });
+
+  it('describes an absence of findings as an absence', () => {
+    expect(DEFAULT_COPY.noSignals).toContain('absence of findings');
+    expect(DEFAULT_COPY.notAnAssurance).toContain('not an assurance');
+  });
+
+  it('says an unknown never contributes to risk', () => {
+    expect(DEFAULT_COPY.unknownsAreNotRisk).toContain('never contributes to a risk level');
+  });
+
+  it('says coverage is never added to a risk total', () => {
+    expect(DEFAULT_COPY.coverageIsNotRisk).toContain('never added to a risk total');
+  });
+
+  it('says a capability is not evidence of use', () => {
+    expect(DEFAULT_COPY.capabilitiesAreNotFindings).toContain('not evidence that it has been');
+  });
+
+  it('leaves the decision with the integrator', () => {
+    expect(DEFAULT_COPY.policyIsYours).toContain('not ours');
+  });
+
+  it('explains a demotion instead of silently dropping the signal', () => {
+    expect(DEFAULT_COPY.demotedExplanation).toContain('cannot raise a risk level');
+  });
+
+  it('attributes an analyst confirmation to a person, not to a badge', () => {
+    expect(DEFAULT_COPY.analystConfirmed).toContain('analyst');
+    expect(DEFAULT_COPY.notAnalystConfirmed).toContain('No analyst has confirmed it');
+  });
+});

package/src/copy.ts

@@ -0,0 +1,151 @@
+/**
+ * Every fixed string these components can put in front of a user.
+ *
+ * It lives in one object for two reasons. The first is customisation: an
+ * integrator passes `copy` to any component and overrides whatever it needs,
+ * including into another language, without forking a component. The second is
+ * enforcement — a single object is something a test can walk end to end, and
+ * `copy.test.ts` does exactly that, because the language rules are far easier
+ * to break in a sentence than in a type.
+ *
+ * The rules these strings are held to:
+ *
+ *  - Never "safe", "scam", "trusted" or "verified" as a claim about a subject.
+ *    "Safe" is a claim no analysis supports, "scam" is an accusation needing
+ *    evidence, and "verified"/"trusted" imply a registry Decentrys does not
+ *    run and will never sell a place in.
+ *  - Limited or absent history is stated, never warned about.
+ *  - An absence of findings is described as an absence, never as a clean bill.
+ *  - Anything above zero hops is described as an inference about a
+ *    counterparty, because that is what it is.
+ */
+
+export interface UiCopy {
+  // Section headings
+  factsHeading: string;
+  capabilitiesHeading: string;
+  signalsHeading: string;
+  unknownsHeading: string;
+  evidenceHeading: string;
+  componentsHeading: string;
+  historyHeading: string;
+  demotedHeading: string;
+
+  // Kind labels — the non-colour carrier that keeps a fact from reading as a
+  // threat. Every row is prefixed with one of these, in text.
+  factLabel: string;
+  capabilityLabel: string;
+  signalLabel: string;
+  unknownLabel: string;
+
+  // Standing statements
+  notAnAssurance: string;
+  factsAreNotFindings: string;
+  capabilitiesAreNotFindings: string;
+  unknownsAreNotRisk: string;
+  coverageIsNotRisk: string;
+  policyIsYours: string;
+  demotedExplanation: string;
+
+  // Empty states — a blank panel is indistinguishable from a clean result, so
+  // there is no blank panel.
+  noFacts: string;
+  noCapabilities: string;
+  noSignals: string;
+  noUnknowns: string;
+  nothingReturned: string;
+
+  // Controls
+  viewDetails: string;
+  close: string;
+  detailsTitle: string;
+  showEvidence: string;
+  hideEvidence: string;
+
+  // Assorted
+  confidenceLabel: string;
+  confidenceCaveat: string;
+  sourceLabel: string;
+  observedLabel: string;
+  grantedByLabel: string;
+  hopsLabel: string;
+  statusLabel: string;
+  analystConfirmed: string;
+  notAnalystConfirmed: string;
+  cachedNotice: string;
+  modelLabel: string;
+  assessedLabel: string;
+  approvalHeading: string;
+  approvalRevocation: string;
+  spenderLabel: string;
+  tokenLabel: string;
+}
+
+export const DEFAULT_COPY: UiCopy = {
+  factsHeading: 'Observed facts',
+  capabilitiesHeading: 'What this contract can do',
+  signalsHeading: 'Threat signals',
+  unknownsHeading: 'Not known',
+  evidenceHeading: 'Evidence',
+  componentsHeading: 'Score components',
+  historyHeading: 'History',
+  demotedHeading: 'Reported as facts, not as risk',
+
+  factLabel: 'Fact',
+  capabilityLabel: 'Capability',
+  signalLabel: 'Threat signal',
+  unknownLabel: 'Unknown',
+
+  notAnAssurance:
+    'An absence of findings is an absence of findings. It is not an assurance about this subject.',
+  factsAreNotFindings:
+    'These are directly observed and carry no accusation. None of them raises a risk level on its own.',
+  capabilitiesAreNotFindings:
+    'What the code is able to do. A capability is not evidence that it has been or will be used.',
+  unknownsAreNotRisk:
+    'Reported as unknown rather than guessed at. An unknown never contributes to a risk level.',
+  coverageIsNotRisk:
+    'Coverage measures how much Decentrys knows about this subject. It is reported separately and is never added to a risk total.',
+  policyIsYours:
+    'Decentrys reports evidence. What happens next is this application’s decision, not ours.',
+  demotedExplanation:
+    'These arrived labelled as risk signals and describe how much is known rather than what was found, so they are shown as facts and cannot raise a risk level.',
+
+  noFacts: 'No facts were returned for this subject.',
+  noCapabilities: 'No security-sensitive capabilities were identified.',
+  noSignals:
+    'No threat signals were found. That is an absence of findings, not a finding that there is nothing to find.',
+  noUnknowns: 'Every attribute checked returned an answer.',
+  nothingReturned:
+    'Decentrys returned no facts, capabilities, threat signals or unknowns for this subject.',
+
+  viewDetails: 'View details',
+  close: 'Close',
+  detailsTitle: 'Assessment details',
+  showEvidence: 'Show evidence',
+  hideEvidence: 'Hide evidence',
+
+  confidenceLabel: 'Confidence',
+  confidenceCaveat:
+    'How well the evidence supports this classification. It is not a measure of how much harm the subject could do.',
+  sourceLabel: 'Source',
+  observedLabel: 'Observed',
+  grantedByLabel: 'Granted by',
+  hopsLabel: 'Distance',
+  statusLabel: 'Status',
+  analystConfirmed: 'Confirmed by a Decentrys analyst against the evidence above.',
+  notAnalystConfirmed: 'Automated finding. No analyst has confirmed it.',
+  cachedNotice: 'Served from a local cache rather than a fresh lookup.',
+  modelLabel: 'Model',
+  assessedLabel: 'Assessed',
+  approvalHeading: 'What you are about to grant',
+  approvalRevocation:
+    'An allowance stays in place until it is revoked, whether or not the application is used again.',
+  spenderLabel: 'Spender',
+  tokenLabel: 'Token',
+};
+
+/** Merge an integrator's overrides over the defaults. */
+export function resolveCopy(overrides?: Partial<UiCopy>): UiCopy {
+  return overrides ? { ...DEFAULT_COPY, ...overrides } : DEFAULT_COPY;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * `@decentrys/ui-sdk` — the drop-in React components integrators embed.
+ *
+ * ## Naming
+ *
+ * The plan calls this package `@decentrys/ui`. That name is already taken by
+ * `packages/ui`, the platform's internal component library, and two packages
+ * sharing a name in one pnpm workspace makes `workspace:*` ambiguous and
+ * breaks install for the whole repository. The `-sdk` suffix follows the
+ * convention already set by `@decentrys/risk-sdk` and `@decentrys/sentinel-sdk`,
+ * which collided with `packages/risk` and `packages/sentinel` the same way.
+ *
+ * ## The rule these components exist to keep
+ *
+ *   Unknown is neutral. Risk requires evidence. Malicious requires stronger
+ *   evidence. Users should be shown why.
+ *
+ * A classifier that honours that rule and a UI that renders "deployed 3 days
+ * ago" in the same amber as "attributed to a drainer family" has still told
+ * the user the wrong thing. So the presentation decisions live in
+ * `presentation.ts` as pure functions, and they are what the tests target.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { Decentrys } from '@decentrys/protect';
+ * import { DecentrysUiProvider, TransactionRiskBanner } from '@decentrys/ui-sdk';
+ *
+ * const decentrys = new Decentrys({ apiKey, failMode: 'warn' });
+ * const result = await decentrys.assessTransaction(tx);
+ *
+ * <DecentrysUiProvider theme={{ surface: '#0b0d10', text: '#e8ebef' }}>
+ *   <TransactionRiskBanner
+ *     result={result}
+ *     // Your button, your policy. This package never disables it.
+ *     actions={<button onClick={sign}>Sign</button>}
+ *   />
+ * </DecentrysUiProvider>
+ * ```
+ *
+ * React and react-dom are peer dependencies and are never bundled. Two copies
+ * of React in one application is a real, common and confusing breakage.
+ */
+
+export { TransactionRiskBanner, type TransactionRiskBannerProps } from './components/TransactionRiskBanner';
+export { ApprovalWarning, type ApprovalWarningProps } from './components/ApprovalWarning';
+export { ContractFacts, type ContractFactsProps } from './components/ContractFacts';
+export { ThreatSignalList, type ThreatSignalListProps } from './components/ThreatSignalList';
+export { RiskDetailsModal, type RiskDetailsModalProps } from './components/RiskDetailsModal';
+export { TokenSecurityPanel, type TokenSecurityPanelProps } from './components/TokenSecurityPanel';
+export { AddressRiskBadge, type AddressRiskBadgeProps } from './components/AddressRiskBadge';
+
+export {
+  DecentrysUiProvider, DecentrysUiStyles, useUiConfig,
+  type DecentrysUiProviderProps, type ResolvedUiConfig, type UiConfigInput,
+} from './context';
+
+export { DECENTRYS_UI_CSS } from './styles';
+
+export {
+  THEME_TOKENS, themeStyle, toneBgVar, toneVar,
+  type DecentrysTheme, type ThemeToken, type Tone,
+} from './theme';
+
+export { DEFAULT_COPY, resolveCopy, type UiCopy } from './copy';
+
+export {
+  MIN_RAISING_CONFIDENCE, RISK_LEVEL_LABEL,
+  approvalPresentation, assessmentSections, availabilityPresentation, capabilityPresentation,
+  componentRows, decisionPresentation, evidencePresentation, factPresentation, formatConfidence,
+  formatTimestamp, formatTokenAmount, historyPresentation, hopPresentation, isUnlimitedAllowance,
+  kindPresentation, levelPresentation, levelRank, plural, shortenAddress, signalPresentation,
+  unknownPresentation,
+  type ApprovalDetails, type ApprovalPresentation, type AssessmentSections,
+  type AvailabilityPresentation, type CapabilityPresentation, type ComponentRow,
+  type DecisionPresentation, type EvidenceKind, type EvidencePresentation, type FactPresentation,
+  type HistoryPresentation, type HopPresentation, type KindPresentation, type LevelPresentation,
+  type SignalPresentation, type UnknownPresentation,
+} from './presentation';
+
+export {
+  Chip, EmptyNote, LevelBadge, Mono, ScreenReaderText, Section, cx,
+  type CommonProps,
+} from './primitives';