pushwave-client 0.3.7 → 0.3.9

package/README.md

@@ -76,6 +76,22 @@ export default function App() {
 - Call it **once** at app startup (e.g., in `App.tsx` or a root component `useEffect`). Recalling it later is unnecessary.
 - In `__DEV__`, the SDK may log additional info/errors (e.g., failed API calls) to help debugging.
 
+### API surface
+
+| Method | Description | Return |
+| --- | --- | --- |
+| `init({ apiKey })` | Registers the installation (Expo token + attestation + device metadata). Persists the API key when SecureStore is available. Must be called first. | `{ success, message? }` |
+| `identify({ userId })` | Links a `userId` to the installation. Requires `init`. | `{ success, message? }` |
+| `setUserAttributes(attributes)` | Sets custom attributes (string \| number \| boolean \| Date \| null). Requires `init`. | `{ success, message?, mismatches? }` |
+| `getUserAttributes()` | Fetches attributes for the current installation/user. Requires `init`. | `Record<string, AttributeValue>` (throws on error) |
+| `logout()` | Unregisters the installation (e.g., on sign-out). Requires `init`. | `{ success, message? }` |
+
+Tip: In production builds, ensure `PUSHWAVE_API_KEY` (or your chosen env) is injected via EAS secrets or `env` in `eas.json`, so `init` can read it at runtime.
+
+Common pitfalls:
+- Calling `identify`/`setUserAttributes`/`getUserAttributes`/`logout` before `init` has succeeded → initialize first.
+- Optional peers: install `expo-secure-store` for persistent installationId and `expo-application`/`expo-device`/`expo-localization` for richer metadata if you need those fields.
+
 ---
 
 ## Dashboard

package/dist/attestation/getApplicationAttestation.d.ts

@@ -1,2 +1,2 @@
 import { ApplicationAttestation } from "./index";
-export declare function getApplicationAttestation(apiKey: string): Promise<ApplicationAttestation>;
+export declare function getApplicationAttestation(): Promise<ApplicationAttestation>;

package/dist/attestation/getApplicationAttestation.js

@@ -4,7 +4,7 @@ exports.getApplicationAttestation = getApplicationAttestation;
 const buffer_1 = require("buffer");
 const react_native_1 = require("react-native");
 const native_1 = require("./native");
-async function getApplicationAttestation(apiKey) {
+async function getApplicationAttestation() {
     const { nonce, timestamp } = createNonce();
     try {
         if (react_native_1.Platform.OS === "android")

package/dist/identify/identify.d.ts

@@ -0,0 +1,2 @@
+import { IdentifyOptions, IdentifyResponse } from "./identify.dto";
+export declare function identify({ userId }: IdentifyOptions): Promise<IdentifyResponse>;

package/dist/identify/identify.dto.d.ts

@@ -0,0 +1,15 @@
+export type IdentifyResponse = {
+    success: boolean;
+    message?: string;
+};
+export type IdentifyOptions = {
+    userId: string;
+};
+export type IdentifyDTO = {
+    userId: string;
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production";
+};

package/dist/identify/identify.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/identify/identify.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identify = identify;
+const react_native_1 = require("react-native");
+const attestation_1 = require("../attestation");
+const register_1 = require("../register");
+const fetch_1 = require("../utils/fetch");
+const pwLogger_1 = require("../utils/pwLogger");
+const installationId_1 = require("../utils/installationId");
+const getApiKey_1 = require("../utils/getApiKey");
+async function identify({ userId }) {
+    const response = { success: false };
+    if (!register_1.IS_INITIALIZED) {
+        pwLogger_1.PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.identify");
+        return response;
+    }
+    let apiKey;
+    try {
+        apiKey = await (0, getApiKey_1.getApiKey)();
+    }
+    catch (e) {
+        pwLogger_1.PWLogger.warn("[PushWave.identify]", e);
+        return response;
+    }
+    const installationId = await (0, installationId_1.getInstallationId)();
+    const appAttestation = await (0, attestation_1.getApplicationAttestation)();
+    const data = {
+        apiKey,
+        userId,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: react_native_1.Platform.OS
+    };
+    try {
+        const res = await (0, fetch_1.fetchApi)("PUT", "app-users", { data });
+        return {
+            success: true,
+            message: res.message,
+        };
+    }
+    catch (err) {
+        const e = err;
+        pwLogger_1.PWLogger.error(e.message);
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}

package/dist/identify/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./identify";
+export * from "./identify.dto";

package/dist/identify/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./identify"), exports);
+__exportStar(require("./identify.dto"), exports);

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 import { RegisterPushWaveClient, RegisterPushWaveResponse } from "./register";
+import { IdentifyOptions, IdentifyResponse } from "./identify";
+import { LogoutResponse } from "./logout";
+import { GetUserAttributesResponse, SetUserAttributes, SetUserAttributesResponse } from "./userAttributes";
 export interface PushWaveClientType {
     init(options: RegisterPushWaveClient): Promise<RegisterPushWaveResponse>;
+    identify(options: IdentifyOptions): Promise<IdentifyResponse>;
+    logout(): Promise<LogoutResponse>;
+    setUserAttributes(options: SetUserAttributes): Promise<SetUserAttributesResponse>;
+    getUserAttributes(): Promise<GetUserAttributesResponse>;
 }
 declare const PushWaveClient: PushWaveClientType;
 export default PushWaveClient;

package/dist/index.js

@@ -1,9 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const register_1 = require("./register");
+const identify_1 = require("./identify");
+const logout_1 = require("./logout");
+const userAttributes_1 = require("./userAttributes");
 const PushWaveClient = {
     init(options) {
         return (0, register_1.registerPushWave)(options);
     },
+    identify(options) {
+        return (0, identify_1.identify)(options);
+    },
+    logout() {
+        return (0, logout_1.logout)();
+    },
+    setUserAttributes(options) {
+        return (0, userAttributes_1.setUserAttributes)(options);
+    },
+    getUserAttributes() {
+        return (0, userAttributes_1.getUserAttributes)();
+    },
 };
 exports.default = PushWaveClient;

package/dist/logout/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./logout";
+export * from "./logout.dto";

package/dist/logout/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logout"), exports);
+__exportStar(require("./logout.dto"), exports);

package/dist/logout/logout.d.ts

@@ -0,0 +1,2 @@
+import { LogoutResponse } from "./logout.dto";
+export declare function logout(): Promise<LogoutResponse>;

package/dist/logout/logout.dto.d.ts

@@ -0,0 +1,11 @@
+export type LogoutResponse = {
+    success: boolean;
+    message?: string;
+};
+export type LogoutDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production";
+};

package/dist/logout/logout.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/logout/logout.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logout = logout;
+const react_native_1 = require("react-native");
+const attestation_1 = require("../attestation");
+const register_1 = require("../register");
+const installationId_1 = require("../utils/installationId");
+const pwLogger_1 = require("../utils/pwLogger");
+const fetch_1 = require("../utils/fetch");
+const getApiKey_1 = require("../utils/getApiKey");
+async function logout() {
+    const response = { success: false };
+    if (!register_1.IS_INITIALIZED) {
+        pwLogger_1.PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.logout");
+        return response;
+    }
+    let apiKey;
+    try {
+        apiKey = await (0, getApiKey_1.getApiKey)();
+    }
+    catch (e) {
+        pwLogger_1.PWLogger.warn("[PushWave.logout]", e);
+        return response;
+    }
+    const installationId = await (0, installationId_1.getInstallationId)();
+    const appAttestation = await (0, attestation_1.getApplicationAttestation)();
+    const data = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: react_native_1.Platform.OS
+    };
+    try {
+        const res = await (0, fetch_1.fetchApi)("POST", "app-installations/logout", { data });
+        return {
+            success: true,
+            message: res.message,
+        };
+    }
+    catch (err) {
+        const e = err;
+        pwLogger_1.PWLogger.error(e.message);
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}

package/dist/register/registerPushWave.d.ts

@@ -1,2 +1,5 @@
 import { RegisterPushWaveClient, RegisterPushWaveResponse } from "./registerPushWave.dto";
+export declare var IS_INITIALIZED: boolean;
+export declare const API_STORAGE_KEY = "pushwave-api-storage-key";
+export declare var CACHE_API_KEY: string | false;
 export declare function registerPushWave({ apiKey }: RegisterPushWaveClient): Promise<RegisterPushWaveResponse>;

package/dist/register/registerPushWave.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_API_KEY = exports.API_STORAGE_KEY = exports.IS_INITIALIZED = void 0;
 exports.registerPushWave = registerPushWave;
 const expoToken_1 = require("../utils/expoToken");
 const react_native_1 = require("react-native");
@@ -9,6 +10,10 @@ const index_1 = require("../attestation/index");
 const fetch_1 = require("../utils/fetch");
 const installationId_1 = require("../utils/installationId");
 const collectDeviceMetaData_1 = require("../utils/collectDeviceMetaData");
+const loadSecureStore_1 = require("../utils/loadSecureStore");
+exports.IS_INITIALIZED = false;
+exports.API_STORAGE_KEY = "pushwave-api-storage-key";
+exports.CACHE_API_KEY = false;
 async function registerPushWave({ apiKey }) {
     const OS = react_native_1.Platform.OS;
     if ((0, apiKeyCheck_1.isSecretKey)(apiKey)) {
@@ -24,7 +29,7 @@ async function registerPushWave({ apiKey }) {
             message: "[PushWaveClient] Error: " + message
         };
     }
-    const appAttestation = await (0, index_1.getApplicationAttestation)(apiKey);
+    const appAttestation = await (0, index_1.getApplicationAttestation)();
     if (appAttestation.status === "disabled")
         pwLogger_1.PWLogger.warn(`(${react_native_1.Platform.OS}) could not get attestation: ${appAttestation.reason}`);
     const path = "expo-tokens";
@@ -45,8 +50,13 @@ async function registerPushWave({ apiKey }) {
         osVersion,
         timezone
     };
+    const SecureStore = (0, loadSecureStore_1.loadSecureStore)();
     try {
         const res = await (0, fetch_1.fetchApi)("PUT", path, { data: options });
+        exports.CACHE_API_KEY = apiKey;
+        if (SecureStore)
+            await SecureStore.setItemAsync(exports.API_STORAGE_KEY, apiKey);
+        exports.IS_INITIALIZED = true;
         return {
             success: true,
             message: res.message,
@@ -54,6 +64,10 @@ async function registerPushWave({ apiKey }) {
     }
     catch (err) {
         const e = err;
+        exports.CACHE_API_KEY = false;
+        if (SecureStore)
+            await SecureStore.deleteItemAsync(exports.API_STORAGE_KEY);
+        exports.IS_INITIALIZED = false;
         pwLogger_1.PWLogger.error(e.message);
         return {
             success: false,

package/dist/userAttributes/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./userAttributes";
+export * from "./userAttributes.dto";

package/dist/userAttributes/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./userAttributes"), exports);
+__exportStar(require("./userAttributes.dto"), exports);

package/dist/userAttributes/userAttributes.d.ts

@@ -0,0 +1,3 @@
+import { GetUserAttributesResponse, SetUserAttributes, SetUserAttributesResponse } from "./userAttributes.dto";
+export declare function setUserAttributes(attributes: SetUserAttributes): Promise<SetUserAttributesResponse>;
+export declare function getUserAttributes(): Promise<GetUserAttributesResponse>;

package/dist/userAttributes/userAttributes.dto.d.ts

@@ -0,0 +1,24 @@
+export type AttributeValue = string | number | boolean | Date | null;
+export type SetUserAttributes = Record<string, AttributeValue>;
+export type SetUserAttributesResponse = {
+    success: boolean;
+    message?: string;
+    mismatches?: string;
+};
+export type SetUserAttributesDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production";
+    attributes: SetUserAttributes;
+};
+export type GetUserAttributes = Record<string, AttributeValue>;
+export type GetUserAttributesResponse = GetUserAttributes;
+export type GetUserAttributesDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production";
+};

package/dist/userAttributes/userAttributes.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/userAttributes/userAttributes.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setUserAttributes = setUserAttributes;
+exports.getUserAttributes = getUserAttributes;
+const react_native_1 = require("react-native");
+const attestation_1 = require("../attestation");
+const register_1 = require("../register");
+const getApiKey_1 = require("../utils/getApiKey");
+const installationId_1 = require("../utils/installationId");
+const pwLogger_1 = require("../utils/pwLogger");
+const fetch_1 = require("../utils/fetch");
+async function setUserAttributes(attributes) {
+    const response = { success: false };
+    if (!register_1.IS_INITIALIZED) {
+        pwLogger_1.PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.setUserAttributes");
+        return response;
+    }
+    let apiKey;
+    try {
+        apiKey = await (0, getApiKey_1.getApiKey)();
+    }
+    catch (e) {
+        pwLogger_1.PWLogger.warn("[PushWave.setUserAttributes]", e);
+        return response;
+    }
+    const installationId = await (0, installationId_1.getInstallationId)();
+    const appAttestation = await (0, attestation_1.getApplicationAttestation)();
+    const data = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: react_native_1.Platform.OS,
+        attributes
+    };
+    try {
+        const res = await (0, fetch_1.fetchApi)("PATCH", "app-users/me/attributes", { data });
+        return {
+            success: true,
+            message: res.message,
+            mismatches: res.mismatches
+        };
+    }
+    catch (err) {
+        const e = err;
+        pwLogger_1.PWLogger.error(e.message);
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}
+async function getUserAttributes() {
+    if (!register_1.IS_INITIALIZED) {
+        const msg = `PushWaveClient.init({ apiKey }) must be called before PushWaveClient.getUserAttributes`;
+        pwLogger_1.PWLogger.warn(msg);
+        throw new Error(msg);
+    }
+    let apiKey;
+    try {
+        apiKey = await (0, getApiKey_1.getApiKey)();
+    }
+    catch (e) {
+        const msg = `[PushWave.getUserAttributes] ${e}`;
+        pwLogger_1.PWLogger.warn(msg);
+        throw new Error(msg);
+    }
+    const installationId = await (0, installationId_1.getInstallationId)();
+    const appAttestation = await (0, attestation_1.getApplicationAttestation)();
+    const data = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: react_native_1.Platform.OS
+    };
+    try {
+        const res = await (0, fetch_1.fetchApi)("POST", "app-users/me/attributes", { data });
+        return res.attributes ?? {};
+    }
+    catch (err) {
+        const e = err;
+        const msg = e.message;
+        pwLogger_1.PWLogger.error(msg);
+        throw new Error(msg);
+    }
+}

package/dist/utils/getApiKey.d.ts

@@ -0,0 +1 @@
+export declare function getApiKey(): Promise<string>;

package/dist/utils/getApiKey.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApiKey = getApiKey;
+const register_1 = require("../register");
+const loadSecureStore_1 = require("./loadSecureStore");
+async function getApiKey() {
+    const SecureStore = (0, loadSecureStore_1.loadSecureStore)();
+    const apiKey = SecureStore ? await SecureStore.getItemAsync(register_1.API_STORAGE_KEY) : register_1.CACHE_API_KEY;
+    if (!apiKey)
+        throw new Error("Unable to retrieve API key.");
+    return apiKey;
+}

package/dist/utils/installationId.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getInstallationId = void 0;
+const loadSecureStore_1 = require("./loadSecureStore");
 const pwLogger_1 = require("./pwLogger");
 const STORAGE_KEY = "pushwave-installation-id";
 let cachedId = null;
@@ -28,18 +29,10 @@ const generateId = () => {
         hex.slice(20)
     ].join("-");
 };
-const loadSecureStore = () => {
-    try {
-        return require("expo-secure-store");
-    }
-    catch (err) {
-        return null;
-    }
-};
 const getInstallationId = async () => {
     if (cachedId)
         return cachedId;
-    const SecureStore = loadSecureStore();
+    const SecureStore = (0, loadSecureStore_1.loadSecureStore)();
     if (SecureStore) {
         try {
             const existing = await SecureStore.getItemAsync(STORAGE_KEY);

package/dist/utils/loadSecureStore.d.ts

@@ -0,0 +1,7 @@
+type SecureStoreModule = {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+};
+export declare const loadSecureStore: () => SecureStoreModule | null;
+export {};

package/dist/utils/loadSecureStore.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSecureStore = void 0;
+const loadSecureStore = () => {
+    try {
+        return require("expo-secure-store");
+    }
+    catch (err) {
+        return null;
+    }
+};
+exports.loadSecureStore = loadSecureStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pushwave-client",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "PushWave Client, Expo Push Notifications SaaS SDK",
   "homepage": "https://github.com/luruk-hai/pushwave-client#readme",
   "bugs": {

package/src/attestation/getApplicationAttestation.ts

@@ -3,7 +3,7 @@ import { Platform } from "react-native";
 import { getAndroidIntegrityToken, getDeviceCheckToken } from "./native";
 import { ApplicationAttestation, AndroidAttestationPayload, DisabledAttestation, IosAttestationPayload } from "./index";
 
-export async function getApplicationAttestation(apiKey: string): Promise<ApplicationAttestation> {
+export async function getApplicationAttestation(): Promise<ApplicationAttestation> {
     const { nonce, timestamp } = createNonce();
 
     try {

package/src/identify/identify.dto.ts

@@ -0,0 +1,17 @@
+export type IdentifyResponse = {
+    success: boolean;
+    message?: string;
+}
+
+export type IdentifyOptions = {
+    userId: string;
+}
+
+export type IdentifyDTO = {
+    userId: string;
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production",
+}

package/src/identify/identify.ts

@@ -0,0 +1,62 @@
+import { Platform } from "react-native";
+import { getApplicationAttestation } from "../attestation";
+import { API_STORAGE_KEY, CACHE_API_KEY, IS_INITIALIZED } from "../register";
+import { fetchApi } from "../utils/fetch";
+import { loadSecureStore } from "../utils/loadSecureStore";
+import { PWLogger } from "../utils/pwLogger";
+import { IdentifyDTO, IdentifyOptions, IdentifyResponse } from "./identify.dto";
+import { getInstallationId } from "../utils/installationId";
+import { getApiKey } from "../utils/getApiKey";
+
+/**
+ * Link a userId to the current installation. Requires a successful registerPushWave/init call.
+ */
+export async function identify({ userId }: IdentifyOptions): Promise<IdentifyResponse> {
+
+    const response: IdentifyResponse = { success: false }
+
+    if (!IS_INITIALIZED) {
+
+        PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.identify");
+
+        return response;
+    }
+
+    let apiKey;
+
+    try {
+        apiKey = await getApiKey();
+    } catch (e) {
+        PWLogger.warn("[PushWave.identify]", e);
+        return response;
+    }
+
+    const installationId = await getInstallationId();
+    const appAttestation = await getApplicationAttestation();
+
+    const data: IdentifyDTO = {
+        apiKey,
+        userId,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: Platform.OS
+    }
+
+    try {
+        const res: IdentifyResponse = await fetchApi("PUT", "app-users", { data })
+        return {
+            success: true,
+            message: res.message,
+        };
+    } catch (err) {
+        const e = err as Error;
+
+        PWLogger.error(e.message);
+
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}

package/src/identify/index.ts

@@ -0,0 +1,2 @@
+export * from "./identify";
+export * from "./identify.dto";

package/src/index.ts

@@ -1,13 +1,58 @@
 import { registerPushWave, RegisterPushWaveClient, RegisterPushWaveResponse } from "./register";
+import { identify, IdentifyOptions, IdentifyResponse } from "./identify";
+import { LogoutResponse, logout } from "./logout";
+import { getUserAttributes, GetUserAttributesDTO, GetUserAttributesResponse, setUserAttributes, SetUserAttributes, SetUserAttributesResponse } from "./userAttributes";
 
 export interface PushWaveClientType {
+  /**
+   * Initialize PushWave for this installation. Must be called once at app startup.
+   * - Requests push permissions + Expo push token.
+   * - Collects device/app metadata and attestation.
+   * - Caches the API key (SecureStore when available) and marks the client initialized.
+   */
   init(options: RegisterPushWaveClient): Promise<RegisterPushWaveResponse>;
+
+  /**
+   * Attach a userId to the current installation for targeting/analytics.
+   * Requires `init` to have run successfully in this session.
+   */
+  identify(options: IdentifyOptions): Promise<IdentifyResponse>;
+
+  /**
+   * Unlink the current installation from the backend (e.g., on logout).
+   * Requires `init` to have run successfully in this session.
+   */
+  logout(): Promise<LogoutResponse>;
+
+  /**
+   * Set custom attributes for the current user/installation.
+   * Requires `init` to have run successfully in this session.
+   */
+  setUserAttributes(options: SetUserAttributes): Promise<SetUserAttributesResponse>;
+
+  /**
+   * Fetch stored attributes for the current user/installation.
+   * Requires `init` to have run successfully in this session.
+   */
+  getUserAttributes(): Promise<GetUserAttributesResponse>;
 }
 
 const PushWaveClient: PushWaveClientType = {
   init(options) {
     return registerPushWave(options);
   },
+  identify(options) {
+    return identify(options)
+  },
+  logout() {
+    return logout();
+  },
+  setUserAttributes(options) {
+    return setUserAttributes(options)
+  },
+  getUserAttributes() {
+    return getUserAttributes();
+  },
 };
 
-export default PushWaveClient;
+export default PushWaveClient;

package/src/logout/index.ts

@@ -0,0 +1,2 @@
+export * from "./logout";
+export * from "./logout.dto";

package/src/logout/logout.dto.ts

@@ -0,0 +1,12 @@
+export type LogoutResponse = {
+    success: boolean;
+    message?: string;
+}
+
+export type LogoutDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production",
+}

package/src/logout/logout.ts

@@ -0,0 +1,59 @@
+import { Platform } from "react-native";
+import { getApplicationAttestation } from "../attestation";
+import { IS_INITIALIZED } from "../register";
+import { getInstallationId } from "../utils/installationId";
+import { PWLogger } from "../utils/pwLogger";
+import { LogoutDTO, LogoutResponse } from "./logout.dto";
+import { fetchApi } from "../utils/fetch";
+import { getApiKey } from "../utils/getApiKey";
+
+/**
+ * Unregister the current installation (e.g., on user logout). Requires a successful init.
+ */
+export async function logout(): Promise<LogoutResponse> {
+    const response: LogoutResponse = { success: false }
+
+    if (!IS_INITIALIZED) {
+
+        PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.logout");
+
+        return response;
+    }
+
+    let apiKey;
+
+    try {
+        apiKey = await getApiKey();
+    } catch (e) {
+        PWLogger.warn("[PushWave.logout]", e);
+        return response;
+    }
+
+    const installationId = await getInstallationId();
+    const appAttestation = await getApplicationAttestation();
+
+    const data: LogoutDTO = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: Platform.OS
+    }
+
+    try {
+        const res: LogoutResponse = await fetchApi("POST", "app-installations/logout", { data })
+        return {
+            success: true,
+            message: res.message,
+        };
+    } catch (err) {
+        const e = err as Error;
+
+        PWLogger.error(e.message);
+
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}

package/src/register/registerPushWave.ts

@@ -7,7 +7,18 @@ import { getApplicationAttestation } from "../attestation/index";
 import { fetchApi } from "../utils/fetch";
 import { getInstallationId } from "../utils/installationId";
 import { collectDeviceMetaData } from "../utils/collectDeviceMetaData";
+import { loadSecureStore } from "../utils/loadSecureStore";
 
+export var IS_INITIALIZED: boolean = false;
+
+export const API_STORAGE_KEY = "pushwave-api-storage-key";
+export var CACHE_API_KEY: string | false = false;
+
+/**
+ * Initialize PushWave for this installation: retrieves the Expo push token, collects
+ * attestation + device metadata, persists the API key when SecureStore is available,
+ * and caches initialization state for subsequent calls.
+ */
 export async function registerPushWave(
     { apiKey }: RegisterPushWaveClient
 ): Promise<RegisterPushWaveResponse> {
@@ -32,7 +43,7 @@ export async function registerPushWave(
         }
     }
 
-    const appAttestation = await getApplicationAttestation(apiKey);
+    const appAttestation = await getApplicationAttestation();
 
     if (appAttestation.status === "disabled")
         PWLogger.warn(`(${Platform.OS}) could not get attestation: ${appAttestation.reason}`);
@@ -59,9 +70,16 @@ export async function registerPushWave(
         timezone
     }
 
+    const SecureStore = loadSecureStore();
+
     try {
         const res: RegisterPushWaveResponse = await fetchApi("PUT", path, { data: options })
 
+        CACHE_API_KEY = apiKey;
+        if (SecureStore) await SecureStore.setItemAsync(API_STORAGE_KEY, apiKey);
+
+        IS_INITIALIZED = true;
+
         return {
             success: true,
             message: res.message,
@@ -69,6 +87,11 @@ export async function registerPushWave(
     } catch (err) {
         const e = err as Error;
 
+        CACHE_API_KEY = false;
+        if (SecureStore) await SecureStore.deleteItemAsync(API_STORAGE_KEY);
+
+        IS_INITIALIZED = false;
+
         PWLogger.error(e.message);
 
         return {

package/src/userAttributes/index.ts

@@ -0,0 +1,2 @@
+export * from "./userAttributes";
+export * from "./userAttributes.dto";

package/src/userAttributes/userAttributes.dto.ts

@@ -0,0 +1,35 @@
+export type AttributeValue =
+    | string
+    | number
+    | boolean
+    | Date
+    | null
+
+export type SetUserAttributes = Record<string, AttributeValue>
+
+export type SetUserAttributesResponse = {
+    success: boolean;
+    message?: string;
+    mismatches?: string;
+}
+
+export type SetUserAttributesDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production",
+    attributes: SetUserAttributes
+}
+
+export type GetUserAttributes = Record<string, AttributeValue>
+
+export type GetUserAttributesResponse = GetUserAttributes;
+
+export type GetUserAttributesDTO = {
+    apiKey: string;
+    installationId: string;
+    platform: string;
+    appAttestation?: any;
+    environment: "development" | "production";
+}

package/src/userAttributes/userAttributes.ts

@@ -0,0 +1,103 @@
+import { Platform } from "react-native";
+import { getApplicationAttestation } from "../attestation";
+import { IS_INITIALIZED } from "../register";
+import { getApiKey } from "../utils/getApiKey";
+import { getInstallationId } from "../utils/installationId";
+import { PWLogger } from "../utils/pwLogger";
+import { GetUserAttributesDTO, GetUserAttributesResponse, SetUserAttributes, SetUserAttributesDTO, SetUserAttributesResponse } from "./userAttributes.dto";
+import { fetchApi } from "../utils/fetch";
+
+/**
+ * Set custom attributes for the current user/installation. Requires a successful init.
+ */
+export async function setUserAttributes(attributes: SetUserAttributes): Promise<SetUserAttributesResponse> {
+    const response: SetUserAttributesResponse = { success: false }
+
+    if (!IS_INITIALIZED) {
+
+        PWLogger.warn("PushWaveClient.init({ apiKey }) must be called before PushWaveClient.setUserAttributes");
+
+        return response;
+    }
+
+    let apiKey;
+
+    try {
+        apiKey = await getApiKey();
+    } catch (e) {
+        PWLogger.warn("[PushWave.setUserAttributes]", e);
+        return response;
+    }
+
+    const installationId = await getInstallationId();
+    const appAttestation = await getApplicationAttestation();
+
+    const data: SetUserAttributesDTO = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: Platform.OS,
+        attributes
+    }
+
+    try {
+        const res: SetUserAttributesResponse = await fetchApi("PATCH", "app-users/me/attributes", { data })
+        return {
+            success: true,
+            message: res.message,
+            mismatches: res.mismatches
+        };
+    } catch (err) {
+        const e = err as Error;
+
+        PWLogger.error(e.message);
+
+        return {
+            success: false,
+            message: e.message,
+        };
+    }
+}
+
+/**
+ * Retrieve attributes for the current user/installation. Requires a successful init.
+ */
+export async function getUserAttributes(): Promise<GetUserAttributesResponse> {
+    if (!IS_INITIALIZED) {
+        const msg = `PushWaveClient.init({ apiKey }) must be called before PushWaveClient.getUserAttributes`
+        PWLogger.warn(msg);
+        throw new Error(msg);
+    }
+
+    let apiKey;
+
+    try {
+        apiKey = await getApiKey();
+    } catch (e) {
+        const msg = `[PushWave.getUserAttributes] ${e}`
+        PWLogger.warn(msg);
+        throw new Error(msg);
+    }
+
+    const installationId = await getInstallationId();
+    const appAttestation = await getApplicationAttestation();
+
+    const data: GetUserAttributesDTO = {
+        apiKey,
+        installationId,
+        appAttestation,
+        environment: __DEV__ ? "development" : "production",
+        platform: Platform.OS
+    }
+
+    try {
+        const res: { attributes: GetUserAttributesResponse } = await fetchApi("POST", "app-users/me/attributes", { data })
+        return res.attributes ?? {};
+    } catch (err) {
+        const e = err as Error;
+        const msg = e.message;
+        PWLogger.error(msg);
+        throw new Error(msg);
+    }
+}

package/src/utils/getApiKey.ts

@@ -0,0 +1,12 @@
+import { API_STORAGE_KEY, CACHE_API_KEY } from "../register";
+import { loadSecureStore } from "./loadSecureStore";
+
+export async function getApiKey(): Promise<string> {
+    const SecureStore = loadSecureStore();
+
+    const apiKey = SecureStore ? await SecureStore.getItemAsync(API_STORAGE_KEY) : CACHE_API_KEY;
+
+    if (!apiKey) throw new Error("Unable to retrieve API key.")
+
+    return apiKey;
+}

package/src/utils/installationId.ts

@@ -1,3 +1,4 @@
+import { loadSecureStore } from "./loadSecureStore";
 import { PWLogger } from "./pwLogger";
 
 const STORAGE_KEY = "pushwave-installation-id";
@@ -5,11 +6,6 @@ const STORAGE_KEY = "pushwave-installation-id";
 let cachedId: string | null = null;
 let warnedMissingSecureStore = false;
 
-type SecureStoreModule = {
-    getItemAsync(key: string): Promise<string | null>;
-    setItemAsync(key: string, value: string): Promise<void>;
-};
-
 const generateId = (): string => {
     if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
         return crypto.randomUUID();
@@ -35,14 +31,6 @@ const generateId = (): string => {
     ].join("-");
 };
 
-const loadSecureStore = (): SecureStoreModule | null => {
-    try {
-        return require("expo-secure-store") as SecureStoreModule;
-    } catch (err) {
-        return null;
-    }
-};
-
 export const getInstallationId = async (): Promise<string> => {
     if (cachedId) return cachedId;
 

package/src/utils/loadSecureStore.ts

@@ -0,0 +1,13 @@
+type SecureStoreModule = {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+};
+
+export const loadSecureStore = (): SecureStoreModule | null => {
+    try {
+        return require("expo-secure-store") as SecureStoreModule;
+    } catch (err) {
+        return null;
+    }
+};