@oxyhq/core 1.11.15 → 1.11.17

package/dist/types/index.d.ts

@@ -28,6 +28,7 @@ export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
+export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto';
 export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from './crypto';
 export * from './models/interfaces';

package/dist/types/mixins/OxyServices.appData.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Per-user App-Data Mixin
+ *
+ * Thin client around `/users/me/app-data/...` — a generic per-user JSON KV
+ * store on the API. Authenticated callers can read, write, list, and delete
+ * entries scoped to their own user account.
+ *
+ * Identifier rules (must match the API):
+ *   - Both `namespace` and `key` must match `/^[a-z0-9_-]{1,64}$/u`.
+ *
+ * Limits (enforced by the API):
+ *   - Serialized JSON values are capped at 64 KB.
+ *   - Writes are rate-limited to 100 / minute / user.
+ *
+ * Intended use cases are small bits of cross-device app state — e.g. Academy
+ * course progress, "last viewed" markers, dismissed banner flags. Do not use
+ * this for large blobs or anything that needs server-side querying; it's a
+ * write-it-and-read-it-back store.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** Thrown when a namespace or key fails the kebab/snake-case validator. */
+export declare class OxyAppDataIdentifierError extends Error {
+    constructor(field: 'namespace' | 'key', value: string);
+}
+export declare function OxyServicesAppDataMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Read the value stored under `(namespace, key)` for the current user.
+         *
+         * @returns The previously-stored value, or `null` if nothing has been
+         *   stored yet. Never throws on "not found" — a missing entry is
+         *   semantically a `null` value.
+         */
+        getAppData<TValue = unknown>(namespace: string, key: string): Promise<TValue | null>;
+        /**
+         * Upsert the value under `(namespace, key)` for the current user.
+         *
+         * Returns the value the server confirmed it stored — typically the same
+         * value the caller passed in, but consumers should prefer the returned
+         * value (the API is the source of truth).
+         *
+         * @throws OxyAppDataIdentifierError when namespace or key is malformed.
+         */
+        setAppData<TValue = unknown>(namespace: string, key: string, value: TValue): Promise<TValue>;
+        /**
+         * Delete the value stored under `(namespace, key)` for the current user.
+         *
+         * Idempotent — resolves successfully whether or not the entry existed.
+         */
+        deleteAppData(namespace: string, key: string): Promise<void>;
+        /**
+         * List every entry stored under `namespace` for the current user.
+         *
+         * Returns an empty object when the namespace contains no entries (the
+         * endpoint never 404s on an empty namespace).
+         */
+        listAppData<TValue = unknown>(namespace: string): Promise<Record<string, TValue>>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string, refreshToken?: string): void;
+        clearTokens(): void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -193,11 +193,47 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>>;
         /**
          * Get access token by session ID
+         *
+         * SECURITY: this endpoint requires the caller to already hold a
+         * bearer token whose user owns the referenced session (C1 hardening
+         * in the API). For the device-flow / QR sign-in case where the
+         * client has no bearer token yet, use `claimSessionByToken` instead.
          */
         getTokenBySession(sessionId: string): Promise<{
             accessToken: string;
             expiresAt: string;
         }>;
+        /**
+         * Exchange a device-flow sessionToken for the first access token.
+         *
+         * The originating client holds a 128-bit `sessionToken` that nobody
+         * else has seen — it was generated client-side, sent once on
+         * `POST /auth/session/create`, and is never echoed back. After
+         * another authenticated device approves the session via
+         * `POST /auth/session/authorize/{sessionToken}` (bearer-authed) and
+         * the auth socket / poll loop notifies this client, the client
+         * exchanges its `sessionToken` here for the first access token,
+         * refresh token, sessionId, and the authorized user.
+         *
+         * This call requires no Authorization header — the high-entropy
+         * `sessionToken` IS the credential (RFC 8628 §3.4). The exchange is
+         * single-use; replay attempts are rejected with 401.
+         *
+         * @param sessionToken - The same sessionToken the SDK passed to
+         *   `POST /auth/session/create` at the start of the flow.
+         * @param options.deviceFingerprint - Optional fingerprint of the
+         *   originating client device.
+         */
+        claimSessionByToken(sessionToken: string, options?: {
+            deviceFingerprint?: string;
+        }): Promise<{
+            accessToken: string;
+            refreshToken: string;
+            sessionId: string;
+            deviceId: string;
+            expiresAt: string;
+            user: User;
+        }>;
         /**
          * Get sessions by session ID
          */

package/dist/types/mixins/index.d.ts

@@ -25,6 +25,7 @@ import { OxyServicesFeaturesMixin } from './OxyServices.features';
 import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
