@oxyhq/core 1.11.15 → 1.11.17

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/OxyServices.auth.js

@@ -317,6 +317,11 @@ export function OxyServicesAuthMixin(Base) {
         }
         /**
          * 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) {
             try {
@@ -328,6 +333,40 @@ export function OxyServicesAuthMixin(Base) {
                 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, options = {}) {
+            try {
+                const res = await this.makeRequest('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);
+            }
+        }
         /**
          * Get sessions by session ID
          */

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,
 ];