sitepong 0.1.12 → 0.2.0

package/README.md

@@ -602,7 +602,7 @@ Native APNs (iOS) and FCM (Android) push notifications, plus iOS Live Activity u
 
 #### 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.
+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 and binds tokens to authenticated users.
 
 ```
 [App launches]
@@ -611,15 +611,19 @@ There are two halves to push: the **client SDK** registers device tokens with th
    ↓
 [registerDeviceToken(token, opts)]           ← SDK POSTs to /api/push/tokens
    ↓                                            with X-API-Key: sp_live_xxx
-[Token stored in SitePong]
+[Token stored anonymously 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
+[User logs in with your backend]
+   ↓
+[Your backend → POST /api/push/tokens/associate]  ← sp_push_xxx + { token, user_id }
+   ↓
+[Your backend → POST /api/push/send]               ← sp_push_xxx + target user_ids
    ↓
 [SitePong → APNs / FCM → Device]
 ```
 
+> **Why two steps?** Publishable SDK keys (`sp_live_xxx`) are embedded in your app binary and can be extracted by anyone who decompiles the APK/IPA. If the client controlled `user_id`, a leaked SDK key would let an attacker register their own device under your users' IDs and silently receive their push notifications (password resets, OTP codes, order details). User attribution therefore only happens server-to-server with the privileged `sp_push_xxx` key — which stays on your backend.
+
 #### 1. Install permission and get the native token
 
 ```bash
@@ -649,26 +653,25 @@ 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.
+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`, `platform`, app version, device model, and OS version — no `user_id`. The server upserts by `(project_id, token)` so re-registration is idempotent.
 
-#### 3. User identification (automatic)
+#### 3. Associate the token with a user (server-side)
 
-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';
+Once your own backend has authenticated the user, have it POST to SitePong's associate endpoint with your `sp_push_xxx` key. Your app should forward the push token to your backend as part of the login flow.
 
-// 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"
+```bash
+curl -X POST https://api.sitepong.com/api/push/tokens/associate \
+  -H "Authorization: Bearer sp_push_xxxxxxxxxxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{ "token": "<expo_or_native_token>", "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.
+On sign-out, POST the same endpoint with `"user_id": null` to clear the association. Because this call is server-authenticated, an attacker who has scraped the SDK key out of your app cannot impersonate a user.
+
+> The older pattern of passing `userId` to `registerDeviceToken()` or `pushUserId` to `SitePongRNProvider` still type-checks for backwards compatibility, but the values are silently ignored on both the client and the server. Migrate to the associate endpoint.
 
 #### 4. Send notifications from your backend
 
@@ -794,6 +797,7 @@ When APNs or FCM reports a token as invalid (app uninstalled, notifications disa
 | 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/tokens/associate` | `Authorization: Bearer sp_push_*` | (server-side only) |
 | POST | `/api/push/send` | `Authorization: Bearer sp_push_*` | (server-side only) |
 | POST | `/api/push/live-activity` | `Authorization: Bearer sp_push_*` | (server-side only) |