+import { OxyServicesAppDataMixin } from './OxyServices.appData';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -34,7 +35,7 @@ import { OxyServicesContactsMixin } from './OxyServices.contacts';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.11.15",
+  "version": "1.11.17",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -35,6 +35,7 @@ export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
+export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 
 // --- Crypto / Identity ---
 export {

package/src/mixins/OxyServices.appData.ts

@@ -0,0 +1,158 @@
+/**
+ * Per-user App-Data Mixin
+ *
+ * Thin client around `/users/me/app-data/...` — a generic per-user JSON KV
+ * store on the API. Authenticated callers can read, write, list, and delete
+ * entries scoped to their own user account.
+ *
+ * Identifier rules (must match the API):
+ *   - Both `namespace` and `key` must match `/^[a-z0-9_-]{1,64}$/u`.
+ *
+ * Limits (enforced by the API):
+ *   - Serialized JSON values are capped at 64 KB.
+ *   - Writes are rate-limited to 100 / minute / user.
+ *
+ * Intended use cases are small bits of cross-device app state — e.g. Academy
+ * course progress, "last viewed" markers, dismissed banner flags. Do not use
+ * this for large blobs or anything that needs server-side querying; it's a
+ * write-it-and-read-it-back store.
+ */
+
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/**
+ * Identifier validator — mirror of the API regex. Validating client-side
+ * gives consumers a clean throw before the request even leaves the device.
+ */
+const APP_DATA_IDENTIFIER_PATTERN = /^[a-z0-9_-]{1,64}$/u;
+
+/** Thrown when a namespace or key fails the kebab/snake-case validator. */
+export class OxyAppDataIdentifierError extends Error {
+  constructor(field: 'namespace' | 'key', value: string) {
+    super(
+      `Invalid app-data ${field} "${value}": must match [a-z0-9_-]{1,64} (lowercase letters, digits, dashes, underscores).`,
+    );
+    this.name = 'OxyAppDataIdentifierError';
+  }
+}
+
+function assertIdentifier(field: 'namespace' | 'key', value: string): void {
+  if (!APP_DATA_IDENTIFIER_PATTERN.test(value)) {
+    throw new OxyAppDataIdentifierError(field, value);
+  }
+}
+
+/** Wire shape of `GET /users/me/app-data/:namespace/:key`. */
+interface AppDataValueResponse<T> {
+  value: T | null;
+}
+
+/** Wire shape of `GET /users/me/app-data/:namespace`. */
+interface AppDataNamespaceResponse<T> {
+  entries: Record<string, T>;
+}
+
+export function OxyServicesAppDataMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Read the value stored under `(namespace, key)` for the current user.
+     *
+     * @returns The previously-stored value, or `null` if nothing has been
+     *   stored yet. Never throws on "not found" — a missing entry is
+     *   semantically a `null` value.
+     */
+    async getAppData<TValue = unknown>(
+      namespace: string,
+      key: string,
+    ): Promise<TValue | null> {
+      assertIdentifier('namespace', namespace);
+      assertIdentifier('key', key);
+
+      return this.withAuthRetry(async () => {
+        const response = await this.makeRequest<AppDataValueResponse<TValue>>(
+          'GET',
+          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+          undefined,
+          { cache: false },
+        );
+        return response?.value ?? null;
+      }, 'getAppData');
+    }
+
+    /**
+     * Upsert the value under `(namespace, key)` for the current user.
+     *
+     * Returns the value the server confirmed it stored — typically the same
+     * value the caller passed in, but consumers should prefer the returned
+     * value (the API is the source of truth).
+     *
+     * @throws OxyAppDataIdentifierError when namespace or key is malformed.
+     */
+    async setAppData<TValue = unknown>(
+      namespace: string,
+      key: string,
+      value: TValue,
+    ): Promise<TValue> {
+      assertIdentifier('namespace', namespace);
+      assertIdentifier('key', key);
+
+      return this.withAuthRetry(async () => {
+        const response = await this.makeRequest<AppDataValueResponse<TValue>>(
+          'PUT',
+          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+          { value },
+          { cache: false },
+        );
+        // The server echoes the stored value back; fall back to the caller's
+        // input only if the server somehow omitted it (defensive — the route
+        // always sets it).
+        return (response?.value ?? value) as TValue;
+      }, 'setAppData');
+    }
+
+    /**
+     * Delete the value stored under `(namespace, key)` for the current user.
+     *
+     * Idempotent — resolves successfully whether or not the entry existed.
+     */
+    async deleteAppData(namespace: string, key: string): Promise<void> {
+      assertIdentifier('namespace', namespace);
+      assertIdentifier('key', key);
+
+      await this.withAuthRetry(async () => {
+        await this.makeRequest<void>(
+          'DELETE',
+          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+          undefined,
+          { cache: false },
+        );
+      }, 'deleteAppData');
+    }
+
+    /**
+     * List every entry stored under `namespace` for the current user.
+     *
+     * Returns an empty object when the namespace contains no entries (the
+     * endpoint never 404s on an empty namespace).
+     */
+    async listAppData<TValue = unknown>(
+      namespace: string,
+    ): Promise<Record<string, TValue>> {
+      assertIdentifier('namespace', namespace);
+
+      return this.withAuthRetry(async () => {
+        const response = await this.makeRequest<AppDataNamespaceResponse<TValue>>(
+          'GET',
+          `/users/me/app-data/${encodeURIComponent(namespace)}`,
+          undefined,
+          { cache: false },
+        );
+        return response?.entries ?? {};
+      }, 'listAppData');
+    }
+  };
+}

