:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(workflows): report each failed row in the push token batch api (#129104)
Daniel Marchuk4de68a252127
diff --git a/posthog/api/integration.py b/posthog/api/integration.pyindex c5b59fa62202..a470bd3f0b0f 100644--- a/posthog/api/integration.py+++ b/posthog/api/integration.py@@ -1710,6 +1710,12 @@ class IntegrationViewSet(return [*base_permissions, TeamMemberLightManagementPermission()]raise NotImplementedError()+ def dangerously_get_required_scopes(self, request: Request, view: Any) -> list[str] | None:+ # Importing devices writes person properties and tells which distinct IDs have a person.+ if self.action == "push_tokens":+ return ["integration:write", "person:write"]+ return None+def get_throttles(self):if self.action == "refresh_github_repos":return [GitHubRepositoryRefreshThrottle(), *super().get_throttles()]@@ -2864,17 +2870,35 @@ class IntegrationViewSet(},summary="Import push device tokens",description="Register existing device tokens, for example exported from another provider, on this push "- "channel. Each token is stored encrypted on its person, as the mobile SDK stores it.",+ "channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no "+ "person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for "+ "the channel. Send dry_run first to see every failure without storing anything.",)@action(methods=["POST"], detail=True, url_path="push_tokens")def push_tokens(self, request: ValidatedRequest, **kwargs) -> Response:+ # Session users skip API scopes, and access control checks only the integration scope_object.+ if not self.user_access_control.check_access_level_for_resource("person", "editor"):+ raise PermissionDenied("You need edit access to persons to import push devices.")integration = self.get_object()if not push_channel_app_id(integration):raise ValidationError("Device tokens can only be imported into an APNs or Firebase push channel.")- result = import_push_tokens(integration, request.validated_data["subscriptions"], integration.team.api_token)+ data = request.validated_data+ result = import_push_tokens(+ integration,+ data["subscriptions"],+ integration.team.api_token,+ dry_run=data["dry_run"],+ create_missing_persons=data["create_missing_persons"],+ import_id=data["import_id"],+ )return Response(PushTokenImportResponseSerializer(- {"imported": result.imported, "failed_distinct_ids": result.failed_distinct_ids}+ {+ "imported": result.imported,+ "dry_run": result.dry_run,+ "failed": result.failed,+ "failed_distinct_ids": result.failed_distinct_ids,+ }).data)diff --git a/posthog/api/integration_push_tokens.py b/posthog/api/integration_push_tokens.pyindex 0be13bf69d7d..26626ff43e88 100644--- a/posthog/api/integration_push_tokens.py+++ b/posthog/api/integration_push_tokens.py@@ -1,5 +1,9 @@+import reimport uuidimport hashlib+from datetime import datetime++from django.db import modelsfrom rest_framework import serializers@@ -7,18 +11,46 @@ from posthog.api.capture import capture_batch_internalfrom posthog.dataclasses import frozenfrom posthog.helpers.encrypted_fields import EncryptedFieldMixinfrom posthog.integrations import IntegrationRecord+from posthog.models.person.util import get_person_uuids_and_matched_distinct_idsDEVICE_SUBSCRIPTION_PREFIX = "$device_push_subscription_"MAX_SUBSCRIPTIONS_PER_REQUEST = 1000+# Capture rejects a longer distinct ID, and it counts bytes, not characters.+MAX_DISTINCT_ID_BYTES = 200EVENT_SOURCE = "push_token_import"+TOKEN_SUFFIX_LENGTH = 6++# Expo tokens address Expo's own push service, so neither APNs nor FCM accepts them.+_EXPO_TOKEN = re.compile(r"^Expo(nent)?PushToken\[.*\]$")+# The iOS SDK hex-encodes the APNs device token. Apple documents the token as variable length,+# so an APNs channel only checks the alphabet.+_HEX_TOKEN = re.compile(r"^(?:[0-9a-fA-F]{2})+$")+_APNS_TOKEN_MIN_HEX_LENGTH = 64+++class PushTokenImportFailureReason(models.TextChoices):+ UNKNOWN_PERSON = "unknown_person", "No person has this distinct ID"+ TOKEN_MISMATCH = "token_mismatch", "The token does not fit this channel"+ NOT_STORED = "not_stored", "The device was not stored"+ PERSON_PROCESSING_DISABLED = "person_processing_disabled", "Person processing is off for this person"class PushTokenSubscriptionSerializer(serializers.Serializer):- distinct_id = serializers.CharField(max_length=200, help_text="The person's distinct ID in this project.")+ distinct_id = serializers.CharField(+ max_length=200,+ help_text="The person's distinct ID in this project: the ID your app passes to `identify`.",+ )device_token = serializers.CharField(- max_length=4096, help_text="The APNs device token or FCM registration token of one device."+ max_length=4096,+ help_text="The token of one device. An APNs channel takes the hex APNs device token. "+ "A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.",)+ def validate_distinct_id(self, value: str) -> str:+ if len(value.encode()) > MAX_DISTINCT_ID_BYTES:+ raise serializers.ValidationError(f"Distinct ID is longer than {MAX_DISTINCT_ID_BYTES} bytes.")+ return value+class PushTokenImportRequestSerializer(serializers.Serializer):subscriptions: serializers.ListSerializer = serializers.ListSerializer(@@ -28,20 +60,71 @@ class PushTokenImportRequestSerializer(serializers.Serializer):help_text=f"Up to {MAX_SUBSCRIPTIONS_PER_REQUEST} devices to register on this push channel. ""List a person once per device.",)+ dry_run = serializers.BooleanField(+ default=False,+ help_text="Check every row and report what would fail, without storing anything. "+ "Run this first and fix the failed rows before importing.",+ )+ import_id = serializers.UUIDField(+ required=False,+ allow_null=True,+ default=None,+ help_text="A new UUID for each batch. Send the same value when you retry that batch, "+ "so a retried batch can be recognized as a repeat.",+ )+ create_missing_persons = serializers.BooleanField(+ default=False,+ help_text="Create a person for a distinct ID that has none. Off by default, because a distinct ID "+ "that does not match your app's identify call creates a person that never gets a push.",+ )+++class PushTokenImportFailureSerializer(serializers.Serializer):+ index = serializers.IntegerField(help_text="Position of the row in the request's `subscriptions`, from 0.")+ distinct_id = serializers.CharField(help_text="The distinct ID of the row.")+ device_token_suffix = serializers.CharField(+ help_text=f"The last {TOKEN_SUFFIX_LENGTH} characters of the row's device token, to find the row."+ )+ reason = serializers.ChoiceField(+ choices=PushTokenImportFailureReason.choices,+ help_text="Why the device was not stored. `unknown_person`: no person has this distinct ID, so check "+ "the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, "+ "for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and "+ "`person_processing_disabled`: ingestion did not store the device.",+ )+ detail = serializers.CharField(help_text="A sentence a person can act on.")class PushTokenImportResponseSerializer(serializers.Serializer):- imported = serializers.IntegerField(help_text="Number of devices stored on their person.")+ imported = serializers.IntegerField(+ help_text="Number of devices stored on their person. On a dry run, the number that would be stored."+ )+ dry_run = serializers.BooleanField(help_text="True when nothing was stored.")+ failed = PushTokenImportFailureSerializer(many=True, help_text="One entry per device that was not stored.")failed_distinct_ids = serializers.ListField(child=serializers.CharField(),- help_text="Distinct IDs with at least one device that was not stored. Send those rows again.",+ help_text="Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why.",)+@frozen+class PushTokenImportFailure:+ index: int+ distinct_id: str+ device_token_suffix: str+ reason: PushTokenImportFailureReason+ detail: str++@frozenclass PushTokenImportResult:imported: int- failed_distinct_ids: list[str]+ dry_run: bool+ failed: list[PushTokenImportFailure]++ @property+ def failed_distinct_ids(self) -> list[str]:+ return sorted({failure.distinct_id for failure in self.failed})class _TokenCipher(EncryptedFieldMixin):@@ -62,24 +145,84 @@ def device_subscription_key(app_id: str, device_token: str) -> str:return f"{DEVICE_SUBSCRIPTION_PREFIX}{app_id}:{digest}"+def token_mismatch(kind: str, device_token: str) -> str | None:+ """Says why a token cannot work on this kind of channel. Rejects only shapes that cannot fit."""+ if _EXPO_TOKEN.match(device_token):+ return "This is an Expo push token. Import the device's APNs or FCM token instead."+ is_hex = bool(_HEX_TOKEN.match(device_token))+ if kind == "apns" and not is_hex:+ return "An APNs channel needs the hex APNs device token. This looks like an FCM or other token."+ if kind == "firebase" and is_hex and len(device_token) >= _APNS_TOKEN_MIN_HEX_LENGTH:+ return "This looks like an APNs device token. Import it into an APNs channel instead."+ return None++def import_push_tokens(- integration: IntegrationRecord, subscriptions: list[dict[str, str]], team_api_token: str+ integration: IntegrationRecord,+ subscriptions: list[dict[str, str]],+ team_api_token: str,+ *,+ dry_run: bool = False,+ create_missing_persons: bool = False,+ import_id: uuid.UUID | None = None,+ timestamp: datetime | None = None,) -> PushTokenImportResult:app_id = push_channel_app_id(integration)if not app_id:raise ValueError("This integration is not a push channel.")+ failed: list[PushTokenImportFailure] = []++ def fail(row: tuple[int, str, str], reason: PushTokenImportFailureReason, detail: str) -> None:+ _, distinct_id, device_token = row+ for index in indexes_by_device[(distinct_id, device_token)]:+ failed.append(+ PushTokenImportFailure(+ index=index,+ distinct_id=distinct_id,+ device_token_suffix=device_token[-TOKEN_SUFFIX_LENGTH:],+ reason=reason,+ detail=detail,+ )+ )++ rows: list[tuple[int, str, str]] = []+ indexes_by_device: dict[tuple[str, str], list[int]] = {}+ for index, subscription in enumerate(subscriptions):+ key = (subscription["distinct_id"], subscription["device_token"])+ if key in indexes_by_device:+ indexes_by_device[key].append(index)+ continue+ indexes_by_device[key] = [index]+ row = (index, *key)+ if mismatch := token_mismatch(integration.kind, row[2]):+ fail(row, PushTokenImportFailureReason.TOKEN_MISMATCH, mismatch)+ else:+ rows.append(row)++ if rows and not create_missing_persons:+ _, known = get_person_uuids_and_matched_distinct_ids(integration.team_id, sorted({d for _, d, _ in rows}))+ for row in rows:+ if row[1] not in known:+ fail(+ row,+ PushTokenImportFailureReason.UNKNOWN_PERSON,+ "No person has this distinct ID. Use the ID your app passes to identify, "+ "or import with create_missing_persons.",+ )+ rows = [row for row in rows if row[1] in known]++ if dry_run or not rows:+ return PushTokenImportResult(imported=len(rows), dry_run=dry_run, failed=failed)+cipher = _TokenCipher()events = []- distinct_id_by_uuid: dict[str, str] = {}- seen: set[tuple[str, str]] = set()- for subscription in subscriptions:- distinct_id, device_token = subscription["distinct_id"], subscription["device_token"]- if (distinct_id, device_token) in seen:- continue- seen.add((distinct_id, device_token))- event_uuid = str(uuid.uuid4())- distinct_id_by_uuid[event_uuid] = distinct_id+ row_by_uuid: dict[str, tuple[int, str, str]] = {}+ for row in rows:+ _, distinct_id, device_token = row+ # A retried batch reuses its event IDs, so its copies can be deduplicated.+ event_uuid = str(uuid.uuid5(import_id, f"{distinct_id}\n{device_token}") if import_id else uuid.uuid4())+ row_by_uuid[event_uuid] = rowevents.append({"event": "$set",@@ -88,6 +231,8 @@ def import_push_tokens(# Encrypted, because the sender ignores a token it cannot decrypt as forged."properties": {"$set": {device_subscription_key(app_id, device_token): cipher.encrypt(device_token)}},"options": {"process_person_profile": True},+ # A retried batch reuses its timestamp too, because deduplication compares it with the event ID.+ **({"timestamp": timestamp} if timestamp else {}),})@@ -98,13 +243,26 @@ def import_push_tokens(process_person_profile=True,)# Capture skips the person update when person processing is disabled, so that device was never stored.- skipped = {+ skipped = [event_uuidfor event_uuid in result.warningsif result.results.get(event_uuid, {}).get("details") == "person_processing_disabled"- }- failed = {*result.dropped, *result.retried, *result.unaccounted, *skipped}- return PushTokenImportResult(- imported=len(events) - len(failed),- failed_distinct_ids=sorted({distinct_id_by_uuid[event_uuid] for event_uuid in failed}),- )+ ]+ not_stored = [+ event_uuid+ for event_uuid in (*result.dropped, *result.retried, *result.unaccounted)+ if event_uuid not in skipped+ ]+ for event_uuid in skipped:+ fail(+ row_by_uuid[event_uuid],+ PushTokenImportFailureReason.PERSON_PROCESSING_DISABLED,+ "Person processing is off for this person, so the device was not stored.",+ )+ for event_uuid in not_stored:+ fail(+ row_by_uuid[event_uuid],+ PushTokenImportFailureReason.NOT_STORED,+ "Ingestion did not store this device. Send the row again.",+ )+ return PushTokenImportResult(imported=len(events) - len(skipped) - len(not_stored), dry_run=False, failed=failed)diff --git a/posthog/api/test/test_integration_push_tokens.py b/posthog/api/test/test_integration_push_tokens.pyindex e01a0f3f6aa4..16511fe264b6 100644--- a/posthog/api/test/test_integration_push_tokens.py+++ b/posthog/api/test/test_integration_push_tokens.py@@ -1,6 +1,6 @@from typing import Any-from posthog.test.base import APIBaseTest+from posthog.test.base import APIBaseTest, _create_person, flush_persons_and_eventsfrom unittest.mock import patchfrom parameterized import parameterized@@ -10,7 +10,9 @@ from posthog.api.capture import CaptureInternalResultfrom posthog.api.integration_push_tokens import MAX_SUBSCRIPTIONS_PER_REQUEST, _TokenCipherfrom posthog.models.integration import Integrationfrom posthog.models.organization import Organization, OrganizationMembership+from posthog.models.personal_api_key import PersonalAPIKeyfrom posthog.models.team import Team+from posthog.models.utils import generate_random_token_personal, hash_key_valuedef _capture_dropping(dropped_distinct_ids: set[str], warning_details: dict[str, str] | None = None):@@ -49,15 +51,18 @@ class TestPushTokenImport(APIBaseTest):config={"project_id": "example-project"},)- def _import(self, integration_id: int, subscriptions: list[dict[str, str]]):+ def _import(self, integration_id: int, subscriptions: list[dict[str, str]], **options: Any):return self.client.post(f"/api/environments/{self.team.pk}/integrations/{integration_id}/push_tokens/",- {"subscriptions": subscriptions},+ {"subscriptions": subscriptions, **options},format="json",)@parameterized.expand([("apns", "com.example.app"), ("firebase", "example-project")])def test_stores_each_device_encrypted_under_the_key_the_sender_reads(self, kind: str, app_id: str) -> None:+ for distinct_id in ["user-1", "user-2", "user-3", "user-4"]:+ _create_person(team=self.team, distinct_ids=[distinct_id])+ flush_persons_and_events()capture, captured = _capture_dropping({"user-2"}, {"user-3": "person_processing_disabled", "user-4": "some_other_warning"})@@ -67,15 +72,35 @@ class TestPushTokenImport(APIBaseTest):[{"distinct_id": "user-1", "device_token": "a1b2c3d4"},{"distinct_id": "user-1", "device_token": "a1b2c3d4"},- {"distinct_id": "user-1", "device_token": "second-device"},- {"distinct_id": "user-2", "device_token": "dropped-device"},- {"distinct_id": "user-3", "device_token": "skipped-device"},- {"distinct_id": "user-4", "device_token": "warned-device"},+ {"distinct_id": "user-1", "device_token": "b2c3d4e5"},+ {"distinct_id": "user-2", "device_token": "c3d4e5f6"},+ {"distinct_id": "user-3", "device_token": "d4e5f6a7"},+ {"distinct_id": "user-4", "device_token": "e5f6a7b8"},],)assert response.status_code == status.HTTP_200_OK, response.json()- assert response.json() == {"imported": 3, "failed_distinct_ids": ["user-2", "user-3"]}+ assert response.json() == {+ "imported": 3,+ "dry_run": False,+ "failed": [+ {+ "index": 4,+ "distinct_id": "user-3",+ "device_token_suffix": "e5f6a7",+ "reason": "person_processing_disabled",+ "detail": "Person processing is off for this person, so the device was not stored.",+ },+ {+ "index": 3,+ "distinct_id": "user-2",+ "device_token_suffix": "d4e5f6",+ "reason": "not_stored",+ "detail": "Ingestion did not store this device. Send the row again.",+ },+ ],+ "failed_distinct_ids": ["user-2", "user-3"],+ }[call] = capturedassert call["token"] == self.team.api_tokenassert call["process_person_profile"] is True@@ -89,6 +114,84 @@ class TestPushTokenImport(APIBaseTest):assert _TokenCipher().decrypt(value) == "a1b2c3d4"assert len(call["events"]) == 5+ def test_a_retried_batch_reuses_its_event_ids(self) -> None:+ _create_person(team=self.team, distinct_ids=["user-1"])+ flush_persons_and_events()+ capture, captured = _capture_dropping(set())+ subscriptions = [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}]+ with patch("posthog.api.integration_push_tokens.capture_batch_internal", side_effect=capture):+ for import_id in [+ None,+ None,+ "8f1a6f0e-2f4c-4b8e-9d55-3f0a3c2b1e10",+ "8f1a6f0e-2f4c-4b8e-9d55-3f0a3c2b1e10",+ ]:+ options = {"import_id": import_id} if import_id else {}+ assert self._import(self.apns.id, subscriptions, **options).status_code == status.HTTP_200_OK++ no_id_first, no_id_retry, first, retry = [call["events"][0]["event_uuid"] for call in captured]+ assert no_id_first != no_id_retry+ assert first == retry++ @parameterized.expand(+ [+ ("expo_on_apns", "apns", "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"),+ ("expo_on_firebase", "firebase", "ExpoPushToken[xxxxxxxxxxxxxxxxxxxxxx]"),+ ("fcm_on_apns", "apns", "cK9dE2fGhIj:APA91bHqL0xYzExampleFcmRegistrationToken_-"),+ ("apns_on_firebase", "firebase", "ab" * 32),+ ]+ )+ def test_reports_a_token_of_the_wrong_kind(self, _name: str, kind: str, device_token: str) -> None:+ _create_person(team=self.team, distinct_ids=["user-1"])+ flush_persons_and_events()+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:+ response = self._import(getattr(self, kind).id, [{"distinct_id": "user-1", "device_token": device_token}])+ assert response.status_code == status.HTTP_200_OK, response.json()+ assert response.json()["imported"] == 0+ assert [f["reason"] for f in response.json()["failed"]] == ["token_mismatch"]+ capture.assert_not_called()++ @parameterized.expand(+ [+ ("rejected_by_default", {}, 1, ["unknown_person"]),+ ("dry_run_reports_without_storing", {"dry_run": True}, 1, ["unknown_person"]),+ ("created_when_asked", {"create_missing_persons": True}, 2, []),+ ]+ )+ def test_a_distinct_id_with_no_person(+ self, _name: str, options: dict[str, bool], imported: int, reasons: list[str]+ ) -> None:+ _create_person(team=self.team, distinct_ids=["known"])+ flush_persons_and_events()+ capture, captured = _capture_dropping(set())+ with patch("posthog.api.integration_push_tokens.capture_batch_internal", side_effect=capture):+ response = self._import(+ self.apns.id,+ [+ {"distinct_id": "known", "device_token": "a1b2c3d4"},+ {"distinct_id": "from-other-platform", "device_token": "b2c3d4e5"},+ ],+ **options,+ )+ assert response.status_code == status.HTTP_200_OK, response.json()+ assert response.json()["imported"] == imported+ assert [f["reason"] for f in response.json()["failed"]] == reasons+ stored = [event["distinct_id"] for call in captured for event in call["events"]]+ assert stored == ([] if options.get("dry_run") else ["known", "from-other-platform"][:imported])++ def test_a_repeated_row_reports_each_of_its_indexes(self) -> None:+ response = self._import(+ self.apns.id,+ [+ {"distinct_id": "nobody", "device_token": "a1b2c3d4"},+ {"distinct_id": "nobody", "device_token": "a1b2c3d4"},+ ],+ dry_run=True,+ )++ assert response.status_code == status.HTTP_200_OK, response.json()+ assert [failure["index"] for failure in response.json()["failed"]] == [0, 1]+def test_rejects_an_integration_that_is_not_a_push_channel(self) -> None:slack = Integration.objects.create(team=self.team, kind="slack", integration_id="T1", config={})with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:@@ -96,6 +199,26 @@ class TestPushTokenImport(APIBaseTest):assert response.status_code == status.HTTP_400_BAD_REQUESTcapture.assert_not_called()+ @parameterized.expand(+ [+ ("integration_only", ["integration:write"], status.HTTP_403_FORBIDDEN),+ ("with_person_write", ["integration:write", "person:write"], status.HTTP_200_OK),+ ]+ )+ def test_an_api_key_needs_person_write_to_import(self, _name: str, scopes: list[str], expected: int) -> None:+ token = generate_random_token_personal()+ PersonalAPIKey.objects.create(label="t", user=self.user, secure_value=hash_key_value(token), scopes=scopes)+ self.client.logout()+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:+ response = self.client.post(+ f"/api/environments/{self.team.pk}/integrations/{self.apns.id}/push_tokens/",+ {"subscriptions": [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}], "dry_run": True},+ format="json",+ HTTP_AUTHORIZATION=f"Bearer {token}",+ )+ assert response.status_code == expected, response.json()+ capture.assert_not_called()+def test_cannot_import_into_another_teams_channel(self) -> None:other_team = Team.objects.create(organization=Organization.objects.create(name="other"))other_apns = Integration.objects.create(@@ -112,6 +235,7 @@ class TestPushTokenImport(APIBaseTest):("too_many", [{"distinct_id": "u", "device_token": "t"}] * (MAX_SUBSCRIPTIONS_PER_REQUEST + 1)),("missing_token", [{"distinct_id": "u"}]),("blank_distinct_id", [{"distinct_id": "", "device_token": "t"}]),+ ("distinct_id_over_the_byte_limit", [{"distinct_id": "🎉" * 51, "device_token": "t"}]),])def test_rejects_invalid_rows_without_capturing(self, _name: str, subscriptions: list[dict[str, str]]) -> None:diff --git a/products/integrations/frontend/generated/api.schemas.ts b/products/integrations/frontend/generated/api.schemas.tsindex 485886477f1f..175648f73655 100644--- a/products/integrations/frontend/generated/api.schemas.ts+++ b/products/integrations/frontend/generated/api.schemas.ts@@ -856,12 +856,12 @@ export interface LinearTeamsResponseApi {export interface PushTokenSubscriptionApi {/**- * The person's distinct ID in this project.+ * The person's distinct ID in this project: the ID your app passes to `identify`.* @maxLength 200*/distinct_id: string/**- * The APNs device token or FCM registration token of one device.+ * The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.* @maxLength 4096*/device_token: string@@ -870,12 +870,59 @@ export interface PushTokenSubscriptionApi {export interface PushTokenImportRequestApi {/** Up to 1000 devices to register on this push channel. List a person once per device. */subscriptions: PushTokenSubscriptionApi[]+ /** Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing. */+ dry_run?: boolean+ /**+ * A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.+ * @nullable+ */+ import_id?: string | null+ /** Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push. */+ create_missing_persons?: boolean+}++/**+ * * `unknown_person` - No person has this distinct ID+ * * `token_mismatch` - The token does not fit this channel+ * * `not_stored` - The device was not stored+ * * `person_processing_disabled` - Person processing is off for this person+ */+export type PushTokenImportFailureReasonEnumApi =+ (typeof PushTokenImportFailureReasonEnumApi)[keyof typeof PushTokenImportFailureReasonEnumApi]++export const PushTokenImportFailureReasonEnumApi = {+ UnknownPerson: 'unknown_person',+ TokenMismatch: 'token_mismatch',+ NotStored: 'not_stored',+ PersonProcessingDisabled: 'person_processing_disabled',+} as const++export interface PushTokenImportFailureApi {+ /** Position of the row in the request's `subscriptions`, from 0. */+ index: number+ /** The distinct ID of the row. */+ distinct_id: string+ /** The last 6 characters of the row's device token, to find the row. */+ device_token_suffix: string+ /** Why the device was not stored. `unknown_person`: no person has this distinct ID, so check the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and `person_processing_disabled`: ingestion did not store the device.+ *+ * * `unknown_person` - No person has this distinct ID+ * * `token_mismatch` - The token does not fit this channel+ * * `not_stored` - The device was not stored+ * * `person_processing_disabled` - Person processing is off for this person */+ reason: PushTokenImportFailureReasonEnumApi+ /** A sentence a person can act on. */+ detail: string}export interface PushTokenImportResponseApi {- /** Number of devices stored on their person. */+ /** Number of devices stored on their person. On a dry run, the number that would be stored. */imported: number- /** Distinct IDs with at least one device that was not stored. Send those rows again. */+ /** True when nothing was stored. */+ dry_run: boolean+ /** One entry per device that was not stored. */+ failed: PushTokenImportFailureApi[]+ /** Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why. */failed_distinct_ids: string[]}diff --git a/products/integrations/frontend/generated/api.ts b/products/integrations/frontend/generated/api.tsindex 8592d340a2a0..9a583848a918 100644--- a/products/integrations/frontend/generated/api.ts+++ b/products/integrations/frontend/generated/api.ts@@ -840,7 +840,7 @@ export const getIntegrationsPushTokensCreateUrl = (projectId: string, id: number}/**- * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for the channel. Send dry_run first to see every failure without storing anything.* @summary Import push device tokens*/export const integrationsPushTokensCreate = async (diff --git a/products/integrations/frontend/generated/api.zod.ts b/products/integrations/frontend/generated/api.zod.tsindex d8aa94c806d0..4c7ba46ec01a 100644--- a/products/integrations/frontend/generated/api.zod.ts+++ b/products/integrations/frontend/generated/api.zod.ts@@ -139,13 +139,16 @@ export const IntegrationsEmailPartialUpdateBody = /* @__PURE__ */ zod.describe('Standard Integration serializer.')/**- * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for the channel. Send dry_run first to see every failure without storing anything.* @summary Import push device tokens*/export const integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax = 200export const integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax = 4096+export const integrationsPushTokensCreateBodyDryRunDefault = false+export const integrationsPushTokensCreateBodyCreateMissingPersonsDefault = false+export const IntegrationsPushTokensCreateBody = /* @__PURE__ */ zod.object({subscriptions: zod.array(@@ -153,14 +156,34 @@ export const IntegrationsPushTokensCreateBody = /* @__PURE__ */ zod.object({distinct_id: zod.string().max(integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax)- .describe("The person's distinct ID in this project."),+ .describe("The person's distinct ID in this project: the ID your app passes to `identify`."),device_token: zod.string().max(integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax)- .describe('The APNs device token or FCM registration token of one device.'),+ .describe(+ 'The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.'+ ),})).describe('Up to 1000 devices to register on this push channel. List a person once per device.'),+ dry_run: zod+ .boolean()+ .default(integrationsPushTokensCreateBodyDryRunDefault)+ .describe(+ 'Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing.'+ ),+ import_id: zod+ .uuid()+ .nullish()+ .describe(+ 'A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.'+ ),+ create_missing_persons: zod+ .boolean()+ .default(integrationsPushTokensCreateBodyCreateMissingPersonsDefault)+ .describe(+ "Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push."+ ),})/**diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 6c020a0cbfd7..1943ad85f308 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -93654,14 +93654,48 @@ export namespace Schemas {pins: PulsePin[];}+ /**+ * * `unknown_person` - No person has this distinct ID+ * * `token_mismatch` - The token does not fit this channel+ * * `not_stored` - The device was not stored+ * * `person_processing_disabled` - Person processing is off for this person+ */+ export type PushTokenImportFailureReasonEnum = typeof PushTokenImportFailureReasonEnum[keyof typeof PushTokenImportFailureReasonEnum];+++ export const PushTokenImportFailureReasonEnum = {+ UnknownPerson: 'unknown_person',+ TokenMismatch: 'token_mismatch',+ NotStored: 'not_stored',+ PersonProcessingDisabled: 'person_processing_disabled',+ } as const;++ export interface PushTokenImportFailure {+ /** Position of the row in the request's `subscriptions`, from 0. */+ index: number;+ /** The distinct ID of the row. */+ distinct_id: string;+ /** The last 6 characters of the row's device token, to find the row. */+ device_token_suffix: string;+ /** Why the device was not stored. `unknown_person`: no person has this distinct ID, so check the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and `person_processing_disabled`: ingestion did not store the device.+ *+ * * `unknown_person` - No person has this distinct ID+ * * `token_mismatch` - The token does not fit this channel+ * * `not_stored` - The device was not stored+ * * `person_processing_disabled` - Person processing is off for this person */+ reason: PushTokenImportFailureReasonEnum;+ /** A sentence a person can act on. */+ detail: string;+ }+export interface PushTokenSubscription {/**- * The person's distinct ID in this project.+ * The person's distinct ID in this project: the ID your app passes to `identify`.* @maxLength 200*/distinct_id: string;/**- * The APNs device token or FCM registration token of one device.+ * The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.* @maxLength 4096*/device_token: string;@@ -93670,12 +93704,25 @@ export namespace Schemas {export interface PushTokenImportRequest {/** Up to 1000 devices to register on this push channel. List a person once per device. */subscriptions: PushTokenSubscription[];+ /** Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing. */+ dry_run?: boolean;+ /**+ * A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.+ * @nullable+ */+ import_id?: string | null;+ /** Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push. */+ create_missing_persons?: boolean;}export interface PushTokenImportResponse {- /** Number of devices stored on their person. */+ /** Number of devices stored on their person. On a dry run, the number that would be stored. */imported: number;- /** Distinct IDs with at least one device that was not stored. Send those rows again. */+ /** True when nothing was stored. */+ dry_run: boolean;+ /** One entry per device that was not stored. */+ failed: PushTokenImportFailure[];+ /** Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why. */failed_distinct_ids: string[];}