react-native-qpush 0.0.0-stage → 1.0.0

package/lib/core/platform.d.ts

@@ -0,0 +1,72 @@
+import type { FcmParams, PermissionStatus } from '../types';
+import type { KeyValueStore } from './storage';
+import type { DeviceInfo } from './subscription';
+export interface Scheduler {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface Subscription {
+    remove(): void;
+}
+export interface FetchResponseLike {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: unknown;
+}
+export type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponseLike>;
+export interface AppStateLike {
+    readonly currentState: string | null | undefined;
+    addEventListener(type: 'change', listener: (state: string) => void): Subscription;
+}
+export interface NativeEventSource {
+    addListener(eventName: string, listener: (payload: any) => void): Subscription;
+}
+/** Result of `registerForPush`. */
+export interface NativePushRegistration {
+    token: string | null;
+    /** Negative `notification_types` value when registration failed. */
+    notificationTypes?: number;
+    error?: string;
+}
+/** Typed facade over the native module (see `NativeQPushPush.ts`). */
+export interface NativeBridge extends KeyValueStore {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    registerForPush(fcmParams: FcmParams | null): Promise<NativePushRegistration>;
+    getPermissionStatus(): Promise<PermissionStatus>;
+    requestPermission(fallbackToSettings: boolean): Promise<boolean>;
+    registerForProvisionalAuthorization(): Promise<boolean>;
+    canRequestPermission(): Promise<boolean>;
+    clearAll(): void;
+    removeNotification(notificationId: string): void;
+    removeGroupedNotifications(groupKey: string): void;
+    /** Clears the app badge and returns the previous value (iOS; 0 on Android). */
+    clearBadge(): Promise<number>;
+    /** Tells native that JS subscribed to events: queued native events are flushed. */
+    setJsReady(): void;
+    displayForegroundNotification(displayId: string): void;
+    preventForegroundDisplay(displayId: string): void;
+    setAutoOpenUrls(enabled: boolean): void;
+    setLogLevel(level: number): void;
+    beginBackgroundTask(): Promise<number>;
+    endBackgroundTask(taskId: number): void;
+}
+/** Everything the core needs from the host environment (injected for tests). */
+export interface PlatformAdapter {
+    os: 'ios' | 'android';
+    native: NativeBridge;
+    nativeEvents: NativeEventSource;
+    appState: AppStateLike;
+    fetch: FetchLike;
+    scheduler: Scheduler;
+    now(): number;
+    random(): number;
+}
+export declare const defaultScheduler: Scheduler;

package/lib/core/platform.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultScheduler = void 0;
+exports.defaultScheduler = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};

package/lib/core/state.d.ts

@@ -0,0 +1,51 @@
+import type { FcmParams, PermissionStatus } from '../types';
+import type { SubscriptionFields } from './subscription';
+/** Local model of the current user. */
+export interface PersistedUser {
+    /** Device-generated id; operations reference users by it. */
+    localId: string;
+    qpushId?: string;
+    externalId?: string;
+    /** Aliases except `qpush_id` / `onesignal_id` (includes `external_id`). */
+    aliases: Record<string, string>;
+    tags: Record<string, string>;
+    language?: string;
+    /** `true` once the developer called `setLanguage()`. */
+    languageExplicit?: boolean;
+    /** Last timezone sent to the server. */
+    timezone?: string;
+}
+/** Local model of this device's push subscription. */
+export interface PersistedSubscription {
+    id?: string;
+    token?: string;
+    /** Negative notification_types from a failed native registration. */
+    tokenError?: number;
+    /** Developer intent: `optIn()` / `optOut()`. */
+    optedIn: boolean;
+    permission: PermissionStatus;
+    /** Fields last acknowledged by the server. */
+    synced?: Partial<SubscriptionFields>;
+    /** Send `badge_count: 0` with the next subscription PATCH. */
+    badgeResetPending?: boolean;
+}
+export interface PersistedConfig {
+    appId: string;
+    serverUrl: string;
+}
+export interface PersistedState {
+    version: 1;
+    config?: PersistedConfig;
+    user: PersistedUser;
+    subscription: PersistedSubscription;
+    /** local user id -> qpush_id, for users referenced by pending operations. */
+    idMap: Record<string, string>;
+    consentRequired: boolean;
+    consentGiven: boolean;
+    /** Last FCM params from android_params.js (`null` = server has none). */
+    fcmParams?: FcmParams | null;
+}
+export declare function createUser(localId: string): PersistedUser;
+export declare function createDefaultState(localId: string): PersistedState;
+/** Validates persisted JSON, falling back to defaults for broken parts. */
+export declare function sanitizeState(raw: unknown, newLocalId: () => string): PersistedState;

