# Limestone SDK

> Contracts-first mobile toolkit for React Native + Expo.
> 16 ports, 33 adapters, 150+ components across 17 categories, hexagonal architecture.
> npm: @objectifthunes/limestone-sdk
> GitHub: https://github.com/MaxouJS/limestone-sdk

## Quick Start

npm install @objectifthunes/limestone-sdk
# Optional peer deps: react-native-reanimated, react-native-gesture-handler,
# react-native-svg, react-native-safe-area-context

## Architecture

Ports (interfaces) → Core logic ← Adapters (implementations)

The deletion test: remove any adapter and the core still compiles.
Only 1 hard dependency: zod.

## 16 Ports

- BiometricProvider: Fingerprint / Face ID authentication
- CameraProvider: Take pictures via device camera
- SecureStorageProvider: Encrypted key-value storage
- HapticsProvider: Tactile feedback (impact, notification, selection)
- NotificationProvider: Local + push notifications, badge count
- PurchaseProvider: In-app purchases and subscriptions
- PermissionsProvider: Check and request OS permissions
- ShareProvider: Native share sheet
- ClipboardProvider: Read/write system clipboard
- KeychainProvider: Secure credential storage
- LocationProvider: GPS position, watch updates
- MediaLibraryProvider: Pick images/videos, save to library
- MapProvider: Render a native map with markers
- WebBrowserProvider: In-app browser
- ContactsProvider: Read device contacts
- ReviewProvider: Trigger native app-review prompt

## 33 Adapters

### 19 Expo Adapters
expo-biometrics, expo-camera, expo-secure-store, expo-haptics,
expo-notifications, expo-purchases, expo-permissions, expo-sharing,
expo-clipboard, expo-location, expo-media-library, expo-map,
expo-web-browser, expo-contacts, expo-review,
expo-keychain, expo-video, expo-qr-scanner, expo-web-view

### 6 R3F Adapters (./r3f — requires @react-three/fiber, @react-three/drei, three)
r3f-scene3d, r3f-model-viewer, r3f-object-scanner,
r3f-before-after-3d, r3f-panorama360, r3f-map-scene3d

### 8 ViroReact Adapters (./viro — requires @reactvision/react-viro)
viro-ar-view, viro-ar-try-on, viro-ar-placement, viro-ar-measure,
viro-ar-annotation, viro-ar-world-object, viro-ar-navigation, viro-ar-body-measure

## 150+ Components across 17 Categories

Primitives (13): Box, Text, Pressable, Image, Icon, Spacer, Divider, Skeleton, Gradient, BlurView, Button, IconButton, Link
Layout (5): Stack, Grid, ScrollView, SafeArea, KeyboardAvoidingView
Inputs (17): TextInput, SearchBar, Select, Switch, Checkbox, RadioGroup, Slider, OTPInput, PhoneInput, SegmentedControl, DatePicker, Chip, ChipInput, QuantityPicker, Autocomplete, Calendar, SignaturePad
Navigation (9): BottomSheet, TabBar, Header, ActionSheet, Drawer, FAB, PageIndicator, CollapsibleHeader, Tabs
Overlays (6): Modal, Popover, Tooltip, Menu, Lightbox, ContextMenu
Feedback (9): Toast, Alert, Dialog, ProgressBar, ProgressCircle, Spinner, Badge, Banner, ConnectionStatus
Interactive (6): SwipeableRow, DragToReorder, PullToRefresh, PinchToZoom, ParallaxHeader, PageView
Social (5): StoryRow, ReactionPicker, CommentThread, MentionInput, PresenceIndicator
Data Display (17): Card, Avatar, Tag, List, Accordion, EmptyState, StepIndicator, Timeline, ListItem, RatingStars, PriceDisplay, KeyValueRow, Chart, ActivityRing, CountdownTimer, CreditCardDisplay, DataTable
Screens (20): AuthScreen, OnboardingScreen, SettingsScreen, ProfileScreen, ListDetailScreen, PaywallScreen, ChatScreen, SearchScreen, ErrorScreen, ForceUpdateScreen, NotificationCenterScreen, DashboardScreen, ProductDetailScreen, OrderTrackingScreen, TransactionDetailScreen, CartScreen, FeedScreen, FormWizardScreen, HistoryScreen, MediaDetailScreen
Media (8): CameraView, ImagePicker, VideoPlayer, Carousel, QRScanner, AudioPlayer, MapView, WebView
Forms (3): Form, FormField, FormError
3D (6): Scene3D, ModelViewer, ObjectScanner, BeforeAfter3D, Panorama360, MapScene3D
AR (8): ARView, ARTryOn, ARPlacement, ARMeasure, ARAnnotation, ARWorldObject, ARNavigation, ARBodyMeasure
Content (5): MarkdownRenderer, CodeBlock, RichTextEditor, BlockQuote, Callout
Offline (5): SyncIndicator, ConflictCard, OfflineQueueList, CachedImage, PendingBadge
Animations (8): FadeIn, SlideUp, ScalePress, SpringBounce, Stagger, Shimmer, Confetti, ErrorShake

