@private.me/shared

Shared types, error constructors, and constants for the Private.Me platform.

@private.me/shared is the foundational package that every other package depends on. It exports the Result<T, E> discriminated union for error handling without thrown exceptions, the ok() and err() constructors, TLV type code constants for message serialization, and 140+ TypeScript interfaces covering every domain in the system.

Install

pnpm add @private.me/shared

Quick Start

import { ok, err } from '@private.me/shared';
import type { Result } from '@private.me/shared';

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return err('Division by zero');
  }
  return ok(a / b);
}

const result = divide(10, 2);

if (result.ok) {
  console.log(result.value); // 5
} else {
  console.error(result.error);
}

Core Exports

Functions

• ok<T>(value: T) — Create successful Result<T, never>
• err<E>(error: E) — Create failed Result<never, E>

Constants

• TLV_TYPE — TLV type codes for message serialization (MESSAGE_BODY, ATTACHMENT, SENDER_ID, TIMESTAMP, MESSAGE_UUID, SHARE_INDEX, TOTAL_SHARES, THRESHOLD, HMAC_KEY, HMAC_SIGNATURE, CONTENT_TYPE, MESSAGE_SUBJECT, SENDER_EMAIL)

Result Pattern

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

The Result<T, E> pattern prevents uncaught exceptions across the entire codebase. Every fallible operation returns a Result instead of throwing, forcing callers to handle errors explicitly.

Type Categories

@private.me/shared exports 140+ TypeScript types organized by domain:

• Core — Result pattern, email providers, channel addresses, security tiers, contact info
• Messages — XailMessage, RegularEmail, Attachment, XailShare, ContentType, MessageType
• Crypto — PaddingError, ReconstructionError, SerializationError, IntegrityError
• Transport — TransportError, OAuth tokens, PKCE challenge
• Search — MessageMetadata, SearchQuery, SearchResult, MessageThread, ExtractedEntity
• AI — InferenceRuntime, MessageEmbedding, AiSettings, OllamaStatus
• Enterprise — EnterpriseConfig, ComplianceCopy, DlpScanResult, AuditEntry, Delegation
• Trust — TrustLevel, KeyTransparencyEntry, VerificationChallenge, KeyRotationRecord
• API — ApiKey, ApiKeyPermission, SplitRequest, RetrieveRequest, ApiRateLimit
• Admin — SsoProvider, SsoConfig, OrgUser, UserRole, OrgPolicy
• White-Label — BrandConfig, DomainConfig, EmailTemplateConfig
• Server — TokenExchangeRequest, InvitationInfo, ServerConfig, ServerError
• Analytics — AnalyticsEvent, AnalyticsEventType, AnalyticsEventFilter
• Accounts — AccountRecord, SyncProfile, DeviceRecord, SubscriptionTier
• Deferred Delivery — DeferredShare, WrapperEmailContent, DeferredDeliveryStatus

Complete type reference →

Security

The Result<T, E> pattern is a deliberate architectural choice that prevents uncaught exceptions across the entire codebase. Every fallible operation returns a Result instead of throwing.

This ensures:

• Error paths are always handled — TypeScript compiler forces callers to check result.ok
• Crypto operations fail closed — HMAC verification failures return structured errors, never unhandled exceptions
• No sensitive data leaks through stack traces — Structured error objects with typed code fields replace thrown Error instances

All error types use typed code discriminants (e.g., 'HMAC_FAILURE', 'TOKEN_REVOKED') for reliable programmatic handling.

Related Packages

| Package | Description | |---------|-------------| | @private.me/crypto | XorIDA threshold sharing, HMAC, TLV serialization, padding | | @private.me/transport | Gmail, Outlook, Yahoo API adapters + share routing | | @private.me/xbind | Agent identity, envelope encryption, trust registry | | @private.me/search | Encrypted metadata index + keyword/entity search | | @private.me/ai | AI provider abstraction layer (Ollama, embeddings) | | @private.me/enterprise | Enterprise compliance module (key escrow, DLP, audit) | | @private.me/cache | AES-256-GCM encrypted IndexedDB message cache |

Documentation

• Complete Type Reference — All 140+ types with detailed field documentation
• Error Handling Guide — Result pattern usage and best practices
• TLV Serialization — Message serialization format

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Node.js 20+ | Supported | Primary target | | Tauri v2 (Chromium) | Supported | Desktop app runtime | | Chromium 113+ | Supported | Ed25519 + X25519 Web Crypto | | Firefox 130+ | Supported | Ed25519 added in 130 | | Safari 17+ | Supported | Ed25519 added in 17 | | Deno 1.40+ | Supported | Web Crypto available | | Bun 1.0+ | Supported | Web Crypto available |

Versioning

This package follows Semantic Versioning 2.0.0. See the Versioning Policy for details.

Pricing

All Private.Me ACIs use usage-based pricing: Basic ($5 per month), Pro ($10 per month), Enterprise ($15 per month).

• Basic — $5 per month (100k interactions)
• Pro — $10 per month (100k interactions, priority support)
• Enterprise — $15 per month (100k interactions, white-label, compliance)

3-month free trial included for all tiers. Start free trial →

See pricing details for complete information.

Purchase Flow

The Private.Me platform uses a unified subscription API for all ACIs:

# Purchase subscription
curl -X POST https://private.me/api/purchase \
  -H "Content-Type: application/json" \
  -d '{
    "product": "shared",
    "tier": "basic",
    "email": "[email protected]"
  }'

Response (RFC 7807 structured error format):

{
  "subscription_id": "sub_1234567890",
  "tier": "basic",
  "status": "active",
  "trial_end": "2026-08-11T00:00:00Z"
}

Field-level error structure:

{
  "type": "https://private.me/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "fields": {
    "email": "Invalid email format",
    "tier": "Must be one of: basic, pro, enterprise"
  }
}

License

Copyright © 2024-2026 Standard Clouds, Inc. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited.

Licensed under: Proprietary Company: Standard Clouds, Inc. dba PRIVATE.ME Registry: Private npm registry

For licensing inquiries: [email protected]

Legal

By using this package, you agree to the Terms of Service and Privacy Policy.

This software is proprietary and confidential. See LICENSE.md for details.

Privacy Notice: This package connects to Private.Me platform services for type validation and error reporting. See our Privacy Policy for data handling practices.