@oxyhq/core 1.11.15 → 1.11.16

package/dist/esm/index.js

@@ -22,6 +22,7 @@ export { OXY_CLOUD_URL, oxyClient } from './OxyServices.js';
 export { AuthManager, createAuthManager } from './AuthManager.js';
 export { CrossDomainAuth, createCrossDomainAuth } from './CrossDomainAuth.js';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth.js';
+export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
 // --- Crypto / Identity ---
 export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/index.js';
 // --- Models & Types ---

package/dist/esm/mixins/OxyServices.appData.js

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+/**
+ * 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, value) {
+        super(`Invalid app-data ${field} "${value}": must match [a-z0-9_-]{1,64} (lowercase letters, digits, dashes, underscores).`);
+        this.name = 'OxyAppDataIdentifierError';
+    }
+}
+function assertIdentifier(field, value) {
+    if (!APP_DATA_IDENTIFIER_PATTERN.test(value)) {
+        throw new OxyAppDataIdentifierError(field, value);
+    }
+}
+export function OxyServicesAppDataMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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(namespace, key) {
+            assertIdentifier('namespace', namespace);
+            assertIdentifier('key', key);
+            return this.withAuthRetry(async () => {
+                const response = await this.makeRequest('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(namespace, key, value) {
+            assertIdentifier('namespace', namespace);
+            assertIdentifier('key', key);
+            return this.withAuthRetry(async () => {
+                const response = await this.makeRequest('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);
+            }, 'setAppData');
+        }
+        /**
+         * Delete the value stored under `(namespace, key)` for the current user.
+         *
+         * Idempotent — resolves successfully whether or not the entry existed.
+         */
+        async deleteAppData(namespace, key) {
+            assertIdentifier('namespace', namespace);
+            assertIdentifier('key', key);
+            await this.withAuthRetry(async () => {
+                await this.makeRequest('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(namespace) {
+            assertIdentifier('namespace', namespace);
+            return this.withAuthRetry(async () => {
+                const response = await this.makeRequest('GET', `/users/me/app-data/${encodeURIComponent(namespace)}`, undefined, { cache: false });
+                return response?.entries ?? {};
+            }, 'listAppData');
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -25,6 +25,7 @@ import { OxyServicesFeaturesMixin } from './OxyServices.features.js';
 import { OxyServicesTopicsMixin } from './OxyServices.topics.js';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts.js';
 import { OxyServicesContactsMixin } from './OxyServices.contacts.js';
+import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -64,6 +65,7 @@ const MIXIN_PIPELINE = [
     OxyServicesTopicsMixin,
     OxyServicesManagedAccountsMixin,
     OxyServicesContactsMixin,
+    OxyServicesAppDataMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];