sitepong 0.1.9 → 0.1.11

package/README.md

@@ -596,6 +596,209 @@ Content inside `<SensitiveView>` is replaced with a black rectangle in recorded
 | `bufferDuration` | `10000` (10s) | `60000` (60s) | Rolling buffer size in ms |
 | `maxDuration` | `3600000` | `3600000` | Max recording duration in ms |
 
+### Push Notifications & Live Activities
+
+Native APNs (iOS) and FCM (Android) push notifications, plus iOS Live Activity updates. SitePong sends directly to Apple/Google — no Expo Push service in the path.
+
+#### Token lifecycle
+
+There are two halves to push: the **client SDK** registers device tokens with the SitePong ingest server, and the **server-side Push API** sends notifications to those tokens.
+
+```
+[App launches]
+   ↓
+[Notifications.getDevicePushTokenAsync()]   ← OS gives you a native token
+   ↓
+[registerDeviceToken(token, opts)]           ← SDK POSTs to /api/push/tokens
+   ↓                                            with X-API-Key: sp_live_xxx
+[Token stored in SitePong]
+   ↓
+[identify('user-123')]                        ← SDK auto re-registers token
+   ↓                                            with user_id (via lazy hook)
+[Your backend → POST /api/push/send]          ← server-only sp_push_xxx key
+   ↓
+[SitePong → APNs / FCM → Device]
+```
+
+#### 1. Install permission and get the native token
+
+```bash
+npx expo install expo-notifications
+```
+
+```typescript
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+import { Platform } from 'react-native';
+
+if (!Device.isDevice) return; // simulator can't receive push
+
+const { status } = await Notifications.requestPermissionsAsync();
+if (status !== 'granted') return;
+
+// Returns the raw native token (APNs hex on iOS, FCM token on Android)
+const { data: token } = await Notifications.getDevicePushTokenAsync();
+```
+
+#### 2. Register the token with SitePong
+
+```typescript
+import { registerDeviceToken } from '@sitepong/sdk/react-native';
+import { Platform } from 'react-native';
+
+registerDeviceToken(token, {
+  platform: Platform.OS as 'ios' | 'android',
+  environment: __DEV__ ? 'sandbox' : 'production',
+  userId: 'user-123', // optional — can be set later via identify()
+});
+```
+
+This makes a `POST /api/push/tokens` request to the ingest server with `X-API-Key: <your SDK key>`. The body includes the token, `token_type` (`apns`/`fcm`), `device_id`, `user_id`, `platform`, app version, device model, and OS version. The server upserts by `(token, environment)` so re-registration is idempotent.
+
+#### 3. User identification (automatic)
+
+When you call `identify(userId)`, the SDK automatically re-registers all cached push, Live Activity, and push-to-start tokens with the new `user_id`. **You do not need to call `registerDeviceToken()` again after login.**
+
+```typescript
+import { identify } from '@sitepong/sdk/react-native';
+
+// Token already registered anonymously at app launch
+// Now user logs in:
+identify('user-123');
+// → SDK re-POSTs /api/push/tokens with user_id: "user-123"
+```
+
+The hook is installed lazily the first time any `register*` function is called, so it works whether you use `SitePongRNProvider` or call `initRN()` directly.
+
+#### 4. Send notifications from your backend
+
+Generate a separate **Push API key** (prefix `sp_push_`) from the Notifications tab in the SitePong dashboard. This is **not** the SDK key — it's server-only and has permission to send pushes.
+
+```bash
+curl -X POST https://api.sitepong.com/api/push/send \
+  -H "Authorization: Bearer sp_push_xxxxxxxxxxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Order Shipped",
+    "body": "Your order #1234 is on its way",
+    "data": { "orderId": "1234" },
+    "target": { "user_ids": ["user-123"] }
+  }'
+```
+
+Targeting options (provide at least one):
+
+- `user_ids: string[]` — sends to all active devices for these users
+- `device_ids: string[]` — sends to specific SitePong device IDs
+- `tokens: string[]` — sends directly to raw APNs/FCM tokens
+
+#### Live Activities (iOS)
+
+SitePong ships a turnkey Live Activity package — a generic SwiftUI Widget Extension that the bundled config plugin generates at prebuild, plus a JavaScript API that drives it from data. **No Swift required.** Customers compose their Live Activity using SF Symbols, custom progress bars, and styled text fields entirely from JS.
+
+Install the package:
+
+```bash
+npm install @sitepong/expo-live-activity
+```
+
+Add the config plugin to `app.json` / `app.config.js`:
+
+```json
+{
+  "plugins": ["@sitepong/expo-live-activity"]
+}
+```
+
+Then prebuild and rebuild your app (`npx expo prebuild --clean`). The plugin creates a Widget Extension target named `SitePongLiveActivityWidget` containing the SitePong template, sets `NSSupportsLiveActivities` in the main app, and wires the extension into the Xcode project.
+
+Start a Live Activity from JavaScript:
+
+```typescript
+import { startLiveActivity, updateLiveActivity, endLiveActivity } from '@sitepong/expo-live-activity';
+
+const { activityId } = await startLiveActivity({
+  activityType: 'order-tracking',
+  attributes: { id: '#1234' },
+  contentState: {
+    title: 'Order #1234',
+    subtitle: 'Driver is on the way',
+    titleStyle:    { size: 16, weight: 'bold',    color: '#111827' },
+    subtitleStyle: { size: 14, weight: 'regular', color: '#6b7280' },
+    leadingIcon:  { symbol: 'shippingbox.fill', color: '#3b82f6' },
+    trailingIcon: { symbol: 'checkmark.seal.fill', color: '#10b981' }, // hidden until you set it
+    progress: {
+      style: 'bar-with-icon',  // 'bar' | 'bar-with-icon' | 'circular' | 'timer'
+      value: 0.6,
+      icon: 'car.fill',         // SF Symbol slides along the track
+      iconColor: '#3b82f6',
+      trackColor: '#e5e7eb',
+      fillColor: '#3b82f6',
+      label: '15 minutes away',
+    },
+  },
+});
+```
+
+Update it locally as state changes:
+
+```typescript
+await updateLiveActivity(activityId, {
+  title: 'Order #1234',
+  subtitle: 'Driver is two blocks away',
+  progress: { style: 'bar-with-icon', value: 0.9, icon: 'car.fill', fillColor: '#3b82f6' },
+});
+```
+
+Or update it remotely from your backend by calling `POST /api/push/live-activity` (see endpoint table below). The package automatically forwards the per-activity push token to SitePong on `startLiveActivity`, so backend updates reach the right device with no extra wiring.
+
+End the activity when the work completes:
+
+```typescript
+await endLiveActivity(activityId, {
+  finalContentState: {
+    title: 'Delivered',
+    leadingIcon: { symbol: 'checkmark.seal.fill', color: '#10b981' },
+  },
+  dismissalDate: Date.now() + 60_000, // remove from lock screen after 1 minute
+});
+```
+
+**Visibility-driven slots.** Every visual element in `contentState` is optional. The SwiftUI template hides slots whose value is omitted, so you control layout density entirely from data. Set `trailingIcon` only on the final "delivered" update and it appears; omit it everywhere else and it stays hidden.
+
+**Available styles.** Title and subtitle accept `size`, `weight` (`ultraLight`...`black`), `color` (hex), `italic`, `monospacedDigit`. Icons accept any SF Symbol name plus `color`, `weight`, `size`. Progress supports `bar`, `bar-with-icon` (the Uber-Eats-style sliding icon), `circular`, and `timer` (Apple's auto-updating countdown).
+
+**Bringing your own widget.** If you need a visually distinctive Live Activity beyond what the template covers, you can skip `@sitepong/expo-live-activity` and write the Widget Extension yourself in Swift, then call the lower-level token registration directly:
+
+```typescript
+import {
+  registerLiveActivityToken,
+  registerPushToStartToken,
+  endLiveActivity as endLiveActivityToken,
+} from 'sitepong/react-native';
+
+registerLiveActivityToken('MyActivityAttributes', activity.id, pushToken, { environment: 'production' });
+registerPushToStartToken('MyActivityAttributes', pushToStartToken, { environment: 'production' });
+endLiveActivityToken('MyActivityAttributes', activity.id);
+```
+
+#### Token invalidation
+
+When APNs or FCM reports a token as invalid (app uninstalled, notifications disabled, token rotated), SitePong marks it inactive on the server side and stops sending. No client action needed. To force a refresh after an OS-level token change, call `registerDeviceToken()` again with the new token.
+
+#### Endpoint reference
+
+| Method | Path | Auth | SDK function |
+|---|---|---|---|
+| POST | `/api/push/tokens` | `X-API-Key: sp_live_*` | `registerDeviceToken()` |
+| POST | `/api/push/live-activity-tokens` | `X-API-Key: sp_live_*` | `registerLiveActivityToken()` |
+| POST | `/api/push/push-to-start-tokens` | `X-API-Key: sp_live_*` | `registerPushToStartToken()` |
+| DELETE | `/api/push/live-activity-tokens` | `X-API-Key: sp_live_*` | `endLiveActivity()` |
+| POST | `/api/push/send` | `Authorization: Bearer sp_push_*` | (server-side only) |
+| POST | `/api/push/live-activity` | `Authorization: Bearer sp_push_*` | (server-side only) |
+
+Default ingest endpoint: `https://ingest.sitepong.com`. Override via the `endpoint` option in `initRN()` or `SitePongRNProvider`.
+
 ### Device Intelligence (React Native)
 
 Persistent device identification that **survives app reinstalls**. Requires the `@sitepong/device-id` native module.

package/dist/entries/rn.js

@@ -3160,7 +3160,20 @@ var RNPerformanceManager = class {
 };
 
 // src/react-native/push.ts
+var identifyHookInstalled = false;
+function ensureIdentifyHookInstalled() {
+  if (identifyHookInstalled) return;
+  identifyHookInstalled = true;
+  try {
+    const c = sitepong;
+    if (typeof c.registerIdentifyHook === "function") {
+      c.registerIdentifyHook(reRegisterTokensWithUserId);
+    }
+  } catch {
+  }
+}
 var cachedDeviceContext = null;
+var registeredPushToken = null;
 var registeredLiveActivityTokens = /* @__PURE__ */ new Map();
 var registeredPushToStartTokens = /* @__PURE__ */ new Map();
 function getEndpoint() {
@@ -3241,9 +3254,10 @@ async function deleteFromIngest(path, body) {
   }
 }
 function registerDeviceToken(token, options) {
+  ensureIdentifyHookInstalled();
   const device = getDeviceContext();
   const tokenType = options.platform === "ios" ? "apns" : "fcm";
-  ({ token, environment: options.environment });
+  registeredPushToken = { token, environment: options.environment };
   postToIngest("/api/push/tokens", {
     native_device_token: token,
     token_type: tokenType,
@@ -3257,6 +3271,7 @@ function registerDeviceToken(token, options) {
   });
 }
 function registerLiveActivityToken(activityType, activityId, pushToken, options) {
+  ensureIdentifyHookInstalled();
   const device = getDeviceContext();
   const userId = getUserId();
   const key = `${activityType}:${activityId}`;
@@ -3276,6 +3291,7 @@ function registerLiveActivityToken(activityType, activityId, pushToken, options)
   });
 }
 function registerPushToStartToken(activityType, pushToStartToken, options) {
+  ensureIdentifyHookInstalled();
   const device = getDeviceContext();
   const userId = getUserId();
   registeredPushToStartTokens.set(activityType, {
@@ -3299,6 +3315,42 @@ function endLiveActivity(activityType, activityId) {
     activity_id: activityId
   });
 }
+function reRegisterTokensWithUserId(userId) {
+  if (registeredPushToken) {
+    const device = getDeviceContext();
+    postToIngest("/api/push/tokens", {
+      expo_push_token: registeredPushToken.token,
+      environment: registeredPushToken.environment,
+      device_id: device.deviceId,
+      user_id: userId,
+      platform: device.platform,
+      app_version: device.appVersion,
+      device_model: device.deviceModel,
+      os_version: device.osVersion
+    });
+  }
+  for (const entry of registeredLiveActivityTokens.values()) {
+    const device = getDeviceContext();
+    postToIngest("/api/push/live-activity-tokens", {
+      activity_type: entry.activityType,
+      activity_id: entry.activityId,
+      push_token: entry.token,
+      environment: entry.environment,
+      device_id: device.deviceId,
+      user_id: userId
+    });
+  }
+  for (const entry of registeredPushToStartTokens.values()) {
+    const device = getDeviceContext();
+    postToIngest("/api/push/push-to-start-tokens", {
+      activity_type: entry.activityType,
+      push_to_start_token: entry.token,
+      environment: entry.environment,
+      device_id: device.deviceId,
+      user_id: userId
+    });
+  }
+}
 var SitePongRNContext = react.createContext({
   isInitialized: false,
   performanceManager: null