package/src/mixins/OxyServices.auth.ts

@@ -440,6 +440,11 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
 
     /**
      * Get access token by session ID
+     *
+     * SECURITY: this endpoint requires the caller to already hold a
+     * bearer token whose user owns the referenced session (C1 hardening
+     * in the API). For the device-flow / QR sign-in case where the
+     * client has no bearer token yet, use `claimSessionByToken` instead.
      */
     async getTokenBySession(sessionId: string): Promise<{ accessToken: string; expiresAt: string }> {
       try {
@@ -449,9 +454,67 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           undefined,
           { cache: false, retry: false }
         );
-        
+
         this.setTokens(res.accessToken);
-        
+
+        return res;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Exchange a device-flow sessionToken for the first access token.
+     *
+     * The originating client holds a 128-bit `sessionToken` that nobody
+     * else has seen — it was generated client-side, sent once on
+     * `POST /auth/session/create`, and is never echoed back. After
+     * another authenticated device approves the session via
+     * `POST /auth/session/authorize/{sessionToken}` (bearer-authed) and
+     * the auth socket / poll loop notifies this client, the client
+     * exchanges its `sessionToken` here for the first access token,
+     * refresh token, sessionId, and the authorized user.
+     *
+     * This call requires no Authorization header — the high-entropy
+     * `sessionToken` IS the credential (RFC 8628 §3.4). The exchange is
+     * single-use; replay attempts are rejected with 401.
+     *
+     * @param sessionToken - The same sessionToken the SDK passed to
+     *   `POST /auth/session/create` at the start of the flow.
+     * @param options.deviceFingerprint - Optional fingerprint of the
+     *   originating client device.
+     */
+    async claimSessionByToken(
+      sessionToken: string,
+      options: { deviceFingerprint?: string } = {}
+    ): Promise<{
+      accessToken: string;
+      refreshToken: string;
+      sessionId: string;
+      deviceId: string;
+      expiresAt: string;
+      user: User;
+    }> {
+      try {
+        const res = await this.makeRequest<{
+          accessToken: string;
+          refreshToken: string;
+          sessionId: string;
+          deviceId: string;
+          expiresAt: string;
+          user: User;
+        }>(
+          'POST',
+          '/auth/session/claim',
+          {
+            sessionToken,
+            ...(options.deviceFingerprint ? { deviceFingerprint: options.deviceFingerprint } : {}),
+          },
+          { cache: false, retry: false }
+        );
+
+        this.setTokens(res.accessToken, res.refreshToken);
+
         return res;
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/__tests__/appData.test.ts

@@ -0,0 +1,203 @@
+/**
+ * App-Data Mixin Tests
+ *
+ * Exercises the typed helpers around `/users/me/app-data/...`. We stub
+ * `makeRequest` so the tests run without a network or a database — what we
+ * care about here is request shape (method, URL, body), identifier
+ * validation, and response handling (`null` when missing, echo on write).
+ *
+ * The mixin sits behind `withAuthRetry`, which polls for a token before
+ * running the operation. We force a token in via `__resetTokensForTests`'
+ * companion path (set access token directly) so the auth wait short-circuits.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { OxyAppDataIdentifierError } from '../OxyServices.appData';
+
+const setAccessTokenForTest = (oxy: OxyServices): void => {
+  // Tokens are managed by HttpService — `hasAccessToken()` is the gate the
+  // `withAuthRetry` loop polls. Reaching in via the public httpService and
+  // calling setTokens with a dummy avoids us needing to expose new test
+  // hooks just for this.
+  oxy.httpService.setTokens('test-token', '');
+};
+
+describe('OxyServices.appData', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    setAccessTokenForTest(oxy);
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    makeRequestSpy.mockRestore();
+  });
+
+  describe('getAppData', () => {
+    it('returns the stored value when the API responds with one', async () => {
+      makeRequestSpy.mockResolvedValue({ value: { completed: ['intro'] } });
+
+      const result = await oxy.getAppData<{ completed: string[] }>(
+        'academy',
+        'getting-started',
+      );
+
+      expect(result).toEqual({ completed: ['intro'] });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/users/me/app-data/academy/getting-started',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('returns null when the API responds with `value: null`', async () => {
+      makeRequestSpy.mockResolvedValue({ value: null });
+      const result = await oxy.getAppData('academy', 'unknown');
+      expect(result).toBeNull();
+    });
+
+    it('returns null when the response object is missing `value`', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.getAppData('academy', 'unknown');
+      expect(result).toBeNull();
+    });
+
+    it('URL-encodes namespace and key path segments', async () => {
+      makeRequestSpy.mockResolvedValue({ value: 'ok' });
+      await oxy.getAppData('a-b_c', 'd-e_f');
+      // URL-encoding is a no-op for our allowed character set, but we still
+      // run through encodeURIComponent — make sure that's wired so the call
+      // site doesn't accidentally bypass it later.
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/users/me/app-data/a-b_c/d-e_f');
+    });
+
+    it('throws OxyAppDataIdentifierError for invalid namespace', async () => {
+      await expect(oxy.getAppData('Bad Namespace', 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws OxyAppDataIdentifierError for invalid key', async () => {
+      await expect(oxy.getAppData('ns', 'Bad/Key')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects empty identifiers (regex requires at least one char)', async () => {
+      await expect(oxy.getAppData('', 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      await expect(oxy.getAppData('n', '')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+
+    it('rejects identifiers longer than 64 chars', async () => {
+      const tooLong = 'a'.repeat(65);
+      await expect(oxy.getAppData(tooLong, 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+
+    it('surfaces API errors (e.g. 401) via withAuthRetry', async () => {
+      const err = Object.assign(new Error('Authentication required'), {
+        response: { status: 401 },
+      });
+      makeRequestSpy.mockRejectedValue(err);
+      await expect(oxy.getAppData('academy', 'getting-started')).rejects.toThrow();
+    });
+  });
+
+  describe('setAppData', () => {
+    it('writes the value and returns the server-echoed value', async () => {
+      makeRequestSpy.mockResolvedValue({ value: { completed: ['intro'] } });
+
+      const result = await oxy.setAppData('academy', 'getting-started', {
+        completed: ['intro'],
+      });
+
+      expect(result).toEqual({ completed: ['intro'] });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'PUT',
+        '/users/me/app-data/academy/getting-started',
+        { value: { completed: ['intro'] } },
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('falls back to the caller value when the server response omits it', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.setAppData('academy', 'k', 'hello');
+      expect(result).toBe('hello');
+    });
+
+    it('throws OxyAppDataIdentifierError before issuing a request', async () => {
+      await expect(oxy.setAppData('UPPER', 'k', 1)).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('deleteAppData', () => {
+    it('issues a DELETE and resolves', async () => {
+      makeRequestSpy.mockResolvedValue(undefined);
+
+      await expect(oxy.deleteAppData('academy', 'getting-started')).resolves.toBeUndefined();
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/users/me/app-data/academy/getting-started',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('throws OxyAppDataIdentifierError on invalid identifiers', async () => {
+      await expect(oxy.deleteAppData('ns', 'BAD KEY')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+  });
+
+  describe('listAppData', () => {
+    it('returns the entries map from the API', async () => {
+      makeRequestSpy.mockResolvedValue({
+        entries: {
+          'getting-started': { completed: ['intro'] },
+          'using-oxy-id': { completed: [] },
+        },
+      });
+
+      const result = await oxy.listAppData<{ completed: string[] }>('academy');
+
+      expect(result).toEqual({
+        'getting-started': { completed: ['intro'] },
+        'using-oxy-id': { completed: [] },
+      });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/users/me/app-data/academy',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('returns an empty object when the API returns no entries', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.listAppData('academy');
+      expect(result).toEqual({});
+    });
+
+    it('throws OxyAppDataIdentifierError on invalid namespace', async () => {
+      await expect(oxy.listAppData('Bad Namespace')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+  });
+});

package/src/mixins/index.ts

@@ -26,6 +26,7 @@ import { OxyServicesFeaturesMixin } from './OxyServices.features';
 import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
+import { OxyServicesAppDataMixin } from './OxyServices.appData';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -56,6 +57,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -115,6 +117,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesTopicsMixin,
     OxyServicesManagedAccountsMixin,
     OxyServicesContactsMixin,
+    OxyServicesAppDataMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,