## Core Systems

- Observable Store: createStore() — reactive state with selectors
- Theme Engine: defineTheme() — Zod-validated tokens (colors, spacing, radii, typography, shadows, motion)
- API Client: createApiClient() — Bearer auth, token refresh, retry, offline queue, GET dedup
- Form Engine: useForm() — Zod schema validation, field-level + form-level
- 17 React Hooks: useStore, useAuth, useNetwork, useApi, useBiometrics, useHaptics, useNotifications, usePermissions, useInAppReview, useDebounce, useKeyboard, useAppState, useDeepLink, useOrientation, useDimensions, useBackHandler, useColorScheme
- 8 Animation Primitives: FadeIn, SlideUp, ScalePress, SpringBounce, Stagger, Shimmer, Confetti, ErrorShake

## Component Pattern

Every component: types.ts → use-xxx.ts (pure function hook) → xxx.tsx (React shell) → index.ts
Hooks accept (ThemeTokens, props), return resolved styles + derived values. No React state in hooks.

## Import Patterns

Core: import { createStore, defineConfig, LimestoneProvider, useTheme, ... } from '@objectifthunes/limestone-sdk'
Adapters: import { createExpoBiometrics } from '@objectifthunes/limestone-sdk/expo-biometrics'
Animations: import { FadeIn, SlideUp } from '@objectifthunes/limestone-sdk/animations'
Testing: import { createTestApp } from '@objectifthunes/limestone-sdk/testing'
Dev: import { createExpoBiometrics } from '@objectifthunes/limestone-sdk/dev'

## Common Tasks

### Add a screen with auth
1. Wrap app in LimestoneProvider with auth config
2. Use useAuth() hook for status/login/logout
3. Guard routes with auth.status === 'authenticated'

### Create a themed component
1. Define types.ts with props extending BoxStyleProps
2. Write pure hook: useMyComponent(tokens, props) → styles
3. Write shell: forwardRef + createElement + useTheme()

### Wire a native feature
1. Install Expo module: npx expo install expo-camera
2. Import adapter: import { createExpoCamera } from './expo-camera'
3. Wire in config: adapters: { camera: createExpoCamera() }
4. Use in component: useLimestone().adapters.camera

## Testing

createTestApp({ theme }) — wires all in-memory adapters + MockApiClient.
app.biometrics.state.available = false   // manipulate adapter state
app.api.mockResponse('GET', '/users/me', { status: 200, body: { id: '1' } })
app.resetAll()  // clean slate between tests

## Error Types

NotFoundError (404), UnauthorizedError (401), ForbiddenError (403),
ValidationError (400), ConflictError (409), RateLimitError (429),
InternalError (500). All extend AppError with code, statusCode, details.

## MCP Server

@objectifthunes/limestone-mcp — Model Context Protocol server for live SDK assistance.

Install in Claude Code: claude mcp add limestone-mcp -- npx @objectifthunes/limestone-mcp

Tools:
- getPortInterface(portName) — Full TypeScript interface + usage example for any of the 16 ports
- getAdapterExample(adapterName) — Import + factory + defineConfig wiring for any of the 17 adapters
- diagnose(errorMessage) — Root cause + fix for SDK errors (NOT_FOUND, UNAUTHORIZED, adapter not registered, Provider not found, etc.)

Resources:
- limestone://ports — All 16 ports with descriptions
- limestone://adapters — All 17 adapters by category
- limestone://components — All 150+ components across 17 categories

## Commands

pnpm run build    — Compile TypeScript
pnpm test         — Unit tests
pnpm run lint     — Type-check (tsc --noEmit)