package/lib/core/state.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUser = createUser;
+exports.createDefaultState = createDefaultState;
+exports.sanitizeState = sanitizeState;
+function createUser(localId) {
+    return { localId, aliases: {}, tags: {} };
+}
+function createDefaultState(localId) {
+    return {
+        version: 1,
+        user: createUser(localId),
+        subscription: { optedIn: true, permission: 'notDetermined' },
+        idMap: {},
+        consentRequired: false,
+        consentGiven: false,
+    };
+}
+function isRecordOfStrings(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    return Object.values(value).every((entry) => typeof entry === 'string');
+}
+const PERMISSIONS = ['notDetermined', 'denied', 'granted', 'provisional', 'ephemeral'];
+/** Validates persisted JSON, falling back to defaults for broken parts. */
+function sanitizeState(raw, newLocalId) {
+    const fallback = createDefaultState(newLocalId());
+    if (typeof raw !== 'object' || raw === null)
+        return fallback;
+    const value = raw;
+    if (value.version !== 1)
+        return fallback;
+    const state = { ...fallback };
+    if (value.config &&
+        typeof value.config.appId === 'string' &&
+        typeof value.config.serverUrl === 'string') {
+        state.config = { appId: value.config.appId, serverUrl: value.config.serverUrl };
+    }
+    const user = value.user;
+    if (user && typeof user.localId === 'string') {
+        state.user = {
+            localId: user.localId,
+            qpushId: typeof user.qpushId === 'string' ? user.qpushId : undefined,
+            externalId: typeof user.externalId === 'string' ? user.externalId : undefined,
+            aliases: isRecordOfStrings(user.aliases) ? user.aliases : {},
+            tags: isRecordOfStrings(user.tags) ? user.tags : {},
+            language: typeof user.language === 'string' ? user.language : undefined,
+            languageExplicit: user.languageExplicit === true,
+            timezone: typeof user.timezone === 'string' ? user.timezone : undefined,
+        };
+    }
+    const subscription = value.subscription;
+    if (subscription && typeof subscription === 'object') {
+        state.subscription = {
+            id: typeof subscription.id === 'string' ? subscription.id : undefined,
+            token: typeof subscription.token === 'string' ? subscription.token : undefined,
+            tokenError: typeof subscription.tokenError === 'number' ? subscription.tokenError : undefined,
+            optedIn: subscription.optedIn !== false,
+            permission: PERMISSIONS.includes(subscription.permission)
+                ? subscription.permission
+                : 'notDetermined',
+            synced: typeof subscription.synced === 'object' && subscription.synced !== null ? subscription.synced : undefined,
+            badgeResetPending: subscription.badgeResetPending === true,
+        };
+    }
+    state.idMap = isRecordOfStrings(value.idMap) ? value.idMap : {};
+    state.consentRequired = value.consentRequired === true;
+    state.consentGiven = value.consentGiven === true;
+    if (value.fcmParams === null)
+        state.fcmParams = null;
+    else if (value.fcmParams && typeof value.fcmParams === 'object')
+        state.fcmParams = value.fcmParams;
+    return state;
+}

