@fishonfire/bubbles-expo 0.1.0 → 0.1.1

package/README.md

@@ -162,10 +162,25 @@ export function EnableNotificationsButton() {
 }
 ```
 
-`useBubblesNotifications()` also exposes `deviceId`, `pushToken`, `permissionStatus`, `notificationsEnabled`, `tokenType`, and `error`.
+`useBubblesNotifications()` also exposes `addDeviceAttribute`, `deviceId`, `pushToken`, `permissionStatus`, `notificationsEnabled`, `tokenType`, and `error`.
 
 If your app already requested notification permissions, call `registerDevice({ requestPermissions: false })`.
 
+## Add custom device attributes
+
+After the provider has a backend `deviceId`, apps can add their own device attributes:
+
+```tsx
+const { addDeviceAttribute, deviceId } = useBubblesNotifications();
+
+if (deviceId) {
+  void addDeviceAttribute('plan', {
+    tier: 'pro',
+    seats: 4,
+  });
+}
+```
+
 ## Example application
 A example application can be found at: https://github.com/fishonfire/bubbles-notifications-expo-example
 
@@ -177,4 +192,4 @@ A example application can be found at: https://github.com/fishonfire/bubbles-not
 ## Copyright and Licence
 Copyright (c) 2026, Fish on Fire.
 
-Source code is licensed under the [`GPL License`](https://github.com/fishonfire/bubbles-notifications-expo/blob/develop/LICENSE).
+Source code is licensed under the [`GPL License`](https://github.com/fishonfire/bubbles-notifications-expo/blob/develop/LICENSE).

package/dist/{chunk-6NPXFGQX.mjs → chunk-3BAGWXHY.mjs}

@@ -458,6 +458,78 @@ function throwAppAuthenticationError(error) {
   }
   throw error;
 }
+function normalizeDeviceAttributes(value) {
+  return normalizeDeviceAttributeObject(value, "attributes", /* @__PURE__ */ new WeakSet());
+}
+function normalizeDeviceAttributeValue(value, sourceDescription, seenValues) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      failWithBubblesError(`${sourceDescription} must be a finite number.`);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (seenValues.has(value)) {
+      failWithBubblesError(`${sourceDescription} must not contain cycles.`);
+    }
+    seenValues.add(value);
+    const normalizedValue = value.map(
+      (entry, index) => normalizeDeviceAttributeValue(
+        entry,
+        `${sourceDescription}[${index}]`,
+        seenValues
+      )
+    );
+    seenValues.delete(value);
+    return normalizedValue;
+  }
+  if (isPlainObject(value)) {
+    return normalizeDeviceAttributeObject(
+      value,
+      sourceDescription,
+      seenValues
+    );
+  }
+  failWithBubblesError(
+    `${sourceDescription} must be a JSON-compatible value.`
+  );
+}
+function normalizeDeviceAttributeObject(value, sourceDescription, seenValues) {
+  if (!isPlainObject(value)) {
+    failWithBubblesError('"attributes" must be an object.');
+  }
+  const valuePrototype = Object.getPrototypeOf(value);
+  if (valuePrototype !== Object.prototype && valuePrototype !== null) {
+    failWithBubblesError(
+      `${sourceDescription} must be a JSON-compatible object.`
+    );
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    failWithBubblesError(
+      `${sourceDescription} must not contain symbol keys.`
+    );
+  }
+  if (seenValues.has(value)) {
+    failWithBubblesError(`${sourceDescription} must not contain cycles.`);
+  }
+  seenValues.add(value);
+  const normalizedValue = {};
+  for (const [attributeName, attributeValue] of Object.entries(value)) {
+    normalizedValue[attributeName] = normalizeDeviceAttributeValue(
+      attributeValue,
+      `${sourceDescription}.${attributeName}`,
+      seenValues
+    );
+  }
+  seenValues.delete(value);
+  return normalizedValue;
+}
 function extractDeviceIdFromDeviceResponse(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return null;
@@ -497,6 +569,18 @@ async function updateBubblesDevice(options) {
     throwAppAuthenticationError(error);
   }
 }
+async function updateBubblesDeviceAttributes(options) {
+  const client = resolveDeviceClient(options);
+  try {
+    return await client.updateDeviceAttributes(
+      normalizeIdentifier(options.deviceId, "deviceId"),
+      normalizeDeviceAttributes(options.attributes),
+      withAppKeyHeader(options.appKey, options.requestOptions)
+    );
+  } catch (error) {
+    throwAppAuthenticationError(error);
+  }
+}
 async function syncBubblesDevice(options) {
   const client = resolveDeviceClient(options);
   if (options.deviceId !== null) {
@@ -1279,6 +1363,7 @@ export {
   extractDeviceIdFromDeviceResponse,
   createBubblesDevice,
   updateBubblesDevice,
+  updateBubblesDeviceAttributes,
   syncBubblesDevice,
   BUBBLES_DELIVERY_STATUSES,
   buildBubblesDeliveryStatusPayload,

package/dist/index.d.mts

@@ -93,10 +93,20 @@ interface SyncBubblesDeviceResult<TResponse = unknown> {
     deviceId: string | null;
     response: TResponse;
 }
+type BubblesDeviceAttributeValue = string | number | boolean | null | BubblesDeviceAttributeValue[] | {
+    [key: string]: BubblesDeviceAttributeValue;
+};
+type BubblesDeviceAttributes = Record<string, BubblesDeviceAttributeValue>;
+interface UpdateBubblesDeviceAttributesOptions extends BubblesDeviceClientInput {
+    deviceId: string | number;
+    attributes: BubblesDeviceAttributes;
+    requestOptions?: RequestOptions;
+}
 declare function createBubblesDeviceClient(options: BubblesDeviceClientOptions): DeviceClient;
 declare function extractDeviceIdFromDeviceResponse(value: unknown): string | null;
 declare function createBubblesDevice<TResponse = unknown>(options: CreateBubblesDeviceOptions): Promise<TResponse>;
 declare function updateBubblesDevice<TResponse = unknown>(options: UpdateBubblesDeviceOptions): Promise<TResponse>;
+declare function updateBubblesDeviceAttributes<TResponse = unknown>(options: UpdateBubblesDeviceAttributesOptions): Promise<TResponse>;
 declare function syncBubblesDevice<TResponse = unknown>(options: SyncBubblesDeviceOptions): Promise<SyncBubblesDeviceResult<TResponse>>;
 
 type DeviceClientFactoryOptions = Omit<DeviceClientOptions, 'baseUrl'>;
@@ -220,6 +230,8 @@ declare function getDeviceRegistrationState(options?: GetDeviceTokenOptions): Pr
 declare function getDeviceToken(options?: GetDeviceTokenOptions): Promise<DeviceTokenResult>;
 declare function getFCMToken(options?: GetDeviceTokenOptions): Promise<string>;
 
+declare function collectBubblesDeviceAttributes(): Promise<BubblesDeviceAttributes>;
+
 interface RegisterDeviceOptions {
     requestPermissions?: boolean;
     permissionRequestOptions?: PermissionRequestOptions;
@@ -256,6 +268,7 @@ interface BubblesNotificationsProviderProps {
 }
 interface BubblesNotificationsContextValue {
     registerDevice: (options?: RegisterDeviceOptions) => Promise<void>;
+    addDeviceAttribute: (name: string, value: BubblesDeviceAttributeValue) => Promise<void>;
     deviceId: string | null;
     pushToken: string | null;
     tokenType: NativeTokenType | null;
@@ -303,4 +316,4 @@ interface BubblesNotificationPayload {
     url: string | null;
 }
 
-export { ANDROID_CHANNEL_IMPORTANCE_VALUES, type AndroidChannelImportance, BUBBLES_DELIVERY_STATUSES, BUBBLES_NOTIFICATIONS_EXPO_EXTRA_KEY, BubblesAppAuthenticationError, type BubblesCreateDevicePayload, type BubblesDeliveryStatus, type BubblesDeliveryStatusPayload, type BubblesDevicePayload, type BubblesDevicePlatform, type BubblesForegroundNotificationPayloadContract, type BubblesNotificationDataContract, type BubblesNotificationPayload, type BubblesNotificationResponseEvent, type BubblesNotificationsContextValue, type BubblesNotificationsLogoutEvent, BubblesNotificationsProvider, type BubblesNotificationsProviderProps, type BubblesNotificationsRuntimeConfig, type BubblesSilentNotificationPayloadContract, type BubblesUpdateDevicePayload, type BubblesVisibleNotificationPayloadContract, type BuildBubblesCreateDevicePayloadOptions, type BuildBubblesDeliveryStatusPayloadOptions, type BuildBubblesDevicePayloadOptions, type CreateBubblesDeviceOptions, type CreateStoredDeliveryStatusEventOptions, type DefaultNotificationChannelConfig, type DeviceRegistrationState, type DeviceTokenResult, type EnsureDefaultNotificationChannelOptions, type ForegroundPresentationOptions, type GetDeviceTokenOptions, type GetNotificationPermissionsOptions, type NativeTokenType, type PermissionRequestOptions, type PostBubblesDeliveryStatusOptions, type PostStoredBubblesDeliveryStatusOptions, type RegisterDeviceOptions, type StoredDeliveryStatusEvent, type StoredDeliveryStatusLedger, type StoredDeviceState, type StoredDeviceStateUpdate, type SupportedPlatform, type SyncBubblesDeviceOptions, type SyncBubblesDeviceResult, type UpdateBubblesDeviceOptions, buildBubblesDeliveryStatusPayload, buildCreateDevicePayload, buildStoredDeliveryStatusEventKey, buildUpdateDevicePayload, createBubblesDevice, createBubblesDeviceClient, createStoredDeliveryStatusEvent, describeNotificationPermissionStatus, enqueueStoredDeliveryStatusEvent, ensureDefaultNotificationChannel, ensureNotificationPermissions, extractDeviceIdFromDeviceResponse, flushStoredBubblesDeliveryStatuses, getAndroidNotificationChannelImportance, getBubblesNotificationsRuntimeConfig, getDefaultNotificationChannelConfig, getDeviceRegistrationState, getDeviceToken, getFCMToken, getNotificationPermissions, isNotificationPermissionGranted, markStoredDeliveryStatusEventPosted, patchStoredDeviceState, postBubblesDeliveryStatus, postStoredBubblesDeliveryStatus, readStoredApiBaseUrl, readStoredAppKey, readStoredDeliveryStatusLedger, readStoredDeviceId, readStoredDeviceState, registerBubblesBackgroundHandlers, storeApiBaseUrl, storeAppKey, storeDeliveryStatusLedger, storeDeviceId, storeDeviceState, syncBubblesDevice, updateBubblesDevice, useBubblesNotifications };
+export { ANDROID_CHANNEL_IMPORTANCE_VALUES, type AndroidChannelImportance, BUBBLES_DELIVERY_STATUSES, BUBBLES_NOTIFICATIONS_EXPO_EXTRA_KEY, BubblesAppAuthenticationError, type BubblesCreateDevicePayload, type BubblesDeliveryStatus, type BubblesDeliveryStatusPayload, type BubblesDeviceAttributeValue, type BubblesDeviceAttributes, type BubblesDevicePayload, type BubblesDevicePlatform, type BubblesForegroundNotificationPayloadContract, type BubblesNotificationDataContract, type BubblesNotificationPayload, type BubblesNotificationResponseEvent, type BubblesNotificationsContextValue, type BubblesNotificationsLogoutEvent, BubblesNotificationsProvider, type BubblesNotificationsProviderProps, type BubblesNotificationsRuntimeConfig, type BubblesSilentNotificationPayloadContract, type BubblesUpdateDevicePayload, type BubblesVisibleNotificationPayloadContract, type BuildBubblesCreateDevicePayloadOptions, type BuildBubblesDeliveryStatusPayloadOptions, type BuildBubblesDevicePayloadOptions, type CreateBubblesDeviceOptions, type CreateStoredDeliveryStatusEventOptions, type DefaultNotificationChannelConfig, type DeviceRegistrationState, type DeviceTokenResult, type EnsureDefaultNotificationChannelOptions, type ForegroundPresentationOptions, type GetDeviceTokenOptions, type GetNotificationPermissionsOptions, type NativeTokenType, type PermissionRequestOptions, type PostBubblesDeliveryStatusOptions, type PostStoredBubblesDeliveryStatusOptions, type RegisterDeviceOptions, type StoredDeliveryStatusEvent, type StoredDeliveryStatusLedger, type StoredDeviceState, type StoredDeviceStateUpdate, type SupportedPlatform, type SyncBubblesDeviceOptions, type SyncBubblesDeviceResult, type UpdateBubblesDeviceAttributesOptions, type UpdateBubblesDeviceOptions, buildBubblesDeliveryStatusPayload, buildCreateDevicePayload, buildStoredDeliveryStatusEventKey, buildUpdateDevicePayload, collectBubblesDeviceAttributes, createBubblesDevice, createBubblesDeviceClient, createStoredDeliveryStatusEvent, describeNotificationPermissionStatus, enqueueStoredDeliveryStatusEvent, ensureDefaultNotificationChannel, ensureNotificationPermissions, extractDeviceIdFromDeviceResponse, flushStoredBubblesDeliveryStatuses, getAndroidNotificationChannelImportance, getBubblesNotificationsRuntimeConfig, getDefaultNotificationChannelConfig, getDeviceRegistrationState, getDeviceToken, getFCMToken, getNotificationPermissions, isNotificationPermissionGranted, markStoredDeliveryStatusEventPosted, patchStoredDeviceState, postBubblesDeliveryStatus, postStoredBubblesDeliveryStatus, readStoredApiBaseUrl, readStoredAppKey, readStoredDeliveryStatusLedger, readStoredDeviceId, readStoredDeviceState, registerBubblesBackgroundHandlers, storeApiBaseUrl, storeAppKey, storeDeliveryStatusLedger, storeDeviceId, storeDeviceState, syncBubblesDevice, updateBubblesDevice, updateBubblesDeviceAttributes, useBubblesNotifications };

package/dist/index.d.ts

@@ -93,10 +93,20 @@ interface SyncBubblesDeviceResult<TResponse = unknown> {
     deviceId: string | null;
     response: TResponse;
 }
+type BubblesDeviceAttributeValue = string | number | boolean | null | BubblesDeviceAttributeValue[] | {
+    [key: string]: BubblesDeviceAttributeValue;
+};
+type BubblesDeviceAttributes = Record<string, BubblesDeviceAttributeValue>;
+interface UpdateBubblesDeviceAttributesOptions extends BubblesDeviceClientInput {
+    deviceId: string | number;
+    attributes: BubblesDeviceAttributes;
+    requestOptions?: RequestOptions;
+}
 declare function createBubblesDeviceClient(options: BubblesDeviceClientOptions): DeviceClient;
 declare function extractDeviceIdFromDeviceResponse(value: unknown): string | null;
 declare function createBubblesDevice<TResponse = unknown>(options: CreateBubblesDeviceOptions): Promise<TResponse>;
 declare function updateBubblesDevice<TResponse = unknown>(options: UpdateBubblesDeviceOptions): Promise<TResponse>;
+declare function updateBubblesDeviceAttributes<TResponse = unknown>(options: UpdateBubblesDeviceAttributesOptions): Promise<TResponse>;
 declare function syncBubblesDevice<TResponse = unknown>(options: SyncBubblesDeviceOptions): Promise<SyncBubblesDeviceResult<TResponse>>;
 
 type DeviceClientFactoryOptions = Omit<DeviceClientOptions, 'baseUrl'>;
@@ -220,6 +230,8 @@ declare function getDeviceRegistrationState(options?: GetDeviceTokenOptions): Pr
 declare function getDeviceToken(options?: GetDeviceTokenOptions): Promise<DeviceTokenResult>;
 declare function getFCMToken(options?: GetDeviceTokenOptions): Promise<string>;
 
+declare function collectBubblesDeviceAttributes(): Promise<BubblesDeviceAttributes>;
+
 interface RegisterDeviceOptions {
     requestPermissions?: boolean;
     permissionRequestOptions?: PermissionRequestOptions;
@@ -256,6 +268,7 @@ interface BubblesNotificationsProviderProps {
 }
 interface BubblesNotificationsContextValue {
     registerDevice: (options?: RegisterDeviceOptions) => Promise<void>;
+    addDeviceAttribute: (name: string, value: BubblesDeviceAttributeValue) => Promise<void>;
     deviceId: string | null;
     pushToken: string | null;
     tokenType: NativeTokenType | null;
@@ -303,4 +316,4 @@ interface BubblesNotificationPayload {
     url: string | null;
 }
 
-export { ANDROID_CHANNEL_IMPORTANCE_VALUES, type AndroidChannelImportance, BUBBLES_DELIVERY_STATUSES, BUBBLES_NOTIFICATIONS_EXPO_EXTRA_KEY, BubblesAppAuthenticationError, type BubblesCreateDevicePayload, type BubblesDeliveryStatus, type BubblesDeliveryStatusPayload, type BubblesDevicePayload, type BubblesDevicePlatform, type BubblesForegroundNotificationPayloadContract, type BubblesNotificationDataContract, type BubblesNotificationPayload, type BubblesNotificationResponseEvent, type BubblesNotificationsContextValue, type BubblesNotificationsLogoutEvent, BubblesNotificationsProvider, type BubblesNotificationsProviderProps, type BubblesNotificationsRuntimeConfig, type BubblesSilentNotificationPayloadContract, type BubblesUpdateDevicePayload, type BubblesVisibleNotificationPayloadContract, type BuildBubblesCreateDevicePayloadOptions, type BuildBubblesDeliveryStatusPayloadOptions, type BuildBubblesDevicePayloadOptions, type CreateBubblesDeviceOptions, type CreateStoredDeliveryStatusEventOptions, type DefaultNotificationChannelConfig, type DeviceRegistrationState, type DeviceTokenResult, type EnsureDefaultNotificationChannelOptions, type ForegroundPresentationOptions, type GetDeviceTokenOptions, type GetNotificationPermissionsOptions, type NativeTokenType, type PermissionRequestOptions, type PostBubblesDeliveryStatusOptions, type PostStoredBubblesDeliveryStatusOptions, type RegisterDeviceOptions, type StoredDeliveryStatusEvent, type StoredDeliveryStatusLedger, type StoredDeviceState, type StoredDeviceStateUpdate, type SupportedPlatform, type SyncBubblesDeviceOptions, type SyncBubblesDeviceResult, type UpdateBubblesDeviceOptions, buildBubblesDeliveryStatusPayload, buildCreateDevicePayload, buildStoredDeliveryStatusEventKey, buildUpdateDevicePayload, createBubblesDevice, createBubblesDeviceClient, createStoredDeliveryStatusEvent, describeNotificationPermissionStatus, enqueueStoredDeliveryStatusEvent, ensureDefaultNotificationChannel, ensureNotificationPermissions, extractDeviceIdFromDeviceResponse, flushStoredBubblesDeliveryStatuses, getAndroidNotificationChannelImportance, getBubblesNotificationsRuntimeConfig, getDefaultNotificationChannelConfig, getDeviceRegistrationState, getDeviceToken, getFCMToken, getNotificationPermissions, isNotificationPermissionGranted, markStoredDeliveryStatusEventPosted, patchStoredDeviceState, postBubblesDeliveryStatus, postStoredBubblesDeliveryStatus, readStoredApiBaseUrl, readStoredAppKey, readStoredDeliveryStatusLedger, readStoredDeviceId, readStoredDeviceState, registerBubblesBackgroundHandlers, storeApiBaseUrl, storeAppKey, storeDeliveryStatusLedger, storeDeviceId, storeDeviceState, syncBubblesDevice, updateBubblesDevice, useBubblesNotifications };
+export { ANDROID_CHANNEL_IMPORTANCE_VALUES, type AndroidChannelImportance, BUBBLES_DELIVERY_STATUSES, BUBBLES_NOTIFICATIONS_EXPO_EXTRA_KEY, BubblesAppAuthenticationError, type BubblesCreateDevicePayload, type BubblesDeliveryStatus, type BubblesDeliveryStatusPayload, type BubblesDeviceAttributeValue, type BubblesDeviceAttributes, type BubblesDevicePayload, type BubblesDevicePlatform, type BubblesForegroundNotificationPayloadContract, type BubblesNotificationDataContract, type BubblesNotificationPayload, type BubblesNotificationResponseEvent, type BubblesNotificationsContextValue, type BubblesNotificationsLogoutEvent, BubblesNotificationsProvider, type BubblesNotificationsProviderProps, type BubblesNotificationsRuntimeConfig, type BubblesSilentNotificationPayloadContract, type BubblesUpdateDevicePayload, type BubblesVisibleNotificationPayloadContract, type BuildBubblesCreateDevicePayloadOptions, type BuildBubblesDeliveryStatusPayloadOptions, type BuildBubblesDevicePayloadOptions, type CreateBubblesDeviceOptions, type CreateStoredDeliveryStatusEventOptions, type DefaultNotificationChannelConfig, type DeviceRegistrationState, type DeviceTokenResult, type EnsureDefaultNotificationChannelOptions, type ForegroundPresentationOptions, type GetDeviceTokenOptions, type GetNotificationPermissionsOptions, type NativeTokenType, type PermissionRequestOptions, type PostBubblesDeliveryStatusOptions, type PostStoredBubblesDeliveryStatusOptions, type RegisterDeviceOptions, type StoredDeliveryStatusEvent, type StoredDeliveryStatusLedger, type StoredDeviceState, type StoredDeviceStateUpdate, type SupportedPlatform, type SyncBubblesDeviceOptions, type SyncBubblesDeviceResult, type UpdateBubblesDeviceAttributesOptions, type UpdateBubblesDeviceOptions, buildBubblesDeliveryStatusPayload, buildCreateDevicePayload, buildStoredDeliveryStatusEventKey, buildUpdateDevicePayload, collectBubblesDeviceAttributes, createBubblesDevice, createBubblesDeviceClient, createStoredDeliveryStatusEvent, describeNotificationPermissionStatus, enqueueStoredDeliveryStatusEvent, ensureDefaultNotificationChannel, ensureNotificationPermissions, extractDeviceIdFromDeviceResponse, flushStoredBubblesDeliveryStatuses, getAndroidNotificationChannelImportance, getBubblesNotificationsRuntimeConfig, getDefaultNotificationChannelConfig, getDeviceRegistrationState, getDeviceToken, getFCMToken, getNotificationPermissions, isNotificationPermissionGranted, markStoredDeliveryStatusEventPosted, patchStoredDeviceState, postBubblesDeliveryStatus, postStoredBubblesDeliveryStatus, readStoredApiBaseUrl, readStoredAppKey, readStoredDeliveryStatusLedger, readStoredDeviceId, readStoredDeviceState, registerBubblesBackgroundHandlers, storeApiBaseUrl, storeAppKey, storeDeliveryStatusLedger, storeDeviceId, storeDeviceState, syncBubblesDevice, updateBubblesDevice, updateBubblesDeviceAttributes, useBubblesNotifications };

package/dist/index.js

@@ -39,6 +39,7 @@ __export(index_exports, {
   buildCreateDevicePayload: () => buildCreateDevicePayload,
   buildStoredDeliveryStatusEventKey: () => buildStoredDeliveryStatusEventKey,
   buildUpdateDevicePayload: () => buildUpdateDevicePayload,
+  collectBubblesDeviceAttributes: () => collectBubblesDeviceAttributes,
   createBubblesDevice: () => createBubblesDevice,
   createBubblesDeviceClient: () => createBubblesDeviceClient,
   createStoredDeliveryStatusEvent: () => createStoredDeliveryStatusEvent,
@@ -73,6 +74,7 @@ __export(index_exports, {
   storeDeviceState: () => storeDeviceState,
   syncBubblesDevice: () => syncBubblesDevice,
   updateBubblesDevice: () => updateBubblesDevice,
+  updateBubblesDeviceAttributes: () => updateBubblesDeviceAttributes,
   useBubblesNotifications: () => useBubblesNotifications
 });
 module.exports = __toCommonJS(index_exports);
@@ -535,6 +537,78 @@ function throwAppAuthenticationError(error) {
   }
   throw error;
 }
+function normalizeDeviceAttributes(value) {
+  return normalizeDeviceAttributeObject(value, "attributes", /* @__PURE__ */ new WeakSet());
+}
+function normalizeDeviceAttributeValue(value, sourceDescription, seenValues) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      failWithBubblesError(`${sourceDescription} must be a finite number.`);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (seenValues.has(value)) {
+      failWithBubblesError(`${sourceDescription} must not contain cycles.`);
+    }
+    seenValues.add(value);
+    const normalizedValue = value.map(
+      (entry, index) => normalizeDeviceAttributeValue(
+        entry,
+        `${sourceDescription}[${index}]`,
+        seenValues
+      )
+    );
+    seenValues.delete(value);
+    return normalizedValue;
+  }
+  if (isPlainObject(value)) {
+    return normalizeDeviceAttributeObject(
+      value,
+      sourceDescription,
+      seenValues
+    );
+  }
+  failWithBubblesError(
+    `${sourceDescription} must be a JSON-compatible value.`
+  );
+}
+function normalizeDeviceAttributeObject(value, sourceDescription, seenValues) {
+  if (!isPlainObject(value)) {
+    failWithBubblesError('"attributes" must be an object.');
+  }
+  const valuePrototype = Object.getPrototypeOf(value);
+  if (valuePrototype !== Object.prototype && valuePrototype !== null) {
+    failWithBubblesError(
+      `${sourceDescription} must be a JSON-compatible object.`
+    );
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    failWithBubblesError(
+      `${sourceDescription} must not contain symbol keys.`
+    );
+  }
+  if (seenValues.has(value)) {
+    failWithBubblesError(`${sourceDescription} must not contain cycles.`);
+  }
+  seenValues.add(value);
+  const normalizedValue = {};
+  for (const [attributeName, attributeValue] of Object.entries(value)) {
+    normalizedValue[attributeName] = normalizeDeviceAttributeValue(
+      attributeValue,
+      `${sourceDescription}.${attributeName}`,
+      seenValues
+    );
+  }
+  seenValues.delete(value);
+  return normalizedValue;
+}
 function extractDeviceIdFromDeviceResponse(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return null;
@@ -574,6 +648,18 @@ async function updateBubblesDevice(options) {
     throwAppAuthenticationError(error);
   }
 }
+async function updateBubblesDeviceAttributes(options) {
+  const client = resolveDeviceClient(options);
+  try {
+    return await client.updateDeviceAttributes(
+      normalizeIdentifier(options.deviceId, "deviceId"),
+      normalizeDeviceAttributes(options.attributes),
+      withAppKeyHeader(options.appKey, options.requestOptions)
+    );
+  } catch (error) {
+    throwAppAuthenticationError(error);
+  }
+}
 async function syncBubblesDevice(options) {
   const client = resolveDeviceClient(options);
   if (options.deviceId !== null) {
@@ -1392,6 +1478,73 @@ async function getFCMToken(options) {
   return tokenResult.token;
 }
 
+// src/runtime/device-attributes.ts
+var Application = __toESM(require("expo-application"));
+var Device = __toESM(require("expo-device"));
+function compactAttributes(attributes) {
+  return Object.fromEntries(
+    Object.entries(attributes).filter((entry) => entry[1] !== null && entry[1] !== void 0)
+  );
+}
+function addSection(attributes, name, section) {
+  const compactedSection = compactAttributes(section);
+  if (Object.keys(compactedSection).length > 0) {
+    attributes[name] = compactedSection;
+  }
+}
+function getDeviceTypeName(deviceType2) {
+  switch (deviceType2) {
+    case Device.DeviceType.PHONE:
+      return "phone";
+    case Device.DeviceType.TABLET:
+      return "tablet";
+    case Device.DeviceType.DESKTOP:
+      return "desktop";
+    case Device.DeviceType.TV:
+      return "tv";
+    case Device.DeviceType.UNKNOWN:
+      return "unknown";
+    default:
+      return void 0;
+  }
+}
+async function getDeviceType() {
+  if (Device.deviceType !== null && Device.deviceType !== void 0) {
+    return Device.deviceType;
+  }
+  try {
+    return await Device.getDeviceTypeAsync();
+  } catch {
+    return null;
+  }
+}
+async function collectBubblesDeviceAttributes() {
+  const attributes = {};
+  const deviceType2 = await getDeviceType();
+  addSection(attributes, "device", {
+    manufacturer: Device.manufacturer,
+    brand: Device.brand,
+    modelName: Device.modelName,
+    modelId: typeof Device.modelId === "string" ? Device.modelId : void 0,
+    deviceName: Device.deviceName,
+    deviceType: getDeviceTypeName(deviceType2),
+    totalMemory: Device.totalMemory
+  });
+  addSection(attributes, "os", {
+    name: Device.osName,
+    version: Device.osVersion,
+    buildId: Device.osBuildId,
+    platformApiLevel: Device.platformApiLevel
+  });
+  addSection(attributes, "app", {
+    applicationId: Application.applicationId,
+    applicationName: Application.applicationName,
+    nativeApplicationVersion: Application.nativeApplicationVersion,
+    nativeBuildVersion: Application.nativeBuildVersion
+  });
+  return attributes;
+}
+
 // src/runtime/BubblesNotificationsProvider.tsx
 var import_react3 = require("react");
 
@@ -1635,6 +1788,20 @@ function buildRuntimeSnapshot(deviceId, registrationState) {
     notificationsEnabled: registrationState.notificationsEnabled
   };
 }
+async function syncBubblesDeviceAttributesBestEffort(apiBaseUrl, appKey, deviceId) {
+  try {
+    const attributes = await collectBubblesDeviceAttributes();
+    if (Object.keys(attributes).length > 0) {
+      await updateBubblesDeviceAttributes({
+        apiBaseUrl,
+        appKey,
+        deviceId,
+        attributes
+      });
+    }
+  } catch {
+  }
+}
 async function syncDeviceRegistrationState(options) {
   const apiBaseUrl = getRequiredNonEmptyString3(options.apiBaseUrl, "apiBaseUrl");
   const appKey = getRequiredNonEmptyString3(options.appKey, "appKey");
@@ -1661,6 +1828,13 @@ async function syncDeviceRegistrationState(options) {
     });
     const nextDeviceId = syncResult.deviceId ?? options.deviceId;
     storeDeviceId(nextDeviceId);
+    if (nextDeviceId) {
+      await syncBubblesDeviceAttributesBestEffort(
+        apiBaseUrl,
+        appKey,
+        nextDeviceId
+      );
+    }
     return {
       ...snapshot,
       action: syncResult.action,
@@ -1848,6 +2022,7 @@ function BubblesNotificationsProvider(props) {
   const [state, setState] = (0, import_react3.useState)(getInitialRuntimeState);
   const { enqueueOperation, isMountedRef } = useBubblesRuntimeOperationQueue(setState);
   const lastAutomaticSyncSignatureRef = (0, import_react3.useRef)(null);
+  const currentDeviceIdRef = (0, import_react3.useRef)(state.deviceId);
   const previousUserIdRef = (0, import_react3.useRef)(normalizedUserId);
   const buildAutomaticSyncSignature = (0, import_react3.useCallback)((deviceId) => {
     return getAutomaticSyncSignature({
@@ -1873,6 +2048,9 @@ function BubblesNotificationsProvider(props) {
       clearBubblesForegroundPresentation();
     };
   }, [isMountedRef]);
+  (0, import_react3.useEffect)(() => {
+    currentDeviceIdRef.current = state.deviceId;
+  }, [state.deviceId]);
   (0, import_react3.useEffect)(() => {
     let isCancelled = false;
     void (async () => {
@@ -1940,6 +2118,7 @@ function BubblesNotificationsProvider(props) {
         appVersion,
         deviceId: storedDeviceId
       });
+      currentDeviceIdRef.current = result.deviceId;
       return getRuntimeStateUpdate(result);
     });
   }, [
@@ -1973,9 +2152,10 @@ function BubblesNotificationsProvider(props) {
         userId: normalizedUserId,
         aliasing,
         appVersion,
-        deviceId: state.deviceId,
+        deviceId: currentDeviceIdRef.current,
         registrationOptions: options
       });
+      currentDeviceIdRef.current = result.deviceId;
       if (result.deviceId !== null) {
         lastAutomaticSyncSignatureRef.current = buildAutomaticSyncSignature(
           result.deviceId
@@ -1984,8 +2164,33 @@ function BubblesNotificationsProvider(props) {
       return getRuntimeStateUpdate(result);
     });
   }
+  function addDeviceAttribute(name, value) {
+    return enqueueOperation(async () => {
+      const attributeName = getRequiredNonEmptyString(name, "attributeName");
+      if (value === void 0) {
+        failWithBubblesError(
+          '"addDeviceAttribute()" requires "value" to be a JSON-compatible value.'
+        );
+      }
+      const deviceId = currentDeviceIdRef.current;
+      if (deviceId === null) {
+        failWithBubblesError(
+          '"addDeviceAttribute()" requires a backend "deviceId" before attributes can be synced.'
+        );
+      }
+      await updateBubblesDeviceAttributes({
+        apiBaseUrl,
+        appKey,
+        deviceId,
+        attributes: {
+          [attributeName]: value
+        }
+      });
+    });
+  }
   const contextValue = {
     registerDevice,
+    addDeviceAttribute,
     deviceId: state.deviceId,
     pushToken: state.pushToken,
     tokenType: state.tokenType,
@@ -2022,6 +2227,7 @@ function useBubblesNotifications() {
   buildCreateDevicePayload,
   buildStoredDeliveryStatusEventKey,
   buildUpdateDevicePayload,
+  collectBubblesDeviceAttributes,
   createBubblesDevice,
   createBubblesDeviceClient,
   createStoredDeliveryStatusEvent,
@@ -2056,5 +2262,6 @@ function useBubblesNotifications() {
   storeDeviceState,
   syncBubblesDevice,
   updateBubblesDevice,
+  updateBubblesDeviceAttributes,
   useBubblesNotifications
 });

package/dist/index.mjs

@@ -47,8 +47,9 @@ import {
   storeDeviceId,
   storeDeviceState,
   syncBubblesDevice,
-  updateBubblesDevice
-} from "./chunk-6NPXFGQX.mjs";
+  updateBubblesDevice,
+  updateBubblesDeviceAttributes
+} from "./chunk-3BAGWXHY.mjs";
 
 // src/runtime/tokens.ts
 import {
@@ -116,6 +117,73 @@ async function getFCMToken(options) {
   return tokenResult.token;
 }
 
+// src/runtime/device-attributes.ts
+import * as Application from "expo-application";
+import * as Device from "expo-device";
+function compactAttributes(attributes) {
+  return Object.fromEntries(
+    Object.entries(attributes).filter((entry) => entry[1] !== null && entry[1] !== void 0)
+  );
+}
+function addSection(attributes, name, section) {
+  const compactedSection = compactAttributes(section);
+  if (Object.keys(compactedSection).length > 0) {
+    attributes[name] = compactedSection;
+  }
+}
+function getDeviceTypeName(deviceType2) {
+  switch (deviceType2) {
+    case Device.DeviceType.PHONE:
+      return "phone";
+    case Device.DeviceType.TABLET:
+      return "tablet";
+    case Device.DeviceType.DESKTOP:
+      return "desktop";
+    case Device.DeviceType.TV:
+      return "tv";
+    case Device.DeviceType.UNKNOWN:
+      return "unknown";
+    default:
+      return void 0;
+  }
+}
+async function getDeviceType() {
+  if (Device.deviceType !== null && Device.deviceType !== void 0) {
+    return Device.deviceType;
+  }
+  try {
+    return await Device.getDeviceTypeAsync();
+  } catch {
+    return null;
+  }
+}
+async function collectBubblesDeviceAttributes() {
+  const attributes = {};
+  const deviceType2 = await getDeviceType();
+  addSection(attributes, "device", {
+    manufacturer: Device.manufacturer,
+    brand: Device.brand,
+    modelName: Device.modelName,
+    modelId: typeof Device.modelId === "string" ? Device.modelId : void 0,
+    deviceName: Device.deviceName,
+    deviceType: getDeviceTypeName(deviceType2),
+    totalMemory: Device.totalMemory
+  });
+  addSection(attributes, "os", {
+    name: Device.osName,
+    version: Device.osVersion,
+    buildId: Device.osBuildId,
+    platformApiLevel: Device.platformApiLevel
+  });
+  addSection(attributes, "app", {
+    applicationId: Application.applicationId,
+    applicationName: Application.applicationName,
+    nativeApplicationVersion: Application.nativeApplicationVersion,
+    nativeBuildVersion: Application.nativeBuildVersion
+  });
+  return attributes;
+}
+
 // src/runtime/BubblesNotificationsProvider.tsx
 import { useCallback as useCallback2, useEffect, useRef as useRef2, useState } from "react";
 
@@ -362,6 +430,20 @@ function buildRuntimeSnapshot(deviceId, registrationState) {
     notificationsEnabled: registrationState.notificationsEnabled
   };
 }
+async function syncBubblesDeviceAttributesBestEffort(apiBaseUrl, appKey, deviceId) {
+  try {
+    const attributes = await collectBubblesDeviceAttributes();
+    if (Object.keys(attributes).length > 0) {
+      await updateBubblesDeviceAttributes({
+        apiBaseUrl,
+        appKey,
+        deviceId,
+        attributes
+      });
+    }
+  } catch {
+  }
+}
 async function syncDeviceRegistrationState(options) {
   const apiBaseUrl = getRequiredNonEmptyString2(options.apiBaseUrl, "apiBaseUrl");
   const appKey = getRequiredNonEmptyString2(options.appKey, "appKey");
@@ -388,6 +470,13 @@ async function syncDeviceRegistrationState(options) {
     });
     const nextDeviceId = syncResult.deviceId ?? options.deviceId;
     storeDeviceId(nextDeviceId);
+    if (nextDeviceId) {
+      await syncBubblesDeviceAttributesBestEffort(
+        apiBaseUrl,
+        appKey,
+        nextDeviceId
+      );
+    }
     return {
       ...snapshot,
       action: syncResult.action,
@@ -578,6 +667,7 @@ function BubblesNotificationsProvider(props) {
   const [state, setState] = useState(getInitialRuntimeState);
   const { enqueueOperation, isMountedRef } = useBubblesRuntimeOperationQueue(setState);
   const lastAutomaticSyncSignatureRef = useRef2(null);
+  const currentDeviceIdRef = useRef2(state.deviceId);
   const previousUserIdRef = useRef2(normalizedUserId);
   const buildAutomaticSyncSignature = useCallback2((deviceId) => {
     return getAutomaticSyncSignature({
@@ -603,6 +693,9 @@ function BubblesNotificationsProvider(props) {
       clearBubblesForegroundPresentation();
     };
   }, [isMountedRef]);
+  useEffect(() => {
+    currentDeviceIdRef.current = state.deviceId;
+  }, [state.deviceId]);
   useEffect(() => {
     let isCancelled = false;
     void (async () => {
@@ -670,6 +763,7 @@ function BubblesNotificationsProvider(props) {
         appVersion,
         deviceId: storedDeviceId
       });
+      currentDeviceIdRef.current = result.deviceId;
       return getRuntimeStateUpdate(result);
     });
   }, [
@@ -703,9 +797,10 @@ function BubblesNotificationsProvider(props) {
         userId: normalizedUserId,
         aliasing,
         appVersion,
-        deviceId: state.deviceId,
+        deviceId: currentDeviceIdRef.current,
         registrationOptions: options
       });
+      currentDeviceIdRef.current = result.deviceId;
       if (result.deviceId !== null) {
         lastAutomaticSyncSignatureRef.current = buildAutomaticSyncSignature(
           result.deviceId
@@ -714,8 +809,33 @@ function BubblesNotificationsProvider(props) {
       return getRuntimeStateUpdate(result);
     });
   }
+  function addDeviceAttribute(name, value) {
+    return enqueueOperation(async () => {
+      const attributeName = getRequiredNonEmptyString(name, "attributeName");
+      if (value === void 0) {
+        failWithBubblesError(
+          '"addDeviceAttribute()" requires "value" to be a JSON-compatible value.'
+        );
+      }
+      const deviceId = currentDeviceIdRef.current;
+      if (deviceId === null) {
+        failWithBubblesError(
+          '"addDeviceAttribute()" requires a backend "deviceId" before attributes can be synced.'
+        );
+      }
+      await updateBubblesDeviceAttributes({
+        apiBaseUrl,
+        appKey,
+        deviceId,
+        attributes: {
+          [attributeName]: value
+        }
+      });
+    });
+  }
   const contextValue = {
     registerDevice,
+    addDeviceAttribute,
     deviceId: state.deviceId,
     pushToken: state.pushToken,
     tokenType: state.tokenType,
@@ -751,6 +871,7 @@ export {
   buildCreateDevicePayload,
   buildStoredDeliveryStatusEventKey,
   buildUpdateDevicePayload,
+  collectBubblesDeviceAttributes,
   createBubblesDevice,
   createBubblesDeviceClient,
   createStoredDeliveryStatusEvent,
@@ -785,5 +906,6 @@ export {
   storeDeviceState,
   syncBubblesDevice,
   updateBubblesDevice,
+  updateBubblesDeviceAttributes,
   useBubblesNotifications
 };

package/dist/register-task.mjs

@@ -1,6 +1,6 @@
 import {
   registerBubblesBackgroundHandlers
-} from "./chunk-6NPXFGQX.mjs";
+} from "./chunk-3BAGWXHY.mjs";
 
 // src/register-task.ts
 registerBubblesBackgroundHandlers();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fishonfire/bubbles-expo",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Expo config plugin, explicit background registration API, and React provider for Bubbles notifications.",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -68,8 +68,10 @@
     }
   },
   "dependencies": {
+    "expo-application": "~57.0.2",
     "@fishonfire/bubbles-js": "0.1.0",
     "expo-constants": "~57.0.16",
+    "expo-device": "~57.0.1",
     "expo-file-system": "~57.0.6"
   },
   "devDependencies": {