package/lib/core/storage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal async key/value store. In the app it is backed by the native module
+ * (SharedPreferences on Android, UserDefaults on iOS) so native code can read
+ * the same values; tests use {@link MemoryStore}.
+ */
+export interface KeyValueStore {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export declare class MemoryStore implements KeyValueStore {
+    readonly data: Map<string, string>;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** Reads and parses a JSON value, returning `null` on any failure. */
+export declare function readJson<T>(store: KeyValueStore, key: string): Promise<T | null>;
+/**
+ * Serializes writes for one key: only the latest value matters, writes never
+ * overlap and a failed write does not break the chain.
+ */
+export declare class SerialWriter {
+    private readonly store;
+    private readonly key;
+    private readonly onError;
+    private chain;
+    private latest;
+    private scheduled;
+    constructor(store: KeyValueStore, key: string, onError?: (error: unknown) => void);
+    write(value: string): Promise<void>;
+    /** Resolves when every pending write finished. */
+    flush(): Promise<void>;
+}

package/lib/core/storage.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerialWriter = exports.MemoryStore = void 0;
+exports.readJson = readJson;
+class MemoryStore {
+    constructor() {
+        this.data = new Map();
+    }
+    async getItem(key) {
+        return this.data.has(key) ? this.data.get(key) : null;
+    }
+    async setItem(key, value) {
+        this.data.set(key, value);
+    }
+    async removeItem(key) {
+        this.data.delete(key);
+    }
+}
+exports.MemoryStore = MemoryStore;
+/** Reads and parses a JSON value, returning `null` on any failure. */
+async function readJson(store, key) {
+    try {
+        const raw = await store.getItem(key);
+        if (raw == null || raw === '')
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serializes writes for one key: only the latest value matters, writes never
+ * overlap and a failed write does not break the chain.
+ */
+class SerialWriter {
+    constructor(store, key, onError = () => { }) {
+        this.store = store;
+        this.key = key;
+        this.onError = onError;
+        this.chain = Promise.resolve();
+        this.latest = null;
+        this.scheduled = false;
+    }
+    write(value) {
+        this.latest = value;
+        if (!this.scheduled) {
+            this.scheduled = true;
+            this.chain = this.chain
+                .then(async () => {
+                this.scheduled = false;
+                const toWrite = this.latest;
+                if (toWrite !== null)
+                    await this.store.setItem(this.key, toWrite);
+            })
+                .catch((error) => {
+                this.scheduled = false;
+                this.onError(error);
+            });
+        }
+        return this.chain;
+    }
+    /** Resolves when every pending write finished. */
+    flush() {
+        return this.chain;
+    }
+}
+exports.SerialWriter = SerialWriter;

package/lib/core/subscription.d.ts

@@ -0,0 +1,67 @@
+import type { PermissionStatus, SubscriptionPayload } from '../types';
+/** Mutable subscription fields that the SDK keeps in sync with the server. */
+export interface SubscriptionFields {
+    token?: string;
+    enabled: boolean;
+    notification_types: number;
+    device_model?: string;
+    device_os?: string;
+    sdk: string;
+    app_version?: string;
+    test_type?: number | null;
+    carrier?: string;
+    rooted?: boolean;
+    net_type?: number;
+}
+export type SubscriptionPatch = Partial<SubscriptionFields> & {
+    badge_count?: number;
+};
+/** Device information reported by the native module. */
+export interface DeviceInfo {
+    platform: 'ios' | 'android';
+    deviceModel?: string;
+    deviceOs?: string;
+    appVersion?: string;
+    /** IANA timezone id. */
+    timezone?: string;
+    /** BCP-47 locale tag (e.g. `pt-BR`). */
+    locale?: string;
+    /** ISO 639-1 language (e.g. `pt`). */
+    language?: string;
+    /** ISO 3166-1 alpha-2 country from the locale. */
+    country?: string;
+    carrier?: string;
+    rooted?: boolean;
+    netType?: number;
+    /** iOS only: 1 development, 2 ad-hoc, null App Store/TestFlight. */
+    testType?: number | null;
+}
+export interface SubscriptionInputs {
+    token?: string | null;
+    /** Negative `notification_types` reported by the native registration. */
+    tokenError?: number | null;
+    permission: PermissionStatus;
+    /** Developer intent (`optIn()` / `optOut()`), default `true`. */
+    optedIn: boolean;
+}
+export declare function isPermissionGranted(permission: PermissionStatus): boolean;
+/**
+ * Computes `notification_types`:
+ * token errors (-3/-10) > opted out / denied (-2) > not asked (0) > subscribed (1).
+ */
+export declare function computeNotificationTypes(input: SubscriptionInputs): number;
+/** `enabled` is false when opted out or when the OS permission is not granted. */
+export declare function computeEnabled(input: SubscriptionInputs): boolean;
+/** What `pushSubscription.getOptedInAsync()` reports. */
+export declare function computeOptedIn(input: SubscriptionInputs): boolean;
+/** Builds the full subscription field set from local state and device info. */
+export declare function buildSubscriptionFields(input: SubscriptionInputs, device: DeviceInfo | null): SubscriptionFields;
+export declare function subscriptionType(platform: 'ios' | 'android'): SubscriptionPayload['type'];
+/** Full payload for `POST /users` / `POST .../subscriptions`. */
+export declare function toSubscriptionPayload(platform: 'ios' | 'android', fields: SubscriptionFields, id?: string): SubscriptionPayload;
+/**
+ * Returns the fields of `current` that differ from what the server last
+ * acknowledged (`synced`). `net_type` alone never triggers a PATCH, it is only
+ * sent along with other changes (it flips constantly).
+ */
+export declare function diffSubscription(synced: Partial<SubscriptionFields> | undefined, current: SubscriptionFields): Partial<SubscriptionFields>;

package/lib/core/subscription.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPermissionGranted = isPermissionGranted;
+exports.computeNotificationTypes = computeNotificationTypes;
+exports.computeEnabled = computeEnabled;
+exports.computeOptedIn = computeOptedIn;
+exports.buildSubscriptionFields = buildSubscriptionFields;
+exports.subscriptionType = subscriptionType;
+exports.toSubscriptionPayload = toSubscriptionPayload;
+exports.diffSubscription = diffSubscription;
+const constants_1 = require("./constants");
+function isPermissionGranted(permission) {
+    return permission === 'granted' || permission === 'provisional' || permission === 'ephemeral';
+}
+/**
+ * Computes `notification_types`:
+ * token errors (-3/-10) > opted out / denied (-2) > not asked (0) > subscribed (1).
+ */
+function computeNotificationTypes(input) {
+    if (typeof input.tokenError === 'number' && input.tokenError < 0)
+        return input.tokenError;
+    if (!input.optedIn)
+        return constants_1.NotificationTypes.unsubscribed;
+    if (input.permission === 'denied')
+        return constants_1.NotificationTypes.unsubscribed;
+    if (input.permission === 'notDetermined')
+        return constants_1.NotificationTypes.notAsked;
+    if (!input.token)
+        return constants_1.NotificationTypes.notAsked;
+    return constants_1.NotificationTypes.subscribed;
+}
+/** `enabled` is false when opted out or when the OS permission is not granted. */
+function computeEnabled(input) {
+    return input.optedIn && isPermissionGranted(input.permission);
+}
+/** What `pushSubscription.getOptedInAsync()` reports. */
+function computeOptedIn(input) {
+    return input.optedIn && isPermissionGranted(input.permission) && !!input.token && !input.tokenError;
+}
+/** Builds the full subscription field set from local state and device info. */
+function buildSubscriptionFields(input, device) {
+    var _a;
+    const fields = {
+        enabled: computeEnabled(input),
+        notification_types: computeNotificationTypes(input),
+        sdk: constants_1.SDK_VERSION,
+    };
+    if (input.token)
+        fields.token = input.token;
+    if (device) {
+        if (device.deviceModel)
+            fields.device_model = device.deviceModel;
+        if (device.deviceOs)
+            fields.device_os = device.deviceOs;
+        if (device.appVersion)
+            fields.app_version = device.appVersion;
+        if (device.carrier)
+            fields.carrier = device.carrier;
+        if (typeof device.rooted === 'boolean')
+            fields.rooted = device.rooted;
+        if (typeof device.netType === 'number')
+            fields.net_type = device.netType;
+        if (device.platform === 'ios')
+            fields.test_type = (_a = device.testType) !== null && _a !== void 0 ? _a : null;
+    }
+    return fields;
+}
+function subscriptionType(platform) {
+    return platform === 'ios' ? 'iOSPush' : 'AndroidPush';
+}
+/** Full payload for `POST /users` / `POST .../subscriptions`. */
+function toSubscriptionPayload(platform, fields, id) {
+    const payload = { type: subscriptionType(platform), ...fields };
+    if (id)
+        payload.id = id;
+    return payload;
+}
+/**
+ * Returns the fields of `current` that differ from what the server last
+ * acknowledged (`synced`). `net_type` alone never triggers a PATCH, it is only
+ * sent along with other changes (it flips constantly).
+ */
+function diffSubscription(synced, current) {
+    const previous = synced !== null && synced !== void 0 ? synced : {};
+    const patch = {};
+    const keys = Object.keys(current);
+    for (const key of keys) {
+        const value = current[key];
+        if (value === undefined)
+            continue;
+        if (previous[key] !== value)
+            patch[key] = value;
+    }
+    const changedKeys = Object.keys(patch);
+    if (changedKeys.length === 1 && changedKeys[0] === 'net_type')
+        return {};
+    return patch;
+}

package/lib/core/tags.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tag helpers. Tags are always strings on the wire; an empty string value in
+ * a PATCH removes the tag (protocol: "Tags are merged; an empty-string value
+ * removes the tag").
+ */
+export type TagMap = Record<string, string>;
+/** Changes to send: `value` sets, `''` removes. */
+export type TagChanges = Record<string, string>;
+/**
+ * Converts a developer supplied tag value to the wire string.
+ * Returns `undefined` for unsupported values (objects, arrays, functions).
+ * `null`/`undefined` map to `''` (removal).
+ */
+export declare function normalizeTagValue(value: unknown): string | undefined;
+/** Returns `true` when the key can be used as a tag key. */
+export declare function isValidTagKey(key: unknown): key is string;
+/**
+ * Normalizes a tag object, dropping invalid keys and values.
+ * The second element lists the keys that were rejected.
+ */
+export declare function normalizeTags(input: Record<string, unknown>): [TagChanges, string[]];
+/**
+ * Computes the changes that turn `previous` into `next`.
+ * Changed / added keys map to their new value, removed keys map to `''`.
+ */
+export declare function diffTags(previous: TagMap, next: TagMap): TagChanges;
+/** Applies changes to a tag map (returns a new object). */
+export declare function applyTagChanges(base: TagMap, changes: TagChanges): TagMap;
+/** Merges two change sets; the later one wins per key. */
+export declare function mergeTagChanges(first: TagChanges, second: TagChanges): TagChanges;
+/**
+ * Computes what must be sent for an `addTags` call given the local cache:
+ * only values that differ from the cache are sent. Empty values are removals
+ * and are always sent (the local cache may not know every server tag).
+ */
+export declare function changesForAdd(current: TagMap, additions: TagChanges): TagChanges;
+/** Computes the removal change set for `removeTags` (always sent). */
+export declare function changesForRemove(keys: readonly string[]): TagChanges;
+export declare function isEmpty(changes: Record<string, unknown> | undefined | null): boolean;

package/lib/core/tags.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Tag helpers. Tags are always strings on the wire; an empty string value in
+ * a PATCH removes the tag (protocol: "Tags are merged; an empty-string value
+ * removes the tag").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTagValue = normalizeTagValue;
+exports.isValidTagKey = isValidTagKey;
+exports.normalizeTags = normalizeTags;
+exports.diffTags = diffTags;
+exports.applyTagChanges = applyTagChanges;
+exports.mergeTagChanges = mergeTagChanges;
+exports.changesForAdd = changesForAdd;
+exports.changesForRemove = changesForRemove;
+exports.isEmpty = isEmpty;
+/**
+ * Converts a developer supplied tag value to the wire string.
+ * Returns `undefined` for unsupported values (objects, arrays, functions).
+ * `null`/`undefined` map to `''` (removal).
+ */
+function normalizeTagValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+            return Number.isFinite(value) ? String(value) : undefined;
+        case 'boolean':
+        case 'bigint':
+            return String(value);
+        default:
+            return undefined;
+    }
+}
+/** Returns `true` when the key can be used as a tag key. */
+function isValidTagKey(key) {
+    return typeof key === 'string' && key.trim().length > 0;
+}
+/**
+ * Normalizes a tag object, dropping invalid keys and values.
+ * The second element lists the keys that were rejected.
+ */
+function normalizeTags(input) {
+    const result = {};
+    const rejected = [];
+    if (!input || typeof input !== 'object')
+        return [result, rejected];
+    for (const key of Object.keys(input)) {
+        const value = normalizeTagValue(input[key]);
+        if (!isValidTagKey(key) || value === undefined) {
+            rejected.push(key);
+            continue;
+        }
+        result[key] = value;
+    }
+    return [result, rejected];
+}
+/**
+ * Computes the changes that turn `previous` into `next`.
+ * Changed / added keys map to their new value, removed keys map to `''`.
+ */
+function diffTags(previous, next) {
+    const changes = {};
+    for (const key of Object.keys(next)) {
+        const value = next[key];
+        if (value === '') {
+            if (key in previous)
+                changes[key] = '';
+        }
+        else if (previous[key] !== value) {
+            changes[key] = value;
+        }
+    }
+    for (const key of Object.keys(previous)) {
+        if (!(key in next))
+            changes[key] = '';
+    }
+    return changes;
+}
+/** Applies changes to a tag map (returns a new object). */
+function applyTagChanges(base, changes) {
+    const result = { ...base };
+    for (const key of Object.keys(changes)) {
+        const value = changes[key];
+        if (value === '')
+            delete result[key];
+        else
+            result[key] = value;
+    }
+    return result;
+}
+/** Merges two change sets; the later one wins per key. */
+function mergeTagChanges(first, second) {
+    return { ...first, ...second };
+}
+/**
+ * Computes what must be sent for an `addTags` call given the local cache:
+ * only values that differ from the cache are sent. Empty values are removals
+ * and are always sent (the local cache may not know every server tag).
+ */
+function changesForAdd(current, additions) {
+    const changes = {};
+    for (const key of Object.keys(additions)) {
+        const value = additions[key];
+        if (value === '' || current[key] !== value)
+            changes[key] = value;
+    }
+    return changes;
+}
+/** Computes the removal change set for `removeTags` (always sent). */
+function changesForRemove(keys) {
+    const changes = {};
+    for (const key of keys) {
+        if (isValidTagKey(key))
+            changes[key] = '';
+    }
+    return changes;
+}
+function isEmpty(changes) {
+    return !changes || Object.keys(changes).length === 0;
+}

package/lib/core/url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * URL helpers. React Native's `URL` polyfill is incomplete (several getters
+ * throw "not implemented"), so everything here is plain string handling.
+ */
+/**
+ * Normalizes the server URL given to `QPush.initialize`:
+ *  - trims whitespace, drops query string / fragment and trailing slashes
+ *  - prepends `https://` when no scheme is given
+ *  - appends `/api/v1` when the path does not already end with it
+ *
+ * Returns `null` when the value cannot be used.
+ */
+export declare function normalizeServerUrl(input: string | null | undefined): string | null;
+/** Joins the API base URL with an absolute API path (`/apps/...`). */
+export declare function joinUrl(base: string, path: string): string;
+/** Encodes a single path segment (alias ids, labels, ids). */
+export declare function encodeSegment(segment: string): string;